JSON-LD: adding structured data to a site that has none

Schema.org vocabulary can be expressed as microdata, as RDFa, or as JSON-LD. All three are read. They differ in where the statement lives. Microdata and RDFa are attributes hung on the elements you already render, so the description of your page is distributed across the page. JSON-LD is a separate block that says the same thing on its own.

Here is one fact, twice.

<!-- Microdata: the statement is threaded through the markup -->
<div itemscope itemtype="https://schema.org/Organization">
  <h1 itemprop="name">Northgate Bindery</h1>
  <img itemprop="logo" src="/logo-600.png" alt="">
  <a itemprop="url" href="https://northgatebindery.com/">Home</a>
</div>

<!-- JSON-LD: the same statement, in one block, in one place -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Northgate Bindery",
  "logo": "https://northgatebindery.com/logo-600.png",
  "url": "https://northgatebindery.com/"
}
</script>

The microdata version is shorter and it is the one to avoid. Not because it is invalid, but because of what happens to it next. A designer moves the logo out of that div and the logo property silently leaves your markup. A component library re-renders the heading without the itemprop. Nobody can review the description of the page in one place, because there is no one place. You cannot diff it, you cannot serialise it from your own data model, and you cannot tell whether it is complete without reading the whole template.

JSON-LD decouples what you say about the page from how the page is laid out. That is the entire argument, and it is enough.

One exception worth knowing: if a page is already marked up in microdata and it works, there is no urgency to convert it. Do not, however, run both syntaxes for the same thing. Two descriptions of one organisation is two organisations as far as a parser is concerned, and nothing in the page decides which is authoritative.

Before you write a line, read what is being served. This is not a formality on the two platforms most sites run on.

WordPress running Yoast SEO or Rank Math already outputs a single connected block per page, typically covering the site, the current page, the publisher and, on a post, the article. Both plugins generate it from settings you may never have opened. If you now hand-add an Organization block, you have two organisation nodes with different identifiers, describing the same company, on the same page. The fix is to correct the plugin's settings, not to add a second voice. Shopify themes are the same story for products: most emit Product markup already, and a second app adding its own produces a duplicate rather than an improvement.

If a site genuinely has nothing, the first thing to state is who publishes it and what the site is. Those two nodes are what author, publisher and breadcrumb markup all end up referring to later, so getting them stable first saves rewriting everything that points at them.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://northgatebindery.com/#organization",
      "name": "Northgate Bindery",
      "url": "https://northgatebindery.com/",
      "logo": {
        "@type": "ImageObject",
        "url": "https://northgatebindery.com/logo-600.png",
        "width": 600,
        "height": 60
      },
      "sameAs": [
        "https://www.linkedin.com/company/northgate-bindery",
        "https://github.com/northgate-bindery"
      ]
    },
    {
      "@type": "WebSite",
      "@id": "https://northgatebindery.com/#website",
      "url": "https://northgatebindery.com/",
      "name": "Northgate Bindery",
      "publisher": { "@id": "https://northgatebindery.com/#organization" }
    }
  ]
}
</script>

Read the publisher value again. It is not a repeated copy of the organisation, it is a pointer to the node declared above it. That is the mechanism that stops a site with forty templates from asserting forty slightly different versions of the same company.

The other property people fill in wrongly on their first attempt is sameAs. It asserts that this entity and the thing at that URL are the same entity, so it takes your own profiles and your own Wikidata or Wikipedia entry if one exists. A link to the industry you work in, or to a directory listing you do not control, is a category rather than an identity. That distinction is most of what the Organization type exists to get right.

The honest starting point: a page with no structured data is not broken. It ranks, it renders, it gets crawled, and for many pages the markup would add nothing a good outline does not already carry. Rated on damage alone this would not be Critical.

It is Critical because of what it gates. Every other check in this pillar reads inside a block, so with no block there is nothing to validate, no properties to complete, no entity to reference and no type to get wrong. The whole group returns the same answer for the same reason, which is the signature of a prerequisite rather than a defect. The severity scale rates a check by what turns on it, and every other check in this pillar turns on this one.

The second reason is that it is the cheapest Critical on the list to clear. A missing canonical needs a decision about which URL wins. A crawl trap needs an architecture change. This needs one block of text in a template, once, and it stays fixed. A Critical you can close in an afternoon should not be sitting open.

Fetch the page rather than inspecting it in a browser tab. curl -s piped to a search for ld+json tells you what a consumer that does not run JavaScript receives, which is the thing that was in doubt. If the block appears in devtools and not in the fetched HTML, your markup exists only for clients that execute scripts.

Then paste the URL into the Schema Markup Validator at validator.schema.org. It lists every type it can parse and does not filter by whether Google renders a feature for it, which makes it the right tool for confirming presence.

What that confirms is that a block exists and parses. Two things it does not confirm are the next two rungs of the same ladder: a block that fails to parse reports as nothing found rather than as an error, and a block missing required properties reports as valid. Both look exactly like success from here.