A human reading a page instantly understands that "14 March" is the publication date, that the name at the bottom is the author and that the number with the euro sign is a price. For a program it is not so obvious. Structured data is additional information, in a standard format, that explicitly describes what a page is about and what its main properties are.
Schema.org: the shared vocabulary
Schema.org is a shared vocabulary, born from a collaboration between the main search engines, which defines types (such as Article, Organization, Person, Product, Event, LocalBusiness) and their properties (such as headline, author, datePublished, price). Types are organised in a hierarchy: NewsArticle and BlogPosting are specialisations of Article, which in turn derives from CreativeWork.
The vocabulary can be expressed in three syntaxes: Microdata, RDFa and JSON-LD. The first two add attributes directly to HTML elements; JSON-LD instead puts all the data in a separate block.
Why JSON-LD
JSON-LD is the most practical format for several reasons:
- it is separate from the visible markup, so you can change the layout without touching the structured data and vice versa;
- it is easy to generate from a template or a static generator, starting from the same data that produces the page;
- it is readable and easy to check at a glance;
- it is the format recommended in Google's documentation.
It goes inside a script element with a specific type, which the browser does not execute:
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "Structured data with Schema.org and JSON-LD",
"datePublished": "2025-02-10",
"dateModified": "2025-03-01",
"author": {
"@type": "Person",
"name": "Author Name",
"url": "https://www.example.com/about/"
},
"image": "https://www.example.com/img/cover.jpg"
}
</script>
@context indicates the vocabulary, @type the type of the entity described. Dates follow the ISO 8601 format.
Useful examples for most sites
Organisation or person
On the home page of a business or personal site you can describe the entity behind the site:
{
"@context": "https://schema.org",
"@type": "Organization",
"name": "Example Ltd",
"url": "https://www.example.com/",
"logo": "https://www.example.com/img/logo.png",
"sameAs": [
"https://www.linkedin.com/company/example"
]
}
The sameAs property links the entity to its official profiles on other platforms, helping engines understand that it is the same organisation.
Breadcrumbs
The navigation path helps represent the page's position within the site:
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{ "@type": "ListItem", "position": 1, "name": "Guides", "item": "https://www.example.com/guides/" },
{ "@type": "ListItem", "position": 2, "name": "SEO", "item": "https://www.example.com/guides/seo/" }
]
}
Several entities on the same page
You can add several JSON-LD blocks or use @graph to gather them into one, linking entities to each other with @id identifiers. For example, the article can reference as its publisher the organisation described elsewhere in the graph, without repeating all its data.
What you get (and what you don't)
Structured data can make a page eligible for rich results: rating stars, prices, event dates, breadcrumbs instead of the URL and other special formats. Three important clarifications:
- Eligible does not mean guaranteed: the engine decides whether and when to show a rich result.
- The types that produce rich results and their requirements change over time: some are introduced, others restricted. Before investing in a specific type, check the search engine's current documentation.
- Structured data is not in itself a factor that lifts a page in the rankings; it helps understanding and presentation.
The fundamental rule: match the visible content
Structured data must describe what the user sees on the page. Adding reviews that do not appear, prices different from those displayed or hidden questions and answers goes against search engine guidelines and can lead to manual actions that remove eligibility for rich results. The safest way to follow the rule is to generate JSON-LD and visible HTML from the same data source.
Generating the data automatically
In a static generator or a CMS, the JSON-LD block should be produced by the page template, not written by hand. A conceptual example in JavaScript:
const structuredData = {
'@context': 'https://schema.org',
'@type': 'BlogPosting',
headline: post.title,
datePublished: post.date,
author: { '@type': 'Person', name: post.author }
};
const json = JSON.stringify(structuredData).replace(/</g, '\\u003c');
Replacing the < character prevents a title containing </script> from closing the block prematurely: it is a small security precaution not to forget when the data comes from editable input.
Validating
- Google's Rich Results Test indicates whether the page is eligible and reports errors and warnings.
- The official Schema.org validator checks correctness against the vocabulary, independently of any specific engine.
- In Search Console, the enhancement reports show errors detected across the whole site over time.
Distinguish errors (which make the data unusable) from warnings (missing recommended properties): the latter block nothing, but filling them in makes the data richer.
In short
- Structured data explicitly describes page content using the Schema.org vocabulary.
- JSON-LD is the most convenient format: separate from the markup and easy to generate.
- It can make a page eligible for rich results, with no guarantees.
- It must always match the visible content: generate it from the same source as the page data.
- Validate with testing tools and monitor errors over time.
