idnits 2.17.1 draft-clacla-netmod-yang-model-update-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 58 instances of too long lines in the document, the longest one being 42 characters in excess of 72. == There are 2 instances of lines with non-RFC2606-compliant FQDNs in the document. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 100: '...name. Thus, a module name MUST NOT be...' RFC 2119 keyword, line 101: '... the "namespace" statement MUST NOT be...' RFC 2119 keyword, line 107: '... this MUST be achieved by a new ...' RFC 2119 keyword, line 241: '...finition is obsolete and SHOULD NOT be...' RFC 2119 keyword, line 504: '... first character MAY be a '[' or '(' t...' (26 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (May 24, 2018) is 2161 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 895, but not defined ** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525) == Outdated reference: A later version (-07) exists of draft-ietf-netconf-rfc7895bis-06 -- Obsolete informational reference (is this intentional?): RFC 8049 (Obsoleted by RFC 8299) Summary: 3 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). 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 (if approved) Cisco Systems, Inc. 5 Intended status: Standards Track B. Lengyel 6 Expires: November 25, 2018 Ericsson 7 K. D'Souza 8 AT&T 9 May 24, 2018 11 New YANG Module Update Procedure 12 draft-clacla-netmod-yang-model-update-05 14 Abstract 16 This document specifies a new YANG module update procedure in case of 17 backward-incompatible changes, as an alternative proposal to the YANG 18 1.1 specifications. This document updates RFC 7950. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on November 25, 2018. 37 Copyright Notice 39 Copyright (c) 2018 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 2. The Problems . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2.1. Slow Standardization . . . . . . . . . . . . . . . . . . 4 57 2.2. Some YANG Modules Are Not Backward Compatible . . . . . . 4 58 2.3. Non-Backward Compatible Errors . . . . . . . . . . . . . 4 59 2.4. YANG Module Transition Strategy . . . . . . . . . . . . . 4 60 2.5. Need to Allow Non-Backward Compatible changes . . . . . . 5 61 2.6. Clear Indication of Node Support . . . . . . . . . . . . 5 62 2.7. No way to easily decide whether a change is Backward 63 Compatible . . . . . . . . . . . . . . . . . . . . . . . 6 64 3. The Solution . . . . . . . . . . . . . . . . . . . . . . . . 7 65 3.1. Semantic Versioning . . . . . . . . . . . . . . . . . . . 7 66 3.1.1. Semantic Versioning, As Set by the YANG Module 67 Designer . . . . . . . . . . . . . . . . . . . . . . 7 68 3.1.2. The Derived Semantic Version . . . . . . . . . . . . 10 69 3.1.3. Implementation Experience . . . . . . . . . . . . . . 10 70 3.2. Import by Semantic Version . . . . . . . . . . . . . . . 11 71 3.3. Updates to YANG 1.1 Module Update Rules . . . . . . . . . 14 72 3.4. Updates to ietf-yang-library . . . . . . . . . . . . . . 14 73 3.5. Deprecated and Obsolete Reasons . . . . . . . . . . . . . 15 74 4. Semantic Version Extension YANG Module . . . . . . . . . . . 16 75 5. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 20 76 6. Security Considerations . . . . . . . . . . . . . . . . . . . 20 77 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 78 7.1. YANG Module Registrations . . . . . . . . . . . . . . . . 20 79 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 80 8.1. Normative References . . . . . . . . . . . . . . . . . . 20 81 8.2. Informative References . . . . . . . . . . . . . . . . . 21 82 Appendix A. Appendix . . . . . . . . . . . . . . . . . . . . . . 21 83 A.1. Open Issues . . . . . . . . . . . . . . . . . . . . . . . 22 84 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 86 1. Introduction 88 The YANG data modeling language [RFC7950] specifies strict rules for 89 updating YANG modules (see section 11 "Updating a Module"). Citing a 90 few of the relevant rules: 92 1. "As experience is gained with a module, it may be desirable to 93 revise that module. However, changes to published modules are 94 not allowed if they have any potential to cause interoperability 95 problems between a client using an original specification and a 96 server using an updated specification." 98 2. "Note that definitions contained in a module are available to be 99 imported by any other module and are referenced in "import" 100 statements via the module name. Thus, a module name MUST NOT be 101 changed. Furthermore, the "namespace" statement MUST NOT be 102 changed, since all XML elements are qualified by the namespace." 104 3. "Otherwise, if the semantics of any previous definition are 105 changed (i.e., if a non-editorial change is made to any 106 definition other than those specifically allowed above), then 107 this MUST be achieved by a new definition with a new identifier." 109 4. "deprecated indicates an obsolete definition, but it permits new/ 110 continued implementation in order to foster interoperability with 111 older/existing implementations." 113 What are the consequences? 115 1. If a YANG module is intended to update another YANG module, the 116 module name should not be changed as it will break existing 117 tooling and code by changing imports statements, service 118 composition at the orchestration layer, general network 119 management applications, etc. 121 2. When the same YANG module name is kept, its new revision must be 122 updated in a backward-compatible way. 124 3. While most of the non-backward compatible changes are prohibited, 125 a client still does not know if a changed module is backward 126 compatible, as a server may remove parts of a module after 127 marking it deprecated or obsolete. 129 This document specifies a new YANG module update procedure in case of 130 backward-incompatible changes, as an alternative proposal to the YANG 131 1.1 specifications. This document updates RFC 7950. 133 This document does not address the potential need of an automatic way 134 to discover that a YANG-MODULE-B obsoletes YANG-MODULE-A, so that 135 YANG-MODULE-A should not be given any attention. This problem is 136 currently solved by RFC obsolete tag as a level of indirection 137 between the YANG modules. 139 2. The Problems 141 This section lists a series of problems, which leads to the solution 142 in the next section. 144 2.1. Slow Standardization 146 The points made in the introduction lead to the logical conclusion 147 that the standardized YANG modules have to be perfect on day one (at 148 least the structure and meaning), which in turn might explain why 149 IETF YANG modules take so long to standardize. Shooting for 150 perfection is obviously a noble goal, but if the perfect standard 151 comes too late, it doesn't help the industry. 153 2.2. Some YANG Modules Are Not Backward Compatible 155 As we learn from our mistakes, we're going to face more and more 156 backward-incompatible YANG modules. An example is the YANG data 157 model for L3VPN service delivery [RFC8049], which, based on 158 implementation experience, has been updated in a backward- 159 incompatible way by [RFC8299]. 161 While Standards Development Organization (SDO) YANG modules are 162 obviously better for the industry, we must recognize that many YANG 163 modules are actually generated YANG modules (for example, from 164 internal databases), also known as native YANG modules, or vendor 165 modules [RFC8199]. From time to time, the new YANG modules are not 166 backward-compatible. 168 In such cases, it would be better to indicate how backward-compatible 169 a given YANG module actually is. 171 2.3. Non-Backward Compatible Errors 173 Sometimes small errors force us to make non-backward compatible 174 updates. As an example imagine that we have a string with a complex 175 pattern (e.g., an IP address). Let's assume the initial pattern 176 incorrectly allows IP addresses to start with 355. In the next 177 version this is corrected to disallow addresses starting with 355. 178 Formally this is an non-backward compatible change as the value space 179 of the string is decreased. In reality an IP address and the 180 implementation behind it was never capable of handling an address 181 starting with 355. So practically this is a backward compatible 182 change, just like a correction of the description statement. Still 183 current YANG rules would force a module name change. 185 2.4. YANG Module Transition Strategy 187 Let's assume for a moment that we change the name of a YANG module 188 when making a backwards-incompatible change, with the specific 189 example of ietf-routing, which some propose to update to ietf- 190 routing-2. [yangcatalog] provides tooling that shows the 191 interdependencies of YANG modules. 193 Here are the over 30 modules that depend on ietf-routing 194 . 198 Let's look at the difference for ietf-routing-2: 199 . 203 Changing the module name from ietf-routing to ietf-routing-2 implies 204 that the we have to warn all draft authors of ietf-routing YANG 205 dependent modules. First, to make sure they are aware of ietf- 206 routing-2 (publishing a RFC8022bis mentioning in the module 207 description that this module is not compatible with the NMDA 208 architecture, and providing a pointer to ietf-routing-2 requires 209 manual, tedius work). And second, to ask them to change their import 210 (or service composition) to ietf-routing-2. Hopefully, in the ietf- 211 routing case, most dependent YANG modules are part of the IETF, so 212 the communication is a manageable. For the already existing 213 dependent vendor modules the problem is worse. And then there are 214 network management applications that may already be using ietf- 215 routing that would require new code to handle ietf-routing-2. 217 Changing the ietf-interfaces YANG module name would be a different 218 challenge, as it's used throughout the industry: 219 223 2.5. Need to Allow Non-Backward Compatible changes 225 As described in the previous sections, there is a need to allow non- 226 backward compatible changes without changing a module's name. This 227 would avoid many of the above problems. Allowing non-backward 228 compatible changes to happen without a module name change will 229 decrease the number of separate modules to handle and will make it a 230 trivial task to track these non-backward compatible changes. 232 2.6. Clear Indication of Node Support 234 The current definition of deprecated and obsolete in [RFC7950] (as 235 quoted below) is problematic and should be corrected. 237 o "deprecated" indicates an obsolete definition, but it permits new/ 238 continued implementation in order to foster interoperability with 239 older/existing implementations. 241 o "obsolete" means that the definition is obsolete and SHOULD NOT be 242 implemented and/or can be removed from implementations. 244 YANG is considered an interface contract between the server and the 245 client. The current definitions of deprecated and obsolete mean that 246 a schema node that is either deprecated or obsolete may or may not be 247 implemented. The client has no way to find out which is the case 248 except for by trying to write or read data at the leaf in question. 249 This probing would need to be done for each separate data-node, which 250 is not a trivial thing to do. This "may or may not" is unacceptable 251 in a contract. In effect, this works as if there would be an if- 252 feature statement on each deprecated schema node where the server 253 does not advertise whether the feature is supported or not. Why is 254 it not advertised? 256 If a schema part is considered old/bad we need to be able to give 257 advance warning that it will be removed. As this is an advance 258 warning the part shall still be present and usable in the current 259 revision; however, it will be removed in one of the next revisions. 260 This is compounded by the fact that obsolete nodes may return bad or 261 incorrect data. A client might expect they work by the fact they 262 return something at all. There must be a clear indication from the 263 server whether or not deprecated and obsolete nodes are implemented 264 as defined. 266 2.7. No way to easily decide whether a change is Backward Compatible 268 A management system, SDN controller or any other user of a module 269 should be capable of easily determining the compatibility between two 270 module versions. Higher level logic for a network function, 271 something that can not be implemented in a purely model driven way, 272 is always dependent on a specific version of the module. If the 273 client finds that the module has been updated on the network node, it 274 has to decide if it tries to handle it as it handled the previous 275 version of the model or if it just stops, to avoid problems. To make 276 this decision the client needs to know if the module was updated in a 277 backward compatible way or not. 279 This is not possible to decide today because of the following: 281 o It is possible to change the semantic behavior of a data node, 282 action or rpc while the YANG definition does not change (with the 283 possible exception of the description statement). In such a case 284 it is impossible to determine whether the change is backward 285 compatible just by looking at the YANG statements. Its only the 286 human model designer that can decide. 288 o Problems with the deprecated and obsolete status statement, 289 Section 2.6 291 o Modelers might decide to violate YANG 1.1 update rules for some of 292 the reasons above 294 Finding status changes or violations of update rules need a line by 295 line comparision of the old and new modules, no easy task. 297 3. The Solution 299 The solution is composed of five parts: 301 1. A semantic versioning YANG extension, along with an optional 302 additional check that validates the semantic versioning from a 303 syntactic point of view, which can either assist in determining 304 the correct semantic versioning values, or which can help in 305 determining the values for YANG modules that don't support this 306 extension. 308 2. The import by version statement" 310 3. Updates to the YANG 1.1 module update rules 312 4. Updates to ietf-yang-library 314 5. The deprecated and obsolotes Reason" 316 3.1. Semantic Versioning 318 3.1.1. Semantic Versioning, As Set by the YANG Module Designer 320 The semantic versioning solution proposed here has already been 321 proposed in [I-D.openconfig-netmod-model-catalog] (included here with 322 the authors' permission) which itself is based on [openconfigsemver]. 323 The goal is to indicate the YANG module backwards (in)compatibility, 324 following semver.org semantic versioning [semver]: 326 "The SEMVER version number for the module is introduced. This is 327 expressed as a semantic version number of the form: x.y.z 329 o x is the MAJOR version. It is incremented when the new version of 330 the specification is incompatible with previous versions. 332 o y is the MINOR version. It is incremented when new functionality 333 is added in a manner that is backward-compatible with previous 334 versions. 336 o z is the PATCH version. It is incremented when bug fixes are made 337 in a backward-compatible manner." 339 The semantic version value is set by the YANG module developer at the 340 design and implementation times. Along these lines, we propose the 341 following YANG 1.1 extension for a more generic semantic version. 342 The formal definition is found at the end of this document. 344 extension module-version { 345 argument semver; 346 } 348 The extension would typically be used this way: 350 module yang-module-name { 352 namespace "name-space"; 353 prefix "prefix-name"; 355 import ietf-semver { prefix "semver"; } 357 description 358 "to be completed"; 360 revision 2017-10-30 { 361 description 362 "Change the module structure"; 363 semver:module-version "2.0.0"; 364 } 366 revision 2017-07-30 { 367 description 368 "Added new feature XXX"; 369 semver:module-version "1.2.0"; 370 } 372 revision 2017-04-03 { 373 description 374 "Update copyright notice."; 375 semver:module-version "1.0.1"; 376 } 378 revision 2017-04-03 { 379 description 380 "First release version."; 381 semver:module-version "1.0.0"; 382 } 384 revision 2017-01-26 { 385 description 386 "Initial module for inet types"; 387 semver:module-version "0.1.0"; 388 } 390 //YANG module definition starts here 392 See also "Semantic Versioning and Structure for IETF Specifications" 393 [I-D.claise-semver] for a mechanism to combine the semantic 394 versioning, the GitHub tools, and a potential change to the IETF 395 process. 397 3.1.2. The Derived Semantic Version 399 If an explicitly defined semantic version is not available in the 400 YANG module, it is possible to algoritmically calculate a derived 401 semantic version. This can be used for modules not containing a 402 definitive semantic-version as defined in this document or as a 403 starting value when specifying the definitive semantic-version. Be 404 aware that this algorithm may sometimes incorrectly classify changes 405 between the categories non-compatible, compatible or error- 406 correction. 408 3.1.3. Implementation Experience 410 [yangcatalog] uses the pyang utility to calculate the derived- 411 semantic-version for all of the modules contained within the catalog. 412 [yangcatalog] contains many revisions of the same module in order to 413 provide its derived-semantic-version for module consumers to know 414 what has changed between revisions of the same module. 416 Two distinct leafs in the YANG module 417 [I-D.clacla-netmod-model-catalog] contain this semver notation: 419 o the semantic-version leaf contains the value embedded within a 420 YANG module (if it is available). 422 o the derived-semantic-version leaf is established by examining the 423 the YANG module themselves. As such derived-semantic-version only 424 takes syntax into account as opposed to the meaning of various 425 elements when it computes the semantic version. 427 o The algorithm used to produce the derived-semantic-version is as 428 follows: 430 1. Order all modules of the same name by revision from oldest to 431 newest. Include module revisions that are not available, but 432 which are defined in the revision statements in one of the 433 available module versions. 435 2. If module A, revision N+1 has failed compilation, bump its 436 derived semantic MAJOR version. For unavailable module 437 versions assume non-backward compatible changes were done., 438 thus bump its derived semantic MAJOR version. 440 3. Else, run "pyang --check-update-from" on module A, revision N 441 and revision N+1 to see if backward-incompatible changes 442 exist. 444 4. If backward-incompatible changes exist, bump module A, 445 revision N+1's derived MAJOR semantic version. 447 5. If no backward-incompatible changes exist, compare the pyang 448 trees of module A, revision N and revision N+1. 450 6. If there are structural differences (e.g., new nodes), bump 451 module A, revision N+1's derived MINOR semantic version. 453 7. If no structural differences exist, bump module A, revision 454 N+1's derived PATCH semantic version. 456 The pyang utility checks many of the points listed in section 11 of 457 [RFC7950] for known module incompatibilities. While this approach is 458 a good way to programmatically obtain a semantic version number, it 459 does not address all cases whereby a major version number might need 460 to be increased. For example, a node may have the same name and same 461 type, but its meaning may change from one revision of a module to 462 another. This represents a semantic change that breaks backwards 463 compatibility, but the above algorithm would not find it. Therefore, 464 additional, sometimes manual, rigor must be done to ensure a proper 465 version is chosen for a given module revision. 467 3.2. Import by Semantic Version 469 If a module is imported by another one, it is usually not specified 470 which revision of the imported module should be used. However, not 471 all revisions may be acceptable. Today YANG 1.1 allows one to 472 specify the revision date of the imported module, but that is too 473 specific, as even a small spelling correction of the imported module 474 results in a change to its revision date, thus making the module 475 revision ineligible for import. 477 Using semantic versioning to indicate the acceptable imported module 478 versions is much more flexible. For example: 480 o Only a module of a specific MAJOR version is acceptable. All 481 MINOR and PATCH versions can also be imported. 483 o A module at a specific MAJOR version or higher is acceptable. 485 o A module at a specific MAJOR.MINOR version is acceptable. All 486 PATCH versions can also be imported. 488 o A module within a certain range of versions are acceptable. For 489 example, in this case, a module between version 1.0.0 (inclusive) 490 and 3.0.0 (exclusive) are acceptable. 492 The ietf-semver module provides another extension, import-versions 493 that is a child of import and specifies the rules for an acceptable 494 set of versions of the given module. The structure of this extension 495 is specified as follows: 497 TODO: How to specify this? One thought is below, not fully 498 formalized as this should be discussed further. Note: while this 499 uses a comma to separate discrete versions, we could instead allow 500 for this to be specified multiple times. 502 [\[(]X[.Y[.Z]][-[X[.Y[.X]]][\])]][,...] 504 Where the first character MAY be a '[' or '(' to indicate at least inclusive and at least 505 exclusive (respectively). If this is omitted, a full semantic version must be specified 506 and the import will only support this one version. 508 The following version, if specified with a '[' or '(' indicates the lower bound. This can 509 be a full semantic version or a MAJOR only or MAJOR.MINOR only. 511 The '-', if specified, is a literal hyphen indicating a range will be specified. If the second portion 512 of the import-versions clause is omitted, then there is no upper bound on what will be considered 513 an acceptable imported version. 515 After the '-' the upper bound semantic version (or part thereof) follows. 517 After the upper bound version, one of ']' or ')' MUST follow to indicate whether this limit is inclusive 518 or exclusive of the upper bound respectively. 520 Finally, a literal comma (',') MAY be specified with additional ranges. Each range is taken as a logical 521 OR. 523 For example: 525 import example-module { 526 semver:import-versions "[1.0.0-3.0.0)"; 527 // All versions between 1.0.0 (inclusive) and 3.0.0 (exclusive) are acceptable. 528 } 530 import example-module { 531 semver:import-versions "[2-5]"; 532 // All versions between 2.0.0 (inclusive) and 5.y.z (inclusive) where y and z are 533 // any value for MINOR and PATCH versions. 534 } 536 import example-module { 537 semver:import-versions "[1.5-2.0.0),[2.5"; 538 // All versions between 1.5.0 (inclusive) and 2.0.0 (exclusive) as well as all versions 539 // greater than 2.5 (inclusive). In this manner, if 2.0 was branched from 1.4, and a 540 // new feature was added into 1.5, all versions of 1.x.x starting at 1.5 are allowed, 541 // but the feature was not merged into 2.y.z until 2.5.0. 542 } 544 import example-module { 545 semver:import-versions "[1"; 546 // All versions greater than MAJOR version 1 are acceptable. This includes any 547 // MINOR or PATCH versions. 548 } 550 import example-module { 551 semver:import-versions "1.0.0"; 552 // Only version 1.0.0 is acceptable (this mimics what exists with import by revision). 553 } 555 import example-module { 556 semver:import-versions "[1.1-2)""; 557 // All versions greater than 1.1 (inclusive, and including all PATCH versions off of 1.1) 558 // up to MAJOR version 2 (exclusive) are acceptable. 559 } 561 import example-module { 562 semver:import-versions "[1.1-2),[3"; 563 // All versions greater than 1.1 (inclusive, and including all PATCH versions off of 1.1) 564 // up to MAJOR version 2 (exclusive), as well as all versions greater than MAJOR version 3 565 // (inclusive) are acceptable. 566 } 568 import example-module { 569 semver:import-versions "[1.1-2),[3.0.0"; 570 // This is equivalent to the example above, simply indicating that a partial semantic version 571 // assumes all missing components are 0. 572 } 573 The import statement SHOULD include a semver:import-versions 574 statement and MUST NOT include a revision statement. An import 575 statement MUST NOT contain both a semver:import-versions and a 576 revision substatement. The use of the revision substatement for 577 import should be discouraged. 579 3.3. Updates to YANG 1.1 Module Update Rules 581 RFC 7950 section 11, must be updated to allow for non-backwards 582 changes provided they follow the semantic versioning guidelines and 583 increase the MAJOR version number when a backwards incompatible 584 change is made. The following is proposed text for this change. 586 "As experience is gained with a module, it may be desirable to revise 587 that module. Changes to published modules are allowed, even if they 588 have some potential to cause interoperability problems, if the 589 module-version YANG extension is used in the revision statement to 590 clearly indicate the nature of the change." 592 3.4. Updates to ietf-yang-library 594 The ietf-semver YANG module also specifies additional ietf-yang- 595 library [RFC7895] [I-D.ietf-netconf-rfc7895bis] leafs to be added at 596 the module and submodule levels. The first is module-version, which 597 augments /yanglib:yang-library/yanglib:module-set/yanglib:module. 598 This specifies the current semantic version of the associated module 599 and revision in a given module-set. The related submodule-version 600 leaf is added at /yanglib:yang-library/yanglib:module- 601 set/yanglib:module/yanglib:submodule to indicate the semantic version 602 of a submodule. 604 In order to satisfy the requirement that deprecated and obsolete node 605 presence and operation are easily and clearly known to clients, ietf- 606 semver also augments the ietf-yang-library with two additional 607 boolean leafs at /yanglib:yang-library/yanglib:module-set/ 608 yanglib:module. A client can make one request of the ietf-yang- 609 library and know whether or a not a module that has deprecated or 610 obsolete has those nodes implemented by the server, as opposed to 611 making multiple requests for each node in question. 613 deprecated-nodes-present : A boolean that indicates whether or not 614 this server implements deprecated nodes. The value of this leaf 615 SHOULD be true; and if so, the server MUST implement nodes within 616 this module as they are documented. If specific deprecated nodes 617 are not implemented as document, then they MUST be listed as 618 deviations. This leaf defaults to true. 620 obsolete-nodes-present : A boolean that indicates whether or not 621 this server implements obsolete nodes. The value of this leaf 622 SHOULD be false; and if so, the server MUST NOT implement nodes 623 within this module. If this leaf is true, then all nodes in this 624 module MUST be implemented as documented in the module. Any 625 variation of this MUST be listed as deviations. This leaf 626 defaults to false. 628 If a module does not have any deprecated or obsolete nodes, the 629 server SHOULD set the corresponding leaf above to true. This is 630 helpful to clients, such that if the MAJOR version number has not 631 changed, and these booleans are true, then a client does not have to 632 check the status of any node for the module. 634 Module compatibility can be affected if values other than the default 635 are used for the leafs described here. For example, if a server does 636 not implemennt deprecated nodes, then a given module revision may be 637 incompatible with a previous revision where the nodes were not 638 deprecated. When calculating backwards compatibility, the default 639 values of these leafs MUST be considered. From a client's point of 640 view, if two module revisions have the same MAJOR version but the 641 run-time value of deprecated-nodes-present (as read from the ietf- 642 yang-library) is false, then compatibility MUST NOT be assumed based 643 on the module-version alone. 645 3.5. Deprecated and Obsolete Reasons 647 The ietf-semver module specifies an extension, status-description, 648 that is designed to be used as a substatement of the status statement 649 when the status is deprecated or obsolete. This argument to this 650 extension is freeform text that explains why the node was deprecated 651 or made obsolete. It may also point to other schema elements that 652 take the place of the deprecated or obsolete node. This text is 653 designed for human consumption to aid in the migration away from 654 nodes that will one day no longer work. An example is shown below. 656 leaf imperial-temperature { 657 type int64; 658 units "degrees Fahrenheit"; 659 status deprecated { 660 semver:status-description 661 "Imperial measurements are being phased out in favor 662 of their metric equivalents. Use metric-temperature 663 instead."; 664 } 665 description 666 "Temperature in degrees Fahrenheit."; 667 } 669 4. Semantic Version Extension YANG Module 671 The extension and related ietf-yang-library changes described in this 672 module are defined in the YANG module below. 674 file "ietf-semver@2018-04-05.yang" 675 module ietf-semver { 676 yang-version 1.1; 677 namespace "urn:ietf:params:xml:ns:yang:ietf-semver"; 678 prefix semver; 680 import ietf-yang-library { 681 prefix yanglib; 682 } 684 organization 685 "IETF NETMOD (Network Modeling) Working Group"; 686 contact 687 "WG Web: 688 WG List: 690 Author: Benoit Claise 691 693 Author: Joe Clarke 694 696 Author: Kevin D'Souza 697 699 Author: Balazs Lengyel 700 "; 701 description 702 "This module contains a definition for a YANG 1.1 extension to 703 express the semantic version of YANG modules."; 705 revision 2018-04-05 { 706 description 707 "* Properly import ietf-yang-library. 708 * Fix the name of module-semver => module-version. 709 * Fix regular expression syntax. 710 * Augment yang-library with booleans as to whether or not 711 deprecated and obsolete nodes are present. 712 * Add an extension to enable import by semantic version. 713 * Add an extension status-description to track deprecated 714 and obsolete reasons. 715 * Fix yang-library augments to use 7895bis."; 716 reference 717 "draft-clacla-netmod-yang-model-update: 718 New YANG Module Update Procedure"; 719 semver:module-version "0.2.1"; 720 } 721 revision 2017-12-15 { 722 description 723 "Initial revision."; 724 reference 725 "draft-clacla-netmod-yang-model-update: 726 New YANG Module Update Procedure"; 727 semver:module-version "0.1.1"; 728 } 730 extension module-version { 731 argument semver; 732 description 733 "The version number for the module revision it is used in. 734 This is expressed as a semantic version string in the form: 735 x.y.z 736 where: 737 * x corresponds to the major version, 738 * y corresponds to a minor version, 739 * z corresponds to a patch version. 741 A major version number of 0 indicates that this model is still 742 in development, and is potentially subject to change. 744 Following a release of major version 1, all modules will 745 increment major revision number where backwards incompatible 746 changes to the model are made. 748 The minor version is changed when features are added to the 749 model that do not impact current clients use of the model. 750 When major version is stepped, the minor version is reset to 0. 752 The patch-level version is incremented when non-feature changes 753 (such as bugfixes or clarifications to human-readable 754 descriptions that do not impact model functionality) are made 755 that maintain backwards compatibility. 756 When major or minor version is stepped, the patch-level is 757 reset to 0. 759 By comparing the module-version between two revisions of a 760 given module, one can know if different revisions are backwards 761 compatible or not, as well as 762 whether or not new features have been added to a newer revision. 764 If a module contains this extension it indicates that for this 765 module the updated status and update rules as this described in 766 RFC XXXX are used. 768 The statement MUST only be a substatement of the revision statement. 769 Zero or one module-version statement is allowed per parent 770 statement. NO substatements are allowed. 771 "; 772 reference "http://semver.org/ : Semantic Versioning 2.0.0"; 773 } 775 extension import-versions { 776 argument version-clause; 777 description 778 "This extension specifies an acceptable set of semantic versions of a given module 779 that may be imported. The version-clause argument is specified in the following 780 format 782 [\\[(]X[.Y[.Z]][-[X[.Y[.X]]][\\])]][,...] 784 Where the first character MAY be a '[' or '(' to indicate at least inclusive and at least 785 exclusive (respectively). If this is omitted, a full semantic version must be specified 786 and the import will only support this one version. 788 The following version, if specified with a '[' or '(' indicates the lower bound. This can 789 be a full semantic version or a MAJOR only or MAJOR.MINOR only. 791 The '-', if specified, is a literal hyphen indicating a range will be specified. If the second portion 792 of the import-versions clause is omitted, then there is no upper bound on what will be considered 793 an acceptable imported version. 795 After the '-' the upper bound semantic version (or part thereof) follows. 796 After the upper bound version, one of ']' or ')' MUST follow to indicate whether this limit is inclusive 797 or exclusive of the upper bound respectively. 799 Finally, a literal comma (',') MAY be specified with additional ranges. Each range is taken as a logical 800 OR. 802 The statement MUST only be a substatement of the import statement. Zero or one 803 import-versions statement is allowed per import statement. NO substatements are allowed."; 804 reference "I-D.clacla-netmod-yang-model-update : Import By Semantic Version"; 805 } 807 extension status-description { 808 argument description; 809 description 810 "Freeform text that describes why a given node has been deprecated or made obsolete. 811 This may point to other schema elements that can be used in lieu of the given node. 813 This statement MUST only be used as a substatement of the status statement, and MUST 814 only be used when the status is deprecated or obsolete. Zero or more status-description 815 statements are allowed per parent statement. NO substatements are allowed."; 816 reference "I-D.clacla-netmod-yang-model-update : Deprecated and Obsolete Reasons"; 817 } 819 augment "/yanglib:yang-library/yanglib:module-set/yanglib:module" { 820 description 821 "Augmentations for the ietf-yang-library module to support semantic versioning."; 822 leaf module-version { 823 type string { 824 pattern '[0-9]+\.[0-9]+\.[0-9]+'; 825 } 826 description 827 "The semantic version for this module in MAJOR.MINOR.PATCH format. This version 828 must match the semver:module-version value in specific revision of the module 829 loaded in this module-set."; 830 } 831 leaf deprecated-nodes-present { 832 type boolean; 833 default "true"; 834 description 835 "A boolean that indicates whether or not this server implements deprecated nodes. 836 The value of this leaf SHOULD be true; and if so, the server MUST implement nodes 837 within this module as they are documented. If specific deprecated nodes are not 838 implemented as document, then they MUST be listed as deviations. If a module does 839 not currently contain any deprecated nodes, then this leaf SHOULD be set to true."; 840 } 841 leaf obsolete-nodes-present { 842 type boolean; 843 default "false"; 844 description 845 "A boolean that indicates whether or not this server implements obsolete nodes. 846 The value of this leaf SHOULD be false; and if so, the server MUST NOT implement 847 nodes within this module. If this leaf is true, then all nodes in this module MUST 848 be implemented as documented in the module. Any variation of this MUST be listed as 849 deviations. If a module does not currently contain any obsolete nodes, then this 850 leaf SHOULD be set to true."; 851 } 852 } 853 augment "/yanglib:yang-library/yanglib:module-set/yanglib:module/yanglib:submodule" { 854 description 855 "Augmentations for the ietf-yang-library module/submodule to support semantic versioning."; 856 leaf submodule-version { 857 type string { 858 pattern '[0-9]+\.[0-9]+\.[0-9]+'; 859 } 860 description 861 "The semantic version for this submodule in MAJOR.MINOR.PATCH format. This version 862 must match the semver:module-version value in specific revision of the submodule 863 loaded in this module-set."; 864 } 865 } 866 } 867 869 5. Contributors 871 o Anees Shaikh, Google 873 o Rob Shakir, Google 875 6. Security Considerations 877 The document does not define any new protocol or data model. There 878 are no security impacts. 880 7. IANA Considerations 882 7.1. YANG Module Registrations 884 The following YANG module is requested to be registred in the "IANA 885 Module Names" registry: 887 The ietf-semver module: 889 o Name: ietf-semver 891 o XML Namespace: urn:ietf:params:xml:ns:yang:ietf-semver 893 o Prefix: semver 895 o Reference: [RFCXXXX] 897 8. References 899 8.1. Normative References 901 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 902 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 903 . 905 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 906 RFC 7950, DOI 10.17487/RFC7950, August 2016, 907 . 909 8.2. Informative References 911 [I-D.clacla-netmod-model-catalog] 912 Clarke, J. and B. Claise, "YANG module for 913 yangcatalog.org", draft-clacla-netmod-model-catalog-03 914 (work in progress), April 2018. 916 [I-D.claise-semver] 917 Claise, B., Barnes, R., and J. Clarke, "Semantic 918 Versioning and Structure for IETF Specifications", draft- 919 claise-semver-02 (work in progress), January 2018. 921 [I-D.ietf-netconf-rfc7895bis] 922 Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 923 and R. Wilton, "YANG Library", draft-ietf-netconf- 924 rfc7895bis-06 (work in progress), April 2018. 926 [I-D.openconfig-netmod-model-catalog] 927 Shaikh, A., Shakir, R., and K. D'Souza, "Catalog and 928 registry for YANG models", draft-openconfig-netmod-model- 929 catalog-02 (work in progress), March 2017. 931 [openconfigsemver] 932 "Semantic Versioning for Openconfig Models", 933 . 935 [RFC8049] Litkowski, S., Tomotaki, L., and K. Ogaki, "YANG Data 936 Model for L3VPN Service Delivery", RFC 8049, 937 DOI 10.17487/RFC8049, February 2017, 938 . 940 [RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module 941 Classification", RFC 8199, DOI 10.17487/RFC8199, July 942 2017, . 944 [RFC8299] Wu, Q., Ed., Litkowski, S., Tomotaki, L., and K. Ogaki, 945 "YANG Data Model for L3VPN Service Delivery", RFC 8299, 946 DOI 10.17487/RFC8299, January 2018, 947 . 949 [semver] "Semantic Versioning 2.0.0", . 951 [yangcatalog] 952 "YANG Catalog", . 954 Appendix A. Appendix 955 A.1. Open Issues 957 There are a number of open issues to be disccused. These include the 958 following: 960 o Do we need a new version of YANG? 961 While eventually this will fold into a new version, the belief is 962 this solution can work with extensions alone with an update to the 963 [RFC7950] text concerning module updates. 965 o Should IETF/IANA officially generate derived semantic versions for 966 their own modules? As they are the owner of the modules it should 967 be their responsibility, but how to document it? Note that next 968 round of funding for the yangcatalog.org could help develop the 969 perfect derived-semantic-version toolset 971 o We could consider a new naming convention for module files. 972 Today, module files are named using a module@revision.yang 973 notation. We could consider module%semver.yang or 974 module#version.yang variants. Re-using the '@' for version is not 975 ideal, so another separator character should be used. In this 976 manner, both version and revision could be used. 978 o Taking another page from Openconfig, the notion of a module bundle 979 could be considered. That is, there may need to be a way to 980 enumerate modules that are part of a bundle and are known to 981 interoperate. This may not be as critical if a rich import-by- 982 version is defined. 983 While the issue is interesting, it will be not be handled in this 984 document. 986 o Similarly, the concept of a feature bundle should be considered. 987 Typically, operators combine and test YANG modules to build value- 988 add services. These bundles form releases for specific features 989 or services, and it is critical to ensure as the modules evolve, 990 the bundles can coherently evolve with them. 991 While the issue is interesting, it will be not be handled in this 992 document. 994 o When we'll start using this new procedure for a new YANG module 995 revision, will we have to update all the dependent YANG modules to 996 start using this new procedure, along with the new import 997 statement? Is this a moot point, as a new YANG module name would 998 suffer from the same symptoms? 999 We see no need for updating other dependent modules. It is a good 1000 idea to update them, as they will benefit from using SEMVER, 1001 however there is no specific need to update them. 1003 Authors' Addresses 1005 Benoit Claise 1006 Cisco Systems, Inc. 1007 De Kleetlaan 6a b1 1008 1831 Diegem 1009 Belgium 1011 Phone: +32 2 704 5622 1012 Email: bclaise@cisco.com 1014 Joe Clarke 1015 Cisco Systems, Inc. 1016 7200-12 Kit Creek Rd 1017 Research Triangle Park, North Carolina 1018 United States of America 1020 Phone: +1-919-392-2867 1021 Email: jclarke@cisco.com 1023 Balazs Lengyel 1024 Ericsson 1025 Magyar Tudosok Korutja 1026 1117 Budapest 1027 Hungary 1029 Phone: +36-70-330-7909 1030 Email: balazs.lengyel@ericsson.com 1032 Kevin D'Souza 1033 AT&T 1034 200 S. Laurel Ave 1035 Middletown, NJ 1036 United States of America 1038 Email: kd6913@att.com