The Hyper Schema Media Type

This proposal defines a format for describing the structure of hypertext
linking and metadata information in JSON-based media types with JSON
Schema (suggested to be application/json+schema). The mechanism for
defining links and metadata can be applied to any JSON media type, and
enables hypertext navigation through data structures that are
represented by JSON. This proposal does not require target JSON media
types (those being described by the hyper-schemas) to follow any
specific structure.

1. Introduction

Hyper Schema media documents builds on JSON Schema to provide a format
for describing the structure of other JSON representations (instances).
This schema can be used to define the required type and constraints on
property values, as well as define the meaning of the property values
for the purpose of describing a resource and determining hyperlinks
within the representation. Hyper Schema acts as a meta-document.

1.1. Design Considerations

This media type does not attempt to dictate the structure of JSON
representations that contain data, but rather provides a separate format
for flexibly communicating how a JSON representation should be
interpreted, such that user agents can extrapolate hyperlink information
with the JSON document. This specification does not define a protocol.
The underlying protocol (such as HTTP) should sufficiently define the
semantics of the client server interaction and the retrieval of resource
represenations linked to by JSON representations. The goal of this
format is to sufficiently describe JSON structures such that one can
utilize latent identification information available in existing JSON
representations from a large variety of services that leverage a REST
architecture using existing protocols.


1.2.  Conventions Used in This Document

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 [RFC2119].

The grammatical rules in this document are to be interpreted as
described in [RFC4234].
  
1.3. Terminology

