idnits 2.17.00 (12 Aug 2021) /tmp/idnits19715/draft-ietf-netmod-yang-solutions-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (1 November 2020) is 559 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-06) exists of draft-ietf-netmod-yang-versioning-reqs-03 == Outdated reference: A later version (-05) exists of draft-ietf-netmod-yang-module-versioning-01 == Outdated reference: A later version (-03) exists of draft-ietf-netmod-yang-packages-00 == Outdated reference: A later version (-01) exists of draft-ietf-netmod-yang-schema-comparison-00 == Outdated reference: A later version (-06) exists of draft-ietf-netmod-yang-semver-01 Summary: 0 errors (**), 0 flaws (~~), 6 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Wilton, Ed. 3 Internet-Draft Cisco Systems, Inc. 4 Intended status: Informational 1 November 2020 5 Expires: 5 May 2021 7 YANG Versioning Solution Overview 8 draft-ietf-netmod-yang-solutions-01 10 Abstract 12 This document gives an overview of the different documents that 13 comprise a full solution to the YANG versioning requirements 14 document. The purpose of this document is to help readers understand 15 how the discrete parts of the YANG versioning solution fit together 16 during working group development of the solution documents. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on 5 May 2021. 35 Copyright Notice 37 Copyright (c) 2020 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 42 license-info) in effect on the date of publication of this document. 43 Please review these documents carefully, as they describe your rights 44 and restrictions with respect to this document. Code Components 45 extracted from this document must include Simplified BSD License text 46 as described in Section 4.e of the Trust Legal Provisions and are 47 provided without warranty as described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 2. Solution Documents . . . . . . . . . . . . . . . . . . . . . 3 53 2.1. Updated YANG Module Revision Handling . . . . . . . . . . 3 54 2.2. YANG Semantic Versioning . . . . . . . . . . . . . . . . 4 55 2.3. Versioned YANG packages . . . . . . . . . . . . . . . . . 4 56 2.4. Dynamic YANG schema selection . . . . . . . . . . . . . . 5 57 2.5. YANG Schema Comparison . . . . . . . . . . . . . . . . . 6 58 3. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 6 59 4. Security Considerations . . . . . . . . . . . . . . . . . . . 7 60 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 61 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 62 6.1. Normative References . . . . . . . . . . . . . . . . . . 7 63 6.2. Informative References . . . . . . . . . . . . . . . . . 7 64 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8 66 1. Introduction 68 [I-D.ietf-netmod-yang-versioning-reqs] documents the requirements for 69 any solution to the YANG [RFC7950] versioning problem. In 70 particular, chapter 5 lists the formal requirements that a solution 71 requires. 73 The complete solution to all of the YANG versioning requirements is 74 comprised of five documents, each addressing different aspects of the 75 solution. These documents are: 77 1. [I-D.ietf-netmod-yang-module-versioning] 79 2. [I-D.ietf-netmod-yang-semver] 81 3. [I-D.ietf-netmod-yang-packages] 83 4. [I-D.ietf-netmod-yang-ver-selection] 85 5. [I-D.ietf-netmod-yang-schema-comparison] 87 The aim of this document is to help readers understand how these 88 different solution documents fit together, and also which documents 89 contribute solutions that address particular individual requirements. 91 Open issues, across all of the solution documents are tracked at 92 https://github.com/netmod-wg/yang-ver-dt/issues. 94 2. Solution Documents 96 2.1. Updated YANG Module Revision Handling 98 In summary, [I-D.ietf-netmod-yang-module-versioning] specifies 99 minimal extensions and updates to the YANG language, YANG Library, 100 and YANG author guidelines to provide more flexible YANG module 101 revision handling. The intent is that these changes and extensions 102 could be folded into future revisions of the updated specifications. 103 The document provides a base solution for all requirements except Req 104 2.2, Req 3.1 and Req 3.2. 106 The extensions and changes in the document can be summarized thus: 108 * It defines a YANG extension statement to indicate where non- 109 backwards-compatible changes have occurred in a module's revision 110 history. 112 * It relaxes the rules for the module revision history to allow for 113 a non-linear module revision history. I.e., any given module 114 revision may have multiple revisions directly derived from it. 116 * It defines a new import extension statement that restricts the 117 allowed module revisions that satisfy the import to only those 118 derived from a specified module revision. 120 * It defines a revision label extension statement to allow an 121 informative name to be associated with a particular revision date, 122 and to be used in import statements, YANG module filenames, and is 123 available in YANG library. One example of how the revision label 124 could be used is to associate a semantic versioning scheme to YANG 125 module revisions. 127 * It updates the YANG rules for changes between module revisions 128 that are allowed to be classified as backwards-compatible. In 129 particular, marking a node as obsolete is no longer classified as 130 a backwards compatible change. 132 * It provides updated guidance on how servers handle deprecated and 133 obsolete YANG nodes and augments YANG library with additional 134 leaves to report the server's behavior to clients. 136 * It provides an extension statement to allow a description 137 statement to be associated with a YANG status statement, providing 138 more information about why the status has changed. 140 * It defines how versioning relates to YANG instance data. 142 * It refines the guidelines for updating modules, taking into 143 consideration that non-backwards-compatible changes are sometimes 144 necessary for various pragmatic reasons. 146 2.2. YANG Semantic Versioning 148 [I-D.ietf-netmod-yang-semver] defines a semantic versioning scheme, 149 derived from the semver.org 2.0.0 specification, that can be used in 150 conjunction with the revision label extension statement defined in 151 Section 2.1 to allow semantic version numbers to be used to manage 152 the revision lifecycle of YANG modules and other related YANG assets, 153 e.g., YANG packages. This document provides an enhanced solution for 154 Req 2.1, but organizations authoring modules are not obliged to use 155 this specific versioning scheme, and could choose a different 156 overlaid versioning scheme, or none at all and rely solely on 157 revision dates. 159 The aims of the YANG semantic versioning scheme are: 161 * to generally allow clients to determine whether NBC changes have 162 occurred between two revisions from the version number alone, 163 without having to check the full revision history; 165 * to give a more informative identifier for a branched revision 166 history over revision dates alone; 168 * to allow revision branches that contain fixes for published non- 169 latest releases. 171 2.3. Versioned YANG packages 173 The two previous solution documents primarily address version and 174 revision management of individual modules. 175 [I-D.ietf-netmod-yang-packages] provides a mechanism to group sets of 176 related YANG modules revisions together, into constructs called YANG 177 packages, and to apply a versioning scheme to the groups. 179 The core part of this document are YANG module definitions that 180 define a YANG package. The definitions are used as an augmentation 181 to YANG library and also in YANG instance data documents for offline 182 access. 184 The principle aims of YANG packages are: 186 To define an efficient hierarchical structure that can precisely 187 specify a YANG schema. 189 To provide an simple alternative mechanism to manage conformance 190 of modules. Rather than checking conformance against a set of 191 individual YANG module revisions and enabled features, it should 192 be easier to check for conformance against a much smaller set of 193 YANG package versions. 195 To provide a more efficient mechanism for servers to share 196 conformance information with clients. Rather that downloading and 197 comparing all individual module revisions and features via YANG 198 library, the client can just check whether the package version is 199 compatible instead. The package definition could be retrieved and 200 cached from multiple sources. 202 To define constructs that can be used for YANG schema selection. 204 Although the YANG packages document does not satisfy any versioning 205 requirements directly, it provides foundational building blocks for 206 the schema selection solution, described in Section 2.4, that does 207 address two of the requirements. 209 2.4. Dynamic YANG schema selection 211 [I-D.ietf-netmod-yang-ver-selection] specifies a solution for 212 requirements 3.1 and 3.2 via the use of 213 [I-D.ietf-netmod-yang-packages] and a model and protocol based schema 214 selection scheme that can be used by clients to choose which schemas 215 to use when interacting with the device from the available schema 216 that are supported and advertised by the server. 218 The dynamic YANG schema selection solution: 220 allows servers to define named 'schema-sets' which specify the 221 schema for each supported datastore via references to YANG 222 packages; 224 can support clients choosing a single default schema-set (from 225 those advertised by the server) that is used for all NETCONF/ 226 RESTCONF protocol sessions; 228 can support clients enabling multiple compatible secondary schema- 229 sets that can be used on separate NETCONF/RESTCONF protocol 230 sessions; 232 can support clients configuring named custom schema-sets that can 233 be selected as default or secondary schema-sets; 235 can support different module versions via placing them in 236 different schema-sets; 237 can support different schema families (e.g., IETF YANG modules , 238 native vendor, or OpenConfig); 240 allows considerable freedom in the schema selection capabilities 241 that servers choose to support. 243 2.5. YANG Schema Comparison 245 The final piece of the solution jigsaw is a document that describes 246 how to algorithmically compare YANG schema, addressing Req 2.2. 248 [I-D.ietf-netmod-yang-schema-comparison] specifies an algorithm that 249 can be used to compare two revisions of a YANG schema to determine 250 the overall scope of the changes, and a list of the specific changes, 251 between the two revisions. 253 The YANG Schema Comparison solution: 255 defines a algorithm for comparing two YANG schema, identifying the 256 differences and classifying them as backwards-compatible, non- 257 backwards-compatible or editorial; 259 can be used to compare individual YANG module revisions; 261 can be used to compare YANG schema defined using YANG packages; 263 can filter the comparison output to the subset of the schema nodes 264 that are of interest, providing a more precise answer for clients 265 to determine whether they would likely be affected when upgrading 266 between two schema versions; 268 defines YANG extensions to improve the accuracy of the comparison 269 algorithm by explicitly annotating the type of change to 270 statements within a YANG module, for use where the type of change 271 would otherwise be ambiguous to a simple programmatic comparison 272 algorithm. 274 3. Contributors 276 This document grew out of the YANG module versioning design team that 277 started after IETF 101. The following individuals are (or have been) 278 members of that design team and have contributed to defining the 279 problem, specifying the requirements, and working on a solution: 281 * Balazs Lengyel 283 * Benoit Claise 284 * Ebben Aries 286 * Jason Sterne 288 * Joe Clarke 290 * Juergen Schoenwaelder 292 * Mahesh Jethanandani 294 * Michael (Wangzitao) 296 * Qin Wu 298 * Reshad Rahman 300 * Rob Wilton 302 * Susan Hares 304 * Wu Bo 306 4. Security Considerations 308 The document does not define any new protocol or data model. There 309 is no security impact. 311 5. IANA Considerations 313 None. 315 6. References 317 6.1. Normative References 319 [I-D.ietf-netmod-yang-versioning-reqs] 320 Clarke, J., "YANG Module Versioning Requirements", Work in 321 Progress, Internet-Draft, draft-ietf-netmod-yang- 322 versioning-reqs-03, 29 June 2020, 323 . 326 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 327 RFC 7950, DOI 10.17487/RFC7950, August 2016, 328 . 330 6.2. Informative References 332 [I-D.ietf-netmod-yang-module-versioning] 333 Wilton, R., Rahman, R., Lengyel, B., Clarke, J., Sterne, 334 J., Claise, B., and K. D'Souza, "Updated YANG Module 335 Revision Handling", Work in Progress, Internet-Draft, 336 draft-ietf-netmod-yang-module-versioning-01, 10 July 2020, 337 . 340 [I-D.ietf-netmod-yang-packages] 341 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and W. Bo, 342 "YANG Packages", Work in Progress, Internet-Draft, draft- 343 ietf-netmod-yang-packages-00, 17 March 2020, 344 . 347 [I-D.ietf-netmod-yang-schema-comparison] 348 Wilton, R., "YANG Schema Comparison", Work in Progress, 349 Internet-Draft, draft-ietf-netmod-yang-schema-comparison- 350 00, 17 March 2020, . 353 [I-D.ietf-netmod-yang-semver] 354 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, 355 B., Sterne, J., and K. D'Souza, "YANG Semantic 356 Versioning", Work in Progress, Internet-Draft, draft-ietf- 357 netmod-yang-semver-01, 13 July 2020, 358 . 361 [I-D.ietf-netmod-yang-ver-selection] 362 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and W. Bo, 363 "YANG Schema Selection", Work in Progress, Internet-Draft, 364 draft-ietf-netmod-yang-ver-selection-00, 17 March 2020, 365 . 368 Author's Address 370 Robert Wilton (editor) 371 Cisco Systems, Inc. 373 Email: rwilton@cisco.com