idnits 2.17.1 draft-ietf-netmod-yang-module-versioning-00.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 (March 17, 2020) is 1473 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 1169, but not defined == Unused Reference: 'I-D.ietf-netmod-rfc6991-bis' is defined on line 1175, but no explicit reference was found in the text == Outdated reference: A later version (-15) exists of draft-ietf-netmod-rfc6991-bis-02 ** Downref: Normative reference to an Informational draft: draft-verdt-netmod-yang-versioning-reqs (ref. 'I-D.verdt-netmod-yang-versioning-reqs') ** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525) == Outdated reference: A later version (-21) exists of draft-ietf-netmod-yang-instance-file-format-08 Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Claise 3 Internet-Draft J. Clarke 4 Updates: 7950,8407,8525 (if approved) R. Rahman 5 Intended status: Standards Track R. Wilton, Ed. 6 Expires: September 18, 2020 Cisco Systems, Inc. 7 B. Lengyel 8 Ericsson 9 J. Sterne 10 Nokia 11 K. D'Souza 12 AT&T 13 March 17, 2020 15 Updated YANG Module Revision Handling 16 draft-ietf-netmod-yang-module-versioning-00 18 Abstract 20 This document specifies a new YANG module update procedure that can 21 document when non-backwards-compatible changes have occurred during 22 the evolution of a YANG module. It extends the YANG import statement 23 with an earliest revision filter to better represent inter-module 24 dependencies. It provides help and guidelines for managing the 25 lifecycle of YANG modules and individual schema nodes. This document 26 updates RFC 7950, RFC 8407 and RFC 8525. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on September 18, 2020. 45 Copyright Notice 47 Copyright (c) 2020 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (https://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 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 . . . . . . . 5 67 3.1.1. Backwards-compatible changes . . . . . . . . . . . . 5 68 3.1.2. Non-backwards-compatible changes . . . . . . . . . . 6 69 3.2. nbc-changes revision extension statement . . . . . . . . 6 70 3.3. Revision label . . . . . . . . . . . . . . . . . . . . . 6 71 3.4. YANG status description extension statement . . . . . . . 7 72 3.5. Examples for updating the YANG module revision history . 7 73 4. Import by derived revision . . . . . . . . . . . . . . . . . 10 74 4.1. Module import examples . . . . . . . . . . . . . . . . . 11 75 5. Updates to ietf-yang-library . . . . . . . . . . . . . . . . 13 76 5.1. Resolving ambiguous module imports . . . . . . . . . . . 13 77 5.2. YANG library versioning augmentations . . . . . . . . . . 14 78 5.2.1. Advertising revision-label . . . . . . . . . . . . . 14 79 5.2.2. Reporting how deprecated and obsolete nodes are 80 handled . . . . . . . . . . . . . . . . . . . . . . . 14 81 6. Versioning of YANG instance data . . . . . . . . . . . . . . 15 82 7. Guidelines for using the YANG module update rules . . . . . . 15 83 7.1. Guidelines for YANG module authors . . . . . . . . . . . 15 84 7.1.1. Making non-backwards-compatible changes to a YANG 85 module . . . . . . . . . . . . . . . . . . . . . . . 16 86 7.2. Versioning Considerations for Clients . . . . . . . . . . 17 87 8. Module Versioning Extension YANG Modules . . . . . . . . . . 18 88 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 25 89 10. Security Considerations . . . . . . . . . . . . . . . . . . . 26 90 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 91 11.1. YANG Module Registrations . . . . . . . . . . . . . . . 26 92 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 93 12.1. Normative References . . . . . . . . . . . . . . . . . . 26 94 12.2. Informative References . . . . . . . . . . . . . . . . . 27 95 Appendix A. Appendix . . . . . . . . . . . . . . . . . . . . . . 28 96 A.1. Examples of guidelines for making NBC changes to a YANG 97 module . . . . . . . . . . . . . . . . . . . . . . . . . 28 98 A.1.1. Removing a data node . . . . . . . . . . . . . . . . 28 99 A.1.2. Changing the type of a leaf node . . . . . . . . . . 29 100 A.1.3. Reducing the range of a leaf node . . . . . . . . . . 30 101 A.1.4. Changing the key of a list . . . . . . . . . . . . . 30 102 A.1.5. Renaming a node . . . . . . . . . . . . . . . . . . . 31 103 A.1.6. Changing a default value . . . . . . . . . . . . . . 32 104 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 32 106 1. Introduction 108 This document defines a solution to the YANG module lifecycle 109 problems described in [I-D.verdt-netmod-yang-versioning-reqs]. 110 Complementary documents provide a complete solution to the YANG 111 versioning requirements, with the overall relationship of the 112 solution drafts described in [I-D.verdt-netmod-yang-solutions]. 114 Specifically, this document recognises a need (within standards 115 organizations, vendors, and the industry) to sometimes allow YANG 116 modules to evolve with non-backwards-compatible changes, which could 117 cause breakage to clients and importing YANG modules. Accepting that 118 non-backwards-compatible changes do sometimes occur, it is important 119 to have mechanisms to report where these changes occur, and to manage 120 their effect on clients and the broader YANG ecosystem. 122 The solution comprises five parts: 124 Refinements to the YANG 1.1 module revision update procedure, 125 supported by new extension statements to indicate when a revision 126 contains non-backwards-compatible changes, and an optional 127 revision label. 129 A YANG extension statement allowing YANG module imports to specify 130 an earliest module revision that may satisfy the import 131 dependency. 133 Updates and augmentations to ietf-yang-library to include the 134 revision label in the module descriptions, to report how 135 "deprecated" and "obsolete" nodes are handled by a server, and to 136 clarify how module imports are resolved when multiple versions 137 could otherwise be chosen. 139 Considerations of how versioning applies to YANG instance data. 141 Guidelines for how the YANG module update rules defined in this 142 document should be used, along with examples. 144 Open issues are tracked at . 147 1.1. Updates to YANG RFCs 149 This document updates [RFC7950] section 11. Section 3 describes 150 modifications to YANG revision handling and update rules, and 151 Section 4 describes a YANG extension statement to do import by 152 derived revision. 154 This document updates [RFC8525] section 3. Section 5 defines how a 155 client of a YANG library datastore schema chooses which revision of 156 an import-only module is used to resolve a module import when the 157 definition is otherwise ambiguous. 159 This document updates [RFC8407] section 4.7. Section 7 provides 160 guidelines on managing the lifecycle of YANG modules that may contain 161 non-backwards-compatible changes and a branched revision history. 163 2. Terminology and Conventions 165 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 166 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 167 "OPTIONAL" in this document are to be interpreted as described in BCP 168 14 [RFC2119] [RFC8174] when, and only when, they appear in all 169 capitals, as shown here. 171 In addition, this document uses the terminology: 173 o YANG module revision: An instance of a YANG module, uniquely 174 identified with a revision date, with no implied ordering or 175 backwards compatibility between different revisions of the same 176 module. 178 o Backwards-compatible (BC) change: A backwards-compatible change 179 between two YANG module revisions, as defined in Section 3.1.1 181 o Non-backwards-compatible (NBC) change: A non-backwards-compatible 182 change between two YANG module revisions, as defined in 183 Section 3.1.2 185 3. Refinements to YANG revision handling 187 [RFC7950] assumes, but does not explicitly state, that the revision 188 history for a YANG module is strictly linear, i.e., it is prohibited 189 to have two independent revisions of a YANG module that are both 190 directly derived from the same parent revision. 192 This document clarifies [RFC7950] to explicitly allow non linear 193 development of YANG module revisions, so modules MAY have multiple 194 revisions that directly derive from the same parent revision. As per 195 [RFC7950], YANG module revisions continue to be uniquely identified 196 by the module's revision date, and hence all revisions of a module 197 MUST have unique revision dates. 199 A module's name and revision date identifies a specific immutable 200 definition of that module within its revision history. Hence, if a 201 module includes submodules then the module's "include" statements 202 MUST use "revision-date" substatements to specify the exact revision 203 date of each included submodule. 205 [RFC7950] section 11 requires that all updates to a YANG module are 206 BC to the previous revision of the module. This document allows for 207 more flexible evolution of YANG modules: NBC changes between module 208 revisions are allowed and are documented using a new "nbc-changes" 209 YANG extension statement in the module revision history. 211 3.1. Updating a YANG module with a new revision 213 This section updates [RFC7950] section 11 to refine the rules for 214 permissible changes when a new YANG module revision is created. 216 Where pragmatic, updates to YANG modules SHOULD be backwards- 217 compatible, following the definition in Section 3.1.1. 219 A new module revision MAY contain NBC changes, i.e., the semantics of 220 an existing definition MAY be changed in an NBC way without requiring 221 a new definition with a new identifier. A new module revision with 222 NBC changes MUST include the "rev:nbc-changes" extension substatement 223 to signal the potential for incompatibility to existing module users 224 and readers. 226 3.1.1. Backwards-compatible changes 228 A change between two module revisions is defined as being "backwards- 229 compatible" if the change conforms to the module update rules 230 specified in [RFC7950] section 11, updated by the following rules: 232 o A "status" "deprecated" statement MAY be added, or changed from 233 "current" to "deprecated", but adding or changing "status" to 234 "obsolete" is not a backwards-compatible change. 236 o Obsolete definitions MAY be removed from published modules, and 237 are classified as backwards-compatible changes. In some 238 circumstances it may be helpful to retain the obsolete definitions 239 to ensure that their identifiers are not reused with a different 240 meaning. 242 o In statements that have any data definition statements as 243 substatements, those data definition substatements MAY be 244 reordered, as long as they do not change the ordering or any "rpc" 245 "input" substatements. If new data definition statements are 246 added, they can be added anywhere in the sequence of existing 247 substatements. 249 3.1.2. Non-backwards-compatible changes 251 Any changes to YANG modules that are not defined by Section 3.1.1 as 252 being backwards-compatible are classified as "non-backwards- 253 compatible" changes. 255 3.2. nbc-changes revision extension statement 257 The "rev:nbc-changes" extension statement is used to indicate YANG 258 module revisions that contain NBC changes. 260 If a revision of a YANG module contains changes, relative to the 261 preceding revision in the revision history, that do not conform to 262 the module update rules defined in Section 3.1.1, then a "rev:nbc- 263 changes" extension statement MUST be added as a substatement to the 264 "revision" statement. 266 Conversely, if a revision does not contain an "rev:nbc-changes" 267 extension substatement then all changes, relative to the preceding 268 revision in the revision history, MUST be backwards-compatible. 270 3.3. Revision label 272 Each revision entry in a module or submodule MAY have a revision 273 label associated with it, providing an alternative alias to identify 274 a particular revision of a module or submodule. The revision label 275 could be used to provide an additional versioning identifier 276 associated with the revision. 278 YANG Semver [I-D.verdt-netmod-yang-semver] defines a versioning 279 scheme based on Semver 2.0.0 [semver] that can be used as a revision 280 label. All revision labels that match the pattern for the "version" 281 typedef in the ietf-yang-semver YANG module MUST be interpreted as 282 YANG semantic version numbers. 284 The revision date and revision label within a submodule's revision 285 history have no effect on the including module's revision. 286 Submodules MUST NOT use revision label schemes that could be confused 287 with the including module's revision label scheme. 289 If a revision has an associated revision label, then it may be used 290 instead of the revision date in two places: 292 In an "rev:revision-or-derived" extension statement argument. 294 In the filename of a YANG module, where it takes the form: module- 295 or-submodule-name ['@' revision-label] ( '.yang' / '.yin' ) 297 3.4. YANG status description extension statement 299 The ietf-yang-revision module specifies the YANG extension statement 300 "status-description" that can be used as a substatement of the status 301 statement. The argument to this extension statement can contain 302 freeform text to help readers of the module understand why the node 303 was deprecated or made obsolete, when it is anticipated that the node 304 will no longer be available for use, and potentially reference other 305 schema elements that can be used instead. An example is shown below. 307 leaf imperial-temperature { 308 type int64; 309 units "degrees Fahrenheit"; 310 status deprecated { 311 rev:status-description 312 "Imperial measurements are being phased out in favor 313 of their metric equivalents. Use metric-temperature 314 instead."; 315 } 316 description 317 "Temperature in degrees Fahrenheit."; 318 } 320 3.5. Examples for updating the YANG module revision history 322 The following diagram, explanation, and module history illustrates 323 how the branched revision history, "nbc-changes" extension statement, 324 and "revision-label" extension statement could be used: 326 Example YANG module with branched revision history. 328 Module revision date Revision label 329 2019-01-01 <- 1.0.0 330 | 331 2019-02-01 <- 2.0.0 332 | \ 333 2019-03-01 \ <- 3.0.0 334 | \ 335 | 2019-04-01 <- 2.1.0 336 | | 337 | 2019-05-01 <- 2.2.0 338 | 339 2019-06-01 <- 3.1.0 341 The tree diagram above illustrates how an example module's version 342 history might evolve, over time. For example, the tree might 343 represent the following changes, listed in chronological order from 344 oldest revision to newest: 346 Example module, revision 2019-06-01: 348 module example-module { 350 namespace "name-space"; 351 prefix "prefix-name"; 353 import ietf-yang-revisions { prefix "rev"; } 355 description 356 "to be completed"; 358 revision 2019-06-01 { 359 rev:revision-label 3.1.0; 360 description "Add new functionality."; 361 } 363 revision 2019-04-01 { 364 rev:revision-label 3.0.0; 365 rev:nbc-changes; 366 description 367 "Add new functionality. Remove some deprecated nodes."; 368 } 370 revision 2019-02-01 { 371 rev:revision-label 2.0.0; 372 rev:nbc-changes; 373 description "Apply bugfix to pattern statement"; 374 } 376 revision 2019-01-01 { 377 rev:revision-label 1.0.0; 378 description "Initial revision"; 379 } 381 //YANG module definition starts here 383 Example module, revision 2019-05-01: 385 module example-module { 387 namespace "name-space"; 388 prefix "prefix-name"; 390 import ietf-yang-revisions { prefix "rev"; } 392 description 393 "to be completed"; 395 revision 2019-05-01 { 396 rev:revision-label 2.2.0; 397 description "Backwards-compatible bugfix to enhancement."; 398 } 400 revision 2019-03-01 { 401 rev:revision-label 2.1.0; 402 description "Apply enhancement to older release train."; 403 } 405 revision 2019-02-01 { 406 rev:revision-label 2.0.0; 407 rev:nbc-changes; 408 description "Apply bugfix to pattern statement"; 409 } 411 revision 2019-01-01 { 412 rev:revision-label 1.0.0; 413 description "Initial revision"; 414 } 416 //YANG module definition starts here 418 4. Import by derived revision 420 RFC 7950 allows YANG module "import" statements to optionally require 421 the imported module to have a particular revision date. In practice, 422 importing a module with an exact revision date is often too 423 restrictive because it requires the importing module to be updated 424 whenever any change to the imported module occurs. The alternative 425 choice of using an import statement without any revision date 426 statement is also not ideal because the importing module may not work 427 with all possible revisions of the imported module. 429 Instead, it is desirable for a importing module to specify a "minimum 430 required revision" of a module that it is compatible with, based on 431 the assumption that later revisions derived from that "minimum 432 required revision" are also likely to be compatible. Many possible 433 changes to a YANG module do not break importing modules, even if the 434 changes themselves are not strictly backwards-compatible. E.g., 435 fixing an incorrect pattern statement or description for a leaf would 436 not break an import, changing the name of a leaf could break an 437 import but frequently would not, but removing a container would break 438 imports if that container is augmented by another module. 440 The ietf-revisions module defines the "revision-or-derived" extension 441 statement, a substatement to the YANG "import" statement, to allow 442 for a "minium required revision" to be specified during import: 444 The argument to the "revision-or-derived" extension statement is a 445 revision date or a revision label. 447 A particular revision of an imported module satisfies an import's 448 "revision-or-derived" extension statement if the imported module's 449 revision history contains a revision statement with a matching 450 revision date or revision label. 452 An "import" statement MUST NOT contain both a "revision-or- 453 derived" extension statement and a "revision-date" statement. 455 The "revision-or-derived" extension statement MAY be specified 456 multiple times, allowing the import to use any module revision 457 that satifies at least one of the "revision-or-derived" extension 458 statements. 460 The "revision-or-derived" extension statement does not gaurantee 461 that all module revisions that satisfy an import statement are 462 necessarily compatible, it only gives an indication that the 463 revisions are more likely to be compatible. Hence, NBC changes to 464 an imported module may also require new revisions of any importing 465 modules, updated to accommodation those changes, along with 466 updated import "revision-or-derived" extension statements to 467 depend on the updated imported module revision. 469 4.1. Module import examples 471 Consider the example module "example-module" from Section 3.5 that is 472 hypothetically available in the following revision/label pairings: 473 2019-01-01/1.0.0, 2019-02-01/2.0.0, 2019-03-01/3.0.0, 474 2019-04-01/2.1.0, 2019-05-01/2.2.0 and 2019-06-01/3.1.0. The 475 relationship between the revisions is as before: 477 Module revision date Revision label 478 2019-01-01 <- 1.0.0 479 | 480 2019-02-01 <- 2.0.0 481 | \ 482 2019-03-01 \ <- 3.0.0 483 | \ 484 | 2019-04-01 <- 2.1.0 485 | | 486 | 2019-05-01 <- 2.2.0 487 | 488 2019-06-01 <- 3.1.0 490 4.1.1. Example 1 492 This example selects module revisions that match, or are derived from 493 the revision 2019-02-01. E.g., this dependency might be used if 494 there was a new container added in revision 2019-02-01 that is 495 augmented by the importing module.It includes revisions/labels: 496 2019-02-01/2.0.0, 2019-03-01/3.0.0, 2019-04-01/2.1.0, 497 2019-05-01/2.2.0 and 2019-06-01/3.1.0. 499 import example-module { 500 rev:revision-or-derived 2019-02-01; 501 } 503 Alternatively, the first example could have used the revision label 504 "1.0.0" instead, which selects the same set of revisions/versions. 506 import example-module { 507 rev:revision-or-derived 1.0.0; 508 } 510 4.1.2. Example 2 512 This example selects module revisions that are derived from 513 2019-04-01 by using the revision label 2.1.0. It includes revisions/ 514 labels: 2019-04-01/2.1.0 and 2019-05-01/2.2.0. Even though 515 2019-06-01/3.1.0 has a higher revision label version number than 516 2019-04-01/2.1.0 it is not a derived revision, and hence it is not a 517 valid revision for import. 519 import example-module { 520 rev:revision-or-derived 2.1.0; 521 } 523 4.1.3. Example 3 525 This example selects revisions derived from either 2019-04-01 or 526 2019-06-01. It includes revisions/labels: 2019-04-01/2.1.0, 527 2019-05-01/2.2.0, and 2019-06-01/3.1.0. 529 import example-module { 530 rev:revision-or-derived 2019-04-01; 531 rev:revision-or-derived 2019-06-01; 532 } 534 5. Updates to ietf-yang-library 536 This document updates YANG library [RFC7895] [RFC8525] to clarify how 537 ambiguous module imports are resolved. It also defines the YANG 538 module, ietf-yl-revisions that augments YANG library with new 539 versioning related meta-data. 541 5.1. Resolving ambiguous module imports 543 A YANG datastore schema, defined in [RFC8525], can specify multiple 544 revisions of a YANG module in the schema using the "import-only" 545 list, with the requirement from [RFC7950] that only a single revision 546 of a YANG module may be implemented. 548 If a YANG module import statement does not specify a specific 549 revision within the datastore schema then it could be ambiguous as to 550 which module revision the import statement should resolve to. Hence, 551 a datastore schema constructed by a client using the information 552 contained in YANG library may not exactly match the datastore schema 553 actually used by the server. 555 The following two rules remove the ambiguity: 557 If a module import statement could resolve to more than one module 558 revision defined in the datastore schema, and one of those revisions 559 is implemented (i.e., not an "import-only" module), then the import 560 statement MUST resolve to the revision of the module that is defined 561 as being implemented by the datastore schema. 563 If a module import statement could resolve to more than one module 564 revision defined in the datastore schema, and none of those revisions 565 are implemented, then the import MUST resolve to the module revision 566 with the latest revision date. 568 5.2. YANG library versioning augmentations 570 The "ietf-yl-revisions" YANG module has the following structure 571 (using the notation defined in [RFC8340]): 573 module: ietf-yl-revisions 574 augment /yanglib:yang-library/yanglib:module-set/yanglib:module: 575 +--ro revision-label? rev:revision-label 576 augment /yanglib:yang-library/yanglib:schema: 577 +--ro deprecated-nodes-implemented? empty 578 +--ro obsolete-nodes-absent? empty 580 5.2.1. Advertising revision-label 582 The ietf-yl-revisions YANG module augments the "module" list in ietf- 583 yang-library with a "revision-label" leaf to optionally declare the 584 revision label associated wth the particular revision of each module. 586 5.2.2. Reporting how deprecated and obsolete nodes are handled 588 The ietf-yl-revisions YANG module augments YANG library with two 589 leaves to allow a server to report how it handles status "deprecated" 590 and status "obsolete" nodes. The leaves are: 592 deprecated-nodes-implemented: If present, this leaf indicates that 593 all schema nodes with a status "deprecated" child statement are 594 implemented equivalently as if they had status "current", or 595 otherwise deviations MUST be used to explicitly remove 596 "deprecated" nodes from the schema. If this leaf is absent then 597 the behavior is unspecified. 599 obsolete-nodes-absent: If present, this leaf indicates that the 600 server does not implement any status "obsolete" nodes. If this 601 leaf is absent then the behaviour is unspecified. 603 Servers SHOULD set both the "deprecated-nodes-implemented" and 604 "obsolete-nodes-absent" leaves. 606 If a server does not set the "deprecated-nodes-implemented" leaf, 607 then clients MUST NOT rely solely on the "rev:nbc-changes" statements 608 to determine whether two module revisions are backwards-compatible, 609 and MUST also consider whether the status of any nodes has changed to 610 "deprecated" and whether those nodes are implemented by the server. 612 6. Versioning of YANG instance data 614 Instance data sets [I-D.ietf-netmod-yang-instance-file-format] do not 615 directly make use of the updated revision handling rules described in 616 this document, as compatibility for instance data is undefined. 618 However, instance data specifies the content-schema of the data-set. 619 This schema SHOULD make use of versioning using revision dates and/or 620 revision labels for the individual YANG modules that comprise the 621 schema or potentially for the entire schema itself (e.g., 622 [I-D.rwilton-netmod-yang-packages] ). 624 In this way, the versioning of a content-schema associated with an 625 instance data set may help a client to determine whether the instance 626 data could also be used in conjunction with other revisions of the 627 YANG schema, or other revisions of the modules that define the 628 schema. 630 7. Guidelines for using the YANG module update rules 632 The following text updates section 4.7 of [RFC8407] to revise the 633 guidelines for updating YANG modules. 635 7.1. Guidelines for YANG module authors 637 All IETF YANG modules MUST include revision-label statements for all 638 newly published YANG modules, and all newly published revisions of 639 existing YANG modules. The revision-label MUST take the form of a 640 YANG semantic version number [I-D.verdt-netmod-yang-semver]. 642 NBC changes to YANG modules may cause problems to clients, who are 643 consumers of YANG models, and hence YANG module authors are 644 RECOMMENDED to minimize NBC changes and keep changes BC whenever 645 possible. 647 When NBC changes are introduced, consideration should be given to the 648 impact on clients and YANG module authors SHOULD try to mitigate that 649 impact. 651 A "rev:nbc-changes" statement SHOULD be added only if there are NBC 652 changes relative to the previous revision. 654 Removing old revision statements from a module's revision history 655 could break import by revision, and hence it is RECOMMENDED to retain 656 them. If all depencencies have been updated to not import specific 657 revisions of a module, then the corresponding revision statements can 658 be removed from that module. An alternative solution, if the 659 revision section is too long, would be remove, or curtail, the older 660 description statements associated with the previous revisions. 662 The "rev:revision-or-derived" extension should be used in YANG module 663 imports to indicate revision dependencies between modules in 664 preference to the "revision-date" statement, which causes overly 665 strict import dependencies and SHOULD NOT be used. 667 A module that includes submodules MUST use the "revision-date" 668 statement to include specific submodule revisions. Changing a 669 module's include statements to include different submodule revisions 670 requires a new revision of the module. 672 7.1.1. Making non-backwards-compatible changes to a YANG module 674 There are various valid situations where a YANG module has to be 675 modified in an NBC way. Here are the different ways in which this 676 can be done: 678 o NBC changes can be sometimes be done incrementally using the 679 "deprecated" status to provide clients time to adapt to NBC 680 changes. 682 o NBC changes are done at once, i.e. without using "status" 683 statements. Depending on the change, this may have a big impact 684 on clients. 686 o If the server can support multiple versions of the YANG module or 687 of YANG packages(as specified in 688 [I-D.rwilton-netmod-yang-packages]), and allows the client to 689 select the version (as per 690 [I-D.wilton-netmod-yang-ver-selection]), then NBC changes MAY be 691 done without using "status" statements. Clients would be required 692 to select the version which they support and the NBC change would 693 have no impact on them 695 Here are some guidelines on how non-backwards-compatible changes can 696 be made incrementally, with the assumption that deprecated nodes are 697 implemented by the server, and obsolete nodes are not: 699 1. The changes should be made gradually, e.g. a data node's status 700 SHOULD NOT be changed directly from "current" to "obsolete" (see 701 Section 4.7 of [RFC8407]), instead the status SHOULD first be 702 marked "deprecated" and then when support is removed its status 703 MUST be changed to "obsolete". Instead of using the "obsolete" 704 status, the data node MAY be removed from the model but this has 705 the risk of breaking modules which import the modified module. 707 2. The new "status-description" extension statement SHOULD be used 708 for nodes which are "obsolete" or "deprecated". 710 3. For status "deprecated", the "status-description" SHOULD also 711 indicate until when support for the node is guaranteed (if 712 known). If there is a replacement data node, rpc, action or 713 notification for the deprecated node, this SHOULD be stated in 714 the "status-description". The reason for deprecating the node 715 can also be included in the "status-description" if it is deemed 716 to be of potential interest to the user. 718 4. For status "obsolete", it is RECOMMENDED to keep the "status- 719 description" information, from when the node had status 720 "deprecated, which is still relevant. 722 5. When obsoleting or deprecating data nodes, the "deprecated" or 723 "obsolete" status SHOULD be applied at the highest possible level 724 in the data tree with an appropriate "status-description" 725 statement. For clarity, the "status" statement SHOULD also be 726 applied to all descendent data nodes, but the "status- 727 description" statement does not need to be repeated if it does 728 not introduce any additional information. 730 See Appendix A.1 for examples on how NBC changes can be made. 732 7.2. Versioning Considerations for Clients 734 Guidelines for clients of modules using the new module revision 735 update procedure: 737 o Clients SHOULD be liberal when processing data received from a 738 server. For example, the server may have increased the range of 739 an operational node causing the client to receive a value which is 740 outside the range of the YANG model revision it was coded against. 742 o Clients SHOULD monitor changes to published YANG modules through 743 their revision history, and use appropriate tooling to understand 744 the specific changes between module revision. In particular, 745 clients SHOULD NOT migrate to NBC revisions of a module without 746 understanding any potential impact of the specific NBC changes. 748 o Clients SHOULD plan to make changes to match published status 749 changes. When a node's status changes from "current" to 750 "deprecated", clients SHOULD plan to stop using that node in a 751 timely fashion. When a node's status changes to "obsolete", 752 clients MUST stop using that node. 754 8. Module Versioning Extension YANG Modules 756 YANG module with extension statements for annotating NBC changes, 757 revision label, status description, and importing by version. 759 file "ietf-yang-revisions@2019-09-18.yang" 760 module ietf-yang-revisions { 761 yang-version 1.1; 762 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-revisions"; 763 prefix rev; 765 import ietf-yang-types { 766 prefix yang; 767 reference 768 "XXXX [ietf-netmod-rfc6991-bis]: Common YANG Data Types"; 769 } 771 organization 772 "IETF NETMOD (Network Modeling) Working Group"; 773 contact 774 "WG Web: 775 WG List: 777 Author: Benoit Claise 778 780 Author: Joe Clarke 781 783 Author: Reshad Rahman 784 786 Author: Robert Wilton 787 789 Author: Kevin D'Souza 790 792 Author: Balazs Lengyel 793 795 Author: Jason Sterne 796 "; 797 description 798 "This YANG 1.1 module contains definitions and extensions to 799 support updated YANG revision handling. 801 Copyright (c) 2019 IETF Trust and the persons identified as 802 authors of the code. All rights reserved. 804 Redistribution and use in source and binary forms, with or 805 without modification, is permitted pursuant to, and subject 806 to the license terms contained in, the Simplified BSD License 807 set forth in Section 4.c of the IETF Trust's Legal Provisions 808 Relating to IETF Documents 809 (http://trustee.ietf.org/license-info). 811 This version of this YANG module is part of RFC XXXX; see 812 the RFC itself for full legal notices. 814 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 815 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 816 'MAY', and 'OPTIONAL' in this document are to be interpreted as 817 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 818 they appear in all capitals, as shown here."; 820 // RFC Ed.: update the date below with the date of RFC publication 821 // and remove this note. 822 // RFC Ed.: replace XXXX (inc above) with actual RFC number and 823 // remove this note. 825 revision 2019-09-18 { 826 description 827 "Initial version."; 828 reference 829 "XXXX: Updated YANG Module Revision Handling"; 830 } 832 typedef revision-label { 833 type string { 834 length "1..255"; 835 pattern '[^\s@]+'; 836 pattern '\d{4}-\d{2}-\d{2}' { 837 modifier invert-match; 838 } 839 } 840 description 841 "A label associated with a YANG revision. 843 Excludes spaces and '@'. MUST NOT match revision-date. 845 Revision labels that classify as YANG semantic versions, 846 as defined by the ietf-yang-semver:version typedef, 847 MUST conform to the versioning behaviour defined in 848 XXXX [verdt]: YANG Semantic Versioning."; 849 reference 850 "XXXX: Updated YANG Module Revision Handling; 851 Section 3.3, Revision label"; 852 } 854 typedef revision-date-or-label { 855 type union { 856 type yang:revision-identifier; 857 type revision-label; 858 } 859 description 860 "Represents either a YANG revision date or a revision label"; 861 } 863 extension nbc-changes { 864 description 865 "This statement is used to indicate YANG module revisions that 866 contain non-backwards-compatible changes. 868 Each 'revision' statement MAY have a single 'nbc-changes' 869 substatement. 871 If a revision of a YANG module contains changes, relative to 872 the preceding revision in the revision history, that do not 873 conform to the module update rules defined in RFC-XXX, then 874 the 'nbc-changes' statement MUST be added as a substatement to 875 the revision statement. 877 Conversely, if a revision of a YANG module only contains 878 changes, relative to the preceding revision in the revision 879 history, that are classified as 'backwards-compatible' then 880 the revision statement MUST NOT contain any 'nbc-changes' 881 substatement."; 883 reference 884 "XXXX: Updated YANG Module Revision Handling; 885 Section 3.2, nbc-changes revision extension statement"; 886 } 888 extension revision-label { 889 argument revision-label; 890 description 891 "The revision label can be used to provide an additional 892 versioning identifier associated with the revision. E.g., one 893 option for a versioning scheme that could be used is [TODO - 894 Reference semver draft]. 896 The format of the revision-label argument MUST conform to the 897 pattern defined for the revision-label typedef. 899 Each 'revision' statement MAY have a single 'revision-label' 900 substatement. 902 Revision labels MUST be unique amongst all revisions of a 903 module."; 905 reference 906 "XXXX: Updated YANG Module Revision Handling; 907 Section 3.3, Revision label"; 908 } 910 extension revision-or-derived { 911 argument revision-date-or-label; 912 description 913 "Restricts the revision of the module that may be imported to 914 one that matches or is derived from the specified 915 revision-date or revision-nlabel. 917 The argument value MUST conform to the 918 'revision-date-or-label' defined type. 920 Each 'import' statement MAY have one or more 921 'revision-or-derived' substatements. If specified multiple 922 times, then any module revision that satifies at least one of 923 the 'revision-or-derived' statements is an acceptable revision 924 for import. 926 An 'import' statement MUST NOT contain both a 927 'revision-or-derived' extension statement and a 928 'revision-date' statement. 930 A particular revision of an imported module satisfies an 931 import's 'revision-or-derived' extension statement if the 932 imported module's revision history contains a revision 933 statement with a matching revision date or revision label. 935 The 'revision-or-derived' extension statement does not 936 gaurantee that all module revisions that satisfy an import 937 statement are necessarily compatible, it only gives an 938 indication that the revisions are more likely to be 939 compatible."; 941 reference 942 "XXXX: Updated YANG Module Revision Handling; 943 Section 4, Import by derived revision"; 944 } 946 extension status-description { 947 argument description; 949 description 950 "Freeform text that describes why a given node has been 951 deprecated or made obsolete. E.g., the description could be 952 used to give the reason for removal, or it could point to an 953 alternative schema elements that can be used in lieu of the 954 given node. 956 Each 'status' statement MAY have a single 'status-description' 957 substatement."; 959 reference 960 "XXXX: Updated YANG Module Revision Handling; 961 Section 3.4, YANG status description extension statement"; 962 } 963 } 964 966 YANG module with augmentations to YANG Library to revision labels 968 file "ietf-yl-revisions@2019-09-18.yang" 969 module ietf-yl-revisions { 970 yang-version 1.1; 971 namespace "urn:ietf:params:xml:ns:yang:ietf-yl-revisions"; 972 prefix yl-rev; 974 import ietf-yang-revisions { 975 prefix rev; 976 reference 977 "XXXX: Updated YANG Module Revision Handling"; 978 } 980 import ietf-yang-library { 981 prefix yanglib; 982 reference "RFC 8525: YANG Libary"; 983 } 985 organization 986 "IETF NETMOD (Network Modeling) Working Group"; 987 contact 988 "WG Web: 989 WG List: 991 Author: Benoit Claise 992 994 Author: Joe Clarke 995 997 Author: Reshad Rahman 998 1000 Author: Robert Wilton 1001 1003 Author: Kevin D'Souza 1004 1006 Author: Balazs Lengyel 1007 1009 Author: Jason Sterne 1010 "; 1011 description 1012 "This module contains augmentations to YANG Library to add module 1013 level revision label and to provide an indication of how 1014 deprecated and obsolete nodes are handled by the server. 1016 Copyright (c) 2019 IETF Trust and the persons identified as 1017 authors of the code. All rights reserved. 1019 Redistribution and use in source and binary forms, with or 1020 without modification, is permitted pursuant to, and subject 1021 to the license terms contained in, the Simplified BSD License 1022 set forth in Section 4.c of the IETF Trust's Legal Provisions 1023 Relating to IETF Documents 1024 (http://trustee.ietf.org/license-info). 1026 This version of this YANG module is part of RFC XXXX; see 1027 the RFC itself for full legal notices. 1029 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1030 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1031 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1032 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1033 they appear in all capitals, as shown here."; 1035 // RFC Ed.: update the date below with the date of RFC publication 1036 // and remove this note. 1037 // RFC Ed.: replace XXXX (including in the imports above) with 1038 // actual RFC number and remove this note. 1039 // RFC Ed.: please replace revision-label version with 1.0.0 and 1040 // remove this note. 1041 revision 2019-09-18 { 1042 rev:revision-label 0.1.0; 1043 description 1044 "Initial revision"; 1045 reference 1046 "XXXX: Updated YANG Module Revision Handling"; 1047 } 1049 augment "/yanglib:yang-library/yanglib:module-set/yanglib:module" { 1050 description 1051 "Augmentation modules with a revision label"; 1052 leaf revision-label { 1053 type rev:revision-label; 1054 description 1055 "The revision label associated with this module revision. 1056 The label MUST match the rev:label value in the specific 1057 revision of the module loaded in this module-set."; 1059 reference 1060 "XXXX: Updated YANG Module Revision Handling; 1061 Section 5.2.1, Advertising revision-label"; 1062 } 1063 } 1065 augment "/yanglib:yang-library/yanglib:schema" { 1066 description 1067 "Augmentations to the ietf-yang-library module to indicate how 1068 deprecated and obsoleted nodes are handled for each datastore 1069 schema supported by the server."; 1071 leaf deprecated-nodes-implemented { 1072 type empty; 1073 description 1074 "If present, this leaf indicates that all schema nodes with a 1075 status 'deprecated' child statement are implemented 1076 equivalently as if they had status 'current', or otherwise 1077 deviations MUST be used to explicitly remove 'deprecated' 1078 nodes from the schema. If this leaf is absent then the 1079 behavior is unspecified."; 1081 reference 1082 "XXXX: Updated YANG Module Revision Handling; 1083 Section 5.2.2, Reporting how deprecated and obsolete nodes 1084 are handled"; 1085 } 1087 leaf obsolete-nodes-absent { 1088 type empty; 1089 description 1090 "If present, this leaf indicates that the server does not 1091 implement any status 'obsolete' nodes. If this leaf is 1092 absent then the behaviour is unspecified."; 1094 reference 1095 "XXXX: Updated YANG Module Revision Handling; 1096 Section 5.2.2, Reporting how deprecated and obsolete nodes 1097 are handled"; 1098 } 1099 } 1100 } 1101 CODE ENDS> 1103 9. Contributors 1105 This document grew out of the YANG module versioning design team that 1106 started after IETF 101. The following individuals are (or have been) 1107 members of the design team and have worked on the YANG versioning 1108 project: 1110 o Balazs Lengyel 1112 o Benoit Claise 1114 o Ebben Aries 1116 o Jason Sterne 1118 o Joe Clarke 1120 o Juergen Schoenwaelder 1122 o Mahesh Jethanandani 1124 o Michael (Wangzitao) 1126 o Qin Wu 1128 o Reshad Rahman 1130 o Rob Wilton 1132 The initial revision of this document was refactored and built upon 1133 [I-D.clacla-netmod-yang-model-update]. 1135 Discussons on the use of Semver for YANG versioning has been held 1136 with authors of the OpenConfig YANG models. We would like thank both 1137 Anees Shaikh and Rob Shakir for their input into this problem space. 1139 10. Security Considerations 1141 The document does not define any new protocol or data model. There 1142 are no security impacts. 1144 11. IANA Considerations 1146 11.1. YANG Module Registrations 1148 The following YANG module is requested to be registred in the "IANA 1149 Module Names" registry: 1151 The ietf-yang-revisions module: 1153 Name: ietf-yang-revisions 1155 XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-revisions 1157 Prefix: rev 1159 Reference: [RFCXXXX] 1161 The ietf-yl-revisions module: 1163 Name: ietf-yl-revisions 1165 XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yl-revisions 1167 Prefix: yl-rev 1169 Reference: [RFCXXXX] 1171 12. References 1173 12.1. Normative References 1175 [I-D.ietf-netmod-rfc6991-bis] 1176 Schoenwaelder, J., "Common YANG Data Types", draft-ietf- 1177 netmod-rfc6991-bis-02 (work in progress), November 2019. 1179 [I-D.verdt-netmod-yang-semver] 1180 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, 1181 B., Sterne, J., and K. D'Souza, "YANG Semantic 1182 Versioning", draft-verdt-netmod-yang-semver-01 (work in 1183 progress), October 2019. 1185 [I-D.verdt-netmod-yang-versioning-reqs] 1186 Clarke, J., "YANG Module Versioning Requirements", draft- 1187 verdt-netmod-yang-versioning-reqs-02 (work in progress), 1188 November 2018. 1190 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1191 Requirement Levels", BCP 14, RFC 2119, 1192 DOI 10.17487/RFC2119, March 1997, 1193 . 1195 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 1196 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 1197 . 1199 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1200 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1201 . 1203 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1204 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1205 May 2017, . 1207 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 1208 Documents Containing YANG Data Models", BCP 216, RFC 8407, 1209 DOI 10.17487/RFC8407, October 2018, 1210 . 1212 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 1213 and R. Wilton, "YANG Library", RFC 8525, 1214 DOI 10.17487/RFC8525, March 2019, 1215 . 1217 12.2. Informative References 1219 [I-D.clacla-netmod-yang-model-update] 1220 Claise, B., Clarke, J., Lengyel, B., and K. D'Souza, "New 1221 YANG Module Update Procedure", draft-clacla-netmod-yang- 1222 model-update-06 (work in progress), July 2018. 1224 [I-D.ietf-netmod-yang-instance-file-format] 1225 Lengyel, B. and B. Claise, "YANG Instance Data File 1226 Format", draft-ietf-netmod-yang-instance-file-format-08 1227 (work in progress), March 2020. 1229 [I-D.rwilton-netmod-yang-packages] 1230 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and W. Bo, 1231 "YANG Packages", draft-rwilton-netmod-yang-packages-03 1232 (work in progress), February 2020. 1234 [I-D.verdt-netmod-yang-solutions] 1235 Wilton, R., "YANG Versioning Solution Overview", draft- 1236 verdt-netmod-yang-solutions-03 (work in progress), 1237 February 2020. 1239 [I-D.wilton-netmod-yang-ver-selection] 1240 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and W. Bo, 1241 "YANG Schema Selection", draft-wilton-netmod-yang-ver- 1242 selection-02 (work in progress), February 2020. 1244 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1245 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1246 . 1248 [semver] "Semantic Versioning 2.0.0", . 1250 Appendix A. Appendix 1252 A.1. Examples of guidelines for making NBC changes to a YANG module 1254 Examples of NBC changes include: 1256 o Deleting a data node, or changing it to status obsolete. 1258 o Changing the name, type, or units of a data node. 1260 o Modifying the description in a way that changes the semantic 1261 meaning of the data node. 1263 o Any changes that change or reduce the allowed value set of the 1264 data node, either through changes in the type definition, or the 1265 addition or changes to "must" statements, or changes in the 1266 description. 1268 o Adding or modifying "when" statements that reduce when the data 1269 node is available in the schema. 1271 o Making the statement conditional on if-feature. 1273 The following sections give guidance for how some of these NBC 1274 changes could be made to a YANG module: 1276 A.1.1. Removing a data node 1278 Removing a leaf or container from the data tree, e.g. because support 1279 for the corresponding feature is being removed: 1281 1. The node's status is changed to "deprecated" and it is supported 1282 for at least one year. This is a BC change. 1284 2. When the node is not available anymore, its status is changed to 1285 "obsolete" and the "status-description" updated, this is an NBC 1286 change. The "status-description" is used to explain why the node 1287 is not available anymore. 1289 If the server can support NBC versions of the YANG module 1290 simultaneously using version selection, then the changes can be done 1291 immediately: 1293 1. The new revision of the YANG module has the node's status changed 1294 to "obsolete" and the "status-description" updated, this is an 1295 NBC change. 1297 2. Clients which require the data node select the older module 1298 revision 1300 A.1.2. Changing the type of a leaf node 1302 Changing the type of a leaf-node. e.g. consider a "vpn-id" node of 1303 type integer being changed to a string: 1305 1. The status of node "vpn-id" is changed to "deprecated" and the 1306 node should be available for at least one year. This is a BC 1307 change. 1309 2. A new node, e.g. "vpn-name", of type string is added to the same 1310 location as the existing node "vpn-id". This new node has status 1311 "current" and its description explains that it is replacing node 1312 "vpn-id". 1314 3. During the period of time where both nodes are available, how the 1315 server behaves when either node is set is outside the scope of 1316 this document and will vary on a case by case basis. Here are 1317 some options: 1319 1. A server may prevent the new node from being set if the old 1320 node is already set (and vice-versa). The new node may have 1321 a when statement to achieve this. The old node must not have 1322 a when statement since this would be an NBC change, but the 1323 server could reject the old node from being set if the new 1324 node is already set. 1326 2. If the new node is set and a client does a get or get-config 1327 operation on the old node, the server could map the value. 1328 For example, if the new node "vpn-name" has value "123" then 1329 the server could return integer value 123 for the old node 1330 "vpn-id". However, if the value can not be mapped, we need a 1331 way of returning "unsupported" TBD. 1333 4. When node "vpn-id" is not available anymore, its status is 1334 changed to "obsolete" and the "status-description" is updated. 1335 This is an NBC change. 1337 If the server can support NBC versions of the YANG module 1338 simultaneously using version selection, then the changes can be done 1339 immediately: 1341 1. In the new revision of the YANG module, the status of node "vpn- 1342 id" is changed to "obsolete". This is an NBC change. 1344 2. New node "vpn-name" is added to the same location as described 1345 above. 1347 3. Clients which require the data node select the older module 1348 revision 1350 4. A server should not map between the nodes "vpn-id" and "vpn- 1351 name", i.e. if a client creates a data instance with "vpn-name" 1352 then that data instance should not be visible to a client using a 1353 module revision which has "vpn-id" (and vice-versa). 1355 A.1.3. Reducing the range of a leaf node 1357 Reducing the range of values of a leaf-node. e.g. consider a "vpn-id" 1358 node of type integer being changed from type uint32 to type uint16: 1360 1. If all values which are being removed were never supported, e.g. 1361 if a vpn-id of 65536 or higher was never accepted, this is a BC 1362 change for the functionality (no functionality change). Even if 1363 it is an NBC change for the YANG model, there should be no impact 1364 for clients using that YANG model. 1366 2. If one or more values being removed was previously supported, 1367 e.g. if a vpn-id of 65536 was accepted previously, this is an NBC 1368 change for the YANG model. Clients using the old YANG model will 1369 be impacted, so a change of this nature should be done carefully, 1370 e.g. by using the steps described in Appendix A.1.2 1372 A.1.4. Changing the key of a list 1374 Changing the key of a list has a big impact to the client. For 1375 example, consider a "sessions" list which has a key "interface" and 1376 there is a need to change the key to "dest-address", such a change 1377 can be done in steps: 1379 1. The status of list "sessions" is changed to "deprecated" and the 1380 list should be available for at least one year. This is a BC 1381 change. 1383 2. A new list is created in the same location with the same data but 1384 with "dest-address" as key. Finding an appropriate name for the 1385 new list can be tricky especially if the name of the existing 1386 list was perfect. In this case the new list is called "sessions- 1387 address", has status "current" and its description should explain 1388 that it is replacing list "session". 1390 3. During the period of time where both lists are available, how the 1391 server behaves when either list is set is outside the scope of 1392 this document and will vary on a case by case basis. Here are 1393 some options: 1395 1. A server could prevent the new list from being set if the old 1396 list already has entries (and vice-versa). 1398 2. If the new list is set and a client does a get or get-config 1399 operation on the old list, the server could map the entries. 1400 However if the new list has entries which would lead to 1401 duplicate keys in the old list, the mapping can not be done. 1403 4. When list "sessions" is not available anymore, its status is 1404 changed to "obsolete" and the "status-description" is updated. 1405 This is an NBC change. 1407 If the server can support NBC versions of the YANG module 1408 simultaneously using version selection, then the changes can be done 1409 immediately: 1411 1. The new revision of the YANG module has the list "sessions" 1412 modified to have "dest-address" as key, this is an NBC change. 1414 2. Clients which require the previous functionality select the older 1415 module revision 1417 A.1.5. Renaming a node 1419 A leaf-node or a container may be renamed, either due to a spelling 1420 error in the previous name or because of a better name. For example 1421 a node "ip-adress" could be renamed to "ip-address": 1423 1. The status of the existing node "ip-adress" is changed to 1424 "deprecated" and the node should be available for at least one 1425 year. This is a BC change. 1427 2. The new node "ip-address" is added to the same location as the 1428 existing node "ip-adress". This new node has status "current" 1429 and its description should explain that it is replacing node "ip- 1430 adress". 1432 3. During the period of time where both nodes are available, how the 1433 server behaves when either node is set is outside the scope of 1434 this document and will vary on a case by case basis. Here are 1435 some options: 1437 1. A server could prevent the new node from being set if the old 1438 node is already set (and vice-versa). The new node could 1439 have a when statement to achieve this. The old node must not 1440 have a when statement since this would be an NBC change, but 1441 the server could reject the old node from being set if the 1442 new node is already set. 1444 2. If the new node is set and a client does a get or get-config 1445 operation on the old node, the server could use the value of 1446 the new node. For example, if the new node "ip-address" has 1447 value X then the server may return value X for the old node 1448 "ip-adress". 1450 4. When node "ip-adress" is not available anymore, its status is 1451 changed to "obsolete" and the "status-description" is updated. 1452 This is an NBC change. 1454 If the server can support NBC versions of the YANG module 1455 simultaneously using version selection, then the changes can be done 1456 immediately: 1458 1. The new revision of the YANG module has the node with the new 1459 name replacing the node with the old name, this is an NBC change. 1461 2. Clients which require the previous node name select the older 1462 module revision 1464 A.1.6. Changing a default value 1466 Authors' Addresses 1467 Benoit Claise 1468 Cisco Systems, Inc. 1469 De Kleetlaan 6a b1 1470 1831 Diegem 1471 Belgium 1473 Phone: +32 2 704 5622 1474 Email: bclaise@cisco.com 1476 Joe Clarke 1477 Cisco Systems, Inc. 1478 7200-12 Kit Creek Rd 1479 Research Triangle Park, North Carolina 1480 United States of America 1482 Phone: +1-919-392-2867 1483 Email: jclarke@cisco.com 1485 Reshad Rahman 1486 Cisco Systems, Inc. 1488 Email: rrahman@cisco.com 1490 Robert Wilton (editor) 1491 Cisco Systems, Inc. 1493 Email: rwilton@cisco.com 1495 Balazs Lengyel 1496 Ericsson 1497 Magyar Tudosok Korutja 1498 1117 Budapest 1499 Hungary 1501 Phone: +36-70-330-7909 1502 Email: balazs.lengyel@ericsson.com 1504 Jason Sterne 1505 Nokia 1507 Email: jason.sterne@nokia.com 1508 Kevin D'Souza 1509 AT&T 1510 200 S. Laurel Ave 1511 Middletown, NJ 1512 United States of America 1514 Email: kd6913@att.com