Skip to content

Instantly share code, notes, and snippets.

@fge

fge/gist:3231325

Created August 1, 2012 22:37
Show Gist options
  • Save fge/3231325 to your computer and use it in GitHub Desktop.
Save fge/3231325 to your computer and use it in GitHub Desktop.
Download ZIP
draftv4 candidate, unfit for release
Raw
gistfile1.txt
Internet Engineering Task Force K. Zyp, Ed.
Internet-Draft SitePen (USA)
Intended status: Informational G. Court
Expires: February 3, 2013 August 2, 2012
A JSON Media Type for Describing the Structure and Meaning of JSON
Documents
draft-zyp-json-schema-04
Abstract
JSON (JavaScript Object Notation) Schema defines the media type
"application/schema+json", a JSON based format for defining the
structure of JSON data. JSON Schema provides a contract for what
JSON data is required for a given application and how to interact
with it. JSON Schema is intended to define validation,
documentation, hyperlink navigation, and interaction control of JSON
data.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on February 3, 2013.
Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
Zyp & Court Expires February 3, 2013 [Page 1]
Internet-Draft JSON Schema Media Type August 2012
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Conventions and Terminology . . . . . . . . . . . . . . . . . 4
3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Design Considerations . . . . . . . . . . . . . . . . . . 6
4. Schema/Instance Association . . . . . . . . . . . . . . . . . 6
4.1. Self-Descriptive Schema . . . . . . . . . . . . . . . . . 7
5. Core Schema Definition . . . . . . . . . . . . . . . . . . . . 7
5.1. Keywords for numeric instances (number, integer) . . . . . 8
5.1.1. minimum . . . . . . . . . . . . . . . . . . . . . . . 8
5.1.2. maximum . . . . . . . . . . . . . . . . . . . . . . . 8
5.1.3. exclusiveMinimum . . . . . . . . . . . . . . . . . . . 8
5.1.4. exclusiveMaximum . . . . . . . . . . . . . . . . . . . 9
5.1.5. mod . . . . . . . . . . . . . . . . . . . . . . . . . 9
5.2. Keywords for string instances . . . . . . . . . . . . . . 9
5.2.1. pattern . . . . . . . . . . . . . . . . . . . . . . . 9
5.2.2. minLength . . . . . . . . . . . . . . . . . . . . . . 9
5.2.3. maxLength . . . . . . . . . . . . . . . . . . . . . . 9
5.3. Keywords for array instances . . . . . . . . . . . . . . . 9
5.3.1. minItems . . . . . . . . . . . . . . . . . . . . . . . 9
5.3.2. maxItems . . . . . . . . . . . . . . . . . . . . . . . 9
5.3.3. items . . . . . . . . . . . . . . . . . . . . . . . . 9
5.3.4. additionalItems . . . . . . . . . . . . . . . . . . . 10
5.3.5. uniqueItems . . . . . . . . . . . . . . . . . . . . . 10
5.4. Keywords for object instances . . . . . . . . . . . . . . 11
5.4.1. minProperties . . . . . . . . . . . . . . . . . . . . 11
5.4.2. maxProperties . . . . . . . . . . . . . . . . . . . . 11
5.4.3. properties . . . . . . . . . . . . . . . . . . . . . . 11
5.4.4. patternProperties . . . . . . . . . . . . . . . . . . 11
5.4.5. additionalProperties . . . . . . . . . . . . . . . . . 12
5.4.6. required . . . . . . . . . . . . . . . . . . . . . . . 12
5.4.7. dependencies . . . . . . . . . . . . . . . . . . . . . 12
5.4.8. Note on properties and patternProperties . . . . . . . 12
5.5. Keywords for instances of any type . . . . . . . . . . . . 13
5.5.1. type . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.5.2. disallow . . . . . . . . . . . . . . . . . . . . . . . 14
5.5.3. format . . . . . . . . . . . . . . . . . . . . . . . . 14
5.5.4. enum . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.5.5. extends . . . . . . . . . . . . . . . . . . . . . . . 15
5.6. Metadata keywords . . . . . . . . . . . . . . . . . . . . 16
5.6.1. default . . . . . . . . . . . . . . . . . . . . . . . 16
5.6.2. title . . . . . . . . . . . . . . . . . . . . . . . . 16
5.6.3. description . . . . . . . . . . . . . . . . . . . . . 16
Zyp & Court Expires February 3, 2013 [Page 2]
Internet-Draft JSON Schema Media Type August 2012
5.6.4. id . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.6.5. $ref . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.6.6. $schema . . . . . . . . . . . . . . . . . . . . . . . 17
6. Hyper Schema . . . . . . . . . . . . . . . . . . . . . . . . . 17
6.1. links . . . . . . . . . . . . . . . . . . . . . . . . . . 17
6.1.1. Link Description Object . . . . . . . . . . . . . . . 17
6.2. fragmentResolution . . . . . . . . . . . . . . . . . . . . 22
6.2.1. json-pointer fragment resolution . . . . . . . . . . . 22
6.3. readonly . . . . . . . . . . . . . . . . . . . . . . . . . 22
6.4. contentEncoding . . . . . . . . . . . . . . . . . . . . . 22
6.5. pathStart . . . . . . . . . . . . . . . . . . . . . . . . 23
6.6. mediaType . . . . . . . . . . . . . . . . . . . . . . . . 23
7. Security Considerations . . . . . . . . . . . . . . . . . . . 23
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24
8.1. Registry of Link Relations . . . . . . . . . . . . . . . . 25
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25
9.1. Normative References . . . . . . . . . . . . . . . . . . . 25
9.2. Informative References . . . . . . . . . . . . . . . . . . 26
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 27
Zyp & Court Expires February 3, 2013 [Page 3]
Internet-Draft JSON Schema Media Type August 2012
1. Introduction
JSON (JavaScript Object Notation) Schema is a JSON media type for
defining the structure of JSON data. JSON Schema provides a contract
for what JSON data is required for a given application and how to
interact with it. JSON Schema is intended to define validation,
documentation, hyperlink navigation, and interaction control of JSON
data.
2. Conventions and Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119].
The terms "JSON", "JSON text", "JSON value", "member", "element",
"object", "array", "number", "string", "boolean", "true", "false",
and "null" in this document are to be interpreted as defined in RFC
4627 [RFC4627].
This specification also uses the following defined terms:
schema A JSON Schema object.
instance Equivalent to "JSON value" as defined in RFC 4627
[RFC4627].
property Equivalent to "member" as defined in RFC 4627 [RFC4627].
item Equivalent to "element" as defined in RFC 4627 [RFC4627].
attribute A property of a JSON Schema object.
3. Overview
JSON Schema defines the media type "application/schema+json" for
describing the structure of JSON text. JSON Schemas are also written
in JSON and includes facilities for describing the structure of JSON
in terms of allowable values, descriptions, and interpreting
relations with other resources.
This document is organized into several separate definitions. The
first definition is the core schema specification. This definition
is primary concerned with describing a JSON structure and specifying
valid elements in the structure. The second definition is the Hyper
Schema specification which is intended to define elements in a
structure that can be interpreted as hyperlinks. Hyper Schema builds
on JSON Schema to describe the hyperlink structure of JSON values.
Zyp & Court Expires February 3, 2013 [Page 4]
Internet-Draft JSON Schema Media Type August 2012
This allows user agents to be able to successfully navigate documents
containing JSON based on their schemas.
Cumulatively JSON Schema acts as meta-JSON that can be used to define
the required type and constraints on JSON values, as well as define
the meaning of the JSON values for the purpose of describing a
resource and determining hyperlinks within the representation.
An example JSON Schema that describes products might look like:
{
"title": "Product",
"properties": {
"id": {
"title": "Product Identifier",
"type": "number"
},
"name": {
"title": "Product Name",
"type": "string"
},
"price": {
"type": "number",
"minimum": 0
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required" : ["id", "name", "price"],
"links": [{
"rel": "full",
"href": "{id}"
}, {
"rel": "comments",
"href": "comments/?id={id}"
}]
}
This schema defines the properties of the instance, the required
properties (id, name, and price), as well as an optional property
(tags). This also defines the link relations of the instance.
Zyp & Court Expires February 3, 2013 [Page 5]
Internet-Draft JSON Schema Media Type August 2012
3.1. Design Considerations
The JSON Schema media type does not attempt to dictate the structure
of JSON values that contain data, but rather provides a separate
format for flexibly communicating how a JSON value should be
interpreted and validated, such that user agents can properly
understand acceptable structures and extrapolate hyperlink
information from the JSON. It is acknowledged that JSON values come
in a variety of structures, and JSON is unique in that the structure
of stored data structures often prescribes a non-ambiguous definite
JSON representation. Attempting to force a specific structure is
generally not viable, and therefore JSON Schema allows for a great
flexibility in the structure of the JSON data that it describes.
This specification is protocol agnostic. The underlying protocol
(such as HTTP) should sufficiently define the semantics of the
client-server interface, the retrieval of resource representations
linked to by JSON representations, and modification of those
resources. The goal of this format is to sufficiently describe JSON
structures such that one can utilize existing information available
in existing JSON representations from a large variety of services
that leverage a representational state transfer architecture using
existing protocols.
4. Schema/Instance Association
JSON values are correlated to their schema by the "describedby"
relation, where the schema is the target of the relation. JSON
values MUST be of the "application/json" media type or any other
subtype. Consequently, dictating how a JSON value should specify the
relation to the schema is beyond the normative scope of this document
since this document specifically defines the JSON Schema media type,
and no other. It is RECOMMNENDED that JSON values specify their
schema so that user agents can interpret the instance and retain the
self-descriptive characteristics. This avoides the need for out-of-
band information about instance data. Two approaches are recommended
for declaring the relation to the schema that describes the meaning
of a JSON instance's (or collection of instances) structure. A MIME
type parameter named "profile" or a relation of "describedby" (which
could be specified by a Link header) may be used:
Content-Type: application/my-media-type+json;
profile=http://example.com/my-hyper-schema
or if the content is being transferred by a protocol (such as HTTP)
that provides headers, a Link header can be used:
Zyp & Court Expires February 3, 2013 [Page 6]
Internet-Draft JSON Schema Media Type August 2012
Link: <http://example.com/my-hyper-schema>; rel="describedby"
Instances MAY specify multiple schemas, to indicate all the schemas
that are applicable to the data, and the data SHOULD be valid by all
the schemas. The instance data MAY have multiple schemas that it is
described by (the instance data SHOULD be valid for those schemas).
Or if the document is a collection of instances, the collection MAY
contain instances from different schemas. The mechanism for
referencing a schema is determined by the media type of the instance
(if it provides a method for referencing schemas).
4.1. Self-Descriptive Schema
JSON Schemas can themselves be described using JSON Schemas. A self-
describing JSON Schema for the core JSON Schema can be found at
http://json-schema.org/schema for the latest version or
http://json-schema.org/draft-04/schema for the draft-04 version. The
hyper schema self-description can be found at
http://json-schema.org/hyper-schema or
http://json-schema.org/draft-04/hyper-schema. All schemas used
within a protocol with a media type specified SHOULD include a MIME
parameter that refers to the self-descriptive hyper schema or another
schema that extends this hyper schema:
Content-Type: application/json;
profile=http://json-schema.org/draft-04/hyper-schema
5. Core Schema Definition
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.
Zyp & Court Expires February 3, 2013 [Page 7]
Internet-Draft JSON Schema Media Type August 2012
An example JSON Schema could look like:
{
"description": "A person",
"type": "object",
"properties": {
"name": {
"type": "string"
},
"age": {
"type": "number",
"divisibleBy": 1,
"minimum": 0,
"maximum": 125
}
}
}
A JSON Schema object MAY have one or more of the properties defined
in this section. These properties (called "keywords" in this
section) are grouped in subsections according to the type of instance
they can validate, while some properties apply to all instance types.
Some other keywords do not participate in instance validation and are
into a section of their own.
5.1. Keywords for numeric instances (number, integer)
5.1.1. minimum
The value of this keyword is a number which defines the minimum value
of the instance.
5.1.2. maximum
The value of this keyword is a number which defines the maximum value
of the instance.
5.1.3. exclusiveMinimum
This keyword MUST be paired with "minimum". Its value is a boolean.
If false (the default), then the instance may be greater than or
equal to "minimum". If true, then the instance must be strictly
greater than "minimum".
Zyp & Court Expires February 3, 2013 [Page 8]
Internet-Draft JSON Schema Media Type August 2012
5.1.4. exclusiveMaximum
This keyword MUST be paired with "maximum". Its value is a boolean.
If false (the default), then the instance may be less than or equal
to "maximum". If true, then the instance must be strictly lower than
"maximum".
5.1.5. mod
This keyword's value is a number which must divide instance with no
remainder (that is, the result of the division must be an integer.)
The value of this keyword MUST NOT be 0.
5.2. Keywords for string instances
5.2.1. pattern
The value of this keyword is an ECMA 262 regular expression that the
instance MUST match in order to be valid.
5.2.2. minLength
The value of this keyword is an integer which defines the minimum
length of the instance.
5.2.3. maxLength
The value of this keyword is an integer which defines the maximum
length of the instance.
5.3. Keywords for array instances
5.3.1. minItems
The value of this keyword is an integer which defines the minimum
number of elements in the instance.
5.3.2. maxItems
The value of this keyword is an integer which defines the minimum
number of elements in the instance.
5.3.3. items
This keyword defines a set of allowed items in the instance. The
value of this keyword MUST be a schema or an array of schemas:
Zyp & Court Expires February 3, 2013 [Page 9]
Internet-Draft JSON Schema Media Type August 2012
if it is a schema, then all items in the instance MUST be valid
against this schema;
if it is an array of schemas, then the item at a given position in
the instance MUST be valid according to the corresponding schema
at the same position in the keyword value. This is called tuple
typing. Constraints on items in the instance which have no
corresponding schema in the keyword value are defined by
"additionalItems" (Section 5.3.4).
5.3.4. additionalItems
This keyword specifies how to handle items in the instance which are
is not explicitly defined by "items" (Section 5.3.3). Its value MUST
be a schema or a boolean. Boolean value true is equivalent to an
empty schema.
If "items" (Section 5.3.3) is present and its value is a schema,
"additionalItems" is ignored.
If "items" (Section 5.3.3) is defined and is an array of n elements,
then:
if "additionalItems" is false, then the instance is valid with
regards to this keyword if and only if it has at most n elements;
if "additionalItems" is a schema, then all instance elements of
index n or greater (assuming array indexes start at 0) MUST be
valid against this schema.
If "items" (Section 5.3.3) is not defined, then:
if "additionalItems" is false, then the instance is invalid;
if "additionalItems" is a schema, then all instance elements MUST
be valid against this schema.
The default value is an empty schema, which allows any value for
additional items.
5.3.5. uniqueItems
This keyword indicates that all items in the instance MUST be unique
(contains no two identical values).
Two JSON instances are consider equal if they are both of the same
type and:
Zyp & Court Expires February 3, 2013 [Page 10]
Internet-Draft JSON Schema Media Type August 2012
are null; or
are booleans/numbers/strings and have the same value; or
are arrays, contain 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
are objects, contain the same set of property names, and each
property in the object is equal to the corresponding property in
the other object.
5.4. Keywords for object instances
5.4.1. minProperties
The value of this keyword is a positive integer which defines the
minimum number of properties the instance must have.
5.4.2. maxProperties
The value of this keyword is a positive integer which defines the
maximum number of properties the instance must have.
5.4.3. properties
The value of this keyword is an object where:
property name match equivalent property names in the instance, if
any, and
property values are schemas.
If the instance has a property name which is equal to a property name
defined in this keyword, then the property value MUST be valid
against the corresponding schema.
Objects are unordered, therefore the order of the instance properties
or attribute properties MUST NOT determine validation success.
5.4.4. patternProperties
The value of this keyword is an object where:
property names are ECMA 262 regular expressions, and
property values are schemas.
Zyp & Court Expires February 3, 2013 [Page 11]
Internet-Draft JSON Schema Media Type August 2012
For each property name of the instance, if it is matched by one or
more regular expressions defined by this keyword, then the matching
value MUST be valid against all such schemas.
Note that regular expressions are not anchored.
5.4.5. additionalProperties
This keyword defines how to handle an instance's properties which
could not be matched by either "properties" (Section 5.4.3) or
"patternProperties" (Section 5.4.4) (here after referred to as
"additional properties"). Its value MUST be either a schema or a
boolean. Boolean value true is equivalent to an empty schema.
If the value of this keyword is false, then the instance is valid if
and only if there are no additional properties in the instance.
If the value of this keyword is a schema, then all additional
properties MUST be valid against this schema.
The default value is an empty schema, which allows any value for
additional properties.
5.4.6. required
The value of this keyword is an array of strings which defines all
the property names that must exist on the instance for it to be
valid.
5.4.7. dependencies
The value of this keyword is an object. Property names of this
object match equivalent property names in the instance, if any.
Property values are either of:
a string or an array of strings; in this case, the instance is
valid if and only if the instance has the corresponding property
name(s);
a schema; in this case, the instance is valid if and only if the
value of the corresponding property name is valid against this
schema.
5.4.8. Note on properties and patternProperties
It should be noted that validation by "properties" and
"patternProperties" are not exclusive: if a property name in an
instance is matched by both a property name in "properties" and one
Zyp & Court Expires February 3, 2013 [Page 12]
Internet-Draft JSON Schema Media Type August 2012
or more regular expressions in "patternProperties", then the
corresponding value MUST validate against all of these schemas.
5.5. Keywords for instances of any type
5.5.1. type
This keyword 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:
Simple Types A string indicating a primitive or simple type. The
string MUST be one of the following values:
object Instance MUST be an object.
array Instance MUST be an array.
string Instance MUST be a string.
number Instance MUST be a number, including floating point
numbers.
integer Instance MUST be an integer number (a positive or
negative natural number with no fractional or decimal
component).
boolean Instance MUST be a JSON boolean (true or false).
null Instance MUST be the JSON literal null. Note that without
this type, null values are not allowed.
any Instance MAY be of any type, including null.
Union Types An array of one or more simple types or schemas. 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.
If this attribute is not specified, then all value types are
accepted.
For example, a schema that defines if an instance can be a string or
a number would be:
{
"type": ["string", "number"]
}
Zyp & Court Expires February 3, 2013 [Page 13]
Internet-Draft JSON Schema Media Type August 2012
5.5.2. disallow
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.
5.5.3. format
This property helps to refine the type of data, content type, or
microformat an instance value must adhere to. A format attribute MAY
be one of the values listed below, and if so, SHOULD adhere to the
semantics describing for the format. A format SHOULD only be used to
give meaning to primitive types (string, integer, number, or
boolean). Validators MUST validate that instances conform to a
format.
A format attribute only validates a defined set of primitive types.
If the primitive type of the currently validated instance is not a
member of this set, the instance MUST be considered valid for this
keyword. All format attributes defined below are listed along with
the primitive types they validate.
The following formats are predefined:
date-time (string) This SHOULD be a date in ISO 8601 format of YYYY-
MM-DDThh:mm:ssZ in UTC time. This is the recommended form of
date/timestamp.
date (string) This SHOULD be a date in the format of YYYY-MM-DD. It
is recommended that you use the "date-time" format instead of
"date" unless you need to transfer only the date part.
time (string) This SHOULD be a time in the format of hh:mm:ss. It
is recommended that you use the "date-time" format instead of
"time" unless you need to transfer only the time part.
utc-millisec (number) This SHOULD be the difference, measured in
milliseconds, between the specified time and midnight, 00:00 of
January 1, 1970 UTC.
regex (string) This SHOULD be an ECMA 262 (ie, JavaScript) regular
expression.
phone (string) This SHOULD be a phone number (format MAY follow
E.123).
Zyp & Court Expires February 3, 2013 [Page 14]
Internet-Draft JSON Schema Media Type August 2012
uri (string) This value SHOULD be a URI.
email (string) This SHOULD be an email address.
ip-address (string) This SHOULD be an ip version 4 address.
ipv6 (string) This SHOULD be an ip version 6 address.
host-name (string) This SHOULD be a host-name.
5.5.4. enum
The value of this keyword is an array which provides an enumeration
of JSON instances. 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 "uniqueItems"
(Section 5.3.5).
The array MUST have at least one element. Elements in the array MUST
be unique.
5.5.5. extends
The value of this keyword 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.
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":
{
"description": "An adult",
"properties": {
"age": {
"minimum": 21
}
},
"extends": {"$ref": "person"}
}
Zyp & Court Expires February 3, 2013 [Page 15]
Internet-Draft JSON Schema Media Type August 2012
{
"description": "Extended schema",
"properties": {
"deprecated": {
"type": "boolean"
}
},
"extends": {"$ref": "http://json-schema.org/draft-04/schema"}
}
5.6. Metadata keywords
The following keywords do not play any role in instance validation
"per se", however three of them ("$ref", "id" and "$schema") play an
important role in the validation process.
5.6.1. default
This keyword defines the default value of the instance when the
instance is undefined.
Note that it is NOT required that the value of the instance matches
the enclosing schema.
5.6.2. title
This keyword is a string that provides a short description of the
instance property.
5.6.3. description
This keyword is a string that provides a full description of the of
purpose the instance property.
5.6.4. id
This keyword 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.
Zyp & Court Expires February 3, 2013 [Page 16]
Internet-Draft JSON Schema Media Type August 2012
5.6.5. $ref
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.
5.6.6. $schema
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 Hyper Schema (Section 6)links
(Section 6.1).
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.
6. Hyper Schema
The following attributes are specified in addition to those
attributes that already provided by the core schema with the specific
purpose of informing user agents of relations between resources based
on JSON data. Just as with JSON schema attributes, all the
attributes in hyper schemas are optional. Therefore, an empty object
is a valid (non-informative) schema, and essentially describes plain
JSON (no constraints on the structures). Addition of attributes
provides additive information for user agents.
6.1. links
The value of the links property MUST be an array, where each item in
the array is a link description object which describes the link
relations of the instances.
6.1.1. Link Description Object
A link description object is used to describe link relations. In the
context of a schema, it defines the link relations of the instances
of the schema, and can be parameterized by the instance values. The
link description format can be used without JSON Schema, and use of
Zyp & Court Expires February 3, 2013 [Page 17]
Internet-Draft JSON Schema Media Type August 2012
this format can be declared by referencing the normative link
description schema as the the schema for the data structure that uses
the links. The URI of the normative link description schema is:
http://json-schema.org/links (latest version) or
http://json-schema.org/draft-04/links (draft-04 version).
6.1.1.1. href
The value of the "href" link description property indicates the
target URI of the related resource. The value of the instance
property SHOULD be resolved as a URI-Reference per RFC 3986 [RFC3986]
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).
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.
For example, if an href value is defined:
http://somesite.com/{id}
Then it would be resolved by replace the value of the "id" property
value from the instance object.
If the value of the "id" property was "45", the expanded URI would
be:
http://somesite.com/45
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.
Zyp & Court Expires February 3, 2013 [Page 18]
Internet-Draft JSON Schema Media Type August 2012
6.1.1.2. rel
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.
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 RFC
4287 [RFC4287]). However, we define these relations here for clarity
of normative interpretation within the context of JSON hyper schema
defined relations:
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.
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.
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.
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.
The following relations are applicable for schemas (the schema as the
"from" resource in the relation):
instances This indicates the target resource that represents
collection of instances of a schema.
Zyp & Court Expires February 3, 2013 [Page 19]
Internet-Draft JSON Schema Media Type August 2012
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).
For example, if a schema is defined:
{
"links": [{
"rel": "self",
"href": "{id}"
}, {
"rel": "up",
"href": "{upId}"
}, {
"rel": "children",
"href": "?upId={id}"
}]
}
And if a collection of instance resource's JSON representation was
retrieved:
GET /Resource/
[{
"id": "thing",
"upId": "parent"
}, {
"id": "thing2",
"upId": "parent"
}]
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".
6.1.1.3. template
This property value is a string that defines the templating language
used in the "href" (Section 6.1.1.1) attribute. If no templating
language is defined, then the default Link Description Object
templating langauge (Section 6.1.1.1) is used.
Zyp & Court Expires February 3, 2013 [Page 20]
Internet-Draft JSON Schema Media Type August 2012
6.1.1.4. targetSchema
This property value is a schema that defines the expected structure
of the JSON representation of the target of the link.
6.1.1.5. Submission Link Properties
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.
6.1.1.5.1. method
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".
6.1.1.5.2. enctype
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).
For example, with the following schema:
{
"links": [{
"enctype": "application/x-www-form-urlencoded",
"method": "GET",
"href": "/Product/",
"properties": {
"name": {
"description": "name of the product"
}
}
}]
}
This indicates that the client can query the server for instances
that have a specific name.
Zyp & Court Expires February 3, 2013 [Page 21]
Internet-Draft JSON Schema Media Type August 2012
For example:
/Product/?name=Slinky
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.
6.1.1.5.3. schema
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).
6.2. fragmentResolution
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.
The fragment identifier is based on RFC 3986, Sec 5 [RFC3986], and
defines the mechanism for resolving references to entities within a
document.
6.2.1. json-pointer fragment resolution
The "json-pointer" fragment resolution protocol uses a JSON Pointer
[json-pointer] to resolve fragment identifiers in URIs within
instance representations.
6.3. readonly
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.
6.4. contentEncoding
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. RFC 2045, Sec 6.1
Zyp & Court Expires February 3, 2013 [Page 22]
Internet-Draft JSON Schema Media Type August 2012
[RFC2045] lists the possible values for this property.
6.5. pathStart
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 RFC 3986, Sec 5 [RFC3986], and is
relative to the instance's URI.
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.
6.6. mediaType
This attribute defines the media type of the instance representations
that this schema is defining.
7. Security Considerations
This specification is a sub-type of the JSON format, and consequently
the security considerations are generally the same as RFC 4627
[RFC4627]. 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.
For example, if a hyper schema was defined:
{
"links": [{
"rel": "self",
"href": "{id}"
}]
}
Zyp & Court Expires February 3, 2013 [Page 23]
Internet-Draft JSON Schema Media Type August 2012
And a resource was requested from somesite.com:
GET /foo/
With a response of:
Content-Type: application/json; profile=/schema-for-this-data
[{
"id": "bar",
"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"
}]
8. IANA Considerations
The proposed MIME media type for JSON Schema is "application/
schema+json".
Type name: application
Subtype name: schema+json
Required parameters: profile
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.
Optional parameters: pretty
Zyp & Court Expires February 3, 2013 [Page 24]
Internet-Draft JSON Schema Media Type August 2012
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.
8.1. Registry of Link Relations
This registry is maintained by IANA per RFC 4287 [RFC4287] and this
specification adds four values: "full", "create", "instances",
"root". New assignments are subject to IESG Approval, as outlined in
RFC 5226 [RFC5226]. Requests should be made by email to IANA, which
will then forward the request to the IESG, requesting approval.
9. References
9.1. Normative References
[RFC2045] Freed, N. and N. Borenstein,
"Multipurpose Internet Mail
Extensions (MIME) Part One: Format
of Internet Message Bodies",
RFC 2045, November 1996.
[RFC2119] Bradner, S., "Key words for use in
RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119,
March 1997.
[RFC3339] Klyne, G., Ed. and C. Newman,
"Date and Time on the Internet:
Timestamps", RFC 3339, July 2002.
[RFC3986] Berners-Lee, T., Fielding, R., and
L. Masinter, "Uniform Resource
Identifier (URI): Generic Syntax",
STD 66, RFC 3986, January 2005.
[RFC4287] Nottingham, M., Ed. and R. Sayre,
Ed., "The Atom Syndication
Format", RFC 4287, December 2005.
[json-pointer] Bryan, P. and K. Zyp, "JSON
Pointer", October 2012, <http://
tools.ietf.org/html/
draft-pbryan-zyp-json-pointer-02>.
Zyp & Court Expires February 3, 2013 [Page 25]
Internet-Draft JSON Schema Media Type August 2012
9.2. Informative References
[RFC2616] Fielding, R., Gettys, J., Mogul,
J., Frystyk, H., Masinter, L.,
Leach, P., and T. Berners-Lee,
"Hypertext Transfer Protocol --
HTTP/1.1", RFC 2616, June 1999.
[RFC4627] Crockford, D., "The application/
json Media Type for JavaScript
Object Notation (JSON)", RFC 4627,
July 2006.
[RFC5226] Narten, T. and H. Alvestrand,
"Guidelines for Writing an IANA
Considerations Section in RFCs",
BCP 26, RFC 5226, May 2008.
[I-D.hammer-discovery] Hammer-Lahav, E., "LRDD: Link-
based Resource Descriptor
Discovery",
draft-hammer-discovery-06 (work in
progress), May 2010.
[I-D.gregorio-uritemplate] Gregorio, J., Fielding, R.,
Hadley, M., Nottingham, M., and D.
Orchard, "URI Template",
draft-gregorio-uritemplate-08
(work in progress), January 2012.
[I-D.nottingham-http-link-header] Nottingham, M., "Web Linking", dra
ft-nottingham-http-link-header-10
(work in progress), May 2010.
[W3C.REC-html401-19991224] Hors, A., Raggett, D., and I.
Jacobs, "HTML 4.01 Specification",
World Wide Web Consortium Recommen
dation REC-html401-19991224,
December 1999, <http://www.w3.org/
TR/1999/REC-html401-19991224>.
[W3C.CR-CSS21-20070719] Hickson, I., Lie, H., Celik, T.,
and B. Bos, "Cascading Style
Sheets Level 2 Revision 1 (CSS
2.1) Specification", World Wide
Web Consortium CR CR-CSS21-
20070719, July 2007, <http://
www.w3.org/TR/2007/
Zyp & Court Expires February 3, 2013 [Page 26]
Internet-Draft JSON Schema Media Type August 2012
CR-CSS21-20070719>.
Appendix A. Change Log
draft-04
* Changed "required" attribute to an array of strings.
* Removed "format" attribute.
* Added "minProperties" and "maxProperties" attributes.
* Replaced "slash-delimited" fragment resolution with "json-
pointer".
* Added "template" LDO attribute.
* Removed irrelevant "Open Issues" section.
* Merged Conventions and Terminology sections.
* Defined terms used in specification.
* Restricted "type" to only the core JSON types.
* Renamed "divisibleBy" to "mod".
* Improved wording of many sections.
draft-03
* Added example and verbiage to "extends" attribute.
* Defined slash-delimited to use a leading slash.
* Made "root" a relation instead of an attribute.
* Removed address values, and MIME media type from format to
reduce confusion (mediaType already exists, so it can be used
for MIME types).
* Added more explanation of nullability.
* Removed "alternate" attribute.
* Upper cased many normative usages of must, may, and should.
Zyp & Court Expires February 3, 2013 [Page 27]
Internet-Draft JSON Schema Media Type August 2012
* Replaced the link submission "properties" attribute to "schema"
attribute.
* Replaced "optional" attribute with "required" attribute.
* Replaced "maximumCanEqual" attribute with "exclusiveMaximum"
attribute.
* Replaced "minimumCanEqual" attribute with "exclusiveMinimum"
attribute.
* Replaced "requires" attribute with "dependencies" attribute.
* Moved "contentEncoding" attribute to hyper schema.
* Added "additionalItems" attribute.
* Added "id" attribute.
* Switched self-referencing variable substitution from "-this" to
"@" to align with reserved characters in URI template.
* Added "patternProperties" attribute.
* Schema URIs are now namespace versioned.
* Added "$ref" and "$schema" attributes.
draft-02
* Replaced "maxDecimal" attribute with "divisibleBy" attribute.
* Added slash-delimited fragment resolution protocol and made it
the default.
* Added language about using links outside of schemas by
referencing its normative URI.
* Added "uniqueItems" attribute.
* Added "targetSchema" attribute to link description object.
draft-01
* Fixed category and updates from template.
Zyp & Court Expires February 3, 2013 [Page 28]
Internet-Draft JSON Schema Media Type August 2012
draft-00
* Initial draft.
Authors' Addresses
Kris Zyp (editor)
SitePen (USA)
530 Lytton Avenue
Palo Alto, CA 94301
USA
Phone: +1 650 968 8787
EMail: kris@sitepen.com
Gary Court
Calgary, AB
Canada
EMail: gary.court@gmail.com
Zyp & Court Expires February 3, 2013 [Page 29]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment