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

Fake your schemas!

json-schema-faker supports (currently) the JSON-Schema specification draft-04 only (?)

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,
      minimumExclusive: 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.

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.

Great, Why?

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

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

Issues

Any contribution is well received.