How to Add Schema.org JSON-LD to WordPress? Rank Math + Custom Code

When you add a recipe to your WordPress site, have you ever wondered whether Google sees it as an actual recipe or just a pile of text? In 2019, when I created 618 recipe pages for italyanmutfagi.com, I noticed that rich snippets weren't appearing in Google Search Console and realized the problem was missing Schema.org JSON-LD. Since then, I've added Schema markup to dozens of WordPress sites. I used Rank Math on some, wrote completely custom code on others, and used both together on most. In this article, I'll explain both methods of adding Schema.org JSON-LD to WordPress, which one makes more sense in which situations, and provide examples from real projects.

I'm skipping basic topics like what Schema.org is and why JSON-LD is important, and going straight to implementation. If you're reading this article, you already know what Schema is and why you need to use it.

Automatic Schema Addition with Rank Math

Rank Math is one of WordPress's most popular SEO plugins and offers built-in Schema support. Unlike Yoast SEO, it has quite powerful Schema features even in its free version.

When you install Rank Math, it automatically adds some basic Schema types. General structures like Organization, Website, and WebPage are automatically created on every page. However, the real power lies in being able to add custom Schema types on a page-by-page basis.

When editing a post or page, you'll see a "Schema" tab inside the Rank Math meta box. From here, you can select dozens of Schema types like Article, BlogPosting, Product, Recipe, Event, and FAQ. When you fill in the relevant fields for each type, Rank Math automatically adds the JSON-LD code to the page's head section.

For example, if you want to add Article Schema for a blog post, you select the Schema type as "Article" and fill in fields like title, author, publication date, and image. Rank Math takes this information and generates JSON-LD code like this:

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Post Title",
  "author": {
    "@type": "Person",
    "name": "Miraç Eroğlu"
  },
  "datePublished": "2024-01-15",
  "image": "https://example.com/image.jpg"
}

Rank Math's strength is that it uses WordPress's existing data. It automatically pulls information like post title, author name, and publication date. You only fill in the fields that are missing or that you want to customize.

Rank Math's Limitations

However, Rank Math has some limitations. It can be insufficient especially for complex or custom Schema types.

Let me give you an example. When creating 79,000 doctor profile pages for doktorbul.com, I needed to add Physician Schema for each doctor. There's no Physician Schema type in Rank Math. There's Person, but fields specific to Physician are missing. For example, fields like "medicalSpecialty" and "hospitalAffiliation" aren't found in Person Schema.

Another example is italyanmutfagi.com. We needed to add Recipe Schema for 618 recipe pages. Rank Math has Recipe Schema, but manually filling in ingredients, steps, and cooking time for each recipe was impossible. The recipes were stored in a custom post type and I needed to automatically pull this data.

In such cases, writing custom code becomes necessary.

Adding Schema with Custom Code

Adding Schema with custom code provides full control. You can use any WordPress data, create complex Schema types, and add conditional logic.

To add JSON-LD to WordPress, you use the wp_head hook. The basic structure is as follows:

