Schema registry for TokenScript with bundled schemas and validation
npm install @tokens-studio/tokenscript-schemasSchema registry test setup for TokenScript with bundled schemas and validation.
This package provides a centralized registry of TokenScript schemas with tools to:
- Organize schemas in a clean, testable structure with file-based script references
- Bundle schemas for distribution with shared bundling logic
- Load schemas at runtime with automatic bundling
- Test schema implementations without requiring a build step
Bundle specific schemas for use in your projects with automatic dependency resolution:
``bashBundle using a preset
npx @tokens-studio/tokenscript-schemas bundle preset:css -o ./schemas.js
#### Docs
- Custom Schema Directories Documentation - Bundle schemas from custom directories
$3
-
- Modern CSS color types (CSS Color Level 4+)
- Types: css-color, hex-color, oklch-color, oklab-color
- Functions: , darken, mix, invert, to_gamut, contrast_ratioConfig File Format (
):`json
{
"schemas": ["oklch-color", "rgb-color", "function:invert"],
"output": "./src/generated/schemas.js"
}
`Generated Output (
):`javascript
// Auto-generated by @tokens-studio/tokenscript-schemas
// Version: 0.0.14
// GitHub: https://github.com/tokens-studio/tokenscript-schemas
// Command: npx tokenscript-schemas bundle preset:css -o ./schemas.js
// Generated: 2026-01-07T10:30:00.000Zimport { Config } from "@tokens-studio/tokenscript-interpreter";
export const SCHEMAS = [
{ uri: "https://schema.../rgb-color/0/", schema: { / bundled schema / } },
{ uri: "https://schema.../oklch-color/0/", schema: { / bundled schema / } },
// ... all dependencies included
];
export function makeConfig() {
return new Config().registerSchemas(SCHEMAS);
}
`Using in Your Code:
javascript
import { makeConfig } from "./schemas.js";
import { Interpreter, Lexer, Parser } from "@tokens-studio/tokenscript-interpreter";const config = makeConfig();
const code =
;const lexer = new Lexer(code);
const parser = new Parser(lexer);
const interpreter = new Interpreter(parser, { config });
const result = interpreter.interpret();
`Structure
Each schema is self-contained in its own folder with file-based script references:
src/schemas/types/srgb-color/
├── schema.json # Complete schema definition (with file references)
├── srgb-initializer.tokenscript # Initializer script
├── from-hex-color.tokenscript # Conversion: HEX → SRGB
├── to-hex-color.tokenscript # Conversion: SRGB → HEX
└── unit.test.ts # Co-located tests
Key Points:
-
contains the complete schema definition with script references like "./filename.tokenscript"
- Scripts are standalone files for better readability and syntax highlighting
- Tests use runtime bundling - no build step required
- The bundler inlines script content for distributionWorking with Custom Schemas
You can use the bundler with your own custom schema directories, useful for:
- Developing experimental schemas without modifying the main repository
- Working with schemas from external projects
- Testing new color types before committing them
See Custom Schema Directories Documentation for detailed examples and usage.
`bash
Bundle from custom directory
npm run cli -- bundle my-color -o ./output.js --schemas-dir ./path/to/custom/schemasBuild from custom directory
npm run build-schemas -- --schemas-dir ./path/to/custom/schemas
`Scripts
$3
bash
npm run build-schemas
`Builds all schemas using the shared build logic from
:
- Reads schema.json from each schema directory
- Finds all ./file.tokenscript references in the schema
- Reads and inlines the script file content
- Outputs built schemas to result/ directory:
- registry.json - Complete registry
- types.json - All type schemas
- functions.json - All function schemas
- types/{slug}.json - Individual type schemas
- functions/{slug}.json - Individual function schemas$3
`bash
Run all tests (logs disabled by default)
npm testRun tests with verbose logging
npm run test:verbose
or
LOG_LEVEL=info npm testRun tests with debug logging
npm run test:debug
or
LOG_LEVEL=debug npm testRun specific test file
npm test -- src/schemas/types/rgb-color/unit.test.ts
`Test Logging:
- Logs are disabled by default to reduce noise (only errors shown)
- Use
environment variable to enable logs: debug, info, warn, error
- See tests/helpers/LOGGING.md for detailed logging documentation
- Tests use from @/bundler/build-schema.ts`