json-schema-faker

Generate valid JSON data from JSON Schema definitions. Zero production dependencies.

If this project saves you time, consider sponsoring its development. Your support keeps it maintained and growing.

import { generate } from "json-schema-faker";

const data = await generate({
  type: "object",
  properties: {
    name: { type: "string", minLength: 2 },
    age: { type: "integer", minimum: 0, maximum: 120 },
    email: { type: "string", format: "email" },
    tags: { type: "array", items: { type: "string" }, maxItems: 3 }
  },
  required: ["name", "email"]
});

Features

• Supports JSON Schema 2019-09 and 2020-12
• Deterministic output via seeded PRNG (Mulberry32)
• All standard types: null, boolean, integer, number, string, array, object
• Composition keywords: allOf, anyOf, oneOf, not, if/then/else (JSON Schema 2020-12)
• $ref resolution with cycle detection and configurable recursion depth
• Remote $ref resolution (HTTP/file) via createRemoteResolver()
• Built-in format generators: date-time, email, uri, hostname, ipv4/ipv6, uuid, json-pointer
• Regex pattern support via AST-based string generator
• Built-in keywords: autoIncrement, template (string interpolation)
• Extension support for faker and chance
• Custom format registration via registerFormat()
• Custom keyword extensions via define() with per-call GenerateContext

Install

npm install json-schema-faker
# or
bun add json-schema-faker

API

generate(schema, options?)

Generate a value from a JSON Schema. Returns Promise<unknown>.

const value = await generate({ type: "string", format: "email" });

createGenerator(options?)

Create a reusable generator with auto-incrementing seeds, producing different output on each call.

const gen = createGenerator({ seed: 42 });
const a = await gen.generate(schema); // seed 42
const b = await gen.generate(schema); // seed 43

registerFormat(name, generator)

Register a custom format generator globally.

registerFormat("phone", (random) => {
  const area = random.int(200, 999);
  const num = random.int(1000000, 9999999);
  return `+1-${area}-${num}`;
});

createRemoteResolver(options?)

Create a $ref resolver for external schemas (URLs or files).

import { generate, createRemoteResolver } from "json-schema-faker";

const resolver = createRemoteResolver({
  baseUrl: "https://example.com/schemas/"
});

await generate(schema, { refResolver: resolver });

define(name, callback)

Register a custom keyword generator. The callback receives:

• value: the keyword value from the schema
• schema: the full schema node
• ctx: the current GenerateContext

Use this to persist extension-local state across calls. Use ctx when you need generation-time details such as the current schema path or output path.

define("counter", function() {
  return ++this.count;
});

define("uuid", function(_value, _schema, ctx) {
  if (ctx.outputPath === "/user/id") {
    return crypto.randomUUID();
  }

  return "fallback-id";
});

For nested properties, ctx.path is the schema traversal path and ctx.outputPath is the final generated-output JSON pointer.

Composition behavior

Nested allOf constraints from multiple branches are preserved during merging. For example, schemas such as:

const schema = {
  type: "object",
  properties: {
    root: {
      allOf: [
        { allOf: [{ properties: { a: { const: "a" } }, required: ["a"] }] },
        { allOf: [{ properties: { b: { const: "b" } }, required: ["b"] }] },
      ],
    },
  },
  required: ["root"],
};

now retain both nested branches instead of discarding the earlier one during merge.

reset(name?)

Clear registered custom keywords. Call without arguments to clear all.

reset("counter"); // clear specific
reset();          // clear all

Options

