glideapps/zod-from-json-schema

README

zod-from-json-schema

A library that creates Zod types from JSON Schema at runtime. This is in contrast to json-schema-to-zod, which generates JavaScript source code.

Installation

npm install zod-from-json-schema

Zod 3 vs 4

Zod 4 is available both as the package version 4, but also as part of the version 3 packages. We support both, as well as Zod 3. Here's which version of this package to use:

Zod	zod-from-json-schema
v4 proper	latest
v4 via 3.x	^0.4.2
v3	^0.1.0

Note that the older package for Zod 3 supports a smaller subset of JSON schema than the latest. New features will only be added to the latest.

Usage

This package supports both ESM and CommonJS formats.

ESM (ES Modules)

import { convertJsonSchemaToZod } from 'zod-from-json-schema';

// Define a JSON Schema with advanced features
const jsonSchema = {
  $schema: "https://json-schema.org/draft/2020-12/schema",
  type: "object",
  properties: {
    name: { type: "string", minLength: 2, maxLength: 50 },
    age: { type: "integer", minimum: 0, maximum: 120 },
    email: { type: "string", pattern: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$" },
    tags: {
      type: "array",
      items: { type: "string" },
      uniqueItems: true,
      minItems: 1,
      maxItems: 10,
      contains: { enum: ["user", "admin", "guest"] }
    },
    coordinates: {
      type: "array",
      prefixItems: [
        { type: "number", minimum: -90, maximum: 90 },   // latitude
        { type: "number", minimum: -180, maximum: 180 }  // longitude
      ],
      items: false  // No additional items allowed
    },
    score: { type: "number", multipleOf: 0.5, minimum: 0, maximum: 100 }
  },
  required: ["name", "email"],
  additionalProperties: false,
  minProperties: 2,
  maxProperties: 10
};

// Convert JSON Schema to Zod schema
const zodSchema = convertJsonSchemaToZod(jsonSchema);

// Use the Zod schema to validate data
try {
  const validData = zodSchema.parse({
    name: "John Doe",
    email: "john@example.com",
    age: 30,
    tags: ["user", "premium", "admin"],  // Contains required "admin" role
    coordinates: [37.7749, -122.4194],   // San Francisco lat/lng
    score: 87.5  // Multiple of 0.5
  });
  console.log("Valid data:", validData);
} catch (error) {
  console.error("Validation error:", error);
}

CommonJS

const { convertJsonSchemaToZod } = require('zod-from-json-schema');

// Define a JSON Schema
const jsonSchema = {
  $schema: "https://json-schema.org/draft/2020-12/schema",
  type: "object",
  properties: {
    name: { type: "string", minLength: 2, maxLength: 50 },
    age: { type: "integer", minimum: 0, maximum: 120 },
    hobbies: {
      type: "array",
      items: { type: "string" },
      minItems: 1,
      maxItems: 5
    }
  },
  required: ["name"],
  additionalProperties: false,
  minProperties: 1
};

// Convert JSON Schema to Zod schema
const zodSchema = convertJsonSchemaToZod(jsonSchema);

// Use the Zod schema to validate data
try {
  const validData = zodSchema.parse({
    name: "John Doe",
    age: 30,
    hobbies: ["reading", "coding", "gaming"]
  });
  console.log("Valid data:", validData);
} catch (error) {
  console.error("Validation error:", error);
}

API Reference

`convertJsonSchemaToZod(schema)`

Converts a JSON Schema object to a complete Zod schema.

Parameters:
- schema (Object): A JSON Schema object
Returns:
- A Zod schema that validates according to the JSON Schema

`jsonSchemaObjectToZodRawShape(schema)`

Extracts the object properties from a JSON Schema object into a Zod raw shape. This is useful when you want to combine the properties with other Zod object configurations.

Parameters:
- schema (Object): A JSON Schema object that should have a properties field
Returns:
- A ZodRawShape object that can be used with z.object()

Example:

import { jsonSchemaObjectToZodRawShape } from 'zod-from-json-schema';
import { z } from 'zod';

const jsonSchema = {
  properties: {
    name: { type: "string" },
    age: { type: "integer" }
  },
  required: ["name"]
};

// Get just the property definitions
const rawShape = jsonSchemaObjectToZodRawShape(jsonSchema);

// Add custom handling
const customSchema = z.object({
  ...rawShape,
  // Add additional fields not in the JSON Schema
  createdAt: z.date().default(() => new Date())
}).refine(data => data.age > 18, {
  message: "Age must be over 18 to continue"
});

Supported JSON Schema Features

This library provides comprehensive support for JSON Schema Draft 2020-12 features with 100% code coverage and extensive test validation against the official JSON Schema Test Suite.

Basic Types

string - Basic string validation
number - Numeric values (including integers)
integer - Integer-only numeric values
boolean - Boolean true/false values
null - Null values
object - Object validation with property definitions
array - Array validation with item constraints

String Validations

minLength - Minimum string length (Unicode grapheme-aware)
maxLength - Maximum string length (Unicode grapheme-aware)
pattern - Regular expression pattern matching

Unicode Support: String length validation correctly counts Unicode grapheme clusters (user-perceived characters) rather than UTF-16 code units, ensuring proper validation of emoji and international text.

Number Validations

minimum - Minimum numeric value
maximum - Maximum numeric value
exclusiveMinimum - Exclusive minimum (greater than)
exclusiveMaximum - Exclusive maximum (less than)
multipleOf - Multiple validation with floating-point precision handling

Draft-4 Compatibility: The legacy boolean form of exclusiveMinimum/exclusiveMaximum (e.g. { "minimum": 5, "exclusiveMinimum": true }, as used by draft-4 and Swagger 2.0) is also accepted: true makes the sibling minimum/maximum bound exclusive, and false is a no-op.

Array Validations

items - Item schema validation (supports schemas, boolean values, and arrays)
prefixItems - Tuple-style positional item validation (Draft 2020-12)
minItems - Minimum array length
maxItems - Maximum array length
uniqueItems - Ensures all array items are unique
contains - Validates that array contains items matching a schema
minContains - Minimum number of items matching the contains schema
maxContains - Maximum number of items matching the contains schema

Advanced Array Features:

Boolean items schemas (items: false = empty arrays only, items: true = any items allowed)
Complex tuple validation with prefixItems and additional items control
Sophisticated contains validation with count constraints

Object Validations

properties - Property schema definitions
required - Required property validation (supports special JavaScript property names)
additionalProperties - Controls whether additional properties are allowed
patternProperties - Regex-based property validation (partial; see Known Limitations)
propertyNames - Validation of property names themselves
dependentSchemas - Schema dependencies based on property presence
minProperties - Minimum number of object properties
maxProperties - Maximum number of object properties
dependentRequired - Required properties based on other property presence

Special Property Support: Correctly handles JavaScript reserved property names like constructor and toString — inherited members are not mistaken for property values, and own keys are validated normally. __proto__ is an exception; see Known Limitations.

Schema Composition

const - Literal value constraints
enum - Enumerated value validation
anyOf - Union type validation (basic cases)
allOf - Intersection validation (basic cases)
oneOf - Exclusive union validation (exactly one schema must match)
not - Negation validation
if / then / else - Conditional schema application

References and Definitions

$ref - Internal references, including JSON pointer fragments (with ~0/~1 and percent-encoding escapes) and references to arbitrary schema locations (e.g. #/properties/foo)
$defs / definitions - Schema definitions for reuse
$id - Intra-document base URI resolution (nearest-parent bases, relative and absolute URIs, URN and file: bases)
$anchor - Location-independent identifiers, scoped to their schema resource
$dynamicRef / $dynamicAnchor - Resolved statically, like $ref/$anchor (no dynamic scoping; see Known Limitations)
Recursive and mutually recursive references
Sibling keywords next to $ref apply conjunctively (Draft 2020-12 semantics)

Remote/external references (documents other than the one being converted) are not yet supported and are ignored; see Known Limitations.

Additional Features

title - Schema titles (carried over to Zod schemas)
description - Schema descriptions (carried over to Zod schemas)
default - Default value annotation, but ignored if it doesn't conform to the schema; a default never satisfies required for a missing property
Boolean schemas (true = allow anything, false = allow nothing)
Implicit type detection from constraints
Comprehensive error messages

Currently Unsupported Features

The following JSON Schema features are not yet implemented:

References and Definitions

Remote/external references (referencing documents other than the one being converted)
True dynamic scoping for $dynamicRef / $dynamicAnchor (they are resolved statically)

Advanced Object Validation

additionalProperties - Fine-grained control over additional properties (basic support exists)
unevaluatedProperties - Properties not covered by schema evaluation

Advanced Array Validation

unevaluatedItems - Items not covered by schema evaluation
Complex prefixItems scenarios with additional item control

Meta-Schema Features

Custom vocabularies and meta-schema validation
Annotation collection and processing

Known Limitations

Beyond the unsupported keywords above, supported features have some known gaps:

__proto__ properties: Zod removes own __proto__ keys from parsed objects to prevent prototype pollution, and this library's validation runs on Zod's parse output. As a result, a __proto__ entry in properties cannot validate its value, and required: ["__proto__"] is only enforced for schemas without an explicit type.
Unresolvable references are ignored: A $ref/$dynamicRef that cannot be resolved within the document (remote URIs, unknown anchors, dangling pointers) does not constrain the value at all; the rest of the schema still applies.
$dynamicRef is resolved statically: Dynamic scoping is not implemented; $dynamicRef behaves like $ref (and $dynamicAnchor like $anchor), which matches the spec whenever the dynamic anchor is bookended in the same schema resource.
Degenerate reference cycles: Reference chains that lead back to themselves without making progress on the data are dropped (treated as unresolvable) when the cycle consists purely of $ref/$dynamicRef edges. Cycles that pass through applicators that don't consume data (e.g. not or allOf) are not detected and will recurse at validation time.
Deeply recursive data: Validating recursive schemas against deeply nested data (on the order of a few hundred nesting levels, engine-dependent) can exhaust the JavaScript call stack.
unevaluatedProperties is ignored: In particular, discriminated unions whose oneOf variants differ only by unevaluatedProperties: false will not reject inputs that mix properties from different variants. Declaring required properties in each variant makes the variants distinguishable instead.

Standards Compliance

JSON Schema Draft 2020-12 - Partial support for core features of the latest JSON Schema standard
Official Test Suite - Passes the majority of tests from the official JSON Schema Test Suite (tests for unsupported features are listed in the skip list)

License

MIT

Sponsor

Sponsored by Glide, the platform for custom business software.

README

zod-from-json-schema

A library that creates Zod types from JSON Schema at runtime. This is in contrast to json-schema-to-zod, which generates JavaScript source code.

Installation

npm install zod-from-json-schema

Zod 3 vs 4

Zod 4 is available both as the package version 4, but also as part of the version 3 packages. We support both, as well as Zod 3. Here's which version of this package to use:

Zod	zod-from-json-schema
v4 proper	latest
v4 via 3.x	^0.4.2
v3	^0.1.0

Note that the older package for Zod 3 supports a smaller subset of JSON schema than the latest. New features will only be added to the latest.

Usage

This package supports both ESM and CommonJS formats.

ESM (ES Modules)

import { convertJsonSchemaToZod } from 'zod-from-json-schema';

// Define a JSON Schema with advanced features
const jsonSchema = {
  $schema: "https://json-schema.org/draft/2020-12/schema",
  type: "object",
  properties: {
    name: { type: "string", minLength: 2, maxLength: 50 },
    age: { type: "integer", minimum: 0, maximum: 120 },
    email: { type: "string", pattern: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$" },
    tags: {
      type: "array",
      items: { type: "string" },
      uniqueItems: true,
      minItems: 1,
      maxItems: 10,
      contains: { enum: ["user", "admin", "guest"] }
    },
    coordinates: {
      type: "array",
      prefixItems: [
        { type: "number", minimum: -90, maximum: 90 },   // latitude
        { type: "number", minimum: -180, maximum: 180 }  // longitude
      ],
      items: false  // No additional items allowed
    },
    score: { type: "number", multipleOf: 0.5, minimum: 0, maximum: 100 }
  },
  required: ["name", "email"],
  additionalProperties: false,
  minProperties: 2,
  maxProperties: 10
};

// Convert JSON Schema to Zod schema
const zodSchema = convertJsonSchemaToZod(jsonSchema);

// Use the Zod schema to validate data
try {
  const validData = zodSchema.parse({
    name: "John Doe",
    email: "john@example.com",
    age: 30,
    tags: ["user", "premium", "admin"],  // Contains required "admin" role
    coordinates: [37.7749, -122.4194],   // San Francisco lat/lng
    score: 87.5  // Multiple of 0.5
  });
  console.log("Valid data:", validData);
} catch (error) {
  console.error("Validation error:", error);
}

CommonJS

const { convertJsonSchemaToZod } = require('zod-from-json-schema');

// Define a JSON Schema
const jsonSchema = {
  $schema: "https://json-schema.org/draft/2020-12/schema",
  type: "object",
  properties: {
    name: { type: "string", minLength: 2, maxLength: 50 },
    age: { type: "integer", minimum: 0, maximum: 120 },
    hobbies: {
      type: "array",
      items: { type: "string" },
      minItems: 1,
      maxItems: 5
    }
  },
  required: ["name"],
  additionalProperties: false,
  minProperties: 1
};

// Convert JSON Schema to Zod schema
const zodSchema = convertJsonSchemaToZod(jsonSchema);

// Use the Zod schema to validate data
try {
  const validData = zodSchema.parse({
    name: "John Doe",
    age: 30,
    hobbies: ["reading", "coding", "gaming"]
  });
  console.log("Valid data:", validData);
} catch (error) {
  console.error("Validation error:", error);
}

API Reference

`convertJsonSchemaToZod(schema)`

Converts a JSON Schema object to a complete Zod schema.

Parameters:
- schema (Object): A JSON Schema object
Returns:
- A Zod schema that validates according to the JSON Schema

`jsonSchemaObjectToZodRawShape(schema)`

Extracts the object properties from a JSON Schema object into a Zod raw shape. This is useful when you want to combine the properties with other Zod object configurations.

Parameters:
- schema (Object): A JSON Schema object that should have a properties field
Returns:
- A ZodRawShape object that can be used with z.object()

Example:

import { jsonSchemaObjectToZodRawShape } from 'zod-from-json-schema';
import { z } from 'zod';

const jsonSchema = {
  properties: {
    name: { type: "string" },
    age: { type: "integer" }
  },
  required: ["name"]
};

// Get just the property definitions
const rawShape = jsonSchemaObjectToZodRawShape(jsonSchema);

// Add custom handling
const customSchema = z.object({
  ...rawShape,
  // Add additional fields not in the JSON Schema
  createdAt: z.date().default(() => new Date())
}).refine(data => data.age > 18, {
  message: "Age must be over 18 to continue"
});

Supported JSON Schema Features

This library provides comprehensive support for JSON Schema Draft 2020-12 features with 100% code coverage and extensive test validation against the official JSON Schema Test Suite.

Basic Types

string - Basic string validation
number - Numeric values (including integers)
integer - Integer-only numeric values
boolean - Boolean true/false values
null - Null values
object - Object validation with property definitions
array - Array validation with item constraints

String Validations

minLength - Minimum string length (Unicode grapheme-aware)
maxLength - Maximum string length (Unicode grapheme-aware)
pattern - Regular expression pattern matching

Number Validations

minimum - Minimum numeric value
maximum - Maximum numeric value
exclusiveMinimum - Exclusive minimum (greater than)
exclusiveMaximum - Exclusive maximum (less than)
multipleOf - Multiple validation with floating-point precision handling

Array Validations

items - Item schema validation (supports schemas, boolean values, and arrays)
prefixItems - Tuple-style positional item validation (Draft 2020-12)
minItems - Minimum array length
maxItems - Maximum array length
uniqueItems - Ensures all array items are unique
contains - Validates that array contains items matching a schema
minContains - Minimum number of items matching the contains schema
maxContains - Maximum number of items matching the contains schema

Advanced Array Features:

Boolean items schemas (items: false = empty arrays only, items: true = any items allowed)
Complex tuple validation with prefixItems and additional items control
Sophisticated contains validation with count constraints

Object Validations

properties - Property schema definitions
required - Required property validation (supports special JavaScript property names)
additionalProperties - Controls whether additional properties are allowed
patternProperties - Regex-based property validation (partial; see Known Limitations)
propertyNames - Validation of property names themselves
dependentSchemas - Schema dependencies based on property presence
minProperties - Minimum number of object properties
maxProperties - Maximum number of object properties
dependentRequired - Required properties based on other property presence

Schema Composition

const - Literal value constraints
enum - Enumerated value validation
anyOf - Union type validation (basic cases)
allOf - Intersection validation (basic cases)
oneOf - Exclusive union validation (exactly one schema must match)
not - Negation validation
if / then / else - Conditional schema application

References and Definitions

$ref - Internal references, including JSON pointer fragments (with ~0/~1 and percent-encoding escapes) and references to arbitrary schema locations (e.g. #/properties/foo)
$defs / definitions - Schema definitions for reuse
$id - Intra-document base URI resolution (nearest-parent bases, relative and absolute URIs, URN and file: bases)
$anchor - Location-independent identifiers, scoped to their schema resource
$dynamicRef / $dynamicAnchor - Resolved statically, like $ref/$anchor (no dynamic scoping; see Known Limitations)
Recursive and mutually recursive references
Sibling keywords next to $ref apply conjunctively (Draft 2020-12 semantics)

Remote/external references (documents other than the one being converted) are not yet supported and are ignored; see Known Limitations.

Additional Features

title - Schema titles (carried over to Zod schemas)
description - Schema descriptions (carried over to Zod schemas)
default - Default value annotation, but ignored if it doesn't conform to the schema; a default never satisfies required for a missing property
Boolean schemas (true = allow anything, false = allow nothing)
Implicit type detection from constraints
Comprehensive error messages

Currently Unsupported Features

The following JSON Schema features are not yet implemented:

References and Definitions

Remote/external references (referencing documents other than the one being converted)
True dynamic scoping for $dynamicRef / $dynamicAnchor (they are resolved statically)

Advanced Object Validation

additionalProperties - Fine-grained control over additional properties (basic support exists)
unevaluatedProperties - Properties not covered by schema evaluation

Advanced Array Validation

unevaluatedItems - Items not covered by schema evaluation
Complex prefixItems scenarios with additional item control

Meta-Schema Features

Custom vocabularies and meta-schema validation
Annotation collection and processing

Known Limitations

Beyond the unsupported keywords above, supported features have some known gaps:

__proto__ properties: Zod removes own __proto__ keys from parsed objects to prevent prototype pollution, and this library's validation runs on Zod's parse output. As a result, a __proto__ entry in properties cannot validate its value, and required: ["__proto__"] is only enforced for schemas without an explicit type.
Unresolvable references are ignored: A $ref/$dynamicRef that cannot be resolved within the document (remote URIs, unknown anchors, dangling pointers) does not constrain the value at all; the rest of the schema still applies.
$dynamicRef is resolved statically: Dynamic scoping is not implemented; $dynamicRef behaves like $ref (and $dynamicAnchor like $anchor), which matches the spec whenever the dynamic anchor is bookended in the same schema resource.
Degenerate reference cycles: Reference chains that lead back to themselves without making progress on the data are dropped (treated as unresolvable) when the cycle consists purely of $ref/$dynamicRef edges. Cycles that pass through applicators that don't consume data (e.g. not or allOf) are not detected and will recurse at validation time.
Deeply recursive data: Validating recursive schemas against deeply nested data (on the order of a few hundred nesting levels, engine-dependent) can exhaust the JavaScript call stack.
unevaluatedProperties is ignored: In particular, discriminated unions whose oneOf variants differ only by unevaluatedProperties: false will not reject inputs that mix properties from different variants. Declaring required properties in each variant makes the variants distinguishable instead.

Standards Compliance

JSON Schema Draft 2020-12 - Partial support for core features of the latest JSON Schema standard
Official Test Suite - Passes the majority of tests from the official JSON Schema Test Suite (tests for unsupported features are listed in the skip list)

License

MIT

Sponsor

Sponsored by Glide, the platform for custom business software.