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. See #78
[ ] It contains references to sections in the document that are not in the notional
registry entry section. This requires major reworking.
[x] 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 in #84.
[x] General: s/e.g./e.g.,/ (6 instances)
[x] 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.
[x] s1, para 1: s/the relevant/a corresponding/, s/previously had not/had not
previously/
[x] s1, para 1: Add a reference to BCP13/RFC 6838 i.e.. [MEDIATYPE] after "suffix".
[x] s1.2, para 2: s/section1.2.1/(see Section 1.2.1)/
[x] s1.2.1, para 2: s/while percent-encoding those characters not allowed/but
percent-encoding of those characters is not allowed/
[x] s1.2.1, first bullet: the term 'serialization detail' ought to be in the list
of YAML terms in s1.1.
[x] 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:/
[x] s4.2, first bullet: s/serialize it JSON/serialize it as JSON/
[x] s4.2, para after Fig 4: s/representaion graph/representation graph/
[x] 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.
A: We're going to fix this ASAP via #76 . Thanks!
[x] 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.
Gen-ART Review
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. See #78
[ ] It contains references to sections in the document that are not in the notional registry entry section. This requires major reworking.
[x] 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
%YAMLdirective in #84.[x] General: s/e.g./e.g.,/ (6 instances)
[x] 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.
[x] s1, para 1: s/the relevant/a corresponding/, s/previously had not/had not previously/
[x] s1, para 1: Add a reference to BCP13/RFC 6838 i.e.. [MEDIATYPE] after "suffix".
[x] s1.2, para 2: s/section1.2.1/(see Section 1.2.1)/
[x] s1.2.1, para 2: s/while percent-encoding those characters not allowed/but percent-encoding of those characters is not allowed/
[x] s1.2.1, first bullet: the term 'serialization detail' ought to be in the list of YAML terms in s1.1.
[x] 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:/
[x] s4.2, first bullet: s/serialize it JSON/serialize it as JSON/
[x] s4.2, para after Fig 4: s/representaion graph/representation graph/
[x] 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.
A: We're going to fix this ASAP via #76 . Thanks!
A: We tried to follow the guidance provided in https://httpwg.org/admin/editors/style-guide#reference-style.
Since we are not using ABNF, #84 removes two RFC references and the only RFC reference outside the BCP boilerplate is the one to JSON Text Sequences.