json-schema-shorthand

JSON Schema is a useful beast, but its schema definition can be a little bit more long-winded than necessary. This module allows to use a few shortcuts that will be expanded into their canonical form.

WARNING: the module is still very young, and there are plenty of properties this module should expand and does not. So don't trust it blindly. If you hit such a case, raise a ticket and I'll refine the process.

To install

npm install json-schema-shorthand

Typical use

import shorthand, { object, array } from 'json-schema-shorthand';

let schema = object({
    foo: 'number',
    bar: array('string'),
});

// schema === {
//    type: 'object',
//    properties: {
//        foo: { type: 'number' },
//        bar: { type: 'array', items: { type: 'string' } }
//    }
// }

Functions

The schemaParts that most of those functions take is a list of simple arrays that will be merged together to form the final schema (which will be then expanded via shorthand(). If a schemaParts item is a string, it'll be expanded as a description attribute.

For example:

object({ foo: 'number' }, "a thing", { minProperties: 3 } )

// => {
//    type: "object",
//    properties: { foo: { type: "number" } },
//    description: "a thing",
//    minProperties: 3
// }

Also, under the hood the merging of all the schemaParts is done via updeep, so you could potentially do funkier things than just pass litteral values to it. Just sayin'.

`shorthand( schema )`

The default export of json-schema-shorthand. Takes in a data structure and expands any shorthand (see next section) found in it. Note that because json-schema-shorthand is using updeep internally, the returned schema is frozen.

`number( ...schemaParts )`

let schema = number({ maximum: 5 });
// => { type: 'number', maximum: 5 }

Expands into a number type.

`integer( ...schemaParts )`

let schema = integer({ maximum: 5 });
// => { type: 'integer', maximum: 5 }

Expands into a integer type.

`string( ...schemaParts )`

let schema = string({ maxLength: 5 });
// => { type: 'string', maxLength: 5 }

Expands into a string type.

`array( itemsSchema, ...schemaParts )`

let schema = array('number', { maxItems: 5 });
// => { type: 'array', items: { type: 'number' }, maxItems: 5 }

Expands into an array type.

`object( properties, ...schemaParts )`

let schema = object({ foo: 'string!' }, { description: "yadah" });
// => { type: 'object', 
//      properties: { foo: { type: 'string' } }, 
//      required: [ 'foo' ],
//      description: "yadah" }

Expands into an object type.

`add_definition( name, ...schemaParts )`

If using Babel and babel-plugin-transform-function-bind:

import { add_definition, object } from 'json-schema-shorthand';

let definitions = {};
let thingy = definitions::add_definition( 'thingy', 'string' );
// thingy === { '$ref': '#/definitions/thingy' }

let schema = object({
    foo: thingy
}, {
    definitions,
});
// ==> {
//    definitions: { thingy: { type: 'string' } },
//    type: 'object',
//    properties: {
//        foo: { '$ref': '#/definitions/thingy },
//    }
//}

Using good ol' bind():

import { add_definition, object } from 'json-schema-shorthand';

let definitions = {};
const add_def = add_definition.bind(definitions);

let thingy = add_def( 'thingy', 'string' );

let schema = object({
    foo: thingy
}, {
    definitions,
});

In both versions, add_definition will add the provided definition to its context (with all shorthands expanded, natch) and return its related schema pointer so that, if assigned to a variable, it can be used as a type shortcut.

Shorthands

Types as string

If a string type is encountered where a property definition is expected, the string is expanded to the object { "type": type }.

{
    "foo": "number",
    "bar": "string"
}

expands to

{
    "foo": { "type": "number" },
    "bar": { "type": "string" }
}

If the string begins with a #, the type is assumed to be a local reference and #type is expanded to { "$ref": type }.

{ "foo": "#/definitions/bar" }

becomes

{ "foo": { "$ref": "#/definitions/bar" } }

If the string begins with a $, the type is assumed to be a general reference and $type is expanded to { "$ref": type }.

{ "foo": "$http://foo.com/bar" }

becomes

{ "foo": { "$ref": "http://foo.com/bar" } }

`object` property

{ object: properties } expands to { type: "object", properties }.

shorthand                              expanded
------------------------               ---------------------------
foo: {                                  foo: {
    object: {                               type: "object",
        bar: { }                            properties: {
    }                                           bar: { }
}                                           }
                                        }

`array` property

{ array: items } expands to { type: "array", items }.

shorthand                              expanded
------------------------               ---------------------------
foo: {                                  foo: {
    array: 'number'                         type: "array",
}                                           items: {
                                                type: 'number' 
                                            }
                                        }

`required` property

If the required attribute is set to true for a property, it is bubbled up to the required attribute of its parent object.

shorthand                              expanded
------------------------               ---------------------------

foo: {                                  foo: {
    properties: {                           required: [ 'bar' ],
      bar: { required: true },              properties: { 
      baz: { }                                bar: {},
    }                                         baz: {}
}                                       }

The type or $ref of a field can also be appended a ! to mark it as required.

shorthand                              expanded
------------------------               ---------------------------

foo: {                                  foo: {
    properties: {                           required: [ 'bar', 'baz' ],
      bar: 'number!'                        properties: { 
      baz: '#baz_type!'                       bar: {   type: 'number' },
    }                                         baz: { '$ref': '#baz_type' }
}                                       }

`range` property

Shortcut to set minimum and maximum in a single array. Two boolean values can also be provided to specify if the extrema are inclusive (true by default).

shorthand                              expanded
------------------------               ---------------------------

foo: {                                  foo: {
    type: 'number',                         type: 'number',
    range: [ 5, 8, true, false ]             minimum: 5,
}                                            exclusiveMaximum: 8,
                                        }

npm