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 General Area Review Team (Gen-ART) (genart)
Deadline 2023-04-10
Requested 2023-03-20
Authors Roberto Polli , Erik Wilde , Eemeli Aro
I-D last updated 2023-04-09
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 Elwyn B. Davies
State Completed
Request Last Call review on draft-ietf-httpapi-yaml-mediatypes by General Area Review Team (Gen-ART) Assigned
Posted at
Reviewed revision 04 (document currently at 10)
Result Not ready
Completed 2023-04-09
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


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

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

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.