search

jsongraph / json-graph-specification

A proposal for representing graph structure (nodes / edges) in JSON.
http://jsongraphformat.info/
Other
449 stars 35 forks source link

Media type support to describe JGF and derivative schemas #14

Closed abargnesi closed 9 years ago

abargnesi commented 9 years ago

The Goal

Recognize JGF data as:

The primary use case is with the HTTP protocol, but the use of media types should reach further.

Following the RFC-laden road

Media types - RFC 6838 Suffixes - RFC 6839 Profiles - RFC 6906 Web linking - RFC 5988

A media type describes the type of data in a file. For example application/json specifies that the described file can be parsed as JSON content. An HTTP response would include a Content-Type: application/json header to convey the response body's content type.

JGF data provides graph structures and semantics on top of application/json that should be conveyed to clients in an explicit manner. Returning a Content-Type: application/json for JGF data only provides a generic JSON format constraint on the data.

How about we mint a new vendor media type called application/vnd.jgf ? Well this would allow us to convey that it is something called jgf, but we no longer convey it derives from JSON.

Ok. How about we add media type suffixes (i.e. +xml, +json, etc.) and mint application/vnd.jgf+json instead? Now clients can recognize the content as vendor-specifc, JSON-formatted, with JGF structure and semantics.

But wait...How would clients discover what the structure and semantics are for JGF? Implicitly they may know that JGF is defined by the schema http://json-graph-format.info/schema.json, but that incorrectly takes the responsibility away from the server and places the burden on the client. Instead let us convey the JGF schema via media type profiles.

To quote from RFC6906:

A media type defines both the semantics and the serialization of a
specific type of content.  In many cases, media types have some
built-in extensibility or openness, so that specific instances of the
media type can layer additional semantics on top of the media type's
foundation.  In this case, a profile is the appropriate mechanism to
signal that the original semantics and processing model of the media
type still apply, but that an additional processing model can be used
to extract additional semantics.  This is in contrast to a new media
type that, instead of just adding processing rules and semantics
defines a complete set of processing rules and semantics in most
cases.

Ok I might buy that. How would that look? Well an HTTP server now responds with the header

Content-Type: application/vnd.jgf+json;
          profile=http://json-graph-format.info/schema.json

Now the content is conveyed as vendor-specific, JSON-formatted with JGF structure and semantics defined by a JSON Schema dereferencable at http://json-graph-format.info/schema.json.

JSON Schema RECOMMENDS this approach for conveying your schema.

We get one more use of profile for free. Multiple profiles can be layered on to the content type so we can describe JGF-derived schemas (i.e. BEL JGF) with multiple profiles:

Content-Type: application/vnd.jgf+json;
          profile=http://json-graph-format.info/schema.json;
          profile=http://json-graph-format.info/child/bel-jgf.json

We should also target the Content-Type / Link header approach as well:

Content-Type: application/vnd.jgf+json;
Link: <http://json-graph-format.info/schema.json>; rel="describedBy"
Link: <http://json-graph-format.info/child/bel-jgf.json>; rel="describedBy"

One challenge with this is knowing which profile (schema) to apply to the content. I think this could be alleviated by what the client Accepts. If they send:

Accept: application/vnd.jgf+json;
          profile=http://json-graph-format.info/child/bel-jgf.json

then maybe the server should supply only that profile?

We could probably avoid multiple profiles altogether for JGF child schemas since they derive from the parent schema. For example the BEL JGF schema extends the parent schema so we would just need the http://json-graph-format.info/child/bel-jgf.json schema.

Alternative to profiles

We could just use application/vnd.jgf+json and stick the schema into the JSON data directly. This approach seems to be like self-describing JSON schemas. One problem with this approach is that the JSON needs to be cracked open to see what schema it should use to validate against. And that would be implicit knowledge...which is bad.

In summary:

  1. Provide vendor-specific media type application/vnd.jgf+json.
  2. Utilize media type profiles URIs that dereference to JSON schema documents.
    • Support Content-Type and Link header (server)
    • Support Accept header (client)
wshayes commented 9 years ago

The proposed solution: 1 and 2 look good to me. Thanks for investigating and providing a proposal.