@adesso-se/zod-from-json-samples

This utility generates a single, robust Zod schema from one or more JSON files. It intelligently infers types by merging the structures of multiple JSON samples, with built-in support for optional fields, union types, and adding examples for OpenAPI documentation.

Usage

Install the script using and run it by providing a glob pattern to select your JSON sample files. Remember to enclose the pattern in quotes.

npm install @adesso-se/zod-from-json-samples -g

samples2zod "path/to/your/json_samples/**/*.json" -f

The script will process all matching files and generate a schema.js file in your current working directory, containing the final Zod schema.

Options

• --force-optional, -f Force all inferred properties to be optional. This is useful if your JSON schema is unstable or if you want to validate objects that may only contain a subset of the properties found in your samples.

Example

Given two JSON files:

user1.json:

{
  "id": 1,
  "name": "John Doe",
  "email": "[email protected]"
}

user2.json:

{
  "id": 2,
  "name": "Jane Doe",
  "email": null,
  "age": 30
}

Running the standard command:

npx @adesso-se/zod-from-json-samples "user*.json"

Will produce schema.js with the following content, where age is automatically detected as optional:

export const MySchema = z.object({
  id: z.number().openapi({ examples: [1, 2] }),
  name: z.string().openapi({ examples: ["John Doe", "Jane Doe"] }),
  email: z
    .string()
    .openapi({ examples: ["[email protected]"] })
    .nullable(),
  age: z
    .number()
    .openapi({ examples: [30] })
    .optional(),
});

Example with --force-optional

Running the command with the new flag:

npx @adesso-se/zod-from-json-samples "user*.json" --force-optional

Will produce schema.js where all properties are now optional:

export const MySchema = z.object({
  id: z
    .number()
    .openapi({ examples: [1, 2] })
    .optional(),
  name: z
    .string()
    .openapi({ examples: ["John Doe", "Jane Doe"] })
    .optional(),
  email: z
    .string()
    .openapi({ examples: ["[email protected]"] })
    .nullable()
    .optional(),
  age: z
    .number()
    .openapi({ examples: [30] })
    .optional(),
});

Features

• Type Inference: Analyzes JSON files to infer data types (string, number, boolean, array, object, null).
• Schema Merging: Combines multiple JSON structures into a single, comprehensive schema.
• Optional Fields: Automatically marks fields as optional if they don't appear in every JSON sample.
• Union Types: Creates union types when a field has different data types across samples.
• OpenAPI Examples: Includes values from your JSON files as examples in the generated schema using .openapi({ examples: [...] }).

Zod Tip: Making an Existing Schema Optional

If you have already generated a schema and want to make all its properties optional without re-running the tool, Zod provides a handy .partial() method.

This is especially useful for update operations (e.g., PATCH requests) where only a subset of fields may be present.

import { z } from "zod";

// Assuming MySchema is your generated schema
import { MySchema } from "./schema.js";

// Create a new schema with all properties being optional
const PartialSchema = MySchema.partial();

// Now you can validate an object with only some of the properties
const result = PartialSchema.safeParse({ name: "Jane Doe" }); // ✅ Success!