README
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!
Join us!
We've recently setup a gitter room for this project, if you want contribute, talk about specific issues from the library, or you need help on json-schema topics just reach us!
What's new?
A release candidate for v0.5.x
series was released in order to support local/remote reference downloading thanks to json-schema-ref-parser
, this change forced jsf
to be completely async.
var jsf = require('json-schema-faker');
var REMOTE_REF = 'https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json';
var schema = {
$ref: REMOTE_REF
};
jsf.resolve(schema).then(function(result) {
console.log(JSON.stringify(result, null, 2));
});
WIP: BREAKING CHANGES
- All code examples from previous versions (
v0.4.x
and below) will not work, however the fix is easy - All dependent tools are of course outdated and they may not work as expected, please take care of this: If you're a maintainer please upgrade your API.
Until a polished v0.5.0
version is released we encourage you to use and test around this RC, the main API will remain intact but probably option names, or subtle behaviors can be introduced.
Examples, new ideas, tips and any kind of kindly feedback is greatly appreciated.
NEW: BACKWARD COMPATIBILITY
- Since
0.5.0-rc3
we introduced ajsf.resolve()
method for full-async results. - Since
0.5.0-rc3
the methodsjsf.sync()
is REMOVED and the API forjsf()
will remain sync.
Thanks for all your feedback in advance to everyone!
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.5.0-rc1/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.
Since v0.5.x
external generators are not longer bundled with jsf, however built-in defaults are shipped for all basic types and formats.
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
}
}
};
jsf.resolve(schema).then(function(sample) {
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.5.0-rc1"
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 v4-draft 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
.
Remote en local references are automatically resolved thanks to json-schema-ref-parser
.
var schema = {
type: 'object',
properties: {
someValue: {
$ref: 'otherSchema'
}
}
};
var refs = [
{
id: 'otherSchema',
type: 'string'
}
];
jsf.resolve(schema, refs).then(function(sample) {
console.log(sample.someValue);
// "voluptatem"
});
Local references are always resolved from the process.cwd()
, of course you can specify a custom folder to look-up: jsf(schema, refs, cwd)
Faking values
jsf
has built-in generators for core-formats, Faker.js and Chance.js (and others) are also supported but they require setup:
jsf.extend('faker', function() {
return require('faker');
});
{
"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, "