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 interface 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 "describedby" 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="describedby"

Instances MAY specify multiple schemas, to indicate all the schemas that 
are applicable to the data. The instance data may have multiple schemas 
that it is defined by (the instance data should be valid for those schemas). 
Or if the document is a collection of instances, the collection contain 
instances from different schemas. When collections can heterogenous 
instances, the pathStart (section 2.8) attribute MAY be specified in the 
schema to disambiguate which schema should be applied for each item in the 
collection.

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 [RFC3986]. 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-Reference per [RFC3986]. The relationship to the target should be interpreted as specifically from the instance object that holds this property, 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 relationship with the target. A relationship to target from the top level resource must be indicated with a top level property in the JSON representation.

Relationship definitions SHOULD NOT be media type dependent, and users are encouraged to utilize existing accepted relationship definitions, including those in existing relationship registries. However, we define these relationship here for clarity of normative interpretation within the context of JSON hyper schema defined relationships:
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.

edit or full - This indicates that the target of the link is the full representation for the instance object. The object that contains this link may not be the full representation.

describedby - This indicates the target of the link is the schema for the instance object.

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".

schema - "schema" defines the relationship of instance object to its schema. This may be used to specifically denote the schemas of objects within a JSON object hierarchy, facilitating polymorphic type data structures.

2.3. baseURI

This property indicates the base URI to use to resolve URIs per [RFC3986].
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
per [RFC3986]).

2.4. 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, but are not defined in this
document.

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

2.4.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. 

Property names SHOULD be URI-encoded. In particular, any "." in a 
property name MUST be encoded to avoid being interpreted as a property 
delimiter.

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.5. 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.6. pathStart

This property value is a URI-Reference that indicates the URI that all 
the URIs for the instances of the schema should start with. 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 URI of the instance begins with the pathStart's referenced 
URI. pathStart MUST be resolved as per [RFC3986] section 5. If the URI of 
the instance does not start with URI indicated by pathStart, 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.

2.7 forms

This is an array of JSON Form definitions that define any additional interaction that can be done for querying and/or posting data back to the server.

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. JSON Forms:

JSON Forms are an extension of JSON schema for defining acceptable requests 
for GET queries and POST requests to post data to a server. JSON Forms can 
be used with JSON Hyper Schemas to describe additional possible ways for a 
user agent to interact with the server. JSON Forms are patterned after HTML 
forms, and serve a similar function.

3.1. method

This indicates which method should be used to submit the form data. In an 
HTTP environment, this would be "GET" or "POST".

3.2. encoding

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:
{
 "forms":[
    {
      "encoding": "application/x-www-form-urlencoded",
      "target": "/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

This should default to application/x-www-form-urlencoded if the method is 
GET and application/json if the method is POST.

3.3. target

This defines the target URI of the form action.

3.4. properties

This is inherited from the base JSON schema definition, and can follow the 
same structure, but its meaning should be used to define the acceptable 
property names and values for the action (whether it be for the GET query 
or POST body). If properties are omitted, and this form is the child of a 
schema, the properties from the parent schema should be used as the basis 
for the form action.

3.5. for

This is an optional reference back to the parent hyper schema.

4. 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",

5. IANA Considerations

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

   Type name: application

   Subtype name: schema+json

   Required parameters: schema
   	The value of the schema 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/hyper-schema,
   	but it is allowable to use other schemas that extend the hyper schema's meta-
   	schema.

   Optional parameters: n/a

6. 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
  
[RFC3986]