Merge pull request #4 from jdesrosiers/add-jref

New Proposal: JSON Reference (JRef) media type

Author: handrews

jdesrosiers-jref.md

@@ -0,0 +1,90 @@
+# JRef Specification
+
+## Introduction
+This specification defines the JSON Reference (JRef) media type. JRef is an
+extension of the [JSON](https://www.rfc-editor.org/rfc/rfc8259) 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 https://github.com/json-schema-org/referencing/issues/7.
+
+## Media Type
+The JRef media type is identified as `application/reference+json` and uses the
+`jref` file extension.
+
+### Fragments
+A URI [fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) that is
+empty or starts with a `/` MUST be interpreted as a [JSON
+Pointer](https://www.rfc-editor.org/rfc/rfc6901). 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.
+
+### Profiles
+This media type allows the "profile" media type parameter as defined by [RFC
+6906](https://www.rfc-editor.org/rfc/rfc6906).
+
+## The "reference" Type
+
+### Syntax
+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.
+
+```json
+{ "$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.
+
+### Following References
+The value of `$href` in a reference MUST be interpreted as a
+[URI-reference](https://www.rfc-editor.org/rfc/rfc3986#section-4.1). The process
+for determining the base URI for the document is defined by [RFC 3986 Section
+5.1](https://www.rfc-editor.org/rfc/rfc3986#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](https://www.rfc-editor.org/rfc/rfc3986#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](https://www.iana.org/assignments/media-types/media-types.xhtml) 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](https://www.rfc-editor.org/rfc/rfc3986#section-3.5)
+semantics of the media type of the referred to document.
+
+## Values
+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.