Why should JSON-LD entities use stable @id values?
Stable identifiers let Article, Organization, WebSite, breadcrumb, and software entities refer to one another without creating contradictory duplicates.
Written for developers maintaining multi-entity JSON-LD graphs across Next.js layouts, pages, articles, and tools.
Key facts
- JSON-LD @id identifies an entity so separate graph nodes can refer to the same thing.
- Stable IDs reduce accidental duplicate Organization or WebSite objects with conflicting properties.
- Identifiers should use the production canonical origin and remain stable across deployments.
A useful rule: make each important claim understandable and verifiable without requiring the reader to reconstruct your meaning from the rest of the page.
What problem does @id solve?
Without identifiers, each nested publisher, author, website, and application object can be interpreted as a new unnamed entity. Different components may then emit slightly different versions of the same organization. An `@id` gives the entity a durable reference, allowing an Article publisher to point to the Organization defined elsewhere in the graph. It is similar to a primary key, though it is a semantic identifier rather than a database constraint. The result is a smaller, clearer graph where relationships are explicit and shared facts have one owner.
- Assign one identifier to each major real-world entity.
- Reference existing nodes instead of nesting full copies.
- Keep page-specific entities separate from global identity.
What should a stable identifier look like?
Use an absolute URL on the canonical production origin, often with a descriptive fragment that does not need to resolve as a separate page. Examples include `https://example.com/#organization`, `https://example.com/#website`, and `https://example.com/tool#software`. An article entity can use its canonical URL plus `#article`. Choose a convention once and encode it in a shared helper. Avoid build IDs, preview domains, random UUIDs generated at render time, and localized labels that may change. Stability matters more than elaborate naming.
- Base IDs on canonical production URLs.
- Use predictable lowercase fragments.
- Reject preview and localhost origins in build tests.
How should page entities connect?
A WebSite node can identify its publisher through the Organization ID. A WebPage can identify `isPartOf` the WebSite and `about` or `mainEntity` the primary tool or dataset. An Article can reference the Organization as publisher and a Person or Organization as author, depending on the visible byline. Breadcrumb markup can remain a separate list while using canonical page URLs. Connect only relationships the page supports; a dense graph is not inherently better. The goal is consistent identity and useful meaning, not maximizing edge count.
- Model publisher and author according to visible responsibility.
- Use `mainEntity` only for the page's primary described thing.
- Avoid speculative relationships added for perceived SEO value.
How do duplicate graphs appear in Next.js?
A root layout may emit Organization and WebSite, while route layouts and pages each emit their own complete copies. Client SEO components can add another set after hydration. Differences in trailing slashes, hostnames, or fragments keep those copies from joining. Centralize global nodes in one server-rendered location and export identifier helpers for page graphs. Parse the final HTML across representative routes and group nodes by type and ID. If two nodes share an ID, their properties should be compatible; if they represent the same thing with different IDs, consolidate them.
- Inventory schema ownership by layout and page.
- Normalize the canonical origin before forming identifiers.
- Test raw HTML and hydrated DOM for duplicate nodes.
What belongs in an entity graph test?
The test should parse every JSON-LD script, expand arrays and `@graph`, then assert expected IDs, types, and relationships. It should reject localhost, deployment-preview domains, malformed URLs, duplicate conflicting IDs, and references to missing critical nodes. Compare page-level fields such as headline and dates with the content record. Run the test against a built homepage, article, and tool because layouts can compose differently. Validation tools remain useful for feature rules, but a repository-specific graph test catches identity regressions that generic validators cannot know are wrong.
- Resolve all nodes into one test inventory.
- Assert stable global IDs and route-specific primary IDs.
- Fail on conflicting properties for the same identifier.
Put it to work
Find the highest-impact fix on your site.
Assign stable identifiers, connect page entities, and remove duplicate organization and website nodes.
Inspect your entity graphSources
- 1.Google Search Central: Introduction to structured dataChecked 2026-07-26
- 2.Google Search Central: General structured data guidelinesChecked 2026-07-26