jiebi/ids-paragraph-commentary-corpus huggingface dataset:
Draft: draft-ietf-httpapi-yaml-mediatypes

Commentary: looks good to me ( with one minor editorial note i left as a comment ) . 
 Would it be valuable to express a preference for over for file extensions ? I 'm assuming 3 character extensions are legacy from DOS file systems that had a 3 character limit . I reviewed the YAML 1.2 spec and there is no mention of using as a file extensions , so this might be a good opportunity to steer the community away from having two extensions . 
 Pls let 's annihilate the DOS zombie ! 
 let 's summon and the YAML folks on that . IMHO : agree on expressing a preference disagree on removing references to .yml , since it 's used in the wild . My2¢ , R. 
 Discussed with YAML folks . Ok for indicating a preference without normative implications .
File extension(s): "yaml" (preferred), "yml".  See int-yaml-
filename-extension.
The "yaml" filename extension is the preferred one; it is the most
popular and widely used on the web.  The "yml" filename extension is
still used.  The simultaneous usage of two filename extensions in the
same context might cause interoperability issues (e.g. when both a
"config.yaml" and a "config.yml" are present).
Draft: draft-ietf-httpapi-yaml-mediatypes

Commentary: in YAML and JSON , explicits that you need to use only information that is stored in the representation graph , not other . See 
 mention presentation and serialization details they can not be used to interoperably convey information comments , ordering and anchor names fall in the above categories .
The terms "presentation", "stream", "YAML document", "representation
graph", "node", "alias node", "anchor" and "anchor name" in this
document are to be interpreted as in YAML.
The terms "presentation", "stream", "YAML document", "representation
graph", "tag", "node", "alias node", "anchor" and "anchor name" in
this document are to be interpreted as in YAML.
When using YAML as a more efficient format to serialize information
intended to be consumed as JSON, information can be discarded: this
includes comments (see Section 3.2.3.3 of YAML) and alias nodes (see
Section 7.1 of YAML), that do not have a JSON counterpart.
When using YAML as a more efficient format to serialize information
intended to be consumed as JSON, information not reflected in the
representation graph and classified as presentation or serialization
detail (see Section 3.2 of YAML) can be discarded.  This includes
comments (see Section 3.2.3.3 of YAML), directives, and alias nodes
(see Section 7.1 of YAML) that do not have a JSON counterpart.
Draft: draft-ietf-httpapi-yaml-mediatypes

Commentary: Fix typical media type template problems    general , LGTM . About change controller , I was waiting for the feedback from the media type mailing list .
The terms "node", "alias node", "anchor" and "named anchor" in this
document are to be intepreded as in YAML.
The terms "node", "alias node", "anchor" and "named anchor" in this
document are to be interpreted as in YAML.
A YAML alias node can be represented in a URI fragment identifier by
encoding it into octects using UTF-8 UTF-8, while percent-encoding
those characters not allowed by the fragment rule in Section 3.5 of
URI.
A YAML alias node can be represented in a URI fragment identifier by
encoding it into bytes using UTF-8 UTF-8, while percent-encoding
those characters not allowed by the fragment rule in Section 3.5 of
URI.
Applications that need a human-friendly, cross language, Unicode
based data serialization language designed around the common
native data types of dynamic programming languages.
See Authors' Addresses section.
When using YAML as a more efficient format to serialize information
intented to be consumed as JSON, information can be discarded: this
includes comments (see Section 3.2.3.3 of YAML) and alias nodes (see
Section 7.1 of YAML), that do not have a JSON counterpart.
When using YAML as a more efficient format to serialize information
intended to be consumed as JSON, information can be discarded: this
includes comments (see Section 3.2.3.3 of YAML) and alias nodes (see
Section 7.1 of YAML), that do not have a JSON counterpart.
ex-fragid provides a non exhaustive list of examples that could help
understanding interoperability issues related to fragment
identifiers.
ex-fragid provides a non-exhaustive list of examples that could help
understand interoperability issues related to fragment identifiers.
Draft: draft-ietf-httpapi-yaml-mediatypes

Commentary: includes clarification on JSON Pointer and alias nodes compatibility includes FAQ fragment identifier moved from media type to section empty fragment + are both under   
 cc : PTAL 
 According to this PR should better clarify   use , so I am going to merge it . The decision on forcing + yaml fragment is deferred to that I will rebase .
