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

[Rebecca VanRheenen <[e-mail]>]

Hi authors,

This is a friendly reminder that we await answers to the questions below and your review of the document before continuing with the publication process. 

Thank you,
RFC Editor/rv



> On Dec 21, 2023, at 11:24 AM, [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 
> -->
> 
> 
> 2) <!-- [rfced] Please insert any keywords (beyond those that appear in 
> the title) for use on https://www.rfc-editor.org/search.
> -->
> 
> 
> 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.
> -->
> 
> 
> 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].
> -->
> 
> 
> 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.
> -->
> 
> 
> 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.  
> -->
> 
> 
> 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].
> -->
> 
> 
> 8) <!--[rfced] As their content is directly about registration templates, may we
> move Sections 2.1 and 2.2 to the IANA Considerations section?
> 
> 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.
> -->
> 
> 
> 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.
> -->
> 
> 
> 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.
> -->
> 
> 
> 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.
> -->
> 
> 
> 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]);
> -->
> 
> 
> 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);
> -->
> 
> 
> 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.
> -->
> 
> 
> 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.
> -->
> 
> 
> 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.
> -->
> 
> 
> 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.
> -->
> 
> 
> 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.
> -->
> 
> 
> 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
> -->
> 
> 
> 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.
> -->
> 
> 
> 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.
> -->
> 
> 
> 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
> 
>