@usesource/schema

Canonical Zod schemas for the SOURCE token registry. The single source of truth for Token, Property, Element, LibraryMapping, and RegistrySnapshot shapes — every other public surface (@usesource/registry types, @usesource/api OpenAPI, @usesource/mcp tool definitions, JSON Schema for CI/IDE integration) is derived from the schemas in this package.

Why one place

Drift between TypeScript types, OpenAPI specs, MCP tool definitions, and JSON Schema validators is structurally impossible if all four are generated from one source. That source is this package.

Install

npm install @usesource/schema

Use

import {
  TokenSchema,
  type Token,
  PropertySchema,
  type Property,
  RegistrySnapshotSchema,
  codegen,
} from "@usesource/schema";

// Validate a token
const result = TokenSchema.safeParse(unknownInput);
if (result.success) {
  const token: Token = result.data;
}

// Generate JSON Schema bundle for downstream tools
const jsonSchema = codegen.buildBundle();

Stability contract

• schemaVersion: "1" is the initial public release.
• Adding optional fields is non-breaking.
• Removing or changing required fields requires a major version bump and a documented deprecation window.
• Canonical IDs (the source.* namespace) are forever — see the deprecatedBy field on Token/Property/Element for the rename pattern.

What's in v1

| Schema | Purpose | |---|---| | Token | A single canonical visual primitive with dimension, value, evidence | | Property | A behavioral capability with semantic fingerprint | | Element | A recognizable component shape (button, card, etc.) | | LibraryMapping | Adapter-side translation from library identifier → canonical | | RegistrySnapshot | Signed, content-hashed, versioned public artifact |

Plus primitives: SourceId, Dimension, Evidence, Fingerprint, SchemaVersion.

Codegen

import { codegen } from "@usesource/schema";

// Single-schema → JSON Schema
const tokenSchema = codegen.toJsonSchema(TokenSchema);

// All public schemas bundled into one $defs document
const bundle = codegen.buildBundle();

OpenAPI spec generation and MCP tool-definition generation are planned for the next iteration of this package; both will derive from the same Zod source.

License

Apache-2.0. See LICENSE at the repository root.