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 ART Area Review Team (artart)
Deadline 2023-04-10
Requested 2023-03-20
Authors Roberto Polli , Erik Wilde , Eemeli Aro
I-D last updated 2023-03-28
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 Barry Leiba
State Completed
Request Last Call review on draft-ietf-httpapi-yaml-mediatypes by ART Area Review Team Assigned
Posted at
Reviewed revision 04 (document currently at 10)
Result Ready w/nits
Completed 2023-03-28
Thanks for this.  I have a few comments, but they're all very minor:

— Section 1.2.1

   If multiple nodes would match a fragment identifier, the first such
   match is selected.

I don’t know what “first” means here — alphabetically first, sequentially first
in a set, something else?  Is this clear enough for someone who actually uses
YAML, or can/should it be clarified?

— Section 2.1 —

   Optional parameters:  N/A; unrecognized parameters should be ignored

Maybe “unrecognized parameters are ignored” ?

— Section 2.2 —

   The suffix +yaml MAY be used with any media type whose representation
   follows that established for application/yaml.

This strikes me as a “may”, not a “MAY”.

   Fragment identifier considerations:  Differently from application/
      yaml, there is no fragment identification syntax defined for

“Differently from” isn’t proper English here.  I think you want “Unlike”.

— Section 3.5 —

   Implementers need to consider that the YAML version and supported
   features (e.g. merge keys) can impact on the generation of the
   representation graph (see Figure 9).

The phrase “impact on” is non-standard English; please consider “affect”

— Section 4.2 —

   YAML documents are rooted, connected, directed graphs and can contain
   reference cycles, so they can't be treated as simple trees (see
   Section 3.2.1 of [YAML]).  An implementation that attempts to do that
   can infinite-loop traversing the YAML representation graph at some
   point, for example:

I find the antecedent to “do that” to be unclear, and using “infinite-loop” as
a verb seems odd.  I suggest this:

An implementation that treats them as simple trees risks going into an
infinite loop while traversing the YAML representation graph.  This
can happen:

— Section 5 —

   IANA has updated the "Media Types" registry at
   ( with the registration
   information provided below.

I presume the duplication of the URI is an artifact of the markup.  But IANA
has not, in fact, made these updates yet (I looked).  I suggest “IANA is asked
to update…”, and the RFC Editor will change this when they have confirmed that
IANA has taken the requested actions.  (This situation occurs twice in Section