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