Fake your schemas!

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.

Online demo

See online demo.

Install

Install json-schema-faker with npm:

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

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

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 and Chance.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);

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.

Automation: grunt plugin

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

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.

Contribution

• Alvaro Cabrera
• Tomasz Ducin

Any contribution is well received, please see contribution guide.