function futia_add_custom_schema() {
    if (is_singular('post')) {
        $schema = array(
            '@context' => 'https://schema.org',
            '@type' => 'Article',
            'headline' => get_the_title(),
            'author' => array(
                '@type' => 'Person',
                'name' => get_the_author()
            )
        );
        
        echo '<script type="application/ld+json">';
        echo json_encode($schema, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
        echo '</script>';
    }
}
add_action('wp_head', 'futia_add_custom_schema');

This code adds a simple Article Schema on every single post page. However, in real projects, you use much more complex structures.

Italyanmutfagi.com Recipe Schema Example

The Recipe Schema code I wrote for italyanmutfagi.com pulled data from a custom post type and created a complete Recipe Schema:

function futia_recipe_schema() {
    if (is_singular('tarif')) {
        $malzemeler = get_post_meta(get_the_ID(), 'malzemeler', true);
        $adimlar = get_post_meta(get_the_ID(), 'adimlar', true);
        $sure = get_post_meta(get_the_ID(), 'pisirme_suresi', true);
        
        $schema = array(
            '@context' => 'https://schema.org',
            '@type' => 'Recipe',
            'name' => get_the_title(),
            'image' => get_the_post_thumbnail_url(get_the_ID(), 'full'),
            'author' => array(
                '@type' => 'Person',
                'name' => get_the_author()
            ),
            'datePublished' => get_the_date('c'),
            'description' => get_the_excerpt(),
            'recipeIngredient' => explode("\n", $malzemeler),
            'recipeInstructions' => array_map(function($adim) {
                return array(
                    '@type' => 'HowToStep',
                    'text' => $adim
                );
            }, explode("\n", $adimlar)),
            'totalTime' => 'PT' . $sure . 'M'
        );
        
        echo '<script type="application/ld+json">';
        echo json_encode($schema, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
        echo '</script>';
    }
}
add_action('wp_head', 'futia_recipe_schema');

This code pulls ingredients and steps from custom fields and converts them to Schema.org Recipe format. Each step is added as a HowToStep object. Cooking time is converted to ISO 8601 duration format.

After setting up this structure, rich snippets started appearing in Google Search Console. Having the recipes' images, ratings, and cooking times displayed in search results had a visible impact on traffic.

Using Rank Math and Custom Code Together

In many projects, I use Rank Math and custom code together. While Rank Math handles basic Schema types, custom code kicks in for special cases.

For example, on kamupersonelhaber.com, we use Rank Math's automatic Schema on general pages. However, on job listing pages, we add custom JobPosting Schema because listings are pulled from the ilan.gov.tr API and this data is stored in custom fields.

The advantage of this approach is leaving the basic SEO structure to Rank Math and only writing code for special cases. This way, you save time and maintenance becomes easier.

However, there's one point you need to be careful about: when you add Schema with both Rank Math and custom code for the same page, two separate JSON-LD blocks are created. This is usually not a problem because Google can read multiple Schemas. However, be careful not to have two Schemas of the same type. For example, don't add Article Schema from both Rank Math and custom code.

Preventing Schema Conflicts

To prevent Schema conflicts, you can disable Rank Math from adding Schema for that page type when adding custom code:

add_filter('rank_math/json_ld', function($data, $jsonld) {
    if (is_singular('tarif')) {
        return array();
    }
    return $data;
}, 10, 2);

This code disables all of Rank Math's Schema output on recipe pages. This way, only your custom Schema is added.

Alternatively, you can remove only a specific Schema type:

add_filter('rank_math/json_ld', function($data, $jsonld) {
    if (is_singular('tarif') && isset($data['Article'])) {
        unset($data['Article']);
    }
    return $data;
}, 10, 2);

Selecting and Optimizing Schema Types

Choosing the right Schema type is more important than technical implementation. Google doesn't evaluate every Schema type the same way, and some types are more suitable for rich snippets.

For Content Pages

Use Article or NewsArticle for blog posts and news content. BlogPosting is also an option, but Article is more general and safe. Every Article Schema must have:

• headline (title)
• author (author, as Person or Organization)
• datePublished (publication date)
• image (visual at least 1200px wide)
• publisher (publisher, as Organization with logo)

The publisher part is especially important because Google won't show rich snippets without it. The logo must be at least 600x60px and must be provided with the organization name.

For E-commerce Pages

Product Schema is mandatory on product pages. However, just basic information isn't enough, you should also add:

• offers (price, stock status, currency)
• aggregateRating (product rating, if available)
• review (user reviews, if available)
• brand (brand)
• sku or gtin (product code)

When adding Product Schema for WooCommerce products on diolivo.com.tr, we dynamically update the stock status. If the product is out of stock, it's marked as "OutOfStock", if available, as "InStock". This is critical for products to be displayed correctly in Google Shopping.

For Local Businesses

LocalBusiness Schema is essential for businesses with a physical location. There are special subtypes in sectors like doctors, lawyers, and restaurants: Physician, Attorney, Restaurant.

On doktorbul.com, we used Physician Schema for each doctor profile. Not just Person, because we needed fields like medicalSpecialty and hospitalAffiliation in Physician:

$schema = array(
    '@context' => 'https://schema.org',
    '@type' => 'Physician',
    'name' => $doktor_adi,
    'medicalSpecialty' => $uzmanlik,
    'address' => array(
        '@type' => 'PostalAddress',
        'addressLocality' => $sehir,
        'addressRegion' => $ilce
    ),
    'telephone' => $telefon
);

Automatically generating this Schema for 79,000 profiles was both error-free and sustainable compared to manual entry.

Testing and Fixing Schema Errors

Always test after adding Schema. Google's Rich Results Test tool is the most reliable method: https://search.google.com/test/rich-results

Enter your page's URL, Google both reads the Schema and tells you which rich snippets can be displayed. If there are errors, it provides detailed explanations.

Common errors:

• Missing required fields: Each Schema type has required fields. For example, recipeIngredient is required in Recipe.
• Wrong data format: Dates must be in ISO 8601 format (2024-01-15T10:30:00+00:00). Durations in PT format (PT30M = 30 minutes).
• Invalid URLs: Fields like image and url must be full URLs, relative paths are not accepted.
• Inconsistent data: Information in Schema must match the visible content on the page. For example, if you write 5 stars in Schema but there are no reviews on the page, Google may see this as manipulation.

You can also see Schema errors in the "Enhancements" section of Google Search Console. However, these reports update days later, use Rich Results Test for instant testing.

Dynamic Schema Generation and Automation

On large sites, manually adding Schema for each page is impossible. Automation is essential.

On memuratamalari.com, 50+ job listings are published daily. JobPosting Schema is automatically created for each listing. Since listing data is pulled from an API, Schema uses the same data:

function futia_job_posting_schema($ilan_id) {
    $ilan = get_ilan_from_api($ilan_id);
    
    $schema = array(
        '@context' => 'https://schema.org',
        '@type' => 'JobPosting',
        'title' => $ilan['baslik'],
        'description' => $ilan['aciklama'],
        'datePosted' => date('c', strtotime($ilan['tarih'])),
        'hiringOrganization' => array(
            '@type' => 'Organization',
            'name' => $ilan['kurum']
        ),
        'jobLocation' => array(
            '@type' => 'Place',
            'address' => array(
                '@type' => 'PostalAddress',
                'addressLocality' => $ilan['sehir'],
                'addressCountry' => 'TR'
            )
        ),
        'employmentType' => 'FULL_TIME'
    );
    
    return $schema;
}

This function runs every time a listing page loads and creates Schema using that listing's data. No manual intervention, minimal error risk.

Similarly, on futia.net, VideoObject Schema is automatically generated for 2,000+ videos in 3 months. Information like duration, thumbnail, and upload date for each video is pulled from the YouTube API and added to Schema.

Multi-page Content and Schema Arrays

Some content doesn't fit on a single page. For example, a guide might be split into 5 pages. In this case, should you use separate Schema for each page or an array?

Google's recommendation is to use a single Schema for step-by-step content like HowTo or Recipe and list the steps within it. However, if each step is on a separate page, you can add a HowToStep specific to that step on each page and use a HowTo Schema containing all steps on the main page.

Alternatively, you can list pages with ItemList Schema:

{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "url": "https://example.com/rehber-sayfa-1"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "url": "https://example.com/rehber-sayfa-2"
    }
  ]
}