A fragment identifier starting with "*" is to be interpreted as a
YAML alias node fragment-alias-node.
A fragment identifier that is empty or that starts with "/" is to be
interpreted as a JSON Pointer JSON-POINTER and is evaluated on the
YAML representation graph, walking through alias nodes; this syntax
can only reference YAML nodes that are on a path that is made up of
nodes interoperable with the JSON data model (see int-yaml-and-json).
An empty fragment identifier references the root node.  A fragment
identifier starting with "*" is to be interpreted as a YAML alias
node application-yaml-fragment.  A fragment identifier starting
with "/" is to be interpreted as a JSON Pointer JSON-POINTER and
is evaluated on the YAML representation graph, walking through
alias nodes; this syntax can only reference YAML nodes that are on
a path that is made up of nodes interoperable with the JSON data
model (see int-yaml-and-json).
Draft: draft-ietf-httpapi-yaml-mediatypes

Commentary: addressing ( and a few minor editorial changes thrown in as well ) . 
 This is probably left over from earlier drafts that did cover multiple media types . 
 There are a couple more places that use the plural form " media types " . Unless I am missing something , these all should be changed to singular form . 
 It 's and . I do n't have preferences and the singular is OK to me . Feel free to PR :) 
 that 's what i also thought but then again is n't a media type ( as i am sure you know ) . let 's make the tie - breaker ! 
 Let 's go with the singular form . 
 fixed via
YAML YAML is a data serialization format that is widely used on the
Internet, including in the API sector (e.g. see oas) but the relevant
media type and structured syntax suffix are not registered by IANA.
YAML YAML is a data serialization format that is widely used on the
Internet, including in the API sector (e.g. see oas) but the relevant
media type and structured syntax suffix previously had not been
registered by IANA.
YAML is an evolving language and, in time, some features have been
added, and others removed.
While this document is based on a given YAML version YAML, media
types registration does not imply a specific version.  This allows
content negotiation of version-independent YAML resources.
Implementers concerned about features related to a specific YAML
version can specify it in the documents using the "%YAML" directive
(see Section 6.8.1 of YAML).
YAML is an evolving language and, over time, some features have been
added and others removed.
While this document is based on a given YAML version YAML, the media
type registration does not imply a specific version.  This allows
content negotiation of version-independent YAML resources.
Implementers concerned about features related to a specific YAML
version can specify it in documents using the "%YAML" directive (see
Section 6.8.1 of YAML).
This specification defines the following new Internet media types
MEDIATYPE.
This specification defines the following new Internet media type
MEDIATYPE.
Draft: draft-ietf-httpapi-yaml-mediatypes

Commentary: no default frag - id for + yaml media types have to explicitly declare syntax and semantics 
 Compile fragment identifier section [ ] for [ x ] for ? Can we pospone this ? 
 It seems strange to me that a media type would define a new " language " intrinsic . 
 I believe the registration should include the fragment identifier .   does not identify one , which creates problems . It probably should have a registration update to address it . Not registering fragment handling means that a reference to a YAML - borne schema can not be referenced . The part beyond the # would be formally nonsensical ( as it is today ) . We can take some inspiration from the work on the same issue for   .   tells us how to craft fragments . The same format applies to the semantic equivalent in YAML documents . I 'll put in a pull request . 
 we have splitted the two documents . I think that yaml fragment identifiers should probably be delegated to " structured " media types since there are multiple possibilities ( eg .  - path ,  pointers , ... ) WRT openapi+yaml for example , we can state that the fragment uses json pointers . 
 Can you confirm that the YAML community agrees with the current statement wrt fragment identifiers ? 
 I 'm pretty sure that fragment identifiers should not be defined for at least for now . As demonstrated e.g. by the work going on even in this repo , YAML is used to represent multiple different forms of structured data , some of which may at times be represented by other formats , such as JSON . So while YAML 1.1 and 1.2 do explicitly support on nodes that would rather naturally work as fragment identifiers , there 's somewhat significant risk that this would complicate usage with sub - formats that natively use different methods , such as JSON Pointers . On the other hand , defining fragment identifiers for to follow the YAML spec for referring to anchors would make sense . 
 FWIW , I completely agree . 
 The choice to leave the fragment identifier of the structured syntax suffix to the media type is sensible : I will PR that .
