jsonschema

What is jsonschema?

The jsonschema npm package is a JSON Schema validator that can validate JavaScript objects using JSON Schemas. It is commonly used to ensure that data conforms to a predefined schema, and it can be used to validate data at runtime, as part of a testing suite, or during development to ensure data integrity.

What are jsonschema's main functionalities?

Validation

This feature allows you to validate a JavaScript object against a JSON Schema. The code sample creates a new Validator instance, defines a schema with required properties, and validates a sample data object against this schema. It outputs an empty array if the data is valid or a list of errors if it is invalid.

{"const Validator = require('jsonschema').Validator; const v = new Validator(); const schema = { 'type': 'object', 'properties': { 'name': { 'type': 'string' }, 'age': { 'type': 'integer', 'minimum': 0 } }, 'required': ['name', 'age'] }; const sampleData = { 'name': 'John Doe', 'age': 25 }; const validation = v.validate(sampleData, schema); console.log(validation.errors); // [] if valid, or list of errors if invalid."}

Custom Formats

This feature allows you to define custom formats for validation. The code sample shows how to add a custom format to the Validator instance and then use it in a schema to validate data.

{"const Validator = require('jsonschema').Validator; const v = new Validator(); v.customFormats.myFormat = function(input) { return input === 'specialValue'; }; const schema = { 'type': 'string', 'format': 'myFormat' }; const sampleData = 'specialValue'; const validation = v.validate(sampleData, schema); console.log(validation.valid); // true if valid, or false if invalid."}

Asynchronous Validation

This feature allows for asynchronous validation, which can be useful when dealing with complex validations that may require I/O operations. The code sample demonstrates how to perform validation asynchronously using a callback function.

{"const Validator = require('jsonschema').Validator; const v = new Validator(); const schema = { 'type': 'object', 'properties': { 'name': { 'type': 'string' }, 'age': { 'type': 'integer', 'minimum': 0 } }, 'required': ['name', 'age'] }; const sampleData = { 'name': 'John Doe', 'age': 25 }; v.validate(sampleData, schema, function(errors, valid) { console.log(valid); // true if valid, or false if invalid });"}

Other packages similar to jsonschema

ajv

Ajv is another popular JSON Schema validator that is known for its performance and being compliant with the JSON Schema specification. It supports all JSON Schema versions and includes features like compiling schemas for faster validation, adding custom keywords, and more. Compared to jsonschema, Ajv may offer better performance and more features.

tv4

Tiny Validator (tv4) is a lightweight JSON Schema validator. It supports draft v4 of the JSON Schema specification and is designed to be simple and easy to use. While it may not have as many features as jsonschema, it is a good choice for projects that require a minimalistic approach.

joi

Joi is a powerful schema description language and data validator for JavaScript. Unlike jsonschema, which uses JSON Schema format, Joi allows you to create validation schemas using a fluent API. It is often used for validating data in REST APIs and can be more intuitive to use for those who prefer a code-based schema definition over JSON.

README

jsonschema

JSON schema validator, which is designed to be fast and simple to use. The latest IETF published draft is v6, this library is mostly v4 compatible.

Contributing & bugs

Please fork the repository, make the changes in your fork and include tests. Once you're done making changes, send in a pull request.

Bug reports

Please include a test which shows why the code fails.

Usage

Simple

Simple object validation using JSON schemas.

var Validator = require('jsonschema').Validator;
var v = new Validator();
var instance = 4;
var schema = {"type": "number"};
console.log(v.validate(instance, schema));

Even simpler

var validate = require('jsonschema').validate;
console.log(validate(4, {"type": "number"}));

Complex example, with split schemas and references

var Validator = require('jsonschema').Validator;
var v = new Validator();

// Address, to be embedded on Person
var addressSchema = {
  "id": "/SimpleAddress",
  "type": "object",
  "properties": {
    "lines": {
      "type": "array",
      "items": {"type": "string"}
    },
    "zip": {"type": "string"},
    "city": {"type": "string"},
    "country": {"type": "string"}
  },
  "required": ["country"]
};

// Person
var schema = {
  "id": "/SimplePerson",
  "type": "object",
  "properties": {
    "name": {"type": "string"},
    "address": {"$ref": "/SimpleAddress"},
    "votes": {"type": "integer", "minimum": 1}
  }
};

