Table of Contents

• Architecture
• Building
• Testing
• Usage

Architecture

The source code is intended to be available through src (for testing), but bundled versions are provided to ensure portabilty:

• Both cjs and es modules are exported for NodeJS and modern Javascript environments respectively
• Standard .js and .min.js are emitted for browser usage, they're exported as umd without dependencies (json-schema-ref-parser and jsonpath)
• Also a single .bundle.min.js is generated containing both dependencies from above, also as umd

Generated sources are available as an NPM dependency and through UNPKG.

import jsf from 'json-schema-faker';

Let's examine how the library works:

// 1.0 - first, we need a working (and valid) `schema`
const schema = {
  type: 'string',
};

// 1.1 - optionally, you can provide used `refs`
const refs = [
  {
    id: 'Test',
    type: 'boolean',
  }
];

// 1.2 - additionally, you can provide a `cwd` for local references
const cwd = `${__dirname}/schema`;

Note that:

• 1.0 — All input MUST be valid JSON-Schema
• 1.1 — Given refs are also valid JSON-Schema
• 1.2 — Given cwd is needed only if relative paths are used

Now we can produce values from our previous settings:

// 2.0 - generate a sample from the given `schema`
const syncValue = jsf.generate(schema, refs);

// 2.1 - resolve and generate complex schemas with remote references
const asyncValue = await jsf.resolve(schema, refs, cwd);

The core provides typed generators for all basic types and well-known formats.

• 2.0 — Built-in generators can be resolved synchronously
• 2.1 — Local and remote references are resolved asynchronously

For more specific values jsf offers a rich menu of options and methods:

// 3.0 - custom formats are supported
jsf.format('name', callback);
jsf.format('name', null); // unregister `name` format

// 3.1 - define `jsf` settings
jsf.option('optionName', 'value');
jsf.option({ optionName: 'value' });

// 3.2 - the `version` is also exported
jsf.version; // 0.5.0-rc16

// 3.3 - internal `random` generators
jsf.random; // { pick, date, shuffle, number, randexp }

// 3.4 - extend keywords with external generators
jsf.extend('chance', () => require('chance'));
jsf.extend('faker', () => require('faker'));

// 3.5 - extend keywords with custom generators
jsf.define('myProp', (value, schema) => schema);

// 3.6 - unregister extensions by keyword
jsf.reset('myProp');
jsf.reset(); // clear extensions

// 3.7 - retrieve registered extensions by keyword
jsf.locate('faker');

• 3.0 — This method should register non supported formats
• 3.1 — You should be able to setup custom behavior or defaults, etc.
• 3.2 — As convenience the package version should be exported
• 3.3 — Helpers should be shared too, to be used outside the API
• 3.4 — Third-party generators should be setup through this method (dependencies)
• 3.5 — Custom keywords like autoIncrement and pattern should be setup through this method (extensions) and stored in a shared container
• 3.6 — Added dependencies and extensions should be cleared from the container through this method, if no name is given the the entire container should be reset
• 3.7 — Any registered third-party generator should be returned through this method

Available options

• defaultInvalidTypeProduct — If failOnInvalidTypes is disabled this value will be returned on any invalid type given (default: null)
• defaultRandExpMax — Setup default value directly as RandExp.prototype.max (default: 10)
• ignoreProperties — Skip given properties from being generated (default: [])
• ignoreMissingRefs — If enabled, it will resolve to {} for unknown references (default: false)
• failOnInvalidTypes — If enabled, it will throw an Error for unknown types (default: true)
• failOnInvalidFormat — If enabled, it will throw an Error for unknown formats (default: true)
• alwaysFakeOptionals — When enabled, it will set optionalsProbability: 1.0 and fixedProbabilities: true (default: false)
• optionalsProbability — A value from 0.0 to 1.0 to generate values in a consistent way, e.g. 0.5 will generate from 0% to 50% of values. Using arrays it means items, on objects they're properties, etc. (default: false)
• fixedProbabilities — If enabled, then optionalsProbability: 0.5 will always generate the half of values (default: false)
• useExamplesValue — If enabled, it will return a random value from examples if they're present (default: false)
• useDefaultValue — If enabled, it will return the default value if present (default: false)
• requiredOnly — If enabled, only required properties will be generated (default: false)
• minItems — Override minItems if it's less than this value (default: 0)
• maxItems — Override maxItems if it's greater than this value (default: null)
• minLength — Override minLength if it's less than this value (default: 0)
• maxLength — Override maxLength if it's greater than this value (default: null)
• resolveJsonPath — If enabled, it will expand jsonPath keywords on all generated objects (default: false)
• reuseProperties — If enabled, it will try to generate missing properties from existing ones. Only when fillProperties is enabled too (default: false)
• fillProperties — If enabled, it will try to generate missing properties to fulfill the schema definition (default: true)
• random — Setup a custom randonmess generator, useful for getting deterministic results (default: Math.random)

Building

JSON-Schema-Faker is a JavaScript tool that can be executed both in the browser and the server.

It's built with bili, as we're using ES6 syntax for the source code and modules.

To generate dist/ sources run:

$ npm run build

Testing

Unit tests are run with mocha -r esm in order to use ES6 modules syntax, allowing to import and test code directly from the src folder.

Also we include "schema tests" to ensure generated data is also valid.

See our reference guide to learn how.

Usage

Use the website tool and generate some values right now.

Please read our guide for further usage instructions.