From 05403b78488238a2b28959812a6151602aac0dc6 Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Wed, 26 Oct 2022 12:14:59 -0700 Subject: [PATCH 1/4] Add the JRef specification --- draft-jdesrsoiers-jref.md | 88 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 draft-jdesrsoiers-jref.md diff --git a/draft-jdesrsoiers-jref.md b/draft-jdesrsoiers-jref.md new file mode 100644 index 0000000..9d24662 --- /dev/null +++ b/draft-jdesrsoiers-jref.md @@ -0,0 +1,88 @@ +# 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. + +## 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 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 a "reference" rather than an "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 a base URI for resolving to a full +[URI](https://www.rfc-editor.org/rfc/rfc3986#section-3) 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 is compatible with [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 NOT assume the response is a JRef +document or use heuristics including file extensions to determine the media type +of the response. For example, an HTTP response for `https://example.com/example` +that has `Content-Type: application/json` should not be treated as a JRef media +type. That means that any objects with a `$href` property should not be +considered a reference. It would just be a JSON object that looks like a JRef +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. From 42c4f7c5f80753cf88a33aeb7a49d750605d8010 Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Mon, 31 Oct 2022 10:32:40 -0700 Subject: [PATCH 2/4] JRef: Improve wording in a few places --- draft-jdesrsoiers-jref.md | 39 ++++++++++++++++++--------------------- 1 file changed, 18 insertions(+), 21 deletions(-) diff --git a/draft-jdesrsoiers-jref.md b/draft-jdesrsoiers-jref.md index 9d24662..3131f6a 100644 --- a/draft-jdesrsoiers-jref.md +++ b/draft-jdesrsoiers-jref.md @@ -30,10 +30,10 @@ This media type allows the "profile" media type parameter as defined by [RFC ## The "reference" Type ### Syntax -A "reference" type is represented 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. +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" } @@ -43,31 +43,28 @@ 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 a "reference" rather than an "object" if it has a -`$href` property and the value of that property is a string. +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 a base URI for resolving to a full -[URI](https://www.rfc-editor.org/rfc/rfc3986#section-3) 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 is compatible with [RFC 3986 Section -5.1](https://www.rfc-editor.org/rfc/rfc3986#section-5.1). +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 NOT assume the response is a JRef -document or use heuristics including file extensions to determine the media type -of the response. For example, an HTTP response for `https://example.com/example` -that has `Content-Type: application/json` should not be treated as a JRef media -type. That means that any objects with a `$href` property should not be -considered a reference. It would just be a JSON object that looks like a JRef -reference. +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 From 169f8aba3ef0d1e2d0a7a94800672ab5661b3175 Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Thu, 3 Nov 2022 18:06:40 -0700 Subject: [PATCH 3/4] Add link to JRef commentary issue to JRef spec --- draft-jdesrsoiers-jref.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/draft-jdesrsoiers-jref.md b/draft-jdesrsoiers-jref.md index 3131f6a..8453406 100644 --- a/draft-jdesrsoiers-jref.md +++ b/draft-jdesrsoiers-jref.md @@ -7,6 +7,11 @@ 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. From 65fd9df987a6e9a314c7610dd341cc920491f8b4 Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Tue, 8 Nov 2022 15:43:02 -0800 Subject: [PATCH 4/4] Rename jref proposal to workaround I-D build system --- draft-jdesrsoiers-jref.md => jdesrosiers-jref.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename draft-jdesrsoiers-jref.md => jdesrosiers-jref.md (100%) diff --git a/draft-jdesrsoiers-jref.md b/jdesrosiers-jref.md similarity index 100% rename from draft-jdesrsoiers-jref.md rename to jdesrosiers-jref.md