idnits 2.17.1 draft-ietf-netmod-yang-schema-comparison-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 1265 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 513, but not defined == Outdated reference: A later version (-11) 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 (-15) exists of draft-ietf-netmod-yang-semver-01 == Outdated reference: A later version (-01) exists of draft-ietf-netmod-yang-solutions-00 ** Downref: Normative reference to an Informational draft: draft-ietf-netmod-yang-solutions (ref. 'I-D.ietf-netmod-yang-solutions') == Outdated reference: A later version (-09) exists of draft-ietf-netmod-yang-versioning-reqs-03 ** Downref: Normative reference to an Informational draft: draft-ietf-netmod-yang-versioning-reqs (ref. 'I-D.ietf-netmod-yang-versioning-reqs') Summary: 2 errors (**), 0 flaws (~~), 7 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Wilton 3 Internet-Draft Cisco Systems, Inc. 4 Intended status: Standards Track 1 November 2020 5 Expires: 5 May 2021 7 YANG Schema Comparison 8 draft-ietf-netmod-yang-schema-comparison-01 10 Abstract 12 This document specifies an algorithm for comparing two revisions of a 13 YANG schema to determine the scope of changes, and a list of changes, 14 between the revisions. The output of the algorithm can be used to 15 help select an appropriate revision-label or YANG semantic version 16 number for a new revision. This document defines a YANG extension 17 that provides YANG annotations to help the tool accurately determine 18 the scope of changes between two revisions. 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 5 May 2021. 37 Copyright Notice 39 Copyright (c) 2020 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 (https://trustee.ietf.org/ 44 license-info) in effect on the date of publication of this document. 45 Please review these documents carefully, as they describe your rights 46 and restrictions with respect to this document. Code Components 47 extracted from this document must include Simplified BSD License text 48 as described in Section 4.e of the Trust Legal Provisions and are 49 provided without warranty as described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 2. Terminology and Conventions . . . . . . . . . . . . . . . . . 4 55 3. Generic YANG schema tree comparison algorithm . . . . . . . . 4 56 3.1. YANG module revision scope extension annotations . . . . 6 57 4. YANG module comparison algorithm . . . . . . . . . . . . . . 6 58 5. YANG schema comparison algorithms . . . . . . . . . . . . . . 6 59 5.1. Standard YANG schema comparison algorithm . . . . . . . . 6 60 5.2. Filtered YANG schema comparison algorithm . . . . . . . . 7 61 6. Comparison tooling . . . . . . . . . . . . . . . . . . . . . 7 62 7. Module Versioning Extension YANG Modules . . . . . . . . . . 8 63 8. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 11 64 9. Security Considerations . . . . . . . . . . . . . . . . . . . 11 65 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 66 10.1. YANG Module Registrations . . . . . . . . . . . . . . . 11 67 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 68 11.1. Normative References . . . . . . . . . . . . . . . . . . 12 69 11.2. Informative References . . . . . . . . . . . . . . . . . 13 70 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 72 1. Introduction 74 Warning, this is an early (-00) draft with the intention of scoping 75 the outline of the solution, hopefully for the WG to back the 76 direction of the solution. Refinement of the solution details is 77 expected, if this approach is accepted by the WG. 79 This document defines a solution to Requirement 2.2 in 80 [I-D.ietf-netmod-yang-versioning-reqs]. Complementary documents 81 provide a complete solution to the YANG versioning requirements, with 82 the overall relationship of the solution drafts described in 83 [I-D.ietf-netmod-yang-solutions]. 85 YANG module 'revision-labels' 86 [I-D.ietf-netmod-yang-module-versioning] and the use of YANG semantic 87 version numbers [I-D.ietf-netmod-yang-semver] can be used to help 88 manage and report changes between revisions of individual YANG 89 modules. 91 YANG packages [I-D.ietf-netmod-yang-packages] along with YANG 92 semantic version numbers can be used to help manage and report 93 changes between revisions of YANG schema. 95 [I-D.ietf-netmod-yang-module-versioning] and 96 [I-D.ietf-netmod-yang-packages] define how to classify changes 97 between two module or package revisions, respectively, as backwards 98 compatible or non-backwards-compatible. 99 [I-D.ietf-netmod-yang-semver] refines the definition, to allow 100 backwards compatible changes to be classified as 'minor changes' or 101 'editorial changes'. 103 'Revision-label's and YANG semantic version numbers, whilst being 104 generally simple and helpful in the mainline revision history case, 105 are not sufficient in all scenarios. For example, when comparing two 106 revisions/versions on independent revision branches, without a direct 107 ancestor relationship between the two revisions/versions. In this 108 cases, an algorithmic comparison approach is beneficial. 110 In addition, the module revision history's 'nbc-changes' extension 111 statement, and YANG semantic version numbers, effectively declare the 112 worst case scenario. If any non-backwards-compatible changes are 113 restricted to only parts of the module/schema that are not used by an 114 operator, then the operator is able to upgrade, and effectively treat 115 the differences between the two revisions/versions as backwards 116 compatible because they are not materially impacted by the non- 117 backwards-compatible changes. 119 Hence, this document defines algorithms that can be applied to 120 revisions of YANG modules or versions of YANG schema (e.g., as 121 represented by YANG packages), to determine the changes, and scope of 122 changes between the revisions/versions. 124 For many YANG statements, programmatic tooling can determine whether 125 the changes between the statements constitutes a backwards-compatible 126 or non-backwards-compatible change. However, for some statements, it 127 is not feasible for current tooling to determine whether the changes 128 are backwards-compatible or not. For example, in the general case, 129 tooling cannot determine whether the change in a YANG description 130 statement causes a change in the semantics of a YANG data node. If 131 the change is to fix a typo or spelling mistake then the change can 132 be classified as an editorial backwards-compatible change. 133 Conversely, if the change modifies the behavioral specification of 134 the data node then the change would need to be classified as either a 135 non editorial backwards-compatible change or a non-backwards- 136 compatible change. Hence, extension statements are defined to 137 annotate a YANG module with additional information to clarify the 138 scope of changes in cases that cannot be determined by algorithmic 139 comparison. 141 Open issues are tracked at https://github.com/netmod-wg/yang-ver-dt/ 142 issues, tagged with 'schema-comparison'. 144 2. Terminology and Conventions 146 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 147 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 148 "OPTIONAL" in this document are to be interpreted as described in BCP 149 14 [RFC2119] [RFC8174] when, and only when, they appear in all 150 capitals, as shown here. 152 This document uses terminology introduced in the YANG versioning 153 requirements document [I-D.ietf-netmod-yang-versioning-reqs]. 155 This document makes of the following terminology introduced in the 156 YANG Packages [I-D.ietf-netmod-yang-packages]: 158 * YANG schema 160 In addition, this document defines the terminology: 162 * Change scope: Whether a change between two revisions is classified 163 as non-backwards-compatible, backwards-compatible, or editorial. 165 3. Generic YANG schema tree comparison algorithm 167 The generic schema comparison algorithm works on any YANG schema. 168 This could be a schema associated with an individual YANG module, or 169 a YANG schema represented by a set of modules, e.g., specified by a 170 YANG package. 172 The algorithm performs a recursive tree wise comparison of two 173 revisions of a YANG schema, with the following behavior: 175 The comparison algorithm primarily acts on the parts of the schema 176 defined by unique identifiers. 178 Each identifier is qualified with the name of the module that 179 defines the identifier. 181 Identifiers in different namespaces (as defined in 6.2.1 or RFC 182 7950) are compared separately. E.g., 'features' are compared 183 separately from 'identities'. 185 Within an identifier namespace, the identifiers are compared 186 between the two schema revisions by qualified identifier name. 187 The 'renamed-from' extension allow for a meaningful comparison 188 where the name of the identifier has changed between revisions. 189 The 'renamed-from' identifier parameter is only used when an 190 identifier in the new schema revision cannot be found in the old 191 schema revision. 193 YANG extensions, features, identities, typedefs are checked by 194 comparing the properties defined by their YANG sub-statements 195 between the two revisions. 197 YANG groupings, top-level data definition statements, rpcs, and 198 notifications are checked by comparing the top level properties 199 defined by their direct child YANG sub-statements, and also by 200 recursively checking the data definition statements. 202 The rules specified in section 3 of 203 [I-D.ietf-netmod-yang-module-versioning] determine whether the 204 changes are backwards-compatible or non-backwards-compatible. 206 The rules specified in section 3.2 of 207 [I-D.ietf-netmod-yang-packages] determine whether backwards- 208 compatible changes are 'minor' or 'editorial'. 210 For YANG description", "must", and "when" statements, the 211 "backwards-compatible" and "editorial" extension statements can be 212 used to mark instances when the statements have changed in a 213 backwards-compatible or editorial way. Since by default the 214 comparison algorithm assumes that any changes in these statements 215 are non-backwards-compatible. XXX, more info required here, since 216 the revisions in the module history probably need to be available 217 for this to work in the general branched revisions case. 219 Submodules are not relevant for schema comparison purposes, i.e. 220 the comparison is performed after submodule resolution has been 221 completed. 223 3.1. YANG module revision scope extension annotations 225 4. YANG module comparison algorithm 227 The schema comparison algorithm defined in Section 3 can be used to 228 compare the schema for individual modules, but with the following 229 modifications: 231 Changes to the module's metadata information (i.e. module level 232 description, contact, organization, reference) should be checked 233 (as potential editorial changes). 235 The module's revision history should be ignored from the 236 comparison. 238 Changes to augmentations and deviations should be sorted by path 239 and compared. 241 5. YANG schema comparison algorithms 243 5.1. Standard YANG schema comparison algorithm 245 The standard method for comparing two YANG schema versions is to 246 individually compare the module revisions for each module implemented 247 by the schema using the algorithm defined in Section 4 and then 248 aggregating the results together: 250 * If all implemented modules in the schema have only changed in an 251 editorial way then the schema is changed in an editorial way 253 * If all implemented modules in the schema have only been changed in 254 an editorial or backwards-compatible way then the schema is 255 changed in a backwards-compatible way 257 * Otherwise if any implemented module in the schema has been changed 258 in a non-backwards-compatible way then the schema is changed in a 259 non-backwards-compatible way. 261 The standard schema comparison method is the RECOMMENDED scheme to 262 calculate the version number change for new versions of YANG 263 packages, because it allows the package version to be calculated 264 based on changes to implemented modules revision history (or YANG 265 semantic version number if used to identify module revisions). 267 5.2. Filtered YANG schema comparison algorithm 269 Another method to compare YANG schema, that is less likely to report 270 inconsequential differences, is to construct full schema trees for 271 the two schema versions, directly apply a version of the comparison 272 algorithm defined in Section 3. This may be particular useful when 273 the schema represents a complete datastore schema for a server 274 because it allows various filtered to the comparison algorithm to 275 provide a more specific answer about what changes may impact a 276 particular client. 278 The full schema tree can easily be constructed from a YANG package 279 definition, or alternative YANG schema definition. 281 Controlled by input parameters to the comparison algorithm, the 282 following parts of the schema trees can optionally be filtered during 283 the comparison: 285 All "grouping" statements can be ignored (after all "use" 286 statements have been processed when constructing the schema). 288 All module and submodule metadata information (i.e. module level 289 description, contact, organization, reference) can be ignored. 291 The comparison can be restricted to the set of features that are 292 of interest (different sets of features may apply to each schema 293 versions). 295 The comparison can be restricted to the subset of data nodes, 296 RPCs, notifications and actions, that are of interest (e.g., the 297 subset actually used by a particular client), providing a more 298 meaningful result. 300 The comparison could filter out backwards-compatible 'editorial' 301 changes. 303 In addition to reporting the overall scope of changes at the schema 304 level, the algorithm output can also optionally generate a list of 305 specific changes between the two schema, along with the 306 classification of those individual changes. 308 6. Comparison tooling 310 'pyang' has some support for comparison two module revisions, but 311 this is currently limited to a linear module history. 313 TODO, it would be helpful if there is reference tooling for schema 314 comparison. 316 7. Module Versioning Extension YANG Modules 318 YANG module with extension statements for annotating NBC changes, 319 revision label, status description, and importing by version. 321 file "ietf-yang-rev-annotations@2019-11-11.yang" 322 module ietf-yang-rev-annotations { 323 yang-version 1.1; 324 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-rev-annotations"; 325 prefix rev-ext; 327 organization 328 "IETF NETMOD (Network Modeling) Working Group"; 329 contact 330 "WG Web: 331 WG List: 333 Author: Robert Wilton 334 "; 336 description 337 "This YANG 1.1 module contains extensions to annotation to YANG 338 module with additional metadata information on the nature of 339 changes between two YANG module revisions. 341 XXX, maybe these annotations could also be included in 342 ietf-yang-revisions? 344 Copyright (c) 2019 IETF Trust and the persons identified as 345 authors of the code. All rights reserved. 347 Redistribution and use in source and binary forms, with or 348 without modification, is permitted pursuant to, and subject 349 to the license terms contained in, the Simplified BSD License 350 set forth in Section 4.c of the IETF Trust's Legal Provisions 351 Relating to IETF Documents 352 (http://trustee.ietf.org/license-info). 354 This version of this YANG module is part of RFC XXXX; see 355 the RFC itself for full legal notices. 357 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 358 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 359 'MAY', and 'OPTIONAL' in this document are to be interpreted as 360 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 361 they appear in all capitals, as shown here."; 363 // RFC Ed.: update the date below with the date of RFC publication 364 // and remove this note. 365 // RFC Ed.: replace XXXX (inc above) with actual RFC number and 366 // remove this note. 368 revision 2019-11-11 { 369 description 370 "Initial version."; 371 reference 372 "XXXX: YANG Schema Comparison"; 373 } 375 extension backwards-compatible { 376 argument revision-date-or-label; 377 description 378 "Identifies a revision (by revision-label, or revision date if 379 a revision-label is not available) where a 380 backwards-compatible change has occurred relative to the 381 previous revision listed in the revision history. 383 The format of the revision-label argument MUST conform to the 384 pattern defined for the ietf-yang-revisions 385 revision-date-or-label typedef. 387 The following YANG statements MAY have zero or more 388 'rev-ext:non-backwards-compatible' statements: 389 description 390 must 391 when 393 Each YANG statement MUST only a have a single 394 non-backwards-compatible, backwards-compatible, or editorial 395 extension statement for a particular revision-label, or 396 corresponding revision-date."; 398 reference 399 "XXXX: YANG Schema Comparison; 400 Section XXX, XXX"; 401 } 403 extension editorial { 404 argument revision-date-or-label; 405 description 406 "Identifies a revision (by revision-label, or revision date if 407 a revision-label is not available) where an editorial change 408 has occurred relative to the previous revision listed in the 409 revision history. 411 The format of the revision-label argument MUST conform to the 412 pattern defined for the ietf-yang-revisions 413 revision-date-or-label typedef. 415 The following YANG statements MAY have zero or more 416 'rev-ext:non-backwards-compatible' statements: 417 description 419 Each YANG statement MUST only a have a single 420 non-backwards-compatible, backwards-compatible, or editorial 421 extension statement for a particular revision-label or 422 corresponding revision-date."; 424 reference 425 "XXXX: YANG Schema Comparison; 426 Section XXX, XXX"; 427 } 429 extension renamed-from { 430 argument yang-identifier; 431 description 432 "Specifies a previous name for this identifier. 434 This can be used when comparing schema to optimize handling 435 for data nodes that have been renamed rather than naively 436 treated them as data nodes that have been deleted and 437 recreated. 439 The argument 'yang-identifier' MUST take the form of a YANG 440 identifier, as defined in section 6.2 of RFC 7950. 442 Any YANG statement that takes a YANG identifier as its 443 argument MAY have a single 'rev-ext:renamed-from' 444 sub-statement. 446 TODO, we should also facilitate identifiers being moved into 447 other modules, e.g. by supporting a module-name qualified 448 identifier."; 450 reference 451 "XXXX: YANG Schema Comparison; 452 Section XXX, XXX"; 453 } 454 } 455 457 8. Contributors 459 This document grew out of the YANG module versioning design team that 460 started after IETF 101. The following individuals are (or have been) 461 members of the design team and have worked on the YANG versioning 462 project: 464 * Balazs Lengyel 466 * Benoit Claise 468 * Bo Wu 470 * Ebben Aries 472 * Jason Sterne 474 * Joe Clarke 476 * Juergen Schoenwaelder 478 * Mahesh Jethanandani 480 * Michael Wang 482 * Qin Wu 484 * Reshad Rahman 486 * Rob Wilton 488 The ideas for a tooling based comparison of YANG module revisions was 489 first described in [I-D.clacla-netmod-yang-model-update]. This 490 document extends upon those initial ideas. 492 9. Security Considerations 494 The document does not define any new protocol or data model. There 495 are no security impacts. 497 10. IANA Considerations 499 10.1. YANG Module Registrations 501 The following YANG module is requested to be registered in the "IANA 502 Module Names" registry: 504 The ietf-yang-rev-annotations module: 506 Name: ietf-yang-rev-annotations 508 XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-rev- 509 annotations 511 Prefix: rev-ext 513 Reference: [RFCXXXX] 515 11. References 517 11.1. Normative References 519 [I-D.ietf-netmod-yang-module-versioning] 520 Wilton, R., Rahman, R., Lengyel, B., Clarke, J., Sterne, 521 J., Claise, B., and K. D'Souza, "Updated YANG Module 522 Revision Handling", Work in Progress, Internet-Draft, 523 draft-ietf-netmod-yang-module-versioning-01, 10 July 2020, 524 . 527 [I-D.ietf-netmod-yang-packages] 528 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and W. Bo, 529 "YANG Packages", Work in Progress, Internet-Draft, draft- 530 ietf-netmod-yang-packages-00, 17 March 2020, 531 . 534 [I-D.ietf-netmod-yang-semver] 535 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, 536 B., Sterne, J., and K. D'Souza, "YANG Semantic 537 Versioning", Work in Progress, Internet-Draft, draft-ietf- 538 netmod-yang-semver-01, 13 July 2020, 539 . 542 [I-D.ietf-netmod-yang-solutions] 543 Wilton, R., "YANG Versioning Solution Overview", Work in 544 Progress, Internet-Draft, draft-ietf-netmod-yang- 545 solutions-00, 19 March 2020, . 548 [I-D.ietf-netmod-yang-versioning-reqs] 549 Clarke, J., "YANG Module Versioning Requirements", Work in 550 Progress, Internet-Draft, draft-ietf-netmod-yang- 551 versioning-reqs-03, 29 June 2020, 552 . 555 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 556 Requirement Levels", BCP 14, RFC 2119, 557 DOI 10.17487/RFC2119, March 1997, 558 . 560 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 561 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 562 May 2017, . 564 11.2. Informative References 566 [I-D.clacla-netmod-yang-model-update] 567 Claise, B., Clarke, J., Lengyel, B., and K. D'Souza, "New 568 YANG Module Update Procedure", Work in Progress, Internet- 569 Draft, draft-clacla-netmod-yang-model-update-06, 2 July 570 2018, . 573 Author's Address 575 Robert Wilton 576 Cisco Systems, Inc. 578 Email: rwilton@cisco.com