Structured Data

A person can look at a recipe page and instantly see the title, the ingredients, and the cooking time. A search engine reads words, and has to guess which ones are the ingredients, and which are the author's life story.

Structured data removes the guessing. It is a small block of labelled facts you add to a page, in a format machines understand: "This is a recipe. Its name is this. Its cooking time is 45 minutes." In return, search engines can understand your page more precisely, and may show it in richer ways, such as with a rating, an image, or a price.

What You Will Learn

• What structured data and schema.org are
• The three formats, and why we use JSON-LD
• How to write it for Article, Recipe, Product, FAQ, Event, and more
• The honesty rules that keep your site safe
• How to escape it safely
• How to test it
• What it can and cannot do

The Big Idea

HTML Code

index.html

<head>
  <title>Easy No-Knead Rye Bread | The Bread Bin</title>

  <script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Recipe",
    "name": "Easy No-Knead Rye Bread",
    "image": "https://thebreadbin.example/img/rye.jpg",
    "author": {"@type": "Person", "name": "Ravi Patel"},
    "prepTime": "PT15M",
    "cookTime": "PT45M",
    "recipeIngredient": ["500 g rye flour", "350 ml warm water", "7 g salt"]
  }
  </script>
</head>

JSON-LD Builder

http://127.0.0.1:5500/index.html

What kind of page is it? Article (a blog post or news story)RecipeProductFAQ pageEvent

Headline

Author name

Date published (YYYY-MM-DD)

Date modified (YYYY-MM-DD)

Image address

Short description

Add this to the page:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Easy No-Knead Rye Bread",
  "author": {
    "@type": "Person",
    "name": "Ravi Patel"
  },
  "datePublished": "2026-03-12",
  "dateModified": "2026-04-02",
  "image": "https://thebreadbin.example/img/rye.jpg",
  "description": "Bake a crusty rye loaf with five simple ingredients."
}
</script>

0 things to check.

No problems found by these simple checks.

This builds valid-looking JSON-LD for common fields. Search engines require different fields for different rich results, and change their rules. Always test with the Rich Results Test and the Schema Markup Validator. And only mark up what is really, visibly on the page. The characters are escaped, so nothing you type can close the script early.

Pick a type, change the fields, and watch the JSON-LD update. Type a wrong date, or a price with a currency symbol, and see the checks respond.

What Structured Data Is

• A vocabulary. schema.org is a shared list of types (such as Recipe, Product, Event) and properties (such as name, price, startDate), agreed by the big search engines.
• A format. You write those types and properties in a format that machines parse easily. The most common is JSON-LD.
• A hint. Search engines use it to understand your page, and may use it to show rich results. It does not guarantee any special display, and it is not a ranking boost on its own.

What it will not do

Structured data does not make a weak page rank well, and adding it does not entitle you to a rich result. It helps search engines understand what is already on your page. If the page is thin, nothing is fixed.

Three Formats, One Winner

Format	How it works	Our advice
JSON-LD	A separate script block with the data	Use this. It is clean, easy to maintain, and what Google recommends
Microdata	Attributes added to your HTML elements	Works, but tangles data with markup
RDFa	Attributes added to your HTML elements	Works, and is less common

A quick look at the same fact, in microdata, so you can recognise it:

<div itemscope itemtype="https://schema.org/Recipe">
  <h1 itemprop="name">Easy No-Knead Rye Bread</h1>
</div>

JSON-LD keeps the data apart from the layout, so redesigning the page does not break it.

How JSON-LD Is Written

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Easy No-Knead Rye Bread",
  "datePublished": "2026-03-12",
  "author": {"@type": "Person", "name": "Ravi Patel"}
}
</script>

• type="application/ld+json" tells the browser this is data, not code to run.
• @context says which vocabulary you use. It is almost always https://schema.org.
• @type says what kind of thing this is.
• Other keys are the properties of that type.
• Nested objects describe related things: an author is a Person, with its own name.
• It is strict JSON: double quotes, no trailing commas, no comments.
• It can sit in the head or the body. Search engines read both.

Common Types

Type	For	Typical properties
Article, BlogPosting, NewsArticle	Posts and stories	headline, author, datePublished, image
Recipe	Recipes	name, image, recipeIngredient, recipeInstructions, cookTime
Product and Offer	Items for sale	name, image, brand, price, priceCurrency, availability
FAQPage	Questions and answers	mainEntity with Question and Answer
Event	Dates and places	name, startDate, location
BreadcrumbList	The breadcrumb trail	itemListElement. See Semantic HTML and SEO
Organization, LocalBusiness	Who you are	name, logo, address, openingHours
WebSite	The site itself	name, url
VideoObject, Review, JobPosting and more	Other content	See schema.org and each search engine's documentation

