Artart review

[ioggstream]

Artart review

• [ ] — 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?

@eemeli do we need further clarification here? Is the following ok? Should we reference https://yaml.org/spec/1.2.2/#alias-nodes

the first
+ occurrence
of such match is selected

• [ ] — Section 2.1 — Note: To be done after moving the registrations in the IANA considerations.

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

• [x] — 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.

• [x] — 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 — TBD after moving registrations in the IANA considerations.

  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.)