From b1103ff5834305a0fa904bc4cb2435ac41822a6d Mon Sep 17 00:00:00 2001 From: Eemeli Aro Date: Tue, 5 Apr 2022 12:22:19 +0300 Subject: [PATCH 1/6] Define fragment identifiers for application/yaml --- draft-ietf-httpapi-yaml-mediatypes.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/draft-ietf-httpapi-yaml-mediatypes.md b/draft-ietf-httpapi-yaml-mediatypes.md index 8aa1df1..58f7a2a 100644 --- a/draft-ietf-httpapi-yaml-mediatypes.md +++ b/draft-ietf-httpapi-yaml-mediatypes.md @@ -138,7 +138,11 @@ Applications that use this media type: : HTTP Fragment identifier considerations: -: None +: For documents labeled as `application/yaml`, + the fragment identifier is parsed as if it were a YAML alias node, + but without a leading `*` indicator. + For YAML 1.2, + this means that it designates a node which has a correspondingly named anchor. Additional information: From 9857e8e9947367af21959f9c1c3f2b3e349dfade Mon Sep 17 00:00:00 2001 From: Eemeli Aro Date: Tue, 5 Apr 2022 14:56:36 +0300 Subject: [PATCH 2/6] Use first match when alias targets are not unique --- draft-ietf-httpapi-yaml-mediatypes.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/draft-ietf-httpapi-yaml-mediatypes.md b/draft-ietf-httpapi-yaml-mediatypes.md index 58f7a2a..1bd90c1 100644 --- a/draft-ietf-httpapi-yaml-mediatypes.md +++ b/draft-ietf-httpapi-yaml-mediatypes.md @@ -143,6 +143,8 @@ Fragment identifier considerations: but without a leading `*` indicator. For YAML 1.2, this means that it designates a node which has a correspondingly named anchor. + If multiple nodes would match a fragment identifier, + the first such match is selected. Additional information: From 8eab8acf3bbf1531f7604dcbd8aad32dd84c9673 Mon Sep 17 00:00:00 2001 From: Eemeli Aro Date: Tue, 5 Apr 2022 20:55:30 +0300 Subject: [PATCH 3/6] Update draft-ietf-httpapi-yaml-mediatypes.md Co-authored-by: Roberto Polli --- draft-ietf-httpapi-yaml-mediatypes.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/draft-ietf-httpapi-yaml-mediatypes.md b/draft-ietf-httpapi-yaml-mediatypes.md index 1bd90c1..8c08569 100644 --- a/draft-ietf-httpapi-yaml-mediatypes.md +++ b/draft-ietf-httpapi-yaml-mediatypes.md @@ -138,10 +138,9 @@ Applications that use this media type: : HTTP Fragment identifier considerations: -: For documents labeled as `application/yaml`, - the fragment identifier is parsed as if it were a YAML alias node, +: The fragment identifier is parsed as if it were a YAML alias node, but without a leading `*` indicator. - For YAML 1.2, + For example, in YAML 1.2, this means that it designates a node which has a correspondingly named anchor. If multiple nodes would match a fragment identifier, the first such match is selected. From c387b6b7fac47a94c9685a8fa1a412a2f42d0e70 Mon Sep 17 00:00:00 2001 From: Roberto Polli Date: Tue, 12 Apr 2022 14:42:25 +0200 Subject: [PATCH 4/6] Fix: #21. Fragment identifiers. --- draft-ietf-httpapi-yaml-mediatypes.md | 53 ++++++++++++++++++++++++--- 1 file changed, 47 insertions(+), 6 deletions(-) diff --git a/draft-ietf-httpapi-yaml-mediatypes.md b/draft-ietf-httpapi-yaml-mediatypes.md index 8c08569..40c5039 100644 --- a/draft-ietf-httpapi-yaml-mediatypes.md +++ b/draft-ietf-httpapi-yaml-mediatypes.md @@ -101,6 +101,52 @@ The terms "content", "content negotiation", "resource", and "user agent" in this document are to be interpreted as in {{!SEMANTICS=I-D.ietf-httpbis-semantics}}. +The terms "fragment" and "fragment identifier" +in this document are to be interpreted as in {{!URI==RFC3986}}. + +The terms "node", "anchor" and "named anchor" +in this document are to be intepreded as in [YAML]. + +## Fragment identification {#application-yaml-fragment} + +This section describes how to use +named anchors (see Section 3.2.2.2 of [YAML]) +as fragment identifier to designate a node. + +A YAML named anchor can be represented in a URI fragment identifier +by encoding it into octects using UTF-8 {{!UTF-8==RFC3629}}, +while percent-encoding those characters not allowed by the fragment rule +in {{Section 3.5 of URI}}. + +If multiple nodes would match a fragment identifier, +the first such match is selected. + +Users concerned with interoperability of fragment identifiers: + +- SHOULD limit named anchors to a set of characters + that do not require encoding + to be expressed as URI fragment identifiers: + this is always possible since named anchors are a serialization + detail; +- SHOULD NOT use a named anchor that matches multiple nodes. + +In the example resource below, the URL `file.yaml#foo` +references the anchor `foo` pointing to the node with value `scalar`; +whereas +the URL `file.yaml#bar` references the anchor `bar` pointing to the node +with value `[ some, sequence, items ]`. + +~~~ example +%YAML 1.2 +--- +one: &foo scalar +two: &bar + - some + - sequence + - items +~~~ + + # Media Type registrations This section describes the information required to register @@ -138,12 +184,7 @@ Applications that use this media type: : HTTP Fragment identifier considerations: -: The fragment identifier is parsed as if it were a YAML alias node, - but without a leading `*` indicator. - For example, in YAML 1.2, - this means that it designates a node which has a correspondingly named anchor. - If multiple nodes would match a fragment identifier, - the first such match is selected. +: see {{application-yaml-fragment}} Additional information: From d712a472580b94c46e5829d2cd35d7c7abfe2a80 Mon Sep 17 00:00:00 2001 From: Roberto Polli Date: Tue, 12 Apr 2022 17:02:05 +0200 Subject: [PATCH 5/6] typos --- draft-ietf-httpapi-yaml-mediatypes.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/draft-ietf-httpapi-yaml-mediatypes.md b/draft-ietf-httpapi-yaml-mediatypes.md index 40c5039..3cfa9cb 100644 --- a/draft-ietf-httpapi-yaml-mediatypes.md +++ b/draft-ietf-httpapi-yaml-mediatypes.md @@ -102,7 +102,7 @@ and "user agent" in this document are to be interpreted as in {{!SEMANTICS=I-D.ietf-httpbis-semantics}}. The terms "fragment" and "fragment identifier" -in this document are to be interpreted as in {{!URI==RFC3986}}. +in this document are to be interpreted as in {{!URI=RFC3986}}. The terms "node", "anchor" and "named anchor" in this document are to be intepreded as in [YAML]. @@ -114,7 +114,7 @@ named anchors (see Section 3.2.2.2 of [YAML]) as fragment identifier to designate a node. A YAML named anchor can be represented in a URI fragment identifier -by encoding it into octects using UTF-8 {{!UTF-8==RFC3629}}, +by encoding it into octects using UTF-8 {{!UTF-8=RFC3629}}, while percent-encoding those characters not allowed by the fragment rule in {{Section 3.5 of URI}}. @@ -137,13 +137,13 @@ the URL `file.yaml#bar` references the anchor `bar` pointing to the node with value `[ some, sequence, items ]`. ~~~ example -%YAML 1.2 ---- -one: &foo scalar -two: &bar - - some - - sequence - - items + %YAML 1.2 + --- + one: &foo scalar + two: &bar + - some + - sequence + - items ~~~ From 55a95ae4805156cc954a367993deb6f2745211b5 Mon Sep 17 00:00:00 2001 From: Roberto Polli Date: Sat, 23 Apr 2022 11:54:13 +0200 Subject: [PATCH 6/6] Update draft-ietf-httpapi-yaml-mediatypes.md --- draft-ietf-httpapi-yaml-mediatypes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-ietf-httpapi-yaml-mediatypes.md b/draft-ietf-httpapi-yaml-mediatypes.md index 3cfa9cb..0516c5a 100644 --- a/draft-ietf-httpapi-yaml-mediatypes.md +++ b/draft-ietf-httpapi-yaml-mediatypes.md @@ -111,7 +111,7 @@ in this document are to be intepreded as in [YAML]. This section describes how to use named anchors (see Section 3.2.2.2 of [YAML]) -as fragment identifier to designate a node. +as fragment identifiers to designate nodes. A YAML named anchor can be represented in a URI fragment identifier by encoding it into octects using UTF-8 {{!UTF-8=RFC3629}},