@tokens-studio/schema-validation

TypeScript implementation of the TokenScript schema-validation library. See ../README.md for the cross-language overview and ../SCHEMA-LANGUAGE.md for the field reference.

Usage

npm install
npm test          # vitest
npm run build     # tsup → dist/
npm run typecheck # tsc --noEmit

Public API

The library uses per-kind namespace exports so that helper types (Schema, Property, ScriptBlock, etc.) can have the same name across kinds without colliding:

import {
  Token, Color, Fn, Unit, Constants,
} from "@tokens-studio/schema-validation";

const tokenSpec     = Token.parseTokenSpec(jsonFromRegistry);
const colorSpec     = Color.parseColorSpec(jsonFromRegistry);
const fnSpec        = Fn.parseFunctionSpec(jsonFromRegistry);
const unitSpec      = Unit.parseUnitSpec(jsonFromRegistry);
const constantsSpec = Constants.parseConstantsSpec(jsonFromRegistry);

// Safe variants:
const result = Token.safeParseTokenSpec(jsonFromRegistry);
if (!result.success) console.error(result.error.issues);

The function-kind namespace is exported as Fn, not Function, because Function is a global JavaScript constructor and a TypeScript built-in type — re-exporting under that name would shadow both.

URL and version utilities are exported as flat helpers (no namespace) because they have no per-kind variant: parseSchemaUri, buildSchemaUri, compareVersions, parseVersionString, etc.

Stack

• zod ^4 — runtime schema validation. Chosen because the Nuxt frontend in this repo already depends on zod; using the same library avoids adding a second runtime validator to the bundle.
• vitest — test runner.
• tsup — bundler.
• typescript ^5.9 — type-checker (no emit).

Tests

npm test

Runs the per-kind unit tests under tests/<kind>.test.ts plus the shared cross-language fixture corpus at ../fixtures/v1/ via tests/fixtures.test.ts.