Shape documentation#

Shape is a schema-by-example validator: your schema looks (almost) exactly like your data. It runs in JavaScript/TypeScript (browser and backend), in Go and in Rust, with the three implementations kept at behavioural parity—TypeScript is the canonical reference.

These docs follow the Diátaxis system and are published at rjrodger.github.io/shape, where a performance report compares shape to other validators. Pick the column that matches what you need right now:

Tutorials#

Start here if you are new. Learning-oriented, worked end-to-end.

• Getting started—build and grow your first shape, in both TypeScript and Go.

How-to guides#

Goal-oriented recipes for a task you already have.

• Validate options with defaults
• Require fields
• Validate objects and nesting
• Validate arrays and tuples
• Add custom validation
• Compose shapes (One / Some / All / Exact / Discriminated)
• Coerce values and check string formats
• Handle and collect errors
• Rename, Define and Refer
• Use key and value expressions
• Use the string DSL (expr / build)
• Use Shape as a Standard Schema
• Serialize a shape
• Export and import a JSON Schema
• Use Shape in Go
• Use Shape in Rust
• Use Shape in the browser

Reference#

Dry, complete, look-it-up material.

• Builder reference—every builder, in TypeScript and Go (the Rust forms are in the Rust API).
• Shape API—compiling, validating, options.
• Errors—error objects and message format.
• The regexp subset—what a pattern may use, and how every engine is made to read it the same way.
• Shape nodes—the compiled node model.
• TypeScript types
• Go API—the Go surface and its idioms.
• Rust API—the Rust surface and its idioms.

Explanation#

Background and design discussion.

• Schema by example—the core idea.
• How validation works—defaults, mutation, traversal, required/optional semantics.
• TypeScript ↔ Go ↔ Rust parity—the parity contract, the shared conformance corpus, and known divergences.
• Performance review—where validation spends its time in each language, and what would make it faster.

Decision records#

Design decisions that are expensive to revisit, with the reasoning behind them.

• ADR index
  • 0001—Validation is synchronous, in both languages

Conventions used in these docs#

• TS examples use the npm package; Go examples use the Go module; Rust examples use the crate. Where behaviour is identical, only one is shown and the other languages differ only in syntax (see the Go API and Rust API for the mapping).
• Runnable examples assume const { Shape } = require('shape') (TS/JS), import "github.com/rjrodger/shape/go" (Go) or use shape::{shape, Schema} (Rust, from the shape-schema crate).
• The canonical behaviour is defined by the TypeScript implementation and pinned by the shared corpus in test/.
• These pages are written to a style guide, which two gates enforce: make lint-docs and the docs-style block of ts/test/docs.test.ts.