TypeBox

TypeBox lets you define a single schema with a fluent builder API and get both a runtime Json Schema object and a fully inferred static TypeScript type from it. Instead of hand-writing a TypeScript interface and a matching Json Schema (or Zod/Ajv schema) separately, you write one TypeBox definition and derive both, keeping validation rules and types permanently in sync.

Beyond the type builder, the package ships a full value toolkit (Check, Cast, Convert, Clean, Default, Clone, Diff, Patch, Hash, Encode/Decode, Parse) and an optional TypeCompiler that JIT-compiles schemas into fast standalone validation functions, plus first-class interoperability with Ajv for teams that prefer a general-purpose Json Schema validator. It targets the Json Schema Draft 7 specification and has zero runtime dependencies.

What You Get

• A fluent Type.* builder covering Json types (Object, Array, String, Number, Union, Literal) and JavaScript-native types (Date, Uint8Array, Promise, Map, Set)
• Static<T> to derive a TypeScript type directly from any TypeBox schema, eliminating duplicate type declarations
• A Value namespace with Check, Cast, Convert, Clean, Default, Clone, Diff, Patch, Hash, Encode/Decode, and Parse operators for working with runtime values against a schema
• An optional TypeCompiler that JIT-compiles a schema into a standalone validation function, plus direct Ajv interoperability for teams standardizing on Ajv
• TypeRegistry and FormatRegistry for registering custom types and string formats
• Support for advanced TypeScript-mirroring composition: generics, recursive types, template literal types, mapped/indexed types, and conditional types

Common Use Cases

• Validating request/response bodies in REST or RPC services without maintaining separate DTO types and validators
• Generating OpenAPI/Json Schema documents directly from the same schema used for runtime validation
• Parsing and coercing untrusted JSON (env vars, config files, webhook payloads) into typed, validated values
• Sharing a single schema definition between a TypeScript backend and a Json Schema-based API contract

Under The Hood

Architecture — TypeBox is organized around a src/type tree (one directory per Json/JavaScript type — object, array, union, mapped, recursive, template-literal, etc.) that each export a Type.* builder function returning a plain, symbol-tagged schema object (Kind from src/type/symbols), and a parallel src/value tree implementing the Check/Cast/Convert/Clean/Default/Clone/Diff/Patch/Hash/Encode/Decode/Parse operators that walk those schema objects against runtime values. src/compiler/compiler.ts implements TypeCompiler, which walks a schema once and emits a JIT-compiled standalone validation function, pulling in TransformEncode/TransformDecode from value/transform, Errors/ValueErrorIterator from src/errors, and TypeRegistry/FormatRegistry from src/type/registry for extensibility. src/index.ts re-exports the full public surface as flat namespaces (Infrastructure, Types, Values, Syntax) rather than a single monolithic object, letting consumers subpath-import @sinclair/typebox/value or @sinclair/typebox/compiler independently.

Tech Stack — Pure TypeScript targeting the Json Schema Draft 7 specification, with zero runtime dependencies declared in package.json; devDependencies are limited to its own build tool (@sinclair/hammer), ajv/ajv-formats for cross-validator interop tests, mocha for the test runner, prettier for formatting, and @arethetypeswrong/cli for package-export correctness checks. The custom hammer task runner drives build/test/format/publish scripts in place of a conventional bundler config.

Code Quality — The test suite is split into test/runtime (functional behavior, ~570 describe blocks across type, value, compiler, compiler-ajv, errors, syntax, and system suites) and test/static (TypeScript type-level assertions), giving both runtime-correctness and type-inference coverage — a distinction few validation libraries make explicit. Source files consistently carry MIT license headers and are organized one-concept-per-file under deeply nested but predictably named directories (e.g. type/object/object.ts), which keeps individual files small despite the library’s large overall surface (~25k lines across src).

API Design — The builder API composes the way TypeScript’s own type system does (Type.Object({...}), Type.Union([...]), Type.Optional(...)), so the learning curve for anyone fluent in TypeScript types is shallow; Static<typeof T> is the single mechanism for going from schema to type, avoiding two-step decorator or codegen workflows. The tradeoff is a very large type-level implementation (heavy use of nested mapped/conditional types, visible in files like type/object/object.ts) needed to make that inference precise, which can produce dense compiler errors on advanced generic/recursive schemas.