idnits 2.17.00 (12 Aug 2021) /tmp/idnits64087/draft-ietf-core-yang-cbor-17.txt: -(9): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding 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 3 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 (25 October 2021) is 207 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: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: '-2' is mentioned on line 1240, but not defined -- Looks like a reference, but probably isn't: '257' on line 1240 == Missing Reference: '0-9' is mentioned on line 1600, but not defined == Missing Reference: '1-9' is mentioned on line 1591, but not defined == Missing Reference: '0-4' is mentioned on line 1600, but not defined == Missing Reference: '0-5' is mentioned on line 1600, but not defined == Missing Reference: '0-9a-fA-F' is mentioned on line 1599, but not defined -- Looks like a reference, but probably isn't: '01' on line 1600 == Outdated reference: A later version (-18) exists of draft-ietf-core-sid-16 Summary: 0 errors (**), 0 flaws (~~), 9 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force M. Veillette, Ed. 3 Internet-Draft Trilliant Networks Inc. 4 Intended status: Standards Track I. Petrov, Ed. 5 Expires: 28 April 2022 Google Switzerland GmbH 6 A. Pelov 7 Acklio 8 C. Bormann 9 Universität Bremen TZI 10 M. Richardson 11 Sandelman Software Works 12 25 October 2021 14 CBOR Encoding of Data Modeled with YANG 15 draft-ietf-core-yang-cbor-17 17 Abstract 19 Based on the Concise Binary Object Representation (CBOR, RFC 8949), 20 this document defines encoding rules for representing configuration 21 data, state data, parameters and results of Remote Procedure Call 22 (RPC) operations or actions, and notifications, defined using YANG 23 (RFC 7950). 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on 28 April 2022. 42 Copyright Notice 44 Copyright (c) 2021 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 49 license-info) in effect on the date of publication of this document. 50 Please review these documents carefully, as they describe your rights 51 and restrictions with respect to this document. Code Components 52 extracted from this document must include Simplified BSD License text 53 as described in Section 4.e of the Trust Legal Provisions and are 54 provided without warranty as described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 3 60 3. Properties of the CBOR Encoding . . . . . . . . . . . . . . . 5 61 3.1. CBOR diagnostic notation . . . . . . . . . . . . . . . . 6 62 3.2. YANG Schema Item iDentifier . . . . . . . . . . . . . . . 8 63 3.3. Name . . . . . . . . . . . . . . . . . . . . . . . . . . 9 64 4. Encoding of YANG Schema Node Instances . . . . . . . . . . . 10 65 4.1. The 'leaf' . . . . . . . . . . . . . . . . . . . . . . . 10 66 4.1.1. Using SIDs in keys . . . . . . . . . . . . . . . . . 11 67 4.1.2. Using names in keys . . . . . . . . . . . . . . . . . 11 68 4.2. The 'container' and other nodes from the data tree . . . 12 69 4.2.1. Using SIDs in keys . . . . . . . . . . . . . . . . . 13 70 4.2.2. Using names in keys . . . . . . . . . . . . . . . . . 14 71 4.3. The 'leaf-list' . . . . . . . . . . . . . . . . . . . . . 15 72 4.3.1. Using SIDs in keys . . . . . . . . . . . . . . . . . 15 73 4.3.2. Using names in keys . . . . . . . . . . . . . . . . . 16 74 4.4. The 'list' and 'list' entries . . . . . . . . . . . . . . 16 75 4.4.1. Using SIDs in keys . . . . . . . . . . . . . . . . . 17 76 4.4.2. Using names in keys . . . . . . . . . . . . . . . . . 19 77 4.5. The 'anydata' . . . . . . . . . . . . . . . . . . . . . . 21 78 4.5.1. Using SIDs in keys . . . . . . . . . . . . . . . . . 22 79 4.5.2. Using names in keys . . . . . . . . . . . . . . . . . 23 80 4.6. The 'anyxml' . . . . . . . . . . . . . . . . . . . . . . 24 81 4.6.1. Using SIDs in keys . . . . . . . . . . . . . . . . . 24 82 4.6.2. Using names in keys . . . . . . . . . . . . . . . . . 25 83 5. Encoding of 'yang-data' extension . . . . . . . . . . . . . . 25 84 5.1. Using SIDs in keys . . . . . . . . . . . . . . . . . . . 26 85 5.2. Using names in keys . . . . . . . . . . . . . . . . . . . 27 86 6. Representing YANG Data Types in CBOR . . . . . . . . . . . . 28 87 6.1. The unsigned integer Types . . . . . . . . . . . . . . . 28 88 6.2. The integer Types . . . . . . . . . . . . . . . . . . . . 29 89 6.3. The 'decimal64' Type . . . . . . . . . . . . . . . . . . 29 90 6.4. The 'string' Type . . . . . . . . . . . . . . . . . . . . 30 91 6.5. The 'boolean' Type . . . . . . . . . . . . . . . . . . . 30 92 6.6. The 'enumeration' Type . . . . . . . . . . . . . . . . . 31 93 6.7. The 'bits' Type . . . . . . . . . . . . . . . . . . . . . 32 94 6.8. The 'binary' Type . . . . . . . . . . . . . . . . . . . . 34 95 6.9. The 'leafref' Type . . . . . . . . . . . . . . . . . . . 34 96 6.10. The 'identityref' Type . . . . . . . . . . . . . . . . . 35 97 6.10.1. SIDs as identityref . . . . . . . . . . . . . . . . 35 98 6.10.2. Name as identityref . . . . . . . . . . . . . . . . 36 99 6.11. The 'empty' Type . . . . . . . . . . . . . . . . . . . . 36 100 6.12. The 'union' Type . . . . . . . . . . . . . . . . . . . . 37 101 6.13. The 'instance-identifier' Type . . . . . . . . . . . . . 38 102 6.13.1. SIDs as instance-identifier . . . . . . . . . . . . 38 103 6.13.2. Names as instance-identifier . . . . . . . . . . . . 41 104 7. Content-Types . . . . . . . . . . . . . . . . . . . . . . . . 43 105 8. Security Considerations . . . . . . . . . . . . . . . . . . . 44 106 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44 107 9.1. Media-Types Registry . . . . . . . . . . . . . . . . . . 44 108 9.2. CoAP Content-Formats Registry . . . . . . . . . . . . . . 45 109 9.3. CBOR Tags Registry . . . . . . . . . . . . . . . . . . . 45 110 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 46 111 10.1. Normative References . . . . . . . . . . . . . . . . . . 46 112 10.2. Informative References . . . . . . . . . . . . . . . . . 47 113 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 48 114 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 48 116 1. Introduction 118 The specification of the YANG 1.1 data modeling language [RFC7950] 119 defines an XML encoding for data instances, i.e., contents of 120 configuration datastores, state data, RPC inputs and outputs, action 121 inputs and outputs, and event notifications. 123 An additional set of encoding rules has been defined in [RFC7951] 124 based on the JavaScript Object Notation (JSON) Data Interchange 125 Format [RFC8259]. 127 The aim of this document is to define a set of encoding rules for the 128 Concise Binary Object Representation (CBOR) [RFC8949], collectively 129 called _YANG-CBOR_. The resulting encoding is more compact compared 130 to XML and JSON and more suitable for Constrained Nodes and/or 131 Constrained Networks as defined by [RFC7228]. 133 2. Terminology and Notation 135 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 136 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 137 "OPTIONAL" in this document are to be interpreted as described in 138 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 139 capitals, as shown here. 141 The following terms are defined in [RFC7950]: 143 * action 145 * anydata 147 * anyxml 149 * data node 151 * data tree 153 * datastore 155 * feature 157 * identity 159 * module 161 * notification 163 * RPC 165 * schema node 167 * submodule 169 The following terms are defined in [RFC8040]: 171 * yang-data extension 173 This specification also makes use of the following terminology: 175 * child: A schema node defined as a child node of a container, a 176 list, a case, a notification, an RPC input, an RPC output, an 177 action input, or an action output. 179 * YANG Schema Item iDentifier (YANG SID or simply SID): Unsigned 180 integer used to identify different YANG items. 182 * delta: Difference between the current YANG SID and a reference 183 YANG SID. A reference YANG SID is defined for each context for 184 which deltas are used. 186 * absolute SID: YANG SID not encoded as a delta. This is usually 187 called out explicitly only in positions where normally a delta 188 would be found. 190 * item: A schema node, an identity, a module, or a feature defined 191 using the YANG modeling language. 193 * list entry: the data associated with a single element of a list. 195 * parent: The container, list, case, notification, RPC input, RPC 196 output, action input or action output node in which a schema node 197 is defined. 199 3. Properties of the CBOR Encoding 201 This document defines CBOR encoding rules for YANG data trees and 202 their subtrees. 204 An instance of a schema node such as container, list, notification, 205 RPC input, RPC output, action input, or action output is serialized 206 using a CBOR map in which each child schema node is encoded using a 207 key and a value. This specification supports two types of CBOR keys; 208 YANG Schema Item iDentifier (YANG SID) as defined in Section 3.2 and 209 names as defined in Section 3.3. Each of these key types is encoded 210 using a specific CBOR type which allows their interpretation during 211 the deserialization process. Protocols or mechanisms implementing 212 this specification can mandate the use of a specific key type. 214 In order to minimize the size of the encoded data, the proposed 215 mapping avoids any unnecessary meta-information beyond that directly 216 provided by the CBOR basic generic data model (Section 2 of 217 [RFC8949]). For instance, CBOR tags are used solely in the case of 218 an absolute SID, anyxml schema nodes, or the union datatype, to 219 distinguish explicitly the use of different YANG datatypes encoded 220 using the same CBOR major type. 222 Unless specified otherwise by the protocol or mechanism implementing 223 this specification, the indefinite length encoding as defined in 224 Section 3.2 of [RFC8949] SHALL be supported by the CBOR decoders 225 employed with YANG-CBOR. (This enables an implementation to begin 226 emitting an array or map before the number of entries in that 227 structure is known, possibly also avoiding excessive locking or race 228 conditions. On the other hand, it deprives the receiver of the 229 encoded data from advance announcement about some size information, 230 so a generator should choose indefinite length encoding only when 231 these benefits do accrue.) 233 Data nodes implemented using a CBOR array, map, byte string, or text 234 string can be instantiated but empty. In this case, they are encoded 235 with a length of zero. 237 When schema nodes are serialized using the rules defined by this 238 specification as part of an application payload, the payload SHOULD 239 include information that would allow a stateless way to identify each 240 node, such as the SID number associated with the node, SID delta from 241 another SID in the application payload, the namespace qualified name, 242 or the instance-identifier. 244 Examples in Section 4 include a root CBOR map with a single entry 245 having a key set to either a namespace qualified name or a SID. This 246 root CBOR map is provided only as a typical usage example and is not 247 part of the present encoding rules. Only the value within this CBOR 248 map is compulsory. 250 3.1. CBOR diagnostic notation 252 Within this document, CBOR binary contents are represented using an 253 equivalent textual form called CBOR diagnostic notation as defined in 254 Section 8 of [RFC8949]. This notation is used strictly for 255 documentation purposes and is never used in the data serialization. 256 Table 1 below provides a summary of this notation. 258 +==========+======+====================+===========+==========+ 259 | CBOR | CBOR | Diagnostic | Example | CBOR | 260 | content | type | notation | | encoding | 261 +==========+======+====================+===========+==========+ 262 | Unsigned | 0 | Decimal digits | 123 | 18 7B | 263 | integer | | | | | 264 +----------+------+--------------------+-----------+----------+ 265 | Negative | 1 | Decimal digits | -123 | 38 7A | 266 | integer | | prefixed by a | | | 267 | | | minus sign | | | 268 +----------+------+--------------------+-----------+----------+ 269 | Byte | 2 | Hexadecimal value | h'F15C' | 42 F15C | 270 | string | | enclosed between | | | 271 | | | single quotes and | | | 272 | | | prefixed by an 'h' | | | 273 +----------+------+--------------------+-----------+----------+ 274 | Text | 3 | String of Unicode | "txt" | 63 | 275 | string | | characters | | 747874 | 276 | | | enclosed between | | | 277 | | | double quotes | | | 278 +----------+------+--------------------+-----------+----------+ 279 | Array | 4 | Comma-separated | [ 1, 2 ] | 82 01 02 | 280 | | | list of values | | | 281 | | | within square | | | 282 | | | brackets | | | 283 +----------+------+--------------------+-----------+----------+ 284 | Map | 5 | Comma-separated | { 1: 123, | A2 | 285 | | | list of key : | 2: 456 } | 01187B | 286 | | | value pairs within | | 021901C8 | 287 | | | curly braces | | | 288 +----------+------+--------------------+-----------+----------+ 289 | Boolean | 7/20 | false | false | F4 | 290 +----------+------+--------------------+-----------+----------+ 291 | | 7/21 | true | true | F5 | 292 +----------+------+--------------------+-----------+----------+ 293 | Null | 7/22 | null | null | F6 | 294 +----------+------+--------------------+-----------+----------+ 295 | Not | 7/23 | undefined | undefined | F7 | 296 | assigned | | | | | 297 +----------+------+--------------------+-----------+----------+ 299 Table 1: CBOR diagnostic notation summary 301 Note: CBOR binary contents shown in this specification are annotated 302 with comments. These comments are delimited by slashes ("/") as 303 defined in [RFC8610] Appendix G.6. 305 3.2. YANG Schema Item iDentifier 307 Some of the items defined in YANG [RFC7950] require the use of a 308 unique identifier. In both Network Configuration Protocol (NETCONF) 309 [RFC6241] and RESTCONF [RFC8040], these identifiers are implemented 310 using text strings. To allow the implementation of data models 311 defined in YANG in constrained devices and constrained networks, a 312 more compact method to identify YANG items is required. This compact 313 identifier, called YANG Schema Item iDentifier, is an unsigned 314 integer. The following items are identified using YANG SIDs (often 315 shortened to SIDs): 317 * identities 319 * data nodes 321 * RPCs and associated input(s) and output(s) 323 * actions and associated input(s) and output(s) 325 * notifications and associated information 327 * YANG modules and features 329 Note that any structuring of modules into submodules is transparent 330 to YANG-CBOR: SIDs are not allocated for the names of submodules, and 331 any items within a submodule are effectively allocated SIDs as part 332 of processing the module that includes them. 334 To minimize their size, SIDs used as keys in CBOR maps are encoded 335 using deltas, i.e., signed (negative or unsigned) integers that are 336 added to the reference SID applying to the map. The reference SID of 337 an outermost map is zero, unless a different reference SID is 338 unambiguously conferred from the environment in which the outermost 339 map is used. The reference SID of a map that is most directly 340 embedded in a map entry with a name-based key is zero. For all other 341 maps, the reference SID is the SID computed for the map entry it is 342 most directly embedded in. (The embedding may be indirect if an 343 array intervenes, e.g., in a YANG list) Where absolute SIDs are 344 desired in map key positions where a bare integer implies a delta, 345 they may be encoded using CBOR tag 47 (as defined in Section 9.3). 347 Thus, conversion from SIDs to deltas and back to SIDs is a stateless 348 process solely based on the data serialized or deserialized combined 349 with, potentially, an outermost reference SID unambiguously conferred 350 by the environment. 352 Mechanisms and processes used to assign SIDs to YANG items and to 353 guarantee their uniqueness are outside the scope of the present 354 specification. If SIDs are to be used, the present specification is 355 used in conjunction with a specification defining this management. 356 [I-D.ietf-core-sid] is the definitive way to assign SID values for 357 YANG modules managed by the IETF. With YANG modules managed by non- 358 IETF entities, use of [I-D.ietf-core-sid] is RECOMMENDED. The 359 present specification has been designed to allow different methods of 360 assignment to be used within separate domains. 362 3.3. Name 364 This specification also supports the encoding of YANG item 365 identifiers as text strings, similar to those used by the JSON 366 Encoding of Data Modeled with YANG [RFC7951]. This approach can be 367 used to avoid the management overhead associated with SID allocation. 368 The main drawback is the significant increase in size of the encoded 369 data. 371 YANG item identifiers implemented using names MUST be in one of the 372 following forms: 374 * simple - the identifier of the YANG item (i.e., schema node or 375 identity). 377 * namespace qualified - the identifier of the YANG item is prefixed 378 with the name of the module in which this item is defined, 379 separated by the colon character (":"). 381 The name of a module determines the namespace of all YANG items 382 defined in that module. If an item is defined in a submodule, then 383 the namespace qualified name uses the name of the main module to 384 which the submodule belongs. 386 ABNF syntax [RFC5234] of a name is shown in Figure 1, where the 387 production for "identifier" is defined in Section 14 of [RFC7950]. 389 name = [identifier ":"] identifier 391 Figure 1: ABNF Production for a simple or namespace qualified name 393 A namespace qualified name MUST be used for all members of a top- 394 level CBOR map and then also whenever the namespaces of the data node 395 and its parent node are different. In all other cases, the simple 396 form of the name SHOULD be used. 398 Definition example: 400 module example-foomod { 401 container top { 402 leaf foo { 403 type uint8; 404 } 405 } 406 } 408 module example-barmod { 409 import example-foomod { 410 prefix "foomod"; 411 } 412 augment "/foomod:top" { 413 leaf bar { 414 type boolean; 415 } 416 } 417 } 419 A valid CBOR encoding of the 'top' container is as follows. 421 CBOR diagnostic notation: 423 { 424 "example-foomod:top": { 425 "foo": 54, 426 "example-barmod:bar": true 427 } 428 } 430 Both the 'top' container and the 'bar' leaf defined in a different 431 YANG module as its parent container are encoded as namespace 432 qualified names. The 'foo' leaf defined in the same YANG module as 433 its parent container is encoded as simple name. 435 4. Encoding of YANG Schema Node Instances 437 Schema node instances defined using the YANG modeling language are 438 encoded using CBOR [RFC8949] based on the rules defined in this 439 section. We assume that the reader is already familiar with both 440 YANG [RFC7950] and CBOR [RFC8949]. 442 4.1. The 'leaf' 444 A 'leaf' MUST be encoded accordingly to its datatype using one of the 445 encoding rules specified in Section 6. 447 The following examples show the encoding of a 'hostname' leaf using a 448 SID or a name. 450 Definition example from [RFC7317]: 452 typedef domain-name { 453 type string { 454 length "1..253"; 455 pattern '((([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9].) 456 *([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.? 457 )|\.'; 458 } 459 } 461 leaf hostname { 462 type inet:domain-name; 463 } 465 4.1.1. Using SIDs in keys 467 As with all examples below, the delta in the outermost map assumes a 468 reference YANG SID (current schema node) of 0. 470 CBOR diagnostic notation: 472 { 473 1752 : "myhost.example.com" / hostname (SID 1752) / 474 } 476 CBOR encoding: 478 A1 # map(1) 479 19 06D8 # unsigned(1752) 480 72 # text(18) 481 6D79686F73742E6578616D706C652E636F6D # "myhost.example.com" 483 4.1.2. Using names in keys 485 CBOR diagnostic notation: 487 { 488 "ietf-system:hostname" : "myhost.example.com" 489 } 491 CBOR encoding: 493 A1 # map(1) 494 74 # text(20) 495 696574662D73797374656D3A686F73746E616D65 496 72 # text(18) 497 6D79686F73742E6578616D706C652E636F6D 499 4.2. The 'container' and other nodes from the data tree 501 Instances of containers, notification contents, RPC inputs, RPC 502 outputs, action inputs, and action outputs schema nodes MUST be 503 encoded using a CBOR map data item (major type 5). The same encoding 504 is also used for the list entries in a list (Section 4.4). A map 505 consists of pairs of data items, with each pair consisting of a key 506 and a value. Each key within the CBOR map is set to a schema node 507 identifier, each value is set to the value of this schema node 508 instance according to the instance datatype. 510 This specification supports two types of CBOR map keys; SID as 511 defined in Section 3.2 and names as defined in Section 3.3. 513 The following examples show the encoding of a 'system-state' 514 container schema node instance using SIDs or names. 516 Definition example from [RFC7317]: 518 typedef date-and-time { 519 type string { 520 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[\+\-] 521 \d{2}:\d{2})'; 522 } 523 } 525 container system-state { 527 container clock { 528 leaf current-datetime { 529 type date-and-time; 530 } 532 leaf boot-datetime { 533 type date-and-time; 534 } 535 } 536 } 538 4.2.1. Using SIDs in keys 540 In the context of containers and other nodes from the data tree, CBOR 541 map keys within inner CBOR maps can be encoded using deltas or 542 absolute SIDs (tag 47). 544 Delta values are computed as follows: 546 * In the case of a 'container', deltas are equal to the SID of the 547 current schema node minus the SID of the parent 'container'. 549 * In the case of a 'list', deltas are equal to the SID of the 550 current schema node minus the SID of the parent 'list'. 552 * In the case of an 'RPC input' or 'RPC output', deltas are equal to 553 the SID of the current schema node minus the SID of the 'RPC'. 555 * In the case of an 'action input' or 'action output', deltas are 556 equal to the SID of the current schema node minus the SID of the 557 'action'. 559 * In the case of a 'notification content', deltas are equal to the 560 SID of the current schema node minus the SID of the 561 'notification'. 563 CBOR diagnostic notation: 565 { 566 1720 : { / system-state (SID 1720) / 567 1 : { / clock (SID 1721) / 568 2 : "2015-10-02T14:47:24Z-05:00", / current-datetime(SID 1723)/ 569 1 : "2015-09-15T09:12:58Z-05:00" / boot-datetime (SID 1722) / 570 } 571 } 572 } 574 CBOR encoding: 576 A1 # map(1) 577 19 06B8 # unsigned(1720) 578 A1 # map(1) 579 01 # unsigned(1) 580 A2 # map(2) 581 02 # unsigned(2) 582 78 1A # text(26) 583 323031352D31302D30325431343A34373A32345A2D30353A3030 584 01 # unsigned(1) 585 78 1A # text(26) 586 323031352D30392D31355430393A31323A35385A2D30353A3030 588 Figure 2: System state clock encoding 590 4.2.2. Using names in keys 592 CBOR map keys implemented using names MUST be encoded using a CBOR 593 text string data item (major type 3). A namespace-qualified name 594 MUST be used each time the namespace of a schema node and its parent 595 differ. In all other cases, the simple form of the name MUST be 596 used. Names and namespaces are defined in Section 4 of [RFC7951]. 598 The following example shows the encoding of a 'system' container 599 schema node instance using names. 601 CBOR diagnostic notation: 603 { 604 "ietf-system:system-state" : { 605 "clock" : { 606 "current-datetime" : "2015-10-02T14:47:24Z-05:00", 607 "boot-datetime" : "2015-09-15T09:12:58Z-05:00" 608 } 609 } 610 } 612 CBOR encoding: 614 A1 # map(1) 615 78 18 # text(24) 616 696574662D73797374656D3A73797374656D2D7374617465 617 A1 # map(1) 618 65 # text(5) 619 636C6F636B # "clock" 620 A2 # map(2) 621 70 # text(16) 622 63757272656E742D6461746574696D65 623 78 1A # text(26) 624 323031352D31302D30325431343A34373A32345A2D30353A3030 625 6D # text(13) 626 626F6F742D6461746574696D65 627 78 1A # text(26) 628 323031352D30392D31355430393A31323A35385A2D30353A3030 630 4.3. The 'leaf-list' 632 A leaf-list MUST be encoded using a CBOR array data item (major type 633 4). Each entry of this array MUST be encoded accordingly to its 634 datatype using one of the encoding rules specified in Section 6. 636 The following example shows the encoding of the 'search' leaf-list 637 schema node instance containing two entries, "ietf.org" and 638 "ieee.org". 640 Definition example [RFC7317]: 642 typedef domain-name { 643 type string { 644 length "1..253"; 645 pattern '((([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9].) 646 *([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.? 647 )|\.'; 648 } 649 } 651 leaf-list search { 652 type domain-name; 653 ordered-by user; 654 } 656 4.3.1. Using SIDs in keys 658 CBOR diagnostic notation: 660 { 661 1746 : [ "ietf.org", "ieee.org" ] / search (SID 1746) / 662 } 664 CBOR encoding: 666 A1 # map(1) 667 19 06D2 # unsigned(1746) 668 82 # array(2) 669 68 # text(8) 670 696574662E6F7267 # "ietf.org" 671 68 # text(8) 672 696565652E6F7267 # "ieee.org" 674 4.3.2. Using names in keys 676 CBOR diagnostic notation: 678 { 679 "ietf-system:search" : [ "ietf.org", "ieee.org" ] 680 } 682 CBOR encoding: 684 A1 # map(1) 685 72 # text(18) 686 696574662D73797374656D3A736561726368 # "ietf-system:search" 687 82 # array(2) 688 68 # text(8) 689 696574662E6F7267 # "ietf.org" 690 68 # text(8) 691 696565652E6F7267 # "ieee.org" 693 4.4. The 'list' and 'list' entries 695 A list or a subset of a list MUST be encoded using a CBOR array data 696 item (major type 4). Each list entry within this CBOR array is 697 encoded using a CBOR map data item (major type 5) based on the 698 encoding rules of a collection as defined in Section 4.2. 700 It is important to note that this encoding rule also applies to a 701 'list' schema node instance that has a single entry. 703 The following examples show the encoding of a 'server' list using 704 SIDs or names. 706 Definition example from [RFC7317]: 708 list server { 709 key name; 711 leaf name { 712 type string; 713 } 714 choice transport { 715 case udp { 716 container udp { 717 leaf address { 718 type host; 719 mandatory true; 720 } 721 leaf port { 722 type port-number; 723 } 724 } 725 } 726 } 727 leaf association-type { 728 type enumeration { 729 enum server; 730 enum peer; 731 enum pool; 732 } 733 default server; 734 } 735 leaf iburst { 736 type boolean; 737 default false; 738 } 739 leaf prefer { 740 type boolean; 741 default false; 742 } 743 } 745 4.4.1. Using SIDs in keys 747 The encoding rules of each 'list' entry are defined in Section 4.2.1. 749 CBOR diagnostic notation: 751 { 752 1756 : [ / server (SID 1756) / 753 { 754 3 : "NRC TIC server", / name (SID 1759) / 755 5 : { / udp (SID 1761) / 756 1 : "tic.nrc.ca", / address (SID 1762) / 757 2 : 123 / port (SID 1763) / 758 }, 759 1 : 0, / association-type (SID 1757) / 760 2 : false, / iburst (SID 1758) / 761 4 : true / prefer (SID 1760) / 762 }, 763 { 764 3 : "NRC TAC server", / name (SID 1759) / 765 5 : { / udp (SID 1761) / 766 1 : "tac.nrc.ca" / address (SID 1762) / 767 } 768 } 769 ] 770 } 772 CBOR encoding: 774 A1 # map(1) 775 19 06DC # unsigned(1756) 776 82 # array(2) 777 A5 # map(5) 778 03 # unsigned(3) 779 6E # text(14) 780 4E52432054494320736572766572 # "NRC TIC server" 781 05 # unsigned(5) 782 A2 # map(2) 783 01 # unsigned(1) 784 6A # text(10) 785 7469632E6E72632E6361 # "tic.nrc.ca" 786 02 # unsigned(2) 787 18 7B # unsigned(123) 788 01 # unsigned(1) 789 00 # unsigned(0) 790 02 # unsigned(2) 791 F4 # primitive(20) 792 04 # unsigned(4) 793 F5 # primitive(21) 794 A2 # map(2) 795 03 # unsigned(3) 796 6E # text(14) 797 4E52432054414320736572766572 # "NRC TAC server" 798 05 # unsigned(5) 799 A1 # map(1) 800 01 # unsigned(1) 801 6A # text(10) 802 7461632E6E72632E6361 # "tac.nrc.ca" 804 4.4.2. Using names in keys 806 The encoding rules of each 'list' entry are defined in Section 4.2.2. 808 CBOR diagnostic notation: 810 { 811 "ietf-system:server" : [ 812 { 813 "name" : "NRC TIC server", 814 "udp" : { 815 "address" : "tic.nrc.ca", 816 "port" : 123 817 }, 818 "association-type" : 0, 819 "iburst" : false, 820 "prefer" : true 821 }, 822 { 823 "name" : "NRC TAC server", 824 "udp" : { 825 "address" : "tac.nrc.ca" 826 } 827 } 828 ] 829 } 831 CBOR encoding: 833 A1 # map(1) 834 72 # text(18) 835 696574662D73797374656D3A736572766572 836 82 # array(2) 837 A5 # map(5) 838 64 # text(4) 839 6E616D65 # "name" 840 6E # text(14) 841 4E52432054494320736572766572 842 63 # text(3) 843 756470 # "udp" 844 A2 # map(2) 845 67 # text(7) 846 61646472657373 # "address" 847 6A # text(10) 848 7469632E6E72632E6361 # "tic.nrc.ca" 849 64 # text(4) 850 706F7274 # "port" 851 18 7B # unsigned(123) 852 70 # text(16) 853 6173736F63696174696F6E2D74797065 854 00 # unsigned(0) 855 66 # text(6) 856 696275727374 # "iburst" 857 F4 # primitive(20) 858 66 # text(6) 859 707265666572 # "prefer" 860 F5 # primitive(21) 861 A2 # map(2) 862 64 # text(4) 863 6E616D65 # "name" 864 6E # text(14) 865 4E52432054414320736572766572 866 63 # text(3) 867 756470 # "udp" 868 A1 # map(1) 869 67 # text(7) 870 61646472657373 # "address" 871 6A # text(10) 872 7461632E6E72632E6361 # "tac.nrc.ca" 874 4.5. The 'anydata' 876 An anydata serves as a container for an arbitrary set of schema nodes 877 that otherwise appear as normal YANG-modeled data. An anydata schema 878 node instance is encoded using the same rules as a container, i.e., 879 CBOR map. The requirement that anydata content can be modeled by 880 YANG implies the following: 882 * CBOR map keys of any inner schema nodes MUST be set to valid 883 deltas or names. 885 * The CBOR array MUST contain either unique scalar values (as a 886 leaf-list, see Section 4.3), or maps (as a list, see Section 4.4). 888 * CBOR map values MUST follow the encoding rules of one of the 889 datatypes listed in Section 4. 891 The following example shows a possible use of an anydata. In this 892 example, an anydata is used to define a schema node containing a 893 notification event; this schema node can be part of a YANG list to 894 create an event logger. 896 Definition example: 898 module event-log { 899 ... 900 anydata last-event; # SID 60123 901 } 903 This example also assumes the assistance of the following 904 notification. 906 module example-port { 907 ... 909 notification example-port-fault { # SID 60200 910 leaf port-name { # SID 60201 911 type string; 912 } 913 leaf port-fault { # SID 60202 914 type string; 915 } 916 } 917 } 919 4.5.1. Using SIDs in keys 921 CBOR diagnostic notation: 923 { 924 60123 : { / last-event (SID 60123) / 925 77 : { / example-port-fault (SID 60200) / 926 1 : "0/4/21", / port-name (SID 60201) / 927 2 : "Open pin 2" / port-fault (SID 60202) / 928 } 929 } 930 } 932 CBOR encoding: 934 A1 # map(1) 935 19 EADB # unsigned(60123) 936 A1 # map(1) 937 18 4D # unsigned(77) 938 A2 # map(2) 939 18 4E # unsigned(78) 940 66 # text(6) 941 302F342F3231 # "0/4/21" 942 18 4F # unsigned(79) 943 6A # text(10) 944 4F70656E2070696E2032 # "Open pin 2" 946 In some implementations, it might be simpler to use the absolute SID 947 encoding (tag 47) for the anydata root element. CBOR diagnostic 948 notation: 950 { 951 60123 : { / last-event (SID 60123) / 952 47(60200) : { / event-port-fault (SID 60200) / 953 1 : "0/4/21", / port-name (SID 60201) / 954 2 : "Open pin 2" / port-fault (SID 60202) / 955 } 956 } 957 } 959 4.5.2. Using names in keys 961 CBOR diagnostic notation: 963 { 964 "event-log:last-event" : { 965 "example-port:example-port-fault" : { 966 "port-name" : "0/4/21", 967 "port-fault" : "Open pin 2" 968 } 969 } 970 } 971 CBOR encoding: 973 A1 # map(1) 974 74 # text(20) 975 6576656E742D6C6F673A6C6173742D6576656E74 976 A1 # map(1) 977 78 20 # text(32) 978 6578616D706C652D706F72743A206578616D7 979 06C652D706F72742D6661756C74 980 A2 # map(2) 981 69 # text(9) 982 706F72742D6E616D65 # "port-name" 983 66 # text(6) 984 302F342F3231 # "0/4/21" 985 6A # text(10) 986 706F72742D6661756C74 # "port-fault" 987 6A # text(10) 988 4F70656E2070696E2032 # "Open pin 2" 990 4.6. The 'anyxml' 992 An anyxml schema node is used to serialize an arbitrary CBOR content, 993 i.e., its value can be any CBOR binary object. An anyxml value MAY 994 contain CBOR data items tagged with one of the tags listed in 995 Section 9.3. The tags listed in Section 9.3 SHALL be supported. 997 The following example shows a valid CBOR encoded anyxml schema node 998 instance consisting of a CBOR array containing the CBOR simple values 999 'true', 'null' and 'true'. 1001 Definition example from [RFC7951]: 1003 module bar-module { 1004 ... 1005 anyxml bar; # SID 60000 1006 } 1008 4.6.1. Using SIDs in keys 1010 CBOR diagnostic notation: 1012 { 1013 60000 : [true, null, true] / bar (SID 60000) / 1014 } 1016 CBOR encoding: 1018 A1 # map(1) 1019 19 EA60 # unsigned(60000) 1020 83 # array(3) 1021 F5 # primitive(21) 1022 F6 # primitive(22) 1023 F5 # primitive(21) 1025 4.6.2. Using names in keys 1027 CBOR diagnostic notation: 1029 { 1030 "bar-module:bar" : [true, null, true] / bar (SID 60000) / 1031 } 1033 CBOR encoding: 1035 A1 # map(1) 1036 6E # text(14) 1037 6261722D6D6F64756C653A626172 # "bar-module:bar" 1038 83 # array(3) 1039 F5 # primitive(21) 1040 F6 # primitive(22) 1041 F5 # primitive(21) 1043 5. Encoding of 'yang-data' extension 1045 The yang-data extension [RFC8040] is used to define data structures 1046 in YANG that are not intended to be implemented as part of a 1047 datastore. 1049 The yang-data extension MUST be encoded using the encoding rules of 1050 nodes of data trees as defined in Section 4.2. 1052 Just like YANG containers, the yang-data extension can be encoded 1053 using either SIDs or names. 1055 Definition example from [I-D.ietf-core-comi] Appendix A: 1057 module ietf-coreconf { 1058 ... 1060 import ietf-restconf { 1061 prefix rc; 1062 } 1064 rc:yang-data yang-errors { 1065 container error { 1066 leaf error-tag { 1067 type identityref { 1068 base error-tag; 1069 } 1070 } 1071 leaf error-app-tag { 1072 type identityref { 1073 base error-app-tag; 1074 } 1075 } 1076 leaf error-data-node { 1077 type instance-identifier; 1078 } 1079 leaf error-message { 1080 type string; 1081 } 1082 } 1083 } 1084 } 1086 5.1. Using SIDs in keys 1088 The yang-data extensions encoded using SIDs are carried in a CBOR map 1089 containing a single item pair. The key of this item is set to the 1090 SID assigned to the yang-data extension container; the value is set 1091 to the CBOR encoding of this container as defined in Section 4.2. 1093 This example shows a serialization example of the yang-errors yang- 1094 data extension as defined in [I-D.ietf-core-comi] using SIDs as 1095 defined in Section 3.2. 1097 CBOR diagnostic notation: 1099 { 1100 1024 : { / error (SID 1024) / 1101 4 : 1011, / error-tag (SID 1028) / 1102 / = invalid-value (SID 1011) / 1103 1 : 1018, / error-app-tag (SID 1025) / 1104 / = not-in-range (SID 1018) / 1105 2 : 1740, / error-data-node (SID 1026) / 1106 / = timezone-utc-offset (SID 1740) / 1107 3 : "Maximum exceeded" / error-message (SID 1027) / 1108 } 1109 } 1111 CBOR encoding: 1113 A1 # map(1) 1114 19 0400 # unsigned(1024) 1115 A4 # map(4) 1116 04 # unsigned(4) 1117 19 03F3 # unsigned(1011) 1118 01 # unsigned(1) 1119 19 03FA # unsigned(1018) 1120 02 # unsigned(2) 1121 19 06CC # unsigned(1740) 1122 03 # unsigned(3) 1123 70 # text(16) 1124 4D6178696D756D206578636565646564 1126 5.2. Using names in keys 1128 The yang-data extensions encoded using names are carried in a CBOR 1129 map containing a single item pair. The key of this item is set to 1130 the namespace qualified name of the yang-data extension container; 1131 the value is set to the CBOR encoding of this container as defined in 1132 Section 3.3. 1134 This example shows a serialization example of the yang-errors yang- 1135 data extension as defined in [I-D.ietf-core-comi] using names as 1136 defined Section 3.3. 1138 CBOR diagnostic notation: 1140 { 1141 "ietf-coreconf:error" : { 1142 "error-tag" : "invalid-value", 1143 "error-app-tag" : "not-in-range", 1144 "error-data-node" : "timezone-utc-offset", 1145 "error-message" : "Maximum exceeded" 1146 } 1147 } 1149 CBOR encoding: 1151 A1 # map(1) 1152 73 # text(19) 1153 696574662D636F7265636F6E663A6572726F72 # "ietf-coreconf:error" 1154 A4 # map(4) 1155 69 # text(9) 1156 6572726F722D746167 # "error-tag" 1157 6D # text(13) 1158 696E76616C69642D76616C7565 # "invalid-value" 1159 6D # text(13) 1160 6572726F722D6170702D746167 # "error-app-tag" 1161 6C # text(12) 1162 6E6F742D696E2D72616E6765 # "not-in-range" 1163 6F # text(15) 1164 6572726F722D646174612D6E6F6465 # "error-data-node" 1165 73 # text(19) 1166 74696D657A6F6E652D7574632D6F6666736574 1167 # "timezone-utc-offset" 1168 6D # text(13) 1169 6572726F722D6D657373616765 # "error-message" 1170 70 # text(16) 1171 4D6178696D756D206578636565646564 1173 6. Representing YANG Data Types in CBOR 1175 The CBOR encoding of an instance of a leaf or leaf-list schema node 1176 depends on the built-in type of that schema node. The following sub- 1177 section defines the CBOR encoding of each built-in type supported by 1178 YANG as listed in Section 4.2.4 of [RFC7950]. Each subsection shows 1179 an example value assigned to a schema node instance of the discussed 1180 built-in type. 1182 6.1. The unsigned integer Types 1184 Leafs of type uint8, uint16, uint32 and uint64 MUST be encoded using 1185 a CBOR unsigned integer data item (major type 0). 1187 The following example shows the encoding of an 'mtu' leaf schema node 1188 instance set to 1280 bytes. 1190 Definition example from [RFC8344]: 1192 leaf mtu { 1193 type uint16 { 1194 range "68..max"; 1195 } 1196 } 1198 CBOR diagnostic notation: 1280 1200 CBOR encoding: 19 0500 1202 6.2. The integer Types 1204 Leafs of type int8, int16, int32 and int64 MUST be encoded using 1205 either CBOR unsigned integer (major type 0) or CBOR negative integer 1206 (major type 1), depending on the actual value. 1208 The following example shows the encoding of a 'timezone-utc-offset' 1209 leaf schema node instance set to -300 minutes. 1211 Definition example from [RFC7317]: 1213 leaf timezone-utc-offset { 1214 type int16 { 1215 range "-1500 .. 1500"; 1216 } 1217 } 1219 CBOR diagnostic notation: -300 1221 CBOR encoding: 39 012B 1223 6.3. The 'decimal64' Type 1225 Leafs of type decimal64 MUST be encoded using a decimal fraction as 1226 defined in Section 3.4.4 of [RFC8949]. 1228 The following example shows the encoding of a 'my-decimal' leaf 1229 schema node instance set to 2.57. 1231 Definition example from [RFC7317]: 1233 leaf my-decimal { 1234 type decimal64 { 1235 fraction-digits 2; 1236 range "1 .. 3.14 | 10 | 20..max"; 1237 } 1238 } 1240 CBOR diagnostic notation: 4([-2, 257]) 1242 CBOR encoding: C4 82 21 19 0101 1244 6.4. The 'string' Type 1246 Leafs of type string MUST be encoded using a CBOR text string data 1247 item (major type 3). 1249 The following example shows the encoding of a 'name' leaf schema node 1250 instance set to "eth0". 1252 Definition example from [RFC8343]: 1254 leaf name { 1255 type string; 1256 } 1258 CBOR diagnostic notation: "eth0" 1260 CBOR encoding: 64 65746830 1262 6.5. The 'boolean' Type 1264 Leafs of type boolean MUST be encoded using a CBOR simple value 1265 'true' (major type 7, additional information 21) or 'false' (major 1266 type 7, additional information 20). 1268 The following example shows the encoding of an 'enabled' leaf schema 1269 node instance set to 'true'. 1271 Definition example from [RFC7317]: 1273 leaf enabled { 1274 type boolean; 1275 } 1277 CBOR diagnostic notation: true 1279 CBOR encoding: F5 1281 6.6. The 'enumeration' Type 1283 Leafs of type enumeration MUST be encoded using a CBOR unsigned 1284 integer (major type 0) or CBOR negative integer (major type 1), 1285 depending on the actual value. Enumeration values are either 1286 explicitly assigned using the YANG statement 'value' or automatically 1287 assigned based on the algorithm defined in Section 9.6.4.2 of 1288 [RFC7950]. 1290 The following example shows the encoding of an 'oper-status' leaf 1291 schema node instance set to 'testing'. 1293 Definition example from [RFC7317]: 1295 leaf oper-status { 1296 type enumeration { 1297 enum up { value 1; } 1298 enum down { value 2; } 1299 enum testing { value 3; } 1300 enum unknown { value 4; } 1301 enum dormant { value 5; } 1302 enum not-present { value 6; } 1303 enum lower-layer-down { value 7; } 1304 } 1305 } 1307 CBOR diagnostic notation: 3 1309 CBOR encoding: 03 1311 Values of 'enumeration' types defined in a 'union' type MUST be 1312 encoded using a CBOR text string data item (major type 3) and MUST 1313 contain one of the names assigned by 'enum' statements in YANG. The 1314 encoding MUST be enclosed by the enumeration CBOR tag as specified in 1315 Section 9.3. 1317 Definition example from [RFC7950]: 1319 type union { 1320 type int32; 1321 type enumeration { 1322 enum unbounded; 1323 } 1324 } 1326 CBOR diagnostic notation: 44("unbounded") 1328 CBOR encoding: D8 2C 69 756E626F756E646564 1330 6.7. The 'bits' Type 1332 Keeping in mind that bit positions are either explicitly assigned 1333 using the YANG statement 'position' or automatically assigned based 1334 on the algorithm defined in Section 9.7.4.2 of [RFC7950], each 1335 element of type bits could be seen as a set of bit positions (or 1336 offsets from position 0), that have a value of either 1, which 1337 represents the bit being set or 0, which represents that the bit is 1338 not set. 1340 Leafs of type bits MUST be encoded either using a CBOR array or byte 1341 string (major type 2). In case CBOR array representation is used, 1342 each element is either a positive integer (major type 0 with value 0 1343 being disallowed) that can be used to calculate the offset of the 1344 next byte string, or a byte string (major type 2) that carries the 1345 information whether certain bits are set or not. The initial offset 1346 value is 0 and each unsigned integer modifies the offset value of the 1347 next byte string by the integer value multiplied by 8. For example, 1348 if the bit offset is 0 and there is an integer with value 5, the 1349 first byte of the byte string that follows will represent bit 1350 positions 40 to 47 both ends included. If the byte string has a 1351 second byte, it will carry information about bits 48 to 55 and so on. 1352 Within each byte, bits are assigned from least to most significant. 1353 After the byte string, the offset is modified by the number of bytes 1354 in the byte string multiplied by 8. Bytes with no bits set (zero 1355 bytes) at the end of the byte string are never generated: If they 1356 would occur at the end of the array, the zero bytes are simply 1357 omitted; if they occur at the end of a byte string preceding an 1358 integer, the zero bytes are removed and the integer adjusted upwards 1359 by the number of zero bytes removed. An example follows. 1361 The following example shows the encoding of an 'alarm-state' leaf 1362 schema node instance with the 'critical' (position 3), 'warning' 1363 (position 8) and 'indeterminate' (position 128) flags set. 1365 typedef alarm-state { 1366 type bits { 1367 bit unknown; 1368 bit under-repair; 1369 bit critical; 1370 bit major; 1371 bit minor; 1372 bit warning { 1373 position 8; 1374 } 1375 bit indeterminate { 1376 position 128; 1377 } 1378 } 1379 } 1381 leaf alarm-state { 1382 type alarm-state; 1383 } 1385 CBOR diagnostic notation: [h'0401', 14, h'01'] 1387 CBOR encoding: 83 42 0401 0E 41 01 1389 In a number of cases the array would only need to have one element - 1390 a byte string with a few bytes inside. For this case, it is expected 1391 to omit the array element and have only the byte array that would 1392 have been inside. To illustrate this, let us consider the same 1393 example YANG definition, but this time encoding only 'under-repair' 1394 and 'critical' flags. The result would be 1396 CBOR diagnostic notation: h'06' 1398 CBOR encoding: 41 06 1400 Elements in the array MUST be either byte strings that do not end in 1401 a zero byte, or positive unsigned integers, where byte strings and 1402 integers MUST alternate, i.e., adjacent byte strings or adjacent 1403 integers are an error. An array with a single byte string MUST 1404 instead be encoded as just that byte string. An array with a single 1405 positive integer is an error. 1407 To maintain compatibility with the encoding of overlapping unions in 1408 XML, values of 'bits' types defined in a 'union' type MUST be encoded 1409 using a CBOR text string data item (major type 3) and MUST contain a 1410 space-separated sequence of names of 'bits' that are set. The 1411 encoding MUST be enclosed by the bits CBOR tag as specified in 1412 Section 9.3. 1414 The following example shows the encoding of an 'alarm-state' leaf 1415 schema node instance defined using a union type with the 'under- 1416 repair' and 'critical' flags set. 1418 Definition example: 1420 leaf alarm-state-2 { 1421 type union { 1422 type alarm-state; 1423 type bits { 1424 bit extra-flag; 1425 } 1426 } 1427 } 1429 CBOR diagnostic notation: 43("under-repair critical") 1431 CBOR encoding: D8 2B 75 756E6465722D72657061697220637269746963616C 1433 6.8. The 'binary' Type 1435 Leafs of type binary MUST be encoded using a CBOR byte string data 1436 item (major type 2). 1438 The following example shows the encoding of an 'aes128-key' leaf 1439 schema node instance set to 0x1f1ce6a3f42660d888d92a4d8030476e. 1441 Definition example: 1443 leaf aes128-key { 1444 type binary { 1445 length 16; 1446 } 1447 } 1449 CBOR diagnostic notation: h'1F1CE6A3F42660D888D92A4D8030476E' 1451 CBOR encoding: 50 1F1CE6A3F42660D888D92A4D8030476E 1453 6.9. The 'leafref' Type 1455 Leafs of type leafref MUST be encoded using the rules of the schema 1456 node referenced by the 'path' YANG statement. 1458 The following example shows the encoding of an 'interface-state-ref' 1459 leaf schema node instance set to "eth1". 1461 Definition example from [RFC8343]: 1463 typedef interface-state-ref { 1464 type leafref { 1465 path "/interfaces-state/interface/name"; 1466 } 1467 } 1469 container interfaces-state { 1470 list interface { 1471 key "name"; 1472 leaf name { 1473 type string; 1474 } 1475 leaf-list higher-layer-if { 1476 type interface-state-ref; 1477 } 1478 } 1479 } 1481 CBOR diagnostic notation: "eth1" 1483 CBOR encoding: 64 65746831 1485 6.10. The 'identityref' Type 1487 This specification supports two approaches for encoding identityref: 1488 as a YANG Schema Item iDentifier as defined in Section 3.2, or as a 1489 name as defined in Section 6.8 of [RFC7951]. 1491 6.10.1. SIDs as identityref 1493 When schema nodes of type identityref are implemented using SIDs, 1494 they MUST be encoded using a CBOR unsigned integer data item (major 1495 type 0). (Note that, as they are not used in the position of CBOR 1496 map keys, no delta mechanism is employed for SIDs used for 1497 identityref.) 1499 The following example shows the encoding of a 'type' leaf schema node 1500 instance set to the value 'iana-if-type:ethernetCsmacd' (SID 1880). 1502 Definition example from [RFC7317]: 1504 identity interface-type { 1505 } 1507 identity iana-interface-type { 1508 base interface-type; 1509 } 1511 identity ethernetCsmacd { 1512 base iana-interface-type; 1513 } 1515 leaf type { 1516 type identityref { 1517 base interface-type; 1518 } 1519 } 1521 CBOR diagnostic notation: 1880 1523 CBOR encoding: 19 0758 1525 6.10.2. Name as identityref 1527 Alternatively, an identityref MAY be encoded using a name as defined 1528 in Section 3.3. When names are used, identityref MUST be encoded 1529 using a CBOR text string data item (major type 3). If the identity 1530 is defined in different module than the leaf node containing the 1531 identityref data node, the namespace qualified form MUST be used. 1532 Otherwise, both the simple and namespace qualified forms are 1533 permitted. Names and namespaces are defined in Section 3.3. 1535 The following example shows the encoding of the identity 'iana-if- 1536 type:ethernetCsmacd' using its namespace qualified name. This 1537 example is described in Section 6.10.1. 1539 CBOR diagnostic notation: "iana-if-type:ethernetCsmacd" 1541 CBOR encoding: 78 1b 1542 69616E612D69662D747970653A65746865726E657443736D616364 1544 6.11. The 'empty' Type 1546 Leafs of type empty MUST be encoded using the CBOR null value (major 1547 type 7, additional information 22). 1549 The following example shows the encoding of an 'is-router' leaf 1550 schema node instance when present. 1552 Definition example from [RFC8344]: 1554 leaf is-router { 1555 type empty; 1556 } 1558 CBOR diagnostic notation: null 1560 CBOR encoding: F6 1562 6.12. The 'union' Type 1564 Leafs of type union MUST be encoded using the rules associated with 1565 one of the types listed. When used in a union, the following YANG 1566 datatypes are enclosed by a CBOR tag to avoid confusion between 1567 different YANG datatypes encoded using the same CBOR major type. 1569 * bits 1571 * enumeration 1573 * identityref 1575 * instance-identifier 1577 See Section 9.3 for the assigned value of these CBOR tags. 1579 As mentioned in Section 6.6 and in Section 6.7, 'enumeration' and 1580 'bits' are encoded as a CBOR text string data item (major type 3) 1581 when defined within a 'union' type. 1583 The following example shows the encoding of an 'ip-address' leaf 1584 schema node instance when set to "2001:db8:a0b:12f0::1". 1586 Definition example from [RFC7317]: 1588 typedef ipv4-address { 1589 type string { 1590 pattern '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3} 1591 ([0-9][1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])(%[\p{N} 1592 \p{L}]+)?'; 1593 } 1594 } 1596 typedef ipv6-address { 1597 type string { 1598 pattern '((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}((([0-9a 1599 -fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|(((25[0-5]|2[0-4][0 1600 -9]|[01]?[0-9]?[0-9])\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0 1601 -9]?[0-9])))(%[\p{N}\p{L}]+)?'; 1602 pattern '(([^:]+:){6}(([^:]+:[^:]+)|(.*\..*)))|((([^:]+:)*[^:]+) 1603 ?::(([^:]+:)*[^:]+)?)(%.+)?'; 1604 } 1605 } 1607 typedef ip-address { 1608 type union { 1609 type ipv4-address; 1610 type ipv6-address; 1611 } 1612 } 1614 leaf address { 1615 type ip-address; 1616 } 1618 CBOR diagnostic notation: "2001:db8:a0b:12f0::1" 1620 CBOR encoding: 74 323030313A6462383A6130623A313266303A3A31 1622 6.13. The 'instance-identifier' Type 1624 This specification supports two approaches for encoding an instance- 1625 identifier, one based on YANG Schema Item iDentifier as defined in 1626 Section 3.2 and one based on names as defined in Section 3.3. 1628 6.13.1. SIDs as instance-identifier 1630 SIDs uniquely identify a schema node. In the case of a single 1631 instance schema node, i.e., a schema node defined at the root of a 1632 YANG module or submodule or schema nodes defined within a container, 1633 the SID is sufficient to identify this instance. (Note that no delta 1634 mechanism is employed for SIDs used for identityref, see 1635 Section 6.10.1.) 1636 In the case of a schema node member of a YANG list, a SID is combined 1637 with the list key(s) to identify each instance within the YANG 1638 list(s). 1640 Single instance schema nodes MUST be encoded using a CBOR unsigned 1641 integer data item (major type 0) and set to the targeted schema node 1642 SID. 1644 Schema node members of a YANG list MUST be encoded using a CBOR array 1645 data item (major type 4) containing the following entries: 1647 * The first entry MUST be encoded as a CBOR unsigned integer data 1648 item (major type 0) and set to the targeted schema node SID. 1650 * The following entries MUST contain the value of each key required 1651 to identify the instance of the targeted schema node. These keys 1652 MUST be ordered as defined in the 'key' YANG statement, starting 1653 from the top level list, and followed by each of the subordinate 1654 list(s). 1656 Examples within this section assume the definition of a schema node 1657 of type 'instance-identifier': 1659 Definition example from [RFC7950]: 1661 container system { 1662 ... 1663 leaf reporting-entity { 1664 type instance-identifier; 1665 } 1667 *First example:* 1669 The following example shows the encoding of the 'reporting-entity' 1670 value referencing data node instance "/system/contact" (SID 1741). 1672 Definition example from [RFC7317]: 1674 container system { 1676 leaf contact { 1677 type string; 1678 } 1680 leaf hostname { 1681 type inet:domain-name; 1682 } 1683 } 1684 CBOR diagnostic notation: 1741 1686 CBOR encoding: 19 06CD 1688 *Second example:* 1690 This example aims to show how a schema node member of a YANG list is 1691 identified. It uses a somewhat arbitrarily modified YANG module 1692 version from [RFC7317] by adding country to the leafs and keys of 1693 authorized-key. 1695 The following example shows the encoding of the 'reporting-entity' 1696 value referencing list instance "/system/authentication/user/ 1697 authorized-key/key-data" (which is assumed to have SID 1734) for user 1698 name "bob" and authorized-key with name "admin" and country "france". 1700 list user { 1701 key name; 1703 leaf name { 1704 type string; 1705 } 1707 leaf password { 1708 type ianach:crypt-hash; 1709 } 1711 list authorized-key { 1712 key "name country"; 1714 leaf country { 1715 type string; 1716 } 1718 leaf name { 1719 type string; 1720 } 1722 leaf algorithm { 1723 type string; 1724 } 1726 leaf key-data { 1727 type binary; 1728 } 1729 } 1730 } 1731 CBOR diagnostic notation: [1734, "bob", "admin", "france"] 1733 CBOR encoding: 1735 84 # array(4) 1736 19 06C6 # unsigned(1734) 1737 63 # text(3) 1738 626F62 # "bob" 1739 65 # text(5) 1740 61646D696E # "admin" 1741 66 # text(6) 1742 6672616E6365 # "france" 1744 *Third example:* 1746 The following example shows the encoding of the 'reporting-entity' 1747 value referencing the list instance "/system/authentication/user" 1748 (SID 1730) corresponding to user name "jack". 1750 CBOR diagnostic notation: [1730, "jack"] 1752 CBOR encoding: 1754 82 # array(2) 1755 19 06C2 # unsigned(1730) 1756 64 # text(4) 1757 6A61636B # "jack" 1759 6.13.2. Names as instance-identifier 1761 An "instance-identifier" value is encoded as a text string that is 1762 analogous to the lexical representation in XML encoding; see 1763 Section 9.13.2 of [RFC7950]. However, the encoding of namespaces in 1764 instance-identifier values follows the rules stated in Section 3.3, 1765 namely: 1767 * The leftmost (top-level) data node name is always in the namespace 1768 qualified form. 1770 * Any subsequent data node name is in the namespace qualified form 1771 if the node is defined in a module other than its parent node, and 1772 the simple form is used otherwise. This rule also holds for node 1773 names appearing in predicates. 1775 For example, 1777 /ietf-interfaces:interfaces/interface[name='eth0']/ietf-ip:ipv4/ip 1778 is a valid instance-identifier value because the data nodes 1779 "interfaces", "interface", and "name" are defined in the module 1780 "ietf-interfaces", whereas "ipv4" and "ip" are defined in "ietf-ip". 1782 The resulting xpath MUST be encoded using a CBOR text string data 1783 item (major type 3). 1785 *First example:* 1787 This example is described in Section 6.13.1. 1789 CBOR diagnostic notation: "/ietf-system:system/contact" 1791 CBOR encoding: 1793 78 1c 2F696574662D73797374656D3A73797374656D2F636F6E74616374 1795 *Second example:* 1797 This example is described in Section 6.13.1. 1799 CBOR diagnostic notation (the line break is inserted for exposition 1800 only): 1802 "/ietf-system:system/authentication/user[name='bob']/ 1803 authorized-key[name='admin'][country='france']/key-data" 1805 CBOR encoding: 1807 78 6B 1808 2F696574662D73797374656D3A73797374656D2F61757468656E74696361 1809 74696F6E2F757365725B6E616D653D27626F62275D2F617574686F72697A 1810 65642D6B65795B6E616D653D2761646D696E275D5B636F756E7472793D27 1811 6672616E6365275D2F6B65792D64617461 1813 *Third example:* 1815 This example is described in Section 6.13.1. 1817 CBOR diagnostic notation: 1819 "/ietf-system:system/authentication/user[name='jack']" 1821 CBOR encoding: 1823 78 33 1824 2F696574662D73797374656D3A73797374656D2F61757468656E74696361 1825 74696F6E2F757365725B6E616D653D27626F62275D 1827 7. Content-Types 1829 This specification defines the media-type application/yang-data+cbor, 1830 which can be used without parameters or with the parameter id=name or 1831 id=sid. 1833 This media-type represents a CBOR YANG document containing one or 1834 multiple data node values. If the media-type parameter id is 1835 present, depending its value, each data node is identified by its 1836 associated namespace qualified name as defined in Section 3.3 1837 (id=name), by its associated YANG SID (represented as a SID delta or 1838 via tag 47) as defined in Section 3.2 (id=sid). If no id parameter 1839 is given, both forms may be present. 1841 The format of an application/yang-data+cbor representation is that of 1842 a CBOR map, mapping names and/or SIDs (as defined above) into 1843 instance values (using the rules defined in Section 4). 1845 It is not foreseen at this point that the valid set of values for the 1846 id parameter will extend beyond name, sid, or being unset; if that 1847 does happen, any new value is foreseen to be of the form 1848 [a-z][a-z0-9]*(-[a-z0-9]+)*. 1850 In summary, this document defines three content-types, which are 1851 intended for use by different classes of applications: 1853 * application/yang-data+cbor; id=sid -- for use by applications that 1854 need to be frugal with encoding space and text string processing 1855 (e.g., applications running on constrained nodes [RFC7228], or 1856 applications with particular performance requirements); 1858 * application/yang-data+cbor; id=name -- for use by applications 1859 that do not want to engage in SID management, and that have ample 1860 resources to manage text-string based item identifiers (e.g., 1861 applications that directly want to substitute application/ 1862 yang.data+json with a more efficient representation without any 1863 other changes); 1865 * application/yang-data+cbor -- for use by more complex applications 1866 that can benefit from the increased efficiency of SID identifiers 1867 but also need to integrate databases of YANG modules before SID 1868 mappings are defined for them. 1870 All three content-types are based on the same representation 1871 mechanisms, parts of which are simply not used in the first and 1872 second case. 1874 8. Security Considerations 1876 The security considerations of [RFC8949] and [RFC7950] apply. 1878 This document defines an alternative encoding for data modeled in the 1879 YANG data modeling language. As such, this encoding does not 1880 contribute any new security issues in addition to those identified 1881 for the specific protocol or context for which it is used. 1883 To minimize security risks, software on the receiving side SHOULD 1884 reject all messages that do not comply to the rules of this document 1885 and reply with an appropriate error message to the sender. 1887 When SIDs are in use, the interpretation of encoded data not only 1888 relies on having the right YANG modules, but also on having the right 1889 SID mapping information. Management and evolution of that mapping 1890 information therefore requires the same care as the management and 1891 evolution of the YANG modules themselves. The procedures in 1892 [I-D.ietf-core-sid] are RECOMMENDED for this purpose. 1894 9. IANA Considerations 1896 9.1. Media-Types Registry 1898 This document adds the following Media-Type to the "Media Types" 1899 registry. 1901 +================+============================+===========+ 1902 | Name | Template | Reference | 1903 +================+============================+===========+ 1904 | yang-data+cbor | application/yang-data+cbor | RFC XXXX | 1905 +----------------+----------------------------+-----------+ 1907 Table 2 1909 // RFC Ed.: please replace RFC XXXX with this RFC number and remove 1910 this note. 1912 Type name: application 1913 Subtype name: yang-data+cbor 1914 Required parameters: N/A 1915 Optional parameters: id (see Section 7 of RFC XXXX) 1916 Encoding considerations: binary (CBOR) 1917 Security considerations: see Section 8 of RFC XXXX 1918 Published specification: RFC XXXX 1919 Person & email address to contact for further information: CORE WG 1920 mailing list (core@ietf.org), or IETF Applications and Real-Time 1921 Area (art@ietf.org) 1923 Intended usage: COMMON 1924 Restrictions on usage: none 1925 Author/Change controller: IETF 1927 9.2. CoAP Content-Formats Registry 1929 This document adds the following Content-Format to the "CoAP Content- 1930 Formats", within the "Constrained RESTful Environments (CoRE) 1931 Parameters" registry, where TBD3 comes from the "Expert Review" 0-255 1932 range and TBD1 and TBD2 come from the "IETF Review" 256-9999 range. 1934 +============================+================+======+===========+ 1935 | Content Type | Content Coding | ID | Reference | 1936 +============================+================+======+===========+ 1937 | application/yang-data+cbor | - | TBD1 | RFC XXXX | 1938 +----------------------------+----------------+------+-----------+ 1939 | application/yang- | - | TBD2 | RFC XXXX | 1940 | data+cbor; id=name | | | | 1941 +----------------------------+----------------+------+-----------+ 1942 | application/yang- | - | TBD3 | RFC XXXX | 1943 | data+cbor; id=sid | | | | 1944 +----------------------------+----------------+------+-----------+ 1946 Table 3 1948 // RFC Ed.: please replace TBDx with assigned IDs, remove the 1949 requested ranges, and remove this note. 1950 // RFC Ed.: please replace RFC XXXX with this RFC number and remove 1951 this note. 1953 9.3. CBOR Tags Registry 1955 In the registry "CBOR Tags" [IANA.cbor-tags], as per Section 9.2 of 1956 [RFC8949], IANA has allocated the CBOR tags in Table 4 for the YANG 1957 datatypes listed. 1959 +=====+==================+============================+===========+ 1960 | Tag | Data Item | Semantics | Reference | 1961 +=====+==================+============================+===========+ 1962 | 43 | text string | YANG bits datatype; see | RFC XXXX | 1963 | | | Section 6.7 | | 1964 +-----+------------------+----------------------------+-----------+ 1965 | 44 | text string | YANG enumeration datatype; | RFC XXXX | 1966 | | | see Section 6.6. | | 1967 +-----+------------------+----------------------------+-----------+ 1968 | 45 | unsigned integer | YANG identityref datatype; | RFC XXXX | 1969 | | or text string | see Section 6.10. | | 1970 +-----+------------------+----------------------------+-----------+ 1971 | 46 | unsigned integer | YANG instance-identifier | RFC XXXX | 1972 | | or text string | datatype; see | | 1973 | | or array | Section 6.13. | | 1974 +-----+------------------+----------------------------+-----------+ 1975 | 47 | unsigned integer | YANG Schema Item | RFC XXXX | 1976 | | | iDentifier (SID); see | | 1977 | | | Section 3.2. | | 1978 +-----+------------------+----------------------------+-----------+ 1980 Table 4: CBOR tags defined by this specification 1982 // RFC Ed.: please replace RFC XXXX with RFC number and remove this 1983 note 1985 10. References 1987 10.1. Normative References 1989 [IANA.cbor-tags] 1990 IANA, "Concise Binary Object Representation (CBOR) Tags", 1991 . 1993 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1994 Requirement Levels", BCP 14, RFC 2119, 1995 DOI 10.17487/RFC2119, March 1997, 1996 . 1998 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1999 Specifications: ABNF", STD 68, RFC 5234, 2000 DOI 10.17487/RFC5234, January 2008, 2001 . 2003 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2004 and A. Bierman, Ed., "Network Configuration Protocol 2005 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2006 . 2008 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2009 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2010 . 2012 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2013 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2014 May 2017, . 2016 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 2017 Definition Language (CDDL): A Notational Convention to 2018 Express Concise Binary Object Representation (CBOR) and 2019 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 2020 June 2019, . 2022 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 2023 Representation (CBOR)", STD 94, RFC 8949, 2024 DOI 10.17487/RFC8949, December 2020, 2025 . 2027 10.2. Informative References 2029 [I-D.ietf-core-comi] 2030 Veillette, M., Stok, P. V. D., Pelov, A., Bierman, A., and 2031 I. Petrov, "CoAP Management Interface (CORECONF)", Work in 2032 Progress, Internet-Draft, draft-ietf-core-comi-11, 17 2033 January 2021, . 2036 [I-D.ietf-core-sid] 2037 Veillette, M., Pelov, A., Petrov, I., and C. Bormann, 2038 "YANG Schema Item iDentifier (YANG SID)", Work in 2039 Progress, Internet-Draft, draft-ietf-core-sid-16, 24 June 2040 2021, . 2043 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 2044 Constrained-Node Networks", RFC 7228, 2045 DOI 10.17487/RFC7228, May 2014, 2046 . 2048 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 2049 System Management", RFC 7317, DOI 10.17487/RFC7317, August 2050 2014, . 2052 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 2053 RFC 7951, DOI 10.17487/RFC7951, August 2016, 2054 . 2056 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2057 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2058 . 2060 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2061 Interchange Format", STD 90, RFC 8259, 2062 DOI 10.17487/RFC8259, December 2017, 2063 . 2065 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 2066 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 2067 . 2069 [RFC8344] Bjorklund, M., "A YANG Data Model for IP Management", 2070 RFC 8344, DOI 10.17487/RFC8344, March 2018, 2071 . 2073 Acknowledgments 2075 This document has been largely inspired by the extensive works done 2076 by Andy Bierman and Peter van der Stok on [I-D.ietf-core-comi]. 2077 [RFC7951] has also been a critical input to this work. The authors 2078 would like to thank the authors and contributors to these two drafts. 2080 The authors would also like to acknowledge the review, feedback, and 2081 comments from Ladislav Lhotka and Jürgen Schönwälder. 2083 Authors' Addresses 2085 Michel Veillette (editor) 2086 Trilliant Networks Inc. 2087 610 Rue du Luxembourg 2088 Granby Quebec J2J 2V2 2089 Canada 2091 Email: michel.veillette@trilliantinc.com 2093 Ivaylo Petrov (editor) 2094 Google Switzerland GmbH 2095 Brandschenkestrasse 110 2096 CH-8002 Zurich 2097 Switzerland 2099 Email: ivaylopetrov@google.com 2100 Alexander Pelov 2101 Acklio 2102 1137A avenue des Champs Blancs 2103 35510 Cesson-Sevigne 2104 France 2106 Email: a@ackl.io 2108 Carsten Bormann 2109 Universität Bremen TZI 2110 Postfach 330440 2111 D-28359 Bremen 2112 Germany 2114 Phone: +49-421-218-63921 2115 Email: cabo@tzi.org 2117 Michael Richardson 2118 Sandelman Software Works 2120 Email: mcr+ietf@sandelman.ca