JSON-LD Explained

JSON-LD (JSON Linked Data) is a method of encoding structured data in a <script type="application/ld+json"> tag so that search engines and AI crawlers can understand what a page is about — without parsing the HTML. It's the format Google uses for rich results (recipe cards, FAQ dropdowns, product prices in search) and one of the primary signals AI engines use to recognize entities (organization names, authors, products). JSON-LD is based on the Schema.org vocabulary and is the only structured data format Google recommends for new implementations. This guide covers the core syntax (@context, @type, @id, @graph), the most important schema types, implementation in HTML and Next.js, and validation tools. For JSON basics see that guide first.

Use Jsonic to validate your JSON-LD syntax before deploying.

Open JSON Formatter

JSON-LD syntax: @context, @type, @id, and @graph

Every JSON-LD document starts with four special keywords prefixed with @. These keywords are part of the JSON-LD specification and are what distinguish it from plain JSON.

  • @context: declares the vocabulary being used — almost always "https://schema.org". This tells parsers that property names like name, author, and datePublished refer to Schema.org definitions.
  • @type: the entity type — "Article", "Organization", "FAQPage", etc. This is the most important field: it tells Google and AI engines what kind of thing the page describes.
  • @id: a URL that uniquely identifies this entity across all pages. Used for entity disambiguation — if two pages both describe the same organization, they should share the same @id URL. Typically set to the canonical URL of the page or entity.
  • @graph: an array of multiple entities in one script tag — more efficient than multiple separate <script> tags. Entities inside @graph can cross-reference each other using their @id values.

The minimal Article schema looks like this:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "@id": "https://example.com/blog/my-post",
  "headline": "My Post Title",
  "datePublished": "2026-05-11",
  "dateModified": "2026-05-11",
  "author": {
    "@type": "Organization",
    "name": "Acme Corp",
    "url": "https://example.com"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Acme Corp",
    "url": "https://example.com"
  }
}
</script>

Note: JSON-LD uses camelCase property names exactly as defined on schema.org (e.g., datePublished, not date_published or DatePublished). Case matters — a property with the wrong casing is simply ignored by parsers. As for placement, you can put the <script> tag anywhere in <head> or <body> — Google recommends <head> for fastest discovery.

The most important schema types and when to use them

Schema.org defines hundreds of types, but only a handful are used in practice for web pages. The table below covers the types Google supports for rich results and the types AI engines weight most heavily for entity recognition.

Schema TypeRich ResultWhen to use
Article / BlogPostingN/A (content signal)Any article or blog post — basic content signal
FAQPageFAQ dropdown in SERPsPages with Q&A sections
HowToStep-by-step rich resultTutorial pages with numbered steps
ProductPrice, availability, reviewsProduct pages
OrganizationKnowledge panelBrand/company identity (in root layout)
WebSiteSitelinks search boxHomepage only
BreadcrumbListBreadcrumb in SERPAny page in a hierarchy
PersonKnowledge panelAuthor bio pages
EventEvent rich resultUpcoming events
RecipeRecipe cardFood/cooking pages

For developer tool sites like this one, the three most impactful types are Article, FAQPage, and Organization. Here are code stubs for each:

// Article — every content page
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "JSON-LD Explained",
  "datePublished": "2026-05-11",
  "dateModified": "2026-05-11",
  "author": { "@type": "Organization", "name": "Jsonic" },
  "publisher": { "@type": "Organization", "name": "Jsonic" }
}

// FAQPage — pages with Q&A content
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What is JSON-LD?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "JSON-LD is a method of encoding structured data..."
      }
    }
  ]
}

// Organization — root layout (appears on every page)
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Jsonic",
  "url": "https://jsonic.io",
  "logo": "https://jsonic.io/logo.png",
  "sameAs": [
    "https://twitter.com/jsonic_io",
    "https://github.com/jsonic-io"
  ]
}

Article and FAQPage: the two most impactful for content sites

Article schema

The core properties for Article are: headline, description, datePublished, dateModified, author, publisher, and image. Of these, dateModified matters the most for AI engine citations — both Perplexity and Google's AI Overviews weight content freshness heavily. A page with an accurate dateModified will rank above an identical page without it for time-sensitive queries.

FAQPage schema

FAQPage uses a mainEntity array of Question + Answer objects. Each question/answer pair is self-contained and can be cited independently by AI engines. The trigger for Google's FAQ rich result is having 2 or more questions that are visible on the page — the content in acceptedAnswer.textmust match the visible text. FAQPage boosts AI citations because each Q&A chunk is the ideal size for retrieval-augmented generation: a complete thought in 1–3 sentences.

