idnits 2.17.1 draft-ietf-core-sid-18.txt: -(9): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There are 2 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 16 instances of too long lines in the document, the longest one being 7 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 271 has weird spacing: '...evision rev...' == Line 273 has weird spacing: '...y-point sid...' == Line 277 has weird spacing: '...ntifier uni...' -- The document date (18 November 2021) is 883 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 1808, but not defined == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-17 == Outdated reference: A later version (-24) exists of draft-ietf-anima-constrained-voucher-14 == Outdated reference: A later version (-17) exists of draft-ietf-core-comi-11 Summary: 1 error (**), 0 flaws (~~), 9 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force M.V. Veillette, Ed. 3 Internet-Draft Trilliant Networks Inc. 4 Intended status: Standards Track A.P. Pelov, Ed. 5 Expires: 22 May 2022 Acklio 6 I. Petrov, Ed. 7 Google Switzerland GmbH 8 C. Bormann 9 Universität Bremen TZI 10 M. Richardson 11 Sandelman Software Works 12 18 November 2021 14 YANG Schema Item iDentifier (YANG SID) 15 draft-ietf-core-sid-18 17 Abstract 19 YANG Schema Item iDentifiers (YANG SID) are globally unique 63-bit 20 unsigned integers used to identify YANG items, as a more compact 21 method to identify YANG items that can be used for efficiency and in 22 constrained environments (RFC 7228). This document defines the 23 semantics, the registration, and assignment processes of YANG SIDs 24 for IETF managed YANG modules. To enable the implementation of these 25 processes, this document also defines a file format used to persist 26 and publish assigned YANG SIDs. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on 22 May 2022. 45 Copyright Notice 47 Copyright (c) 2021 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 52 license-info) in effect on the date of publication of this document. 53 Please review these documents carefully, as they describe your rights 54 and restrictions with respect to this document. Code Components 55 extracted from this document must include Revised BSD License text as 56 described in Section 4.e of the Trust Legal Provisions and are 57 provided without warranty as described in the Revised BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 4 63 3. ".sid" file lifecycle . . . . . . . . . . . . . . . . . . . . 5 64 4. ".sid" file format . . . . . . . . . . . . . . . . . . . . . 6 65 5. Content-Types . . . . . . . . . . . . . . . . . . . . . . . . 13 66 6. Security Considerations . . . . . . . . . . . . . . . . . . . 13 67 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 68 7.1. YANG Namespace Registration . . . . . . . . . . . . . . . 14 69 7.2. Register ".sid" File Format Module . . . . . . . . . . . 14 70 7.3. Create new IANA Registry: "YANG SID Mega-Range" 71 registry . . . . . . . . . . . . . . . . . . . . . . . . 15 72 7.3.1. Structure . . . . . . . . . . . . . . . . . . . . . . 15 73 7.3.2. Allocation policy . . . . . . . . . . . . . . . . . . 15 74 7.3.2.1. First allocation . . . . . . . . . . . . . . . . 16 75 7.3.2.2. Consecutive allocations . . . . . . . . . . . . . 16 76 7.3.3. Initial contents of the Registry . . . . . . . . . . 16 77 7.4. Create a new IANA Registry: IETF YANG SID Range Registry 78 (managed by IANA) . . . . . . . . . . . . . . . . . . . . 17 79 7.4.1. Structure . . . . . . . . . . . . . . . . . . . . . . 17 80 7.4.2. Allocation policy . . . . . . . . . . . . . . . . . . 17 81 7.4.3. Publication of the ".sid" file . . . . . . . . . . . 18 82 7.4.4. Initial contents of the registry . . . . . . . . . . 19 83 7.5. Create new IANA Registry: "IETF YANG SID Registry" . . . 21 84 7.5.1. Structure . . . . . . . . . . . . . . . . . . . . . . 21 85 7.5.2. Allocation policy . . . . . . . . . . . . . . . . . . 21 86 7.5.3. Recursive Allocation of YANG SID Range at Document 87 Adoption . . . . . . . . . . . . . . . . . . . . . . 22 88 7.5.4. Initial contents of the registry . . . . . . . . . . 23 89 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 90 8.1. Normative References . . . . . . . . . . . . . . . . . . 23 91 8.2. Informative References . . . . . . . . . . . . . . . . . 24 92 Appendix A. ".sid" file example . . . . . . . . . . . . . . . . 26 93 Appendix B. SID auto generation . . . . . . . . . . . . . . . . 36 94 Appendix C. ".sid" file lifecycle . . . . . . . . . . . . . . . 37 95 C.1. ".sid" File Creation . . . . . . . . . . . . . . . . . . 37 96 C.2. ".sid" File Update . . . . . . . . . . . . . . . . . . . 38 97 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 39 98 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 40 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 40 101 1. Introduction 103 Some of the items defined in YANG [RFC7950] require the use of a 104 unique identifier. In both Network Configuration Protocol (NETCONF) 105 [RFC6241] and RESTCONF [RFC8040], these identifiers are implemented 106 using names. To allow the implementation of data models defined in 107 YANG in constrained devices [RFC7228] and constrained networks, a 108 more compact method to identify YANG items is required. This compact 109 identifier, called YANG Schema Item iDentifier or YANG SID (or simply 110 SID in this document and when the context is clear), is encoded using 111 a 63-bit unsigned integer. The limitation to 63-bit unsigned 112 integers allows SIDs to be manipulated more easily on platforms that 113 might otherwise lack 64-bit unsigned arithmetic. The loss of a 114 single bit of range is not significant given the size of the 115 remaining space. 117 The following items are identified using SIDs: 119 * identities 121 * data nodes (Note: including those nodes defined by the 'yang-data' 122 extension.) 124 * remote procedure calls (RPCs) and associated input(s) and 125 output(s) 127 * actions and associated input(s) and output(s) 129 * notifications and associated information 131 * YANG modules and features 133 It is possible that some protocols use only a subset of the assigned 134 SIDs, for example, for protocols equivalent to NETCONF [RFC6241] like 135 [I-D.ietf-core-comi] the transportation of YANG module SIDs might be 136 unnecessary. Other protocols might need to be able to transport this 137 information, for example protocols related to discovery such as 138 Constrained YANG Module Library [I-D.ietf-core-yang-library]. 140 SIDs are globally unique integers. A registration system is used in 141 order to guarantee their uniqueness. SIDs are registered in blocks 142 called "SID ranges". 144 SIDs are assigned permanently. Items introduced by a new revision of 145 a YANG module are added to the list of SIDs already assigned. 146 Assignment of SIDs to YANG items are usually automated as discussed 147 in Appendix B, which also discusses some cases where manual 148 interventions may be appropriate. 150 Section 3 provides more details about the registration process of 151 YANG modules and associated SIDs. To enable the implementation of 152 this registry, Section 4 defines a standard file format used to store 153 and publish SIDs. 155 IETF managed YANG modules that need to allocate SIDs use the IANA 156 mechanism specified in this document. YANG modules created by other 157 parties allocate SID ranges using the IANA allocation mechanisms via 158 Mega-Ranges (see Section 7.3); within the Mega-Range allocation, 159 those other parties are free to make up their own mechanism. 161 At the time of writing, a tool for automated ".sid" file generation 162 is available as part of the open-source project PYANG [PYANG]. 164 2. Terminology and Notation 166 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 167 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 168 "OPTIONAL" in this document are to be interpreted as described in 169 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 170 capitals, as shown here. 172 The following terms are defined in [RFC7950]: 174 * action 176 * feature 178 * module 180 * notification 182 * RPC 184 * schema node 186 * schema tree 188 * submodule 190 The following term is defined in [RFC8040]: 192 * yang-data extension 194 This specification also makes use of the following terminology: 196 * item: A schema node, an identity, a module, or a feature defined 197 using the YANG modeling language. 199 * schema-node path: A schema-node path is a string that identifies a 200 schema node within the schema tree. A path consists of the list 201 of consecutive schema node identifier(s) separated by slashes 202 ("/"). Schema node identifier(s) are always listed from the top- 203 level schema node up to the targeted schema node and could contain 204 namespace information. (e.g. "/ietf-system:system-state/clock/ 205 current-datetime") 207 * Namespace-qualified form - a schema node identifier is prefixed 208 with the name of the module in which the schema node is defined, 209 separated from the schema node identifier by the colon character 210 (":"). 212 * YANG Schema Item iDentifier (YANG SID or simply SID): Unsigned 213 integer used to identify different YANG items. 215 3. ".sid" file lifecycle 217 YANG is a language designed to model data accessed using one of the 218 compatible protocols (e.g. NETCONF [RFC6241], RESTCONF [RFC8040] and 219 CORECONF [I-D.ietf-core-comi]). A YANG module defines hierarchies of 220 data, including configuration, state data, RPCs, actions and 221 notifications. 223 Many YANG modules are not created in the context of constrained 224 applications. YANG modules can be implemented using NETCONF 225 [RFC6241] or RESTCONF [RFC8040] without the need to assign SIDs. 227 As needed, authors of YANG modules can assign SIDs to their YANG 228 modules. In order to do that, they should first obtain a SID range 229 from a registry and use that range to assign or generate SIDs to 230 items of their YANG module. The assignments can then be stored in a 231 ".sid" file. For example on how this could be achieved, please refer 232 to Appendix C. 234 Registration of the ".sid" file associated to a YANG module is 235 optional but recommended to promote interoperability between devices 236 and to avoid duplicate allocation of SIDs to a single YANG module. 237 Different registries might have different requirements for the 238 registration and publication of the ".sid" files. For a diagram of 239 one of the possibilities, please refer to the activity diagram on 240 Figure 4 in Appendix C. 242 Each time a YANG module or one of its imported module(s) or included 243 sub-module(s) is updated, a new ".sid" file MAY be created if the new 244 or updated items will need SIDs. All the SIDs present in the 245 previous version of the ".sid" file MUST be present in the new 246 version as well. The creation of this new version of the ".sid" file 247 SHOULD be performed using an automated tool. 249 If a new revision requires more SIDs than initially allocated, a new 250 SID range MUST be added to the 'assignment-range' as defined in 251 Section 4. These extra SIDs are used for subsequent assignments. 253 For an example of this update process, see activity diagram Figure 5 254 in Appendix C. 256 4. ".sid" file format 258 ".sid" files are used to persist and publish SIDs assigned to the 259 different YANG items of a specific YANG module. It has the following 260 structure. 262 module: ietf-sid-file 264 structure sid-file: 265 +-- module-name yang:yang-identifier 266 +-- module-revision? revision-identifier 267 +-- sid-file-version? sid-file-version-identifier 268 +-- description? string 269 +-- dependency-revision* [module-name] 270 | +-- module-name yang:yang-identifier 271 | +-- module-revision revision-identifier 272 +-- assignment-range* [entry-point] 273 | +-- entry-point sid 274 | +-- size uint64 275 +-- item* [namespace identifier] 276 +-- namespace enumeration 277 +-- identifier union 278 +-- sid sid 280 Figure 1: YANG tree for ietf-sid-file 282 The following YANG module defines the structure of this file, 283 encoding is performed in JSON [RFC8259] using the rules defined in 284 [RFC7951]. It references ietf-yang-types defined in [RFC6991] and 285 ietf-restconf defined in [RFC8040]. 287 RFC Ed.: please update the date of the module and Copyright if needed 288 and remove this note. 290 file "ietf-sid-file@2021-11-16.yang" 291 module ietf-sid-file { 292 yang-version 1.1; 293 namespace "urn:ietf:params:xml:ns:yang:ietf-sid-file"; 294 prefix sid; 296 import ietf-yang-types { 297 prefix yang; 298 reference "RFC 6991: Common YANG Data Types."; 299 } 300 import ietf-yang-structure-ext { 301 prefix sx; 302 reference "RFC 8791: YANG Data Structure Extensions."; 303 } 305 organization 306 "IETF Core Working Group"; 308 contact 309 "WG Web: 311 WG List: 313 Editor: Michel Veillette 314 316 Editor: Andy Bierman 317 319 Editor: Alexander Pelov 320 322 Editor: Ivaylo Petrov 323 "; 325 description 326 "Copyright (c) 2021 IETF Trust and the persons identified as 327 authors of the code. All rights reserved. 329 Redistribution and use in source and binary forms, with or 330 without modification, is permitted pursuant to, and subject to 331 the license terms contained in, the Simplified BSD License set 332 forth in Section 4.c of the IETF Trust's Legal Provisions 333 Relating to IETF Documents 334 (https://trustee.ietf.org/license-info). 336 This version of this YANG module is part of RFC XXXX 337 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself 338 for full legal notices. 340 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 341 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 342 'MAY', and 'OPTIONAL' in this document are to be interpreted as 343 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 344 they appear in all capitals, as shown here. 346 This module defines the structure of the .sid files. 348 Each .sid file contains the mapping between each 349 string identifier defined by a YANG module and a 350 corresponding numeric value called YANG SID."; 352 revision 2021-11-16 { 353 description 354 "Initial revision."; 355 reference 356 "[RFC XXXX] YANG Schema Item iDentifier (YANG SID)"; 357 } 359 typedef revision-identifier { 360 type string { 361 pattern '\d{4}-\d{2}-\d{2}'; 362 } 363 description 364 "Represents a date in YYYY-MM-DD format."; 365 } 367 typedef sid-file-version-identifier { 368 type uint32; 369 description 370 "Represents the version of a .sid file."; 371 } 373 typedef sid { 374 type uint64 { 375 range "0..9223372036854775807"; 376 } 377 description 378 "YANG Schema Item iDentifier"; 379 reference 380 "[RFC XXXX] YANG Schema Item iDentifier (YANG SID)"; 381 } 383 typedef schema-node-path { 384 type string { 385 pattern 386 '/[a-zA-Z_][a-zA-Z0-9\-_.]*:[a-zA-Z_][a-zA-Z0-9\-_.]*' + 387 '(/[a-zA-Z_][a-zA-Z0-9\-_.]*(:[a-zA-Z_][a-zA-Z0-9\-_.]*)?)*'; 388 } 389 description 390 "A schema-node path is an absolute YANG schema node identifier 391 as defined by the YANG ABNF rule absolute-schema-nodeid, 392 except that module names are used instead of prefixes. 394 This string additionally follows the following rules: 396 o The leftmost (top-level) data node name is always in the 397 namespace-qualified form. 398 o Any subsequent schema node name is in the 399 namespace-qualified form if the node is defined in a module 400 other than its parent node, and the simple form is used 401 otherwise. No predicates are allowed."; 402 reference 403 "RFC 7950, The YANG 1.1 Data Modeling Language; 404 Section 6.5: Schema Node Identifier;"; 405 } 407 sx:structure sid-file { 408 uses sid-file-contents; 409 } 411 grouping sid-file { 412 description "A grouping that contains a YANG container 413 representing the file structure of a .sid files."; 415 container sid-file { 416 description 417 "A Wrapper container that together with the rc:yang-data 418 extension marks the YANG data structures inside as not being 419 intended to be implemented as part of a configuration 420 datastore or as an operational state within the server."; 421 uses sid-file-contents; 422 } 423 } 425 grouping sid-file-contents { 426 description 427 "A grouping that defines the contents of a container that 428 represente the file structure of a .sid files."; 430 leaf module-name { 431 type yang:yang-identifier; 432 mandatory true; 433 description 434 "Name of the YANG module associated with this .sid file."; 435 } 437 leaf module-revision { 438 type revision-identifier; 439 description 440 "Revision of the YANG module associated with this .sid 441 file. 442 This leaf is not present if no revision statement is 443 defined in the YANG module."; 444 } 446 leaf sid-file-version { 447 type sid-file-version-identifier; 448 default 0; 449 description 450 "Optional leaf that specifies the version number of the 451 .sid file. .sid files and the version sequence are 452 specific to a given YANG module revision. This number 453 starts at zero when there is a new YANG module revision and 454 increases monotonically. This number can distinguish 455 updates to the .sid file which are the result of new 456 processing, or the result of reported errata."; 457 } 459 leaf description { 460 type string; 461 description 462 "Free-form meta information about the generated file. It 463 might include .sid file generation tool and time among 464 other things."; 465 } 467 list dependency-revision { 468 key "module-name"; 470 description 471 "Information about the used revision during the .sid file 472 generation of each YANG module that the module in 473 'module-name' imported."; 475 leaf module-name { 476 type yang:yang-identifier; 477 description 478 "Name of the YANG module, dependency of 'module-name', 479 for which revision information is provided."; 480 } 481 leaf module-revision { 482 type revision-identifier; 483 mandatory true; 484 description 485 "Revision of the YANG module, dependency of 486 'module-name', for which revision information is 487 provided."; 488 } 489 } 491 list assignment-range { 492 key "entry-point"; 493 description 494 "YANG SID range(s) allocated to the YANG module identified 495 by 'module-name' and 'module-revision'. 497 - The YANG SID range first available value is entry-point 498 and the last available value in the range is 499 (entry-point + size - 1). 500 - The YANG SID ranges specified by all assignment-rages 501 MUST NOT overlap."; 503 leaf entry-point { 504 type sid; 505 description 506 "Lowest YANG SID available for assignment."; 507 } 509 leaf size { 510 type uint64; 511 mandatory true; 512 description 513 "Number of YANG SIDs available for assignment."; 514 } 515 } 517 list item { 518 key "namespace identifier"; 519 unique "sid"; 521 description 522 "Each entry within this list defined the mapping between 523 a YANG item string identifier and a YANG SID. This list 524 MUST include a mapping entry for each YANG item defined by 525 the YANG module identified by 'module-name' and 526 'module-revision'."; 528 leaf namespace { 529 type enumeration { 530 enum module { 531 value 0; 532 description 533 "All module and submodule names share the same 534 global module identifier namespace."; 535 } 536 enum identity { 537 value 1; 538 description 539 "All identity names defined in a module and its 540 submodules share the same identity identifier 541 namespace."; 542 } 543 enum feature { 544 value 2; 545 description 546 "All feature names defined in a module and its 547 submodules share the same feature identifier 548 namespace."; 549 } 550 enum data { 551 value 3; 552 description 553 "The namespace for all data nodes, as defined in 554 YANG."; 555 } 556 } 557 description 558 "Namespace of the YANG item for this mapping entry."; 559 } 561 leaf identifier { 562 type union { 563 type yang:yang-identifier; 564 type schema-node-path; 565 } 566 description 567 "String identifier of the YANG item for this mapping 568 entry. 570 If the corresponding 'namespace' field is 'module', 571 'feature', or 'identity', then this field MUST 572 contain a valid YANG identifier string. 574 If the corresponding 'namespace' field is 'data', 575 then this field MUST contain a valid schema node 576 path."; 577 } 579 leaf sid { 580 type sid; 581 mandatory true; 582 description 583 "YANG SID assigned to the YANG item for this mapping 584 entry."; 585 } 586 } 587 } 588 } 589 591 Figure 2: YANG module ietf-sid-file 593 5. Content-Types 595 The following Content-Type has been defined in 596 [I-D.ietf-core-yang-cbor]: 598 application/yang-data+cbor; id=sid: This Content-Type represents a 599 CBOR YANG document containing one or multiple data node values. 600 Each data node is identified by its associated SID. 602 FORMAT: CBOR map of SID, instance-value 604 The message payload of Content-Type 'application/yang-data+cbor' 605 is encoded using a CBOR map. Each entry within the CBOR map 606 contains the data node identifier (i.e. SID) and the associated 607 instance-value. Instance-values are encoded using the rules 608 defined in Section 4 of [I-D.ietf-core-yang-cbor]. 610 6. Security Considerations 612 This document defines a new type of identifier used to encode data 613 that are modeled in YANG [RFC7950]. This new identifier maps 614 semantic concepts to integers, and if the source of this mapping is 615 not trusted, then new security risks might occur if an attacker can 616 control the mapping. 618 At the time of writing, it is expected that the SID files will be 619 processed by a software developer, within a software development 620 environment. Developers are advised to only import SID files from 621 authoritative sources. IANA is the authoritative source for IETF 622 managed YANG modules. 624 Conceptually, SID files could be processed by less-constrained target 625 systems such as network management systems. Such systems need to 626 take extra care to make sure that they are only processing SID files 627 from authoritative sources, as authoritative as the YANG modules that 628 they are using. 630 7. IANA Considerations 632 7.1. YANG Namespace Registration 634 This document registers the following XML namespace URN in the "IETF 635 XML Registry", following the format defined in [RFC3688]: 637 URI: please assign urn:ietf:params:xml:ns:yang:ietf-sid-file 639 Registrant Contact: The IESG. 641 XML: N/A, the requested URI is an XML namespace. 643 Reference: RFC XXXX 645 // RFC Ed.: please replace XXXX with RFC number and remove this note 647 7.2. Register ".sid" File Format Module 649 This document registers one YANG module in the "YANG Module Names" 650 registry [RFC6020]: 652 * name: ietf-sid-file 654 * namespace: urn:ietf:params:xml:ns:yang:ietf-sid-file 656 * prefix: sid 658 * reference: RFC XXXX 660 // RFC Ed.: please replace XXXX with RFC number and remove this note 662 7.3. Create new IANA Registry: "YANG SID Mega-Range" registry 664 The name of this registry is "YANG SID Mega-Range". This registry is 665 used to record the delegation of the management of a block of SIDs to 666 third parties (such as SDOs or registrars). 668 7.3.1. Structure 670 Each entry in this registry must include: 672 * The entry point (first SID) of the registered SID block. 674 * The size of the registered SID block. The size SHOULD be one 675 million (1 000 000) SIDs, it MAY exceptionally be a multiple of 676 1 000 000. 678 * The contact information of the requesting organization including: 680 - The policy of SID range allocations: Public, Private or Both. 682 - Organization name 684 - URL 686 7.3.2. Allocation policy 688 The IANA policy for future additions to this registry is "Expert 689 Review" [RFC8126]. 691 An organization requesting to manage a YANG SID Range (and thus have 692 an entry in the YANG SID Mega-Range Registry), must ensure the 693 following capacities: 695 * The capacity to manage and operate a YANG SID Range Registry. A 696 YANG SID Range Registry MUST provide the following information for 697 all YANG SID Ranges allocated by the Registry: 699 - Entry Point of allocated YANG SID Range 701 - Size of allocated YANG SID Range 703 - Type: Public or Private 705 o Public Ranges MUST include at least a reference to the YANG 706 module and ".sid" files for that YANG SID Range (e.g., 707 compare Section 7.4.3 for the IETF YANG SID registry). 709 o Private Ranges MUST be marked as "Private" 711 * A Policy of allocation, which clearly identifies if the YANG SID 712 Range allocations would be Private, Public or Both. 714 * Technical capacity to ensure the sustained operation of the 715 registry for a period of at least 5 years. If Private 716 Registrations are allowed, the period must be of at least 10 717 years. 719 If a size of the allocation beyond 1 000 000 is desired, the 720 organization must demonstrate the sustainability of the technical 721 approach for utilizing this size of allocation and how it does not 722 negatively impact the overall usability of the SID allocation 723 mechanisms; such allocations are preferably placed in the space above 724 4 295 000 000 (64-bit space). 726 7.3.2.1. First allocation 728 For a first allocation to be provided, the requesting organization 729 must demonstrate a functional registry infrastructure. 731 7.3.2.2. Consecutive allocations 733 On subsequent allocation request(s), the organization must 734 demonstrate the exhaustion of the prior range. These conditions need 735 to be asserted by the assigned expert(s). 737 If that extra-allocation is done within 3 years from the last 738 allocation, the experts need to discuss this request on the CORE 739 working group mailing list and consensus needs to be obtained before 740 allocating a new Mega-Range. 742 7.3.3. Initial contents of the Registry 744 The initial entry in this registry is allocated to IANA: 746 +=============+=========+============+===================+==========+ 747 | Entry Point | Size | Allocation | Organization | URL | 748 | | | | name | | 749 +=============+=========+============+===================+==========+ 750 | 0 | 1000000 | Public | IANA | iana.org | 751 +-------------+---------+------------+-------------------+----------+ 753 Table 1 755 7.4. Create a new IANA Registry: IETF YANG SID Range Registry (managed 756 by IANA) 758 7.4.1. Structure 760 Each entry in this registry must include: 762 * The SID range entry point. 764 * The SID range size. 766 * The YANG module name. 768 * Document reference. 770 7.4.2. Allocation policy 772 The first million SIDs assigned to IANA is sub-divided as follows: 774 * The range of 0 to 999 (size 1000) is subject to "IESG Approval" as 775 defined in [RFC8126]; of these, SID value 0 has been reserved for 776 implementations to internally signify the absence of a SID number 777 and does not occur in interchange. 779 * The range of 1000 to 59,999 (size 59,000) is designated for YANG 780 modules defined in RFCs. 782 - The IANA policy for additions to this registry is either: 784 o "Expert Review" [RFC8126] in case the ".sid" file comes from 785 a YANG module from an existing RFC, or 787 o "RFC Required" [RFC8126] otherwise. 789 - The Expert MUST verify that the YANG module for which this 790 allocation is made has an RFC (existing RFC) OR is on track to 791 become RFC (early allocation with a request from the WG chairs 792 as defined by [BCP100]). 794 * The range of 60,000 to 99,999 (size 40,000) is reserved for 795 experimental YANG modules. This range MUST NOT be used in 796 operational deployments since these SIDs are not globally unique 797 which limit their interoperability. The IANA policy for this 798 range is "Experimental use" [RFC8126]. 800 * The range of 100,000 to 999,999 (size 900,000) is "Reserved" as 801 defined in [RFC8126]. 803 +=============+=========+==========================+ 804 | Entry Point | Size | IANA policy | 805 +=============+=========+==========================+ 806 | 0 | 1,000 | IESG Approval | 807 +-------------+---------+--------------------------+ 808 | 1,000 | 59,000 | RFC Required | 809 +-------------+---------+--------------------------+ 810 | 60,000 | 40,000 | Experimental/Private use | 811 +-------------+---------+--------------------------+ 812 | 100,000 | 900,000 | Reserved | 813 +-------------+---------+--------------------------+ 815 Table 2 817 The size of the SID range allocated for a YANG module is recommended 818 to be a multiple of 50 and to be at least 33% above the current 819 number of YANG items. This headroom allows assignment within the 820 same range of new YANG items introduced by subsequent revisions. The 821 SID range size SHOULD NOT exceed 1000; a larger size may be requested 822 by the authors if this recommendation is considered insufficient. It 823 is important to note that an additional SID range can be allocated to 824 an existing YANG module if the initial range is exhausted; this then 825 just leads to slightly less efficient representation. 827 In case a SID range is allocated for an existing RFC through the 828 "Expert Review" policy, the Document reference field for the given 829 allocation should point to the RFC that the YANG module is defined 830 in. 832 In case a SID range is required before publishing the RFC due to 833 implementations needing stable SID values, early allocation as 834 defined in [BCP100] can be employed. As specified in Section 4.6 of 835 [RFC8126], RFCs and by extension documents that are expected to 836 become an RFC fulfill the requirement for "Specification Required" 837 stated in Section 2 of [BCP100], which allows for the early 838 allocation process to be employed. 840 7.4.3. Publication of the ".sid" file 842 For a YANG module approved for publication as an RFC, a ".sid" file 843 SHOULD be included in the Internet-Draft as a source code block. 844 This ".sid" file is to be extracted by IANA/the expert reviewer and 845 put into the YANG SID Registry (Section 7.5) along with the YANG 846 module. The ".sid" file MUST NOT be published as part of the RFC: 847 the IANA Registry is authoritative and a link is to be inserted in 848 the RFC. 850 7.4.4. Initial contents of the registry 852 Initial entries in this registry are as follows: 854 +=======+=====+==============+======================================+ 855 | Entry | Size|Module name | Document reference | 856 | Point | | | | 857 +=======+=====+==============+======================================+ 858 | 0 | 1|(Reserved: not| RFCXXXX | 859 | | |a valid SID) | | 860 +-------+-----+--------------+--------------------------------------+ 861 | 1000 | 100|ietf-coreconf | [I-D.ietf-core-comi] | 862 +-------+-----+--------------+--------------------------------------+ 863 | 1100 | 50|ietf-yang- | [RFC6991] | 864 | | |types | | 865 +-------+-----+--------------+--------------------------------------+ 866 | 1150 | 50|ietf-inet- | [RFC6991] | 867 | | |types | | 868 +-------+-----+--------------+--------------------------------------+ 869 | 1200 | 50|iana-crypt- | [RFC7317] | 870 | | |hash | | 871 +-------+-----+--------------+--------------------------------------+ 872 | 1250 | 50|ietf-netconf- | [RFC8341] | 873 | | |acm | | 874 +-------+-----+--------------+--------------------------------------+ 875 | 1300 | 50|ietf-sid-file | RFCXXXX | 876 +-------+-----+--------------+--------------------------------------+ 877 | 1500 | 100|ietf- | [RFC8343] | 878 | | |interfaces | | 879 +-------+-----+--------------+--------------------------------------+ 880 | 1600 | 100|ietf-ip | [RFC8344] | 881 +-------+-----+--------------+--------------------------------------+ 882 | 1700 | 100|ietf-system | [RFC7317] | 883 +-------+-----+--------------+--------------------------------------+ 884 | 1800 | 400|iana-if-type | [RFC7224] | 885 +-------+-----+--------------+--------------------------------------+ 886 | 2400 | 50|ietf-voucher | [RFC8366] | 887 +-------+-----+--------------+--------------------------------------+ 888 | 2450 | 50|ietf- | [I-D.ietf-anima-constrained-voucher] | 889 | | |constrained- | | 890 | | |voucher | | 891 +-------+-----+--------------+--------------------------------------+ 892 | 2500 | 50|ietf- | [I-D.ietf-anima-constrained-voucher] | 893 | | |constrained- | | 894 | | |voucher- | | 895 | | |request | | 896 +-------+-----+--------------+--------------------------------------+ 898 Table 3 900 // RFC Ed.: replace XXXX with RFC number assigned to this draft. 902 For allocation, RFC publication of the YANG module is required as per 903 [RFC8126]. The YANG module must be registered in the "YANG module 904 Name" registry according to the rules specified in Section 14 of 905 [RFC6020]. 907 7.5. Create new IANA Registry: "IETF YANG SID Registry" 909 The name of this registry is "IETF YANG SID Registry". This registry 910 is used to record the allocation of SIDs for individual YANG module 911 items. 913 7.5.1. Structure 915 Each entry in this registry must include: 917 * The YANG module name. This module name must be present in the 918 "Name" column of the "YANG Module Names" registry. 920 * A link to the associated ".yang" file. This file link must be 921 present in the "File" column of the "YANG Module Names" registry. 923 * The link to the ".sid" file which defines the allocation. The 924 ".sid" file is stored by IANA. 926 * The number of actually allocated SIDs in the ".sid" file. 928 7.5.2. Allocation policy 930 The allocation policy is Expert review. The Expert MUST ensure that 931 the following conditions are met: 933 * The ".sid" file has a valid structure: 935 - The ".sid" file MUST be a valid JSON file following the 936 structure of the module defined in RFCXXXX (RFC Ed: replace XXX 937 with RFC number assigned to this draft). 939 * The ".sid" file allocates individual SIDs ONLY in the YANG SID 940 Ranges for this YANG module (as allocated in the IETF YANG SID 941 Range Registry): 943 - All SIDs in this ".sid" file MUST be within the ranges 944 allocated to this YANG module in the "IETF YANG SID Range 945 Registry". 947 * If another ".sid" file has already allocated SIDs for this YANG 948 module (e.g. for older or newer versions of the YANG module), the 949 YANG items are assigned the same SIDs as in the other ".sid" file. 951 * If there is an older version of the ".sid" file, all allocated 952 SIDs from that version are still present in the current version of 953 the ".sid" file. 955 7.5.3. Recursive Allocation of YANG SID Range at Document Adoption 957 Due to the difficulty in changing SID values during IETF document 958 processing, it is expected that most documents will ask for SID 959 allocations using Early Allocations [BCP100]. The details of the 960 Early Allocation should be included in any Working Group Adoption 961 call. Prior to Working Group Adoption, an internet draft author can 962 use the experimental SID range (as per Section 7.4.2) for their SIDs 963 allocations or other values that do not create ambiguity with other 964 SID uses (for example they can use a range that comes from a non-IANA 965 managed "YANG SID Mega-Range" registry). 967 After Working Group Adoption, any modification of a ".sid" file is 968 expected to be discussed on the mailing list of the appropriate 969 Working Groups. Specific attention should be paid to implementers' 970 opinion after Working Group Last Call if a SID value is to change its 971 meaning. In all cases, a ".sid" file and the SIDs associated with it 972 are subject to change before the publication of an internet draft as 973 an RFC. 975 During the early use of SIDs, many existing, previously published 976 YANG modules will not have SID allocations. For an allocation to be 977 useful the included YANG modules may also need to have SID 978 allocations made. 980 The Expert Reviewer who performs the (Early) Allocation analysis will 981 need to go through the list of included YANG modules and perform SID 982 allocations for those modules as well. 984 * If the document is a published RFC, then the allocation of SIDs 985 for its referenced YANG modules is permanent. The Expert Reviewer 986 provides the generated ".sid" file to IANA for registration. This 987 process may be time-consuming during a bootstrap period (there are 988 over 100 YANG modules to date, none of which have SID 989 allocations), but should quiet down once needed entries are 990 allocated. 992 * If the document is an unprocessed Internet-Draft adopted in a WG, 993 then an Early Allocation is performed for this document as well. 994 Early Allocations require approval by an IESG Area Director. An 995 early allocation which requires additional allocations will list 996 the other allocations in its description, and will be cross-posted 997 to the any other working group mailing lists. 999 * A YANG module which references a module in a document which has 1000 not yet been adopted by any working group will be unable to 1001 perform an Early Allocation for that other document until it is 1002 adopted by a working group. As described in [BCP100], an AD 1003 Sponsored document acts as if it had a working group. The 1004 approving AD may also exempt a document from this policy by 1005 agreeing to AD Sponsor the document. 1007 At the end of the IETF process all the dependencies of a given module 1008 for which SIDs are assigned, should also have SIDs assigned. Those 1009 dependencies' assignments should be permanent (not Early Allocation). 1011 A previously SID-allocated YANG module which changes its references 1012 to include a YANG module for which there is no SID allocation needs 1013 to repeat the Early Allocation process. 1015 Early Allocations are made with a one-year period, after which they 1016 are expired. [BCP100] indicates that at most one renewal may be 1017 made. For the SID allocation a far more lenient stance is desired. 1019 1. An extension of a referencing documents Early Allocation should 1020 update any referenced Early Allocations to expire no sooner than 1021 the referencing document. 1023 2. The [BCP100] mechanism allows the IESG to provide a second 1024 renewal, and such an event may prompt some thought about how the 1025 collection of documents are being processed. 1027 This is driven by the very generous size of the SID space and the 1028 often complex and deep dependencies of YANG modules. Often a core 1029 module with many dependencies will undergo extensive review, delaying 1030 the publication of other documents. 1032 [BCP100] also says: 1034 Note that if a document is submitted for review to the IESG and at 1035 the time of submission some early allocations are valid (not 1036 expired), these allocations should not be expired while the document 1037 is under IESG consideration or waiting in the RFC Editor's queue 1038 after approval by the IESG. 1040 7.5.4. Initial contents of the registry 1042 None. 1044 8. References 1046 8.1. Normative References 1048 [BCP100] Cotton, M., "Early IANA Allocation of Standards Track Code 1049 Points", BCP 100, RFC 7120, January 2014. 1051 1053 [I-D.ietf-core-yang-cbor] 1054 Veillette, M., Petrov, I., Pelov, A., Bormann, C., and M. 1055 Richardson, "CBOR Encoding of Data Modeled with YANG", 1056 Work in Progress, Internet-Draft, draft-ietf-core-yang- 1057 cbor-17, 25 October 2021, 1058 . 1061 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1062 Requirement Levels", BCP 14, RFC 2119, 1063 DOI 10.17487/RFC2119, March 1997, 1064 . 1066 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1067 DOI 10.17487/RFC3688, January 2004, 1068 . 1070 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1071 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1072 . 1074 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1075 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1076 . 1078 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 1079 RFC 7951, DOI 10.17487/RFC7951, August 2016, 1080 . 1082 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1083 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1084 . 1086 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1087 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1088 May 2017, . 1090 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1091 Interchange Format", STD 90, RFC 8259, 1092 DOI 10.17487/RFC8259, December 2017, 1093 . 1095 8.2. Informative References 1097 [I-D.ietf-anima-constrained-voucher] 1098 Richardson, M., Stok, P. V. D., Kampanakis, P., and E. 1099 Dijk, "Constrained Bootstrapping Remote Secure Key 1100 Infrastructure (BRSKI)", Work in Progress, Internet-Draft, 1101 draft-ietf-anima-constrained-voucher-14, 25 October 2021, 1102 . 1105 [I-D.ietf-core-comi] 1106 Veillette, M., Stok, P. V. D., Pelov, A., Bierman, A., and 1107 I. Petrov, "CoAP Management Interface (CORECONF)", Work in 1108 Progress, Internet-Draft, draft-ietf-core-comi-11, 17 1109 January 2021, . 1112 [I-D.ietf-core-yang-library] 1113 Veillette, M. and I. Petrov, "Constrained YANG Module 1114 Library", Work in Progress, Internet-Draft, draft-ietf- 1115 core-yang-library-03, 11 January 2021, 1116 . 1119 [PYANG] Bjorklund, M., "An extensible YANG validator and converter 1120 in python", . 1122 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1123 the Network Configuration Protocol (NETCONF)", RFC 6020, 1124 DOI 10.17487/RFC6020, October 2010, 1125 . 1127 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1128 and A. Bierman, Ed., "Network Configuration Protocol 1129 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1130 . 1132 [RFC7224] Bjorklund, M., "IANA Interface Type YANG Module", 1133 RFC 7224, DOI 10.17487/RFC7224, May 2014, 1134 . 1136 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1137 Constrained-Node Networks", RFC 7228, 1138 DOI 10.17487/RFC7228, May 2014, 1139 . 1141 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1142 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1143 2014, . 1145 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1146 Writing an IANA Considerations Section in RFCs", BCP 26, 1147 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1148 . 1150 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1151 Access Control Model", STD 91, RFC 8341, 1152 DOI 10.17487/RFC8341, March 2018, 1153 . 1155 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 1156 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 1157 . 1159 [RFC8344] Bjorklund, M., "A YANG Data Model for IP Management", 1160 RFC 8344, DOI 10.17487/RFC8344, March 2018, 1161 . 1163 [RFC8366] Watsen, K., Richardson, M., Pritikin, M., and T. Eckert, 1164 "A Voucher Artifact for Bootstrapping Protocols", 1165 RFC 8366, DOI 10.17487/RFC8366, May 2018, 1166 . 1168 Appendix A. ".sid" file example 1170 The following ".sid" file (ietf-system@2014-08-06.sid) has been 1171 generated using the following yang modules: 1173 * ietf-system@2014-08-06.yang (defined in [RFC7317]) 1175 * ietf-yang-types@2013-07-15.yang (defined in [RFC6991]) 1177 * ietf-inet-types@2013-07-15.yang (defined in [RFC6991]) 1179 * ietf-netconf-acm@2018-02-14.yang (defined in [RFC8341]) 1181 * iana-crypt-hash@2014-08-06.yang (defined in [RFC7317]) 1183 For purposes of exposition, line breaks have been introduced below in 1184 some JSON strings that represent overly long identifiers. 1186 { 1187 "ietf-sid-file:sid-file" : { 1188 "module-name": "ietf-system", 1189 "module-revision": "2014-08-06", 1190 "dependency-revision": [ 1191 { 1192 "module-name": "ietf-yang-types", 1193 "module-revision": "2013-07-15" 1194 }, 1195 { 1196 "module-name": "ietf-inet-types", 1197 "module-revision": "2013-07-15" 1198 }, 1199 { 1200 "module-name": "ietf-netconf-acm", 1201 "module-revision": "2018-02-14" 1202 }, 1203 { 1204 "module-name": "iana-crypt-hash", 1205 "module-revision": "2014-08-06" 1206 } 1207 ], 1208 "description": "Example sid file", 1209 "assignment-range": [ 1210 { 1211 "entry-point": 1700, 1212 "size": 100 1213 } 1214 ], 1215 "item": [ 1216 { 1217 "namespace": "module", 1218 "identifier": "ietf-system", 1219 "sid": 1700 1220 }, 1221 { 1222 "namespace": "identity", 1223 "identifier": "authentication-method", 1224 "sid": 1701 1225 }, 1226 { 1227 "namespace": "identity", 1228 "identifier": "local-users", 1229 "sid": 1702 1230 }, 1231 { 1232 "namespace": "identity", 1233 "identifier": "radius", 1234 "sid": 1703 1235 }, 1236 { 1237 "namespace": "identity", 1238 "identifier": "radius-authentication-type", 1239 "sid": 1704 1240 }, 1241 { 1242 "namespace": "identity", 1243 "identifier": "radius-chap", 1244 "sid": 1705 1245 }, 1246 { 1247 "namespace": "identity", 1248 "identifier": "radius-pap", 1249 "sid": 1706 1250 }, 1251 { 1252 "namespace": "feature", 1253 "identifier": "authentication", 1254 "sid": 1707 1255 }, 1256 { 1257 "namespace": "feature", 1258 "identifier": "dns-udp-tcp-port", 1259 "sid": 1708 1260 }, 1261 { 1262 "namespace": "feature", 1263 "identifier": "local-users", 1264 "sid": 1709 1265 }, 1266 { 1267 "namespace": "feature", 1268 "identifier": "ntp", 1269 "sid": 1710 1270 }, 1271 { 1272 "namespace": "feature", 1273 "identifier": "ntp-udp-port", 1274 "sid": 1711 1275 }, 1276 { 1277 "namespace": "feature", 1278 "identifier": "radius", 1279 "sid": 1712 1280 }, 1281 { 1282 "namespace": "feature", 1283 "identifier": "radius-authentication", 1284 "sid": 1713 1285 }, 1286 { 1287 "namespace": "feature", 1288 "identifier": "timezone-name", 1289 "sid": 1714 1290 }, 1291 { 1292 "namespace": "data", 1293 "identifier": "/ietf-system:set-current-datetime", 1294 "sid": 1715 1295 }, 1296 { 1297 "namespace": "data", 1298 "identifier": "/ietf-system:set-current-datetime/ 1299 current-datetime", 1300 "sid": 1716 1301 }, 1302 { 1303 "namespace": "data", 1304 "identifier": "/ietf-system:system", 1305 "sid": 1717 1306 }, 1307 { 1308 "namespace": "data", 1309 "identifier": "/ietf-system:system-restart", 1310 "sid": 1718 1311 }, 1312 { 1313 "namespace": "data", 1314 "identifier": "/ietf-system:system-shutdown", 1315 "sid": 1719 1316 }, 1317 { 1318 "namespace": "data", 1319 "identifier": "/ietf-system:system-state", 1320 "sid": 1720 1321 }, 1322 { 1323 "namespace": "data", 1324 "identifier": "/ietf-system:system-state/clock", 1325 "sid": 1721 1326 }, 1327 { 1328 "namespace": "data", 1329 "identifier": "/ietf-system:system-state/clock/boot-datetime", 1330 "sid": 1722 1331 }, 1332 { 1333 "namespace": "data", 1334 "identifier": "/ietf-system:system-state/clock/ 1335 current-datetime", 1336 "sid": 1723 1338 }, 1339 { 1340 "namespace": "data", 1341 "identifier": "/ietf-system:system-state/platform", 1342 "sid": 1724 1343 }, 1344 { 1345 "namespace": "data", 1346 "identifier": "/ietf-system:system-state/platform/machine", 1347 "sid": 1725 1348 }, 1349 { 1350 "namespace": "data", 1351 "identifier": "/ietf-system:system-state/platform/os-name", 1352 "sid": 1726 1353 }, 1354 { 1355 "namespace": "data", 1356 "identifier": "/ietf-system:system-state/platform/os-release", 1357 "sid": 1727 1358 }, 1359 { 1360 "namespace": "data", 1361 "identifier": "/ietf-system:system-state/platform/os-version", 1362 "sid": 1728 1363 }, 1364 { 1365 "namespace": "data", 1366 "identifier": "/ietf-system:system/authentication", 1367 "sid": 1729 1368 }, 1369 { 1370 "namespace": "data", 1371 "identifier": "/ietf-system:system/authentication/user", 1372 "sid": 1730 1373 }, 1374 { 1375 "namespace": "data", 1376 "identifier": "/ietf-system:system/authentication/ 1377 user-authentication-order", 1378 "sid": 1731 1379 }, 1380 { 1381 "namespace": "data", 1382 "identifier": "/ietf-system:system/authentication/user/ 1383 authorized-key", 1384 "sid": 1732 1385 }, 1386 { 1387 "namespace": "data", 1388 "identifier": "/ietf-system:system/authentication/user/ 1389 authorized-key/algorithm", 1390 "sid": 1733 1391 }, 1392 { 1393 "namespace": "data", 1394 "identifier": "/ietf-system:system/authentication/user/ 1395 authorized-key/key-data", 1396 "sid": 1734 1397 }, 1398 { 1399 "namespace": "data", 1400 "identifier": "/ietf-system:system/authentication/user/ 1401 authorized-key/name", 1402 "sid": 1735 1403 }, 1404 { 1405 "namespace": "data", 1406 "identifier": "/ietf-system:system/authentication/user/ 1407 name", 1408 "sid": 1736 1409 }, 1410 { 1411 "namespace": "data", 1412 "identifier": "/ietf-system:system/authentication/user/ 1413 password", 1414 "sid": 1737 1415 }, 1416 { 1417 "namespace": "data", 1418 "identifier": "/ietf-system:system/clock", 1419 "sid": 1738 1420 }, 1421 { 1422 "namespace": "data", 1423 "identifier": "/ietf-system:system/clock/timezone-name", 1424 "sid": 1739 1425 }, 1426 { 1427 "namespace": "data", 1428 "identifier": "/ietf-system:system/clock/timezone-utc-offset", 1429 "sid": 1740 1430 }, 1431 { 1432 "namespace": "data", 1433 "identifier": "/ietf-system:system/contact", 1434 "sid": 1741 1435 }, 1436 { 1437 "namespace": "data", 1438 "identifier": "/ietf-system:system/dns-resolver", 1439 "sid": 1742 1440 }, 1441 { 1442 "namespace": "data", 1443 "identifier": "/ietf-system:system/dns-resolver/options", 1444 "sid": 1743 1445 }, 1446 { 1447 "namespace": "data", 1448 "identifier": "/ietf-system:system/dns-resolver/options/ 1449 attempts", 1450 "sid": 1744 1451 }, 1452 { 1453 "namespace": "data", 1454 "identifier": "/ietf-system:system/dns-resolver/options/ 1455 timeout", 1456 "sid": 1745 1457 }, 1458 { 1459 "namespace": "data", 1460 "identifier": "/ietf-system:system/dns-resolver/search", 1461 "sid": 1746 1462 }, 1463 { 1464 "namespace": "data", 1465 "identifier": "/ietf-system:system/dns-resolver/server", 1466 "sid": 1747 1467 }, 1468 { 1469 "namespace": "data", 1470 "identifier": "/ietf-system:system/dns-resolver/server/name", 1471 "sid": 1748 1472 }, 1473 { 1474 "namespace": "data", 1475 "identifier": "/ietf-system:system/dns-resolver/server/ 1476 udp-and-tcp", 1477 "sid": 1749 1478 }, 1479 { 1480 "namespace": "data", 1481 "identifier": "/ietf-system:system/dns-resolver/server/ 1482 udp-and-tcp/address", 1483 "sid": 1750 1484 }, 1485 { 1486 "namespace": "data", 1487 "identifier": "/ietf-system:system/dns-resolver/server/ 1488 udp-and-tcp/port", 1489 "sid": 1751 1490 }, 1491 { 1492 "namespace": "data", 1493 "identifier": "/ietf-system:system/hostname", 1494 "sid": 1752 1495 }, 1496 { 1497 "namespace": "data", 1498 "identifier": "/ietf-system:system/location", 1499 "sid": 1753 1500 }, 1501 { 1502 "namespace": "data", 1503 "identifier": "/ietf-system:system/ntp", 1504 "sid": 1754 1505 }, 1506 { 1507 "namespace": "data", 1508 "identifier": "/ietf-system:system/ntp/enabled", 1509 "sid": 1755 1510 }, 1511 { 1512 "namespace": "data", 1513 "identifier": "/ietf-system:system/ntp/server", 1514 "sid": 1756 1515 }, 1516 { 1517 "namespace": "data", 1518 "identifier": "/ietf-system:system/ntp/server/ 1519 association-type", 1520 "sid": 1757 1521 }, 1522 { 1523 "namespace": "data", 1524 "identifier": "/ietf-system:system/ntp/server/iburst", 1525 "sid": 1758 1526 }, 1527 { 1528 "namespace": "data", 1529 "identifier": "/ietf-system:system/ntp/server/name", 1530 "sid": 1759 1531 }, 1532 { 1533 "namespace": "data", 1534 "identifier": "/ietf-system:system/ntp/server/prefer", 1535 "sid": 1760 1536 }, 1537 { 1538 "namespace": "data", 1539 "identifier": "/ietf-system:system/ntp/server/udp", 1540 "sid": 1761 1541 }, 1542 { 1543 "namespace": "data", 1544 "identifier": "/ietf-system:system/ntp/server/udp/address", 1545 "sid": 1762 1546 }, 1547 { 1548 "namespace": "data", 1549 "identifier": "/ietf-system:system/ntp/server/udp/port", 1550 "sid": 1763 1551 }, 1552 { 1553 "namespace": "data", 1554 "identifier": "/ietf-system:system/radius", 1555 "sid": 1764 1556 }, 1557 { 1558 "namespace": "data", 1559 "identifier": "/ietf-system:system/radius/options", 1560 "sid": 1765 1561 }, 1562 { 1563 "namespace": "data", 1564 "identifier": "/ietf-system:system/radius/options/attempts", 1565 "sid": 1766 1566 }, 1567 { 1568 "namespace": "data", 1569 "identifier": "/ietf-system:system/radius/options/timeout", 1570 "sid": 1767 1571 }, 1572 { 1573 "namespace": "data", 1574 "identifier": "/ietf-system:system/radius/server", 1575 "sid": 1768 1576 }, 1577 { 1578 "namespace": "data", 1579 "identifier": "/ietf-system:system/radius/server/ 1580 authentication-type", 1581 "sid": 1769 1582 }, 1583 { 1584 "namespace": "data", 1585 "identifier": "/ietf-system:system/radius/server/name", 1586 "sid": 1770 1587 }, 1588 { 1589 "namespace": "data", 1590 "identifier": "/ietf-system:system/radius/server/udp", 1591 "sid": 1771 1592 }, 1593 { 1594 "namespace": "data", 1595 "identifier": "/ietf-system:system/radius/server/udp/ 1596 address", 1597 "sid": 1772 1598 }, 1599 { 1600 "namespace": "data", 1601 "identifier": "/ietf-system:system/radius/server/udp/ 1602 authentication-port", 1603 "sid": 1773 1604 }, 1605 { 1606 "namespace": "data", 1607 "identifier": "/ietf-system:system/radius/server/udp/ 1608 shared-secret", 1609 "sid": 1774 1610 } 1611 ] 1612 } 1613 } 1615 Figure 3: Example .sid file (ietf-system, with extra line-breaks) 1617 For reconstructing the actual JSON file from this figure, all line 1618 breaks that occur in what would be JSON strings need to be removed, 1619 including any following blank space (indentation) on the line after 1620 the line break; in each such case, a single identifier without any 1621 embedded blank space results. This removal can be accomplished with 1622 this simple Ruby script: 1624 @u = %{[^"\n]*}; @q = @u + '"' 1625 puts ARGF.read.gsub(/^(#@q(#@q#@q)*#@u) *\n +(#@q)/, "\\1\\3") 1627 Appendix B. SID auto generation 1629 Assignment of SIDs to YANG items SHOULD be automated. The 1630 recommended process to assign SIDs is as follows: 1632 1. A tool extracts the different items defined for a specific YANG 1633 module. 1635 2. The list of items is sorted in alphabetical order, 'namespace' in 1636 descending order, 'identifier' in ascending order. The 1637 'namespace' and 'identifier' formats are described in the YANG 1638 module 'ietf-sid-file' defined in Section 4. 1640 3. SIDs are assigned sequentially from the entry point up to the 1641 size of the registered SID range. This approach is recommended 1642 to minimize the serialization overhead, especially when delta 1643 between a reference SID and the current SID is used by protocols 1644 aiming to reduce message size. 1646 4. If the number of items exceeds the SID range(s) allocated to a 1647 YANG module, an extra range is added for subsequent assignments. 1649 5. The "dependency-revision" should reflect the revision numbers of 1650 each YANG module that the YANG module imports at the moment of 1651 the generation. 1653 When updating a YANG module that is in active use, the existing SID 1654 assignments are maintained. (In contrast, when evolving an early 1655 draft that has not yet been adopted by a community of developers, SID 1656 assignments are often better done from scratch after a revision.) If 1657 the name of a schema node changes, but the data remain structurally 1658 and semantically similar to what was previously available under an 1659 old name, the SID that was used for the old name MAY continue to be 1660 used for the new name. If the meaning of an item changes, a new SID 1661 MAY be assigned to it; this is particularly useful to allow the new 1662 SID to identify the new structure or semantics of the item. If the 1663 YANG data type changes in a new revision of a published module, such 1664 that the resulting CBOR encoding is changed, then implementations 1665 will be aided significantly if a new SID is assigned. Note that 1666 these decisions are generally at the discretion of the YANG module 1667 author, who should decide if the benefits of a manual intervention 1668 are worth the deviation from automatic assignment. 1670 In case of an update to an existing ".sid" file, an additional step 1671 is needed that increments the ".sid" file version number. If there 1672 was no version number in the previous version of the ".sid" file, 0 1673 is assumed as the version number of the old version of the ".sid" 1674 file and the version number is 1 for the new ".sid" file. Apart from 1675 that, changes of ".sid" files can also be automated using the same 1676 method described above, only unassigned YANG items are processed at 1677 step #3. Already existing items in the ".sid" file should not be 1678 given new SIDs. 1680 Note that ".sid" file versions are specific to a YANG module 1681 revision. For each new YANG module or each new revision of an 1682 existing YANG module, the version number of the initial ".sid" file 1683 should either be 0 or should not be present. 1685 Note also that RPC or action "input" and "output" data nodes MUST 1686 always be assigned SID even if they don't contain data nodes. The 1687 reason for this requirement is that other modules can augment the 1688 given module and those SIDs might be necessary. 1690 Appendix C. ".sid" file lifecycle 1692 Before assigning SIDs to their YANG modules, YANG module authors must 1693 acquire a SID range from a "YANG SID Range Registry". If the YANG 1694 module is part of an IETF draft or RFC, the SID range need to be 1695 acquired from the "IETF YANG SID Range Registry" as defined in 1696 Section 7.4. For the other YANG modules, the authors can acquire a 1697 SID range from any "YANG SID Range Registry" of their choice. 1699 Once the SID range is acquired, owners can use it to generate ".sid" 1700 file/s for their YANG module/s. It is recommended to leave some 1701 unallocated SIDs following the allocated range in each ".sid" file in 1702 order to allow better evolution of the YANG module in the future. 1703 Generation of ".sid" files should be performed using an automated 1704 tool. Note that ".sid" files can only be generated for YANG modules 1705 and not for submodules. 1707 C.1. ".sid" File Creation 1709 The following activity diagram summarizes the creation of a YANG 1710 module and its associated ".sid" file. 1712 +---------------+ 1713 o | Creation of a | 1714 -+- -->| YANG module | 1715 / \ +------+--------+ 1716 | 1717 v 1718 .-------------. 1719 / Standardized \ yes 1720 \ YANG module ? /------------+ 1721 '-----+-------' | 1722 | no | 1723 v v 1724 .-------------. +---------------+ 1725 +--> / Constrained \ yes | SID range | 1726 | \ application ? /---->| registration |<---------+ 1727 | '-----+-------' +------+--------+ | 1728 | | no | | 1729 | v v | 1730 | +---------------+ +---------------+ | 1731 +----+ YANG module | | SID sub-range | | 1732 | update | | assignment |<----------+ 1733 +---------------+ +-------+-------+ | 1734 | | 1735 v | 1736 +---------------+ +------+------+ 1737 | ".sid" file | | Rework YANG | 1738 | generation | | module | 1739 +-------+-------+ +-------------+ 1740 | ^ 1741 v | 1742 .----------. yes | 1743 / Work in \ -----------+ 1744 \ progress / 1745 '----+-----' 1746 | no 1747 v 1748 .-------------. .-------------. 1749 / RFC \ no / Open \ no 1750 \ publication? /---> \ specification?/---+ 1751 '------+------' '------+------' | 1752 yes | | yes | 1753 | .------------' | 1754 | / | 1755 v v v 1756 +---------------+ +---------------+ 1757 | IANA | | Third party | 1758 | registration | | registration | 1759 +-------+-------+ +---------+-----+ 1760 | | 1761 +---------------------------------+ 1762 v 1763 [DONE] 1765 Figure 4: SID Lifecycle 1767 C.2. ".sid" File Update 1769 The following Activity diagram summarizes the update of a YANG module 1770 and its associated ".sid" file. 1772 +---------------+ 1773 o | Update of the | 1774 -+- -->| YANG module | 1775 / \ | or include(s) | 1776 | or import(s) | 1777 +------+--------+ 1778 | 1779 v 1780 .-------------. 1781 / New items \ yes 1782 \ created ? /------+ 1783 '------+------' | 1784 | no v 1785 | .-------------. +----------------+ 1786 | / SID range \ yes | Extra sub-range| 1787 | \ exhausted ? /---->| assignment | 1788 | '------+------' +-------+--------+ 1789 | | no | 1790 | +---------------------+ 1791 | | 1792 | v 1793 | +---------------+ 1794 | | ".sid" file | 1795 | | update based | 1796 | | on previous | 1797 | | ".sid" file | 1798 | +-------+-------+ 1799 | | 1800 | v 1801 | .-------------. +---------------+ 1802 | / Publicly \ yes | YANG module | 1803 | \ available ? /---->| registration | 1804 | '------+------' +-------+-------+ 1805 | | no | 1806 +--------------+---------------------+ 1807 | 1808 [DONE] 1810 Figure 5: YANG and ".sid" file update 1812 Acknowledgments 1814 The authors would like to thank Andy Bierman, Michael Richardson, 1815 Abhinav Somaraju, Peter van der Stok, Laurent Toutain and Randy 1816 Turner for their help during the development of this document and 1817 their useful comments during the review process. 1819 Contributors 1821 Andy Bierman 1822 YumaWorks 1823 685 Cochran St. 1824 Suite #160 1825 Simi Valley, CA 93065 1826 United States of America 1828 Email: andy@yumaworks.com 1830 Authors' Addresses 1832 Michel Veillette (editor) 1833 Trilliant Networks Inc. 1834 610 Rue du Luxembourg 1835 Granby Quebec J2J 2V2 1836 Canada 1838 Phone: +14503750556 1839 Email: michel.veillette@trilliant.com 1841 Alexander Pelov (editor) 1842 Acklio 1843 1137A avenue des Champs Blancs 1844 35510 Cesson-Sevigne 1845 France 1847 Email: a@ackl.io 1849 Ivaylo Petrov (editor) 1850 Google Switzerland GmbH 1851 Brandschenkestrasse 110 1852 CH-8002 Zurich 1853 Switzerland 1855 Email: ivaylopetrov@google.com 1857 Carsten Bormann 1858 Universität Bremen TZI 1859 Postfach 330440 1860 D-28359 Bremen 1861 Germany 1862 Phone: +49-421-218-63921 1863 Email: cabo@tzi.org 1865 Michael Richardson 1866 Sandelman Software Works 1868 Email: mcr+ietf@sandelman.ca