Codestin Search App

Command Line Interface

Use jsf from the command line to generate JSON data from schema files.

Installation

Install globally to use the jsf command anywhere.

npm install -g json-schema-faker

Basic Usage

Generate JSON from a schema file. Output to stdout or save to a file with -o.

# Generate to stdout
jsf schema.json

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

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

CLI Options

Control generation with command-line flags.

# Deterministic output with seed
jsf schema.json --seed 42

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

# Override array/string constraints
jsf schema.json --min-items 5 --max-length 20

# Use schema defaults and examples
jsf schema.json --use-defaults --use-examples

# Read from stdin
cat schema.json | jsf -

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

Available Flags

-o, --output <file> Output file

-c, --count <n> Array count

--options <file> Options JSON

--seed <n> Random seed

--max-depth <n> Max recursion

--min-items <n> Min array items

--max-items <n> Max array items

--min-length <n> Min string length

--max-length <n> Max string length

--optionals <0-1> Probability

--all-optionals Include all

--use-defaults Use defaults

Programmatic Usage

Import what you need using named imports:

import {
    generate,
    createGenerator,
    registerFormat,
    define,
    reset,
} from "json-schema-faker";

API

`generate(schema, options?)`

Main entry point. Returns a Promise<unknown>.

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

`createGenerator(options?)`

Creates a reusable generator with auto-incrementing seeds.

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

`registerFormat(name, generator)`

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

`createRemoteResolver(options?)`

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

import { createRemoteResolver } from 'json-schema-faker';

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

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

Available Options

Basic usage with options:

const result = await generate(schema, {
    seed: 42,
    maxDepth: 5,
    alwaysFakeOptionals: true
});

Options summary:

interface GenerateOptions {
    seed?: number;                         // Deterministic generation
    maxDepth?: number;                     // Limit nesting depth
    maxDefaultItems?: number;              // Default: 3
    optionalsProbability?: number;         // Default: 0.5
    alwaysFakeOptionals?: boolean;         // Always include optionals
    fillProperties?: boolean;              // Fill all properties
    minItems?: number;                     // Override minItems
    maxItems?: number;                     // Override maxItems
    minLength?: number;                    // Override minLength
    maxLength?: number;                    // Override maxLength
    useDefaultValue?: boolean;             // Use schema defaults
    useExamplesValue?: boolean;            // Use examples array
    formats?: Record<string, Function>;    // Custom formats
    refResolver?: RefResolver;             // Custom $ref resolver
    refDepth?: number;                     // Set both min/max
    refDepthMin?: number;                  // Minimum recursion
    refDepthMax?: number;                  // Maximum recursion
    resolveJsonPath?: boolean;             // Enable JSONPath
    extensions?: { faker?: any; chance?: any };
    minDateTime?: string;                  // ISO 8601 date
    maxDateTime?: string;                  // ISO 8601 date
    pruneProperties?: string[];            // Properties to remove
    failOnInvalidTypes?: boolean;          // Default: false
    defaultInvalidTypeProduct?: unknown;   // Fallback value
    validateSchemaVersion?: boolean;       // Check $schema
    fixedProbabilities?: boolean;          // Deterministic
    propAliases?: Record<string, string>;  // Remap schema keys
}

Seeding & Randomness

Control randomness for reproducible results.

seed

number

Seed for the random number generator to produce deterministic output. Same seed produces same results.

// Deterministic output
const r1 = await generate(schema, { seed: 12345 });
const r2 = await generate(schema, { seed: 12345 });
// r1 === r2

fixedProbabilities

boolean

Use fixed/deterministic probabilities for testing purposes. Ensures consistent test results.

const result = await generate(schema, {
    seed: 42,
    fixedProbabilities: true
});

Depth Control

Limit nested structure generation.

maxDepth

number

Maximum depth for nested object/array generation. Prevents deeply nested structures.

const schema = {
    type: 'object',
    properties: {
        child: { $ref: '#' }
    }
};

const result = await generate(schema, { maxDepth: 3 });