Test your sense of which type to choose:

http://127.0.0.1:5500/index.html

Which schema.org type fits each page?

A blog post about baking tips, with an author and a date Choose...ArticleRecipeProductFAQPageEventLocalBusinessBreadcrumbList

A page with ingredients, steps, and a cooking time Choose...ArticleRecipeProductFAQPageEventLocalBusinessBreadcrumbList

A bread bin for sale, with a price and stock status Choose...ArticleRecipeProductFAQPageEventLocalBusinessBreadcrumbList

A page of common questions, each with an answer Choose...ArticleRecipeProductFAQPageEventLocalBusinessBreadcrumbList

A baking class on 14 June at the village hall Choose...ArticleRecipeProductFAQPageEventLocalBusinessBreadcrumbList

A bakery's shop page with an address and opening hours Choose...ArticleRecipeProductFAQPageEventLocalBusinessBreadcrumbList

The Home > Recipes > Rye Bread trail at the top of a page Choose...ArticleRecipeProductFAQPageEventLocalBusinessBreadcrumbList

The Rules You Must Follow

Search engines publish structured data guidelines. They boil down to a few honest habits:

1. Mark up what is really on the page. Every fact in your markup should be visible to people on that page. Do not describe things that are hidden or absent.
2. Be accurate and current. Prices, dates, and availability must match the page. Out-of-date data can mislead.
3. Use the right type. Do not call a page a Recipe if it is not.
4. No fake or self-serving reviews. Do not invent ratings, or mark up reviews you wrote about your own business, as if they came from customers.
5. Do not mark up content that is not about the page, such as the same company-wide rating on every page.
6. Follow each search engine's current guidelines. They differ, and they change.

Breaking these rules can lead to a manual action, where the search engine stops showing your rich results, or lowers your site's visibility.

Fake markup hurts real people

A fake five-star rating or a wrong price does not just break a rule. It can cause someone to buy something on false information.

Rich Results: What to Expect

Rich results are the extras in a search listing: stars, prices, images, dates, breadcrumbs, and more. Some points to keep in mind:

• They are never guaranteed. Even valid markup may not be shown.
• Search engines change them. For example, Google has reduced or limited the display of some types over time, such as FAQ and how-to results. Check the current documentation before you build a plan on them.
• Different search engines support different features, and some only in certain countries and languages.
• The best reason to add markup is to be clear. Rich results are a bonus.

Linking Things Together

For bigger sites, you can connect items with @id, so each fact is stated once, and others refer to it:

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://thebreadbin.example/#org",
      "name": "The Bread Bin",
      "url": "https://thebreadbin.example/",
      "logo": "https://thebreadbin.example/img/logo.png"
    },
    {
      "@type": "Article",
      "headline": "Easy No-Knead Rye Bread",
      "publisher": {"@id": "https://thebreadbin.example/#org"}
    }
  ]
}

@graph holds several items in one block. The Article names the Organization by its @id, so you do not repeat the details.

Dates, Prices, and Other Formats

Structured data expects specific formats:

• Dates: ISO 8601, such as 2026-03-12 or 2026-06-14T10:00+01:00. Never "March 12" or "12/03/26."
• Durations: ISO 8601 durations, such as PT45M (45 minutes) or PT1H30M.
• Prices: numbers only, such as 39.00, with a separate priceCurrency of USD, EUR, or INR.
• Addresses: a PostalAddress object, with its own parts.
• Addresses of images and pages: full URLs, starting with https://.
• Availability: a full schema.org address, such as https://schema.org/InStock.

Test It

http://127.0.0.1:5500/index.html

Test it for real

1. Google's Rich Results Test shows which rich results your page could be eligible for, and any errors.
2. The Schema Markup Validator (from schema.org) checks the syntax against the shared vocabulary, for any type.
3. Search Console's enhancement reports show problems found across your live site.
4. "View source" to check that your data is in the page the server sends, not only added later by scripts.
5. Compare the markup with the page. Is every fact visible?

Structured Data in Docusaurus

Docusaurus lets you add tags to a page with its Head component, and you can place a JSON-LD script there, written with JSON.stringify so it is always valid. Some themes and plugins also add basic data for you. Always look at the built output, and test it with the tools above. Details change between versions, so check the current documentation.

Good Habits

• Use JSON-LD, in a separate script block.
• Mark up only what is visible and true.
• Choose the most specific type that fits.
• Use correct formats for dates, prices, and durations.
• Escape data that comes from users or a database.
• Keep markup in step with the page, and update it when the page changes.
• Test every template with the validators.
• Treat rich results as a bonus, not a plan.

Structured Data Checklist

