From 4ff8647f1fda1bbfc678854623fe8e98d0c6e42a Mon Sep 17 00:00:00 2001
From: Eemeli Aro <eemeli@gmail.com>
Date: Thu, 12 May 2022 14:55:08 +0300
Subject: [PATCH] Define fragment identifiers for application/yaml (#38)

* Define fragment identifiers for application/yaml

* Use first match when alias targets are not unique

* Update draft-ietf-httpapi-yaml-mediatypes.md

Co-authored-by: Roberto Polli <robipolli@gmail.com>

* Fix: #21. Fragment identifiers.

* typos

* Update draft-ietf-httpapi-yaml-mediatypes.md

Co-authored-by: Roberto Polli <robipolli@gmail.com>
---
 draft-ietf-httpapi-yaml-mediatypes.md | 48 ++++++++++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

diff --git a/draft-ietf-httpapi-yaml-mediatypes.md b/draft-ietf-httpapi-yaml-mediatypes.md
index 9b5a6e7..125c849 100644
--- a/draft-ietf-httpapi-yaml-mediatypes.md
+++ b/draft-ietf-httpapi-yaml-mediatypes.md
@@ -106,6 +106,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 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}},
+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
@@ -144,7 +190,7 @@ Applications that use this media type:
 : HTTP
 
 Fragment identifier considerations:
-: None
+: see {{application-yaml-fragment}}
 
 Additional information: