json-schema-faker

What is json-schema-faker?

The json-schema-faker npm package is a tool that generates fake data based on JSON Schema definitions. It is useful for testing, prototyping, and mocking APIs.

What are json-schema-faker's main functionalities?

Basic JSON Schema Support

Generates fake data based on a simple JSON Schema. The schema defines an object with 'name' and 'age' properties, and json-schema-faker generates a corresponding fake object.

const jsf = require('json-schema-faker');
const schema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    age: { type: 'integer' }
  },
  required: ['name', 'age']
};
const fakeData = jsf.generate(schema);
console.log(fakeData);

Custom Formats

Allows the creation of custom formats for generating specific types of fake data. In this example, a custom format 'customFormat' is defined to always return 'customValue'.

const jsf = require('json-schema-faker');
jsf.format('customFormat', () => 'customValue');
const schema = {
  type: 'object',
  properties: {
    customField: { type: 'string', format: 'customFormat' }
  }
};
const fakeData = jsf.generate(schema);
console.log(fakeData);

Extending with Faker.js

Integrates with Faker.js to use its extensive library of fake data generators. In this example, the schema uses Faker.js to generate a fake email address.

const jsf = require('json-schema-faker');
const faker = require('faker');
jsf.extend('faker', () => faker);
const schema = {
  type: 'object',
  properties: {
    email: { type: 'string', faker: 'internet.email' }
  }
};
const fakeData = jsf.generate(schema);
console.log(fakeData);

Other packages similar to json-schema-faker

faker

Faker.js is a popular library for generating fake data. It provides a wide range of data types and is highly customizable. Unlike json-schema-faker, it does not use JSON Schema definitions but offers a rich API for generating fake data directly.

chance

Chance.js is another library for generating random data. It is lightweight and provides a simple API for generating various types of random data. Like Faker.js, it does not use JSON Schema definitions but offers a straightforward way to generate random data.

mockaroo

Mockaroo is an online tool and API for generating fake data. It supports a wide range of data types and allows users to define schemas using a web interface. It is more user-friendly for non-developers compared to json-schema-faker.

README

Use JSON Schema along with fake generators to provide consistent fake data for your system. Note that json-schema-faker supports (currently) the JSON-Schema specification draft-04 only.

Table of contents

• Basics
  • JSON-schema-faker
  • Online demo
  • Install
  • Overview
  • Example usage
• Advanced
  • Supported keywords
  • Using references
  • Faking values
  • Custom formats
  • Extending dependencies
  • Inferred Types
  • Automation
    • Grunt plugin
• Misc
  • Resources
  • Motivation
  • Contribution

Online demo

See online demo.

Install

Install json-schema-faker with npm:

npm install json-schema-faker --save-dev

Overview

JSON-schema-faker (or jsf for short) combines two things:

• The JSON-schema specification, that defines what is the allowed content of a JSON document
• Fake data generators, that are used to generate basic or complex data, conforming to the schema. Following libraries come bundled with jsf:
  • faker.js
  • chance.js
  • randexp

Example usage

var jsf = require('json-schema-faker');

var schema = {
  type: 'object',
  properties: {
    user: {
      type: 'object',
      properties: {
        id: {
          $ref: '#/definitions/positiveInt'
        },
        name: {
          type: 'string',
          faker: 'name.findName'
        },
        email: {
          type: 'string',
          format: 'email',
          faker: 'internet.email'
        }
      },
      required: ['id', 'name', 'email']
    }
  },
  required: ['user'],
  definitions: {
    positiveInt: {
      type: 'integer',
      minimum: 0,
      exclusiveMinimum: true
    }
  }
};

var sample = jsf(schema);

console.log(sample.user.name);
// output: John Doe

Supported keywords

• $ref — Resolve internal references only, and/or external if provided.
• required — All required properties are guaranteed, if not can be omitted.
• pattern — Generate samples based on RegExp values.
• format — Core formats only: date-time, email, hostname, ipv4, ipv6 and uri.
• enum — Returns any of these enumerated values.
• minLength/maxLength — Applies length constraints to string values.
• minimum/maximum — Applies constraints to numeric values.
• exclusiveMinimum/exclusiveMaximum — Adds exclusivity for numeric values.
• multipleOf — Multiply constraints for numeric values.
• items — Support for subschema and fixed item values.
• minItems/maxItems — Adds length constraints for array items.
• uniqueItems — Applies uniqueness constraints for array items.
• additionalItems — Partially supported (?)
• allOf/oneOf/anyOf — Subschema combinators.
• properties — Object properties to be generated.
• minProperties/maxProperties — Adds length constraints for object properties.
• patternProperties — RegExp-based object properties.
• additionalProperties — Partially supported (?)
• dependencies — Not supported yet (?)
• not — Not supported yet (?)

Using references

Inline references are fully supported (json-pointers) but external can't be resolved by json-schema-faker.

