typebox

Install

$ npm install typebox

Usage

…

Overview

Documentation

TypeBox is a runtime type system that creates in-memory JSON Schema objects that infer as TypeScript types. The schematics produced by this library are designed to match the static type checking rules of the TypeScript compiler. TypeBox offers a unified type that can be statically checked by TypeScript and runtime checked using standard JSON Schema validation.

This library is designed to allow JSON Schema to compose similar to how types compose within TypeScript's type system. It can be used as a simple tool to build up complex schematics or integrated into REST and RPC services to help validate data received over the wire.

License: MIT

Contents

• Type
• Script
• Schema
• Versions
• Contribute

Type

Documentation | Example

TypeBox types are JSON Schema fragments that compose into more complex types. The library provides a core set of types for constructing JSON Schema compliant schematics, alongside extended types designed to model constructs native to JavaScript and TypeScript. The JSON Schema schematics produced by TypeBox can be passed directly to any compliant validator.

Example

The following creates a User type and infers with Static.

…

Script

Documentation | Example 1 | Example 2

TypeBox includes a micro TypeScript engine that can transform TypeScript definitions to JSON Schema. The engine is fully type-safe and supports many programmable constructs including Conditional, Mapped, Indexed, Generics, Distributive Generics, and more.

Example

Syntax highlighting is available via the Visual Studio Marketplace.

…

Schema

Documentation | Example 1 | Example 2 | Example 3

TypeBox includes a high-performance JSON Schema JIT compiler that supports Draft 3 through to 2020-12. The compiler is designed to be a lightweight industry-grade alternative to Ajv and offers improved compilation and validation performance. It also offers automatic fallback to dynamic validation in JIT restricted environments such as Cloudflare Workers.

The compiler is available via optional sub module import.

import Schema from 'typebox/schema'

Compile

The compiler accepts TypeBox types as well as plain JSON Schema objects, and returns a Validator instance which can be used to check values. The following compiles a Vector type.

import Schema from 'typebox/schema'

// Compile

const Vector = Schema.Compile(Type.Script(`{
  x: number
  y: number
  z: number
}`))

// Check

const valid = Vector.Check({ x: 1, y: 0, z: 0 })   // const valid: boolean

// Parse

const result = Vector.Parse({ x: 1, y: 0, z: 0 })  // const result: {      
                                                   //   x: number
                                                   //   y: number
                                                   //   z: number
                                                   // }

Compatibility

JSON Schema Test Suite | JSON Schema Compliance Suite

TypeBox supports all versions of JSON Schema and is heavily tested against the official JSON Schema Test Suite. It prioritizes compatibility with modern specifications while also maintaining broad support for legacy versions provided their semantics are not in conflict with modern specifications.

Spec 3 4 6 7 2019-09 2020-12 v1 additionalItems ✅ ✅ ✅ ✅ ✅ - - additionalProperties ✅ ✅ ✅ ✅ ✅ ✅ ✅ allOf - ✅ ✅ ✅ ✅ ✅ ✅ anchor - - - - ✅ ✅ ✅ anyOf - ✅ ✅ ✅ ✅ ✅ ✅ boolean_schema - - ✅ ✅ ✅ ✅ ✅ const - - ✅ ✅ ✅ ✅ ✅ contains - - ✅ ✅ ✅ ✅ ✅ content - - - - ✅ ✅ ✅ default ✅ ✅ ✅ ✅ ✅ ✅ ✅ definitions - 1/2 ✅ ✅ - - - defs - - - - ✅ ✅ - dependencies 17/18 ✅ ✅ ✅ - - - dependentRequired - - - - ✅ ✅ ✅ dependentSchemas - - - - ✅ ✅ ✅ dynamicRef - - - - - ✅ ✅ enum 16/18 ✅ ✅ ✅ ✅ ✅ ✅ exclusiveMaximum - - ✅ ✅ ✅ ✅ ✅ exclusiveMinimum - - ✅ ✅ ✅ ✅ ✅ if-then-else - - - ✅ ✅ ✅ ✅ infinite-loop-detection ✅ ✅ ✅ ✅ ✅ ✅ ✅ items ✅ ✅ ✅ ✅ ✅ ✅ ✅ maxContains - - - - ✅ ✅ ✅ maximum 13/14 13/14 ✅ ✅ ✅ ✅ ✅ maxItems ✅ ✅ ✅ ✅ ✅ ✅ ✅ maxLength ✅ ✅ ✅ ✅ ✅ ✅ ✅ maxProperties - ✅ ✅ ✅ ✅ ✅ ✅ minContains - - - - ✅ ✅ ✅ minimum 12/13 16/17 ✅ ✅ ✅ ✅ ✅ minItems ✅ ✅ ✅ ✅ ✅ ✅ ✅ minLength ✅ ✅ ✅ ✅ ✅ ✅ ✅ minProperties - ✅ ✅ ✅ ✅ ✅ ✅ multipleOf - ✅ ✅ ✅ ✅ ✅ ✅ not - ✅ ✅ ✅ ✅ ✅ ✅ oneOf - ✅ ✅ ✅ ✅ ✅ ✅ pattern ✅ ✅ ✅ ✅ ✅ ✅ ✅ patternProperties ✅ ✅ ✅ ✅ ✅ ✅ ✅ prefixItems - - - - - ✅ ✅ properties ✅ ✅ ✅ ✅ ✅ ✅ ✅ propertyNames - - ✅ ✅ ✅ ✅ ✅ recursiveRef - - - - ✅ - - ref 23/27 38/45 69/70 77/78 ✅ ✅ ✅ refRemote 7/8 11/17 ✅ ✅ ✅ ✅ ✅ required 3/4 ✅ ✅ ✅ ✅ ✅ ✅ type 73/80 ✅ ✅ ✅ ✅ ✅ ✅ unevaluatedItems - - - - ✅ ✅ ✅ unevaluatedProperties - - - - ✅ ✅ ✅ uniqueItems ✅ ✅ ✅ ✅ ✅ ✅ ✅

Performance

TypeBox tracks performance against AJV8 only as the defacto performance standard. For broader comparative benchmarks, refer to the following community maintained projects.

Runtime Benchmarks | Schema Benchmarks

Compile

The following table shows compile performance for various JSON Schema structures. These benchmarks measure the time required to build and runtime JIT schematics. Faster compilation results in faster application startup.

…

Validate

The following table shows validation performance for various JSON Schema structures. These benchmarks measure overall validation throughput for compiled schematics.

…

Versions

TypeBox ships two distinct versions that span two generations of the TypeScript compiler.

TypeBox TypeScript Description 1.x 6.0 - 7.0+ Latest. Developed against the TypeScript 7 native compiler. Provides advanced type inference and native JSON Schema 2020-12 support. Includes backwards compatibility with 0.x types. ESM only. 0.x 5.0 - 6.0 LTS. Developed against older TypeScript versions and actively maintained under Long Term Support. Compatible with both ESM and CJS. Issues should be submitted to the Sinclair TypeBox repository.

Contribute

TypeBox is open to community contribution. Please ensure you submit an issue before submitting a pull request. The TypeBox project prefers open community discussion before accepting new features.