Last Call Review of draft-ietf-httpapi-yaml-mediatypes-04
review-ietf-httpapi-yaml-mediatypes-04-opsdir-lc-wu-2023-04-08-00

This document registers the application/yaml media type and the +yaml
structured syntax suffix on the IANA Media Types registry. In addition, this
documents provides security considerations and interoperability considerations
related to YMAL and JSON.

I believe this document is well written and ready for publication, however I do
have a few comments as follows: Major issues: No

Minor issues:
1. Section 2
For Media Type registration in section 2, I am not clear whether Macintosh file
type code and Windows Clipboard Name should be mentioned as additional
information?

2. Section 2.2
For The +yaml Structured Syntax Suffix in section 2.2, how many contacts do we
allowed? My impression, in most case, the single contact is preferred, wrong?

3.Section 3.1 said:
“   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 YAML documents using the %YAML directive
   (see Section 6.8.1 of [YAML]).
”
It looks these two paragraphs contradict to each other, if we see features
related to a specific YAML version as some kind of YAML resource, should we
also allow content negotiation of version specific YAML resources? Correct me
if I am wrong?

4. Section 3.2 said:
“
   When receiving a multi-document stream, an application that only
   expects one-document streams, ought to signal an error instead of
   ignoring the extra documents.

   Current implementations consider different documents in a stream
   independent, similarly to JSON Text Sequences (see [RFC7464]);
   elements such as anchors are not guaranteed to be referenceable
   across different documents.

”
I am a little confused here, Is current implementations documented by this
draft? Or new implementation related to this draft should consider different
document in a stream dependently or can detect whether a single document or
multiple documents are carried in a stream?

I also suggest we should leave how to signal an error beyond the scope of this
document.

5. Section 3.4 figure 3
Not clear whether figure 3 in section 3.4 should be moved to Appendix A.
Or some figure in appendix A should be moved to section 3.4, e.g.,
One interoperability issue， i.e., mapping keys that are not strings
is clearly related to appendix A.1

6. Nits
s/ when trying to serialize it JSON/ when trying to serialize it in JSON
s/ representaion graph/ representation graph
s/ can infinite-loop traversing the YAML representation graph/ can fall into
infinite-loop traversing the YAML representation graph