How to add structured data to a site, whatever it is built with

Structured data is not a ranking factor. It makes a page eligible for rich results, and it tells machines what the page is about in a form they do not have to guess. Both matter, the second one more each year, because assistants read it too.

• JSON-LD is the format Google recommends. Microdata and RDFa are still read.
• It can sit in the head or the body, and Google renders pages so a script can inject it. The answering AI crawlers do not run scripts, so put it in the server's HTML.
• Several types can live in one block, joined in an @graph.
• Markup that describes something not visible on the page is a policy violation, not a clever trick.

Whatever the platform, the same rule applies: one block per page, rendered by the server, with the values coming from the same data that renders the visible page. Markup maintained by hand in a second place drifts within a month.

This is the home page of a fictional product. Two types in one graph, with the identifiers that let other pages point at the same organisation.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://yourproduct.com/#organization",
      "name": "YourProduct",
      "url": "https://yourproduct.com/",
      "logo": {
        "@type": "ImageObject",
        "url": "https://yourproduct.com/logo-512.png",
        "width": 512,
        "height": 512
      },
      "sameAs": [
        "https://x.com/yourproduct",
        "https://github.com/yourproduct"
      ]
    },
    {
      "@type": "WebSite",
      "@id": "https://yourproduct.com/#website",
      "url": "https://yourproduct.com/",
      "name": "YourProduct",
      "publisher": { "@id": "https://yourproduct.com/#organization" }
    }
  ]
}
</script>

The logo must be crawlable and at least 112 pixels on each side. The sameAs list is how Google connects the site to the profiles that describe the same entity.

• A generator: fill the fields for a type, copy the block, paste it into the template. Faster than remembering which fields are required, and it validates the shape as you type.
• A CMS plugin: writes the common types from what the CMS already knows. Check what it emits before adding anything yourself.
• Your own template: the right answer once a value changes often. Render the JSON from the same object that renders the page, and it can never disagree with what a reader sees.

1. 1

   Validate the syntax while you write

   The Schema Markup Validator checks the JSON against schema.org without Google's extra rules. It catches a missing brace and a misspelt property.

2. 2

   Check eligibility with the Rich Results Test

   Paste the URL, not only the snippet, so the test sees the page as Google fetches it. It says which rich results the page is eligible for and which required fields are missing.

3. 3

   Read a page's markup on the live site

   After deploying, run a structured data check on the URL to confirm the block is in the served HTML and not only in your editor.

4. 4

   Watch Search Console after the next crawl

   Enhancement reports appear per type, with errors and warnings across the site. That is where a template-wide mistake shows up, which a single-page test cannot see.

• Every URL absolute, including images and item references. Relative URLs are the most common error the test reports.
• Dates in ISO 8601, and the same dates a reader sees on the page.
• Prices as numbers, with the currency in its own field. Never a string with a currency sign.
• Ratings inside their scale, and only ratings that exist on the page. A business rating itself is not shown as a rich result.
• One block per page, one type per thing. Two Organization blocks on one page is a graph nobody can read.
• When content changes, the markup changes with it, which is why it should be generated, not pasted.

Eligibility is not a promise. Google decides per query whether to draw a rich result, and it takes a crawl before anything can change at all.

• Wait for the recrawl. Nothing changes in results before Google has fetched the page again.
• Check the Search Console enhancement report for that type, which shows errors the single-page test passed.
• Remember which results no longer exist: FAQ rich results for an ordinary site, HowTo results, and the sitelinks search box, all withdrawn between 2023 and 2024.
• Check the markup is in the served HTML, not only in the rendered page, if you want the AI crawlers to read it too.

A finished job looks like this: the home page carries Organization and WebSite, every inner page carries a breadcrumb trail that matches its URL, the product page carries its type with the required fields, and the Rich Results Test reports no errors on all three.