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

[Roberto Polli <[e-mail]>]

Dear Elwyn,

sorry for the late reply and thanks for your feedback.
Replies inline. Moreover, you can see a detailed list of your suggestion
in the following Issue https://github.com/ietf-wg-httpapi/mediatypes/issues/83

On Sun, 9 Apr 2023 at 23:17, Elwyn Davies via Datatracker
<[e-mail]> wrote:
>
> Reviewer: Elwyn Davies
> Review result: Not Ready

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

We intend to fix it via this PR
https://github.com/ietf-wg-httpapi/mediatypes/pull/77
and I will notify anyone once an agreement with IANA is achieved.

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

We are trying to fix this together with the IANA. The shape of the section
is the same as the media type registration from RFC9110
https://www.rfc-editor.org/rfc/rfc9110#section-18.8
where the IANA Considerations section references a document section.


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

Now all examples start with the %YAML directive.


> 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/

All fixed, thanks for your detailed review!



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

This is going to be addressed within IANA Review. See
https://github.com/ietf-wg-httpapi/mediatypes/pull/77


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

We tried to follow the guidance provided in
https://httpwg.org/admin/editors/style-guide#reference-style.

this is a small hint that the RFC number is not the identifier they
should be remembering.

Since we are not using ABNF, PR #84 removes two RFC references and the
only RFC reference outside the BCP boilerplate is the one to JSON Text
Sequences.


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

Fixed.

Please, let us know whether the clarifications are sufficient.
Thanks again for all your time,
R.