Mock JSON Schema

Common errors

• TypeError: mock is not a function

  cause Attempting to import `mock` as a default export when it is a named export, or using incorrect destructuring syntax in CommonJS.
  fix For ES Modules, use `import { mock } from 'mock-json-schema';`. For CommonJS, use `const { mock } = require('mock-json-schema');`. Ensure you're not trying to `import mock from 'mock-json-schema';`.

• Generated object does not match schema requirements / Property '...' is missing in mock output

  cause The generated mock data might be too generic due to missing `example` or `default` values in the schema, or the schema itself might be malformed or relying on unsupported features like `$ref` pointers.
  fix Review your JSON Schema to ensure all desired properties have explicit `example` or `default` values. Verify the schema's validity and ensure it doesn't contain `$ref` pointers, as they are not resolved by this library. For `required` fields, provide an `example` or `default` to guarantee their presence.

• Type 'number' is not assignable to type 'string' (TypeScript error)

  cause A common type mismatch when the JSON Schema defines a type (e.g., `"type": "string"`) but the provided `example` or `default` value in the schema, or a value from a generated mock, does not conform to that type.
  fix Ensure that the `example` or `default` values within your JSON Schema strictly adhere to the `type` specified for that property. For instance, if `"type": "string"`, `"example": 123` would cause a type error. Correct the schema's example/default values to match the declared type.

Warnings

• gotcha The `mock-json-schema` library currently does not support `$ref` pointers within JSON Schemas. If your schema relies on external or internal references for definitions, these will not be resolved, potentially leading to incomplete or incorrect mock objects.
  Fix: Manually inline referenced schemas or preprocess your schema to resolve `$ref` pointers (e.g., using `json-schema-ref-parser`) before passing it to `mock-json-schema`. This limitation applies to all versions up to 1.1.2.
• gotcha While `mock-json-schema` supports many JSON Schema keywords, it prioritizes `example` and `default` values. For properties where neither is provided, it generates basic type-specific defaults (e.g., `1` for number, `""` for string, `true` for boolean, `1970-01-01T00:00:00.000Z` for `date-time`). This can result in generic or less realistic data if explicit examples or defaults are not defined.
  Fix: Always provide `example` or `default` values in your JSON Schema for any properties where specific mock data is desired. Review the generated output carefully, especially for fields without explicit definitions, to ensure it meets expectations.
• gotcha This library is explicitly designed for *deterministic* output. Unlike some other mocking libraries, it does not introduce any randomness. For a given schema, `mock()` will always produce the identical object. If your use case requires varied or randomized data, `mock-json-schema` alone will not suffice.
  Fix: Use `mock-json-schema` for establishing a consistent baseline of mock data. If randomized values are needed for specific fields (e.g., in a test suite requiring unique IDs), combine its output with other data generation libraries like `faker.js` for those particular fields.

Install

• npm install mock-json-schema npm
• yarn add mock-json-schema yarn
• pnpm add mock-json-schema pnpm

Imports

• mock
  wrong:

  import mock from 'mock-json-schema';
  const mock = require('mock-json-schema').default;

  correct:

  import { mock } from 'mock-json-schema';

  The primary mocking function, `mock`, is a named export. Ensure you destructure it when importing, especially in ESM environments, to avoid undefined errors.
• mock
  wrong:

  const mock = require('mock-json-schema');

  correct:

  const { mock } = require('mock-json-schema');

  For CommonJS environments, access the `mock` function by destructuring it from the module's exports object, as it is not a default export.
• JSONSchema
  wrong:

  import { JSONSchema } from 'mock-json-schema';

  correct:

  import type { JSONSchema } from 'mock-json-schema';

  When using TypeScript, import `JSONSchema` as a type-only import (`import type`) to ensure it's removed during compilation, optimizing bundle size and preventing accidental runtime imports.

Quickstart

Demonstrates how to generate a mock object for a complex product schema, leveraging `example`, `default`, and built-in format types for deterministic output.

import { mock } from 'mock-json-schema';

const productSchema = {
  type: 'object',
  properties: {
    id: { type: 'string', format: 'uuid', example: 'a1b2c3d4-e5f6-7890-1234-567890abcdef' },
    name: { type: 'string', default: 'Example Product' },
    price: { type: 'number', minimum: 0, default: 99.99 },
    tags: {
      type: 'array',
      items: { type: 'string' },
      default: ['electronics', 'gadget']
    },
    releaseDate: { type: 'string', format: 'date-time' },
    isAvailable: { type: 'boolean', default: true }
  },
  required: ['id', 'name', 'price']
};

const exampleProduct = mock(productSchema);

console.log(exampleProduct);
/*
Expected output (or similar deterministic structure):
{
  id: 'a1b2c3d4-e5f6-7890-1234-567890abcdef',
  name: 'Example Product',
  price: 99.99,
  tags: [ 'electronics', 'gadget' ],
  releaseDate: '1970-01-01T00:00:00.000Z', // Default for date-time if no example provided
  isAvailable: true
}
*/