CI Coverage npm version

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.

npm install zod-from-json-schema

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:

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.

This package supports both ESM and CommonJS formats.

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);
}

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);
}

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

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"
});

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.

• 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

• 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.

• 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

• 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

• properties - Property schema definitions
• required - Required property validation (supports special JavaScript property names)
• additionalProperties - Controls whether additional properties are allowed
• minProperties - Minimum number of object properties
• maxProperties - Maximum number of object properties

Special Property Support: Correctly handles JavaScript reserved property names like constructor, toString, and __proto__.

• 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

• title - Schema titles (carried over to Zod schemas)
• description - Schema descriptions (carried over to Zod schemas)
• Boolean schemas (true = allow anything, false = allow nothing)
• Implicit type detection from constraints
• Comprehensive error messages

The following JSON Schema features are not yet implemented:

• $ref - JSON Pointer references
• $defs / definitions - Schema definitions for reuse
• Remote references ($id resolution)
• $dynamicRef / $dynamicAnchor - Dynamic references

• patternProperties - Property validation based on regex patterns
• additionalProperties - Fine-grained control over additional properties (basic support exists)
• dependentSchemas - Schema dependencies based on property presence
• dependentRequired - Required properties based on other property presence
• propertyNames - Validation of property names themselves
• unevaluatedProperties - Properties not covered by schema evaluation

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

• if / then / else - Conditional schema application

• Custom vocabularies and meta-schema validation
• Annotation collection and processing

• 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 (246 tests currently skipped for unsupported features)

MIT