In order to achieve that you can use refaker and then use the resolved schemas:

var schema = {
  type: 'object',
  properties: {
    someValue: {
      $ref: 'otherSchema'
    }
  }
};

var refs = [
  {
    id: 'otherSchema',
    type: 'string'
  }
];

var sample = jsf(schema, refs);

console.log(sample.someValue);
// output: voluptatem

Faking values

json-schema-faker has built-in generators for core-formats, Faker.js and Chance.js are also supported.

You can use faker or chance properties but they are optional:

{
  "type": "string",
  "faker": "internet.email"
}

The above schema will invoke:

require('faker').internet.email();

Another example is passing arguments to the generator:

{
  "type": "string",
  "chance": {
    "email": {
      "domain": "fake.com"
    }
  }
}

And will invoke:

var Chance = require('chance'),
  chance = new Chance();

chance.email({ "domain": "fake.com" });

If you pass an array, they will be used as raw arguments.

Note that both generators has higher precedence than format.

You can also use standard JSON Schema keywords, e.g. pattern:

{
  "type": "string",
  "pattern": "yes|no|maybe|i don't know"
}

Custom formats

Additionally, you can add custom generators for those:

jsf.formats('semver', function(gen, schema) {
  return gen.randexp('^\\d\\.\\d\\.\\d{1,2}$');
});

Now that format can be generated:

{
  "type": "string",
  "format": "semver"
}

Usage:

• formats() — Return all registered formats (custom only)
• formats(obj) — Register formats by key/value → name/callback
• formats(name) — Returns that format generator (undefined if not exists)
• formats(name, callback) — Register a custom format by name/callback

Callback:

• gen (object) — Built in generators
  • faker (object) — Faker.js instance
  • chance (object) — Chance.js instance
  • randexp (function) — Randexp generator
• schema (object) — The schema for input

Note that custom generators has lower precedence than core ones.

Extending dependencies

You may extend Faker.js:

var jsf = require('json-schema-faker');

jsf.extend('faker', function(faker){
  faker.locale = "de"; // or any other language
  faker.custom = {
    statement: function(length) {
      return faker.name.firstName() + " has " + faker.finance.amount() + " on " + faker.finance.account(length) + ".";
    }
  };
  return faker;
});

var schema = {
  "type": "string",
  "faker": {
    "custom.statement": [19]
  }
}

var sample = jsf(schema);

or if you want to use faker's individual localization packages, simply do the following:

jsf.extend('faker', function() {
  // just ignore the passed faker instance
  var faker = require('faker/locale/de');
  // do other stuff
  return faker;
});

You can also extend Chance.js, using built-in chance.mixin function:

var jsf = require('json-schema-faker');

jsf.extend('chance', function(chance){
  chance.mixin({
    'user': function() {
      return {
        first: chance.first(),
        last: chance.last(),
        email: chance.email()
      };
    }
  });

  return chance;
});

var schema = {
  "type": "string",
  "chance": "user"
}

var sample = jsf(schema);

The first parameter of extend function is the generator name (faker or chance). The second one is the function that accepts the dependency library; the function alters the library and returns it.

Inferred Types

JSON Schema does not require you to provide the type property for your JSON Schema documents and document fragments.

But since jsf uses the type property to create the proper fake data, we attempt to infer the type whenever it is not provided. We do this based on the JSON Schema validation properties you use.

Now this means that if you do not use any of the JSON Schema validation properties, json-schema-faker will not be able to infer the type for you and you will need to explicitly set your type manually.)

Below is the list of JSON Schema validation properties and the inferred type based on the property:

array

• additionalItems
• items
• maxItems
• minItems
• uniqueItems

integer (Number uses the same properties so if you need number, set your type explicitly)

• exclusiveMaximum
• exclusiveMinimum
• maximum
• minimum
• multipleOf

object

• additionalProperties
• dependencies
• maxProperties
• minProperties
• patternProperties
• properties
• required

string

• maxLength
• minLength
• pattern

Automation

Grunt plugin

Use grunt-jsonschema-faker to automate running json-schema-faker against your JSON schemas.

Resources

• JSON, JSON Schema & JSON-schema-faker - WarsawJS meetup presentation recording, a step-by-step guide to JSON-related tools, including jsf

Motivation

Actually, I've found some projects or services:

• http://www.json-generator.com/
• https://github.com/unindented/fake-json
• https://github.com/jonahkagan/schematic-ipsum
• https://www.npmjs.org/package/json-schema-mock
• https://github.com/thaume/json-schema-processor
• https://github.com/andreineculau/json-schema-random
• https://github.com/murgatroid99/json-schema-random-instance
• https://github.com/tomarad/JSON-Schema-Instantiator

Many of they are incomplete (?), so I decided to code this library.

Contribution

• Alvaro Cabrera
• Tomasz Ducin
• Jeremy Whitlock
• artwork by Ajay Karat

Any contribution is well received, please see contribution guide.