jsonwidget JSON Schema Definition
This document describes the JSON schema format used by jsonwidget.
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.
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 text
Most of the following sections are themselves 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
- 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.
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
Additionally, the following more advanced properties are
Schema object properties
A "schema object property" is a name/value pair inside the schema
object. Each valid name is described below.
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:
- A string as described in section 2.5 of RFC 4627
- An integer. This is a number as described in section 2.4 of RFC
4627, but without the optional "frac" and "exp" components.
- A number as described in section 2.4 of RFC 4627.
- A boolean value. Must be either "true" or "false".
- 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.
- Nested mapping of key/value pairs (a.k.a. 'properties'). Schema
objects containing this type value must also have a 'mapping'
schema object property.
- 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
- Any value allowed. Currently only support in
A user-friendly title for the schema object. This value will be
used as the field title in forms that are generated.
A globally unique identifier within the schema. This identifier
used to reference this schema object property using the 'idref'
schema object property.
A description for use in documentation and context help.
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
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
Enumerated sequence of valid values for this schema object.
A mapping containing a description for each possible value listed
in the enumeration (enum) property. Used for documentation and
If 'true', then this property must always be present.
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
The 'type' schema object property must be set to 'map' to use
A JSON array containing a single schema object which describes
valid target JSON values.
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.