Skip to Content

Structured Data

Build deterministic Schema.org graphs and serialize safe JSON-LD.

@puzzle-ui/seo builds Schema.org nodes into a JSON-LD graph, resolves references and merges nodes sharing an ID.

Install

For connected organization, website, page, article, product and FAQ examples, follow the SEO publication tutorial.

npm install @puzzle-ui/seo react

React 19 is a peer dependency. Framework adapters do not require a framework package at runtime.

Quick start

import { createSeoGraphBuilder, serializeSeoGraph } from "@puzzle-ui/seo/core";

const builder = createSeoGraphBuilder({ baseUrl: "https://example.com" });
builder.add({ "@type": "Organization", "@id": "#org", name: "Example" });
builder.add({
  "@type": "WebPage",
  name: "Home",
  publisher: { "@id": "#org" },
});
const graph = builder.build();
const result = serializeSeoGraph(graph, { scriptSafe: true });
if (result.errors.length) console.error(result.errors);
const jsonLd = result.value;

Nested nodes are extracted and referenced by ID. Explicit IDs override generated IDs. A builder has isolated state; addMany, build, and getIssues support incremental construction and inspection. The default conflict strategy is deterministic; first, last and error are also available. Check issues when merging data from different sources.

Graph options

NameTypeDefaultDescription
baseUrlstring—Base for resolving IDs and references.
localestring—Locale available to graph normalization.
contextstring | objectSchema.org contextJSON-LD context.
rootIdsstring[]—Graph root IDs.
conflictStrategy"deterministic" | "first" | "last" | "error""deterministic"Policy for conflicting scalar values.
strictReferencesbooleanfalseReport unresolved local references as errors.

serializeSeoGraph returns { value, errors }; stringifySeoGraph returns a string. Serialization is deterministic and script-safe by default. Keep script-safe escaping enabled when embedding JSON-LD in HTML; never concatenate unescaped user input into a script tag.

Schema registry

import { createDefaultSchemaRegistry, validateSchemaNode } from "@puzzle-ui/seo/schema";

const registry = createDefaultSchemaRegistry();
const issues = validateSchemaNode(
  { "@type": "Organization", name: "Example" },
  registry,
);

The generated registry includes Schema.org definitions and inherited properties. createSchemaRegistry accepts generated and custom definitions, extensions, and an allowGeneratedOverrides option; inspect registry.getConflicts() when composing definitions. React schema components are documented in React Integration; complete reports and rich-result profiles are covered in Validation.

Exports

  • @puzzle-ui/seo/core: normalizeSeoId, createSeoNode, mergeSeoNodes, createSeoGraphBuilder, buildSeoGraph, resolveSeoReferences, validateSeoGraph, serializeSeoGraph, stringifySeoGraph and graph types.
  • @puzzle-ui/seo/schema: createSchemaRegistry, createDefaultSchemaRegistry, validateSchemaNode, SCHEMAORG_VERSION, SCHEMAORG_SOURCE_HASH, generatedSchemaDefinitions and registry types.