Customizable and hackable json-validator and json-schema utilities for traversal, data generation and validation
This package offers tools and utilities to work with json-schema, create and validate data. Unfortunately, most packages, editors or validators do not care to expose basic json-schema functionality. Instead of small memory footprint or high performance, this package focuses on exposing utilities for browser and node environments and lessens the pain to build custom tools around json-schema.
npm i json-schema-library -S
or yarn add json-schema-library
- This package is tested on node v10.16 and in latest Browsers.
- This library currently supports all draft4 features (@see benchmark)
Breaking Changes
- with version
v5.0.0
the apie has changed to es6 modules, where there is no default epxport, only named exports. Additionally all code has been rewritten to typescript. If directly accessing files, switch todist/module/*.js
-files for plain js-modules. - with version
v4.0.0
the api has changed in order to use the defined (root) schema in core as default where possible. This means, most methods have a a changed signature, wheredata
is passed before an optionalschema
argument. Check the Core Overview for the current signature - additionally
iterateSchema
has been renamed toeachSchema
for consistency
Overview
Either select an existing validator (core
) or create your own. Each Core holds all functions that are required
for the json-schema operations like validation. In order to overwrite a custom function you can either
- modify the map-objects (i.e. /lib/validation/keywords.js)
- overwrite functions or keys in the generated instance (
const instance = new Core()
) - Create a custom Core following the examples in /lib/cores
Additionally, helper functions and tools are separately exposed via CommonJS Modules. Most of them do require a core-object as parameter, but use only some of the functions defined in an core-instance.
Core
The default interface of a validator can be found in /lib/cores/CoreInterface. It exposes the following methods
method | signature | description |
---|---|---|
constructor | schema : instance | pass the root-schema in the constructor |
each | data, callback, [schema], [pointer] | Iterates over the data, passing value and its schema |
getSchema | pointer, [data], [schema] : Schema | Get the json-schema describing the data found at pointer |
getTemplate | data, [schema] : Mixed | returns a template object based of the given json-schema |
isValid | data, [schema], [pointer] : Boolean | Check if the given schema validates the data |
resolveOneOf | data, [schema], [pointer] : Schema | returns the oneOf-schema for the passed data |
resolveRef | schema : Schema | resolves a $ref on a given schema-object |
setSchema | schema | set a new (root) schema |
step | key, schema, data, [pointer] : Schema | step into a json-schema by the given key (property or index) |
validate | data, [schema], [pointer] : Array | Get a list of validation errors |
Each core holds some mapping objects, that may be modified
Core {
// keyword validations for each type, e.g. "array": ["enum", "items", "minItems", "maxItems", ...]
// for each item in the given list, the validation function in `validationKeyword` will be called
typeKeywords: {}
// keyword validation functions, e.g. validateKeyword.enum(), validateKeyword.items(), ...
validateKeyword: {}
// type validation for array, object, number, etc. Basically runs over typeKeywords and executes
// validation functions from `validateKeyword`
validateType: {}
// format validation functions. will be executed if a) typeKeywords includes 'format' and a
// validation function is set in validateFormat
validateFormat: {}
// list of error-creator functions. They receive an object with the data of the error and must
// return an object like { type: 'error', message: "" }
errors: {}
}
Examples
getSchema(core, pointer, [data], [schema])
Get the json-schema describing the
data
found atpointer
. The default json-schema-definitions can be resolved without any data as input:core.getSchema('#/article/title')
. For any dynamic values (likeoneOf
,definitions
) the data has to be passed in addition.
import { Draft04 as Core } from "json-schema-library";
const core = new Core(rootSchema);
const targetSchema = core.getSchema('#/path/to/target', rootData);
Currently may also return an error:
if (targetSchema.type === "error") {
throw new Error(targetSchema.message);
}
Or using getSchema
directly
import { Draft04 as Core } from "json-schema-library";
const core = new Core(rootSchema);
const targetSchema = getSchema(core, '#/path/to/target', rootData);
getTemplate(core, data, [schema])
Generate data which is valid to the given json-schema. Additionally, a data object may be given, which will be extended by any missing items or properties.
import { Draft04 as Core } from "json-schema-library";
const core = new Core();
const baseData = core.getTemplate(
{ other: true },
{ type: "object", properties: { target: { type: "string", default: "v" } } },
); // returns { other: true, target: "v" }
validate(core, data, [schema])
Get a list of validation errors
import { Draft04 as Core } from "json-schema-library";
const core = new Core(rootSchema);
const errors = core.validate({ validationOf: "rootSchema" });
// validation errors running data for 'rootSchema'
const customSchemaErrors = core.validate("", { type: "number" });
// returns { type: "TypeError" }
isValid(core, data, [schema])
Check if the given schema validates the data
basically core.validate("", { type: "number" }).length === 0
import { Draft04 as Core } from "json-schema-library";
const core = new Core(rootSchema);
const baseSchema = core.isValid("", { type: "number" });
// returns false
validateAsync(core, data, [options])
Asynchronous validation helper
Optional support for onError helper, which is invoked for each error (after being resolved)
import { Draft04 as Core } from "json-schema-library";
const core = new Core(rootSchema);
// signature: Core, data, { onError: [onErrorCallback], schema: JSONSchema, pointer: [Pointer]} : Promise
validateAsync(core, "", { onError: (err) => {}, schema: { type: "number" } })
.then(allErrors => {});
step(core, key, schema, data)
Get the json-schema of a child-property
import { Draft04 as Core } from "json-schema-library";
const core = new Core(rootSchema);
const baseSchema = core.step(
"target"
{ type: "object", properties: { target: { type: "string" } } },
{ target: "value" }
); // returns {type: "string"}
each(core, data, callback, [schema])
Iterates over each data-item (object, array and value); passing the value and its corresponding schema
import { Draft04 as Core } from "json-schema-library";
const core = new Core({
type: "array",
items: [
{ type: "number" },
{ type: "string" }
]
});
core.each([5, "nine"], (schema, value, pointer) => {
// 1. schema = { type: "array", items: [...] }, data = [5, "nine"], pointer = #
// 2. schema = { type: "number" }, data = 5, pointer = #/0
// 3. schema = { type: "string" }, data = "nine", pointer = #/1
});
Add custom validators
import { addValidator } from "json-schema-library";
// add a custom format 'id'
addValidator.format(core, "id", (core, schema, value, pointer) => {});
// add custom keyword 'capitalized' for type 'string'
addValidator.keyword(core, "string", "capitalized", (core, schema, value, pointer) => {});
// add a custom error (may overwrite existing errors)
addValidator.error(core, "minLengthError", (data) => ({
type: "error",
code: "custom-min-length-error",
message: "my custom error message",
data
}));
Additional helpers
getChildSchemaSelection(core, key, schema)
Returns a list of possible schemas for the given child-property or index
import { getChildSchemaSelection } from "json-schema-library";
const listOfAvailableOptions = getChildSchemaSelection(core, "childKey", schema);
createSchemaOf(data)
Creates a json-schema for the given input-data.
import { createSchemaOf } from "json-schema-library";
const baseSchema = createSchemaOf({ target: "" });
// returns {type: "object", properties: { target: "string"}},
eachSchema(schema, callback)
Iterate the schema, invoking the callback function for each type (schema) definition
import { eachSchema } from "json-schema-library";
const baseSchema = eachSchema(schema, (schema, pointer) => {});
Custom extensions
pattern
For error generation, an attribute patternExample
may be set for a pattern
validation. Instead of the regular
expression, the example will be printed in the error message.
oneOf-flag
In resolveOneOf.fuzzy.js
For an explicit oneOf resolution the schema may be extended by a oneOfProperty
-property.
This will always associate an entry with a matching value (instead of schema validation).
Example
const schema = {
oneOfProperty: "id",
oneOf: [
{ type: "object", properties: { id: { type: "string", pattern: "^1$" }, title: { type: "number" } } },
{ type: "object", properties: { id: { type: "string", pattern: "^2$" }, title: { type: "number" } } },
{ type: "object", properties: { id: { type: "string", pattern: "^3$" }, title: { type: "number" } } }
]
}
const result = resolveOneOf(core, { id: "2", title: "not a number" }, schema);
// will always return (even if invalid)
// { type: "object", properties: { id: { type: "string", pattern: "^2$" }, title: { type: "number" } } }