Array Generation

Override array constraints.

minItems

number

Override schema minItems. Forces arrays to have at least this many items.

const schema = {
    type: 'array',
    items: { type: 'string' },
    minItems: 2
};

// Override to generate at least 5 items
const result = await generate(schema, { minItems: 5 });

maxItems

number

Override schema maxItems. Caps the maximum number of array items.

const schema = {
    type: 'array',
    items: { type: 'number' },
    maxItems: 100
};

// Cap at 10 items
const result = await generate(schema, { maxItems: 10 });

maxDefaultItems

number

Maximum items for arrays without explicit length constraints. Default: 3

const result = await generate(schema, {
    maxDefaultItems: 5
});

String Generation

Override string length constraints.

minLength

number

Override schema minLength. Ensures strings are at least this long.

const schema = {
    type: 'string',
    minLength: 3
};

const result = await generate(schema, { minLength: 10 });

maxLength

number

Override schema maxLength. Caps the maximum string length.

const schema = {
    type: 'string',
    maxLength: 1000
};

const result = await generate(schema, { maxLength: 50 });

Optional Properties

Control generation of optional schema properties.

optionalsProbability

number

Probability (0-1) of generating optional properties. 0 = never, 1 = always. Default: 0.5

// 75% chance to include optionals
const result = await generate(schema, {
    optionalsProbability: 0.75
});

alwaysFakeOptionals

boolean

Always generate all optional properties regardless of probability.

const result = await generate(schema, {
    alwaysFakeOptionals: true
});

fillProperties

boolean

Fill properties beyond required. Forces all properties to be generated.

const schema = {
    type: 'object',
    properties: {
        name: { type: 'string' },
        email: { type: 'string' }
    },
    required: ['name']
};

const result = await generate(schema, { fillProperties: true });

Defaults & Examples

Use schema-defined default values and examples.

useDefaultValue

boolean

Use schema default values when generating. Properties with defaults use those values.

const schema = {
    type: 'object',
    properties: {
        status: {
            type: 'string',
            default: 'pending'
        }
    }
};

const result = await generate(schema, {
    useDefaultValue: true
});
// { status: 'pending' }

useExamplesValue

boolean

Use examples array values when generating. Picks from examples array.

const schema = {
    type: 'object',
    properties: {
        role: {
            type: 'string',
            examples: ['admin', 'user', 'guest']
        }
    }
};

const result = await generate(schema, {
    useExamplesValue: true
});
// { role: 'admin' } or 'user' or 'guest'

Custom Formats

formats

Record<string, Function>

Record of custom format name to generator function. Define your own formats for string generation.

const schema = {
    type: 'object',
    properties: {
        customId: { type: 'string', format: 'custom-id' },
        color: { type: 'string', format: 'hex-color' }
    }
};

const result = await generate(schema, {
    formats: {
        'custom-id': (random) => `ID-${random.int(1000, 9999)}`,
        'hex-color': (random) => {
            const hex = random.int(0, 16777215).toString(16);
            return '#' + hex.padStart(6, '0');
        }
    }
});

These formats are automatically available:

Format	Example Output
date-time	2024-03-15T14:30:00Z
date	2024-03-15
time	14:30:00Z
email	[email protected]
uri	https://example.com/path
hostname	host.example.com
ipv4	192.168.1.1
ipv6	2001:0db8:85a3:0000:0000:8a2e:0370:7334
uuid	550e8400-e29b-41d4-a716-446655440000
json-pointer	/users/0/name

References & Resolution

Handle $ref and external schema resolution.

refResolver

RefResolver

Custom function to resolve $ref references. Fetch from external sources or databases.

const result = await generate(schema, {
    refResolver: async (ref) => {
        if (ref.startsWith('https://')) {
            return await fetch(ref).then(r => r.json());
        }
    }
});

refDepth

number

Set both refDepthMin and refDepthMax to the same value for exact recursion levels.

// Exactly 3 levels of recursion
const result = await generate(schema, { refDepth: 3 });

