idnits 2.17.1 draft-ietf-netmod-yang-module-versioning-03.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 5 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 12, 2021) is 1011 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 1390, but not defined == Unused Reference: 'I-D.ietf-netmod-rfc6991-bis' is defined on line 1456, but no explicit reference was found in the text == Outdated reference: A later version (-15) exists of draft-ietf-netmod-rfc6991-bis-06 == Outdated reference: A later version (-15) exists of draft-ietf-netmod-yang-semver-02 ** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525) == Outdated reference: A later version (-21) exists of draft-ietf-netmod-yang-instance-file-format-13 == 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 (~~), 8 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: January 13, 2022 B. Lengyel, Ed. 7 Ericsson 8 J. Clarke 9 Cisco Systems, Inc. 10 J. Sterne 11 Nokia 12 July 12, 2021 14 Updated YANG Module Revision Handling 15 draft-ietf-netmod-yang-module-versioning-03 17 Abstract 19 This document specifies a new YANG module update procedure that can 20 document when non-backwards-compatible changes have occurred during 21 the evolution of a YANG module. It extends the YANG import statement 22 with an earliest revision filter to better represent inter-module 23 dependencies. It provides help and guidelines for managing the 24 lifecycle of YANG modules and individual schema nodes. It provides a 25 mechanism, via the revision-label YANG extension, to specify a 26 revision identifier for YANG modules and submodules. This document 27 updates RFC 7950, RFC 8407 and RFC 8525. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on January 13, 2022. 46 Copyright Notice 48 Copyright (c) 2021 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (https://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.1. Updates to YANG RFCs . . . . . . . . . . . . . . . . . . 4 65 2. Terminology and Conventions . . . . . . . . . . . . . . . . . 4 66 3. Refinements to YANG revision handling . . . . . . . . . . . . 5 67 3.1. Updating a YANG module with a new revision . . . . . . . 6 68 3.1.1. Backwards-compatible rules . . . . . . . . . . . . . 6 69 3.1.2. Non-backwards-compatible changes . . . . . . . . . . 7 70 3.2. non-backwards-compatible revision extension statement . . 7 71 3.3. Removing revisions from the revision history . . . . . . 7 72 3.4. Revision label . . . . . . . . . . . . . . . . . . . . . 8 73 3.4.1. File names . . . . . . . . . . . . . . . . . . . . . 8 74 3.4.2. Revision label scheme extension statement . . . . . . 9 75 3.5. Examples for updating the YANG module revision history . 9 76 4. Import by derived revision . . . . . . . . . . . . . . . . . 12 77 4.1. Module import examples . . . . . . . . . . . . . . . . . 14 78 5. Updates to ietf-yang-library . . . . . . . . . . . . . . . . 15 79 5.1. Resolving ambiguous module imports . . . . . . . . . . . 15 80 5.2. YANG library versioning augmentations . . . . . . . . . . 16 81 5.2.1. Advertising revision-label . . . . . . . . . . . . . 16 82 5.2.2. Reporting how deprecated and obsolete nodes are 83 handled . . . . . . . . . . . . . . . . . . . . . . . 16 84 6. Versioning of YANG instance data . . . . . . . . . . . . . . 17 85 7. Guidelines for using the YANG module update rules . . . . . . 17 86 7.1. Guidelines for YANG module authors . . . . . . . . . . . 17 87 7.1.1. Making non-backwards-compatible changes to a YANG 88 module . . . . . . . . . . . . . . . . . . . . . . . 18 89 7.2. Versioning Considerations for Clients . . . . . . . . . . 20 90 8. Module Versioning Extension YANG Modules . . . . . . . . . . 20 91 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 29 92 10. Security Considerations . . . . . . . . . . . . . . . . . . . 30 93 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 94 11.1. YANG Module Registrations . . . . . . . . . . . . . . . 30 95 11.2. Guidance for versioning in IANA maintained YANG modules 31 96 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 32 97 12.1. Normative References . . . . . . . . . . . . . . . . . . 32 98 12.2. Informative References . . . . . . . . . . . . . . . . . 33 99 Appendix A. Examples of changes that are NBC . . . . . . . . . . 34 100 Appendix B. Examples of applying the NBC change guidelines . . . 35 101 B.1. Removing a data node . . . . . . . . . . . . . . . . . . 35 102 B.2. Changing the type of a leaf node . . . . . . . . . . . . 36 103 B.3. Reducing the range of a leaf node . . . . . . . . . . . . 37 104 B.4. Changing the key of a list . . . . . . . . . . . . . . . 37 105 B.5. Renaming a node . . . . . . . . . . . . . . . . . . . . . 38 106 B.6. Changing a default value . . . . . . . . . . . . . . . . 39 107 Appendix C. Changes between revisions . . . . . . . . . . . . . 39 108 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 39 110 1. Introduction 112 This document defines a solution to the YANG module lifecycle 113 problems described in [I-D.ietf-netmod-yang-versioning-reqs]. 114 Complementary documents provide a complete solution to the YANG 115 versioning requirements, with the overall relationship of the 116 solution drafts described in [I-D.ietf-netmod-yang-solutions]. 118 Specifically, this document recognises a need (within standards 119 organizations, vendors, and the industry) to sometimes allow YANG 120 modules to evolve with non-backwards-compatible changes, which could 121 cause breakage to clients and importing YANG modules. Accepting that 122 non-backwards-compatible changes do sometimes occur, it is important 123 to have mechanisms to report where these changes occur, and to manage 124 their effect on clients and the broader YANG ecosystem. 126 The document comprises five parts: 128 Refinements to the YANG 1.1 module revision update procedure, 129 supported by new extension statements to indicate when a revision 130 contains non-backwards-compatible changes, and an optional 131 revision label. 133 A YANG extension statement allowing YANG module imports to specify 134 an earliest module revision that may satisfy the import 135 dependency. 137 Updates and augmentations to ietf-yang-library to include the 138 revision label in the module and submodule descriptions, to report 139 how "deprecated" and "obsolete" nodes are handled by a server, and 140 to clarify how module imports are resolved when multiple revisions 141 could otherwise be chosen. 143 Considerations of how versioning applies to YANG instance data. 145 Guidelines for how the YANG module update rules defined in this 146 document should be used, along with examples. 148 Note to RFC Editor (To be removed by RFC Editor) 150 Open issues are tracked at . 153 1.1. Updates to YANG RFCs 155 This document updates [RFC7950] section 11. Section 3 describes 156 modifications to YANG revision handling and update rules, and 157 Section 4 describes a YANG extension statement to do import by 158 derived revision. 160 This document updates [RFC7950] section 5.2. Section 3.4.1 describes 161 the use of a revision label in the name of a file containing a YANG 162 module or submodule. 164 This document updates [RFC7950] section 5.6.5. Section 5.1 defines 165 how a client of a YANG library datastore schema resolves ambiguous 166 imports for modules which are not "import-only". 168 This document updates [RFC8407] section 4.7. Section 7 provides 169 guidelines on managing the lifecycle of YANG modules that may contain 170 non-backwards-compatible changes and a branched revision history. 172 This document updates [RFC8525] with augmentations to include 173 revision labels in the YANG library data and two boolean leaves to 174 indicate whether status deprecated and status obsolete schema nodes 175 are implemented by the server. 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.2 199 3. Refinements to YANG revision handling 201 [RFC7950] assumes, but does not explicitly state, that the revision 202 history for a YANG module or submodule is strictly linear, i.e., it 203 is prohibited to have two independent revisions of a YANG module or 204 submodule that are both directly derived from the same parent 205 revision. 207 This document clarifies [RFC7950] to explicitly allow non-linear 208 development of YANG module and submodule revisions, so that they MAY 209 have multiple revisions that directly derive from the same parent 210 revision. As per [RFC7950], YANG module and submodule revisions 211 continue to be uniquely identified by their revision date, and hence 212 all revisions of a given module or submodule MUST have unique 213 revision dates. 215 A corollary to the above is that the relationship between two module 216 or submodule revisions cannot be determined by comparing the module 217 or submodule revision date alone, and the revision history, or 218 revision label, must also be taken into consideration. 220 A module's name and revision date identifies a specific immutable 221 definition of that module within its revision history. Hence, if a 222 module includes submodules then to ensure that the module's content 223 is uniquely defined, the module's "include" statements SHOULD use 224 "revision-date" substatements to specify the exact revision date of 225 each included submodule. When a module does not include its 226 submodules by revision-date, the revision of submodules used cannot 227 be derived from the including module. Mechanisms such as YANG 228 packages [I-D.ietf-netmod-yang-packages], and YANG library [RFC7895] 229 [RFC8525], MAY be used to specify the exact submodule revisions used 230 when the submodule revision date is not constrained by the "include" 231 statement. 233 [RFC7950] section 11 requires that all updates to a YANG module are 234 BC to the previous revision of the module. This document introduces 235 a method to indicate that an NBC change has occurred between module 236 revisions: this is done by using a new "non-backwards-compatible" 237 YANG extension statement in the module revision history. 239 Two revisions of a module or submodule MAY have identical content 240 except for the revision history. This could occur, for example, if a 241 module or submodule has a branched history and identical changes are 242 applied in multiple branches. 244 3.1. Updating a YANG module with a new revision 246 This section updates [RFC7950] section 11 to refine the rules for 247 permissible changes when a new YANG module revision is created. 249 Where pragmatic, updates to YANG modules SHOULD be backwards- 250 compatible, following the definition in Section 3.1.1. 252 A new module revision MAY contain NBC changes, e.g., the semantics of 253 an existing data-node definition MAY be changed in an NBC manner 254 without requiring a new data-node definition with a new identifier. 255 A YANG extension, defined in Section 3.2, is used to signal the 256 potential for incompatibility to existing module users and readers. 258 As per [RFC7950], all published revisions of a module are given a new 259 unique revision date. This applies even for module revisions 260 containing (in the module or included submodules) only changes to any 261 whitespace, formatting, comments or line endings (e.g., DOS vs UNIX). 263 3.1.1. Backwards-compatible rules 265 A change between two module revisions is defined as being "backwards- 266 compatible" if the change conforms to the module update rules 267 specified in [RFC7950] section 11, updated by the following rules: 269 o A "status" "deprecated" statement MAY be added, or changed from 270 "current" to "deprecated", but adding or changing "status" to 271 "obsolete" is not a backwards-compatible change. 273 o YANG schema nodes with a "status" "obsolete" substatement MAY be 274 removed from published modules, and are classified as backwards- 275 compatible changes. In some circumstances it may be helpful to 276 retain the obsolete definitions to ensure that their identifiers 277 are not reused with a different meaning. 279 o In statements that have any data definition statements as 280 substatements, those data definition substatements MAY be 281 reordered, as long as they do not change the ordering of any 282 "input" or "output" data definition substatements of "rpc" or 283 "action" statements. If new data definition statements are added, 284 they can be added anywhere in the sequence of existing 285 substatements. 287 o Any changes (including whitespace or formatting changes) that do 288 not change the semantic meaning of the module are backwards 289 compatible. 291 o A statement that is defined using the YANG "extension" statement 292 MAY be added, removed, or changed, if it does not change the 293 semantics of the module. Extension statement definitions SHOULD 294 specify whether adding, removing, or changing statements defined 295 by that extension are backwards-compatible or non-backwards- 296 compatible. 298 3.1.2. Non-backwards-compatible changes 300 Any changes to YANG modules that are not defined by Section 3.1.1 as 301 being backwards-compatible are classified as "non-backwards- 302 compatible" changes. 304 3.2. non-backwards-compatible revision extension statement 306 The "rev:non-backwards-compatible" extension statement is used to 307 indicate YANG module revisions that contain NBC changes. 309 If a revision of a YANG module contains changes, relative to the 310 preceding revision in the revision history, that do not conform to 311 the module update rules defined in Section 3.1.1, then a "rev:non- 312 backwards-compatible" extension statement MUST be added as a 313 substatement to the "revision" statement. 315 3.3. Removing revisions from the revision history 317 Authors may wish to remove revision statements from a module or 318 submodule. Removal of revision information may be desired for a 319 number of reasons including reducing the size of a large revision 320 history, or removing a revision that should no longer be used or 321 imported. Removing revision statements is allowed, but can cause 322 issues and SHOULD NOT be done without careful analysis of the 323 potential impact to users of the module or submodule. Doing so can 324 lead to import breakages when import by revision-or-derived is used. 325 Moreover, truncating history may cause loss of visibility of when 326 non-backwards-compatible changes were introduced. 328 If a revision containing a rev:non-backwards-compatible substatement 329 is removed from the revision history then a rev:non-backwards- 330 compatible substatement MUST be added to the nearest newer revision 331 entry in the revision history that is not being removed. 333 3.4. Revision label 335 Each revision entry in a module or submodule MAY have a revision 336 label associated with it, providing an alternative alias to identify 337 a particular revision of a module or submodule. The revision label 338 could be used to provide an additional versioning identifier 339 associated with the revision. 341 YANG Semver [I-D.ietf-netmod-yang-semver] defines a versioning scheme 342 based on Semver 2.0.0 [semver] that can be used as a revision label. 344 Submodules MAY use a revision label scheme. When they use a revision 345 label scheme, submodules MAY use a revision label scheme that is 346 different from the one used in the including module. 348 The revision label space of submodules is separate from the revision 349 label space of the including module. A change in one submodule MUST 350 result in a new revision label of that submodule and the including 351 module, but the actual values of the revision labels in the module 352 and submodule could be completely different. A change in one 353 submodule does not result in a new revision label in another 354 submodule. A change in a module revision label does not necessarily 355 mean a change to the revision label in all included submodules. 357 If a revision has an associated revision label, then it may be used 358 instead of the revision date in a "rev:revision-or-derived" extension 359 statement argument. 361 A specific revision-label identifies a specific revision (variant) of 362 the module. If two YANG modules contain the same module name and the 363 same revision-label (and hence also the same revision-date) in their 364 latest revision statement, then the file contents of the two modules, 365 including the revision history, MUST be identical. 367 3.4.1. File names 369 This section updates [RFC7950] section 5.2. 371 If a revision has an associated revision label, then the revision- 372 label may be used instead of the revision date in the filename of a 373 YANG file, where it takes the form: 375 module-or-submodule-name [['@' revision-date]|['#' revision-label]] 376 ( '.yang' / '.yin' ) 378 E.g., acme-router-module@2018-01-25.yang 379 E.g., acme-router-module#2.0.3.yang 381 YANG module (or submodule) files MAY be identified using either 382 revision-date or revision-label. Typically, only one file name 383 SHOULD exist for the same module (or submodule) revision. Two file 384 names, one with the revision date and another with the revision 385 label, MAY exist for the same module (or submodule) revision, e.g., 386 when migrating from one scheme to the other. 388 3.4.2. Revision label scheme extension statement 390 The optional "rev:revision-label-scheme" extension statement is used 391 to indicate which revision-label scheme a module or submodule uses. 392 There MUST NOT be more than one revision label scheme in a module or 393 submodule. The mandatory argument to this extension statement: 395 o specifies the revision-label scheme used by the module or 396 submodule 398 o is defined in the document which specifies the revision-label 399 scheme 401 o MUST be an identity derived from "revision-label-scheme-base". 403 The revision-label scheme used by a module or submodule SHOULD NOT 404 change during the lifetime of the module or submodule. If the 405 revision-label scheme used by a module or submodule is changed to a 406 new scheme, then all revision-label statements that do not conform to 407 the new scheme MUST be replaced or removed. 409 3.5. Examples for updating the YANG module revision history 411 The following diagram, explanation, and module history illustrates 412 how the branched revision history, "non-backwards-compatible" 413 extension statement, and "revision-label" extension statement could 414 be used: 416 Example YANG module with branched revision history. 418 Module revision date Revision label 419 2019-01-01 <- 1.0.0 420 | 421 2019-02-01 <- 2.0.0 422 | \ 423 2019-03-01 \ <- 3.0.0 424 | \ 425 | 2019-04-01 <- 2.1.0 426 | | 427 | 2019-05-01 <- 2.2.0 428 | 429 2019-06-01 <- 3.1.0 431 The tree diagram above illustrates how an example module's revision 432 history might evolve, over time. For example, the tree might 433 represent the following changes, listed in chronological order from 434 the oldest revision to the newest revision: 436 Example module, revision 2019-06-01: 438 module example-module { 440 namespace "urn:example:module"; 441 prefix "prefix-name"; 442 rev:revision-label-scheme "yangver:yang-semver"; 444 import ietf-yang-revisions { prefix "rev"; } 445 import ietf-yang-semver { prefix "yangver"; } 447 description 448 "to be completed"; 450 revision 2019-06-01 { 451 rev:revision-label 3.1.0; 452 description "Add new functionality."; 453 } 455 revision 2019-03-01 { 456 rev:revision-label 3.0.0; 457 rev:non-backwards-compatible; 458 description 459 "Add new functionality. Remove some deprecated nodes."; 460 } 462 revision 2019-02-01 { 463 rev:revision-label 2.0.0; 464 rev:non-backwards-compatible; 465 description "Apply bugfix to pattern statement"; 466 } 468 revision 2019-01-01 { 469 rev:revision-label 1.0.0; 470 description "Initial revision"; 471 } 473 //YANG module definition starts here 474 } 476 Example module, revision 2019-05-01: 478 module example-module { 480 namespace "urn:example:module"; 481 prefix "prefix-name"; 482 rev:revision-label-scheme "yangver:yang-semver"; 484 import ietf-yang-revisions { prefix "rev"; } 485 import ietf-yang-semver { prefix "yangver"; } 487 description 488 "to be completed"; 490 revision 2019-05-01 { 491 rev:revision-label 2.2.0; 492 description "Backwards-compatible bugfix to enhancement."; 493 } 495 revision 2019-04-01 { 496 rev:revision-label 2.1.0; 497 description "Apply enhancement to older release train."; 498 } 500 revision 2019-02-01 { 501 rev:revision-label 2.0.0; 502 rev:non-backwards-compatible; 503 description "Apply bugfix to pattern statement"; 504 } 506 revision 2019-01-01 { 507 rev:revision-label 1.0.0; 508 description "Initial revision"; 509 } 511 //YANG module definition starts here 512 } 514 4. Import by derived revision 516 RFC 7950 allows YANG module "import" statements to optionally require 517 the imported module to have a particular revision date. In practice, 518 importing a module with an exact revision date is often too 519 restrictive because it requires the importing module to be updated 520 whenever any change to the imported module occurs. The alternative 521 choice of using an import statement without any revision date 522 statement is also not ideal because the importing module may not work 523 with all possible revisions of the imported module. 525 Instead, it is desirable for an importing module to specify a 526 "minimum required revision" of a module that it is compatible with, 527 based on the assumption that later revisions derived from that 528 "minimum required revision" are also likely to be compatible. Many 529 possible changes to a YANG module do not break importing modules, 530 even if the changes themselves are not strictly backwards-compatible. 531 E.g., fixing an incorrect pattern statement or description for a leaf 532 would not break an import, changing the name of a leaf could break an 533 import but frequently would not, but removing a container would break 534 imports if that container is augmented by another module. 536 The ietf-revisions module defines the "revision-or-derived" extension 537 statement, a substatement to the YANG "import" statement, to allow 538 for a "minimum required revision" to be specified during import: 540 The argument to the "revision-or-derived" extension statement is a 541 revision date or a revision label. 543 A particular revision of an imported module satisfies an import's 544 "revision-or-derived" extension statement if the imported module's 545 revision history contains a revision statement with a matching 546 revision date or revision label. 548 An "import" statement MUST NOT contain both a "revision-or- 549 derived" extension statement and a "revision-date" statement. 551 The "revision-or-derived" extension statement MAY be specified 552 multiple times, allowing the import to use any module revision 553 that satisfies at least one of the "revision-or-derived" extension 554 statements. 556 The "revision-or-derived" extension statement does not guarantee 557 that all module revisions that satisfy an import statement are 558 necessarily compatible, it only gives an indication that the 559 revisions are more likely to be compatible. Hence, NBC changes to 560 an imported module may also require new revisions of any importing 561 modules, updated to accommodation those changes, along with 562 updated import "revision-or-derived" extension statements to 563 depend on the updated imported module revision. 565 Adding, modifying or removing a "revision-or-derived" extension 566 statement is considered to be a BC change. 568 Adding, modifying or removing a "revision-date" extension 569 statement is considered to be a BC change. 571 4.1. Module import examples 573 Consider the example module "example-module" from Section 3.5 that is 574 hypothetically available in the following revision/label pairings: 575 2019-01-01/1.0.0, 2019-02-01/2.0.0, 2019-03-01/3.0.0, 576 2019-04-01/2.1.0, 2019-05-01/2.2.0 and 2019-06-01/3.1.0. The 577 relationship between the revisions is as before: 579 Module revision date Revision label 580 2019-01-01 <- 1.0.0 581 | 582 2019-02-01 <- 2.0.0 583 | \ 584 2019-03-01 \ <- 3.0.0 585 | \ 586 | 2019-04-01 <- 2.1.0 587 | | 588 | 2019-05-01 <- 2.2.0 589 | 590 2019-06-01 <- 3.1.0 592 4.1.1. Example 1 594 This example selects module revisions that match, or are derived from 595 the revision 2019-02-01. E.g., this dependency might be used if 596 there was a new container added in revision 2019-02-01 that is 597 augmented by the importing module. It includes revisions/labels: 598 2019-02-01/2.0.0, 2019-03-01/3.0.0, 2019-04-01/2.1.0, 599 2019-05-01/2.2.0 and 2019-06-01/3.1.0. 601 import example-module { 602 rev:revision-or-derived 2019-02-01; 603 } 605 Alternatively, the first example could have used the revision label 606 "2.0.0" instead, which selects the same set of revisions/labels. 608 import example-module { 609 rev:revision-or-derived 2.0.0; 610 } 612 4.1.2. Example 2 614 This example selects module revisions that are derived from 615 2019-04-01 by using the revision label 2.1.0. It includes revisions/ 616 labels: 2019-04-01/2.1.0 and 2019-05-01/2.2.0. Even though 617 2019-06-01/3.1.0 has a higher revision label number than 618 2019-04-01/2.1.0 it is not a derived revision, and hence it is not a 619 valid revision for import. 621 import example-module { 622 rev:revision-or-derived 2.1.0; 623 } 625 4.1.3. Example 3 627 This example selects revisions derived from either 2019-04-01 or 628 2019-06-01. It includes revisions/labels: 2019-04-01/2.1.0, 629 2019-05-01/2.2.0, and 2019-06-01/3.1.0. 631 import example-module { 632 rev:revision-or-derived 2019-04-01; 633 rev:revision-or-derived 2019-06-01; 634 } 636 5. Updates to ietf-yang-library 638 This document updates YANG library [RFC7950] to clarify how ambiguous 639 module imports are resolved. It also defines the YANG module, ietf- 640 yang-library-revisions that augments YANG library [RFC8525] with new 641 revision-label related meta-data. 643 5.1. Resolving ambiguous module imports 645 A YANG datastore schema, defined in [RFC8525], can specify multiple 646 revisions of a YANG module in the schema using the "import-only" 647 list, with the requirement from [RFC7950] that only a single revision 648 of a YANG module may be implemented. 650 If a YANG module import statement does not specify a specific 651 revision within the datastore schema then it could be ambiguous as to 652 which module revision the import statement should resolve to. Hence, 653 a datastore schema constructed by a client using the information 654 contained in YANG library may not exactly match the datastore schema 655 actually used by the server. 657 The following two rules remove the ambiguity: 659 If a module import statement could resolve to more than one module 660 revision defined in the datastore schema, and one of those revisions 661 is implemented (i.e., not an "import-only" module), then the import 662 statement MUST resolve to the revision of the module that is defined 663 as being implemented by the datastore schema. 665 If a module import statement could resolve to more than one module 666 revision defined in the datastore schema, and none of those revisions 667 are implemented, then the import MUST resolve to the module revision 668 with the latest revision date. 670 5.2. YANG library versioning augmentations 672 The "ietf-yang-library-revisions" YANG module has the following 673 structure (using the notation defined in [RFC8340]): 675 module: ietf-yang-library-revisions 676 augment /yanglib:yang-library/yanglib:module-set/yanglib:module: 677 +--ro revision-label? rev:revision-label 678 augment /yanglib:yang-library/yanglib:module-set/yanglib:module 679 /yanglib:submodule: 680 +--ro revision-label? rev:revision-label 681 augment /yanglib:yang-library/yanglib:module-set 682 /yanglib:import-only-module/yanglib:submodule: 683 +--ro revision-label? rev:revision-label 684 augment /yanglib:yang-library/yanglib:schema: 685 +--ro deprecated-nodes-implemented? boolean 686 +--ro obsolete-nodes-absent? boolean 688 5.2.1. Advertising revision-label 690 The ietf-yang-library-revisions YANG module augments the "module" 691 list in ietf-yang-library with a "revision-label" leaf to optionally 692 declare the revision label associated wth the particular revision of 693 each module. 695 5.2.2. Reporting how deprecated and obsolete nodes are handled 697 The ietf-yang-library-revisions YANG module augments YANG library 698 with two leaves to allow a server to report how it handles status 699 "deprecated" and status "obsolete" nodes. The leaves are: 701 deprecated-nodes-implemented: If set to "true", this leaf indicates 702 that all schema nodes with a status "deprecated" child statement 703 are implemented equivalently as if they had status "current", or 704 otherwise deviations MUST be used to explicitly remove 705 "deprecated" nodes from the schema. If this leaf is set to 706 "false" or absent, then the behavior is unspecified. 708 obsolete-nodes-absent: If set to "true", this leaf indicates that 709 the server does not implement any status "obsolete" nodes. If 710 this leaf is set to "false" or absent, then the behaviour is 711 unspecified. 713 Servers SHOULD set both the "deprecated-nodes-implemented" and 714 "obsolete-nodes-absent" leaves to "true". 716 If a server does not set the "deprecated-nodes-implemented" leaf to 717 "true", then clients MUST NOT rely solely on the "rev:non-backwards- 718 compatible" statements to determine whether two module revisions are 719 backwards-compatible, and MUST also consider whether the status of 720 any nodes has changed to "deprecated" and whether those nodes are 721 implemented by the server. 723 6. Versioning of YANG instance data 725 Instance data sets [I-D.ietf-netmod-yang-instance-file-format] do not 726 directly make use of the updated revision handling rules described in 727 this document, as compatibility for instance data is undefined. 729 However, instance data specifies the content-schema of the data-set. 730 This schema SHOULD make use of versioning using revision dates and/or 731 revision labels for the individual YANG modules that comprise the 732 schema or potentially for the entire schema itself (e.g., 733 [I-D.ietf-netmod-yang-packages]). 735 In this way, the versioning of a content-schema associated with an 736 instance data set may help a client to determine whether the instance 737 data could also be used in conjunction with other revisions of the 738 YANG schema, or other revisions of the modules that define the 739 schema. 741 7. Guidelines for using the YANG module update rules 743 The following text updates section 4.7 of [RFC8407] to revise the 744 guidelines for updating YANG modules. 746 7.1. Guidelines for YANG module authors 748 All IETF YANG modules MUST include revision-label statements for all 749 newly published YANG modules, and all newly published revisions of 750 existing YANG modules. The revision-label MUST take the form of a 751 YANG semantic version number [I-D.ietf-netmod-yang-semver]. 753 NBC changes to YANG modules may cause problems to clients, who are 754 consumers of YANG models, and hence YANG module authors are 755 RECOMMENDED to minimize NBC changes and keep changes BC whenever 756 possible. 758 When NBC changes are introduced, consideration should be given to the 759 impact on clients and YANG module authors SHOULD try to mitigate that 760 impact. 762 A "rev:non-backwards-compatible" statement MUST be added if there are 763 NBC changes relative to the previous revision. 765 Removing old revision statements from a module's revision history 766 could break import by revision, and hence it is RECOMMENDED to retain 767 them. If all depencencies have been updated to not import specific 768 revisions of a module, then the corresponding revision statements can 769 be removed from that module. An alternative solution, if the 770 revision section is too long, would be to remove, or curtail, the 771 older description statements associated with the previous revisions. 773 The "rev:revision-or-derived" extension should be used in YANG module 774 imports to indicate revision dependencies between modules in 775 preference to the "revision-date" statement, which causes overly 776 strict import dependencies and SHOULD NOT be used. 778 A module that includes submodules SHOULD use the "revision-date" 779 statement to include specific submodule revisions. The revision of 780 the including module MUST be updated when any included submodule has 781 changed. The revision-label substatement used in the new module 782 revision MUST indicate the nature of the change, i.e. NBC or BC, to 783 the module's schema tree. 785 In some cases a module or submodule revision that is not strictly NBC 786 by the definition in Section 3.1.2 of this specification may include 787 the "non-backwards-compatible" statement. Here is an example when 788 adding the statement may be desirable: 790 o A "config false" leaf had its value space expanded (for example, a 791 range was increased, or additional enum values were added) and the 792 author or server implementor feels there is a significant 793 compatibility impact for clients and users of the module or 794 submodule 796 7.1.1. Making non-backwards-compatible changes to a YANG module 798 There are various valid situations where a YANG module has to be 799 modified in an NBC way. Here are the different ways in which this 800 can be done: 802 o NBC changes can be sometimes be done incrementally using the 803 "deprecated" status to provide clients time to adapt to NBC 804 changes. 806 o NBC changes are done at once, i.e. without using "status" 807 statements. Depending on the change, this may have a big impact 808 on clients. 810 o If the server can support multiple revisions of the YANG module or 811 of YANG packages(as specified in [I-D.ietf-netmod-yang-packages]), 812 and allows the client to select the revision (as per 813 [I-D.ietf-netmod-yang-ver-selection]), then NBC changes MAY be 814 done without using "status" statements. Clients would be required 815 to select the revision which they support and the NBC change would 816 have no impact on them. 818 Here are some guidelines on how non-backwards-compatible changes can 819 be made incrementally, with the assumption that deprecated nodes are 820 implemented by the server, and obsolete nodes are not: 822 1. The changes should be made gradually, e.g., a data node's status 823 SHOULD NOT be changed directly from "current" to "obsolete" (see 824 Section 4.7 of [RFC8407]), instead the status SHOULD first be 825 marked "deprecated" and then when support is removed its status 826 MUST be changed to "obsolete". Instead of using the "obsolete" 827 status, the data node MAY be removed from the model but this has 828 the risk of breaking modules which import the modified module. 830 2. For deprecated data nodes the "description" statement SHOULD also 831 indicate until when support for the node is guaranteed (if 832 known). If there is a replacement data node, rpc, action or 833 notification for the deprecated node, this SHOULD be stated in 834 the "description". The reason for deprecating the node can also 835 be included in the "description" if it is deemed to be of 836 potential interest to the user. 838 3. For obsolete data nodes, it is RECOMMENDED to keep the above 839 information, from when the node had status "deprecated", which is 840 still relevant. 842 4. When obsoleting or deprecating data nodes, the "deprecated" or 843 "obsolete" status SHOULD be applied at the highest possible level 844 in the data tree. For clarity, the "status" statement SHOULD 845 also be applied to all descendent data nodes, but the additional 846 status related information does not need to be repeated if it 847 does not introduce any additional information. 849 5. NBC changes which can break imports SHOULD be avoided because of 850 the impact on the importing module. The importing modules could 851 get broken, e.g., if an augmented node in the importing module 852 has been removed from the imported module. Alternatively, the 853 schema of the importing modules could undergo an NBC change due 854 to the NBC change in the imported module, e.g., if a node in a 855 grouping has been removed. As described in Appendix B.1, instead 856 of removing a node, that node SHOULD first be deprecated and then 857 obsoleted. 859 See Appendix B for examples on how NBC changes can be made. 861 7.2. Versioning Considerations for Clients 863 Guidelines for clients of modules using the new module revision 864 update procedure: 866 o Clients SHOULD be liberal when processing data received from a 867 server. For example, the server may have increased the range of 868 an operational node causing the client to receive a value which is 869 outside the range of the YANG model revision it was coded against. 871 o Clients SHOULD monitor changes to published YANG modules through 872 their revision history, and use appropriate tooling to understand 873 the specific changes between module revision. In particular, 874 clients SHOULD NOT migrate to NBC revisions of a module without 875 understanding any potential impact of the specific NBC changes. 877 o Clients SHOULD plan to make changes to match published status 878 changes. When a node's status changes from "current" to 879 "deprecated", clients SHOULD plan to stop using that node in a 880 timely fashion. When a node's status changes to "obsolete", 881 clients MUST stop using that node. 883 8. Module Versioning Extension YANG Modules 885 YANG module with extension statements for annotating NBC changes, 886 revision label, revision label scheme, and importing by revision. 888 file "ietf-yang-revisions@2021-06-30.yang" 889 module ietf-yang-revisions { 890 yang-version 1.1; 891 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-revisions"; 892 prefix rev; 894 // RFC Ed.: We need the bis version to get the new type revision-identifier 895 // If 6991-bis is not yet an RFC we need to copy the definition here 896 import ietf-yang-types { 897 prefix yang; 898 reference 899 "XXXX [ietf-netmod-rfc6991-bis]: Common YANG Data Types"; 900 } 901 organization 902 "IETF NETMOD (Network Modeling) Working Group"; 903 contact 904 "WG Web: 905 WG List: 907 Author: Joe Clarke 908 910 Author: Reshad Rahman 911 913 Author: Robert Wilton 914 916 Author: Balazs Lengyel 917 919 Author: Jason Sterne 920 "; 921 description 922 "This YANG 1.1 module contains definitions and extensions to 923 support updated YANG revision handling. 925 Copyright (c) 2021 IETF Trust and the persons identified as 926 authors of the code. All rights reserved. 928 Redistribution and use in source and binary forms, with or 929 without modification, is permitted pursuant to, and subject 930 to the license terms contained in, the Simplified BSD License 931 set forth in Section 4.c of the IETF Trust's Legal Provisions 932 Relating to IETF Documents 933 (http://trustee.ietf.org/license-info). 935 This version of this YANG module is part of RFC XXXX; see 936 the RFC itself for full legal notices. 938 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 939 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 940 'MAY', and 'OPTIONAL' in this document are to be interpreted as 941 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 942 they appear in all capitals, as shown here."; 944 // RFC Ed.: update the date below with the date of RFC publication 945 // and remove this note. 946 // RFC Ed.: replace XXXX (inc above) with actual RFC number and 947 // remove this note. 949 revision 2021-06-30 { 950 description 951 "Initial version."; 952 reference 953 "XXXX: Updated YANG Module Revision Handling"; 954 } 956 typedef revision-label { 957 type string { 958 length "1..255"; 959 pattern '[a-zA-Z0-9,\-_.+]+'; 960 pattern '\d{4}-\d{2}-\d{2}' { 961 modifier invert-match; 962 } 963 } 964 description 965 "A label associated with a YANG revision. 967 Alphanumeric characters, comma, hyphen, underscore, period 968 and plus are the only accepted characters. MUST NOT match 969 revision-date."; 970 reference 971 "XXXX: Updated YANG Module Revision Handling; 972 Section 3.3, Revision label"; 973 } 975 typedef revision-date-or-label { 976 type union { 977 type yang:revision-identifier; 978 type revision-label; 979 } 980 description 981 "Represents either a YANG revision date or a revision label"; 982 } 984 extension nbc-changes { 985 description 986 "This statement is used to indicate YANG module revisions that 987 contain non-backwards-compatible changes. 989 The statement MUST only be a substatement of the 'revision' 990 statement. Zero or one 'non-backwards-compatible' statements 991 per parent statement is allowed. No substatements for this 992 extension have been standardized. 994 If a revision of a YANG module contains changes, relative to 995 the preceding revision in the revision history, that do not 996 conform to the module update rules defined in RFC-XXX, then 997 the 'non-backwards-compatible' statement MUST be added as a 998 substatement to the revision statement. 1000 Conversely, if a revision does not contain a 1001 'non-backwards-compatible' statement then all changes, 1002 relative to the preceding revision in the revision history, 1003 MUST be backwards-compatible. 1005 A new module revision that only contains changes that are 1006 backwards compatible SHOULD NOT include the 1007 'non-backwards-compatible' statement. An example of when 1008 an author might add the 'non-backwards-compatible' statement 1009 is if they believe a change could negatively impact clients 1010 even though the backwards compatibility rules defined in 1011 RFC-XXXX classify it as a backwards-compatible change. 1013 Add, removing, or changing a 'non-backwards-compatible' 1014 statement is a backwards-compatible version change."; 1016 reference 1017 "XXXX: Updated YANG Module Revision Handling; 1018 Section 3.2, nbc-changes revision extension statement"; 1019 } 1021 extension revision-label { 1022 argument revision-label; 1023 description 1024 "The revision label can be used to provide an additional 1025 versioning identifier associated with a module or submodule 1026 revision. E.g., one option for a versioning scheme that 1027 could be used is [XXXX: ietf-netmod-yang-semver]. 1029 The format of the revision-label argument MUST conform to the 1030 pattern defined for the revision-label typedef. 1032 The statement MUST only be a substatement of the revision 1033 statement. Zero or one revision-label statements per parent 1034 statement are allowed. No substatements for this extension 1035 have been standardized. 1037 Revision labels MUST be unique amongst all revisions of a 1038 module or submodule. 1040 Adding a revision label is a backwards-compatible version 1041 change. Changing or removing an existing revision label in 1042 the revision history is a non-backwards-compatible version 1043 change, because it could impact any references to that 1044 revision label."; 1046 reference 1047 "XXXX: Updated YANG Module Revision Handling; 1048 Section 3.3, Revision label"; 1049 } 1051 extension revision-label-scheme { 1052 argument revision-label-scheme-identity; 1053 description 1054 "The revision label scheme specifies which revision-label scheme 1055 the module or submodule uses. 1057 The mandatory revision-label-scheme-identity argument MUST be an 1058 identity derived from revision-label-scheme-base. 1060 This extension is only valid as a top-level statement, i.e., 1061 given as as a substatement to 'module' or 'submodule'. No 1062 substatements for this extension have been standardized. 1064 This extension MUST be used if there is a revision-label 1065 statement in the module or submodule. 1067 Adding a revision label scheme is a backwards-compatible version 1068 change. Changing a revision label scheme is a 1069 non-backwards-compatible version change, unless the new revision 1070 label scheme is backwards-compatible with the replaced revision 1071 label scheme. Removing a revision label scheme is a 1072 non-backwards-compatible version change."; 1074 reference 1075 "XXXX: Updated YANG Module Revision Handling; 1076 Section 3.3.1, Revision label scheme extension statement"; 1077 } 1079 extension revision-or-derived { 1080 argument revision-date-or-label; 1081 description 1082 "Restricts the revision of the module that may be imported to 1083 one that matches or is derived from the specified 1084 revision-date or revision-label. 1086 The argument value MUST conform to the 1087 'revision-date-or-label' defined type. 1089 The statement MUST only be a substatement of the import 1090 statement. Zero, one or more 'revision-or-derived' statements 1091 per parent statement are allowed. No substatements for this 1092 extension have been standardized. 1094 If specified multiple times, then any module revision that 1095 satisfies at least one of the 'revision-or-derived' statements 1096 is an acceptable revision for import. 1098 An 'import' statement MUST NOT contain both a 1099 'revision-or-derived' extension statement and a 1100 'revision-date' statement. 1102 A particular revision of an imported module satisfies an 1103 import's 'revision-or-derived' extension statement if the 1104 imported module's revision history contains a revision 1105 statement with a matching revision date or revision label. 1107 The 'revision-or-derived' extension statement does not 1108 guarantee that all module revisions that satisfy an import 1109 statement are necessarily compatible, it only gives an 1110 indication that the revisions are more likely to be 1111 compatible. 1113 Adding, removing or updating a 'revision-or-derived' 1114 statement to an import is a backwards-compatible change. 1115 "; 1117 reference 1118 "XXXX: Updated YANG Module Revision Handling; 1119 Section 4, Import by derived revision"; 1120 } 1122 identity revision-label-scheme-base { 1123 description 1124 "Base identity from which all revision label schemes are 1125 derived."; 1127 reference 1128 "XXXX: Updated YANG Module Revision Handling; 1129 Section 3.3.1, Revision label scheme extension statement"; 1131 } 1132 } 1133 1135 YANG module with augmentations to YANG Library to revision labels 1137 file "ietf-yang-library-revisions@2021-06-30.yang" 1138 module ietf-yang-library-revisions { 1139 yang-version 1.1; 1140 namespace 1141 "urn:ietf:params:xml:ns:yang:ietf-yang-library-revisions"; 1143 prefix yl-rev; 1145 import ietf-yang-revisions { 1146 prefix rev; 1147 reference 1148 "XXXX: Updated YANG Module Revision Handling"; 1149 } 1151 import ietf-yang-library { 1152 prefix yanglib; 1153 reference "RFC 8525: YANG Libary"; 1154 } 1156 organization 1157 "IETF NETMOD (Network Modeling) Working Group"; 1158 contact 1159 "WG Web: 1160 WG List: 1162 Author: Joe Clarke 1163 1165 Author: Reshad Rahman 1166 1168 Author: Robert Wilton 1169 1171 Author: Balazs Lengyel 1172 1174 Author: Jason Sterne 1175 "; 1176 description 1177 "This module contains augmentations to YANG Library to add module 1178 level revision label and to provide an indication of how 1179 deprecated and obsolete nodes are handled by the server. 1181 Copyright (c) 2021 IETF Trust and the persons identified as 1182 authors of the code. All rights reserved. 1184 Redistribution and use in source and binary forms, with or 1185 without modification, is permitted pursuant to, and subject 1186 to the license terms contained in, the Simplified BSD License 1187 set forth in Section 4.c of the IETF Trust's Legal Provisions 1188 Relating to IETF Documents 1189 (http://trustee.ietf.org/license-info). 1190 This version of this YANG module is part of RFC XXXX; see 1191 the RFC itself for full legal notices. 1193 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1194 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1195 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1196 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1197 they appear in all capitals, as shown here."; 1199 // RFC Ed.: update the date below with the date of RFC publication 1200 // and remove this note. 1201 // RFC Ed.: replace XXXX (including in the imports above) with 1202 // actual RFC number and remove this note. 1203 // RFC Ed.: please replace revision-label version with 1.0.0 and 1204 // remove this note. 1205 revision 2021-06-30 { 1206 rev:revision-label 0.2.0; 1207 description 1208 "Initial revision"; 1209 reference 1210 "XXXX: Updated YANG Module Revision Handling"; 1211 } 1213 augment "/yanglib:yang-library/yanglib:module-set/yanglib:module" { 1214 description 1215 "Augmentation modules with a revision label"; 1216 leaf revision-label { 1217 type rev:revision-label; 1218 description 1219 "The revision label associated with this module revision. 1220 The label MUST match the rev:label value in the specific 1221 revision of the module loaded in this module-set."; 1223 reference 1224 "XXXX: Updated YANG Module Revision Handling; 1225 Section 5.2.1, Advertising revision-label"; 1226 } 1227 } 1229 augment "/yanglib:yang-library/yanglib:module-set/yanglib:module/" 1230 + "yanglib:submodule" { 1231 description 1232 "Augment submodule information with a revision label"; 1233 leaf revision-label { 1234 type rev:revision-label; 1235 description 1236 "The revision label associated with this submodule revision. 1237 The label MUST match the rev:label value in the specific 1238 revision of the submodule included by the module loaded in 1239 this module-set."; 1241 reference 1242 "XXXX: Updated YANG Module Revision Handling; 1243 Section 5.2.1, Advertising revision-label"; 1244 } 1245 } 1247 augment "/yanglib:yang-library/yanglib:module-set/" 1248 + "yanglib:import-only-module/yanglib:submodule" { 1249 description 1250 "Augment submodule information with a revision label"; 1251 leaf revision-label { 1252 type rev:revision-label; 1253 description 1254 "The revision label associated with this submodule revision. 1255 The label MUST match the rev:label value in the specific 1256 revision of the submodule included by the 1257 import-only-module loaded in this module-set."; 1259 reference 1260 "XXXX: Updated YANG Module Revision Handling; 1261 Section 5.2.1, Advertising revision-label"; 1262 } 1263 } 1265 augment "/yanglib:yang-library/yanglib:schema" { 1266 description 1267 "Augmentations to the ietf-yang-library module to indicate how 1268 deprecated and obsoleted nodes are handled for each datastore 1269 schema supported by the server."; 1271 leaf deprecated-nodes-implemented { 1272 type boolean; 1273 description 1274 "If set to true, this leaf indicates that all schema nodes with 1275 a status 'deprecated' child statement are implemented 1276 equivalently as if they had status 'current', or otherwise 1277 deviations MUST be used to explicitly remove 'deprecated' 1278 nodes from the schema. If this leaf is absent or set to false, 1279 then the behavior is unspecified."; 1281 reference 1282 "XXXX: Updated YANG Module Revision Handling; 1283 Section 5.2.2, Reporting how deprecated and obsolete nodes 1284 are handled"; 1285 } 1286 leaf obsolete-nodes-absent { 1287 type boolean; 1288 description 1289 "If set to true, this leaf indicates that the server does not 1290 implement any status 'obsolete' nodes. If this leaf is 1291 absent or set to false, then the behaviour is unspecified."; 1293 reference 1294 "XXXX: Updated YANG Module Revision Handling; 1295 Section 5.2.2, Reporting how deprecated and obsolete nodes 1296 are handled"; 1297 } 1298 } 1299 } 1300 1302 9. Contributors 1304 This document grew out of the YANG module versioning design team that 1305 started after IETF 101. The following individuals are (or have been) 1306 members of the design team and have worked on the YANG versioning 1307 project: 1309 o Balazs Lengyel 1311 o Benoit Claise 1313 o Ebben Aries 1315 o Jan Lindblad 1317 o Jason Sterne 1319 o Joe Clarke 1321 o Juergen Schoenwaelder 1323 o Mahesh Jethanandani 1325 o Michael (Wangzitao) 1327 o Qin Wu 1329 o Reshad Rahman 1331 o Rob Wilton 1333 o Bo Wu 1334 The initial revision of this document was refactored and built upon 1335 [I-D.clacla-netmod-yang-model-update]. 1337 Discussons on the use of Semver for YANG versioning has been held 1338 with authors of the OpenConfig YANG models. We would like to thank 1339 both Anees Shaikh and Rob Shakir for their input into this problem 1340 space. 1342 We would also like to thank Lou Berger, Andy Bierman, Martin 1343 Bjorklund, Italo Busi, Tom Hill, Scott Mansfield, Kent Watsen for 1344 their contributions and review comments. 1346 10. Security Considerations 1348 The document does not define any new protocol or data model. There 1349 are no security considerations beyond those specified in [RFC7950]. 1351 11. IANA Considerations 1353 11.1. YANG Module Registrations 1355 This document requests IANA to registers a URI in the "IETF XML 1356 Registry" [RFC3688]. Following the format in RFC 3688, the following 1357 registrations are requested. 1359 URI: urn:ietf:params:xml:ns:yang:ietf-yang-revisions 1360 Registrant Contact: The IESG. 1361 XML: N/A, the requested URI is an XML namespace. 1363 URI: urn:ietf:params:xml:ns:yang:ietf-yang-library-revisions 1364 Registrant Contact: The IESG. 1365 XML: N/A, the requested URI is an XML namespace. 1367 The following YANG module is requested to be registred in the "IANA 1368 Module Names" [RFC6020]. Following the format in RFC 6020, the 1369 following registrations are requested: 1371 The ietf-yang-revisions module: 1373 Name: ietf-yang-revisions 1375 XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-revisions 1377 Prefix: rev 1379 Reference: [RFCXXXX] 1381 The ietf-yang-library-revisions module: 1383 Name: ietf-yang-library-revisions 1385 XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-library- 1386 revisions 1388 Prefix: yl-rev 1390 Reference: [RFCXXXX] 1392 11.2. Guidance for versioning in IANA maintained YANG modules 1394 Note for IANA (to be removed by the RFC editor): Please check that 1395 the registries and IANA YANG modules are referenced in the 1396 appropriate way. 1398 IANA is responsible for maintaining and versioning YANG modules that 1399 are derived from other IANA registries. For example, "iana-if- 1400 type.yang" [IfTypeYang] is derived from the "Interface Types (ifType) 1401 IANA registry" [IfTypesReg], and "iana-routing-types.yang" 1402 [RoutingTypesYang] is derived from the "Address Family Numbers" 1403 [AddrFamilyReg] and "Subsequent Address Family Identifiers (SAFI) 1404 Parameters" [SAFIReg] IANA registries. 1406 Normally, updates to the registries cause any derived YANG modules to 1407 be updated in a backwards-compatible way, but there are some cases 1408 where the registry updates can cause non-backward-compatible updates 1409 to the derived YANG module. An example of such an update is the 1410 2020-12-31 revision of iana-routing-types.yang 1411 [RoutingTypesDecRevision], where the enum name for two SAFI values 1412 was changed. 1414 In all cases, IANA MUST follow the versioning guidance specified in 1415 Section 3.1, and MUST include a "rev:non-backwards-compatible" 1416 substatement to the latest revision statement whenever an IANA 1417 maintained module is updated in a non-backwards-compatible way, as 1418 described in Section 3.2. 1420 Note: For published IANA maintained YANG modules that contain non- 1421 backwards-compatible changes between revisions, a new revision should 1422 be published with the "rev:non-backwards-compatible" substatement 1423 retrospectively added to any revisions containing non-backwards- 1424 compatible changes. 1426 Non-normative examples of updates to enumeration types in IANA 1427 maintained modules that would be classified as non-backwards- 1428 compatible changes are: Changing the status of an enumeration typedef 1429 to obsolete, changing the status of an enum entry to obsolete, 1430 removing an enum entry, changing the identifier of an enum entry, or 1431 changing the described meaning of an enum entry. 1433 Non-normative examples of updates to enumeration types in IANA 1434 maintained modules that would be classified as backwards-compatible 1435 changes are: Adding a new enum entry to the end of the enumeration, 1436 changing the status or an enum entry to deprecated, or improving the 1437 description of an enumeration that does not change its defined 1438 meaning. 1440 Non-normative examples of updates to identity types in IANA 1441 maintained modules that would be classified as non-backwards- 1442 compatible changes are: Changing the status of an identity to 1443 obsolete, removing an identity, renaming an identity, or changing the 1444 described meaning of an identity. 1446 Non-normative examples of updates to identity types in IANA 1447 maintained modules that would be classified as backwards-compatible 1448 changes are: Adding a new identity, changing the status or an 1449 identity to deprecated, or improving the description of an identity 1450 that does not change its defined meaning. 1452 12. References 1454 12.1. Normative References 1456 [I-D.ietf-netmod-rfc6991-bis] 1457 Schoenwaelder, J., "Common YANG Data Types", draft-ietf- 1458 netmod-rfc6991-bis-06 (work in progress), April 2021. 1460 [I-D.ietf-netmod-yang-semver] 1461 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, 1462 B., Sterne, J., and K. D'Souza, "YANG Semantic 1463 Versioning", draft-ietf-netmod-yang-semver-02 (work in 1464 progress), February 2021. 1466 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1467 Requirement Levels", BCP 14, RFC 2119, 1468 DOI 10.17487/RFC2119, March 1997, 1469 . 1471 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1472 DOI 10.17487/RFC3688, January 2004, 1473 . 1475 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1476 the Network Configuration Protocol (NETCONF)", RFC 6020, 1477 DOI 10.17487/RFC6020, October 2010, 1478 . 1480 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 1481 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 1482 . 1484 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1485 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1486 . 1488 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1489 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1490 May 2017, . 1492 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 1493 Documents Containing YANG Data Models", BCP 216, RFC 8407, 1494 DOI 10.17487/RFC8407, October 2018, 1495 . 1497 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 1498 and R. Wilton, "YANG Library", RFC 8525, 1499 DOI 10.17487/RFC8525, March 2019, 1500 . 1502 12.2. Informative References 1504 [AddrFamilyReg] 1505 "Address Family Numbers IANA Registry", 1506 . 1509 [I-D.clacla-netmod-yang-model-update] 1510 Claise, B., Clarke, J., Lengyel, B., and K. D'Souza, "New 1511 YANG Module Update Procedure", draft-clacla-netmod-yang- 1512 model-update-06 (work in progress), July 2018. 1514 [I-D.ietf-netmod-yang-instance-file-format] 1515 Lengyel, B. and B. Claise, "YANG Instance Data File 1516 Format", draft-ietf-netmod-yang-instance-file-format-13 1517 (work in progress), March 2021. 1519 [I-D.ietf-netmod-yang-packages] 1520 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and B. Wu, 1521 "YANG Packages", draft-ietf-netmod-yang-packages-01 (work 1522 in progress), November 2020. 1524 [I-D.ietf-netmod-yang-solutions] 1525 Wilton, R., "YANG Versioning Solution Overview", draft- 1526 ietf-netmod-yang-solutions-01 (work in progress), November 1527 2020. 1529 [I-D.ietf-netmod-yang-ver-selection] 1530 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and B. Wu, 1531 "YANG Schema Selection", draft-ietf-netmod-yang-ver- 1532 selection-00 (work in progress), March 2020. 1534 [I-D.ietf-netmod-yang-versioning-reqs] 1535 Clarke, J., "YANG Module Versioning Requirements", draft- 1536 ietf-netmod-yang-versioning-reqs-04 (work in progress), 1537 January 2021. 1539 [IfTypesReg] 1540 "Interface Types (ifType) IANA Registry", 1541 . 1544 [IfTypeYang] 1545 "iana-if-type YANG Module", 1546 . 1549 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1550 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1551 . 1553 [RoutingTypesDecRevision] 1554 "2020-12-31 revision of iana-routing-types.yang", 1555 . 1558 [RoutingTypesYang] 1559 "iana-routing-types YANG Module", 1560 . 1563 [SAFIReg] "Subsequent Address Family Identifiers (SAFI) Parameters 1564 IANA Registry", . 1567 [semver] "Semantic Versioning 2.0.0", . 1569 Appendix A. Examples of changes that are NBC 1571 Examples of NBC changes include: 1573 o Deleting a data node, or changing it to status obsolete. 1575 o Changing the name, type, or units of a data node. 1577 o Modifying the description in a way that changes the semantic 1578 meaning of the data node. 1580 o Any changes that change or reduce the allowed value set of the 1581 data node, either through changes in the type definition, or the 1582 addition or changes to "must" statements, or changes in the 1583 description. 1585 o Adding or modifying "when" statements that reduce when the data 1586 node is available in the schema. 1588 o Making the statement conditional on if-feature. 1590 Appendix B. Examples of applying the NBC change guidelines 1592 The following sections give guidance for how some of these NBC 1593 changes could be made to a YANG module. The examples are all for 1594 "config true" nodes. 1596 B.1. Removing a data node 1598 Removing a leaf or container from the data tree, e.g., because 1599 support for the corresponding feature is being removed: 1601 1. The node's status is changed to "deprecated" and it is supported 1602 for at least one year. This is a BC change. 1604 2. When the node is not available anymore, its status is changed to 1605 "obsolete" and the "description" updated, this is an NBC change. 1607 If the server can support NBC revisions of the YANG module 1608 simultaneously using version selection 1609 [I-D.ietf-netmod-yang-ver-selection], then the changes can be done 1610 immediately: 1612 1. The new revision of the YANG module has the node's status changed 1613 to "obsolete" and the "description" updated, this is an NBC 1614 change. 1616 2. Clients which require the data node select the YANG package 1617 containing the schema version they use. 1619 B.2. Changing the type of a leaf node 1621 Changing the type of a leaf-node. e.g., consider a "vpn-id" node of 1622 type integer being changed to a string: 1624 1. The status of node "vpn-id" is changed to "deprecated" and the 1625 node should be available for at least one year. This is a BC 1626 change. 1628 2. A new node, e.g., "vpn-name", of type string is added to the same 1629 location as the existing node "vpn-id". This new node has status 1630 "current" and its description explains that it is replacing node 1631 "vpn-id". 1633 3. During the period of time when both nodes are available, how the 1634 server behaves when either node is set is outside the scope of 1635 this document and will vary on a case by case basis. Here are 1636 some options: 1638 1. A server may prevent the new node from being set if the old 1639 node is already set (and vice-versa). The new node may have 1640 a when statement to achieve this. The old node must not have 1641 a when statement since this would be an NBC change, but the 1642 server could reject the old node from being set if the new 1643 node is already set. 1645 2. If the new node is set and a client does a get or get-config 1646 operation on the old node, the server could map the value. 1647 For example, if the new node "vpn-name" has value "123" then 1648 the server could return integer value 123 for the old node 1649 "vpn-id". However, if the value can not be mapped then the 1650 configuration would be incomplete, this is outside the scope 1651 of this document. 1653 4. When node "vpn-id" is not available anymore, its status is 1654 changed to "obsolete" and the "description" is updated. This is 1655 an NBC change. 1657 If the server can support NBC revisions of the YANG module 1658 simultaneously using version selection 1659 [I-D.ietf-netmod-yang-ver-selection], then the changes can be done 1660 immediately: 1662 1. In the new revision of the YANG module, the status of node "vpn- 1663 id" is changed to "obsolete". This is an NBC change. 1665 2. New node "vpn-name" is added to the same location as described 1666 above. 1668 3. Clients which require the data node select the YANG package 1669 containing the schema version they use 1671 4. A server should not map between the nodes "vpn-id" and "vpn- 1672 name", i.e. if a client creates a data instance with "vpn-name" 1673 then that data instance should not be visible to a client using a 1674 module revision which has "vpn-id" (and vice-versa). 1676 B.3. Reducing the range of a leaf node 1678 Reducing the range of values of a leaf-node, e.g., consider a "vpn- 1679 id" node of type integer being changed from type uint32 to type 1680 uint16: 1682 1. If all values which are being removed were never supported, e.g., 1683 if a vpn-id of 65536 or higher was never accepted, this is a BC 1684 change for the functionality (no functionality change). Even if 1685 it is an NBC change for the YANG model, there should be no impact 1686 for clients using that YANG model. 1688 2. If one or more values being removed was previously supported, 1689 e.g., if a vpn-id of 65536 was accepted previously, this is an 1690 NBC change for the YANG model. Clients using the old YANG model 1691 will be impacted, so a change of this nature should be done 1692 carefully, e.g., by using the steps described in Appendix B.2 1694 B.4. Changing the key of a list 1696 Changing the key of a list has a big impact to the client. For 1697 example, consider a "sessions" list which has a key "interface" and 1698 there is a need to change the key to "dest-address", such a change 1699 can be done in steps: 1701 1. The status of list "sessions" is changed to "deprecated" and the 1702 list should be available for at least one year. This is a BC 1703 change. 1705 2. A new list is created in the same location with the same data but 1706 with "dest-address" as key. Finding an appropriate name for the 1707 new list can be tricky especially if the name of the existing 1708 list was perfect. In this case the new list is called "sessions- 1709 address", has status "current" and its description should explain 1710 that it is replacing list "session". 1712 3. During the period of time when both lists are available, how the 1713 server behaves when either list is set is outside the scope of 1714 this document and will vary on a case by case basis. Here are 1715 some options: 1717 1. A server could prevent the new list from being set if the old 1718 list already has entries (and vice-versa). 1720 2. If the new list is set and a client does a get or get-config 1721 operation on the old list, the server could map the entries. 1722 However, if the new list has entries which would lead to 1723 duplicate keys in the old list, the mapping can not be done. 1725 4. When list "sessions" is not available anymore, its status is 1726 changed to "obsolete" and the "description" is updated. This is 1727 an NBC change. 1729 If the server can support NBC revisions of the YANG module 1730 simultaneously using version selection 1731 [I-D.ietf-netmod-yang-ver-selection], then the changes can be done 1732 immediately: 1734 1. The new revision of the YANG module has the list "sessions" 1735 modified to have "dest-address" as key, this is an NBC change. 1737 2. Clients which require the previous functionality select the older 1738 module revision 1740 B.5. Renaming a node 1742 A leaf-node or a container may be renamed, either due to a spelling 1743 error in the previous name or because of a better name. For example 1744 a node "ip-adress" could be renamed to "ip-address": 1746 1. The status of the existing node "ip-adress" is changed to 1747 "deprecated" and the node should be available for at least one 1748 year. This is a BC change. 1750 2. The new node "ip-address" is added to the same location as the 1751 existing node "ip-adress". This new node has status "current" 1752 and its description should explain that it is replacing node "ip- 1753 adress". 1755 3. During the period of time when both nodes are available, how the 1756 server behaves when either node is set is outside the scope of 1757 this document and will vary on a case by case basis. Here are 1758 some options: 1760 1. A server could prevent the new node from being set if the old 1761 node is already set (and vice-versa). The new node could 1762 have a when statement to achieve this. The old node must not 1763 have a when statement since this would be an NBC change, but 1764 the server could reject the old node from being set if the 1765 new node is already set. 1767 2. If the new node is set and a client does a get or get-config 1768 operation on the old node, the server could use the value of 1769 the new node. For example, if the new node "ip-address" has 1770 value X then the server may return value X for the old node 1771 "ip-adress". 1773 4. When node "ip-adress" is not available anymore, its status is 1774 changed to "obsolete" and the "description" is updated. This is 1775 an NBC change. 1777 If the server can support NBC revisions of the YANG module 1778 simultaneously using version selection 1779 [I-D.ietf-netmod-yang-ver-selection], then the changes can be done 1780 immediately: 1782 1. The new revision of the YANG module has the node with the new 1783 name replacing the node with the old name, this is an NBC change. 1785 2. Clients which require the previous node name select the older 1786 module revision 1788 B.6. Changing a default value 1790 Appendix C. Changes between revisions 1792 Note to RFC Editor (To be removed by RFC Editor) 1794 v00 - v01 1796 o Removed status-description 1798 o Allowed both revision-date and revision-label in the filename. 1800 o New extension revision-label-scheme 1802 o To include submodules, inclusion by revision-date changed from 1803 MUST to SHOULD 1805 o Submodules can use revision label scheme and it can be same or 1806 different as the including module's scheme 1808 o Addressed various comments provided at WG adoption on rev-00 1810 Authors' Addresses 1811 Robert Wilton (editor) 1812 Cisco Systems, Inc. 1814 Email: rwilton@cisco.com 1816 Reshad Rahman (editor) 1818 Email: reshad@yahoo.com 1820 Balazs Lengyel (editor) 1821 Ericsson 1823 Email: balazs.lengyel@ericsson.com 1825 Joe Clarke 1826 Cisco Systems, Inc. 1828 Email: jclarke@cisco.com 1830 Jason Sterne 1831 Nokia 1833 Email: jason.sterne@nokia.com