softschema

The TypeScript/Zod implementation of softschema: validate and structure Markdown/YAML artifacts with frontmatter contracts. It is the idiomatic Zod counterpart to the Python/Pydantic package and is held to exact behavioral parity with it: the same CLI inputs/outputs/flags, the same library surface, and the same canonical compiled JSON Schema (content-identical, equal schema_sha256 over its canonical JSON; YAML serialization bytes may differ).

npx softschema@latest --help            # zero-install
# or
bun add softschema

CLI

softschema-ts exposes the same commands and flags as the Python softschema:

softschema-ts validate <doc.md> --schema <schema.yaml> [--model mod.ts:Export] [--envelope key]
softschema-ts compile <mod.ts:ZodSchema> --contract <id> --out <schema.yaml> [--check]
softschema-ts inspect <doc.md>
softschema-ts generate <doc.md> [--check]
softschema-ts docs --list [--json] | softschema-ts docs <topic>
softschema-ts skill --brief | softschema-ts skill --install

Library

import { z } from "zod";
import { compileSchema, validateArtifact, validateValues, SchemaView, softField } from "softschema";

Source schemas are Zod (z.strictObject(...)); validation uses safeParse; per-field authoring metadata uses softField(schema, {...}). See the TypeScript design doc for the module layout and the Python↔TypeScript API parity table, and the softschema Guide / Spec for the language-neutral concept and artifact format.

Development

bun + bunup + biome. bun run check runs lint, types, and tests. The shared golden corpus (tests/golden/) runs against this CLI via SOFTSCHEMA_IMPL=ts; a cross-implementation conformance test asserts the Zod and Pydantic compilers produce an identical canonical compiled schema. See the parity development process in docs/development.md.