refDepthMin

number

Minimum reference depth for recursive schemas. Ensures minimum recursion levels.

const result = await generate(schema, { refDepthMin: 2 });

refDepthMax

number

Maximum reference depth for recursive schemas. Prevents infinite recursion.

const result = await generate(schema, { refDepthMax: 5 });

resolveJsonPath

boolean

Enable JSONPath resolution for cross-references within generated data. Allows referencing other generated values.

const schema = {
    type: 'object',
    properties: {
        userId: { type: 'integer' },
        firstId: { type: 'integer' }
    }
};

const result = await generate(schema, {
    resolveJsonPath: true
});

External Extensions

Use Faker.js or Chance.js for generation.

extensions

object

External extensions for generating values using faker.js or chance.js. Pass instances to enable advanced data generation.

import { faker } from '@faker-js/faker';
import Chance from 'chance';

const schema = {
    type: 'object',
    properties: {
        name: { type: 'string', faker: 'person.fullName' },
        email: { type: 'string', chance: 'email' },
        avatar: { type: 'string', faker: 'image.avatar' }
    }
};

const result = await generate(schema, {
    extensions: { faker, chance: new Chance() }
});

Custom Keywords

Define custom keyword generators to extend schema processing.

define(name, callback)

function

Register a custom keyword generator. The callback receives value (keyword value from schema) and schema (full schema object). Use this to persist state across calls.

import { generate, define, reset } from 'json-schema-faker';

// Sequential counter
define('counter', function() {
    return ++this.count;
});

// Custom generator
define('uuid', function() {
    return crypto.randomUUID();
});

const schema = {
    type: 'object',
    properties: {
        id: { type: 'integer', counter: true },
        uuid: { type: 'string', uuid: true }
    }
};

const result = await generate(schema);
// { id: 1, uuid: "550e8400-e29b-41d4-a716-446655440000" }

reset(name?)

function

Clear registered keywords. Call without arguments to clear all.

// Clear specific keyword
reset('counter');

// Clear all keywords
reset();

Built-in Keywords

JSON Schema Faker includes built-in keywords for common patterns.

autoIncrement

boolean

Generate sequential integers. Use initialOffset to set the starting value.

const schema = {
    type: 'object',
    properties: {
        id: {
            type: 'integer',
            autoIncrement: true,
            initialOffset: 1000
        }
    }
};

await generate(schema); // { id: 1000 }
await generate(schema); // { id: 1001 }

template

string

String template with #{propName} placeholders resolved from sibling properties.

const schema = {
    type: 'object',
    properties: {
        firstName: { type: 'string' },
        lastName: { type: 'string' },
        fullName: {
            type: 'string',
            template: "#{firstName} #{lastName}"
        }
    }
};

Date & Time

Configure date-time format constraints.

minDateTime

string

Minimum date/time for date-time format (ISO 8601). Limits generated dates to after this timestamp.

const result = await generate(
    { type: 'string', format: 'date-time' },
    {
        minDateTime: '2020-01-01T00:00:00Z',
        maxDateTime: '2024-12-31T23:59:59Z'
    }
);

maxDateTime

string

Maximum date/time for date-time format (ISO 8601). Limits generated dates to before this timestamp.

const result = await generate(schema, {
    minDateTime: '2023-01-01T00:00:00Z',
    maxDateTime: '2025-12-31T23:59:59Z'
});

Advanced Options

Error handling, pruning, and schema validation.

pruneProperties

string[]

Remove specified properties from generated objects. Useful for filtering sensitive data.

const schema = {
    type: 'object',
    properties: {
        id: { type: 'integer' },
        name: { type: 'string' },
        password: { type: 'string' }
    }
};

const result = await generate(schema, {
    pruneProperties: ['password', 'internalNote']
});

failOnInvalidTypes

boolean

Throw error on invalid types or return default. Default: false (returns default product).

// Return default for invalid types
await generate(schema, { failOnInvalidTypes: false });

// Throw error on invalid types
await generate(schema, { failOnInvalidTypes: true });

