JSON-LD structured data: a practical developer guide

JSON-LD is a way to describe page content in a machine-readable format. Search engines and other tools can use it to understand the page type, name, author, organization, or other facts that the page visibly supports.

Google recommends JSON-LD when a site's setup supports it because it keeps the structured data separate from the visible HTML. Read the introduction to structured data markup before choosing a schema type.

Choose a type that matches the page

Start with the page's visible purpose. An article can use Article. A home page can use WebSite. A product page may use Product when it contains the required product information. Read the documentation for the specific rich result before adding fields.

Do not add a type because it sounds useful. Structured data must describe the page a reader can see. A blog page with no review content should not contain fake review markup. A product page should not claim a price, availability, or rating that the page does not show.

Add JSON-LD in the document head

This example describes an article. Replace the values with facts from the rendered page:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Website launch checklist for developers",
  "description": "A checklist for checking a public page before launch.",
  "url": "https://example.com/blog/website-launch-checklist",
  "datePublished": "2026-09-01",
  "author": {
    "@type": "Organization",
    "name": "Example team"
  }
}
</script>

Use valid JSON, not JavaScript expressions. Escape values through the serializer in your framework instead of joining strings by hand. Make the url agree with the page's canonical URL. Use ISO 8601 dates for date fields.

Include complete, visible facts

Required properties depend on the rich result type. Add recommended properties only when you have accurate values. Fewer complete fields are better than a large object full of placeholders.

Keep these values synchronized with the page:

• The headline and description match visible copy.
• The author name links to a real author or organization identity.
• The image exists at the advertised absolute URL.
• The publication and modification dates reflect the actual article.
• The page URL resolves to the same canonical route.

If a value changes, update the page and JSON-LD together. Generate both from the same route data when possible.

Validate the result

Use the Rich Results Test for a page that targets a Google rich result. Also inspect the rendered HTML in browser developer tools. A source-only request may not show JSON-LD that a client application injects after load.

Check for:

1. Valid JSON syntax.
2. The intended @type.
3. Required properties for that result type.
4. Absolute URLs that return the expected content.
5. Values that readers can see on the page.
6. No hidden, misleading, or placeholder claims.

Google's structured data policies explain why valid syntax alone is not enough. Structured data can make a page eligible for a search feature. It does not guarantee that Google will show that feature or improve a ranking.

Handle client-rendered pages carefully

Google can process JSON-LD generated by JavaScript, but server-rendered markup is easier to inspect and less dependent on a second rendering pass. If your application injects JSON-LD in the browser, confirm that the final DOM contains one correct script and that it appears after a clean load.

Avoid duplicate objects from the server shell and client app unless you intentionally combine them. Duplicate or conflicting values can make debugging harder.

Slop Audit checks whether it can parse meaningful JSON-LD from the public page and links the result to the page evidence. It does not certify structured data or guarantee a rich result. The canonical URL guide covers the URL signal that should agree with the JSON-LD url.

JSON-LD release checklist

visible page type → supported schema → valid JSON
→ required fields → matching visible facts → Rich Results Test
→ rendered DOM check → production URL

Treat structured data as part of the page template. Test one representative route after every template change, then check the important page types in production.