However, this approach isn't very effective for rich snippets. If possible, it's better to keep the content on a single page and provide the Schema all at once.

FAQ Schema and Accordion Blocks

FAQ Schema displays expandable question-answer boxes in search results. It's a powerful tool especially for informational content.

Rank Math has an FAQ block that you can use in the Gutenberg editor. Each question-answer pair is automatically added to FAQ Schema. However, you can create more flexible structures with custom code.

For example, pulling FAQs from a repeater field created with ACF and adding them to Schema:

function futia_faq_schema() {
    if (have_rows('faq')) {
        $faqs = array();
        while (have_rows('faq')) {
            the_row();
            $faqs[] = array(
                '@type' => 'Question',
                'name' => get_sub_field('soru'),
                'acceptedAnswer' => array(
                    '@type' => 'Answer',
                    'text' => get_sub_field('cevap')
                )
            );
        }
        
        $schema = array(
            '@context' => 'https://schema.org',
            '@type' => 'FAQPage',
            'mainEntity' => $faqs
        );
        
        echo '<script type="application/ld+json">';
        echo json_encode($schema, JSON_UNESCAPED_UNICODE);
        echo '</script>';
    }
}
add_action('wp_head', 'futia_faq_schema');

Points to consider when using FAQ Schema:

• Each question-answer pair must be visible on the page. Hidden content is not accepted.
• Answers must be at least 40-50 characters, single-word answers are invalid.
• If advertising or sales-focused content is marked as FAQ, Google may apply manual action.

Schema.org Updates and the Future

Schema.org is constantly being updated. New types are being added, new fields are being added to existing types. For example, the SpecialAnnouncement type was added for COVID-19 in 2023, now it's used for general announcements.

It's important to track which Schema types Google supports. Just because a type exists on Schema.org doesn't mean Google will use it in rich snippets. Check Google's official documentation: https://developers.google.com/search/docs/appearance/structured-data/search-gallery

AI tools have also started using Schema. Tools like ChatGPT and Perplexity read Schema when extracting information from web pages. If you have proper Schema, the likelihood of AIs using your site as a source increases.

For example, doctor profiles on doktorbul.com are correctly interpreted by AI assistants thanks to Physician Schema. When asked "cardiologist in Istanbul", AI can read the specialty and location from Schema.

This trend will strengthen. Schema is becoming important not just for Google, but for the entire digital ecosystem.

Adding Schema to your WordPress site isn't a technical requirement, it's translating your content into a language that machines can understand. Rank Math is sufficient for basic needs, but custom code is essential for special cases and automation. By using both together, you can achieve both quick setup and full control.

I plan Schema from the start in every project, determining which types are needed based on content structure. Then I set up the basic structure with Rank Math and write custom code for special cases. This approach both saves time and provides ease of maintenance in the long run.

If you're stuck on a point while adding Schema to your site or need custom Schema solutions, you can contact me via WhatsApp: +90 532 491 17 05. As FUTIA, we provide custom Schema implementations for WordPress sites, especially in large-scale and programmatic SEO projects.