idnits 2.17.00 (12 Aug 2021) /tmp/idnits40552/draft-ietf-core-sid-17.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 12 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 (26 October 2021) is 207 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 1764, but not defined == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-16 == Outdated reference: A later version (-17) exists of draft-ietf-anima-constrained-voucher-14 Summary: 1 error (**), 0 flaws (~~), 8 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: 29 April 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 26 October 2021 14 YANG Schema Item iDentifier (YANG SID) 15 draft-ietf-core-sid-17 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 29 April 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 Simplified BSD License text 56 as described in Section 4.e of the Trust Legal Provisions and are 57 provided without warranty as described in the Simplified 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 . . . . . . . . . . . . . . . . . . . . . 13 68 7.1. YANG Namespace Registration . . . . . . . . . . . . . . . 13 69 7.2. Register ".sid" File Format Module . . . . . . . . . . . 14 70 7.3. CoAP Content-Formats Registry . . . . . . . . . . . . . . 14 71 7.4. Create new IANA Registry: "YANG SID Mega-Range" 72 registry . . . . . . . . . . . . . . . . . . . . . . . . 14 73 7.4.1. Structure . . . . . . . . . . . . . . . . . . . . . . 14 74 7.4.2. Allocation policy . . . . . . . . . . . . . . . . . . 15 75 7.4.2.1. First allocation . . . . . . . . . . . . . . . . 15 76 7.4.2.2. Consecutive allocations . . . . . . . . . . . . . 15 77 7.4.3. Initial contents of the Registry . . . . . . . . . . 16 78 7.5. Create a new IANA Registry: IETF YANG SID Range Registry 79 (managed by IANA) . . . . . . . . . . . . . . . . . . . . 16 80 7.5.1. Structure . . . . . . . . . . . . . . . . . . . . . . 16 81 7.5.2. Allocation policy . . . . . . . . . . . . . . . . . . 16 82 7.5.3. Initial contents of the registry . . . . . . . . . . 18 83 7.6. Create new IANA Registry: "IETF YANG SID Registry" . . . 20 84 7.6.1. Structure . . . . . . . . . . . . . . . . . . . . . . 20 85 7.6.2. Allocation policy . . . . . . . . . . . . . . . . . . 20 86 7.6.3. Recursive Allocation of YANG SID Range at Document 87 Adoption . . . . . . . . . . . . . . . . . . . . . . 21 88 7.6.4. Initial contents of the registry . . . . . . . . . . 22 89 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 90 8.1. Normative References . . . . . . . . . . . . . . . . . . 22 91 8.2. Informative References . . . . . . . . . . . . . . . . . 23 92 Appendix A. ".sid" file example . . . . . . . . . . . . . . . . 25 93 Appendix B. SID auto generation . . . . . . . . . . . . . . . . 34 94 Appendix C. ".sid" file lifecycle . . . . . . . . . . . . . . . 36 95 C.1. ".sid" File Creation . . . . . . . . . . . . . . . . . . 36 96 C.2. ".sid" File Update . . . . . . . . . . . . . . . . . . . 37 97 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 38 98 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 39 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 39 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 SHOULD be automated. For more 147 details how this can be achieved, and when manual interventions may 148 be appropriate, see Appendix B. 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 which need to allocate SIDs, MUST use the 156 IANA mechanism specified in this document. For YANG modules created 157 by other parties, the use of IANA allocation mechanisms via use of 158 Mega-Ranges (see Section 7.4) is RECOMMENDED. Within the Mega-Range 159 allocation, those other parties are free to make up their own 160 mechanism. 162 At the time of writing, a tool for automated SID file generation is 163 available as part of the open-source project PYANG [PYANG]. 165 2. Terminology and Notation 167 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 168 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 169 "OPTIONAL" in this document are to be interpreted as described in 170 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 171 capitals, as shown here. 173 The following terms are defined in [RFC7950]: 175 * action 177 * feature 179 * module 181 * notification 183 * RPC 185 * schema node 187 * schema tree 189 * submodule 191 The following term is defined in [RFC8040]: 193 * yang-data extension 195 This specification also makes use of the following terminology: 197 * item: A schema node, an identity, a module, or a feature defined 198 using the YANG modeling language. 200 * schema-node path: A schema-node path is a string that identifies a 201 schema node within the schema tree. A path consists of the list 202 of consecutive schema node identifier(s) separated by slashes 203 ("/"). Schema node identifier(s) are always listed from the top- 204 level schema node up to the targeted schema node and could contain 205 namespace information. (e.g. "/ietf-system:system-state/clock/ 206 current-datetime") 208 * Namespace-qualified form - a schema node identifier is prefixed 209 with the name of the module in which the schema node is defined, 210 separated from the schema node identifier by the colon character 211 (":"). 213 * YANG Schema Item iDentifier (YANG SID or simply SID): Unsigned 214 integer used to identify different YANG items. 216 3. ".sid" file lifecycle 218 YANG is a language designed to model data accessed using one of the 219 compatible protocols (e.g. NETCONF [RFC6241], RESTCONF [RFC8040] and 220 CORECONF [I-D.ietf-core-comi]). A YANG module defines hierarchies of 221 data, including configuration, state data, RPCs, actions and 222 notifications. 224 Many YANG modules are not created in the context of constrained 225 applications. YANG modules can be implemented using NETCONF 226 [RFC6241] or RESTCONF [RFC8040] without the need to assign SIDs. 228 As needed, authors of YANG modules can assign SIDs to their YANG 229 modules. In order to do that, they should first obtain a SID range 230 from a registry and use that range to assign or generate SIDs to 231 items of their YANG module. The assignments can then be stored in a 232 ".sid" file. For example on how this could be achieved, please refer 233 to Appendix C. 235 Registration of the ".sid" file associated to a YANG module is 236 optional but recommended to promote interoperability between devices 237 and to avoid duplicate allocation of SIDs to a single YANG module. 238 Different registries might have different requirements for the 239 registration and publication of the ".sid" files. For a diagram of 240 one of the possibilities, please refer to the activity diagram on 241 Figure 1 in Appendix C. 243 Each time a YANG module or one of its imported module(s) or included 244 sub-module(s) is updated, a new ".sid" file MAY be created if the new 245 or updated items will need SIDs. All the SIDs present in the 246 previous version of the ".sid" file MUST be present in the new 247 version as well. The creation of this new version of the ".sid" file 248 SHOULD be performed using an automated tool. 250 If a new revision requires more SIDs than initially allocated, a new 251 SID range MUST be added to the 'assignment-range' as defined in 252 Section 4. These extra SIDs are used for subsequent assignments. 254 For an example of this update process, see activity diagram Figure 2 255 in Appendix C. 257 4. ".sid" file format 259 ".sid" files are used to persist and publish SIDs assigned to the 260 different YANG items of a specific YANG module. It has the following 261 structure. 263 module: ietf-sid-file 264 +-- 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 The following YANG module defines the structure of this file, 281 encoding is performed in JSON [RFC8259] using the rules defined in 282 [RFC7951]. It references ietf-yang-types defined in [RFC6991] and 283 ietf-restconf defined in [RFC8040]. 285 RFC Ed.: please update the date of the module and Copyright if needed 286 and remove this note. 288 file "ietf-sid-file@2020-02-05.yang" 289 module ietf-sid-file { 290 yang-version 1.1; 291 namespace "urn:ietf:params:xml:ns:yang:ietf-sid-file"; 292 prefix sid; 294 import ietf-yang-types { 295 prefix yang; 296 reference "RFC 6991: Common YANG Data Types."; 297 } 298 import ietf-restconf { 299 prefix rc; 300 reference "RFC 8040: RESTCONF Protocol."; 301 } 303 organization 304 "IETF Core Working Group"; 306 contact 307 "WG Web: 309 WG List: 311 Editor: Michel Veillette 312 314 Editor: Andy Bierman 315 317 Editor: Alexander Pelov 318 320 Editor: Ivaylo Petrov 321 "; 323 description 324 "Copyright (c) 2021 IETF Trust and the persons identified as 325 authors of the code. All rights reserved. 327 Redistribution and use in source and binary forms, with or 328 without modification, is permitted pursuant to, and subject to 329 the license terms contained in, the Simplified BSD License set 330 forth in Section 4.c of the IETF Trust's Legal Provisions 331 Relating to IETF Documents 332 (https://trustee.ietf.org/license-info). 334 This version of this YANG module is part of RFC XXXX 335 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself 336 for full legal notices. 338 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 339 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 340 'MAY', and 'OPTIONAL' in this document are to be interpreted as 341 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 342 they appear in all capitals, as shown here. 344 This module defines the structure of the .sid files. 346 Each .sid file contains the mapping between each 347 string identifier defined by a YANG module and a 348 corresponding numeric value called YANG SID."; 350 revision 2020-02-05 { 351 description 352 "Initial revision."; 353 reference 354 "[RFC XXXX] YANG Schema Item iDentifier (YANG SID)"; 355 } 357 typedef revision-identifier { 358 type string { 359 pattern '\d{4}-\d{2}-\d{2}'; 360 } 361 description 362 "Represents a date in YYYY-MM-DD format."; 363 } 365 typedef sid-file-version-identifier { 366 type uint32; 367 description 368 "Represents the version of a .sid file."; 369 } 371 typedef sid { 372 type uint64 { 373 range "0..9223372036854775807"; 374 } 375 description 376 "YANG Schema Item iDentifier"; 377 reference 378 "[RFC XXXX] YANG Schema Item iDentifier (YANG SID)"; 379 } 381 typedef schema-node-path { 382 type string { 383 pattern 384 '/[a-zA-Z_][a-zA-Z0-9\-_.]*:[a-zA-Z_][a-zA-Z0-9\-_.]*' + 385 '(/[a-zA-Z_][a-zA-Z0-9\-_.]*(:[a-zA-Z_][a-zA-Z0-9\-_.]*)?)*'; 386 } 387 description 388 "A schema-node path is an absolute YANG schema node identifier 389 as defined by the YANG ABNF rule absolute-schema-nodeid, 390 except that module names are used instead of prefixes. 392 This string additionally follows the following rules: 394 o The leftmost (top-level) data node name is always in the 395 namespace-qualified form. 396 o Any subsequent schema node name is in the 397 namespace-qualified form if the node is defined in a module 398 other than its parent node, and the simple form is used 399 otherwise. No predicates are allowed."; 400 reference 401 "RFC 7950, The YANG 1.1 Data Modeling Language; 402 Section 6.5: Schema Node Identifier;"; 403 } 405 rc:yang-data sid-file { 406 uses sid-file; 407 } 409 grouping sid-file { 410 description "A grouping that contains a YANG container 411 representing the file structure of a .sid files."; 413 container sid-file { 414 description 415 "A Wrapper container that together with the rc:yang-data 416 extension marks the YANG data structures inside as not being 417 intended to be implemented as part of a configuration 418 datastore or as an operational state within the server."; 419 leaf module-name { 420 type yang:yang-identifier; 421 description 422 "Name of the YANG module associated with this .sid file."; 423 } 424 leaf module-revision { 425 type revision-identifier; 426 description 427 "Revision of the YANG module associated with this .sid 428 file. 429 This leaf is not present if no revision statement is 430 defined in the YANG module."; 431 } 433 leaf sid-file-version { 434 type sid-file-version-identifier; 435 default 0; 436 description 437 "Optional leaf that specifies the version number of the 438 .sid file. .sid files and the version sequence are 439 specific to a given YANG module revision. This number 440 starts at zero when there is a new YANG module revision and 441 increases monotonically. This number can distinguish 442 updates to the .sid file which are the result of new 443 processing, or the result of reported errata."; 444 } 446 leaf description { 447 type string; 448 description 449 "Free-form meta information about the generated file. It 450 might include .sid file generation tool and time among 451 other things."; 452 } 454 list dependency-revision { 455 key "module-name"; 457 description 458 "Information about the used revision during the .sid file 459 generation of each YANG module that the module in 460 'module-name' imported."; 462 leaf module-name { 463 type yang:yang-identifier; 464 description 465 "Name of the YANG module, dependency of 'module-name', 466 for which revision information is provided."; 467 } 468 leaf module-revision { 469 type revision-identifier; 470 mandatory true; 471 description 472 "Revision of the YANG module, dependency of 473 'module-name', for which revision information is 474 provided."; 475 } 476 } 478 list assignment-range { 479 key "entry-point"; 480 description 481 "YANG SID range(s) allocated to the YANG module identified 482 by 'module-name' and 'module-revision'. 484 - The YANG SID range first available value is entry-point 485 and the last available value in the range is 486 (entry-point + size - 1). 487 - The YANG SID ranges specified by all assignment-rages 488 MUST NOT overlap."; 490 leaf entry-point { 491 type sid; 492 description 493 "Lowest YANG SID available for assignment."; 494 } 496 leaf size { 497 type uint64; 498 mandatory true; 499 description 500 "Number of YANG SIDs available for assignment."; 501 } 502 } 504 list item { 505 key "namespace identifier"; 506 unique "sid"; 508 description 509 "Each entry within this list defined the mapping between 510 a YANG item string identifier and a YANG SID. This list 511 MUST include a mapping entry for each YANG item defined by 512 the YANG module identified by 'module-name' and 513 'module-revision'."; 515 leaf namespace { 516 type enumeration { 517 enum module { 518 value 0; 519 description 520 "All module and submodule names share the same 521 global module identifier namespace."; 522 } 523 enum identity { 524 value 1; 525 description 526 "All identity names defined in a module and its 527 submodules share the same identity identifier 528 namespace."; 529 } 530 enum feature { 531 value 2; 532 description 533 "All feature names defined in a module and its 534 submodules share the same feature identifier 535 namespace."; 536 } 537 enum data { 538 value 3; 539 description 540 "The namespace for all data nodes, as defined in 541 YANG."; 542 } 543 } 544 description 545 "Namespace of the YANG item for this mapping entry."; 546 } 548 leaf identifier { 549 type union { 550 type yang:yang-identifier; 551 type schema-node-path; 552 } 553 description 554 "String identifier of the YANG item for this mapping 555 entry. 557 If the corresponding 'namespace' field is 'module', 558 'feature', or 'identity', then this field MUST 559 contain a valid YANG identifier string. 561 If the corresponding 'namespace' field is 'data', 562 then this field MUST contain a valid schema node 563 path."; 564 } 566 leaf sid { 567 type sid; 568 mandatory true; 569 description 570 "YANG SID assigned to the YANG item for this mapping 571 entry."; 572 } 573 } 574 } 575 } 576 } 577 579 5. Content-Types 581 The following Content-Type has been defined in 582 [I-D.ietf-core-yang-cbor]: 584 application/yang-data+cbor; id=sid: This Content-Type represents a 585 CBOR YANG document containing one or multiple data node values. 586 Each data node is identified by its associated SID. 588 FORMAT: CBOR map of SID, instance-value 590 The message payload of Content-Type 'application/yang-data+cbor' 591 is encoded using a CBOR map. Each entry within the CBOR map 592 contains the data node identifier (i.e. SID) and the associated 593 instance-value. Instance-values are encoded using the rules 594 defined in Section 4 of [I-D.ietf-core-yang-cbor]. 596 6. Security Considerations 598 This document defines a new type of identifier used to encode data 599 that are modeled in YANG [RFC7950]. As such, this identifier does 600 not contribute to any new security issues in addition of those 601 identified for the specific protocols or contexts for which it is 602 used. 604 7. IANA Considerations 606 7.1. YANG Namespace Registration 608 This document registers the following XML namespace URN in the "IETF 609 XML Registry", following the format defined in [RFC3688]: 611 URI: please assign urn:ietf:params:xml:ns:yang:ietf-sid-file 613 Registrant Contact: The IESG. 615 XML: N/A, the requested URI is an XML namespace. 617 Reference: RFC XXXX 619 // RFC Ed.: please replace XXXX with RFC number and remove this note 621 7.2. Register ".sid" File Format Module 623 This document registers one YANG module in the "YANG Module Names" 624 registry [RFC6020]: 626 * name: ietf-sid-file 628 * namespace: urn:ietf:params:xml:ns:yang:ietf-sid-file 630 * prefix: sid 632 * reference: RFC XXXX 634 // RFC Ed.: please replace XXXX with RFC number and remove this note 636 7.3. CoAP Content-Formats Registry 638 A Content-Format for application/yang-data+cbor; id=sid has been 639 added to the "CoAP Content-Formats" within the "Constrained RESTful 640 Environments (CoRE) Parameters" registry, in 641 [I-D.ietf-core-yang-cbor]. 643 7.4. Create new IANA Registry: "YANG SID Mega-Range" registry 645 The name of this registry is "YANG SID Mega-Range". This registry is 646 used to record the delegation of the management of a block of SIDs to 647 third parties (such as SDOs or registrars). 649 7.4.1. Structure 651 Each entry in this registry must include: 653 * The entry point (first SID) of the registered SID block. 655 * The size of the registered SID block. The size MUST be one 656 million (1 000 000) SIDs. 658 * The contact information of the requesting organization including: 660 - The policy of SID range allocations: Public, Private or Both. 662 - Organization name 664 - URL 666 The information associated to the Organization name should not be 667 publicly visible in the registry, but should be available. This 668 information includes contact email and phone number and change 669 controller email and phone number. 671 7.4.2. Allocation policy 673 The IANA policy for future additions to this registry is "Expert 674 Review" [RFC8126]. 676 An organization requesting to manage a YANG SID Range (and thus have 677 an entry in the YANG SID Mega-Range Registry), must ensure the 678 following capacities: 680 * The capacity to manage and operate a YANG SID Range Registry. A 681 YANG SID Range Registry MUST provide the following information for 682 all YANG SID Ranges allocated by the Registry: 684 - Entry Point of allocated YANG SID Range 686 - Size of allocated YANG SID Range 688 - Type: Public or Private 690 o Public Ranges MUST include at least a reference to the YANG 691 module and ".sid" files for that YANG SID Range. 693 o Private Ranges MUST be marked as "Private" 695 * A Policy of allocation, which clearly identifies if the YANG SID 696 Range allocations would be Private, Public or Both. 698 * Technical capacity to ensure the sustained operation of the 699 registry for a period of at least 5 years. If Private 700 Registrations are allowed, the period must be of at least 10 701 years. 703 7.4.2.1. First allocation 705 For a first allocation to be provided, the requesting organization 706 must demonstrate a functional registry infrastructure. 708 7.4.2.2. Consecutive allocations 710 On subsequent allocation request(s), the organization must 711 demonstrate the exhaustion of the prior range. These conditions need 712 to be asserted by the assigned expert(s). 714 If that extra-allocation is done within 3 years from the last 715 allocation, the experts need to discuss this request on the CORE 716 working group mailing list and consensus needs to be obtained before 717 allocating a new Mega-Range. 719 7.4.3. Initial contents of the Registry 721 The initial entry in this registry is allocated to IANA: 723 +=============+=========+============+===================+==========+ 724 | Entry Point | Size | Allocation | Organization | URL | 725 | | | | name | | 726 +=============+=========+============+===================+==========+ 727 | 0 | 1000000 | Public | IANA | iana.org | 728 +-------------+---------+------------+-------------------+----------+ 730 Table 1 732 7.5. Create a new IANA Registry: IETF YANG SID Range Registry (managed 733 by IANA) 735 7.5.1. Structure 737 Each entry in this registry must include: 739 * The SID range entry point. 741 * The SID range size. 743 * The YANG module name. 745 * Document reference. 747 7.5.2. Allocation policy 749 The first million SIDs assigned to IANA is sub-divided as follows: 751 * The range of 0 to 999 (size 1000) is "Reserved" as defined in 752 [RFC8126]. 754 * The range of 1000 to 59,999 (size 59,000) is reserved for YANG 755 modules defined in RFCs. 757 - The IANA policy for additions to this registry is either: 759 o "Expert Review" [RFC8126] in case the ".sid" file comes from 760 a YANG module from an existing RFC, or 762 o "RFC Required" [RFC8126] otherwise. 764 - The Expert MUST verify that the YANG module for which this 765 allocation is made has an RFC (existing RFC) OR is on track to 766 become RFC (early allocation with a request from the WG chairs 767 as defined by [BCP100]). 769 * The range of 60,000 to 99,999 (size 40,000) is reserved for 770 experimental YANG modules. This range MUST NOT be used in 771 operational deployments since these SIDs are not globally unique 772 which limit their interoperability. The IANA policy for this 773 range is "Experimental use" [RFC8126]. 775 * The range of 100,000 to 999,999 (size 900,000) is "Reserved" as 776 defined in [RFC8126]. 778 +=============+=========+===============================+ 779 | Entry Point | Size | IANA policy | 780 +=============+=========+===============================+ 781 | 0 | 1,000 | Reserved | 782 +-------------+---------+-------------------------------+ 783 | 1,000 | 59,000 | Expert Review or RFC Required | 784 +-------------+---------+-------------------------------+ 785 | 60,000 | 40,000 | Experimental use | 786 +-------------+---------+-------------------------------+ 787 | 100,000 | 900,000 | Reserved | 788 +-------------+---------+-------------------------------+ 790 Table 2 792 The size of the SID range allocated for a YANG module is recommended 793 to be a multiple of 50 and to be at least 33% above the current 794 number of YANG items. This headroom allows assignment within the 795 same range of new YANG items introduced by subsequent revisions. The 796 SID range size SHOULD NOT exceed 1000; a larger size may be requested 797 by the authors if this recommendation is considered insufficient. It 798 is important to note that an additional SID range can be allocated to 799 an existing YANG module if the initial range is exhausted; this then 800 just leads to slightly less efficient representation. 802 In case a SID range is allocated for an existing RFC through the 803 "Expert Review" policy, the Document reference field for the given 804 allocation should point to the RFC that the YANG module is defined 805 in. 807 In case a SID range is required before publishing the RFC due to 808 implementations needing stable SID values, early allocation as 809 defined in [BCP100] can be employed. As specified in Section 4.6 of 811 [RFC8126], RFCs and by extension documents that are expected to 812 become an RFC fulfill the requirement for "Specification Required" 813 stated in Section 2 of [BCP100], which allows for the early 814 allocation process to be employed. 816 7.5.3. Initial contents of the registry 818 Initial entries in this registry are as follows: 820 +=======+=====+==============+======================================+ 821 | Entry | Size|Module name | Document reference | 822 | Point | | | | 823 +=======+=====+==============+======================================+ 824 | 1000 | 100|ietf-coreconf | [I-D.ietf-core-comi] | 825 +-------+-----+--------------+--------------------------------------+ 826 | 1100 | 50|ietf-yang- | [RFC6991] | 827 | | |types | | 828 +-------+-----+--------------+--------------------------------------+ 829 | 1150 | 50|ietf-inet- | [RFC6991] | 830 | | |types | | 831 +-------+-----+--------------+--------------------------------------+ 832 | 1200 | 50|iana-crypt- | [RFC7317] | 833 | | |hash | | 834 +-------+-----+--------------+--------------------------------------+ 835 | 1250 | 50|ietf-netconf- | [RFC8341] | 836 | | |acm | | 837 +-------+-----+--------------+--------------------------------------+ 838 | 1300 | 50|ietf-sid-file | RFCXXXX | 839 +-------+-----+--------------+--------------------------------------+ 840 | 1500 | 100|ietf- | [RFC8343] | 841 | | |interfaces | | 842 +-------+-----+--------------+--------------------------------------+ 843 | 1600 | 100|ietf-ip | [RFC8344] | 844 +-------+-----+--------------+--------------------------------------+ 845 | 1700 | 100|ietf-system | [RFC7317] | 846 +-------+-----+--------------+--------------------------------------+ 847 | 1800 | 400|iana-if-type | [RFC7224] | 848 +-------+-----+--------------+--------------------------------------+ 849 | 2400 | 50|ietf-voucher | [RFC8366] | 850 +-------+-----+--------------+--------------------------------------+ 851 | 2450 | 50|ietf- | [I-D.ietf-anima-constrained-voucher] | 852 | | |constrained- | | 853 | | |voucher | | 854 +-------+-----+--------------+--------------------------------------+ 855 | 2500 | 50|ietf- | [I-D.ietf-anima-constrained-voucher] | 856 | | |constrained- | | 857 | | |voucher- | | 858 | | |request | | 859 +-------+-----+--------------+--------------------------------------+ 861 Table 3 863 // RFC Ed.: replace XXXX with RFC number assigned to this draft. 865 For allocation, RFC publication of the YANG module is required as per 866 [RFC8126]. The YANG module must be registered in the "YANG module 867 Name" registry according to the rules specified in Section 14 of 868 [RFC6020]. 870 7.6. Create new IANA Registry: "IETF YANG SID Registry" 872 The name of this registry is "IETF YANG SID Registry". This registry 873 is used to record the allocation of SIDs for individual YANG module 874 items. 876 7.6.1. Structure 878 Each entry in this registry must include: 880 * The YANG module name. This module name must be present in the 881 "Name" column of the "YANG Module Names" registry. 883 * A link to the associated ".yang" file. This file link must be 884 present in the "File" column of the "YANG Module Names" registry. 886 * The link to the ".sid" file which defines the allocation. The 887 ".sid" file is stored by IANA. 889 * The number of actually allocated SIDs in the ".sid" file. 891 7.6.2. Allocation policy 893 The allocation policy is Expert review. The Expert MUST ensure that 894 the following conditions are met: 896 * The ".sid" file has a valid structure: 898 - The ".sid" file MUST be a valid JSON file following the 899 structure of the module defined in RFCXXXX (RFC Ed: replace XXX 900 with RFC number assigned to this draft). 902 * The ".sid" file allocates individual SIDs ONLY in the YANG SID 903 Ranges for this YANG module (as allocated in the IETF YANG SID 904 Range Registry): 906 - All SIDs in this ".sid" file MUST be within the ranges 907 allocated to this YANG module in the "IETF YANG SID Range 908 Registry". 910 * If another ".sid" file has already allocated SIDs for this YANG 911 module (e.g. for older or newer versions of the YANG module), the 912 YANG items are assigned the same SIDs as in the other ".sid" file. 914 * If there is an older version of the ".sid" file, all allocated 915 SIDs from that version are still present in the current version of 916 the ".sid" file. 918 7.6.3. Recursive Allocation of YANG SID Range at Document Adoption 920 Due to the difficulty in changing SID values during IETF document 921 processing, it is expected that most documents will ask for SID 922 allocations using Early Allocations [BCP100]. The details of the 923 Early Allocation should be included in any Working Group Adoption 924 call. Prior to Working Group Adoption, an internet draft authors can 925 use the experimental SID range (as per Section 7.5.2) for their SIDs 926 allocations or other values that do not create ambiguity with other 927 SID uses (for example they can use a range that comes from a non-IANA 928 managed "YANG SID Mega-Range" registry). 930 After Working Group Adoption, any modification of a ".sid" file is 931 expected to be discussed on the mailing list of the appropriate 932 Working Groups. Specific attention should be paid to implementers' 933 opinion after Working Group Last Call if a SID value is to change its 934 meaning. In all cases, a ".sid" file and the SIDs associated with it 935 are subject to change before the publication of an internet draft as 936 an RFC. 938 During the early use of SIDs, many existing, previously published 939 YANG modules will not have SID allocations. For an allocation to be 940 useful the included YANG modules may also need to have SID 941 allocations made. 943 The Expert Reviewer who performs the (Early) Allocation analysis will 944 need to go through the list of included YANG modules and perform SID 945 allocations for those modules as well. 947 * If the document is a published RFC, then the allocation of SIDs 948 for its referenced YANG modules is permanent. The Expert Reviewer 949 provides the generated SID file to IANA for registration. This 950 process may be time-consuming during a bootstrap period (there are 951 over 100 YANG modules to date, none of which have SID 952 allocations), but should quiet down once needed entries are 953 allocated. 955 * If the document is an unprocessed Internet-Draft adopted in a WG, 956 then an Early Allocation is performed for this document as well. 957 Early Allocations require approval by an IESG Area Director. An 958 early allocation which requires additional allocations will list 959 the other allocations in its description, and will be cross-posted 960 to the any other working group mailing lists. 962 * A YANG module which references a module in a document which has 963 not yet been adopted by any working group will be unable to 964 perform an Early Allocation for that other document until it is 965 adopted by a working group. As described in [BCP100], an AD 966 Sponsored document acts as if it had a working group. The 967 approving AD may also exempt a document from this policy by 968 agreeing to AD Sponsor the document. 970 At the end of the IETF process all the dependencies of a given module 971 for which SIDs are assigned, should also have SIDs assigned. Those 972 dependencies' assignments should be permanent (not Early Allocation). 974 A previously SID-allocated YANG module which changes its references 975 to include a YANG module for which there is no SID allocation needs 976 to repeat the Early Allocation process. 978 Early Allocations are made with a one-year period, after which they 979 are expired. [BCP100] indicates that at most one renewal may be 980 made. For the SID allocation a far more lenient stance is desired. 982 1. An extension of a referencing documents Early Allocation should 983 update any referenced Early Allocations to expire no sooner than 984 the referencing document. 986 2. The [BCP100] mechanism allows the IESG to provide a second 987 renewal, and such an event may prompt some thought about how the 988 collection of documents are being processed. 990 This is driven by the very generous size of the SID space and the 991 often complex and deep dependencies of YANG modules. Often a core 992 module with many dependencies will undergo extensive review, delaying 993 the publication of other documents. 995 [BCP100] also says: 997 Note that if a document is submitted for review to the IESG and at 998 the time of submission some early allocations are valid (not 999 expired), these allocations should not be expired while the document 1000 is under IESG consideration or waiting in the RFC Editor's queue 1001 after approval by the IESG. 1003 7.6.4. Initial contents of the registry 1005 None. 1007 8. References 1009 8.1. Normative References 1011 [BCP100] Cotton, M., "Early IANA Allocation of Standards Track Code 1012 Points", BCP 100, RFC 7120, January 2014. 1014 1016 [I-D.ietf-core-yang-cbor] 1017 Veillette, M., Petrov, I., Pelov, A., and C. Bormann, 1018 "CBOR Encoding of Data Modeled with YANG", Work in 1019 Progress, Internet-Draft, draft-ietf-core-yang-cbor-16, 24 1020 June 2021, . 1023 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1024 Requirement Levels", BCP 14, RFC 2119, 1025 DOI 10.17487/RFC2119, March 1997, 1026 . 1028 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1029 DOI 10.17487/RFC3688, January 2004, 1030 . 1032 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1033 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1034 . 1036 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1037 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1038 . 1040 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 1041 RFC 7951, DOI 10.17487/RFC7951, August 2016, 1042 . 1044 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1045 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1046 . 1048 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1049 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1050 May 2017, . 1052 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1053 Interchange Format", STD 90, RFC 8259, 1054 DOI 10.17487/RFC8259, December 2017, 1055 . 1057 8.2. Informative References 1059 [I-D.ietf-anima-constrained-voucher] 1060 Richardson, M., Stok, P. V. D., Kampanakis, P., and E. 1061 Dijk, "Constrained Bootstrapping Remote Secure Key 1062 Infrastructure (BRSKI)", Work in Progress, Internet-Draft, 1063 draft-ietf-anima-constrained-voucher-14, 25 October 2021, 1064 . 1067 [I-D.ietf-core-comi] 1068 Veillette, M., Stok, P. V. D., Pelov, A., Bierman, A., and 1069 I. Petrov, "CoAP Management Interface (CORECONF)", Work in 1070 Progress, Internet-Draft, draft-ietf-core-comi-11, 17 1071 January 2021, . 1074 [I-D.ietf-core-yang-library] 1075 Veillette, M. and I. Petrov, "Constrained YANG Module 1076 Library", Work in Progress, Internet-Draft, draft-ietf- 1077 core-yang-library-03, 11 January 2021, 1078 . 1081 [PYANG] Bjorklund, M., "An extensible YANG validator and converter 1082 in python", . 1084 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1085 the Network Configuration Protocol (NETCONF)", RFC 6020, 1086 DOI 10.17487/RFC6020, October 2010, 1087 . 1089 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1090 and A. Bierman, Ed., "Network Configuration Protocol 1091 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1092 . 1094 [RFC7224] Bjorklund, M., "IANA Interface Type YANG Module", 1095 RFC 7224, DOI 10.17487/RFC7224, May 2014, 1096 . 1098 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1099 Constrained-Node Networks", RFC 7228, 1100 DOI 10.17487/RFC7228, May 2014, 1101 . 1103 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1104 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1105 2014, . 1107 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1108 Writing an IANA Considerations Section in RFCs", BCP 26, 1109 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1110 . 1112 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1113 Access Control Model", STD 91, RFC 8341, 1114 DOI 10.17487/RFC8341, March 2018, 1115 . 1117 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 1118 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 1119 . 1121 [RFC8344] Bjorklund, M., "A YANG Data Model for IP Management", 1122 RFC 8344, DOI 10.17487/RFC8344, March 2018, 1123 . 1125 [RFC8366] Watsen, K., Richardson, M., Pritikin, M., and T. Eckert, 1126 "A Voucher Artifact for Bootstrapping Protocols", 1127 RFC 8366, DOI 10.17487/RFC8366, May 2018, 1128 . 1130 Appendix A. ".sid" file example 1132 The following ".sid" file (ietf-system@2014-08-06.sid) has been 1133 generated using the following yang modules: 1135 * ietf-system@2014-08-06.yang (defined in [RFC7317]) 1137 * ietf-yang-types@2013-07-15.yang (defined in [RFC6991]) 1139 * ietf-inet-types@2013-07-15.yang (defined in [RFC6991]) 1141 * ietf-netconf-acm@2018-02-14.yang (defined in [RFC8341]) 1143 * iana-crypt-hash@2014-08-06.yang (defined in [RFC7317]) 1145 For purposes of exposition, line breaks have been introduced below in 1146 some JSON strings that represent overly long identifiers. For 1147 reconstructing the actual JSON file from this figure, all line breaks 1148 that occur in what would be JSON strings need to be removed, 1149 including any following blank space (indentation) on the line after 1150 the line break; in each such case, a single identifier without any 1151 embedded blank space results. 1153 { 1154 "ietf-sid-file:sid-file" : { 1155 "module-name": "ietf-system", 1156 "module-revision": "2020-02-05", 1157 "dependency-revision": [ 1158 { 1159 "module-name": "ietf-yang-types", 1160 "module-revision": "2013-07-15" 1161 }, 1162 { 1163 "module-name": "ietf-inet-types", 1164 "module-revision": "2013-07-15" 1165 }, 1166 { 1167 "module-name": "ietf-netconf-acm", 1168 "module-revision": "2018-02-14" 1169 }, 1170 { 1171 "module-name": "iana-crypt-hash", 1172 "module-revision": "2014-08-06" 1173 } 1174 ], 1175 "description": "Example sid file", 1176 "assignment-range": [ 1177 { 1178 "entry-point": 1700, 1179 "size": 100 1180 } 1181 ], 1182 "item": [ 1183 { 1184 "namespace": "module", 1185 "identifier": "ietf-system", 1186 "sid": 1700 1187 }, 1188 { 1189 "namespace": "identity", 1190 "identifier": "authentication-method", 1191 "sid": 1701 1192 }, 1193 { 1194 "namespace": "identity", 1195 "identifier": "local-users", 1196 "sid": 1702 1197 }, 1198 { 1199 "namespace": "identity", 1200 "identifier": "radius", 1201 "sid": 1703 1202 }, 1203 { 1204 "namespace": "identity", 1205 "identifier": "radius-authentication-type", 1206 "sid": 1704 1207 }, 1208 { 1209 "namespace": "identity", 1210 "identifier": "radius-chap", 1211 "sid": 1705 1212 }, 1213 { 1214 "namespace": "identity", 1215 "identifier": "radius-pap", 1216 "sid": 1706 1217 }, 1218 { 1219 "namespace": "feature", 1220 "identifier": "authentication", 1221 "sid": 1707 1222 }, 1223 { 1224 "namespace": "feature", 1225 "identifier": "dns-udp-tcp-port", 1226 "sid": 1708 1227 }, 1228 { 1229 "namespace": "feature", 1230 "identifier": "local-users", 1231 "sid": 1709 1232 }, 1233 { 1234 "namespace": "feature", 1235 "identifier": "ntp", 1236 "sid": 1710 1237 }, 1238 { 1239 "namespace": "feature", 1240 "identifier": "ntp-udp-port", 1241 "sid": 1711 1242 }, 1243 { 1244 "namespace": "feature", 1245 "identifier": "radius", 1246 "sid": 1712 1247 }, 1248 { 1249 "namespace": "feature", 1250 "identifier": "radius-authentication", 1251 "sid": 1713 1252 }, 1253 { 1254 "namespace": "feature", 1255 "identifier": "timezone-name", 1256 "sid": 1714 1257 }, 1258 { 1259 "namespace": "data", 1260 "identifier": "/ietf-system:set-current-datetime", 1261 "sid": 1715 1262 }, 1263 { 1264 "namespace": "data", 1265 "identifier": "/ietf-system:set-current-datetime/ 1266 current-datetime", 1267 "sid": 1716 1268 }, 1269 { 1270 "namespace": "data", 1271 "identifier": "/ietf-system:system", 1272 "sid": 1717 1273 }, 1274 { 1275 "namespace": "data", 1276 "identifier": "/ietf-system:system-restart", 1277 "sid": 1718 1278 }, 1279 { 1280 "namespace": "data", 1281 "identifier": "/ietf-system:system-shutdown", 1282 "sid": 1719 1283 }, 1284 { 1285 "namespace": "data", 1286 "identifier": "/ietf-system:system-state", 1287 "sid": 1720 1288 }, 1289 { 1290 "namespace": "data", 1291 "identifier": "/ietf-system:system-state/clock", 1292 "sid": 1721 1293 }, 1294 { 1295 "namespace": "data", 1296 "identifier": "/ietf-system:system-state/clock/boot-datetime", 1297 "sid": 1722 1298 }, 1299 { 1300 "namespace": "data", 1301 "identifier": "/ietf-system:system-state/clock/ 1302 current-datetime", 1303 "sid": 1723 1304 }, 1305 { 1306 "namespace": "data", 1307 "identifier": "/ietf-system:system-state/platform", 1308 "sid": 1724 1309 }, 1310 { 1311 "namespace": "data", 1312 "identifier": "/ietf-system:system-state/platform/machine", 1313 "sid": 1725 1314 }, 1315 { 1316 "namespace": "data", 1317 "identifier": "/ietf-system:system-state/platform/os-name", 1318 "sid": 1726 1319 }, 1320 { 1321 "namespace": "data", 1322 "identifier": "/ietf-system:system-state/platform/os-release", 1323 "sid": 1727 1324 }, 1325 { 1326 "namespace": "data", 1327 "identifier": "/ietf-system:system-state/platform/os-version", 1328 "sid": 1728 1329 }, 1330 { 1331 "namespace": "data", 1332 "identifier": "/ietf-system:system/authentication", 1333 "sid": 1729 1334 }, 1335 { 1336 "namespace": "data", 1337 "identifier": "/ietf-system:system/authentication/user", 1338 "sid": 1730 1339 }, 1340 { 1341 "namespace": "data", 1342 "identifier": "/ietf-system:system/authentication/ 1343 user-authentication-order", 1344 "sid": 1731 1346 }, 1347 { 1348 "namespace": "data", 1349 "identifier": "/ietf-system:system/authentication/user/ 1350 authorized-key", 1351 "sid": 1732 1352 }, 1353 { 1354 "namespace": "data", 1355 "identifier": "/ietf-system:system/authentication/user/ 1356 authorized-key/algorithm", 1357 "sid": 1733 1358 }, 1359 { 1360 "namespace": "data", 1361 "identifier": "/ietf-system:system/authentication/user/ 1362 authorized-key/key-data", 1363 "sid": 1734 1364 }, 1365 { 1366 "namespace": "data", 1367 "identifier": "/ietf-system:system/authentication/user/ 1368 authorized-key/name", 1369 "sid": 1735 1370 }, 1371 { 1372 "namespace": "data", 1373 "identifier": "/ietf-system:system/authentication/user/ 1374 name", 1375 "sid": 1736 1376 }, 1377 { 1378 "namespace": "data", 1379 "identifier": "/ietf-system:system/authentication/user/ 1380 password", 1381 "sid": 1737 1382 }, 1383 { 1384 "namespace": "data", 1385 "identifier": "/ietf-system:system/clock", 1386 "sid": 1738 1387 }, 1388 { 1389 "namespace": "data", 1390 "identifier": "/ietf-system:system/clock/timezone-name", 1391 "sid": 1739 1392 }, 1393 { 1394 "namespace": "data", 1395 "identifier": "/ietf-system:system/clock/timezone-utc-offset", 1396 "sid": 1740 1397 }, 1398 { 1399 "namespace": "data", 1400 "identifier": "/ietf-system:system/contact", 1401 "sid": 1741 1402 }, 1403 { 1404 "namespace": "data", 1405 "identifier": "/ietf-system:system/dns-resolver", 1406 "sid": 1742 1407 }, 1408 { 1409 "namespace": "data", 1410 "identifier": "/ietf-system:system/dns-resolver/options", 1411 "sid": 1743 1412 }, 1413 { 1414 "namespace": "data", 1415 "identifier": "/ietf-system:system/dns-resolver/options/ 1416 attempts", 1417 "sid": 1744 1418 }, 1419 { 1420 "namespace": "data", 1421 "identifier": "/ietf-system:system/dns-resolver/options/ 1422 timeout", 1423 "sid": 1745 1424 }, 1425 { 1426 "namespace": "data", 1427 "identifier": "/ietf-system:system/dns-resolver/search", 1428 "sid": 1746 1429 }, 1430 { 1431 "namespace": "data", 1432 "identifier": "/ietf-system:system/dns-resolver/server", 1433 "sid": 1747 1434 }, 1435 { 1436 "namespace": "data", 1437 "identifier": "/ietf-system:system/dns-resolver/server/name", 1438 "sid": 1748 1439 }, 1440 { 1441 "namespace": "data", 1442 "identifier": "/ietf-system:system/dns-resolver/server/ 1443 udp-and-tcp", 1444 "sid": 1749 1445 }, 1446 { 1447 "namespace": "data", 1448 "identifier": "/ietf-system:system/dns-resolver/server/ 1449 udp-and-tcp/address", 1450 "sid": 1750 1451 }, 1452 { 1453 "namespace": "data", 1454 "identifier": "/ietf-system:system/dns-resolver/server/ 1455 udp-and-tcp/port", 1456 "sid": 1751 1457 }, 1458 { 1459 "namespace": "data", 1460 "identifier": "/ietf-system:system/hostname", 1461 "sid": 1752 1462 }, 1463 { 1464 "namespace": "data", 1465 "identifier": "/ietf-system:system/location", 1466 "sid": 1753 1467 }, 1468 { 1469 "namespace": "data", 1470 "identifier": "/ietf-system:system/ntp", 1471 "sid": 1754 1472 }, 1473 { 1474 "namespace": "data", 1475 "identifier": "/ietf-system:system/ntp/enabled", 1476 "sid": 1755 1477 }, 1478 { 1479 "namespace": "data", 1480 "identifier": "/ietf-system:system/ntp/server", 1481 "sid": 1756 1482 }, 1483 { 1484 "namespace": "data", 1485 "identifier": "/ietf-system:system/ntp/server/ 1486 association-type", 1487 "sid": 1757 1488 }, 1489 { 1490 "namespace": "data", 1491 "identifier": "/ietf-system:system/ntp/server/iburst", 1492 "sid": 1758 1493 }, 1494 { 1495 "namespace": "data", 1496 "identifier": "/ietf-system:system/ntp/server/name", 1497 "sid": 1759 1498 }, 1499 { 1500 "namespace": "data", 1501 "identifier": "/ietf-system:system/ntp/server/prefer", 1502 "sid": 1760 1503 }, 1504 { 1505 "namespace": "data", 1506 "identifier": "/ietf-system:system/ntp/server/udp", 1507 "sid": 1761 1508 }, 1509 { 1510 "namespace": "data", 1511 "identifier": "/ietf-system:system/ntp/server/udp/address", 1512 "sid": 1762 1513 }, 1514 { 1515 "namespace": "data", 1516 "identifier": "/ietf-system:system/ntp/server/udp/port", 1517 "sid": 1763 1518 }, 1519 { 1520 "namespace": "data", 1521 "identifier": "/ietf-system:system/radius", 1522 "sid": 1764 1523 }, 1524 { 1525 "namespace": "data", 1526 "identifier": "/ietf-system:system/radius/options", 1527 "sid": 1765 1528 }, 1529 { 1530 "namespace": "data", 1531 "identifier": "/ietf-system:system/radius/options/attempts", 1532 "sid": 1766 1533 }, 1534 { 1535 "namespace": "data", 1536 "identifier": "/ietf-system:system/radius/options/timeout", 1537 "sid": 1767 1539 }, 1540 { 1541 "namespace": "data", 1542 "identifier": "/ietf-system:system/radius/server", 1543 "sid": 1768 1544 }, 1545 { 1546 "namespace": "data", 1547 "identifier": "/ietf-system:system/radius/server/ 1548 authentication-type", 1549 "sid": 1769 1550 }, 1551 { 1552 "namespace": "data", 1553 "identifier": "/ietf-system:system/radius/server/name", 1554 "sid": 1770 1555 }, 1556 { 1557 "namespace": "data", 1558 "identifier": "/ietf-system:system/radius/server/udp", 1559 "sid": 1771 1560 }, 1561 { 1562 "namespace": "data", 1563 "identifier": "/ietf-system:system/radius/server/udp/ 1564 address", 1565 "sid": 1772 1566 }, 1567 { 1568 "namespace": "data", 1569 "identifier": "/ietf-system:system/radius/server/udp/ 1570 authentication-port", 1571 "sid": 1773 1572 }, 1573 { 1574 "namespace": "data", 1575 "identifier": "/ietf-system:system/radius/server/udp/ 1576 shared-secret", 1577 "sid": 1774 1578 } 1579 ] 1580 } 1581 } 1583 Appendix B. SID auto generation 1585 Assignment of SIDs to YANG items SHOULD be automated. The 1586 recommended process to assign SIDs is as follows: 1588 1. A tool extracts the different items defined for a specific YANG 1589 module. 1591 2. The list of items is sorted in alphabetical order, 'namespace' in 1592 descending order, 'identifier' in ascending order. The 1593 'namespace' and 'identifier' formats are described in the YANG 1594 module 'ietf-sid-file' defined in Section 4. 1596 3. SIDs are assigned sequentially from the entry point up to the 1597 size of the registered SID range. This approach is recommended 1598 to minimize the serialization overhead, especially when delta 1599 between a reference SID and the current SID is used by protocols 1600 aiming to reduce message size. 1602 4. If the number of items exceeds the SID range(s) allocated to a 1603 YANG module, an extra range is added for subsequent assignments. 1605 5. The "dependency-revision" should reflect the revision numbers of 1606 each YANG module that the YANG module imports at the moment of 1607 the generation. 1609 When updating a YANG module that is in active use, the existing SID 1610 assignments are maintained. (In contrast, when evolving an early 1611 draft that has not yet been adopted by a community of developers, SID 1612 assignments are often better done from scratch after a revision.) If 1613 the name of a schema node changes, but the data remain structurally 1614 and semantically similar to what was previously available under an 1615 old name, the SID that was used for the old name MAY continue to be 1616 used for the new name. If the meaning of an item changes, a new SID 1617 MAY be assigned to it; this is particularly useful to allow the new 1618 SID to identify the new structure or semantics of the item. If the 1619 YANG data type changes in a new revision of a published module, such 1620 that the resulting CBOR encoding is changed, then implementations 1621 will be aided significantly if a new SID is assigned. Note that 1622 these decisions are generally at the discretion of the YANG module 1623 author, who should decide if the benefits of a manual intervention 1624 are worth the deviation from automatic assignment. 1626 In case of an update to an existing ".sid" file, an additional step 1627 is needed that increments the ".sid" file version number. If there 1628 was no version number in the previous version of the ".sid" file, 0 1629 is assumed as the version number of the old version of the ".sid" 1630 file and the version number is 1 for the new ".sid" file. Apart from 1631 that, changes of ".sid" files can also be automated using the same 1632 method described above, only unassigned YANG items are processed at 1633 step #3. Already existing items in the ".sid" file should not be 1634 given new SIDs. 1636 Note that ".sid" file versions are specific to a YANG module 1637 revision. For each new YANG module or each new revision of an 1638 existing YANG module, the version number of the initial ".sid" file 1639 should either be 0 or should not be present. 1641 Note also that RPC or action "input" and "output" data nodes MUST 1642 always be assigned SID even if they don't contain data nodes. The 1643 reason for this requirement is that other modules can augment the 1644 given module and those SIDs might be necessary. 1646 Appendix C. ".sid" file lifecycle 1648 Before assigning SIDs to their YANG modules, YANG module authors must 1649 acquire a SID range from a "YANG SID Range Registry". If the YANG 1650 module is part of an IETF draft or RFC, the SID range need to be 1651 acquired from the "IETF YANG SID Range Registry" as defined in 1652 Section 7.5. For the other YANG modules, the authors can acquire a 1653 SID range from any "YANG SID Range Registry" of their choice. 1655 Once the SID range is acquired, owners can use it to generate ".sid" 1656 file/s for their YANG module/s. It is recommended to leave some 1657 unallocated SIDs following the allocated range in each ".sid" file in 1658 order to allow better evolution of the YANG module in the future. 1659 Generation of ".sid" files should be performed using an automated 1660 tool. Note that ".sid" files can only be generated for YANG modules 1661 and not for submodules. 1663 C.1. ".sid" File Creation 1665 The following activity diagram summarizes the creation of a YANG 1666 module and its associated ".sid" file. 1668 +---------------+ 1669 o | Creation of a | 1670 -+- -->| YANG module | 1671 / \ +------+--------+ 1672 | 1673 v 1674 .-------------. 1675 / Standardized \ yes 1676 \ YANG module ? /------------+ 1677 '-----+-------' | 1678 | no | 1679 v v 1680 .-------------. +---------------+ 1681 +--> / Constrained \ yes | SID range | 1682 | \ application ? /---->| registration |<---------+ 1683 | '-----+-------' +------+--------+ | 1684 | | no | | 1685 | v v | 1686 | +---------------+ +---------------+ | 1687 +----+ YANG module | | SID sub-range | | 1688 | update | | assignment |<----------+ 1689 +---------------+ +-------+-------+ | 1690 | | 1691 v | 1692 +---------------+ +------+------+ 1693 | ".sid" file | | Rework YANG | 1694 | generation | | module | 1695 +-------+-------+ +-------------+ 1696 | ^ 1697 v | 1698 .----------. yes | 1699 / Work in \ -----------+ 1700 \ progress / 1701 '----+-----' 1702 | no 1703 v 1704 .-------------. .-------------. 1705 / RFC \ no / Open \ no 1706 \ publication? /---> \ specification?/---+ 1707 '------+------' '------+------' | 1708 yes | | yes | 1709 | .------------' | 1710 | / | 1711 v v v 1712 +---------------+ +---------------+ 1713 | IANA | | Third party | 1714 | registration | | registration | 1715 +-------+-------+ +---------+-----+ 1716 | | 1717 +---------------------------------+ 1718 v 1719 [DONE] 1721 Figure 1: SID Lifecycle 1723 C.2. ".sid" File Update 1725 The following Activity diagram summarizes the update of a YANG module 1726 and its associated ".sid" file. 1728 +---------------+ 1729 o | Update of the | 1730 -+- -->| YANG module | 1731 / \ | or include(s) | 1732 | or import(s) | 1733 +------+--------+ 1734 | 1735 v 1736 .-------------. 1737 / New items \ yes 1738 \ created ? /------+ 1739 '------+------' | 1740 | no v 1741 | .-------------. +----------------+ 1742 | / SID range \ yes | Extra sub-range| 1743 | \ exhausted ? /---->| assignment | 1744 | '------+------' +-------+--------+ 1745 | | no | 1746 | +---------------------+ 1747 | | 1748 | v 1749 | +---------------+ 1750 | | ".sid" file | 1751 | | update based | 1752 | | on previous | 1753 | | ".sid" file | 1754 | +-------+-------+ 1755 | | 1756 | v 1757 | .-------------. +---------------+ 1758 | / Publicly \ yes | YANG module | 1759 | \ available ? /---->| registration | 1760 | '------+------' +-------+-------+ 1761 | | no | 1762 +--------------+---------------------+ 1763 | 1764 [DONE] 1766 Figure 2: YANG and ".sid" file update 1768 Acknowledgments 1770 The authors would like to thank Andy Bierman, Michael Richardson, 1771 Abhinav Somaraju, Peter van der Stok, Laurent Toutain and Randy 1772 Turner for their help during the development of this document and 1773 their useful comments during the review process. 1775 Contributors 1777 Andy Bierman 1778 YumaWorks 1779 685 Cochran St. 1780 Suite #160 1781 Simi Valley, CA 93065 1782 United States of America 1784 Email: andy@yumaworks.com 1786 Authors' Addresses 1788 Michel Veillette (editor) 1789 Trilliant Networks Inc. 1790 610 Rue du Luxembourg 1791 Granby Quebec J2J 2V2 1792 Canada 1794 Phone: +14503750556 1795 Email: michel.veillette@trilliant.com 1797 Alexander Pelov (editor) 1798 Acklio 1799 1137A avenue des Champs Blancs 1800 35510 Cesson-Sevigne 1801 France 1803 Email: a@ackl.io 1805 Ivaylo Petrov (editor) 1806 Google Switzerland GmbH 1807 Brandschenkestrasse 110 1808 CH-8002 Zurich 1809 Switzerland 1811 Email: ivaylopetrov@google.com 1813 Carsten Bormann 1814 Universität Bremen TZI 1815 Postfach 330440 1816 D-28359 Bremen 1817 Germany 1818 Phone: +49-421-218-63921 1819 Email: cabo@tzi.org 1821 Michael Richardson 1822 Sandelman Software Works 1824 Email: mcr+ietf@sandelman.ca