Skip to main content

Last Call Review of draft-ietf-httpapi-yaml-mediatypes-04

Request Review of draft-ietf-httpapi-yaml-mediatypes
Requested revision No specific revision (document currently at 10)
Type Last Call Review
Team Ops Directorate (opsdir)
Deadline 2023-04-10
Requested 2023-03-20
Authors Roberto Polli , Erik Wilde , Eemeli Aro
I-D last updated 2023-04-08
Completed reviews Artart Last Call review of -04 by Barry Leiba (diff)
Genart Last Call review of -04 by Elwyn B. Davies (diff)
Secdir Last Call review of -04 by Shawn M Emery (diff)
Opsdir Last Call review of -04 by Qin Wu (diff)
Assignment Reviewer Qin Wu
State Completed
Request Last Call review on draft-ietf-httpapi-yaml-mediatypes by Ops Directorate Assigned
Posted at
Reviewed revision 04 (document currently at 10)
Result Has nits
Completed 2023-04-08
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

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

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