idnits 2.17.00 (12 Aug 2021) /tmp/idnits36550/draft-ietf-core-sid-06.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 : ---------------------------------------------------------------------------- ** There are 11 instances of too long lines in the document, the longest one being 9 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 28, 2019) is 1150 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: 'DONE' is mentioned on line 1304, but not defined == Unused Reference: 'RFC7120' is defined on line 675, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-11) exists of draft-ietf-core-comi-04 -- Obsolete informational reference (is this intentional?): RFC 6021 (Obsoleted by RFC 6991) -- Obsolete informational reference (is this intentional?): RFC 6536 (Obsoleted by RFC 8341) -- 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 (~~), 4 warnings (==), 5 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 A. Pelov, Ed. 5 Expires: September 29, 2019 I. Petrov, Ed. 6 Acklio 7 March 28, 2019 9 YANG Schema Item iDentifier (SID) 10 draft-ietf-core-sid-06 12 Abstract 14 YANG Schema Item iDentifiers (SID) are globally unique 64-bit 15 unsigned numbers used to identify YANG items. This document defines 16 the semantics, the registration, and assignment processes of SIDs. 17 To enable the implementation of these processes, this document also 18 defines a file format used to persist and publish assigned SIDs. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on September 29, 2019. 37 Copyright Notice 39 Copyright (c) 2019 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 3 56 3. ".sid" file lifecycle . . . . . . . . . . . . . . . . . . . . 4 57 4. ".sid" file format . . . . . . . . . . . . . . . . . . . . . 5 58 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 59 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 60 6.1. Register SID File Format Module . . . . . . . . . . . . . 9 61 6.2. Create new IANA Registry: "SID Mega-Range" registry . . . 9 62 6.2.1. Structure . . . . . . . . . . . . . . . . . . . . . . 10 63 6.2.2. Allocation policy . . . . . . . . . . . . . . . . . . 10 64 6.2.2.1. First allocation . . . . . . . . . . . . . . . . 11 65 6.2.2.2. Consecutive allocations . . . . . . . . . . . . . 11 66 6.2.3. Initial contents of the Registry . . . . . . . . . . 11 67 6.3. Create a new IANA Registry: IETF SID Range Registry 68 (managed by IANA) . . . . . . . . . . . . . . . . . . . . 11 69 6.3.1. Structure . . . . . . . . . . . . . . . . . . . . . . 11 70 6.3.2. Allocation policy . . . . . . . . . . . . . . . . . . 12 71 6.3.3. Initial contents of the registry . . . . . . . . . . 13 72 6.4. Create new IANA Registry: "IETF SID Registry" . . . . . . 13 73 6.4.1. Structure . . . . . . . . . . . . . . . . . . . . . . 13 74 6.4.2. Allocation policy . . . . . . . . . . . . . . . . . . 14 75 6.4.3. Initial contents of the registry . . . . . . . . . . 14 76 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 14 77 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 78 8.1. Normative References . . . . . . . . . . . . . . . . . . 15 79 8.2. Informative References . . . . . . . . . . . . . . . . . 15 80 Appendix A. ".sid" file example . . . . . . . . . . . . . . . . 16 81 Appendix B. SID auto generation . . . . . . . . . . . . . . . . 25 82 Appendix C. ".sid" file lifecycle . . . . . . . . . . . . . . . 26 83 C.1. SID File Creation . . . . . . . . . . . . . . . . . . . . 26 84 C.2. SID File Update . . . . . . . . . . . . . . . . . . . . . 27 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 87 1. Introduction 89 Some of the items defined in YANG [RFC7950] require the use of a 90 unique identifier. In both NETCONF [RFC6241] and RESTCONF [RFC8040], 91 these identifiers are implemented using names. To allow the 92 implementation of data models defined in YANG in constrained devices 93 and constrained networks, a more compact method to identify YANG 94 items is required. This compact identifier, called SID, is encoded 95 using a 64-bit unsigned integer. The following items are identified 96 using SIDs: 98 o identities 100 o data nodes (Note: including those part of a YANG template as 101 defined by the 'yang-data' extension.) 103 o RPCs and associated input(s) and output(s) 105 o actions and associated input(s) and output(s) 107 o notifications and associated information 109 o YANG modules, submodules and features 111 To minimize their size, in certain positions, SIDs could be 112 represented using a (signed) delta from a reference SID and the 113 current SID (for example during transmissions). Such difference is 114 itself called "delta", shorthand for "delta-encoded SID". Conversion 115 from SIDs to deltas and back to SIDs is a stateless process. Each 116 protocol implementing deltas must unambiguously define the reference 117 SID for each YANG item. 119 SIDs are globally unique numbers, a registration system is used in 120 order to guarantee their uniqueness. SIDs are registered in blocks 121 called "SID ranges". 123 Assignment of SIDs to YANG items can be automated. For more details 124 how this could be achieved, please consult Appendix B. 126 SIDs are assigned permanently, items introduced by a new revision of 127 a YANG module are added to the list of SIDs already assigned. 129 Section 3 provides more details about the registration process of 130 YANG modules and associated SIDs. To enable the implementation of 131 this registry, Section 4 defines a standard file format used to store 132 and publish SIDs. 134 2. Terminology and Notation 136 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 137 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 138 document are to be interpreted as described in [RFC2119]. 140 The following terms are defined in [RFC7950]: 142 o action 144 o feature 145 o module 147 o notification 149 o RPC 151 o schema node 153 o schema tree 155 o submodule 157 The following term is defined in [RFC8040]: 159 o yang-data extension 161 This specification also makes use of the following terminology: 163 o delta : Difference between the current SID and a reference SID. 164 Each protocol that uses delta encoded SIDs MUST define how the 165 reference SID is obtained. 167 o item: A schema node, an identity, a module, a submodule or a 168 feature defined using the YANG modeling language. 170 o path: A path is a string that identifies a schema node within the 171 schema tree. A path consists of the list of schema node 172 identifier(s) separated by slashes ("/"). Schema node 173 identifier(s) are always listed from the top-level schema node up 174 to the targeted schema node. (e.g. "/ietf-system:system- 175 state/clock/current-datetime") 177 o YANG Schema Item iDentifier (SID): Unsigned integer used to 178 identify different YANG items. 180 3. ".sid" file lifecycle 182 YANG is a language designed to model data accessed using one of the 183 compatible protocols (e.g. NETCONF [RFC6241], RESCONF [RFC8040] and 184 CoMI [I-D.ietf-core-comi]). A YANG module defines hierarchies of 185 data, including configuration, state data, RPCs, actions and 186 notifications. 188 YANG modules are not necessarily created in the context of 189 constrained applications. YANG modules can be implemented using 190 NETCONF [RFC6241] or RESTCONF [RFC8040] without the need to assign 191 SIDs. 193 As needed, authors of YANG modules can assign SIDs to their YANG 194 modules. In order to do that, they should first obtain a SID range 195 from a registry and use that range to assign or generate SIDs to 196 items of their YANG module. For example how this could be achieved, 197 please refer to Appendix C. 199 Registration of the .sid file associated to a YANG module is optional 200 but recommended to promote interoperability between devices and to 201 avoid duplicate allocation of SIDs to a single YANG module. 202 Different registries might have different requirements for the 203 registration and publication of the ".sid" files. For diagram of one 204 of the possibilities, please refer to the activity diagram on 205 Figure 1 in Appendix C. 207 Each time a YANG module or one of its imported module(s) or included 208 sub-module(s) is updated, the ".sid" file MAY need to be updated. 209 This update SHOULD also be performed using an automated tool. 211 If a new revision requires more SIDs than initially allocated, a new 212 SID range MUST be added to the 'assignment-ranges' as defined in 213 Section 4. These extra SIDs are used for subsequent assignments. 215 For an example of this update process, see activity diagram Figure 2 216 in Appendix C. 218 4. ".sid" file format 220 ".sid" files are used to persist and publish SIDs assigned to the 221 different YANG items of a specific YANG module. The following YANG 222 module defined the structure of this file, encoding is performed 223 using the rules defined in [RFC7951]. 225 file "ietf-sid-file@2017-11-26.yang" 226 module ietf-sid-file { 227 namespace "urn:ietf:params:xml:ns:yang:ietf-sid-file"; 228 prefix sid; 230 import ietf-yang-types { 231 prefix yang; 232 } 234 organization 235 "IETF Core Working Group"; 237 contact 238 "Michel Veillette 239 240 Andy Bierman 241 243 Alexander Pelov 244 "; 246 description 247 "This module defines the structure of the .sid files. 249 Each .sid file contains the mapping between the different 250 string identifiers defined by a YANG module and a 251 corresponding numeric value called SID."; 253 revision 2017-11-26 { 254 description 255 "Initial revision."; 256 reference 257 "[I-D.ietf-core-sid] YANG Schema Item iDentifier (SID)"; 258 } 260 typedef revision-identifier { 261 type string { 262 pattern '\d{4}-\d{2}-\d{2}'; 263 } 264 description 265 "Represents a date in YYYY-MM-DD format."; 266 } 268 typedef sid { 269 type uint64; 270 description 271 "YANG Schema Item iDentifier"; 272 reference 273 "[I-D.ietf-core-sid] YANG Schema Item iDentifier (SID)"; 274 } 276 typedef schema-node-path { 277 type string { 278 pattern 279 '/[a-zA-Z_][a-zA-Z0-9\-_.]*:[a-zA-Z_][a-zA-Z0-9\-_.]*' + 280 '(/[a-zA-Z_][a-zA-Z0-9\-_.]*(:[a-zA-Z_][a-zA-Z0-9\-_.]*)?)*'; 281 } 282 description 283 "Identifies a schema-node path string for use in the 284 SID registry. This string format follows the rules 285 for an instance-identifier, as defined in RFC 7959, 286 except that no predicates are allowed. 288 This format is intended to support the YANG 1.1 ABNF 289 for a schema node identifier, except module names 290 are used instead of prefixes, as specified in RFC 7951."; 291 reference 292 "RFC 7950, The YANG 1.1 Data Modeling Language; 293 Section 6.5: Schema Node Identifier; 294 RFC 7951, JSON Encoding of YANG Data; 295 Section 6.11: The instance-identifier type"; 296 } 298 leaf module-name { 299 type yang:yang-identifier; 300 description 301 "Name of the YANG module associated with this .sid file."; 302 } 304 leaf module-revision { 305 type revision-identifier; 306 description 307 "Revision of the YANG module associated with this .sid file. 308 This leaf is not present if no revision statement is 309 defined in the YANG module."; 310 } 312 list assigment-ranges { 313 key "entry-point"; 314 description 315 "SID range(s) allocated to the YANG module identified by 316 'module-name' and 'module-revision'."; 318 leaf entry-point { 319 type sid; 320 mandatory true; 321 description 322 "Lowest SID available for assignment."; 323 } 325 leaf size { 326 type uint64; 327 mandatory true; 328 description 329 "Number of SIDs available for assignment."; 330 } 331 } 333 list items { 334 key "namespace identifier"; 335 description 336 "Each entry within this list defined the mapping between 337 a YANG item string identifier and a SID. This list MUST 338 include a mapping entry for each YANG item defined by 339 the YANG module identified by 'module-name' and 340 'module-revision'."; 342 leaf namespace { 343 type enumeration { 344 enum module { 345 value 0; 346 description 347 "All module and submodule names share the same 348 global module identifier namespace."; 349 } 350 enum identity { 351 value 1; 352 description 353 "All identity names defined in a module and its 354 submodules share the same identity identifier 355 namespace."; 356 } 357 enum feature { 358 value 2; 359 description 360 "All feature names defined in a module and its 361 submodules share the same feature identifier 362 namespace."; 363 } 364 enum data { 365 value 3; 366 description 367 "The namespace for all data nodes, as defined in YANG."; 368 } 369 } 370 description 371 "Namespace of the YANG item for this mapping entry."; 372 } 374 leaf identifier { 375 type union { 376 type yang:yang-identifier; 377 type schema-node-path; 378 } 379 description 380 "String identifier of the YANG item for this mapping entry. 382 If the corresponding 'namespace' field is 'module', 383 'feature', or 'identity', then this field MUST 384 contain a valid YANG identifier string. 386 If the corresponding 'namespace' field is 'data', 387 then this field MUST contain a valid schema node 388 path."; 389 } 391 leaf sid { 392 type sid; 393 mandatory true; 394 description 395 "SID assigned to the YANG item for this mapping entry."; 396 } 397 } 398 } 399 401 5. Security Considerations 403 The security considerations of [RFC7049] and [RFC7950] apply. 405 This document defines a new type of identifier used to encode data 406 models defined in YANG [RFC7950]. As such, this identifier does not 407 contribute to any new security issues in addition of those identified 408 for the specific protocols or contexts for which it is used. 410 6. IANA Considerations 412 6.1. Register SID File Format Module 414 This document registers one YANG modules in the "YANG Module Names" 415 registry [RFC6020]: 417 o name: ietf-sid-file 419 o namespace: urn:ietf:params:xml:ns:yang:ietf-sid-file 421 o prefix: sid 423 o reference: [[THISRFC]] 425 6.2. Create new IANA Registry: "SID Mega-Range" registry 427 The name of this registry is "SID Mega-Range". This registry is used 428 to record the delegation of the management of a block of SIDs to 429 third parties (e.g. SDOs, registrars, etc). 431 6.2.1. Structure 433 Each entry in this registry must include: 435 o The entry point (first SID) of the registered SID block. 437 o The size of the registered SID block. The size MUST be one 438 million (1 000 000) SIDs. 440 o The contact information of the requesting organization including: 442 * The policy of SID range allocations: Public, Private or Both. 444 * Organization name 446 * URL 448 The information associated to the Organization name should not be 449 publicly visible in the registry, but should be available. This 450 information includes contact email and phone number and change 451 controller email and phone number. 453 6.2.2. Allocation policy 455 The IANA policies for future additions to this registry are "Expert 456 Review" [RFC8126]. 458 An organization requesting to manage a SID Range (and thus have an 459 entry in the SID Mega-Range Registry), must ensure the following 460 capacities: 462 o The capacity to manage and operate a SID Range Registry. A SID 463 Range Registry MUST provide the following information for all SID 464 Ranges allocated by the Registry: 466 * Entry Point of allocated SID Range 468 * Size of allocated SID Range 470 * Type: Public or Private 472 + Public Ranges MUST include at least a reference to the YANG 473 module and ".sid" files for that SID Range. 475 + Private Ranges MUST be marked as "Private" 477 o A Policy of allocation, which clearly identifies if the SID Range 478 allocations would be Private, Public or Both. 480 o Technical capacity to ensure the sustained operation of the 481 registry for a period of at least 5 years. If Private 482 Registrations are allowed, the period must be of at least 10 483 years. 485 6.2.2.1. First allocation 487 For a first allocation to be provided, the requesting organization 488 must demonstrate a functional registry infrastructure. 490 6.2.2.2. Consecutive allocations 492 On subsequent allocation request(s), the organization must 493 demonstrate the exhaustion of the prior range. These conditions need 494 to be asserted by the assigned expert(s). 496 If that extra-allocation is done within 3 years from the last 497 allocation, the experts need to discuss this request on the CORE 498 working group mailing list and consensus needs to be obtained before 499 allocating new Mega-Range. 501 6.2.3. Initial contents of the Registry 503 The initial entry in this registry is allocated to IANA: 505 +-------------+---------+------------+-------------------+----------+ 506 | Entry Point | Size | Allocation | Organization name | URL | 507 +-------------+---------+------------+-------------------+----------+ 508 | 0 | 1000000 | Public | IANA | iana.org | 509 +-------------+---------+------------+-------------------+----------+ 511 6.3. Create a new IANA Registry: IETF SID Range Registry (managed by 512 IANA) 514 6.3.1. Structure 516 Each entry in this registry must include: 518 o The SID range entry point. 520 o The SID range size. 522 o The YANG module name. 524 o Document reference. 526 6.3.2. Allocation policy 528 The first million SIDs assigned to IANA is sub-divided as follows: 530 o The range of 0 to 999 (size 1000) is "Reserved" as defined in 531 [RFC8126]. 533 o The range of 1000 to 59,999 (size 59,000) is reserved for YANG 534 modules defined in RFCs. The IANA policy for additions to this 535 registry is "Expert Review" [RFC8126]. 537 * The Expert MUST verify that the YANG module for which this 538 allocation is made has an RFC (existing RFC) OR is on track to 539 become RFC (early allocation with a request from the WG 540 chairs). 542 o The SID range allocated for a YANG module can follow in one of the 543 four categories: 545 * SMALL (50 SIDs) 547 * MEDIUM (100 SIDs) 549 * LARGE (250 SIDs) 551 * CUSTOM (requested by the YANG module author, with a maximum of 552 1000 SIDs). In all cases, the size of a SID range assigned to 553 a YANG module should be at least 33% above the current number 554 of YANG items. This headroom allows assignment within the same 555 range of new YANG items introduced by subsequent revisions. A 556 larger SID range size may be requested by the authors if this 557 recommendation is considered insufficient. It is important to 558 note that an additional SID range can be allocated to an 559 existing YANG module if the initial range is exhausted. 561 o The range of 60,000 to 99,999 (size 40,000)is reserved for 562 experimental YANG modules. This range MUST NOT be used in 563 operational deployments since these SIDs are not globally unique 564 which limit their interoperability. The IANA policy for this 565 range is "Experimental use" [RFC8126]. 567 o The range of 100,000 to 999,999 (size 900,000) is "Reserved" as 568 defined in [RFC8126]. 570 +-------------+---------+------------------+ 571 | Entry Point | Size | IANA policy | 572 +-------------+---------+------------------+ 573 | 0 | 1,000 | Reserved | 574 | 1,000 | 59,000 | Expert Review | 575 | 60,000 | 40,000 | Experimental use | 576 | 100,000 | 900,000 | Reserved | 577 +-------------+---------+------------------+ 579 6.3.3. Initial contents of the registry 581 Initial entries in this registry are as follows: 583 +-------------+------+------------------+----------------------+ 584 | Entry Point | Size | Module name | Document reference | 585 +-------------+------+------------------+----------------------+ 586 | 1000 | 100 | ietf-comi | [I-D.ietf-core-comi] | 587 | 1100 | 50 | ietf-yang-types | [RFC6021] | 588 | 1150 | 50 | ietf-inet-types | [RFC6021] | 589 | 1200 | 50 | iana-crypt-hash | [RFC7317] | 590 | 1250 | 50 | ietf-netconf-acm | [RFC6536] | 591 | 1300 | 50 | ietf-sid-file | RFCXXXX | 592 | 1500 | 100 | ietf-interfaces | [RFC7223] | 593 | 1600 | 100 | ietf-ip | [RFC7277] | 594 | 1700 | 100 | ietf-system | [RFC7317] | 595 | 1800 | 400 | iana-if-type | [RFC7224] | 596 +-------------+------+------------------+----------------------+ 598 // RFC Ed.: replace XXXX with RFC number assigned to this draft. 600 For allocation, RFC publication of the YANG module is required as per 601 [RFC8126]. The YANG module must be registered in the "YANG module 602 Name" registry according to the rules specified in section 14 of 603 [RFC6020]. 605 6.4. Create new IANA Registry: "IETF SID Registry" 607 The name of this registry is "IETF SID Registry". This registry is 608 used to record the allocation of individual SIDs YANG module items. 610 6.4.1. Structure 612 Each entry in this registry must include: 614 o The YANG module name. This module name must be present in the 615 "Name" column of the "YANG Module Names" registry. 617 o A link to the associated ".yang" file. This file link must be 618 present in the "File" column of the "YANG Module Names" registry. 620 o The link to the ".sid" file which defines the allocation. 622 o The number of actually allocated SIDs in the ".sid" file. 624 The ".sid" file is stored by IANA. 626 6.4.2. Allocation policy 628 The allocation policy is Expert review. The Expert MUST ensure that 629 the following conditions are met: 631 o The ".sid" file has a valid structure: 633 * The ".sid" file MUST be a valid JSON file following the 634 structure of the module defined in RFCXXXX (RFC Ed: replace XXX 635 with RFC number assigned to this draft). 637 o The ".sid" file allocates individual SIDs ONLY in the SID Ranges 638 for this YANG module (as allocated in the IETF SID Range 639 Registry): 641 * All SIDs in this ".sid" file MUST be within the ranges 642 allocated to this YANG module in the "IETF SID Range Registry". 644 o If another ".sid" file has already allocated SIDs for this YANG 645 module (e.g. for older or newer versions of the YANG module), the 646 YANG items are assigned the same SIDs as in the the other ".sid" 647 file. 649 o SIDs never change. 651 6.4.3. Initial contents of the registry 653 None. 655 7. Acknowledgments 657 The authors would like to thank Andy Bierman, Carsten Bormann, 658 Abhinav Somaraju, Laurent Toutain, Randy Turner and Peter van der 659 Stok for their help during the development of this document and their 660 useful comments during the review process. 662 8. References 664 8.1. Normative References 666 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 667 Requirement Levels", BCP 14, RFC 2119, 668 DOI 10.17487/RFC2119, March 1997, 669 . 671 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 672 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 673 October 2013, . 675 [RFC7120] Cotton, M., "Early IANA Allocation of Standards Track Code 676 Points", BCP 100, RFC 7120, DOI 10.17487/RFC7120, January 677 2014, . 679 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 680 RFC 7950, DOI 10.17487/RFC7950, August 2016, 681 . 683 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 684 RFC 7951, DOI 10.17487/RFC7951, August 2016, 685 . 687 8.2. Informative References 689 [I-D.ietf-core-comi] 690 Veillette, M., Stok, P., Pelov, A., and A. Bierman, "CoAP 691 Management Interface", draft-ietf-core-comi-04 (work in 692 progress), November 2018. 694 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 695 the Network Configuration Protocol (NETCONF)", RFC 6020, 696 DOI 10.17487/RFC6020, October 2010, 697 . 699 [RFC6021] Schoenwaelder, J., Ed., "Common YANG Data Types", 700 RFC 6021, DOI 10.17487/RFC6021, October 2010, 701 . 703 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 704 and A. Bierman, Ed., "Network Configuration Protocol 705 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 706 . 708 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 709 Protocol (NETCONF) Access Control Model", RFC 6536, 710 DOI 10.17487/RFC6536, March 2012, 711 . 713 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 714 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 715 . 717 [RFC7224] Bjorklund, M., "IANA Interface Type YANG Module", 718 RFC 7224, DOI 10.17487/RFC7224, May 2014, 719 . 721 [RFC7277] Bjorklund, M., "A YANG Data Model for IP Management", 722 RFC 7277, DOI 10.17487/RFC7277, June 2014, 723 . 725 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 726 System Management", RFC 7317, DOI 10.17487/RFC7317, August 727 2014, . 729 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 730 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 731 . 733 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 734 Writing an IANA Considerations Section in RFCs", BCP 26, 735 RFC 8126, DOI 10.17487/RFC8126, June 2017, 736 . 738 Appendix A. ".sid" file example 740 The following .sid file (ietf-system@2014-08-06.sid) have been 741 generated using the following yang modules: 743 o ietf-system@2014-08-06.yang 745 o ietf-yang-types@2013-07-15.yang 747 o ietf-inet-types@2013-07-15.yang 749 o ietf-netconf-acm@2012-02-22.yang 751 o iana-crypt-hash@2014-04-04.yang 753 { 754 "assignment-ranges": [ 755 { 756 "entry-point": 1700, 757 "size": 100 758 } 759 ], 760 "module-name": "ietf-system", 761 "module-revision": "2014-08-06", 762 "items": [ 763 { 764 "namespace": "module", 765 "identifier": "ietf-system", 766 "sid": 1700 767 }, 768 { 769 "namespace": "identity", 770 "identifier": "authentication-method", 771 "sid": 1701 772 }, 773 { 774 "namespace": "identity", 775 "identifier": "local-users", 776 "sid": 1702 777 }, 778 { 779 "namespace": "identity", 780 "identifier": "radius", 781 "sid": 1703 782 }, 783 { 784 "namespace": "identity", 785 "identifier": "radius-authentication-type", 786 "sid": 1704 787 }, 788 { 789 "namespace": "identity", 790 "identifier": "radius-chap", 791 "sid": 1705 792 }, 793 { 794 "namespace": "identity", 795 "identifier": "radius-pap", 796 "sid": 1706 797 }, 798 { 799 "namespace": "feature", 800 "identifier": "authentication", 801 "sid": 1707 802 }, 803 { 804 "namespace": "feature", 805 "identifier": "dns-udp-tcp-port", 806 "sid": 1708 807 }, 808 { 809 "namespace": "feature", 810 "identifier": "local-users", 811 "sid": 1709 812 }, 813 { 814 "namespace": "feature", 815 "identifier": "ntp", 816 "sid": 1710 817 }, 818 { 819 "namespace": "feature", 820 "identifier": "ntp-udp-port", 821 "sid": 1711 822 }, 823 { 824 "namespace": "feature", 825 "identifier": "radius", 826 "sid": 1712 827 }, 828 { 829 "namespace": "feature", 830 "identifier": "radius-authentication", 831 "sid": 1713 832 }, 833 { 834 "namespace": "feature", 835 "identifier": "timezone-name", 836 "sid": 1714 837 }, 838 { 839 "namespace": "data", 840 "identifier": "/ietf-system:set-current-datetime", 841 "sid": 1715 842 }, 843 { 844 "namespace": "data", 845 "identifier": "/ietf-system:set-current-datetime/ 846 current-datetime", 847 "sid": 1716 848 }, 849 { 850 "namespace": "data", 851 "identifier": "/ietf-system:system", 852 "sid": 1717 853 }, 854 { 855 "namespace": "data", 856 "identifier": "/ietf-system:system-restart", 857 "sid": 1718 858 }, 859 { 860 "namespace": "data", 861 "identifier": "/ietf-system:system-shutdown", 862 "sid": 1719 863 }, 864 { 865 "namespace": "data", 866 "identifier": "/ietf-system:system-state", 867 "sid": 1720 868 }, 869 { 870 "namespace": "data", 871 "identifier": "/ietf-system:system-state/clock", 872 "sid": 1721 873 }, 874 { 875 "namespace": "data", 876 "identifier": "/ietf-system:system-state/clock/boot-datetime", 877 "sid": 1722 878 }, 879 { 880 "namespace": "data", 881 "identifier": "/ietf-system:system-state/clock/ 882 current-datetime", 883 "sid": 1723 884 }, 885 { 886 "namespace": "data", 887 "identifier": "/ietf-system:system-state/platform", 888 "sid": 1724 889 }, 890 { 891 "namespace": "data", 892 "identifier": "/ietf-system:system-state/platform/machine", 893 "sid": 1725 894 }, 895 { 896 "namespace": "data", 897 "identifier": "/ietf-system:system-state/platform/os-name", 898 "sid": 1726 899 }, 900 { 901 "namespace": "data", 902 "identifier": "/ietf-system:system-state/platform/os-release", 903 "sid": 1727 904 }, 905 { 906 "namespace": "data", 907 "identifier": "/ietf-system:system-state/platform/os-version", 908 "sid": 1728 909 }, 910 { 911 "namespace": "data", 912 "identifier": "/ietf-system:system/authentication", 913 "sid": 1729 914 }, 915 { 916 "namespace": "data", 917 "identifier": "/ietf-system:system/authentication/user", 918 "sid": 1730 919 }, 920 { 921 "namespace": "data", 922 "identifier": "/ietf-system:system/authentication/ 923 user-authentication-order", 924 "sid": 1731 925 }, 926 { 927 "namespace": "data", 928 "identifier": "/ietf-system:system/authentication/user/ 929 authorized-key", 930 "sid": 1732 931 }, 932 { 933 "namespace": "data", 934 "identifier": "/ietf-system:system/authentication/user/ 935 authorized-key/algorithm", 936 "sid": 1733 937 }, 938 { 939 "namespace": "data", 940 "identifier": "/ietf-system:system/authentication/user/ 941 authorized-key/key-data", 942 "sid": 1734 943 }, 944 { 945 "namespace": "data", 946 "identifier": "/ietf-system:system/authentication/user/ 947 authorized-key/name", 949 "sid": 1735 950 }, 951 { 952 "namespace": "data", 953 "identifier": "/ietf-system:system/authentication/user/ 954 name", 955 "sid": 1736 956 }, 957 { 958 "namespace": "data", 959 "identifier": "/ietf-system:system/authentication/user/ 960 password", 961 "sid": 1737 962 }, 963 { 964 "namespace": "data", 965 "identifier": "/ietf-system:system/clock", 966 "sid": 1738 967 }, 968 { 969 "namespace": "data", 970 "identifier": "/ietf-system:system/clock/timezone-name", 971 "sid": 1739 972 }, 973 { 974 "namespace": "data", 975 "identifier": "/ietf-system:system/clock/timezone-utc-offset", 976 "sid": 1740 977 }, 978 { 979 "namespace": "data", 980 "identifier": "/ietf-system:system/contact", 981 "sid": 1741 982 }, 983 { 984 "namespace": "data", 985 "identifier": "/ietf-system:system/dns-resolver", 986 "sid": 1742 987 }, 988 { 989 "namespace": "data", 990 "identifier": "/ietf-system:system/dns-resolver/options", 991 "sid": 1743 992 }, 993 { 994 "namespace": "data", 995 "identifier": "/ietf-system:system/dns-resolver/options/ 996 attempts", 998 "sid": 1744 999 }, 1000 { 1001 "namespace": "data", 1002 "identifier": "/ietf-system:system/dns-resolver/options/ 1003 timeout", 1004 "sid": 1745 1005 }, 1006 { 1007 "namespace": "data", 1008 "identifier": "/ietf-system:system/dns-resolver/search", 1009 "sid": 1746 1010 }, 1011 { 1012 "namespace": "data", 1013 "identifier": "/ietf-system:system/dns-resolver/server", 1014 "sid": 1747 1015 }, 1016 { 1017 "namespace": "data", 1018 "identifier": "/ietf-system:system/dns-resolver/server/name", 1019 "sid": 1748 1020 }, 1021 { 1022 "namespace": "data", 1023 "identifier": "/ietf-system:system/dns-resolver/server/ 1024 udp-and-tcp", 1025 "sid": 1749 1026 }, 1027 { 1028 "namespace": "data", 1029 "identifier": "/ietf-system:system/dns-resolver/server/ 1030 udp-and-tcp/address", 1031 "sid": 1750 1032 }, 1033 { 1034 "namespace": "data", 1035 "identifier": "/ietf-system:system/dns-resolver/server/ 1036 udp-and-tcp/port", 1037 "sid": 1751 1038 }, 1039 { 1040 "namespace": "data", 1041 "identifier": "/ietf-system:system/hostname", 1042 "sid": 1752 1043 }, 1044 { 1045 "namespace": "data", 1046 "identifier": "/ietf-system:system/location", 1047 "sid": 1753 1048 }, 1049 { 1050 "namespace": "data", 1051 "identifier": "/ietf-system:system/ntp", 1052 "sid": 1754 1053 }, 1054 { 1055 "namespace": "data", 1056 "identifier": "/ietf-system:system/ntp/enabled", 1057 "sid": 1755 1058 }, 1059 { 1060 "namespace": "data", 1061 "identifier": "/ietf-system:system/ntp/server", 1062 "sid": 1756 1063 }, 1064 { 1065 "namespace": "data", 1066 "identifier": "/ietf-system:system/ntp/server/ 1067 association-type", 1068 "sid": 1757 1069 }, 1070 { 1071 "namespace": "data", 1072 "identifier": "/ietf-system:system/ntp/server/iburst", 1073 "sid": 1758 1074 }, 1075 { 1076 "namespace": "data", 1077 "identifier": "/ietf-system:system/ntp/server/name", 1078 "sid": 1759 1079 }, 1080 { 1081 "namespace": "data", 1082 "identifier": "/ietf-system:system/ntp/server/prefer", 1083 "sid": 1760 1084 }, 1085 { 1086 "namespace": "data", 1087 "identifier": "/ietf-system:system/ntp/server/udp", 1088 "sid": 1761 1089 }, 1090 { 1091 "namespace": "data", 1092 "identifier": "/ietf-system:system/ntp/server/udp/address", 1093 "sid": 1762 1095 }, 1096 { 1097 "namespace": "data", 1098 "identifier": "/ietf-system:system/ntp/server/udp/port", 1099 "sid": 1763 1100 }, 1101 { 1102 "namespace": "data", 1103 "identifier": "/ietf-system:system/radius", 1104 "sid": 1764 1105 }, 1106 { 1107 "namespace": "data", 1108 "identifier": "/ietf-system:system/radius/options", 1109 "sid": 1765 1110 }, 1111 { 1112 "namespace": "data", 1113 "identifier": "/ietf-system:system/radius/options/attempts", 1114 "sid": 1766 1115 }, 1116 { 1117 "namespace": "data", 1118 "identifier": "/ietf-system:system/radius/options/timeout", 1119 "sid": 1767 1120 }, 1121 { 1122 "namespace": "data", 1123 "identifier": "/ietf-system:system/radius/server", 1124 "sid": 1768 1125 }, 1126 { 1127 "namespace": "data", 1128 "identifier": "/ietf-system:system/radius/server/ 1129 authentication-type", 1130 "sid": 1769 1131 }, 1132 { 1133 "namespace": "data", 1134 "identifier": "/ietf-system:system/radius/server/name", 1135 "sid": 1770 1136 }, 1137 { 1138 "namespace": "data", 1139 "identifier": "/ietf-system:system/radius/server/udp", 1140 "sid": 1771 1141 }, 1142 { 1143 "namespace": "data", 1144 "identifier": "/ietf-system:system/radius/server/udp/ 1145 address", 1146 "sid": 1772 1147 }, 1148 { 1149 "namespace": "data", 1150 "identifier": "/ietf-system:system/radius/server/udp/ 1151 authentication-port", 1152 "sid": 1773 1153 }, 1154 { 1155 "namespace": "data", 1156 "identifier": "/ietf-system:system/radius/server/udp/ 1157 shared-secret", 1158 "sid": 1774 1159 } 1160 ] 1161 } 1163 Appendix B. SID auto generation 1165 Assignment of SIDs to YANG items can be automated, the recommended 1166 process to assign SIDs is as follows: 1168 1. A tool extracts the different items defined for a specific YANG 1169 module. 1171 2. The list of items is sorted in alphabetical order, 'namespace' in 1172 descending order, 'identifier' in ascending order. The 1173 'namespace' and 'identifier' formats are described in the YANG 1174 module 'ietf-sid-file' defined in Section 4. 1176 3. SIDs are assigned sequentially from the entry point up to the 1177 size of the registered SID range. This approach is recommended 1178 to minimize the serialization overhead, especially when delta 1179 encoding is implemented. 1181 4. If the number of items exceeds the SID range(s) allocated to a 1182 YANG module, an extra range is added for subsequent assignments. 1184 Changes of SID files can also be automated using the same method 1185 described above, only unassigned YANG items are processed at step #3. 1187 Appendix C. ".sid" file lifecycle 1189 Before assigning SIDs to their YANG modules, YANG module authors must 1190 acquire a SID range from a "SID Range Registry". If the YANG module 1191 is part of an IETF draft or RFC, the SID range need to be acquired 1192 from the "IETF SID Range Registry" as defined in Section 6.3. For 1193 the other YANG modules, the authors can acquire a SID range from any 1194 "SID Range Registry" of their choice. 1196 Once the SID range is acquired, the owner can use it to generate 1197 ".sid" file/s for his YANG module/s. It is recommended to leave some 1198 unallocated SIDs following the allocated range in each ".sid" file in 1199 order to allow better evolution of the YANG module in the future. 1200 Generation of ".sid" files should be performed using an automated 1201 tool. Note that ".sid" files can only be generated for YANG modules 1202 and not for submodules. 1204 C.1. SID File Creation 1206 The following activity diagram summarizes the creation of a YANG 1207 module and its associated .sid file. 1209 +---------------+ 1210 O | Creation of a | 1211 -|- ->| YANG module | 1212 / \ +---------------+ 1213 | 1214 V 1215 /-------------\ 1216 / Standardized \ yes 1217 \ YANG module ? /-------------+ 1218 \-------------/ | 1219 | no | 1220 V V 1221 /-------------\ +---------------+ 1222 / Constrained \ yes | SID range | 1223 +-->\ application ? /---->| registration |<----------+ 1224 | \-------------/ +---------------+ | 1225 | | no | | 1226 | V V | 1227 | +---------------+ +---------------+ | 1228 +---| YANG module | | SID sub-range | | 1229 | update | | assignment |<----------+ 1230 +---------------+ +---------------+ | 1231 | | 1232 V | 1233 +---------------+ +-------------+ 1234 | .sid file | | Rework YANG | 1235 | generation | | model | 1236 +---------------+ +-------------+ 1237 | ^ 1238 V | 1239 /----------\ yes | 1240 / Work in \ -----------+ 1241 \ progress / 1242 \----------/ 1243 | no 1244 V 1245 /-------------\ /-------------\ 1246 / RFC \ no / Open \ no 1247 \ publication? /---->\ specification?/---+ 1248 \-------------/ \-------------/ | 1249 | yes | yes | 1250 | +---------------+ | 1251 V V V 1252 +---------------+ +---------------+ 1253 | IANA | | Third party | 1254 | registration | | registration | 1255 +-------+-------+ +-------+-------+ 1256 | | 1257 +---------------------------------+ 1258 V 1259 [DONE] 1261 Figure 1: SID Lifecycle 1263 C.2. SID File Update 1265 The following Activity diagram summarizes the update of a YANG module 1266 and its associated .sid file. 1268 +---------------+ 1269 O | Update of the | 1270 -|- ->| YANG module | 1271 / \ | or include(s) | 1272 | or import(s) | 1273 +---------------+ 1274 | 1275 V 1276 /-------------\ 1277 / New items \ yes 1278 \ created ? /------+ 1279 \-------------/ | 1280 | no V 1281 | /-------------\ +----------------+ 1282 | / SID range \ yes | Extra sub-range| 1283 | \ exhausted ? /---->| assignment | 1284 | \-------------/ +----------------+ 1285 | | no | 1286 | +---------------------+ 1287 | | 1288 | V 1289 | +---------------+ 1290 | | .sid file | 1291 | | update based | 1292 | | on previous | 1293 | | .sid file | 1294 | +---------------+ 1295 | | 1296 | V 1297 | /-------------\ +---------------+ 1298 | / Publicly \ yes | YANG module | 1299 | \ available ? /---->| registration | 1300 | \-------------/ +---------------+ 1301 | | no | 1302 +--------------+---------------------+ 1303 | 1304 [DONE] 1306 Figure 2: YANG and SID file update 1308 Authors' Addresses 1309 Michel Veillette (editor) 1310 Trilliant Networks Inc. 1311 610 Rue du Luxembourg 1312 Granby, Quebec J2J 2V2 1313 Canada 1315 Phone: +14503750556 1316 Email: michel.veillette@trilliant.com 1318 Alexander Pelov (editor) 1319 Acklio 1320 1137A avenue des Champs Blancs 1321 Cesson-Sevigne, Bretagne 35510 1322 France 1324 Email: a@ackl.io 1326 Ivaylo Petrov (editor) 1327 Acklio 1328 1137A avenue des Champs Blancs 1329 Cesson-Sevigne, Bretagne 35510 1330 France 1332 Email: ivaylo@ackl.io