For cases defined in +yaml, where the fragment identifier
resolves per the +yaml rules, then process as specified in
+yaml.
For cases defined in +yaml, where the fragment identifier does
not resolve per the +yaml rules, then process as specified in
"xxx/yyy+yaml".
For cases not defined in +yaml, then process as specified in
"xxx/yyy+yaml".
Differently from "application/yaml", there is no fragment
identification syntax defined for +yaml.  A specific "xxx/
yyy+yaml" media type needs to define the syntax and semantics for
fragment identifiers because the ones in application-yaml do not
apply unless explicitly expressed.
Draft: draft-ietf-httpapi-yaml-mediatypes

Commentary: This might be a bit nitpicky , but I think the draft should explicitly say that contains YAML . 
 If you are ok with the integration , feel free to squash and merge
The following information serves as the registration form for the
"application/yaml" media type.
The media type for YAML text is "application/yaml"; the following
information serves as the registration form for this media type.
Draft: draft-ietf-httpapi-rest-api-mediatypes

Commentary: editorial cleanup
Person and email address to contact for further information: See
Authors' Addresses section.
Author: See Authors' Addresses section.
The use of JSON Pointers as URI fragment identifiers is described in
RFC6901.  Fragment identifiers that are empty or start with a "/",
MUST be interpreted as JSON Pointer fragment identifiers.
The use of JSON Pointers as URI fragment identifiers is described in
JSON-POINTER.  Fragment identifiers that are empty or start with a
"/", MUST be interpreted as JSON Pointer fragment identifiers.
schema: A URI identifying the JSON Schema dialect the schema was
written for.  If this value conflicts with the value of the
"$schema" keyword in the schema, the "$schema" keyword takes
precedence.
N/A.
Interoperability requirements for media type registrations are
discussed in Section 4.6 of MEDIATYPE.  and YAML-MEDIATYPES.
Security requirements for media type registrations are discussed in
Section 4.6 of MEDIATYPE.  and YAML-MEDIATYPES.
A URI identifying a JSON Schema that provides semantic
information about this JSON representation.
Interoperability requirements for media type registrations are
discussed in Section 4.6 of MEDIATYPE.  and Section 3 of YAML-
MEDIATYPES.
Security requirements for media type registrations are discussed in
Section 4.6 of MEDIATYPE.  and Section 4 of YAML-MEDIATYPES.
Draft: draft-ietf-httpapi-yaml-mediatypes

Commentary: editorial cleanup before publication of -00
Person and email address to contact for further information: See
Authors' Addresses section.
Restrictions on usage: None.
Author: See Authors' Addresses section.
None.
Contact: See Authors' Addresses section.
For cases defined in +yaml, where the fragment identifier
resolves per the +yaml rules, then process as specified in
+yaml.
For cases defined in +yaml, where the fragment identifier does
not resolve per the +yaml rules, then process as specified in
"xxx/yyy+yaml".
For cases not defined in +yaml, then process as specified in
"xxx/yyy+yaml".
Even if a document is not cyclic, treating it as a tree could lead to
improper behaviors (such as the "billion laughs" problem).
Even if a document is not cyclic, treating it as a simple tree could
lead to improper behaviors (such as the "billion laughs" problem).
Draft: draft-ietf-httpapi-rest-api-mediatypes

Commentary: references httpbis minor improvements .
The terms "content", "content negotiation", "resource", and "user
agent" in this document are to be interpreted as in SEMANTICS.
The use of JSON Pointers as URI fragment identifiers is described in
RFC 6901 RFC6901.  Fragment identifiers that are empty or start with
a "/", MUST be interpreted as JSON Pointer fragment identifiers.
The use of JSON Pointers as URI fragment identifiers is described in
RFC6901.  Fragment identifiers that are empty or start with a "/",
MUST be interpreted as JSON Pointer fragment identifiers.
Draft: draft-ietf-httpapi-rest-api-mediatypes

Commentary: YAML evolving 
 registration is independent from YAML version version is in % YAML
YAML is an evolving language and, in time, some features have been
added, and others removed.
While this document is based on a given YAML version YAML, media
types registration does not imply a specific version.  This allows
content negotiation of version-independent YAML resources.
Implementers concerned about features related to a specific YAML
version can specify it the documents using the "%YAML" directive (see
Section 6.8.1 of YAML).
Draft: draft-ietf-httpapi-rest-api-mediatypes

