JSON-LD schema that matters: the types worth adding and how to link them

A handful of schema.org types, written as JSON-LD and linked into one graph, covers what most business websites need. Organization and WebSite on the home page, WebPage and BreadcrumbList on every page, and a specific type where the content calls for it: BlogPosting, Product, Service or FAQPage. The rest is keeping it accurate.

Structured data used to be mostly about rich results in search. It now does a second job: it gives AI assistants and agents facts about your business in a form they do not have to guess from layout. A crawler reading your page can see that a name is your organization, that a date is the publish date, and that a list of questions is an FAQ. That is worth getting right.

The short list of types

You do not need dozens of types. You need the right one in the right place.

• Organization: your business name, logo, URL and a short description. Put it on the home page. It is the entity every other page is "about".
• WebSite: the site itself, with its name and publisher. Also on the home page.
• WebPage: on every page, with the page's name, description and URL.
• BreadcrumbList: on every inner page, matching the breadcrumb a visitor sees.
• BlogPosting or Article: for each article, with headline, dates, author and image.
• Product: for items you sell, with name, image, price and availability as shown on the page.
• Service: for service pages, with a description and provider.
• FAQPage: only where the page actually shows questions and answers.

The full vocabulary lives at schema.org. Google's search gallery lists which types can produce rich results, and it changes, so check it rather than relying on older guides.

Link everything into one graph with @id

The most common weakness we see is not a missing type. It is disconnected blocks. Each page declares its own Organization with slightly different details, and nothing says they are the same business.

The fix is @id. Give each entity a stable identifier, usually your URL plus a fragment, define it fully once, and refer to it everywhere else:

{"@context": "https://schema.org", "@graph": [
  {"@type": "Organization", "@id": "https://example.com/#org",
   "name": "Example Co", "url": "https://example.com/"},
  {"@type": "WebSite", "@id": "https://example.com/#site",
   "publisher": {"@id": "https://example.com/#org"}},
  {"@type": "WebPage", "@id": "https://example.com/pricing/#webpage",
   "isPartOf": {"@id": "https://example.com/#site"},
   "about": {"@id": "https://example.com/#org"}}
]}

Now every page points back to one organization and one site. A reader, human or machine, can follow the references instead of reconciling near-duplicates. This site works the same way: the home page defines #org and #site, and every other page references them.

Keep it matching the visible page

Structured data is a description of the page, not a second, better version of it. Google's structured data guidelines are explicit that markup should reflect content visible to users. In practice:

• FAQ answers must match the visible answers. If you edit a question on the page, edit the JSON-LD in the same change. We generate both from one source so they cannot drift.
• Prices and availability must match what a shopper sees. Stale Product data is worse than none.
• Do not mark up reviews or ratings you do not show, and do not invent them. The same goes for dates: dateModified should change when the content changes, not on every deploy.

This matters more now that AI assistants read the markup. If your JSON-LD says one thing and the page says another, you have told the machine something the human cannot check. Our guide to FAQ and structured data for answer engines goes deeper on the question-and-answer case.

Validate before you ship

Two free tools cover it:

• The Schema Markup Validator checks that your JSON-LD is valid schema.org, for any type.
• Google's Rich Results Test checks whether a page is eligible for the rich results Google supports, and shows errors and warnings.

Run both after any template change. A single stray character can make a whole block unreadable, and nothing on the visible page will tell you.

Common mistakes

• Several Organization blocks with different names across pages. Define it once and reference it.
• FAQPage on pages without a visible FAQ, added only for the search appearance.
• Copying markup from a plugin and never checking it. Plugins often output types that do not match the page, or duplicate what your theme already emits.
• Escaping problems: a quote or a closing script tag inside a value can break the block. Serialize with a proper JSON encoder rather than string concatenation.

Where it fits with the rest

JSON-LD is one of several signals an agent reads. It sits alongside llms.txt, which points assistants to your important pages, and Markdown on request, which gives them the page text without the layout. Together they make your site easy to read correctly. If you build on a platform, the platform pages describe where the markup usually comes from on each one.

What you can skip

schema.org has hundreds of types, and it is tempting to mark up everything. Resist it. Markup that describes nothing a visitor can see, or that no search engine or agent uses, adds maintenance without benefit. Start with the short list above, get it correct and connected, and add a new type only when a page genuinely contains that kind of thing: an event with a date and place, a job posting, a recipe. One accurate block is worth more than five speculative ones.

Next step

Run the free agent-readiness scan. It reports which JSON-LD types your home page declares and whether each block parses, next to the other files agents look for. If you want the structured data, templates and generation done for you, our SEO work covers it.