idnits 2.17.1 draft-wu-netmod-yang-xml-doc-conventions-01.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 copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (May 29, 2018) is 2158 days in the past. Is this intentional? Checking references for intended status: Best Current Practice ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFCYYYY' is mentioned on line 311, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Netmod Working Group Q. Wu 3 Internet-Draft Huawei 4 Intended status: Best Current Practice A. Farrel 5 Expires: November 30, 2018 Juniper Networks 6 B. Claise 7 Cisco Systems, Inc. 8 May 29, 2018 10 Documentation Conventions for Expressing YANG in XML 11 draft-wu-netmod-yang-xml-doc-conventions-01 13 Abstract 15 Many documents that define YANG modules also include artwork examples 16 presented in XML/JSON. 18 IETF documentation has specific limits on line length and some 19 artwork examples such as XML examples have to include line wraps that 20 would not normally be allowed according to the XML representation 21 rules of RFC7950 and RFC7952.The same applies to JSON. 23 This document lays out documentation conventions that allow YANG 24 examples to be presented in IETF documentation when XML/JSON encoded 25 YANG data instance would otherwise exceed the maximum line length and 26 provide consistent XML/JSON encoded YANG data node instance example 27 within an Internet-Draft or RFC. There are no implications in this 28 document for YANG parsers: this document does not change the rules 29 for presenting YANG models or for encoding YANG in data files or in 30 the wire. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at https://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on November 30, 2018. 49 Copyright Notice 51 Copyright (c) 2018 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents 56 (https://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 67 2. Conventions Used in this Document . . . . . . . . . . . . . . 3 68 3. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 3 69 4. Separating Components of a Leaf Example . . . . . . . . . . . 4 70 5. Splitting an Example Leaf Node Value Across Lines . . . . . . 5 71 6. Representing XML and JSON Encodings of Metadata Annotations . 6 72 7. Mandatory Boilerplate for Splitting Leaf node value and 73 Metadata Annotations . . . . . . . . . . . . . . . . . . . . 7 74 8. Automatic Generation of Valid XML From Examples . . . . . . . 7 75 9. Security Considerations . . . . . . . . . . . . . . . . . . . 8 76 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 77 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8 78 12. Normative References . . . . . . . . . . . . . . . . . . . . 9 79 Appendix A. Backslash appears in the node value not used for 80 split line . . . . . . . . . . . . . . . . . . . . . 9 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 83 1. Introduction 85 YANG [RFC7950] defines four main types of data node for data modeling 86 and describes how these are represented in XML [XML]. For list nodes 87 and container nodes, any whitespace, carriage returns, or line feeds 88 between the subelements is insignificant, i.e., an implementation MAY 89 insert whitespace, carriage return, or line feed characters between 90 subelements. 92 However for leaf nodes, [RFC7950] section 7.6.6 says 94 The value of the leaf node is encoded to XML according to the type 95 and is sent as character data in the element. 97 Thus whitespace, carriage return, and line feed characters 98 interpreted as part of the leaf value when the leaf is of type string 99 must not be included. The same applies to leaf-list nodes. 101 However, when documenting examples of YANG modules represented in XML 102 encoding it is possible that the encoding of a single leaf node will 103 exceed the available line length (73 characters). 105 This document describes documentation conventions that allow YANG 106 examples to be presented in IETF documentation when XML/JSON encoded 107 YANG data instance would otherwise exceed the maximum line length and 108 provide consistent XML/JSON encoded YANG data node instance example 109 within an Internet-Draft or RFC. These document conventions also 110 allow the presentation of such examples in a way that is easily 111 parsed by a human reader, but which is not representative of how the 112 XML must be presented to a software component or carried on the wire. 114 There are no implications in this document for YANG parsers: this 115 document does not change the rules for presenting YANG models or for 116 encoding YANG in data files or in the wire. 118 2. Conventions Used in this Document 120 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 121 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 122 "OPTIONAL" in this document are to be interpreted as described in BCP 123 14 [RFC2119] [RFC8174] when, and only when, they appear in all 124 capitals, as shown here. 126 3. Objectives 128 To reduce complexity of XML/JSON encoded YANG data node instance, the 129 following assumptions are made: 131 o If the problem comes from the poorly chosen length of YANG data 132 node instance encoded by XML or JSON,it is recommended to reduce 133 the length of YANG data node instance name or YANG data node 134 instance value to the minimum before applying document convention 135 defined in this document. 137 o If the problem comes from the poorly chosen length of the YANG 138 data node instance containing metadata annotation as attribute, it 139 is recommended to reduce the length of each attribute to the 140 minimum before applying the document convention defined in this 141 document. 143 In order to provide consistent XML/JSON encoded YANG data node 144 instance example within an Internet-Draft or RFC, the following 145 design criteria are used: 147 o Split long line YANG data node instance(e.g.,leaf node instance) 148 exceeding 73 characters limits with the backslash ("\") and use 149 backslash ("\")to indicate wrapping at the end of the line. 151 o Split long line YANG data node instance containing metadata 152 annotation attributes with the backslash ("\")and use backslash 153 ("\")to indicate wrapping at the end of the line. 155 o When a backslash appears in the node value not used for split 156 line, the example MUST be arranged so that this backslash is not 157 the final character of a broken line. 159 o Allow the representation of such examples, if possible,in a way 160 that is easily parsed by a human reader instead of machine or 161 software component: 163 * The first child node within each parent node of the XML/JSON 164 encoded YANG data node instance should be indented with a 165 whitespace offset of two characters. 167 * Where possible, all line breaks should be inserted between 168 metadata attributes. 170 * Where possible, all line breaks should not be inserted between 171 close (">") and open ("<") angle brackets within XML encoded 172 YANG data instance. 174 * Where possible, all line breaks should be inserted between 175 double-quote strings or between data node identifier and data 176 node separated by colon character within JSON encoded YANG data 177 instance. 179 4. Separating Components of a Leaf Example 181 An example of the documentation of a leaf node is shown in Figure 1. 182 The leaf is called "long-leaf-node-name" and is assigned the value 183 "long-leaf-node-value". As can be seen in the example, this fits on 184 one line. However it would only take the addition of a few more 185 characters to the node label or value for the example to overflow the 186 73 character limit. 188 long-leaf-node-value 190 Figure 1: A Simple Leaf Node Example 192 For the sake of documentation purpose, the representation shown in 193 Figure 2 SHALL be considered as equivalent to that shown in Figure 1, 194 but when a document uses this convention it MUST also include the 195 text shown in Section 7. Note that the first example representation 196 in figure 2 is more easily parsed by a human reader than the second 197 example in figure 2. 199 \ 200 long-leaf-node-value \ 201 202 or 203 long-le \ 204 af-node-value 207 Figure 2: A Split Leaf Node Example 209 5. Splitting an Example Leaf Node Value Across Lines 211 When the XML representation of a leaf node value in an example would 212 result in a line being longer than the maximum line length for an 213 IETF document the value of the leaf node must be split and printed on 214 more than one lines. This is most likely to happen when the example 215 leaf node contains a string. Indeed, if this problem arises for 216 other leaf types it may be indicative of poorly chosen leaf values, 217 and the YANG definitions should be revised. 219 In this case, conventions MUST be observed: 221 o The broken line MUST be terminated with a backslash ("\") without 222 the addition of any additional space before the backslash and with 223 no further characters after the backslash. The backslash at the 224 end of the line indicates wrapping. 226 o Any continuation lines MUST align with the first line and not be 227 indented with any whitespace offset. 229 These conventions also apply to JSON representation of a leaf node 230 value [RFC7951]. 232 Furthermore, whenever a document uses this convention it MUST also 233 include the text shown in Section 7. 235 Figure 3 shows an example leaf with a long value. As can be seen, 236 the addition of a few more characters would cause the line to be too 237 long. 239 Figure 4 shows a semantically equivalent representation of the 240 example if the text from Section 7 is also present. 242 243 Once upon a time, in a land far away, there lived a Great King. 244 246 Figure 3: An Example Leaf Node With a Long String Value 248 249 Once upon a time, in a land far away, \ 250 there lived a Great King. 251 253 Figure 4: A Long String Leaf Node Example Split Across Lines 255 6. Representing XML and JSON Encodings of Metadata Annotations 257 [RFC7952] section 5.1 and section 5.2 provide an encoding rule for 258 metadata annotations in XML and JSON respectively. 260 When an example XML representation of a leaf node element that 261 includes metadata attributes results in a line being longer than the 262 maximum number of characters allowed in a line of an IETF document, 263 the value of the leaf node must be split across more than one line. 265 Where possible, all line breaks should be inserted between metadata 266 attributes. Continuation lines MUST align with the first line and 267 not be indented with any whitespace. The leading and trailing 268 whitespace of each line MUST be ignored. Figure 5 gives a XML 269 example. 271 When an example JSON representation of a leaf node element that 272 includes metadata attributes starting with the "@" character results 273 in a line being longer than the maximum number of characters allowed 274 in a line of an IETF document,the value of the leaf node must be 275 split across more than one line. Continuation lines MUST align with 276 the first line and indented with one whitespace character. The 277 leading and trailing whitespace of each line MUST be ignored. 278 Figure 6 gives a JSON example. 280 Whenever this documentation convention is used, the boilerplate text 281 shown in Section 7 MUST be present in the document using the 282 convention. 284 286 ... 287 289 Figure 5: An XML Example Leaf Node With Metadata Split Across Lines 291 "cask": { 292 "@": { 293 "example-org-example-last-modified:last-modified":\ 294 "2015-09-16T10:27:35+02:00" 295 }, 296 ... 297 } 299 Figure 6: A JSON Example Leaf Node With Metadata Split Across Lines 301 7. Mandatory Boilerplate for Splitting Leaf node value and Metadata 302 Annotations 304 When the conventions described in , (Section 4), (Section 5)Section 6 305 are used for the benefit of the representation of an example of a 306 YANG module or YANG fragment in XML/JSON or YANG frament containing 307 metadata annotations in XML/JSON, the following text MUST be included 308 in the document presenting the example. 310 The examples in this document adopt the conventions shown in BCP 311 XX [RFCYYYY] for splitting node labels and node values or metadata 312 annotation across multiple lines. This convention is used to make 313 the examples easier to read but does not change the encoding rules 314 for the XML/JSON representation of YANG metadata annotations as 315 described in [RFC7952]. 317 RFC Editor Note: Please replace XX and YYYY with the numbers assigned 318 for this document. 320 8. Automatic Generation of Valid XML From Examples 322 It should be noted that it is never the intention that example YANG 323 fragment should be converted to XML that is passed to a YANG 324 consumer. Nevertheless, there are good reasons to be able to convert 325 an example into valid YANG in order to parse it and check its 326 validity against the YANG model itself. This will ensure that 327 examples in documents are accurate and useful. 329 When parsing a leaf or leaf-list node in an example, the following 330 rules should be applied to generate valid XML. 332 o If a white space, carriage return, or line feed character is 333 encountered between close (">") and open ("<") angle brackets it 334 should be stripped. 336 o If a white space, carriage return, or line feed character is 337 encountered within a string value of a leaf node or leaf-list 338 node, it should generally be preserved exactly as shown except in 339 the special case that follows. 341 o If a backslash character ("\") appears within the string value of 342 a leaf node or leaf-list node and if and only if it is immediately 343 followed by a carriage return or line feed character then all 344 carriage return, line feed, and whitespace characters should be 345 stripped until the next character is encountered. 347 o If a white space, carriage return, or line feed character is 348 encountered within metadata annotations, but not within quotes, it 349 should be stripped. Parsing may expect the next valid character 350 found to indicate the start of a new metadata attribute. 352 o If a backslash character ("\") appears within the quoted value of 353 a metadata attribute and if and only if it is immediately followed 354 by a carriage return or line feed character then all carriage 355 return, line feed, and whitespace characters should be stripped 356 until the next character is encountered. 358 9. Security Considerations 360 There is no direct security impact related to the XML/JSON encoding 361 documentation convention described in this document. However, 362 attempting to provide actual XML/JSON using the documentation 363 conventions described in this document would have unpredictable 364 results. The risk here is that someone uses an example as a template 365 for actual XML/JSON. The mandatory boilerplate text provides a 366 mitigation against this risk. 368 10. IANA Considerations 370 There are no IANA requests or assignments included in this document. 372 11. Acknowledgements 374 Thanks to Kent Watsen for discussions that kept us close to being on 375 the right track. Additional thanks to John Scudder for flagging some 376 nits. Also thanks Martin Bjorklund, Charles Eckel, Robert Wilton and 377 many others for valuable comments and review. 379 12. Normative References 381 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 382 Requirement Levels", BCP 14, RFC 2119, 383 DOI 10.17487/RFC2119, March 1997, 384 . 386 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 387 RFC 7950, DOI 10.17487/RFC7950, August 2016, 388 . 390 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 391 RFC 7951, DOI 10.17487/RFC7951, August 2016, 392 . 394 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", 395 RFC 7952, DOI 10.17487/RFC7952, August 2016, 396 . 398 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 399 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 400 May 2017, . 402 [XML] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and 403 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 404 Edition)", World Wide Web Consortium Recommendation REC- 405 xml-20081126, November 2008, 406 . 408 Appendix A. Backslash appears in the node value not used for split line 410 Figure 7 and Figure 8 show a more complex example where the node 411 value includes both line feeds and a backslash. Note how the line 412 breaks are arranged to avoid potential confusion and to make the real 413 characters evident. 415 416 Punctuation is important. As are line feeds. 417 Some characters are special. E.g., //Same line as the first row 418 the backslash \. Don't forget. //Same line as the firs row 419 421 Figure 7: An Example Leaf Node With a Complex String Value 422 423 Punctuation is important. As are line feeds.\ 424 Some characters are special. E.g., the backslash \. \ 425 Don't forget. 426 428 Figure 8: An Example Leaf Node With a Complex String Value Split 429 Across Lines 431 Authors' Addresses 433 Qin Wu 434 Huawei 435 101 Software Avenue, Yuhua District 436 Nanjing, Jiangsu 210012 437 China 439 Email: bill.wu@huawei.com 441 Adrian Farrel 442 Juniper Networks 444 Email: afarrel@juniper.net 446 Benoit Claise 447 Cisco Systems, Inc. 448 De Kleetlaan 6a b1 449 1831 Diegem 450 Belgium 452 Phone: +32 2 704 5622 453 Email: bclaise@cisco.com