Adding Structured Data to HTML Documents

Structured data is a standardized format for providing explicit information about a page to search engines. By adding structured data to your HTML, you can unlock "rich snippets" in Google and other search engines.

Rich snippets are enhanced search results that display extra information, such as star ratings on recipes, prices on products, or dates on event tickets. You've probably seen them in search results already.

While search engines are smart, they often struggle to differentiate between a random number and a product's price, or a name and a book's author. Structured data explicitly connects this data for them.

So by adding structured data to your HTML, you're essentially giving search engines a cheat sheet to understand your content better. This can lead to higher click-through rates and better search engine rankings.

Older Standards

In the past, developers used two older standards to add structured data: Microdata and RDFa. Both required you to add special attributes directly to your existing HTML tags. For example:

While these approaches still work, they make HTML very cluttered and are much harder to maintain.

Using JSON-LD

The modern alternative is JSON-LD (JavaScript Object Notation for Linked Data). Instead of scattering attributes throughout your HTML, you gather all the structured data into a single self-contained block of JSON, wrapped in a script tag. This block is entirely separate from your visible HTML and lives inside the head of your document.

This approach has several advantages:

• Clean HTML: Your visible markup stays clean and readable. No extra attributes cluttering your tags.
• Easy to update: The structured data is all in one place, so you can update it without touching the rest of the page.
• Google's recommended format: Google explicitly recommends JSON-LD over the older alternatives. Other search engines like Bing and DuckDuckGo also support JSON-LD.

The vocabulary used to define this data is maintained by Schema.org. They have formulas for almost everything, including local businesses, products, articles, recipes, job postings, and more.

Every JSON-LD block uses two mandatory fields: @context, which always points to https://schema.org, and @type, which declares what kind of thing the page is describing. You then add properties relevant to that type.

Here is a basic example for an Article page:

And here is an example for a Product page. Notice how the @type changes, and the properties change with it to match what is relevant to a product (offers, price, availability, etc):

Schema.org defines hundreds of types. You can browse the full list at Schema.org to find the type that best matches your content.

Full Working Example

Below is a visual example of a recipe card. The beautiful visual layout is built with standard HTML and CSS. Behind the scenes, an invisible JSON-LD script block is explicitly feeding the exact ingredients, cooking time, and star rating directly to search engines.

View the source code in the preview to see the invisible JSON-LD data block: