idnits 2.17.1 draft-ietf-core-yang-cbor-10.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 08, 2019) is 1817 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 1079, but not defined -- Looks like a reference, but probably isn't: '257' on line 1079 == Missing Reference: '0-9' is mentioned on line 1396, but not defined == Missing Reference: '1-9' is mentioned on line 1387, but not defined == Missing Reference: '0-4' is mentioned on line 1396, but not defined == Missing Reference: '0-5' is mentioned on line 1396, but not defined == Missing Reference: '0-9a-fA-F' is mentioned on line 1395, but not defined -- Looks like a reference, but probably isn't: '01' on line 1396 ** 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 10, 2019 A. Pelov 6 Acklio 7 April 08, 2019 9 CBOR Encoding of Data Modeled with YANG 10 draft-ietf-core-yang-cbor-10 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 10, 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 . . . . . . . . . . . . . . . . . . . . . . . 40 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 42. 428 Delta values are computed as follows: 430 o In the case of a 'container', deltas are equal to the SID of the 431 current schema node minus the SID of the parent 'container'. 433 o In the case of a 'list', deltas are equal to the SID of the 434 current schema node minus the SID of the parent 'list'. 436 o In the case of an 'rpc input' or 'rcp output', deltas are equal to 437 the SID of the current schema node minus the SID of the 'rpc'. 439 o In the case of an 'action input' or 'action output', deltas are 440 equal to the SID of the current schema node minus the SID of the 441 'action'. 443 o In the case of an 'notification content', deltas are equal to the 444 SID of the current schema node minus the SID of the 445 'notification'. 447 This example assumes that the Media Type used to carry this container 448 consists of a CBOR map composed of the data node SID and data node 449 encoding. This root CBOR map is not part of the present encoding 450 rules and is not compulsory. 452 CBOR diagnostic notation: 454 { 455 1720 : { / system-state / 456 +1 : { / clock (SID 1721) / 457 +2 : "2015-10-02T14:47:24Z-05:00",/ current-datetime (SID 1723) / 458 +1 : "2015-09-15T09:12:58Z-05:00" / boot-datetime (SID 1722) / 459 } 460 } 461 } 463 CBOR encoding: 465 A1 # map(1) 466 19 06B8 # unsigned(1720) 467 A1 # map(1) 468 01 # unsigned(1) 469 A2 # map(2) 470 02 # unsigned(2) 471 78 1A # text(26) 472 323031352D31302D30325431343A34373A32345A2D30353A3030 473 01 # unsigned(1) 474 78 1A # text(26) 475 323031352D30392D31355430393A31323A35385A2D30353A3030 477 4.2.2. Names as keys 479 CBOR map keys implemented using names MUST be encoded using a CBOR 480 text string data item (major type 3). A namespace-qualified name 481 MUST be used each time the namespace of a schema node and its parent 482 differ. In all other cases, the simple form of the name MUST be 483 used. Names and namespaces are defined in [RFC7951] section 4. 485 The following example shows the encoding of a 'system' container 486 instance using names. 488 Definition example from [RFC7317]: 490 typedef date-and-time { 491 type string { 492 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[\+\-] 493 \d{2}:\d{2})'; 494 } 495 } 497 container system-state { 499 container clock { 500 leaf current-datetime { 501 type date-and-time; 502 } 504 leaf boot-datetime { 505 type date-and-time; 506 } 507 } 508 } 510 This example assumes that the Media Type used to carry this container 511 consists of a CBOR map composed of the data node namespace qualified 512 name and data node encoding. This root CBOR map is not part of the 513 present encoding rules and is not compulsory. 515 CBOR diagnostic notation: 517 { 518 "ietf-system:system-state" : { 519 "ietf-system:clock" : { 520 "current-datetime" : "2015-10-02T14:47:24Z-05:00", 521 "boot-datetime" : "2015-09-15T09:12:58Z-05:00" 522 } 523 } 524 } 526 CBOR encoding: 528 A1 # map(1) 529 78 18 # text(24) 530 696574662D73797374656D3A73797374656D2D7374617465 531 A1 # map(1) 532 71 # text(17) 533 696574662D73797374656D3A636C6F636B 534 A2 # map(2) 535 70 # text(16) 536 63757272656E742D6461746574696D65 537 78 1A # text(26) 538 323031352D31302D30325431343A34373A32345A2D30353A3030 539 6D # text(13) 540 626F6F742D6461746574696D65 541 78 1A # text(26) 542 323031352D30392D31355430393A31323A35385A2D30353A3030 544 4.3. The 'leaf-list' 546 A leaf-list MUST be encoded using a CBOR array data item (major type 547 4). Each entry of this array MUST be encoded accordingly to its 548 datatype using one of the encoding rules specified in Section 6. 550 The following example shows the encoding of the 'search' leaf-list 551 instance containing two entries, "ietf.org" and "ieee.org". 553 Definition example [RFC7317]: 555 typedef domain-name { 556 type string { 557 length "1..253"; 558 pattern '((([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9].) 559 *([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.? 560 )|\.'; 561 } 562 } 564 leaf-list search { 565 type domain-name; 566 ordered-by user; 567 } 569 CBOR diagnostic notation: [ "ietf.org", "ieee.org" ] 571 CBOR encoding: 82 68 696574662E6F7267 68 696565652E6F7267 573 4.4. The 'list' and 'list' instance(s) 575 A list or a subset of a list MUST be encoded using a CBOR array data 576 item (major type 4). Each list instance within this CBOR array is 577 encoded using a CBOR map data item (major type 5) based on the 578 encoding rules of a collection as defined in Section 4.2. 580 It is important to note that this encoding rule also apply to a 581 single 'list' instance. 583 The following examples show the encoding of a 'server' list using 584 SIDs or names. 586 Definition example from [RFC7317]: 588 list server { 589 key name; 591 leaf name { 592 type string; 593 } 594 choice transport { 595 case udp { 596 container udp { 597 leaf address { 598 type host; 599 mandatory true; 600 } 601 leaf port { 602 type port-number; 603 } 604 } 605 } 606 } 607 leaf association-type { 608 type enumeration { 609 enum server; 610 enum peer; 611 enum pool; 612 } 613 default server; 614 } 615 leaf iburst { 616 type boolean; 617 default false; 618 } 619 leaf prefer { 620 type boolean; 621 default false; 622 } 623 } 625 4.4.1. SIDs as keys 627 The encoding rules of each 'list' instance are defined in 628 Section 4.2.1. Deltas of list members are equal to the SID of the 629 current schema node minus the SID of the 'list'. 631 This example assumes that the Media Type used to carry this list 632 consists of a CBOR map composed of the data node SID and data node 633 encoding. This root CBOR map is not part of the present encoding 634 rules and is not compulsory. 636 CBOR diagnostic notation: 638 { 639 1756 : [ / server (SID 1756) / 640 { 641 +3 : "NRC TIC server", / name (SID 1759) / 642 +5 : { / udp (SID 1761) / 643 +1 : "tic.nrc.ca", / address (SID 1762) / 644 +2 : 123 / port (SID 1763) / 645 }, 646 +1 : 0, / association-type (SID 1757) / 647 +2 : false, / iburst (SID 1758) / 648 +4 : true / prefer (SID 1760) / 649 }, 650 { 651 +3 : "NRC TAC server", / name (SID 1759) / 652 +5 : { / udp (SID 1761) / 653 +1 : "tac.nrc.ca" / address (SID 1762) / 654 } 655 } 656 ] 657 } 659 CBOR encoding: 661 A1 # map(1) 662 19 06DC # unsigned(1756) 663 82 # array(2) 664 A5 # map(5) 665 03 # unsigned(3) 666 6E # text(14) 667 4E52432054494320736572766572 # "NRC TIC server" 668 05 # unsigned(5) 669 A2 # map(2) 670 01 # unsigned(1) 671 6A # text(10) 672 7469632E6E72632E6361 # "tic.nrc.ca" 673 02 # unsigned(2) 674 18 7B # unsigned(123) 675 01 # unsigned(1) 676 00 # unsigned(0) 677 02 # unsigned(2) 678 F4 # primitive(20) 679 04 # unsigned(4) 680 F5 # primitive(21) 681 A2 # map(2) 682 03 # unsigned(3) 683 6E # text(14) 684 4E52432054414320736572766572 # "NRC TAC server" 685 05 # unsigned(5) 686 A1 # map(1) 687 01 # unsigned(1) 688 6A # text(10) 689 7461632E6E72632E6361 # "tac.nrc.ca" 691 4.4.2. Names as keys 693 The encoding rules of each 'list' instance are defined in 694 Section 4.2.2. 696 This example assumes that the Media Type used to carry this container 697 consists of a CBOR map composed of the data node namespace qualified 698 name and data node encoding. This root CBOR map is not part of the 699 present encoding rules and is not compulsory. 701 CBOR diagnostic notation: 703 { 704 "ietf-system:server" : [ 705 { 706 "name" : "NRC TIC server", 707 "udp" : { 708 "address" : "tic.nrc.ca", 709 "port" : 123 710 }, 711 "association-type" : 0, 712 "iburst" : false, 713 "prefer" : true 714 }, 715 { 716 "name" : "NRC TAC server", 717 "udp" : { 718 "address" : "tac.nrc.ca" 719 } 720 } 721 ] 722 } 724 CBOR encoding: 726 A1 # map(1) 727 72 # text(18) 728 696574662D73797374656D3A736572766572 729 82 # array(2) 730 A5 # map(5) 731 64 # text(4) 732 6E616D65 # "name" 733 6E # text(14) 734 4E52432054494320736572766572 735 63 # text(3) 736 756470 # "udp" 737 A2 # map(2) 738 67 # text(7) 739 61646472657373 # "address" 740 6A # text(10) 741 7469632E6E72632E6361 # "tic.nrc.ca" 742 64 # text(4) 743 706F7274 # "port" 744 18 7B # unsigned(123) 745 70 # text(16) 746 6173736F63696174696F6E2D74797065 747 00 # unsigned(0) 748 66 # text(6) 749 696275727374 # "iburst" 750 F4 # primitive(20) 751 66 # text(6) 752 707265666572 # "prefer" 753 F5 # primitive(21) 754 A2 # map(2) 755 64 # text(4) 756 6E616D65 # "name" 757 6E # text(14) 758 4E52432054414320736572766572 759 63 # text(3) 760 756470 # "udp" 761 A1 # map(1) 762 67 # text(7) 763 61646472657373 # "address" 764 6A # text(10) 765 7461632E6E72632E6361 # "tac.nrc.ca" 767 4.5. The 'anydata' 769 An anydata serves as a container for an arbitrary set of schema nodes 770 that otherwise appear as normal YANG-modeled data. An anydata 771 instance is encoded using the same rules as a container, i.e., CBOR 772 map. The requirement that anydata content can be modeled by YANG 773 implies the following: 775 o CBOR map keys of any inner schema nodes MUST be set to valid 776 deltas or names. 778 o The CBOR array MUST contain either unique scalar values (as a 779 leaf-list, see Section 4.3), or maps (as a list, see Section 4.4). 781 o CBOR map values MUST follow the encoding rules of one of the 782 datatypes listed in Section 4. 784 The following example shows a possible use of an anydata. In this 785 example, an anydata is used to define a schema node containing a 786 notification event, this schema node can be part of a YANG list to 787 create an event logger. 789 Definition example: 791 module event-log { 792 ... 793 anydata last-event; # SID 60123 795 This example also assumes the assistance of the following 796 notification. 798 module example-port { 799 ... 801 notification example-port-fault { # SID 60200 802 leaf port-name { # SID 60201 803 type string; 804 } 805 leaf port-fault { # SID 60202 806 type string; 807 } 808 } 809 } 811 This example assumes that the Media Type used to carry this anydata 812 consists of a CBOR map composed of the data node SID and data node 813 encoding. This root CBOR map is not part of the present encoding 814 rules and is not compulsory. 816 CBOR diagnostic notation: 818 { 819 60123 : { / last-event (SID=60123) / 820 +77 : { / event (SID=60200) / 821 +1 : "0/4/21", / port-name (SID=60201) / 822 +2 : "Open pin 2" / port-fault (SID=60202) / 823 } 824 } 825 } 827 CBOR encoding: 829 A1 # map(1) 830 19 EADB # unsigned(60123) 831 A1 # map(1) 832 18 4D # unsigned(77) 833 A2 # map(2) 834 18 4E # unsigned(78) 835 66 # text(6) 836 302F342F3231 # "0/4/21" 837 18 4F # unsigned(79) 838 6A # text(10) 839 4F70656E2070696E2032 # "Open pin 2" 841 In some implementations, it might be simpler to use the absolute SID 842 tag encoding for the anydata root element. The resulting encoding is 843 as follow: 845 { 846 60123 : { / last-event (SID=60123) / 847 42(60200) : { / event (SID=60123) / 848 +1 : "0/4/21", / port-name (SID=60201) / 849 +2 : "Open pin 2" / port-fault (SID=60202) / 850 } 851 } 852 } 854 4.6. The 'anyxml' 856 An anyxml schema node is used to serialize an arbitrary CBOR content, 857 i.e., its value can be any CBOR binary object. anyxml value MAY 858 contain CBOR data items tagged with one of the tag listed in 859 Section 8.1, these tags shall be supported. 861 The following example shows a valid CBOR encoded instance consisting 862 of a CBOR array containing the CBOR simple values 'true', 'null' and 863 'true'. 865 Definition example from [RFC7951]: 867 anyxml bar; 869 Note: This example assumes that the Media Type used to carry this 870 anyxml consists of a CBOR map composed of the data node SID and data 871 node encoding. This root CBOR map is not part of the present 872 encoding rules and is not compulsory. 874 CBOR diagnostic notation: 876 { 877 60000 : [true, null, true] / bar (SID 60000) / 878 } 880 CBOR encoding: 882 A1 # map(1) 883 19 EA60 # unsigned(60000) 884 83 # array(3) 885 F5 # primitive(21) 886 F6 # primitive(22) 887 F5 # primitive(21) 889 5. Encoding of YANG data templates 891 YANG data templates are data structures defined in YANG but not 892 intended to be implemented as part of a datastore. YANG data 893 templates are defined using the 'yang-data' extension as described by 894 RFC 8040. 896 YANG data templates SHOULD be encoded using the encoding rules of a 897 collection as defined in Section 4.2. 899 Just like YANG containers, YANG data templates can be encoded using 900 either SIDs or names. 902 Definition example from [I-D.ietf-core-comi]: 904 import ietf-restconf { 905 prefix rc; 906 } 908 rc:yang-data yang-errors { 909 container error { 910 leaf error-tag { 911 type identityref { 912 base error-tag; 913 } 914 } 915 leaf error-app-tag { 916 type identityref { 917 base error-app-tag; 918 } 919 } 920 leaf error-data-node { 921 type instance-identifier; 922 } 923 leaf error-message { 924 type string; 925 } 926 } 927 } 929 5.1. SIDs as keys 931 YANG template encoded using SIDs are carried in a CBOR map containing 932 a single item pair. The key of this item is set to the SID assigned 933 to the YANG template container, the value is set the CBOR encoding of 934 this container as defined in Section 4.2. 936 This example shows a serialization example of the yang-errors 937 template as defined in [I-D.ietf-core-comi] using SIDs as defined in 938 Section 3.2. 940 CBOR diagnostic notation: 942 { 943 1024 : { / error (SID 1024) / 944 +4 : 1011, / error-tag (SID 1028) / 945 / = invalid-value (SID 1011) / 946 +1 : 1018, / error-app-tag (SID 1025) / 947 / = not-in-range (SID 1018) / 948 +2 : 1740, / error-data-node (SID 1026) / 949 / = timezone-utc-offset (SID 1740) / 950 +3 : "Maximum exceeded" / error-message (SID 1027) / 951 } 952 } 954 CBOR encoding: 956 A1 # map(1) 957 19 0400 # unsigned(1024) 958 A4 # map(4) 959 04 # unsigned(4) 960 19 03F3 # unsigned(1011) 961 01 # unsigned(1) 962 19 03FA # unsigned(1018) 963 02 # unsigned(2) 964 19 06CC # unsigned(1740) 965 03 # unsigned(3) 966 70 # text(16) 967 4D6178696D756D206578636565646564 969 5.2. Names as keys 971 YANG template encoded using names are carried in a CBOR map 972 containing a single item pair. The key of this item is set to the 973 namespace qualified name of the YANG template container, the value is 974 set the CBOR encoding of this container as defined in Section 3.3. 976 This example shows a serialization example of the yang-errors 977 template as defined in [I-D.ietf-core-comi] using names as defined 978 Section 3.3. 980 CBOR diagnostic notation: 982 { 983 "ietf-comi:error" : { 984 "error-tag" : "invalid-value", 985 "error-app-tag" : "not-in-range", 986 "error-data-node" : "timezone-utc-offset", 987 "error-message" : "Maximum exceeded" 988 } 989 } 990 CBOR encoding: 992 A1 # map(1) 993 6F # text(15) 994 696574662D636F6D693A6572726F72 # "ietf-comi:error" 995 A4 # map(4) 996 69 # text(9) 997 6572726F722D746167 # "error-tag" 998 6D # text(13) 999 696E76616C69642D76616C7565 # "invalid-value" 1000 6D # text(13) 1001 6572726F722D6170702D746167 # "error-app-tag" 1002 6C # text(12) 1003 6E6F742D696E2D72616E6765 # "not-in-range" 1004 6F # text(15) 1005 6572726F722D646174612D6E6F6465 # "error-data-node" 1006 73 # text(19) 1007 74696D657A6F6E652D7574632D6F6666736574 # "timezone-utc-offset" 1008 6D # text(13) 1009 6572726F722D6D657373616765 # "error-message" 1010 70 # text(16) 1011 4D6178696D756D206578636565646564 1013 6. Representing YANG Data Types in CBOR 1015 The CBOR encoding of an instance of a leaf or leaf-list schema node 1016 depends on the built-in type of that schema node. The following sub- 1017 section defined the CBOR encoding of each built-in type supported by 1018 YANG as listed in [RFC7950] section 4.2.4. Each subsection shows an 1019 example value assigned to a schema node instance of the discussed 1020 built-in type. 1022 6.1. The unsigned integer Types 1024 Leafs of type uint8, uint16, uint32 and uint64 MUST be encoded using 1025 a CBOR unsigned integer data item (major type 0). 1027 The following example shows the encoding of a 'mtu' leaf instance set 1028 to 1280 bytes. 1030 Definition example from [RFC7277]: 1032 leaf mtu { 1033 type uint16 { 1034 range "68..max"; 1035 } 1036 } 1037 CBOR diagnostic notation: 1280 1039 CBOR encoding: 19 0500 1041 6.2. The integer Types 1043 Leafs of type int8, int16, int32 and int64 MUST be encoded using 1044 either CBOR unsigned integer (major type 0) or CBOR negative integer 1045 (major type 1), depending on the actual value. 1047 The following example shows the encoding of a 'timezone-utc-offset' 1048 leaf instance set to -300 minutes. 1050 Definition example from [RFC7317]: 1052 leaf timezone-utc-offset { 1053 type int16 { 1054 range "-1500 .. 1500"; 1055 } 1056 } 1058 CBOR diagnostic notation: -300 1060 CBOR encoding: 39 012B 1062 6.3. The 'decimal64' Type 1064 Leafs of type decimal64 MUST be encoded using a decimal fraction as 1065 defined in [RFC7049] section 2.4.3. 1067 The following example shows the encoding of a 'my-decimal' leaf 1068 instance set to 2.57. 1070 Definition example from [RFC7317]: 1072 leaf my-decimal { 1073 type decimal64 { 1074 fraction-digits 2; 1075 range "1 .. 3.14 | 10 | 20..max"; 1076 } 1077 } 1079 CBOR diagnostic notation: 4([-2, 257]) 1081 CBOR encoding: C4 82 21 19 0101 1083 6.4. The 'string' Type 1085 Leafs of type string MUST be encoded using a CBOR text string data 1086 item (major type 3). 1088 The following example shows the encoding of a 'name' leaf instance 1089 set to "eth0". 1091 Definition example from [RFC7223]: 1093 leaf name { 1094 type string; 1095 } 1097 CBOR diagnostic notation: "eth0" 1099 CBOR encoding: 64 65746830 1101 6.5. The 'boolean' Type 1103 Leafs of type boolean MUST be encoded using a CBOR simple value 1104 'true' (major type 7, additional information 21) or 'false' (major 1105 type 7, additional information 20). 1107 The following example shows the encoding of an 'enabled' leaf 1108 instance set to 'true'. 1110 Definition example from [RFC7317]: 1112 leaf enabled { 1113 type boolean; 1114 } 1116 CBOR diagnostic notation: true 1118 CBOR encoding: F5 1120 6.6. The 'enumeration' Type 1122 Leafs of type enumeration MUST be encoded using a CBOR unsigned 1123 integer (major type 0) or CBOR negative integer (major type 1), 1124 depending on the actual value. Enumeration values are either 1125 explicitly assigned using the YANG statement 'value' or automatically 1126 assigned based on the algorithm defined in [RFC7950] section 9.6.4.2. 1128 The following example shows the encoding of an 'oper-status' leaf 1129 instance set to 'testing'. 1131 Definition example from [RFC7317]: 1133 leaf oper-status { 1134 type enumeration { 1135 enum up { value 1; } 1136 enum down { value 2; } 1137 enum testing { value 3; } 1138 enum unknown { value 4; } 1139 enum dormant { value 5; } 1140 enum not-present { value 6; } 1141 enum lower-layer-down { value 7; } 1142 } 1143 } 1145 CBOR diagnostic notation: 3 1147 CBOR encoding: 03 1149 To avoid overlap of 'value' defined in different 'enumeration' 1150 statements, 'enumeration' defined in a Leafs of type 'union' MUST be 1151 encoded using a CBOR text string data item (major type 3) and MUST 1152 contain one of the names assigned by 'enum' statements in YANG. The 1153 encoding MUST be prefixed with the enumeration CBOR tag as specified 1154 in Section 8.1. 1156 Definition example from [RFC7950]: 1158 type union { 1159 type int32; 1160 type enumeration { 1161 enum "unbounded"; 1162 } 1163 } 1165 CBOR diagnostic notation: 44("unbounded") 1167 CBOR encoding: D8 2C 69 756E626F756E646564 1169 6.7. The 'bits' Type 1171 Leafs of type bits MUST be encoded using a CBOR byte string data item 1172 (major type 2). Bits position are either explicitly assigned using 1173 the YANG statement 'position' or automatically assigned based on the 1174 algorithm defined in [RFC7950] section 9.7.4.2. 1176 Bits position 0 to 7 are assigned to the first byte within the byte 1177 string, bits 8 to 15 to the second byte, and subsequent bytes are 1178 assigned similarly. Within each byte, bits are assigned from least 1179 to most significant. 1181 The following example shows the encoding of an 'alarm-state' leaf 1182 instance with the 'under-repair' and 'critical' flags set. 1184 Definition example from [RFC8348]: 1186 typedef alarm-state { 1187 type bits { 1188 bit unknown; 1189 bit under-repair; 1190 bit critical; 1191 bit major; 1192 bit minor; 1193 bit warning; 1194 bit indeterminate; 1195 } 1196 } 1198 leaf alarm-state { 1199 type alarm-state; 1200 } 1202 CBOR diagnostic notation: h'06' 1204 CBOR encoding: 41 06 1206 To avoid overlap of 'bit' defined in different 'bits' statements, 1207 'bits' defined in a Leafs of type 'union' MUST be encoded using a 1208 CBOR text string data item (major type 3) and MUST contain a space- 1209 separated sequence of names of 'bit' that are set. The encoding MUST 1210 be prefixed with the bits CBOR tag as specified in Section 8.1. 1212 The following example shows the encoding of an 'alarm-state' leaf 1213 instance defined using a union type with the 'under-repair' and 1214 'critical' flags set. 1216 Definition example: 1218 leaf alarm-state-2 { 1219 type union { 1220 type alarm-state; 1221 type bits { 1222 bit extra-flag; 1223 } 1224 } 1225 } 1226 CBOR diagnostic notation: 43("under-repair critical") 1228 CBOR encoding: D8 2B 75 756E6465722D72657061697220637269746963616C 1230 6.8. The 'binary' Type 1232 Leafs of type binary MUST be encoded using a CBOR byte string data 1233 item (major type 2). 1235 The following example shows the encoding of an 'aes128-key' leaf 1236 instance set to 0x1f1ce6a3f42660d888d92a4d8030476e. 1238 Definition example: 1240 leaf aes128-key { 1241 type binary { 1242 length 16; 1243 } 1244 } 1246 CBOR diagnostic notation: h'1F1CE6A3F42660D888D92A4D8030476E' 1248 CBOR encoding: 50 1F1CE6A3F42660D888D92A4D8030476E 1250 6.9. The 'leafref' Type 1252 Leafs of type leafref MUST be encoded using the rules of the schema 1253 node referenced by the 'path' YANG statement. 1255 The following example shows the encoding of an 'interface-state-ref' 1256 leaf instance set to "eth1". 1258 Definition example from [RFC7223]: 1260 typedef interface-state-ref { 1261 type leafref { 1262 path "/interfaces-state/interface/name"; 1263 } 1264 } 1266 container interfaces-state { 1267 list interface { 1268 key "name"; 1269 leaf name { 1270 type string; 1271 } 1272 leaf-list higher-layer-if { 1273 type interface-state-ref; 1274 } 1275 } 1276 } 1278 CBOR diagnostic notation: "eth1" 1280 CBOR encoding: 64 65746831 1282 6.10. The 'identityref' Type 1284 This specification supports two approaches for encoding identityref, 1285 a YANG Schema Item iDentifier (SID) as defined in Section 3.2 or a 1286 name as defined in [RFC7951] section 6.8. 1288 6.10.1. SIDs as identityref 1290 When schema nodes of type identityref are implemented using SIDs, 1291 they MUST be encoded using a CBOR unsigned integer data item (major 1292 type 0). (Note that no delta mechanism is employed for SIDs as 1293 identityref.) 1295 The following example shows the encoding of a 'type' leaf instance 1296 set to the value 'iana-if-type:ethernetCsmacd' (SID 1880). 1298 Definition example from [RFC7317]: 1300 identity interface-type { 1301 } 1303 identity iana-interface-type { 1304 base interface-type; 1305 } 1307 identity ethernetCsmacd { 1308 base iana-interface-type; 1309 } 1311 leaf type { 1312 type identityref { 1313 base interface-type; 1314 } 1315 } 1317 CBOR diagnostic notation: 1880 1319 CBOR encoding: 19 0758 1321 6.10.2. Name as identityref 1323 Alternatively, an identityref MAY be encoded using a name as defined 1324 in Section 3.3. When names are used, identityref MUST be encoded 1325 using a CBOR text string data item (major type 3). If the identity 1326 is defined in different module than the leaf node containing the 1327 identityref data node, the namespace qualified form MUST be used. 1328 Otherwise, both the simple and namespace qualified forms are 1329 permitted. Names and namespaces are defined in Section 3.3. 1331 The following example shows the encoding of the identity 'iana-if- 1332 type:ethernetCsmacd' using its namespace qualified name. This 1333 example is described in Section 6.10.1. 1335 CBOR diagnostic notation: "iana-if-type:ethernetCsmacd" 1337 CBOR encoding: 78 1b 1338 69616E612D69662D747970653A65746865726E657443736D616364 1340 6.11. The 'empty' Type 1342 Leafs of type empty MUST be encoded using the CBOR null value (major 1343 type 7, additional information 22). 1345 The following example shows the encoding of a 'is-router' leaf 1346 instance when present. 1348 Definition example from [RFC7277]: 1350 leaf is-router { 1351 type empty; 1352 } 1354 CBOR diagnostic notation: null 1356 CBOR encoding: F6 1358 6.12. The 'union' Type 1360 Leafs of type union MUST be encoded using the rules associated with 1361 one of the types listed. When used in a union, the following YANG 1362 datatypes are prefixed by CBOR tag to avoid confusion between 1363 different YANG datatypes encoded using the same CBOR major type. 1365 o bits 1367 o enumeration 1369 o identityref 1371 o instance-identifier 1373 See Section 8.1 for the assigned value of these CBOR tags. 1375 As mentioned in Section 6.6 and in Section 6.7, 'enumeration' and 1376 'bits' are encoded as CBOR text string data item (major type 3) when 1377 defined within a 'union' type. 1379 The following example shows the encoding of an 'ip-address' leaf 1380 instance when set to "2001:db8:a0b:12f0::1". 1382 Definition example from [RFC7317]: 1384 typedef ipv4-address { 1385 type string { 1386 pattern '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3} 1387 ([0-9][1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])(%[\p{N} 1388 \p{L}]+)?'; 1389 } 1390 } 1392 typedef ipv6-address { 1393 type string { 1394 pattern '((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}((([0-9a 1395 -fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|(((25[0-5]|2[0-4][0 1396 -9]|[01]?[0-9]?[0-9])\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0 1397 -9]?[0-9])))(%[\p{N}\p{L}]+)?'; 1398 pattern '(([^:]+:){6}(([^:]+:[^:]+)|(.*\..*)))|((([^:]+:)*[^:]+) 1399 ?::(([^:]+:)*[^:]+)?)(%.+)?'; 1400 } 1401 } 1403 typedef ip-address { 1404 type union { 1405 type ipv4-address; 1406 type ipv6-address; 1407 } 1408 } 1410 leaf address { 1411 type inet:ip-address; 1412 } 1414 CBOR diagnostic notation: "2001:db8:a0b:12f0::1" 1416 CBOR encoding: 74 323030313A6462383A6130623A313266303A3A31 1418 6.13. The 'instance-identifier' Type 1420 This specification supports two approaches for encoding an instance- 1421 identifier, one based on YANG Schema Item iDentifier (SID) as defined 1422 in Section 3.2 and one based on names as defined in Section 3.3. 1424 6.13.1. SIDs as instance-identifier 1426 SIDs uniquely identify a schema node. In the case of a single 1427 instance schema node, i.e. a schema node defined at the root of a 1428 YANG module or submodule or schema nodes defined within a container, 1429 the SID is sufficient to identify this instance. 1431 In the case of a schema node member of a YANG list, a SID is combined 1432 with the list key(s) to identify each instance within the YANG 1433 list(s). 1435 Single instance schema nodes MUST be encoded using a CBOR unsigned 1436 integer data item (major type 0) and set to the targeted schema node 1437 SID. 1439 Schema nodes member of a YANG list MUST be encoded using a CBOR array 1440 data item (major type 4) containing the following entries: 1442 o The first entry MUST be encoded as a CBOR unsigned integer data 1443 item (major type 0) and set to the targeted schema node SID. 1445 o The following entries MUST contain the value of each key required 1446 to identify the instance of the targeted schema node. These keys 1447 MUST be ordered as defined in the 'key' YANG statement, starting 1448 from top level list, and follow by each of the subordinate 1449 list(s). 1451 Examples within this section assume the definition of a schema node 1452 of type 'instance-identifier': 1454 Definition example from [RFC7950]: 1456 container system { 1457 ... 1458 leaf reporting-entity { 1459 type instance-identifier; 1460 } 1462 leaf contact { type string; } 1464 leaf hostname { type inet:domain-name; } } ~~~~ 1466 *First example:* 1468 The following example shows the encoding of the 'reporting-entity' 1469 value referencing data node instance "/system/contact" (SID 1741). 1471 Definition example from [RFC7317]: 1473 container system { 1475 leaf contact { 1476 type string; 1477 } 1479 leaf hostname { 1480 type inet:domain-name; 1481 } 1482 } 1484 CBOR diagnostic notation: 1741 1486 CBOR encoding: 19 06CD 1488 *Second example:* 1490 The following example shows the encoding of the 'reporting-entity' 1491 value referencing list instance "/system/authentication/user/ 1492 authorized-key/key-data" (SID 1734) for user name "bob" and 1493 authorized-key "admin". 1495 Definition example from [RFC7317]: 1497 list user { 1498 key name; 1500 leaf name { 1501 type string; 1502 } 1503 leaf password { 1504 type ianach:crypt-hash; 1505 } 1507 list authorized-key { 1508 key name; 1510 leaf name { 1511 type string; 1512 } 1513 leaf algorithm { 1514 type string; 1515 } 1516 leaf key-data { 1517 type binary; 1518 } 1519 } 1520 CBOR diagnostic notation: [1734, "bob", "admin"] 1522 CBOR encoding: 1524 83 # array(3) 1525 19 06C6 # unsigned(1734) 1526 63 # text(3) 1527 626F62 # "bob" 1528 65 # text(5) 1529 61646D696E # "admin" 1531 *Third example:* 1533 The following example shows the encoding of the 'reporting-entity' 1534 value referencing the list instance "/system/authentication/user" 1535 (SID 1730) corresponding to user name "jack". 1537 CBOR diagnostic notation: [1730, "jack"] 1539 CBOR encoding: 1541 82 # array(2) 1542 19 06C2 # unsigned(1730) 1543 64 # text(4) 1544 6A61636B # "jack" 1546 6.13.2. Names as instance-identifier 1548 An "instance-identifier" value is encoded as a string that is 1549 analogical to the lexical representation in XML encoding; see 1550 Section 9.13.2 in [RFC7950]. However, the encoding of namespaces in 1551 instance-identifier values follows the rules stated in Section 3.3, 1552 namely: 1554 o The leftmost (top-level) data node name is always in the namespace 1555 qualified form. 1557 o Any subsequent data node name is in the namespace qualified form 1558 if the node is defined in a module other than its parent node, and 1559 the simple form is used otherwise. This rule also holds for node 1560 names appearing in predicates. 1562 For example, 1564 /ietf-interfaces:interfaces/interface[name='eth0']/ietf-ip:ipv4/ip 1565 is a valid instance-identifier value because the data nodes 1566 "interfaces", "interface", and "name" are defined in the module 1567 "ietf-interfaces", whereas "ipv4" and "ip" are defined in "ietf-ip". 1569 The resulting xpath MUST be encoded using a CBOR text string data 1570 item (major type 3). 1572 *First example:* 1574 This example is described in Section 6.13.1. 1576 CBOR diagnostic notation: "/ietf-system:system/contact" 1578 CBOR encoding: 1580 78 1c 2F696574662D73797374656D3A73797374656D2F636F6E74616374 1582 *Second example:* 1584 This example is described in Section 6.13.1. 1586 CBOR diagnostic notation: 1588 "/ietf-system:system/authentication/user[name='bob']/authorized-key 1589 [name='admin']/key-data" 1591 CBOR encoding: 1593 78 59 1594 2F696574662D73797374656D3A73797374656D2F61757468656E74696361 1595 74696F6E2F757365725B6E616D653D27626F62275D2F617574686F72697A 1596 65642D6B65790D0A5B6E616D653D2761646D696E275D2F6B65792D64617461 1598 *Third example:* 1600 This example is described in Section 6.13.1. 1602 CBOR diagnostic notation: 1604 "/ietf-system:system/authentication/user[name='bob']" 1606 CBOR encoding: 1608 78 33 1609 2F696574662D73797374656D3A73797374656D2F61757468656E74696361 1610 74696F6E2F757365725B6E616D653D27626F62275D 1612 7. Security Considerations 1614 The security considerations of [RFC7049] and [RFC7950] apply. 1616 This document defines an alternative encoding for data modeled in the 1617 YANG data modeling language. As such, this encoding does not 1618 contribute any new security issues in addition of those identified 1619 for the specific protocol or context for which it is used. 1621 To minimize security risks, software on the receiving side SHOULD 1622 reject all messages that do not comply to the rules of this document 1623 and reply with an appropriate error message to the sender. 1625 8. IANA Considerations 1627 8.1. Tags Registry 1629 This specification requires the assignment of CBOR tags for the 1630 following YANG datatypes. These tags are added to the Tags Registry 1631 as defined in section 7.2 of [RFC7049]. 1633 +----+----------+---------------------+-----------------------------+ 1634 | Ta | Data | Semantics | Reference | 1635 | g | Item | | | 1636 +----+----------+---------------------+-----------------------------+ 1637 | 42 | unsigned | YANG Schema Item | [draft-ietf-core-yang-cbor] | 1638 | | integer | iDentifier (sid); | | 1639 | | | see Section 3.2. | | 1640 | 43 | byte | YANG bits datatype; | [draft-ietf-core-yang-cbor] | 1641 | | string | see Section 6.7. | | 1642 | 44 | unsigned | YANG enumeration | [draft-ietf-core-yang-cbor] | 1643 | | integer | datatype; see | | 1644 | | | Section 6.6. | | 1645 | 45 | unsigned | YANG identityref | [draft-ietf-core-yang-cbor] | 1646 | | integer | datatype; see | | 1647 | | or text | Section 6.10. | | 1648 | | string | | | 1649 | 46 | unsigned | YANG instance- | [draft-ietf-core-yang-cbor] | 1650 | | integer | identifier | | 1651 | | or text | datatype; see | | 1652 | | string | Section 6.13. | | 1653 | | or array | | | 1654 +----+----------+---------------------+-----------------------------+ 1656 // RFC Ed.: replace [draft-ietf-core-yang-cbor] with RFC number and 1657 remove this note 1659 9. Acknowledgments 1661 This document has been largely inspired by the extensive works done 1662 by Andy Bierman and Peter van der Stok on [I-D.ietf-core-comi]. 1663 [RFC7951] has also been a critical input to this work. The authors 1664 would like to thank the authors and contributors to these two drafts. 1666 The authors would also like to acknowledge the review, feedback, and 1667 comments from Ladislav Lhotka and Juergen Schoenwaelder. 1669 10. References 1671 10.1. Normative References 1673 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1674 Requirement Levels", BCP 14, RFC 2119, 1675 DOI 10.17487/RFC2119, March 1997, 1676 . 1678 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1679 and A. Bierman, Ed., "Network Configuration Protocol 1680 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1681 . 1683 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1684 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1685 October 2013, . 1687 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1688 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1689 . 1691 10.2. Informative References 1693 [I-D.ietf-core-comi] 1694 Veillette, M., Stok, P., Pelov, A., and A. Bierman, "CoAP 1695 Management Interface", draft-ietf-core-comi-04 (work in 1696 progress), November 2018. 1698 [I-D.ietf-core-sid] 1699 Veillette, M., Pelov, A., and I. Petrov, "YANG Schema Item 1700 iDentifier (SID)", draft-ietf-core-sid-06 (work in 1701 progress), March 2019. 1703 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1704 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1705 2014, . 1707 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1708 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1709 . 1711 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1712 Constrained-Node Networks", RFC 7228, 1713 DOI 10.17487/RFC7228, May 2014, 1714 . 1716 [RFC7277] Bjorklund, M., "A YANG Data Model for IP Management", 1717 RFC 7277, DOI 10.17487/RFC7277, June 2014, 1718 . 1720 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1721 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1722 2014, . 1724 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 1725 RFC 7951, DOI 10.17487/RFC7951, August 2016, 1726 . 1728 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1729 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1730 . 1732 [RFC8348] Bierman, A., Bjorklund, M., Dong, J., and D. Romascanu, "A 1733 YANG Data Model for Hardware Management", RFC 8348, 1734 DOI 10.17487/RFC8348, March 2018, 1735 . 1737 Authors' Addresses 1739 Michel Veillette (editor) 1740 Trilliant Networks Inc. 1741 610 Rue du Luxembourg 1742 Granby, Quebec J2J 2V2 1743 Canada 1745 Email: michel.veillette@trilliantinc.com 1747 Ivaylo Petrov (editor) 1748 Acklio 1749 1137A avenue des Champs Blancs 1750 Cesson-Sevigne, Bretagne 35510 1751 France 1753 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