The recommended approach is to combine both types in a single @graph:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Article",
      "@id": "https://example.com/guides/json-ld-explained",
      "headline": "JSON-LD Explained: Structured Data for SEO and AI Engines",
      "description": "JSON-LD adds machine-readable structured data to web pages...",
      "datePublished": "2026-05-11",
      "dateModified": "2026-05-11",
      "author": {
        "@type": "Organization",
        "name": "Jsonic",
        "url": "https://jsonic.io"
      },
      "publisher": {
        "@type": "Organization",
        "name": "Jsonic",
        "url": "https://jsonic.io",
        "logo": {
          "@type": "ImageObject",
          "url": "https://jsonic.io/logo.png"
        }
      },
      "image": {
        "@type": "ImageObject",
        "url": "https://jsonic.io/opengraph-image",
        "width": 1200,
        "height": 630
      }
    },
    {
      "@type": "FAQPage",
      "mainEntity": [
        {
          "@type": "Question",
          "name": "What is JSON-LD?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "JSON-LD (JSON Linked Data) is a standard for encoding structured data as JSON, embedded in a web page via a script tag."
          }
        },
        {
          "@type": "Question",
          "name": "Does JSON-LD help with SEO?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "Yes — JSON-LD enables rich results in Google Search including FAQ dropdowns, HowTo steps, and breadcrumbs."
          }
        }
      ]
    }
  ]
}
</script>

Organization and WebSite: entity recognition for AI engines

Organization

Organization schema tells AI engines that your domain is a real, identifiable entity. The key properties are name, url, logo, and — most critically — sameAs. The sameAs property is an array of URLs linking your organization to its profiles on other authoritative sites. This is how AI engines connect your domain to their training data: if ChatGPT has seen your ProductHunt launch or GitHub org, the sameAs link helps it treat your site as a citable, known entity rather than an anonymous URL.

The sameAs sources with the most impact for AI engine recognition: ProductHunt, GitHub, Twitter/X, LinkedIn, and Wikipedia (if applicable). Include every profile you have — the more corroborating signals, the stronger the entity association.

WebSite and BreadcrumbList

WebSite goes on the homepage only. Its main value is enabling the sitelinks search box in Google Search results via a potentialAction + SearchAction. BreadcrumbList replaces the raw URL in SERP snippets with a human-readable path like Jsonic > Guides > JSON-LD. Using @id references inside @graph, you can linkBreadcrumbList items back to the WebPage or Article they belong to:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://jsonic.io/#organization",
      "name": "Jsonic",
      "url": "https://jsonic.io",
      "logo": {
        "@type": "ImageObject",
        "url": "https://jsonic.io/logo.png"
      },
      "sameAs": [
        "https://twitter.com/jsonic_io",
        "https://github.com/jsonic-io",
        "https://www.producthunt.com/products/jsonic",
        "https://www.linkedin.com/company/jsonic"
      ]
    },
    {
      "@type": "WebSite",
      "@id": "https://jsonic.io/#website",
      "url": "https://jsonic.io",
      "name": "Jsonic",
      "publisher": { "@id": "https://jsonic.io/#organization" },
      "potentialAction": {
        "@type": "SearchAction",
        "target": {
          "@type": "EntryPoint",
          "urlTemplate": "https://jsonic.io/?q={search_term_string}"
        },
        "query-input": "required name=search_term_string"
      }
    },
    {
      "@type": "BreadcrumbList",
      "itemListElement": [
        { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://jsonic.io" },
        { "@type": "ListItem", "position": 2, "name": "Guides", "item": "https://jsonic.io/guides" },
        { "@type": "ListItem", "position": 3, "name": "JSON-LD Explained", "item": "https://jsonic.io/guides/json-ld-explained" }
      ]
    }
  ]
}
</script>

Implement JSON-LD in HTML and Next.js

Plain HTML

Drop a <script type="application/ld+json"> tag anywhere in <head> or <body>. Google recommends <head> for earliest discovery by the crawler:

<!DOCTYPE html>
<html>
<head>
  <title>My Page</title>
  <script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Article",
    "headline": "My Page Title",
    "datePublished": "2026-05-11",
    "dateModified": "2026-05-11",
    "author": { "@type": "Organization", "name": "My Site" }
  }
  </script>
</head>
<body>...</body>
</html>

Next.js App Router

In the App Router, inject JSON-LD via a <script> tag with dangerouslySetInnerHTML inside your page component or layout. Define the schema object as a plain JS object and serialize it with JSON.stringify:

// app/guides/my-guide/page.tsx
const articleLd = {
  '@context': 'https://schema.org',
  '@type': 'Article',
  headline: 'My Guide Title',
  datePublished: '2026-05-11',
  dateModified: '2026-05-11',
  author: { '@type': 'Organization', name: 'My Site', url: 'https://example.com' },
  publisher: { '@type': 'Organization', name: 'My Site', url: 'https://example.com' },
}

export default function MyGuidePage() {
  return (
    <>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{ __html: JSON.stringify(articleLd) }}
      />
      <article>...</article>
    </>
  )
}

For Organization and WebSite schemas that appear on every page, put them in your root app/layout.tsx:

