A JSON Schema is a JSON object that defines various attributes
(including usage and valid values) of a JSON value. JSON
Schema has recursive capabilities; there are a number of elements
in the structure that allow for nested JSON Schemas.
</t>
<figure>
<preamble>An example JSON Schema could look like:</preamble>
<artwork>
<![CDATA[
{
"description": "A person",
"type": "object",
"properties": {
"name": {
"type": "string"
},
"age": {
"type": "number",
"divisibleBy": 1,
"minimum": 0,
"maximum": 125
}
}
}
]]>
</artwork>
</figure>
<t>
A JSON Schema object MAY have any of the following optional properties:
</t>
<!-- TODO: Break attributes up into type sections -->
<!-- TODO: Add examples for (almost) every attribute -->
<sectiontitle="type"anchor="type">
<t>
This attribute defines what the primitive type or the schema of the instance MUST be in order to validate.
This attribute can take one of two forms:
<liststyle="hanging">
<thangText="Simple Types">
A string indicating a primitive or simple type. The string MUST be one of the following values:
<liststyle="hanging">
<thangText="object">Instance MUST be an object.</t>
<thangText="array">Instance MUST be an array.</t>
<thangText="string">Instance MUST be a string.</t>
<thangText="number">Instance MUST be a number, including floating point numbers.</t>
<thangText="boolean">Instance MUST be the JSON literal "true" or "false".</t>
<thangText="null">Instance MUST be the JSON literal "null". Note that without this type, null values are not allowed.</t>
<thangText="any">Instance MAY be of any type, including null.</t>
</list>
</t>
<thangText="Union Types">
An array of one or more simple or schema types.
The instance value is valid if it is of the same type as one of the simple types, or valid by one of the schemas, in the array.
</t>
</list>
If this attribute is not specified, then all value types are accepted.
</t>
<figure>
<preamble>For example, a schema that defines if an instance can be a string or a number would be:</preamble>
<artwork>
<![CDATA[
{
"type": ["string", "number"]
}
]]></artwork>
</figure>
</section>
<sectiontitle="properties"anchor="properties">
<t>
This attribute is an object with properties that specify the schemas for the properties of the instance object.
In this attribute's object, each property value MUST be a schema.
When the instance value is an object, the value of the instance's properties MUST be valid according to the schemas with the same property names specified in this attribute.
Objects are unordered, so therefore the order of the instance properties or attribute properties MUST NOT determine validation success.
This attribute is an object that defines the schema for a set of property names of an object instance.
The name of each property of this attribute's object is a regular expression pattern in the ECMA 262/Perl 5 format, while the value is a schema.
If the pattern matches the name of a property on the instance object, the value of the instance's property MUST be valid against the pattern name's schema value.
<t>This attribute specifies how any instance property that is not explicitly defined by either the <xreftarget="properties">"properties"</xref> or <xreftarget="patternProperties">"patternProperties"</xref> attributes (hereafter referred to as "additional properties") is handled. If specified, the value MUST be a schema or a boolean.</t>
<t>If a schema is provided, then all additional properties MUST be valid according to the schema.</t>
<t>If false is provided, then no additional properties are allowed.</t>
<t>The default value is an empty schema, which allows any value for additional properties.</t>
</section>
<sectiontitle="items"anchor="items">
<t>This attribute provides the allowed items in an array instance. If specified, this attribute MUST be a schema or an array of schemas.</t>
<t>When this attribute value is a schema and the instance value is an array, then all the items in the array MUST be valid according to the schema.</t>
<t>When this attribute value is an array of schemas and the instance value is an array, each position in the instance array MUST be valid according to the schema in the corresponding position for this array. This called tuple typing. When tuple typing is used, additional items are allowed, disallowed, or constrained by the <xreftarget="additionalItems">"additionalItems"</xref> attribute the same way as <xreftarget="additionalProperties">"additionalProperties"</xref> for objects is.</t>
<t>This attribute specifies how any item in the array instance that is not explicitly defined by <xreftarget="items">"items"</xref> (hereafter referred to as "additional items") is handled. If specified, the value MUST be a schema or a boolean.</t>
<t>If a schema is provided:
<list>
<t>If the <xreftarget="items">"items"</xref> attribute is unspecified, then all items in the array instance must be valid against this schema.</t>
<t>If the <xreftarget="items">"items"</xref> attribute is a schema, then this attribute is ignored.</t>
<t>If the <xreftarget="items">"items"</xref> attribute is an array (during tuple typing), then any additional items MUST be valid against this schema.</t>
</list>
</t>
<t>If false is provided, then any additional items in the array are not allowed.</t>
<t>The default value is an empty schema, which allows any value for additional items.</t>
</section>
<sectiontitle="required"anchor="required">
<t>This attribute is an array of strings that defines all the property names that must exist on the object instance.</t>
<t>This attribute is an object that specifies the requirements of a property on an object instance. If an object instance has a property with the same name as a property in this attribute's object, then the instance must be valid against the attribute's property value (hereafter referred to as the "dependency value").</t>
<t>
The dependency value can take one of two forms:
<liststyle="hanging">
<thangText="Simple Dependency">
If the dependency value is a string, then the instance object MUST have a property with the same name as the dependency value.
If the dependency value is an array of strings, then the instance object MUST have a property with the same name as each string in the dependency value's array.
</t>
<thangText="Schema Dependency">
If the dependency value is a schema, then the instance object MUST be valid against the schema.
</t>
</list>
</t>
</section>
<sectiontitle="minimum"anchor="minimum">
<t>This attribute defines the minimum value of the instance property when the type of the instance value is a number.</t>
</section>
<sectiontitle="maximum"anchor="maximum">
<t>This attribute defines the maximum value of the instance property when the type of the instance value is a number.</t>
<t>This attribute indicates if the value of the instance (if the instance is a number) can not equal the number defined by the "minimum" attribute. This is false by default, meaning the instance value can be greater then or equal to the minimum value.</t>
<t>This attribute indicates if the value of the instance (if the instance is a number) can not equal the number defined by the "maximum" attribute. This is false by default, meaning the instance value can be less then or equal to the maximum value.</t>
</section>
<sectiontitle="minItems"anchor="minItems">
<t>This attribute defines the minimum number of values in an array when the array is the instance value.</t>
</section>
<sectiontitle="maxItems"anchor="maxItems">
<t>This attribute defines the maximum number of values in an array when the array is the instance value.</t>
<t>This attribute defines the maximum number of properties the object instance can have.</t>
</section>
<sectiontitle="uniqueItems"anchor="uniqueItems">
<t>This attribute indicates that all items in an array instance MUST be unique (contains no two identical values).</t>
<t>
Two instance are consider equal if they are both of the same type and:
<list>
<t>are null; or</t>
<t>are booleans/numbers/strings and have the same value; or</t>
<t>are arrays, contains the same number of items, and each item in the array is equal to the item at the corresponding index in the other array; or</t>
<t>are objects, contains the same property names, and each property in the object is equal to the corresponding property in the other object.</t>
</list>
</t>
</section>
<sectiontitle="pattern"anchor="pattern">
<t>When the instance value is a string, this provides a regular expression that a string instance MUST match in order to be valid. Regular expressions SHOULD follow the regular expression specification from ECMA 262/Perl 5</t>
</section>
<sectiontitle="minLength"anchor="minLength">
<t>When the instance value is a string, this defines the minimum length of the string.</t>
</section>
<sectiontitle="maxLength"anchor="maxLength">
<t>When the instance value is a string, this defines the maximum length of the string.</t>
</section>
<sectiontitle="enum"anchor="enum">
<t>This provides an enumeration of all possible values that are valid for the instance property. This MUST be an array, and each item in the array represents a possible value for the instance value. If this attribute is defined, the instance value MUST be one of the values in the array in order for the schema to be valid. Comparison of enum values uses the same algorithm as defined in <xreftarget="uniqueItems">"uniqueItems"</xref>.</t>
</section>
<sectiontitle="default"anchor="default">
<t>This attribute defines the default value of the instance when the instance is undefined.</t>
</section>
<sectiontitle="title"anchor="title">
<t>This attribute is a string that provides a short description of the instance property.</t>
</section>
<sectiontitle="description"anchor="description">
<t>This attribute is a string that provides a full description of the of purpose the instance property.</t>
</section>
<sectiontitle="divisibleBy"anchor="divisibleBy">
<t>This attribute defines what value the number instance must be divisible by with no remainder (the result of the division must be an integer.) The value of this attribute SHOULD NOT be 0.</t>
</section>
<sectiontitle="disallow"anchor="disallow">
<t>This attribute takes the same values as the "type" attribute, however if the instance matches the type or if this value is an array and the instance matches any type or schema in the array, then this instance is not valid.</t>
</section>
<sectiontitle="extends"anchor="extends">
<t>The value of this property MUST be another schema which will provide a base schema which the current schema will inherit from. The inheritance rules are such that any instance that is valid according to the current schema MUST be valid according to the referenced schema. This MAY also be an array, in which case, the instance MUST be valid for all the schemas in the array. A schema that extends another schema MAY define additional attributes, constrain existing attributes, or add other constraints.</t>
<t>
Conceptually, the behavior of extends can be seen as validating an
instance against all constraints in the extending schema as well as
the extended schema(s). More optimized implementations that merge
schemas are possible, but are not required. Some examples of using "extends":
This attribute defines the current URI of this schema (this attribute is
effectively a "self" link). This URI MAY be relative or absolute. If
the URI is relative it is resolved against the current URI of the parent
schema it is contained in. If this schema is not contained in any
parent schema, the current URI of the parent schema is held to be the
URI under which this schema was addressed. If id is missing, the current URI of a schema is
defined to be that of the parent schema. The current URI of the schema
is also used to construct relative references such as for $ref.
</t>
</section>
<sectiontitle="$ref"anchor="ref">
<t>
This attribute defines a URI of a schema that contains the full representation of this schema.
When a validator encounters this attribute, it SHOULD replace the current schema with the schema referenced by the value's URI (if known and available) and re-validate the instance.
This URI MAY be relative or absolute, and relative URIs SHOULD be resolved against the URI of the current schema.
</t>
</section>
<sectiontitle="$schema"anchor="schema">
<t>
This attribute defines a URI of a JSON Schema that is the schema of the current schema.
When this attribute is defined, a validator SHOULD use the schema referenced by the value's URI (if known and available) when resolving <xreftarget="hyper-schema">Hyper Schema</xref><xreftarget="links">links</xref>.
</t>
<t>
A validator MAY use this attribute's value to determine which version of JSON Schema the current schema is written in, and provide the appropriate validation features and behavior.
Therefore, it is RECOMMENDED that all schema authors include this attribute in their schemas to prevent conflicts with future JSON Schema specification changes.
indicates the target URI of the related resource. The value
of the instance property SHOULD be resolved as a URI-Reference per <xreftarget="RFC3986">RFC 3986</xref>
and MAY be a relative URI. The base URI to be used for relative resolution
SHOULD be the URI used to retrieve the instance object (not the schema)
when used within a schema. Also, when links are used within a schema, the URI
SHOULD be parametrized by the property values of the instance
object, if property values exist for the corresponding variables
in the template (otherwise they MAY be provided from alternate sources, like user input).
</t>
<t>
Instance property values SHOULD be substituted into the URIs where
matching braces ('{', '}') are found surrounding zero or more characters,
creating an expanded URI. Instance property value substitutions are resolved
by using the text between the braces to denote the property name
from the instance to get the value to substitute.
<figure>
<preamble>For example, if an href value is defined:</preamble>
<artwork>
<![CDATA[
http://somesite.com/{id}
]]>
</artwork>
<postamble>Then it would be resolved by replace the value of the "id" property value from the instance object.</postamble>
</figure>
<figure>
<preamble>If the value of the "id" property was "45", the expanded URI would be:</preamble>
<artwork>
<![CDATA[
http://somesite.com/45
]]>
</artwork>
</figure>
If matching braces are found with the string "@" (no quotes) between the braces, then the
actual instance value SHOULD be used to replace the braces, rather than a property value.
This should only be used in situations where the instance is a scalar (string,
boolean, or number), and not for objects or arrays.
</t>
</section>
<sectiontitle="rel">
<t>
The value of the "rel" property indicates the name of the
relation to the target resource. The relation to the target SHOULD be interpreted as specifically from the instance object that the schema (or sub-schema) applies to, not just the top level resource that contains the object within its hierarchy. If a resource JSON representation contains a sub object with a property interpreted as a link, that sub-object holds the relation with the target. A relation to target from the top level resource MUST be indicated with the schema describing the top level JSON representation.
</t>
<t>
Relationship definitions SHOULD NOT be media type dependent, and users are encouraged to utilize existing accepted relation definitions, including those in existing relation registries (see <xreftarget="RFC4287">RFC 4287</xref>). However, we define these relations here for clarity of normative interpretation within the context of JSON hyper schema defined relations:
<liststyle="hanging">
<thangText="self">
If the relation value is "self", when this property is encountered in
the instance object, the object represents a resource and the instance object is
treated as a full representation of the target resource identified by
the specified URI.
</t>
<thangText="full">
This indicates that the target of the link is the full representation for the instance object. The object that contains this link possibly may not be the full representation.
</t>
<thangText="describedby">
This indicates the target of the link is the schema for the instance object. This MAY be used to specifically denote the schemas of objects within a JSON object hierarchy, facilitating polymorphic type data structures.
</t>
<thangText="root">
This relation indicates that the target of the link
SHOULD be treated as the root or the body of the representation for the
purposes of user agent interaction or fragment resolution. All other
properties of the instance objects can be regarded as meta-data
descriptions for the data.
</t>
</list>
</t>
<t>
The following relations are applicable for schemas (the schema as the "from" resource in the relation):
<liststyle="hanging">
<thangText="instances">This indicates the target resource that represents collection of instances of a schema.</t>
<thangText="create">This indicates a target to use for creating new instances of a schema. This link definition SHOULD be a submission link with a non-safe method (like POST).</t>
</list>
</t>
<t>
<figure>
<preamble>For example, if a schema is defined:</preamble>
<artwork>
<![CDATA[
{
"links": [{
"rel": "self",
"href": "{id}"
}, {
"rel": "up",
"href": "{upId}"
}, {
"rel": "children",
"href": "?upId={id}"
}]
}
]]>
</artwork>
</figure>
<figure>
<preamble>And if a collection of instance resource's JSON representation was retrieved:</preamble>
<artwork>
<![CDATA[
GET /Resource/
[{
"id": "thing",
"upId": "parent"
}, {
"id": "thing2",
"upId": "parent"
}]
]]>
</artwork>
</figure>
This would indicate that for the first item in the collection, its own
(self) URI would resolve to "/Resource/thing" and the first item's "up"
relation SHOULD be resolved to the resource at "/Resource/parent".
The "children" collection would be located at "/Resource/?upId=thing".
</t>
</section>
<sectiontitle="template">
<t>This property value is a string that defines the templating language used in the <xreftarget="href">"href"</xref> attribute. If no templating language is defined, then the default <xreftarget="href">Link Description Object templating langauge</xref> is used.</t>
</section>
<sectiontitle="targetSchema">
<t>This property value is a schema that defines the expected structure of the JSON representation of the target of the link.</t>
</section>
<sectiontitle="Submission Link Properties">
<t>
The following properties also apply to link definition objects, and
provide functionality analogous to HTML forms, in providing a
means for submitting extra (often user supplied) information to send to a server.
</t>
<sectiontitle="method">
<t>
This attribute defines which method can be used to access the target resource.
In an HTTP environment, this would be "GET" or "POST" (other HTTP methods
such as "PUT" and "DELETE" have semantics that are clearly implied by
accessed resources, and do not need to be defined here).
This defaults to "GET".
</t>
</section>
<sectiontitle="enctype">
<t>
If present, this property indicates a query media type format that the server
supports for querying or posting to the collection of instances at the target
resource. The query can be
suffixed to the target URI to query the collection with
property-based constraints on the resources that SHOULD be returned from
the server or used to post data to the resource (depending on the method).
<figure>
<preamble>For example, with the following schema:</preamble>
<artwork>
<![CDATA[
{
"links": [{
"enctype": "application/x-www-form-urlencoded",
"method": "GET",
"href": "/Product/",
"properties": {
"name": {
"description": "name of the product"
}
}
}]
}
]]>
</artwork>
<postamble>This indicates that the client can query the server for instances that have a specific name.</postamble>
</figure>
<figure>
<preamble>For example:</preamble>
<artwork>
<![CDATA[
/Product/?name=Slinky
]]>
</artwork>
</figure>
If no enctype or method is specified, only the single URI specified by
the href property is defined. If the method is POST, "application/json" is
the default media type.
</t>
</section>
<sectiontitle="schema">
<t>
This attribute contains a schema which defines the acceptable structure of the submitted
request (for a GET request, this schema would define the properties for the query string
and for a POST request, this would define the body).
</t>
</section>
</section>
</section>
</section>
<sectiontitle="fragmentResolution">
<t>
This property indicates the fragment resolution protocol to use for
resolving fragment identifiers in URIs within the instance
representations. This applies to the instance object URIs and all
children of the instance object's URIs. The default fragment resolution
protocol is "json-pointer", which is defined below. Other fragment
resolution protocols MAY be used, but are not defined in this document.
</t>
<t>
The fragment identifier is based on <xreftarget="RFC3986">RFC 3986, Sec 5</xref>, and defines the
mechanism for resolving references to entities within a document.
</t>
<sectiontitle="json-pointer fragment resolution">
<t>The "json-pointer" fragment resolution protocol uses a <xreftarget="json-pointer">JSON Pointer</xref> to resolve fragment identifiers in URIs within instance representations.</t>
</section>
</section>
<!-- TODO: Remove this? -->
<sectiontitle="readonly">
<t>This attribute indicates that the instance value SHOULD NOT be changed. Attempts by a user agent to modify the value of this property are expected to be rejected by a server.</t>
</section>
<sectiontitle="contentEncoding">
<t>If the instance property value is a string, this attribute defines that the string SHOULD be interpreted as binary data and decoded using the encoding named by this schema property. <xreftarget="RFC2045">RFC 2045, Sec 6.1</xref> lists the possible values for this property.</t>
</section>
<sectiontitle="pathStart">
<t>
This attribute is a URI that defines what the instance's URI MUST start with in order to validate.
The value of the "pathStart" attribute MUST be resolved as per <xreftarget="RFC3986">RFC 3986, Sec 5</xref>,
and is relative to the instance's URI.
</t>
<t>
When multiple schemas have been referenced for an instance, the user agent
can determine if this schema is applicable for a particular instance by
determining if the URI of the instance begins with the the value of the "pathStart"
attribute. If the URI of the instance does not start with this URI,
or if another schema specifies a starting URI that is longer and also matches the
instance, this schema SHOULD NOT be applied to the instance. Any schema
that does not have a pathStart attribute SHOULD be considered applicable
to all the instances for which it is referenced.
</t>
</section>
<sectiontitle="mediaType">
<t>This attribute defines the media type of the instance representations that this schema is defining.</t>
</section>
</section>
<sectiontitle="Security Considerations">
<t>
This specification is a sub-type of the JSON format, and
consequently the security considerations are generally the same as <xreftarget="RFC4627">RFC 4627</xref>.
However, an additional issue is that when link relation of "self"
is used to denote a full representation of an object, the user agent
SHOULD NOT consider the representation to be the authoritative representation
of the resource denoted by the target URI if the target URI is not
equivalent to or a sub-path of the the URI used to request the resource
representation which contains the target URI with the "self" link.
<figure>
<preamble>For example, if a hyper schema was defined:</preamble>
<artwork>
<![CDATA[
{
"links": [{
"rel": "self",
"href": "{id}"
}]
}
]]>
</artwork>
</figure>
<figure>
<preamble>And a resource was requested from somesite.com:</preamble>
"name": "This representation can be safely treated \
as authoritative "
}, {
"id": "/baz",
"name": "This representation should not be treated as \
authoritative the user agent should make request the resource\
from '/baz' to ensure it has the authoritative representation"
}, {
"id": "http://othersite.com/something",
"name": "This representation\
should also not be treated as authoritative and the target\
resource representation should be retrieved for the\
authoritative representation"
}]
]]>
</artwork>
</figure>
</t>
</section>
<sectiontitle="IANA Considerations">
<t>The proposed MIME media type for JSON Schema is "application/schema+json".</t>
<t>Type name: application</t>
<t>Subtype name: schema+json</t>
<t>Required parameters: profile</t>
<t>
The value of the profile parameter SHOULD be a URI (relative or absolute) that
refers to the schema used to define the structure of this structure (the
meta-schema). Normally the value would be http://json-schema.org/draft-04/hyper-schema,
but it is allowable to use other schemas that extend the hyper schema's meta-
schema.
</t>
<t>Optional parameters: pretty</t>
<t>The value of the pretty parameter MAY be true or false to indicate if additional whitespace has been included to make the JSON representation easier to read.</t>
<sectiontitle="Registry of Link Relations">
<t>
This registry is maintained by IANA per <xreftarget="RFC4287">RFC 4287</xref> and this specification adds
four values: "full", "create", "instances", "root". New
assignments are subject to IESG Approval, as outlined in <xreftarget="RFC5226">RFC 5226</xref>.
Requests should be made by email to IANA, which will then forward the