• The JSON-LD is valid, with double quotes and no trailing commas
• @context and @type are set
• Every marked-up fact is visible on the page
• Dates, durations, prices, and currencies use the right formats
• Image and page addresses are full https URLs
• Required fields for the type are present
• No fake, copied, or unrelated reviews and ratings
• Data is escaped, and cannot close the script early
• No private data is included
• Tested with the Rich Results Test and the Schema Markup Validator
• Reviewed whenever the page changes

Security and Privacy Notes

• Escape everything that is not fixed. If a title, name, or description comes from a database or a user, a value containing </script> could close your script early and inject HTML. Build the JSON with JSON.stringify, and then replace < with < before you write it into the page. The builder above does this.
• Never build JSON by pasting strings together. A stray quote breaks the whole block, and an attacker can use that to inject content.
• Structured data is public. Anything in it can be read by anyone who views the source, and by every crawler. Do not include private phone numbers, personal emails, home addresses, or internal ids.
• Be careful with Person markup. Naming real people, with their photos or profile links, needs their agreement. Prefer a role or a shared address if you are unsure.
• Never fake ratings or reviews. It harms customers, and it is against search engine rules and, in many places, consumer law. This is not legal advice.
• Do not copy another site's markup, or claim another organisation's identity. It can mislead people, and may be treated as spam.
• Watch for tampering. If a hacked site has spam markup added, it can lead to penalties. Check your live markup from time to time.

Global Audience Notes

• Use international formats. ISO dates and durations, three-letter currency codes, and a clear time zone offset avoid confusion between countries.
• Describe the language. Use inLanguage (such as "en", "fr") on content, and write each language version's markup in that language.
• Addresses differ by country. PostalAddress has parts for region, postal code, and country. Fill them in the way that country does. Use the standard two-letter country code.
• Phone numbers are clearest in international format, such as +44 1225 000000.
• Prices: give the price in the currency the page shows, with one priceCurrency. Do not mix.
• Rich result support varies by country and language, so features you see in one place may not appear in another.
• Names and scripts: use UTF-8, and write names as people write them, in their own script.

Common Mistakes to Avoid

1. Marking up content that is not on the page.
2. Invalid JSON, such as a trailing comma or single quotes.
3. Missing @context or @type.
4. Dates like "March 12" instead of 2026-03-12.
5. Prices with symbols or words, such as $39 or free.
6. Relative image addresses such as /img/rye.jpg.
7. Wrong or too-general types.
8. Fake or copied reviews.
9. Out-of-date prices and availability.
10. Unescaped user data inside the script.
11. Markup added only by scripts, and never tested in the final page.
12. Treating markup as a ranking trick.

Practice Time

Try these in your browser and your editor:

1. Use the builder with each of the five types. Which field did you find hardest?
2. Type a wrong date and a price with a symbol in the builder. What does it say?
3. Take the type quiz. Which scenario made you hesitate?
4. Run the checker on the messy page, fix every problem, and run it again.
5. Write JSON-LD for a page on a site you know, and check that every fact is visible on that page.
6. Run Google's Rich Results Test on the page.
7. Run the Schema Markup Validator on the same page. Do the two tools agree?
8. Add an Organization block with a logo, and link an Article to it with @id.
9. Try to break your script on purpose, by putting a quote and </script> in a title. How does your code handle it?
10. Bonus: add BreadcrumbList markup to a page, and compare it with the visible breadcrumb.

Quick Recap

Click a question to check your answer.

1. What is structured data?

A block of labelled facts about a page, written in a format that machines understand, using the shared schema.org vocabulary.

2. Which format should you use?

JSON-LD, in a script block with type="application/ld+json". It keeps the data separate from your layout.

3. Does structured data guarantee rich results or better ranking?

No. It helps search engines understand the page, and may make it eligible for rich results, but display is never guaranteed, and it is not a ranking boost on its own.

4. What is the most important rule?

Only mark up what is really visible on the page, and keep it accurate. Fake or hidden markup can lead to penalties, and mislead people.

5. How should dates and prices be written?

Dates in ISO 8601 (2026-03-12), durations like PT45M, and prices as plain numbers with a separate three-letter priceCurrency.

6. How do you stop user data breaking out of the script?

Build the JSON with JSON.stringify, and replace < with < before writing it into the page, so </script> can never appear inside the data.

Key Takeaways

• Structured data labels the facts on your page for machines, using schema.org.
• Use JSON-LD, in a script block, with valid JSON.
• Choose the right type, and fill in its key fields.
• Mark up only what is visible, true, and current.
• Use correct formats for dates, durations, prices, and addresses.
• Escape everything that is not fixed.
• Test with the Rich Results Test and the Schema Markup Validator.
• Rich results are never guaranteed. The real goal is clarity.

Next, learn how to control how your links look when they are shared, with Open Graph.