// app/layout.tsx
const organizationLd = {
  '@context': 'https://schema.org',
  '@type': 'Organization',
  name: 'My Site',
  url: 'https://example.com',
  logo: 'https://example.com/logo.png',
  sameAs: ['https://twitter.com/mysite', 'https://github.com/mysite'],
}

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <script
          type="application/ld+json"
          dangerouslySetInnerHTML={{ __html: JSON.stringify(organizationLd) }}
        />
      </head>
      <body>{children}</body>
    </html>
  )
}

Common mistake: if your JSON data contains the string </script>, it will prematurely close the script tag and break the page. This is unlikely with schema data but worth guarding against in dynamic content. The fix is to escape it before serializing:

// Safe serialization that escapes </script> inside JSON strings
const safeStringify = (obj: unknown) =>
  JSON.stringify(obj).replace(/</script>/gi, '<\/script>')

// Then use:
dangerouslySetInnerHTML={{ __html: safeStringify(articleLd) }}

Multiple schemas: @graph vs multiple tags. Both approaches work — Google processes multiple <script type="application/ld+json"> tags correctly. However, @graph in a single tag is cleaner: it reduces the number of inline scripts, and entities can cross-reference each other via @id. After implementation, test with the Google Rich Results Test (search.google.com/test/rich-results) and the Schema.org Validator (validator.schema.org). You can also validate your JSON-LD syntax in Jsonic before deploying.

Frequently asked questions

What is JSON-LD?

JSON-LD (JSON Linked Data) is a standard for encoding structured data as JSON, embedded in a web page via a <script type="application/ld+json"> tag. It describes the content of a page in a machine-readable way using the Schema.org vocabulary — entity types like Article, Product, FAQPage, and Organization with properties like name, datePublished, and author. Search engines like Google use JSON-LD to generate rich results (FAQ dropdowns, recipe cards, breadcrumbs). AI engines use it for entity recognition and citation confidence. For a deeper introduction to the underlying format, see the guide on JSON basics.

What is the difference between JSON-LD and regular JSON?

Regular JSON has no predefined meaning for its keys — {'name': 'Alice'} could mean anything. JSON-LD adds semantic meaning by linking to a vocabulary (@context): {"@context": "https://schema.org", "@type": "Person", "name": "Alice"} unambiguously means "a Schema.org Person entity named Alice." The @ prefixed keywords (@context, @type, @id, @graph) are JSON-LD syntax; everything else follows the Schema.org property definitions. JSON-LD is valid JSON and can be parsed with any standard JSON parser — see JSON structure examples for more on JSON syntax.

Does JSON-LD help with SEO?

Yes — JSON-LD enables rich results in Google Search (FAQ dropdowns, HowTo steps, product prices, recipe cards, breadcrumbs). Pages with rich results typically have higher click-through rates. FAQPageschema specifically creates expandable Q&A sections directly in search results. BreadcrumbList replaces the raw URL in search results with a cleaner path. Beyond rich results, Article schema with accurate dateModified helps content freshness signals, and Organization with sameAs social profiles improves entity recognition across AI engines. JSON-LD complements other structured formats — compare it with JSON Schema validation which serves a different purpose (data validation, not search engine signals).

What is @graph in JSON-LD?

@graph lets you include multiple schema entities in a single <script> tag. Instead of two separate <script type="application/ld+json"> tags for Article and BreadcrumbList, use one tag with "@graph": [{ ...Article }, { ...BreadcrumbList }]. Entities in @graph can reference each other by @id, creating a linked data graph. This is the recommended approach because it reduces HTTP overhead (one fewer inline script) and allows Google to understand relationships between entities on the page.

How do I test my JSON-LD structured data?

Use two tools: (1) Google Rich Results Test (search.google.com/test/rich-results) — paste your URL or code and see which rich results your schema is eligible for and any warnings or errors. (2) Schema.org Validator (validator.schema.org) — validates your JSON-LD against the Schema.org spec, catching property mismatches and missing required fields. Common errors: dateModified is required for Article freshness signals; acceptedAnswer.text must be a string in FAQPage; publisher.logo requires a URL, not just a name. You can also validate your JSON-LD syntax in Jsonic to catch JSON formatting errors before submitting to the Rich Results Test.

Which AI engines use JSON-LD for citations?

Google's AI Overviews use JSON-LD heavily — FAQPage and Article schema are among the strongest signals for AI Overview inclusion. Perplexity crawls and indexes structured data, giving pages with accurate Article + dateModified an advantage in freshness ranking. ChatGPT uses JSON-LD indirectly — Organization schema with sameAs links to known entities (Wikipedia, ProductHunt, GitHub) helps ChatGPT recognize a brand as a real, citable entity rather than an unknown website. Claude (Anthropic) uses entity recognition signals from JSON-LD in a similar way. JSON-LD is also related to other JSON-based web standards — see the guide on JWT tokens for another JSON-based standard used across the web.

Validate your JSON-LD

Paste your structured data into Jsonic to catch JSON syntax errors before deploying to production.

Open JSON Formatter
← Back to all tools