idnits 2.17.1 draft-ietf-netmod-yang-module-versioning-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 6 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: While incoming configuration data is checked according to YANG constraints, constraints on state data sent by the server MAY or MAY NOT be enforced. The following guidelines are provided for client application designers to allow a smooth interworking with servers. -- The document date (February 22, 2021) is 1157 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: 'RFCXXXX' is mentioned on line 1360, but not defined == Unused Reference: 'I-D.ietf-netmod-rfc6991-bis' is defined on line 1426, but no explicit reference was found in the text == Outdated reference: A later version (-15) exists of draft-ietf-netmod-rfc6991-bis-04 == Outdated reference: A later version (-15) exists of draft-ietf-netmod-yang-semver-01 ** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525) == Outdated reference: A later version (-21) exists of draft-ietf-netmod-yang-instance-file-format-12 == Outdated reference: A later version (-03) exists of draft-ietf-netmod-yang-packages-01 == Outdated reference: A later version (-09) exists of draft-ietf-netmod-yang-versioning-reqs-04 Summary: 2 errors (**), 0 flaws (~~), 9 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Wilton, Ed. 3 Internet-Draft Cisco Systems, Inc. 4 Updates: 7950,8407,8525 (if approved) R. Rahman, Ed. 5 Intended status: Standards Track 6 Expires: August 26, 2021 B. Lengyel, Ed. 7 Ericsson 8 J. Clarke 9 Cisco Systems, Inc. 10 J. Sterne 11 Nokia 12 B. Claise 13 Huawei 14 K. D'Souza 15 AT&T 16 February 22, 2021 18 Updated YANG Module Revision Handling 19 draft-ietf-netmod-yang-module-versioning-02 21 Abstract 23 This document specifies a new YANG module update procedure that can 24 document when non-backwards-compatible changes have occurred during 25 the evolution of a YANG module. It extends the YANG import statement 26 with an earliest revision filter to better represent inter-module 27 dependencies. It provides help and guidelines for managing the 28 lifecycle of YANG modules and individual schema nodes. It provides a 29 mechanism, via the revision-label YANG extension, to specify a 30 revision identifier for YANG modules. This document updates RFC 31 7950, RFC 8407 and RFC 8525. 33 Status of This Memo 35 This Internet-Draft is submitted in full conformance with the 36 provisions of BCP 78 and BCP 79. 38 Internet-Drafts are working documents of the Internet Engineering 39 Task Force (IETF). Note that other groups may also distribute 40 working documents as Internet-Drafts. The list of current Internet- 41 Drafts is at https://datatracker.ietf.org/drafts/current/. 43 Internet-Drafts are draft documents valid for a maximum of six months 44 and may be updated, replaced, or obsoleted by other documents at any 45 time. It is inappropriate to use Internet-Drafts as reference 46 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on August 26, 2021. 50 Copyright Notice 52 Copyright (c) 2021 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (https://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 68 1.1. Updates to YANG RFCs . . . . . . . . . . . . . . . . . . 4 69 2. Terminology and Conventions . . . . . . . . . . . . . . . . . 4 70 3. Refinements to YANG revision handling . . . . . . . . . . . . 5 71 3.1. Updating a YANG module with a new revision . . . . . . . 6 72 3.1.1. Backwards-compatible rules for config data . . . . . 6 73 3.1.2. Backwards-compatibility rules for config false and 74 output data . . . . . . . . . . . . . . . . . . . . . 7 75 3.1.3. Non-backwards-compatible changes . . . . . . . . . . 8 76 3.2. nbc-changes revision extension statement . . . . . . . . 8 77 3.3. Revision label . . . . . . . . . . . . . . . . . . . . . 8 78 3.3.1. Revision label scheme extension statement . . . . . . 10 79 3.3.2. Removing revisions from the revision history . . . . 10 80 3.4. Examples for updating the YANG module revision history . 10 81 4. Import by derived revision . . . . . . . . . . . . . . . . . 13 82 4.1. Module import examples . . . . . . . . . . . . . . . . . 15 83 5. Updates to ietf-yang-library . . . . . . . . . . . . . . . . 16 84 5.1. Resolving ambiguous module imports . . . . . . . . . . . 16 85 5.2. YANG library versioning augmentations . . . . . . . . . . 17 86 5.2.1. Advertising revision-label . . . . . . . . . . . . . 17 87 5.2.2. Reporting how deprecated and obsolete nodes are 88 handled . . . . . . . . . . . . . . . . . . . . . . . 17 89 6. Versioning of YANG instance data . . . . . . . . . . . . . . 18 90 7. Guidelines for using the YANG module update rules . . . . . . 18 91 7.1. Guidelines for YANG module authors . . . . . . . . . . . 18 92 7.1.1. Making non-backwards-compatible changes to a YANG 93 module . . . . . . . . . . . . . . . . . . . . . . . 19 94 7.2. Versioning Considerations for Clients . . . . . . . . . . 20 95 8. Module Versioning Extension YANG Modules . . . . . . . . . . 21 96 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 29 97 10. Security Considerations . . . . . . . . . . . . . . . . . . . 29 98 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 99 11.1. YANG Module Registrations . . . . . . . . . . . . . . . 30 100 11.2. Guidance for versioning in IANA maintained YANG modules 30 101 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 31 102 12.1. Normative References . . . . . . . . . . . . . . . . . . 31 103 12.2. Informative References . . . . . . . . . . . . . . . . . 32 104 Appendix A. Examples of changes that are NBC . . . . . . . . . . 34 105 Appendix B. Examples of applying the NBC change guidelines . . . 34 106 B.1. Removing a data node . . . . . . . . . . . . . . . . . . 34 107 B.2. Changing the type of a leaf node . . . . . . . . . . . . 35 108 B.3. Reducing the range of a leaf node . . . . . . . . . . . . 36 109 B.4. Changing the key of a list . . . . . . . . . . . . . . . 36 110 B.5. Renaming a node . . . . . . . . . . . . . . . . . . . . . 37 111 B.6. Changing a default value . . . . . . . . . . . . . . . . 38 112 Appendix C. Changes between revisions . . . . . . . . . . . . . 38 113 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 39 115 1. Introduction 117 This document defines a solution to the YANG module lifecycle 118 problems described in [I-D.ietf-netmod-yang-versioning-reqs]. 119 Complementary documents provide a complete solution to the YANG 120 versioning requirements, with the overall relationship of the 121 solution drafts described in [I-D.ietf-netmod-yang-solutions]. 123 Specifically, this document recognises a need (within standards 124 organizations, vendors, and the industry) to sometimes allow YANG 125 modules to evolve with non-backwards-compatible changes, which could 126 cause breakage to clients and importing YANG modules. Accepting that 127 non-backwards-compatible changes do sometimes occur, it is important 128 to have mechanisms to report where these changes occur, and to manage 129 their effect on clients and the broader YANG ecosystem. 131 The document comprises five parts: 133 Refinements to the YANG 1.1 module revision update procedure, 134 supported by new extension statements to indicate when a revision 135 contains non-backwards-compatible changes, and an optional 136 revision label. 138 A YANG extension statement allowing YANG module imports to specify 139 an earliest module revision that may satisfy the import 140 dependency. 142 Updates and augmentations to ietf-yang-library to include the 143 revision label in the module descriptions, to report how 144 "deprecated" and "obsolete" nodes are handled by a server, and to 145 clarify how module imports are resolved when multiple revisions 146 could otherwise be chosen. 148 Considerations of how versioning applies to YANG instance data. 150 Guidelines for how the YANG module update rules defined in this 151 document should be used, along with examples. 153 Note to RFC Editor (To be removed by RFC Editor) 155 Open issues are tracked at . 158 1.1. Updates to YANG RFCs 160 This document updates [RFC7950] section 11. Section 3 describes 161 modifications to YANG revision handling and update rules, and 162 Section 4 describes a YANG extension statement to do import by 163 derived revision. 165 This document updates [RFC7950] section 5.6.5. Section 5.1 defines 166 how a client of a YANG library datastore schema resolves ambiguous 167 imports for modules which are not "import-only". 169 This document updates [RFC8407] section 4.7. Section 7 provides 170 guidelines on managing the lifecycle of YANG modules that may contain 171 non-backwards-compatible changes and a branched revision history. 173 This document updates [RFC7950] section 5.2. Section 3.3 describes 174 the use of a revision label in the name of a file containing a YANG 175 module or submodule. 177 2. Terminology and Conventions 179 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 180 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 181 "OPTIONAL" in this document are to be interpreted as described in BCP 182 14 [RFC2119] [RFC8174] when, and only when, they appear in all 183 capitals, as shown here. 185 In addition, this document uses the terminology: 187 o YANG module revision: An instance of a YANG module, uniquely 188 identified with a revision date, with no implied ordering or 189 backwards compatibility between different revisions of the same 190 module. 192 o Backwards-compatible (BC) change: A backwards-compatible change 193 between two YANG module revisions, as defined in Section 3.1.1 195 o Non-backwards-compatible (NBC) change: A non-backwards-compatible 196 change between two YANG module revisions, as defined in 197 Section 3.1.3 199 o Valuespace: The valuespace of a leaf or leaf-list is the set of 200 values that the schema node may have according to the type and 201 constraint statements of the YANG model. 203 3. Refinements to YANG revision handling 205 [RFC7950] assumes, but does not explicitly state, that the revision 206 history for a YANG module is strictly linear, i.e., it is prohibited 207 to have two independent revisions of a YANG module that are both 208 directly derived from the same parent revision. 210 This document clarifies [RFC7950] to explicitly allow non linear 211 development of YANG module revisions, so modules MAY have multiple 212 revisions that directly derive from the same parent revision. As per 213 [RFC7950], YANG module revisions continue to be uniquely identified 214 by the module's revision date, and hence all revisions of a module 215 MUST have unique revision dates. 217 A corollary to the above is that the relationship between two module 218 revisions cannot be determined by comparing the module revision date 219 alone, and the revision history, or revision label, must also be 220 taken into consideration. 222 A module's name and revision date identifies a specific immutable 223 definition of that module within its revision history. Hence, if a 224 module includes submodules then to ensure that the module's content 225 is uniquely defined, the module's "include" statements SHOULD use 226 "revision-date" substatements to specify the exact revision date of 227 each included submodule. When a module does not include its 228 submodules by revision-date, the revision of submodules used cannot 229 be derived from the including module. Mechanisms such as YANG 230 packages [I-D.ietf-netmod-yang-packages], and YANG library [[RFC7895] 231 [RFC8525], MAY be used to specify the exact submodule revisions used 232 when the submodule revision date is not constrained by the "include" 233 statement. 235 [RFC7950] section 11 requires that all updates to a YANG module are 236 BC to the previous revision of the module. This document allows for 237 more flexible evolution of YANG modules: NBC changes between module 238 revisions are allowed and are documented using a new "nbc-changes" 239 YANG extension statement in the module revision history. 241 Two revisions of a module MAY have identical content except for the 242 revision history. This could occur, for example, if a module has a 243 branched history and identical changes are applied in multiple 244 branches. 246 3.1. Updating a YANG module with a new revision 248 This section updates [RFC7950] section 11 to refine the rules for 249 permissible changes when a new YANG module revision is created. 251 Where pragmatic, updates to YANG modules SHOULD be backwards- 252 compatible, following the definition in Section 3.1.1. 254 A new module revision MAY contain NBC changes, i.e., the semantics of 255 an existing definition MAY be changed in an NBC way without requiring 256 a new definition with a new identifier. A new module revision with 257 NBC changes MUST include the "rev:nbc-changes" extension substatement 258 to signal the potential for incompatibility to existing module users 259 and readers. 261 3.1.1. Backwards-compatible rules for config data 263 A change between two module revisions is defined as being "backwards- 264 compatible" if the change conforms to the module update rules 265 specified in [RFC7950] section 11, updated by the following rules: 267 o A "status" "deprecated" statement MAY be added, or changed from 268 "current" to "deprecated", but adding or changing "status" to 269 "obsolete" is not a backwards-compatible change. 271 o Obsolete definitions MAY be removed from published modules, and 272 are classified as backwards-compatible changes. In some 273 circumstances it may be helpful to retain the obsolete definitions 274 to ensure that their identifiers are not reused with a different 275 meaning. 277 o In statements that have any data definition statements as 278 substatements, those data definition substatements MAY be 279 reordered, as long as they do not change the ordering of any 280 "input" or "output" data definition substatements of "rpc" or 281 "action" statements. If new data definition statements are added, 282 they can be added anywhere in the sequence of existing 283 substatements. 285 o Any changes (including whitespace or formatting changes) that do 286 not change the semantic meaning of the module are backwards 287 compatible. 289 3.1.2. Backwards-compatibility rules for config false and output data 291 Compatibility behavior of configuration and state data is different. 292 While adding a mandatory configuration leaf makes earlier 293 configurations invalid, an additional state leaf can easily be 294 discarded. Decreasing the valuespace of a configuration leaf makes 295 any configuration invalid that uses the newly excluded values; 296 decreasing the valuespace of a state schema node should not disturb a 297 client application. Data in the output section of notifications, 298 actions or rpcs is governed by the same backwards compatibility 299 behavior as config=false data. 301 While incoming configuration data is checked according to YANG 302 constraints, constraints on state data sent by the server MAY or MAY 303 NOT be enforced. The following guidelines are provided for client 304 application designers to allow a smooth interworking with servers. 306 o A client MUST tolerate any data received (or not received) without 307 crashing. 309 o A client MUST be able to discard any data that is not part of the 310 model but is sent by the server additionally (e.g. XML elements 311 or attributes, JSON properties). 313 o A client SHOULD be able to handle valid parts of a received data 314 set even if it discards other parts as invalid. 316 o A client SHOULD be able to handle data that is outside the 317 valuespace defined, as long as it is of the same basic type. 319 o A client SHOULD be prepared to handle more items for a list or 320 leaf-list than what is defined by the model. 322 Based on the above client guidelines and the intent to allow the 323 correct and flexible handling of state and output data even after 324 module revision changes the following rules define which config false 325 and output schema changes are considered BC or NBC. The rules 326 reflect common client behavior, however a client that expects a 327 specific server behavior or data set may have problems with any 328 change. The rules are defined as a compromise between protecting 329 client applications and allowing the most common changes. 331 o Adding mandatory or optional schema nodes is BC 333 o Changing an optional schema node to mandatory is BC 335 o Removal of a mandatory or optional schema node is NBC 336 o Changing a mandatory schema node to optional is NBC 338 o Expanding the valuespace of a leaf or leaf-list is BC. Change of 339 the valuespace may be the result of a change to a range, length, 340 pattern, base, enum, bit, require-instance or must statements. 342 o Decreasing the valuespace of a leaf or leaf-list is BC 344 o Changing max-elements is BC 346 o Increasing min-element is BC 348 o Changing min-elements to a lower value is NBC (it is like removing 349 mandatory) 351 o Modifying the type of a leaf or leaf-list is NBC 353 3.1.3. Non-backwards-compatible changes 355 Any changes to YANG modules that are not defined by Section 3.1.1 or 356 Section 3.1.2 as being backwards-compatible are classified as "non- 357 backwards-compatible" changes. 359 3.2. nbc-changes revision extension statement 361 The "rev:nbc-changes" extension statement is used to indicate YANG 362 module revisions that contain NBC changes. 364 If a revision of a YANG module contains changes, relative to the 365 preceding revision in the revision history, that do not conform to 366 the module update rules defined in Section 3.1.1 or Section 3.1.2, 367 then a "rev:nbc-changes" extension statement MUST be added as a 368 substatement to the "revision" statement. 370 Conversely, if a revision does not contain an "rev:nbc-changes" 371 extension substatement then all changes, relative to the preceding 372 revision in the revision history, MUST be backwards-compatible. 374 3.3. Revision label 376 This section updates [RFC7950] section 5.2, it explains how a 377 revision label can be used in the name of a file containing a YANG 378 module or submodule. 380 Each revision entry in a module or submodule MAY have a revision 381 label associated with it, providing an alternative alias to identify 382 a particular revision of a module or submodule. The revision label 383 could be used to provide an additional versioning identifier 384 associated with the revision. 386 YANG Semver [I-D.ietf-netmod-yang-semver] defines a versioning scheme 387 based on Semver 2.0.0 [semver] that can be used as a revision label. 389 Submodules MAY use a revision label scheme. When they use a revision 390 label scheme, submodules MAY use a revision label scheme that is 391 different from the one used in the including module. 393 The revision label space of submodules is separate from the revision 394 label space of the including module. A change in one submodule MUST 395 result in a new revision label of that submodule and the including 396 module, but the actual values of the revision labels in the module 397 and submodule could be completely different. A change in one 398 submodule does not result in a new revision label in another 399 submodule. A change in a module revision label does not necessarily 400 mean a change to the revision label in all included submodules. 402 If a revision has an associated revision label, then it may be used 403 instead of the revision date in an "rev:revision-or-derived" 404 extension statement argument. 406 A specific revision-label identifies a specific revision (variant) of 407 the module. If two YANG modules contain the same module name and the 408 same revision-label (and hence also the same revision-date) in their 409 latest revision statement, then the contents of the two modules, 410 including the revision history, MUST be identical. 412 If a revision has an associated revision label, then the revision- 413 label may be used instead of the revision date in the filename of a 414 YANG file, where it takes the form: 416 module-or-submodule-name [['@' revision-date]|['#' revision-label]] 417 ( '.yang' / '.yin' ) 419 E.g., acme-router-module@2018-01-25.yang 420 E.g., acme-router-module#2.0.3.yang 422 YANG module (or submodule) files MAY be identified using either 423 revision-date or revision-label. Typically, only one file name 424 SHOULD exist for the same module (or submodule) revision. Two file 425 names, one with the revision date and another with the revision 426 label, MAY exist for the same module (or submodule) revision, e.g 427 when migrating from one scheme to the other. 429 3.3.1. Revision label scheme extension statement 431 The "rev:revision-label-scheme" extension statement is used to 432 indicate which revision-label scheme a module or submodule uses. The 433 mandatory argument to this extension statement: 435 o Specifies the revision-label scheme used by the module or 436 submodule 438 o Is defined in the document which specifies the revision-label 439 scheme 441 o MUST be an identity derived from "revision-label-scheme-base" 443 The revision-label scheme used by a module or submodule SHOULD NOT 444 change during the lifetime of the module or submodule. If the 445 revision-label scheme used by a module or submodule is changed to a 446 new scheme, then all revision-label statements that do not conform to 447 the new scheme MUST be replaced or removed. 449 3.3.2. Removing revisions from the revision history 451 Module authors may wish to remove revision statements from a module 452 or submodule. Removal of revision information may be desired for a 453 number of reasons including reducing the size of a large revision 454 history, or removing a revision that should no longer be used or 455 imported. Removing revision statements is allowed, but can cause 456 issues and SHOULD NOT be done without careful analysis of the impacts 457 to users of the module or submodule. Doing so can lead to import 458 breakages when import by revision-or-derived is used. Moreover, 459 truncating history may cause loss of visibility of when non- 460 backwards-compatible changes were introduced. 462 3.4. Examples for updating the YANG module revision history 464 The following diagram, explanation, and module history illustrates 465 how the branched revision history, "nbc-changes" extension statement, 466 and "revision-label" extension statement could be used: 468 Example YANG module with branched revision history. 470 Module revision date Revision label 471 2019-01-01 <- 1.0.0 472 | 473 2019-02-01 <- 2.0.0 474 | \ 475 2019-03-01 \ <- 3.0.0 476 | \ 477 | 2019-04-01 <- 2.1.0 478 | | 479 | 2019-05-01 <- 2.2.0 480 | 481 2019-06-01 <- 3.1.0 483 The tree diagram above illustrates how an example module's revision 484 history might evolve, over time. For example, the tree might 485 represent the following changes, listed in chronological order from 486 oldest revision to newest: 488 Example module, revision 2019-06-01: 490 module example-module { 492 namespace "urn:example:module"; 493 prefix "prefix-name"; 495 import ietf-yang-revisions { prefix "rev"; } 497 description 498 "to be completed"; 500 revision 2019-06-01 { 501 rev:revision-label 3.1.0; 502 description "Add new functionality."; 503 } 505 revision 2019-03-01 { 506 rev:revision-label 3.0.0; 507 rev:nbc-changes; 508 description 509 "Add new functionality. Remove some deprecated nodes."; 510 } 512 revision 2019-02-01 { 513 rev:revision-label 2.0.0; 514 rev:nbc-changes; 515 description "Apply bugfix to pattern statement"; 516 } 518 revision 2019-01-01 { 519 rev:revision-label 1.0.0; 520 description "Initial revision"; 521 } 523 //YANG module definition starts here 524 } 526 Example module, revision 2019-05-01: 528 module example-module { 530 namespace "urn:example:module"; 531 prefix "prefix-name"; 533 import ietf-yang-revisions { prefix "rev"; } 535 description 536 "to be completed"; 538 revision 2019-05-01 { 539 rev:revision-label 2.2.0; 540 description "Backwards-compatible bugfix to enhancement."; 541 } 543 revision 2019-04-01 { 544 rev:revision-label 2.1.0; 545 description "Apply enhancement to older release train."; 546 } 548 revision 2019-02-01 { 549 rev:revision-label 2.0.0; 550 rev:nbc-changes; 551 description "Apply bugfix to pattern statement"; 552 } 554 revision 2019-01-01 { 555 rev:revision-label 1.0.0; 556 description "Initial revision"; 557 } 559 //YANG module definition starts here 560 } 562 4. Import by derived revision 564 RFC 7950 allows YANG module "import" statements to optionally require 565 the imported module to have a particular revision date. In practice, 566 importing a module with an exact revision date is often too 567 restrictive because it requires the importing module to be updated 568 whenever any change to the imported module occurs. The alternative 569 choice of using an import statement without any revision date 570 statement is also not ideal because the importing module may not work 571 with all possible revisions of the imported module. 573 Instead, it is desirable for a importing module to specify a "minimum 574 required revision" of a module that it is compatible with, based on 575 the assumption that later revisions derived from that "minimum 576 required revision" are also likely to be compatible. Many possible 577 changes to a YANG module do not break importing modules, even if the 578 changes themselves are not strictly backwards-compatible. E.g., 579 fixing an incorrect pattern statement or description for a leaf would 580 not break an import, changing the name of a leaf could break an 581 import but frequently would not, but removing a container would break 582 imports if that container is augmented by another module. 584 The ietf-revisions module defines the "revision-or-derived" extension 585 statement, a substatement to the YANG "import" statement, to allow 586 for a "minimum required revision" to be specified during import: 588 The argument to the "revision-or-derived" extension statement is a 589 revision date or a revision label. 591 A particular revision of an imported module satisfies an import's 592 "revision-or-derived" extension statement if the imported module's 593 revision history contains a revision statement with a matching 594 revision date or revision label. 596 An "import" statement MUST NOT contain both a "revision-or- 597 derived" extension statement and a "revision-date" statement. 599 The "revision-or-derived" extension statement MAY be specified 600 multiple times, allowing the import to use any module revision 601 that satisfies at least one of the "revision-or-derived" extension 602 statements. 604 The "revision-or-derived" extension statement does not guarantee 605 that all module revisions that satisfy an import statement are 606 necessarily compatible, it only gives an indication that the 607 revisions are more likely to be compatible. Hence, NBC changes to 608 an imported module may also require new revisions of any importing 609 modules, updated to accommodation those changes, along with 610 updated import "revision-or-derived" extension statements to 611 depend on the updated imported module revision. 613 Adding, modifying or removing a "revision-or-derived" extension 614 statement is considered to be a BC change. 616 Adding, modifying or removing a "revision-date" extension 617 statement is considered to be a BC change. 619 4.1. Module import examples 621 Consider the example module "example-module" from Section 3.4 that is 622 hypothetically available in the following revision/label pairings: 623 2019-01-01/1.0.0, 2019-02-01/2.0.0, 2019-03-01/3.0.0, 624 2019-04-01/2.1.0, 2019-05-01/2.2.0 and 2019-06-01/3.1.0. The 625 relationship between the revisions is as before: 627 Module revision date Revision label 628 2019-01-01 <- 1.0.0 629 | 630 2019-02-01 <- 2.0.0 631 | \ 632 2019-03-01 \ <- 3.0.0 633 | \ 634 | 2019-04-01 <- 2.1.0 635 | | 636 | 2019-05-01 <- 2.2.0 637 | 638 2019-06-01 <- 3.1.0 640 4.1.1. Example 1 642 This example selects module revisions that match, or are derived from 643 the revision 2019-02-01. E.g., this dependency might be used if 644 there was a new container added in revision 2019-02-01 that is 645 augmented by the importing module.It includes revisions/labels: 646 2019-02-01/2.0.0, 2019-03-01/3.0.0, 2019-04-01/2.1.0, 647 2019-05-01/2.2.0 and 2019-06-01/3.1.0. 649 import example-module { 650 rev:revision-or-derived 2019-02-01; 651 } 653 Alternatively, the first example could have used the revision label 654 "2.0.0" instead, which selects the same set of revisions/labels. 656 import example-module { 657 rev:revision-or-derived 2.0.0; 658 } 660 4.1.2. Example 2 662 This example selects module revisions that are derived from 663 2019-04-01 by using the revision label 2.1.0. It includes revisions/ 664 labels: 2019-04-01/2.1.0 and 2019-05-01/2.2.0. Even though 665 2019-06-01/3.1.0 has a higher revision label number than 666 2019-04-01/2.1.0 it is not a derived revision, and hence it is not a 667 valid revision for import. 669 import example-module { 670 rev:revision-or-derived 2.1.0; 671 } 673 4.1.3. Example 3 675 This example selects revisions derived from either 2019-04-01 or 676 2019-06-01. It includes revisions/labels: 2019-04-01/2.1.0, 677 2019-05-01/2.2.0, and 2019-06-01/3.1.0. 679 import example-module { 680 rev:revision-or-derived 2019-04-01; 681 rev:revision-or-derived 2019-06-01; 682 } 684 5. Updates to ietf-yang-library 686 This document updates YANG library [RFC7950] to clarify how ambiguous 687 module imports are resolved. It also defines the YANG module, ietf- 688 yang-library-revisions that augments YANG library [RFC8525] with new 689 revision-label related meta-data. 691 5.1. Resolving ambiguous module imports 693 A YANG datastore schema, defined in [RFC8525], can specify multiple 694 revisions of a YANG module in the schema using the "import-only" 695 list, with the requirement from [RFC7950] that only a single revision 696 of a YANG module may be implemented. 698 If a YANG module import statement does not specify a specific 699 revision within the datastore schema then it could be ambiguous as to 700 which module revision the import statement should resolve to. Hence, 701 a datastore schema constructed by a client using the information 702 contained in YANG library may not exactly match the datastore schema 703 actually used by the server. 705 The following two rules remove the ambiguity: 707 If a module import statement could resolve to more than one module 708 revision defined in the datastore schema, and one of those revisions 709 is implemented (i.e., not an "import-only" module), then the import 710 statement MUST resolve to the revision of the module that is defined 711 as being implemented by the datastore schema. 713 If a module import statement could resolve to more than one module 714 revision defined in the datastore schema, and none of those revisions 715 are implemented, then the import MUST resolve to the module revision 716 with the latest revision date. 718 5.2. YANG library versioning augmentations 720 The "ietf-yang-library-revisions" YANG module has the following 721 structure (using the notation defined in [RFC8340]): 723 module: ietf-yang-library-revisions 724 augment /yanglib:yang-library/yanglib:module-set/yanglib:module: 725 +--ro revision-label? rev:revision-label 726 augment /yanglib:yang-library/yanglib:schema: 727 +--ro deprecated-nodes-implemented? boolean 728 +--ro obsolete-nodes-absent? boolean 730 5.2.1. Advertising revision-label 732 The ietf-yang-library-revisions YANG module augments the "module" 733 list in ietf-yang-library with a "revision-label" leaf to optionally 734 declare the revision label associated wth the particular revision of 735 each module. 737 5.2.2. Reporting how deprecated and obsolete nodes are handled 739 The ietf-yang-library-revisions YANG module augments YANG library 740 with two leaves to allow a server to report how it handles status 741 "deprecated" and status "obsolete" nodes. The leaves are: 743 deprecated-nodes-implemented: If set to "true", this leaf indicates 744 that all schema nodes with a status "deprecated" child statement 745 are implemented equivalently as if they had status "current", or 746 otherwise deviations MUST be used to explicitly remove 747 "deprecated" nodes from the schema. If this leaf is set to 748 "false" or absent, then the behavior is unspecified. 750 obsolete-nodes-absent: If set to "true", this leaf indicates that 751 the server does not implement any status "obsolete" nodes. If 752 this leaf is set to "false" or absent, then the behaviour is 753 unspecified. 755 Servers SHOULD set both the "deprecated-nodes-implemented" and 756 "obsolete-nodes-absent" leaves to "true". 758 If a server does not set the "deprecated-nodes-implemented" leaf to 759 "true", then clients MUST NOT rely solely on the "rev:nbc-changes" 760 statements to determine whether two module revisions are backwards- 761 compatible, and MUST also consider whether the status of any nodes 762 has changed to "deprecated" and whether those nodes are implemented 763 by the server. 765 6. Versioning of YANG instance data 767 Instance data sets [I-D.ietf-netmod-yang-instance-file-format] do not 768 directly make use of the updated revision handling rules described in 769 this document, as compatibility for instance data is undefined. 771 However, instance data specifies the content-schema of the data-set. 772 This schema SHOULD make use of versioning using revision dates and/or 773 revision labels for the individual YANG modules that comprise the 774 schema or potentially for the entire schema itself (e.g., 775 [I-D.ietf-netmod-yang-packages] ). 777 In this way, the versioning of a content-schema associated with an 778 instance data set may help a client to determine whether the instance 779 data could also be used in conjunction with other revisions of the 780 YANG schema, or other revisions of the modules that define the 781 schema. 783 7. Guidelines for using the YANG module update rules 785 The following text updates section 4.7 of [RFC8407] to revise the 786 guidelines for updating YANG modules. 788 7.1. Guidelines for YANG module authors 790 All IETF YANG modules MUST include revision-label statements for all 791 newly published YANG modules, and all newly published revisions of 792 existing YANG modules. The revision-label MUST take the form of a 793 YANG semantic version number [I-D.ietf-netmod-yang-semver]. 795 NBC changes to YANG modules may cause problems to clients, who are 796 consumers of YANG models, and hence YANG module authors are 797 RECOMMENDED to minimize NBC changes and keep changes BC whenever 798 possible. 800 When NBC changes are introduced, consideration should be given to the 801 impact on clients and YANG module authors SHOULD try to mitigate that 802 impact. 804 A "rev:nbc-changes" statement MUST be added if there are NBC changes 805 relative to the previous revision. 807 Removing old revision statements from a module's revision history 808 could break import by revision, and hence it is RECOMMENDED to retain 809 them. If all depencencies have been updated to not import specific 810 revisions of a module, then the corresponding revision statements can 811 be removed from that module. An alternative solution, if the 812 revision section is too long, would be remove, or curtail, the older 813 description statements associated with the previous revisions. 815 The "rev:revision-or-derived" extension should be used in YANG module 816 imports to indicate revision dependencies between modules in 817 preference to the "revision-date" statement, which causes overly 818 strict import dependencies and SHOULD NOT be used. 820 A module that includes submodules SHOULD use the "revision-date" 821 statement to include specific submodule revisions. The revision of 822 the including module MUST be updated when any included submodule has 823 changed. The revision-label substatement used in the new module 824 revision MUST indicate the nature of the change, i.e. NBC or BC, to 825 the module's schema tree. 827 7.1.1. Making non-backwards-compatible changes to a YANG module 829 There are various valid situations where a YANG module has to be 830 modified in an NBC way. Here are the different ways in which this 831 can be done: 833 o NBC changes can be sometimes be done incrementally using the 834 "deprecated" status to provide clients time to adapt to NBC 835 changes. 837 o NBC changes are done at once, i.e. without using "status" 838 statements. Depending on the change, this may have a big impact 839 on clients. 841 o If the server can support multiple revisions of the YANG module or 842 of YANG packages(as specified in [I-D.ietf-netmod-yang-packages]), 843 and allows the client to select the revision (as per 844 [I-D.ietf-netmod-yang-ver-selection]), then NBC changes MAY be 845 done without using "status" statements. Clients would be required 846 to select the revision which they support and the NBC change would 847 have no impact on them 849 Here are some guidelines on how non-backwards-compatible changes can 850 be made incrementally, with the assumption that deprecated nodes are 851 implemented by the server, and obsolete nodes are not: 853 1. The changes should be made gradually, e.g. a data node's status 854 SHOULD NOT be changed directly from "current" to "obsolete" (see 855 Section 4.7 of [RFC8407]), instead the status SHOULD first be 856 marked "deprecated" and then when support is removed its status 857 MUST be changed to "obsolete". Instead of using the "obsolete" 858 status, the data node MAY be removed from the model but this has 859 the risk of breaking modules which import the modified module. 861 2. For deprecated data nodes the "description" statement SHOULD also 862 indicate until when support for the node is guaranteed (if 863 known). If there is a replacement data node, rpc, action or 864 notification for the deprecated node, this SHOULD be stated in 865 the "description". The reason for deprecating the node can also 866 be included in the "description" if it is deemed to be of 867 potential interest to the user. 869 3. For obsolete data nodes, it is RECOMMENDED to keep the above 870 information, from when the node had status "deprecated", which is 871 still relevant. 873 4. When obsoleting or deprecating data nodes, the "deprecated" or 874 "obsolete" status SHOULD be applied at the highest possible level 875 in the data tree. For clarity, the "status" statement SHOULD 876 also be applied to all descendent data nodes, but the additional 877 status related information does not need to be repeated if it 878 does not introduce any additional information. 880 5. NBC changes which can break imports SHOULD be avoided because of 881 the impact on the importing module. The importing modules could 882 get broken, e.g. if an augmented node in the importing module has 883 been removed from the imported module. Alternatively, the schema 884 of the importing modules could undergo an NBC change due to the 885 NBC change in the imported module, e.g. if a node in a grouping 886 has been removed. As described in Appendix B.1, instead of 887 removing a node, that node SHOULD first be deprecated and then 888 obsoleted. 890 See Appendix B for examples on how NBC changes can be made. 892 7.2. Versioning Considerations for Clients 894 Guidelines for clients of modules using the new module revision 895 update procedure: 897 o Clients SHOULD be liberal when processing data received from a 898 server. For example, the server may have increased the range of 899 an operational node causing the client to receive a value which is 900 outside the range of the YANG model revision it was coded against. 902 o Clients SHOULD monitor changes to published YANG modules through 903 their revision history, and use appropriate tooling to understand 904 the specific changes between module revision. In particular, 905 clients SHOULD NOT migrate to NBC revisions of a module without 906 understanding any potential impact of the specific NBC changes. 908 o Clients SHOULD plan to make changes to match published status 909 changes. When a node's status changes from "current" to 910 "deprecated", clients SHOULD plan to stop using that node in a 911 timely fashion. When a node's status changes to "obsolete", 912 clients MUST stop using that node. 914 8. Module Versioning Extension YANG Modules 916 YANG module with extension statements for annotating NBC changes, 917 revision label, revision label scheme, and importing by revision. 919 file "ietf-yang-revisions@2021-02-17.yang" 920 module ietf-yang-revisions { 921 yang-version 1.1; 922 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-revisions"; 923 prefix rev; 925 // RFC Ed.: We need the bis version to get the new type revision-identifier 926 // If 6991-bis is not yet an RFC we need to copy the definition here 927 import ietf-yang-types { 928 prefix yang; 929 reference 930 "XXXX [ietf-netmod-rfc6991-bis]: Common YANG Data Types"; 931 } 933 organization 934 "IETF NETMOD (Network Modeling) Working Group"; 935 contact 936 "WG Web: 937 WG List: 939 Author: Benoit Claise 940 942 Author: Joe Clarke 943 945 Author: Reshad Rahman 946 948 Author: Robert Wilton 949 951 Author: Kevin D'Souza 952 954 Author: Balazs Lengyel 955 957 Author: Jason Sterne 958 "; 959 description 960 "This YANG 1.1 module contains definitions and extensions to 961 support updated YANG revision handling. 963 Copyright (c) 2019 IETF Trust and the persons identified as 964 authors of the code. All rights reserved. 966 Redistribution and use in source and binary forms, with or 967 without modification, is permitted pursuant to, and subject 968 to the license terms contained in, the Simplified BSD License 969 set forth in Section 4.c of the IETF Trust's Legal Provisions 970 Relating to IETF Documents 971 (http://trustee.ietf.org/license-info). 973 This version of this YANG module is part of RFC XXXX; see 974 the RFC itself for full legal notices. 976 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 977 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 978 'MAY', and 'OPTIONAL' in this document are to be interpreted as 979 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 980 they appear in all capitals, as shown here."; 982 // RFC Ed.: update the date below with the date of RFC publication 983 // and remove this note. 984 // RFC Ed.: replace XXXX (inc above) with actual RFC number and 985 // remove this note. 987 revision 2021-02-17 { 988 description 989 "Initial version."; 990 reference 991 "XXXX: Updated YANG Module Revision Handling"; 992 } 994 typedef revision-label { 995 type string { 996 length "1..255"; 997 pattern '[a-zA-Z0-9,\-_.+]+'; 998 pattern '\d{4}-\d{2}-\d{2}' { 999 modifier invert-match; 1000 } 1001 } 1002 description 1003 "A label associated with a YANG revision. 1005 Alphanumeric characters, comma, hyphen, underscore, period 1006 and plus are the only accepted characters. MUST NOT match 1007 revision-date."; 1008 reference 1009 "XXXX: Updated YANG Module Revision Handling; 1010 Section 3.3, Revision label"; 1011 } 1013 typedef revision-date-or-label { 1014 type union { 1015 type yang:revision-identifier; 1016 type revision-label; 1017 } 1018 description 1019 "Represents either a YANG revision date or a revision label"; 1020 } 1022 extension nbc-changes { 1023 description 1024 "This statement is used to indicate YANG module revisions that 1025 contain non-backwards-compatible changes. 1027 The statement MUST only be a substatement of the 'revision' 1028 statement. 1029 Zero or one 'nbc-changes' statement per parent statement is 1030 allowed. 1031 The statement MUST NOT have any substatements. 1033 If a revision of a YANG module contains changes, relative to 1034 the preceding revision in the revision history, that do not 1035 conform to the module update rules defined in RFC-XXX, then 1036 the 'nbc-changes' statement MUST be added as a substatement to 1037 the revision statement. 1039 Conversely, if a revision of a YANG module only contains 1040 changes, relative to the preceding revision in the revision 1041 history, that are classified as 'backwards-compatible' then 1042 the revision statement MUST NOT contain any 'nbc-changes' 1043 substatement."; 1045 reference 1046 "XXXX: Updated YANG Module Revision Handling; 1047 Section 3.2, nbc-changes revision extension statement"; 1048 } 1050 extension revision-label { 1051 argument revision-label; 1052 description 1053 "The revision label can be used to provide an additional 1054 versioning identifier associated with the revision. E.g., one 1055 option for a versioning scheme that could be used is [TODO - 1056 Reference semver draft]. 1058 The format of the revision-label argument MUST conform to the 1059 pattern defined for the revision-label typedef. 1061 The statement MUST only be a substatement of the revision 1062 statement. 1063 Zero or one revision-label statement per parent statement 1064 is allowed. 1065 The statement MUST NOT have any substatements. 1067 Revision labels MUST be unique amongst all revisions of a 1068 module."; 1070 reference 1071 "XXXX: Updated YANG Module Revision Handling; 1072 Section 3.3, Revision label"; 1073 } 1075 extension revision-label-scheme { 1076 argument revision-label-scheme-identity; 1077 description 1078 "The revision label scheme specifies which revision-label scheme 1079 the module or submodule uses. 1081 The mandatory revision-label-scheme-identity argument MUST be an 1082 identity derived from revision-label-scheme-base. 1084 This extension is only valid as a top-level statement, i.e., 1085 given as as a substatement to 'module' or 'submodule'. 1087 This extension MUST be used if there is a revision-label 1088 statement in the module or submodule. 1090 The statement MUST NOT have any substatements."; 1092 reference 1093 "XXXX: Updated YANG Module Revision Handling; 1094 Section 3.3.1, Revision label scheme extension statement"; 1096 } 1098 extension revision-or-derived { 1099 argument revision-date-or-label; 1100 description 1101 "Restricts the revision of the module that may be imported to 1102 one that matches or is derived from the specified 1103 revision-date or revision-label. 1105 The argument value MUST conform to the 1106 'revision-date-or-label' defined type. 1108 The statement MUST only be a substatement of the import 1109 statement. 1110 Zero, one or more 'revision-or-derived' statement per parent 1111 statement is allowed. 1112 The statement MUST NOT have any substatements. 1114 If specified multiple 1115 times, then any module revision that satisfies at least one of 1116 the 'revision-or-derived' statements is an acceptable revision 1117 for import. 1119 An 'import' statement MUST NOT contain both a 1120 'revision-or-derived' extension statement and a 1121 'revision-date' statement. 1123 A particular revision of an imported module satisfies an 1124 import's 'revision-or-derived' extension statement if the 1125 imported module's revision history contains a revision 1126 statement with a matching revision date or revision label. 1128 The 'revision-or-derived' extension statement does not 1129 guarantee that all module revisions that satisfy an import 1130 statement are necessarily compatible, it only gives an 1131 indication that the revisions are more likely to be 1132 compatible."; 1134 reference 1135 "XXXX: Updated YANG Module Revision Handling; 1136 Section 4, Import by derived revision"; 1137 } 1139 identity revision-label-scheme-base { 1140 description 1141 "Base identity from which all revision label schemes are 1142 derived."; 1144 reference 1145 "XXXX: Updated YANG Module Revision Handling; 1146 Section 3.3.1, Revision label scheme extension statement"; 1148 } 1149 } 1150 1152 YANG module with augmentations to YANG Library to revision labels 1154 file "ietf-yang-library-revisions@2020-07-06.yang" 1155 module ietf-yang-library-revisions { 1156 yang-version 1.1; 1157 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-library-revisions"; 1158 prefix yl-rev; 1160 import ietf-yang-revisions { 1161 prefix rev; 1162 reference 1163 "XXXX: Updated YANG Module Revision Handling"; 1164 } 1166 import ietf-yang-library { 1167 prefix yanglib; 1168 reference "RFC 8525: YANG Library"; 1169 } 1171 organization 1172 "IETF NETMOD (Network Modeling) Working Group"; 1173 contact 1174 "WG Web: 1175 WG List: 1177 Author: Benoit Claise 1178 1180 Author: Joe Clarke 1181 1183 Author: Reshad Rahman 1184 1186 Author: Robert Wilton 1187 1189 Author: Kevin D'Souza 1190 1192 Author: Balazs Lengyel 1193 1195 Author: Jason Sterne 1196 "; 1197 description 1198 "This module contains augmentations to YANG Library to add module 1199 level revision label and to provide an indication of how 1200 deprecated and obsolete nodes are handled by the server. 1202 Copyright (c) 2019 IETF Trust and the persons identified as 1203 authors of the code. All rights reserved. 1205 Redistribution and use in source and binary forms, with or 1206 without modification, is permitted pursuant to, and subject 1207 to the license terms contained in, the Simplified BSD License 1208 set forth in Section 4.c of the IETF Trust's Legal Provisions 1209 Relating to IETF Documents 1210 (http://trustee.ietf.org/license-info). 1212 This version of this YANG module is part of RFC XXXX; see 1213 the RFC itself for full legal notices. 1215 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1216 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1217 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1218 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1219 they appear in all capitals, as shown here."; 1221 // RFC Ed.: update the date below with the date of RFC publication 1222 // and remove this note. 1223 // RFC Ed.: replace XXXX (including in the imports above) with 1224 // actual RFC number and remove this note. 1225 // RFC Ed.: please replace revision-label version with 1.0.0 and 1226 // remove this note. 1227 revision 2020-07-06 { 1228 rev:revision-label 0.1.0; 1229 description 1230 "Initial revision"; 1231 reference 1232 "XXXX: Updated YANG Module Revision Handling"; 1233 } 1235 augment "/yanglib:yang-library/yanglib:module-set/yanglib:module" { 1236 description 1237 "Augmentation modules with a revision label"; 1238 leaf revision-label { 1239 type rev:revision-label; 1240 description 1241 "The revision label associated with this module revision. 1242 The label MUST match the rev:label value in the specific 1243 revision of the module loaded in this module-set."; 1245 reference 1246 "XXXX: Updated YANG Module Revision Handling; 1247 Section 5.2.1, Advertising revision-label"; 1248 } 1249 } 1251 augment "/yanglib:yang-library/yanglib:schema" { 1252 description 1253 "Augmentations to the ietf-yang-library module to indicate how 1254 deprecated and obsoleted nodes are handled for each datastore 1255 schema supported by the server."; 1257 leaf deprecated-nodes-implemented { 1258 type boolean; 1259 description 1260 "If set to true, this leaf indicates that all schema nodes with 1261 a status 'deprecated' child statement are implemented 1262 equivalently as if they had status 'current', or otherwise 1263 deviations MUST be used to explicitly remove 'deprecated' 1264 nodes from the schema. If this leaf is set to false or absent, 1265 then the behavior is unspecified."; 1267 reference 1268 "XXXX: Updated YANG Module Revision Handling; 1269 Section 5.2.2, Reporting how deprecated and obsolete nodes 1270 are handled"; 1271 } 1273 leaf obsolete-nodes-absent { 1274 type boolean; 1275 description 1276 "If set to true, this leaf indicates that the server does not 1277 implement any status 'obsolete' nodes. If this leaf is 1278 set to false or absent, then the behaviour is unspecified."; 1280 reference 1281 "XXXX: Updated YANG Module Revision Handling; 1282 Section 5.2.2, Reporting how deprecated and obsolete nodes 1283 are handled"; 1284 } 1285 } 1286 } 1287 1288 9. Contributors 1290 This document grew out of the YANG module versioning design team that 1291 started after IETF 101. The following individuals are (or have been) 1292 members of the design team and have worked on the YANG versioning 1293 project: 1295 o Balazs Lengyel 1297 o Benoit Claise 1299 o Ebben Aries 1301 o Jason Sterne 1303 o Joe Clarke 1305 o Juergen Schoenwaelder 1307 o Mahesh Jethanandani 1309 o Michael (Wangzitao) 1311 o Qin Wu 1313 o Reshad Rahman 1315 o Rob Wilton 1317 o Bo Wu 1319 The initial revision of this document was refactored and built upon 1320 [I-D.clacla-netmod-yang-model-update]. 1322 Discussons on the use of Semver for YANG versioning has been held 1323 with authors of the OpenConfig YANG models. We would like thank both 1324 Anees Shaikh and Rob Shakir for their input into this problem space. 1326 We would also like to thank Martin Bjorklund, Jan Lindblad and Italo 1327 Busi for their contributions. 1329 10. Security Considerations 1331 The document does not define any new protocol or data model. There 1332 are no security considerations beyond those specified in [RFC7950]. 1334 11. IANA Considerations 1336 11.1. YANG Module Registrations 1338 The following YANG module is requested to be registred in the "IANA 1339 Module Names" registry: 1341 The ietf-yang-revisions module: 1343 Name: ietf-yang-revisions 1345 XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-revisions 1347 Prefix: rev 1349 Reference: [RFCXXXX] 1351 The ietf-yang-library-revisions module: 1353 Name: ietf-yang-library-revisions 1355 XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-library- 1356 revisions 1358 Prefix: yl-rev 1360 Reference: [RFCXXXX] 1362 11.2. Guidance for versioning in IANA maintained YANG modules 1364 Note for IANA (to be removed by the RFC editor): Please check that 1365 the registries and IANA YANG modules are referenced in the 1366 appropriate way. 1368 IANA is responsible for maintaining and versioning YANG modules that 1369 are derived from other IANA registries. For example, "iana-if- 1370 type.yang" [IfTypeYang] is derived from the "Interface Types (ifType) 1371 IANA registry" [IfTypesReg], and "iana-routing-types.yang" 1372 [RoutingTypesYang] is derived from the "Address Family Numbers" 1373 [AddrFamilyReg] and "Subsequent Address Family Identifiers (SAFI) 1374 Parameters" [SAFIReg] IANA registries. 1376 Normally, updates to the registries cause any derived YANG modules to 1377 be updated in a backwards-compatible way, but there are some cases 1378 where the registry updates can cause non-backward-compatible updates 1379 to the derived YANG module. An example of such an update is the 1380 2020-12-31 revision of iana-routing-types.yang 1382 [RoutingTypesDecRevision], where the enum name for two SAFI values 1383 was changed. 1385 In all cases, IANA MUST follow the versioning guidance specified in 1386 Section 3.1, and MUST include a "rev:nbc-changes" substatement to the 1387 latest revision statement whenever an IANA maintained module is 1388 updated in a non-backwards-compatible way, as described in 1389 Section 3.2. 1391 Note: For published IANA maintained YANG modules that contain non- 1392 backwards-compatible changes between revisions, a new revision should 1393 be published with the "rev:nbc-changes" substatement retrospectively 1394 added to any revisions containing non-backwards-compatible changes. 1396 Non normative examples of updates to enumeration types in IANA 1397 maintained modules that would be classified as non-backwards- 1398 compatible changes are: Changing the status of an enumeration typedef 1399 to obsolete, changing the status of an enum entry to obsolete, 1400 removing an enum entry, changing the identifier of an enum entry, or 1401 changing the described meaning of an enum entry. 1403 Non normative examples of updates to enumeration types in IANA 1404 maintained modules that would be classified as backwards-compatible 1405 changes are: Adding a new enum entry to the end of the enumeration, 1406 changing the status or an enum entry to deprecated, or improving the 1407 description of an enumeration that does not change its defined 1408 meaning. 1410 Non normative examples of updates to identity types in IANA 1411 maintained modules that would be classified as non-backwards- 1412 compatible changes are: Changing the status of an identity to 1413 obsolete, removing an identity, renaming an identity, or changing the 1414 described meaning of an identity. 1416 Non normative examples of updates to identity types in IANA 1417 maintained modules that would be classified as backwards-compatible 1418 changes are: Adding a new identity, changing the status or an 1419 identity to deprecated, or improving the description of an identity 1420 that does not change its defined meaning. 1422 12. References 1424 12.1. Normative References 1426 [I-D.ietf-netmod-rfc6991-bis] 1427 Schoenwaelder, J., "Common YANG Data Types", draft-ietf- 1428 netmod-rfc6991-bis-04 (work in progress), July 2020. 1430 [I-D.ietf-netmod-yang-semver] 1431 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, 1432 B., Sterne, J., and K. D'Souza, "YANG Semantic 1433 Versioning", draft-ietf-netmod-yang-semver-01 (work in 1434 progress), July 2020. 1436 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1437 Requirement Levels", BCP 14, RFC 2119, 1438 DOI 10.17487/RFC2119, March 1997, 1439 . 1441 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 1442 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 1443 . 1445 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1446 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1447 . 1449 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1450 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1451 May 2017, . 1453 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 1454 Documents Containing YANG Data Models", BCP 216, RFC 8407, 1455 DOI 10.17487/RFC8407, October 2018, 1456 . 1458 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 1459 and R. Wilton, "YANG Library", RFC 8525, 1460 DOI 10.17487/RFC8525, March 2019, 1461 . 1463 12.2. Informative References 1465 [AddrFamilyReg] 1466 "Address Family Numbers IANA Registry", 1467 . 1470 [I-D.clacla-netmod-yang-model-update] 1471 Claise, B., Clarke, J., Lengyel, B., and K. D'Souza, "New 1472 YANG Module Update Procedure", draft-clacla-netmod-yang- 1473 model-update-06 (work in progress), July 2018. 1475 [I-D.ietf-netmod-yang-instance-file-format] 1476 Lengyel, B. and B. Claise, "YANG Instance Data File 1477 Format", draft-ietf-netmod-yang-instance-file-format-12 1478 (work in progress), April 2020. 1480 [I-D.ietf-netmod-yang-packages] 1481 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and W. Bo, 1482 "YANG Packages", draft-ietf-netmod-yang-packages-01 (work 1483 in progress), November 2020. 1485 [I-D.ietf-netmod-yang-solutions] 1486 Wilton, R., "YANG Versioning Solution Overview", draft- 1487 ietf-netmod-yang-solutions-01 (work in progress), November 1488 2020. 1490 [I-D.ietf-netmod-yang-ver-selection] 1491 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and W. Bo, 1492 "YANG Schema Selection", draft-ietf-netmod-yang-ver- 1493 selection-00 (work in progress), March 2020. 1495 [I-D.ietf-netmod-yang-versioning-reqs] 1496 Clarke, J., "YANG Module Versioning Requirements", draft- 1497 ietf-netmod-yang-versioning-reqs-04 (work in progress), 1498 January 2021. 1500 [IfTypesReg] 1501 "Interface Types (ifType) IANA Registry", 1502 . 1505 [IfTypeYang] 1506 "iana-if-type YANG Module", 1507 . 1510 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1511 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1512 . 1514 [RoutingTypesDecRevision] 1515 "2020-12-31 revision of iana-routing-types.yang", 1516 . 1519 [RoutingTypesYang] 1520 "iana-routing-types YANG Module", 1521 . 1524 [SAFIReg] "Subsequent Address Family Identifiers (SAFI) Parameters 1525 IANA Registry", . 1528 [semver] "Semantic Versioning 2.0.0", . 1530 Appendix A. Examples of changes that are NBC 1532 Examples of NBC changes include: 1534 o Deleting a data node, or changing it to status obsolete. 1536 o Changing the name, type, or units of a data node. 1538 o Modifying the description in a way that changes the semantic 1539 meaning of the data node. 1541 o Any changes that change or reduce the allowed value set of the 1542 data node, either through changes in the type definition, or the 1543 addition or changes to "must" statements, or changes in the 1544 description. 1546 o Adding or modifying "when" statements that reduce when the data 1547 node is available in the schema. 1549 o Making the statement conditional on if-feature. 1551 Appendix B. Examples of applying the NBC change guidelines 1553 The following sections give guidance for how some of these NBC 1554 changes could be made to a YANG module. The examples are all for 1555 "config true" nodes. 1557 B.1. Removing a data node 1559 Removing a leaf or container from the data tree, e.g. because support 1560 for the corresponding feature is being removed: 1562 1. The node's status is changed to "deprecated" and it is supported 1563 for at least one year. This is a BC change. 1565 2. When the node is not available anymore, its status is changed to 1566 "obsolete" and the "description" updated, this is an NBC change. 1568 If the server can support NBC revisions of the YANG module 1569 simultaneously using version selection 1570 [I-D.ietf-netmod-yang-ver-selection], then the changes can be done 1571 immediately: 1573 1. The new revision of the YANG module has the node's status changed 1574 to "obsolete" and the "description" updated, this is an NBC 1575 change. 1577 2. Clients which require the data node select the YANG package 1578 containing the schema version they use 1580 B.2. Changing the type of a leaf node 1582 Changing the type of a leaf-node. e.g. consider a "vpn-id" node of 1583 type integer being changed to a string: 1585 1. The status of node "vpn-id" is changed to "deprecated" and the 1586 node should be available for at least one year. This is a BC 1587 change. 1589 2. A new node, e.g. "vpn-name", of type string is added to the same 1590 location as the existing node "vpn-id". This new node has status 1591 "current" and its description explains that it is replacing node 1592 "vpn-id". 1594 3. During the period of time where both nodes are available, how the 1595 server behaves when either node is set is outside the scope of 1596 this document and will vary on a case by case basis. Here are 1597 some options: 1599 1. A server may prevent the new node from being set if the old 1600 node is already set (and vice-versa). The new node may have 1601 a when statement to achieve this. The old node must not have 1602 a when statement since this would be an NBC change, but the 1603 server could reject the old node from being set if the new 1604 node is already set. 1606 2. If the new node is set and a client does a get or get-config 1607 operation on the old node, the server could map the value. 1608 For example, if the new node "vpn-name" has value "123" then 1609 the server could return integer value 123 for the old node 1610 "vpn-id". However, if the value can not be mapped then the 1611 configuration would be incomplete, this is outside the scope 1612 of this document. 1614 4. When node "vpn-id" is not available anymore, its status is 1615 changed to "obsolete" and the "description" is updated. This is 1616 an NBC change. 1618 If the server can support NBC revisions of the YANG module 1619 simultaneously using version selection 1621 [I-D.ietf-netmod-yang-ver-selection], then the changes can be done 1622 immediately: 1624 1. In the new revision of the YANG module, the status of node "vpn- 1625 id" is changed to "obsolete". This is an NBC change. 1627 2. New node "vpn-name" is added to the same location as described 1628 above. 1630 3. Clients which require the data node select the YANG package 1631 containing the schema version they use 1633 4. A server should not map between the nodes "vpn-id" and "vpn- 1634 name", i.e. if a client creates a data instance with "vpn-name" 1635 then that data instance should not be visible to a client using a 1636 module revision which has "vpn-id" (and vice-versa). 1638 B.3. Reducing the range of a leaf node 1640 Reducing the range of values of a leaf-node. e.g. consider a "vpn-id" 1641 node of type integer being changed from type uint32 to type uint16: 1643 1. If all values which are being removed were never supported, e.g. 1644 if a vpn-id of 65536 or higher was never accepted, this is a BC 1645 change for the functionality (no functionality change). Even if 1646 it is an NBC change for the YANG model, there should be no impact 1647 for clients using that YANG model. 1649 2. If one or more values being removed was previously supported, 1650 e.g. if a vpn-id of 65536 was accepted previously, this is an NBC 1651 change for the YANG model. Clients using the old YANG model will 1652 be impacted, so a change of this nature should be done carefully, 1653 e.g. by using the steps described in Appendix B.2 1655 B.4. Changing the key of a list 1657 Changing the key of a list has a big impact to the client. For 1658 example, consider a "sessions" list which has a key "interface" and 1659 there is a need to change the key to "dest-address", such a change 1660 can be done in steps: 1662 1. The status of list "sessions" is changed to "deprecated" and the 1663 list should be available for at least one year. This is a BC 1664 change. 1666 2. A new list is created in the same location with the same data but 1667 with "dest-address" as key. Finding an appropriate name for the 1668 new list can be tricky especially if the name of the existing 1669 list was perfect. In this case the new list is called "sessions- 1670 address", has status "current" and its description should explain 1671 that it is replacing list "session". 1673 3. During the period of time where both lists are available, how the 1674 server behaves when either list is set is outside the scope of 1675 this document and will vary on a case by case basis. Here are 1676 some options: 1678 1. A server could prevent the new list from being set if the old 1679 list already has entries (and vice-versa). 1681 2. If the new list is set and a client does a get or get-config 1682 operation on the old list, the server could map the entries. 1683 However if the new list has entries which would lead to 1684 duplicate keys in the old list, the mapping can not be done. 1686 4. When list "sessions" is not available anymore, its status is 1687 changed to "obsolete" and the "description" is updated. This is 1688 an NBC change. 1690 If the server can support NBC revisions of the YANG module 1691 simultaneously using version selection 1692 [I-D.ietf-netmod-yang-ver-selection], then the changes can be done 1693 immediately: 1695 1. The new revision of the YANG module has the list "sessions" 1696 modified to have "dest-address" as key, this is an NBC change. 1698 2. Clients which require the previous functionality select the older 1699 module revision 1701 B.5. Renaming a node 1703 A leaf-node or a container may be renamed, either due to a spelling 1704 error in the previous name or because of a better name. For example 1705 a node "ip-adress" could be renamed to "ip-address": 1707 1. The status of the existing node "ip-adress" is changed to 1708 "deprecated" and the node should be available for at least one 1709 year. This is a BC change. 1711 2. The new node "ip-address" is added to the same location as the 1712 existing node "ip-adress". This new node has status "current" 1713 and its description should explain that it is replacing node "ip- 1714 adress". 1716 3. During the period of time where both nodes are available, how the 1717 server behaves when either node is set is outside the scope of 1718 this document and will vary on a case by case basis. Here are 1719 some options: 1721 1. A server could prevent the new node from being set if the old 1722 node is already set (and vice-versa). The new node could 1723 have a when statement to achieve this. The old node must not 1724 have a when statement since this would be an NBC change, but 1725 the server could reject the old node from being set if the 1726 new node is already set. 1728 2. If the new node is set and a client does a get or get-config 1729 operation on the old node, the server could use the value of 1730 the new node. For example, if the new node "ip-address" has 1731 value X then the server may return value X for the old node 1732 "ip-adress". 1734 4. When node "ip-adress" is not available anymore, its status is 1735 changed to "obsolete" and the "description" is updated. This is 1736 an NBC change. 1738 If the server can support NBC revisions of the YANG module 1739 simultaneously using version selection 1740 [I-D.ietf-netmod-yang-ver-selection], then the changes can be done 1741 immediately: 1743 1. The new revision of the YANG module has the node with the new 1744 name replacing the node with the old name, this is an NBC change. 1746 2. Clients which require the previous node name select the older 1747 module revision 1749 B.6. Changing a default value 1751 Appendix C. Changes between revisions 1753 Note to RFC Editor (To be removed by RFC Editor) 1755 v00 - v01 1757 o Removed status-description 1759 o Allowed both revision-date and revision-label in the filename. 1761 o New extension revision-label-scheme 1762 o To include submodules, inclusion by revision-date changed from 1763 MUST to SHOULD 1765 o Submodules can use revision label scheme and it can be same or 1766 different as the including module's scheme 1768 o Addressed various comments provided at WG adoption on rev-00 1770 Authors' Addresses 1772 Robert Wilton (editor) 1773 Cisco Systems, Inc. 1775 Email: rwilton@cisco.com 1777 Reshad Rahman (editor) 1779 Email: reshad@yahoo.com 1781 Balazs Lengyel (editor) 1782 Ericsson 1784 Email: balazs.lengyel@ericsson.com 1786 Joe Clarke 1787 Cisco Systems, Inc. 1789 Email: jclarke@cisco.com 1791 Jason Sterne 1792 Nokia 1794 Email: jason.sterne@nokia.com 1796 Benoit Claise 1797 Huawei 1799 Email: benoit.claise@huawei.com 1800 Kevin D'Souza 1801 AT&T 1803 Email: kd6913@att.com