[Gen-art] Genart last call review of draft-ietf-httpapi-yaml-mediatypes-04

[Elwyn Davies via Datatracker <[e-mail]>]

Reviewer: Elwyn Davies
Review result: Not Ready

I am the assigned Gen-ART reviewer for this draft. The General Area
Review Team (Gen-ART) reviews all IETF documents being processed
by the IESG for the IETF Chair.  Please treat these comments just
like any other last call comments.

For more information, please see the FAQ at

<https://trac.ietf.org/trac/gen/wiki/GenArtfaq>.

Document: draft-ietf-httpapi-yaml-mediatypes-04
Reviewer: Elwyn Davies
Review Date: 2023-04-09
IETF LC End Date: 2023-04-10
IESG Telechat date: Not scheduled for a telechat

Summary:  The document is not ready for approval mainly because the registry
specifications are not in a form where IANA can simply cut and paste them into
the resistry database.  IANA have called this out during their review.

Major issues:
As noted in the IANA review, the text for the registry updates is not in a
state where it can simply be cut and pasted into the registry entries by IANA. 
It contains references to sections in the document that are not in the notional
registry entry section.  This requires major reworking.

Minor issues:
The figures in the document consist of plain text and it is not easy to see
where the figure text starts in the text or htmlized versions.  I am not quite
sure how this can best be resolved but some delineator at the start of the
figure would be helpful. Maybe a YAML comment at the start of the figure text.

Nits/editorial comments:
General: s/e.g./e.g.,/ (6 instances)

Abstract: Suggest adding "intended to be used to identify document components
formatted according to the YAML Ain’t Markup Language (YAML™) specification" to
te end of the abstract.

s1, para 1: s/the relevant/a corresponding/, s/previously had not/had not
previously/

s1, para 1: Add a reference to BCP13/RFC 6838 i.e.. [MEDIATYPE] after "suffix".

s1.2, para 2: s/section1.2.1/(see Section 1.2.1)/

s1.2.1, para 2: s/while percent-encoding those characters not allowed/but
percent-encoding of those characters is not allowed/

s1.2.1, first bullet:  the term 'serialization detail' ought to be in the list
of YAML terms in s1.1.

s4.2. para 1: s/can infinite-loop traversing the YAML representation graph at
some point, for example:/can result in an infinite-loop when traversing the
YAML representation graph at some point, for example:/

s4.2, first bullet: s/serialize it JSON/serialize it as JSON/

s4.2, para after Fig 4: s/representaion graph/representation graph/

s4.2, para after Fig 4:  Suggest: s/"billion laughs" problem/"billion laughs"
or "Exponential Entity Expansion" problem/

s5:  IANA has not yet updated the registries.  This section should be worded as
requests for IANA to perform the updates.  As mentioned above, the text in
sections 2.1 and 2.2 is not in a state where IANA can use it to update the
registries.

s6: I personally find the mix of reference tag formats for RFCs, where some use
the RFCxxxx format and others are relevant text strings irritating. I would
prefer for all RFC references to be named RFCxxxx.

Appendix B:  Acknowledgements  and Authors' Addresses should be provided as
sections within the body of the document rather than in an Appendix.