JSON-LD (JavaScript Object Notation for Linked Data) is the implementation format Google officially recommends for structured data, and it is the format most reliably parsed by AI systems including ChatGPT, Gemini, and Perplexity's retrieval pipelines. Unlike Microdata (embedded in HTML attributes) or RDFa (mixed into HTML tags), JSON-LD is a self-contained data block that lives in a <script> tag and can be added, updated, or removed without touching your page's HTML structure. This implementation flexibility makes JSON-LD the practical choice for teams building AI-optimized content at scale. This guide covers JSON-LD syntax fundamentals, the @graph pattern for multi-type stacking, framework-specific implementation patterns for Next.js, Nuxt, and WordPress, the validation workflow, and common implementation errors that silently break AI parsing.
JSON-LD Syntax Fundamentals and @context Declaration
Every JSON-LD block begins with two required fields: @context and @type. @context declares the vocabulary being used—for schema.org markup, this is always 'https://schema.org'. @type declares which schema.org type this entity represents—'Article', 'Organization', 'Product', etc. Beyond these two fields, every other property follows the naming conventions defined at schema.org for that @type. A minimal valid Article JSON-LD block looks like: {"@context": "https://schema.org", "@type": "Article", "headline": "Your Article Title", "datePublished": "2026-05-01"}. Critical syntax rules: all keys must be quoted strings; all values must be valid JSON (string, number, boolean, array, or object); nested objects use the same @type pattern as root objects. The @id field creates a named identifier for the entity—use a stable URL as the @id value. For entities that exist at a specific URL, use that URL: {"@id": "https://yoursite.com/article-slug"}. For entities without a dedicated URL, use a URL fragment: {"@id": "https://yoursite.com/#organization"}. @id-based entity references are how JSON-LD creates links between entities without duplication—you can reference the same Organization node from multiple Article nodes by its @id rather than repeating the full object.
- @context must always be 'https://schema.org' for schema.org structured data
- @type must exactly match a valid schema.org type—check schema.org for spelling
- @id should be the canonical URL for URL-based entities or a fragment for anonymous entities
- All JSON-LD must be valid JSON—use a linter to check before deployment
- Nested entities use the same @type pattern as root entities—schema.org is fully recursive
The @graph Pattern for Multi-Type Schema Stacking
The @graph pattern allows you to declare multiple schema entities in a single JSON-LD block while maintaining explicit entity relationships between them. This is the recommended approach for pages that need multiple @type declarations—which includes most content pages on a well-optimized site. The @graph syntax: {"@context": "https://schema.org", "@graph": [{"@type": "WebPage", "@id": "https://yoursite.com/article-slug", "name": "Article Title", "url": "https://yoursite.com/article-slug", "isPartOf": {"@id": "https://yoursite.com/#website"}}, {"@type": "Article", "@id": "https://yoursite.com/article-slug#article", "headline": "Article Title", "mainEntityOfPage": {"@id": "https://yoursite.com/article-slug"}, "author": {"@id": "https://yoursite.com/authors/jane-smith"}, "publisher": {"@id": "https://yoursite.com/#organization"}}, {"@type": "Organization", "@id": "https://yoursite.com/#organization", "name": "Your Company", "url": "https://yoursite.com"}, {"@type": "Person", "@id": "https://yoursite.com/authors/jane-smith", "name": "Jane Smith"}]}. The power of @graph is entity referencing by @id: the Article's author field references the Person node's @id rather than duplicating its properties. This creates a connected entity graph from a single JSON-LD block—exactly the structure AI knowledge graph parsers prefer.
- @graph allows multiple @type declarations in one script block with entity cross-referencing
- Entity referencing by @id eliminates property duplication and creates explicit relationship edges
- A standard content page @graph should include WebPage, Article, Organization, and Person nodes
- isPartOf relationship links individual pages to the parent WebSite entity
- mainEntityOfPage anchors the Article to its canonical WebPage @id
Framework Implementation: Next.js, Nuxt, and WordPress
Each major web framework has a preferred pattern for JSON-LD injection. In Next.js (App Router), use a JSON-LD component that renders a <script type='application/ld+json'> tag in the page's <head> via the metadata API or a custom Head component: export function JsonLd({ data }: { data: object }) { return (<script type='application/ld+json' dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }} />); }. Call this component in your page layout with the schema data object generated per-page based on your CMS content. In Nuxt 3, use useHead() to inject JSON-LD: useHead({ script: [{ type: 'application/ld+json', children: JSON.stringify(schemaData) }] }). This pattern is reactive and works correctly with Nuxt's SSR, ensuring JSON-LD is present in server-rendered HTML—critical for AI crawlers that do not execute JavaScript. In WordPress, the recommended approach is the Yoast SEO or Rank Math plugins (both implement complete @graph JSON-LD), or a custom plugin using wp_head action: add_action('wp_head', function() { $schema = generate_schema_for_post(get_the_ID()); echo '<script type="application/ld+json">' . json_encode($schema) . '</script>'; }); For all frameworks: always generate JSON-LD server-side (not client-side JavaScript) to ensure AI crawlers that do not execute JavaScript can parse the markup.
- Next.js: inject JSON-LD via a dangerouslySetInnerHTML script component in the page head
- Nuxt 3: use useHead() with script type 'application/ld+json' for SSR-compatible injection
- WordPress: Yoast SEO or Rank Math provide production-ready @graph JSON-LD automatically
- Always render JSON-LD server-side—client-side JavaScript injection is invisible to many AI crawlers
- Generate JSON-LD from CMS data per-page to prevent schema drift from content updates
Validation Workflow and Common Implementation Errors
The validation workflow for JSON-LD should be: (1) local validation with a JSON linter to catch syntax errors before deployment, (2) schema.org validation at validator.schema.org to check @type and property usage against the specification, (3) Google Rich Results Test at search.google.com/test/rich-results to verify Google's specific parsing of your markup and eligibility for rich results, (4) Google Search Console monitoring post-deployment for errors at scale. Common implementation errors and their symptoms: Missing closing brackets in nested objects—causes complete schema invalidation with no error in the browser console; inconsistent @id references—the Article's author @id must exactly match the Person node's @id, including protocol and trailing slash; URL property values without quotes—{"url": https://yoursite.com} is invalid JSON; content mismatches between schema fields and visible page content—causes rich result eligibility revocation by Google. Specific AI crawler errors to watch for: schema not present in server-rendered HTML (client-side injection issue), @type value spelled incorrectly ('article' instead of 'Article'—schema.org types are case-sensitive), and deprecated properties that were removed in recent schema.org version updates (check schema.org/version for changelogs). A pre-deployment checklist should include: JSON syntax valid, all @id references match their targets, visible content matches schema content, Rich Results Test passes, no console errors on page load.
- Run JSON linter → schema.org validator → Rich Results Test before every deployment
- schema.org @type values are case-sensitive—'Article' not 'article'
- @id reference mismatches (protocol, trailing slash) cause silent entity resolution failures
- Content mismatch between schema and visible page content triggers rich result revocation
- Monitor Search Console Enhancements weekly for new schema errors on high-value page templates
JSON-LD implementation excellence is the technical foundation of AI SEO. Every schema optimization strategy—FAQPage for answer visibility, Article for authority, Product for recommendations—depends on correctly implemented, server-rendered, validated JSON-LD. The implementation patterns covered here—@graph entity linking, framework-specific injection, server-side rendering, and the four-step validation workflow—represent the production standard for AI-era structured data. Organizations that build robust JSON-LD implementation infrastructure now are creating a compounding technical advantage as AI search usage grows and competition for structured data quality intensifies.
Frequently Asked Questions
Is client-side JSON-LD injection (via JavaScript after page load) effective for AI SEO?
No. Client-side JSON-LD injection is unreliable for AI SEO because most AI crawlers do not execute JavaScript—they parse server-rendered HTML only. Google's crawler does eventually process some JavaScript, but with delays that reduce the freshness and reliability of schema detection. Always render JSON-LD in server-side HTML. For frameworks like Next.js and Nuxt, use SSR-compatible injection methods that include the JSON-LD in the initial HTML response, not in JavaScript that executes after hydration.
How many JSON-LD script blocks can a page have?
There is no strict technical limit on the number of JSON-LD script blocks per page, but best practice is to consolidate into a single @graph block for maintainability and parser efficiency. Multiple separate script blocks are valid and parsed correctly by Google and most AI systems, but they are harder to maintain and more prone to @id inconsistencies across blocks. The @graph pattern provides all the multi-type stacking capability you need in a single, coherent block that is easier to validate and audit.
Does JSON-LD in the page body work as well as JSON-LD in the document head?
Google's documentation states that JSON-LD can be placed in either the <head> or <body> of a page. In practice, <head> placement is strongly preferred for AI SEO because it ensures the markup is encountered before page body content during parsing, and some AI crawler implementations prioritize head-section metadata. For any framework where head injection is straightforward (Next.js, Nuxt, WordPress), always inject JSON-LD in <head>. Only use body injection if your framework makes head injection significantly more complex.