await generate(schema, {
  // Seeding & limits
  seed: 12345,                       // Random seed (default: 1)
  maxDepth: 5,                       // Max recursion depth (default: 5)
  maxDefaultItems: 3,                // Default max array items (default: 3)

  // Property generation
  optionalsProbability: 0.5,           // Probability of optional properties (default: 0.5)
  alwaysFakeOptionals: true,           // Always generate optional properties
  fillProperties: true,                // Fill beyond required properties
  fixedProbabilities: true,            // Deterministic probabilities for testing
  pruneProperties: ["internal"],       // Remove properties from output

  // Schema overrides
  minItems: 2,                       // Override schema minItems
  maxItems: 10,                      // Override schema maxItems
  minLength: 5,                      // Override schema minLength
  maxLength: 20,                     // Override schema maxLength

  // Value sources
  useDefaultValue: true,             // Use schema `default` values
  useExamplesValue: true,            // Use schema `examples` values

  // $ref recursion
  refDepthMin: 1,                    // Minimum $ref recursion depth
  refDepthMax: 5,                    // Maximum $ref recursion depth
  refDepth: 3,                       // Set both min and max to same value

  // Date-time range
  minDateTime: "2000-01-01",
  maxDateTime: "2025-12-31",

  // Invalid types
  failOnInvalidTypes: false,         // Return default instead of throwing
  defaultInvalidTypeProduct: null,   // Value for invalid types

  // Extensions
  resolveJsonPath: true,             // Enable jsonPath cross-references
  validateSchemaVersion: true,       // Throw on unsupported $schema
  formats: {                         // Inline custom formats
    custom: (random) => "value"
  },
  refResolver: myResolver,          // Custom $ref resolver
  extensions: {                      // faker/chance instances
    faker: fakerInstance,
    chance: chanceInstance,
  }
});

Extensions (faker / chance)

Use faker or chance to generate realistic data. Works for all types:

import { faker } from "@faker-js/faker";

await generate({
  type: "object",
  properties: {
    name: { type: "string", faker: "person.fullName" },
    email: { faker: "internet.email" },
    age: { type: "integer", faker: { "number.int": [{ min: 18, max: 65 }] } },
    active: { type: "boolean", chance: "bool" },
  }
}, { extensions: { faker } });

Values are automatically cast to match the schema's type.

CLI

Install globally to use from command line:

npm install -g json-schema-faker
jsf schema.json

CLI Usage

jsf <schema.json> [options]

Arguments:

• schema.json - Path to JSON schema file (use - for stdin)

Options:

-o, --output <file>   Output file path (default: stdout)
-c, --count <n>       Generate N items as array
    --options <file>  Path to options JSON file
    --seed <n>        Random seed for deterministic output
    --max-depth <n>   Maximum recursion depth (default: 5)
    --min-items <n>   Override minItems for arrays
    --max-items <n>   Override maxItems for arrays
    --min-length <n>  Override minLength for strings
    --max-length <n>  Override maxLength for strings
    --optionals <0-1> Probability for optional properties
    --all-optionals   Include all optional properties
    --use-defaults    Use schema default values
    --use-examples    Use schema examples values
    --resolve-jsonpath Enable JSONPath resolution
    --prune <props>   Comma-separated properties to remove
    --pretty          Pretty print output (default)
    --no-pretty       Compact output

Examples:

# Generate to stdout
jsf schema.json

# Generate to file
jsf schema.json -o output.json

# Generate 10 items as array
jsf schema.json -c 10

# With seed for reproducible output
jsf schema.json --seed 42

# Include all optional properties
jsf schema.json --all-optionals

# Combine options
jsf schema.json -o output.json -c 5 --seed 42

# Read from stdin
cat schema.json | jsf -

Standalone Binaries

Download platform-specific binaries from GitHub Releases:

• jsf-linux-x64
• jsf-linux-arm64
• jsf-darwin-x64 (macOS Intel)
• jsf-darwin-arm64 (macOS Apple Silicon)
• jsf-windows-x64.exe

Development

make dev          # Run development mode (tequio-dev)
make test         # Run all tests
make test_all     # Run all tests including skipped
make typecheck    # TypeScript type checking
make build        # Build the project
make check        # Run typecheck + test
make ci           # Full CI check (typecheck + test_all + build)

License

MIT

The new implementation reuses the v0.5.x ideas but is rewritten in TypeScript for Bun with zero production dependencies.

It emphasizes a clear, typed API (generate, createGenerator, registerFormat, createRemoteResolver) and a focused runtime suitable for Node-like or Bun environments.

Migration notes for older integrations are available in MIGRATION.md.

If you rely on the original behavior or want historical reference, you can review the previous work at: https://github.com/json-schema-faker/json-schema-faker/tree/0.5.x