json-gate validates JSON objects against a JSON schema.
In other words, it makes sure an object conforms to the type and structure that your code expects.
For example, a server can use it to ensure input received from a client conforms to the API.
The JSON schema can also help with documentation and collaboration.
Copy it to your API document and everybody should understand exactly what is expected.
json-gate likes you! It is...
Intuitive - API is super easy to use.
Produces human-friendly, detailed error messages - for both you and your customers.
Fast - Your CPU won't have time to blink.
Well documented, in case you don't feel like digging into the IETF specifications.
Just keep reading, it's all here.
Conforms to standard - no relearning, no obligation, no surprises.
Both synchronous and asynchronous modes - your choice.
What's a JSON schema?
JSON Schema is a proposed Internet draft defining a JSON media type (application/schema+json) with the following goals:
Validation - You can use JSON Schema to validate your JSON data.
Documentation - You can extract documentation information from a JSON Schema, match this documentation to your data, and use that information for user interaction.
Hyperlinking - You can pair your JSON data with the defining JSON Schema to build hyperlinks into parts of that JSON data.
supports most of , minus the hyperlinking and hyper schema parts.
This schema is explained below in the Hello, schema section.
Installation
$ npm install json-gate
Usage
json-gate.createSchema(jsonSchema)
This function gets a JSON Schema definition and returns a new Schema object.
It verifies that the schema is valid.
If the latter is malformed an error will be thrown pinpointing the problem.
Schema.validate(jsonObject)
This function gets a JSON object and validates it against the schema.
If the JSON object does not conform to the schema an error will be thrown (or returned, see Synchronous/Asynchronous below).
The function stops after encountering an error. It does not return multiple errors.
The function does not return a value.
Be aware that the input JSON object may be edited in-place if the default attribute is used.
Errors
The error messages are human-friendly and detailed.
For example: "JSON object property 'user.password': length is 3 when it should be at least 6".
Ready to be shrink-wrapped in a 400 Bad Request response and shipped to the client!
Equaly helpful error messages are produced in the case of a malformed schema, to assist you during development.
For example: "Schema property 'num': 'exclusiveMaximum' attribute is a number when it should be a boolean".
Synchronous/Asynchronous
Schema.validate can be called in two ways, to suit your needs:
Synchronously - as in the example above, with one parameter.
As already stated, it returns nothing if the object checks out. Otherwise it throws an error.
Asynchronously - by providing a 2nd parameter: a callback function.
The callback function gets two arguments: error and result (the original JSON object, which may be modified).
It should be noted that the JSON object passed to the callback function is the same as the input JSON object.
It is only passed for convenience.
Any default values used will affect the original JSON object, even when calling asynchronously.
Hello, schema
A JSON schema is defined using a JavaScript object containing various attributes.
Let's start by analyzing the schema given in the example above.
What does it say about the JSON object?
The JSON object should be an object (as opposed to an array).
It should have a property named query, which should be a string of 1 to 64 characters.
It may optionaly have a property named maxResults, which should be an integer with a maximum value of 20.
If maxResults is missing, it will be generated with a value of 10.
Additional properties (other than query and maxResults) are not allowed.
JSON Schema properties can be nested: objects and arrays include other attributes, which may themselves be objects and arrays.
Notice that objects' properties are unordered, whereas array items are ordered.
See Attributes section below to learn about more possibilities.
Attributes
Below are all the supported attributes.
Terminology: in this section, instance refers to a JSON value (object or property) that the schema will be describing and validating.
type
Defines the expected instance type.
It can take one of two forms:
Simple type - any of the following: 'string', 'number', 'integer', 'boolean', 'object', 'array', 'null' or 'any'.
Union type - an array of simple types and/or schemas. The instance type should be one of the types in the array.
Example - instance should be either a string or null:
type: ['string', 'null']
The default is 'any'.
disallow
Defines the disallowed instance type. This is the opposite of type.
It can take one of two forms:
Simple type - any of the following: 'string', 'number', 'integer', 'boolean', 'object', 'array', 'null' or 'any'.
Union type - an array of simple types and/or schemas. The instance type should not be any of the types in the array.
For example, if type is ['string', 'null'] then the instance may be neither a string nor null.
required
A boolean indicating whether an instance is mandatory (true) or optional (false).
Example with a mandatory property and an optional one:
Note: Properties are considered unordered, the order of the instance properties may be in any order.
patternProperties
Applies only to instances of type 'object'.
This attribute is similar to the properties attribute, but the keys are regular expression patterns instead of property names.
Any instance property whose name fits a pattern must be valid against the appropriate schema.
Note that using this attribute may cause instances to be validated more than once:
If a property name is defined by properties and also matches a pattern in patternProperties.
If a property name matches more than one pattern in patternProperties.
additionalProperties
Applies only to instances of type 'object'.
Defines a schema for all properties that are not explicitly defined by properties and do not match any pattern in patternProperties.
It can take one of two forms:
Schema - all the additional properties must be valid against the schema.
The default is an empty schema, which allows any value for additional properties.
dependencies
Applies only to instances of type 'object'.
This attribute is an object, matching properties to their requirements.
If the instance object has a property with the same name as a property in the dependencies attribute object,
then the instance must comply with the requirement.
The requirement can take one of three forms:
Simple dependency - a string.
The instance object must have a property with the same name as the requirement.
Example: dependencies: { start: 'finish' }.
Means that if an instance has a property 'start', it must also have a property 'finish'.
Simple dependency tuple - an array of strings.
The instance object must have a property with the same name as each string in the requirement's array.
Example: dependencies: { towel: [ 'toothbrush', 'soap', 'space suit' ]}.
Means that if an instance has a property 'towel', it must also have properties 'toothbrush', 'soap' and 'space suit'.
Schema dependency - a schema.
The instance object must be valid against the schema.
Example: dependencies: { 'cuba-libre': { properties: { glass: { format: 'highball', required: true }}}}
Means that if an instance has a property 'cuba-libre', it must also have a property 'glass' with a 'highball' format.
items
Applies only to instances of type 'array'.
Defines the items of the instance array.
It can take one of two forms:
Schema - all the items in the array must be valid against the schema.
Tuple typing - an array of schemas.
Each position in the instance array must conform to the schema in the corresponding position for this array.
The instance array is not required to contain all defined items.
Additional items are allowed, disallowed, or constrained by the additionalItems attribute.
additionalItems
Applies only to instances of type 'array', and only together with the tuple typing form of the items attribute.
additionalItems defines the behavior when there are more items in the instance array than in the items array.
It can take one of two forms:
Schema - all the additional items must be valid against the schema.
False - additional items are not allowed.
Example - a string, an integer and the rest are booleans:
Defines what value the number instance must be divisible by with no remainder.
This value may not be 0.
format
Applies only to instances of types 'string' or 'number'.
Defines the expected instance format.
Available formats:
date-time - A string containing a date in ISO 8601 format of YYYY-MM-DDThh:mm:ss[.fraction]Z in UTC time.
The decimal fraction is optional and the decimal dot can be replaced with a comma.
Example: '2012-11-06T09:13:24Z'.
date - A string containing a date in the format of YYYY-MM-DD.
Example: '2012-11-06'.
time - A string containing a time in the format of hh:mm:ss.
Example: '09:13:24'.
utc-millisec - A number or an integer containing the number of milliseconds that have elapsed since midnight UTC, 1 January 1970.
regex - A string containing a regular expression, following the regular expression specification from ECMA 262.
Example: '^[0-9]{5}-[0-9]{4}$'.
color - A string containing a CSS color, based on CSS 2.1 [W3C.CR-CSS21-20070719].
Examples: 'red', '#FF9900', 'f90', 'rgb(64, 224, 208)', 'rgb(100%, 0%, 25%)'.
phone - A string containing a national or international phone number, based on E.123.
No hypens allows, only spaces.
Examples: '(42) 123 4567', '+31 42 123 4567'.
uri - A string containing a URI.
Example: 'https://github.com/oferei/json-gate'.
email - A string containing an email address.
Example: 'thepope@gmail.com'.
ip-address - A string containing an ip version 4 address.
Example: '192.168.1.1'.
ipv6 - A string containing an ip version 6 address.
Example: '2001:0db8:85a3:0042:0000:8a2e:0370:7334'.
host-name - A string containing a host-name.
Example: 'github.com'.
Note: Unknown formats are silently ignored.
title
A string that provides a short description of instance property.
It allows to document the JSON schema.
It has no effect on the validation process.
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.