TypeBox — JSON Schema Type Builder for TypeScript

Introduction

TypeBox is a TypeScript library that lets you define JSON Schema types using a composable builder API, then extract static TypeScript types from those definitions. This means you write your schema once and get both runtime validation and compile-time type checking without code generation or separate type files. TypeBox produces standard JSON Schema output compatible with any JSON Schema validator.

What TypeBox Does

• Builds JSON Schema objects using a fluent TypeScript API (Type.String(), Type.Object(), Type.Array(), etc.)
• Infers static TypeScript types from schema definitions via the Static utility type
• Provides a built-in Value module for checking, casting, diffing, and patching values against schemas
• Supports advanced JSON Schema features: conditional types, recursive schemas, and references
• Outputs standard JSON Schema Draft 2020-12 that works with Ajv and other validators

Architecture Overview

TypeBox schemas are plain JavaScript objects that conform to the JSON Schema specification. The Type namespace provides builder functions that return schema objects annotated with TypeScript symbol metadata for type inference. The Static type extracts TypeScript types from these annotated objects at compile time. The Value module provides runtime operations (Check, Cast, Create, Decode, Encode) without depending on an external validation library.

Self-Hosting & Configuration

• Install @sinclair/typebox as a single dependency with zero transitive dependencies
• Import Type for schema building and Static for type inference
• Use the Value module for validation or connect schemas to Ajv for spec-compliant validation
• TypeBox schemas are serializable JSON; store them in files or send them over the wire
• Works in Node.js, Deno, Bun, and browser environments without configuration

Key Features

• Zero dependencies: the entire library is self-contained at around 80 KB unpacked
• Full JSON Schema Draft 2020-12 compliance for interoperability
• Composable schema definitions using TypeScript generics for DRY validation logic
• Transform types for encoding/decoding values during validation (e.g., Date strings to Date objects)
• Used by Fastify, Elysia, and FeathersJS as the default schema/type system

Comparison with Similar Tools

• Zod — TypeScript-first validation with its own schema format; TypeBox outputs standard JSON Schema
• Yup — runtime validation focused on forms; TypeBox provides both static types and JSON Schema
• Ajv — JSON Schema validator without type inference; TypeBox generates schemas that Ajv can validate
• io-ts — functional approach to runtime types; TypeBox is more approachable with a builder pattern
• Valibot — modular schema validation; TypeBox produces portable JSON Schema rather than a proprietary format

FAQ

Q: How does TypeBox differ from Zod? A: Zod defines its own schema format. TypeBox produces standard JSON Schema, making schemas portable across languages and tools.

Q: Can I use TypeBox with Ajv? A: Yes. TypeBox schemas are valid JSON Schema objects that you can pass directly to Ajv for validation.

Q: Does TypeBox validate at runtime? A: Yes, via the built-in Value.Check() and Value.Decode() functions, or by passing schemas to an external validator like Ajv.

Q: Is TypeBox suitable for API contract definitions? A: Absolutely. The JSON Schema output can be used in OpenAPI specs, shared with non-TypeScript services, and validated on both client and server.

Sources

• https://github.com/sinclairzx81/typebox
• https://sinclairzx81.github.io/typebox