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

[Lars Eggert <[e-mail]>]

Elwyn, thank you for your review. I have entered a No Objection ballot for this document.

Lars


> On Apr 10, 2023, at 00:17, Elwyn Davies via Datatracker <[e-mail]> wrote:
> 
> 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.
> 
> 
> 
> _______________________________________________
> Gen-art mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/gen-art