desen-schemas

Canonical JSON Schemas for the DESEN Protocol. Every normative shape from SPEC.md §2 / §4.5 / §7.3 packaged as installable JSON files plus typed TypeScript barrels.

Install

npm install desen-schemas

When to use the npm package

| Use this package when… | Use the live URLs (https://schemas.desen.run/) when… | |---|---| | You're validating documents inside a build pipeline that should not depend on network availability | You're authoring docs, blog posts, or tutorial code that should always show the canonical URL | | Your bundler can't resolve remote $ref URLs at build time | A reader is meant to fetch the schema in their browser to inspect it | | You want compile-time guarantees that a schema at a given version actually exists | An external Producer / Runtime needs to load the latest published version dynamically | | You're vendoring schemas alongside your conformance artefacts | — |

The two stay in lock-step — every release of this package mirrors the JSON files served at the live registry.

Quick start

Validate a document with Ajv

import Ajv from "ajv";
import addFormats from "ajv-formats";
import { all, surfaceSpec } from "desen-schemas";

const ajv = new Ajv({ strict: false, allErrors: true });
addFormats(ajv);

// Register every canonical schema so internal `$ref`s resolve.
for (const schema of all) ajv.addSchema(schema, schema.$id);

const validate = ajv.compile(surfaceSpec);
if (!validate(myDocument)) {
    console.error(validate.errors);
}

Resolve a schema by its canonical URL

import { byId } from "desen-schemas";

const surface = byId["https://schemas.desen.run/surface-spec.v1"];

Direct JSON imports

import surfaceSpec from "desen-schemas/schemas/surface-spec.v1.json";

What's exported

| Name | $id | Spec section | |---|---|---| | bindReference | https://schemas.desen.run/bind-reference.v1 | §2.7 | | bindingSpec | https://schemas.desen.run/binding-spec.v1 | §2.7 | | compositionSpec | https://schemas.desen.run/composition-spec.v1 | §2.3 | | elementSpecCore | https://schemas.desen.run/element-spec.core.v1 | §2.2 | | goalSpec | https://schemas.desen.run/goal-spec.v1 | §2.12 | | implementationProfile | https://schemas.desen.run/implementation-profile.v1 | §7.3 | | modifiersSpec | https://schemas.desen.run/modifiers-spec.v1 | §2.11 | | repeaterSpec | https://schemas.desen.run/repeater-spec.v1 | §2.5 | | surfaceSpec | https://schemas.desen.run/surface-spec.v1 | §2.8 | | telemetryEnvelope | https://schemas.desen.run/telemetry-envelope.v1 | §4.5 |

Plus convenience exports:

• all: an immutable array of all schemas — pass to ajv.addSchema() in one shot.
• byId: an immutable { [canonicalUrl]: schema } map.
• BASE_SPEC_VERSION: the SPEC.md version this release tracks ("1.0.0-RC1").

Versioning

desen-schemas is part of the DESEN fixed-bump group — its version always matches desen, @desenlabs/core, @desenlabs/cli, and @desenlabs/react-renderer. Pin against the same line:

npm install desen-schemas@beta
# 1.0.0-beta.1 currently

A future RFC that introduces a new schema version will produce a coordinated bump of every package in the group; old schemas remain available under their .v1 / .v2 / … suffixes.

Source of truth

The schemas live in packages/schemas/src/schemas/ in the DESEN monorepo. The same files are served at https://schemas.desen.run/ via the deploy pipeline at infra/scripts/deploy.sh. The npm package never diverges from the live URLs — both build from the same source on every release.

License

Apache-2.0.