docs

Table of Contents

• Architecture
• Building
• Testing
• Usage

Architecture

The source code is written in modern ES6-modules through src (for testing), but bundled versions are provided to ensure portabilty:

• vendor.js required dependencies for browser usage: json-schema-ref-parser and jsonpath-plus
• bundle.js is generated containing both dependencies from above, ready for the browser!
• main.{iife,esm,cjs}.js are the bundled versions for general usage on NodeJS

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

Dependencies are not needed for generating basic types and resolving local references, so it is fine to getting started this way.

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

// 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-js/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)
• pruneProperties — Remove given properties from generated objects (default: [])
• 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 or single value from example if 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)
• refDepthMin — Set a minimum circular $ref depth to render (default: 0)
• refDepthMax — Set a maximum circular $ref depth to render (default: 3)
• 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)
• sortProperties — If true, properties will be sorted alphabetically, with false original order is kept, or null to keep them randomized (default: null)
• 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)
• replaceEmptyByRandomValue — Replace default empty value by a random value (default: false)
• omitNulls — Remove any generated null value from the resulting value (default: false)
• minDateTime — When generating a string with format date-time, set the minimum date that will get selected. If it's a number it will be the offset from now in milliseconds (default: -2524608000000)
• maxDateTime — When generating a string with format date-time, set the maximum date that will get selected. If it's a number it will be the offset from now in milliseconds (default: 1000)

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.