Re: [auth48] AUTH48: RFC-to-be 9512 <draft-ietf-httpapi-yaml-mediatypes-10> for your review

[Roberto Polli <[e-mail]>]

Dear all,

thanks for your accurate review! Replies inline.

On Thu, 21 Dec 2023 at 20:24, <[e-mail]> wrote:
>
> Authors,
>
> While reviewing this document during AUTH48, please resolve (as necessary) the following questions, which are also in the XML file.
>
> 1) <!-- [rfced] This is a question for author Roberto Polli. What is the best way
> to shorten your organization so that it fits in the space allowed in the
> document header in the txt output? Note that we can use the "abbrev"
> attribute of the organization element to use a shortened form in the
> document header and then use the longer form in the Authors' Addresses
> section.
>
> Current:
>  Digital Transformation Department, Italian Government
>
> Perhaps:
>  Digital Transformation Dept.
>
> Or:
>  Italian Government
> -->

Can the following work for you?

abbrev: DTD, Italian Government



>
>
> 2) <!-- [rfced] Please insert any keywords (beyond those that appear in
> the title) for use on https://www.rfc-editor.org/search.
> -->

I think that the "YAML" and "mediatype" keywords contained
in the title are sufficient for searching the document.
We could add "data interchange format".
Anyway, suggestions are welcome.

>
>
> 3) <!-- [rfced] The application/yaml media type is registered in the "Media
> Types" registry, but the +yaml structured syntax suffix is not. May we
> update this text as follows to clarify that? Also, may we update
> "intended to be used to identify" as follows?
>
> Original:
>    This document registers the application/yaml media type and the +yaml
>    structured syntax suffix on the IANA Media Types registry, intended
>    to be used to identify document components serialized according to
>    the YAML specification.
>
> Perhaps:
>    This document defines the application/yaml media type and the +yaml
>    structured syntax suffix, both of which identify document components
>    that are serialized according to the YAML specification.
>
> Or:
>    This document registers the application/yaml media type and the +yaml
>    structured syntax suffix with IANA. Both identify document components
>    that are serialized according to the YAML specification.
> -->

I like the second proposal, since it references the IANA registration.

>
>
> 4) <!-- [rfced] We do not see the terms "content" (except in "content
> negotiation") and "user agent" used in this document. Should these terms
> be removed from this sentence?
>
> Original:
>    The terms "content", "content negotiation", "resource", and "user
>    agent" in this document are to be interpreted as in [HTTP].
> -->

Good catch! I think we can remove "user agent" and "content".

OLD:
   The terms "content", "content negotiation", "resource", and "user
   agent" in this document are to be interpreted as in [HTTP].

NEW:
  The terms  "content negotiation" and "resource"
  in this document are to be interpreted as in [HTTP].

>
>
> 5) <!-- [rfced] We note that Figure 9 starts with "%YAML 1.1" rather than "%YAML
> 1.2". We believe this is intentional per the introductory text before
> Figure 9 that mentions YAML 1.1. However, are any updates needed to this
> sentence in Section 1.1?
>
> Original:
>    Figures containing YAML code always start with the "%YAML 1.2"
>    directive to improve readability.
> -->

OLD:
  Figures containing YAML code always start with the "%YAML 1.2"
  directive to improve readability.
NEW:
  Figures containing YAML code always start with the "%YAML"
  directive to improve readability.


>
>
> 6) <!-- [rfced] We are having trouble understanding how "walking through alias
> nodes" connects to the rest of this sentence. Please review and let us
> know if this sentence should be updated for clarity.
>
> Original:
>    For single-document YAML streams, a fragment identifier that is empty
>    or that starts with "/" is to be interpreted as a JSON Pointer
>    [JSON-POINTER] and is evaluated on the YAML representation graph,
>    walking through alias nodes; in particular, the empty fragment
>    identifier references the root node.
> -->

What do you think about "traversing" instead of "walking through"?

OLD:
    walking through alias nodes; in particular, the empty fragment
    identifier references the root node.
NEW:
    traversing alias nodes; in particular, the empty fragment
    identifier references the root node.

Otherwise, I would retain the current wording since it was agreed upon
during the editorial phase.


>
> 7) <!-- [rfced] This text in Section 2 only introduces the media type in Section
> 2.1 and does not mention the suffix +yaml in Section 2.2. May we either
> delete this sentence altogether or update as shown below?
>
> Original:
>    This section describes the information required to register the above
>    media type according to [MEDIATYPE]
>
> Perhaps:
>    This section includes the information required for IANA to register the
>    application/yaml media type and the +yaml structured syntax suffix per
>    [MEDIATYPE].
> -->

OK!

>
>
> 8) <!--[rfced] As their content is directly about registration templates, may we
> move Sections 2.1 and 2.2 to the IANA Considerations section?

