idnits 2.17.00 (12 Aug 2021) /tmp/idnits43849/draft-ietf-httpapi-yaml-mediatypes-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document date (1 April 2022) is 43 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '0' on line 271 -- Looks like a reference, but probably isn't: '1' on line 271 Summary: 0 errors (**), 0 flaws (~~), 0 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTPAPI R. Polli 3 Internet-Draft Digital Transformation Department, Italian Government 4 Intended status: Informational E. Wilde 5 Expires: 3 October 2022 Axway 6 E. Aro 7 1 April 2022 9 YAML Media Types 10 draft-ietf-httpapi-yaml-mediatypes-00 12 Abstract 14 This document registers the application/yaml media type and the +yaml 15 structured syntax suffix on the IANA Media Types registry. 17 Note to Readers 19 _RFC EDITOR: please remove this section before publication_ 21 Discussion of this draft takes place on the HTTP APIs working group 22 mailing list (httpapi@ietf.org), which is archived at 23 https://mailarchive.ietf.org/arch/browse/httpapi/ 24 (https://mailarchive.ietf.org/arch/browse/httpapi/). 26 The source code and issues list for this draft can be found at 27 https://github.com/ietf-wg-httpapi/mediatypes (https://github.com/ 28 ietf-wg-httpapi/mediatypes). 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at https://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on 3 October 2022. 47 Copyright Notice 49 Copyright (c) 2022 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 54 license-info) in effect on the date of publication of this document. 55 Please review these documents carefully, as they describe your rights 56 and restrictions with respect to this document. Code Components 57 extracted from this document must include Revised BSD License text as 58 described in Section 4.e of the Trust Legal Provisions and are 59 provided without warranty as described in the Revised BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 64 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 65 2. Media Type registrations . . . . . . . . . . . . . . . . . . 3 66 2.1. Media Type application/yaml . . . . . . . . . . . . . . . 3 67 2.2. The +yaml Structured Syntax Suffix . . . . . . . . . . . 4 68 3. Interoperability Considerations . . . . . . . . . . . . . . . 5 69 3.1. YAML is an Evolving Language . . . . . . . . . . . . . . 5 70 3.2. YAML and JSON . . . . . . . . . . . . . . . . . . . . . . 5 71 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 72 4.1. Arbitrary Code Execution . . . . . . . . . . . . . . . . 6 73 4.2. Resource Exhaustion . . . . . . . . . . . . . . . . . . . 7 74 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 75 6. Normative References . . . . . . . . . . . . . . . . . . . . 8 76 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9 77 FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 78 Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 81 1. Introduction 83 YAML [YAML] is a data serialization format that is widely used on the 84 Internet, including in the API sector (e.g. see [oas]) but the 85 relevant media type and structured syntax suffix are not registered 86 by IANA. 88 To increase interoperability when exchanging YAML data and leverage 89 content negotiation mechanisms when exchanging YAML resources, this 90 specification registers the application/yaml media type and the +yaml 91 structured syntax suffix. 93 Moreover, it provides security considerations and interoperability 94 considerations related to [YAML], including its relation with [JSON]. 96 1.1. Notational Conventions 98 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 99 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 100 "OPTIONAL" in this document are to be interpreted as described in 101 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 102 capitals, as shown here. These words may also appear in this 103 document in lower case as plain English words, absent their normative 104 meanings. 106 This document uses the Augmented BNF defined in [RFC5234] and updated 107 by [RFC7405]. 109 The terms "content", "content negotiation", "resource", and "user 110 agent" in this document are to be interpreted as in [SEMANTICS]. 112 2. Media Type registrations 114 This section describes the information required to register the above 115 media types according to [MEDIATYPE] 117 2.1. Media Type application/yaml 119 The following information serves as the registration form for the 120 application/yaml media type. 122 Type name: application 124 Subtype name: yaml 126 Required parameters: None 128 Optional parameters: None; unrecognized parameters should be ignored 130 Encoding considerations: binary 132 Security considerations: see Section 4 of this document 134 Interoperability considerations: see Section 3 of this document 136 Published specification: this document 138 Applications that use this media type: HTTP 140 Fragment identifier considerations: None 142 Additional information: 144 * Deprecated alias names for this type: application/x-yaml, text/ 145 yaml, text/x-yaml 147 * Magic number(s) n/a 149 * File extension(s): yaml, yml 151 * Macintosh file type code(s): n/a 153 Person and email address to contact for further information: See Aut 154 hors' Addresses section. 156 Intended usage: COMMON 158 Restrictions on usage: None. 160 Author: See Authors' Addresses section. 162 Change controller: n/a 164 2.2. The +yaml Structured Syntax Suffix 166 The suffix +yaml MAY be used with any media type whose representation 167 follows that established for application/yaml. The media type 168 structured syntax suffix registration form follows. See [MEDIATYPE] 169 for definitions of each of the registration form headings. 171 Name: YAML Ain't Markup LanguageML (YAML) 173 +suffix: +yaml 175 References: [YAML] 177 Encoding considerations: see Section 2.1 179 Fragment identifier considerations: The syntax and semantics of 180 fragment identifiers specified for +yaml SHOULD be as specified 181 for Section 2.1 The syntax and semantics for fragment identifiers 182 for a specific xxx/yyy+yaml SHOULD be processed as follows: 184 1. For cases defined in +yaml, where the fragment identifier 185 resolves per the +yaml rules, then process as specified in 186 +yaml. 188 2. For cases defined in +yaml, where the fragment identifier does 189 not resolve per the +yaml rules, then process as specified in 190 xxx/yyy+yaml. 192 3. For cases not defined in +yaml, then process as specified in 193 xxx/yyy+yaml. 195 Interoperability considerations: See Section 2.1 197 Security considerations: See Section 2.1 199 Contact: See Authors' Addresses section. 201 Author: See Authors' Addresses section 203 Change controller: n/a 205 3. Interoperability Considerations 207 3.1. YAML is an Evolving Language 209 YAML is an evolving language and, in time, some features have been 210 added, and others removed. 212 While this document is based on a given YAML version [YAML], media 213 types registration does not imply a specific version. This allows 214 content negotiation of version-independent YAML resources. 216 Implementers concerned about features related to a specific YAML 217 version can specify it in the documents using the %YAML directive 218 (see Section 6.8.1 of [YAML]). 220 3.2. YAML and JSON 222 When using flow collection styles (see Section 7.4 of [YAML]) a YAML 223 document could look like JSON [JSON], thus similar interoperability 224 considerations apply. 226 When using YAML as a more efficient format to serialize information 227 intented to be consumed as JSON, information can be discarded: this 228 includes comments (see Section 3.2.3.3 of [YAML]) and alias nodes 229 (see Section 7.1 of [YAML]), that do not have a JSON counterpart. 231 # This comment will be lost 232 # when serializing in JSON. 233 Title: 234 type: string 235 maxLength: &text_limit 64 237 Name: 238 type: string 239 maxLength: *text_limit # Replaced by the value 64. 241 Figure 1: JSON replaces alias nodes with static values. 243 Implementers need to ensure that relevant information will not be 244 lost during the processing. For example, they might consider 245 acceptable that alias nodes are replaced by static values. 247 In some cases an implementer may want to define a list of allowed 248 YAML features, taking into account that the following ones might have 249 interoperability issues with JSON: 251 * non UTF-8 encoding, since YAML supports UTF-16 and UTF-32 in 252 addition to UTF-8; 254 * mapping keys that are not strings; 256 * circular references represented using anchor (see Section 4.2 and 257 Figure 3); 259 * .inf and .nan float values, since JSON does not support them; 261 * non-JSON types, including the ones associated with tags like 262 !!timestamp that were included in the default schema of older YAML 263 versions; 265 * tags in general, and specifically the ones that do not map to JSON 266 types like custom and local tags such as !!python/object and 267 !mytag (see Section 2.4 of [YAML]); 269 non-json-keys: 270 2020-01-01: a timestamp 271 [0, 1]: a sequence 272 ? {k: v} 273 : a map 274 non-json-value: 2020-01-01 276 Figure 2: Example of mapping keys not supported in JSON 278 4. Security Considerations 280 Security requirements for both media type and media type suffix 281 registrations are discussed in Section 4.6 of [MEDIATYPE]. 283 4.1. Arbitrary Code Execution 285 Care should be used when using YAML tags, because their resolution 286 might trigger unexpected code execution. 288 Code execution in deserializers should be disabled by default, and 289 only be enabled explicitly. In those cases, the implementation 290 should ensure - for example, via specific functions - that the code 291 execution results in strictly bounded time/memory limits. 293 Many implementations provide safe deserializers addressing these 294 issues. 296 4.2. Resource Exhaustion 298 YAML documents are rooted, connected, directed graphs and can contain 299 reference cycles, so they can't be treated as simple trees (see 300 Section 3.2.1 of [YAML]). An implementation that attempts to do that 301 can infinite-loop at some point (e.g. when trying to serialize a YAML 302 document in JSON). 304 x: &x 305 y: *x 307 Figure 3: A cyclic document 309 Even if a document is not cyclic, treating it as a simple tree could 310 lead to improper behaviors (such as the "billion laughs" problem). 312 x1: &a1 ["a", "a"] 313 x2: &a2 [*a1, *a1] 314 x3: &a3 [*a2, *a2] 316 Figure 4: A billion laughs document 318 This can be addressed using processors limiting the anchor recursion 319 depth and validating the input before processing it; even in these 320 cases it is important to carefully test the implementation you are 321 going to use. The same considerations apply when serializing a YAML 322 representation graph in a format that does not support reference 323 cycles (see Section 3.2). 325 5. IANA Considerations 327 This specification defines the following new Internet media types 328 [MEDIATYPE]. 330 IANA has updated the "Media Types" registry at 331 https://www.iana.org/assignments/media-types 332 (https://www.iana.org/assignments/media-types) with the registration 333 information provided below. 335 +==================+==============================+ 336 | Media Type | Section | 337 +==================+==============================+ 338 | application/yaml | Section 2.1 of this document | 339 +------------------+------------------------------+ 341 Table 1 343 IANA has updated the "Structured Syntax Suffixes" registry at 344 https://www.iana.org/assignments/media-type-structured-suffix 345 (https://www.iana.org/assignments/media-type-structured-suffix) with 346 the registration information provided below. 348 +========+==============================+ 349 | Suffix | Section | 350 +========+==============================+ 351 | +yaml | Section 2.2 of this document | 352 +--------+------------------------------+ 354 Table 2 356 6. Normative References 358 [JSON] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 359 Interchange Format", STD 90, RFC 8259, 360 DOI 10.17487/RFC8259, December 2017, 361 . 363 [MEDIATYPE] 364 Freed, N., Klensin, J., and T. Hansen, "Media Type 365 Specifications and Registration Procedures", BCP 13, 366 RFC 6838, DOI 10.17487/RFC6838, January 2013, 367 . 369 [oas] Darrel Miller, Jeremy Whitlock, Marsh Gardiner, Mike 370 Ralphson, Ron Ratovsky, and Uri Sarid, "OpenAPI 371 Specification 3.0.0", 26 July 2017. 373 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 374 Requirement Levels", BCP 14, RFC 2119, 375 DOI 10.17487/RFC2119, March 1997, 376 . 378 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 379 Specifications: ABNF", STD 68, RFC 5234, 380 DOI 10.17487/RFC5234, January 2008, 381 . 383 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 384 RFC 7405, DOI 10.17487/RFC7405, December 2014, 385 . 387 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 388 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 389 May 2017, . 391 [SEMANTICS] 392 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 393 Semantics", Work in Progress, Internet-Draft, draft-ietf- 394 httpbis-semantics-19, 12 September 2021, 395 . 398 [YAML] Oren Ben-Kiki, Clark Evans, and Ingy dot Net, "YAML Ain't 399 Markup Language Version 1.2", 1 October 2021, 400 . 402 Appendix A. Acknowledgements 404 Thanks to Erik Wilde and David Biesack for being the initial 405 contributors of this specification, and to Darrel Miller and Rich 406 Salz for their support during the adoption phase. 408 In addition to the people above, this document owes a lot to the 409 extensive discussion inside and outside the HTTPAPI workgroup. The 410 following contributors have helped improve this specification by 411 opening pull requests, reporting bugs, asking smart questions, 412 drafting or reviewing text, and evaluating open issues: 414 Tina (tinita) Mueller, Ben Hutton, Manu Sporny and Jason Desrosiers. 416 FAQ 418 Q: Why this document? After all these years, we still lack a proper 419 media-type for YAML. This has some security implications too (eg. 420 wrt on identifying parsers or treat downloads) 422 Change Log 424 RFC EDITOR PLEASE DELETE THIS SECTION. 426 Authors' Addresses 428 Roberto Polli 429 Digital Transformation Department, Italian Government 430 Italy 431 Email: robipolli@gmail.com 433 Erik Wilde 434 Axway 435 Switzerland 436 Email: erik.wilde@dret.net 438 Eemeli Aro 439 Finland 440 Email: eemeli@gmail.com