idnits 2.17.1 draft-ietf-httpapi-yaml-mediatypes-02.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: ---------------------------------------------------------------------------- == There are 2 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (23 June 2022) is 672 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 332 -- Looks like a reference, but probably isn't: '1' on line 332 == Outdated reference: A later version (-21) exists of draft-ietf-jsonpath-base-05 Summary: 0 errors (**), 0 flaws (~~), 3 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: 25 December 2022 Axway 6 E. Aro 7 Mozilla 8 23 June 2022 10 YAML Media Type 11 draft-ietf-httpapi-yaml-mediatypes-02 13 Abstract 15 This document registers the application/yaml media type and the +yaml 16 structured syntax suffix on the IANA Media Types registry. 18 Note to Readers 20 _RFC EDITOR: please remove this section before publication_ 22 Discussion of this draft takes place on the HTTP APIs working group 23 mailing list (httpapi@ietf.org), which is archived at 24 https://mailarchive.ietf.org/arch/browse/httpapi/ 25 (https://mailarchive.ietf.org/arch/browse/httpapi/). 27 The source code and issues list for this draft can be found at 28 https://github.com/ietf-wg-httpapi/mediatypes (https://github.com/ 29 ietf-wg-httpapi/mediatypes). 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at https://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on 25 December 2022. 48 Copyright Notice 50 Copyright (c) 2022 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 55 license-info) in effect on the date of publication of this document. 56 Please review these documents carefully, as they describe your rights 57 and restrictions with respect to this document. Code Components 58 extracted from this document must include Revised BSD License text as 59 described in Section 4.e of the Trust Legal Provisions and are 60 provided without warranty as described in the Revised BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 65 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 66 1.2. Fragment identification . . . . . . . . . . . . . . . . . 3 67 2. Media Type and Structured Syntax Suffix registrations . . . . 4 68 2.1. Media Type application/yaml . . . . . . . . . . . . . . . 4 69 2.2. The +yaml Structured Syntax Suffix . . . . . . . . . . . 5 70 3. Interoperability Considerations . . . . . . . . . . . . . . . 6 71 3.1. YAML is an Evolving Language . . . . . . . . . . . . . . 6 72 3.2. YAML and JSON . . . . . . . . . . . . . . . . . . . . . . 6 73 3.3. Fragment identifiers . . . . . . . . . . . . . . . . . . 8 74 4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 75 4.1. Arbitrary Code Execution . . . . . . . . . . . . . . . . 8 76 4.2. Resource Exhaustion . . . . . . . . . . . . . . . . . . . 9 77 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 78 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 79 6.1. Normative References . . . . . . . . . . . . . . . . . . 10 80 6.2. Informative References . . . . . . . . . . . . . . . . . 11 81 Appendix A. Examples related to fragment identifier 82 interoperability . . . . . . . . . . . . . . . . . . . . 12 83 A.1. Unreferenceable nodes . . . . . . . . . . . . . . . . . . 12 84 A.2. Referencing a missing node . . . . . . . . . . . . . . . 12 85 A.3. Representation graph with anchors and cyclic 86 references . . . . . . . . . . . . . . . . . . . . . . . 12 87 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 13 88 FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 89 Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 90 Since draft-ietf-httpapi-yaml-mediatypes-01 . . . . . . . . . . 14 91 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 93 1. Introduction 95 YAML [YAML] is a data serialization format that is widely used on the 96 Internet, including in the API sector (e.g. see [OAS]), but the 97 relevant media type and structured syntax suffix previously had not 98 been registered by IANA. 100 To increase interoperability when exchanging YAML data and leverage 101 content negotiation mechanisms when exchanging YAML resources, this 102 specification registers the application/yaml media type and the +yaml 103 structured syntax suffix. 105 Moreover, it provides security considerations and interoperability 106 considerations related to [YAML], including its relation with [JSON]. 108 1.1. Notational Conventions 110 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 111 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 112 "OPTIONAL" in this document are to be interpreted as described in 113 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 114 capitals, as shown here. These words may also appear in this 115 document in lower case as plain English words, absent their normative 116 meanings. 118 This document uses the Augmented BNF defined in [RFC5234] and updated 119 by [RFC7405]. 121 The terms "content", "content negotiation", "resource", and "user 122 agent" in this document are to be interpreted as in [SEMANTICS]. 124 The terms "fragment" and "fragment identifier" in this document are 125 to be interpreted as in [URI]. 127 The terms "node", "alias node", "anchor" and "named anchor" in this 128 document are to be intepreded as in [YAML]. 130 1.2. Fragment identification 132 This section describes how to use alias nodes (see Section 3.2.2.2 133 and 7.1 of [YAML]) as fragment identifiers to designate nodes. 135 A YAML alias node can be represented in a URI fragment identifier by 136 encoding it into octects using UTF-8 [UTF-8], while percent-encoding 137 those characters not allowed by the fragment rule in Section 3.5 of 138 [URI]. 140 If multiple nodes would match a fragment identifier, the first such 141 match is selected. 143 A fragment identifier is not guaranteed to reference an existing 144 node. Therefore, applications SHOULD define how an unresolved alias 145 node ought to be handled. 147 Users concerned with interoperability of fragment identifiers: 149 * SHOULD limit alias nodes to a set of characters that do not 150 require encoding to be expressed as URI fragment identifiers: this 151 is generally possible since named anchors are a serialization 152 detail; 154 * SHOULD NOT use alias nodes that match multiple nodes. 156 In the example resource below, the URL file.yaml#*foo references the 157 alias node *foo pointing to the node with value scalar; whereas the 158 URL file.yaml#*bar references the alias node *bar pointing to the 159 node with value [ some, sequence, items ]. 161 %YAML 1.2 162 --- 163 one: &foo scalar 164 two: &bar 165 - some 166 - sequence 167 - items 169 2. Media Type and Structured Syntax Suffix registrations 171 This section describes the information required to register the above 172 media type according to [MEDIATYPE] 174 2.1. Media Type application/yaml 176 The media type for YAML text is application/yaml; the following 177 information serves as the registration form for this media type. 179 Type name: application 181 Subtype name: yaml 183 Required parameters: None 185 Optional parameters: None; unrecognized parameters should be ignored 187 Encoding considerations: binary 188 Security considerations: see Section 4 of this document 190 Interoperability considerations: see Section 3 of this document 192 Published specification: [YAML] 194 Applications that use this media type: HTTP 196 Fragment identifier considerations: An empty fragment identifier 197 references the root node. 199 A fragment identifier starting with "*" is to be interpreted as a 200 YAML alias node Section 1.2. 202 A fragment identifier starting with "/" is to be interpreted as a 203 JSON Pointer [JSON-POINTER] and is evaluated on the YAML 204 representation graph, walking through alias nodes; this syntax can 205 only reference YAML nodes that are on a path that is made up of 206 nodes interoperable with the JSON data model (see Section 3.2). 208 Additional information: 210 * Deprecated alias names for this type: application/x-yaml, text/ 211 yaml, text/x-yaml 213 * Magic number(s) n/a 215 * File extension(s): yaml, yml 217 * Macintosh file type code(s): n/a 219 Person and email address to contact for further information: See Aut 220 hors' Addresses section. 222 Intended usage: COMMON 224 Restrictions on usage: None. 226 Author: See Authors' Addresses section. 228 Change controller: n/a 230 2.2. The +yaml Structured Syntax Suffix 232 The suffix +yaml MAY be used with any media type whose representation 233 follows that established for application/yaml. The media type 234 structured syntax suffix registration form follows. See [MEDIATYPE] 235 for definitions of each of the registration form headings. 237 Name: YAML Ain't Markup Language (YAML) 239 +suffix: +yaml 241 References: [YAML] 243 Encoding considerations: see Section 2.1 245 Fragment identifier considerations: Differently from application/ 246 yaml, there is no fragment identification syntax defined for 247 +yaml. 249 A specific xxx/yyy+yaml media type needs to define the syntax and 250 semantics for fragment identifiers because the ones in Section 2.1 251 do not apply unless explicitly expressed. 253 Interoperability considerations: See Section 2.1 255 Security considerations: See Section 2.1 257 Contact: See Authors' Addresses section. 259 Author: See Authors' Addresses section 261 Change controller: n/a 263 3. Interoperability Considerations 265 3.1. YAML is an Evolving Language 267 YAML is an evolving language and, over time, some features have been 268 added and others removed. 270 While this document is based on a given YAML version [YAML], the 271 media type registration does not imply a specific version. This 272 allows content negotiation of version-independent YAML resources. 274 Implementers concerned about features related to a specific YAML 275 version can specify it in documents using the %YAML directive (see 276 Section 6.8.1 of [YAML]). 278 3.2. YAML and JSON 280 When using flow collection styles (see Section 7.4 of [YAML]) a YAML 281 document could look like JSON [JSON], thus similar interoperability 282 considerations apply. 284 When using YAML as a more efficient format to serialize information 285 intented to be consumed as JSON, information can be discarded: this 286 includes comments (see Section 3.2.3.3 of [YAML]) and alias nodes 287 (see Section 7.1 of [YAML]), that do not have a JSON counterpart. 289 # This comment will be lost 290 # when serializing in JSON. 291 Title: 292 type: string 293 maxLength: &text_limit 64 295 Name: 296 type: string 297 maxLength: *text_limit # Replaced by the value 64. 299 Figure 1: JSON replaces alias nodes with static values. 301 Implementers need to ensure that relevant information will not be 302 lost during the processing. For example, they might consider 303 acceptable that alias nodes are replaced by static values. 305 In some cases an implementer may want to define a list of allowed 306 YAML features, taking into account that the following ones might have 307 interoperability issues with JSON: 309 * non UTF-8 encoding, since YAML supports UTF-16 and UTF-32 in 310 addition to UTF-8; 312 * mapping keys that are not strings; 314 * circular references represented using anchor (see Section 4.2 and 315 Figure 3); 317 * .inf and .nan float values, since JSON does not support them; 319 * non-JSON types, including the ones associated with tags like 320 !!timestamp that were included in the default schema of older YAML 321 versions; 323 * tags in general, and specifically the ones that do not map to JSON 324 types like custom and local tags such as !!python/object and 325 !mytag (see Section 2.4 of [YAML]); 327 %YAML 1.2 328 --- 329 non-json-keys: 330 0: a number 331 2020-01-01: a timestamp 332 [0, 1]: a sequence 333 ? {k: v} 334 : a map 335 non-json-value: 2020-01-01 337 Figure 2: Example of mapping keys not supported in JSON 339 3.3. Fragment identifiers 341 To allow fragment identifiers to traverse alias nodes, the YAML 342 representation graph needs to be generated before the fragment 343 identifier evaluation. It is important that this evaluation will not 344 cause the issues mentioned in Section 3.2 and in Security 345 considerations (Section 4) such as infinite loops and unexpected code 346 execution. 348 Implementers need to consider that the YAML version and supported 349 features (e.g. merge keys) can impact on the generation of the 350 representation graph (see Figure 8). 352 In Section 2.1, this document extends the use of specifications based 353 on the JSON data model with support for YAML fragment identifiers. 354 This is to improve the interoperability of already consolidated 355 practices, such as the one of writing OpenAPI documents [OAS] in 356 YAML. 358 Appendix A provides a non exhaustive list of examples that could help 359 understanding interoperability issues related to fragment 360 identifiers. 362 4. Security Considerations 364 Security requirements for both media type and media type suffix 365 registrations are discussed in Section 4.6 of [MEDIATYPE]. 367 4.1. Arbitrary Code Execution 369 Care should be used when using YAML tags, because their resolution 370 might trigger unexpected code execution. 372 Code execution in deserializers should be disabled by default, and 373 only be enabled explicitly. In those cases, the implementation 374 should ensure - for example, via specific functions - that the code 375 execution results in strictly bounded time/memory limits. 377 Many implementations provide safe deserializers addressing these 378 issues. 380 4.2. Resource Exhaustion 382 YAML documents are rooted, connected, directed graphs and can contain 383 reference cycles, so they can't be treated as simple trees (see 384 Section 3.2.1 of [YAML]). An implementation that attempts to do that 385 can infinite-loop traversing the YAML representation graph at some 386 point, for example: 388 * when trying to serialize it JSON; 390 * or when searching/identifying nodes using specifications based on 391 the JSON data model (e.g. [JSON-POINTER]). 393 x: &x 394 y: *x 396 Figure 3: A cyclic document 398 Even if a document is not cyclic, treating it as a simple tree could 399 lead to improper behaviors (such as the "billion laughs" problem). 401 x1: &a1 ["a", "a"] 402 x2: &a2 [*a1, *a1] 403 x3: &a3 [*a2, *a2] 405 Figure 4: A billion laughs document 407 This can be addressed using processors limiting the anchor recursion 408 depth and validating the input before processing it; even in these 409 cases it is important to carefully test the implementation you are 410 going to use. The same considerations apply when serializing a YAML 411 representation graph in a format that does not support reference 412 cycles (see Section 3.2). 414 5. IANA Considerations 416 This specification defines the following new Internet media type 417 [MEDIATYPE]. 419 IANA has updated the "Media Types" registry at 420 https://www.iana.org/assignments/media-types 421 (https://www.iana.org/assignments/media-types) with the registration 422 information provided below. 424 +==================+==============================+ 425 | Media Type | Section | 426 +==================+==============================+ 427 | application/yaml | Section 2.1 of this document | 428 +------------------+------------------------------+ 430 Table 1 432 IANA has updated the "Structured Syntax Suffixes" registry at 433 https://www.iana.org/assignments/media-type-structured-suffix 434 (https://www.iana.org/assignments/media-type-structured-suffix) with 435 the registration information provided below. 437 +========+==============================+ 438 | Suffix | Section | 439 +========+==============================+ 440 | +yaml | Section 2.2 of this document | 441 +--------+------------------------------+ 443 Table 2 445 6. References 447 6.1. Normative References 449 [JSON] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 450 Interchange Format", STD 90, RFC 8259, 451 DOI 10.17487/RFC8259, December 2017, 452 . 454 [JSON-POINTER] 455 Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 456 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 457 DOI 10.17487/RFC6901, April 2013, 458 . 460 [MEDIATYPE] 461 Freed, N., Klensin, J., and T. Hansen, "Media Type 462 Specifications and Registration Procedures", BCP 13, 463 RFC 6838, DOI 10.17487/RFC6838, January 2013, 464 . 466 [OAS] Darrel Miller, Jeremy Whitlock, Marsh Gardiner, Mike 467 Ralphson, Ron Ratovsky, and Uri Sarid, "OpenAPI 468 Specification 3.0.0", 26 July 2017. 470 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 471 Requirement Levels", BCP 14, RFC 2119, 472 DOI 10.17487/RFC2119, March 1997, 473 . 475 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 476 Specifications: ABNF", STD 68, RFC 5234, 477 DOI 10.17487/RFC5234, January 2008, 478 . 480 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 481 RFC 7405, DOI 10.17487/RFC7405, December 2014, 482 . 484 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 485 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 486 May 2017, . 488 [SEMANTICS] 489 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 490 Semantics", Work in Progress, Internet-Draft, draft-ietf- 491 httpbis-semantics-19, 12 September 2021, 492 . 495 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 496 Resource Identifier (URI): Generic Syntax", STD 66, 497 RFC 3986, DOI 10.17487/RFC3986, January 2005, 498 . 500 [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO 501 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 502 2003, . 504 [YAML] Oren Ben-Kiki, Clark Evans, Ingy dot Net, Tina Müller, 505 Pantelis Antoniou, Eemeli Aro, and Thomas Smith, "YAML 506 Ain't Markup Language Version 1.2", 1 October 2021, 507 . 509 6.2. Informative References 511 [I-D.ietf-jsonpath-base] 512 Gössner, S., Normington, G., and C. Bormann, "JSONPath: 513 Query expressions for JSON", Work in Progress, Internet- 514 Draft, draft-ietf-jsonpath-base-05, 25 April 2022, 515 . 518 Appendix A. Examples related to fragment identifier interoperability 520 A.1. Unreferenceable nodes 522 In this example, a couple of YAML nodes that cannot be referenced 523 based on the JSON data model since their mapping keys are not 524 strings. 526 %YAML 1.2 527 --- 528 a-map-cannot: 529 ? {be: expressed} 530 : with a JSON Pointer 532 0: no numeric mapping keys in JSON 534 Figure 5: Example of YAML nodes that are not referenceable based 535 on JSON data model. 537 A.2. Referencing a missing node 539 In this example the fragment #/0 does not reference an existing node 541 0: "JSON Pointer `#/0` references a string mapping key." 543 Figure 6: Example of a JSON Pointer that does not reference an 544 existing node. 546 A.3. Representation graph with anchors and cyclic references 548 In this YAML document, the #/foo/bar/baz fragment identifier 549 traverses the representation graph and references the string you. 550 Moreover, the presence of a cyclic reference implies that there are 551 infinite fragment identifiers #/foo/bat/../bat/bar referencing the 552 &anchor node. 554 anchor: &anchor 555 baz: you 556 foo: &foo 557 bar: *anchor 558 bat: *foo 560 Figure 7: Example of a cyclic references and alias nodes. 562 Many YAML implementations will resolve the merge key "<<:" 563 (https://yaml.org/type/merge.html) defined in YAML 1.1 in the 564 representation graph. This means that the fragment #/book/author/ 565 given_name references the string Federico and that the fragment 566 #/book/<< will not reference any existing node. 568 %YAML 1.1 569 --- 570 # Many implementations use merge keys. 571 the-viceroys: &the-viceroys 572 title: The Viceroys 573 author: 574 given_name: Federico 575 family_name: De Roberto 576 book: 577 <<: *the-viceroys 578 title: The Illusion 580 Figure 8: Example of YAML merge keys. 582 Appendix B. Acknowledgements 584 Thanks to Erik Wilde and David Biesack for being the initial 585 contributors of this specification, and to Darrel Miller and Rich 586 Salz for their support during the adoption phase. 588 In addition to the people above, this document owes a lot to the 589 extensive discussion inside and outside the HTTPAPI workgroup. The 590 following contributors have helped improve this specification by 591 opening pull requests, reporting bugs, asking smart questions, 592 drafting or reviewing text, and evaluating open issues: 594 Tina (tinita) Mueller, Ben Hutton, Manu Sporny and Jason Desrosiers. 596 FAQ 598 This section is to be removed before publishing as an RFC. 600 Q: Why this document? After all these years, we still lack a proper 601 media-type for YAML. This has some security implications too (eg. 602 wrt on identifying parsers or treat downloads) 604 Q: Why using alias nodes as fragment identifiers? Alias nodes starts 605 with *. This allow to distinguish a fragment identifier expressed 606 as an alias node from one expressed in JSON Pointer [JSON-POINTER] 607 which is expected to start with /. Moreover, since json-path 608 [I-D.ietf-jsonpath-base] expressions start with $, this mechanism 609 is even extensible that specification. 611 Change Log 613 This section is to be removed before publishing as an RFC. 615 Since draft-ietf-httpapi-yaml-mediatypes-01 617 * application/yaml fragment identifiers compatible with JSON Pointer 618 #41 (#47). 620 Authors' Addresses 622 Roberto Polli 623 Digital Transformation Department, Italian Government 624 Italy 625 Email: robipolli@gmail.com 627 Erik Wilde 628 Axway 629 Switzerland 630 Email: erik.wilde@dret.net 632 Eemeli Aro 633 Mozilla 634 Finland 635 Email: eemeli@gmail.com