Commentary: adds the + yaml suffix 
 can we merge ? 
 to register the structured syntax suffix
Moreover it defines and registers the "+yaml" structured syntax
suffix.
This section describes the information required to register the above
media types.
The suffix "+yaml" MAY be used with any media type whose
representation follows that established for "application/yaml".  The
media type structured syntax suffix registration form follows.  See
MEDIATYPE for definitions of each of the registration form headings.
Contact: See Authors' Addresses section.
IANA has updated the "Structured Syntax Suffixes" registry at
https://www.iana.org/assignments/media-type-structured-suffix [4]
with the registration information provided below.
Draft: draft-ietf-httpapi-rest-api-mediatypes

Commentary: introduce numbered sections for YAML since each media type is defined in its IANA consideration , would it be ok for you if we just add a section for YAML ? Feel free to PR with another proposal . 
 could you PTAL ? :) 
 to be honest , i prefer definitions to have URIs and not just registrations . but if we have URIs , that 's already a lot better than not having URIs ! thanks ! 
 it 's maybe just OCD ( and because it 's very useful for to have linkable references ) but i think it 's nice to have numbered sections for everything that 's being defined in the spec . in this case , i suggest to have a numbered section for each of the four media types , and to have a brief explanation of what it identifies . that way , each definition is self - contained and can be easily referenced when necessary .
The OpenAPI Specification Media Types convey OpenAPI Specification
(OAS) files as defined in oas for version 3.0.0 and above.
Those files can be serialized in JSON or yaml.  Since there are
multiple OpenAPI Specification Specifications versions, those media-
types support the "version" parameter.
This section describes the information required to register the above
media types.
The following information serves as the registration form for the
"application/yaml" media type.
The OpenAPI Specification Media Types convey OpenAPI document (OAS)
files as defined in oas for version 3.0.0 and above.
Those files can be serialized in JSON or yaml.  Since there are
multiple OpenAPI Specification versions, those media-types support
the "version" parameter.
The following information serves as the registration form for the
"application/openapi+json" media type.
The following information serves as the registration form for the
"application/openapi+yaml" media type.
IANA has updated the "Media Types" registry at
https://www.iana.org/assignments/media-types [3] with the
registration information provided below.
Draft: draft-ietf-httpapi-rest-api-mediatypes

Commentary: Thanks to
Discussion of this draft takes place on the HTTP working group
mailing list (httpapi@ietf.org), which is archived at
https://lists.w3.org/Archives/Public/ietf-httpapi-wg/ [1].
OpenAPI oas version 3 and above is a consolidated standard for
describing HTTP APIs using the JSON JSON and yaml yaml data format.
To increase interoperability when processing API specifications and
leverage content negotiation mechanisms when exchanging OpenAPI
resources this specification register the following media-types:
"text/yaml", "application/yaml", "application/openapi+json" and
"application/openapi+yaml".
This document registers the following media types used in APIs on the
IANA Media Types registry: text/yaml, application/yaml, application/
openapi+json, and application/openapi+yaml.
Discussion of this draft takes place on the HTTP APIs working group
mailing list (httpapi@ietf.org), which is archived at
https://mailarchive.ietf.org/arch/browse/httpapi/ [1].
OpenAPI Specification oas version 3 and above is a consolidated
standard for describing HTTP APIs using the JSON JSON and yaml yaml
data format.
To increase interoperability when processing API specifications and
leverage content negotiation mechanisms when exchanging OpenAPI
Specification resources this specification register the following
media-types: "text/yaml", "application/yaml", "application/
openapi+json" and "application/openapi+yaml".
The OpenAPI Media Types convey OpenAPI specification files as defined
in oas for version 3.0.0 and above.
Those files can be serialized in JSON or yaml.  Since there are
multiple OpenAPI Specifications versions, those media-types support
the "version" parameter.
The OpenAPI Specification Media Types convey OpenAPI Specification
(OAS) files as defined in oas for version 3.0.0 and above.
Those files can be serialized in JSON or yaml.  Since there are
multiple OpenAPI Specification Specifications versions, those media-
types support the "version" parameter.