Structured data (Schema markup)
Structured data labels page facts in a machine-readable format, usually JSON-LD using the Schema.org vocabulary, so software does not have to guess entities.
Structured data is the practice of labeling the facts on a web page in a machine-readable format, usually JSON-LD written in the Schema.org vocabulary, so software does not have to guess the entities and relationships from the body text. It is often called Schema markup.
The same information exists on a page in two forms: the text written for people, and fields written for machines inside a <script type="application/ld+json"> block. The second form removes ambiguity. In body text, whether “Shanghai” is an address or the topic of an article depends on context. In a field like "addressLocality": "Shanghai", there is only one way to read it.
Common types for entity recognition
- Organization: the company itself. Fields such as
legalName,foundingDate,taxIDandaddressare what make a brand entity uniquely identifiable, and sameAs ties your domains and external profiles into one entity. - FAQPage: question-and-answer pairs. Useful for disambiguation questions such as “Is X the same company as Y?”
- DefinedTerm: a glossary definition.
alternateNamerecords aliases so different names point to the same concept. - BreadcrumbList: where the page sits in the site hierarchy.
- Article / WebPage: the content and who published it.
- Service: what a service page offers.
Why markup silently fails
The most common problem with structured data is not that it is missing. It is that it exists but the whole block is thrown away:
- Unescaped quotation marks. A straight double quote inside answer text breaks the JSON. The entire JSON-LD block gets discarded, while the page itself looks completely normal.
- Conflicting blocks. The same entity is given different names or addresses in different script blocks on the same page or across pages.
- Markup that does not match the page. The markup states facts that a visitor cannot find in the visible text.
The fix is to stop writing JSON by hand. Generate JSON-LD from data with a serializer, which handles escaping for you. Give each entity a stable @id and keep its declaration consistent across pages.
How it fits with llms.txt
Structured data is aimed at crawlers that parse web pages. llms.txt is aimed at AI clients that read plain text. They do not replace each other: structured data labels facts, llms.txt provides navigation.
Structured data also feeds into search engines’ knowledge graphs. Markup is effectively a candidate record that gets cross-checked against other sources before it is trusted.
How to check after publishing
- Validate the syntax. Parse the JSON to confirm it is valid.
- Check against the page. Compare each field to the visible content. Is the product image reachable? Is the service name correct? Is the price still current? Valid JSON does not mean the fields meet the requirements of any particular search feature.
- Use the search engine’s own tools. Run the target search engine’s testing tool for the types it supports.
Not every type in the Schema.org vocabulary corresponds to a Google rich result, and passing a test does not guarantee any special display. Above all, never add ratings, reviews or client results that do not exist just to fill out fields. Google’s structured data guidelines treat markup that misrepresents page content as a policy violation.
An example for a company website
- The about page describes the Organization.
- Service pages describe a Service.
- Articles describe an Article.
- All of them reference the publisher through the same stable
@id.
The same entity can be described on several pages, but the name, URL and other facts must match. There is no need to declare every business page as the same article.
When a product entry point or the scope of a service changes, check the body text, the FAQ and the JSON-LD together, so machines do not keep reading the old facts. For internal sign-off, keep a field list that records where each value came from and when it was last checked, rather than only a screenshot of a passing test. A maintained knowledge base makes this much easier.
Limits
Structured data makes facts easier to read; it does not make them more trusted. Authority still comes from the content itself and from third-party evidence that confirms it.
To check your entity markup against your site content, see the free GEO audit.
Related
- Brand entity — A brand entity is the record a machine uses to treat a brand as one uniquely identifiable object, not just a string of characters that appears in text.
- Knowledge graph — A knowledge graph stores facts as entity–relationship–entity triples, so machines can reason along connections instead of only matching strings of text.
- llms.txt — llms.txt is a plain-text Markdown file at a website's root that tells large language models what the site is and which key pages are worth reading first.