[Last-Call] Artart last call review of draft-ietf-httpapi-yaml-mediatypes-04

[Barry Leiba via Datatracker <[e-mail]>]

Reviewer: Barry Leiba
Review result: Ready with Nits

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
      +yaml.

“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”
instead.

— 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:

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

— Section 5 —

   IANA has updated the "Media Types" registry at
   https://www.iana.org/assignments/media-types
   (https://www.iana.org/assignments/media-types) 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
5.)

--
Barry