var p = {
  "name": "Barack Obama",
  "address": {
    "lines": [ "1600 Pennsylvania Avenue Northwest" ],
    "zip": "DC 20500",
    "city": "Washington",
    "country": "USA"
  },
  "votes": "lots"
};

v.addSchema(addressSchema, '/SimpleAddress');
console.log(v.validate(p, schema));

Example for Array schema

var arraySchema = {
        "type": "array",
        "items": {
            "properties": {
                "name": { "type": "string" },
                "lastname": { "type": "string" }
            },
            "required": ["name", "lastname"]
        }
    }

For a comprehensive, annotated example illustrating all possible validation options, see examples/all.js

Features

Definitions

All schema definitions are supported, $schema is ignored.

Types

All types are supported

Formats

Disabling the format keyword.

You may disable format validation by providing disableFormat: true to the validator options.

String Formats

All formats are supported, phone numbers are expected to follow the E.123 standard.

Custom Formats

You may add your own custom format functions. Format functions accept the input being validated and return a boolean value. If the returned value is true, then validation succeeds. If the returned value is false, then validation fails.

• Formats added to Validator.prototype.customFormats do not affect previously instantiated Validators. This is to prevent validator instances from being altered once created. It is conceivable that multiple validators may be created to handle multiple schemas with different formats in a program.
• Formats added to validator.customFormats affect only that Validator instance.

Here is an example that uses custom formats:

Validator.prototype.customFormats.myFormat = function(input) {
  return input === 'myFormat';
};

var validator = new Validator();
validator.validate('myFormat', {type: 'string', format: 'myFormat'}).valid; // true
validator.validate('foo', {type: 'string', format: 'myFormat'}).valid; // false

Results

The first error found will be thrown as an Error object if options.throwError is true. Otherwise all results will be appended to the result.errors array. Each item in this array is a ValidationError with the following properties:

• property: string. Describes the property path. Starts with instance (this is configurable with the options.propertyName option), and is delimited with a dot (.).
• message: string. A human-readable message for debugging use. Provided in English and subject to change.
• schema: object. The schema containing the keyword that failed
• instance: any. The instance that failed
• name: string. The keyword within the schema that failed.
• argument: any. Provides information about the keyword that failed.

"nestedErrors" option

When oneOf or anyOf validations fail, errors that caused any of the sub-schemas referenced therein to fail are normally suppressed, because it is not necessary to fix all of them. And in the case of oneOf, it would itself be an error to fix all of the listed errors.

This behavor may be configured with options.nestedErrors. If truthy, it will emit all the errors from the subschemas. This option may be useful when troubleshooting validation errors in complex schemas:

var schema = {
  oneOf: [
    { type: 'string', minLength: 32, maxLength: 32 },
    { type: 'string', maxLength: 16 },
    { type: 'number' },
  ]
};
var validator = new Validator();
var result = validator.validate('This string is 28 chars long', schema, {nestedErrors: true});

// result.toString() reads out:
// 0: instance does not meet minimum length of 32
// 1: instance does not meet maximum length of 16
// 2: instance is not of a type(s) number
// 3: instance is not exactly one from [subschema 0],[subschema 1],[subschema 2]

Localizing Error Messages

To provide localized, human-readable errors, use the name string as a translation key. Feel free to open an issue for support relating to localizing error messages. For example:

var localized = result.errors.map(function(err){
  return localeService.translate(err.name);
});

Custom properties

Specify your own JSON Schema properties with the validator.attributes property:

validator.attributes.contains = function validateContains(instance, schema, options, ctx) {
  if(typeof instance !== 'string') return;
  if(typeof schema.contains !== 'string') throw new jsonschema.SchemaError('"contains" expects a string', schema);
  if(instance.indexOf(schema.contains)<0){
    return 'does not contain the string ' + JSON.stringify(schema.contains);
  }
}
var result = validator.validate("I am an instance", { type:"string", contains: "I am" });
// result.valid === true;

The instance passes validation if the function returns nothing. A single validation error is produced if the function returns a string. Any number of errors (maybe none at all) may be returned by passing a ValidatorResult object, which may be used like so:

  var result = new ValidatorResult(instance, schema, options, ctx);
  while(someErrorCondition()){
    result.addError('fails some validation test');
  }
  return result;

