+ {{ content }}
+
+ {{ page.title | escape }}
+
+ {{ content }}
+
+
+The latest IETF published draft is v4. The specification is split into three parts: - -
-
| JSON Schema Core | -defines the basic foundation of JSON Schema | -
| JSON Schema Validation | -defines the validation keywords of JSON Schema | -
| JSON Hyper-Schema | -defines the hyper-media keywords of JSON Schema | -
They are also available on the IETF main site: core, validation and hyper-schema. -
The meta-schemas are the schemas which define the JSON Schema and Hyper-Schema formats. - -
-
| Core/Validation Meta-Schema | -Used for schemas written for pure validation. | -
| Hyper Meta-Schema | -Used for schemas written for validation and hyper-linking. | -
These sample schemas describe simple data structures which can be expressed as JSON: - -
-
| Geographic Coordinate | -a location as longitude and latitude | -
| Card | -a microformat-style representation of a person, company, organization, or place | -
| Calendar | -a microformat-style representation of an event | -
| Address | -a microformat-style representation of a street address | -
Let's pretend we're interacting with a JSON based product catalog. This catalog has a product which has an id, a name, a price, and an optional set of tags.
- -An example product in this API is:
- -
-{
- "id": 1,
- "name": "A green door",
- "price": 12.50,
- "tags": ["home", "green"]
-}
-
-
- While generally straightforward, that example leaves some open questions. For example, one may ask:
- -When you're talking about a data format, you want to have metadata about what fields mean, and what valid inputs for those fields are. JSON schema is a specification for standardizing how to answer those questions for JSON data.
-To start a schema definition, let's begin with a basic JSON schema:
- -
-{
- "$schema": "http://json-schema.org/draft-04/schema#",
- "title": "Product",
- "description": "A product from Acme's catalog",
- "type": "object"
-}
-
-
- The above schema has four properties called keywords. - - The title and description keywords are descriptive only, in that they do not add - constraints to the data being validated. The intent of the schema is stated with these two keywords - (that is, this schema describes a product).
- -The type keyword defines the first constraint on our JSON data: it has to be a JSON - Object.
- -Finally, the $schema keyword states that this schema is written according to the draft - v4 specification.
-Next let's answer our previous questions about this API, starting with id.
- -id is a numeric value that uniquely identifies a product. Since this is the canonical identifier for a product, it doesn't make sense to have a product without one, so it is required.
- -In JSON Schema terms, we can update our schema to:
-
-{
- "$schema": "http://json-schema.org/draft-04/schema#",
- "title": "Product",
- "description": "A product from Acme's catalog",
- "type": "object",
- "properties": {
- "id": {
- "description": "The unique identifier for a product",
- "type": "integer"
- }
- },
- "required": ["id"]
-}
-
-
- name is a string value that describes a product. Since there isn't - much to a product without a name, it also is required. Adding this gives us the schema:
- -
-{
- "$schema": "http://json-schema.org/draft-04/schema#",
- "title": "Product",
- "description": "A product from Acme's catalog",
- "type": "object",
- "properties": {
- "id": {
- "description": "The unique identifier for a product",
- "type": "integer"
- },
- "name": {
- "description": "Name of the product",
- "type": "string"
- }
- },
- "required": ["id", "name"]
-}
-
-
- According to Acme's docs, there are no free products. In JSON schema a number can have a minimum. By default this minimum is inclusive, so we need to specify exclusiveMinimum. Therefore we can update our schema with price:
- -
-{
- "$schema": "http://json-schema.org/draft-04/schema#",
- "title": "Product",
- "description": "A product from Acme's catalog",
- "type": "object",
- "properties": {
- "id": {
- "description": "The unique identifier for a product",
- "type": "integer"
- },
- "name": {
- "description": "Name of the product",
- "type": "string"
- },
- "price": {
- "type": "number",
- "minimum": 0,
- "exclusiveMinimum": true
- }
- },
- "required": ["id", "name", "price"]
-}
-
-
- Finally, we come to the tags property. Unlike the previous - properties, tags have many values, and is represented as a JSON array. According - to Acme's docs, all tags must be strings, but you aren't required to specify - tags. We simply leave tags out of the list of required properties.
- -However, Acme's docs add two constraints:
- -The first constraint can be added with minItems, and the second one by - specifying uniqueItems as being true:
- -
-{
- "$schema": "http://json-schema.org/draft-04/schema#",
- "title": "Product",
- "description": "A product from Acme's catalog",
- "type": "object",
- "properties": {
- "id": {
- "description": "The unique identifier for a product",
- "type": "integer"
- },
- "name": {
- "description": "Name of the product",
- "type": "string"
- },
- "price": {
- "type": "number",
- "minimum": 0,
- "exclusiveMinimum": true
- },
- "tags": {
- "type": "array",
- "items": {
- "type": "string"
- },
- "minItems": 1,
- "uniqueItems": true
- }
- },
- "required": ["id", "name", "price"]
-}
-
-The above example is by no means definitive of all the types of data JSON schema can define. For more definitive information see the full standard draft.
-As a final example, here's a spec for an array of products, with the products having 2 new properties. The first is a dimensions property for the size of the product, and the second is a warehouseLocation field for where the warehouse that stores them is geographically located.
-And also, since JSON Schema defines a reference schema for a geographic location, instead of coming up with our own, we'll reference the canonical one.
- -
-[
- {
- "id": 2,
- "name": "An ice sculpture",
- "price": 12.50,
- "tags": ["cold", "ice"],
- "dimensions": {
- "length": 7.0,
- "width": 12.0,
- "height": 9.5
- },
- "warehouseLocation": {
- "latitude": -78.75,
- "longitude": 20.4
- }
- },
- {
- "id": 3,
- "name": "A blue mouse",
- "price": 25.50,
- "dimensions": {
- "length": 3.1,
- "width": 1.0,
- "height": 1.0
- },
- "warehouseLocation": {
- "latitude": 54.4,
- "longitude": -32.7
- }
- }
-]
-
-
-
-{
- "$schema": "http://json-schema.org/draft-04/schema#",
- "title": "Product set",
- "type": "array",
- "items": {
- "title": "Product",
- "type": "object",
- "properties": {
- "id": {
- "description": "The unique identifier for a product",
- "type": "number"
- },
- "name": {
- "type": "string"
- },
- "price": {
- "type": "number",
- "minimum": 0,
- "exclusiveMinimum": true
- },
- "tags": {
- "type": "array",
- "items": {
- "type": "string"
- },
- "minItems": 1,
- "uniqueItems": true
- },
- "dimensions": {
- "type": "object",
- "properties": {
- "length": {"type": "number"},
- "width": {"type": "number"},
- "height": {"type": "number"}
- },
- "required": ["length", "width", "height"]
- },
- "warehouseLocation": {
- "description": "Coordinates of the warehouse with the product",
- "$ref": "http://json-schema.org/geo"
- }
- },
- "required": ["id", "name", "price"]
- }
-}
-
-This example shows a possible JSON representation of a hypothetical machine's mount points as
- represented in an /etc/fstab file.
An entry in the fstab file can have many different forms. Here is a possible representation of a - full fstab:
- -
-{
- "/": {
- "storage": {
- "type": "disk",
- "device": "/dev/sda1"
- },
- "fstype": "btrfs",
- "readonly": true
- },
- "/var": {
- "storage": {
- "type": "disk",
- "label": "8f3ba6f4-5c70-46ec-83af-0d5434953e5f"
- },
- "fstype": "ext4",
- "options": [ "nosuid" ]
- },
- "/tmp": {
- "storage": {
- "type": "tmpfs",
- "sizeInMB": 64
- }
- },
- "/var/www": {
- "storage": {
- "type": "nfs",
- "server": "my.nfs.server",
- "remotePath": "/exports/mypath"
- }
- }
-}
-
-
- Not all constraints to an fstab file can be modeled using JSON Schema alone; however, it can - already represent a good number of them. We will add constraints one after the other until we get to - a satisfactory result.
-We will start with a base schema expressing the following constraints:
- -/).We also want the schema to be regarded as a draft v4 schema, we must therefore specify - $schema:
- -
-{
- "$schema": "http://json-schema.org/draft-04/schema#",
- "type": "object",
- "properties": {
- "/": {}
- },
- "patternProperties": {
- "^(/[^/]+)+$": {}
- },
- "additionalProperties": false,
- "required": [ "/" ]
-}
-
-
- Note how the valid paths constraint is enforced here:
- -/ entry;/);/ or to match the regular expression.You will notice that the regular expression is explicitly anchored (with ^ and
- $): in JSON Schema, regular expressions (in patternProperties and in
- pattern) are not anchored by default.
For now, the schemas describing individual entries are empty: we will start describing the - constraints in the following paragraphs, using another schema, which we will reference from the main - schema when we are ready.
-Here again we will proceed step by step. We will start with the global structure of our schema, which will be as such:
- -
-{
- "id": "http://some.site.somewhere/entry-schema#",
- "$schema": "http://json-schema.org/draft-04/schema#",
- "description": "schema for an fstab entry",
- "type": "object",
- "required": [ "storage" ],
- "properties": {
- "storage": {
- "type": "object",
- "oneOf": [
- { "$ref": "#/definitions/diskDevice" },
- { "$ref": "#/definitions/diskUUID" },
- { "$ref": "#/definitions/nfs" },
- { "$ref": "#/definitions/tmpfs" }
- ]
- }
- },
- "definitions": {
- "diskDevice": {},
- "diskUUID": {},
- "nfs": {},
- "tmpfs": {}
- }
-}
-
-
- You should already be familiar with some of the constraints:
- -"type": "object");"required": [ "storage" ]);There are a couple of novelties:
- -Let's now extend this skeleton to add constraints to these three properties. Note that none of - them are required:
- -ext3, ext4 and btrfs as
- filesystem types;With these added constraints, the schema now looks like this:
- -
-{
- "id": "http://some.site.somewhere/entry-schema#",
- "$schema": "http://json-schema.org/draft-04/schema#",
- "description": "schema for an fstab entry",
- "type": "object",
- "required": [ "storage" ],
- "properties": {
- "storage": {
- "type": "object",
- "oneOf": [
- { "$ref": "#/definitions/diskDevice" },
- { "$ref": "#/definitions/diskUUID" },
- { "$ref": "#/definitions/nfs" },
- { "$ref": "#/definitions/tmpfs" }
- ]
- },
- "fstype": {
- "enum": [ "ext3", "ext4", "btrfs" ]
- },
- "options": {
- "type": "array",
- "minItems": 1,
- "items": { "type": "string" },
- "uniqueItems": true
- },
- "readonly": { "type": "boolean" }
- },
- "definitions": {
- "diskDevice": {},
- "diskUUID": {},
- "nfs": {},
- "tmpfs": {}
- }
-}
-
-
- For now, all definitions are empty (an empty JSON Schema validates all instances). We will write - schemas for individual definitions below, and fill these schemas into the entry schema.
-This storage type has two required properties, type and device. The type can - only be disk, and the device must be an absolute path starting with /dev. No other - properties are allowed:
- -
-{
- "properties": {
- "type": { "enum": [ "disk" ] },
- "device": {
- "type": "string",
- "pattern": "^/dev/[^/]+(/[^/]+)*$"
- }
- },
- "required": [ "type", "device" ],
- "additionalProperties": false
-}
-
-
- You will have noted that we need not specify that type must be a string: the constraint - described by enum is enough.
-This storage type has two required properties, type and label. The type can - only be disk, and the label must be a valid UUID. No other properties are allowed:
- -
-{
- "properties": {
- "type": { "enum": [ "disk" ] },
- "label": {
- "type": "string",
- "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
- }
- },
- "required": [ "type", "label" ],
- "additionalProperties": false
-}
-
-This storage type has three required properties: type, server and - remotePath. What is more, the server may be either a host name, an IPv4 address or an IPv6 - address.
- -For the constraints on server, we use a new keyword: format. While it is not - required that format be supported, we will suppose that it is here:
- -
-{
- "properties": {
- "type": { "enum": [ "nfs" ] },
- "remotePath": {
- "type": "string",
- "pattern": "^(/[^/]+)+$"
- },
- "server": {
- "type": "string",
- "oneOf": [
- { "format": "host-name" },
- { "format": "ipv4" },
- { "format": "ipv6" }
- ]
- }
- },
- "required": [ "type", "server", "remotePath" ],
- "additionalProperties": false
-}
-
-This storage type has two required properties: type and sizeInMB. The size can - only be an integer. What is more, we will require that the size be between 16 and 512, - inclusive:
- -
-{
- "properties": {
- "type": { "enum": [ "tmpfs" ] },
- "sizeInMB": {
- "type": "integer",
- "minimum": 16,
- "maximum": 512
- }
- },
- "required": [ "type", "sizeInMB" ],
- "additionalProperties": false
-}
-
-The resulting schema is quite large:
-
-{
- "id": "http://some.site.somewhere/entry-schema#",
- "$schema": "http://json-schema.org/draft-04/schema#",
- "description": "schema for an fstab entry",
- "type": "object",
- "required": [ "storage" ],
- "properties": {
- "storage": {
- "type": "object",
- "oneOf": [
- { "$ref": "#/definitions/diskDevice" },
- { "$ref": "#/definitions/diskUUID" },
- { "$ref": "#/definitions/nfs" },
- { "$ref": "#/definitions/tmpfs" }
- ]
- },
- "fstype": {
- "enum": [ "ext3", "ext4", "btrfs" ]
- },
- "options": {
- "type": "array",
- "minItems": 1,
- "items": { "type": "string" },
- "uniqueItems": true
- },
- "readonly": { "type": "boolean" }
- },
- "definitions": {
- "diskDevice": {
- "properties": {
- "type": { "enum": [ "disk" ] },
- "device": {
- "type": "string",
- "pattern": "^/dev/[^/]+(/[^/]+)*$"
- }
- },
- "required": [ "type", "device" ],
- "additionalProperties": false
- },
- "diskUUID": {
- "properties": {
- "type": { "enum": [ "disk" ] },
- "label": {
- "type": "string",
- "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
- }
- },
- "required": [ "type", "label" ],
- "additionalProperties": false
- },
- "nfs": {
- "properties": {
- "type": { "enum": [ "nfs" ] },
- "remotePath": {
- "type": "string",
- "pattern": "^(/[^/]+)+$"
- },
- "server": {
- "type": "string",
- "oneOf": [
- { "format": "host-name" },
- { "format": "ipv4" },
- { "format": "ipv6" }
- ]
- }
- },
- "required": [ "type", "server", "remotePath" ],
- "additionalProperties": false
- },
- "tmpfs": {
- "properties": {
- "type": { "enum": [ "tmpfs" ] },
- "sizeInMB": {
- "type": "integer",
- "minimum": 16,
- "maximum": 512
- }
- },
- "required": [ "type", "sizeInMB" ],
- "additionalProperties": false
- }
- }
-}
-
-Now that all possible entries have been described, we can refer to the entry schema from our main - schema. We will, again, use a JSON Reference here:
- -
-{
- "$schema": "http://json-schema.org/draft-04/schema#",
- "type": "object",
- "properties": {
- "/": { "$ref": "http://some.site.somewhere/entry-schema#" }
- },
- "patternProperties": {
- "^(/[^/]+)+$": { "$ref": "http://some.site.somewhere/entry-schema#" }
- },
- "additionalProperties": false,
- "required": [ "/" ]
-}
-
-This example is much more advanced than the previous example; you will have learned of schema - referencing and identification, you will have been introduced to other keywords. There are also a - few additional points to consider.
- -This is only an example for learning purposes. Some additional constraints could be described. - For instance:
- -/ to be mounted on a tmpfs filesystem;As an exercise, you can always try and add these constraints. It would probably require splitting - the schema further.
- -JSON Schema limits itself to describing the structure of JSON data, it cannot express functional - constraints.
- -If we take an NFS entry as an example, JSON Schema alone cannot check that the submitted NFS - server's hostname, or IP address, is actually correct: this check is left to applications.
- -While this is not a concern if you know that the schema you write will be used by you alone, you - should keep this in mind if you write a schema which other people can potentially use. The schema we - have written here has some features which can be problematic for portability:
- -Here is a basic example of a JSON Schema: -
-{
- "title": "Example Schema",
- "type": "object",
- "properties": {
- "firstName": {
- "type": "string"
- },
- "lastName": {
- "type": "string"
- },
- "age": {
- "description": "Age in years",
- "type": "integer",
- "minimum": 0
- }
- },
- "required": ["firstName", "lastName"]
-}
-
-The two examples below are step-by-step guides into building a schema: -
The Space Telescope Science Institute has also published an guide aimed at schema authors. -
Implementations below are written in different languages, and support part, or all, of the - specification.
- -Implementations below are classified based on their functionality. When known, the - license of the project is also mentioned.
- -If you have updates to this list, Look at the GitHub repo - under the gh-pages branch
-| JSON Schema | -describes your JSON data format | -
| JSON Hyper-Schema | -turns your JSON data into hyper-text | -
Interested? Check out: -
Questions? Feeling helpful? Get involved on: -
The latest draft is v4. The specification is split into three parts: +
The latest IETF published draft is v4. The specification is split into three parts:
They are also available as Internet Drafts on the IETF site: core, validation and hyper-schema. +
They are also available on the IETF main site: core, validation and hyper-schema.
Let's pretend we're interacting with a JSON based product catalog. This catalog has a product which has an id, a name, a price, and an optional set of tags.
@@ -211,7 +184,7 @@The above example is by no means definitive of all the types of data JSON schema can define. For more definitive information see the full standard draft.
+The above example is by no means definitive of all the types of data JSON schema can define. For more definitive information see the full standard draft.
As a final example, here's a spec for an array of products, with the products having 2 new properties. The first is a dimensions property for the size of the product, and the second is a warehouseLocation field for where the warehouse that stores them is geographically located.
And also, since JSON Schema defines a reference schema for a geographic location, instead of coming up with our own, we'll reference the canonical one.
@@ -237,7 +210,7 @@This example shows a possible JSON representation of a hypothetical machine's mount points as
represented in an /etc/fstab file.
Here is a basic example of a JSON Schema:
@@ -63,9 +35,4 @@Walkthroughs
The Space Telescope Science Institute has also published an guide aimed at schema authors. -
Implementations below are written in different languages, and support part, or all, of the specification.
Implementations below are classified based on their functionality. When known, the license of the project is also mentioned.
+ +If you have updates to this list, Look at the GitHub repo + under the gh-pages branch
| TOC |
|
- JSON Schema is a JSON based format for defining the structure of JSON data. - This document specifies hyperlink- and hypermedia-related keywords for the JSON Schema format. - -
--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 March 30, 2013.
- --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 -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.
-
-1.
-Introduction
-2.
-Conventions and Terminology
-3.
-Overview
- 3.1.
-Design Considerations
-4.
-Keywords
- 4.1.
-links
- 4.1.1.
-Link Description Object
- 4.2.
-fragmentResolution
- 4.2.1.
-json-pointer fragment resolution
- 4.3.
-media
- 4.3.1.
-contentEncoding
- 4.3.2.
-mediaType
- 4.4.
-pathStart
-5.
-Security Considerations
- 5.1.
-"self" links
- 5.2.
-"mediaType" property of Link Description Objects
- 5.3.
-"targetSchema" property of Link Description Objects
- 5.4.
-"invalidates" property of Link Description Objects
-6.
-IANA Considerations
- 6.1.
-Registry of Link Relations
-7.
-References
- 7.1.
-Normative References
- 7.2.
-Informative References
-Appendix A.
-Change Log
-
| TOC |
- JSON Schema is a JSON based format for defining the structure of JSON data. - This document specifies hyperlink- and hypermedia-related keywords for the JSON Schema format. - -
-| TOC |
- - - 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 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [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 (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) [RFC4627]. - -
-- This specification also uses the following defined terms: - -
--
- schema
-- A JSON Schema object. -
-- instance
-- Equivalent to "JSON value" as defined in RFC 4627 (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) [RFC4627]. -
-- property
-- Equivalent to "member" as defined in RFC 4627 (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) [RFC4627]. -
-- item
-- Equivalent to "element" as defined in RFC 4627 (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) [RFC4627]. -
-- attribute
-- A property of a JSON Schema object. -
-
- -
-| TOC |
- JSON Schema defines the media type "application/schema+json". - JSON Schemas are also written in JSON and include facilities for describing the structure of JSON data in terms of allowable values, descriptions, and interpreting relations with other resources. - -
-- This document describes how JSON Schema can be used to define hyperlinks on instance data, and to define how to interpret JSON data as rich multimedia documents. - -
-- Just as with the core JSON schema attributes, all the attributes described here are optional. - Therefore, an empty object is a valid (non-informative) schema, and essentially describes plain JSON. - Addition of attributes provides additive information for user agents. - -
-An example JSON Schema defining hyperlinks, and providing hypermedia interpretation for one of the properties is: -
-
-{
- "title": "Written Article",
- "properties": {
- "id": {
- "title": "Article Identifier",
- "type": "number"
- },
- "title": {
- "title": "Article Title",
- "type": "string"
- },
- "author": {
- "type": "integer"
- },
- "imgData": {
- "title": "Article Illustration (small)",
- "type": "string",
- "media": {
- "contentEncoding": "base64",
- "mediaType": "image/png"
- }
- }
- },
- "required" : ["id", "title", "author"],
- "links": [
- {
- "rel": "full",
- "href": "{id}"
- },
- {
- "rel": "author",
- "href": "/user?id={author}"
- }
- ]
-}
-
-- This schema defines the properties of the instance, as well as a hypermedia interpretation for the "imgData" property. - It also defines link relations for the instance, with URIs incorporating values from the instance. - -
-| TOC |
- In addition to the design considerations for the core JSON Schema specification: - -
-- 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. - -
-| TOC |
- The following properties are defined for JSON Schema objects: - -
-| TOC |
- The property of schemas is used to associate Link Description Options with instances. The value of this property MUST be an array, and the items in the array must be Link Description Objects, as defined below. - -
-An example schema using the links keywords could be: -
-
-{
- "title": "Schema defining links",
- "links": [
- {
- "rel": "full",
- "href": "{id}"
- },
- {
- "rel": "parent",
- "href": "{parent}"
- }
- ]
-}
-
-| TOC |
- 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 this format can be declared by referencing the normative link description schema as 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). - -
-| TOC |
- 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 (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.) [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. - The property name between the braces SHOULD be percent encoded (FIXME reference?). - In particular, the character for the braces ('{' and '}') as well as the percent sign ('%') MUST be encoded, such that decoding the text obtains the correct property name. - - -
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 - -
| TOC |
Values may only be used for substitution if they are of a scalar type (string, boolean or number). -
-In cases where suitable values do not exist for substitution because they are of an incorrect type, then they should be treated as if the values were missing, and substitute values MAY be provided from alternate sources, like user input. -
-| TOC |
- 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 link relation from the top level resource to a target 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 (Nottingham, M., Ed. and R. Sayre, Ed., “The Atom Syndication Format,” December 2005.) [RFC4287]). - However, we define these relations here for clarity of normative interpretation within the context of JSON 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 instance that contains this link may not be the full representation. - -
-- describedBy
-- - This indicates the target of the link is a schema describing 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 a collection of instances of a schema. - -
-- 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). - -
-
- - Links defined in the schema using these relation values SHOULD not require parameterization with data from the instance, as they describe a link for the schema, not the instances. - -
-- -
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 resources were retrieved with JSON representation: -
-
-GET /Resource/
-
-[{
- "id": "thing",
- "upId": "parent"
-}, {
- "id": "thing2",
- "upId": "parent"
-}]
-
-Note that these relationship values are case-insensitive, consistent with their use in HTML and the HTTP Link header (Nottingham, M., “Web Linking,” May 2010.) [I‑D.nottingham‑http‑link‑header]. -
-| TOC |
- This property value is a string that defines the templating language used in the "href" (href) attribute. - If no templating language is defined, then the default Link Description Object templating language (href) is used. - -
-| TOC |
- This property value is advisory only, and is a schema that defines the expected structure of the JSON representation of the target of the link, if the target of the link is returned using JSON representation. - -
-| TOC |
- The value of this property is advisory only, and represents the media type RFC 2046 (Freed, N. and N. Borenstein, “Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types,” November 1996.) [RFC2046], that is expected to be returned when fetching this resource. - This property value MAY be a media range instead, using the same pattern defined in RFC 2161, section 14.1 - HTTP "Accept" header (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.) [RFC2616]. - -
-- This property is analogous to the "type" property of elements in HTML 4.01 (advisory content type), or the "type" parameter in the HTTP Link header (Nottingham, M., “Web Linking,” May 2010.) [I‑D.nottingham‑http‑link‑header]. - User agents MAY use this information to inform the interface they present to the user before the link is followed, but this information MUST NOT use this information in the interpretation of the resulting data. - When deciding how to interpret data obtained through following this link, the behaviour of user agents MUST be identical regardless of the value of the this property. - -
-- If this property's value is specified, and the link's target is to be obtained using any protocol that supports the HTTP/1.1 "Accept" header RFC 2616, section 14.1 (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.) [RFC2616], then user agents MAY use the value of this property to aid in the assembly of that header when making the request to the server. - -
-- If this property's value is not specified, then the value should be taken to be "application/json". - -
-- -
For example, if a schema is defined: -
-
-{
- "links": [{
- "rel": "self",
- "href": "/{id}/json"
- }, {
- "rel": "alternate",
- "href": "/{id}/html",
- "mimeType": "text/html"
- }, {
- "rel": "alternate",
- "href": "/{id}/rss",
- "mimeType": "application/rss+xml"
- }, {
- "rel": "icon",
- "href": "{id}/icon",
- "mimeType": "image/*"
- }]
-}
-
-- A visual user agent displaying the item from the above example might present a button representing an RSS feed, which when pressed passes the target URI (calculated "href" value) to an view more suited to displaying it, such as a news feed aggregator tab. - -
-- Note that presenting the link in the above manner, or passing the URI to a news feed aggregator view does not constitute interpretation of the data, but an interpretation of the link. - The interpretation of the data itself is performed by the news feed aggregator, which SHOULD reject any data that would not have also been interpreted as a news feed, had it been displayed in the main view. - -
-| TOC |
- The value of this property is advisory only, and represents a URI or set of URIs which may change in response to this link being followed. Its value must be either a string or an array. - -
-- If this property value is a string, then when the link is followed, this value should be filled out as a template and resolved to a full URI using the same method as used for the "href (href)" property. - Any stored data fetched from a URI matching this value MAY then be considered out-of-date by the client, and removed from any cache. - -
-- If this property is an array, then its entries MUST be strings, each of which is treated according to the above behaviour. - -
-| TOC |
- 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. - -
-| TOC |
- This attribute defines which method can be used to access the target resource. - In an HTTP environment, this could 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". - -
-| TOC |
- 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. -
- - -For example: -
- -/Product/?name=Slinky - -
| TOC |
- 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. - -
-| TOC |
- 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 (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.) [RFC3986], and defines the mechanism for resolving references to entities within a document. - -
-- Note that if the instance is described by a schema providing the a link with "root" relation, or such a link is provided in using the HTTP Link header, then all fragment resolution should be resolved relative to the target of the root link. - The only exception to this is the resolution of "root" links themselves. - -
-| TOC |
- The "json-pointer" fragment resolution protocol uses a JSON Pointer (Bryan, P. and K. Zyp, “JSON Pointer,” October 2011.) [json‑pointer] to resolve fragment identifiers in URIs within instance representations. - -
-| TOC |
- The value of this attribute MUST be an object. It MAY contain any of the following properties: - -
-| TOC |
- The value of this property SHOULD be ignored for any instance that is not a string. - If the instance value is a string, this attribute defines that the string SHOULD be interpreted as binary data and decoded using the encoding named by this property. - RFC 2045, Sec 6.1 (Freed, N. and N. Borenstein, “Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies,” November 1996.) [RFC2045] lists the possible values for this property. - -
-| TOC |
- The value of this property must be a media type RFC 2046 (Freed, N. and N. Borenstein, “Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types,” November 1996.) [RFC2046]. - This attribute defines the media type of instances which this schema defines. - -
-- If the "contentEncoding" property is not set, but the instance value is a string, then the value of this property SHOULD specify a text document, and the character set SHOULD be considered to be UTF-8. - -
-- -
For example: -
-
-{
- "type": "string",
- "media": {
- "contentEncoding": "base64",
- "mediaType": "image/png"
- }
-}
-
-Instances described by this schema should be strings, and their values should be interpretable as base64-encoded PNG images. -
- - -Another example: -
-
-{
- "type": "string",
- "media": {
- "mediaType": "text/html"
- }
-}
-
-Instances described by this schema should be strings containing HTML, using the UTF-8 character set. -
- - -| TOC |
- 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 (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.) [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 considered to describe the instance. - Any schema that does not have a pathStart attribute SHOULD be considered applicable to all the instances for which it is referenced. - -
-| TOC |
- This specification is a sub-type of the JSON format, and consequently the security considerations are generally the same as RFC 4627 (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) [RFC4627]. - However, there are additional security concerns when using the hyperlink definitions. - -
-| TOC |
- 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}"
- }]
-}
-
-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"
-}]
-
-| TOC |
- The "mediaType" property in link definitions defines the expected format of the link's target. - However, this is advisory only, and MUST NOT be considered authoritative. - User agents MAY use this information to determine how they represent the link or where to display it (for example hover-text, opening in a new tab). - If user agents decide to pass the link to an external program, they SHOULD first verify that the data is of a type that would normally be passed to that external program. - -
-- When choosing how to interpret data, the type information provided by the server (or inferred from the filename, or any other usual method) MUST be the only consideration, and the "mimeType" property of the link MUST NOT be used. - -
-- This is to guard against situations where a source is providing data that is safe when interpreted as the correct type (for example plain text), but that could be damaging if a third party were allowed to provide a different interpretation (such as client-side code). - -
-| TOC |
- Since, through the "media" keyword, schemas can provide interpretations of string data, exactly the same considerations apply for this keyword as for the "mediaType" keyword of Link Description Objects. - -
-| TOC |
- User agents also MUST NOT fetch the target of a link when the resulting data is validated, unless the user has already explicitly or implicitly indicated them to do so. - If the user's intentions are not known, then the user agent SHOULD NOT refetch the data unless the target of the link is a sub-path of the URI being invalidated. - (See above for a discussion of how to determine if one path is a sub-path of another.) - -
-- This is to guard against the possibility of tricking user agents into making requests on behalf of the user, to track their behaviour. - -
-| TOC |
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 -
-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. -
-| TOC |
- This registry is maintained by IANA per RFC 4287 (Nottingham, M., Ed. and R. Sayre, Ed., “The Atom Syndication Format,” December 2005.) [RFC4287] and this specification adds four values: "full", "create", "instances", "root". - New assignments are subject to IESG Approval, as outlined in RFC 5226 (Narten, T. and H. Alvestrand, “Guidelines for Writing an IANA Considerations Section in RFCs,” May 2008.) [RFC5226]. - Requests should be made by email to IANA, which will then forward the request to the IESG, requesting approval. - -
-| TOC |
| TOC |
| [RFC2045] | -Freed, N. and N. Borenstein, “Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies,” RFC 2045, November 1996 (TXT). |
| [RFC2119] | -Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML). |
| [RFC3339] | -Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” RFC 3339, July 2002 (TXT, HTML, XML). |
| [RFC3986] | -Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” STD 66, RFC 3986, January 2005 (TXT, HTML, XML). |
| [RFC4287] | -Nottingham, M., Ed. and R. Sayre, Ed., “The Atom Syndication Format,” RFC 4287, December 2005 (TXT, HTML, XML). |
| [json-pointer] | -Bryan, P. and K. Zyp, “JSON Pointer,” October 2011. |
| TOC |
| [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 (TXT, PS, PDF, HTML, XML). |
| [RFC4627] | -Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” RFC 4627, July 2006 (TXT). |
| [RFC5226] | -Narten, T. and H. Alvestrand, “Guidelines for Writing an IANA Considerations Section in RFCs,” BCP 26, RFC 5226, May 2008 (TXT). |
| [RFC2046] | -Freed, N. and N. Borenstein, “Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types,” RFC 2046, November 1996 (TXT). |
| [I-D.hammer-discovery] | -Hammer-Lahav, E., “LRDD: Link-based Resource Descriptor Discovery,” draft-hammer-discovery-06 (work in progress), May 2010 (TXT). |
| [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 (TXT). |
| [I-D.nottingham-http-link-header] | -Nottingham, M., “Web Linking,” draft-nottingham-http-link-header-10 (work in progress), May 2010 (TXT). |
| [W3C.REC-html401-19991224] | -Hors, A., Raggett, D., and I. Jacobs, “HTML 4.01 Specification,” World Wide Web Consortium Recommendation REC-html401-19991224, December 1999 (HTML). |
| [W3C.CR-CSS21-20070719] | -Hickson, I., Lie, H., Çelik, 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 (HTML). |
| TOC |
-
--
- draft-04
-- - -
--
- -- Split hyper-schema definition out from main schema. -
-- Removed "readonly" -
-- Capitalised the T in "encType" -
-- Moved "mediaType" and "contentEncoding" to the new "media" property -
-- Added "mediaType" property to LDOs -
-- Added "invalidates" property to LDOs -
-- Replaced "slash-delimited" fragment resolution with - "json-pointer". -
-- Added "template" LDO attribute. -
-- Improved wording of 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. -
-- 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. -
-- draft-00
-- - -
--
- -- Initial draft. -
-
- -
-| TOC |
| - | 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 |
| - | Geraint Luff |
| t |