Skip to content

Graphs & Entity References

A single @graph lets related entities reference shared nodes without repeating their properties across several JSON-LD documents. unschema-graph builds that graph, resolves relative identities, and merges nodes that share an @id.


When search crawlers (like Googlebot) inspect a web page, they need to understand how entities relate to each other:

  • Is this Article published by this Organization?
  • Is this Person the author of this content?
  • How does the BreadcrumbList relate to the WebPage?

Scattering multiple <script type="application/ld+json"> tags makes it harder for bots to correlate data. A unified @graph array bundles all nodes into a coherent knowledge graph for the page.


To reference an entity from another, assign it an @id:

src/lib/schema.ts
import { Article, Organization, Person } from '@unschema-graph/core';
// 1. Shared organization node with fragment identifier
const organization = Organization({
'@id': '#organization',
name: 'Acme Publishing',
url: 'https://example.com',
});
// 2. Author with path fragment
const author = Person({
'@id': '/authors/ada#person',
name: 'Ada Lovelace',
url: 'https://example.com/authors/ada',
});
// 3. Article referencing both via @id strings
const article = Article({
'@id': '#article',
headline: 'Graphs & References Guide',
image: 'https://example.com/cover.jpg',
datePublished: 'today',
author: '/authors/ada#person', // References Person
publisher: '#organization', // References Organization
});

The recommended v1 pattern is passing the entity object directly rather than a string identifier. Because every builder returns a fully-typed Schema.org object, TypeScript validates relation types at compile time:

const organization = Organization({
'@id': '#organization',
name: 'Acme Publishing',
url: 'https://example.com',
});
const article = Article({
headline: 'Connected structured data',
image: 'https://example.com/cover.jpg',
datePublished: '2026-09-29',
author: 'Ada Lovelace',
publisher: organization, // Typed entity-object reference!
});

When buildJsonLdGraph runs, it:

  1. Detects that organization has an @id.
  2. Hoists organization into the top-level @graph array.
  3. Automatically replaces article.publisher with { "@id": "https://example.com/#organization" }.

A string is treated as a reference when it starts with a fragment (#org), an explicit path prefix (/about#org, ./docs/page, ../docs/page), or an absolute URI with any valid scheme (https:, urn:, mailto:, tel:, and so on). It is then transformed into an { "@id": "..." } pointer:

// Both of these produce identical JSON-LD:
publisher: '#organization'
publisher: { '@id': '#organization' }

Otherwise, when the relation declares a fallbackType, the string becomes an inline named entity. Without a fallback type, a plain string is rejected: pass a direct entity, an explicit ID-looking string, or an { '@id': '...' } object instead.

  • author: 'Ada Lovelace' → { "@type": "Person", "name": "Ada Lovelace" }
  • brand: 'Acme Corp' → { "@type": "Brand", "name": "Acme Corp" }
  • brand: 'AC/DC' → { "@type": "Brand", "name": "AC/DC" }

The distinction is determined by identity, not by nesting depth:

  • a nested entity with an @id becomes its own node in @graph, and its parent keeps only { '@id': '...' };
  • a nested entity without an @id remains inline in its parent;
  • an object containing only @id is already a reference and does not create an empty node.
const organization = Organization({
'@id': '#organization',
name: 'Acme',
});
const website = WebSite({
'@id': '#website',
name: 'Acme',
url: 'https://example.com',
publisher: organization,
});
const graph = buildJsonLdGraph(website);
// Organization is a node; website.publisher is { '@id': '#organization' }.

Reusable identities such as Organization, Person, WebSite, WebPage, Product, Service, and Event are common node candidates. Value objects such as PostalAddress, GeoCoordinates, ContactPoint, Rating, AggregateRating, and NutritionInformation normally remain inline because they usually have no independent identity. This is a library convention for predictable graphs, not a Schema.org rule.


In development or across multiple environments (staging, production), you often want to write relative identifiers like #organization or /about#organization.

When you provide a baseUrl (or set site in Astro’s astro.config.mjs), unschema-graph resolves explicit relative @id values recursively. URL properties remain URL strings; the collector never guesses semantics from property names such as url or item.

Input @id Configured baseUrl Output in @graph
#organization https://example.com https://example.com/#organization
#organization https://example.com/about https://example.com/about#organization
#organization https://example.com/about/ https://example.com/about/#organization
/about https://example.com https://example.com/about
/about#organization https://example.com https://example.com/about#organization
https://example.com/#organization https://example.com unchanged
urn:example:foo https://example.com unchanged
mailto:[email protected] https://example.com unchanged
tel:+33123456789 https://example.com unchanged

Fragment resolution preserves the path form supplied by baseUrl: /about and /about/ remain distinct document URLs.

Built-in schemas distinguish these values explicitly: WebUrlSchema validates absolute HTTP(S) URLs, RelativeOrAbsoluteUrlSchema validates URL properties, and entity relations normalize reference strings to { '@id': value } before graph collection. Only explicit @id properties are resolved. Ordinary values such as name, serviceType, and description are always preserved, even when they look like a path, fragment, or URI.


5. Automatic discovery, deduplication, and node merging

Section titled “5. Automatic discovery, deduplication, and node merging”

You can pass only the root entity. The collector recursively follows object and array relations, discovers every linked entity with an @id, and emits dependencies before the parent that references them.

const graph = buildJsonLdGraph(webpage);
// Discovers WebPage → WebSite → Organization.

The same entity object may be reused by several parents; it is registered once. Cyclic relations between identified entities terminate safely and become references in both directions. Entities without @id stay inline and are not globally deduplicated.

If multiple parts of your application declare entities sharing the same resolved @id, unschema-graph merges them into a single graph node instead of generating duplicates.

Example: Global Layout + Local Page
// In Global Layout:
const baseOrg = Organization({
'@id': '#organization',
name: 'Acme',
url: 'https://example.com',
});
// In Specific Page:
const richOrg = Organization({
'@id': '#organization',
logo: 'https://example.com/logo.png',
sameAs: ['https://twitter.com/acme'],
});
// When passed together:
<Schema items={[baseOrg, richOrg]} />

The resulting @graph contains only one Organization node with all properties merged: name, url, logo, and sameAs.

Duplicate handling is explicit and deterministic:

Strategy Behavior
merge (default) Combines properties; the latest conflicting value wins.
first Keeps the first node encountered.
last Replaces it with the last node encountered.
error Throws DuplicateEntityError on any duplicate @id.

Use onDiagnostic to collect machine-readable merge conflicts and broken local references. Fragment, relative, and same-origin references are checked against graph nodes; absolute external and non-HTTP identifiers are preserved without being reported.

const diagnostics: GraphDiagnostic[] = [];
const graph = buildJsonLdGraph(items, {
duplicateStrategy: 'merge',
onDiagnostic: (diagnostic) => diagnostics.push(diagnostic),
});

Core normalization never mutates user-owned entities, including nested arrays and objects. Graph collection follows a stable depth-first encounter order, so identical input and options produce identical node order and serialization. Passing an already normalized graph document through buildJsonLdGraph() again preserves its structure; reference and ID normalizers are likewise idempotent.

Merged node
{
"@type": "Organization",
"@id": "https://example.com/#organization",
"name": "Acme",
"url": "https://example.com",
"logo": { "@type": "ImageObject", "url": "https://example.com/logo.png" },
"sameAs": ["https://twitter.com/acme"]
}

Some entities represent multiple Schema.org types simultaneously (e.g. an Article that is also a TechArticle or CreativeWork).

Use the withAdditionalTypes() helper to attach secondary types while preserving the primary builder type:

src/pages/docs/[slug].astro
import { Article, withAdditionalTypes } from '@unschema-graph/astro';
const techGuide = withAdditionalTypes(
Article({
headline: 'Advanced TypeScript Architecture',
image: 'https://example.com/cover.jpg',
datePublished: 'today',
author: 'Ada Lovelace',
}),
['TechArticle', 'CreativeWork']
);

The output @type becomes an array: ["Article", "TechArticle", "CreativeWork"]. The helper keeps the builder’s primary type first, removes duplicates in first-seen order, and rejects empty type names. Applying it again preserves these invariants.


By default, <Schema /> always wraps entities inside a root @graph array. If you are rendering an isolated single entity and need flat output without @graph, set graph={false}:

<Schema item={article} graph={false} />

Output:

{
"@context": "https://schema.org",
"@type": "Article",
"headline": "Advanced TypeScript Architecture",
...
}

Next: learn when validation happens and how to handle failures.