We had this discussion, and decided to separate the registration templates
from the IANA considerations, like in RFC9110 (HTTP).
See for example
https://datatracker.ietf.org/doc/html/rfc9110#name-media-type-registration

>
> Additionally, we do not find the tables in the IANA Considerations section to
> be helpful. We suggest deleting Tables 1 and 2 and updating the text to point
> to the appropriate sections (unless the registration templates are moved to
> the IANA Considerations section). Please let us know your preference in updating
> the IANA Considerations section.
> -->

Replacing the tables with a text is OK. Can the following work for you?

OLD:
  IANA has updated the "Media Types" registry with the registration
information provided below.
  TABLE 1
  IANA has updated the "Structured Syntax Suffixes" registry with the
registration information provided below.
  TABLE 2

NEW:
  IANA has updated the "Media Types" registry
  with the registration information in  Section 2.1 for the media type
"application/yaml".

  IANA has updated the "Structured Syntax Suffixes" registry
  with the registration information in Section 2.2 for the structured
syntax suffix "+yaml".


>
>
> 9) <!--[rfced] FYI: In Section 2.2, we have moved "Fragment identifier
> considerations" to be listed after "Interoperability considerations" to
> parallel the order in Section 6.2 of RFC 6838 and IANA's "Structured Syntax Suffixes" registry.
> -->

OK.

>
>
> 10) <!-- [rfced] May we update "This [YAML] media type registration" as shown
> below?
>
> Original:
>    This [YAML] media type registration is independent of YAML version.
>
> Perhaps:
>    The application/yaml media type is independent of the YAML version.
> -->

OK!

>
>
> 11) <!-- [rfced] This sentence uses "one-document" but we see "single-document"
> used in another sentence. Would you like to update "one-document" here to
> "single-document" for consistency?
>
> Original:
>    When receiving a multi-document stream, an application that only
>    expects one-document streams, ought to signal an error instead of
>    ignoring the extra documents.
> -->

OK. Thanks!

>
>
> 12) <!-- [rfced] We note that "JSON text sequence" is lowercased in RFC
> 7464. Should it also be lowercased in this sentence for consistency with
> RFC 7464?
>
> Original:
>    Current implementations consider different documents in a stream
>    independent, similarly to JSON Text Sequences (see [RFC7464]);
>
> Perhaps:
>    Current implementations consider different documents in a stream
>    independent, similarly to JSON text sequences (see [RFC7464]);
> -->

OK, thanks!

>
>
> 13) <!-- [rfced] Please review the use of "circular" here and let us know if any
> updates are needed. We see "cyclic" in Section 4.2 and Figure 4.
>
> Original:
>    *  circular references represented using anchor (see Section 4.2 and
>       Figure 4);
> -->

OK with "cyclic", thanks!

OLD:
   *  circular references represented using anchor (see Section 4.2 and
       Figure 4);
NEW:
   *  cyclic references represented using anchor (see Section 4.2 and
      Figure 4);

>
>
> 14) <!-- [rfced] Please confirm that the pointer to Section 2.1 is correct
> here.
>
> Original:
>    In Section 2.1, this document extends the use of specifications based
>    on the JSON data model with support for YAML fragment identifiers.
> -->

Good catch. The correct section is 1.2.

OLD:
  In Section 2.1, this document extends the use of specifications based
  on the JSON data model with support for YAML fragment identifiers.
NEW:
  In Section 1.2, this document extends the use of specifications based
  on the JSON data model with support for YAML fragment identifiers.


>
>
> 15) <!-- [rfced] Will "In those cases" be clear to readers? The first sentence
> below is included for context.
>
> Original:
>    Code execution in deserializers should be disabled by default, and
>    only be enabled explicitly.  In those cases, the implementation
>    should ensure - for example, via specific functions - that the code
>    execution results in strictly bounded time/memory limits.
>
> Perhaps:
>    Code execution in deserializers should be disabled by default and
>    only be enabled explicitly.  When this is done, the implementation
>    should ensure (for example, via specific functions) that the code
>    execution results in strictly bounded time/memory limits.
> -->

What do you think of "In the latter case"?

NEW:
    Code execution in deserializers should be disabled by default and
    only be enabled explicitly.  In the latter case, the implementation
    should ensure (for example, via specific functions) that the code
    execution results in strictly bounded time/memory limits.

Otherwise, your proposal "When this is done" is OK.
Let me know!


