json-schema-validator-gen

A lightweight JSON Schema validator generator that creates minimal TypeScript code and type definitions.

Features

• 🚀 Zero runtime dependencies - Generated validators are standalone
• 🔍 Type-safe - Full TypeScript support with generated type definitions
• ⚡ Fast validation - No runtime schema parsing, direct code execution
• 🌐 Universal - Works in Node.js and browsers
• 📋 Detailed errors - Rich error information with path, expected/received values

Installation

npm install -D @speria-jp/json-schema-validator-gen
# or
yarn add -D @speria-jp/json-schema-validator-gen
# or
pnpm add -D @speria-jp/json-schema-validator-gen
# or
bun add -D @speria-jp/json-schema-validator-gen

Usage

CLI

Basic usage:

# Generate from root schema (type name derived from file name)
npx @speria-jp/json-schema-validator-gen -s user-schema.json -o validator.ts

# Generate with custom type name
npx @speria-jp/json-schema-validator-gen -s schema.json -o validator.ts \
  -t 'path=#,name=User'

# Generate from specific definition
npx @speria-jp/json-schema-validator-gen -s schema.json -o validator.ts \
  -t '#/$defs/User'

# Generate multiple types with custom names
npx @speria-jp/json-schema-validator-gen -s schema.json -o types.ts \
  -t 'path=#/$defs/User,name=AppUser' \
  -t 'path=#/$defs/Post,name=BlogPost'

If installed locally, you can also use your package manager directly:

# npm
npx json-schema-validator-gen -s schema.json -o validator.ts

# yarn
yarn json-schema-validator-gen -s schema.json -o validator.ts

# pnpm
pnpm json-schema-validator-gen -s schema.json -o validator.ts

# bun
bun json-schema-validator-gen -s schema.json -o validator.ts

Options:

• -s, --schema - Path to JSON Schema file (required)
• -o, --output - Output path for generated code (required)
• -t, --target - JSON Schema target path (e.g., #/$defs/User). Can be specified multiple times to generate multiple types. Supports custom type names with path=...,name=... format. Defaults to # (root schema)
• -h, --help - Show help message

Programmatic API

import { generate } from '@speria-jp/json-schema-validator-gen';

// Generate from root schema (default, type name derived from file name)
const result = await generate({
  schemaPath: './user-schema.json',
  outputPath: './validator.ts'
});

// Generate from root with custom type name
const result = await generate({
  schemaPath: './schema.json',
  outputPath: './validator.ts',
  targets: ['path=#,name=User']
});

// Generate from specific targets
const results = await generate({
  schemaPath: './schema.json',
  outputPath: './types.ts',
  targets: ['#/$defs/User', '#/$defs/Post']
});

// Generate with custom type names
const results = await generate({
  schemaPath: './schema.json',
  outputPath: './types.ts',
  targets: [
    'path=#/$defs/User,name=AppUser',
    'path=#/$defs/Post,name=BlogPost'
  ]
});

Example

Given a JSON Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "User",
  "required": ["id", "name", "email"],
  "properties": {
    "id": {
      "type": "integer",
      "minimum": 1
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "email": {
      "type": "string",
      "format": "email",
      "pattern": "^[\\w.-]+@[\\w.-]+\\.[a-z]{2,}$"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "role": {
      "type": "string",
      "enum": ["admin", "user", "guest"]
    }
  },
  "additionalProperties": false
}

The generator creates:

export type User = {
    id: number;
    name: string;
    email: string;
    age?: number;
    tags?: string[];
    role?: "admin" | "user" | "guest";
};

// Returns ValidationResult with detailed error information
export function validateUser(value: unknown, options?: ValidationOptions): ValidationResult<User> {
    // ... validation logic
}

// Throws an error if validation fails, returns the validated value otherwise
export function unsafeValidateUser(value: unknown): User {
    // ... validation logic
}

Usage:

import { validateUser, unsafeValidateUser, type User } from './validator';

// Using validateUser - returns ValidationResult
const result = validateUser(data);
if (result.success) {
    console.log('Valid user:', result.data);
} else {
    console.log('Validation errors:', result.issues);
    // Each issue contains: code, path, message, expected, received
}

// Using unsafeValidateUser - throws on invalid input
try {
    const user = unsafeValidateUser(data);
    console.log('Valid user:', user);
} catch (error) {
    console.log('Validation failed:', error.message);
}

// Abort early option - stop on first error
const result = validateUser(data, { abortEarly: true });

Multiple Types Example

You can generate multiple types from a single JSON Schema file using the --target option:

# Generate User and Post types from $defs (type names derived from path)
npx json-schema-validator-gen -s schema.json -o types.ts \
  -t '#/$defs/User' -t '#/$defs/Post'

Given a JSON Schema with $defs:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$defs": {
    "Address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" },
        "zipCode": { "type": "string" }
      },
      "required": ["street", "city"]
    },
    "User": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" },
        "email": { "type": "string" },
        "address": { "$ref": "#/$defs/Address" }
      },
      "required": ["id", "name", "email"]
    },
    "Post": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "title": { "type": "string" },
        "authorId": { "type": "string" }
      },
      "required": ["id", "title", "authorId"]
    }
  }
}