defaultInvalidTypeProduct

unknown

Default value to return for invalid types when failOnInvalidTypes is false.

const result = await generate(schema, {
    failOnInvalidTypes: false,
    defaultInvalidTypeProduct: null
});

validateSchemaVersion

boolean

Validate that $schema is 2020-12. Throws error if unsupported version.

const schema = {
    $schema: 'https://json-schema.org/draft/2020-12/schema',
    type: 'object',
    properties: { name: { type: 'string' } }
};

const result = await generate(schema, {
    validateSchemaVersion: true
});

propAliases

Record<string, string>

Remap schema property names before processing. Useful for non-identifier extension keys (e.g. x-faker) or older Draft 04 definitions compatibility.

// Map x-faker to faker so non-identifier keys work
const result = await generate(schema, {
    propAliases: { 'x-faker': 'faker' }
});

// Support Draft 04 definitions keyword
const result2 = await generate(schema, {
    propAliases: { 'definitions': '$defs' }
});

Primitive Types

Generate basic JSON primitive values: null, boolean, string, and number types. These form the foundation of all JSON Schema data generation.

Null & Boolean

Generate null values or random boolean values. Boolean schemas produce true or false with equal probability. These are the simplest schema types and always produce predictable outputs.

// Null - always returns null
await generate({ type: "null" });
// null

// Boolean - randomly true or false
await generate({ type: "boolean" });
// true or false

String

Generate string values with various constraints. Control length, match regex patterns, use built-in formats, or create template strings that reference other properties.

Basic String & Length Constraints

Generate random alphanumeric strings. Use minLength and maxLength to control string size. Without constraints, strings default to 8 characters with mixed case letters and numbers.

// Basic string - random alphanumeric
await generate({ type: "string" });
// "aB3xK9pL2"

// Minimum length constraint
await generate({ type: "string", minLength: 10 });
// "abcdefghij"

// Maximum length constraint
await generate({ type: "string", maxLength: 5 });
// "abc"

Regex Pattern

Generate strings that match a regex pattern using an AST-based parser. The generator analyzes your pattern and produces valid matching strings. Supports character classes, quantifiers, and groups.

// Match lowercase letters only
await generate({ type: "string", pattern: "^[a-z]+$" });
// "abcdef"

// Phone number format: 3 digits, dash, 4 digits
await generate({ type: "string", pattern: "^[0-9]{3}-[0-9]{4}$" });
// "123-4567"

Format (Built-in)

Use built-in format to generate realistic data like emails, URIs, UUIDs, IP addresses, and dates. These formats produce RFC-compliant values without requiring external libraries.

// Email format - RFC 5322 compliant
await generate({ type: "string", format: "email" });
// "[email protected]"

// UUID format - RFC 4122 compliant
await generate({ type: "string", format: "uuid" });
// "550e8400-e29b-41d4-a716-446655440000"

Template Strings

Create derived values that reference other properties in the same object. Use #{propertyName} placeholders to build computed strings like full names or formatted addresses. Note: Use alwaysFakeOptionals to ensure all referenced properties are generated.

await generate({
  type: "object",
  properties: {
    firstName: { type: "string", minLength: 2 },
    lastName: { type: "string", minLength: 2 },
    fullName: { type: "string", template: "#{firstName} #{lastName}" }
  }
}, { alwaysFakeOptionals: true });
// { firstName: "Ab", lastName: "Cd", fullName: "Ab Cd" }

Numbers

Generate integer and number (float) values with constraints. Control ranges with minimum/maximum, enforce multiples, or generate negative values.

Integer

Generate whole numbers. Use minimum and maximum to define acceptable ranges. The multipleOf constraint ensures values are divisible by a specific number.

// Random integer (can be negative)
await generate({ type: "integer" });
// -456 or 123

// Bounded range: 1 to 10
await generate({ type: "integer", minimum: 1, maximum: 10 });
// 7

// Multiples of 5
await generate({ type: "integer", multipleOf: 5 });
// 15, 20, 25...

