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 element — decides whether half the systems you care about ever see it.
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.
| Encoding | Description | | --- | --- | | JSON-LD | A JSON object in a element. Separate from the visible markup, so it survives a redesign. The recommended form, and the one with the mechanical caveat in the next section. | | Microdata | itemscope, itemtype and itemprop attributes on the visible elements themselves. Cannot drift from what is displayed, because it is attached to it. Verbose, and painful to keep correct across a component library. | | RDFa | The same idea with a different attribute set, from the wider linked-data world. Fully supported by the major parsers and rarely chosen for new work. |
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.
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.
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.
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.
These types and properties all exist in the vocabulary and are widely consumed. Pick by what your page is, not by what sounds impressive.
| Type | Description | | --- | --- | | Article / TechArticle / BlogPosting | For prose. TechArticle is an Article subtype and is the accurate choice for documentation and technical explainers. Carries headline, description, datePublished, dateModified, author, publisher, inLanguage, timeRequired. | | BreadcrumbList | The trail you already render, as ListItem entries with position and item. Cheap, unambiguous, and it tells a parser your site's shape without it inferring one from your navigation. | | Organization | Your identity, on one page, with sameAs pointing at the profiles that are also you. This is the property that ties your identifiers together and it matters for entity resolution — see the page on false claims about your company. | | WebSite | Site-level name and URL, usually with the Article's isPartOf pointing at it. | | CollectionPage + ItemList | For a hub that lists other pages. The ItemList should be the same list in the same order the page renders, which is the point of it. | | Product / Offer | For something purchasable, with price and priceCurrency. Only where the price is on the page and current. | | SoftwareApplication | For a tool or an app: applicationCategory, operatingSystem, and a zero-price Offer where it is genuinely free. Do not describe a calculator as an Article. | | Dataset | For downloadable data, with distribution, license and creator. Under-used, and it is the type most likely to make a data page findable by something that wants data. | | FAQPage / QAPage | Question and Answer entries. Still valid vocabulary and still parsed, but see the section on rich results before assuming it earns a display change. | | citation / isBasedOn / license | Properties rather than types, and the most underused ones here. They state what a page rests on and what may be done with it, in machine-readable form. |
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.
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.
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 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. 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. 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. 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. Run the extraction test from the second section, so you know which of your facts survive to the text a chunker sees.