YAML Media Type
draft-ietf-httpapi-yaml-mediatypes-10

# Internet AD comments for draft-ietf-httpapi-yaml-mediatypes-06
CC @ekline

* comment syntax:
  - https://github.com/mnot/ietf-comments/blob/main/format.md

* "Handling Ballot Positions":
  - https://ietf.org/about/groups/iesg/statements/handling-ballot-positions/

## Comments

### S4.1

* Even though the document is Informational, S1.1 introduces the RFC 2119 and
  RFC 8174 keywords (which I find helpful for expressing intent irrespective
  of the document's intended status).

  With that in mind, I think this could be capitalised:

  "Code execution in deserializers should be disabled by default" ->
  "Code execution in deserializers SHOULD be disabled by default"

# GEN AD review of draft-ietf-httpapi-yaml-mediatypes-06

CC @larseggert

Thanks to Elwyn Davies for the General Area Review Team (Gen-ART) review
(https://mailarchive.ietf.org/arch/msg/gen-art/o9UaFCXheaEmcZM-2Vw9RWuFI8Q).

## Comments

### Boilerplate

Document has Informational status, but uses the RFC2119 keywords "SHOULD",
"MAY", and "SHOULD NOT". Given how they are used, that may not be necessary?

### Inclusive language

Found terminology that should be reviewed for inclusivity; see
https://www.rfc-editor.org/part2/#inclusive_language for background and more
guidance:

 * Term `native`; alternatives might be `built-in`, `fundamental`, `ingrained`,
   `intrinsic`, `original`

## Nits

All comments below are about very minor potential issues that you may choose to
address in some way - or ignore - as you see fit. Some were flagged by
automated tools (via https://github.com/larseggert/ietf-reviewtool), so there
will likely be some false positives. There is no need to let me know what you
did with these suggestions.

### Grammar/style

#### Section 3.4, paragraph 7
```
lues not supported in JSON in a multi- document YAML stream 3.5. Fragment ide
                                ^^^^^^^^^^^^^^^
```
This word seems to be formatted incorrectly. Consider fixing the spacing or
removing the hyphen completely.

#### Section 3.5, paragraph 4
```
o improper behaviors (such as the "billion laughs" or "Exponential Entity Exp
                                   ^^^^^^^
```
Use "a billion", or use a number before "billion".

#### "A.1.", paragraph 1
```
 has some security implications too (eg. wrt on identifying parsers or treat
                                     ^^^
```
The abbreviation "e.g." (= for example) requires two periods.

## Notes

This review is in the ["IETF Comments" Markdown format][ICMF], You can use the
[`ietf-comments` tool][ICT] to automatically convert this review into
individual GitHub issues. Review generated by the [`ietf-reviewtool`][IRT].

[ICMF]: https://github.com/mnot/ietf-comments/blob/main/format.md
[ICT]: https://github.com/mnot/ietf-comments
[IRT]: https://github.com/larseggert/ietf-reviewtool

Thank you to Shawn Emery for the SECDIR review.

** Section 1.2.1
In the example resource below, the URL file.yaml#*foo references the
   first alias node *foo pointing to the node with value scalar and not
   the one in the second document; whereas the URL file.yaml#*document_2
   references the root node of the second document { one: [a,
   sequence]}.

Are “file.yaml#*foo” and “file.yaml#*document_2” valid URLs?  There is no scheme or authority.

** Consider leaving the FAQ in the final RFC.  I believe it has archival value in explain design decisions.

** For the responsible AD evaluate:  The following are crucial normative references (especially [YAML]), however they are DOWNREFs not called out in IETF Last Call.

[YAML]    Oren Ben-Kiki, Clark Evans, Ingy dot Net, Tina Müller,
             Pantelis Antoniou, Eemeli Aro, and Thomas Smith, "YAML
             Ain't Markup Language Version 1.2", 1 October 2021,
             <https://yaml.org/spec/1.2.2/>.
[OAS]     Darrel Miller, Jeremy Whitlock, Marsh Gardiner, Mike
             Ralphson, Ron Ratovsky, and Uri Sarid, "OpenAPI
             Specification 3.0.0", 26 July 2017.