This specification defines the JSON Reference (JRef) media type. JRef is an extension of the JSON media type that adds the "reference" type. A "reference" type represents a web-style uni-directional link to a location in either the current document or a different resource.
NOTE: This document is written as a spec and therefore doesn't have commentary on why I made the decisions I made or what impacts they would have for the specifications that might be interested in adopting this spec. For that type of information see #7.
The JRef media type is identified as application/reference+json and uses the
jref file extension.
A URI fragment that is
empty or starts with a / MUST be interpreted as a JSON
Pointer. A JSON Pointer fragment
represents a secondary resource that is the result of applying the JSON Pointer
to the full document. Implementations MUST raise an error if the JSON Pointer
does not successfully resolve to a location within the document.
Specifications that extend this media type MAY define semantics for fragments that are not JSON Pointers, but if the fragment semantics are not understood, implementations MUST raise an error.
This media type allows the "profile" media type parameter as defined by RFC 6906.
A "reference" type is represented with the same syntax as a JSON object with a
$href property whose value is string. Specifications that extend this media
type MAY define semantics for additional properties, but implementations MUST
raise an error if they encounter a property that is not defined.
{ "$href": "https://example.com/example.json#/foo/bar" }Although the "reference" type has syntactic overlap with the JSON "object" type, it MUST NOT be interpreted as a JSON object. The "reference" type is a scalar value that can not be indexed into like a JSON object.
A JSON object is considered of type "reference" rather than type "object" if it
has a $href property and the value of that property is a string.
The value of $href in a reference MUST be interpreted as a
URI-reference. The process
for determining the base URI for the document is defined by RFC 3986 Section
5.1. Specifications that
extend this media type MAY add keywords that effect the base URI, but if they
do, they MUST do so in a way that fits into the framework expressed in RFC 3986
Section 5.1.
Following a reference may result in media types other than JRef being returned. While implementations are not limited to only handling JRef responses, they MUST raise an error if they encounter a media type they do not support.
When following a URI that uses a protocol where the response is self describing
of its media type, implementations MUST respect the declared media type. For
example, an HTTP response for https://example.com/example that has
Content-Type: application/json should be treated as plain JSON document rather
than as JRef document. That means that any objects with a $href would be of
type "object" rather than type "reference".
When following a URI using a protocol where the response is not self describing of its media type (such as file system access), implementations MAY use whatever heuristic they deem necessary to determine the media type of the response including context hints from the referring document. If implementations use file extensions as a heuristic, they SHOULD use the IANA media types registry to determine which file extensions map to which media types.
A reference may point to a secondary resource within the referred to document as defined by the fragment semantics of the media type of the referred to document.
The "value" of a reference is the JSON-compatible value of the result of following the reference. Implementations MAY define how non-JSON media types translate to a JSON-compatible value. Implementations MAY provide an API for working with media types that do not translate to a JSON compatible value.