Objects

Generate JSON objects with properties. Define property schemas, mark required fields, and control which properties appear in the output.

Basic Object

Create objects with typed properties. Each property can have its own schema defining type, constraints, and format. Properties not in the required array are optional. Use alwaysFakeOptionals to include all properties.

await generate({
  type: "object",
  properties: {
    name: { type: "string" },
    age: { type: "integer" }
  }
}, { alwaysFakeOptionals: true });
// { name: "aB3xK9", age: 42 }

Required & Optional Properties

Control which properties appear using the required array. Properties not required are optional and may be omitted. Use alwaysFakeOptionals to include all properties regardless of required status.

await generate({
  type: "object",
  properties: {
    id: { type: "integer" },
    name: { type: "string" }
  },
  required: ["id", "name"]
}, { alwaysFakeOptionals: true });
// { id: 1, name: "John" }

Arrays

Generate arrays of values. Control array length, enforce unique items, or create tuples with specific item types at each position.

Basic Array

Create arrays where all items conform to a single schema. Use minItems and maxItems to control array size. Items are generated independently with random values.

await generate({
  type: "array",
  items: { type: "integer" },
  minItems: 3,
  maxItems: 5
});
// [1, 2, 3, -4, 5]

Tuple (prefixItems)

Create fixed-length arrays where each position has a specific type. Use prefixItems to define schemas for each position in order. This creates typed tuples similar to database rows.

await generate({
  type: "array",
  prefixItems: [
    { type: "string" },
    { type: "integer" },
    { type: "boolean" }
  ]
});
// ["hello", 42, true]

Composition

Combine schemas using allOf, anyOf, oneOf, and if/then/else. These powerful keywords let you build complex schemas from simpler components.

allOf, anyOf, oneOf

allOf merges all subschemas into one object. anyOf picks one subschema randomly. oneOf validates against exactly one subschema. Use these for flexible schema composition. Add alwaysFakeOptionals to include all merged properties.

// allOf - merge all properties into single object
await generate({
  allOf: [
    { type: "object", properties: { a: { type: "string" } } },
    { type: "object", properties: { b: { type: "integer" } } }
  ]
}, { alwaysFakeOptionals: true });
// { a: "hello", b: 42 }

if, then, else

Conditional schema generation. If the if schema can be satisfied, the then schema is applied. Otherwise, the else schema is used (if defined). Falls back to base schema if both branches fail.

await generate({
  type: "object",
  properties: {
    status: { enum: ["draft", "published"] },
    publishedAt: { type: "string" }
  },
  required: ["status"],
  if: { properties: { status: { const: "published" } } },
  then: { required: ["publishedAt"] },
  else: { properties: { publishedAt: { type: "null" } } }
});
// { status: "published", publishedAt: "2024-01-15T10:30:00Z" }
// OR
// { status: "draft", publishedAt: null }

References

Use $ref to reference schemas defined in $defs or definitions. This enables schema reuse, recursion, and modular schema design.

Internal $ref

Reference schemas defined in $defs (or definitions) using JSON Pointer syntax. The $ref is resolved and replaced with the referenced schema. Use this for reusable type definitions and recursive structures. Add alwaysFakeOptionals to include all properties in referenced schemas.

await generate({
  type: "object",
  properties: {
    person: { $ref: "#/$defs/Person" }
  },
  $defs: {
    Person: {
      type: "object",
      properties: {
        name: { type: "string" },
        age: { type: "integer" }
      }
    }
  }
}, { alwaysFakeOptionals: true });
// { person: { name: "Ab", age: 42 } }

Extensions (faker/chance)

Integrate @faker-js/faker or chance for realistic test data. Add the faker or chance keyword to your schema with a method path to generate contextual data.

Using faker

Pass a faker instance via extensions option. Then use the faker keyword in schemas with dot-notation method paths like 'person.fullName' or 'internet.email'. Supports all faker methods for localized, realistic data.

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