>
>
> 16) <!-- [rfced] Are "billion laughs" and "Exponential Entity Expansion" the same
> thing? If so, may we update as follows?
>
> Original:
>    Even if a representation graph is not cyclic, treating it as a simple
>    tree could lead to improper behaviors (such as the "billion laughs"
>    or "Exponential Entity Expansion" problem).
>
> Perhaps:
>    Even if a representation graph is not cyclic, treating it as a simple
>    tree could lead to improper behaviors, such as the "Billion Laughs"
>    (also called "Exponential Entity Expansion") problem.
> -->

What do you think about reusing the more general
https://capec.mitre.org/data/definitions/197.html wording?

NEW:
    Even if a representation graph is not cyclic, treating it as a simple
    tree could lead to improper behaviors, such as triggering an
    "Exponential Data Expansion" (e.g. a "Billion Laughs Attack").


>
>
> 17) <!-- [rfced] We note that his reference has a newer version (see
> https://github.com/OAI/OpenAPI-Specification) Would you like to
> reference the latest version?
>
> Original:
>    [OAS]      Darrel Miller, Jeremy Whitlock, Marsh Gardiner, Mike
>               Ralphson, Ron Ratovsky, and Uri Sarid, "OpenAPI
>               Specification 3.0.0", 26 July 2017.
>
> Perhaps:
>    [OAS]      Miller, D., Whitlock, J., Gardiner, M., Ralphson, M.,
>               Ratovsky, R., and U. Sarid, "OpenAPI Specification", v3.1.0,
>               February 2021.
> -->

I prefer to leave this unchanged. Referencing OAS 3.0 is OK.

>
>
> 18) <!-- [rfced] May we update this text as follows to make it a complete
> sentence?
>
> Original:
>    In this example, a couple of YAML nodes that cannot be referenced
>    based on the JSON data model since their mapping keys are not
>    strings.
>
> Perhaps:
>    This example shows a couple of YAML nodes that cannot be referenced
>    based on the JSON data model since their mapping keys are not
>    strings.
> -->

OK, thanks!

>
>
> 19) <!-- [rfced] Please review the use of <tt> in this document to ensure
> consistency. Specifically, should the usage be consistent for the
> following?
>
> <tt>application/yaml</tt>
> "application/yaml"
> application/yaml
>
> <tt>+yaml</tt>
> +yaml
>
> <tt>scalar</tt>
> scalar
>
> <tt>%YAML</tt> directive
> "%YAML 1.2" directive
> -->

I would prefer:

* using <tt> whenever there is a reference to an exact string,
  e.g.,  <tt>application/yaml</tt>, <tt>+yaml</tt>,  <tt>%YAML</tt>,
<tt>scalar</tt>
* I don't know whether <tt> can be used in the media type registration forms.
  If it is not possible, for registration forms I would use the double
quotes (e.g., "application/yaml").

I cannot find any reference to the word 'scalar' without <tt/>.

>
>
> 20) <!-- [rfced] We see type="yaml" and type="example" for the sourcecode elements
> in this document. These are not included in our current list of preferred
> values; see https://www.rfc-editor.org/materials/sourcecode-types.txt.
> Please review the list and let us know which value to use for "type".
>
> If the current list does not contain an applicable type, feel free to suggest
> additions for consideration. Note that it is also acceptable to leave the
> "type" attribute not set.
> -->

Thanks for this hint! If it is possible to suggest the addition of
"yaml" to https://www.rfc-editor.org/materials/sourcecode-types.txt
it would be great to replace in every <sourcecode> containing YAML:

OLD:
  <sourcecode type="example">
NEW:
  <sourcecode type="yaml">

Otherwise, it is OK to just leave the "type" attribute unset.

>
>
> 21) <!-- [rfced] Please review the "Inclusive Language" portion of the online
> Style Guide <https://www.rfc-editor.org/styleguide/part2/#inclusive_language>
> and let us know if any changes are needed.
>
> For example, please consider whether "native" should be updated.
> -->

The expression

"human-friendly, cross-language,
and Unicode-based data serialization language
designed around the common native data types of dynamic programming languages."

is verbatim from the Abstract of https://yaml.org/spec/1.2.2/
If you think it should be updated, it is ok to me.

Thanks for all your time and support,
and sorry for the delayed reply.

Have a nice day,
R.

