idnits 2.17.00 (12 Aug 2021) /tmp/idnits6484/draft-ietf-core-yang-cbor-15.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 (24 January 2021) is 481 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 1215, but not defined -- Looks like a reference, but probably isn't: '257' on line 1215 == Missing Reference: '0-9' is mentioned on line 1565, but not defined == Missing Reference: '1-9' is mentioned on line 1556, but not defined == Missing Reference: '0-4' is mentioned on line 1565, but not defined == Missing Reference: '0-5' is mentioned on line 1565, but not defined == Missing Reference: '0-9a-fA-F' is mentioned on line 1564, but not defined -- Looks like a reference, but probably isn't: '01' on line 1565 == Outdated reference: A later version (-18) exists of draft-ietf-core-sid-15 Summary: 0 errors (**), 0 flaws (~~), 8 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 July 2021 Google Switzerland GmbH 6 A. Pelov 7 Acklio 8 24 January 2021 10 CBOR Encoding of Data Modeled with YANG 11 draft-ietf-core-yang-cbor-15 13 Abstract 15 This document defines encoding rules for serializing configuration 16 data, state data, RPC input and RPC output, action input, action 17 output, notifications and yang-data extension defined within YANG 18 modules using the Concise Binary Object Representation (CBOR, RFC 19 8949). 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at https://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on 28 July 2021. 38 Copyright Notice 40 Copyright (c) 2021 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 45 license-info) in effect on the date of publication of this document. 46 Please review these documents carefully, as they describe your rights 47 and restrictions with respect to this document. Code Components 48 extracted from this document must include Simplified BSD License text 49 as described in Section 4.e of the Trust Legal Provisions and are 50 provided without warranty as described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 3 56 3. Properties of the CBOR Encoding . . . . . . . . . . . . . . . 5 57 3.1. CBOR diagnostic notation . . . . . . . . . . . . . . . . 6 58 3.2. YANG Schema Item iDentifier . . . . . . . . . . . . . . . 8 59 3.3. Name . . . . . . . . . . . . . . . . . . . . . . . . . . 8 60 4. Encoding of YANG Schema Node Instances . . . . . . . . . . . 10 61 4.1. The 'leaf' . . . . . . . . . . . . . . . . . . . . . . . 10 62 4.1.1. Using SIDs in keys . . . . . . . . . . . . . . . . . 10 63 4.1.2. Using names in keys . . . . . . . . . . . . . . . . . 11 64 4.2. The 'container' and other nodes from the data tree . . . 11 65 4.2.1. Using SIDs in keys . . . . . . . . . . . . . . . . . 12 66 4.2.2. Using names in keys . . . . . . . . . . . . . . . . . 13 67 4.3. The 'leaf-list' . . . . . . . . . . . . . . . . . . . . . 15 68 4.3.1. Using SIDs in keys . . . . . . . . . . . . . . . . . 15 69 4.3.2. Using names in keys . . . . . . . . . . . . . . . . . 15 70 4.4. The 'list' and 'list' instance(s) . . . . . . . . . . . . 16 71 4.4.1. Using SIDs in keys . . . . . . . . . . . . . . . . . 17 72 4.4.2. Using names in keys . . . . . . . . . . . . . . . . . 19 73 4.5. The 'anydata' . . . . . . . . . . . . . . . . . . . . . . 21 74 4.5.1. Using SIDs in keys . . . . . . . . . . . . . . . . . 22 75 4.5.2. Using names in keys . . . . . . . . . . . . . . . . . 23 76 4.6. The 'anyxml' . . . . . . . . . . . . . . . . . . . . . . 24 77 4.6.1. Using SIDs in keys . . . . . . . . . . . . . . . . . 24 78 4.6.2. Using names in keys . . . . . . . . . . . . . . . . . 25 79 5. Encoding of 'yang-data' extension . . . . . . . . . . . . . . 25 80 5.1. Using SIDs in keys . . . . . . . . . . . . . . . . . . . 26 81 5.2. Using names in keys . . . . . . . . . . . . . . . . . . . 27 82 6. Representing YANG Data Types in CBOR . . . . . . . . . . . . 28 83 6.1. The unsigned integer Types . . . . . . . . . . . . . . . 28 84 6.2. The integer Types . . . . . . . . . . . . . . . . . . . . 29 85 6.3. The 'decimal64' Type . . . . . . . . . . . . . . . . . . 29 86 6.4. The 'string' Type . . . . . . . . . . . . . . . . . . . . 30 87 6.5. The 'boolean' Type . . . . . . . . . . . . . . . . . . . 30 88 6.6. The 'enumeration' Type . . . . . . . . . . . . . . . . . 31 89 6.7. The 'bits' Type . . . . . . . . . . . . . . . . . . . . . 32 90 6.8. The 'binary' Type . . . . . . . . . . . . . . . . . . . . 34 91 6.9. The 'leafref' Type . . . . . . . . . . . . . . . . . . . 34 92 6.10. The 'identityref' Type . . . . . . . . . . . . . . . . . 35 93 6.10.1. SIDs as identityref . . . . . . . . . . . . . . . . 35 94 6.10.2. Name as identityref . . . . . . . . . . . . . . . . 36 95 6.11. The 'empty' Type . . . . . . . . . . . . . . . . . . . . 36 96 6.12. The 'union' Type . . . . . . . . . . . . . . . . . . . . 37 97 6.13. The 'instance-identifier' Type . . . . . . . . . . . . . 38 98 6.13.1. SIDs as instance-identifier . . . . . . . . . . . . 38 99 6.13.2. Names as instance-identifier . . . . . . . . . . . . 41 100 7. Content-Types . . . . . . . . . . . . . . . . . . . . . . . . 43 101 8. Security Considerations . . . . . . . . . . . . . . . . . . . 43 102 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43 103 9.1. Media-Types Registry . . . . . . . . . . . . . . . . . . 43 104 9.2. CoAP Content-Formats Registry . . . . . . . . . . . . . . 44 105 9.3. CBOR Tags Registry . . . . . . . . . . . . . . . . . . . 44 106 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 45 107 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 45 108 11.1. Normative References . . . . . . . . . . . . . . . . . . 45 109 11.2. Informative References . . . . . . . . . . . . . . . . . 46 110 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 47 112 1. Introduction 114 The specification of the YANG 1.1 data modeling language [RFC7950] 115 defines an XML encoding for data instances, i.e. contents of 116 configuration datastores, state data, RPC inputs and outputs, action 117 inputs and outputs, and event notifications. 119 An additional set of encoding rules has been defined in [RFC7951] 120 based on the JavaScript Object Notation (JSON) Data Interchange 121 Format [RFC8259]. 123 The aim of this document is to define a set of encoding rules for the 124 Concise Binary Object Representation (CBOR) [RFC8949]. The resulting 125 encoding is more compact compared to XML and JSON and more suitable 126 for Constrained Nodes and/or Constrained Networks as defined by 127 [RFC7228]. 129 2. Terminology and Notation 131 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 132 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 133 "OPTIONAL" in this document are to be interpreted as described in BCP 134 14 [RFC2119] [RFC8174] when, and only when, they appear in all 135 capitals, as shown here. 137 The following terms are defined in [RFC7950]: 139 * action 141 * anydata 143 * anyxml 145 * data node 147 * data tree 149 * datastore 151 * feature 153 * identity 155 * module 157 * notification 159 * RPC 161 * schema node 163 * schema tree 165 * submodule 167 The following terms are defined in [RFC8040]: 169 * yang-data extension 171 This specification also makes use of the following terminology: 173 * child: A schema node defined as a child node of a container, a 174 list, a case, a notification, an RPC input, an RPC output, an 175 action input, an action output. 177 * delta: Difference between the current YANG SID and a reference 178 YANG SID. A reference YANG SID is defined for each context for 179 which deltas are used. 181 * item: A schema node, an identity, a module, a submodule or a 182 feature defined using the YANG modeling language. 184 * parent: The container, list, case, notification, RPC input, RPC 185 output, action input or action output node in which a schema node 186 is defined. 188 * YANG Schema Item iDentifier (YANG SID or simply SID): Unsigned 189 integer used to identify different YANG items. 191 3. Properties of the CBOR Encoding 193 This document defines CBOR encoding rules for YANG data trees and 194 their subtrees. 196 A node from the data tree such as container, list instance, 197 notification, RPC input, RPC output, action input and action output 198 is serialized using a CBOR map in which each child schema node is 199 encoded using a key and a value. This specification supports two 200 types of CBOR keys; YANG Schema Item iDentifier (YANG SID) as defined 201 in Section 3.2 and names as defined in Section 3.3. Each of these 202 key types is encoded using a specific CBOR type which allows their 203 interpretation during the deserialization process. Protocols or 204 mechanisms implementing this specification can mandate the use of a 205 specific key type. 207 In order to minimize the size of the encoded data, the proposed 208 mapping avoids any unnecessary meta-information beyond those natively 209 supported by CBOR. For instance, CBOR tags are used solely in the 210 case of SID not encoded as delta, anyxml schema nodes and the union 211 datatype to distinguish explicitly the use of different YANG 212 datatypes encoded using the same CBOR major type. 214 Unless specified otherwise by the protocol or mechanism implementing 215 this specification, the indefinite lengths encoding as defined in 216 Section 3.2 of [RFC8949] SHALL be supported by CBOR decoders. 218 Data nodes implemented using a CBOR array, map, byte string, and text 219 string can be instantiated but empty. In this case, they are encoded 220 with a length of zero. 222 When schema node are serialized using the rules defined by this 223 specification as part of an application payload, the payload SHOULD 224 include information that would allow a stateless way to identify each 225 node, such as the SID number associated with the node, SID delta from 226 another SID in the application payload, the namespace qualified name 227 or the instance-identifier. 229 Examples in Section 4 include a root CBOR map with a single entry 230 having a key set to either a namespace qualified name or a SID. This 231 root CBOR map is provided only as a typical usage example and is not 232 part of the present encoding rules. Only the value within this CBOR 233 map is compulsory. 235 3.1. CBOR diagnostic notation 237 Within this document, CBOR binary contents are represented using an 238 equivalent textual form called CBOR diagnostic notation as defined in 239 Section 8 of [RFC8949]. This notation is used strictly for 240 documentation purposes and is never used in the data serialization. 241 Table 1 below provides a summary of this notation. 243 +==========+======+====================+===========+==========+ 244 | CBOR | CBOR | Diagnostic | Example | CBOR | 245 | content | type | notation | | encoding | 246 +==========+======+====================+===========+==========+ 247 | Unsigned | 0 | Decimal digits | 123 | 18 7B | 248 | integer | | | | | 249 +----------+------+--------------------+-----------+----------+ 250 | Negative | 1 | Decimal digits | -123 | 38 7A | 251 | integer | | prefixed by a | | | 252 | | | minus sign | | | 253 +----------+------+--------------------+-----------+----------+ 254 | Byte | 2 | Hexadecimal value | h'F15C' | 42 F15C | 255 | string | | enclosed between | | | 256 | | | single quotes and | | | 257 | | | prefixed by an 'h' | | | 258 +----------+------+--------------------+-----------+----------+ 259 | Text | 3 | String of Unicode | "txt" | 63 | 260 | string | | characters | | 747874 | 261 | | | enclosed between | | | 262 | | | double quotes | | | 263 +----------+------+--------------------+-----------+----------+ 264 | Array | 4 | Comma-separated | [ 1, 2 ] | 82 01 02 | 265 | | | list of values | | | 266 | | | within square | | | 267 | | | brackets | | | 268 +----------+------+--------------------+-----------+----------+ 269 | Map | 5 | Comma-separated | { 1: 123, | A2 | 270 | | | list of key : | 2: 456 } | 01187B | 271 | | | value pairs within | | 021901C8 | 272 | | | curly braces | | | 273 +----------+------+--------------------+-----------+----------+ 274 | Boolean | 7/20 | false | false | F4 | 275 +----------+------+--------------------+-----------+----------+ 276 | | 7/21 | true | true | F5 | 277 +----------+------+--------------------+-----------+----------+ 278 | Null | 7/22 | null | null | F6 | 279 +----------+------+--------------------+-----------+----------+ 280 | Not | 7/23 | undefined | undefined | F7 | 281 | assigned | | | | | 282 +----------+------+--------------------+-----------+----------+ 284 Table 1: CBOR diagnostic notation summary 286 Note: CBOR binary contents shown in this specification are annotated 287 with comments. These comments are delimited by slashes ("/") as 288 defined in [RFC8610] Appendix G.6. 290 3.2. YANG Schema Item iDentifier 292 Some of the items defined in YANG [RFC7950] require the use of a 293 unique identifier. In both NETCONF [RFC6241] and RESTCONF [RFC8040], 294 these identifiers are implemented using strings. To allow the 295 implementation of data models defined in YANG in constrained devices 296 and constrained networks, a more compact method to identify YANG 297 items is required. This compact identifier, called YANG Schema Item 298 iDentifier, is an unsigned integer. The following items are 299 identified using YANG SIDs (often shortened to SIDs): 301 * identities 303 * data nodes 305 * RPCs and associated input(s) and output(s) 307 * actions and associated input(s) and output(s) 309 * notifications and associated information 311 * YANG modules, submodules and features 313 To minimize their size, SIDs used as keys in inner CBOR maps are 314 typically encoded using deltas. Conversion from SIDs to deltas and 315 back to SIDs are stateless processes solely based on the data 316 serialized or deserialized. These SIDs may also be encoded as 317 absolute number when enclosed by CBOR tag 47. 319 Mechanisms and processes used to assign SIDs to YANG items and to 320 guarantee their uniqueness are outside the scope of the present 321 specification. If SIDs are to be used, the present specification is 322 used in conjunction with a specification defining this management. 323 One example for such a specification is [I-D.ietf-core-sid]. 325 3.3. Name 327 This specification also supports the encoding of YANG item 328 identifiers as string, similar as those used by the JSON Encoding of 329 Data Modeled with YANG [RFC7951]. This approach can be used to avoid 330 the management overhead associated to SIDs allocation. The main 331 drawback is the significant increase in size of the encoded data. 333 YANG item identifiers implemented using names MUST be in one of the 334 following forms: 336 * simple - the identifier of the YANG item (i.e. schema node or 337 identity). 339 * namespace qualified - the identifier of the YANG item is prefixed 340 with the name of the module in which this item is defined, 341 separated by the colon character (":"). 343 The name of a module determines the namespace of all YANG items 344 defined in that module. If an item is defined in a submodule, then 345 the namespace qualified name uses the name of the main module to 346 which the submodule belongs. 348 ABNF syntax [RFC5234] of a name is shown in Figure 1, where the 349 production for "identifier" is defined in Section 14 of [RFC7950]. 351 name = [identifier ":"] identifier 353 Figure 1: ABNF Production for a simple or namespace qualified name 355 A namespace qualified name MUST be used for all members of a top- 356 level CBOR map and then also whenever the namespaces of the data node 357 and its parent node are different. In all other cases, the simple 358 form of the name SHOULD be used. 360 Definition example: 362 module example-foomod { 363 container top { 364 leaf foo { 365 type uint8; 366 } 367 } 368 } 370 module example-barmod { 371 import example-foomod { 372 prefix "foomod"; 373 } 374 augment "/foomod:top" { 375 leaf bar { 376 type boolean; 377 } 378 } 379 } 381 A valid CBOR encoding of the 'top' container is as follows. 383 CBOR diagnostic notation: 385 { 386 "example-foomod:top": { 387 "foo": 54, 388 "example-barmod:bar": true 389 } 390 } 392 Both the 'top' container and the 'bar' leaf defined in a different 393 YANG module as its parent container are encoded as namespace 394 qualified names. The 'foo' leaf defined in the same YANG module as 395 its parent container is encoded as simple name. 397 4. Encoding of YANG Schema Node Instances 399 Schema node instances defined using the YANG modeling language are 400 encoded using CBOR [RFC8949] based on the rules defined in this 401 section. We assume that the reader is already familiar with both 402 YANG [RFC7950] and CBOR [RFC8949]. 404 4.1. The 'leaf' 406 A 'leaf' MUST be encoded accordingly to its datatype using one of the 407 encoding rules specified in Section 6. 409 The following examples shows the encoding of a 'hostname' leaf using 410 a SID or a name. 412 Definition example from [RFC7317]: 414 leaf hostname { 415 type inet:domain-name; 416 } 418 4.1.1. Using SIDs in keys 420 CBOR diagnostic notation: 422 { 423 1752 : "myhost.example.com" / hostname (SID 1752) / 424 } 426 CBOR encoding: 428 A1 # map(1) 429 19 06D8 # unsigned(1752) 430 72 # text(18) 431 6D79686F73742E6578616D706C652E636F6D # "myhost.example.com" 433 4.1.2. Using names in keys 435 CBOR diagnostic notation: 437 { 438 "ietf-system:hostname" : "myhost.example.com" 439 } 441 CBOR encoding: 443 A1 # map(1) 444 74 # text(20) 445 696574662D73797374656D3A686F73746E616D65 446 72 # text(18) 447 6D79686F73742E6578616D706C652E636F6D 449 4.2. The 'container' and other nodes from the data tree 451 Containers, list instances, notification contents, rpc inputs, rpc 452 outputs, action inputs and action outputs MUST be encoded using a 453 CBOR map data item (major type 5). A map is comprised of pairs of 454 data items, with each data item consisting of a key and a value. 455 Each key within the CBOR map is set to a schema node identifier, each 456 value is set to the value of this schema node instance according to 457 the instance datatype. 459 This specification supports two types of CBOR keys; SID as defined in 460 Section 3.2 and names as defined in Section 3.3. 462 The following examples shows the encoding of a 'system-state' 463 container instance using SIDs or names. 465 Definition example from [RFC7317]: 467 typedef date-and-time { 468 type string { 469 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[\+\-] 470 \d{2}:\d{2})'; 471 } 472 } 474 container system-state { 476 container clock { 477 leaf current-datetime { 478 type date-and-time; 479 } 481 leaf boot-datetime { 482 type date-and-time; 483 } 484 } 485 } 487 4.2.1. Using SIDs in keys 489 In the context of containers and other nodes from the data tree, CBOR 490 map keys within inner CBOR maps can be encoded using deltas or SIDs. 491 In the case of deltas, they MUST be encoded using a CBOR unsigned 492 integer (major type 0) or CBOR negative integer (major type 1), 493 depending on the actual delta value. In the case of SID, they are 494 encoded using the SID value enclosed by CBOR tag 47 as defined in 495 Section 9.3. 497 Delta values are computed as follows: 499 * In the case of a 'container', deltas are equal to the SID of the 500 current schema node minus the SID of the parent 'container'. 502 * In the case of a 'list', deltas are equal to the SID of the 503 current schema node minus the SID of the parent 'list'. 505 * In the case of an 'rpc input' or 'rpc output', deltas are equal to 506 the SID of the current schema node minus the SID of the 'rpc'. 508 * In the case of an 'action input' or 'action output', deltas are 509 equal to the SID of the current schema node minus the SID of the 510 'action'. 512 * In the case of an 'notification content', deltas are equal to the 513 SID of the current schema node minus the SID of the 514 'notification'. 516 CBOR diagnostic notation: 518 { 519 1720 : { / system-state (SID 1720) / 520 1 : { / clock (SID 1721) / 521 2 : "2015-10-02T14:47:24Z-05:00", / current-datetime(SID 1723)/ 522 1 : "2015-09-15T09:12:58Z-05:00" / boot-datetime (SID 1722) / 523 } 524 } 525 } 527 CBOR encoding: 529 A1 # map(1) 530 19 06B8 # unsigned(1720) 531 A1 # map(1) 532 01 # unsigned(1) 533 A2 # map(2) 534 02 # unsigned(2) 535 78 1A # text(26) 536 323031352D31302D30325431343A34373A32345A2D30353A3030 537 01 # unsigned(1) 538 78 1A # text(26) 539 323031352D30392D31355430393A31323A35385A2D30353A3030 541 Figure 2: System state clock encoding 543 4.2.2. Using names in keys 545 CBOR map keys implemented using names MUST be encoded using a CBOR 546 text string data item (major type 3). A namespace-qualified name 547 MUST be used each time the namespace of a schema node and its parent 548 differ. In all other cases, the simple form of the name MUST be 549 used. Names and namespaces are defined in [RFC7951] section 4. 551 The following example shows the encoding of a 'system' container 552 instance using names. 554 Definition example from [RFC7317]: 556 typedef date-and-time { 557 type string { 558 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[\+\-] 559 \d{2}:\d{2})'; 560 } 561 } 563 container system-state { 565 container clock { 566 leaf current-datetime { 567 type date-and-time; 568 } 570 leaf boot-datetime { 571 type date-and-time; 572 } 573 } 574 } 576 CBOR diagnostic notation: 578 { 579 "ietf-system:system-state" : { 580 "clock" : { 581 "current-datetime" : "2015-10-02T14:47:24Z-05:00", 582 "boot-datetime" : "2015-09-15T09:12:58Z-05:00" 583 } 584 } 585 } 587 CBOR encoding: 589 A1 # map(1) 590 78 18 # text(24) 591 696574662D73797374656D3A73797374656D2D7374617465 592 A1 # map(1) 593 65 # text(5) 594 636C6F636B # "clock" 595 A2 # map(2) 596 70 # text(16) 597 63757272656E742D6461746574696D65 598 78 1A # text(26) 599 323031352D31302D30325431343A34373A32345A2D30353A3030 600 6D # text(13) 601 626F6F742D6461746574696D65 602 78 1A # text(26) 603 323031352D30392D31355430393A31323A35385A2D30353A3030 605 4.3. The 'leaf-list' 607 A leaf-list MUST be encoded using a CBOR array data item (major type 608 4). Each entry of this array MUST be encoded accordingly to its 609 datatype using one of the encoding rules specified in Section 6. 611 The following example shows the encoding of the 'search' leaf-list 612 instance containing two entries, "ietf.org" and "ieee.org". 614 Definition example [RFC7317]: 616 typedef domain-name { 617 type string { 618 length "1..253"; 619 pattern '((([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9].) 620 *([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.? 621 )|\.'; 622 } 623 } 625 leaf-list search { 626 type domain-name; 627 ordered-by user; 628 } 630 4.3.1. Using SIDs in keys 632 CBOR diagnostic notation: 634 { 635 1746 : [ "ietf.org", "ieee.org" ] / search (SID 1746) / 636 } 638 CBOR encoding: 640 A1 # map(1) 641 19 06D2 # unsigned(1746) 642 82 # array(2) 643 68 # text(8) 644 696574662E6F7267 # "ietf.org" 645 68 # text(8) 646 696565652E6F7267 # "ieee.org" 648 4.3.2. Using names in keys 650 CBOR diagnostic notation: 652 { 653 "ietf-system:search" : [ "ietf.org", "ieee.org" ] 654 } 656 CBOR encoding: 658 A1 # map(1) 659 72 # text(18) 660 696574662D73797374656D3A736561726368 # "ietf-system:search" 661 82 # array(2) 662 68 # text(8) 663 696574662E6F7267 # "ietf.org" 664 68 # text(8) 665 696565652E6F7267 # "ieee.org" 667 4.4. The 'list' and 'list' instance(s) 669 A list or a subset of a list MUST be encoded using a CBOR array data 670 item (major type 4). Each list instance within this CBOR array is 671 encoded using a CBOR map data item (major type 5) based on the 672 encoding rules of a collection as defined in Section 4.2. 674 It is important to note that this encoding rule also apply to a 675 single 'list' instance. 677 The following examples show the encoding of a 'server' list using 678 SIDs or names. 680 Definition example from [RFC7317]: 682 list server { 683 key name; 685 leaf name { 686 type string; 687 } 688 choice transport { 689 case udp { 690 container udp { 691 leaf address { 692 type host; 693 mandatory true; 694 } 695 leaf port { 696 type port-number; 697 } 698 } 699 } 700 } 701 leaf association-type { 702 type enumeration { 703 enum server; 704 enum peer; 705 enum pool; 706 } 707 default server; 708 } 709 leaf iburst { 710 type boolean; 711 default false; 712 } 713 leaf prefer { 714 type boolean; 715 default false; 716 } 717 } 719 4.4.1. Using SIDs in keys 721 The encoding rules of each 'list' instance are defined in 722 Section 4.2.1. Deltas of list members are equal to the SID of the 723 current schema node minus the SID of the 'list'. 725 CBOR diagnostic notation: 727 { 728 1756 : [ / server (SID 1756) / 729 { 730 3 : "NRC TIC server", / name (SID 1759) / 731 5 : { / udp (SID 1761) / 732 1 : "tic.nrc.ca", / address (SID 1762) / 733 2 : 123 / port (SID 1763) / 734 }, 735 1 : 0, / association-type (SID 1757) / 736 2 : false, / iburst (SID 1758) / 737 4 : true / prefer (SID 1760) / 738 }, 739 { 740 3 : "NRC TAC server", / name (SID 1759) / 741 5 : { / udp (SID 1761) / 742 1 : "tac.nrc.ca" / address (SID 1762) / 743 } 744 } 745 ] 746 } 748 CBOR encoding: 750 A1 # map(1) 751 19 06DC # unsigned(1756) 752 82 # array(2) 753 A5 # map(5) 754 03 # unsigned(3) 755 6E # text(14) 756 4E52432054494320736572766572 # "NRC TIC server" 757 05 # unsigned(5) 758 A2 # map(2) 759 01 # unsigned(1) 760 6A # text(10) 761 7469632E6E72632E6361 # "tic.nrc.ca" 762 02 # unsigned(2) 763 18 7B # unsigned(123) 764 01 # unsigned(1) 765 00 # unsigned(0) 766 02 # unsigned(2) 767 F4 # primitive(20) 768 04 # unsigned(4) 769 F5 # primitive(21) 770 A2 # map(2) 771 03 # unsigned(3) 772 6E # text(14) 773 4E52432054414320736572766572 # "NRC TAC server" 774 05 # unsigned(5) 775 A1 # map(1) 776 01 # unsigned(1) 777 6A # text(10) 778 7461632E6E72632E6361 # "tac.nrc.ca" 780 4.4.2. Using names in keys 782 The encoding rules of each 'list' instance are defined in 783 Section 4.2.2. 785 CBOR diagnostic notation: 787 { 788 "ietf-system:server" : [ 789 { 790 "name" : "NRC TIC server", 791 "udp" : { 792 "address" : "tic.nrc.ca", 793 "port" : 123 794 }, 795 "association-type" : 0, 796 "iburst" : false, 797 "prefer" : true 798 }, 799 { 800 "name" : "NRC TAC server", 801 "udp" : { 802 "address" : "tac.nrc.ca" 803 } 804 } 805 ] 806 } 808 CBOR encoding: 810 A1 # map(1) 811 72 # text(18) 812 696574662D73797374656D3A736572766572 813 82 # array(2) 814 A5 # map(5) 815 64 # text(4) 816 6E616D65 # "name" 817 6E # text(14) 818 4E52432054494320736572766572 819 63 # text(3) 820 756470 # "udp" 821 A2 # map(2) 822 67 # text(7) 823 61646472657373 # "address" 824 6A # text(10) 825 7469632E6E72632E6361 # "tic.nrc.ca" 826 64 # text(4) 827 706F7274 # "port" 828 18 7B # unsigned(123) 829 70 # text(16) 830 6173736F63696174696F6E2D74797065 831 00 # unsigned(0) 832 66 # text(6) 833 696275727374 # "iburst" 834 F4 # primitive(20) 835 66 # text(6) 836 707265666572 # "prefer" 837 F5 # primitive(21) 838 A2 # map(2) 839 64 # text(4) 840 6E616D65 # "name" 841 6E # text(14) 842 4E52432054414320736572766572 843 63 # text(3) 844 756470 # "udp" 845 A1 # map(1) 846 67 # text(7) 847 61646472657373 # "address" 848 6A # text(10) 849 7461632E6E72632E6361 # "tac.nrc.ca" 851 4.5. The 'anydata' 853 An anydata serves as a container for an arbitrary set of schema nodes 854 that otherwise appear as normal YANG-modeled data. An anydata 855 instance is encoded using the same rules as a container, i.e., CBOR 856 map. The requirement that anydata content can be modeled by YANG 857 implies the following: 859 * CBOR map keys of any inner schema nodes MUST be set to valid 860 deltas or names. 862 * The CBOR array MUST contain either unique scalar values (as a 863 leaf-list, see Section 4.3), or maps (as a list, see Section 4.4). 865 * CBOR map values MUST follow the encoding rules of one of the 866 datatypes listed in Section 4. 868 The following example shows a possible use of an anydata. In this 869 example, an anydata is used to define a schema node containing a 870 notification event, this schema node can be part of a YANG list to 871 create an event logger. 873 Definition example: 875 module event-log { 876 ... 877 anydata last-event; # SID 60123 879 This example also assumes the assistance of the following 880 notification. 882 module example-port { 883 ... 885 notification example-port-fault { # SID 60200 886 leaf port-name { # SID 60201 887 type string; 888 } 889 leaf port-fault { # SID 60202 890 type string; 891 } 892 } 893 } 895 4.5.1. Using SIDs in keys 897 CBOR diagnostic notation: 899 { 900 60123 : { / last-event (SID 60123) / 901 77 : { / example-port-fault (SID 60200) / 902 1 : "0/4/21", / port-name (SID 60201) / 903 2 : "Open pin 2" / port-fault (SID 60202) / 904 } 905 } 906 } 907 CBOR encoding: 909 A1 # map(1) 910 19 EADB # unsigned(60123) 911 A1 # map(1) 912 18 4D # unsigned(77) 913 A2 # map(2) 914 18 4E # unsigned(78) 915 66 # text(6) 916 302F342F3231 # "0/4/21" 917 18 4F # unsigned(79) 918 6A # text(10) 919 4F70656E2070696E2032 # "Open pin 2" 921 In some implementations, it might be simpler to use the absolute SID 922 tag encoding for the anydata root element. The resulting encoding is 923 as follows: 925 { 926 60123 : { / last-event (SID 60123) / 927 47(60200) : { / event-port-fault (SID 60200) / 928 1 : "0/4/21", / port-name (SID 60201) / 929 2 : "Open pin 2" / port-fault (SID 60202) / 930 } 931 } 932 } 934 4.5.2. Using names in keys 936 CBOR diagnostic notation: 938 { 939 "event-log:last-event" : { 940 "example-port:example-port-fault" : { 941 "port-name" : "0/4/21", 942 "port-fault" : "Open pin 2" 943 } 944 } 945 } 947 CBOR encoding: 949 A1 # map(1) 950 74 # text(20) 951 6576656E742D6C6F673A6C6173742D6576656E74 952 A1 # map(1) 953 78 20 # text(32) 954 6578616D706C652D706F72743A206578616D7 955 06C652D706F72742D6661756C74 956 A2 # map(2) 957 69 # text(9) 958 706F72742D6E616D65 # "port-name" 959 66 # text(6) 960 302F342F3231 # "0/4/21" 961 6A # text(10) 962 706F72742D6661756C74 # "port-fault" 963 6A # text(10) 964 4F70656E2070696E2032 # "Open pin 2" 966 4.6. The 'anyxml' 968 An anyxml schema node is used to serialize an arbitrary CBOR content, 969 i.e., its value can be any CBOR binary object. anyxml value MAY 970 contain CBOR data items tagged with one of the tags listed in 971 Section 9.3, these tags shall be supported. 973 The following example shows a valid CBOR encoded instance consisting 974 of a CBOR array containing the CBOR simple values 'true', 'null' and 975 'true'. 977 Definition example from [RFC7951]: 979 module bar-module { 980 ... 981 anyxml bar; # SID 60000 983 4.6.1. Using SIDs in keys 985 CBOR diagnostic notation: 987 { 988 60000 : [true, null, true] / bar (SID 60000) / 989 } 991 CBOR encoding: 993 A1 # map(1) 994 19 EA60 # unsigned(60000) 995 83 # array(3) 996 F5 # primitive(21) 997 F6 # primitive(22) 998 F5 # primitive(21) 1000 4.6.2. Using names in keys 1002 CBOR diagnostic notation: 1004 { 1005 "bar-module:bar" : [true, null, true] / bar (SID 60000) / 1006 } 1008 CBOR encoding: 1010 A1 # map(1) 1011 6E # text(14) 1012 6261722D6D6F64756C653A626172 # "bar-module:bar" 1013 83 # array(3) 1014 F5 # primitive(21) 1015 F6 # primitive(22) 1016 F5 # primitive(21) 1018 5. Encoding of 'yang-data' extension 1020 The yang-data extension [RFC8040] is used to define data structures 1021 in YANG that are not intended to be implemented as part of a 1022 datastore. 1024 The yang-data extension MUST be encoded using the encoding rules of 1025 nodes of data trees as defined in Section 4.2. 1027 Just like YANG containers, yang-data extension can be encoded using 1028 either SIDs or names. 1030 Definition example from [I-D.ietf-core-comi] Appendix A: 1032 module ietf-coreconf { 1033 ... 1035 import ietf-restconf { 1036 prefix rc; 1037 } 1039 rc:yang-data yang-errors { 1040 container error { 1041 leaf error-tag { 1042 type identityref { 1043 base error-tag; 1044 } 1045 } 1046 leaf error-app-tag { 1047 type identityref { 1048 base error-app-tag; 1049 } 1050 } 1051 leaf error-data-node { 1052 type instance-identifier; 1053 } 1054 leaf error-message { 1055 type string; 1056 } 1057 } 1058 } 1059 } 1061 5.1. Using SIDs in keys 1063 The yang-data extensions encoded using SIDs are carried in a CBOR map 1064 containing a single item pair. The key of this item is set to the 1065 SID assigned to the yang-data extension container, the value is set 1066 the CBOR encoding of this container as defined in Section 4.2. 1068 This example shows a serialization example of the yang-errors yang- 1069 data extension as defined in [I-D.ietf-core-comi] using SIDs as 1070 defined in Section 3.2. 1072 CBOR diagnostic notation: 1074 { 1075 1024 : { / error (SID 1024) / 1076 4 : 1011, / error-tag (SID 1028) / 1077 / = invalid-value (SID 1011) / 1078 1 : 1018, / error-app-tag (SID 1025) / 1079 / = not-in-range (SID 1018) / 1080 2 : 1740, / error-data-node (SID 1026) / 1081 / = timezone-utc-offset (SID 1740) / 1082 3 : "Maximum exceeded" / error-message (SID 1027) / 1083 } 1084 } 1086 CBOR encoding: 1088 A1 # map(1) 1089 19 0400 # unsigned(1024) 1090 A4 # map(4) 1091 04 # unsigned(4) 1092 19 03F3 # unsigned(1011) 1093 01 # unsigned(1) 1094 19 03FA # unsigned(1018) 1095 02 # unsigned(2) 1096 19 06CC # unsigned(1740) 1097 03 # unsigned(3) 1098 70 # text(16) 1099 4D6178696D756D206578636565646564 1101 5.2. Using names in keys 1103 The yang-data extensions encoded using names are carried in a CBOR 1104 map containing a single item pair. The key of this item is set to 1105 the namespace qualified name of the yang-data extension container, 1106 the value is set the CBOR encoding of this container as defined in 1107 Section 3.3. 1109 This example shows a serialization example of the yang-errors yang- 1110 data extension as defined in [I-D.ietf-core-comi] using names as 1111 defined Section 3.3. 1113 CBOR diagnostic notation: 1115 { 1116 "ietf-coreconf:error" : { 1117 "error-tag" : "invalid-value", 1118 "error-app-tag" : "not-in-range", 1119 "error-data-node" : "timezone-utc-offset", 1120 "error-message" : "Maximum exceeded" 1121 } 1122 } 1124 CBOR encoding: 1126 A1 # map(1) 1127 73 # text(19) 1128 696574662D636F7265636F6E663A6572726F72 # "ietf-coreconf:error" 1129 A4 # map(4) 1130 69 # text(9) 1131 6572726F722D746167 # "error-tag" 1132 6D # text(13) 1133 696E76616C69642D76616C7565 # "invalid-value" 1134 6D # text(13) 1135 6572726F722D6170702D746167 # "error-app-tag" 1136 6C # text(12) 1137 6E6F742D696E2D72616E6765 # "not-in-range" 1138 6F # text(15) 1139 6572726F722D646174612D6E6F6465 # "error-data-node" 1140 73 # text(19) 1141 74696D657A6F6E652D7574632D6F6666736574 1142 # "timezone-utc-offset" 1143 6D # text(13) 1144 6572726F722D6D657373616765 # "error-message" 1145 70 # text(16) 1146 4D6178696D756D206578636565646564 1148 6. Representing YANG Data Types in CBOR 1150 The CBOR encoding of an instance of a leaf or leaf-list schema node 1151 depends on the built-in type of that schema node. The following sub- 1152 section defines the CBOR encoding of each built-in type supported by 1153 YANG as listed in [RFC7950] section 4.2.4. Each subsection shows an 1154 example value assigned to a schema node instance of the discussed 1155 built-in type. 1157 6.1. The unsigned integer Types 1159 Leafs of type uint8, uint16, uint32 and uint64 MUST be encoded using 1160 a CBOR unsigned integer data item (major type 0). 1162 The following example shows the encoding of a 'mtu' leaf instance set 1163 to 1280 bytes. 1165 Definition example from [RFC8344]: 1167 leaf mtu { 1168 type uint16 { 1169 range "68..max"; 1170 } 1171 } 1173 CBOR diagnostic notation: 1280 1175 CBOR encoding: 19 0500 1177 6.2. The integer Types 1179 Leafs of type int8, int16, int32 and int64 MUST be encoded using 1180 either CBOR unsigned integer (major type 0) or CBOR negative integer 1181 (major type 1), depending on the actual value. 1183 The following example shows the encoding of a 'timezone-utc-offset' 1184 leaf instance set to -300 minutes. 1186 Definition example from [RFC7317]: 1188 leaf timezone-utc-offset { 1189 type int16 { 1190 range "-1500 .. 1500"; 1191 } 1192 } 1194 CBOR diagnostic notation: -300 1196 CBOR encoding: 39 012B 1198 6.3. The 'decimal64' Type 1200 Leafs of type decimal64 MUST be encoded using a decimal fraction as 1201 defined in Section 3.4.4 of [RFC8949]. 1203 The following example shows the encoding of a 'my-decimal' leaf 1204 instance set to 2.57. 1206 Definition example from [RFC7317]: 1208 leaf my-decimal { 1209 type decimal64 { 1210 fraction-digits 2; 1211 range "1 .. 3.14 | 10 | 20..max"; 1212 } 1213 } 1215 CBOR diagnostic notation: 4([-2, 257]) 1217 CBOR encoding: C4 82 21 19 0101 1219 6.4. The 'string' Type 1221 Leafs of type string MUST be encoded using a CBOR text string data 1222 item (major type 3). 1224 The following example shows the encoding of a 'name' leaf instance 1225 set to "eth0". 1227 Definition example from [RFC8343]: 1229 leaf name { 1230 type string; 1231 } 1233 CBOR diagnostic notation: "eth0" 1235 CBOR encoding: 64 65746830 1237 6.5. The 'boolean' Type 1239 Leafs of type boolean MUST be encoded using a CBOR simple value 1240 'true' (major type 7, additional information 21) or 'false' (major 1241 type 7, additional information 20). 1243 The following example shows the encoding of an 'enabled' leaf 1244 instance set to 'true'. 1246 Definition example from [RFC7317]: 1248 leaf enabled { 1249 type boolean; 1250 } 1252 CBOR diagnostic notation: true 1254 CBOR encoding: F5 1256 6.6. The 'enumeration' Type 1258 Leafs of type enumeration MUST be encoded using a CBOR unsigned 1259 integer (major type 0) or CBOR negative integer (major type 1), 1260 depending on the actual value. Enumeration values are either 1261 explicitly assigned using the YANG statement 'value' or automatically 1262 assigned based on the algorithm defined in [RFC7950] section 9.6.4.2. 1264 The following example shows the encoding of an 'oper-status' leaf 1265 instance set to 'testing'. 1267 Definition example from [RFC7317]: 1269 leaf oper-status { 1270 type enumeration { 1271 enum up { value 1; } 1272 enum down { value 2; } 1273 enum testing { value 3; } 1274 enum unknown { value 4; } 1275 enum dormant { value 5; } 1276 enum not-present { value 6; } 1277 enum lower-layer-down { value 7; } 1278 } 1279 } 1281 CBOR diagnostic notation: 3 1283 CBOR encoding: 03 1285 Values of 'enumeration' types defined in a 'union' type MUST be 1286 encoded using a CBOR text string data item (major type 3) and MUST 1287 contain one of the names assigned by 'enum' statements in YANG. The 1288 encoding MUST be enclosed by the enumeration CBOR tag as specified in 1289 Section 9.3. 1291 Definition example from [RFC7950]: 1293 type union { 1294 type int32; 1295 type enumeration { 1296 enum unbounded; 1297 } 1298 } 1300 CBOR diagnostic notation: 44("unbounded") 1302 CBOR encoding: D8 2C 69 756E626F756E646564 1304 6.7. The 'bits' Type 1306 Keeping in mind that bit positions are either explicitly assigned 1307 using the YANG statement 'position' or automatically assigned based 1308 on the algorithm defined in [RFC7950] section 9.7.4.2, each element 1309 of type bits could be seen as a set of bit positions (or offsets from 1310 position 0), that have a value of ether 1, which represents the bit 1311 being set or 0, which represents that the bit is not set. 1313 Leafs of type bits MUST be encoded either using a CBOR array or byte 1314 string (major type 2). In case CBOR array representation is used, 1315 each element is either a positive integer (major type 0 with value 0 1316 being disallowed) that can be used to calculate the offset of the 1317 next byte string, or a byte string (major type 2) that carries the 1318 information whether certain bits are set or not. The initial offset 1319 value is 0 and each unsigned integer modifies the offset value of the 1320 next byte string by the integer value multiplied by 8. For example, 1321 if the bit offset is 0 and there is an integer with value 5, the 1322 first byte of the byte string that follows will represent bit 1323 positions 40 to 47 both ends included. If the byte string has a 1324 second byte, it will carry information about bits 48 to 55 and so on. 1325 Within each byte, bits are assigned from least to most significant. 1326 After the byte string, the offset is modified by the number of bytes 1327 in the byte string multiplied by 8. Bytes with no bits set at the 1328 end of the byte string are removed. An example follows. 1330 The following example shows the encoding of an 'alarm-state' leaf 1331 instance with the 'critical', 'warning' and 'indeterminate' flags 1332 set. 1334 typedef alarm-state { 1335 type bits { 1336 bit unknown; 1337 bit under-repair; 1338 bit critical; 1339 bit major; 1340 bit minor; 1341 bit warning { 1342 position 8; 1343 } 1344 bit indeterminate { 1345 position 128; 1346 } 1347 } 1348 } 1350 leaf alarm-state { 1351 type alarm-state; 1352 } 1354 CBOR diagnostic notation: [h'0401', 14, h'01'] 1356 CBOR encoding: 83 42 0401 0E 41 01 1358 In a number of cases the array would only need to have one element - 1359 a byte string with a small number of bytes inside. For this case, it 1360 is expected to omit the array element and have only the byte array 1361 that would have been inside. To illustrate this, let us consider the 1362 same example yang definition, but this time encoding only 'under- 1363 repair' and 'critical' flags. The result would be 1365 CBOR diagnostic notation: h'06' 1367 CBOR encoding: 41 06 1369 Elements in the array MUST be either byte strings or positive 1370 unsigned integers, where byte strings and integers MUST alternate, 1371 i.e., adjacent byte strings or adjacent integers are an error. An 1372 array with a single byte string MUST instead by encoded as just that 1373 byte string. An array with a single positive integer is an error. 1375 Values of 'bit' types defined in a 'union' type MUST be encoded using 1376 a CBOR text string data item (major type 3) and MUST contain a space- 1377 separated sequence of names of 'bit' that are set. The encoding MUST 1378 be enclosed by the bits CBOR tag as specified in Section 9.3. 1380 The following example shows the encoding of an 'alarm-state' leaf 1381 instance defined using a union type with the 'under-repair' and 1382 'critical' flags set. 1384 Definition example: 1386 leaf alarm-state-2 { 1387 type union { 1388 type alarm-state; 1389 type bits { 1390 bit extra-flag; 1391 } 1392 } 1393 } 1395 CBOR diagnostic notation: 43("under-repair critical") 1397 CBOR encoding: D8 2B 75 756E6465722D72657061697220637269746963616C 1399 6.8. The 'binary' Type 1401 Leafs of type binary MUST be encoded using a CBOR byte string data 1402 item (major type 2). 1404 The following example shows the encoding of an 'aes128-key' leaf 1405 instance set to 0x1f1ce6a3f42660d888d92a4d8030476e. 1407 Definition example: 1409 leaf aes128-key { 1410 type binary { 1411 length 16; 1412 } 1413 } 1415 CBOR diagnostic notation: h'1F1CE6A3F42660D888D92A4D8030476E' 1417 CBOR encoding: 50 1F1CE6A3F42660D888D92A4D8030476E 1419 6.9. The 'leafref' Type 1421 Leafs of type leafref MUST be encoded using the rules of the schema 1422 node referenced by the 'path' YANG statement. 1424 The following example shows the encoding of an 'interface-state-ref' 1425 leaf instance set to "eth1". 1427 Definition example from [RFC8343]: 1429 typedef interface-state-ref { 1430 type leafref { 1431 path "/interfaces-state/interface/name"; 1432 } 1433 } 1435 container interfaces-state { 1436 list interface { 1437 key "name"; 1438 leaf name { 1439 type string; 1440 } 1441 leaf-list higher-layer-if { 1442 type interface-state-ref; 1443 } 1444 } 1445 } 1447 CBOR diagnostic notation: "eth1" 1449 CBOR encoding: 64 65746831 1451 6.10. The 'identityref' Type 1453 This specification supports two approaches for encoding identityref, 1454 a YANG Schema Item iDentifier as defined in Section 3.2 or a name as 1455 defined in [RFC7951] section 6.8. 1457 6.10.1. SIDs as identityref 1459 When schema nodes of type identityref are implemented using SIDs, 1460 they MUST be encoded using a CBOR unsigned integer data item (major 1461 type 0). (Note that no delta mechanism is employed for SIDs as 1462 identityref.) 1464 The following example shows the encoding of a 'type' leaf instance 1465 set to the value 'iana-if-type:ethernetCsmacd' (SID 1880). 1467 Definition example from [RFC7317]: 1469 identity interface-type { 1470 } 1472 identity iana-interface-type { 1473 base interface-type; 1474 } 1476 identity ethernetCsmacd { 1477 base iana-interface-type; 1478 } 1480 leaf type { 1481 type identityref { 1482 base interface-type; 1483 } 1484 } 1486 CBOR diagnostic notation: 1880 1488 CBOR encoding: 19 0758 1490 6.10.2. Name as identityref 1492 Alternatively, an identityref MAY be encoded using a name as defined 1493 in Section 3.3. When names are used, identityref MUST be encoded 1494 using a CBOR text string data item (major type 3). If the identity 1495 is defined in different module than the leaf node containing the 1496 identityref data node, the namespace qualified form MUST be used. 1497 Otherwise, both the simple and namespace qualified forms are 1498 permitted. Names and namespaces are defined in Section 3.3. 1500 The following example shows the encoding of the identity 'iana-if- 1501 type:ethernetCsmacd' using its namespace qualified name. This 1502 example is described in Section 6.10.1. 1504 CBOR diagnostic notation: "iana-if-type:ethernetCsmacd" 1506 CBOR encoding: 78 1b 1507 69616E612D69662D747970653A65746865726E657443736D616364 1509 6.11. The 'empty' Type 1511 Leafs of type empty MUST be encoded using the CBOR null value (major 1512 type 7, additional information 22). 1514 The following example shows the encoding of a 'is-router' leaf 1515 instance when present. 1517 Definition example from [RFC8344]: 1519 leaf is-router { 1520 type empty; 1521 } 1523 CBOR diagnostic notation: null 1525 CBOR encoding: F6 1527 6.12. The 'union' Type 1529 Leafs of type union MUST be encoded using the rules associated with 1530 one of the types listed. When used in a union, the following YANG 1531 datatypes are enclosed by a CBOR tag to avoid confusion between 1532 different YANG datatypes encoded using the same CBOR major type. 1534 * bits 1536 * enumeration 1538 * identityref 1540 * instance-identifier 1542 See Section 9.3 for the assigned value of these CBOR tags. 1544 As mentioned in Section 6.6 and in Section 6.7, 'enumeration' and 1545 'bits' are encoded as CBOR text string data item (major type 3) when 1546 defined within a 'union' type. 1548 The following example shows the encoding of an 'ip-address' leaf 1549 instance when set to "2001:db8:a0b:12f0::1". 1551 Definition example from [RFC7317]: 1553 typedef ipv4-address { 1554 type string { 1555 pattern '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3} 1556 ([0-9][1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])(%[\p{N} 1557 \p{L}]+)?'; 1558 } 1559 } 1561 typedef ipv6-address { 1562 type string { 1563 pattern '((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}((([0-9a 1564 -fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|(((25[0-5]|2[0-4][0 1565 -9]|[01]?[0-9]?[0-9])\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0 1566 -9]?[0-9])))(%[\p{N}\p{L}]+)?'; 1567 pattern '(([^:]+:){6}(([^:]+:[^:]+)|(.*\..*)))|((([^:]+:)*[^:]+) 1568 ?::(([^:]+:)*[^:]+)?)(%.+)?'; 1569 } 1570 } 1572 typedef ip-address { 1573 type union { 1574 type ipv4-address; 1575 type ipv6-address; 1576 } 1577 } 1579 leaf address { 1580 type inet:ip-address; 1581 } 1583 CBOR diagnostic notation: "2001:db8:a0b:12f0::1" 1585 CBOR encoding: 74 323030313A6462383A6130623A313266303A3A31 1587 6.13. The 'instance-identifier' Type 1589 This specification supports two approaches for encoding an instance- 1590 identifier, one based on YANG Schema Item iDentifier as defined in 1591 Section 3.2 and one based on names as defined in Section 3.3. 1593 6.13.1. SIDs as instance-identifier 1595 SIDs uniquely identify a schema node. In the case of a single 1596 instance schema node, i.e. a schema node defined at the root of a 1597 YANG module or submodule or schema nodes defined within a container, 1598 the SID is sufficient to identify this instance. 1600 In the case of a schema node member of a YANG list, a SID is combined 1601 with the list key(s) to identify each instance within the YANG 1602 list(s). 1604 Single instance schema nodes MUST be encoded using a CBOR unsigned 1605 integer data item (major type 0) and set to the targeted schema node 1606 SID. 1608 Schema nodes member of a YANG list MUST be encoded using a CBOR array 1609 data item (major type 4) containing the following entries: 1611 * The first entry MUST be encoded as a CBOR unsigned integer data 1612 item (major type 0) and set to the targeted schema node SID. 1614 * The following entries MUST contain the value of each key required 1615 to identify the instance of the targeted schema node. These keys 1616 MUST be ordered as defined in the 'key' YANG statement, starting 1617 from top level list, and follow by each of the subordinate 1618 list(s). 1620 Examples within this section assume the definition of a schema node 1621 of type 'instance-identifier': 1623 Definition example from [RFC7950]: 1625 container system { 1626 ... 1627 leaf reporting-entity { 1628 type instance-identifier; 1629 } 1631 leaf contact { type string; } 1633 leaf hostname { type inet:domain-name; } } ~~~~ 1635 *First example:* 1637 The following example shows the encoding of the 'reporting-entity' 1638 value referencing data node instance "/system/contact" (SID 1741). 1640 Definition example from [RFC7317]: 1642 container system { 1644 leaf contact { 1645 type string; 1646 } 1648 leaf hostname { 1649 type inet:domain-name; 1650 } 1651 } 1653 CBOR diagnostic notation: 1741 1655 CBOR encoding: 19 06CD 1657 *Second example:* 1659 The following example shows the encoding of the 'reporting-entity' 1660 value referencing list instance "/system/authentication/user/ 1661 authorized-key/key-data" (SID 1734) for user name "bob" and 1662 authorized-key "admin". 1664 Definition example from [RFC7317]: 1666 list user { 1667 key name; 1669 leaf name { 1670 type string; 1671 } 1672 leaf password { 1673 type ianach:crypt-hash; 1674 } 1676 list authorized-key { 1677 key name; 1679 leaf name { 1680 type string; 1681 } 1682 leaf algorithm { 1683 type string; 1684 } 1685 leaf key-data { 1686 type binary; 1687 } 1688 } 1689 CBOR diagnostic notation: [1734, "bob", "admin"] 1691 CBOR encoding: 1693 83 # array(3) 1694 19 06C6 # unsigned(1734) 1695 63 # text(3) 1696 626F62 # "bob" 1697 65 # text(5) 1698 61646D696E # "admin" 1700 *Third example:* 1702 The following example shows the encoding of the 'reporting-entity' 1703 value referencing the list instance "/system/authentication/user" 1704 (SID 1730) corresponding to user name "jack". 1706 CBOR diagnostic notation: [1730, "jack"] 1708 CBOR encoding: 1710 82 # array(2) 1711 19 06C2 # unsigned(1730) 1712 64 # text(4) 1713 6A61636B # "jack" 1715 6.13.2. Names as instance-identifier 1717 An "instance-identifier" value is encoded as a string that is 1718 analogical to the lexical representation in XML encoding; see 1719 Section 9.13.2 in [RFC7950]. However, the encoding of namespaces in 1720 instance-identifier values follows the rules stated in Section 3.3, 1721 namely: 1723 * The leftmost (top-level) data node name is always in the namespace 1724 qualified form. 1726 * Any subsequent data node name is in the namespace qualified form 1727 if the node is defined in a module other than its parent node, and 1728 the simple form is used otherwise. This rule also holds for node 1729 names appearing in predicates. 1731 For example, 1733 /ietf-interfaces:interfaces/interface[name='eth0']/ietf-ip:ipv4/ip 1734 is a valid instance-identifier value because the data nodes 1735 "interfaces", "interface", and "name" are defined in the module 1736 "ietf-interfaces", whereas "ipv4" and "ip" are defined in "ietf-ip". 1738 The resulting xpath MUST be encoded using a CBOR text string data 1739 item (major type 3). 1741 *First example:* 1743 This example is described in Section 6.13.1. 1745 CBOR diagnostic notation: "/ietf-system:system/contact" 1747 CBOR encoding: 1749 78 1c 2F696574662D73797374656D3A73797374656D2F636F6E74616374 1751 *Second example:* 1753 This example is described in Section 6.13.1. 1755 CBOR diagnostic notation: 1757 "/ietf-system:system/authentication/user[name='bob']/authorized-key 1758 [name='admin']/key-data" 1760 CBOR encoding: 1762 78 59 1763 2F696574662D73797374656D3A73797374656D2F61757468656E74696361 1764 74696F6E2F757365725B6E616D653D27626F62275D2F617574686F72697A 1765 65642D6B65790D0A5B6E616D653D2761646D696E275D2F6B65792D64617461 1767 *Third example:* 1769 This example is described in Section 6.13.1. 1771 CBOR diagnostic notation: 1773 "/ietf-system:system/authentication/user[name='jack']" 1775 CBOR encoding: 1777 78 33 1778 2F696574662D73797374656D3A73797374656D2F61757468656E74696361 1779 74696F6E2F757365725B6E616D653D27626F62275D 1781 7. Content-Types 1783 The following Content-Type is defined: 1785 application/yang-data+cbor; id=name: This Content-Type represents a 1786 CBOR YANG document containing one or multiple data node values. 1787 Each data node is identified by its associated namespace qualified 1788 name as defined in Section 3.3. 1790 FORMAT: CBOR map of name, instance-value 1792 The message payload of Content-Type 'application/yang-data+cbor' 1793 is encoded using a CBOR map. Each entry within the CBOR map 1794 contains the data node identifier (i.e. its namespace qualified 1795 name) and the associated instance-value. Instance-values are 1796 encoded using the rules defined in Section 4 1798 8. Security Considerations 1800 The security considerations of [RFC8949] and [RFC7950] apply. 1802 This document defines an alternative encoding for data modeled in the 1803 YANG data modeling language. As such, this encoding does not 1804 contribute any new security issues in addition of those identified 1805 for the specific protocol or context for which it is used. 1807 To minimize security risks, software on the receiving side SHOULD 1808 reject all messages that do not comply to the rules of this document 1809 and reply with an appropriate error message to the sender. 1811 9. IANA Considerations 1813 9.1. Media-Types Registry 1815 This document adds the following Media-Type to the "Media Types" 1816 registry. 1818 +================+============================+===========+ 1819 | Name | Template | Reference | 1820 +================+============================+===========+ 1821 | yang-data+cbor | application/yang-data+cbor | RFC XXXX | 1822 +----------------+----------------------------+-----------+ 1824 Table 2 1826 // RFC Ed.: please replace RFC XXXX with this RFC number and remove 1827 this note. 1829 Type name: application 1830 Subtype name: yang-data+cbor 1831 Required parameters: none 1832 Optional parameters: none 1833 Encoding considerations: binary (CBOR) 1834 Security considerations: see Section 8 of RFC XXXX 1835 Published specification: RFC XXXX 1836 Person & email address to contact for further information: CORE WG 1837 mailing list (core@ietf.org), or IETF Applications and Real-Time 1838 Area (art@ietf.org) 1839 Intended usage: COMMON 1840 Restrictions on usage: none 1841 Author/Change controller: IETF 1843 9.2. CoAP Content-Formats Registry 1845 This document adds the following Content-Format to the "CoAP Content- 1846 Formats", within the "Constrained RESTful Environments (CoRE) 1847 Parameters" registry. 1849 +====================+================+======+===========+ 1850 | Media Type | Content Coding | ID | Reference | 1851 +====================+================+======+===========+ 1852 | application/yang- | | TBD1 | RFC XXXX | 1853 | data+cbor; id=name | | | | 1854 +--------------------+----------------+------+-----------+ 1856 Table 3 1858 // RFC Ed.: please replace TBD1 with assigned IDs and remove this 1859 note. // RFC Ed.: please replace RFC XXXX with this RFC number and 1860 remove this note. 1862 9.3. CBOR Tags Registry 1864 This specification requires the assignment of CBOR tags for the 1865 following YANG datatypes. These tags are added to the CBOR Tags 1866 Registry as defined in Section 9.2 of [RFC8949]. 1868 +=====+==================+=============================+===========+ 1869 | Tag | Data Item | Semantics | Reference | 1870 +=====+==================+=============================+===========+ 1871 | 43 | text string | YANG bits datatype | [this] | 1872 +-----+------------------+-----------------------------+-----------+ 1873 | | | ; see Section 6.7. | | 1874 +-----+------------------+-----------------------------+-----------+ 1875 | 44 | text string | YANG enumeration datatype | [this] | 1876 +-----+------------------+-----------------------------+-----------+ 1877 | | | ; see Section 6.6. | | 1878 +-----+------------------+-----------------------------+-----------+ 1879 | 45 | unsigned integer | YANG identityref datatype | [this] | 1880 +-----+------------------+-----------------------------+-----------+ 1881 | | or text string | ; see Section 6.10. | | 1882 +-----+------------------+-----------------------------+-----------+ 1883 | 46 | unsigned integer | YANG instance-identifier | [this] | 1884 +-----+------------------+-----------------------------+-----------+ 1885 | | or text string | datatype; see Section 6.13. | [this] | 1886 +-----+------------------+-----------------------------+-----------+ 1887 | | or array | | | 1888 +-----+------------------+-----------------------------+-----------+ 1889 | 47 | unsigned integer | YANG Schema Item iDentifier | | 1890 +-----+------------------+-----------------------------+-----------+ 1891 | | | ; see Section 3.2. | [this] | 1892 +-----+------------------+-----------------------------+-----------+ 1894 Table 4 1896 // RFC Ed.: please replace [this] with RFC number and remove this 1897 note 1899 10. Acknowledgments 1901 This document has been largely inspired by the extensive works done 1902 by Andy Bierman and Peter van der Stok on [I-D.ietf-core-comi]. 1903 [RFC7951] has also been a critical input to this work. The authors 1904 would like to thank the authors and contributors to these two drafts. 1906 The authors would also like to acknowledge the review, feedback, and 1907 comments from Ladislav Lhotka and Juergen Schoenwaelder. 1909 11. References 1911 11.1. Normative References 1913 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1914 Requirement Levels", BCP 14, RFC 2119, 1915 DOI 10.17487/RFC2119, March 1997, 1916 . 1918 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1919 Specifications: ABNF", STD 68, RFC 5234, 1920 DOI 10.17487/RFC5234, January 2008, 1921 . 1923 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1924 and A. Bierman, Ed., "Network Configuration Protocol 1925 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1926 . 1928 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1929 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1930 . 1932 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1933 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1934 May 2017, . 1936 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1937 Definition Language (CDDL): A Notational Convention to 1938 Express Concise Binary Object Representation (CBOR) and 1939 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1940 June 2019, . 1942 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 1943 Representation (CBOR)", STD 94, RFC 8949, 1944 DOI 10.17487/RFC8949, December 2020, 1945 . 1947 11.2. Informative References 1949 [I-D.ietf-core-comi] 1950 Veillette, M., Stok, P., Pelov, A., Bierman, A., and I. 1951 Petrov, "CoAP Management Interface (CORECONF)", Work in 1952 Progress, Internet-Draft, draft-ietf-core-comi-11, 17 1953 January 2021, . 1956 [I-D.ietf-core-sid] 1957 Veillette, M., Pelov, A., and I. Petrov, "YANG Schema Item 1958 iDentifier (YANG SID)", Work in Progress, Internet-Draft, 1959 draft-ietf-core-sid-15, 17 January 2021, 1960 . 1963 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1964 Constrained-Node Networks", RFC 7228, 1965 DOI 10.17487/RFC7228, May 2014, 1966 . 1968 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1969 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1970 2014, . 1972 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 1973 RFC 7951, DOI 10.17487/RFC7951, August 2016, 1974 . 1976 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1977 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1978 . 1980 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1981 Interchange Format", STD 90, RFC 8259, 1982 DOI 10.17487/RFC8259, December 2017, 1983 . 1985 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 1986 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 1987 . 1989 [RFC8344] Bjorklund, M., "A YANG Data Model for IP Management", 1990 RFC 8344, DOI 10.17487/RFC8344, March 2018, 1991 . 1993 Authors' Addresses 1995 Michel Veillette (editor) 1996 Trilliant Networks Inc. 1997 610 Rue du Luxembourg 1998 Granby Quebec J2J 2V2 1999 Canada 2001 Email: michel.veillette@trilliantinc.com 2002 Ivaylo Petrov (editor) 2003 Google Switzerland GmbH 2004 Brandschenkestrasse 110 2005 CH-8002 Zurich 2006 Switzerland 2008 Email: ivaylopetrov@google.com 2010 Alexander Pelov 2011 Acklio 2012 1137A avenue des Champs Blancs 2013 35510 Cesson-Sevigne 2014 France 2016 Email: a@ackl.io