draft-ietf-netmod-yang-module-versioning-00.txt   draft-ietf-netmod-yang-module-versioning-01.txt 
Network Working Group B. Claise Network Working Group R. Wilton, Ed.
Internet-Draft J. Clarke Internet-Draft R. Rahman, Ed.
Updates: 7950,8407,8525 (if approved) R. Rahman Updates: 7950,8407,8525 (if approved) Cisco Systems, Inc.
Intended status: Standards Track R. Wilton, Ed. Intended status: Standards Track B. Lengyel, Ed.
Expires: September 18, 2020 Cisco Systems, Inc. Expires: January 11, 2021 Ericsson
B. Lengyel J. Clarke
Ericsson Cisco Systems, Inc.
J. Sterne J. Sterne
Nokia Nokia
B. Claise
Cisco Systems, Inc.
K. D'Souza K. D'Souza
AT&T AT&T
March 17, 2020 July 10, 2020
Updated YANG Module Revision Handling Updated YANG Module Revision Handling
draft-ietf-netmod-yang-module-versioning-00 draft-ietf-netmod-yang-module-versioning-01
Abstract Abstract
This document specifies a new YANG module update procedure that can This document specifies a new YANG module update procedure that can
document when non-backwards-compatible changes have occurred during document when non-backwards-compatible changes have occurred during
the evolution of a YANG module. It extends the YANG import statement the evolution of a YANG module. It extends the YANG import statement
with an earliest revision filter to better represent inter-module with an earliest revision filter to better represent inter-module
dependencies. It provides help and guidelines for managing the dependencies. It provides help and guidelines for managing the
lifecycle of YANG modules and individual schema nodes. This document lifecycle of YANG modules and individual schema nodes. It provides a
updates RFC 7950, RFC 8407 and RFC 8525. mechanism, via the revision-label YANG extension, to specify a
revision identifier for YANG modules. This document updates RFC
7950, RFC 8407 and RFC 8525.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
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 January 11, 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/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 27 skipping to change at page 2, line 27
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Updates to YANG RFCs . . . . . . . . . . . . . . . . . . 4 1.1. Updates to YANG RFCs . . . . . . . . . . . . . . . . . . 4
2. Terminology and Conventions . . . . . . . . . . . . . . . . . 4 2. Terminology and Conventions . . . . . . . . . . . . . . . . . 4
3. Refinements to YANG revision handling . . . . . . . . . . . . 5 3. Refinements to YANG revision handling . . . . . . . . . . . . 5
3.1. Updating a YANG module with a new revision . . . . . . . 5 3.1. Updating a YANG module with a new revision . . . . . . . 5
3.1.1. Backwards-compatible changes . . . . . . . . . . . . 5 3.1.1. Backwards-compatible changes . . . . . . . . . . . . 6
3.1.2. Non-backwards-compatible changes . . . . . . . . . . 6 3.1.2. Non-backwards-compatible changes . . . . . . . . . . 6
3.2. nbc-changes revision extension statement . . . . . . . . 6 3.2. nbc-changes revision extension statement . . . . . . . . 7
3.3. Revision label . . . . . . . . . . . . . . . . . . . . . 6 3.3. Revision label . . . . . . . . . . . . . . . . . . . . . 7
3.4. YANG status description extension statement . . . . . . . 7 3.3.1. Revision label scheme extension statement . . . . . . 8
3.5. Examples for updating the YANG module revision history . 7 3.4. Examples for updating the YANG module revision history . 8
4. Import by derived revision . . . . . . . . . . . . . . . . . 10 4. Import by derived revision . . . . . . . . . . . . . . . . . 11
4.1. Module import examples . . . . . . . . . . . . . . . . . 11 4.1. Module import examples . . . . . . . . . . . . . . . . . 12
5. Updates to ietf-yang-library . . . . . . . . . . . . . . . . 13 5. Updates to ietf-yang-library . . . . . . . . . . . . . . . . 14
5.1. Resolving ambiguous module imports . . . . . . . . . . . 13 5.1. Resolving ambiguous module imports . . . . . . . . . . . 14
5.2. YANG library versioning augmentations . . . . . . . . . . 14 5.2. YANG library versioning augmentations . . . . . . . . . . 15
5.2.1. Advertising revision-label . . . . . . . . . . . . . 14 5.2.1. Advertising revision-label . . . . . . . . . . . . . 15
5.2.2. Reporting how deprecated and obsolete nodes are 5.2.2. Reporting how deprecated and obsolete nodes are
handled . . . . . . . . . . . . . . . . . . . . . . . 14 handled . . . . . . . . . . . . . . . . . . . . . . . 15
6. Versioning of YANG instance data . . . . . . . . . . . . . . 15 6. Versioning of YANG instance data . . . . . . . . . . . . . . 16
7. Guidelines for using the YANG module update rules . . . . . . 15 7. Guidelines for using the YANG module update rules . . . . . . 16
7.1. Guidelines for YANG module authors . . . . . . . . . . . 15 7.1. Guidelines for YANG module authors . . . . . . . . . . . 16
7.1.1. Making non-backwards-compatible changes to a YANG 7.1.1. Making non-backwards-compatible changes to a YANG
module . . . . . . . . . . . . . . . . . . . . . . . 16 module . . . . . . . . . . . . . . . . . . . . . . . 17
7.2. Versioning Considerations for Clients . . . . . . . . . . 17 7.2. Versioning Considerations for Clients . . . . . . . . . . 18
8. Module Versioning Extension YANG Modules . . . . . . . . . . 18 8. Module Versioning Extension YANG Modules . . . . . . . . . . 18
9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 25 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 26
10. Security Considerations . . . . . . . . . . . . . . . . . . . 26 10. Security Considerations . . . . . . . . . . . . . . . . . . . 27
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27
11.1. YANG Module Registrations . . . . . . . . . . . . . . . 26 11.1. YANG Module Registrations . . . . . . . . . . . . . . . 27
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 11.2. Instructions . . . . . . . . . . . . . . . . . . . . . . 28
12.1. Normative References . . . . . . . . . . . . . . . . . . 26
12.2. Informative References . . . . . . . . . . . . . . . . . 27 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 28
Appendix A. Appendix . . . . . . . . . . . . . . . . . . . . . . 28 12.1. Normative References . . . . . . . . . . . . . . . . . . 28
A.1. Examples of guidelines for making NBC changes to a YANG 12.2. Informative References . . . . . . . . . . . . . . . . . 29
module . . . . . . . . . . . . . . . . . . . . . . . . . 28 Appendix A. Examples of changes that are NBC . . . . . . . . . . 29
A.1.1. Removing a data node . . . . . . . . . . . . . . . . 28 Appendix B. Examples of applying the NBC change guidelines . . . 30
A.1.2. Changing the type of a leaf node . . . . . . . . . . 29 B.1. Removing a data node . . . . . . . . . . . . . . . . . . 30
A.1.3. Reducing the range of a leaf node . . . . . . . . . . 30 B.2. Changing the type of a leaf node . . . . . . . . . . . . 31
A.1.4. Changing the key of a list . . . . . . . . . . . . . 30 B.3. Reducing the range of a leaf node . . . . . . . . . . . . 32
A.1.5. Renaming a node . . . . . . . . . . . . . . . . . . . 31 B.4. Changing the key of a list . . . . . . . . . . . . . . . 32
A.1.6. Changing a default value . . . . . . . . . . . . . . 32 B.5. Renaming a node . . . . . . . . . . . . . . . . . . . . . 33
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 32 B.6. Changing a default value . . . . . . . . . . . . . . . . 34
Appendix C. Changes between revisions . . . . . . . . . . . . . 34
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34
1. Introduction 1. Introduction
This document defines a solution to the YANG module lifecycle This document defines a solution to the YANG module lifecycle
problems described in [I-D.verdt-netmod-yang-versioning-reqs]. problems described in [I-D.ietf-netmod-yang-versioning-reqs].
Complementary documents provide a complete solution to the YANG Complementary documents provide a complete solution to the YANG
versioning requirements, with the overall relationship of the versioning requirements, with the overall relationship of the
solution drafts described in [I-D.verdt-netmod-yang-solutions]. solution drafts described in [I-D.ietf-netmod-yang-solutions].
Specifically, this document recognises a need (within standards Specifically, this document recognises a need (within standards
organizations, vendors, and the industry) to sometimes allow YANG organizations, vendors, and the industry) to sometimes allow YANG
modules to evolve with non-backwards-compatible changes, which could modules to evolve with non-backwards-compatible changes, which could
cause breakage to clients and importing YANG modules. Accepting that cause breakage to clients and importing YANG modules. Accepting that
non-backwards-compatible changes do sometimes occur, it is important non-backwards-compatible changes do sometimes occur, it is important
to have mechanisms to report where these changes occur, and to manage to have mechanisms to report where these changes occur, and to manage
their effect on clients and the broader YANG ecosystem. their effect on clients and the broader YANG ecosystem.
The solution comprises five parts: The document comprises five parts:
Refinements to the YANG 1.1 module revision update procedure, Refinements to the YANG 1.1 module revision update procedure,
supported by new extension statements to indicate when a revision supported by new extension statements to indicate when a revision
contains non-backwards-compatible changes, and an optional contains non-backwards-compatible changes, and an optional
revision label. revision label.
A YANG extension statement allowing YANG module imports to specify A YANG extension statement allowing YANG module imports to specify
an earliest module revision that may satisfy the import an earliest module revision that may satisfy the import
dependency. dependency.
Updates and augmentations to ietf-yang-library to include the Updates and augmentations to ietf-yang-library to include the
revision label in the module descriptions, to report how revision label in the module descriptions, to report how
"deprecated" and "obsolete" nodes are handled by a server, and to "deprecated" and "obsolete" nodes are handled by a server, and to
clarify how module imports are resolved when multiple versions clarify how module imports are resolved when multiple revisions
could otherwise be chosen. could otherwise be chosen.
Considerations of how versioning applies to YANG instance data. Considerations of how versioning applies to YANG instance data.
Guidelines for how the YANG module update rules defined in this Guidelines for how the YANG module update rules defined in this
document should be used, along with examples. document should be used, along with examples.
Note to RFC Editor (To be removed by RFC Editor)
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>. issues>.
1.1. Updates to YANG RFCs 1.1. Updates to YANG RFCs
This document updates [RFC7950] section 11. Section 3 describes This document updates [RFC7950] section 11. Section 3 describes
modifications to YANG revision handling and update rules, and modifications to YANG revision handling and update rules, and
Section 4 describes a YANG extension statement to do import by Section 4 describes a YANG extension statement to do import by
derived revision. derived revision.
This document updates [RFC8525] section 3. Section 5 defines how a This document updates [RFC7950] section 5.6.5. Section 5.1 defines
client of a YANG library datastore schema chooses which revision of how a client of a YANG library datastore schema resolves ambiguous
an import-only module is used to resolve a module import when the imports for modules which are not "import-only".
definition is otherwise ambiguous.
This document updates [RFC8407] section 4.7. Section 7 provides This document updates [RFC8407] section 4.7. Section 7 provides
guidelines on managing the lifecycle of YANG modules that may contain guidelines on managing the lifecycle of YANG modules that may contain
non-backwards-compatible changes and a branched revision history. non-backwards-compatible changes and a branched revision history.
This document updates [RFC7950] section 5.2. Section 3.3 describes
the use of a revision label in the name of a file containing a YANG
module or submodule.
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.
In addition, this document uses the terminology: In addition, this document uses the terminology:
skipping to change at page 5, line 19 skipping to change at page 5, line 19
to have two independent revisions of a YANG module that are both to have two independent revisions of a YANG module that are both
directly derived from the same parent revision. directly derived from the same parent revision.
This document clarifies [RFC7950] to explicitly allow non linear This document clarifies [RFC7950] to explicitly allow non linear
development of YANG module revisions, so modules MAY have multiple development of YANG module revisions, so modules MAY have multiple
revisions that directly derive from the same parent revision. As per revisions that directly derive from the same parent revision. As per
[RFC7950], YANG module revisions continue to be uniquely identified [RFC7950], YANG module revisions continue to be uniquely identified
by the module's revision date, and hence all revisions of a module by the module's revision date, and hence all revisions of a module
MUST have unique revision dates. MUST have unique revision dates.
A corollary to the above is that the relationship between two module
revisions cannot be determined by comparing the module revision date
alone, and the revision history, or revision label, must also be
taken into consideration.
A module's name and revision date identifies a specific immutable A module's name and revision date identifies a specific immutable
definition of that module within its revision history. Hence, if a definition of that module within its revision history. Hence, if a
module includes submodules then the module's "include" statements module includes submodules then to ensure that the module's content
MUST use "revision-date" substatements to specify the exact revision is uniquely defined, the module's "include" statements SHOULD use
date of each included submodule. "revision-date" substatements to specify the exact revision date of
each included submodule. When a module does not include its
submodules by revision-date, the revision of submodules used cannot
be derived from the including module. Mechanisms such as YANG
packages [I-D.ietf-netmod-yang-packages], and YANG library [[RFC7895]
[RFC8525], MAY be used to specify the exact submodule revisions used
when the submodule revision date is not constrained by the "include"
statement.
[RFC7950] section 11 requires that all updates to a YANG module are [RFC7950] section 11 requires that all updates to a YANG module are
BC to the previous revision of the module. This document allows for BC to the previous revision of the module. This document allows for
more flexible evolution of YANG modules: NBC changes between module more flexible evolution of YANG modules: NBC changes between module
revisions are allowed and are documented using a new "nbc-changes" revisions are allowed and are documented using a new "nbc-changes"
YANG extension statement in the module revision history. YANG extension statement in the module revision history.
Two revisions of a module MAY have identical content except for the
revision history. This could occur, for example, if a module has a
branched history and identical changes are applied in multiple
branches.
3.1. Updating a YANG module with a new revision 3.1. Updating a YANG module with a new revision
This section updates [RFC7950] section 11 to refine the rules for This section updates [RFC7950] section 11 to refine the rules for
permissible changes when a new YANG module revision is created. permissible changes when a new YANG module revision is created.
Where pragmatic, updates to YANG modules SHOULD be backwards- Where pragmatic, updates to YANG modules SHOULD be backwards-
compatible, following the definition in Section 3.1.1. compatible, following the definition in Section 3.1.1.
A new module revision MAY contain NBC changes, i.e., the semantics of A new module revision MAY contain NBC changes, i.e., the semantics of
an existing definition MAY be changed in an NBC way without requiring an existing definition MAY be changed in an NBC way without requiring
skipping to change at page 6, line 17 skipping to change at page 6, line 33
"obsolete" is not a backwards-compatible change. "obsolete" is not a backwards-compatible change.
o Obsolete definitions MAY be removed from published modules, and o Obsolete definitions MAY be removed from published modules, and
are classified as backwards-compatible changes. In some are classified as backwards-compatible changes. In some
circumstances it may be helpful to retain the obsolete definitions circumstances it may be helpful to retain the obsolete definitions
to ensure that their identifiers are not reused with a different to ensure that their identifiers are not reused with a different
meaning. meaning.
o In statements that have any data definition statements as o In statements that have any data definition statements as
substatements, those data definition substatements MAY be substatements, those data definition substatements MAY be
reordered, as long as they do not change the ordering or any "rpc" reordered, as long as they do not change the ordering of any
"input" substatements. If new data definition statements are "input" or "output" data definition substatements of "rpc" or
added, they can be added anywhere in the sequence of existing "action" statements. If new data definition statements are added,
they can be added anywhere in the sequence of existing
substatements. substatements.
o Any changes (including whitespace or formatting changes) that do
not change the semantic meaning of the module are backwards
compatible.
3.1.2. Non-backwards-compatible changes 3.1.2. Non-backwards-compatible changes
Any changes to YANG modules that are not defined by Section 3.1.1 as Any changes to YANG modules that are not defined by Section 3.1.1 as
being backwards-compatible are classified as "non-backwards- being backwards-compatible are classified as "non-backwards-
compatible" changes. compatible" changes.
3.2. nbc-changes revision extension statement 3.2. nbc-changes revision extension statement
The "rev:nbc-changes" extension statement is used to indicate YANG The "rev:nbc-changes" extension statement is used to indicate YANG
module revisions that contain NBC changes. module revisions that contain NBC changes.
skipping to change at page 6, line 45 skipping to change at page 7, line 22
the module update rules defined in Section 3.1.1, then a "rev:nbc- the module update rules defined in Section 3.1.1, then a "rev:nbc-
changes" extension statement MUST be added as a substatement to the changes" extension statement MUST be added as a substatement to the
"revision" statement. "revision" statement.
Conversely, if a revision does not contain an "rev:nbc-changes" Conversely, if a revision does not contain an "rev:nbc-changes"
extension substatement then all changes, relative to the preceding extension substatement then all changes, relative to the preceding
revision in the revision history, MUST be backwards-compatible. revision in the revision history, MUST be backwards-compatible.
3.3. Revision label 3.3. Revision label
This section updates [RFC7950] section 5.2, it explains how a
revision label can be used in the name of a file containing a YANG
module or submodule.
Each revision entry in a module or submodule MAY have a revision Each revision entry in a module or submodule MAY have a revision
label associated with it, providing an alternative alias to identify label associated with it, providing an alternative alias to identify
a particular revision of a module or submodule. The revision label a particular revision of a module or submodule. The revision label
could be used to provide an additional versioning identifier could be used to provide an additional versioning identifier
associated with the revision. associated with the revision.
YANG Semver [I-D.verdt-netmod-yang-semver] defines a versioning YANG Semver [I-D.ietf-netmod-yang-semver] defines a versioning scheme
scheme based on Semver 2.0.0 [semver] that can be used as a revision based on Semver 2.0.0 [semver] that can be used as a revision label.
label. All revision labels that match the pattern for the "version"
typedef in the ietf-yang-semver YANG module MUST be interpreted as
YANG semantic version numbers.
The revision date and revision label within a submodule's revision Submodules MAY use a revision label scheme. When they use a revision
history have no effect on the including module's revision. label scheme, submodules MAY use a revision label scheme that is
Submodules MUST NOT use revision label schemes that could be confused different from the one used in the including module.
with the including module's revision label scheme.
The revision label space of submodules is separate from the revision
label space of the including module. A change in one submodule MUST
result in a new revision label of that submodule and the including
module, but the actual values of the revision labels in the module
and submodule could be completely different. A change in one
submodule does not result in a new revision label in another
submodule. A change in a module revision label does not necessarily
mean a change to the revision label in all included submodules.
If a revision has an associated revision label, then it may be used If a revision has an associated revision label, then it may be used
instead of the revision date in two places: instead of the revision date in an "rev:revision-or-derived"
extension statement argument.
In an "rev:revision-or-derived" extension statement argument. If a revision has an associated revision label, then it may be used
instead of the revision date in the filename of a YANG module, where
it takes the form:
In the filename of a YANG module, where it takes the form: module- module-or-submodule-name [['@' revision-date]|['#' revision-label]]
or-submodule-name ['@' revision-label] ( '.yang' / '.yin' ) ( '.yang' / '.yin' )
3.4. YANG status description extension statement E.g., acme-router-modules@2018-01-25.yang
E.g., acme-router-modules#2.0.3.yang
The ietf-yang-revision module specifies the YANG extension statement Two file names, one with the revision date and another with the
"status-description" that can be used as a substatement of the status revision label, MAY exist for the same module (or submodule)
statement. The argument to this extension statement can contain revision.
freeform text to help readers of the module understand why the node
was deprecated or made obsolete, when it is anticipated that the node
will no longer be available for use, and potentially reference other
schema elements that can be used instead. An example is shown below.
leaf imperial-temperature { A specific revision-label identifies a specific revision (variant) of
type int64; the module. If two YANG modules contain the same module name and the
units "degrees Fahrenheit"; same revision-label (and hence also the same revision-date) in their
status deprecated { latest revision statement, then the contents of the two modules MUST
rev:status-description be identical.
"Imperial measurements are being phased out in favor
of their metric equivalents. Use metric-temperature
instead.";
}
description
"Temperature in degrees Fahrenheit.";
}
3.5. Examples for updating the YANG module revision history 3.3.1. Revision label scheme extension statement
The "rev:revision-label-scheme" extension statement is used to
indicate which revision-label scheme a module or submodule uses. The
mandatory argument to this extension statement:
o Specifies the revision-label scheme used by the module or
submodule
o Is defined in the document which specifies the revision-label
scheme
o MUST be an identity derived from "revision-label-scheme-base"
The revision-label scheme used by a module or submodule SHOULD NOT
change during the lifetime of the module or submodule. If the
revision-label scheme used by a module or submodule is changed to a
new scheme, then all revision-label statements that do not conform to
the new scheme MUST be replaced or removed.
3.4. Examples for updating the YANG module revision history
The following diagram, explanation, and module history illustrates The following diagram, explanation, and module history illustrates
how the branched revision history, "nbc-changes" extension statement, how the branched revision history, "nbc-changes" extension statement,
and "revision-label" extension statement could be used: and "revision-label" extension statement could be used:
Example YANG module with branched revision history. Example YANG module with branched revision history.
Module revision date Revision label Module revision date Revision label
2019-01-01 <- 1.0.0 2019-01-01 <- 1.0.0
| |
2019-02-01 <- 2.0.0 2019-02-01 <- 2.0.0
| \ | \
2019-03-01 \ <- 3.0.0 2019-03-01 \ <- 3.0.0
| \ | \
| 2019-04-01 <- 2.1.0 | 2019-04-01 <- 2.1.0
| | | |
| 2019-05-01 <- 2.2.0 | 2019-05-01 <- 2.2.0
| |
2019-06-01 <- 3.1.0 2019-06-01 <- 3.1.0
The tree diagram above illustrates how an example module's version The tree diagram above illustrates how an example module's revision
history might evolve, over time. For example, the tree might history might evolve, over time. For example, the tree might
represent the following changes, listed in chronological order from represent the following changes, listed in chronological order from
oldest revision to newest: oldest revision to newest:
Example module, revision 2019-06-01: Example module, revision 2019-06-01:
module example-module { module example-module {
namespace "name-space"; namespace "urn:example:module";
prefix "prefix-name"; prefix "prefix-name";
import ietf-yang-revisions { prefix "rev"; } import ietf-yang-revisions { prefix "rev"; }
description description
"to be completed"; "to be completed";
revision 2019-06-01 { revision 2019-06-01 {
rev:revision-label 3.1.0; rev:revision-label 3.1.0;
description "Add new functionality."; description "Add new functionality.";
skipping to change at page 10, line 4 skipping to change at page 10, line 41
rev:nbc-changes; rev:nbc-changes;
description "Apply bugfix to pattern statement"; description "Apply bugfix to pattern statement";
} }
revision 2019-01-01 { revision 2019-01-01 {
rev:revision-label 1.0.0; rev:revision-label 1.0.0;
description "Initial revision"; description "Initial revision";
} }
//YANG module definition starts here //YANG module definition starts here
}
Example module, revision 2019-05-01: Example module, revision 2019-05-01:
module example-module { module example-module {
namespace "name-space"; namespace "urn:example:module";
prefix "prefix-name"; prefix "prefix-name";
import ietf-yang-revisions { prefix "rev"; } import ietf-yang-revisions { prefix "rev"; }
description description
"to be completed"; "to be completed";
revision 2019-05-01 { revision 2019-05-01 {
rev:revision-label 2.2.0; rev:revision-label 2.2.0;
description "Backwards-compatible bugfix to enhancement."; description "Backwards-compatible bugfix to enhancement.";
skipping to change at page 10, line 39 skipping to change at page 11, line 39
rev:nbc-changes; rev:nbc-changes;
description "Apply bugfix to pattern statement"; description "Apply bugfix to pattern statement";
} }
revision 2019-01-01 { revision 2019-01-01 {
rev:revision-label 1.0.0; rev:revision-label 1.0.0;
description "Initial revision"; description "Initial revision";
} }
//YANG module definition starts here //YANG module definition starts here
}
4. Import by derived revision 4. Import by derived revision
RFC 7950 allows YANG module "import" statements to optionally require RFC 7950 allows YANG module "import" statements to optionally require
the imported module to have a particular revision date. In practice, the imported module to have a particular revision date. In practice,
importing a module with an exact revision date is often too importing a module with an exact revision date is often too
restrictive because it requires the importing module to be updated restrictive because it requires the importing module to be updated
whenever any change to the imported module occurs. The alternative whenever any change to the imported module occurs. The alternative
choice of using an import statement without any revision date choice of using an import statement without any revision date
statement is also not ideal because the importing module may not work statement is also not ideal because the importing module may not work
skipping to change at page 11, line 15 skipping to change at page 12, line 18
required revision" are also likely to be compatible. Many possible required revision" are also likely to be compatible. Many possible
changes to a YANG module do not break importing modules, even if the changes to a YANG module do not break importing modules, even if the
changes themselves are not strictly backwards-compatible. E.g., changes themselves are not strictly backwards-compatible. E.g.,
fixing an incorrect pattern statement or description for a leaf would fixing an incorrect pattern statement or description for a leaf would
not break an import, changing the name of a leaf could break an not break an import, changing the name of a leaf could break an
import but frequently would not, but removing a container would break import but frequently would not, but removing a container would break
imports if that container is augmented by another module. imports if that container is augmented by another module.
The ietf-revisions module defines the "revision-or-derived" extension The ietf-revisions module defines the "revision-or-derived" extension
statement, a substatement to the YANG "import" statement, to allow statement, a substatement to the YANG "import" statement, to allow
for a "minium required revision" to be specified during import: for a "minimum required revision" to be specified during import:
The argument to the "revision-or-derived" extension statement is a The argument to the "revision-or-derived" extension statement is a
revision date or a revision label. revision date or a revision label.
A particular revision of an imported module satisfies an import's A particular revision of an imported module satisfies an import's
"revision-or-derived" extension statement if the imported module's "revision-or-derived" extension statement if the imported module's
revision history contains a revision statement with a matching revision history contains a revision statement with a matching
revision date or revision label. revision date or revision label.
An "import" statement MUST NOT contain both a "revision-or- An "import" statement MUST NOT contain both a "revision-or-
derived" extension statement and a "revision-date" statement. derived" extension statement and a "revision-date" statement.
The "revision-or-derived" extension statement MAY be specified The "revision-or-derived" extension statement MAY be specified
multiple times, allowing the import to use any module revision multiple times, allowing the import to use any module revision
that satifies at least one of the "revision-or-derived" extension that satisfies at least one of the "revision-or-derived" extension
statements. statements.
The "revision-or-derived" extension statement does not gaurantee The "revision-or-derived" extension statement does not guarantee
that all module revisions that satisfy an import statement are that all module revisions that satisfy an import statement are
necessarily compatible, it only gives an indication that the necessarily compatible, it only gives an indication that the
revisions are more likely to be compatible. Hence, NBC changes to revisions are more likely to be compatible. Hence, NBC changes to
an imported module may also require new revisions of any importing an imported module may also require new revisions of any importing
modules, updated to accommodation those changes, along with modules, updated to accommodation those changes, along with
updated import "revision-or-derived" extension statements to updated import "revision-or-derived" extension statements to
depend on the updated imported module revision. depend on the updated imported module revision.
4.1. Module import examples 4.1. Module import examples
Consider the example module "example-module" from Section 3.5 that is Consider the example module "example-module" from Section 3.4 that is
hypothetically available in the following revision/label pairings: hypothetically available in the following revision/label pairings:
2019-01-01/1.0.0, 2019-02-01/2.0.0, 2019-03-01/3.0.0, 2019-01-01/1.0.0, 2019-02-01/2.0.0, 2019-03-01/3.0.0,
2019-04-01/2.1.0, 2019-05-01/2.2.0 and 2019-06-01/3.1.0. The 2019-04-01/2.1.0, 2019-05-01/2.2.0 and 2019-06-01/3.1.0. The
relationship between the revisions is as before: relationship between the revisions is as before:
Module revision date Revision label Module revision date Revision label
2019-01-01 <- 1.0.0 2019-01-01 <- 1.0.0
| |
2019-02-01 <- 2.0.0 2019-02-01 <- 2.0.0
| \ | \
skipping to change at page 12, line 32 skipping to change at page 13, line 32
there was a new container added in revision 2019-02-01 that is there was a new container added in revision 2019-02-01 that is
augmented by the importing module.It includes revisions/labels: augmented by the importing module.It includes revisions/labels:
2019-02-01/2.0.0, 2019-03-01/3.0.0, 2019-04-01/2.1.0, 2019-02-01/2.0.0, 2019-03-01/3.0.0, 2019-04-01/2.1.0,
2019-05-01/2.2.0 and 2019-06-01/3.1.0. 2019-05-01/2.2.0 and 2019-06-01/3.1.0.
import example-module { import example-module {
rev:revision-or-derived 2019-02-01; rev:revision-or-derived 2019-02-01;
} }
Alternatively, the first example could have used the revision label Alternatively, the first example could have used the revision label
"1.0.0" instead, which selects the same set of revisions/versions. "2.0.0" instead, which selects the same set of revisions/labels.
import example-module { import example-module {
rev:revision-or-derived 1.0.0; rev:revision-or-derived 2.0.0;
} }
4.1.2. Example 2 4.1.2. Example 2
This example selects module revisions that are derived from This example selects module revisions that are derived from
2019-04-01 by using the revision label 2.1.0. It includes revisions/ 2019-04-01 by using the revision label 2.1.0. It includes revisions/
labels: 2019-04-01/2.1.0 and 2019-05-01/2.2.0. Even though labels: 2019-04-01/2.1.0 and 2019-05-01/2.2.0. Even though
2019-06-01/3.1.0 has a higher revision label version number than 2019-06-01/3.1.0 has a higher revision label number than
2019-04-01/2.1.0 it is not a derived revision, and hence it is not a 2019-04-01/2.1.0 it is not a derived revision, and hence it is not a
valid revision for import. valid revision for import.
import example-module { import example-module {
rev:revision-or-derived 2.1.0; rev:revision-or-derived 2.1.0;
} }
4.1.3. Example 3 4.1.3. Example 3
This example selects revisions derived from either 2019-04-01 or This example selects revisions derived from either 2019-04-01 or
2019-06-01. It includes revisions/labels: 2019-04-01/2.1.0, 2019-06-01. It includes revisions/labels: 2019-04-01/2.1.0,
2019-05-01/2.2.0, and 2019-06-01/3.1.0. 2019-05-01/2.2.0, and 2019-06-01/3.1.0.
import example-module { import example-module {
rev:revision-or-derived 2019-04-01; rev:revision-or-derived 2019-04-01;
rev:revision-or-derived 2019-06-01; rev:revision-or-derived 2019-06-01;
} }
5. Updates to ietf-yang-library 5. Updates to ietf-yang-library
This document updates YANG library [RFC7895] [RFC8525] to clarify how This document updates YANG library [RFC7950] to clarify how ambiguous
ambiguous module imports are resolved. It also defines the YANG module imports are resolved. It also defines the YANG module, ietf-
module, ietf-yl-revisions that augments YANG library with new yang-library-revisions that augments YANG library [RFC8525] with new
versioning related meta-data. revision-label related meta-data.
5.1. Resolving ambiguous module imports 5.1. Resolving ambiguous module imports
A YANG datastore schema, defined in [RFC8525], can specify multiple A YANG datastore schema, defined in [RFC8525], can specify multiple
revisions of a YANG module in the schema using the "import-only" revisions of a YANG module in the schema using the "import-only"
list, with the requirement from [RFC7950] that only a single revision list, with the requirement from [RFC7950] that only a single revision
of a YANG module may be implemented. of a YANG module may be implemented.
If a YANG module import statement does not specify a specific If a YANG module import statement does not specify a specific
revision within the datastore schema then it could be ambiguous as to revision within the datastore schema then it could be ambiguous as to
skipping to change at page 14, line 7 skipping to change at page 15, line 7
statement MUST resolve to the revision of the module that is defined statement MUST resolve to the revision of the module that is defined
as being implemented by the datastore schema. as being implemented by the datastore schema.
If a module import statement could resolve to more than one module If a module import statement could resolve to more than one module
revision defined in the datastore schema, and none of those revisions revision defined in the datastore schema, and none of those revisions
are implemented, then the import MUST resolve to the module revision are implemented, then the import MUST resolve to the module revision
with the latest revision date. with the latest revision date.
5.2. YANG library versioning augmentations 5.2. YANG library versioning augmentations
The "ietf-yl-revisions" YANG module has the following structure The "ietf-yang-library-revisions" YANG module has the following
(using the notation defined in [RFC8340]): structure (using the notation defined in [RFC8340]):
module: ietf-yl-revisions module: ietf-yang-library-revisions
augment /yanglib:yang-library/yanglib:module-set/yanglib:module: augment /yanglib:yang-library/yanglib:module-set/yanglib:module:
+--ro revision-label? rev:revision-label +--ro revision-label? rev:revision-label
augment /yanglib:yang-library/yanglib:schema: augment /yanglib:yang-library/yanglib:schema:
+--ro deprecated-nodes-implemented? empty +--ro deprecated-nodes-implemented? boolean
+--ro obsolete-nodes-absent? empty +--ro obsolete-nodes-absent? boolean
5.2.1. Advertising revision-label 5.2.1. Advertising revision-label
The ietf-yl-revisions YANG module augments the "module" list in ietf- The ietf-yang-library-revisions YANG module augments the "module"
yang-library with a "revision-label" leaf to optionally declare the list in ietf-yang-library with a "revision-label" leaf to optionally
revision label associated wth the particular revision of each module. declare the revision label associated wth the particular revision of
each module.
5.2.2. Reporting how deprecated and obsolete nodes are handled 5.2.2. Reporting how deprecated and obsolete nodes are handled
The ietf-yl-revisions YANG module augments YANG library with two The ietf-yang-library-revisions YANG module augments YANG library
leaves to allow a server to report how it handles status "deprecated" with two leaves to allow a server to report how it handles status
and status "obsolete" nodes. The leaves are: "deprecated" and status "obsolete" nodes. The leaves are:
deprecated-nodes-implemented: If present, this leaf indicates that deprecated-nodes-implemented: If set to "true", this leaf indicates
all schema nodes with a status "deprecated" child statement are that all schema nodes with a status "deprecated" child statement
implemented equivalently as if they had status "current", or are implemented equivalently as if they had status "current", or
otherwise deviations MUST be used to explicitly remove otherwise deviations MUST be used to explicitly remove
"deprecated" nodes from the schema. If this leaf is absent then "deprecated" nodes from the schema. If this leaf is set to
the behavior is unspecified. "false" or absent, then the behavior is unspecified.
obsolete-nodes-absent: If present, this leaf indicates that the obsolete-nodes-absent: If set to "true", this leaf indicates that
server does not implement any status "obsolete" nodes. If this the server does not implement any status "obsolete" nodes. If
leaf is absent then the behaviour is unspecified. this leaf is set to "false" or absent, then the behaviour is
unspecified.
Servers SHOULD set both the "deprecated-nodes-implemented" and Servers SHOULD set both the "deprecated-nodes-implemented" and
"obsolete-nodes-absent" leaves. "obsolete-nodes-absent" leaves to "true".
If a server does not set the "deprecated-nodes-implemented" leaf, If a server does not set the "deprecated-nodes-implemented" leaf to
then clients MUST NOT rely solely on the "rev:nbc-changes" statements "true", then clients MUST NOT rely solely on the "rev:nbc-changes"
to determine whether two module revisions are backwards-compatible, statements to determine whether two module revisions are backwards-
and MUST also consider whether the status of any nodes has changed to compatible, and MUST also consider whether the status of any nodes
"deprecated" and whether those nodes are implemented by the server. has changed to "deprecated" and whether those nodes are implemented
by the server.
6. Versioning of YANG instance data 6. Versioning of YANG instance data
Instance data sets [I-D.ietf-netmod-yang-instance-file-format] do not Instance data sets [I-D.ietf-netmod-yang-instance-file-format] do not
directly make use of the updated revision handling rules described in directly make use of the updated revision handling rules described in
this document, as compatibility for instance data is undefined. this document, as compatibility for instance data is undefined.
However, instance data specifies the content-schema of the data-set. However, instance data specifies the content-schema of the data-set.
This schema SHOULD make use of versioning using revision dates and/or This schema SHOULD make use of versioning using revision dates and/or
revision labels for the individual YANG modules that comprise the revision labels for the individual YANG modules that comprise the
schema or potentially for the entire schema itself (e.g., schema or potentially for the entire schema itself (e.g.,
[I-D.rwilton-netmod-yang-packages] ). [I-D.ietf-netmod-yang-packages] ).
In this way, the versioning of a content-schema associated with an In this way, the versioning of a content-schema associated with an
instance data set may help a client to determine whether the instance instance data set may help a client to determine whether the instance
data could also be used in conjunction with other revisions of the data could also be used in conjunction with other revisions of the
YANG schema, or other revisions of the modules that define the YANG schema, or other revisions of the modules that define the
schema. schema.
7. Guidelines for using the YANG module update rules 7. Guidelines for using the YANG module update rules
The following text updates section 4.7 of [RFC8407] to revise the The following text updates section 4.7 of [RFC8407] to revise the
guidelines for updating YANG modules. guidelines for updating YANG modules.
7.1. Guidelines for YANG module authors 7.1. Guidelines for YANG module authors
All IETF YANG modules MUST include revision-label statements for all All IETF YANG modules MUST include revision-label statements for all
newly published YANG modules, and all newly published revisions of newly published YANG modules, and all newly published revisions of
existing YANG modules. The revision-label MUST take the form of a existing YANG modules. The revision-label MUST take the form of a
YANG semantic version number [I-D.verdt-netmod-yang-semver]. YANG semantic version number [I-D.ietf-netmod-yang-semver].
NBC changes to YANG modules may cause problems to clients, who are NBC changes to YANG modules may cause problems to clients, who are
consumers of YANG models, and hence YANG module authors are consumers of YANG models, and hence YANG module authors are
RECOMMENDED to minimize NBC changes and keep changes BC whenever RECOMMENDED to minimize NBC changes and keep changes BC whenever
possible. possible.
When NBC changes are introduced, consideration should be given to the When NBC changes are introduced, consideration should be given to the
impact on clients and YANG module authors SHOULD try to mitigate that impact on clients and YANG module authors SHOULD try to mitigate that
impact. impact.
A "rev:nbc-changes" statement SHOULD be added only if there are NBC A "rev:nbc-changes" statement MUST be added if there are NBC changes
changes relative to the previous revision. relative to the previous revision.
Removing old revision statements from a module's revision history Removing old revision statements from a module's revision history
could break import by revision, and hence it is RECOMMENDED to retain could break import by revision, and hence it is RECOMMENDED to retain
them. If all depencencies have been updated to not import specific them. If all depencencies have been updated to not import specific
revisions of a module, then the corresponding revision statements can revisions of a module, then the corresponding revision statements can
be removed from that module. An alternative solution, if the be removed from that module. An alternative solution, if the
revision section is too long, would be remove, or curtail, the older revision section is too long, would be remove, or curtail, the older
description statements associated with the previous revisions. description statements associated with the previous revisions.
The "rev:revision-or-derived" extension should be used in YANG module The "rev:revision-or-derived" extension should be used in YANG module
imports to indicate revision dependencies between modules in imports to indicate revision dependencies between modules in
preference to the "revision-date" statement, which causes overly preference to the "revision-date" statement, which causes overly
strict import dependencies and SHOULD NOT be used. strict import dependencies and SHOULD NOT be used.
A module that includes submodules MUST use the "revision-date" A module that includes submodules SHOULD use the "revision-date"
statement to include specific submodule revisions. Changing a statement to include specific submodule revisions. The revision of
module's include statements to include different submodule revisions the including module MUST be updated when any included submodule has
requires a new revision of the module. changed. The revision-label substatement used in the new module
revision MUST indicate the nature of the change, i.e. NBC or BC, to
the module's schema tree.
7.1.1. Making non-backwards-compatible changes to a YANG module 7.1.1. Making non-backwards-compatible changes to a YANG module
There are various valid situations where a YANG module has to be There are various valid situations where a YANG module has to be
modified in an NBC way. Here are the different ways in which this modified in an NBC way. Here are the different ways in which this
can be done: can be done:
o NBC changes can be sometimes be done incrementally using the o NBC changes can be sometimes be done incrementally using the
"deprecated" status to provide clients time to adapt to NBC "deprecated" status to provide clients time to adapt to NBC
changes. changes.
o NBC changes are done at once, i.e. without using "status" o NBC changes are done at once, i.e. without using "status"
statements. Depending on the change, this may have a big impact statements. Depending on the change, this may have a big impact
on clients. on clients.
o If the server can support multiple versions of the YANG module or o If the server can support multiple revisions of the YANG module or
of YANG packages(as specified in of YANG packages(as specified in [I-D.ietf-netmod-yang-packages]),
[I-D.rwilton-netmod-yang-packages]), and allows the client to and allows the client to select the revision (as per
select the version (as per [I-D.ietf-netmod-yang-ver-selection]), then NBC changes MAY be
[I-D.wilton-netmod-yang-ver-selection]), then NBC changes MAY be
done without using "status" statements. Clients would be required done without using "status" statements. Clients would be required
to select the version which they support and the NBC change would to select the revision which they support and the NBC change would
have no impact on them have no impact on them
Here are some guidelines on how non-backwards-compatible changes can Here are some guidelines on how non-backwards-compatible changes can
be made incrementally, with the assumption that deprecated nodes are be made incrementally, with the assumption that deprecated nodes are
implemented by the server, and obsolete nodes are not: implemented by the server, and obsolete nodes are not:
1. The changes should be made gradually, e.g. a data node's status 1. The changes should be made gradually, e.g. a data node's status
SHOULD NOT be changed directly from "current" to "obsolete" (see SHOULD NOT be changed directly from "current" to "obsolete" (see
Section 4.7 of [RFC8407]), instead the status SHOULD first be Section 4.7 of [RFC8407]), instead the status SHOULD first be
marked "deprecated" and then when support is removed its status marked "deprecated" and then when support is removed its status
MUST be changed to "obsolete". Instead of using the "obsolete" MUST be changed to "obsolete". Instead of using the "obsolete"
status, the data node MAY be removed from the model but this has status, the data node MAY be removed from the model but this has
the risk of breaking modules which import the modified module. the risk of breaking modules which import the modified module.
2. The new "status-description" extension statement SHOULD be used 2. For deprecated data nodes the "description" statement SHOULD also
for nodes which are "obsolete" or "deprecated".
3. For status "deprecated", the "status-description" SHOULD also
indicate until when support for the node is guaranteed (if indicate until when support for the node is guaranteed (if
known). If there is a replacement data node, rpc, action or known). If there is a replacement data node, rpc, action or
notification for the deprecated node, this SHOULD be stated in notification for the deprecated node, this SHOULD be stated in
the "status-description". The reason for deprecating the node the "description". The reason for deprecating the node can also
can also be included in the "status-description" if it is deemed be included in the "description" if it is deemed to be of
to be of potential interest to the user. potential interest to the user.
4. For status "obsolete", it is RECOMMENDED to keep the "status- 3. For obsolete data nodes, it is RECOMMENDED to keep the above
description" information, from when the node had status information, from when the node had status "deprecated", which is
"deprecated, which is still relevant. still relevant.
5. When obsoleting or deprecating data nodes, the "deprecated" or 4. When obsoleting or deprecating data nodes, the "deprecated" or
"obsolete" status SHOULD be applied at the highest possible level "obsolete" status SHOULD be applied at the highest possible level
in the data tree with an appropriate "status-description" in the data tree. For clarity, the "status" statement SHOULD
statement. For clarity, the "status" statement SHOULD also be also be applied to all descendent data nodes, but the additional
applied to all descendent data nodes, but the "status- status related information does not need to be repeated if it
description" statement does not need to be repeated if it does does not introduce any additional information.
not introduce any additional information.
See Appendix A.1 for examples on how NBC changes can be made. See Appendix B for examples on how NBC changes can be made.
7.2. Versioning Considerations for Clients 7.2. Versioning Considerations for Clients
Guidelines for clients of modules using the new module revision Guidelines for clients of modules using the new module revision
update procedure: update procedure:
o Clients SHOULD be liberal when processing data received from a o Clients SHOULD be liberal when processing data received from a
server. For example, the server may have increased the range of server. For example, the server may have increased the range of
an operational node causing the client to receive a value which is an operational node causing the client to receive a value which is
outside the range of the YANG model revision it was coded against. outside the range of the YANG model revision it was coded against.
skipping to change at page 18, line 8 skipping to change at page 18, line 51
o Clients SHOULD plan to make changes to match published status o Clients SHOULD plan to make changes to match published status
changes. When a node's status changes from "current" to changes. When a node's status changes from "current" to
"deprecated", clients SHOULD plan to stop using that node in a "deprecated", clients SHOULD plan to stop using that node in a
timely fashion. When a node's status changes to "obsolete", timely fashion. When a node's status changes to "obsolete",
clients MUST stop using that node. clients MUST stop using that node.
8. Module Versioning Extension YANG Modules 8. Module Versioning Extension YANG Modules
YANG module with extension statements for annotating NBC changes, YANG module with extension statements for annotating NBC changes,
revision label, status description, and importing by version. revision label, revision label scheme, and importing by revision.
<CODE BEGINS> file "ietf-yang-revisions@2019-09-18.yang" <CODE BEGINS> file "ietf-yang-revisions@2020-07-06.yang"
module ietf-yang-revisions { module ietf-yang-revisions {
yang-version 1.1; yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-revisions"; namespace "urn:ietf:params:xml:ns:yang:ietf-yang-revisions";
prefix rev; prefix rev;
import ietf-yang-types { import ietf-yang-types {
prefix yang; prefix yang;
reference reference
"XXXX [ietf-netmod-rfc6991-bis]: Common YANG Data Types"; "XXXX [ietf-netmod-rfc6991-bis]: Common YANG Data Types";
} }
organization organization
"IETF NETMOD (Network Modeling) Working Group"; "IETF NETMOD (Network Modeling) Working Group";
contact contact
"WG Web: <https://datatracker.ietf.org/wg/netmod/> "WG Web: <https://datatracker.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org> WG List: <mailto:netmod@ietf.org>
Author: Benoit Claise Author: Benoit Claise
<mailto:bclaise@cisco.com> <mailto:bclaise@cisco.com>
Author: Joe Clarke Author: Joe Clarke
<mailto:jclarke@cisco.com> <mailto:jclarke@cisco.com>
Author: Reshad Rahman Author: Reshad Rahman
<mailto:rrahman@cisco.com> <mailto:rrahman@cisco.com>
Author: Robert Wilton Author: Robert Wilton
<mailto:rwilton@cisco.com> <mailto:rwilton@cisco.com>
Author: Kevin D'Souza Author: Kevin D'Souza
<mailto:kd6913@att.com> <mailto:kd6913@att.com>
Author: Balazs Lengyel Author: Balazs Lengyel
<mailto:balazs.lengyel@ericsson.com> <mailto:balazs.lengyel@ericsson.com>
Author: Jason Sterne Author: Jason Sterne
<mailto:jason.sterne@nokia.com>"; <mailto:jason.sterne@nokia.com>";
description description
"This YANG 1.1 module contains definitions and extensions to "This YANG 1.1 module contains definitions and extensions to
support updated YANG revision handling. support updated YANG revision handling.
Copyright (c) 2019 IETF Trust and the persons identified as Copyright (c) 2019 IETF Trust and the persons identified as
authors of the code. All rights reserved. authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents Relating to IETF Documents
(http://trustee.ietf.org/license-info). (http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices. the RFC itself for full legal notices.
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
'MAY', and 'OPTIONAL' in this document are to be interpreted as 'MAY', and 'OPTIONAL' in this document are to be interpreted as
described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
they appear in all capitals, as shown here."; they appear in all capitals, as shown here.";
// RFC Ed.: update the date below with the date of RFC publication // RFC Ed.: update the date below with the date of RFC publication
// and remove this note. // and remove this note.
// RFC Ed.: replace XXXX (inc above) with actual RFC number and // RFC Ed.: replace XXXX (inc above) with actual RFC number and
// remove this note. // remove this note.
revision 2019-09-18 { revision 2020-07-06 {
description description
"Initial version."; "Initial version.";
reference reference
"XXXX: Updated YANG Module Revision Handling"; "XXXX: Updated YANG Module Revision Handling";
} }
typedef revision-label { typedef revision-label {
type string { type string {
length "1..255"; length "1..255";
pattern '[^\s@]+'; pattern '[^\s@]+';
pattern '\d{4}-\d{2}-\d{2}' { pattern '\d{4}-\d{2}-\d{2}' {
modifier invert-match; modifier invert-match;
}
} }
description }
"A label associated with a YANG revision. description
"A label associated with a YANG revision.
Excludes spaces and '@'. MUST NOT match revision-date. Excludes spaces and '@'. MUST NOT match revision-date.";
reference
"XXXX: Updated YANG Module Revision Handling;
Section 3.3, Revision label";
}
Revision labels that classify as YANG semantic versions, typedef revision-date-or-label {
as defined by the ietf-yang-semver:version typedef, type union {
MUST conform to the versioning behaviour defined in type yang:revision-identifier;
XXXX [verdt]: YANG Semantic Versioning."; type revision-label;
reference
"XXXX: Updated YANG Module Revision Handling;
Section 3.3, Revision label";
} }
description
"Represents either a YANG revision date or a revision label";
}
typedef revision-date-or-label { extension nbc-changes {
type union { description
type yang:revision-identifier; "This statement is used to indicate YANG module revisions that
type revision-label; contain non-backwards-compatible changes.
}
description
"Represents either a YANG revision date or a revision label";
}
extension nbc-changes { The statement MUST only be a substatement of the 'revision'
description statement.
"This statement is used to indicate YANG module revisions that Zero or one 'nbc-changes' statement per parent statement is
contain non-backwards-compatible changes. allowed.
The statement MUST NOT have any substatements.
Each 'revision' statement MAY have a single 'nbc-changes' If a revision of a YANG module contains changes, relative to
substatement. the preceding revision in the revision history, that do not
conform to the module update rules defined in RFC-XXX, then
the 'nbc-changes' statement MUST be added as a substatement to
the revision statement.
If a revision of a YANG module contains changes, relative to Conversely, if a revision of a YANG module only contains
the preceding revision in the revision history, that do not changes, relative to the preceding revision in the revision
conform to the module update rules defined in RFC-XXX, then history, that are classified as 'backwards-compatible' then
the 'nbc-changes' statement MUST be added as a substatement to the revision statement MUST NOT contain any 'nbc-changes'
the revision statement. substatement.";
Conversely, if a revision of a YANG module only contains reference
changes, relative to the preceding revision in the revision "XXXX: Updated YANG Module Revision Handling;
history, that are classified as 'backwards-compatible' then Section 3.2, nbc-changes revision extension statement";
the revision statement MUST NOT contain any 'nbc-changes' }
substatement.";
reference extension revision-label {
"XXXX: Updated YANG Module Revision Handling; argument revision-label;
Section 3.2, nbc-changes revision extension statement"; description
} "The revision label can be used to provide an additional
versioning identifier associated with the revision. E.g., one
option for a versioning scheme that could be used is [TODO -
Reference semver draft].
extension revision-label { The format of the revision-label argument MUST conform to the
argument revision-label; pattern defined for the revision-label typedef.
description
"The revision label can be used to provide an additional
versioning identifier associated with the revision. E.g., one
option for a versioning scheme that could be used is [TODO -
Reference semver draft].
The format of the revision-label argument MUST conform to the The statement MUST only be a substatement of the revision
pattern defined for the revision-label typedef. statement.
Zero or one revision-label statement per parent statement
is allowed.
The statement MUST NOT have any substatements.
Each 'revision' statement MAY have a single 'revision-label' Revision labels MUST be unique amongst all revisions of a
substatement. module.";
Revision labels MUST be unique amongst all revisions of a reference
module."; "XXXX: Updated YANG Module Revision Handling;
Section 3.3, Revision label";
}
reference extension revision-label-scheme {
"XXXX: Updated YANG Module Revision Handling; argument revision-label-scheme-identity;
Section 3.3, Revision label"; description
} "The revision label scheme specifies which revision-label scheme
the module or submodule uses.
extension revision-or-derived { The mandatory revision-label-scheme-identity argument MUST be an
argument revision-date-or-label; identity derived from revision-label-scheme-base.
description
"Restricts the revision of the module that may be imported to
one that matches or is derived from the specified
revision-date or revision-nlabel.
The argument value MUST conform to the This extension is only valid as a top-level statement, i.e.,
'revision-date-or-label' defined type. given as as a substatement to 'module' or 'submodule'.
Each 'import' statement MAY have one or more This extension MUST be used if there is a revision-label
'revision-or-derived' substatements. If specified multiple statement in the module or submodule.
times, then any module revision that satifies at least one of
the 'revision-or-derived' statements is an acceptable revision
for import.
An 'import' statement MUST NOT contain both a The statement MUST NOT have any substatements.";
'revision-or-derived' extension statement and a
'revision-date' statement.
A particular revision of an imported module satisfies an reference
import's 'revision-or-derived' extension statement if the "XXXX: Updated YANG Module Revision Handling;
imported module's revision history contains a revision Section 3.3.1, Revision label scheme extension statement";
statement with a matching revision date or revision label. }
The 'revision-or-derived' extension statement does not extension revision-or-derived {
gaurantee that all module revisions that satisfy an import argument revision-date-or-label;
statement are necessarily compatible, it only gives an description
indication that the revisions are more likely to be "Restricts the revision of the module that may be imported to
compatible."; one that matches or is derived from the specified
revision-date or revision-label.
reference The argument value MUST conform to the
"XXXX: Updated YANG Module Revision Handling; 'revision-date-or-label' defined type.
Section 4, Import by derived revision";
}
extension status-description { The statement MUST only be a substatement of the import
argument description; statement.
Zero, one or more 'revision-or-derived' statement per parent
statement is allowed.
The statement MUST NOT have any substatements.
description If specified multiple
"Freeform text that describes why a given node has been times, then any module revision that satisfies at least one of
deprecated or made obsolete. E.g., the description could be the 'revision-or-derived' statements is an acceptable revision
used to give the reason for removal, or it could point to an for import.
alternative schema elements that can be used in lieu of the
given node.
Each 'status' statement MAY have a single 'status-description' An 'import' statement MUST NOT contain both a
substatement."; 'revision-or-derived' extension statement and a
'revision-date' statement.
A particular revision of an imported module satisfies an
import's 'revision-or-derived' extension statement if the
imported module's revision history contains a revision
statement with a matching revision date or revision label.
The 'revision-or-derived' extension statement does not
guarantee that all module revisions that satisfy an import
statement are necessarily compatible, it only gives an
indication that the revisions are more likely to be
compatible.";
reference
"XXXX: Updated YANG Module Revision Handling;
Section 4, Import by derived revision";
}
identity revision-label-scheme-base {
description
"Base identity from which all revision label schemes are
derived.";
reference reference
"XXXX: Updated YANG Module Revision Handling; "XXXX: Updated YANG Module Revision Handling;
Section 3.4, YANG status description extension statement"; Section 3.3.1, Revision label scheme extension statement";
}
} }
<CODE ENDS> }
<CODE ENDS>
YANG module with augmentations to YANG Library to revision labels YANG module with augmentations to YANG Library to revision labels
<CODE BEGINS> file "ietf-yl-revisions@2019-09-18.yang" <CODE BEGINS> file "ietf-yang-library-revisions@2020-07-06.yang"
module ietf-yl-revisions { module ietf-yang-library-revisions {
yang-version 1.1; yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-yl-revisions"; namespace "urn:ietf:params:xml:ns:yang:ietf-yang-library-revisions";
prefix yl-rev; prefix yl-rev;
import ietf-yang-revisions { import ietf-yang-revisions {
prefix rev; prefix rev;
reference reference
"XXXX: Updated YANG Module Revision Handling"; "XXXX: Updated YANG Module Revision Handling";
}
import ietf-yang-library { }
prefix yanglib;
reference "RFC 8525: YANG Libary";
}
organization import ietf-yang-library {
"IETF NETMOD (Network Modeling) Working Group"; prefix yanglib;
contact reference "RFC 8525: YANG Library";
"WG Web: <https://datatracker.ietf.org/wg/netmod/> }
WG List: <mailto:netmod@ietf.org>
Author: Benoit Claise organization
<mailto:bclaise@cisco.com> "IETF NETMOD (Network Modeling) Working Group";
contact
"WG Web: <https://datatracker.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org>
Author: Joe Clarke Author: Benoit Claise
<mailto:jclarke@cisco.com> <mailto:bclaise@cisco.com>
Author: Reshad Rahman Author: Joe Clarke
<mailto:rrahman@cisco.com> <mailto:jclarke@cisco.com>
Author: Robert Wilton Author: Reshad Rahman
<mailto:rwilton@cisco.com> <mailto:rrahman@cisco.com>
Author: Kevin D'Souza Author: Robert Wilton
<mailto:kd6913@att.com> <mailto:rwilton@cisco.com>
Author: Balazs Lengyel Author: Kevin D'Souza
<mailto:balazs.lengyel@ericsson.com> <mailto:kd6913@att.com>
Author: Jason Sterne Author: Balazs Lengyel
<mailto:jason.sterne@nokia.com>"; <mailto:balazs.lengyel@ericsson.com>
description
"This module contains augmentations to YANG Library to add module
level revision label and to provide an indication of how
deprecated and obsolete nodes are handled by the server.
Copyright (c) 2019 IETF Trust and the persons identified as Author: Jason Sterne
authors of the code. All rights reserved. <mailto:jason.sterne@nokia.com>";
description
"This module contains augmentations to YANG Library to add module
level revision label and to provide an indication of how
deprecated and obsolete nodes are handled by the server.
Redistribution and use in source and binary forms, with or Copyright (c) 2019 IETF Trust and the persons identified as
without modification, is permitted pursuant to, and subject authors of the code. All rights reserved.
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see Redistribution and use in source and binary forms, with or
the RFC itself for full legal notices. without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices.
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
'MAY', and 'OPTIONAL' in this document are to be interpreted as 'MAY', and 'OPTIONAL' in this document are to be interpreted as
described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
they appear in all capitals, as shown here."; they appear in all capitals, as shown here.";
// RFC Ed.: update the date below with the date of RFC publication // RFC Ed.: update the date below with the date of RFC publication
// and remove this note. // and remove this note.
// RFC Ed.: replace XXXX (including in the imports above) with // RFC Ed.: replace XXXX (including in the imports above) with
// actual RFC number and remove this note. // actual RFC number and remove this note.
// RFC Ed.: please replace revision-label version with 1.0.0 and // RFC Ed.: please replace revision-label version with 1.0.0 and
// remove this note. // remove this note.
revision 2019-09-18 { revision 2020-07-06 {
rev:revision-label 0.1.0; rev:revision-label 0.1.0;
description description
"Initial revision"; "Initial revision";
reference reference
"XXXX: Updated YANG Module Revision Handling"; "XXXX: Updated YANG Module Revision Handling";
} }
augment "/yanglib:yang-library/yanglib:module-set/yanglib:module" { augment "/yanglib:yang-library/yanglib:module-set/yanglib:module" {
description description
"Augmentation modules with a revision label"; "Augmentation modules with a revision label";
leaf revision-label { leaf revision-label {
type rev:revision-label; type rev:revision-label;
description description
"The revision label associated with this module revision. "The revision label associated with this module revision.
The label MUST match the rev:label value in the specific The label MUST match the rev:label value in the specific
revision of the module loaded in this module-set."; revision of the module loaded in this module-set.";
reference reference
"XXXX: Updated YANG Module Revision Handling; "XXXX: Updated YANG Module Revision Handling;
Section 5.2.1, Advertising revision-label"; Section 5.2.1, Advertising revision-label";
} }
} }
augment "/yanglib:yang-library/yanglib:schema" { augment "/yanglib:yang-library/yanglib:schema" {
description description
"Augmentations to the ietf-yang-library module to indicate how "Augmentations to the ietf-yang-library module to indicate how
deprecated and obsoleted nodes are handled for each datastore deprecated and obsoleted nodes are handled for each datastore
schema supported by the server."; schema supported by the server.";
leaf deprecated-nodes-implemented { leaf deprecated-nodes-implemented {
type empty; type boolean;
description description
"If present, this leaf indicates that all schema nodes with a "If set to true, this leaf indicates that all schema nodes with
status 'deprecated' child statement are implemented a status 'deprecated' child statement are implemented
equivalently as if they had status 'current', or otherwise equivalently as if they had status 'current', or otherwise
deviations MUST be used to explicitly remove 'deprecated' deviations MUST be used to explicitly remove 'deprecated'
nodes from the schema. If this leaf is absent then the nodes from the schema. If this leaf is set to false or absent,
behavior is unspecified."; then the behavior is unspecified.";
reference reference
"XXXX: Updated YANG Module Revision Handling; "XXXX: Updated YANG Module Revision Handling;
Section 5.2.2, Reporting how deprecated and obsolete nodes Section 5.2.2, Reporting how deprecated and obsolete nodes
are handled"; are handled";
} }
leaf obsolete-nodes-absent { leaf obsolete-nodes-absent {
type empty; type boolean;
description description
"If present, this leaf indicates that the server does not "If set to true, this leaf indicates that the server does not
implement any status 'obsolete' nodes. If this leaf is implement any status 'obsolete' nodes. If this leaf is
absent then the behaviour is unspecified."; set to false or absent, then the behaviour is unspecified.";
reference reference
"XXXX: Updated YANG Module Revision Handling; "XXXX: Updated YANG Module Revision Handling;
Section 5.2.2, Reporting how deprecated and obsolete nodes Section 5.2.2, Reporting how deprecated and obsolete nodes
are handled"; are handled";
} }
} }
} }
CODE ENDS> <CODE ENDS>
9. Contributors 9. 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 o Balazs Lengyel
skipping to change at page 25, line 45 skipping to change at page 27, line 14
o Mahesh Jethanandani o Mahesh Jethanandani
o Michael (Wangzitao) o Michael (Wangzitao)
o Qin Wu o Qin Wu
o Reshad Rahman o Reshad Rahman
o Rob Wilton o Rob Wilton
o Bo Wu
The initial revision of this document was refactored and built upon The initial revision of this document was refactored and built upon
[I-D.clacla-netmod-yang-model-update]. [I-D.clacla-netmod-yang-model-update].
Discussons on the use of Semver for YANG versioning has been held Discussons on the use of Semver for YANG versioning has been held
with authors of the OpenConfig YANG models. We would like thank both with authors of the OpenConfig YANG models. We would like thank both
Anees Shaikh and Rob Shakir for their input into this problem space. Anees Shaikh and Rob Shakir for their input into this problem space.
We would also like to thank Martin Bjorklund, Jan Lindblad and Italo
Busi for their contributions.
10. Security Considerations 10. 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 considerations beyond those specified in [RFC7950].
11. IANA Considerations 11. IANA Considerations
11.1. YANG Module Registrations 11.1. YANG Module Registrations
The following YANG module is requested to be registred in the "IANA The following YANG module is requested to be registred in the "IANA
Module Names" registry: Module Names" registry:
The ietf-yang-revisions module: The ietf-yang-revisions module:
Name: ietf-yang-revisions Name: ietf-yang-revisions
XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-revisions XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-revisions
Prefix: rev Prefix: rev
Reference: [RFCXXXX] Reference: [RFCXXXX]
The ietf-yl-revisions module: The ietf-yang-library-revisions module:
Name: ietf-yl-revisions
XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yl-revisions Name: ietf-yang-library-revisions
XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-library-
revisions
Prefix: yl-rev Prefix: yl-rev
Reference: [RFCXXXX] Reference: [RFCXXXX]
11.2. Instructions
We may need to give new instructions to IANA e.g. how to review
revision-label statements to make sure they are accurate? TBD
12. References 12. References
12.1. Normative References 12.1. Normative References
[I-D.ietf-netmod-rfc6991-bis] [I-D.ietf-netmod-rfc6991-bis]
Schoenwaelder, J., "Common YANG Data Types", draft-ietf- Schoenwaelder, J., "Common YANG Data Types", draft-ietf-
netmod-rfc6991-bis-02 (work in progress), November 2019. netmod-rfc6991-bis-04 (work in progress), July 2020.
[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", draft-ietf-netmod-yang-semver-00 (work in
progress), October 2019. progress), March 2020.
[I-D.verdt-netmod-yang-versioning-reqs]
Clarke, J., "YANG Module Versioning Requirements", draft-
verdt-netmod-yang-versioning-reqs-02 (work in progress),
November 2018.
[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 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, Library", RFC 7895, DOI 10.17487/RFC7895, June 2016,
<https://www.rfc-editor.org/info/rfc7895>. <https://www.rfc-editor.org/info/rfc7895>.
skipping to change at page 27, line 46 skipping to change at page 29, line 19
12.2. Informative References 12.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", draft-clacla-netmod-yang-
model-update-06 (work in progress), July 2018. model-update-06 (work in progress), July 2018.
[I-D.ietf-netmod-yang-instance-file-format] [I-D.ietf-netmod-yang-instance-file-format]
Lengyel, B. and B. Claise, "YANG Instance Data File Lengyel, B. and B. Claise, "YANG Instance Data File
Format", draft-ietf-netmod-yang-instance-file-format-08 Format", draft-ietf-netmod-yang-instance-file-format-12
(work in progress), March 2020. (work in progress), April 2020.
[I-D.rwilton-netmod-yang-packages] [I-D.ietf-netmod-yang-packages]
Wilton, R., Rahman, R., Clarke, J., Sterne, J., and W. Bo, Wilton, R., Rahman, R., Clarke, J., Sterne, J., and W. Bo,
"YANG Packages", draft-rwilton-netmod-yang-packages-03 "YANG Packages", draft-ietf-netmod-yang-packages-00 (work
(work in progress), February 2020. in progress), March 2020.
[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", draft-
verdt-netmod-yang-solutions-03 (work in progress), ietf-netmod-yang-solutions-00 (work in progress), March
February 2020. 2020.
[I-D.wilton-netmod-yang-ver-selection] [I-D.ietf-netmod-yang-ver-selection]
Wilton, R., Rahman, R., Clarke, J., Sterne, J., and W. Bo, Wilton, R., Rahman, R., Clarke, J., Sterne, J., and W. Bo,
"YANG Schema Selection", draft-wilton-netmod-yang-ver- "YANG Schema Selection", draft-ietf-netmod-yang-ver-
selection-02 (work in progress), February 2020. selection-00 (work in progress), March 2020.
[I-D.ietf-netmod-yang-versioning-reqs]
Clarke, J., "YANG Module Versioning Requirements", draft-
ietf-netmod-yang-versioning-reqs-03 (work in progress),
June 2020.
[RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
<https://www.rfc-editor.org/info/rfc8340>. <https://www.rfc-editor.org/info/rfc8340>.
[semver] "Semantic Versioning 2.0.0", <https://www.semver.org>. [semver] "Semantic Versioning 2.0.0", <https://www.semver.org>.
Appendix A. Appendix Appendix A. Examples of changes that are NBC
A.1. Examples of guidelines for making NBC changes to a YANG module
Examples of NBC changes include: Examples of NBC changes include:
o Deleting a data node, or changing it to status obsolete. o Deleting a data node, or changing it to status obsolete.
o Changing the name, type, or units of a data node. o Changing the name, type, or units of a data node.
o Modifying the description in a way that changes the semantic o Modifying the description in a way that changes the semantic
meaning of the data node. meaning of the data node.
o Any changes that change or reduce the allowed value set of the o Any changes that change or reduce the allowed value set of the
data node, either through changes in the type definition, or the data node, either through changes in the type definition, or the
addition or changes to "must" statements, or changes in the addition or changes to "must" statements, or changes in the
description. description.
o Adding or modifying "when" statements that reduce when the data o Adding or modifying "when" statements that reduce when the data
node is available in the schema. node is available in the schema.
o Making the statement conditional on if-feature. o Making the statement conditional on if-feature.
Appendix B. Examples of applying the NBC change guidelines
The following sections give guidance for how some of these NBC The following sections give guidance for how some of these NBC
changes could be made to a YANG module: changes could be made to a YANG module. The examples are all for
"config true" nodes.
A.1.1. Removing a data node B.1. Removing a data node
Removing a leaf or container from the data tree, e.g. because support Removing a leaf or container from the data tree, e.g. because support
for the corresponding feature is being removed: for the corresponding feature is being removed:
1. The node's status is changed to "deprecated" and it is supported 1. The node's status is changed to "deprecated" and it is supported
for at least one year. This is a BC change. for at least one year. This is a BC change.
2. When the node is not available anymore, its status is changed to 2. When the node is not available anymore, its status is changed to
"obsolete" and the "status-description" updated, this is an NBC "obsolete" and the "description" updated, this is an NBC change.
change. The "status-description" is used to explain why the node
is not available anymore.
If the server can support NBC versions of the YANG module If the server can support NBC revisions of the YANG module
simultaneously using version selection, then the changes can be done simultaneously using version selection
[I-D.ietf-netmod-yang-ver-selection], then the changes can be done
immediately: immediately:
1. The new revision of the YANG module has the node's status changed 1. The new revision of the YANG module has the node's status changed
to "obsolete" and the "status-description" updated, this is an to "obsolete" and the "description" updated, this is an NBC
NBC change. change.
2. Clients which require the data node select the older module 2. Clients which require the data node select the YANG package
revision containing the schema version they use
A.1.2. Changing the type of a leaf node B.2. Changing the type of a leaf node
Changing the type of a leaf-node. e.g. consider a "vpn-id" node of Changing the type of a leaf-node. e.g. consider a "vpn-id" node of
type integer being changed to a string: type integer being changed to a string:
1. The status of node "vpn-id" is changed to "deprecated" and the 1. The status of node "vpn-id" is changed to "deprecated" and the
node should be available for at least one year. This is a BC node should be available for at least one year. This is a BC
change. change.
2. A new node, e.g. "vpn-name", of type string is added to the same 2. A new node, e.g. "vpn-name", of type string is added to the same
location as the existing node "vpn-id". This new node has status location as the existing node "vpn-id". This new node has status
skipping to change at page 30, line 5 skipping to change at page 31, line 35
node is already set (and vice-versa). The new node may have node is already set (and vice-versa). The new node may have
a when statement to achieve this. The old node must not have a when statement to achieve this. The old node must not have
a when statement since this would be an NBC change, but the a when statement since this would be an NBC change, but the
server could reject the old node from being set if the new server could reject the old node from being set if the new
node is already set. node is already set.
2. If the new node is set and a client does a get or get-config 2. If the new node is set and a client does a get or get-config
operation on the old node, the server could map the value. operation on the old node, the server could map the value.
For example, if the new node "vpn-name" has value "123" then For example, if the new node "vpn-name" has value "123" then
the server could return integer value 123 for the old node the server could return integer value 123 for the old node
"vpn-id". However, if the value can not be mapped, we need a "vpn-id". However, if the value can not be mapped then the
way of returning "unsupported" TBD. configuration would be incomplete, this is outside the scope
of this document.
4. When node "vpn-id" is not available anymore, its status is 4. When node "vpn-id" is not available anymore, its status is
changed to "obsolete" and the "status-description" is updated. changed to "obsolete" and the "description" is updated. This is
This is an NBC change. an NBC change.
If the server can support NBC versions of the YANG module If the server can support NBC revisions of the YANG module
simultaneously using version selection, then the changes can be done simultaneously using version selection
[I-D.ietf-netmod-yang-ver-selection], then the changes can be done
immediately: immediately:
1. In the new revision of the YANG module, the status of node "vpn- 1. In the new revision of the YANG module, the status of node "vpn-
id" is changed to "obsolete". This is an NBC change. id" is changed to "obsolete". This is an NBC change.
2. New node "vpn-name" is added to the same location as described 2. New node "vpn-name" is added to the same location as described
above. above.
3. Clients which require the data node select the older module 3. Clients which require the data node select the YANG package
revision containing the schema version they use
4. A server should not map between the nodes "vpn-id" and "vpn- 4. A server should not map between the nodes "vpn-id" and "vpn-
name", i.e. if a client creates a data instance with "vpn-name" name", i.e. if a client creates a data instance with "vpn-name"
then that data instance should not be visible to a client using a then that data instance should not be visible to a client using a
module revision which has "vpn-id" (and vice-versa). module revision which has "vpn-id" (and vice-versa).
A.1.3. Reducing the range of a leaf node B.3. Reducing the range of a leaf node
Reducing the range of values of a leaf-node. e.g. consider a "vpn-id" Reducing the range of values of a leaf-node. e.g. consider a "vpn-id"
node of type integer being changed from type uint32 to type uint16: node of type integer being changed from type uint32 to type uint16:
1. If all values which are being removed were never supported, e.g. 1. If all values which are being removed were never supported, e.g.
if a vpn-id of 65536 or higher was never accepted, this is a BC if a vpn-id of 65536 or higher was never accepted, this is a BC
change for the functionality (no functionality change). Even if change for the functionality (no functionality change). Even if
it is an NBC change for the YANG model, there should be no impact it is an NBC change for the YANG model, there should be no impact
for clients using that YANG model. for clients using that YANG model.
2. If one or more values being removed was previously supported, 2. If one or more values being removed was previously supported,
e.g. if a vpn-id of 65536 was accepted previously, this is an NBC e.g. if a vpn-id of 65536 was accepted previously, this is an NBC
change for the YANG model. Clients using the old YANG model will change for the YANG model. Clients using the old YANG model will
be impacted, so a change of this nature should be done carefully, be impacted, so a change of this nature should be done carefully,
e.g. by using the steps described in Appendix A.1.2 e.g. by using the steps described in Appendix B.2
A.1.4. Changing the key of a list B.4. Changing the key of a list
Changing the key of a list has a big impact to the client. For Changing the key of a list has a big impact to the client. For
example, consider a "sessions" list which has a key "interface" and example, consider a "sessions" list which has a key "interface" and
there is a need to change the key to "dest-address", such a change there is a need to change the key to "dest-address", such a change
can be done in steps: can be done in steps:
1. The status of list "sessions" is changed to "deprecated" and the 1. The status of list "sessions" is changed to "deprecated" and the
list should be available for at least one year. This is a BC list should be available for at least one year. This is a BC
change. change.
skipping to change at page 31, line 32 skipping to change at page 33, line 14
1. A server could prevent the new list from being set if the old 1. A server could prevent the new list from being set if the old
list already has entries (and vice-versa). list already has entries (and vice-versa).
2. If the new list is set and a client does a get or get-config 2. If the new list is set and a client does a get or get-config
operation on the old list, the server could map the entries. operation on the old list, the server could map the entries.
However if the new list has entries which would lead to However if the new list has entries which would lead to
duplicate keys in the old list, the mapping can not be done. duplicate keys in the old list, the mapping can not be done.
4. When list "sessions" is not available anymore, its status is 4. When list "sessions" is not available anymore, its status is
changed to "obsolete" and the "status-description" is updated. changed to "obsolete" and the "description" is updated. This is
This is an NBC change. an NBC change.
If the server can support NBC versions of the YANG module If the server can support NBC revisions of the YANG module
simultaneously using version selection, then the changes can be done simultaneously using version selection
[I-D.ietf-netmod-yang-ver-selection], then the changes can be done
immediately: immediately:
1. The new revision of the YANG module has the list "sessions" 1. The new revision of the YANG module has the list "sessions"
modified to have "dest-address" as key, this is an NBC change. modified to have "dest-address" as key, this is an NBC change.
2. Clients which require the previous functionality select the older 2. Clients which require the previous functionality select the older
module revision module revision
A.1.5. Renaming a node B.5. Renaming a node
A leaf-node or a container may be renamed, either due to a spelling A leaf-node or a container may be renamed, either due to a spelling
error in the previous name or because of a better name. For example error in the previous name or because of a better name. For example
a node "ip-adress" could be renamed to "ip-address": a node "ip-adress" could be renamed to "ip-address":
1. The status of the existing node "ip-adress" is changed to 1. The status of the existing node "ip-adress" is changed to
"deprecated" and the node should be available for at least one "deprecated" and the node should be available for at least one
year. This is a BC change. year. This is a BC change.
2. The new node "ip-address" is added to the same location as the 2. The new node "ip-address" is added to the same location as the
skipping to change at page 32, line 33 skipping to change at page 34, line 14
the server could reject the old node from being set if the the server could reject the old node from being set if the
new node is already set. new node is already set.
2. If the new node is set and a client does a get or get-config 2. If the new node is set and a client does a get or get-config
operation on the old node, the server could use the value of operation on the old node, the server could use the value of
the new node. For example, if the new node "ip-address" has the new node. For example, if the new node "ip-address" has
value X then the server may return value X for the old node value X then the server may return value X for the old node
"ip-adress". "ip-adress".
4. When node "ip-adress" is not available anymore, its status is 4. When node "ip-adress" is not available anymore, its status is
changed to "obsolete" and the "status-description" is updated. changed to "obsolete" and the "description" is updated. This is
This is an NBC change. an NBC change.
If the server can support NBC versions of the YANG module If the server can support NBC revisions of the YANG module
simultaneously using version selection, then the changes can be done simultaneously using version selection
[I-D.ietf-netmod-yang-ver-selection], then the changes can be done
immediately: immediately:
1. The new revision of the YANG module has the node with the new 1. The new revision of the YANG module has the node with the new
name replacing the node with the old name, this is an NBC change. name replacing the node with the old name, this is an NBC change.
2. Clients which require the previous node name select the older 2. Clients which require the previous node name select the older
module revision module revision
A.1.6. Changing a default value B.6. Changing a default value
Authors' Addresses Appendix C. Changes between revisions
Benoit Claise
Cisco Systems, Inc.
De Kleetlaan 6a b1
1831 Diegem
Belgium
Phone: +32 2 704 5622 Note to RFC Editor (To be removed by RFC Editor)
Email: bclaise@cisco.com
Joe Clarke v00 - v01
Cisco Systems, Inc.
7200-12 Kit Creek Rd
Research Triangle Park, North Carolina
United States of America
Phone: +1-919-392-2867 o Removed status-description
Email: jclarke@cisco.com
Reshad Rahman o Allowed both revision-date and revision-label in the filename.
Cisco Systems, Inc.
Email: rrahman@cisco.com o New extension revision-label-scheme
o To include submodules, inclusion by revision-date changed from
MUST to SHOULD
o Submodules can use revision label scheme and it can be same or
different as the including module's scheme
o Addressed various comments provided at WG adoption on rev-00
Authors' Addresses
Robert Wilton (editor) Robert Wilton (editor)
Cisco Systems, Inc. Cisco Systems, Inc.
Email: rwilton@cisco.com Email: rwilton@cisco.com
Balazs Lengyel Reshad Rahman (editor)
Cisco Systems, Inc.
Email: rrahman@cisco.com
Balazs Lengyel (editor)
Ericsson Ericsson
Magyar Tudosok Korutja
1117 Budapest
Hungary
Phone: +36-70-330-7909
Email: balazs.lengyel@ericsson.com Email: balazs.lengyel@ericsson.com
Joe Clarke
Cisco Systems, Inc.
Email: jclarke@cisco.com
Jason Sterne Jason Sterne
Nokia Nokia
Email: jason.sterne@nokia.com Email: jason.sterne@nokia.com
Benoit Claise
Cisco Systems, Inc.
Email: bclaise@cisco.com
Kevin D'Souza Kevin D'Souza
AT&T AT&T
200 S. Laurel Ave
Middletown, NJ
United States of America
Email: kd6913@att.com Email: kd6913@att.com
 End of changes. 187 change blocks. 
525 lines changed or deleted 623 lines changed or added

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