>
>
> Thank you.
>
> RFC Editor/rv/ap
>
>
> On Dec 21, 2023, at 11:23 AM, [e-mail] wrote:
>
> *****IMPORTANT*****
>
> Updated 2023/12/21
>
> RFC Author(s):
> --------------
>
> Instructions for Completing AUTH48
>
> Your document has now entered AUTH48.  Once it has been reviewed and
> approved by you and all coauthors, it will be published as an RFC.
> If an author is no longer available, there are several remedies
> available as listed in the FAQ (https://www.rfc-editor.org/faq/)
>
> You and you coauthors are responsible for engaging other parties
> (e.g., Contributors or Working Group) as necessary before providing
> your approval.
>
> Planning your review
> ---------------------
>
> Please review the following aspects of your document:
>
> *  RFC Editor questions
>
>    Please review and resolve any questions raised by the RFC Editor
>    that have been included in the XML file as comments marked as
>    follows:
>
>    <!-- [rfced] ... -->
>
>    These questions will also be sent in a subsequent email.
>
> *  Changes submitted by coauthors
>
>    Please ensure that you review any changes submitted by your
>    coauthors.  We assume that if you do not speak up that you
>    agree to changes submitted by your coauthors.
>
> *  Content
>
>    Please review the full content of the document, as this cannot
>    change once the RFC is published.  Please pay particular attention to:
>    - IANA considerations updates (if applicable)
>    - contact information
>    - references
>
> *  Copyright notices and legends
>
>    Please review the copyright notice and legends as defined in
>    RFC 5378 and the Trust Legal Provisions
>    (TLP – https://trustee.ietf.org/license-info/)
>
> *  Semantic markup
>
>    Please review the markup in the XML file to ensure that elements of
>    content are correctly tagged.  For example, ensure that <sourcecode>
>    and <artwork> are set correctly.  See details at
>    <https://authors.ietf.org/rfcxml-vocabulary>.
>
> *  Formatted output
>
>    Please review the PDF, HTML, and TXT files to ensure that the
>    formatted output, as generated from the markup in the XML file, is
>    reasonable.  Please note that the TXT will have formatting
>    limitations compared to the PDF and HTML.
>
>
> Submitting changes
> ------------------
>
> To submit changes, please reply to this email using ‘REPLY ALL’ as all
> the parties CCed on this message need to see your changes. The parties
> include:
>
>    *  your coauthors
>
>    *  [e-mail] (the RPC team)
>
>    *  other document participants, depending on the stream (e.g.,
>       IETF Stream participants are your working group chairs, the
>       responsible ADs, and the document shepherd).
>
>    *  [e-mail], which is a new archival mailing list
>       to preserve AUTH48 conversations; it is not an active discussion
>       list:
>
>      *  More info:
>         https://mailarchive.ietf.org/arch/msg/ietf-announce/yb6lpIGh-4Q9l2USxIAe6P8O4Zc
>
>      *  The archive itself:
>         https://mailarchive.ietf.org/arch/browse/auth48archive/
>
>      *  Note: If only absolutely necessary, you may temporarily opt out
>         of the archiving of messages (e.g., to discuss a sensitive matter).
>         If needed, please add a note at the top of the message that you
>         have dropped the address. When the discussion is concluded,
>         [e-mail] will be re-added to the CC list and
>         its addition will be noted at the top of the message.
>
> You may submit your changes in one of two ways:
>
> An update to the provided XML file
>  — OR —
> An explicit list of changes in this format
>
> Section # (or indicate Global)
>
> OLD:
> old text
>
> NEW:
> new text
>
> You do not need to reply with both an updated XML file and an explicit
> list of changes, as either form is sufficient.
>
> We will ask a stream manager to review and approve any changes that seem
> beyond editorial in nature, e.g., addition of new text, deletion of text,
> and technical changes.  Information about stream managers can be found in
> the FAQ.  Editorial changes do not require approval from a stream manager.
>
>
> Approving for publication
> --------------------------
>
> To approve your RFC for publication, please reply to this email stating
> that you approve this RFC for publication.  Please use ‘REPLY ALL’,
> as all the parties CCed on this message need to see your approval.
>
>
> Files
> -----
>
> The files are available here:
>    https://www.rfc-editor.org/authors/rfc9512.xml
>    https://www.rfc-editor.org/authors/rfc9512.html
>    https://www.rfc-editor.org/authors/rfc9512.pdf
>    https://www.rfc-editor.org/authors/rfc9512.txt
>
> Diff file of the text:
>    https://www.rfc-editor.org/authors/rfc9512-diff.html
>    https://www.rfc-editor.org/authors/rfc9512-rfcdiff.html (side by side)
>
> Diff of the XML:
>    https://www.rfc-editor.org/authors/rfc9512-xmldiff1.html
>
>
> Tracking progress
> -----------------
>
> The details of the AUTH48 status of your document are here:
>    https://www.rfc-editor.org/auth48/rfc9512
>
> Please let us know if you have any questions.
>
> Thank you for your cooperation,
>
> RFC Editor
>
> --------------------------------------
> RFC9512 (draft-ietf-httpapi-yaml-mediatypes-10)
>
> Title            : YAML Media Type
> Author(s)        : R. Polli, E. Wilde, E. Aro
> WG Chair(s)      : Darrel Miller, Rich Salz
> Area Director(s) : Murray Kucherawy, Francesca Palombini
>
>