idnits 2.17.1 draft-ietf-netmod-yang-module-versioning-01.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 10, 2020) is 1386 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 1251, but not defined == Unused Reference: 'I-D.ietf-netmod-rfc6991-bis' is defined on line 1262, but no explicit reference was found in the text == Outdated reference: A later version (-15) exists of draft-ietf-netmod-rfc6991-bis-04 == Outdated reference: A later version (-15) exists of draft-ietf-netmod-yang-semver-00 ** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525) == Outdated reference: A later version (-21) exists of draft-ietf-netmod-yang-instance-file-format-12 == Outdated reference: A later version (-03) exists of draft-ietf-netmod-yang-packages-00 == Outdated reference: A later version (-01) exists of draft-ietf-netmod-yang-solutions-00 == Outdated reference: A later version (-09) exists of draft-ietf-netmod-yang-versioning-reqs-03 Summary: 1 error (**), 0 flaws (~~), 9 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Wilton, Ed. 3 Internet-Draft R. Rahman, Ed. 4 Updates: 7950,8407,8525 (if approved) Cisco Systems, Inc. 5 Intended status: Standards Track B. Lengyel, Ed. 6 Expires: January 11, 2021 Ericsson 7 J. Clarke 8 Cisco Systems, Inc. 9 J. Sterne 10 Nokia 11 B. Claise 12 Cisco Systems, Inc. 13 K. D'Souza 14 AT&T 15 July 10, 2020 17 Updated YANG Module Revision Handling 18 draft-ietf-netmod-yang-module-versioning-01 20 Abstract 22 This document specifies a new YANG module update procedure that can 23 document when non-backwards-compatible changes have occurred during 24 the evolution of a YANG module. It extends the YANG import statement 25 with an earliest revision filter to better represent inter-module 26 dependencies. It provides help and guidelines for managing the 27 lifecycle of YANG modules and individual schema nodes. It provides a 28 mechanism, via the revision-label YANG extension, to specify a 29 revision identifier for YANG modules. This document updates RFC 30 7950, RFC 8407 and RFC 8525. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at https://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on January 11, 2021. 49 Copyright Notice 51 Copyright (c) 2020 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents 56 (https://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 67 1.1. Updates to YANG RFCs . . . . . . . . . . . . . . . . . . 4 68 2. Terminology and Conventions . . . . . . . . . . . . . . . . . 4 69 3. Refinements to YANG revision handling . . . . . . . . . . . . 5 70 3.1. Updating a YANG module with a new revision . . . . . . . 5 71 3.1.1. Backwards-compatible changes . . . . . . . . . . . . 6 72 3.1.2. Non-backwards-compatible changes . . . . . . . . . . 6 73 3.2. nbc-changes revision extension statement . . . . . . . . 7 74 3.3. Revision label . . . . . . . . . . . . . . . . . . . . . 7 75 3.3.1. Revision label scheme extension statement . . . . . . 8 76 3.4. Examples for updating the YANG module revision history . 8 77 4. Import by derived revision . . . . . . . . . . . . . . . . . 11 78 4.1. Module import examples . . . . . . . . . . . . . . . . . 12 79 5. Updates to ietf-yang-library . . . . . . . . . . . . . . . . 14 80 5.1. Resolving ambiguous module imports . . . . . . . . . . . 14 81 5.2. YANG library versioning augmentations . . . . . . . . . . 15 82 5.2.1. Advertising revision-label . . . . . . . . . . . . . 15 83 5.2.2. Reporting how deprecated and obsolete nodes are 84 handled . . . . . . . . . . . . . . . . . . . . . . . 15 85 6. Versioning of YANG instance data . . . . . . . . . . . . . . 16 86 7. Guidelines for using the YANG module update rules . . . . . . 16 87 7.1. Guidelines for YANG module authors . . . . . . . . . . . 16 88 7.1.1. Making non-backwards-compatible changes to a YANG 89 module . . . . . . . . . . . . . . . . . . . . . . . 17 90 7.2. Versioning Considerations for Clients . . . . . . . . . . 18 91 8. Module Versioning Extension YANG Modules . . . . . . . . . . 18 92 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 26 93 10. Security Considerations . . . . . . . . . . . . . . . . . . . 27 94 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 95 11.1. YANG Module Registrations . . . . . . . . . . . . . . . 27 96 11.2. Instructions . . . . . . . . . . . . . . . . . . . . . . 28 98 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 28 99 12.1. Normative References . . . . . . . . . . . . . . . . . . 28 100 12.2. Informative References . . . . . . . . . . . . . . . . . 29 101 Appendix A. Examples of changes that are NBC . . . . . . . . . . 29 102 Appendix B. Examples of applying the NBC change guidelines . . . 30 103 B.1. Removing a data node . . . . . . . . . . . . . . . . . . 30 104 B.2. Changing the type of a leaf node . . . . . . . . . . . . 31 105 B.3. Reducing the range of a leaf node . . . . . . . . . . . . 32 106 B.4. Changing the key of a list . . . . . . . . . . . . . . . 32 107 B.5. Renaming a node . . . . . . . . . . . . . . . . . . . . . 33 108 B.6. Changing a default value . . . . . . . . . . . . . . . . 34 109 Appendix C. Changes between revisions . . . . . . . . . . . . . 34 110 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34 112 1. Introduction 114 This document defines a solution to the YANG module lifecycle 115 problems described in [I-D.ietf-netmod-yang-versioning-reqs]. 116 Complementary documents provide a complete solution to the YANG 117 versioning requirements, with the overall relationship of the 118 solution drafts described in [I-D.ietf-netmod-yang-solutions]. 120 Specifically, this document recognises a need (within standards 121 organizations, vendors, and the industry) to sometimes allow YANG 122 modules to evolve with non-backwards-compatible changes, which could 123 cause breakage to clients and importing YANG modules. Accepting that 124 non-backwards-compatible changes do sometimes occur, it is important 125 to have mechanisms to report where these changes occur, and to manage 126 their effect on clients and the broader YANG ecosystem. 128 The document comprises five parts: 130 Refinements to the YANG 1.1 module revision update procedure, 131 supported by new extension statements to indicate when a revision 132 contains non-backwards-compatible changes, and an optional 133 revision label. 135 A YANG extension statement allowing YANG module imports to specify 136 an earliest module revision that may satisfy the import 137 dependency. 139 Updates and augmentations to ietf-yang-library to include the 140 revision label in the module descriptions, to report how 141 "deprecated" and "obsolete" nodes are handled by a server, and to 142 clarify how module imports are resolved when multiple revisions 143 could otherwise be chosen. 145 Considerations of how versioning applies to YANG instance data. 147 Guidelines for how the YANG module update rules defined in this 148 document should be used, along with examples. 150 Note to RFC Editor (To be removed by RFC Editor) 152 Open issues are tracked at . 155 1.1. Updates to YANG RFCs 157 This document updates [RFC7950] section 11. Section 3 describes 158 modifications to YANG revision handling and update rules, and 159 Section 4 describes a YANG extension statement to do import by 160 derived revision. 162 This document updates [RFC7950] section 5.6.5. Section 5.1 defines 163 how a client of a YANG library datastore schema resolves ambiguous 164 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 [RFC7950] section 5.2. Section 3.3 describes 171 the use of a revision label in the name of a file containing a YANG 172 module or submodule. 174 2. Terminology and Conventions 176 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 177 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 178 "OPTIONAL" in this document are to be interpreted as described in BCP 179 14 [RFC2119] [RFC8174] when, and only when, they appear in all 180 capitals, as shown here. 182 In addition, this document uses the terminology: 184 o YANG module revision: An instance of a YANG module, uniquely 185 identified with a revision date, with no implied ordering or 186 backwards compatibility between different revisions of the same 187 module. 189 o Backwards-compatible (BC) change: A backwards-compatible change 190 between two YANG module revisions, as defined in Section 3.1.1 192 o Non-backwards-compatible (NBC) change: A non-backwards-compatible 193 change between two YANG module revisions, as defined in 194 Section 3.1.2 196 3. Refinements to YANG revision handling 198 [RFC7950] assumes, but does not explicitly state, that the revision 199 history for a YANG module is strictly linear, i.e., it is prohibited 200 to have two independent revisions of a YANG module that are both 201 directly derived from the same parent revision. 203 This document clarifies [RFC7950] to explicitly allow non linear 204 development of YANG module revisions, so modules MAY have multiple 205 revisions that directly derive from the same parent revision. As per 206 [RFC7950], YANG module revisions continue to be uniquely identified 207 by the module's revision date, and hence all revisions of a module 208 MUST have unique revision dates. 210 A corollary to the above is that the relationship between two module 211 revisions cannot be determined by comparing the module revision date 212 alone, and the revision history, or revision label, must also be 213 taken into consideration. 215 A module's name and revision date identifies a specific immutable 216 definition of that module within its revision history. Hence, if a 217 module includes submodules then to ensure that the module's content 218 is uniquely defined, the module's "include" statements SHOULD use 219 "revision-date" substatements to specify the exact revision date of 220 each included submodule. When a module does not include its 221 submodules by revision-date, the revision of submodules used cannot 222 be derived from the including module. Mechanisms such as YANG 223 packages [I-D.ietf-netmod-yang-packages], and YANG library [[RFC7895] 224 [RFC8525], MAY be used to specify the exact submodule revisions used 225 when the submodule revision date is not constrained by the "include" 226 statement. 228 [RFC7950] section 11 requires that all updates to a YANG module are 229 BC to the previous revision of the module. This document allows for 230 more flexible evolution of YANG modules: NBC changes between module 231 revisions are allowed and are documented using a new "nbc-changes" 232 YANG extension statement in the module revision history. 234 Two revisions of a module MAY have identical content except for the 235 revision history. This could occur, for example, if a module has a 236 branched history and identical changes are applied in multiple 237 branches. 239 3.1. Updating a YANG module with a new revision 241 This section updates [RFC7950] section 11 to refine the rules for 242 permissible changes when a new YANG module revision is created. 244 Where pragmatic, updates to YANG modules SHOULD be backwards- 245 compatible, following the definition in Section 3.1.1. 247 A new module revision MAY contain NBC changes, i.e., the semantics of 248 an existing definition MAY be changed in an NBC way without requiring 249 a new definition with a new identifier. A new module revision with 250 NBC changes MUST include the "rev:nbc-changes" extension substatement 251 to signal the potential for incompatibility to existing module users 252 and readers. 254 3.1.1. Backwards-compatible changes 256 A change between two module revisions is defined as being "backwards- 257 compatible" if the change conforms to the module update rules 258 specified in [RFC7950] section 11, updated by the following rules: 260 o A "status" "deprecated" statement MAY be added, or changed from 261 "current" to "deprecated", but adding or changing "status" to 262 "obsolete" is not a backwards-compatible change. 264 o Obsolete definitions MAY be removed from published modules, and 265 are classified as backwards-compatible changes. In some 266 circumstances it may be helpful to retain the obsolete definitions 267 to ensure that their identifiers are not reused with a different 268 meaning. 270 o In statements that have any data definition statements as 271 substatements, those data definition substatements MAY be 272 reordered, as long as they do not change the ordering of any 273 "input" or "output" data definition substatements of "rpc" or 274 "action" statements. If new data definition statements are added, 275 they can be added anywhere in the sequence of existing 276 substatements. 278 o Any changes (including whitespace or formatting changes) that do 279 not change the semantic meaning of the module are backwards 280 compatible. 282 3.1.2. Non-backwards-compatible changes 284 Any changes to YANG modules that are not defined by Section 3.1.1 as 285 being backwards-compatible are classified as "non-backwards- 286 compatible" changes. 288 3.2. nbc-changes revision extension statement 290 The "rev:nbc-changes" extension statement is used to indicate YANG 291 module revisions that contain NBC changes. 293 If a revision of a YANG module contains changes, relative to the 294 preceding revision in the revision history, that do not conform to 295 the module update rules defined in Section 3.1.1, then a "rev:nbc- 296 changes" extension statement MUST be added as a substatement to the 297 "revision" statement. 299 Conversely, if a revision does not contain an "rev:nbc-changes" 300 extension substatement then all changes, relative to the preceding 301 revision in the revision history, MUST be backwards-compatible. 303 3.3. Revision label 305 This section updates [RFC7950] section 5.2, it explains how a 306 revision label can be used in the name of a file containing a YANG 307 module or submodule. 309 Each revision entry in a module or submodule MAY have a revision 310 label associated with it, providing an alternative alias to identify 311 a particular revision of a module or submodule. The revision label 312 could be used to provide an additional versioning identifier 313 associated with the revision. 315 YANG Semver [I-D.ietf-netmod-yang-semver] defines a versioning scheme 316 based on Semver 2.0.0 [semver] that can be used as a revision label. 318 Submodules MAY use a revision label scheme. When they use a revision 319 label scheme, submodules MAY use a revision label scheme that is 320 different from the one used in the including module. 322 The revision label space of submodules is separate from the revision 323 label space of the including module. A change in one submodule MUST 324 result in a new revision label of that submodule and the including 325 module, but the actual values of the revision labels in the module 326 and submodule could be completely different. A change in one 327 submodule does not result in a new revision label in another 328 submodule. A change in a module revision label does not necessarily 329 mean a change to the revision label in all included submodules. 331 If a revision has an associated revision label, then it may be used 332 instead of the revision date in an "rev:revision-or-derived" 333 extension statement argument. 335 If a revision has an associated revision label, then it may be used 336 instead of the revision date in the filename of a YANG module, where 337 it takes the form: 339 module-or-submodule-name [['@' revision-date]|['#' revision-label]] 340 ( '.yang' / '.yin' ) 342 E.g., acme-router-modules@2018-01-25.yang 343 E.g., acme-router-modules#2.0.3.yang 345 Two file names, one with the revision date and another with the 346 revision label, MAY exist for the same module (or submodule) 347 revision. 349 A specific revision-label identifies a specific revision (variant) of 350 the module. If two YANG modules contain the same module name and the 351 same revision-label (and hence also the same revision-date) in their 352 latest revision statement, then the contents of the two modules MUST 353 be identical. 355 3.3.1. Revision label scheme extension statement 357 The "rev:revision-label-scheme" extension statement is used to 358 indicate which revision-label scheme a module or submodule uses. The 359 mandatory argument to this extension statement: 361 o Specifies the revision-label scheme used by the module or 362 submodule 364 o Is defined in the document which specifies the revision-label 365 scheme 367 o MUST be an identity derived from "revision-label-scheme-base" 369 The revision-label scheme used by a module or submodule SHOULD NOT 370 change during the lifetime of the module or submodule. If the 371 revision-label scheme used by a module or submodule is changed to a 372 new scheme, then all revision-label statements that do not conform to 373 the new scheme MUST be replaced or removed. 375 3.4. Examples for updating the YANG module revision history 377 The following diagram, explanation, and module history illustrates 378 how the branched revision history, "nbc-changes" extension statement, 379 and "revision-label" extension statement could be used: 381 Example YANG module with branched revision history. 383 Module revision date Revision label 384 2019-01-01 <- 1.0.0 385 | 386 2019-02-01 <- 2.0.0 387 | \ 388 2019-03-01 \ <- 3.0.0 389 | \ 390 | 2019-04-01 <- 2.1.0 391 | | 392 | 2019-05-01 <- 2.2.0 393 | 394 2019-06-01 <- 3.1.0 396 The tree diagram above illustrates how an example module's revision 397 history might evolve, over time. For example, the tree might 398 represent the following changes, listed in chronological order from 399 oldest revision to newest: 401 Example module, revision 2019-06-01: 403 module example-module { 405 namespace "urn:example:module"; 406 prefix "prefix-name"; 408 import ietf-yang-revisions { prefix "rev"; } 410 description 411 "to be completed"; 413 revision 2019-06-01 { 414 rev:revision-label 3.1.0; 415 description "Add new functionality."; 416 } 418 revision 2019-04-01 { 419 rev:revision-label 3.0.0; 420 rev:nbc-changes; 421 description 422 "Add new functionality. Remove some deprecated nodes."; 423 } 425 revision 2019-02-01 { 426 rev:revision-label 2.0.0; 427 rev:nbc-changes; 428 description "Apply bugfix to pattern statement"; 429 } 431 revision 2019-01-01 { 432 rev:revision-label 1.0.0; 433 description "Initial revision"; 434 } 436 //YANG module definition starts here 437 } 439 Example module, revision 2019-05-01: 441 module example-module { 443 namespace "urn:example:module"; 444 prefix "prefix-name"; 446 import ietf-yang-revisions { prefix "rev"; } 448 description 449 "to be completed"; 451 revision 2019-05-01 { 452 rev:revision-label 2.2.0; 453 description "Backwards-compatible bugfix to enhancement."; 454 } 456 revision 2019-03-01 { 457 rev:revision-label 2.1.0; 458 description "Apply enhancement to older release train."; 459 } 461 revision 2019-02-01 { 462 rev:revision-label 2.0.0; 463 rev:nbc-changes; 464 description "Apply bugfix to pattern statement"; 465 } 467 revision 2019-01-01 { 468 rev:revision-label 1.0.0; 469 description "Initial revision"; 470 } 472 //YANG module definition starts here 473 } 475 4. Import by derived revision 477 RFC 7950 allows YANG module "import" statements to optionally require 478 the imported module to have a particular revision date. In practice, 479 importing a module with an exact revision date is often too 480 restrictive because it requires the importing module to be updated 481 whenever any change to the imported module occurs. The alternative 482 choice of using an import statement without any revision date 483 statement is also not ideal because the importing module may not work 484 with all possible revisions of the imported module. 486 Instead, it is desirable for a importing module to specify a "minimum 487 required revision" of a module that it is compatible with, based on 488 the assumption that later revisions derived from that "minimum 489 required revision" are also likely to be compatible. Many possible 490 changes to a YANG module do not break importing modules, even if the 491 changes themselves are not strictly backwards-compatible. E.g., 492 fixing an incorrect pattern statement or description for a leaf would 493 not break an import, changing the name of a leaf could break an 494 import but frequently would not, but removing a container would break 495 imports if that container is augmented by another module. 497 The ietf-revisions module defines the "revision-or-derived" extension 498 statement, a substatement to the YANG "import" statement, to allow 499 for a "minimum required revision" to be specified during import: 501 The argument to the "revision-or-derived" extension statement is a 502 revision date or a revision label. 504 A particular revision of an imported module satisfies an import's 505 "revision-or-derived" extension statement if the imported module's 506 revision history contains a revision statement with a matching 507 revision date or revision label. 509 An "import" statement MUST NOT contain both a "revision-or- 510 derived" extension statement and a "revision-date" statement. 512 The "revision-or-derived" extension statement MAY be specified 513 multiple times, allowing the import to use any module revision 514 that satisfies at least one of the "revision-or-derived" extension 515 statements. 517 The "revision-or-derived" extension statement does not guarantee 518 that all module revisions that satisfy an import statement are 519 necessarily compatible, it only gives an indication that the 520 revisions are more likely to be compatible. Hence, NBC changes to 521 an imported module may also require new revisions of any importing 522 modules, updated to accommodation those changes, along with 523 updated import "revision-or-derived" extension statements to 524 depend on the updated imported module revision. 526 4.1. Module import examples 528 Consider the example module "example-module" from Section 3.4 that is 529 hypothetically available in the following revision/label pairings: 530 2019-01-01/1.0.0, 2019-02-01/2.0.0, 2019-03-01/3.0.0, 531 2019-04-01/2.1.0, 2019-05-01/2.2.0 and 2019-06-01/3.1.0. The 532 relationship between the revisions is as before: 534 Module revision date Revision label 535 2019-01-01 <- 1.0.0 536 | 537 2019-02-01 <- 2.0.0 538 | \ 539 2019-03-01 \ <- 3.0.0 540 | \ 541 | 2019-04-01 <- 2.1.0 542 | | 543 | 2019-05-01 <- 2.2.0 544 | 545 2019-06-01 <- 3.1.0 547 4.1.1. Example 1 549 This example selects module revisions that match, or are derived from 550 the revision 2019-02-01. E.g., this dependency might be used if 551 there was a new container added in revision 2019-02-01 that is 552 augmented by the importing module.It includes revisions/labels: 553 2019-02-01/2.0.0, 2019-03-01/3.0.0, 2019-04-01/2.1.0, 554 2019-05-01/2.2.0 and 2019-06-01/3.1.0. 556 import example-module { 557 rev:revision-or-derived 2019-02-01; 558 } 560 Alternatively, the first example could have used the revision label 561 "2.0.0" instead, which selects the same set of revisions/labels. 563 import example-module { 564 rev:revision-or-derived 2.0.0; 565 } 567 4.1.2. Example 2 569 This example selects module revisions that are derived from 570 2019-04-01 by using the revision label 2.1.0. It includes revisions/ 571 labels: 2019-04-01/2.1.0 and 2019-05-01/2.2.0. Even though 572 2019-06-01/3.1.0 has a higher revision label number than 573 2019-04-01/2.1.0 it is not a derived revision, and hence it is not a 574 valid revision for import. 576 import example-module { 577 rev:revision-or-derived 2.1.0; 578 } 580 4.1.3. Example 3 582 This example selects revisions derived from either 2019-04-01 or 583 2019-06-01. It includes revisions/labels: 2019-04-01/2.1.0, 584 2019-05-01/2.2.0, and 2019-06-01/3.1.0. 586 import example-module { 587 rev:revision-or-derived 2019-04-01; 588 rev:revision-or-derived 2019-06-01; 589 } 591 5. Updates to ietf-yang-library 593 This document updates YANG library [RFC7950] to clarify how ambiguous 594 module imports are resolved. It also defines the YANG module, ietf- 595 yang-library-revisions that augments YANG library [RFC8525] with new 596 revision-label related meta-data. 598 5.1. Resolving ambiguous module imports 600 A YANG datastore schema, defined in [RFC8525], can specify multiple 601 revisions of a YANG module in the schema using the "import-only" 602 list, with the requirement from [RFC7950] that only a single revision 603 of a YANG module may be implemented. 605 If a YANG module import statement does not specify a specific 606 revision within the datastore schema then it could be ambiguous as to 607 which module revision the import statement should resolve to. Hence, 608 a datastore schema constructed by a client using the information 609 contained in YANG library may not exactly match the datastore schema 610 actually used by the server. 612 The following two rules remove the ambiguity: 614 If a module import statement could resolve to more than one module 615 revision defined in the datastore schema, and one of those revisions 616 is implemented (i.e., not an "import-only" module), then the import 617 statement MUST resolve to the revision of the module that is defined 618 as being implemented by the datastore schema. 620 If a module import statement could resolve to more than one module 621 revision defined in the datastore schema, and none of those revisions 622 are implemented, then the import MUST resolve to the module revision 623 with the latest revision date. 625 5.2. YANG library versioning augmentations 627 The "ietf-yang-library-revisions" YANG module has the following 628 structure (using the notation defined in [RFC8340]): 630 module: ietf-yang-library-revisions 631 augment /yanglib:yang-library/yanglib:module-set/yanglib:module: 632 +--ro revision-label? rev:revision-label 633 augment /yanglib:yang-library/yanglib:schema: 634 +--ro deprecated-nodes-implemented? boolean 635 +--ro obsolete-nodes-absent? boolean 637 5.2.1. Advertising revision-label 639 The ietf-yang-library-revisions YANG module augments the "module" 640 list in ietf-yang-library with a "revision-label" leaf to optionally 641 declare the revision label associated wth the particular revision of 642 each module. 644 5.2.2. Reporting how deprecated and obsolete nodes are handled 646 The ietf-yang-library-revisions YANG module augments YANG library 647 with two leaves to allow a server to report how it handles status 648 "deprecated" and status "obsolete" nodes. The leaves are: 650 deprecated-nodes-implemented: If set to "true", this leaf indicates 651 that all schema nodes with a status "deprecated" child statement 652 are implemented equivalently as if they had status "current", or 653 otherwise deviations MUST be used to explicitly remove 654 "deprecated" nodes from the schema. If this leaf is set to 655 "false" or absent, then the behavior is unspecified. 657 obsolete-nodes-absent: If set to "true", this leaf indicates that 658 the server does not implement any status "obsolete" nodes. If 659 this leaf is set to "false" or absent, then the behaviour is 660 unspecified. 662 Servers SHOULD set both the "deprecated-nodes-implemented" and 663 "obsolete-nodes-absent" leaves to "true". 665 If a server does not set the "deprecated-nodes-implemented" leaf to 666 "true", then clients MUST NOT rely solely on the "rev:nbc-changes" 667 statements to determine whether two module revisions are backwards- 668 compatible, and MUST also consider whether the status of any nodes 669 has changed to "deprecated" and whether those nodes are implemented 670 by the server. 672 6. Versioning of YANG instance data 674 Instance data sets [I-D.ietf-netmod-yang-instance-file-format] do not 675 directly make use of the updated revision handling rules described in 676 this document, as compatibility for instance data is undefined. 678 However, instance data specifies the content-schema of the data-set. 679 This schema SHOULD make use of versioning using revision dates and/or 680 revision labels for the individual YANG modules that comprise the 681 schema or potentially for the entire schema itself (e.g., 682 [I-D.ietf-netmod-yang-packages] ). 684 In this way, the versioning of a content-schema associated with an 685 instance data set may help a client to determine whether the instance 686 data could also be used in conjunction with other revisions of the 687 YANG schema, or other revisions of the modules that define the 688 schema. 690 7. Guidelines for using the YANG module update rules 692 The following text updates section 4.7 of [RFC8407] to revise the 693 guidelines for updating YANG modules. 695 7.1. Guidelines for YANG module authors 697 All IETF YANG modules MUST include revision-label statements for all 698 newly published YANG modules, and all newly published revisions of 699 existing YANG modules. The revision-label MUST take the form of a 700 YANG semantic version number [I-D.ietf-netmod-yang-semver]. 702 NBC changes to YANG modules may cause problems to clients, who are 703 consumers of YANG models, and hence YANG module authors are 704 RECOMMENDED to minimize NBC changes and keep changes BC whenever 705 possible. 707 When NBC changes are introduced, consideration should be given to the 708 impact on clients and YANG module authors SHOULD try to mitigate that 709 impact. 711 A "rev:nbc-changes" statement MUST be added if there are NBC changes 712 relative to the previous revision. 714 Removing old revision statements from a module's revision history 715 could break import by revision, and hence it is RECOMMENDED to retain 716 them. If all depencencies have been updated to not import specific 717 revisions of a module, then the corresponding revision statements can 718 be removed from that module. An alternative solution, if the 719 revision section is too long, would be remove, or curtail, the older 720 description statements associated with the previous revisions. 722 The "rev:revision-or-derived" extension should be used in YANG module 723 imports to indicate revision dependencies between modules in 724 preference to the "revision-date" statement, which causes overly 725 strict import dependencies and SHOULD NOT be used. 727 A module that includes submodules SHOULD use the "revision-date" 728 statement to include specific submodule revisions. The revision of 729 the including module MUST be updated when any included submodule has 730 changed. The revision-label substatement used in the new module 731 revision MUST indicate the nature of the change, i.e. NBC or BC, to 732 the module's schema tree. 734 7.1.1. Making non-backwards-compatible changes to a YANG module 736 There are various valid situations where a YANG module has to be 737 modified in an NBC way. Here are the different ways in which this 738 can be done: 740 o NBC changes can be sometimes be done incrementally using the 741 "deprecated" status to provide clients time to adapt to NBC 742 changes. 744 o NBC changes are done at once, i.e. without using "status" 745 statements. Depending on the change, this may have a big impact 746 on clients. 748 o If the server can support multiple revisions of the YANG module or 749 of YANG packages(as specified in [I-D.ietf-netmod-yang-packages]), 750 and allows the client to select the revision (as per 751 [I-D.ietf-netmod-yang-ver-selection]), then NBC changes MAY be 752 done without using "status" statements. Clients would be required 753 to select the revision which they support and the NBC change would 754 have no impact on them 756 Here are some guidelines on how non-backwards-compatible changes can 757 be made incrementally, with the assumption that deprecated nodes are 758 implemented by the server, and obsolete nodes are not: 760 1. The changes should be made gradually, e.g. a data node's status 761 SHOULD NOT be changed directly from "current" to "obsolete" (see 762 Section 4.7 of [RFC8407]), instead the status SHOULD first be 763 marked "deprecated" and then when support is removed its status 764 MUST be changed to "obsolete". Instead of using the "obsolete" 765 status, the data node MAY be removed from the model but this has 766 the risk of breaking modules which import the modified module. 768 2. For deprecated data nodes the "description" statement SHOULD also 769 indicate until when support for the node is guaranteed (if 770 known). If there is a replacement data node, rpc, action or 771 notification for the deprecated node, this SHOULD be stated in 772 the "description". The reason for deprecating the node can also 773 be included in the "description" if it is deemed to be of 774 potential interest to the user. 776 3. For obsolete data nodes, it is RECOMMENDED to keep the above 777 information, from when the node had status "deprecated", which is 778 still relevant. 780 4. When obsoleting or deprecating data nodes, the "deprecated" or 781 "obsolete" status SHOULD be applied at the highest possible level 782 in the data tree. For clarity, the "status" statement SHOULD 783 also be applied to all descendent data nodes, but the additional 784 status related information does not need to be repeated if it 785 does not introduce any additional information. 787 See Appendix B for examples on how NBC changes can be made. 789 7.2. Versioning Considerations for Clients 791 Guidelines for clients of modules using the new module revision 792 update procedure: 794 o Clients SHOULD be liberal when processing data received from a 795 server. For example, the server may have increased the range of 796 an operational node causing the client to receive a value which is 797 outside the range of the YANG model revision it was coded against. 799 o Clients SHOULD monitor changes to published YANG modules through 800 their revision history, and use appropriate tooling to understand 801 the specific changes between module revision. In particular, 802 clients SHOULD NOT migrate to NBC revisions of a module without 803 understanding any potential impact of the specific NBC changes. 805 o Clients SHOULD plan to make changes to match published status 806 changes. When a node's status changes from "current" to 807 "deprecated", clients SHOULD plan to stop using that node in a 808 timely fashion. When a node's status changes to "obsolete", 809 clients MUST stop using that node. 811 8. Module Versioning Extension YANG Modules 813 YANG module with extension statements for annotating NBC changes, 814 revision label, revision label scheme, and importing by revision. 816 file "ietf-yang-revisions@2020-07-06.yang" 817 module ietf-yang-revisions { 818 yang-version 1.1; 819 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-revisions"; 820 prefix rev; 822 import ietf-yang-types { 823 prefix yang; 824 reference 825 "XXXX [ietf-netmod-rfc6991-bis]: Common YANG Data Types"; 826 } 828 organization 829 "IETF NETMOD (Network Modeling) Working Group"; 830 contact 831 "WG Web: 832 WG List: 834 Author: Benoit Claise 835 837 Author: Joe Clarke 838 840 Author: Reshad Rahman 841 843 Author: Robert Wilton 844 846 Author: Kevin D'Souza 847 849 Author: Balazs Lengyel 850 852 Author: Jason Sterne 853 "; 854 description 855 "This YANG 1.1 module contains definitions and extensions to 856 support updated YANG revision handling. 858 Copyright (c) 2019 IETF Trust and the persons identified as 859 authors of the code. All rights reserved. 861 Redistribution and use in source and binary forms, with or 862 without modification, is permitted pursuant to, and subject 863 to the license terms contained in, the Simplified BSD License 864 set forth in Section 4.c of the IETF Trust's Legal Provisions 865 Relating to IETF Documents 866 (http://trustee.ietf.org/license-info). 868 This version of this YANG module is part of RFC XXXX; see 869 the RFC itself for full legal notices. 871 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 872 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 873 'MAY', and 'OPTIONAL' in this document are to be interpreted as 874 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 875 they appear in all capitals, as shown here."; 877 // RFC Ed.: update the date below with the date of RFC publication 878 // and remove this note. 879 // RFC Ed.: replace XXXX (inc above) with actual RFC number and 880 // remove this note. 882 revision 2020-07-06 { 883 description 884 "Initial version."; 885 reference 886 "XXXX: Updated YANG Module Revision Handling"; 887 } 889 typedef revision-label { 890 type string { 891 length "1..255"; 892 pattern '[^\s@]+'; 893 pattern '\d{4}-\d{2}-\d{2}' { 894 modifier invert-match; 895 } 896 } 897 description 898 "A label associated with a YANG revision. 900 Excludes spaces and '@'. MUST NOT match revision-date."; 901 reference 902 "XXXX: Updated YANG Module Revision Handling; 903 Section 3.3, Revision label"; 904 } 906 typedef revision-date-or-label { 907 type union { 908 type yang:revision-identifier; 909 type revision-label; 910 } 911 description 912 "Represents either a YANG revision date or a revision label"; 913 } 915 extension nbc-changes { 916 description 917 "This statement is used to indicate YANG module revisions that 918 contain non-backwards-compatible changes. 920 The statement MUST only be a substatement of the 'revision' 921 statement. 922 Zero or one 'nbc-changes' statement per parent statement is 923 allowed. 924 The statement MUST NOT have any substatements. 926 If a revision of a YANG module contains changes, relative to 927 the preceding revision in the revision history, that do not 928 conform to the module update rules defined in RFC-XXX, then 929 the 'nbc-changes' statement MUST be added as a substatement to 930 the revision statement. 932 Conversely, if a revision of a YANG module only contains 933 changes, relative to the preceding revision in the revision 934 history, that are classified as 'backwards-compatible' then 935 the revision statement MUST NOT contain any 'nbc-changes' 936 substatement."; 938 reference 939 "XXXX: Updated YANG Module Revision Handling; 940 Section 3.2, nbc-changes revision extension statement"; 941 } 943 extension revision-label { 944 argument revision-label; 945 description 946 "The revision label can be used to provide an additional 947 versioning identifier associated with the revision. E.g., one 948 option for a versioning scheme that could be used is [TODO - 949 Reference semver draft]. 951 The format of the revision-label argument MUST conform to the 952 pattern defined for the revision-label typedef. 954 The statement MUST only be a substatement of the revision 955 statement. 956 Zero or one revision-label statement per parent statement 957 is allowed. 958 The statement MUST NOT have any substatements. 960 Revision labels MUST be unique amongst all revisions of a 961 module."; 963 reference 964 "XXXX: Updated YANG Module Revision Handling; 965 Section 3.3, Revision label"; 966 } 968 extension revision-label-scheme { 969 argument revision-label-scheme-identity; 970 description 971 "The revision label scheme specifies which revision-label scheme 972 the module or submodule uses. 974 The mandatory revision-label-scheme-identity argument MUST be an 975 identity derived from revision-label-scheme-base. 977 This extension is only valid as a top-level statement, i.e., 978 given as as a substatement to 'module' or 'submodule'. 980 This extension MUST be used if there is a revision-label 981 statement in the module or submodule. 983 The statement MUST NOT have any substatements."; 985 reference 986 "XXXX: Updated YANG Module Revision Handling; 987 Section 3.3.1, Revision label scheme extension statement"; 988 } 990 extension revision-or-derived { 991 argument revision-date-or-label; 992 description 993 "Restricts the revision of the module that may be imported to 994 one that matches or is derived from the specified 995 revision-date or revision-label. 997 The argument value MUST conform to the 998 'revision-date-or-label' defined type. 1000 The statement MUST only be a substatement of the import 1001 statement. 1002 Zero, one or more 'revision-or-derived' statement per parent 1003 statement is allowed. 1004 The statement MUST NOT have any substatements. 1006 If specified multiple 1007 times, then any module revision that satisfies at least one of 1008 the 'revision-or-derived' statements is an acceptable revision 1009 for import. 1011 An 'import' statement MUST NOT contain both a 1012 'revision-or-derived' extension statement and a 1013 'revision-date' statement. 1015 A particular revision of an imported module satisfies an 1016 import's 'revision-or-derived' extension statement if the 1017 imported module's revision history contains a revision 1018 statement with a matching revision date or revision label. 1020 The 'revision-or-derived' extension statement does not 1021 guarantee that all module revisions that satisfy an import 1022 statement are necessarily compatible, it only gives an 1023 indication that the revisions are more likely to be 1024 compatible."; 1026 reference 1027 "XXXX: Updated YANG Module Revision Handling; 1028 Section 4, Import by derived revision"; 1029 } 1031 identity revision-label-scheme-base { 1032 description 1033 "Base identity from which all revision label schemes are 1034 derived."; 1036 reference 1037 "XXXX: Updated YANG Module Revision Handling; 1038 Section 3.3.1, Revision label scheme extension statement"; 1040 } 1041 } 1042 1044 YANG module with augmentations to YANG Library to revision labels 1046 file "ietf-yang-library-revisions@2020-07-06.yang" 1047 module ietf-yang-library-revisions { 1048 yang-version 1.1; 1049 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-library-revisions"; 1050 prefix yl-rev; 1052 import ietf-yang-revisions { 1053 prefix rev; 1054 reference 1055 "XXXX: Updated YANG Module Revision Handling"; 1057 } 1059 import ietf-yang-library { 1060 prefix yanglib; 1061 reference "RFC 8525: YANG Library"; 1062 } 1064 organization 1065 "IETF NETMOD (Network Modeling) Working Group"; 1066 contact 1067 "WG Web: 1068 WG List: 1070 Author: Benoit Claise 1071 1073 Author: Joe Clarke 1074 1076 Author: Reshad Rahman 1077 1079 Author: Robert Wilton 1080 1082 Author: Kevin D'Souza 1083 1085 Author: Balazs Lengyel 1086 1088 Author: Jason Sterne 1089 "; 1090 description 1091 "This module contains augmentations to YANG Library to add module 1092 level revision label and to provide an indication of how 1093 deprecated and obsolete nodes are handled by the server. 1095 Copyright (c) 2019 IETF Trust and the persons identified as 1096 authors of the code. All rights reserved. 1098 Redistribution and use in source and binary forms, with or 1099 without modification, is permitted pursuant to, and subject 1100 to the license terms contained in, the Simplified BSD License 1101 set forth in Section 4.c of the IETF Trust's Legal Provisions 1102 Relating to IETF Documents 1103 (http://trustee.ietf.org/license-info). 1104 This version of this YANG module is part of RFC XXXX; see 1105 the RFC itself for full legal notices. 1107 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1108 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1109 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1110 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1111 they appear in all capitals, as shown here."; 1113 // RFC Ed.: update the date below with the date of RFC publication 1114 // and remove this note. 1115 // RFC Ed.: replace XXXX (including in the imports above) with 1116 // actual RFC number and remove this note. 1117 // RFC Ed.: please replace revision-label version with 1.0.0 and 1118 // remove this note. 1119 revision 2020-07-06 { 1120 rev:revision-label 0.1.0; 1121 description 1122 "Initial revision"; 1123 reference 1124 "XXXX: Updated YANG Module Revision Handling"; 1125 } 1127 augment "/yanglib:yang-library/yanglib:module-set/yanglib:module" { 1128 description 1129 "Augmentation modules with a revision label"; 1130 leaf revision-label { 1131 type rev:revision-label; 1132 description 1133 "The revision label associated with this module revision. 1134 The label MUST match the rev:label value in the specific 1135 revision of the module loaded in this module-set."; 1137 reference 1138 "XXXX: Updated YANG Module Revision Handling; 1139 Section 5.2.1, Advertising revision-label"; 1140 } 1141 } 1143 augment "/yanglib:yang-library/yanglib:schema" { 1144 description 1145 "Augmentations to the ietf-yang-library module to indicate how 1146 deprecated and obsoleted nodes are handled for each datastore 1147 schema supported by the server."; 1149 leaf deprecated-nodes-implemented { 1150 type boolean; 1151 description 1152 "If set to true, this leaf indicates that all schema nodes with 1153 a status 'deprecated' child statement are implemented 1154 equivalently as if they had status 'current', or otherwise 1155 deviations MUST be used to explicitly remove 'deprecated' 1156 nodes from the schema. If this leaf is set to false or absent, 1157 then the behavior is unspecified."; 1159 reference 1160 "XXXX: Updated YANG Module Revision Handling; 1161 Section 5.2.2, Reporting how deprecated and obsolete nodes 1162 are handled"; 1163 } 1165 leaf obsolete-nodes-absent { 1166 type boolean; 1167 description 1168 "If set to true, this leaf indicates that the server does not 1169 implement any status 'obsolete' nodes. If this leaf is 1170 set to false or absent, then the behaviour is unspecified."; 1172 reference 1173 "XXXX: Updated YANG Module Revision Handling; 1174 Section 5.2.2, Reporting how deprecated and obsolete nodes 1175 are handled"; 1176 } 1177 } 1178 } 1179 1181 9. Contributors 1183 This document grew out of the YANG module versioning design team that 1184 started after IETF 101. The following individuals are (or have been) 1185 members of the design team and have worked on the YANG versioning 1186 project: 1188 o Balazs Lengyel 1190 o Benoit Claise 1192 o Ebben Aries 1194 o Jason Sterne 1196 o Joe Clarke 1198 o Juergen Schoenwaelder 1199 o Mahesh Jethanandani 1201 o Michael (Wangzitao) 1203 o Qin Wu 1205 o Reshad Rahman 1207 o Rob Wilton 1209 o Bo Wu 1211 The initial revision of this document was refactored and built upon 1212 [I-D.clacla-netmod-yang-model-update]. 1214 Discussons on the use of Semver for YANG versioning has been held 1215 with authors of the OpenConfig YANG models. We would like thank both 1216 Anees Shaikh and Rob Shakir for their input into this problem space. 1218 We would also like to thank Martin Bjorklund, Jan Lindblad and Italo 1219 Busi for their contributions. 1221 10. Security Considerations 1223 The document does not define any new protocol or data model. There 1224 are no security considerations beyond those specified in [RFC7950]. 1226 11. IANA Considerations 1228 11.1. YANG Module Registrations 1230 The following YANG module is requested to be registred in the "IANA 1231 Module Names" registry: 1233 The ietf-yang-revisions module: 1235 Name: ietf-yang-revisions 1237 XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-revisions 1239 Prefix: rev 1241 Reference: [RFCXXXX] 1243 The ietf-yang-library-revisions module: 1245 Name: ietf-yang-library-revisions 1246 XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-library- 1247 revisions 1249 Prefix: yl-rev 1251 Reference: [RFCXXXX] 1253 11.2. Instructions 1255 We may need to give new instructions to IANA e.g. how to review 1256 revision-label statements to make sure they are accurate? TBD 1258 12. References 1260 12.1. Normative References 1262 [I-D.ietf-netmod-rfc6991-bis] 1263 Schoenwaelder, J., "Common YANG Data Types", draft-ietf- 1264 netmod-rfc6991-bis-04 (work in progress), July 2020. 1266 [I-D.ietf-netmod-yang-semver] 1267 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, 1268 B., Sterne, J., and K. D'Souza, "YANG Semantic 1269 Versioning", draft-ietf-netmod-yang-semver-00 (work in 1270 progress), March 2020. 1272 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1273 Requirement Levels", BCP 14, RFC 2119, 1274 DOI 10.17487/RFC2119, March 1997, 1275 . 1277 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 1278 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 1279 . 1281 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1282 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1283 . 1285 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1286 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1287 May 2017, . 1289 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 1290 Documents Containing YANG Data Models", BCP 216, RFC 8407, 1291 DOI 10.17487/RFC8407, October 2018, 1292 . 1294 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 1295 and R. Wilton, "YANG Library", RFC 8525, 1296 DOI 10.17487/RFC8525, March 2019, 1297 . 1299 12.2. Informative References 1301 [I-D.clacla-netmod-yang-model-update] 1302 Claise, B., Clarke, J., Lengyel, B., and K. D'Souza, "New 1303 YANG Module Update Procedure", draft-clacla-netmod-yang- 1304 model-update-06 (work in progress), July 2018. 1306 [I-D.ietf-netmod-yang-instance-file-format] 1307 Lengyel, B. and B. Claise, "YANG Instance Data File 1308 Format", draft-ietf-netmod-yang-instance-file-format-12 1309 (work in progress), April 2020. 1311 [I-D.ietf-netmod-yang-packages] 1312 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and W. Bo, 1313 "YANG Packages", draft-ietf-netmod-yang-packages-00 (work 1314 in progress), March 2020. 1316 [I-D.ietf-netmod-yang-solutions] 1317 Wilton, R., "YANG Versioning Solution Overview", draft- 1318 ietf-netmod-yang-solutions-00 (work in progress), March 1319 2020. 1321 [I-D.ietf-netmod-yang-ver-selection] 1322 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and W. Bo, 1323 "YANG Schema Selection", draft-ietf-netmod-yang-ver- 1324 selection-00 (work in progress), March 2020. 1326 [I-D.ietf-netmod-yang-versioning-reqs] 1327 Clarke, J., "YANG Module Versioning Requirements", draft- 1328 ietf-netmod-yang-versioning-reqs-03 (work in progress), 1329 June 2020. 1331 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1332 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1333 . 1335 [semver] "Semantic Versioning 2.0.0", . 1337 Appendix A. Examples of changes that are NBC 1339 Examples of NBC changes include: 1341 o Deleting a data node, or changing it to status obsolete. 1343 o Changing the name, type, or units of a data node. 1345 o Modifying the description in a way that changes the semantic 1346 meaning of the data node. 1348 o Any changes that change or reduce the allowed value set of the 1349 data node, either through changes in the type definition, or the 1350 addition or changes to "must" statements, or changes in the 1351 description. 1353 o Adding or modifying "when" statements that reduce when the data 1354 node is available in the schema. 1356 o Making the statement conditional on if-feature. 1358 Appendix B. Examples of applying the NBC change guidelines 1360 The following sections give guidance for how some of these NBC 1361 changes could be made to a YANG module. The examples are all for 1362 "config true" nodes. 1364 B.1. Removing a data node 1366 Removing a leaf or container from the data tree, e.g. because support 1367 for the corresponding feature is being removed: 1369 1. The node's status is changed to "deprecated" and it is supported 1370 for at least one year. This is a BC change. 1372 2. When the node is not available anymore, its status is changed to 1373 "obsolete" and the "description" updated, this is an NBC change. 1375 If the server can support NBC revisions of the YANG module 1376 simultaneously using version selection 1377 [I-D.ietf-netmod-yang-ver-selection], then the changes can be done 1378 immediately: 1380 1. The new revision of the YANG module has the node's status changed 1381 to "obsolete" and the "description" updated, this is an NBC 1382 change. 1384 2. Clients which require the data node select the YANG package 1385 containing the schema version they use 1387 B.2. Changing the type of a leaf node 1389 Changing the type of a leaf-node. e.g. consider a "vpn-id" node of 1390 type integer being changed to a string: 1392 1. The status of node "vpn-id" is changed to "deprecated" and the 1393 node should be available for at least one year. This is a BC 1394 change. 1396 2. A new node, e.g. "vpn-name", of type string is added to the same 1397 location as the existing node "vpn-id". This new node has status 1398 "current" and its description explains that it is replacing node 1399 "vpn-id". 1401 3. During the period of time where both nodes are available, how the 1402 server behaves when either node is set is outside the scope of 1403 this document and will vary on a case by case basis. Here are 1404 some options: 1406 1. A server may prevent the new node from being set if the old 1407 node is already set (and vice-versa). The new node may have 1408 a when statement to achieve this. The old node must not have 1409 a when statement since this would be an NBC change, but the 1410 server could reject the old node from being set if the new 1411 node is already set. 1413 2. If the new node is set and a client does a get or get-config 1414 operation on the old node, the server could map the value. 1415 For example, if the new node "vpn-name" has value "123" then 1416 the server could return integer value 123 for the old node 1417 "vpn-id". However, if the value can not be mapped then the 1418 configuration would be incomplete, this is outside the scope 1419 of this document. 1421 4. When node "vpn-id" is not available anymore, its status is 1422 changed to "obsolete" and the "description" is updated. This is 1423 an NBC change. 1425 If the server can support NBC revisions of the YANG module 1426 simultaneously using version selection 1427 [I-D.ietf-netmod-yang-ver-selection], then the changes can be done 1428 immediately: 1430 1. In the new revision of the YANG module, the status of node "vpn- 1431 id" is changed to "obsolete". This is an NBC change. 1433 2. New node "vpn-name" is added to the same location as described 1434 above. 1436 3. Clients which require the data node select the YANG package 1437 containing the schema version they use 1439 4. A server should not map between the nodes "vpn-id" and "vpn- 1440 name", i.e. if a client creates a data instance with "vpn-name" 1441 then that data instance should not be visible to a client using a 1442 module revision which has "vpn-id" (and vice-versa). 1444 B.3. Reducing the range of a leaf node 1446 Reducing the range of values of a leaf-node. e.g. consider a "vpn-id" 1447 node of type integer being changed from type uint32 to type uint16: 1449 1. If all values which are being removed were never supported, e.g. 1450 if a vpn-id of 65536 or higher was never accepted, this is a BC 1451 change for the functionality (no functionality change). Even if 1452 it is an NBC change for the YANG model, there should be no impact 1453 for clients using that YANG model. 1455 2. If one or more values being removed was previously supported, 1456 e.g. if a vpn-id of 65536 was accepted previously, this is an NBC 1457 change for the YANG model. Clients using the old YANG model will 1458 be impacted, so a change of this nature should be done carefully, 1459 e.g. by using the steps described in Appendix B.2 1461 B.4. Changing the key of a list 1463 Changing the key of a list has a big impact to the client. For 1464 example, consider a "sessions" list which has a key "interface" and 1465 there is a need to change the key to "dest-address", such a change 1466 can be done in steps: 1468 1. The status of list "sessions" is changed to "deprecated" and the 1469 list should be available for at least one year. This is a BC 1470 change. 1472 2. A new list is created in the same location with the same data but 1473 with "dest-address" as key. Finding an appropriate name for the 1474 new list can be tricky especially if the name of the existing 1475 list was perfect. In this case the new list is called "sessions- 1476 address", has status "current" and its description should explain 1477 that it is replacing list "session". 1479 3. During the period of time where both lists are available, how the 1480 server behaves when either list is set is outside the scope of 1481 this document and will vary on a case by case basis. Here are 1482 some options: 1484 1. A server could prevent the new list from being set if the old 1485 list already has entries (and vice-versa). 1487 2. If the new list is set and a client does a get or get-config 1488 operation on the old list, the server could map the entries. 1489 However if the new list has entries which would lead to 1490 duplicate keys in the old list, the mapping can not be done. 1492 4. When list "sessions" is not available anymore, its status is 1493 changed to "obsolete" and the "description" is updated. This is 1494 an NBC change. 1496 If the server can support NBC revisions of the YANG module 1497 simultaneously using version selection 1498 [I-D.ietf-netmod-yang-ver-selection], then the changes can be done 1499 immediately: 1501 1. The new revision of the YANG module has the list "sessions" 1502 modified to have "dest-address" as key, this is an NBC change. 1504 2. Clients which require the previous functionality select the older 1505 module revision 1507 B.5. Renaming a node 1509 A leaf-node or a container may be renamed, either due to a spelling 1510 error in the previous name or because of a better name. For example 1511 a node "ip-adress" could be renamed to "ip-address": 1513 1. The status of the existing node "ip-adress" is changed to 1514 "deprecated" and the node should be available for at least one 1515 year. This is a BC change. 1517 2. The new node "ip-address" is added to the same location as the 1518 existing node "ip-adress". This new node has status "current" 1519 and its description should explain that it is replacing node "ip- 1520 adress". 1522 3. During the period of time where both nodes are available, how the 1523 server behaves when either node is set is outside the scope of 1524 this document and will vary on a case by case basis. Here are 1525 some options: 1527 1. A server could prevent the new node from being set if the old 1528 node is already set (and vice-versa). The new node could 1529 have a when statement to achieve this. The old node must not 1530 have a when statement since this would be an NBC change, but 1531 the server could reject the old node from being set if the 1532 new node is already set. 1534 2. If the new node is set and a client does a get or get-config 1535 operation on the old node, the server could use the value of 1536 the new node. For example, if the new node "ip-address" has 1537 value X then the server may return value X for the old node 1538 "ip-adress". 1540 4. When node "ip-adress" is not available anymore, its status is 1541 changed to "obsolete" and the "description" is updated. This is 1542 an NBC change. 1544 If the server can support NBC revisions of the YANG module 1545 simultaneously using version selection 1546 [I-D.ietf-netmod-yang-ver-selection], then the changes can be done 1547 immediately: 1549 1. The new revision of the YANG module has the node with the new 1550 name replacing the node with the old name, this is an NBC change. 1552 2. Clients which require the previous node name select the older 1553 module revision 1555 B.6. Changing a default value 1557 Appendix C. Changes between revisions 1559 Note to RFC Editor (To be removed by RFC Editor) 1561 v00 - v01 1563 o Removed status-description 1565 o Allowed both revision-date and revision-label in the filename. 1567 o New extension revision-label-scheme 1569 o To include submodules, inclusion by revision-date changed from 1570 MUST to SHOULD 1572 o Submodules can use revision label scheme and it can be same or 1573 different as the including module's scheme 1575 o Addressed various comments provided at WG adoption on rev-00 1577 Authors' Addresses 1578 Robert Wilton (editor) 1579 Cisco Systems, Inc. 1581 Email: rwilton@cisco.com 1583 Reshad Rahman (editor) 1584 Cisco Systems, Inc. 1586 Email: rrahman@cisco.com 1588 Balazs Lengyel (editor) 1589 Ericsson 1591 Email: balazs.lengyel@ericsson.com 1593 Joe Clarke 1594 Cisco Systems, Inc. 1596 Email: jclarke@cisco.com 1598 Jason Sterne 1599 Nokia 1601 Email: jason.sterne@nokia.com 1603 Benoit Claise 1604 Cisco Systems, Inc. 1606 Email: bclaise@cisco.com 1608 Kevin D'Souza 1609 AT&T 1611 Email: kd6913@att.com