jsonv-ts weekly downloads statistics

jsonv-ts: JSON Schema Builder and Validator for TypeScript

<!-- TOC depthfrom:2 updateonsave:true -->

• Installation
• Example
• Motivation
• Schema Types
  • Strings
  • Numbers
  • Integers
  • Booleans
  • Literals
  • Arrays
  • Objects
    • Strict Object
    • Partial Object
    • Record
  • Unions
  • Any
  • From Schema
  • References
  • Custom Schemas
• Utilities
  • TypeScript Type Generation
• Hono Integration
  • Validator Middleware
  • OpenAPI generation
• MCP
  • Hono MCP Middleware
  • MCP Client
• Validation
  • Integrated Validator
    • Using Standard Schema
  • Using ajv
  • Using @cfworker/json-schema
  • Using json-schema-library
• Development
• License
• Acknowledgements

<!-- /TOC --> <!-- /TOC -->

A simple, lightweight and dependency-free TypeScript library for defining and validating JSON schemas with static type inference.

• Type-safe JSON schema definition in TypeScript.
• Static type inference from schemas using the Static helper.
• Built-in spec-compliant validation for the latest JSON schema draft (2020-12).
• Hono integration for OpenAPI generation and request validation.
• MCP server and client implementation.
• Support for standard JSON schema types, references, and validation keywords.

The schemas composed can be used with any JSON schema validator, it strips all metadata when being JSON stringified.

jsonv-ts allows you to define JSON schemas using a TypeScript API. It provides functions for all standard JSON schema types (object, string, number, array, boolean) as well as common patterns like optional fields, union types (anyOf, oneOf, and allOf), and constants/enums. The Static type helper infers the corresponding TypeScript type directly from your schema definition.

Installation

npm install jsonv-ts

Example

import { s, type Static } from "jsonv-ts";

const schema = s.object({
   id: s.number(),
   username: s.string({ minLength: 3 }),
   email: s.string({ format: "email" }).optional(),
});
// {
//    "type": "object",
//    "properties": {
//       "id": { "type": "number" },
//       "username": { "type": "string", "minLength": 3 },
//       "email": { "type": "string", "format": "email" }
//    },
//    "required": ["id", "username"]
// }

// Infer the TypeScript type from the schema
type User = Static<typeof schema>;
// { id: number; username: string; email?: string | undefined }

// Example usage:
const user: User = {
   id: 123,
   username: "john_doe",
   // email is optional
};

// Type checking works as expected:
// const invalidUser: User = { id: "abc", username: "jd" }; // Type error

// Use the integrated validation
const result = schema.validate(user);
// { valid: true, errors: [] }

const result2 = schema.validate({ id: 1 });
// {
//  "valid": false,
//  "errors": [
//    {
//      "keywordLocation": "/required",
//      "instanceLocation": "/",
//      "error": "Expected object with required properties id, username",
//      "data": {
//        "id": 1
//      }
//    }
//  ]
// }

Motivation

If you validate schemas only within the same code base and need comprehensive functionality, you might be better off choosing another library such as zod, TypeBox, etc.

But if you need controllable and predictable schema validation, this library is for you. I was frustrated about the lack of adherence to the JSON schema specification in other libraries, so I decided to create this library. Furthermore, most of the other libraries may reduce your IDE performance due to the sheer number of features they provide.

JSON Schema is simple, elegant and well-defined, so why not use it directly?

Schema Types

Below are the primary functions for building schemas:

Strings

Defines a string type. Optional schema can include standard JSON schema string constraints like minLength, maxLength, pattern, format, etc.

const schema = s.string({ format: "email" });
// { type: "string", format: "email" }

type Email = Static<typeof schema>; // string

To define an Enum, you can add the enum property to the schema. It'll be inferred correctly.

const schema = s.string({ enum: ["red", "green", "blue"] });
// { type: "string", enum: [ "red", "green", "blue" ] }

type Color = Static<typeof schema>; // "red" | "green" | "blue"

The same applies to Constants:

const schema = s.string({ const: "active" });
// { type: "string", const: "active" }

type Status = Static<typeof schema>; // "active"

Numbers

Defines a number type. Optional schema can include minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf.

const schema = s.number({ minimum: 0 });
// { type: "number", minimum: 0 }

type PositiveNumber = Static<typeof schema>; // number
```…