Kris Zyp's Questionable Assumptions

August 18th, 2009
I recently wrote a new draft for an extension to JSON schema called JSON Hyper Schema, that defines a mechanism for describing referencing and linking elements with a JSON structure. JSON Hyper Schema allows schemas to define which properties can link information and how they should be interpreted, with thorough integration into the RESTful architecture of the web. As the abstract for draft states:

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.

This is intended to superset and supersede JSON referencing, with a much more flexible mechanism that can support user defined properties for references, and clear declaration of the referencing used in a document. JSON referencing defined two specific properties as a convention for references, but JSON hyper schema allows for any property to have link information. One of the important benefits of this meta-descriptive approach to references is that allows JSON hyper schema to be applied to any JSON structure unobtrusively. One could easily use JSON hyper schema to define the relationships that a JSON object created a serialized row from a database has to other rows through foreign keys. As the design considerations state:

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.

The most crucial attribute introduced by JSON hyper schema is the “links” attribute, which defines relations that should be interpreted from the instance document. A simple hyper schema example (this is the schema):

{
“properties”: {
“id”: {
“link”: “self”
},
links: [
{
“href”: “{parent_id}”,
“rel”: “parent”
}
]
}
}
Now if an instance of this hyper schema was retrieved from “http://somesite.com/data/a” :

Content-Type: application/json; definedby=/schema/my-schema
{
“id”:”a”,
“parent_id”:”b”
}
A client or user agent could then use the schema to interpret this instance data to mean that the given JSON representation is authoritatively located at the URI referenced by “a”, which is “http://somesite.com/data/a” (the full URI is determined from the context, usually the URI used to request the object), and that the “parent” resource is located at the URI referenced by “b”, which is “http://somesite.com/data/b”.

JSON Hyper Schema is complementary extension to JSON Schema. In order to truly fulfill the self-descriptive property with JSON schema, the meta-schema (the schema for schemas) requires the ability to define circular structures. Previously, this had required a dependence on the JSON referencing convention, but now JSON schema itself can be used to describe the referencing mechanism, making the JSON schema/hyper schema pair self dependent and self-descriptive.

With JSON Hyper Schema, JSON referencing is simply one type of linking structure can be mechanically defined by hyper schema. To make it easier there is actually a schema that can be referenced to declare that a JSON structure utilizes the JSON referencing convention:

Content-Type: application/json; definedby=http://json-schema.org/json-ref

JSON hyper schemas themselves are defined to use the JSON referencing convention (partly to preserve backwards compatibility), but the structures the schemas describe can have any linking structure.

The addition of JSON hyper schema provides an important step forward towards full JSON schema specification that comprehensively provides metadata in the context of the RESTful world of the web.