Overview
unschema-graph is a Schema.org JSON-LD engine powered by Zod. It helps TypeScript, Astro, and Svelte projects build typed entities, validate supported inputs, connect them in a graph, and safely serialize the result into HTML.
Start with your environment
Section titled “Start with your environment”- Astro: a server-rendered component, integration, development toolbar, and Content Collections helpers.
- Svelte 5: a reactive component that writes JSON-LD through
<svelte:head>. - TypeScript / Core: the framework-neutral engine for custom rendering pipelines.
Compare the three environments or go directly to the Astro quick start.
Core Pillars
Section titled “Core Pillars”Server-First with Zero Client JS in Astro
Section titled “Server-First with Zero Client JS in Astro”Structured data is rendered server-side or during static build. In Astro, the <Schema /> component emits static JSON-LD without hydration directives, adding 0 kB to your client bundle. In Svelte 5, the component integrates with framework reactivity for dynamic updates without browser-only dependencies.
Strict Zod Builders
Section titled “Strict Zod Builders”Every builder is strictly typed and validated at runtime. Typos, misspelled keys, and missing required properties are caught immediately before hitting production.
Unified @graph Resolution
Section titled “Unified @graph Resolution”Instead of disjointed <script> tags, unschema-graph links entities into a unified @graph, automatically resolving relative #id fragments and canonical URLs.
Built-in Anti-XSS Protection
Section titled “Built-in Anti-XSS Protection”HTML-sensitive characters are Unicode-escaped during serialization to prevent </script> tag breakout vulnerabilities.
Why unschema-graph?
Section titled “Why unschema-graph?”Generating structured data manually or with loose TypeScript definitions often leads to subtle errors that can silently produce invalid structured data. Here is how unschema-graph compares:
| Feature | Manual <script> |
schema-dts |
unschema-graph |
|---|---|---|---|
| Compile-time TypeScript types | ❌ | ✅ | ✅ |
| Runtime validation (Zod) | ❌ | ❌ | ✅ (Catches CMS & dynamic errors) |
Unified @graph resolution |
Manual | Manual | ✅ (Automatic #id linking) |
XSS sanitization (</script>) |
Manual | ❌ | ✅ (Automatic Unicode escaping) |
| Astro Dev Toolbar inspector | ❌ | ❌ | ✅ (Live interactive debugger) |
| Svelte 5 runes support | ❌ | ❌ | ✅ (Native $props & $derived) |
| Client bundle cost | 0 kB | 0 kB | 0 kB in Astro / native Svelte |
Package Ecosystem
Section titled “Package Ecosystem”unschema-graph is modular and designed to fit into any modern TypeScript stack:
| Package | Purpose |
|---|---|
@unschema-graph/astro |
Astro integration (schemaGraph), <Schema /> component, Dev Toolbar inspector, and Content Layer helpers. |
@unschema-graph/svelte |
Svelte 5 component (<Schema /> using runes) with full re-export of all builders. |
@unschema-graph/core |
Universal engine: Zod schemas, @graph resolution, temporal and duration helpers, and CLI/API audit. |
Pipeline Architecture
Section titled “Pipeline Architecture”The journey of your data from page source to the final HTML <script>:
┌────────────────────────────────────────────────────────┐│ Source Data (Markdown, CMS, API, Props) │└───────────────────────────┬────────────────────────────┘ │ ▼┌────────────────────────────────────────────────────────┐│ Strict Schema.org Builders (Zod 4) ││ Article({ headline, author, ... }) │ ◄── Catches invalid properties & typos└───────────────────────────┬────────────────────────────┘ │ ▼┌────────────────────────────────────────────────────────┐│ Graph Normalization & Resolution ││ buildJsonLdGraph([items], { baseUrl }) │ ◄── Resolves relative #ids & deduplicates└───────────────────────────┬────────────────────────────┘ │ ▼┌────────────────────────────────────────────────────────┐│ Unicode Anti-XSS Serializer ││ serializeJsonLd(payload) │ ◄── Escapes unsafe HTML characters (< > &)└───────────────────────────┬────────────────────────────┘ │ ▼┌────────────────────────────────────────────────────────┐│ HTML <script type="application/ld+json"> │ ◄── Injected in SSR / Static <head> (0 kB JS in Astro)└────────────────────────────────────────────────────────┘Next Steps
Section titled “Next Steps”1. Installation
Section titled “1. Installation”Install the package for Astro, Svelte 5, or universal TypeScript.
2. Quick Start
Section titled “2. Quick Start”Build your first connected @graph in under 3 minutes.
3. Framework Integrations
Section titled “3. Framework Integrations”Explore the Astro Dev Toolbar and Svelte 5 reactive runes.
Explore Astro · Explore Svelte 5
4. Audit & CI
Section titled “4. Audit & CI”Validate your compiled HTML files automatically in CI/CD pipelines.