Dereferencing schemas

Sometimes you may want to download schemas from remote sources, like a database, or over HTTP. When importing a schema, unknown references are inserted into the validator.unresolvedRefs Array. Asynchronously shift elements off this array and import them:

var Validator = require('jsonschema').Validator;
var v = new Validator();
v.addSchema(initialSchema);
function importNextSchema(){
  var nextSchema = v.unresolvedRefs.shift();
  if(!nextSchema){ done(); return; }
  databaseGet(nextSchema, function(schema){
    v.addSchema(schema);
    importNextSchema();
  });
}
importNextSchema();

Default base URI

Schemas should typically have an id with an absolute, full URI. However if the schema you are using contains only relative URI references, the base option will be used to resolve these.

This following example would throw a SchemaError if the base option were unset:

var result = validate(["Name"], {
  id: "/schema.json",
  type: "array",
  items: { $ref: "http://example.com/schema.json#/definitions/item" },
  definitions: {
    item: { type: "string" },
  },
}, { base: 'http://example.com/' });

Rewrite Hook

The rewrite option lets you change the value of an instance after it has successfully been validated. This will mutate the instance passed to the validate function. This can be useful for unmarshalling data and parsing it into native instances, such as changing a string to a Date instance.

The rewrite option accepts a function with the following arguments:

• instance: any
• schema: object
• options: object
• ctx: object
• return value: any new value for the instance

The value may be removed by returning undefined. If you don't want to change the value, call return instance.

Here is an example that can convert a property expecting a date into a Date instance:

const schema = {
  properties: {
    date: {id: 'http://example.com/date', type: 'string'},
  },
};

const value = {
  date: '2020-09-30T23:39:27.060Z',
};

function unmarshall(instance, schema){
  if(schema.id === 'http://example.com/date'){
    return new Date(instance);
  }
  return instance;
}

const v = new Validator();
const res = v.validate(value, schema, {rewrite: unmarshall});

assert(res.instance.date instanceof Date);

Pre-Property Validation Hook

If some processing of properties is required prior to validation a function may be passed via the options parameter of the validate function. For example, say you needed to perform type coercion for some properties:

const coercionHook = function (instance, property, schema, options, ctx) {
  var value = instance[property];

  // Skip null and undefined
  if (value === null || typeof value == 'undefined') {
    return;
  }

  // If the schema declares a type and the property fails type validation.
  if (schema.type && this.attributes.type.call(this, instance, schema, options, ctx.makeChild(schema, property))) {
    var types = Array.isArray(schema.type) ? schema.type : [schema.type];
    var coerced = undefined;

    // Go through the declared types until we find something that we can
    // coerce the value into.
    for (var i = 0; typeof coerced == 'undefined' && i < types.length; i++) {
      // If we support coercion to this type
      if (lib.coercions[types[i]]) {
        // ...attempt it.
        coerced = lib.coercions[types[i]](value);
      }
    }
    // If we got a successful coercion we modify the property of the instance.
    if (typeof coerced != 'undefined') {
      instance[property] = coerced;
    }
  }
}.bind(validator)

// And now, to actually perform validation with the coercion hook!
v.validate(instance, schema, { preValidateProperty: coercionHook });

Skip validation of certain keywords

Use the "skipAttributes" option to skip validation of certain keywords. Provide an array of keywords to ignore.

For skipping the "format" keyword, see the disableFormat option.

Fail on unknown keywords

By default, JSON Schema is supposed to ignore unknown schema keywords.

You can change this behavior to require that all keywords used in a schema have a defined behavior, by using setting the "allowUnknownAttributes" option to false.

This example will throw a SchemaError:

var schema = {
  type: "string",
  format: "email",
  example: "foo",
};
var result = validate("Name", schema, { allowUnknownAttributes: false });

Tests

Uses JSON Schema Test Suite as well as our own tests. You'll need to update and init the git submodules:

git submodule update --init
npm test

Contributions

This library would not be possible without the valuable contributions by:

• Austin Wright

... and many others!

License

jsonschema is licensed under MIT license.

Copyright (C) 2012-2019 Tom de Grunt <[e-mail]>

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.