Use JSON Schema along with fake generators to provide consistent and meaningful fake data for your system.
We are looking for contributors! If you wanna help us make jsf
more awesome, simply write us so!
NEW in JSON Schema Faker: store schemas online!
Table of contents
- Basics
- Advanced
- Misc
Online demo
See online demo. You can save your schemas online and share the link with your collaborators.
Install
jsf
is installable through 3 different channels:
npm
Install json-schema-faker
with npm:
npm install json-schema-faker --save
bower
Install json-schema-faker
with bower:
bower install json-schema-faker --save
cdnjs
JSON-Schema-faker is also available at cdnjs.com. This means you can just include the script file into your HTML:
# remember to update the version number!
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/json-schema-faker/0.3.4/json-schema-faker.min.js"></script>
It will be fetched from the Content Delivery Network without installing any node.js package.
You can see an example JS fiddle based on jsf
loaded from cdnjs.
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:
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);
// "[object Object]"
console.log(sample.user.name);
// "John Doe"
(demo »)
jsf.version
attribute is available to check which version you're using:
var jsf = require('json-schema-faker');
console.log(jsf.version);
// "0.3.6"
More examples
- json-schema.org/example1.html: warehouse location, Product from Acme catalog
- json-schema.org/example2.html: diskDevice storage type, diskUUID storage type, nfs storage type, tmpfs storage type
Gist demos
Clone these gists and execute them locally (each gist has its own readme with instructions):
- jsf console - minimal example of jsf working directly under command line
- jsf grunt - example of jsf working under grunt.js
Automation
angular-jsf
Use angular-jsf
module (installable via npm
and bower
) to get jsf
working in your angular app out of the box! And check out angular-jsf demo.
Grunt plugin
Use grunt-jsonschema-faker
to automate running json-schema-faker
against your JSON schemas.
CLI
Use json-schema-faker-cli
to run jsf
from your command line.
Webpack loader
Use json-schema-faker-loader
to execute jsf
as a webpack loader.
JSON Schema specification support
Currently jsf
supports the JSON-Schema specification draft-04 only.
If you want to use draft-03, you may find useful information here.
Supported keywords
Below is the list of 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
anduri
-- demo »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 jsf
.
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);
// "voluptatem"
Faking values
jsf
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"
}
(demo »)
The above schema will invoke faker.internet.email()
.
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"
}
(demo »)
Advanced usage of faker.js and Chance.js
In following inline code examples the faker
and chance
variables are assumed to be created with, respectively:
var faker = require('faker');
var Chance = require('chance'),
chance = new Chance();
Another example of faking values is passing arguments to the generator:
{
"type": "string",
"chance": {
"email": {
"domain": "fake.com"
}
}
}
(demo »)
which will invoke chance.email({ "domain": "fake.com" })
.
This example works for single-parameter generator function.
However, if you pass multiple arguments to the generator function, just pass them wrapped in an array.
In the example below we use the faker.finance.amount(min, max, dec, symbol)
generator which has 4 parameters. We just wrap them with an array and it's equivalent to faker.finance.amount(100, 10000, 2, "$")
:
{
"type": "object",
"properties": {
"cash": {
"type": "string",
"faker": {
"finance.amount": [100, 10000, 2, "$"]
}
}
},
"required": [
"cash"
]
}
(demo »)
However, if you want to pass a single parameter that is an array itself, e.g.
chance.pickone(["banana", "apple", "orange"])
,
just like described here,
then you need to wrap it with an array once more (twice in total). The outer brackets determine that the content is gonna be a list of params injected into the generator. The inner brackets are just the value itself - the array we pass:
{
"type": "object",
"properties": {
"food": {
"type": "string",
"chance": {
"pickone": [
[
"banana",
"apple",
"orange"
]
]
}
}
},
"required": [
"food"
]
}
(demo »)
BREAKING CHANGES
Since
0.3.0
thefaker
andchance
dependencies aren't shipped by default, in order to use both generators you MUST install them withnpm install faker chance --save
.
Custom formats
Additionally, you can add custom generators for those:
jsf.format('semver', function(gen, schema) {
return gen.randexp('^\\d\\.\\d\\.\\d{1,2}$');
});
Now that format can be generated:
{
"type": "string",
"format": "semver"
}
Usage:
- format() — Return all registered formats (custom only)
- format(obj) — Register formats by key/value → name/callback
- format(name) — Returns that format generator (undefined if not exists)
- format(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.
Custom Options
You may define following options for jsf
that alter its behavior:
failOnInvalidTypes
: boolean - don't throw exception when invalid type passeddefaultInvalidTypeProduct
: - default value generated for a schema with invalid type (works only iffailOnInvalidTypes
is set tofalse
)maxItems
: number - Configure a maximum amount of items to generate in an array. This will override the maximum items found inside a JSON Schema.maxLength
: number - Configure a maximum length to allow generating strings for. This will override the maximum length found inside a JSON Schema.
Set options just as below:
jsf.option({
failOnInvalidTypes: false
});
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, jsf 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
Swagger extensions
jsf
supports OpenAPI Specification vendor extensions, i.e.
x-faker
property that stands forfaker
property (demo »)x-chance
property that stands forchance
property (demo »)
Thanks to it, you can use valid swagger definitions for jsf
data generation.
Bundling
JSON-Schema-faker might be used in Node.js as well as in the browser. In order to execute jsf
in a browser, you should include the distribution file from dist
directory. Each new version of jsf
is bundled using browserify and stored by the library maintainers. The bundle includes full versions of all dependencies.
However, you may want to bundle a smaller package of jsf
, because:
- you want to reduce the bundle file size
- you don't need all languages from faker.js
- you wish to use chance.js only and get rid of other dependencies
- or for any other reason...
In that case you may bundle the distribution yourself manually. It's easily achievable: just modify the
lib/util/container.js
file and either remove o rmodify therequire
calls (they're directly used by browserify to include dependencies). Automation of this feature is expected in near future.
Contribution
- Alvaro Cabrera
- Tomasz Ducin
- artwork by Ajay Karat
We are more than happy to welcome new contributors, our project is heavily developed, but we need more power :) Please see contribution guide, you can always contact us to ask how you can help.
Technical Documentation
If you want to contribute, take a look at the technical documentation page. You may find some important information there making it easier to start.
Moreover, if you find something unclear (e.g. how does something work) or would like to suggest improving the docs, please submit an issue, we'll gladly provide more info for future contributors.
Resources
- JSON, JSON Schema & JSON-schema-faker - WarsawJS meetup presentation recording, a step-by-step guide to JSON-related tools, including
jsf
Motivation
There were some existing projects or services trying to achieve similar goals as jsf
:
- 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
but they were either incomplete, outdated, broken or non-standard. That's why jsf
was created.