gem-hunter

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

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.

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

• 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

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

• 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

The following JSON Schema features are not yet implemented:

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

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

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

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

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.

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

MIT

Sponsored by Glide, the platform for custom business software.