idnits 2.17.1 draft-ietf-netmod-yang-module-versioning-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 14 instances of too long lines in the document, the longest one being 8 characters in excess of 72. -- The abstract seems to indicate that this document updates RFC6020, but the header doesn't have an 'Updates:' line to match this. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (25 October 2021) is 908 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 1472, but not defined == Unused Reference: 'I-D.ietf-netmod-rfc6991-bis' is defined on line 1538, but no explicit reference was found in the text == Outdated reference: A later version (-15) exists of draft-ietf-netmod-rfc6991-bis-07 == Outdated reference: A later version (-15) exists of draft-ietf-netmod-yang-semver-03 == 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-05 Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 2 comments (--). 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: 28 April 2022 B. Lengyel, Ed. 7 Ericsson 8 J. Clarke 9 Cisco Systems, Inc. 10 J. Sterne 11 Nokia 12 25 October 2021 14 Updated YANG Module Revision Handling 15 draft-ietf-netmod-yang-module-versioning-04 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 guidelines for managing the lifecycle of 24 YANG modules and individual schema nodes. It provides a mechanism, 25 via the revision-label YANG extension, to specify a revision 26 identifier for YANG modules and submodules. This document updates 27 RFC 7950, RFC 6020, 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 28 April 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 (https://trustee.ietf.org/ 53 license-info) in effect on the date of publication of this document. 54 Please review these documents carefully, as they describe your rights 55 and restrictions with respect to this document. Code Components 56 extracted from this document must include Simplified BSD License text 57 as described in Section 4.e of the Trust Legal Provisions and are 58 provided without warranty as described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 1.1. Updates to YANG RFCs . . . . . . . . . . . . . . . . . . 4 64 2. Terminology and Conventions . . . . . . . . . . . . . . . . . 4 65 3. Refinements to YANG revision handling . . . . . . . . . . . . 5 66 3.1. Updating a YANG module with a new revision . . . . . . . 6 67 3.1.1. Backwards-compatible rules . . . . . . . . . . . . . 6 68 3.1.2. Non-backwards-compatible changes . . . . . . . . . . 7 69 3.2. non-backwards-compatible revision extension statement . . 7 70 3.3. Removing revisions from the revision history . . . . . . 7 71 3.4. Revision label . . . . . . . . . . . . . . . . . . . . . 9 72 3.4.1. File names . . . . . . . . . . . . . . . . . . . . . 10 73 3.4.2. Revision label scheme extension statement . . . . . . 10 74 3.5. Examples for updating the YANG module revision history . 11 75 4. Import by derived revision . . . . . . . . . . . . . . . . . 13 76 4.1. Module import examples . . . . . . . . . . . . . . . . . 15 77 5. Updates to ietf-yang-library . . . . . . . . . . . . . . . . 16 78 5.1. Resolving ambiguous module imports . . . . . . . . . . . 16 79 5.2. YANG library versioning augmentations . . . . . . . . . . 17 80 5.2.1. Advertising revision-label . . . . . . . . . . . . . 17 81 5.2.2. Reporting how deprecated and obsolete nodes are 82 handled . . . . . . . . . . . . . . . . . . . . . . . 17 83 6. Versioning of YANG instance data . . . . . . . . . . . . . . 18 84 7. Guidelines for using the YANG module update rules . . . . . . 18 85 7.1. Guidelines for YANG module authors . . . . . . . . . . . 19 86 7.1.1. Making non-backwards-compatible changes to a YANG 87 module . . . . . . . . . . . . . . . . . . . . . . . 20 88 7.2. Versioning Considerations for Clients . . . . . . . . . . 21 89 8. Module Versioning Extension YANG Modules . . . . . . . . . . 22 90 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 31 91 10. Security Considerations . . . . . . . . . . . . . . . . . . . 32 92 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 93 11.1. YANG Module Registrations . . . . . . . . . . . . . . . 32 94 11.2. Guidance for versioning in IANA maintained YANG 95 modules . . . . . . . . . . . . . . . . . . . . . . . . 33 96 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 34 97 12.1. Normative References . . . . . . . . . . . . . . . . . . 34 98 12.2. Informative References . . . . . . . . . . . . . . . . . 35 99 Appendix A. Examples of changes that are NBC . . . . . . . . . . 37 100 Appendix B. Examples of applying the NBC change guidelines . . . 37 101 B.1. Removing a data node . . . . . . . . . . . . . . . . . . 38 102 B.2. Changing the type of a leaf node . . . . . . . . . . . . 38 103 B.3. Reducing the range of a leaf node . . . . . . . . . . . . 39 104 B.4. Changing the key of a list . . . . . . . . . . . . . . . 39 105 B.5. Renaming a node . . . . . . . . . . . . . . . . . . . . . 40 106 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 41 108 1. Introduction 110 This document defines the foundational pieces of a solution to the 111 YANG module lifecycle problems described in 112 [I-D.ietf-netmod-yang-versioning-reqs]. Complementary documents 113 provide other parts of the solution, with the overall relationship of 114 the solution drafts described in [I-D.ietf-netmod-yang-solutions]. 116 Specifically, this document recognises a need (within standards 117 organizations, vendors, and the industry) to sometimes allow YANG 118 modules to evolve with non-backwards-compatible changes, which could 119 cause breakage to clients and importing YANG modules. Accepting that 120 non-backwards-compatible changes do sometimes occur, it is important 121 to have mechanisms to report where these changes occur, and to manage 122 their effect on clients and the broader YANG ecosystem. 124 The document comprises five parts: 126 * Refinements to the YANG 1.1 module revision update procedure, 127 supported by new extension statements to indicate when a revision 128 contains non-backwards-compatible changes, and an optional 129 revision label. 131 * A YANG extension statement allowing YANG module imports to specify 132 an earliest module revision that may satisfy the import 133 dependency. 135 * Updates and augmentations to ietf-yang-library to include the 136 revision label in the module and submodule descriptions, to report 137 how "deprecated" and "obsolete" nodes are handled by a server, and 138 to clarify how module imports are resolved when multiple revisions 139 could otherwise be chosen. 141 * Considerations of how versioning applies to YANG instance data. 143 * Guidelines for how the YANG module update rules defined in this 144 document should be used, along with examples. 146 Note to RFC Editor (To be removed by RFC Editor) 148 Open issues are tracked at https://github.com/netmod-wg/yang-ver-dt/ 149 issues. 151 1.1. Updates to YANG RFCs 153 This document updates [RFC7950] section 11 and [RFC6020] section 10. 154 Section 3 describes modifications to YANG revision handling and 155 update rules, and Section 4 describes a YANG extension statement to 156 do import by derived revision. 158 This document updates [RFC7950] section 5.2 and [RFC6020] section 159 5.2. Section 3.4.1 describes the use of a revision label in the name 160 of a file containing a YANG module or submodule. 162 This document updates [RFC7950] section 5.6.5 and [RFC8525]. 163 Section 5.1 defines how a client of a YANG library datastore schema 164 resolves ambiguous imports for modules which are not "import-only". 166 This document updates [RFC8407] section 4.7. Section 7 provides 167 guidelines on managing the lifecycle of YANG modules that may contain 168 non-backwards-compatible changes and a branched revision history. 170 This document updates [RFC8525] with augmentations to include 171 revision labels in the YANG library data and two boolean leafs to 172 indicate whether status deprecated and status obsolete schema nodes 173 are implemented by the server. 175 2. Terminology and Conventions 177 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 178 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 179 "OPTIONAL" in this document are to be interpreted as described in BCP 180 14 [RFC2119] [RFC8174] when, and only when, they appear in all 181 capitals, as shown here. 183 In addition, this document uses the following terminology: 185 * YANG module revision: An instance of a YANG module, uniquely 186 identified with a revision date, with no implied ordering or 187 backwards compatibility between different revisions of the same 188 module. 190 * Backwards-compatible (BC) change: A backwards-compatible change 191 between two YANG module revisions, as defined in Section 3.1.1 193 * Non-backwards-compatible (NBC) change: A non-backwards-compatible 194 change between two YANG module revisions, as defined in 195 Section 3.1.2 197 3. Refinements to YANG revision handling 199 [RFC7950] and [RFC6020] assume, but do not explicitly state, that the 200 revision history for a YANG module or submodule is strictly linear, 201 i.e., it is prohibited to have two independent revisions of a YANG 202 module or submodule that are both directly derived from the same 203 parent revision. 205 This document clarifies [RFC7950] and [RFC6020] to explicitly allow 206 non-linear development of YANG module and submodule revisions, so 207 that they MAY have multiple revisions that directly derive from the 208 same parent revision. As per [RFC7950] and [RFC6020], YANG module 209 and submodule revisions continue to be uniquely identified by their 210 revision date, and hence all revisions of a given module or submodule 211 MUST have unique revision dates. 213 A corollary to the above is that the relationship between two module 214 or submodule revisions cannot be determined by comparing the module 215 or submodule revision date alone, and the revision history, or 216 revision label, must also be taken into consideration. 218 A module's name and revision date identifies a specific immutable 219 definition of that module within its revision history. Hence, if a 220 module includes submodules then to ensure that the module's content 221 is uniquely defined, the module's "include" statements SHOULD use 222 "revision-date" substatements to specify the exact revision date of 223 each included submodule. When a module does not include its 224 submodules by revision-date, the revision of submodules used cannot 225 be derived from the including module. Mechanisms such as YANG 226 packages [I-D.ietf-netmod-yang-packages], and YANG library [RFC8525], 227 MAY be used to specify the exact submodule revisions used when the 228 submodule revision date is not constrained by the "include" 229 statement. 231 [RFC7950] section 11 and [RFC6020] section 10 require that all 232 updates to a YANG module are BC to the previous revision of the 233 module. This document introduces a method to indicate that an NBC 234 change has occurred between module revisions: this is done by using a 235 new "non-backwards-compatible" YANG extension statement in the module 236 revision history. 238 Two revisions of a module or submodule MAY have identical content 239 except for the revision history. This could occur, for example, if a 240 module or submodule has a branched history and identical changes are 241 applied in multiple branches. 243 3.1. Updating a YANG module with a new revision 245 This section updates [RFC7950] section 11 and [RFC6020] section 10 to 246 refine the rules for permissible changes when a new YANG module 247 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] and [RFC6020], all published revisions of a module 259 are given a new unique revision date. This applies even for module 260 revisions containing (in the module or included submodules) only 261 changes to any whitespace, formatting, comments or line endings 262 (e.g., DOS vs UNIX). 264 3.1.1. Backwards-compatible rules 266 A change between two module revisions is defined as being "backwards- 267 compatible" if the change conforms to the module update rules 268 specified in [RFC7950] section 11 and [RFC6020] section 10, updated 269 by the following rules: 271 * A "status" "deprecated" statement MAY be added, or changed from 272 "current" to "deprecated", but adding or changing "status" to 273 "obsolete" is not a backwards-compatible change. 275 * YANG schema nodes with a "status" "obsolete" substatement MAY be 276 removed from published modules, and are classified as backwards- 277 compatible changes. In some circumstances it may be helpful to 278 retain the obsolete definitions since their identifiers may still 279 be referenced by other modules and to ensure that their 280 identifiers are not reused with a different meaning. 282 * In statements that have any data definition statements as 283 substatements, those data definition substatements MAY be 284 reordered, as long as they do not change the ordering of any 285 "input" or "output" data definition substatements of "rpc" or 286 "action" statements. If new data definition statements are added, 287 they can be added anywhere in the sequence of existing 288 substatements. 290 * A statement that is defined using the YANG "extension" statement 291 MAY be added, removed, or changed, if it does not change the 292 semantics of the module. Extension statement definitions SHOULD 293 specify whether adding, removing, or changing statements defined 294 by that extension are backwards-compatible or non-backwards- 295 compatible. 297 * Any changes (including whitespace or formatting changes) that do 298 not change the semantic meaning of the module are backwards 299 compatible. 301 3.1.2. Non-backwards-compatible changes 303 Any changes to YANG modules that are not defined by Section 3.1.1 as 304 being backwards-compatible are classified as "non-backwards- 305 compatible" changes. 307 3.2. non-backwards-compatible revision extension statement 309 The "rev:non-backwards-compatible" extension statement is used to 310 indicate YANG module revisions that contain NBC changes. 312 If a revision of a YANG module contains changes, relative to the 313 preceding revision in the revision history, that do not conform to 314 the module update rules defined in Section 3.1.1, then a "rev:non- 315 backwards-compatible" extension statement MUST be added as a 316 substatement to the "revision" statement. 318 3.3. Removing revisions from the revision history 320 Authors may wish to remove revision statements from a module or 321 submodule. Removal of revision information may be desirable for a 322 number of reasons including reducing the size of a large revision 323 history, or removing a revision that should no longer be used or 324 imported. Removing revision statements is allowed, but can cause 325 issues and SHOULD NOT be done without careful analysis of the 326 potential impact to users of the module or submodule. Doing so can 327 lead to import breakages when import by revision-or-derived is used. 328 Moreover, truncating history may cause loss of visibility of when 329 non-backwards-compatible changes were introduced. 331 An author MAY remove a contiguous sequence of entries from the end 332 (i.e., oldest entries) of the revision history. This is acceptable 333 even if the first remaining (oldest) revision entry in the revision 334 history contains a rev:non-backwards-compatible substatement. 336 An author MAY remove a contiguous sequence of entries in the revision 337 history as long as the presence or absence of any existing rev:non- 338 backwards-compatible substatements on all remaining entries still 339 accurately reflect the compatibility relationship to their preceding 340 entries remaining in the revision history. 342 The author MUST NOT remove the first (i.e., newest) revision entry in 343 the revision history. 345 Example revision history: 347 revision 2020-11-11 { 348 rev:revision-label 4.0.0; 349 rev:non-backwards-compatible; 350 } 352 revision 2020-08-09 { 353 rev:revision-label 3.0.0; 354 rev:non-backwards-compatible; 355 } 357 revision 2020-06-07 { 358 rev:revision-label 2.1.0; 359 } 361 revision 2020-02-10 { 362 rev:revision-label 2.0.0; 363 rev:non-backwards-compatible; 364 } 366 revision 2019-10-21 { 367 rev:revision-label 1.1.3; 368 } 370 revision 2019-03-04 { 371 rev:revision-label 1.1.2; 372 } 374 revision 2019-01-02 { 375 rev:revision-label 1.1.1; 376 } 377 In the revision history example above, removing the revision history 378 entry for 2020-02-10 would also remove the rev:non-backwards- 379 compatible annotation and hence the resulting revision history would 380 incorrectly indicate that revision 2020-06-07 is backwards-compatible 381 with revisions 2019-01-02 through 2019-10-21 when it is not, and so 382 this change cannot be made. Conversely, removing one or more 383 revisions out of 2019-03-04, 2019-10-21 and 2020-08-09 from the 384 revision history would still retain a consistent revision history, 385 and is acceptable, subject to an awareness of the concerns raised in 386 the first paragraph of this section. 388 3.4. Revision label 390 Each revision entry in a module or submodule MAY have a revision 391 label associated with it, providing an alternative alias to identify 392 a particular revision of a module or submodule. The revision label 393 could be used to provide an additional versioning identifier 394 associated with the revision. 396 A revision label scheme is a set of rules describing how a particular 397 type of revision-label operates for versioning YANG modules and 398 submodules. For example, YANG Semver [I-D.ietf-netmod-yang-semver] 399 defines a revision label scheme based on Semver 2.0.0 [semver]. 400 Other documents may define other YANG revision label schemes. 402 Submodules MAY use a revision label scheme. When they use a revision 403 label scheme, submodules MAY use a revision label scheme that is 404 different from the one used in the including module. 406 The revision label space of submodules is separate from the revision 407 label space of the including module. A change in one submodule MUST 408 result in a new revision label of that submodule and the including 409 module, but the actual values of the revision labels in the module 410 and submodule could be completely different. A change in one 411 submodule does not result in a new revision label in another 412 submodule. A change in a module revision label does not necessarily 413 mean a change to the revision label in all included submodules. 415 If a revision has an associated revision label, then it may be used 416 instead of the revision date in a "rev:revision-or-derived" extension 417 statement argument. 419 A specific revision-label identifies a specific revision of the 420 module. If two YANG modules contain the same module name and the 421 same revision-label (and hence also the same revision-date) in their 422 latest revision statement, then the file contents of the two modules, 423 including the revision history, MUST be identical. 425 3.4.1. File names 427 This section updates [RFC7950] section 5.2 and [RFC6020] section 5.2. 429 If a revision has an associated revision label, then the revision- 430 label MAY be used instead of the revision date in the filename of a 431 YANG file, where it takes the form: 433 module-or-submodule-name [['@' revision-date]|['#' revision-label]] 434 ( '.yang' / '.yin' ) 436 E.g., acme-router-module@2018-01-25.yang 437 E.g., acme-router-module#2.0.3.yang 439 YANG module (or submodule) files MAY be identified using either 440 revision-date or revision-label. Typically, only one file name 441 SHOULD exist for the same module (or submodule) revision. Two file 442 names, one with the revision date and another with the revision 443 label, MAY exist for the same module (or submodule) revision, e.g., 444 when migrating from one scheme to the other. 446 3.4.2. Revision label scheme extension statement 448 The optional "rev:revision-label-scheme" extension statement is used 449 to indicate which revision-label scheme a module or submodule uses. 450 There MUST NOT be more than one revision label scheme in a module or 451 submodule. The mandatory argument to this extension statement: 453 * specifies the revision-label scheme used by the module or 454 submodule 456 * is defined in the document which specifies the revision-label 457 scheme 459 * MUST be an identity derived from "revision-label-scheme-base". 461 The revision-label scheme used by a module or submodule SHOULD NOT 462 change during the lifetime of the module or submodule. If the 463 revision-label scheme used by a module or submodule is changed to a 464 new scheme, then all revision-label statements that do not conform to 465 the new scheme MUST be replaced or removed. 467 3.5. Examples for updating the YANG module revision history 469 The following diagram, explanation, and module history illustrates 470 how the branched revision history, "non-backwards-compatible" 471 extension statement, and "revision-label" extension statement could 472 be used: 474 Example YANG module with branched revision history. 476 Module revision date Revision label 477 2019-01-01 <- 1.0.0 478 | 479 2019-02-01 <- 2.0.0 480 | \ 481 2019-03-01 \ <- 3.0.0 482 | \ 483 | 2019-04-01 <- 2.1.0 484 | | 485 | 2019-05-01 <- 2.2.0 486 | 487 2019-06-01 <- 3.1.0 489 The tree diagram above illustrates how an example module's revision 490 history might evolve, over time. For example, the tree might 491 represent the following changes, listed in chronological order from 492 the oldest revision to the newest revision: 494 Example module, revision 2019-06-01: 496 module example-module { 498 namespace "urn:example:module"; 499 prefix "prefix-name"; 500 rev:revision-label-scheme "yangver:yang-semver"; 502 import ietf-yang-revisions { prefix "rev"; } 503 import ietf-yang-semver { prefix "yangver"; } 505 description 506 "to be completed"; 508 revision 2019-06-01 { 509 rev:revision-label 3.1.0; 510 description "Add new functionality."; 511 } 513 revision 2019-03-01 { 514 rev:revision-label 3.0.0; 515 rev:non-backwards-compatible; 516 description 517 "Add new functionality. Remove some deprecated nodes."; 518 } 520 revision 2019-02-01 { 521 rev:revision-label 2.0.0; 522 rev:non-backwards-compatible; 523 description "Apply bugfix to pattern statement"; 524 } 526 revision 2019-01-01 { 527 rev:revision-label 1.0.0; 528 description "Initial revision"; 529 } 531 //YANG module definition starts here 532 } 534 Example module, revision 2019-05-01: 536 module example-module { 538 namespace "urn:example:module"; 539 prefix "prefix-name"; 540 rev:revision-label-scheme "yangver:yang-semver"; 542 import ietf-yang-revisions { prefix "rev"; } 543 import ietf-yang-semver { prefix "yangver"; } 545 description 546 "to be completed"; 548 revision 2019-05-01 { 549 rev:revision-label 2.2.0; 550 description "Backwards-compatible bugfix to enhancement."; 551 } 553 revision 2019-04-01 { 554 rev:revision-label 2.1.0; 555 description "Apply enhancement to older release train."; 556 } 558 revision 2019-02-01 { 559 rev:revision-label 2.0.0; 560 rev:non-backwards-compatible; 561 description "Apply bugfix to pattern statement"; 562 } 564 revision 2019-01-01 { 565 rev:revision-label 1.0.0; 566 description "Initial revision"; 567 } 569 //YANG module definition starts here 570 } 572 4. Import by derived revision 574 [RFC7950] and [RFC6020] allow YANG module "import" statements to 575 optionally require the imported module to have a particular revision 576 date. In practice, importing a module with an exact revision date is 577 often too restrictive because it requires the importing module to be 578 updated whenever any change to the imported module occurs. The 579 alternative choice of using an import statement without any revision 580 date statement is also not ideal because the importing module may not 581 work with all possible revisions of the imported module. 583 Instead, it is desirable for an importing module to specify a 584 "minimum required revision" of a module that it is compatible with, 585 based on the assumption that later revisions derived from that 586 "minimum required revision" are also likely to be compatible. Many 587 possible changes to a YANG module do not break importing modules, 588 even if the changes themselves are not strictly backwards-compatible. 589 E.g., fixing an incorrect pattern statement or description for a leaf 590 would not break an import, changing the name of a leaf could break an 591 import but frequently would not, but removing a container would break 592 imports if that container is augmented by another module. 594 The ietf-revisions module defines the "revision-or-derived" extension 595 statement, a substatement to the YANG "import" statement, to allow 596 for a "minimum required revision" to be specified during import: 598 The argument to the "revision-or-derived" extension statement is a 599 revision date or a revision label. 601 A particular revision of an imported module satisfies an import's 602 "revision-or-derived" extension statement if the imported module's 603 revision history contains a revision statement with a matching 604 revision date or revision label. 606 An "import" statement MUST NOT contain both a "revision-or- 607 derived" extension statement and a "revision-date" statement. 609 The "revision-or-derived" extension statement MAY be specified 610 multiple times, allowing the import to use any module revision 611 that satisfies at least one of the "revision-or-derived" extension 612 statements. 614 The "revision-or-derived" extension statement does not guarantee 615 that all module revisions that satisfy an import statement are 616 necessarily compatible; it only gives an indication that the 617 revisions are more likely to be compatible. Hence, NBC changes to 618 an imported module may also require new revisions of any importing 619 modules, updated to accommodation those changes, along with 620 updated import "revision-or-derived" extension statements to 621 depend on the updated imported module revision. 623 Adding, modifying or removing a "revision-or-derived" extension 624 statement is considered to be a BC change. 626 4.1. Module import examples 628 Consider the example module "example-module" from Section 3.5 that is 629 hypothetically available in the following revision/label pairings: 630 2019-01-01/1.0.0, 2019-02-01/2.0.0, 2019-03-01/3.0.0, 631 2019-04-01/2.1.0, 2019-05-01/2.2.0 and 2019-06-01/3.1.0. The 632 relationship between the revisions is as before: 634 Module revision date Revision label 635 2019-01-01 <- 1.0.0 636 | 637 2019-02-01 <- 2.0.0 638 | \ 639 2019-03-01 \ <- 3.0.0 640 | \ 641 | 2019-04-01 <- 2.1.0 642 | | 643 | 2019-05-01 <- 2.2.0 644 | 645 2019-06-01 <- 3.1.0 647 4.1.1. Example 1 649 This example selects module revisions that match, or are derived from 650 the revision 2019-02-01. E.g., this dependency might be used if 651 there was a new container added in revision 2019-02-01 that is 652 augmented by the importing module. It includes revisions/labels: 653 2019-02-01/2.0.0, 2019-03-01/3.0.0, 2019-04-01/2.1.0, 654 2019-05-01/2.2.0 and 2019-06-01/3.1.0. 656 import example-module { 657 rev:revision-or-derived 2019-02-01; 658 } 660 Alternatively, the first example could have used the revision label 661 "2.0.0" instead, which selects the same set of revisions/labels. 663 import example-module { 664 rev:revision-or-derived 2.0.0; 665 } 667 4.1.2. Example 2 669 This example selects module revisions that are derived from 670 2019-04-01 by using the revision label 2.1.0. It includes revisions/ 671 labels: 2019-04-01/2.1.0 and 2019-05-01/2.2.0. Even though 672 2019-06-01/3.1.0 has a higher revision label number than 673 2019-04-01/2.1.0 it is not a derived revision, and hence it is not a 674 valid revision for import. 676 import example-module { 677 rev:revision-or-derived 2.1.0; 678 } 680 4.1.3. Example 3 682 This example selects revisions derived from either 2019-04-01 or 683 2019-06-01. It includes revisions/labels: 2019-04-01/2.1.0, 684 2019-05-01/2.2.0, and 2019-06-01/3.1.0. 686 import example-module { 687 rev:revision-or-derived 2019-04-01; 688 rev:revision-or-derived 2019-06-01; 689 } 691 5. Updates to ietf-yang-library 693 This document updates YANG 1.1 [RFC7950] and YANG library [RFC8525] 694 to clarify how ambiguous module imports are resolved. It also 695 defines the YANG module, ietf-yang-library-revisions, that augments 696 YANG library [RFC8525] with revision labels and two leafs to indicate 697 how a server implements deprecated and obsolete schema nodes. 699 5.1. Resolving ambiguous module imports 701 A YANG datastore schema, defined in [RFC8525], can specify multiple 702 revisions of a YANG module in the schema using the "import-only" 703 list, with the requirement from [RFC7950] section 5.6.5 that only a 704 single revision of a YANG module may be implemented. 706 If a YANG module import statement does not specify a specific 707 revision within the datastore schema then it could be ambiguous as to 708 which module revision the import statement should resolve to. Hence, 709 a datastore schema constructed by a client using the information 710 contained in YANG library may not exactly match the datastore schema 711 actually used by the server. 713 The following two rules remove the ambiguity: 715 If a module import statement could resolve to more than one module 716 revision defined in the datastore schema, and one of those revisions 717 is implemented (i.e., not an "import-only" module), then the import 718 statement MUST resolve to the revision of the module that is defined 719 as being implemented by the datastore schema. 721 If a module import statement could resolve to more than one module 722 revision defined in the datastore schema, and none of those revisions 723 are implemented, then the import MUST resolve to the module revision 724 with the latest revision date. 726 5.2. YANG library versioning augmentations 728 The "ietf-yang-library-revisions" YANG module has the following 729 structure (using the notation defined in [RFC8340]): 731 module: ietf-yang-library-revisions 732 augment /yanglib:yang-library/yanglib:module-set/yanglib:module: 733 +--ro revision-label? rev:revision-label 734 augment /yanglib:yang-library/yanglib:module-set/yanglib:module 735 /yanglib:submodule: 736 +--ro revision-label? rev:revision-label 737 augment /yanglib:yang-library/yanglib:module-set 738 /yanglib:import-only-module/yanglib:submodule: 739 +--ro revision-label? rev:revision-label 740 augment /yanglib:yang-library/yanglib:schema: 741 +--ro deprecated-nodes-implemented? boolean 742 +--ro obsolete-nodes-absent? boolean 744 5.2.1. Advertising revision-label 746 The ietf-yang-library-revisions YANG module augments the "module" and 747 "submodule" lists in ietf-yang-library with "revision-label" leafs to 748 optionally declare the revision label associated with each module and 749 submodule. 751 5.2.2. Reporting how deprecated and obsolete nodes are handled 753 The ietf-yang-library-revisions YANG module augments YANG library 754 with two boolean leafs to allow a server to report how it implements 755 status "deprecated" and status "obsolete" schema nodes. The leafs 756 are: 758 deprecated-nodes-implemented: If set to "true", this leaf indicates 759 that all schema nodes with a status "deprecated" are implemented 760 equivalently as if they had status "current"; otherwise deviations 761 MUST be used to explicitly remove "deprecated" nodes from the 762 schema. If this leaf is set to "false" or absent, then the 763 behavior is unspecified. 765 obsolete-nodes-absent: If set to "true", this leaf indicates that 766 the server does not implement any status "obsolete" schema nodes. 767 If this leaf is set to "false" or absent, then the behaviour is 768 unspecified. 770 Servers SHOULD set both the "deprecated-nodes-implemented" and 771 "obsolete-nodes-absent" leafs to "true". 773 If a server does not set the "deprecated-nodes-implemented" leaf to 774 "true", then clients MUST NOT rely solely on the "rev:non-backwards- 775 compatible" statements to determine whether two module revisions are 776 backwards-compatible, and MUST also consider whether the status of 777 any nodes has changed to "deprecated" and whether those nodes are 778 implemented by the server. 780 6. Versioning of YANG instance data 782 Instance data sets [I-D.ietf-netmod-yang-instance-file-format] do not 783 directly make use of the updated revision handling rules described in 784 this document, as compatibility for instance data is undefined. 786 However, instance data specifies the content-schema of the data-set. 787 This schema SHOULD make use of versioning using revision dates and/or 788 revision labels for the individual YANG modules that comprise the 789 schema or potentially for the entire schema itself (e.g., 790 [I-D.ietf-netmod-yang-packages]). 792 In this way, the versioning of a content-schema associated with an 793 instance data set may help a client to determine whether the instance 794 data could also be used in conjunction with other revisions of the 795 YANG schema, or other revisions of the modules that define the 796 schema. 798 7. Guidelines for using the YANG module update rules 800 The following text updates section 4.7 of [RFC8407] to revise the 801 guidelines for updating YANG modules. 803 7.1. Guidelines for YANG module authors 805 All IETF YANG modules MUST include revision-label statements for all 806 newly published YANG modules, and all newly published revisions of 807 existing YANG modules. The revision-label MUST take the form of a 808 YANG semantic version number [I-D.ietf-netmod-yang-semver]. 810 NBC changes to YANG modules may cause problems to clients, who are 811 consumers of YANG models, and hence YANG module authors SHOULD 812 minimize NBC changes and keep changes BC whenever possible. 814 When NBC changes are introduced, consideration should be given to the 815 impact on clients and YANG module authors SHOULD try to mitigate that 816 impact. 818 A "rev:non-backwards-compatible" statement MUST be added if there are 819 NBC changes relative to the previous revision. 821 Removing old revision statements from a module's revision history 822 could break import by revision, and hence it is RECOMMENDED to retain 823 them. If all dependencies have been updated to not import specific 824 revisions of a module, then the corresponding revision statements can 825 be removed from that module. An alternative solution, if the 826 revision section is too long, would be to remove, or curtail, the 827 older description statements associated with the previous revisions. 829 The "rev:revision-or-derived" extension SHOULD be used in YANG module 830 imports to indicate revision dependencies between modules in 831 preference to the "revision-date" statement, which causes overly 832 strict import dependencies and SHOULD NOT be used. 834 A module that includes submodules SHOULD use the "revision-date" 835 statement to include specific submodule revisions. The revision of 836 the including module MUST be updated when any included submodule has 837 changed. 839 In some cases a module or submodule revision that is not strictly NBC 840 by the definition in Section 3.1.2 of this specification may include 841 the "non-backwards-compatible" statement. Here is an example when 842 adding the statement may be desirable: 844 * A "config false" leaf had its value space expanded (for example, a 845 range was increased, or additional enum values were added) and the 846 author or server implementor feels there is a significant 847 compatibility impact for clients and users of the module or 848 submodule 850 7.1.1. Making non-backwards-compatible changes to a YANG module 852 There are various valid situations where a YANG module has to be 853 modified in an NBC way. Here are the different ways in which this 854 can be done: 856 * NBC changes can be sometimes be done incrementally using the 857 "deprecated" status to provide clients time to adapt to NBC 858 changes. 860 * NBC changes are done at once, i.e. without using "status" 861 statements. Depending on the change, this may have a big impact 862 on clients. 864 * If the server can support multiple revisions of the YANG module or 865 of YANG packages (as specified in 866 [I-D.ietf-netmod-yang-packages]), and allows the client to select 867 the revision (as per [I-D.ietf-netmod-yang-ver-selection]), then 868 NBC changes MAY be done without using "status" statements. 869 Clients would be required to select the revision which they 870 support and the NBC change would have no impact on them. 872 Here are some guidelines on how non-backwards-compatible changes can 873 be made incrementally, with the assumption that deprecated nodes are 874 implemented by the server, and obsolete nodes are not: 876 1. The changes should be made gradually, e.g., a data node's status 877 SHOULD NOT be changed directly from "current" to "obsolete" (see 878 Section 4.7 of [RFC8407]), instead the status SHOULD first be 879 marked "deprecated". At some point in the future, when support 880 is removed for the data node, there are two options. The first, 881 and preferred, option is to keep the data node definition in the 882 model and change the status to "obsolete". The second option is 883 to simply remove the data node from the model, but this has the 884 risk of breaking modules which import the modified module, and 885 the removed identifier may be accidently reused in a future 886 revision. 888 2. For deprecated data nodes the "description" statement SHOULD also 889 indicate until when support for the node is guaranteed (if 890 known). If there is a replacement data node, rpc, action or 891 notification for the deprecated node, this SHOULD be stated in 892 the "description". The reason for deprecating the node can also 893 be included in the "description" if it is deemed to be of 894 potential interest to the user. 896 3. For obsolete data nodes, it is RECOMMENDED to keep the above 897 information, from when the node had status "deprecated", which is 898 still relevant. 900 4. When obsoleting or deprecating data nodes, the "deprecated" or 901 "obsolete" status SHOULD be applied at the highest possible level 902 in the data tree. For clarity, the "status" statement SHOULD 903 also be applied to all descendent data nodes, but the additional 904 status related information does not need to be repeated if it 905 does not introduce any additional information. 907 5. NBC changes which can break imports SHOULD be avoided because of 908 the impact on the importing module. The importing modules could 909 get broken, e.g., if an augmented node in the importing module 910 has been removed from the imported module. Alternatively, the 911 schema of the importing modules could undergo an NBC change due 912 to the NBC change in the imported module, e.g., if a node in a 913 grouping has been removed. As described in Appendix B.1, instead 914 of removing a node, that node SHOULD first be deprecated and then 915 obsoleted. 917 See Appendix B for examples on how NBC changes can be made. 919 7.2. Versioning Considerations for Clients 921 Guidelines for clients of modules using the new module revision 922 update procedure: 924 * Clients SHOULD be liberal when processing data received from a 925 server. For example, the server may have increased the range of 926 an operational node causing the client to receive a value which is 927 outside the range of the YANG model revision it was coded against. 929 * Clients SHOULD monitor changes to published YANG modules through 930 their revision history, and use appropriate tooling to understand 931 the specific changes between module revision. In particular, 932 clients SHOULD NOT migrate to NBC revisions of a module without 933 understanding any potential impact of the specific NBC changes. 935 * Clients SHOULD plan to make changes to match published status 936 changes. When a node's status changes from "current" to 937 "deprecated", clients SHOULD plan to stop using that node in a 938 timely fashion. When a node's status changes to "obsolete", 939 clients MUST stop using that node. 941 8. Module Versioning Extension YANG Modules 943 YANG module with extension statements for annotating NBC changes, 944 revision label, revision label scheme, and importing by revision. 946 file "ietf-yang-revisions@2021-06-30.yang" 947 module ietf-yang-revisions { 948 yang-version 1.1; 949 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-revisions"; 950 prefix rev; 952 // RFC Ed.: We need the bis version to get the new type revision-identifier 953 // If 6991-bis is not yet an RFC we need to copy the definition here 954 import ietf-yang-types { 955 prefix yang; 956 reference 957 "XXXX [ietf-netmod-rfc6991-bis]: Common YANG Data Types"; 958 } 960 organization 961 "IETF NETMOD (Network Modeling) Working Group"; 962 contact 963 "WG Web: 964 WG List: 966 Author: Joe Clarke 967 969 Author: Reshad Rahman 970 972 Author: Robert Wilton 973 975 Author: Balazs Lengyel 976 978 Author: Jason Sterne 979 "; 980 description 981 "This YANG 1.1 module contains definitions and extensions to 982 support updated YANG revision handling. 984 Copyright (c) 2021 IETF Trust and the persons identified as 985 authors of the code. All rights reserved. 987 Redistribution and use in source and binary forms, with or 988 without modification, is permitted pursuant to, and subject 989 to the license terms contained in, the Simplified BSD License 990 set forth in Section 4.c of the IETF Trust's Legal Provisions 991 Relating to IETF Documents 992 (http://trustee.ietf.org/license-info). 994 This version of this YANG module is part of RFC XXXX; see 995 the RFC itself for full legal notices. 997 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 998 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 999 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1000 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1001 they appear in all capitals, as shown here."; 1003 // RFC Ed.: update the date below with the date of RFC publication 1004 // and remove this note. 1005 // RFC Ed.: replace XXXX (inc above) with actual RFC number and 1006 // remove this note. 1008 revision 2021-06-30 { 1009 rev:revision-label 1.0.0-draft-ietf-netmod-yang-module-versioning-04; 1010 description 1011 "Initial version."; 1012 reference 1013 "XXXX: Updated YANG Module Revision Handling"; 1014 } 1016 typedef revision-label { 1017 type string { 1018 length "1..255"; 1019 pattern '[a-zA-Z0-9,\-_.+]+'; 1020 pattern '\d{4}-\d{2}-\d{2}' { 1021 modifier invert-match; 1022 } 1023 } 1024 description 1025 "A label associated with a YANG revision. 1027 Alphanumeric characters, comma, hyphen, underscore, period 1028 and plus are the only accepted characters. MUST NOT match 1029 revision-date."; 1030 reference 1031 "XXXX: Updated YANG Module Revision Handling; 1032 Section 3.3, Revision label"; 1033 } 1035 typedef revision-date-or-label { 1036 type union { 1037 type yang:revision-identifier; 1038 type revision-label; 1039 } 1040 description 1041 "Represents either a YANG revision date or a revision label"; 1042 } 1044 extension non-backwards-compatible { 1045 description 1046 "This statement is used to indicate YANG module revisions that 1047 contain non-backwards-compatible changes. 1049 The statement MUST only be a substatement of the 'revision' 1050 statement. Zero or one 'non-backwards-compatible' statements 1051 per parent statement is allowed. No substatements for this 1052 extension have been standardized. 1054 If a revision of a YANG module contains changes, relative to 1055 the preceding revision in the revision history, that do not 1056 conform to the backwards compatible module update rules defined 1057 in RFC-XXX, then the 'non-backwards-compatible' statement MUST 1058 be added as a substatement to the revision statement. 1060 Conversely, if a revision does not contain a 1061 'non-backwards-compatible' statement then all changes, 1062 relative to the preceding revision in the revision history, 1063 MUST be backwards-compatible. 1065 A new module revision that only contains changes that are 1066 backwards compatible SHOULD NOT include the 1067 'non-backwards-compatible' statement. An example of when 1068 an author might add the 'non-backwards-compatible' statement 1069 is if they believe a change could negatively impact clients 1070 even though the backwards compatibility rules defined in 1071 RFC-XXXX classify it as a backwards-compatible change. 1073 Add, removing, or changing a 'non-backwards-compatible' 1074 statement is a backwards-compatible version change."; 1076 reference 1077 "XXXX: Updated YANG Module Revision Handling; 1078 Section 3.2, nbc-changes revision extension statement"; 1079 } 1081 extension revision-label { 1082 argument revision-label; 1083 description 1084 "The revision label can be used to provide an additional 1085 versioning identifier associated with a module or submodule 1086 revision. One such scheme that 1087 could be used is [XXXX: ietf-netmod-yang-semver]. 1089 The format of the revision-label argument MUST conform to the 1090 pattern defined for the revision-label typedef in this module. 1092 The statement MUST only be a substatement of the revision 1093 statement. Zero or one revision-label statements per parent 1094 statement are allowed. No substatements for this extension 1095 have been standardized. 1097 Revision labels MUST be unique amongst all revisions of a 1098 module or submodule. 1100 Adding a revision label is a backwards-compatible version 1101 change. Changing or removing an existing revision label in 1102 the revision history is a non-backwards-compatible version 1103 change, because it could impact any references to that 1104 revision label."; 1106 reference 1107 "XXXX: Updated YANG Module Revision Handling; 1108 Section 3.3, Revision label"; 1109 } 1111 extension revision-label-scheme { 1112 argument revision-label-scheme-identity; 1113 description 1114 "The revision label scheme specifies which revision-label scheme 1115 the module or submodule uses. 1117 The mandatory revision-label-scheme-identity argument MUST be an 1118 identity derived from revision-label-scheme-base. 1120 This extension is only valid as a top-level statement, i.e., 1121 given as as a substatement to 'module' or 'submodule'. No 1122 substatements for this extension have been standardized. 1124 This extension MUST be used if there is a revision-label 1125 statement in the module or submodule. 1127 Adding a revision label scheme is a backwards-compatible version 1128 change. Changing a revision label scheme is a 1129 non-backwards-compatible version change, unless the new revision 1130 label scheme is backwards-compatible with the replaced revision 1131 label scheme. Removing a revision label scheme is a 1132 non-backwards-compatible version change."; 1134 reference 1135 "XXXX: Updated YANG Module Revision Handling; 1136 Section 3.3.1, Revision label scheme extension statement"; 1137 } 1139 extension revision-or-derived { 1140 argument revision-date-or-label; 1141 description 1142 "Restricts the revision of the module that may be imported to 1143 one that matches or is derived from the specified 1144 revision-date or revision-label. 1146 The argument value MUST conform to the 1147 'revision-date-or-label' defined type. 1149 The statement MUST only be a substatement of the import 1150 statement. Zero, one or more 'revision-or-derived' statements 1151 per parent statement are allowed. No substatements for this 1152 extension have been standardized. 1154 If specified multiple times, then any module revision that 1155 satisfies at least one of the 'revision-or-derived' statements 1156 is an acceptable revision for import. 1158 An 'import' statement MUST NOT contain both a 1159 'revision-or-derived' extension statement and a 1160 'revision-date' statement. 1162 A particular revision of an imported module satisfies an 1163 import's 'revision-or-derived' extension statement if the 1164 imported module's revision history contains a revision 1165 statement with a matching revision date or revision label. 1167 The 'revision-or-derived' extension statement does not 1168 guarantee that all module revisions that satisfy an import 1169 statement are necessarily compatible, it only gives an 1170 indication that the revisions are more likely to be 1171 compatible. 1173 Adding, removing or updating a 'revision-or-derived' 1174 statement to an import is a backwards-compatible change. 1175 "; 1177 reference 1178 "XXXX: Updated YANG Module Revision Handling; 1179 Section 4, Import by derived revision"; 1180 } 1181 identity revision-label-scheme-base { 1182 description 1183 "Base identity from which all revision label schemes are 1184 derived."; 1186 reference 1187 "XXXX: Updated YANG Module Revision Handling; 1188 Section 3.3.1, Revision label scheme extension statement"; 1190 } 1191 } 1192 1194 YANG module with augmentations to YANG Library to revision labels 1196 file "ietf-yang-library-revisions@2021-10-22.yang" 1197 module ietf-yang-library-revisions { 1198 yang-version 1.1; 1199 namespace 1200 "urn:ietf:params:xml:ns:yang:ietf-yang-library-revisions"; 1201 prefix yl-rev; 1203 import ietf-yang-revisions { 1204 prefix rev; 1205 reference 1206 "XXXX: Updated YANG Module Revision Handling"; 1207 } 1209 import ietf-yang-library { 1210 prefix yanglib; 1211 reference "RFC 8525: YANG Library"; 1212 } 1214 organization 1215 "IETF NETMOD (Network Modeling) Working Group"; 1216 contact 1217 "WG Web: 1218 WG List: 1220 Author: Joe Clarke 1221 1223 Author: Reshad Rahman 1224 1226 Author: Robert Wilton 1227 1229 Author: Balazs Lengyel 1230 1232 Author: Jason Sterne 1233 "; 1234 description 1235 "This module contains augmentations to YANG Library to add module 1236 level revision label and to provide an indication of how 1237 deprecated and obsolete nodes are handled by the server. 1239 Copyright (c) 2021 IETF Trust and the persons identified as 1240 authors of the code. All rights reserved. 1242 Redistribution and use in source and binary forms, with or 1243 without modification, is permitted pursuant to, and subject 1244 to the license terms contained in, the Simplified BSD License 1245 set forth in Section 4.c of the IETF Trust's Legal Provisions 1246 Relating to IETF Documents 1247 (http://trustee.ietf.org/license-info). 1249 This version of this YANG module is part of RFC XXXX; see 1250 the RFC itself for full legal notices. 1252 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1253 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1254 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1255 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1256 they appear in all capitals, as shown here."; 1258 // RFC Ed.: update the date below with the date of RFC publication 1259 // and remove this note. 1260 // RFC Ed.: replace XXXX (including in the imports above) with 1261 // actual RFC number and remove this note. 1262 // RFC Ed.: please replace revision-label version with 1.0.0 and 1263 // remove this note. 1264 revision 2021-10-22 { 1265 rev:revision-label 1.0.0-draft-ietf-netmod-yang-module-versioning-04; 1266 description 1267 "Initial revision"; 1268 reference 1269 "XXXX: Updated YANG Module Revision Handling"; 1270 } 1272 // library 1.0 modules-state is not augmented with revision-label 1274 augment "/yanglib:yang-library/yanglib:module-set/yanglib:module" { 1275 description 1276 "Add a revision label to module information"; 1278 leaf revision-label { 1279 type rev:revision-label; 1280 description 1281 "The revision label associated with this module revision. 1282 The label MUST match the rev:revision-label value in the specific 1283 revision of the module loaded in this module-set."; 1285 reference 1286 "XXXX: Updated YANG Module Revision Handling; 1287 Section 5.2.1, Advertising revision-label"; 1288 } 1289 } 1291 augment "/yanglib:yang-library/yanglib:module-set/yanglib:module/" 1292 + "yanglib:submodule" { 1293 description 1294 "Add a revision label to submodule information"; 1295 leaf revision-label { 1296 type rev:revision-label; 1297 description 1298 "The revision label associated with this submodule revision. 1299 The label MUST match the rev:revision-label value in the specific 1300 revision of the submodule included by the module loaded in 1301 this module-set."; 1303 reference 1304 "XXXX: Updated YANG Module Revision Handling; 1305 Section 5.2.1, Advertising revision-label"; 1306 } 1307 } 1309 augment "/yanglib:yang-library/yanglib:module-set/" 1310 + "yanglib:import-only-module" { 1311 description 1312 "Add a revision label to module information"; 1313 leaf revision-label { 1314 type rev:revision-label; 1315 description 1316 "The revision label associated with this module revision. 1317 The label MUST match the rev:revision-label value in the specific 1318 revision of the module included in this module-set."; 1320 reference 1321 "XXXX: Updated YANG Module Revision Handling; 1322 Section 5.2.1, Advertising revision-label"; 1323 } 1324 } 1325 augment "/yanglib:yang-library/yanglib:module-set/" 1326 + "yanglib:import-only-module/yanglib:submodule" { 1327 description 1328 "Add a revision label to submodule information"; 1329 leaf revision-label { 1330 type rev:revision-label; 1331 description 1332 "The revision label associated with this submodule revision. 1333 The label MUST match the rev:label value in the specific 1334 revision of the submodule included by the 1335 import-only-module loaded in this module-set."; 1337 reference 1338 "XXXX: Updated YANG Module Revision Handling; 1339 Section 5.2.1, Advertising revision-label"; 1340 } 1341 } 1343 augment "/yanglib:yang-library/yanglib:schema" { 1344 description 1345 "Augmentations to the ietf-yang-library module to indicate how 1346 deprecated and obsoleted nodes are handled for each datastore 1347 schema supported by the server."; 1349 leaf deprecated-nodes-implemented { 1350 type boolean; 1351 description 1352 "If set to true, this leaf indicates that all schema nodes with 1353 a status 'deprecated' are implemented 1354 equivalently as if they had status 'current'; otherwise 1355 deviations MUST be used to explicitly remove deprecated 1356 nodes from the schema. If this leaf is absent or set to false, 1357 then the behavior is unspecified."; 1359 reference 1360 "XXXX: Updated YANG Module Revision Handling; 1361 Section 5.2.2, Reporting how deprecated and obsolete nodes 1362 are handled"; 1363 } 1365 leaf obsolete-nodes-absent { 1366 type boolean; 1367 description 1368 "If set to true, this leaf indicates that the server does not 1369 implement any status 'obsolete' schema nodes. If this leaf is 1370 absent or set to false, then the behaviour is unspecified."; 1372 reference 1373 "XXXX: Updated YANG Module Revision Handling; 1374 Section 5.2.2, Reporting how deprecated and obsolete nodes 1375 are handled"; 1376 } 1377 } 1378 } 1379 1381 9. Contributors 1383 This document grew out of the YANG module versioning design team that 1384 started after IETF 101. The following individuals are (or have been) 1385 members of the design team and have worked on the YANG versioning 1386 project: 1388 * Balazs Lengyel 1390 * Benoit Claise 1392 * Bo Wu 1394 * Ebben Aries 1396 * Jan Lindblad 1398 * Jason Sterne 1400 * Joe Clarke 1402 * Juergen Schoenwaelder 1404 * Mahesh Jethanandani 1406 * Michael (Wangzitao) 1408 * Qin Wu 1410 * Reshad Rahman 1412 * Rob Wilton 1414 The initial revision of this document was refactored and built upon 1415 [I-D.clacla-netmod-yang-model-update]. We would like to thank Kevin 1416 D'Souza and Benoit Claise for their initial work in this problem 1417 space. 1419 Discussons on the use of Semver for YANG versioning has been held 1420 with authors of the OpenConfig YANG models. We would like to thank 1421 both Anees Shaikh and Rob Shakir for their input into this problem 1422 space. 1424 We would also like to thank Lou Berger, Andy Bierman, Martin 1425 Bjorklund, Italo Busi, Tom Hill, Scott Mansfield, Kent Watsen for 1426 their contributions and review comments. 1428 10. Security Considerations 1430 The document does not define any new protocol or data model. There 1431 are no security considerations beyond those specified in [RFC7950] 1432 and [RFC6020]. 1434 11. IANA Considerations 1436 11.1. YANG Module Registrations 1438 This document requests IANA to registers a URI in the "IETF XML 1439 Registry" [RFC3688]. Following the format in RFC 3688, the following 1440 registrations are requested. 1442 URI: urn:ietf:params:xml:ns:yang:ietf-yang-revisions 1443 Registrant Contact: The IESG. 1444 XML: N/A, the requested URI is an XML namespace. 1446 URI: urn:ietf:params:xml:ns:yang:ietf-yang-library-revisions 1447 Registrant Contact: The IESG. 1448 XML: N/A, the requested URI is an XML namespace. 1450 The following YANG module is requested to be registred in the "IANA 1451 Module Names" [RFC6020]. Following the format in RFC 6020, the 1452 following registrations are requested: 1454 The ietf-yang-revisions module: 1456 Name: ietf-yang-revisions 1458 XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-revisions 1460 Prefix: rev 1462 Reference: [RFCXXXX] 1464 The ietf-yang-library-revisions module: 1466 Name: ietf-yang-library-revisions 1467 XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-library- 1468 revisions 1470 Prefix: yl-rev 1472 Reference: [RFCXXXX] 1474 11.2. Guidance for versioning in IANA maintained YANG modules 1476 Note for IANA (to be removed by the RFC editor): Please check that 1477 the registries and IANA YANG modules are referenced in the 1478 appropriate way. 1480 IANA is responsible for maintaining and versioning YANG modules that 1481 are derived from other IANA registries. For example, 1482 "iana-if-type.yang" [IfTypeYang] is derived from the "Interface Types 1483 (ifType) IANA registry" [IfTypesReg], and "iana-routing-types.yang" 1484 [RoutingTypesYang] is derived from the "Address Family Numbers" 1485 [AddrFamilyReg] and "Subsequent Address Family Identifiers (SAFI) 1486 Parameters" [SAFIReg] IANA registries. 1488 Normally, updates to the registries cause any derived YANG modules to 1489 be updated in a backwards-compatible way, but there are some cases 1490 where the registry updates can cause non-backward-compatible updates 1491 to the derived YANG module. An example of such an update is the 1492 2020-12-31 revision of iana-routing-types.yang 1493 [RoutingTypesDecRevision], where the enum name for two SAFI values 1494 was changed. 1496 In all cases, IANA MUST follow the versioning guidance specified in 1497 Section 3.1, and MUST include a "rev:non-backwards-compatible" 1498 substatement to the latest revision statement whenever an IANA 1499 maintained module is updated in a non-backwards-compatible way, as 1500 described in Section 3.2. 1502 Note: For published IANA maintained YANG modules that contain non- 1503 backwards-compatible changes between revisions, a new revision should 1504 be published with the "rev:non-backwards-compatible" substatement 1505 retrospectively added to any revisions containing non-backwards- 1506 compatible changes. 1508 Non-normative examples of updates to enumeration types in IANA 1509 maintained modules that would be classified as non-backwards- 1510 compatible changes are: Changing the status of an enumeration typedef 1511 to obsolete, changing the status of an enum entry to obsolete, 1512 removing an enum entry, changing the identifier of an enum entry, or 1513 changing the described meaning of an enum entry. 1515 Non-normative examples of updates to enumeration types in IANA 1516 maintained modules that would be classified as backwards-compatible 1517 changes are: Adding a new enum entry to the end of the enumeration, 1518 changing the status or an enum entry to deprecated, or improving the 1519 description of an enumeration that does not change its defined 1520 meaning. 1522 Non-normative examples of updates to identity types in IANA 1523 maintained modules that would be classified as non-backwards- 1524 compatible changes are: Changing the status of an identity to 1525 obsolete, removing an identity, renaming an identity, or changing the 1526 described meaning of an identity. 1528 Non-normative examples of updates to identity types in IANA 1529 maintained modules that would be classified as backwards-compatible 1530 changes are: Adding a new identity, changing the status or an 1531 identity to deprecated, or improving the description of an identity 1532 that does not change its defined meaning. 1534 12. References 1536 12.1. Normative References 1538 [I-D.ietf-netmod-rfc6991-bis] 1539 Schoenwaelder, J., "Common YANG Data Types", Work in 1540 Progress, Internet-Draft, draft-ietf-netmod-rfc6991-bis- 1541 07, 9 July 2021, . 1544 [I-D.ietf-netmod-yang-semver] 1545 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, 1546 B., Sterne, J., and K. D'Souza, "YANG Semantic 1547 Versioning", Work in Progress, Internet-Draft, draft-ietf- 1548 netmod-yang-semver-03, 12 July 2021, 1549 . 1552 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1553 Requirement Levels", BCP 14, RFC 2119, 1554 DOI 10.17487/RFC2119, March 1997, 1555 . 1557 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1558 DOI 10.17487/RFC3688, January 2004, 1559 . 1561 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1562 the Network Configuration Protocol (NETCONF)", RFC 6020, 1563 DOI 10.17487/RFC6020, October 2010, 1564 . 1566 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1567 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1568 . 1570 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1571 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1572 May 2017, . 1574 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 1575 Documents Containing YANG Data Models", BCP 216, RFC 8407, 1576 DOI 10.17487/RFC8407, October 2018, 1577 . 1579 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 1580 and R. Wilton, "YANG Library", RFC 8525, 1581 DOI 10.17487/RFC8525, March 2019, 1582 . 1584 12.2. Informative References 1586 [AddrFamilyReg] 1587 "Address Family Numbers IANA Registry", 1588 . 1591 [I-D.clacla-netmod-yang-model-update] 1592 Claise, B., Clarke, J., Lengyel, B., and K. D'Souza, "New 1593 YANG Module Update Procedure", Work in Progress, Internet- 1594 Draft, draft-clacla-netmod-yang-model-update-06, 2 July 1595 2018, . 1598 [I-D.ietf-netmod-yang-instance-file-format] 1599 Lengyel, B. and B. Claise, "YANG Instance Data File 1600 Format", Work in Progress, Internet-Draft, draft-ietf- 1601 netmod-yang-instance-file-format-21, 8 October 2021, 1602 . 1605 [I-D.ietf-netmod-yang-packages] 1606 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and B. Wu, 1607 "YANG Packages", Work in Progress, Internet-Draft, draft- 1608 ietf-netmod-yang-packages-01, 2 November 2020, 1609 . 1612 [I-D.ietf-netmod-yang-solutions] 1613 Wilton, R., "YANG Versioning Solution Overview", Work in 1614 Progress, Internet-Draft, draft-ietf-netmod-yang- 1615 solutions-01, 2 November 2020, 1616 . 1619 [I-D.ietf-netmod-yang-ver-selection] 1620 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and B. Wu, 1621 "YANG Schema Selection", Work in Progress, Internet-Draft, 1622 draft-ietf-netmod-yang-ver-selection-00, 17 March 2020, 1623 . 1626 [I-D.ietf-netmod-yang-versioning-reqs] 1627 Clarke, J., "YANG Module Versioning Requirements", Work in 1628 Progress, Internet-Draft, draft-ietf-netmod-yang- 1629 versioning-reqs-05, 6 July 2021, 1630 . 1633 [IfTypesReg] 1634 "Interface Types (ifType) IANA Registry", 1635 . 1638 [IfTypeYang] 1639 "iana-if-type YANG Module", 1640 . 1643 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1644 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1645 . 1647 [RoutingTypesDecRevision] 1648 "2020-12-31 revision of iana-routing-types.yang", 1649 . 1652 [RoutingTypesYang] 1653 "iana-routing-types YANG Module", 1654 . 1657 [SAFIReg] "Subsequent Address Family Identifiers (SAFI) Parameters 1658 IANA Registry", . 1661 [semver] "Semantic Versioning 2.0.0", . 1663 Appendix A. Examples of changes that are NBC 1665 Examples of NBC changes include: 1667 * Deleting a data node, or changing it to status obsolete. 1669 * Changing the name, type, or units of a data node. 1671 * Modifying the description in a way that changes the semantic 1672 meaning of the data node. 1674 * Any changes that change or reduce the allowed value set of the 1675 data node, either through changes in the type definition, or the 1676 addition or changes to "must" statements, or changes in the 1677 description. 1679 * Adding or modifying "when" statements that reduce when the data 1680 node is available in the schema. 1682 * Making the statement conditional on if-feature. 1684 Appendix B. Examples of applying the NBC change guidelines 1686 The following sections give steps that could be taken for making NBC 1687 changes to a YANG module or submodule using the incremental approach 1688 described in section Section 7.1.1. 1690 The examples are all for "config true" nodes. 1692 Alternatively, the NBC changes MAY be done non-incrementally and 1693 without using "status" statements if the server can support multiple 1694 revisions of the YANG module or of YANG packages. Clients would be 1695 required to select the revision which they support and the NBC change 1696 would have no impact on them. 1698 B.1. Removing a data node 1700 Removing a leaf or container from the data tree, e.g., because 1701 support for the corresponding feature is being removed: 1703 1. The schema node's status is changed to "deprecated" and the node 1704 is supported for some period of time (e.g. one year). This is a 1705 BC change. 1707 2. When the schema node is not supported anymore, its status is 1708 changed to "obsolete" and the "description" updated. This is an 1709 NBC change. 1711 B.2. Changing the type of a leaf node 1713 Changing the type of a leaf node. e.g., a "vpn-id" node of type 1714 integer being changed to a string: 1716 1. The status of schema node "vpn-id" is changed to "deprecated" and 1717 the node is supported for some period of time (e.g. one year). 1718 This is a BC change. The description is updated to indicate that 1719 "vpn-name" is replacing this node. 1721 2. A new schema node, e.g., "vpn-name", of type string is added to 1722 the same location as the existing node "vpn-id". This new node 1723 has status "current" and its description explains that it is 1724 replacing node "vpn-id". 1726 3. During the period of time when both schema nodes are supported, 1727 the interactions between the two nodes is outside the scope of 1728 this document and will vary on a case by case basis. Here are 1729 some options: 1731 1. A server may prevent the new node from being set if the old 1732 node is already set (and vice-versa). A "choice" 1733 construction could be used, or the new node may have a "when" 1734 statement to achieve this. The old node must not have a 1735 "when" statement since this would be an NBC change, but the 1736 server could reject the old node from being set if the new 1737 node is already set. 1739 2. If the new node is set and a client does a get or get-config 1740 operation on the old node, the server could map the value. 1741 For example, if the new node "vpn-name" has value "123" then 1742 the server could return integer value 123 for the old node 1743 "vpn-id". However, if the value can not be mapped then the 1744 configuration would be incomplete. The behavior in this case 1745 is outside the scope of this document. 1747 4. When the schema node "vpn-id" is not supported anymore, its 1748 status is changed to "obsolete" and the "description" is updated. 1749 This is an NBC change. 1751 B.3. Reducing the range of a leaf node 1753 Reducing the range of values of a leaf-node, e.g., consider a "vpn- 1754 id" schema node of type uint32 being changed from range 1..5000 to 1755 range 1..2000: 1757 1. If all values which are being removed were never supported, e.g., 1758 if a vpn-id of 2001 or higher was never accepted, this is a BC 1759 change for the functionality (no functionality change). Even if 1760 it is an NBC change for the YANG model, there should be no impact 1761 for clients using that YANG model. 1763 2. If one or more values being removed was previously supported, 1764 e.g., if a vpn-id of 3333 was accepted previously, this is an NBC 1765 change for the YANG model. Clients using the old YANG model will 1766 be impacted, so a change of this nature should be done carefully, 1767 e.g., by using the steps described in Appendix B.2 1769 B.4. Changing the key of a list 1771 Changing the key of a list has a big impact to the client. For 1772 example, consider a "sessions" list which has a key "interface" and 1773 there is a need to change the key to "dest-address". Such a change 1774 can be done in steps: 1776 1. The status of list "sessions" is changed to "deprecated" and the 1777 list is supported for some period of time (e.g. one year). This 1778 is a BC change. The description is updated to indicate the new 1779 list that is replacing this list. 1781 2. A new list is created in the same location with the same 1782 descendant schema nodes but with "dest-address" as key. Finding 1783 an appropriate name for the new list can be difficult. In this 1784 case the new list is called "sessions-address", has status 1785 "current" and its description should explain that it is replacing 1786 list "session". 1788 3. During the period of time when both lists are supported, the 1789 interactions between the two lists is outside the scope of this 1790 document and will vary on a case by case basis. Here are some 1791 options: 1793 1. A server could prevent entries in the new list from being 1794 created if the old list already has entries (and vice-versa). 1796 2. If the new list has entries created and a client does a get 1797 or get-config operation on the old list, the server could map 1798 the entries. However, if the new list has entries which 1799 would lead to duplicate keys in the old list, the mapping can 1800 not be done. 1802 4. When list "sessions" is not available anymore, its status is 1803 changed to "obsolete" and the "description" is updated. This is 1804 an NBC change. 1806 If the server can support NBC revisions of the YANG module 1807 simultaneously using version selection 1808 [I-D.ietf-netmod-yang-ver-selection], then the changes can be done 1809 immediately: 1811 1. The new revision of the YANG module has the list "sessions" 1812 modified to have "dest-address" as key, this is an NBC change. 1814 2. Clients which require the previous functionality select the older 1815 module revision 1817 B.5. Renaming a node 1819 A leaf or container schema node may be renamed, either due to a 1820 spelling error in the previous name or because of a better name. For 1821 example a node "ip-adress" could be renamed to "ip-address": 1823 1. The status of the existing node "ip-adress" is changed to 1824 "deprecated" and is supported for some period of time (e.g. one 1825 year). This is a BC change. The description is updated to 1826 indicate the node that is replacing this node. 1828 2. The new schema node "ip-address" is added to the same location as 1829 the existing node "ip-adress". This new node has status 1830 "current" and its description should explain that it is replacing 1831 node "ip-adress". 1833 3. During the period of time when both nodes are available, the 1834 interactions between the two nodes is outside the scope of this 1835 document and will vary on a case by case basis. Here are some 1836 options: 1838 1. A server may prevent the new node from being set if the old 1839 node is already set (and vice-versa). A "choice" 1840 construction could be used, or the new node may have a "when" 1841 statement to achieve this. The old node must not have a 1842 "when" statement since this would be an NBC change, but the 1843 server could reject the old node from being set if the new 1844 node is already set. 1846 2. If the new node is set and a client does a get or get-config 1847 operation on the old node, the server could use the value of 1848 the new node. For example, if the new node "ip-address" has 1849 value X then the server may return value X for the old node 1850 "ip-adress". 1852 4. When node "ip-adress" is not available anymore, its status is 1853 changed to "obsolete" and the "description" is updated. This is 1854 an NBC change. 1856 Authors' Addresses 1858 Robert Wilton (editor) 1859 Cisco Systems, Inc. 1861 Email: rwilton@cisco.com 1863 Reshad Rahman (editor) 1865 Email: reshad@yahoo.com 1867 Balazs Lengyel (editor) 1868 Ericsson 1870 Email: balazs.lengyel@ericsson.com 1872 Joe Clarke 1873 Cisco Systems, Inc. 1875 Email: jclarke@cisco.com 1877 Jason Sterne 1878 Nokia 1880 Email: jason.sterne@nokia.com