idnits 2.17.1 draft-verdt-netmod-yang-schema-comparison-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 (November 16, 2019) is 1622 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 == Unused Reference: 'RFC7895' is defined on line 550, but no explicit reference was found in the text == Unused Reference: 'RFC7950' is defined on line 554, but no explicit reference was found in the text == Unused Reference: 'RFC8407' is defined on line 562, but no explicit reference was found in the text == Unused Reference: 'RFC8525' is defined on line 567, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-netmod-yang-instance-file-format' is defined on line 579, but no explicit reference was found in the text == Unused Reference: 'RFC8340' is defined on line 584, but no explicit reference was found in the text == Outdated reference: A later version (-03) exists of draft-rwilton-netmod-yang-packages-02 == Outdated reference: A later version (-03) exists of draft-verdt-netmod-yang-solutions-01 ** Downref: Normative reference to an Informational draft: draft-verdt-netmod-yang-solutions (ref. 'I-D.verdt-netmod-yang-solutions') ** 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-04 Summary: 3 errors (**), 0 flaws (~~), 11 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 November 16, 2019 5 Expires: May 19, 2020 7 YANG Schema Comparison 8 draft-verdt-netmod-yang-schema-comparison-00 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 May 19, 2020. 37 Copyright Notice 39 Copyright (c) 2019 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. Terminology and Conventions . . . . . . . . . . . . . . . . . 4 56 3. Generic YANG schema tree comparison algorithm . . . . . . . . 4 57 3.1. YANG module revision scope extension annotations . . . . 5 58 4. YANG module comparison algorithm . . . . . . . . . . . . . . 5 59 5. YANG schema comparison algorithms . . . . . . . . . . . . . . 6 60 5.1. Standard YANG schema comparison algorithm . . . . . . . . 6 61 5.2. Filtered YANG schema comparison algorithm . . . . . . . . 6 62 6. Comparison tooling . . . . . . . . . . . . . . . . . . . . . 7 63 7. Module Versioning Extension YANG Modules . . . . . . . . . . 7 64 8. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 10 65 9. Security Considerations . . . . . . . . . . . . . . . . . . . 11 66 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 67 10.1. YANG Module Registrations . . . . . . . . . . . . . . . 11 68 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 69 11.1. Normative References . . . . . . . . . . . . . . . . . . 11 70 11.2. Informative References . . . . . . . . . . . . . . . . . 12 71 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 73 1. Introduction 75 Warning, this is an early (-00) draft with the intention of scoping 76 the outline of the solution, hopefully for the WG to back the 77 direction of the solution. Refinement of the solution details is 78 expected, if this approach is accepted by the WG. 80 This document defines a solution to Requirement 2.2 in 81 [I-D.verdt-netmod-yang-versioning-reqs]. Complementary documents 82 provide a complete solution to the YANG versioning requirements, with 83 the overall relationship of the solution drafts described in 84 [I-D.verdt-netmod-yang-solutions]. 86 YANG module 'revision-labels' 87 [I-D.verdt-netmod-yang-module-versioning] and the use of YANG 88 semantic version numbers [I-D.verdt-netmod-yang-semver] can be used 89 to help manage and report changes between revisions of individual 90 YANG modules. 92 YANG packages [I-D.rwilton-netmod-yang-packages] along with YANG 93 semantic version numbers can be used to help manage and report 94 changes between revisions of YANG schema. 96 [I-D.verdt-netmod-yang-module-versioning] and 97 [I-D.rwilton-netmod-yang-packages] define how to classify changes 98 between two module or package revisions, respectively, as backwards 99 compatible or non-backwards-compatible. 100 [I-D.verdt-netmod-yang-semver] refines the definition, to allow 101 backwards compatible changes to be classified as 'minor changes' or 102 'editorial changes'. 104 'Revision-label's and YANG semantic version numbers, whilst being 105 generally simple and helpful in the mainline revision history case, 106 are not sufficient in all scenarios. For example, when comparing two 107 revisions/versions on independent revision branches, without a direct 108 ancestor relationship between the two revisions/versions. In this 109 cases, an algorithmic comparison approach is beneficial. 111 In addition, the module revision history's 'nbc-changes' extension 112 statement, and YANG semantic version numbers, effectively declare the 113 worst case scenario. If any non-backwards-compatible changes are 114 restricted to only parts of the module/schema that are not used by an 115 operator, then the operator is able to upgrade, and effectively treat 116 the differences between the two revisions/versions as backwards 117 compatible because they are not materially impacted by the non- 118 backwards-compatible changes. 120 Hence, this document defines algorithms that can be applied to 121 revisions of YANG modules or versions of YANG schema (e.g., as 122 represented by YANG packages), to determine the changes, and scope of 123 changes between the revisions/versions. 125 For many YANG statements, programmatic tooling can determine whether 126 the changes between the statements constitutes a backwards-compatible 127 or non-backwards-compatible change. However, for some statements, it 128 is not feasible for current tooling to determine whether the changes 129 are backwards-compatible or not. For example, in the general case, 130 tooling cannot determine whether the change in a YANG description 131 statement causes a change in the semantics of a YANG data node. If 132 the change is to fix a typo or spelling mistake then the change can 133 be classified as an editorial backwards-compatible change. 134 Conversely, if the change modifies the behavioral specification of 135 the data node then the change would need to be classified as either a 136 non editorial backwards-compatible change or a non-backwards- 137 compatible change. Hence, extension statements are defined to 138 annotate a YANG module with additional information to clarify the 139 scope of changes in cases that cannot be determined by algorithmic 140 comparison. 142 Open issues are tracked at , tagged with 'schema-comparison'. 145 2. Terminology and Conventions 147 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 148 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 149 "OPTIONAL" in this document are to be interpreted as described in BCP 150 14 [RFC2119] [RFC8174] when, and only when, they appear in all 151 capitals, as shown here. 153 This document uses terminology introduced in the YANG versioning 154 requirements document [I-D.verdt-netmod-yang-versioning-reqs]. 156 This document makes of the following terminology introduced in the 157 YANG Packages [I-D.rwilton-netmod-yang-packages]: 159 o YANG schema 161 In addition, this document defines the terminology: 163 o Change scope: Whether a change between two revisions is classified 164 as non-backwards-compatible, backwards-compatible, or editorial. 166 3. Generic YANG schema tree comparison algorithm 168 The generic schema comparison algorithm works on any YANG schema. 169 This could be a schema associated with an individual YANG module, or 170 a YANG schema represented by a set of modules, e.g., specified by a 171 YANG package. 173 The algorithm performs a recursive tree wise comparison of two 174 revisions of a YANG schema, with the following behavior: 176 The comparison algorithm primarily acts on the parts of the schema 177 defined by unique identifiers. 179 Each identifier is qualified with the name of the module that 180 defines the identifier. 182 Identifiers in different namespaces (as defined in 6.2.1 or RFC 183 7950) are compared separately. E.g., 'features' are compared 184 separately from 'identities'. 186 Within an identifier namespace, the identifiers are compared 187 between the two schema revisions by qualified identifier name. 188 The 'renamed-from' extension allow for a meaningful comparison 189 where the name of the identifier has changed between revisions. 190 The 'renamed-from' identifier parameter is only used when an 191 identifier in the new schema revision cannot be found in the old 192 schema revision. 194 YANG extensions, features, identities, typedefs are checked by 195 comparing the properties defined by their YANG sub-statements 196 between the two revisions. 198 YANG groupings, top-level data definition statements, rpcs, and 199 notifications are checked by comparing the top level properties 200 defined by their direct child YANG sub-statements, and also by 201 recursively checking the data definition statements. 203 The rules specified in section 3 of 204 [I-D.verdt-netmod-yang-module-versioning] determine whether the 205 changes are backwards-compatible or non-backwards-compatible. 207 The rules specified in section 3.2 of 208 [I-D.rwilton-netmod-yang-packages] determine whether backwards- 209 compatible changes are 'minor' or 'editorial'. 211 For YANG description", "must", and "when" statements, the 212 "backwards-compatible" and "editorial" extension statements can be 213 used to mark instances when the statements have changed in a 214 backwards-compatible or editorial way. Since by default the 215 comparison algorithm assumes that any changes in these statements 216 are non-backwards-compatible. XXX, more info required here, since 217 the revisions in the module history probably need to be available 218 for this to work in the general branched revisions case. 220 Submodules are not relevant for schema comparison purposes, i.e. 221 the comparison is performed after submodule resolution has been 222 completed. 224 3.1. YANG module revision scope extension annotations 226 4. YANG module comparison algorithm 228 The schema comparison algorithm defined in Section 3 can be used to 229 compare the schema for individual modules, but with the following 230 modifications: 232 Changes to the module's metadata information (i.e. module level 233 description, contact, organization, reference) should be checked 234 (as potential editorial changes). 236 The module's revision history should be ignored from the 237 comparison. 239 Changes to augmentations and deviations should be sorted by path 240 and compared. 242 5. YANG schema comparison algorithms 244 5.1. Standard YANG schema comparison algorithm 246 The standard method for comparing two YANG schema versions is to 247 individually compare the module revisions for each module implemented 248 by the schema using the algorithm defined in Section 4 and then 249 aggregating the results together: 251 o If all implemented modules in the schema have only changed in an 252 editorial way then the schema is changed in an editorial way 254 o If all implemented modules in the schema have only been changed in 255 an editorial or backwards-compatible way then the schema is 256 changed in a backwards-compatible way 258 o Otherwise if any implemented module in the schema has been changed 259 in a non-backwards-compatible way then the schema is changed in a 260 non-backwards-compatible way. 262 The standard schema comparison method is the RECOMMENDED scheme to 263 calculate the version number change for new versions of YANG 264 packages, because it allows the package version to be calculated 265 based on changes to implemented modules revision history (or YANG 266 semantic version number if used to identify module revisions). 268 5.2. Filtered YANG schema comparison algorithm 270 Another method to compare YANG schema, that is less likely to report 271 inconsequential differences, is to construct full schema trees for 272 the two schema versions, directly apply a version of the comparison 273 algorithm defined in Section 3. This may be particular useful when 274 the schema represents a complete datastore schema for a server 275 because it allows various filtered to the comparison algorithm to 276 provide a more specific answer about what changes may impact a 277 particular client. 279 The full schema tree can easily be constructed from a YANG package 280 definition, or alternative YANG schema definition. 282 Controlled by input parameters to the comparison algorithm, the 283 following parts of the schema trees can optionally be filtered during 284 the comparison: 286 All "grouping" statements can be ignored (after all "use" 287 statements have been processed when constructing the schema). 289 All module and submodule metadata information (i.e. module level 290 description, contact, organization, reference) can be ignored. 292 The comparison can be restricted to the set of features that are 293 of interest (different sets of features may apply to each schema 294 versions). 296 The comparison can be restricted to the subset of data nodes, 297 RPCs, notifications and actions, that are of interest (e.g., the 298 subset actually used by a particular client), providing a more 299 meaningful result. 301 The comparison could filter out backwards-compatible 'editorial' 302 changes. 304 In addition to reporting the overall scope of changes at the schema 305 level, the algorithm output can also optionally generate a list of 306 specific changes between the two schema, along with the 307 classification of those individual changes. 309 6. Comparison tooling 311 'pyang' has some support for comparison two module revisions, but 312 this is currently limited to a linear module history. 314 TODO, it would be helpful if there is reference tooling for schema 315 comparison. 317 7. Module Versioning Extension YANG Modules 319 YANG module with extension statements for annotating NBC changes, 320 revision label, status description, and importing by version. 322 file "ietf-yang-rev-annotations@2019-11-11.yang" 323 module ietf-yang-rev-annotations { 324 yang-version 1.1; 325 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-rev-annotations"; 326 prefix rev-ext; 328 organization 329 "IETF NETMOD (Network Modeling) Working Group"; 330 contact 331 "WG Web: 332 WG List: 334 Author: Robert Wilton 335 "; 337 description 338 "This YANG 1.1 module contains extensions to annotation to YANG 339 module with additional metadata information on the nature of 340 changes between two YANG module revisions. 342 XXX, maybe these annotations could also be included in 343 ietf-yang-revisions? 345 Copyright (c) 2019 IETF Trust and the persons identified as 346 authors of the code. All rights reserved. 348 Redistribution and use in source and binary forms, with or 349 without modification, is permitted pursuant to, and subject 350 to the license terms contained in, the Simplified BSD License 351 set forth in Section 4.c of the IETF Trust's Legal Provisions 352 Relating to IETF Documents 353 (http://trustee.ietf.org/license-info). 355 This version of this YANG module is part of RFC XXXX; see 356 the RFC itself for full legal notices. 358 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 359 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 360 'MAY', and 'OPTIONAL' in this document are to be interpreted as 361 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 362 they appear in all capitals, as shown here."; 364 // RFC Ed.: update the date below with the date of RFC publication 365 // and remove this note. 366 // RFC Ed.: replace XXXX (inc above) with actual RFC number and 367 // remove this note. 369 revision 2019-11-11 { 370 description 371 "Initial version."; 372 reference 373 "XXXX: YANG Schema Comparison"; 374 } 376 extension backwards-compatible { 377 argument revision-date-or-label; 378 description 379 "Identifies a revision (by revision-label, or revision date if 380 a revision-label is not available) where a 381 backwards-compatible change has occurred relative to the 382 previous revision listed in the revision history. 384 The format of the revision-label argument MUST conform to the 385 pattern defined for the ietf-yang-revisions 386 revision-date-or-label typedef. 388 The following YANG statements MAY have zero or more 389 'rev-ext:non-backwards-compatible' statements: 390 description 391 must 392 when 394 Each YANG statement MUST only a have a single 395 non-backwards-compatible, backwards-compatible, or editorial 396 extension statement for a particular revision-label, or 397 corresponding revision-date."; 399 reference 400 "XXXX: YANG Schema Comparison; 401 Section XXX, XXX"; 402 } 404 extension editorial { 405 argument revision-date-or-label; 406 description 407 "Identifies a revision (by revision-label, or revision date if 408 a revision-label is not available) where an editorial change 409 has occurred relative to the previous revision listed in the 410 revision history. 412 The format of the revision-label argument MUST conform to the 413 pattern defined for the ietf-yang-revisions 414 revision-date-or-label typedef. 416 The following YANG statements MAY have zero or more 417 'rev-ext:non-backwards-compatible' statements: 418 description 420 Each YANG statement MUST only a have a single 421 non-backwards-compatible, backwards-compatible, or editorial 422 extension statement for a particular revision-label or 423 corresponding revision-date."; 425 reference 426 "XXXX: YANG Schema Comparison; 427 Section XXX, XXX"; 428 } 430 extension renamed-from { 431 argument yang-identifier; 432 description 433 "Specifies a previous name for this identifier. 435 This can be used when comparing schema to optimize handling 436 for data nodes that have been renamed rather than naively 437 treated them as data nodes that have been deleted and 438 recreated. 440 The argument 'yang-identifier' MUST take the form of a YANG 441 identifier, as defined in section 6.2 of RFC 7950. 443 Any YANG statement that takes a YANG identifier as its 444 argument MAY have a single 'rev-ext:renamed-from' 445 sub-statement. 447 TODO, we should also facilitate identifiers being moved into 448 other modules, e.g. by supporting a module-name qualified 449 identifier."; 451 reference 452 "XXXX: YANG Schema Comparison; 453 Section XXX, XXX"; 454 } 455 } 456 458 8. Contributors 460 This document grew out of the YANG module versioning design team that 461 started after IETF 101. The following individuals are (or have been) 462 members of the design team and have worked on the YANG versioning 463 project: 465 o Balazs Lengyel 467 o Benoit Claise 469 o Bo Wu 471 o Ebben Aries 473 o Jason Sterne 475 o Joe Clarke 477 o Juergen Schoenwaelder 479 o Mahesh Jethanandani 480 o Michael Wang 482 o Qin Wu 484 o Reshad Rahman 486 o 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.rwilton-netmod-yang-packages] 520 Wilton, R., "YANG Packages", draft-rwilton-netmod-yang- 521 packages-02 (work in progress), October 2019. 523 [I-D.verdt-netmod-yang-module-versioning] 524 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, 525 B., Sterne, J., and K. D'Souza, "Updated YANG Module 526 Revision Handling", draft-verdt-netmod-yang-module- 527 versioning-01 (work in progress), October 2019. 529 [I-D.verdt-netmod-yang-semver] 530 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, 531 B., Sterne, J., and K. D'Souza, "YANG Semantic 532 Versioning", draft-verdt-netmod-yang-semver-01 (work in 533 progress), October 2019. 535 [I-D.verdt-netmod-yang-solutions] 536 Wilton, R., "YANG Versioning Solution Overview", draft- 537 verdt-netmod-yang-solutions-01 (work in progress), July 538 2019. 540 [I-D.verdt-netmod-yang-versioning-reqs] 541 Clarke, J., "YANG Module Versioning Requirements", draft- 542 verdt-netmod-yang-versioning-reqs-02 (work in progress), 543 November 2018. 545 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 546 Requirement Levels", BCP 14, RFC 2119, 547 DOI 10.17487/RFC2119, March 1997, 548 . 550 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 551 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 552 . 554 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 555 RFC 7950, DOI 10.17487/RFC7950, August 2016, 556 . 558 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 559 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 560 May 2017, . 562 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 563 Documents Containing YANG Data Models", BCP 216, RFC 8407, 564 DOI 10.17487/RFC8407, October 2018, 565 . 567 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 568 and R. Wilton, "YANG Library", RFC 8525, 569 DOI 10.17487/RFC8525, March 2019, 570 . 572 11.2. Informative References 574 [I-D.clacla-netmod-yang-model-update] 575 Claise, B., Clarke, J., Lengyel, B., and K. D'Souza, "New 576 YANG Module Update Procedure", draft-clacla-netmod-yang- 577 model-update-06 (work in progress), July 2018. 579 [I-D.ietf-netmod-yang-instance-file-format] 580 Lengyel, B. and B. Claise, "YANG Instance Data File 581 Format", draft-ietf-netmod-yang-instance-file-format-04 582 (work in progress), August 2019. 584 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 585 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 586 . 588 [semver] "Semantic Versioning 2.0.0", . 590 Author's Address 592 Robert Wilton 593 Cisco Systems, Inc. 595 Email: rwilton@cisco.com