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.
- 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.
Thanks for all your feedback in advance to everyone!
# Table of contents
...
...
@@ -82,7 +105,7 @@ Install `json-schema-faker` with bower:
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:
@@ -234,7 +256,7 @@ Below is the list of supported keywords:
Inline references are fully supported (json-pointers) but external can't be resolved by `jsf`.
In order to achieve that you can use [refaker](https://github.com/json-schema-faker/refaker) and then use the resolved schemas:
Remote en local references are automatically resolved thanks to `json-schema-ref-parser`.
```javascript
varschema={
...
...
@@ -253,17 +275,23 @@ var refs = [
}
];
varsample=jsf(schema,refs);
console.log(sample.someValue);
// "voluptatem"
jsf(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](https://github.com/marak/Faker.js/) and [Chance.js](http://chancejs.com/) are also supported.
`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:
You can use **faker** or **chance** properties but they are optional:
```js
jsf.extend('faker',function(){
returnrequire('faker');
});
```
```json
{
...
...
@@ -366,18 +394,13 @@ then you need to wrap it with an array once more (twice in total). The outer bra
> Since `0.3.0` the `faker` and `chance` dependencies aren't shipped by default,
> in order to use both generators you MUST install them with `npm install faker chance --save`.
## Custom formats
Additionally, you can add custom generators for those:
```javascript
jsf.format('semver',function(gen,schema){
returngen.randexp('^\\d\\.\\d\\.\\d{1,2}$');
jsf.format('semver',function(){
returnjsf.utils.randexp('\\d\\.\\d\\.[1-9]\\d?');
});
```
...
...
@@ -399,10 +422,6 @@ Usage:
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.
...
...
@@ -431,7 +450,9 @@ You may extend [Faker.js](http://marak.com/faker.js/):
```javascript
varjsf=require('json-schema-faker');
jsf.extend('faker',function(faker){
jsf.extend('faker',function(){
varfaker=require('faker');
faker.locale="de";// or any other language
faker.custom={
statement:function(length){
...
...
@@ -448,7 +469,7 @@ var schema = {
}
}
varsample=jsf(schema);
jsf(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:
...
...
@@ -467,7 +488,10 @@ You can also extend [Chance.js](http://chancejs.com/), using built-in [chance.mi
```javascript
varjsf=require('json-schema-faker');
jsf.extend('chance',function(chance){
jsf.extend('chance',function(){
varChance=require('chance');
varchance=newChance();
chance.mixin({
'user':function(){
return{
...
...
@@ -486,10 +510,10 @@ var schema = {
"chance":"user"
}
varsample=jsf(schema);
jsf(schema).then(...);
```
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**.
The first parameter of `extend` function is the generator name (`faker`,`chance`, etc.). The second one is the function that **must return** the dependency library.
## Inferred Types
...
...
@@ -544,14 +568,9 @@ 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 [browserify](http://browserify.org/) and stored by the library maintainers. The bundle includes full versions of all dependencies.
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.
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`](lib/util/container.js) file and either remove o rmodify the `require` calls (they're directly used by browserify to include dependencies). Automation of this feature is expected in near future.
From `v0.5.x` and beyond we'll not longer bundle external generators, locales and such due the unnecessary waste of time and space.
## Contribution
...
...
@@ -586,5 +605,3 @@ There were some existing projects or services trying to achieve similar goals as