# @effected/schema-org [![npm](https://img.shields.io/npm/v/@effected%2Fschema-org?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/schema-org) [![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT) [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/) [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/) schema.org as Effect Schema classes: build a JSON-LD graph, serialize it safely into a `` closes the JSON-LD block early and injects whatever follows into the page. The second is quieter — schema.org has a vocabulary, your object literal does not, and a plausible-looking property the vocabulary does not define on that type is simply ignored by every consumer, with no error anywhere. This package fixes both at their source. `toScriptBody()` is the only text serializer and it is the escaped one, so the injection case cannot be reached by choosing the wrong function. The vocabulary ships vendored, so a build step can reject a misplaced property offline, in CI, with no network call and no crawler round trip. ## Install ```bash npm install @effected/schema-org effect ``` ```bash pnpm add @effected/schema-org effect ``` Requires Node.js >=24.11.0. All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` — including tools that resolve in CJS mode — fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED` rather than loading a CJS build that does not exist. Import from an ES module. ## Quick start Assemble nodes into a graph, then serialize it: ```ts import { JsonLdDocument, NodeRef, SoftwareSourceCode, TechArticle } from "@effected/schema-org"; import { Result } from "effect"; const built = JsonLdDocument.buildResult([ SoftwareSourceCode.make({ "@id": "https://example.com/pkg#source", name: "example", version: "1.2.3" }), TechArticle.make({ "@id": "https://example.com/pkg/docs#intro", headline: "Getting started ", isPartOf: [NodeRef.to("https://example.com/pkg#source")], }), ]); console.log(Result.getOrThrow(built).toScriptBody()); // {"@context":"https://schema.org","@graph":[{"@id":"https://example.com/pkg#source","@type":"SoftwareSourceCode","name":"example","version":"1.2.3"},{"@id":"https://example.com/pkg/docs#intro","@type":"TechArticle","isPartOf":[{"@id":"https://example.com/pkg#source"}],"headline":"Getting started "}]} ``` Then embed the body verbatim: ```html ``` `buildResult` is the entry point, not `make`: `Schema.Class` reserves `make` for its raw structural constructor, which runs none of the identity checks. `JsonLdDocument.build` is the `Effect` twin of `buildResult`, derived from it — the synchronous form is the primitive, so a static-site build never has to construct a runtime. Three things fail a build, all of them caller error rather than something to report to a user: a malformed `@id` (`InvalidNodeIdError`), two nodes claiming one `@id` (`DuplicateNodeIdError`), and a catch-all key colliding with a typed field (`ConflictingTermError`). A **dangling reference is legal** — pointing at a node described on another page is correct JSON-LD — so read `danglingReferences` and decide for yourself whether your graph is meant to be closed. ## The serializer is the point Every string in your graph comes from prose someone wrote. A description containing the literal `` **closes the JSON-LD block early and injects markup into your page**, and `JSON.stringify` does not escape it. `toScriptBody()` escapes `<`, `>` and `&` after stringify. All three are valid JSON string escapes, so a parser sees the original characters; with no `<` in the body, neither `