draft-ietf-netmod-yang-module-versioning-04.txt   draft-ietf-netmod-yang-module-versioning-05.txt 
Network Working Group R. Wilton, Ed. Network Working Group R. Wilton, Ed.
Internet-Draft Cisco Systems, Inc. Internet-Draft Cisco Systems, Inc.
Updates: 7950, 8407, 8525 (if approved) R. Rahman, Ed. Updates: 6020,7950,8407,8525 (if R. Rahman, Ed.
Intended status: Standards Track approved)
Expires: 28 April 2022 B. Lengyel, Ed. Intended status: Standards Track B. Lengyel, Ed.
Ericsson Expires: May 12, 2022 Ericsson
J. Clarke J. Clarke
Cisco Systems, Inc. Cisco Systems, Inc.
J. Sterne J. Sterne
Nokia Nokia
25 October 2021 November 8, 2021
Updated YANG Module Revision Handling Updated YANG Module Revision Handling
draft-ietf-netmod-yang-module-versioning-04 draft-ietf-netmod-yang-module-versioning-05
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 guidelines for managing the lifecycle of dependencies. It provides guidelines for managing the lifecycle of
YANG modules and individual schema nodes. It provides a mechanism, YANG modules and individual schema nodes. It provides a mechanism,
via the revision-label YANG extension, to specify a revision via the revision-label YANG extension, to specify a revision
skipping to change at page 1, line 45 skipping to change at page 1, line 45
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 28 April 2022. This Internet-Draft will expire on May 12, 2022.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2021 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 (https://trustee.ietf.org/ Provisions Relating to IETF Documents
license-info) in effect on the date of publication of this document. (https://trustee.ietf.org/license-info) in effect on the date of
Please review these documents carefully, as they describe your rights publication of this document. Please review these documents
and restrictions with respect to this document. Code Components carefully, as they describe your rights and restrictions with respect
extracted from this document must include Simplified BSD License text to this document. Code Components extracted from this document must
as described in Section 4.e of the Trust Legal Provisions and are include Simplified BSD License text as described in Section 4.e of
provided without warranty as described in the Simplified BSD License. the Trust Legal Provisions and are provided without warranty as
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 . . . . . . . 6 3.1. Updating a YANG module with a new revision . . . . . . . 6
3.1.1. Backwards-compatible rules . . . . . . . . . . . . . 6 3.1.1. Backwards-compatible rules . . . . . . . . . . . . . 6
3.1.2. Non-backwards-compatible changes . . . . . . . . . . 7 3.1.2. Non-backwards-compatible changes . . . . . . . . . . 7
3.2. non-backwards-compatible revision extension statement . . 7 3.2. non-backwards-compatible revision extension statement . . 7
3.3. Removing revisions from the revision history . . . . . . 7 3.3. Removing revisions from the revision history . . . . . . 7
3.4. Revision label . . . . . . . . . . . . . . . . . . . . . 9 3.4. Revision label . . . . . . . . . . . . . . . . . . . . . 9
3.4.1. File names . . . . . . . . . . . . . . . . . . . . . 10 3.4.1. File names . . . . . . . . . . . . . . . . . . . . . 10
3.4.2. Revision label scheme extension statement . . . . . . 10 3.4.2. Revision label scheme extension statement . . . . . . 10
3.5. Examples for updating the YANG module revision history . 11 3.5. Examples for updating the YANG module revision history . 11
4. Import by derived revision . . . . . . . . . . . . . . . . . 13 4. Import by derived revision . . . . . . . . . . . . . . . . . 13
4.1. Module import examples . . . . . . . . . . . . . . . . . 15 4.1. Module import examples . . . . . . . . . . . . . . . . . 14
5. Updates to ietf-yang-library . . . . . . . . . . . . . . . . 16 5. Updates to ietf-yang-library . . . . . . . . . . . . . . . . 16
5.1. Resolving ambiguous module imports . . . . . . . . . . . 16 5.1. Resolving ambiguous module imports . . . . . . . . . . . 16
5.2. YANG library versioning augmentations . . . . . . . . . . 17 5.2. YANG library versioning augmentations . . . . . . . . . . 17
5.2.1. Advertising revision-label . . . . . . . . . . . . . 17 5.2.1. Advertising revision-label . . . . . . . . . . . . . 17
5.2.2. Reporting how deprecated and obsolete nodes are 5.2.2. Reporting how deprecated and obsolete nodes are
handled . . . . . . . . . . . . . . . . . . . . . . . 17 handled . . . . . . . . . . . . . . . . . . . . . . . 17
6. Versioning of YANG instance data . . . . . . . . . . . . . . 18 6. Versioning of YANG instance data . . . . . . . . . . . . . . 18
7. Guidelines for using the YANG module update rules . . . . . . 18 7. Guidelines for using the YANG module update rules . . . . . . 18
7.1. Guidelines for YANG module authors . . . . . . . . . . . 19 7.1. Guidelines for YANG module authors . . . . . . . . . . . 18
7.1.1. Making non-backwards-compatible changes to a YANG 7.1.1. Making non-backwards-compatible changes to a YANG
module . . . . . . . . . . . . . . . . . . . . . . . 20 module . . . . . . . . . . . . . . . . . . . . . . . 19
7.2. Versioning Considerations for Clients . . . . . . . . . . 21 7.2. Versioning Considerations for Clients . . . . . . . . . . 21
8. Module Versioning Extension YANG Modules . . . . . . . . . . 22 8. Module Versioning Extension YANG Modules . . . . . . . . . . 21
9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 31 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 30
10. Security Considerations . . . . . . . . . . . . . . . . . . . 32 10. Security Considerations . . . . . . . . . . . . . . . . . . . 31
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31
11.1. YANG Module Registrations . . . . . . . . . . . . . . . 32 11.1. YANG Module Registrations . . . . . . . . . . . . . . . 31
11.2. Guidance for versioning in IANA maintained YANG 11.2. Guidance for versioning in IANA maintained YANG modules 32
modules . . . . . . . . . . . . . . . . . . . . . . . . 33 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 33
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 34 12.1. Normative References . . . . . . . . . . . . . . . . . . 33
12.1. Normative References . . . . . . . . . . . . . . . . . . 34 12.2. Informative References . . . . . . . . . . . . . . . . . 34
12.2. Informative References . . . . . . . . . . . . . . . . . 35 Appendix A. Examples of changes that are NBC . . . . . . . . . . 36
Appendix A. Examples of changes that are NBC . . . . . . . . . . 37 Appendix B. Examples of applying the NBC change guidelines . . . 36
Appendix B. Examples of applying the NBC change guidelines . . . 37 B.1. Removing a data node . . . . . . . . . . . . . . . . . . 36
B.1. Removing a data node . . . . . . . . . . . . . . . . . . 38 B.2. Changing the type of a leaf node . . . . . . . . . . . . 37
B.2. Changing the type of a leaf node . . . . . . . . . . . . 38 B.3. Reducing the range of a leaf node . . . . . . . . . . . . 38
B.3. Reducing the range of a leaf node . . . . . . . . . . . . 39 B.4. Changing the key of a list . . . . . . . . . . . . . . . 38
B.4. Changing the key of a list . . . . . . . . . . . . . . . 39 B.5. Renaming a node . . . . . . . . . . . . . . . . . . . . . 39
B.5. Renaming a node . . . . . . . . . . . . . . . . . . . . . 40 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 40
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 41
1. Introduction 1. Introduction
This document defines the foundational pieces of a solution to the This document defines the foundational pieces of a solution to the
YANG module lifecycle problems described in YANG module lifecycle problems described in
[I-D.ietf-netmod-yang-versioning-reqs]. Complementary documents [I-D.ietf-netmod-yang-versioning-reqs]. Complementary documents
provide other parts of the solution, with the overall relationship of provide other parts of the solution, with the overall relationship of
the solution drafts described in [I-D.ietf-netmod-yang-solutions]. the 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 document 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 and submodule descriptions, to report revision label in the module and submodule descriptions, to report
how "deprecated" and "obsolete" nodes are handled by a server, and how "deprecated" and "obsolete" nodes are handled by a server, and
to clarify how module imports are resolved when multiple revisions to 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) 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 and [RFC6020] section 10. This document updates [RFC7950] section 11 and [RFC6020] section 10.
Section 3 describes modifications to YANG revision handling and Section 3 describes modifications to YANG revision handling and
update rules, and Section 4 describes a YANG extension statement to update rules, and Section 4 describes a YANG extension statement to
do import by derived revision. do import by derived revision.
This document updates [RFC7950] section 5.2 and [RFC6020] section This document updates [RFC7950] section 5.2 and [RFC6020] section
5.2. Section 3.4.1 describes the use of a revision label in the name 5.2. Section 3.4.1 describes the use of a revision label in the name
skipping to change at page 4, line 47 skipping to change at page 4, line 47
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 following terminology: In addition, this document uses the following terminology:
* YANG module revision: An instance of a YANG module, uniquely o YANG module revision: An instance of a YANG module, uniquely
identified with a revision date, with no implied ordering or identified with a revision date, with no implied ordering or
backwards compatibility between different revisions of the same backwards compatibility between different revisions of the same
module. module.
* Backwards-compatible (BC) change: A backwards-compatible change o Backwards-compatible (BC) change: A backwards-compatible change
between two YANG module revisions, as defined in Section 3.1.1 between two YANG module revisions, as defined in Section 3.1.1
* Non-backwards-compatible (NBC) change: A non-backwards-compatible o Non-backwards-compatible (NBC) change: A non-backwards-compatible
change between two YANG module revisions, as defined in change between two YANG module revisions, as defined in
Section 3.1.2 Section 3.1.2
3. Refinements to YANG revision handling 3. Refinements to YANG revision handling
[RFC7950] and [RFC6020] assume, but do not explicitly state, that the [RFC7950] and [RFC6020] assume, but do not explicitly state, that the
revision history for a YANG module or submodule is strictly linear, revision history for a YANG module or submodule is strictly linear,
i.e., it is prohibited to have two independent revisions of a YANG i.e., it is prohibited to have two independent revisions of a YANG
module or submodule that are both directly derived from the same module or submodule that are both directly derived from the same
parent revision. parent revision.
skipping to change at page 6, line 38 skipping to change at page 6, line 38
changes to any whitespace, formatting, comments or line endings changes to any whitespace, formatting, comments or line endings
(e.g., DOS vs UNIX). (e.g., DOS vs UNIX).
3.1.1. Backwards-compatible rules 3.1.1. Backwards-compatible rules
A change between two module revisions is defined as being "backwards- A change between two module revisions is defined as being "backwards-
compatible" if the change conforms to the module update rules compatible" if the change conforms to the module update rules
specified in [RFC7950] section 11 and [RFC6020] section 10, updated specified in [RFC7950] section 11 and [RFC6020] section 10, updated
by the following rules: by the following rules:
* A "status" "deprecated" statement MAY be added, or changed from o A "status" "deprecated" statement MAY be added, or changed from
"current" to "deprecated", but adding or changing "status" to "current" to "deprecated", but adding or changing "status" to
"obsolete" is not a backwards-compatible change. "obsolete" is not a backwards-compatible change.
* YANG schema nodes with a "status" "obsolete" substatement MAY be o YANG schema nodes with a "status" "obsolete" substatement MAY be
removed from published modules, and are classified as backwards- removed from published modules, and are classified as backwards-
compatible changes. In some circumstances it may be helpful to compatible changes. In some circumstances it may be helpful to
retain the obsolete definitions since their identifiers may still retain the obsolete definitions since their identifiers may still
be referenced by other modules and to ensure that their be referenced by other modules and to ensure that their
identifiers are not reused with a different meaning. identifiers are not reused with a different meaning.
* 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 of any reordered, as long as they do not change the ordering of any
"input" or "output" data definition substatements of "rpc" or "input" or "output" data definition substatements of "rpc" or
"action" statements. If new data definition statements are added, "action" statements. If new data definition statements are added,
they can be added anywhere in the sequence of existing they can be added anywhere in the sequence of existing
substatements. substatements.
* A statement that is defined using the YANG "extension" statement o A statement that is defined using the YANG "extension" statement
MAY be added, removed, or changed, if it does not change the MAY be added, removed, or changed, if it does not change the
semantics of the module. Extension statement definitions SHOULD semantics of the module. Extension statement definitions SHOULD
specify whether adding, removing, or changing statements defined specify whether adding, removing, or changing statements defined
by that extension are backwards-compatible or non-backwards- by that extension are backwards-compatible or non-backwards-
compatible. compatible.
* Any changes (including whitespace or formatting changes) that do o Any changes (including whitespace or formatting changes) that do
not change the semantic meaning of the module are backwards not change the semantic meaning of the module are backwards
compatible. 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. non-backwards-compatible revision extension statement 3.2. non-backwards-compatible revision extension statement
skipping to change at page 10, line 33 skipping to change at page 10, line 33
label, MAY exist for the same module (or submodule) revision, e.g., label, MAY exist for the same module (or submodule) revision, e.g.,
when migrating from one scheme to the other. when migrating from one scheme to the other.
3.4.2. Revision label scheme extension statement 3.4.2. Revision label scheme extension statement
The optional "rev:revision-label-scheme" extension statement is used The optional "rev:revision-label-scheme" extension statement is used
to indicate which revision-label scheme a module or submodule uses. to indicate which revision-label scheme a module or submodule uses.
There MUST NOT be more than one revision label scheme in a module or There MUST NOT be more than one revision label scheme in a module or
submodule. The mandatory argument to this extension statement: submodule. The mandatory argument to this extension statement:
* specifies the revision-label scheme used by the module or o specifies the revision-label scheme used by the module or
submodule submodule
* is defined in the document which specifies the revision-label o is defined in the document which specifies the revision-label
scheme scheme
* MUST be an identity derived from "revision-label-scheme-base". o MUST be an identity derived from "revision-label-scheme-base".
The revision-label scheme used by a module or submodule SHOULD NOT The revision-label scheme used by a module or submodule SHOULD NOT
change during the lifetime of the module or submodule. If the change during the lifetime of the module or submodule. If the
revision-label scheme used by a module or submodule is changed to a 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 new scheme, then all revision-label statements that do not conform to
the new scheme MUST be replaced or removed. the new scheme MUST be replaced or removed.
3.5. Examples for updating the YANG module revision history 3.5. Examples for updating the YANG module revision history
The following diagram, explanation, and module history illustrates The following diagram, explanation, and module history illustrates
skipping to change at page 19, line 46 skipping to change at page 19, line 28
A module that includes submodules SHOULD use the "revision-date" A module that includes submodules SHOULD use the "revision-date"
statement to include specific submodule revisions. The revision of statement to include specific submodule revisions. The revision of
the including module MUST be updated when any included submodule has the including module MUST be updated when any included submodule has
changed. changed.
In some cases a module or submodule revision that is not strictly NBC In some cases a module or submodule revision that is not strictly NBC
by the definition in Section 3.1.2 of this specification may include by the definition in Section 3.1.2 of this specification may include
the "non-backwards-compatible" statement. Here is an example when the "non-backwards-compatible" statement. Here is an example when
adding the statement may be desirable: adding the statement may be desirable:
* A "config false" leaf had its value space expanded (for example, a o A "config false" leaf had its value space expanded (for example, a
range was increased, or additional enum values were added) and the range was increased, or additional enum values were added) and the
author or server implementor feels there is a significant author or server implementor feels there is a significant
compatibility impact for clients and users of the module or compatibility impact for clients and users of the module or
submodule submodule
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:
* 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.
* 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.
* If the server can support multiple revisions 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]), and allows the client to select [I-D.ietf-netmod-yang-packages]), and allows the client to select
the revision (as per [I-D.ietf-netmod-yang-ver-selection]), then the revision (as per [I-D.ietf-netmod-yang-ver-selection]), then
NBC changes MAY be done without using "status" statements. NBC changes MAY be done without using "status" statements.
Clients would be required to select the revision which they Clients would be required to select the revision which they
support and the NBC change would have no impact on them. support and the NBC change would 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
skipping to change at page 21, line 33 skipping to change at page 21, line 12
of removing a node, that node SHOULD first be deprecated and then of removing a node, that node SHOULD first be deprecated and then
obsoleted. obsoleted.
See Appendix B 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:
* 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.
* Clients SHOULD monitor changes to published YANG modules through o Clients SHOULD monitor changes to published YANG modules through
their revision history, and use appropriate tooling to understand their revision history, and use appropriate tooling to understand
the specific changes between module revision. In particular, the specific changes between module revision. In particular,
clients SHOULD NOT migrate to NBC revisions of a module without clients SHOULD NOT migrate to NBC revisions of a module without
understanding any potential impact of the specific NBC changes. understanding any potential impact of the specific NBC changes.
* 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, revision label scheme, and importing by revision. revision label, revision label scheme, and importing by revision.
<CODE BEGINS> file "ietf-yang-revisions@2021-06-30.yang" <CODE BEGINS> file "ietf-yang-revisions@2021-11-04.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;
// RFC Ed.: We need the bis version to get the new type revision-identifier // RFC Ed.: We need the bis version to get the new type revision-identifier
// If 6991-bis is not yet an RFC we need to copy the definition here // If 6991-bis is not yet an RFC we need to copy the definition here
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: Joe Clarke
<mailto:jclarke@cisco.com>
Author: Joe Clarke Author: Reshad Rahman
<mailto:jclarke@cisco.com> <mailto:reshad@yahoo.com>
Author: Reshad Rahman Author: Robert Wilton
<mailto:reshad@yahoo.com> <mailto:rwilton@cisco.com>
Author: Robert Wilton Author: Balazs Lengyel
<mailto:rwilton@cisco.com> <mailto:balazs.lengyel@ericsson.com>
Author: Balazs Lengyel Author: Jason Sterne
<mailto:balazs.lengyel@ericsson.com> <mailto:jason.sterne@nokia.com>";
description
"This YANG 1.1 module contains definitions and extensions to
support updated YANG revision handling.
Author: Jason Sterne Copyright (c) 2021 IETF Trust and the persons identified as
<mailto:jason.sterne@nokia.com>"; authors of the code. All rights reserved.
description
"This YANG 1.1 module contains definitions and extensions to
support updated YANG revision handling.
Copyright (c) 2021 IETF Trust and the persons identified as Redistribution and use in source and binary forms, with or
authors of the code. All rights reserved. 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).
Redistribution and use in source and binary forms, with or This version of this YANG module is part of RFC XXXX; see
without modification, is permitted pursuant to, and subject the RFC itself for full legal notices.
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 key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
the RFC itself for full legal notices. NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
'MAY', and 'OPTIONAL' in this document are to be interpreted as
described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
they appear in all capitals, as shown here.";
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL // RFC Ed.: update the date below with the date of RFC publication
NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', // and remove this note.
'MAY', and 'OPTIONAL' in this document are to be interpreted as // RFC Ed.: replace XXXX (inc above) with actual RFC number and
described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, // remove this note.
they appear in all capitals, as shown here.";
// RFC Ed.: update the date below with the date of RFC publication revision 2021-11-04 {
// and remove this note. rev:revision-label 1.0.0-draft-ietf-netmod-yang-module-versioning-05;
// RFC Ed.: replace XXXX (inc above) with actual RFC number and description
// remove this note. "Initial version.";
reference
"XXXX: Updated YANG Module Revision Handling";
revision 2021-06-30 { }
rev:revision-label 1.0.0-draft-ietf-netmod-yang-module-versioning-04;
description
"Initial version.";
reference
"XXXX: Updated YANG Module Revision Handling";
}
typedef revision-label { typedef revision-label {
type string { type string {
length "1..255"; length "1..255";
pattern '[a-zA-Z0-9,\-_.+]+'; pattern '[a-zA-Z0-9,\-_.+]+';
pattern '\d{4}-\d{2}-\d{2}' { pattern '\d{4}-\d{2}-\d{2}' {
modifier invert-match; modifier invert-match;
} }
} }
description description
"A label associated with a YANG revision. "A label associated with a YANG revision.
Alphanumeric characters, comma, hyphen, underscore, period Alphanumeric characters, comma, hyphen, underscore, period
and plus are the only accepted characters. MUST NOT match and plus are the only accepted characters. MUST NOT match
revision-date."; revision-date.";
reference reference
"XXXX: Updated YANG Module Revision Handling; "XXXX: Updated YANG Module Revision Handling;
Section 3.3, Revision label"; Section 3.3, Revision label";
} }
typedef revision-date-or-label { typedef revision-date-or-label {
type union { type union {
type yang:revision-identifier; type yang:revision-identifier;
type revision-label; type revision-label;
} }
description description
"Represents either a YANG revision date or a revision label"; "Represents either a YANG revision date or a revision label";
} }
extension non-backwards-compatible { extension non-backwards-compatible {
description description
"This statement is used to indicate YANG module revisions that "This statement is used to indicate YANG module revisions that
contain non-backwards-compatible changes. contain non-backwards-compatible changes.
The statement MUST only be a substatement of the 'revision' The statement MUST only be a substatement of the 'revision'
statement. Zero or one 'non-backwards-compatible' statements statement. Zero or one 'non-backwards-compatible' statements
per parent statement is allowed. No substatements for this per parent statement is allowed. No substatements for this
extension have been standardized. extension have been standardized.
If a revision of a YANG module contains changes, relative to If a revision of a YANG module contains changes, relative to
the preceding revision in the revision history, that do not the preceding revision in the revision history, that do not
conform to the backwards compatible module update rules defined conform to the backwards compatible module update rules defined
in RFC-XXX, then the 'non-backwards-compatible' statement MUST in RFC-XXX, then the 'non-backwards-compatible' statement MUST
be added as a substatement to the revision statement. be added as a substatement to the revision statement.
Conversely, if a revision does not contain a Conversely, if a revision does not contain a
'non-backwards-compatible' statement then all changes, 'non-backwards-compatible' statement then all changes,
relative to the preceding revision in the revision history, relative to the preceding revision in the revision history,
MUST be backwards-compatible. MUST be backwards-compatible.
A new module revision that only contains changes that are A new module revision that only contains changes that are
backwards compatible SHOULD NOT include the backwards compatible SHOULD NOT include the
'non-backwards-compatible' statement. An example of when 'non-backwards-compatible' statement. An example of when
an author might add the 'non-backwards-compatible' statement an author might add the 'non-backwards-compatible' statement
is if they believe a change could negatively impact clients is if they believe a change could negatively impact clients
even though the backwards compatibility rules defined in even though the backwards compatibility rules defined in
RFC-XXXX classify it as a backwards-compatible change. RFC-XXXX classify it as a backwards-compatible change.
Add, removing, or changing a 'non-backwards-compatible' Add, removing, or changing a 'non-backwards-compatible'
statement is a backwards-compatible version change."; statement is a backwards-compatible version change.";
reference reference
"XXXX: Updated YANG Module Revision Handling; "XXXX: Updated YANG Module Revision Handling;
Section 3.2, nbc-changes revision extension statement"; Section 3.2, non-backwards-compatible revision extension statement";
} }
extension revision-label { extension revision-label {
argument revision-label; argument revision-label;
description description
"The revision label can be used to provide an additional "The revision label can be used to provide an additional
versioning identifier associated with a module or submodule versioning identifier associated with a module or submodule
revision. One such scheme that revision. One such scheme that
could be used is [XXXX: ietf-netmod-yang-semver]. could be used is [XXXX: ietf-netmod-yang-semver].
The format of the revision-label argument MUST conform to the The format of the revision-label argument MUST conform to the
pattern defined for the revision-label typedef in this module. pattern defined for the revision-label typedef in this module.
The statement MUST only be a substatement of the revision The statement MUST only be a substatement of the revision
statement. Zero or one revision-label statements per parent statement. Zero or one revision-label statements per parent
statement are allowed. No substatements for this extension statement are allowed. No substatements for this extension
have been standardized. have been standardized.
Revision labels MUST be unique amongst all revisions of a Revision labels MUST be unique amongst all revisions of a
module or submodule. module or submodule.
Adding a revision label is a backwards-compatible version Adding a revision label is a backwards-compatible version
change. Changing or removing an existing revision label in change. Changing or removing an existing revision label in
the revision history is a non-backwards-compatible version the revision history is a non-backwards-compatible version
change, because it could impact any references to that change, because it could impact any references to that
revision label."; revision label.";
reference reference
"XXXX: Updated YANG Module Revision Handling; "XXXX: Updated YANG Module Revision Handling;
Section 3.3, Revision label"; Section 3.3, Revision label";
} }
extension revision-label-scheme {
argument revision-label-scheme-base;
description
"The revision label scheme specifies which revision-label scheme
the module or submodule uses.
extension revision-label-scheme { The mandatory revision-label-scheme-base argument MUST be an
argument revision-label-scheme-identity; identity derived from revision-label-scheme-base.
description
"The revision label scheme specifies which revision-label scheme
the module or submodule uses.
The mandatory revision-label-scheme-identity argument MUST be an This extension is only valid as a top-level statement, i.e.,
identity derived from revision-label-scheme-base. given as as a substatement to 'module' or 'submodule'. No
substatements for this extension have been standardized.
This extension is only valid as a top-level statement, i.e., This extension MUST be used if there is a revision-label
given as as a substatement to 'module' or 'submodule'. No statement in the module or submodule.
substatements for this extension have been standardized.
This extension MUST be used if there is a revision-label Adding a revision label scheme is a backwards-compatible version
statement in the module or submodule. change. Changing a revision label scheme is a
non-backwards-compatible version change, unless the new revision
label scheme is backwards-compatible with the replaced revision
label scheme. Removing a revision label scheme is a
non-backwards-compatible version change.";
Adding a revision label scheme is a backwards-compatible version reference
change. Changing a revision label scheme is a "XXXX: Updated YANG Module Revision Handling;
non-backwards-compatible version change, unless the new revision Section 3.3.1, Revision label scheme extension statement";
label scheme is backwards-compatible with the replaced revision }
label scheme. Removing a revision label scheme is a
non-backwards-compatible version change.";
reference extension revision-or-derived {
"XXXX: Updated YANG Module Revision Handling; argument revision-date-or-label;
Section 3.3.1, Revision label scheme extension statement"; 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-label.
extension revision-or-derived { The argument value MUST conform to the
argument revision-date-or-label; 'revision-date-or-label' defined type.
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-label.
The argument value MUST conform to the The statement MUST only be a substatement of the import
'revision-date-or-label' defined type. statement. Zero, one or more 'revision-or-derived' statements
per parent statement are allowed. No substatements for this
extension have been standardized.
The statement MUST only be a substatement of the import If specified multiple times, then any module revision that
statement. Zero, one or more 'revision-or-derived' statements satisfies at least one of the 'revision-or-derived' statements
per parent statement are allowed. No substatements for this is an acceptable revision for import.
extension have been standardized.
If specified multiple times, then any module revision that An 'import' statement MUST NOT contain both a
satisfies at least one of the 'revision-or-derived' statements 'revision-or-derived' extension statement and a
is an acceptable revision for import. 'revision-date' statement.
An 'import' statement MUST NOT contain both a A particular revision of an imported module satisfies an
'revision-or-derived' extension statement and a import's 'revision-or-derived' extension statement if the
'revision-date' statement. imported module's revision history contains a revision
statement with a matching revision date or revision label.
A particular revision of an imported module satisfies an The 'revision-or-derived' extension statement does not
import's 'revision-or-derived' extension statement if the guarantee that all module revisions that satisfy an import
imported module's revision history contains a revision statement are necessarily compatible, it only gives an
statement with a matching revision date or revision label. indication that the revisions are more likely to be
compatible.
The 'revision-or-derived' extension statement does not Adding, removing or updating a 'revision-or-derived'
guarantee that all module revisions that satisfy an import statement to an import is a backwards-compatible change.
statement are necessarily compatible, it only gives an ";
indication that the revisions are more likely to be
compatible.
Adding, removing or updating a 'revision-or-derived' reference
statement to an import is a backwards-compatible change. "XXXX: Updated YANG Module Revision Handling;
"; Section 4, Import by derived revision";
}
reference identity revision-label-scheme-base {
"XXXX: Updated YANG Module Revision Handling; description
Section 4, Import by derived revision"; "Base identity from which all revision label schemes are
} derived.";
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.3.1, Revision label scheme 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-yang-library-revisions@2021-10-22.yang" <CODE BEGINS> file "ietf-yang-library-revisions@2021-11-04.yang"
module ietf-yang-library-revisions { module ietf-yang-library-revisions {
yang-version 1.1; yang-version 1.1;
namespace namespace
"urn:ietf:params:xml:ns:yang:ietf-yang-library-revisions"; "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 { import ietf-yang-library {
prefix yanglib; prefix yanglib;
reference "RFC 8525: YANG Library"; reference "RFC 8525: YANG Library";
} }
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: Joe Clarke Author: Joe Clarke
<mailto:jclarke@cisco.com> <mailto:jclarke@cisco.com>
Author: Reshad Rahman Author: Reshad Rahman
<mailto:reshad@yahoo.com> <mailto:reshad@yahoo.com>
Author: Robert Wilton Author: Robert Wilton
<mailto:rwilton@cisco.com> <mailto:rwilton@cisco.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 module contains augmentations to YANG Library to add module "This module contains augmentations to YANG Library to add module
level revision label and to provide an indication of how level revision label and to provide an indication of how
deprecated and obsolete nodes are handled by the server. deprecated and obsolete nodes are handled by the server.
Copyright (c) 2021 IETF Trust and the persons identified as Copyright (c) 2021 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 (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 2021-10-22 { revision 2021-11-04 {
rev:revision-label 1.0.0-draft-ietf-netmod-yang-module-versioning-04; rev:revision-label 1.0.0-draft-ietf-netmod-yang-module-versioning-05;
description description
"Initial revision"; "Initial revision";
reference reference
"XXXX: Updated YANG Module Revision Handling"; "XXXX: Updated YANG Module Revision Handling";
} }
// library 1.0 modules-state is not augmented with revision-label // library 1.0 modules-state is not augmented with revision-label
augment "/yanglib:yang-library/yanglib:module-set/yanglib:module" { augment "/yanglib:yang-library/yanglib:module-set/yanglib:module" {
description description
"Add a revision label to module information"; "Add a revision label to module information";
leaf revision-label {
type rev:revision-label;
description
"The revision label associated with this module revision.
The label MUST match the rev:revision-label value in the specific
revision of the module loaded in this module-set.";
leaf revision-label { reference
type rev:revision-label; "XXXX: Updated YANG Module Revision Handling;
description Section 5.2.1, Advertising revision-label";
"The revision label associated with this module revision. }
The label MUST match the rev:revision-label value in the specific }
revision of the module loaded in this module-set.";
reference augment "/yanglib:yang-library/yanglib:module-set/yanglib:module/"
"XXXX: Updated YANG Module Revision Handling; + "yanglib:submodule" {
Section 5.2.1, Advertising revision-label"; description
} "Add a revision label to submodule information";
} leaf revision-label {
type rev:revision-label;
description
"The revision label associated with this submodule revision.
The label MUST match the rev:revision-label value in the specific
revision of the submodule included by the module loaded in
this module-set.";
augment "/yanglib:yang-library/yanglib:module-set/yanglib:module/" reference
+ "yanglib:submodule" { "XXXX: Updated YANG Module Revision Handling;
description Section 5.2.1, Advertising revision-label";
"Add a revision label to submodule information"; }
leaf revision-label { }
type rev:revision-label;
description
"The revision label associated with this submodule revision.
The label MUST match the rev:revision-label value in the specific
revision of the submodule included by the module loaded in
this module-set.";
reference augment "/yanglib:yang-library/yanglib:module-set/"
"XXXX: Updated YANG Module Revision Handling; + "yanglib:import-only-module" {
Section 5.2.1, Advertising revision-label"; description
} "Add a revision label to module information";
} leaf revision-label {
type rev:revision-label;
description
"The revision label associated with this module revision.
The label MUST match the rev:revision-label value in the specific
revision of the module included in this module-set.";
augment "/yanglib:yang-library/yanglib:module-set/" reference
+ "yanglib:import-only-module" { "XXXX: Updated YANG Module Revision Handling;
description Section 5.2.1, Advertising revision-label";
"Add a revision label to module information"; }
leaf revision-label { }
type rev:revision-label;
description
"The revision label associated with this module revision.
The label MUST match the rev:revision-label value in the specific
revision of the module included in this module-set.";
reference augment "/yanglib:yang-library/yanglib:module-set/"
"XXXX: Updated YANG Module Revision Handling; + "yanglib:import-only-module/yanglib:submodule" {
Section 5.2.1, Advertising revision-label"; description
} "Add a revision label to submodule information";
} leaf revision-label {
augment "/yanglib:yang-library/yanglib:module-set/" type rev:revision-label;
+ "yanglib:import-only-module/yanglib:submodule" { description
description "The revision label associated with this submodule revision.
"Add a revision label to submodule information"; The label MUST match the rev:label value in the specific
leaf revision-label { revision of the submodule included by the
type rev:revision-label; import-only-module loaded in this module-set.";
description
"The revision label associated with this submodule revision.
The label MUST match the rev:label value in the specific
revision of the submodule included by the
import-only-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 boolean; type boolean;
description description
"If set to true, this leaf indicates that all schema nodes with "If set to true, this leaf indicates that all schema nodes with
a status 'deprecated' are implemented a status 'deprecated' are implemented
equivalently as if they had status 'current'; otherwise equivalently as if they had status 'current'; 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 or set to false, nodes from the schema. If this leaf is absent or set to false,
then the 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 boolean; type boolean;
description description
"If set to true, this leaf indicates that the server does not "If set to true, this leaf indicates that the server does not
implement any status 'obsolete' schema nodes. If this leaf is implement any status 'obsolete' schema nodes. If this leaf is
absent or set to false, then the behaviour is unspecified."; absent or set to false, 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:
* Balazs Lengyel o Balazs Lengyel
* Benoit Claise
* Bo Wu o Benoit Claise
* Ebben Aries o Bo Wu
* Jan Lindblad o Ebben Aries
* Jason Sterne o Jan Lindblad
o Jason Sterne
* Joe Clarke o Joe Clarke
* Juergen Schoenwaelder o Juergen Schoenwaelder
* Mahesh Jethanandani o Mahesh Jethanandani
* Michael (Wangzitao) o Michael (Wangzitao)
* Qin Wu o Qin Wu
* Reshad Rahman o Reshad Rahman
* Rob Wilton o Rob Wilton
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]. We would like to thank Kevin [I-D.clacla-netmod-yang-model-update]. We would like to thank Kevin
D'Souza and Benoit Claise for their initial work in this problem D'Souza and Benoit Claise for their initial work in this problem
space. space.
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 to thank with authors of the OpenConfig YANG models. We would like to thank
both Anees Shaikh and Rob Shakir for their input into this problem both Anees Shaikh and Rob Shakir for their input into this problem
space. space.
skipping to change at page 33, line 18 skipping to change at page 32, line 41
Reference: [RFCXXXX] Reference: [RFCXXXX]
11.2. Guidance for versioning in IANA maintained YANG modules 11.2. Guidance for versioning in IANA maintained YANG modules
Note for IANA (to be removed by the RFC editor): Please check that Note for IANA (to be removed by the RFC editor): Please check that
the registries and IANA YANG modules are referenced in the the registries and IANA YANG modules are referenced in the
appropriate way. appropriate way.
IANA is responsible for maintaining and versioning YANG modules that IANA is responsible for maintaining and versioning YANG modules that
are derived from other IANA registries. For example, are derived from other IANA registries. For example, "iana-if-
"iana-if-type.yang" [IfTypeYang] is derived from the "Interface Types type.yang" [IfTypeYang] is derived from the "Interface Types (ifType)
(ifType) IANA registry" [IfTypesReg], and "iana-routing-types.yang" IANA registry" [IfTypesReg], and "iana-routing-types.yang"
[RoutingTypesYang] is derived from the "Address Family Numbers" [RoutingTypesYang] is derived from the "Address Family Numbers"
[AddrFamilyReg] and "Subsequent Address Family Identifiers (SAFI) [AddrFamilyReg] and "Subsequent Address Family Identifiers (SAFI)
Parameters" [SAFIReg] IANA registries. Parameters" [SAFIReg] IANA registries.
Normally, updates to the registries cause any derived YANG modules to Normally, updates to the registries cause any derived YANG modules to
be updated in a backwards-compatible way, but there are some cases be updated in a backwards-compatible way, but there are some cases
where the registry updates can cause non-backward-compatible updates where the registry updates can cause non-backward-compatible updates
to the derived YANG module. An example of such an update is the to the derived YANG module. An example of such an update is the
2020-12-31 revision of iana-routing-types.yang 2020-12-31 revision of iana-routing-types.yang
[RoutingTypesDecRevision], where the enum name for two SAFI values [RoutingTypesDecRevision], where the enum name for two SAFI values
was changed. was changed.
In all cases, IANA MUST follow the versioning guidance specified in In all cases, IANA MUST follow the versioning guidance specified in
Section 3.1, and MUST include a "rev:non-backwards-compatible" Section 3.1, and MUST include a "rev:non-backwards-compatible"
substatement to the latest revision statement whenever an IANA substatement to the latest revision statement whenever an IANA
maintained module is updated in a non-backwards-compatible way, as maintained module is updated in a non-backwards-compatible way, as
described in Section 3.2. described in Section 3.2.
Note: For published IANA maintained YANG modules that contain non- Note: For published IANA maintained YANG modules that contain non-
skipping to change at page 34, line 29 skipping to change at page 33, line 51
maintained modules that would be classified as backwards-compatible maintained modules that would be classified as backwards-compatible
changes are: Adding a new identity, changing the status or an changes are: Adding a new identity, changing the status or an
identity to deprecated, or improving the description of an identity identity to deprecated, or improving the description of an identity
that does not change its defined meaning. that does not change its defined meaning.
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", Work in Schoenwaelder, J., "Common YANG Data Types", draft-ietf-
Progress, Internet-Draft, draft-ietf-netmod-rfc6991-bis- netmod-rfc6991-bis-08 (work in progress), November 2021.
07, 9 July 2021, <https://www.ietf.org/archive/id/draft-
ietf-netmod-rfc6991-bis-07.txt>.
[I-D.ietf-netmod-yang-semver] [I-D.ietf-netmod-yang-semver]
Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, Clarke, J., Wilton, R., Rahman, R., Lengyel, B., Sterne,
B., Sterne, J., and K. D'Souza, "YANG Semantic J., and B. Claise, "YANG Semantic Versioning", draft-ietf-
Versioning", Work in Progress, Internet-Draft, draft-ietf- netmod-yang-semver-04 (work in progress), October 2021.
netmod-yang-semver-03, 12 July 2021,
<https://www.ietf.org/archive/id/draft-ietf-netmod-yang-
semver-03.txt>.
[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>.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
DOI 10.17487/RFC3688, January 2004, DOI 10.17487/RFC3688, January 2004,
<https://www.rfc-editor.org/info/rfc3688>. <https://www.rfc-editor.org/info/rfc3688>.
skipping to change at page 35, line 37 skipping to change at page 34, line 51
12.2. Informative References 12.2. Informative References
[AddrFamilyReg] [AddrFamilyReg]
"Address Family Numbers IANA Registry", "Address Family Numbers IANA Registry",
<https://www.iana.org/assignments/address-family-numbers/ <https://www.iana.org/assignments/address-family-numbers/
address-family-numbers.xhtml>. address-family-numbers.xhtml>.
[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", Work in Progress, Internet- YANG Module Update Procedure", draft-clacla-netmod-yang-
Draft, draft-clacla-netmod-yang-model-update-06, 2 July model-update-06 (work in progress), July 2018.
2018, <https://www.ietf.org/archive/id/draft-clacla-
netmod-yang-model-update-06.txt>.
[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", Work in Progress, Internet-Draft, draft-ietf- Format", draft-ietf-netmod-yang-instance-file-format-21
netmod-yang-instance-file-format-21, 8 October 2021, (work in progress), October 2021.
<https://www.ietf.org/archive/id/draft-ietf-netmod-yang-
instance-file-format-21.txt>.
[I-D.ietf-netmod-yang-packages] [I-D.ietf-netmod-yang-packages]
Wilton, R., Rahman, R., Clarke, J., Sterne, J., and B. Wu, Wilton, R., Rahman, R., Clarke, J., Sterne, J., and B. Wu,
"YANG Packages", Work in Progress, Internet-Draft, draft- "YANG Packages", draft-ietf-netmod-yang-packages-02 (work
ietf-netmod-yang-packages-01, 2 November 2020, in progress), October 2021.
<https://www.ietf.org/archive/id/draft-ietf-netmod-yang-
packages-01.txt>.
[I-D.ietf-netmod-yang-solutions] [I-D.ietf-netmod-yang-solutions]
Wilton, R., "YANG Versioning Solution Overview", Work in Wilton, R., "YANG Versioning Solution Overview", draft-
Progress, Internet-Draft, draft-ietf-netmod-yang- ietf-netmod-yang-solutions-01 (work in progress), November
solutions-01, 2 November 2020, 2020.
<https://www.ietf.org/archive/id/draft-ietf-netmod-yang-
solutions-01.txt>.
[I-D.ietf-netmod-yang-ver-selection] [I-D.ietf-netmod-yang-ver-selection]
Wilton, R., Rahman, R., Clarke, J., Sterne, J., and B. Wu, Wilton, R., Rahman, R., Clarke, J., Sterne, J., and B. Wu,
"YANG Schema Selection", Work in Progress, Internet-Draft, "YANG Schema Selection", draft-ietf-netmod-yang-ver-
draft-ietf-netmod-yang-ver-selection-00, 17 March 2020, selection-00 (work in progress), March 2020.
<https://www.ietf.org/archive/id/draft-ietf-netmod-yang-
ver-selection-00.txt>.
[I-D.ietf-netmod-yang-versioning-reqs] [I-D.ietf-netmod-yang-versioning-reqs]
Clarke, J., "YANG Module Versioning Requirements", Work in Clarke, J., "YANG Module Versioning Requirements", draft-
Progress, Internet-Draft, draft-ietf-netmod-yang- ietf-netmod-yang-versioning-reqs-05 (work in progress),
versioning-reqs-05, 6 July 2021, July 2021.
<https://www.ietf.org/archive/id/draft-ietf-netmod-yang-
versioning-reqs-05.txt>.
[IfTypesReg] [IfTypesReg]
"Interface Types (ifType) IANA Registry", "Interface Types (ifType) IANA Registry",
<https://www.iana.org/assignments/smi-numbers/smi- <https://www.iana.org/assignments/smi-numbers/smi-
numbers.xhtml#smi-numbers-5>. numbers.xhtml#smi-numbers-5>.
[IfTypeYang] [IfTypeYang]
"iana-if-type YANG Module", "iana-if-type YANG Module",
<https://www.iana.org/assignments/iana-if-type/iana-if- <https://www.iana.org/assignments/iana-if-type/iana-if-
type.xhtml>. type.xhtml>.
skipping to change at page 37, line 20 skipping to change at page 36, line 15
[SAFIReg] "Subsequent Address Family Identifiers (SAFI) Parameters [SAFIReg] "Subsequent Address Family Identifiers (SAFI) Parameters
IANA Registry", <https://www.iana.org/assignments/safi- IANA Registry", <https://www.iana.org/assignments/safi-
namespace/safi-namespace.xhtml>. namespace/safi-namespace.xhtml>.
[semver] "Semantic Versioning 2.0.0", <https://www.semver.org>. [semver] "Semantic Versioning 2.0.0", <https://www.semver.org>.
Appendix A. Examples of changes that are NBC Appendix A. Examples of changes that are NBC
Examples of NBC changes include: Examples of NBC changes include:
* Deleting a data node, or changing it to status obsolete. o Deleting a data node, or changing it to status obsolete.
* Changing the name, type, or units of a data node. o Changing the name, type, or units of a data node.
* 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.
* 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.
* 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.
* Making the statement conditional on if-feature. o Making the statement conditional on if-feature.
Appendix B. Examples of applying the NBC change guidelines Appendix B. Examples of applying the NBC change guidelines
The following sections give steps that could be taken for making NBC The following sections give steps that could be taken for making NBC
changes to a YANG module or submodule using the incremental approach changes to a YANG module or submodule using the incremental approach
described in section Section 7.1.1. described in section Section 7.1.1.
The examples are all for "config true" nodes. The examples are all for "config true" nodes.
Alternatively, the NBC changes MAY be done non-incrementally and Alternatively, the NBC changes MAY be done non-incrementally and
 End of changes. 137 change blocks. 
477 lines changed or deleted 461 lines changed or added

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