draft-ietf-netmod-yang-schema-comparison-00.txt   draft-ietf-netmod-yang-schema-comparison-01.txt 
Network Working Group R. Wilton Network Working Group R. Wilton
Internet-Draft Cisco Systems, Inc. Internet-Draft Cisco Systems, Inc.
Intended status: Standards Track March 17, 2020 Intended status: Standards Track 1 November 2020
Expires: September 18, 2020 Expires: 5 May 2021
YANG Schema Comparison YANG Schema Comparison
draft-ietf-netmod-yang-schema-comparison-00 draft-ietf-netmod-yang-schema-comparison-01
Abstract Abstract
This document specifies an algorithm for comparing two revisions of a This document specifies an algorithm for comparing two revisions of a
YANG schema to determine the scope of changes, and a list of changes, YANG schema to determine the scope of changes, and a list of changes,
between the revisions. The output of the algorithm can be used to between the revisions. The output of the algorithm can be used to
help select an appropriate revision-label or YANG semantic version help select an appropriate revision-label or YANG semantic version
number for a new revision. This document defines a YANG extension number for a new revision. This document defines a YANG extension
that provides YANG annotations to help the tool accurately determine that provides YANG annotations to help the tool accurately determine
the scope of changes between two revisions. the scope of changes between two revisions.
skipping to change at page 1, line 36 skipping to change at page 1, line 36
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 18, 2020. This Internet-Draft will expire on 5 May 2021.
Copyright Notice Copyright Notice
Copyright (c) 2020 IETF Trust and the persons identified as the Copyright (c) 2020 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents (https://trustee.ietf.org/
(https://trustee.ietf.org/license-info) in effect on the date of license-info) in effect on the date of publication of this document.
publication of this document. Please review these documents Please review these documents carefully, as they describe your rights
carefully, as they describe your rights and restrictions with respect and restrictions with respect to this document. Code Components
to this document. Code Components extracted from this document must extracted from this document must include Simplified BSD License text
include Simplified BSD License text as described in Section 4.e of as described in Section 4.e of the Trust Legal Provisions and are
the Trust Legal Provisions and are provided without warranty as provided without warranty as described in the Simplified BSD License.
described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology and Conventions . . . . . . . . . . . . . . . . . 4 2. Terminology and Conventions . . . . . . . . . . . . . . . . . 4
3. Generic YANG schema tree comparison algorithm . . . . . . . . 4 3. Generic YANG schema tree comparison algorithm . . . . . . . . 4
3.1. YANG module revision scope extension annotations . . . . 5 3.1. YANG module revision scope extension annotations . . . . 6
4. YANG module comparison algorithm . . . . . . . . . . . . . . 5 4. YANG module comparison algorithm . . . . . . . . . . . . . . 6
5. YANG schema comparison algorithms . . . . . . . . . . . . . . 6 5. YANG schema comparison algorithms . . . . . . . . . . . . . . 6
5.1. Standard YANG schema comparison algorithm . . . . . . . . 6 5.1. Standard YANG schema comparison algorithm . . . . . . . . 6
5.2. Filtered YANG schema comparison algorithm . . . . . . . . 6 5.2. Filtered YANG schema comparison algorithm . . . . . . . . 7
6. Comparison tooling . . . . . . . . . . . . . . . . . . . . . 7 6. Comparison tooling . . . . . . . . . . . . . . . . . . . . . 7
7. Module Versioning Extension YANG Modules . . . . . . . . . . 7 7. Module Versioning Extension YANG Modules . . . . . . . . . . 8
8. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 10 8. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 11
9. Security Considerations . . . . . . . . . . . . . . . . . . . 11 9. Security Considerations . . . . . . . . . . . . . . . . . . . 11
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
10.1. YANG Module Registrations . . . . . . . . . . . . . . . 11 10.1. YANG Module Registrations . . . . . . . . . . . . . . . 11
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 12
11.1. Normative References . . . . . . . . . . . . . . . . . . 11 11.1. Normative References . . . . . . . . . . . . . . . . . . 12
11.2. Informative References . . . . . . . . . . . . . . . . . 13 11.2. Informative References . . . . . . . . . . . . . . . . . 13
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13
1. Introduction 1. Introduction
Warning, this is an early (-00) draft with the intention of scoping Warning, this is an early (-00) draft with the intention of scoping
the outline of the solution, hopefully for the WG to back the the outline of the solution, hopefully for the WG to back the
direction of the solution. Refinement of the solution details is direction of the solution. Refinement of the solution details is
expected, if this approach is accepted by the WG. expected, if this approach is accepted by the WG.
This document defines a solution to Requirement 2.2 in This document defines a solution to Requirement 2.2 in
[I-D.verdt-netmod-yang-versioning-reqs]. Complementary documents [I-D.ietf-netmod-yang-versioning-reqs]. Complementary documents
provide a complete solution to the YANG versioning requirements, with provide a complete solution to the YANG versioning requirements, with
the overall relationship of the solution drafts described in the overall relationship of the solution drafts described in
[I-D.verdt-netmod-yang-solutions]. [I-D.ietf-netmod-yang-solutions].
YANG module 'revision-labels' YANG module 'revision-labels'
[I-D.verdt-netmod-yang-module-versioning] and the use of YANG [I-D.ietf-netmod-yang-module-versioning] and the use of YANG semantic
semantic version numbers [I-D.verdt-netmod-yang-semver] can be used version numbers [I-D.ietf-netmod-yang-semver] can be used to help
to help manage and report changes between revisions of individual manage and report changes between revisions of individual YANG
YANG modules. modules.
YANG packages [I-D.rwilton-netmod-yang-packages] along with YANG YANG packages [I-D.ietf-netmod-yang-packages] along with YANG
semantic version numbers can be used to help manage and report semantic version numbers can be used to help manage and report
changes between revisions of YANG schema. changes between revisions of YANG schema.
[I-D.verdt-netmod-yang-module-versioning] and [I-D.ietf-netmod-yang-module-versioning] and
[I-D.rwilton-netmod-yang-packages] define how to classify changes [I-D.ietf-netmod-yang-packages] define how to classify changes
between two module or package revisions, respectively, as backwards between two module or package revisions, respectively, as backwards
compatible or non-backwards-compatible. compatible or non-backwards-compatible.
[I-D.verdt-netmod-yang-semver] refines the definition, to allow [I-D.ietf-netmod-yang-semver] refines the definition, to allow
backwards compatible changes to be classified as 'minor changes' or backwards compatible changes to be classified as 'minor changes' or
'editorial changes'. 'editorial changes'.
'Revision-label's and YANG semantic version numbers, whilst being 'Revision-label's and YANG semantic version numbers, whilst being
generally simple and helpful in the mainline revision history case, generally simple and helpful in the mainline revision history case,
are not sufficient in all scenarios. For example, when comparing two are not sufficient in all scenarios. For example, when comparing two
revisions/versions on independent revision branches, without a direct revisions/versions on independent revision branches, without a direct
ancestor relationship between the two revisions/versions. In this ancestor relationship between the two revisions/versions. In this
cases, an algorithmic comparison approach is beneficial. cases, an algorithmic comparison approach is beneficial.
skipping to change at page 3, line 51 skipping to change at page 4, line 22
the change is to fix a typo or spelling mistake then the change can the change is to fix a typo or spelling mistake then the change can
be classified as an editorial backwards-compatible change. be classified as an editorial backwards-compatible change.
Conversely, if the change modifies the behavioral specification of Conversely, if the change modifies the behavioral specification of
the data node then the change would need to be classified as either a the data node then the change would need to be classified as either a
non editorial backwards-compatible change or a non-backwards- non editorial backwards-compatible change or a non-backwards-
compatible change. Hence, extension statements are defined to compatible change. Hence, extension statements are defined to
annotate a YANG module with additional information to clarify the annotate a YANG module with additional information to clarify the
scope of changes in cases that cannot be determined by algorithmic scope of changes in cases that cannot be determined by algorithmic
comparison. comparison.
Open issues are tracked at <https://github.com/netmod-wg/yang-ver-dt/ Open issues are tracked at https://github.com/netmod-wg/yang-ver-dt/
issues>, tagged with 'schema-comparison'. issues, tagged with 'schema-comparison'.
2. Terminology and Conventions 2. Terminology and Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
This document uses terminology introduced in the YANG versioning This document uses terminology introduced in the YANG versioning
requirements document [I-D.verdt-netmod-yang-versioning-reqs]. requirements document [I-D.ietf-netmod-yang-versioning-reqs].
This document makes of the following terminology introduced in the This document makes of the following terminology introduced in the
YANG Packages [I-D.rwilton-netmod-yang-packages]: YANG Packages [I-D.ietf-netmod-yang-packages]:
o YANG schema * YANG schema
In addition, this document defines the terminology: In addition, this document defines the terminology:
o Change scope: Whether a change between two revisions is classified * Change scope: Whether a change between two revisions is classified
as non-backwards-compatible, backwards-compatible, or editorial. as non-backwards-compatible, backwards-compatible, or editorial.
3. Generic YANG schema tree comparison algorithm 3. Generic YANG schema tree comparison algorithm
The generic schema comparison algorithm works on any YANG schema. The generic schema comparison algorithm works on any YANG schema.
This could be a schema associated with an individual YANG module, or This could be a schema associated with an individual YANG module, or
a YANG schema represented by a set of modules, e.g., specified by a a YANG schema represented by a set of modules, e.g., specified by a
YANG package. YANG package.
The algorithm performs a recursive tree wise comparison of two The algorithm performs a recursive tree wise comparison of two
skipping to change at page 5, line 15 skipping to change at page 5, line 36
YANG extensions, features, identities, typedefs are checked by YANG extensions, features, identities, typedefs are checked by
comparing the properties defined by their YANG sub-statements comparing the properties defined by their YANG sub-statements
between the two revisions. between the two revisions.
YANG groupings, top-level data definition statements, rpcs, and YANG groupings, top-level data definition statements, rpcs, and
notifications are checked by comparing the top level properties notifications are checked by comparing the top level properties
defined by their direct child YANG sub-statements, and also by defined by their direct child YANG sub-statements, and also by
recursively checking the data definition statements. recursively checking the data definition statements.
The rules specified in section 3 of The rules specified in section 3 of
[I-D.verdt-netmod-yang-module-versioning] determine whether the [I-D.ietf-netmod-yang-module-versioning] determine whether the
changes are backwards-compatible or non-backwards-compatible. changes are backwards-compatible or non-backwards-compatible.
The rules specified in section 3.2 of The rules specified in section 3.2 of
[I-D.rwilton-netmod-yang-packages] determine whether backwards- [I-D.ietf-netmod-yang-packages] determine whether backwards-
compatible changes are 'minor' or 'editorial'. compatible changes are 'minor' or 'editorial'.
For YANG description", "must", and "when" statements, the For YANG description", "must", and "when" statements, the
"backwards-compatible" and "editorial" extension statements can be "backwards-compatible" and "editorial" extension statements can be
used to mark instances when the statements have changed in a used to mark instances when the statements have changed in a
backwards-compatible or editorial way. Since by default the backwards-compatible or editorial way. Since by default the
comparison algorithm assumes that any changes in these statements comparison algorithm assumes that any changes in these statements
are non-backwards-compatible. XXX, more info required here, since are non-backwards-compatible. XXX, more info required here, since
the revisions in the module history probably need to be available the revisions in the module history probably need to be available
for this to work in the general branched revisions case. for this to work in the general branched revisions case.
skipping to change at page 6, line 14 skipping to change at page 6, line 36
5. YANG schema comparison algorithms 5. YANG schema comparison algorithms
5.1. Standard YANG schema comparison algorithm 5.1. Standard YANG schema comparison algorithm
The standard method for comparing two YANG schema versions is to The standard method for comparing two YANG schema versions is to
individually compare the module revisions for each module implemented individually compare the module revisions for each module implemented
by the schema using the algorithm defined in Section 4 and then by the schema using the algorithm defined in Section 4 and then
aggregating the results together: aggregating the results together:
o If all implemented modules in the schema have only changed in an * If all implemented modules in the schema have only changed in an
editorial way then the schema is changed in an editorial way editorial way then the schema is changed in an editorial way
o If all implemented modules in the schema have only been changed in * If all implemented modules in the schema have only been changed in
an editorial or backwards-compatible way then the schema is an editorial or backwards-compatible way then the schema is
changed in a backwards-compatible way changed in a backwards-compatible way
o Otherwise if any implemented module in the schema has been changed * Otherwise if any implemented module in the schema has been changed
in a non-backwards-compatible way then the schema is changed in a in a non-backwards-compatible way then the schema is changed in a
non-backwards-compatible way. non-backwards-compatible way.
The standard schema comparison method is the RECOMMENDED scheme to The standard schema comparison method is the RECOMMENDED scheme to
calculate the version number change for new versions of YANG calculate the version number change for new versions of YANG
packages, because it allows the package version to be calculated packages, because it allows the package version to be calculated
based on changes to implemented modules revision history (or YANG based on changes to implemented modules revision history (or YANG
semantic version number if used to identify module revisions). semantic version number if used to identify module revisions).
5.2. Filtered YANG schema comparison algorithm 5.2. Filtered YANG schema comparison algorithm
skipping to change at page 10, line 36 skipping to change at page 11, line 12
} }
<CODE ENDS> <CODE ENDS>
8. Contributors 8. Contributors
This document grew out of the YANG module versioning design team that This document grew out of the YANG module versioning design team that
started after IETF 101. The following individuals are (or have been) started after IETF 101. The following individuals are (or have been)
members of the design team and have worked on the YANG versioning members of the design team and have worked on the YANG versioning
project: project:
o Balazs Lengyel * Balazs Lengyel
o Benoit Claise * Benoit Claise
o Bo Wu * Bo Wu
o Ebben Aries * Ebben Aries
o Jason Sterne * Jason Sterne
o Joe Clarke * Joe Clarke
o Juergen Schoenwaelder * Juergen Schoenwaelder
o Mahesh Jethanandani * Mahesh Jethanandani
o Michael Wang
o Qin Wu * Michael Wang
o Reshad Rahman * Qin Wu
o Rob Wilton * Reshad Rahman
* Rob Wilton
The ideas for a tooling based comparison of YANG module revisions was The ideas for a tooling based comparison of YANG module revisions was
first described in [I-D.clacla-netmod-yang-model-update]. This first described in [I-D.clacla-netmod-yang-model-update]. This
document extends upon those initial ideas. document extends upon those initial ideas.
9. Security Considerations 9. Security Considerations
The document does not define any new protocol or data model. There The document does not define any new protocol or data model. There
are no security impacts. are no security impacts.
skipping to change at page 11, line 43 skipping to change at page 12, line 18
annotations annotations
Prefix: rev-ext Prefix: rev-ext
Reference: [RFCXXXX] Reference: [RFCXXXX]
11. References 11. References
11.1. Normative References 11.1. Normative References
[I-D.rwilton-netmod-yang-packages] [I-D.ietf-netmod-yang-module-versioning]
Wilton, R., Rahman, R., Clarke, J., Sterne, J., and W. Bo, Wilton, R., Rahman, R., Lengyel, B., Clarke, J., Sterne,
"YANG Packages", draft-rwilton-netmod-yang-packages-03 J., Claise, B., and K. D'Souza, "Updated YANG Module
(work in progress), February 2020. Revision Handling", Work in Progress, Internet-Draft,
draft-ietf-netmod-yang-module-versioning-01, 10 July 2020,
<https://tools.ietf.org/html/draft-ietf-netmod-yang-
module-versioning-01>.
[I-D.verdt-netmod-yang-module-versioning] [I-D.ietf-netmod-yang-packages]
Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, Wilton, R., Rahman, R., Clarke, J., Sterne, J., and W. Bo,
B., Sterne, J., and K. D'Souza, "Updated YANG Module "YANG Packages", Work in Progress, Internet-Draft, draft-
Revision Handling", draft-verdt-netmod-yang-module- ietf-netmod-yang-packages-00, 17 March 2020,
versioning-01 (work in progress), October 2019. <https://tools.ietf.org/html/draft-ietf-netmod-yang-
packages-00>.
[I-D.verdt-netmod-yang-semver] [I-D.ietf-netmod-yang-semver]
Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel,
B., Sterne, J., and K. D'Souza, "YANG Semantic B., Sterne, J., and K. D'Souza, "YANG Semantic
Versioning", draft-verdt-netmod-yang-semver-01 (work in Versioning", Work in Progress, Internet-Draft, draft-ietf-
progress), October 2019. netmod-yang-semver-01, 13 July 2020,
<https://tools.ietf.org/html/draft-ietf-netmod-yang-
semver-01>.
[I-D.verdt-netmod-yang-solutions] [I-D.ietf-netmod-yang-solutions]
Wilton, R., "YANG Versioning Solution Overview", draft- Wilton, R., "YANG Versioning Solution Overview", Work in
verdt-netmod-yang-solutions-03 (work in progress), Progress, Internet-Draft, draft-ietf-netmod-yang-
February 2020. solutions-00, 19 March 2020, <https://tools.ietf.org/html/
draft-ietf-netmod-yang-solutions-00>.
[I-D.verdt-netmod-yang-versioning-reqs] [I-D.ietf-netmod-yang-versioning-reqs]
Clarke, J., "YANG Module Versioning Requirements", draft- Clarke, J., "YANG Module Versioning Requirements", Work in
verdt-netmod-yang-versioning-reqs-02 (work in progress), Progress, Internet-Draft, draft-ietf-netmod-yang-
November 2018. versioning-reqs-03, 29 June 2020,
<https://tools.ietf.org/html/draft-ietf-netmod-yang-
versioning-reqs-03>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
Library", RFC 7895, DOI 10.17487/RFC7895, June 2016,
<https://www.rfc-editor.org/info/rfc7895>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016,
<https://www.rfc-editor.org/info/rfc7950>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of
Documents Containing YANG Data Models", BCP 216, RFC 8407,
DOI 10.17487/RFC8407, October 2018,
<https://www.rfc-editor.org/info/rfc8407>.
[RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K.,
and R. Wilton, "YANG Library", RFC 8525,
DOI 10.17487/RFC8525, March 2019,
<https://www.rfc-editor.org/info/rfc8525>.
11.2. Informative References 11.2. Informative References
[I-D.clacla-netmod-yang-model-update] [I-D.clacla-netmod-yang-model-update]
Claise, B., Clarke, J., Lengyel, B., and K. D'Souza, "New Claise, B., Clarke, J., Lengyel, B., and K. D'Souza, "New
YANG Module Update Procedure", draft-clacla-netmod-yang- YANG Module Update Procedure", Work in Progress, Internet-
model-update-06 (work in progress), July 2018. Draft, draft-clacla-netmod-yang-model-update-06, 2 July
2018, <https://tools.ietf.org/html/draft-clacla-netmod-
[I-D.ietf-netmod-yang-instance-file-format] yang-model-update-06>.
Lengyel, B. and B. Claise, "YANG Instance Data File
Format", draft-ietf-netmod-yang-instance-file-format-08
(work in progress), March 2020.
[RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
<https://www.rfc-editor.org/info/rfc8340>.
[semver] "Semantic Versioning 2.0.0", <https://www.semver.org>.
Author's Address Author's Address
Robert Wilton Robert Wilton
Cisco Systems, Inc. Cisco Systems, Inc.
Email: rwilton@cisco.com Email: rwilton@cisco.com
 End of changes. 44 change blocks. 
103 lines changed or deleted 85 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/