// Generate realistic names
await generate({
  faker: "person.fullName"
}, { extensions: { faker } });
// "John Doe"

// Generate realistic emails
await generate({
  faker: "internet.email"
}, { extensions: { faker } });
// "[email protected]"

Custom Formats

Define your own format generators for domain-specific data like phone numbers, IDs, or codes. Custom formats receive a random instance for generating values.

Inline Custom Formats

Pass custom format generators via the formats option. Each generator receives a random object with methods like int(), pick(), and bool() for generating deterministic random values.

await generate({
  type: "string",
  format: "phone"
}, {
  formats: {
    phone: (random) => `+1-${random.int(200, 999)}-${random.int(1000000, 9999999)}`
  }
});
// "+1-555-1234567"

Advanced Features

Advanced capabilities including default values, examples array, JSONPath cross-references, and more for sophisticated data generation scenarios.

Default Values & Examples

Use schema-defined default values with useDefaultValue option. Properties with a default keyword will use that value instead of generating random data. Similarly, useExamplesValue picks from the examples array. Add alwaysFakeOptionals to ensure the property is included.

await generate({
  type: "object",
  properties: {
    name: { type: "string", default: "Anonymous" }
  }
}, { useDefaultValue: true, alwaysFakeOptionals: true });
// { name: "Anonymous" }

JSONPath Resolution

Enable JSONPath resolution to reference values elsewhere in the generated output. Add a jsonPath property to your schema to create derived properties that reference sibling or nested values dynamically.

await generate({
  type: "object",
  properties: {
    users: {
      type: "array",
      items: { type: "object", properties: { id: { type: "integer" } } },
      minItems: 2
    },
    firstUserId: {
      type: "integer",
      jsonPath: "$.users[0].id"
    }
  }
}, {
  resolveJsonPath: true,
  alwaysFakeOptionals: true
});
// { users: [{id: 123}, {id: 456}], firstUserId: 123 }

Schema Input

Generated Output

Ready

Randomness

Seed

Fixed probabilities

Depth

Max depth

Ref depth min

Ref depth max

Arrays

Min items

Max items

Default items

Strings

Min length

Max length

Properties

Optionals prob.

Always fake optionals

Fill properties

Values

Use examples array

Use default value

Date / Time

Min date-time

Max date-time

Advanced

Prune properties

Resolve JSON path

Fail on invalid types

Validate schema version

Prop aliases

GitHub Gist

Token

Generate a PAT with gist scope

Fake Your JSON Schemas

Simple, Powerful API

Everything You Need

JSON Schema Support

Extension Support

Custom Generators

$ref Support

Zero Dependencies

Regex Patterns

Ready to Get Started?

On this page

Contents

Command Line Interface

Installation

Basic Usage

CLI Options

Available Flags

Programmatic Usage

API

generate(schema, options?)

createGenerator(options?)

registerFormat(name, generator)

createRemoteResolver(options?)

Available Options

Seeding & Randomness

seed

fixedProbabilities

Depth Control

maxDepth

Array Generation

minItems

maxItems

maxDefaultItems

String Generation

minLength

maxLength

Optional Properties

optionalsProbability

alwaysFakeOptionals

fillProperties

Defaults & Examples

useDefaultValue

useExamplesValue

Custom Formats

formats

References & Resolution

refResolver

refDepth

refDepthMin

refDepthMax

resolveJsonPath

External Extensions

extensions

Custom Keywords

define(name, callback)

reset(name?)

Built-in Keywords

autoIncrement

template

Date & Time

minDateTime

maxDateTime

Advanced Options

pruneProperties

failOnInvalidTypes

defaultInvalidTypeProduct

validateSchemaVersion

propAliases

On this page

On this page

Primitive Types

Null & Boolean

String

Basic String & Length Constraints

Regex Pattern

Format (Built-in)

Template Strings

Numbers

Integer

Objects

Fake Your
JSON Schemas

`generate(schema, options?)`

`createGenerator(options?)`

`registerFormat(name, generator)`

`createRemoteResolver(options?)`