@graph (Schema.org)
@graph is the JSON-LD property that lets multiple Schema.org entities be declared in a single JSON-LD block, with @id references linking them. Replaces the alternative of separate JSON-LD script blocks. Useful for declaring related entities (Article + Author Person + Publisher Organization + ImageObject + BreadcrumbList) in one parseable structure.
Also called: Schema.org @graph, JSON-LD @graph property · Last updated: May 27, 2026 · By Joseph W. Anady
Why it matters.
@graph solves a practical problem in Schema.org implementations: pages often need to declare multiple related entities (an article + its author + its publisher + breadcrumbs + main image). Separate JSON-LD blocks work but make cross-references harder to maintain. @graph lets you declare all entities once in an array, then reference them by @id from anywhere in the structure.
How it works.
A JSON-LD block with @graph has @context at the top and an @graph array containing entity objects. Each entity gets its own @id. Cross-references use the @id values: an Article's author property can be {'@id': 'https://yoursite.com/authors/joseph/#joseph'} pointing to a Person entity declared elsewhere in the same @graph. The parser resolves these references as if they were inline.
2026 reality check.
@graph has become the dominant pattern for entity-rich pages in 2026. As Schema.org implementations have grown more sophisticated (typical TDG page has 4-5 entities), maintaining separate blocks with manual cross-references becomes error-prone. @graph keeps the cross-references in one place and validates as a single unit.
Data points
- JSON-LD 1.1 @graph documented in W3C JSON-LD specification
- @graph allows multiple entities in single JSON-LD block with @id cross-references
- Dominant pattern in 2026 for entity-rich Schema.org implementations
- Each entity in @graph needs unique @id for cross-references
- Google's parser merges all JSON-LD on a page before resolving cross-references
First-hand insight from ThatDeveloperGuy.
ThatDeveloperGuy uses both patterns: @graph for the homepage Organization + Person + WebSite + WebPage hub (everything cross-referenced in one block) and separate JSON-LD blocks for per-page schema (Service + Article + FAQPage + BreadcrumbList). Both are valid; the choice depends on whether the entities have strong cross-references (@graph) or are independent (separate blocks).
How TDG approaches it
TDG's homepage uses @graph for the entity hub (Organization + Person founder + WebSite + WebPage + LocalBusiness all cross-referenced via @id). Per-page schema uses separate blocks for Service + Article + FAQPage + BreadcrumbList (each independently maintainable). Validated via Google's Schema Markup Validator at build time.
Common mistakes.
- Mixing @graph and separate blocks on the same page (works but confusing)
- Missing @id on entities inside @graph (cross-references won't resolve)
- Circular @id references (entity A's author is entity B, entity B's author is entity A — invalid)
- Forgetting @context at the top of @graph block (every JSON-LD needs @context)
- Over-nesting (@graph inside @graph — not invalid but unnecessary)
FAQ.
@graph or separate JSON-LD blocks?
Either is valid. @graph is cleaner for entity-rich pages with cross-references. Separate blocks are easier to maintain when entities are independent.
Can I cross-reference @id across separate JSON-LD blocks on the same page?
Yes. Google's parser merges all JSON-LD blocks on a page before resolving @id references. Cross-block @id works.
Does @graph affect performance?
Negligibly. JSON-LD parsing is fast. The size difference between @graph and separate blocks for the same entities is minimal.
Should every page use @graph?
Not necessarily. Pages with 1-2 schema types are fine with separate blocks. Pages with 4+ types benefit from @graph organization.
Can different @graph blocks reference each other?
Yes. @id references work across blocks. But for cleanliness, related entities should be in the same @graph.
Maintained by Joseph W. Anady at ThatDeveloperGuy. Back to glossary · Suggest a term