See [online demo](http://json-schema-faker.js.org/). 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](https://www.cdnjs.com/libraries/json-schema-faker). This means you can just include the script file into your HTML:
Clone these gists and execute them locally (each gist has its own readme with instructions):
*[jsf console](https://gist.github.com/ducin/9f2364ccde2e9248fbcd) - minimal example of jsf working directly under command line
*[jsf grunt](https://gist.github.com/ducin/87e0b55bddd1801d3d99) - example of jsf working under grunt.js
## Automation
## Automation
> Notice these tools can be outdated, please open a PR for helping them or raise and issue in their respective repositories.
### angular-jsf
### angular-jsf
Use [`angular-jsf`](https://github.com/json-schema-faker/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](http://angular-jsf.js.org/).
Use [`angular-jsf`](https://github.com/json-schema-faker/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](http://angular-jsf.js.org/).
...
@@ -168,12 +117,14 @@ to run `jsf` from your command line.
...
@@ -168,12 +117,14 @@ to run `jsf` from your command line.
Use [json-schema-faker-loader](https://github.com/jeffcatania/json-schema-faker-loader)
Use [json-schema-faker-loader](https://github.com/jeffcatania/json-schema-faker-loader)
to execute `jsf` as a [webpack](https://webpack.github.io/) loader.
to execute `jsf` as a [webpack](https://webpack.github.io/) loader.
## JSONSchema specification support
## JSON-Schema specification support
Currently `jsf` supports the JSON-Schema specification **draft-04** only.
Currently `jsf` supports the JSON-Schema specification **draft-04** only.
If you want to use **draft-03**, you may find useful information [here](https://github.com/json-schema-faker/json-schema-faker/issues/66).
If you want to use **draft-03**, you may find useful information [here](https://github.com/json-schema-faker/json-schema-faker/issues/66).
> There are [plans to support](https://github.com/json-schema-faker/json-schema-faker/issues/289) latest `draft-06` and `draft-07` but currently is out of scope until a stable `0.5.x` API is released.
## Supported keywords
## Supported keywords
Below is the list of supported keywords:
Below is the list of supported keywords:
...
@@ -206,6 +157,8 @@ Below is the list of supported keywords:
...
@@ -206,6 +157,8 @@ Below is the list of supported keywords:
-`dependencies`— Not supported yet (?)
-`dependencies`— Not supported yet (?)
-`not`— Not supported yet (?)
-`not`— Not supported yet (?)
> Notice `not` support is complex to achieve and is probably will not work as you expected, most opened issues are related to that: so any feedback there is very appreaciated!
## Using references
## Using references
Inline references are fully supported (json-pointers) but external can't be resolved by `jsf`.
Inline references are fully supported (json-pointers) but external can't be resolved by `jsf`.
...
@@ -213,7 +166,7 @@ Inline references are fully supported (json-pointers) but external can't be reso
...
@@ -213,7 +166,7 @@ Inline references are fully supported (json-pointers) but external can't be reso
Remote en local references are automatically resolved thanks to `json-schema-ref-parser`.
Remote en local references are automatically resolved thanks to `json-schema-ref-parser`.
```javascript
```javascript
varschema={
constschema={
type:'object',
type:'object',
properties:{
properties:{
someValue:{
someValue:{
...
@@ -222,29 +175,27 @@ var schema = {
...
@@ -222,29 +175,27 @@ var schema = {
}
}
};
};
varrefs=[
constrefs=[
{
{
id:'otherSchema',
id:'otherSchema',
type:'string'
type:'string'
}
}
];
];
jsf.resolve(schema,refs).then(function(sample){
jsf.resolve(schema,refs).then(sample=>{
console.log(sample.someValue);
console.log(sample.someValue);
// "voluptatem"
// "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)`
> Local references are always resolved from the `process.cwd()`, of course you can specify a custom folder to look-up: `jsf.resolve(schema, refs, cwd)`
## Faking values
## Faking values
`jsf` has built-in generators for core-formats, [Faker.js](https://github.com/marak/Faker.js/) and [Chance.js](http://chancejs.com/)(and others) are also supported but they require setup:
`jsf` has built-in generators for core-formats, [Faker.js](https://github.com/marak/Faker.js/) and [Chance.js](http://chancejs.com/)(and others) are also supported but they require setup:
```js
```js
jsf.extend('faker',function(){
jsf.extend('faker',()=>require('faker'));
returnrequire('faker');
});
```
```
```json
```json
...
@@ -274,13 +225,14 @@ You can also use standard JSON Schema keywords, e.g. `pattern`:
...
@@ -274,13 +225,14 @@ You can also use standard JSON Schema keywords, e.g. `pattern`:
In following inline code examples the `faker` and `chance` variables are assumed to be created with, respectively:
In following inline code examples the `faker` and `chance` variables are assumed to be created with, respectively:
```javascript
```javascript
varfaker=require('faker');
importfakerfrom'faker';
importChancefrom'chance';
varChance=require('chance'),
jsf.extend('faker',()=>faker);
chance=newChance();
jsf.extend('chance',()=>newChance());
```
```
Another example of faking values is passing arguments to the generator:
E.g. using `chance` to faking values while passing arguments to the generator:
```json
```json
{
{
...
@@ -294,7 +246,7 @@ Another example of faking values is passing arguments to the generator:
...
@@ -294,7 +246,7 @@ Another example of faking values is passing arguments to the generator:
which will invoke [`chance.email({ "domain": "fake.com" })`](https://github.com/chancejs/chancejs/blob/b4c143bf53f516dfd77a8376d0f631462458c062/chance.js#L1118).
...which will invoke [`chance.email({ "domain": "fake.com" })`](https://github.com/chancejs/chancejs/blob/b4c143bf53f516dfd77a8376d0f631462458c062/chance.js#L1118).
This example works for single-parameter generator function.
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.
However, if you pass multiple arguments to the generator function, just pass them wrapped in an array.
...
@@ -353,9 +305,7 @@ then you need to wrap it with an array once more (twice in total). The outer bra
...
@@ -353,9 +305,7 @@ then you need to wrap it with an array once more (twice in total). The outer bra
Additionally, you can add custom generators for those:
Additionally, you can add custom generators for those:
-**format(name)**— Returns that format generator (undefined if not exists)
-**format(name)**— Returns that format generator (undefined if not exists)
-**format(name, callback)**— Register a custom format by name/callback
-**format(name, callback)**— Register a custom format by name/callback
> If you provide `null` as callback the format will be unregistered, the same if you pass `null` as the name: all added formats will be unregistered too.
Callback:
Callback:
-**schema** (object) — The schema for input
-**schema** (object) — The schema for input
...
@@ -384,43 +336,34 @@ Note that custom generators has lower precedence than core ones.
...
@@ -384,43 +336,34 @@ Note that custom generators has lower precedence than core ones.
You may define following options for `jsf` that alter its behavior:
You may define following options for `jsf` that alter its behavior:
-`failOnInvalidTypes`: boolean - don't throw exception when invalid type passed
-`defaultInvalidTypeProduct`: - default value generated for a schema with invalid type (works only if `failOnInvalidTypes` is set to `false`)
-`failOnInvalidFormat`: boolean - don't throw exception when invalid format passed
-`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.
-`random`: Function - a replacement for `Math.random` to support pseudorandom number generation.
-`alwaysFakeOptionals`: boolean - When true, all object-properties will be generated regardless they're `required` or not.
-`optionalsProbability`: number - A decimal number from 0 to 1 that indicates the probability to fake a non-required object property (default: 0). When `0.0`, only `required` properties will be generated; when `1.0`, all properties are generated. This option is overwritten to 1 when `alwaysFakeOptionals = true`.
Set options just as below:
```javascript
```javascript
jsf.option({
jsf.option({
failOnInvalidTypes:false
failOnInvalidTypes:false
});
});
```
```
> Please read the [available options here](./#available-options).
## Extending dependencies
## Extending dependencies
You may extend [Faker.js](http://marak.com/faker.js/):
You may extend [Faker.js](http://marak.com/faker.js/):
```javascript
```javascript
varjsf=require('json-schema-faker');
importjsffrom'json-schema-faker';
jsf.extend('faker',function(){
jsf.extend('faker',()=>{
varfaker=require('faker');
constfaker=require('faker');
faker.locale="de";// or any other language
faker.locale='de';// or any other language
faker.custom={
faker.custom={
statement:function(length){
statement:length=>{
returnfaker.name.firstName()+" has "+faker.finance.amount()+" on "+faker.finance.account(length)+".";
returnfaker.name.firstName()+" has "+faker.finance.amount()+" on "+faker.finance.account(length)+".";
}
}
};
};
returnfaker;
returnfaker;
});
});
varschema={
constschema={
"type":"string",
"type":"string",
"faker":{
"faker":{
"custom.statement":[19]
"custom.statement":[19]
...
@@ -430,12 +373,12 @@ var schema = {
...
@@ -430,12 +373,12 @@ var schema = {
jsf.resolve(schema).then(...);
jsf.resolve(schema).then(...);
```
```
or if you want to use [faker's *individual localization packages*](https://github.com/Marak/faker.js#individual-localization-packages), simply do the following:
...or if you want to use [faker's *individual localization packages*](https://github.com/Marak/faker.js#individual-localization-packages), simply do the following:
@@ -483,52 +426,11 @@ But since `jsf` uses the `type` property to create the proper fake data, we atte
...
@@ -483,52 +426,11 @@ But since `jsf` uses the `type` property to create the proper fake data, we atte
Below is the list of JSON Schema validation properties and the inferred type based on the property:
Below is the list of JSON Schema validation properties and the inferred type based on the property:
**array**
-**array**—`additionalItems`, `items`, `maxItems`, `minItems` and `uniqueItems`
-**integer**—`exclusiveMaximum`, `exclusiveMinimum`, `maximum`, `minimum` and `multipleOf`
*`additionalItems`
-**number**— same as above
*`items`
-**object**—`additionalProperties`, `dependencies`, `maxProperties`, `minProperties`, `patternProperties`, `properties` and `required`
*`maxItems`
-**string**—`maxLength`, `minLength` and `pattern`
*`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*](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#vendorExtensions), i.e.
*`x-faker` property that stands for `faker` property ([demo »](http://json-schema-faker.js.org/#gist/7cdf200c27eceb6163a79fbc50813fcb))
*`x-chance` property that stands for `chance` property ([demo »](http://json-schema-faker.js.org/#gist/c0084695b4ca1c4cd015ded1f5c6dc33))
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`](dist) directory. Each new version of `jsf` is bundled using [Rollup.js](http://rollupjs.org/) and stored by the library maintainers. The bundle includes full versions of all dependencies.
> From `v0.5.x` and beyond we'll not longer bundle external generators, locales and such due the unnecessary waste of time and space.