JSON schema is the modern equivalent to XSchema/DDML or the good old ancient DTDs. It provides a lightweight, self-describing and abstract protocol for describing and validating data formats and models. There are validator implementations in many languages, but the most obvious use is in pre-send validation for frontend JavaScript applications. A good validator and some simple wrappers or data binding (like say, this...) and you can code up a complex and powerful new application in days.
Its simple JSON structure and savviness of the community has thus far kept any kind of introductory documentation from cropping up, instead one must simply read through the spec and digest it for themselves. Since this is a time-consuming process, I did up a quick cheatsheet of the properties involved in schema declarations so that once one understands the basic principle you don't have to go back and check for what the name of something was repeatedly.
Currently in draft v4, this documentation was originally written for v3 but from what I can tell (I actually cannot find a changelog anywhere, which bothers me; if anyone has a link please share!) not very much has changed since then, save for the removal of the integer type in favour of {type: "number", divisibleBy: 1}.
All datatypes
- title
- short property description for readability
- description
- full description of the property
- extends
- Another schema to inherit validation from. Note that this basically validates the extended schema in turn, some implementations may merge but it is not required. most often, you'll want to specify this as
{"$ref" : "anotherschemaURI"}. - If you're extending a schema with an ID, always set a new ID in the extending schema - otherwise, the new properties will be merged into the base schema!
- Another schema to inherit validation from. Note that this basically validates the extended schema in turn, some implementations may merge but it is not required. most often, you'll want to specify this as
- id
- Defines the URI of the current schema block. Child blocks will inherit the URI from their parents.
- $ref
- Basically an include. Loads the referenced schema (see 'id') into the document. URIs may be relative or absolute, and are resolved against the URI of the current schema.
- $schema
- Defines the schema of the current schema. You should do this to ensure that changes to the JSON schema draft do not change the way your schemas validate. Currently, the latest draft schema is 'http://json-schema.org/draft-03/schema'.
- type
string,number,integer,boolean,object,array,nullorany[default], or- an array of these for multiple allowable types
- disallow
- The reverse of 'type', used to exclude datatypes
- required
- True if required (default false)
- default
- Default value for this property
- enum
- Defines an array of all possible values of this property
- dependencies
- when a string: instance object must have this property
- when an array of strings: instance object must have all these properties
- when a schema: instance object must be valid against this schema
Numbers
- minimum
- maximum
- exclusiveMinimum / exclusiveMaximum
- Specifies whether the minimum/maximum values exclude those defined (default false)
- divisibleBy
- Used for specifying numbers that must be multiples of others. Must not be 0!
Strings
- pattern
- regex for validation of the string
- minLength / maxLength
- Specifies length constraints on the string
All Primitives
- format
- A well-known datatype for a primitive value. Note that your validator may not necessarily validate these. You may also create your own microformats and specify them as a URI to the format's schema. Some standard possible values include:
date-time(YYYY-MM-DDThh:mm:ssZ in UTC)date(YYYY-MM-DD)time(hh:mm:ss)utc-millisec(int or float, usec since the epoch)regex(ECMA 262/Perl 5/standard JS)color(CSS 2.1 color value)style(a CSS style definition)phone(in E.123 format)uriemailip-addressipv6host-name
- A well-known datatype for a primitive value. Note that your validator may not necessarily validate these. You may also create your own microformats and specify them as a URI to the format's schema. Some standard possible values include:
Objects
- properties
- Specifies schemas to validate each of this object's properties in turn.
- patternProperties
- like properties, but keyed by regexes
- additionalProperties
- When
false, only core schema properties are allowed - When
{}ortrue(default) allow any extra properties to be set - When defined as schemas, this adds validation to any extra properties. It basically allows you to validate arbitrary properties on the object.
- Note that setting this to false will lock the schema from being extended further.
- When
Arrays
- minItems / maxItems
- sets the min & max number of elements that can be present
- uniqueItems
- If true, force array elements to be unique
- items
- a child schema providing validation for all elements in the array, or
- an array of child schemas validating each item in the array at their index
- additionalItems
- If
false, only defined array elements are allowed - If a schema, the schema specifies validation for any elements in the array not covered by the array of item schemas
- If
HYPER SCHEMA
The hyper-schema adds stuff to describe the links between objects. It adds a 'links' array property to the top-level schema, each of which is an object containing:
- rel
- The relationship name. Standard names are
self,full,describedbyandroot.instancesandcreateare also valid for schemas.
- The relationship name. Standard names are
- href
- The target URI of the related resource. Properties of the object instance may be substituted using curly braces. An @ between the braces means "the actual instance value SHOULD be used to replace the braces, rather than a property value".
- targetSchema
- Defines the schema that should validate the data contained at this URI
The following properties allow advanced control over the way a resource is requested:
- method
- Request method. Defaults to
GET.
- Request method. Defaults to
- enctype
- Defaults to
application/x-www-form-urlencodedfor GET,application/jsonfor POST
- Defaults to
- properties
- Specifies the parameters that can be passed using the specified HTTP 'method', encoded via 'enctype', to retrieve the resource
- schema
- Defines the acceptable structure of the submitted request
Other Schema Properties
- fragmentResolution
- Fragment resolution algorithm for constructing objects out of URLs. Defaults to 'slash-delimited'.
- pathStart
- Defines what the instance's URI must start with in order to validate. Can also be used to auto-match a schema onto an object retrieved from a request.
Misc Additions
- readonly (defaults to
false)
String additions
- contentEncoding
- Interpret a string as binary data, and encode as specified (see http://tools.ietf.org/html/rfc2045#section-6.1)
--more to do--