jsonwidget JSON Schema Definition

This document describes the JSON schema format used by jsonwidget.

Purpose

JSON is a flexible data format that allows developers to express a wide array of data structures. Sometimes, however, it's helpful to describe a particular subset of JSON texts that are valid for a particular problem domain. A JSON schema is a JSON text which in turn allows one to generate or validate a domain-specific subset of all possible JSON texts.

Definitions

This document will use the vocabulary defined in RFC 4627 unless otherwise noted. In particular, the following terms are used as described: Some key definitions:
JSON schema
What this document is describing. A JSON schema is a JSON text consisting of a single object: a "root schema object".
Root schema object
This is simply the topmost schema object in the JSON schema. The root schema object may in turn contain other schema objects using the "mapping" and/or "sequence" schema object properties described below.
Target JSON text
A JSON text that is being validated by the JSON schema.
Target JSON name
Name (inside a name/value pair) currently being validated inside the target JSON text.
Target JSON value
The portion of the target JSON text that is being compared to a given schema object. This might be the value inside a name/value pair, it may be a value listed in an array, or it may be the root of the target JSON text.
Most of the following sections are themselves definitions.

Schema Objects

A schema object is an "object" as described in section 2.2 of RFC 4627. A schema object describes what constitutes a valid value within the target JSON text. The root schema object describes what constitutes a valid value for the target JSON text. The schema objects within the root schema object are mapped to values in the target JSON text as described below.

Schema objects can (and often should) contain name/value pairs with the following names:

Documentation for these and all other name/value pairs is below, described as "Schema object properties".

If "type" is "map" or "seq", then the appropriate one of the following properties must also be present:

If you'd like to constrain the values in a particular field to a list of enumerated values, then the following properties are useful:

Additionally, the following more advanced properties are available (currently only available in jsonwidget-javascript):

Schema object properties

A "schema object property" is a name/value pair inside the schema object. Each valid name is described below.

type

This is a required schema object property (and the only one that's required in all contexts). The "type" field describes what constitutes a valid value for this particular node of the target JSON text. Values:
str
A string as described in section 2.5 of RFC 4627
int
An integer. This is a number as described in section 2.4 of RFC 4627, but without the optional "frac" and "exp" components.
number
A number as described in section 2.4 of RFC 4627.
bool
A boolean value. Must be either "true" or "false".
seq
Nested sequence of items ('array' in many languages). When type="seq" on a schema object, then that object must also have a 'sequence' schema object property.
map
Nested mapping of key/value pairs (a.k.a. 'properties'). Schema objects containing this type value must also have a 'mapping' schema object property.
idref
Indicates this schema object is a reference to another schema object. Schema objects containing this type value must also have an 'idref' schema object property. This property is currently only supported in jsonwidget-javascript.
any
Any value allowed. Currently only support in jsonwidget-javascript.

title

A user-friendly title for the schema object. This value will be used as the field title in forms that are generated.

id

A globally unique identifier within the schema. This identifier used to reference this schema object property using the 'idref' schema object property.

desc

A description for use in documentation and context help.

user_key

Key for name/value pairs where the name is document-specific. This can be used only when type="map", and there must be a corresponding schema object in the mapping using the name provided in this field. If the target JSON name doesn't match any of the names from the "mapping" schema object property value

idref

Reference to a schema object with the given 'id' property. The 'type' attribute must be set to 'idref'. An "idref" schema object takes on the definition of the object that it references. This property is only currently supported by jsonwidget-javascript.

enum

Enumerated sequence of valid values for this schema object.

desc_enum

A mapping containing a description for each possible value listed in the enumeration (enum) property. Used for documentation and context help.

required

If 'true', then this property must always be present.

mapping

An object ("mapping object") where each name/value pair describes a valid target JSON name and target JSON value. Each mapping object name is a valid target JSON name, and each mapping object value is a schema object describing valid target JSON values. If the 'user_key' schema object property is present, then a name/value pair describing arbitrary target JSON names may also be present.

The 'type' schema object property must be set to 'map' to use this property.

sequence

A JSON array containing a single schema object which describes valid target JSON values.

Acknowledgements, etc

The original design for this is just about a strict subset of the schema format in Kwalify by Makoto Kuwata. At the time jsonwidget was created (2005), this was the most credible solution in this particular problem space.

Since that time, there's been work done on an IETF Internet draft for JSON schemas. I haven't done a thorough enough evaluation of this proposal to know if it is a suitable replacement for this schema definition format.

Rob Lanphier