JSON hyper schemas are an extended form of JSON schema
(http://www.json-schema.org) with attributes specifically designed for
defining the meaning of JSON properties in JSON representations.

An instance representation is a JSON structure that is described by the
hyper-schema.

1.4. Associating instances with schemas.

Instance representations may be of the application/json media type or
any other subtype. Consequently, dictating how an instance
representation should specify its schema is beyond the normative scope
of this document (since this document specifically defines the JSON
hyper schema media type, no other), but it is recommended that instances
specify their schema so that user agents can interpret the instance
representation and messages may retain the self-descriptive
characteristic, avoiding the need for out-of-band information about
instance data. Two approaches are recommended for declaring the
hyper-schema that describes the meaning of a JSON instance's structure
or a collection of instance's structure. A MIME type parameter named
"schema" or a Link header with a relationship of "schema" SHOULD be used:

Content-Type: application/json; schema=http://json.com/my-hyper-schema

or if the content is being transferred by a protocol (such as HTTP) that
provides headers, the Link header can be used:

Link: <http://json.com/my-hyper-schema>; rel="schema"

1.5. Self-descriptive hyper schema

Hyper schemas are themselves instances for the hyper schema for hyper
schemas. A self-describing JSON hyper schema for JSON hyper schemas can
be found at http://json-schema.org/hyper-schema. All hyper schemas
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;
schema=http://www.json-schema.org/hyper-schema

2. A hyper schema defines the following attributes in addition to those
attributes that already provided by JSON schema. Just as with JSON
schema attributes, all the attributes in hyper-schema 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.

2.1 hrefProperty

This defines the name of the property that indicates a hyperlink
throughout the hierarchy of instance JSON representations. When this
property is encountered in the instance object or any of it’s child
objects (or arrays), the value of the property indicates target URI of
the hyperlink and is resolved per RFC 2396. The object may include other
properties providing a partial/summary representation of the target
resource. The name of property in which the value is found should imply
the relationship name of the link. For example, if a schema is defined:

{
    "hrefProperty": "href"
}

If an instance resource's JSON representation is:

{
    "name": "A resource",
    "up": {"href": "http://somesite.com/parent"}
}

This would indicate that the "up" property value SHOULD be resolved to
the resource at "http://somesite.com/parent". Implicitly the given
resource is linked to "http://somesite.com/parent" by an "up" relationship.

2.2. link

This indicates that the value of the given instance property is a URI
that should be interpreted as link. The value of this schema property
indicates the name of the relationship to the linked target. The value
of the instance property should be resolved as a URI resolved per RFC 2396.

If the relation value is "self", when this property is encountered in
the instance object, the object represents a resource and the object is
treated as a full representation of the target resource identified by
the specified URI.

For example, if a schema is defined:
{
    "properties": {
        "id": {
            "link": "self"
        },
        "up_id": {
            "link": "up"
        }
    }
}
And if a collection of instance resource's JSON representation was
retrieved:
GET /Resource/

[
    {
        "id": "thing",
        "up_id": "parent"
    },
    {
        "id": "thing2",
        "up_id": "parent"
    }
]
This would indicate that for the first item in the collection, it's own
(self) URI would resolve to /Resource/thing and the first item's "up"
relationship should be resolved to the resource at "/Resource/parent".

2.3. baseURI

This property indicates the baseURI to use to resolve URIs (RFC 2396).
Relative URIs can then be resolved using this resolved URI as a context.
The baseURI value itself can be a relative URI as well (and resolved
according to its context).

2.4. instances

When present, the value of this property MUST be the collection of
instances of this defined schema. This will generally be a link to the
collection URI, by which user agents SHOULD be able to retrieve the
instances with a GET (and possibly query for specific instances), and
user agents SHOULD be able to POST to this target to create new
instances (if such an action is allowed).

2.5 queryEncoding

This property indicates the query encoding format that the server
supports for querying the collection of instances. The query can be
suffixed to the collection URI to query the collection with
property-based constraints on the resources that SHOULD be returned from
the server. For example, with the following schema:
{
    "queryEncoding": "application/x-www-form-urlencoded",
    "instances":{"$ref":"/Product/"},
    "properties":{
        "name":{"description":"name of the product"}
    }
}
This indicates that the client can query the server for instances that
have a specific name:
/Product/?name=Slinky

2.6. 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 "dot-delimited", which is defined below. Other fragment
resolution protocols may include JSONPath.

The fragment identifier is based on RFC 2396 Sec 5, and defines the
mechanism for resolving references to entities within a document.

2.6.1. "dot-delimited" fragment resolution

With the dot-delimited fragment resolution protocol, the fragment
identifier is interpreted as a series of property reference tokens that
are delimited by the "." character (\x2E). Each property reference token
is a series of any characters except the "." character. Each property
reference token should be interpreted, starting from the beginning of
the fragment identifier, as a path reference in the target JSON
structure. The final target value of the fragment can be determined by
starting with the root of the JSON structure from the representation of
the resource identified by the pre-fragment URI. If the target is a JSON
object, than the new target is the value of the property with the name
identified by the next property reference token in the fragment. If the
target is a JSON array, than the target is determined by finding the
item in array the array with the index defined by the next property
reference token (which MUST be a number). The target is successively
updated for each property reference token, until the entire fragment has
been traversed.

For example, for the following JSON representation:

{
   "foo":{
      "anArray":[
        {"prop":44}
      ],
      "another prop":{
          "baz":"A string"
      }
   }
}
The following fragment identifiers would be resolved:

fragment identifier    resolution
#            self (the root of the resource itself)
#foo            the object referred to by the foo property
#foo.another prop    the object referred to by the "another prop"
property of the object referred to by the foo property
#foo.another prop.baz    the string referred to by the value of "baz"
property of the "another prop" property of the object referred to by the
foo property
#foo.anArray.0        the first object in the "anArray" array

2.7. root

This attribute indicates that the value of the instance property value
SHOULD be treated as the root or the body of the representation for the
purposes of user agent interaction and fragment resolution (all other
properties of the instance objects are can be regarded as metadata
descriptions for the data).

2.8. uriTemplate
This property may be used in conjunction with a link property to
indicate how the target URI should be constructed. The URI should be
constructed using the URI template provided by the value in combination
with the property values of the instance object as variables per
http://bitworking.org/projects/URI-Templates/spec/draft-gregorio-uritemplate-03.txt.
For example:
{
    "properties": {
        "children": {
            "link":"children",
            "uriTemplate": "?up_id={id}"
        }
    }
}

3. Security Considerations

This specification is primarily a sub-type of the JSON format, and 
consequently the security considerations are generally the same as RFC
4627. However, an additional issue is that when link relationship 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 subpath of the the URI used to request the resource 
represenation which contains the target URI with the "self" link.
For example, if a hyper schema was defined:
{
  "properties":{
    "id":{"link":"self"}
  }
}
And a resource was requested from somesite.com:
GET /foo/

With a response of:
Content-Type: application/json; schema=/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",

4. IANA Considerations

   The suggested MIME media type for a Hyper Schema is
application/json+schema.

   Type name: application

   Subtype name: json+schema

   Required parameters: n/a

   Optional parameters: schema

5. Normative References

[JSON]		Crockford, D., "JavaScript Object Notation", RFC 4627, July 2006

[JSON SCHEMA]	Zyp, K., "JSON Schema Proposal"

Author's Address

  Kris Zyp
  SitePen
  kris@sitepen.com