The generator automatically collects dependencies and creates all necessary types in a single file. Note that Address is also generated because it's referenced by User, but it's not exported since it wasn't specified in --target:

// Address type (generated as dependency, not exported)
type Address = {
    street: string;
    city: string;
    zipCode?: string;
};

// User type uses type reference instead of inline expansion
export type User = {
    id: string;
    name: string;
    email: string;
    address?: Address;
};

export type Post = {
    id: string;
    title: string;
    authorId: string;
};

// Dependency validator (not exported)
function validateAddress(value: unknown): ValidationResult<Address> { /* ... */ }

// Exported validators for User and Post
export function validateUser(value: unknown): ValidationResult<User> { /* ... */ }
export function unsafeValidateUser(value: unknown): User { /* ... */ }

export function validatePost(value: unknown): ValidationResult<Post> { /* ... */ }
export function unsafeValidatePost(value: unknown): Post { /* ... */ }

Validation Result

Generated validators return a ValidationResult<T> discriminated union:

type ValidationResult<T> =
  | { success: true; data: T }
  | { success: false; issues: ValidationIssue[] };

interface ValidationIssue {
  code: ValidationIssueCode;
  path: (string | number)[];  // e.g., ["address", "zipCode"] or ["items", 0]
  message: string;
  expected: string;
  received: string;
}

Error Codes

| Code | Description | Example | |------|-------------|---------| | invalid_type | Value has wrong type | Expected string, received number | | missing_key | Required property is missing | Missing email property | | too_small | Value below minimum | Number < minimum, string length < minLength | | too_big | Value above maximum | Number > maximum, string length > maxLength | | invalid_string | String doesn't match pattern | Email pattern mismatch | | invalid_value | Value not in allowed set | Enum value not in list | | not_integer | Number is not an integer | 25.5 instead of 25 | | not_unique | Array has duplicate items | ["a", "a"] with uniqueItems: true | | unrecognized_key | Unknown property | Extra property with additionalProperties: false |

Supported JSON Schema Features

• Basic types: string, number, integer, boolean, null, array, object
• Type constraints:
  • Numbers: minimum, maximum
  • Strings: minLength, maxLength, pattern, format
  • Arrays: items validation
  • Integers: proper integer validation
• Object validation: required properties, additionalProperties
• Array validation: items schema validation
• Enums and const values: Full enum support
• Union types: Full support for oneOf and anyOf with validation
• References: $ref support for local definitions (#/definitions/ and #/$defs/)
• Optional properties: Proper handling of required vs optional fields

Security Considerations

For general security considerations when working with JSON Schema validation, please refer to the Ajv Security Guidelines. While this tool generates code at build time rather than runtime, many of the same principles apply regarding input validation and schema design.

Development

# Install dependencies
bun install

# Run development CLI
bun run dev

# Build the project
bun run build

# Run tests
bun test

# Type checking
bun run typecheck

# Linting
bun run lint
bun run lint:fix

License

MIT