Structured Data and Schema Markup: A Developer Guide

Structured data is machine-readable markup that describes the meaning of a page's content rather than just its appearance. Search engines, social platforms, and other consumers use it to understand what a page is about — a product, an article, a recipe, an event — and may use that understanding to render richer search results. This guide covers the vocabulary, the recommended syntax, the types worth implementing, and how to validate your work.

What structured data actually is

Structured data attaches a defined vocabulary to your content so a parser can extract entities and their properties. Instead of guessing that "$24.99" near a heading is a price, a consumer reads an explicit price property tied to a Product entity. The dominant shared vocabulary is Schema.org, a collaborative project backed by Google, Microsoft, Yahoo, and Yandex that defines types (like Article, Recipe, Organization) and the properties each type supports.

Schema.org is the vocabulary; it is not the syntax. The same vocabulary can be expressed in three encodings: JSON-LD, Microdata, and RDFa. JSON-LD has become the practical default because it lives in a single <script> block, keeps semantic data separate from your presentation markup, and is straightforward to generate on the server or client. For a deeper comparison of the encodings, see our JSON-LD vs Microdata breakdown.

JSON-LD: the recommended syntax

JSON-LD (JSON for Linked Data) embeds structured data as a JSON object inside a <script type="application/ld+json"> tag, typically in the document head. Because it is decoupled from the visible HTML, you can add, change, or remove it without touching your templates or layout, and you avoid sprinkling itemprop attributes throughout the DOM. Google's documentation explicitly recommends JSON-LD over the inline alternatives.

A minimal article example looks like this:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Structured Data and Schema Markup: A Developer Guide",
  "datePublished": "2026-05-27",
  "author": {
    "@type": "Person",
    "name": "Shannon Patterson"
  }
}
</script>

Two keys are mandatory. The @context tells the parser which vocabulary you are using — almost always https://schema.org. The @type names the entity. Everything else is a property defined for that type. Generate the payload from your data model and serialize it; never hand-maintain it as a static string that can drift out of sync with the page. A Schema JSON-LD generator is a fast way to scaffold a valid block for a new type before you wire it into templates.

Microdata, briefly

Microdata expresses the same vocabulary through HTML attributes: itemscope marks an element as an entity, itemtype gives its type URL, and itemprop labels each property. It still works and is parsed correctly, but it couples semantics to layout, which makes it harder to maintain. Reach for it only when you cannot inject a script tag.

Schema types worth implementing

You do not need to mark up everything. Focus on the types that match your content and that consumers actually act on. The most broadly useful ones for a typical site:

• Organization and WebSite — site-level identity: name, logo, and links. Often placed once on the home page.
• Article / BlogPosting / NewsArticle — headline, author, publish and modified dates for editorial content.
• BreadcrumbList — the page's position in your site hierarchy, which can surface as a breadcrumb trail in results.
• Product with Offer — name, price, currency, and availability for commerce pages.
• FAQPage and HowTo — question/answer pairs and ordered steps; useful for documentation and support content.
• LocalBusiness — address, hours, and contact details for physical locations.

Each type has required and recommended properties. A Product with a price but no Offer wrapper, or a Review without an author, may be parsed but ignored for rich results. Check Schema.org's reference for the specific type, and treat Google's "required" list as the stricter gate if you are targeting Google features.

Common mistakes that break it

Structured data fails quietly. The page still renders, so problems are easy to ship unnoticed. The recurring causes:

• Marking up content that is not on the page. Structured data must describe what a user actually sees. Declaring a rating or price that does not appear in the visible content violates the guidelines and risks a manual penalty.
• Invalid JSON. A trailing comma or an unescaped quote inside a string makes the whole block unparseable, and the parser typically discards all of it. Run the payload through a JSON formatter to catch syntax errors before deploying.
• Wrong or missing @type. A typo in the type name, or omitting @context, means the parser cannot resolve the vocabulary.
• Stale data. Hardcoded JSON-LD that no longer matches the rendered price, date, or stock status. Generate it from the same source of truth as the page.
• Confusing structured data with meta tags. They serve different layers — see the section below.

How structured data differs from meta tags and Open Graph

These are often lumped together but operate at different levels. Standard meta tags (<title>, <meta name="description">) describe the page to a search engine and influence the snippet text. Open Graph tags (og:title, og:image) control how a link is rendered when shared on social platforms. Structured data describes the entities within the page using a formal vocabulary, enabling richer interpretations such as breadcrumbs, FAQ expanders, or product detail in results.

In practice you use all three together: meta tags for the snippet, Open Graph for social cards, and JSON-LD for entity semantics. A meta tag generator covers the first two, and our meta tags SEO guide goes deeper on that layer.

Validating your markup

Always validate before and after deploying. Two tools are standard. Google's Rich Results Test checks whether your markup is eligible for specific Google rich-result features and reports type-specific errors. The vendor-neutral Schema.org Validator (formerly the Structured Data Testing Tool) reports general syntax and vocabulary issues without tying you to one search engine's feature set.

Validation catches structural problems — malformed JSON, unknown properties, missing required fields — but it cannot tell you whether the data is true. That responsibility stays with you: the markup must always reflect the page's actual, visible content. After a feature ships, spot-check the rendered HTML to confirm the JSON-LD that reaches production matches what your templates intended, then preview how the page may appear with a SERP preview tool.

Generating JSON Schema vs Schema.org markup

One naming collision worth clearing up: "JSON Schema" and "Schema.org markup" are unrelated despite the shared word. JSON Schema is a specification for validating the shape of JSON data (required fields, types, formats) in APIs and config files. Schema.org markup describes web content for search engines. If you are documenting an API payload, you want a JSON Schema generator; if you are marking up a page for search, you want JSON-LD with a Schema.org type.

Frequently Asked Questions