Structured Data That Machines Read

Structured data is the one place where you tell a machine what your page means rather than hoping it infers it. It is also where honest sites quietly stop being honest, and where a mechanical detail — that JSON-LD lives inside a <script> element — decides whether half the systems you care about ever see it.

Three encodings, one vocabulary

schema.org is a vocabulary of types and properties. It can be expressed three ways in a page, and the choice matters more than it looks.

Use JSON-LD unless you have a specific reason not to. It is generated from the same variables your template already has, which is the only arrangement in which the markup and the page cannot disagree.

Why JSON-LD is invisible to a text extractor

Here is the mechanism nobody writes down, and it is tier-2 observable in one command.

A structured-data parser looks for script elements of type application/ld+json and reads their contents. An HTML-to-text converter — the kind that sits in the fetch stage of a retrieval pipeline, turning a fetched page into something to chunk — does the opposite: it strips script and style elements first, precisely because their contents are not prose and would poison the text with JavaScript. Your JSON-LD is discarded before the text is ever chunked.

Prove it on your own page in one line, with any HTML-to-text tool:

# Does the structured data survive text extraction?
curl -sS https://example.com/some-page > page.html

# What a structured-data parser sees:
grep -c 'application/ld+json' page.html

# What a text extractor sees (python-readability, trafilatura,
# lynx -dump, or your own stripper) — search the output for a value
# that appears ONLY in the JSON-LD:
lynx -dump -nolist page.html | grep -c 'a-value-only-in-your-jsonld'

If the second count is zero, the conclusion is not that structured data is useless. It is that structured data reaches parsers, and visible text reaches extractors, and you should not rely on one to carry a fact the other needs. Every fact that matters must be in the prose. The markup is a second, machine-typed statement of facts the page already makes.

Microdata behaves differently here, because its values are the visible text — an extractor keeps them by definition. That is not a reason to switch, but it is the reason the rule below is not merely an ethical preference.

The rule that keeps markup honest

One rule, and it makes several other decisions for you: nothing in the structured data may be a fact the page does not also show a human. Every value passed to the generator should be the same variable the visible markup renders.

What that rules out, concretely:

• An aggregateRating with no reviews on the page. The most abused property in the vocabulary and the one most likely to earn a manual action.
• A priceValidUntil you have not committed to. If you cannot honour the date, it is not a fact.
• FAQ markup for questions not on the page. The guidance is explicit that the question and answer text must both be visible.
• An author nobody wrote. If the page has no byline, the author is the organisation, and saying so is more credible than inventing a person.
• An image that does not illustrate the article. Pointing a thousand articles at one site-wide mark is a claim that each illustrates itself; omitting the property is more honest and costs nothing.

The rule also gives you an implementation test: if your generator takes an argument that is not already on the page, that argument is the bug.

The types worth the effort

These types and properties all exist in the vocabulary and are widely consumed. Pick by what your page is, not by what sounds impressive.

A complete article block

Generated from the page’s own fields, with no value invented. The escaping detail in the last line is not optional: a string in your data containing a closing script tag would end the element early, which is the one genuine injection risk in a block like this.

function articleJsonLd(page, siteUrl) {
  const url = `${siteUrl}/learn/${page.slug}`;
  return {
    "@context": "https://schema.org",
    "@type": "TechArticle",
    "@id": url,
    mainEntityOfPage: { "@type": "WebPage", "@id": url },
    headline: page.title,          // the visible <h1>
    description: page.summary,     // the meta description
    datePublished: page.published, // the date the URL began to exist
    dateModified: page.updated,    // the visible "updated" line
    timeRequired: `PT${page.minutes}M`,  // the visible "N min read"
    inLanguage: "en",
    author:    { "@type": "Organization", name: "Example", url: siteUrl },
    publisher: { "@type": "Organization", name: "Example", url: siteUrl },
  };
}

// Rendering it. The escape matters.
<script
  type="application/ld+json"
  dangerouslySetInnerHTML={{
    __html: JSON.stringify(data).replace(/</g, "\\u003c"),
  }}
/>

timeRequired takes an ISO 8601 duration, so “6 min read” is PT6M. datePublished and dateModified take ISO dates or datetimes. Getting the format wrong is the most common validator error and it is silent otherwise.

What stopped producing rich results

Two changes from 2023 are still being sold as tactics and are worth knowing precisely, because they are tier-1 facts you can read in the operator’s own documentation.

• FAQ rich results were restricted. Google announced in August 2023 that the FAQ rich result would generally be shown only for well-known authoritative government and health sites. The markup is still valid and still parsed; the display change is what went away for everyone else.
• HowTo rich results were removed. Announced in the same change, limited and then dropped as a search feature.

The lesson generalises past those two: a display feature is a product decision and can be withdrawn, while the vocabulary is a standard and does not disappear. Mark up your page because the markup is a true, structured statement of what the page contains. If you are marking it up for a specific visual treatment, you have bought an asset with an unannounced expiry date.

Validating it, and testing extraction

1. Validate the vocabulary. The Schema Markup Validator at validator.schema.org checks your JSON against schema.org itself, with no opinion about any search product. This is the one that tells you whether your types and properties are real.
2. Check the search-product view. Google’s Rich Results Test tells you whether a specific feature is eligible, which is a narrower and more volatile question.
3. Validate the rendered page, not the source. If your markup is injected client-side, paste the URL rather than the source — or better, move the block to the server response, because a non-rendering fetcher will never run the injection at all. See JavaScript rendering and what crawlers see.
4. Diff the markup against the page. Take every value in the JSON and confirm the string appears in the visible text. A twenty-line script that does this in CI is the cheapest possible defence against the whole class of dishonest-markup problems.
5. Run the extraction test from the second section, so you know which of your facts survive to the text a chunker sees.

What structured data does not do

It is not a ranking factor in the sense people mean, and no assistant operator documents using it to choose sources. Claims that adding JSON-LD raises your citation rate are tier 3 under the scale in what is real and what is sold — unverifiable at your scale and unsupported by any public documentation.

What it does do is cheap, real and independent of that question: it removes ambiguity for parsers that read it, it makes your dates, authorship and identity machine-readable, and it forces you to write down what your page actually claims to be. That is worth an afternoon. It is not worth a retainer.