@getguru/content-model

Guru's card content model: the element schema and the structural validator for plain-JSON Guru card content trees.

What's in the package

• card-schema.json — the schema itself: element types, containment rules, property constraints, and text marks. Also importable directly: require("@getguru/content-model/card-schema.json").
• validateTree(document, options) — checks a content tree against the schema and returns violations ({ rule, path, nodeType }). Checks only, never mutates.
• Types — ContentNode, ContentViolation, ElementType, and the typed EDITOR_SCHEMA registry.

Usage

import { validateTree } from "@getguru/content-model";

const violations = validateTree(document, { entities: draft.entities ?? {} });
// [{ rule: "heading/invalid-level", path: [0], nodeType: "heading" }]

options.at scopes validation to the container an operation changed; omit it to validate the whole document. options.entities is the draft's entities map ({} for a draft with no entities).

What validation means

Passing validateTree means the tree is well-formed — shaped so Guru's editor renders it without repairing it. It is not a security check: sanitization and authorization happen server-side.

Publishing & delivery

The package is published to the public npm registry from guru-ui's master CI workflow via npm trusted publishing (OIDC) — there is no npm token anywhere.

The contract:

• Bump version in this package.json in the same PR as any change to shipped files (everything in the tarball: src/** including card-schema.json, this README, LICENSE, package.json). CI fails PRs that change shipped files without a bump — this is what makes a schema change visible to downstream consumers, so it is not optional.
• Which bump is human judgment: patch for fixes and docs, minor for additive schema or API changes, major for breaking changes to the schema or the validator API. The schema's own version field (constraint epoch) is independent of package semver.
• Master builds publish automatically when the version is new, and no-op (green) when it isn't.
• Consumers: internal JS consumers install through CodeArtifact's npmjs upstream proxy with existing read auth; external consumers install straight from npmjs. Vendored copies of card-schema.json (guru-server, guru-agent) track published releases via their own drift checks.