idnits 2.17.1 draft-ietf-core-yang-cbor-09.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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC7049]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 02, 2019) is 1813 days in the past. Is this intentional? 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: 'RFC5234' is mentioned on line 323, but not defined == Missing Reference: '-2' is mentioned on line 1083, but not defined -- Looks like a reference, but probably isn't: '257' on line 1083 == Missing Reference: '0-9' is mentioned on line 1406, but not defined == Missing Reference: '1-9' is mentioned on line 1397, but not defined == Missing Reference: '0-4' is mentioned on line 1406, but not defined == Missing Reference: '0-5' is mentioned on line 1406, but not defined == Missing Reference: '0-9a-fA-F' is mentioned on line 1405, but not defined -- Looks like a reference, but probably isn't: '01' on line 1406 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-17) exists of draft-ietf-core-comi-04 == Outdated reference: A later version (-24) exists of draft-ietf-core-sid-06 -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) -- Obsolete informational reference (is this intentional?): RFC 7277 (Obsoleted by RFC 8344) Summary: 2 errors (**), 0 flaws (~~), 10 warnings (==), 6 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: October 4, 2019 A. Pelov 6 Acklio 7 April 02, 2019 9 CBOR Encoding of Data Modeled with YANG 10 draft-ietf-core-yang-cbor-09 12 Abstract 14 This document defines encoding rules for serializing configuration 15 data, state data, RPC input and RPC output, Action input, Action 16 output and notifications defined within YANG modules using the 17 Concise Binary Object Representation (CBOR) [RFC7049]. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on October 4, 2019. 36 Copyright Notice 38 Copyright (c) 2019 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (https://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 54 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 3 55 3. Properties of the CBOR Encoding . . . . . . . . . . . . . . . 4 56 3.1. CBOR diagnostic notation . . . . . . . . . . . . . . . . 5 57 3.2. YANG Schema Item iDentifier (SID) . . . . . . . . . . . . 6 58 3.3. Name . . . . . . . . . . . . . . . . . . . . . . . . . . 7 59 4. Encoding of YANG Schema Node Instances . . . . . . . . . . . 9 60 4.1. The 'leaf' . . . . . . . . . . . . . . . . . . . . . . . 9 61 4.2. The 'container' and other collections . . . . . . . . . . 9 62 4.2.1. SIDs as keys . . . . . . . . . . . . . . . . . . . . 10 63 4.2.2. Names as keys . . . . . . . . . . . . . . . . . . . . 11 64 4.3. The 'leaf-list' . . . . . . . . . . . . . . . . . . . . . 13 65 4.4. The 'list' and 'list' instance(s) . . . . . . . . . . . . 14 66 4.4.1. SIDs as keys . . . . . . . . . . . . . . . . . . . . 15 67 4.4.2. Names as keys . . . . . . . . . . . . . . . . . . . . 17 68 4.5. The 'anydata' . . . . . . . . . . . . . . . . . . . . . . 19 69 4.6. The 'anyxml' . . . . . . . . . . . . . . . . . . . . . . 21 70 5. Encoding of YANG data templates . . . . . . . . . . . . . . . 22 71 5.1. SIDs as keys . . . . . . . . . . . . . . . . . . . . . . 23 72 5.2. Names as keys . . . . . . . . . . . . . . . . . . . . . . 24 73 6. Representing YANG Data Types in CBOR . . . . . . . . . . . . 25 74 6.1. The unsigned integer Types . . . . . . . . . . . . . . . 25 75 6.2. The integer Types . . . . . . . . . . . . . . . . . . . . 26 76 6.3. The 'decimal64' Type . . . . . . . . . . . . . . . . . . 26 77 6.4. The 'string' Type . . . . . . . . . . . . . . . . . . . . 27 78 6.5. The 'boolean' Type . . . . . . . . . . . . . . . . . . . 27 79 6.6. The 'enumeration' Type . . . . . . . . . . . . . . . . . 27 80 6.7. The 'bits' Type . . . . . . . . . . . . . . . . . . . . . 28 81 6.8. The 'binary' Type . . . . . . . . . . . . . . . . . . . . 30 82 6.9. The 'leafref' Type . . . . . . . . . . . . . . . . . . . 30 83 6.10. The 'identityref' Type . . . . . . . . . . . . . . . . . 31 84 6.10.1. SIDs as identityref . . . . . . . . . . . . . . . . 31 85 6.10.2. Name as identityref . . . . . . . . . . . . . . . . 32 86 6.11. The 'empty' Type . . . . . . . . . . . . . . . . . . . . 32 87 6.12. The 'union' Type . . . . . . . . . . . . . . . . . . . . 33 88 6.13. The 'instance-identifier' Type . . . . . . . . . . . . . 34 89 6.13.1. SIDs as instance-identifier . . . . . . . . . . . . 34 90 6.13.2. Names as instance-identifier . . . . . . . . . . . . 37 91 7. Security Considerations . . . . . . . . . . . . . . . . . . . 39 92 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 93 8.1. Tags Registry . . . . . . . . . . . . . . . . . . . . . . 39 94 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 39 95 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 40 96 10.1. Normative References . . . . . . . . . . . . . . . . . . 40 97 10.2. Informative References . . . . . . . . . . . . . . . . . 40 98 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 41 100 1. Introduction 102 The specification of the YANG 1.1 data modelling language [RFC7950] 103 defines an XML encoding for data instances, i.e. contents of 104 configuration datastores, state data, RPC inputs and outputs, action 105 inputs and outputs, and event notifications. 107 A new set of encoding rules has been defined to allow the use of the 108 same data models in environments based on the JavaScript Object 109 Notation (JSON) Data Interchange Format [RFC7159]. This is 110 accomplished in the JSON Encoding of Data Modeled with YANG 111 specification [RFC7951]. 113 The aim of this document is to define a set of encoding rules for the 114 Concise Binary Object Representation (CBOR) [RFC7049]. The resulting 115 encoding is more compact compared to XML and JSON and more suitable 116 for Constrained Nodes and/or Constrained Networks as defined by 117 [RFC7228]. 119 2. Terminology and Notation 121 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 122 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 123 document are to be interpreted as described in [RFC2119]. 125 The following terms are defined in [RFC7950]: 127 o action 129 o anydata 131 o anyxml 133 o data node 135 o data tree 137 o datastore 139 o feature 141 o identity 143 o module 144 o notification 146 o RPC 148 o schema node 150 o schema tree 152 o submodule 154 The following terms are defined in [RFC8040]: 156 o yang-data (YANG extension) 158 o YANG data template 160 This specification also makes use of the following terminology: 162 o child: A schema node defined within a collection such as a 163 container, a list, a case, a notification, an RPC input, an RPC 164 output, an action input, an action output. 166 o delta: Difference between the current SID and a reference SID. A 167 reference SID is defined for each context for which deltas are 168 used. 170 o item: A schema node, an identity, a module, a submodule or a 171 feature defined using the YANG modeling language. 173 o parent: The collection in which a schema node is defined. 175 o YANG Schema Item iDentifier (SID): Unsigned integer used to 176 identify different YANG items. 178 3. Properties of the CBOR Encoding 180 This document defines CBOR encoding rules for YANG schema trees and 181 their subtrees. 183 A collection such as container, list instance, notification, RPC 184 input, RPC output, action input and action output is serialized using 185 a CBOR map in which each child schema node is encoded using a key and 186 a value. This specification supports two type of CBOR keys; YANG 187 Schema Item iDentifier (SID) as defined in Section 3.2 and names as 188 defined in Section 3.3. Each of these key types is encoded using a 189 specific CBOR type which allows their interpretation during the 190 deserialization process. Protocols or mechanisms implementing this 191 specification can mandate the use of a specific key type. 193 In order to minimize the size of the encoded data, the proposed 194 mapping avoids any unnecessary meta-information beyond those natively 195 supported by CBOR. For instance, CBOR tags are used solely in the 196 case of anyxml schema nodes and the union datatype to distinguish 197 explicitly the use of different YANG datatypes encoded using the same 198 CBOR major type. 200 Unless specified otherwise by the protocol or mechanism implementing 201 this specification, the infinite lengths encoding as defined in 202 [RFC7049] section 2.2 SHALL be supported by CBOR decoders. 204 Data nodes implemented using a CBOR array, map, byte string, and text 205 string can be instantiated but empty. In this case, they are encoded 206 with a length of zero. 208 Application payloads carrying a value serialized using the rules 209 defined by this specification (e.g. CoAP Content-Format) SHOULD 210 include the identifier (e.g. SID, namespace qualified name, 211 instance-identifier) of this value. When SIDs are used as 212 identifiers, the reference SID SHALL be included in the payload to 213 allow stateless conversion of delta values to SIDs. Formats of these 214 application payloads are not defined by the current specification. 216 3.1. CBOR diagnostic notation 218 Within this document, CBOR binary contents are represented using an 219 equivalent textual form called CBOR diagnostic notation as defined in 220 [RFC7049] section 6. This notation is used strictly for 221 documentation purposes and is never used in the data serialization. 222 Table 1 below provides a summary of this notation. 224 +----------+------+--------------------------+-----------+----------+ 225 | CBOR | CBOR | Diagnostic notation | Example | CBOR | 226 | content | type | | | encoding | 227 +----------+------+--------------------------+-----------+----------+ 228 | Unsigned | 0 | Decimal digits | 123 | 18 7B | 229 | integer | | | | | 230 | Negative | 1 | Decimal digits prefixed | -123 | 38 7A | 231 | integer | | by a minus sign | | | 232 | Byte | 2 | Hexadecimal value | h'F15C' | 42 f15C | 233 | string | | enclosed between single | | | 234 | | | quotes and prefixed by | | | 235 | | | an 'h' | | | 236 | Text | 3 | String of Unicode | "txt" | 63 | 237 | string | | characters enclosed | | 747874 | 238 | | | between double quotes | | | 239 | Array | 4 | Comma-separated list of | [ 1, 2 ] | 82 01 02 | 240 | | | values within square | | | 241 | | | brackets | | | 242 | Map | 5 | Comma-separated list of | { 1: 123, | a2 | 243 | | | key : value pairs within | 2: 456 } | 01187B | 244 | | | curly braces | | 021901C8 | 245 | Boolean | 7/20 | false | false | F4 | 246 | | 7/21 | true | true | F5 | 247 | Null | 7/22 | null | null | F6 | 248 | Not | 7/23 | undefined | undefined | F7 | 249 | assigned | | | | | 250 +----------+------+--------------------------+-----------+----------+ 252 Table 1: CBOR diagnostic notation summary 254 The following extensions to the CBOR diagnostic notation are 255 supported: 257 o Any text within and including a pair of slashes is considered a 258 comment. 260 o Deltas are visualized as numbers preceded by a '+' or '-' sign. 261 The use of the '+' sign for positive deltas represents an 262 extension to the CBOR diagnostic notation as defined by [RFC7049] 263 section 6. 265 3.2. YANG Schema Item iDentifier (SID) 267 Some of the items defined in YANG [RFC7950] require the use of a 268 unique identifier. In both NETCONF [RFC6241] and RESTCONF [RFC8040], 269 these identifiers are implemented using strings. To allow the 270 implementation of data models defined in YANG in constrained devices 271 and constrained networks, a more compact method to identify YANG 272 items is required. This compact identifier, called YANG Schema Item 273 iDentifier (SID), is an unsigned integer. The following items are 274 identified using SIDs: 276 o identities 278 o data nodes 280 o RPCs and associated input(s) and output(s) 282 o actions and associated input(s) and output(s) 284 o notifications and associated information 286 o YANG modules, submodules and features 288 To minimize its size, in certain positions, SIDs are represented 289 using a (signed) delta from a reference SID and the current SID. 290 Conversion from SIDs to deltas and back to SIDs are stateless 291 processes solely based on the data serialized or deserialized. 293 Mechanisms and processes used to assign SIDs to YANG items and to 294 guarantee their uniqueness is outside the scope of the present 295 specification. If SIDs are to be used, the present specification is 296 used in conjunction with a specification defining this management. 297 One example for such a specification is under development as 298 [I-D.ietf-core-sid]. 300 3.3. Name 302 This specification also supports the encoding of YANG item 303 identifiers as string, similar as those used by the JSON Encoding of 304 Data Modeled with YANG [RFC7951]. This approach can be used to avoid 305 the management overhead associated to SIDs allocation. The main 306 drawback is the significant increase is size of the encoded data. 308 YANG items identifiers implemented using names MUST be in one of the 309 following forms: 311 o simple - the identifier of the YANG item (i.e. schema node or 312 identity). 314 o namespace qualified - the identifier of the YANG item is prefixed 315 with the name of the module in which this item is defined, 316 separated by the colon character (":"). 318 The name of a module determines the namespace of all YANG items 319 defined in that module. If an item is defined in a submodule, then 320 the namespace qualified name uses the name of the main module to 321 which the submodule belongs. 323 ABNF syntax [RFC5234] of a name is shown in Figure 1, where the 324 production for "identifier" is defined in Section 14 of [RFC7950]. 326 name = [identifier ":"] identifier 328 Figure 1: ABNF Production for a simple or namespace qualified name 330 A namespace qualified name MUST be used for all members of a top- 331 level CBOR map and then also whenever the namespaces of the data node 332 and its parent node are different. In all other cases, the simple 333 form of the name SHOULD be used. 335 Definition example: 337 module example-foomod { 338 container top { 339 leaf foo { 340 type uint8; 341 } 342 } 343 } 345 module example-barmod { 346 import example-foomod { 347 prefix "foomod"; 348 } 349 augment "/foomod:top" { 350 leaf bar { 351 type boolean; 352 } 353 } 354 } 356 A valid CBOR encoding of the 'top' container is as follow. 358 CBOR diagnostic notation: 360 { 361 "example-foomod:top": { 362 "foo": 54, 363 "example-barmod:bar": true 364 } 365 } 366 Both the 'top' container and the 'bar' leaf defined in a different 367 YANG module as its parent container are encoded as namespace 368 qualified names. The 'foo' leaf defined in the same YANG module as 369 its parent container is encoded as simple name. 371 4. Encoding of YANG Schema Node Instances 373 Schema node instances defined using the YANG modeling language are 374 encoded using CBOR [RFC7049] based on the rules defined in this 375 section. We assume that the reader is already familiar with both 376 YANG [RFC7950] and CBOR [RFC7049]. 378 4.1. The 'leaf' 380 A 'leaf' MUST be encoded accordingly to its datatype using one of the 381 encoding rules specified in Section 6. 383 4.2. The 'container' and other collections 385 Collections such as containers, list instances, notification 386 contents, rpc inputs, rpc outputs, action inputs and action outputs 387 MUST be encoded using a CBOR map data item (major type 5). A map is 388 comprised of pairs of data items, with each data item consisting of a 389 key and a value. Each key within the CBOR map is set to a schema 390 node identifier, each value is set to the value of this schema node 391 instance according to the instance datatype. 393 This specification supports two type of CBOR keys; SID as defined in 394 Section 3.2 and names as defined in Section 3.3. 396 The following examples shows the encoding of a 'system-state' 397 container instance using SIDs or names. 399 Definition example from [RFC7317]: 401 typedef date-and-time { 402 type string { 403 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[\+\-] 404 \d{2}:\d{2})'; 405 } 406 } 408 container system-state { 410 container clock { 411 leaf current-datetime { 412 type date-and-time; 413 } 415 leaf boot-datetime { 416 type date-and-time; 417 } 418 } 419 } 421 4.2.1. SIDs as keys 423 CBOR map keys implemented using SIDs MUST be encoded using a CBOR 424 unsigned integer (major type 0) or CBOR negative integer (major type 425 1), depending on the actual delta or to a SID preceded by the CBOR 426 tag 99. 428 // RFC Ed.: replace 99 by the allocated CBOR tag. 430 Delta values are computed as follows: 432 o In the case of a 'container', deltas are equal to the SID of the 433 current schema node minus the SID of the parent 'container'. 435 o In the case of a 'list', deltas are equal to the SID of the 436 current schema node minus the SID of the parent 'list'. 438 o In the case of an 'rpc input' or 'rcp output', deltas are equal to 439 the SID of the current schema node minus the SID of the 'rpc'. 441 o In the case of an 'action input' or 'action output', deltas are 442 equal to the SID of the current schema node minus the SID of the 443 'action'. 445 o In the case of an 'notification content', deltas are equal to the 446 SID of the current schema node minus the SID of the 447 'notification'. 449 This example assumes that the Media Type used to carry this container 450 consists of a CBOR map composed of the data node SID and data node 451 encoding. This root CBOR map is not part of the present encoding 452 rules and is not compulsory. 454 CBOR diagnostic notation: 456 { 457 1720 : { / system-state / 458 +1 : { / clock (SID 1721) / 459 +2 : "2015-10-02T14:47:24Z-05:00",/ current-datetime (SID 1723) / 460 +1 : "2015-09-15T09:12:58Z-05:00" / boot-datetime (SID 1722) / 461 } 462 } 463 } 465 CBOR encoding: 467 A1 # map(1) 468 19 06B8 # unsigned(1720) 469 A1 # map(1) 470 01 # unsigned(1) 471 A2 # map(2) 472 02 # unsigned(2) 473 78 1A # text(26) 474 323031352D31302D30325431343A34373A32345A2D30353A3030 475 01 # unsigned(1) 476 78 1A # text(26) 477 323031352D30392D31355430393A31323A35385A2D30353A3030 479 4.2.2. Names as keys 481 CBOR map keys implemented using names MUST be encoded using a CBOR 482 text string data item (major type 3). A namespace-qualified name 483 MUST be used each time the namespace of a schema node and its parent 484 differ. In all other cases, the simple form of the name MUST be 485 used. Names and namespaces are defined in [RFC7951] section 4. 487 The following example shows the encoding of a 'system' container 488 instance using names. 490 Definition example from [RFC7317]: 492 typedef date-and-time { 493 type string { 494 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[\+\-] 495 \d{2}:\d{2})'; 496 } 497 } 499 container system-state { 501 container clock { 502 leaf current-datetime { 503 type date-and-time; 504 } 506 leaf boot-datetime { 507 type date-and-time; 508 } 509 } 510 } 512 This example assumes that the Media Type used to carry this container 513 consists of a CBOR map composed of the data node namespace qualified 514 name and data node encoding. This root CBOR map is not part of the 515 present encoding rules and is not compulsory. 517 CBOR diagnostic notation: 519 { 520 "ietf-system:system-state" : { 521 "ietf-system:clock" : { 522 "current-datetime" : "2015-10-02T14:47:24Z-05:00", 523 "boot-datetime" : "2015-09-15T09:12:58Z-05:00" 524 } 525 } 526 } 528 CBOR encoding: 530 A1 # map(1) 531 78 18 # text(24) 532 696574662D73797374656D3A73797374656D2D7374617465 533 A1 # map(1) 534 71 # text(17) 535 696574662D73797374656D3A636C6F636B 536 A2 # map(2) 537 70 # text(16) 538 63757272656E742D6461746574696D65 539 78 1A # text(26) 540 323031352D31302D30325431343A34373A32345A2D30353A3030 541 6D # text(13) 542 626F6F742D6461746574696D65 543 78 1A # text(26) 544 323031352D30392D31355430393A31323A35385A2D30353A3030 546 4.3. The 'leaf-list' 548 A leaf-list MUST be encoded using a CBOR array data item (major type 549 4). Each entry of this array MUST be encoded accordingly to its 550 datatype using one of the encoding rules specified in Section 6. 552 The following example shows the encoding of the 'search' leaf-list 553 instance containing two entries, "ietf.org" and "ieee.org". 555 Definition example [RFC7317]: 557 typedef domain-name { 558 type string { 559 length "1..253"; 560 pattern '((([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9].) 561 *([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.? 562 )|\.'; 563 } 564 } 566 leaf-list search { 567 type domain-name; 568 ordered-by user; 569 } 571 CBOR diagnostic notation: [ "ietf.org", "ieee.org" ] 573 CBOR encoding: 82 68 696574662E6F7267 68 696565652E6F7267 575 4.4. The 'list' and 'list' instance(s) 577 A list or a subset of a list MUST be encoded using a CBOR array data 578 item (major type 4). Each list instance within this CBOR array is 579 encoded using a CBOR map data item (major type 5) based on the 580 encoding rules of a collection as defined in Section 4.2. 582 It is important to note that this encoding rule also apply to a 583 single 'list' instance. 585 The following examples show the encoding of a 'server' list using 586 SIDs or names. 588 Definition example from [RFC7317]: 590 list server { 591 key name; 593 leaf name { 594 type string; 595 } 596 choice transport { 597 case udp { 598 container udp { 599 leaf address { 600 type host; 601 mandatory true; 602 } 603 leaf port { 604 type port-number; 605 } 606 } 607 } 608 } 609 leaf association-type { 610 type enumeration { 611 enum server; 612 enum peer; 613 enum pool; 614 } 615 default server; 616 } 617 leaf iburst { 618 type boolean; 619 default false; 620 } 621 leaf prefer { 622 type boolean; 623 default false; 624 } 625 } 627 4.4.1. SIDs as keys 629 The encoding rules of each 'list' instance are defined in 630 Section 4.2.1. Deltas of list members are equal to the SID of the 631 current schema node minus the SID of the 'list'. 633 This example assumes that the Media Type used to carry this list 634 consists of a CBOR map composed of the data node SID and data node 635 encoding. This root CBOR map is not part of the present encoding 636 rules and is not compulsory. 638 CBOR diagnostic notation: 640 { 641 1756 : [ / server (SID 1756) / 642 { 643 +3 : "NRC TIC server", / name (SID 1759) / 644 +5 : { / udp (SID 1761) / 645 +1 : "tic.nrc.ca", / address (SID 1762) / 646 +2 : 123 / port (SID 1763) / 647 }, 648 +1 : 0, / association-type (SID 1757) / 649 +2 : false, / iburst (SID 1758) / 650 +4 : true / prefer (SID 1760) / 651 }, 652 { 653 +3 : "NRC TAC server", / name (SID 1759) / 654 +5 : { / udp (SID 1761) / 655 +1 : "tac.nrc.ca" / address (SID 1762) / 656 } 657 } 658 ] 659 } 661 CBOR encoding: 663 A1 # map(1) 664 19 06DC # unsigned(1756) 665 82 # array(2) 666 A5 # map(5) 667 03 # unsigned(3) 668 6E # text(14) 669 4E52432054494320736572766572 # "NRC TIC server" 670 05 # unsigned(5) 671 A2 # map(2) 672 01 # unsigned(1) 673 6A # text(10) 674 7469632E6E72632E6361 # "tic.nrc.ca" 675 02 # unsigned(2) 676 18 7B # unsigned(123) 677 01 # unsigned(1) 678 00 # unsigned(0) 679 02 # unsigned(2) 680 F4 # primitive(20) 681 04 # unsigned(4) 682 F5 # primitive(21) 683 A2 # map(2) 684 03 # unsigned(3) 685 6E # text(14) 686 4E52432054414320736572766572 # "NRC TAC server" 687 05 # unsigned(5) 688 A1 # map(1) 689 01 # unsigned(1) 690 6A # text(10) 691 7461632E6E72632E6361 # "tac.nrc.ca" 693 4.4.2. Names as keys 695 The encoding rules of each 'list' instance are defined in 696 Section 4.2.2. 698 This example assumes that the Media Type used to carry this container 699 consists of a CBOR map composed of the data node namespace qualified 700 name and data node encoding. This root CBOR map is not part of the 701 present encoding rules and is not compulsory. 703 CBOR diagnostic notation: 705 { 706 "ietf-system:server" : [ 707 { 708 "name" : "NRC TIC server", 709 "udp" : { 710 "address" : "tic.nrc.ca", 711 "port" : 123 712 }, 713 "association-type" : 0, 714 "iburst" : false, 715 "prefer" : true 716 }, 717 { 718 "name" : "NRC TAC server", 719 "udp" : { 720 "address" : "tac.nrc.ca" 721 } 722 } 723 ] 724 } 726 CBOR encoding: 728 A1 # map(1) 729 72 # text(18) 730 696574662D73797374656D3A736572766572 731 82 # array(2) 732 A5 # map(5) 733 64 # text(4) 734 6E616D65 # "name" 735 6E # text(14) 736 4E52432054494320736572766572 737 63 # text(3) 738 756470 # "udp" 739 A2 # map(2) 740 67 # text(7) 741 61646472657373 # "address" 742 6A # text(10) 743 7469632E6E72632E6361 # "tic.nrc.ca" 744 64 # text(4) 745 706F7274 # "port" 746 18 7B # unsigned(123) 747 70 # text(16) 748 6173736F63696174696F6E2D74797065 749 00 # unsigned(0) 750 66 # text(6) 751 696275727374 # "iburst" 752 F4 # primitive(20) 753 66 # text(6) 754 707265666572 # "prefer" 755 F5 # primitive(21) 756 A2 # map(2) 757 64 # text(4) 758 6E616D65 # "name" 759 6E # text(14) 760 4E52432054414320736572766572 761 63 # text(3) 762 756470 # "udp" 763 A1 # map(1) 764 67 # text(7) 765 61646472657373 # "address" 766 6A # text(10) 767 7461632E6E72632E6361 # "tac.nrc.ca" 769 4.5. The 'anydata' 771 An anydata serves as a container for an arbitrary set of schema nodes 772 that otherwise appear as normal YANG-modeled data. An anydata 773 instance is encoded using the same rules as a container, i.e., CBOR 774 map. The requirement that anydata content can be modeled by YANG 775 implies the following: 777 o CBOR map keys of any inner schema nodes MUST be set to valid 778 deltas or names. 780 o The CBOR array MUST contain either unique scalar values (as a 781 leaf-list, see Section 4.3), or maps (as a list, see Section 4.4). 783 o CBOR map values MUST follow the encoding rules of one of the 784 datatypes listed in Section 4. 786 The following example shows a possible use of an anydata. In this 787 example, an anydata is used to define a schema node containing a 788 notification event, this schema node can be part of a YANG list to 789 create an event logger. 791 Definition example: 793 module event-log { 794 ... 795 anydata last-event; # SID 60123 797 This example also assumes the assistance of the following 798 notification. 800 module example-port { 801 ... 803 notification example-port-fault { # SID 60200 804 leaf port-name { # SID 60201 805 type string; 806 } 807 leaf port-fault { # SID 60202 808 type string; 809 } 810 } 811 } 813 This example assumes that the Media Type used to carry this anydata 814 consists of a CBOR map composed of the data node SID and data node 815 encoding. This root CBOR map is not part of the present encoding 816 rules and is not compulsory. 818 CBOR diagnostic notation: 820 { 821 60123 : { / last-event (SID=60123) / 822 +77 : { / event (SID=60200) / 823 +1 : "0/4/21", / port-name (SID=60201) / 824 +2 : "Open pin 2" / port-fault (SID=60202) / 825 } 826 } 827 } 829 CBOR encoding: 831 A1 # map(1) 832 19 EADB # unsigned(60123) 833 A1 # map(1) 834 18 4D # unsigned(77) 835 A2 # map(2) 836 18 4E # unsigned(78) 837 66 # text(6) 838 302F342F3231 # "0/4/21" 839 18 4F # unsigned(79) 840 6A # text(10) 841 4F70656E2070696E2032 # "Open pin 2" 843 In some implementations, it might be simpler to use the absolute SID 844 tag encoding for the anydata root element. The resulting encoding is 845 as follow: 847 { 848 60123 : { / last-event (SID=60123) / 849 99(60200) : { / event (SID=60123) / 850 +1 : "0/4/21", / port-name (SID=60201) / 851 +2 : "Open pin 2" / port-fault (SID=60202) / 852 } 853 } 854 } 856 // RFC Ed.: replace 99 by the allocated CBOR tag. 858 4.6. The 'anyxml' 860 An anyxml schema node is used to serialize an arbitrary CBOR content, 861 i.e., its value can be any CBOR binary object. anyxml value MAY 862 contain CBOR data items tagged with one of the tag listed in 863 Section 8.1, these tags shall be supported. 865 The following example shows a valid CBOR encoded instance consisting 866 of a CBOR array containing the CBOR simple values 'true', 'null' and 867 'true'. 869 Definition example from [RFC7951]: 871 anyxml bar; 873 Note: This example assumes that the Media Type used to carry this 874 anyxml consists of a CBOR map composed of the data node SID and data 875 node encoding. This root CBOR map is not part of the present 876 encoding rules and is not compulsory. 878 CBOR diagnostic notation: 880 { 881 60000 : [true, null, true] / bar (SID 60000) / 882 } 884 CBOR encoding: 886 A1 # map(1) 887 19 EA60 # unsigned(60000) 888 83 # array(3) 889 F5 # primitive(21) 890 F6 # primitive(22) 891 F5 # primitive(21) 893 5. Encoding of YANG data templates 895 YANG data templates are data structures defined in YANG but not 896 intended to be implemented as part of a datastore. YANG data 897 templates are defined using the 'yang-data' extension as described by 898 RFC 8040. 900 YANG data templates SHOULD be encoded using the encoding rules of a 901 collection as defined in Section 4.2. 903 Just like YANG containers, YANG data templates can be encoded using 904 either SIDs or names. 906 Definition example from [I-D.ietf-core-comi]: 908 import ietf-restconf { 909 prefix rc; 910 } 912 rc:yang-data yang-errors { 913 container error { 914 leaf error-tag { 915 type identityref { 916 base error-tag; 917 } 918 } 919 leaf error-app-tag { 920 type identityref { 921 base error-app-tag; 922 } 923 } 924 leaf error-data-node { 925 type instance-identifier; 926 } 927 leaf error-message { 928 type string; 929 } 930 } 931 } 933 5.1. SIDs as keys 935 YANG template encoded using SIDs are carried in a CBOR map containing 936 a single item pair. The key of this item is set to the SID assigned 937 to the YANG template container, the value is set the CBOR encoding of 938 this container as defined in Section 4.2. 940 This example shows a serialization example of the yang-errors 941 template as defined in [I-D.ietf-core-comi] using SIDs as defined in 942 Section 3.2. 944 CBOR diagnostic notation: 946 { 947 1024 : { / error (SID 1024) / 948 +4 : 1011, / error-tag (SID 1028) / 949 / = invalid-value (SID 1011) / 950 +1 : 1018, / error-app-tag (SID 1025) / 951 / = not-in-range (SID 1018) / 952 +2 : 1740, / error-data-node (SID 1026) / 953 / = timezone-utc-offset (SID 1740) / 954 +3 : "Maximum exceeded" / error-message (SID 1027) / 955 } 956 } 958 CBOR encoding: 960 A1 # map(1) 961 19 0400 # unsigned(1024) 962 A4 # map(4) 963 04 # unsigned(4) 964 19 03F3 # unsigned(1011) 965 01 # unsigned(1) 966 19 03FA # unsigned(1018) 967 02 # unsigned(2) 968 19 06CC # unsigned(1740) 969 03 # unsigned(3) 970 70 # text(16) 971 4D6178696D756D206578636565646564 973 5.2. Names as keys 975 YANG template encoded using names are carried in a CBOR map 976 containing a single item pair. The key of this item is set to the 977 namespace qualified name of the YANG template container, the value is 978 set the CBOR encoding of this container as defined in Section 3.3. 980 This example shows a serialization example of the yang-errors 981 template as defined in [I-D.ietf-core-comi] using names as defined 982 Section 3.3. 984 CBOR diagnostic notation: 986 { 987 "ietf-comi:error" : { 988 "error-tag" : "invalid-value", 989 "error-app-tag" : "not-in-range", 990 "error-data-node" : "timezone-utc-offset", 991 "error-message" : "Maximum exceeded" 992 } 993 } 994 CBOR encoding: 996 A1 # map(1) 997 6F # text(15) 998 696574662D636F6D693A6572726F72 # "ietf-comi:error" 999 A4 # map(4) 1000 69 # text(9) 1001 6572726F722D746167 # "error-tag" 1002 6D # text(13) 1003 696E76616C69642D76616C7565 # "invalid-value" 1004 6D # text(13) 1005 6572726F722D6170702D746167 # "error-app-tag" 1006 6C # text(12) 1007 6E6F742D696E2D72616E6765 # "not-in-range" 1008 6F # text(15) 1009 6572726F722D646174612D6E6F6465 # "error-data-node" 1010 73 # text(19) 1011 74696D657A6F6E652D7574632D6F6666736574 # "timezone-utc-offset" 1012 6D # text(13) 1013 6572726F722D6D657373616765 # "error-message" 1014 70 # text(16) 1015 4D6178696D756D206578636565646564 1017 6. Representing YANG Data Types in CBOR 1019 The CBOR encoding of an instance of a leaf or leaf-list schema node 1020 depends on the built-in type of that schema node. The following sub- 1021 section defined the CBOR encoding of each built-in type supported by 1022 YANG as listed in [RFC7950] section 4.2.4. Each subsection shows an 1023 example value assigned to a schema node instance of the discussed 1024 built-in type. 1026 6.1. The unsigned integer Types 1028 Leafs of type uint8, uint16, uint32 and uint64 MUST be encoded using 1029 a CBOR unsigned integer data item (major type 0). 1031 The following example shows the encoding of a 'mtu' leaf instance set 1032 to 1280 bytes. 1034 Definition example from [RFC7277]: 1036 leaf mtu { 1037 type uint16 { 1038 range "68..max"; 1039 } 1040 } 1041 CBOR diagnostic notation: 1280 1043 CBOR encoding: 19 0500 1045 6.2. The integer Types 1047 Leafs of type int8, int16, int32 and int64 MUST be encoded using 1048 either CBOR unsigned integer (major type 0) or CBOR negative integer 1049 (major type 1), depending on the actual value. 1051 The following example shows the encoding of a 'timezone-utc-offset' 1052 leaf instance set to -300 minutes. 1054 Definition example from [RFC7317]: 1056 leaf timezone-utc-offset { 1057 type int16 { 1058 range "-1500 .. 1500"; 1059 } 1060 } 1062 CBOR diagnostic notation: -300 1064 CBOR encoding: 39 012B 1066 6.3. The 'decimal64' Type 1068 Leafs of type decimal64 MUST be encoded using a decimal fraction as 1069 defined in [RFC7049] section 2.4.3. 1071 The following example shows the encoding of a 'my-decimal' leaf 1072 instance set to 2.57. 1074 Definition example from [RFC7317]: 1076 leaf my-decimal { 1077 type decimal64 { 1078 fraction-digits 2; 1079 range "1 .. 3.14 | 10 | 20..max"; 1080 } 1081 } 1083 CBOR diagnostic notation: 4([-2, 257]) 1085 CBOR encoding: C4 82 21 19 0101 1087 6.4. The 'string' Type 1089 Leafs of type string MUST be encoded using a CBOR text string data 1090 item (major type 3). 1092 The following example shows the encoding of a 'name' leaf instance 1093 set to "eth0". 1095 Definition example from [RFC7223]: 1097 leaf name { 1098 type string; 1099 } 1101 CBOR diagnostic notation: "eth0" 1103 CBOR encoding: 64 65746830 1105 6.5. The 'boolean' Type 1107 Leafs of type boolean MUST be encoded using a CBOR simple value 1108 'true' (major type 7, additional information 21) or 'false' (major 1109 type 7, additional information 20). 1111 The following example shows the encoding of an 'enabled' leaf 1112 instance set to 'true'. 1114 Definition example from [RFC7317]: 1116 leaf enabled { 1117 type boolean; 1118 } 1120 CBOR diagnostic notation: true 1122 CBOR encoding: F5 1124 6.6. The 'enumeration' Type 1126 Leafs of type enumeration MUST be encoded using a CBOR unsigned 1127 integer (major type 0) or CBOR negative integer (major type 1), 1128 depending on the actual value. Enumeration values are either 1129 explicitly assigned using the YANG statement 'value' or automatically 1130 assigned based on the algorithm defined in [RFC7950] section 9.6.4.2. 1132 The following example shows the encoding of an 'oper-status' leaf 1133 instance set to 'testing'. 1135 Definition example from [RFC7317]: 1137 leaf oper-status { 1138 type enumeration { 1139 enum up { value 1; } 1140 enum down { value 2; } 1141 enum testing { value 3; } 1142 enum unknown { value 4; } 1143 enum dormant { value 5; } 1144 enum not-present { value 6; } 1145 enum lower-layer-down { value 7; } 1146 } 1147 } 1149 CBOR diagnostic notation: 3 1151 CBOR encoding: 03 1153 To avoid overlap of 'value' defined in different 'enumeration' 1154 statements, 'enumeration' defined in a Leafs of type 'union' MUST be 1155 encoded using a CBOR text string data item (major type 3) and MUST 1156 contain one of the names assigned by 'enum' statements in YANG. The 1157 encoding MUST be prefixed with the enumeration CBOR tag as specified 1158 in Section 8.1. 1160 Definition example from [RFC7950]: 1162 type union { 1163 type int32; 1164 type enumeration { 1165 enum "unbounded"; 1166 } 1167 } 1169 CBOR diagnostic notation: 99("unbounded") 1171 CBOR encoding: D8 63 69 756E626F756E646564 1173 // RFC Ed.: update 99 and D8 63 with the enumerator CBOR tag 1174 allocated. 1176 6.7. The 'bits' Type 1178 Leafs of type bits MUST be encoded using a CBOR byte string data item 1179 (major type 2). Bits position are either explicitly assigned using 1180 the YANG statement 'position' or automatically assigned based on the 1181 algorithm defined in [RFC7950] section 9.7.4.2. 1183 Bits position 0 to 7 are assigned to the first byte within the byte 1184 string, bits 8 to 15 to the second byte, and subsequent bytes are 1185 assigned similarly. Within each byte, bits are assigned from least 1186 to most significant. 1188 The following example shows the encoding of an 'alarm-state' leaf 1189 instance with the 'under-repair' and 'critical' flags set. 1191 Definition example from [RFC8348]: 1193 typedef alarm-state { 1194 type bits { 1195 bit unknown; 1196 bit under-repair; 1197 bit critical; 1198 bit major; 1199 bit minor; 1200 bit warning; 1201 bit indeterminate; 1202 } 1203 } 1205 leaf alarm-state { 1206 type alarm-state; 1207 } 1209 CBOR diagnostic notation: h'06' 1211 CBOR encoding: 41 06 1213 To avoid overlap of 'bit' defined in different 'bits' statements, 1214 'bits' defined in a Leafs of type 'union' MUST be encoded using a 1215 CBOR text string data item (major type 3) and MUST contain a space- 1216 separated sequence of names of 'bit' that are set. The encoding MUST 1217 be prefixed with the bits CBOR tag as specified in Section 8.1. 1219 The following example shows the encoding of an 'alarm-state' leaf 1220 instance defined using a union type with the 'under-repair' and 1221 'critical' flags set. 1223 Definition example: 1225 leaf alarm-state-2 { 1226 type union { 1227 type alarm-state; 1228 type bits { 1229 bit extra-flag; 1230 } 1231 } 1232 } 1234 CBOR diagnostic notation: 99("under-repair critical") 1236 CBOR encoding: D8 63 75 756E6465722D72657061697220637269746963616C 1238 // RFC Ed.: update 99 and D8 63 with the bits CBOR tag allocated. 1240 6.8. The 'binary' Type 1242 Leafs of type binary MUST be encoded using a CBOR byte string data 1243 item (major type 2). 1245 The following example shows the encoding of an 'aes128-key' leaf 1246 instance set to 0x1f1ce6a3f42660d888d92a4d8030476e. 1248 Definition example: 1250 leaf aes128-key { 1251 type binary { 1252 length 16; 1253 } 1254 } 1256 CBOR diagnostic notation: h'1F1CE6A3F42660D888D92A4D8030476E' 1258 CBOR encoding: 50 1F1CE6A3F42660D888D92A4D8030476E 1260 6.9. The 'leafref' Type 1262 Leafs of type leafref MUST be encoded using the rules of the schema 1263 node referenced by the 'path' YANG statement. 1265 The following example shows the encoding of an 'interface-state-ref' 1266 leaf instance set to "eth1". 1268 Definition example from [RFC7223]: 1270 typedef interface-state-ref { 1271 type leafref { 1272 path "/interfaces-state/interface/name"; 1273 } 1274 } 1276 container interfaces-state { 1277 list interface { 1278 key "name"; 1279 leaf name { 1280 type string; 1281 } 1282 leaf-list higher-layer-if { 1283 type interface-state-ref; 1284 } 1285 } 1286 } 1288 CBOR diagnostic notation: "eth1" 1290 CBOR encoding: 64 65746831 1292 6.10. The 'identityref' Type 1294 This specification supports two approaches for encoding identityref, 1295 a YANG Schema Item iDentifier (SID) as defined in Section 3.2 or a 1296 name as defined in [RFC7951] section 6.8. 1298 6.10.1. SIDs as identityref 1300 When schema nodes of type identityref are implemented using SIDs, 1301 they MUST be encoded using a CBOR unsigned integer data item (major 1302 type 0). (Note that no delta mechanism is employed for SIDs as 1303 identityref.) 1305 The following example shows the encoding of a 'type' leaf instance 1306 set to the value 'iana-if-type:ethernetCsmacd' (SID 1880). 1308 Definition example from [RFC7317]: 1310 identity interface-type { 1311 } 1313 identity iana-interface-type { 1314 base interface-type; 1315 } 1317 identity ethernetCsmacd { 1318 base iana-interface-type; 1319 } 1321 leaf type { 1322 type identityref { 1323 base interface-type; 1324 } 1325 } 1327 CBOR diagnostic notation: 1880 1329 CBOR encoding: 19 0758 1331 6.10.2. Name as identityref 1333 Alternatively, an identityref MAY be encoded using a name as defined 1334 in Section 3.3. When names are used, identityref MUST be encoded 1335 using a CBOR text string data item (major type 3). If the identity 1336 is defined in different module than the leaf node containing the 1337 identityref data node, the namespace qualified form MUST be used. 1338 Otherwise, both the simple and namespace qualified forms are 1339 permitted. Names and namespaces are defined in Section 3.3. 1341 The following example shows the encoding of the identity 'iana-if- 1342 type:ethernetCsmacd' using its namespace qualified name. This 1343 example is described in Section 6.10.1. 1345 CBOR diagnostic notation: "iana-if-type:ethernetCsmacd" 1347 CBOR encoding: 78 1b 1348 69616E612D69662D747970653A65746865726E657443736D616364 1350 6.11. The 'empty' Type 1352 Leafs of type empty MUST be encoded using the CBOR null value (major 1353 type 7, additional information 22). 1355 The following example shows the encoding of a 'is-router' leaf 1356 instance when present. 1358 Definition example from [RFC7277]: 1360 leaf is-router { 1361 type empty; 1362 } 1364 CBOR diagnostic notation: null 1366 CBOR encoding: F6 1368 6.12. The 'union' Type 1370 Leafs of type union MUST be encoded using the rules associated with 1371 one of the types listed. When used in a union, the following YANG 1372 datatypes are prefixed by CBOR tag to avoid confusion between 1373 different YANG datatypes encoded using the same CBOR major type. 1375 o bits 1377 o enumeration 1379 o identityref 1381 o instance-identifier 1383 See Section 8.1 for the assigned value of these CBOR tags. 1385 As mentioned in Section 6.6 and in Section 6.7, 'enumeration' and 1386 'bits' are encoded as CBOR text string data item (major type 3) when 1387 defined within a 'union' type. 1389 The following example shows the encoding of an 'ip-address' leaf 1390 instance when set to "2001:db8:a0b:12f0::1". 1392 Definition example from [RFC7317]: 1394 typedef ipv4-address { 1395 type string { 1396 pattern '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3} 1397 ([0-9][1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])(%[\p{N} 1398 \p{L}]+)?'; 1399 } 1400 } 1402 typedef ipv6-address { 1403 type string { 1404 pattern '((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}((([0-9a 1405 -fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|(((25[0-5]|2[0-4][0 1406 -9]|[01]?[0-9]?[0-9])\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0 1407 -9]?[0-9])))(%[\p{N}\p{L}]+)?'; 1408 pattern '(([^:]+:){6}(([^:]+:[^:]+)|(.*\..*)))|((([^:]+:)*[^:]+) 1409 ?::(([^:]+:)*[^:]+)?)(%.+)?'; 1410 } 1411 } 1413 typedef ip-address { 1414 type union { 1415 type ipv4-address; 1416 type ipv6-address; 1417 } 1418 } 1420 leaf address { 1421 type inet:ip-address; 1422 } 1424 CBOR diagnostic notation: "2001:db8:a0b:12f0::1" 1426 CBOR encoding: 74 323030313A6462383A6130623A313266303A3A31 1428 6.13. The 'instance-identifier' Type 1430 This specification supports two approaches for encoding an instance- 1431 identifier, one based on YANG Schema Item iDentifier (SID) as defined 1432 in Section 3.2 and one based on names as defined in Section 3.3. 1434 6.13.1. SIDs as instance-identifier 1436 SIDs uniquely identify a schema node. In the case of a single 1437 instance schema node, i.e. a schema node defined at the root of a 1438 YANG module or submodule or schema nodes defined within a container, 1439 the SID is sufficient to identify this instance. 1441 In the case of a schema node member of a YANG list, a SID is combined 1442 with the list key(s) to identify each instance within the YANG 1443 list(s). 1445 Single instance schema nodes MUST be encoded using a CBOR unsigned 1446 integer data item (major type 0) and set to the targeted schema node 1447 SID. 1449 Schema nodes member of a YANG list MUST be encoded using a CBOR array 1450 data item (major type 4) containing the following entries: 1452 o The first entry MUST be encoded as a CBOR unsigned integer data 1453 item (major type 0) and set to the targeted schema node SID. 1455 o The following entries MUST contain the value of each key required 1456 to identify the instance of the targeted schema node. These keys 1457 MUST be ordered as defined in the 'key' YANG statement, starting 1458 from top level list, and follow by each of the subordinate 1459 list(s). 1461 Examples within this section assume the definition of a schema node 1462 of type 'instance-identifier': 1464 Definition example from [RFC7950]: 1466 container system { 1467 ... 1468 leaf reporting-entity { 1469 type instance-identifier; 1470 } 1472 leaf contact { type string; } 1474 leaf hostname { type inet:domain-name; } } ~~~~ 1476 *First example:* 1478 The following example shows the encoding of the 'reporting-entity' 1479 value referencing data node instance "/system/contact" (SID 1741). 1481 Definition example from [RFC7317]: 1483 container system { 1485 leaf contact { 1486 type string; 1487 } 1489 leaf hostname { 1490 type inet:domain-name; 1491 } 1492 } 1494 CBOR diagnostic notation: 1741 1496 CBOR encoding: 19 06CD 1498 *Second example:* 1500 The following example shows the encoding of the 'reporting-entity' 1501 value referencing list instance "/system/authentication/user/ 1502 authorized-key/key-data" (SID 1734) for user name "bob" and 1503 authorized-key "admin". 1505 Definition example from [RFC7317]: 1507 list user { 1508 key name; 1510 leaf name { 1511 type string; 1512 } 1513 leaf password { 1514 type ianach:crypt-hash; 1515 } 1517 list authorized-key { 1518 key name; 1520 leaf name { 1521 type string; 1522 } 1523 leaf algorithm { 1524 type string; 1525 } 1526 leaf key-data { 1527 type binary; 1528 } 1529 } 1530 CBOR diagnostic notation: [1734, "bob", "admin"] 1532 CBOR encoding: 1534 83 # array(3) 1535 19 06C6 # unsigned(1734) 1536 63 # text(3) 1537 626F62 # "bob" 1538 65 # text(5) 1539 61646D696E # "admin" 1541 *Third example:* 1543 The following example shows the encoding of the 'reporting-entity' 1544 value referencing the list instance "/system/authentication/user" 1545 (SID 1730) corresponding to user name "jack". 1547 CBOR diagnostic notation: [1730, "jack"] 1549 CBOR encoding: 1551 82 # array(2) 1552 19 06C2 # unsigned(1730) 1553 64 # text(4) 1554 6A61636B # "jack" 1556 6.13.2. Names as instance-identifier 1558 An "instance-identifier" value is encoded as a string that is 1559 analogical to the lexical representation in XML encoding; see 1560 Section 9.13.2 in [RFC7950]. However, the encoding of namespaces in 1561 instance-identifier values follows the rules stated in Section 3.3, 1562 namely: 1564 o The leftmost (top-level) data node name is always in the namespace 1565 qualified form. 1567 o Any subsequent data node name is in the namespace qualified form 1568 if the node is defined in a module other than its parent node, and 1569 the simple form is used otherwise. This rule also holds for node 1570 names appearing in predicates. 1572 For example, 1574 /ietf-interfaces:interfaces/interface[name='eth0']/ietf-ip:ipv4/ip 1575 is a valid instance-identifier value because the data nodes 1576 "interfaces", "interface", and "name" are defined in the module 1577 "ietf-interfaces", whereas "ipv4" and "ip" are defined in "ietf-ip". 1579 The resulting xpath MUST be encoded using a CBOR text string data 1580 item (major type 3). 1582 *First example:* 1584 This example is described in Section 6.13.1. 1586 CBOR diagnostic notation: "/ietf-system:system/contact" 1588 CBOR encoding: 1590 78 1c 2F696574662D73797374656D3A73797374656D2F636F6E74616374 1592 *Second example:* 1594 This example is described in Section 6.13.1. 1596 CBOR diagnostic notation: 1598 "/ietf-system:system/authentication/user[name='bob']/authorized-key 1599 [name='admin']/key-data" 1601 CBOR encoding: 1603 78 59 1604 2F696574662D73797374656D3A73797374656D2F61757468656E74696361 1605 74696F6E2F757365725B6E616D653D27626F62275D2F617574686F72697A 1606 65642D6B65790D0A5B6E616D653D2761646D696E275D2F6B65792D64617461 1608 *Third example:* 1610 This example is described in Section 6.13.1. 1612 CBOR diagnostic notation: 1614 "/ietf-system:system/authentication/user[name='bob']" 1616 CBOR encoding: 1618 78 33 1619 2F696574662D73797374656D3A73797374656D2F61757468656E74696361 1620 74696F6E2F757365725B6E616D653D27626F62275D 1622 7. Security Considerations 1624 The security considerations of [RFC7049] and [RFC7950] apply. 1626 This document defines an alternative encoding for data modeled in the 1627 YANG data modeling language. As such, this encoding does not 1628 contribute any new security issues in addition of those identified 1629 for the specific protocol or context for which it is used. 1631 To minimize security risks, software on the receiving side SHOULD 1632 reject all messages that do not comply to the rules of this document 1633 and reply with an appropriate error message to the sender. 1635 8. IANA Considerations 1637 8.1. Tags Registry 1639 This specification requires the assignment of CBOR tags for the 1640 following YANG datatypes. These tags are added to the Tags Registry 1641 as defined in section 7.2 of [RFC7049]. 1643 +-----+---------------------+---------------------------+-----------+ 1644 | Tag | Data Item | Semantics | Reference | 1645 +-----+---------------------+---------------------------+-----------+ 1646 | xx | SID | YANG Schema Item | RFC XXXX | 1647 | | | iDentifier | | 1648 | xx | bits | YANG bits datatype | RFC XXXX | 1649 | xx | enumeration | YANG enumeration datatype | RFC XXXX | 1650 | xx | identityref | YANG identityref datatype | RFC XXXX | 1651 | xx | instance-identifier | YANG instance-identifier | RFC XXXX | 1652 | | | datatype | | 1653 +-----+---------------------+---------------------------+-----------+ 1655 // RFC Ed.: update Tag values using allocated tags and remove this 1656 note // RFC Ed.: replace XXXX with RFC number and remove this note 1658 9. Acknowledgments 1660 This document has been largely inspired by the extensive works done 1661 by Andy Bierman and Peter van der Stok on [I-D.ietf-core-comi]. 1662 [RFC7951] has also been a critical input to this work. The authors 1663 would like to thank the authors and contributors to these two drafts. 1665 The authors would also like to acknowledge the review, feedback, and 1666 comments from Ladislav Lhotka and Juergen Schoenwaelder. 1668 10. References 1670 10.1. Normative References 1672 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1673 Requirement Levels", BCP 14, RFC 2119, 1674 DOI 10.17487/RFC2119, March 1997, 1675 . 1677 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1678 and A. Bierman, Ed., "Network Configuration Protocol 1679 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1680 . 1682 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1683 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1684 October 2013, . 1686 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1687 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1688 . 1690 10.2. Informative References 1692 [I-D.ietf-core-comi] 1693 Veillette, M., Stok, P., Pelov, A., and A. Bierman, "CoAP 1694 Management Interface", draft-ietf-core-comi-04 (work in 1695 progress), November 2018. 1697 [I-D.ietf-core-sid] 1698 Veillette, M., Pelov, A., and I. Petrov, "YANG Schema Item 1699 iDentifier (SID)", draft-ietf-core-sid-06 (work in 1700 progress), March 2019. 1702 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1703 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1704 2014, . 1706 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1707 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1708 . 1710 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1711 Constrained-Node Networks", RFC 7228, 1712 DOI 10.17487/RFC7228, May 2014, 1713 . 1715 [RFC7277] Bjorklund, M., "A YANG Data Model for IP Management", 1716 RFC 7277, DOI 10.17487/RFC7277, June 2014, 1717 . 1719 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1720 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1721 2014, . 1723 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 1724 RFC 7951, DOI 10.17487/RFC7951, August 2016, 1725 . 1727 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1728 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1729 . 1731 [RFC8348] Bierman, A., Bjorklund, M., Dong, J., and D. Romascanu, "A 1732 YANG Data Model for Hardware Management", RFC 8348, 1733 DOI 10.17487/RFC8348, March 2018, 1734 . 1736 Authors' Addresses 1738 Michel Veillette (editor) 1739 Trilliant Networks Inc. 1740 610 Rue du Luxembourg 1741 Granby, Quebec J2J 2V2 1742 Canada 1744 Email: michel.veillette@trilliantinc.com 1746 Ivaylo Petrov (editor) 1747 Acklio 1748 1137A avenue des Champs Blancs 1749 Cesson-Sevigne, Bretagne 35510 1750 France 1752 Email: ivaylo@ackl.io 1754 Alexander Pelov 1755 Acklio 1756 1137A avenue des Champs Blancs 1757 Cesson-Sevigne, Bretagne 35510 1758 France 1760 Email: a@ackl.io