JSON-LD explained: the schema format Google recommends

What is JSON-LD?

JSON-LD stands for JavaScript Object Notation for Linked Data. It is one of three ways to write structured data — the machine-readable labels that tell a search engine what a page is about.

It is a W3C Recommendation, published in July 2020. So it is a real open standard, not a Google invention.

If you are still deciding which types to mark up, start with our overview of schema markup and what it does. This page is only about the format you write it in — the syntax, the placement, and the plumbing.

The difference is simple. Microdata and RDFa are written into your HTML as extra attributes on tags you already have. JSON-LD is written beside your HTML as one self-contained block.

JSON-LD vs Microdata vs RDFa

All three are valid. Google's own documentation lists JSON-LD, Microdata and RDFa as supported formats, and says it recommends JSON-LD "whenever possible". The honest framing: this is a maintainability argument, not a ranking one.

Mixing them is where teams get hurt. Google will read all three, but describing the same product in both Microdata and JSON-LD gives you two descriptions of one thing that have to be kept identical forever. Pick one format per entity.

Why Google recommends JSON-LD

Not because it ranks better. Because it is cheaper to run. Four practical reasons:

• It is one block, in one place. You can read the whole description of the page at a glance instead of hunting attributes across a template.
• It survives a redesign. Changing your HTML layout does not touch the data, because the data was never attached to the layout.
• It can be generated. A plugin, a tag manager or a schema markup generator can output a JSON block cleanly. Generating nested Microdata attributes is far harder.
• It handles relationships well. Linked Data is built for connecting things with an @id — the same idea behind entity SEO, where you describe how your organisation, people and products relate.

If your site already runs Microdata and it validates, you do not have to rip it out. Migrate when you next rebuild the template.

Where the JSON-LD block goes on the page

Google's structured data documentation describes JSON-LD as a notation embedded in a script tag "in the page head or body". Either is fine. There is no SEO penalty for one over the other.

Two other placement facts worth knowing:

• Injected JSON-LD counts. Google states it can read JSON-LD that is dynamically inserted into page content by JavaScript or by an embedded widget from your CMS. That is what makes tag-manager delivery workable.
• It still has to be in the rendered page. Rendering has to complete for the block to be seen, which is an ordinary technical SEO concern, not a schema one. If the page is slow or script-blocked, the schema is slow too.

Our own preference for client sites is the head, output by the SEO plugin. It is the one location nobody edits by accident.

How to add JSON-LD on WordPress

On WordPress there are three honest routes: your SEO plugin's custom schema field, your theme, or a tag manager. The route you must not use is the post editor.

1. Build the block. Write it by hand or generate it, then read it back line by line. One missing comma kills the whole block.
2. Check the quotes. Straight quotes only. Pasting from Word or Google Docs converts them to curly quotes and the JSON stops parsing. This is the single most common break we see.
3. Put it in AIOSEO > Custom Schema. Open the AIOSEO schema panel on the post or page you are marking up and add a custom schema entry. The plugin outputs it in the head for you.
4. Or add it in your theme if the block is sitewide — hook it into the head from your child theme or a code-snippet plugin, not from inside the content.
5. Confirm it is really there. View the rendered source of the live URL and search for your block. If it is missing, something stripped it. Then validate it with Google's structured data testing tools.

What a JSON-LD block actually looks like

Here is a minimal Organization block. Put this in your plugin's custom schema field or your theme — never in the post body.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Your Company Name",
  "url": "https://example.com/",
  "logo": "https://example.com/logo.png",
  "sameAs": [
    "https://www.linkedin.com/company/your-company/"
  ]
}
</script>

Three parts do the work. @context says the vocabulary is schema.org. @type says what kind of thing this is. Everything after that is a property of that thing.

If you are pasting into a custom schema field, most plugins want only the JSON object — the curly braces and what is inside them — because the plugin adds the script wrapper itself. Check which your plugin expects before you paste.

Not on WordPress? The same split applies: find the platform's own schema field rather than editing the template. Our notes on Wix SEO cover that pattern on a closed platform.

Mistakes that break a JSON-LD block

Most failures are not strategy problems. They are typing problems.

• Curly quotes. Covered above, and still number one.
• A trailing comma after the last property. Valid in some languages. Not in JSON.
• Missing @context. Without it the parser does not know the terms mean schema.org terms.
• Marking up content that is not on the page. Google's guidelines require the structured data to describe what a visitor can actually see.
• Duplicating what your plugin already emits. If AIOSEO outputs BlogPosting, adding a second BlogPosting creates a conflict rather than reinforcement.
• Adding FAQPage for the rich result. Google's documentation notice says the FAQ feature stopped appearing in Search from 7 May 2026, and the documentation was removed on 15 June 2026. The markup is still valid schema.org and still machine-readable context — it simply draws no rich result now. Our post on FAQ schema has the detail.

What switching to JSON-LD will not do

Two expectations to set honestly.

It is not a ranking change. Google parses Microdata and RDFa just as it parses JSON-LD. Converting a validating Microdata implementation to JSON-LD makes your site easier to maintain. It does not make the page rank higher by itself.

It is not an AI visibility tactic. Google's guidance on content in its AI experiences, updated 10 July 2026, states there are no additional technical requirements and no special structured data needed to appear in AI Overviews or AI Mode. Structured data governs rich-result eligibility in Search. That is its job. For what actually moves the needle on those surfaces, see our AI search guides.

What JSON-LD does give you is a clean, single, machine-readable description of the page — generated once, maintained in one place, and readable by anything that parses the web.

Where to go from here

Pick the format, then pick the plumbing, then stop touching it.

1. Standardise on JSON-LD for anything new you build.
2. Choose one output location — the SEO plugin for most sites — and document it so nobody adds a second copy.
3. Audit for duplicates before you add anything, since your plugin is probably already emitting the basics.
4. Only then decide which types to add. Format is the easy half; choosing the right types for your pages is the half that earns the rich result.