Schema.org JSON-LD Implementation Guide: Syntax, Entity Graphs, and Validation

Why JSON-LD Over Microdata and RDFa

Search engines unanimously recommend JSON-LD (JavaScript Object Notation for Linked Data) over inline microdata or RDFa attributes. JSON-LD encapsulates structured knowledge inside `<script type="application/ld+json">` elements located in the document `<head>` or `<body>`, completely decoupled from presentation markup.

This decoupling prevents accidental markup breakage during CSS refactoring and allows clean automated code generation.

The Power of Entity Graphs (@graph)

Rather than declaring isolated schema objects across separate script tags, modern architectures use an interconnected `@graph` array. For example, an Article schema should link directly to an Organization publisher and a Person author via canonical IDs (`@id`):

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#org",
      "name": "Acme Corp",
      "url": "https://example.com"
    },
    {
      "@type": "Person",
      "@id": "https://example.com/team/jane#author",
      "name": "Jane Doe"
    },
    {
      "@type": "TechArticle",
      "headline": "Modern Structured Data",
      "author": { "@id": "https://example.com/team/jane#author" },
      "publisher": { "@id": "https://example.com/#org" }
    }
  ]
}

Common Failure Modes in Structured Data

During automated audits, SiteScore frequently identifies three critical failure points: 1) Syntax errors such as trailing commas that invalidate JSON parsing; 2) Declaring an Article without an author or datePublished; 3) Mismatched URLs between the canonical tag and the schema `mainEntityOfPage`.