draft-ietf-netmod-yang-packages-00.txt   draft-ietf-netmod-yang-packages-01.txt 
Network Working Group R. Wilton, Ed. Network Working Group R. Wilton, Ed.
Internet-Draft R. Rahman Internet-Draft R. Rahman
Intended status: Standards Track J. Clarke Intended status: Standards Track J. Clarke
Expires: September 18, 2020 Cisco Systems, Inc. Expires: May 6, 2021 Cisco Systems, Inc.
J. Sterne J. Sterne
Nokia Nokia
B. Wu B. Wu, Ed.
Huawei Huawei
March 17, 2020 November 2, 2020
YANG Packages YANG Packages
draft-ietf-netmod-yang-packages-00 draft-ietf-netmod-yang-packages-01
Abstract Abstract
This document defines YANG packages, a versioned organizational This document defines YANG packages, a versioned organizational
structure holding a set of related YANG modules, that collectively structure holding a set of related YANG modules that collectively
define a YANG schema. It describes how packages: are represented on define a YANG schema. It describes how packages: are represented on
a server, can be defined in offline YANG instance data documents, and a server, can be defined in offline YANG instance data files, and can
can be used to define the schema associated with YANG instance data be used to define the schema associated with YANG instance data
documents. files.
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 May 6, 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 19 skipping to change at page 2, line 19
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Terminology and Conventions . . . . . . . . . . . . . . . . . 3 1. Terminology and Conventions . . . . . . . . . . . . . . . . . 3
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Background on YANG packages . . . . . . . . . . . . . . . . . 4 3. Background on YANG packages . . . . . . . . . . . . . . . . . 4
4. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 5 4. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 5
5. YANG Package Definition . . . . . . . . . . . . . . . . . . . 6 5. YANG Package Definition . . . . . . . . . . . . . . . . . . . 6
5.1. Package definition rules . . . . . . . . . . . . . . . . 7 5.1. Package definition rules . . . . . . . . . . . . . . . . 7
5.2. Package versioning . . . . . . . . . . . . . . . . . . . 7 5.2. Package versioning . . . . . . . . . . . . . . . . . . . 8
5.2.1. Updating a package with a new version . . . . . . . . 8 5.2.1. Updating a package with a new version . . . . . . . . 8
5.2.1.1. Non-Backwards-compatible changes . . . . . . . . 8 5.2.1.1. Non-Backwards-compatible changes . . . . . . . . 8
5.2.1.2. Backwards-compatible changes . . . . . . . . . . 8 5.2.1.2. Backwards-compatible changes . . . . . . . . . . 9
5.2.1.3. Editorial changes . . . . . . . . . . . . . . . . 9 5.2.1.3. Editorial changes . . . . . . . . . . . . . . . . 9
5.2.2. YANG Semantic Versioning for packages . . . . . . . . 9 5.2.2. YANG Semantic Versioning for packages . . . . . . . . 9
5.2.3. Revision history . . . . . . . . . . . . . . . . . . 10 5.2.3. Revision history . . . . . . . . . . . . . . . . . . 10
5.3. Package conformance . . . . . . . . . . . . . . . . . . . 10 5.3. Package conformance . . . . . . . . . . . . . . . . . . . 10
5.3.1. Use of YANG semantic versioning . . . . . . . . . . . 10 5.3.1. Use of YANG semantic versioning . . . . . . . . . . . 10
5.3.2. Package checksums . . . . . . . . . . . . . . . . . . 11 5.3.2. Package checksums . . . . . . . . . . . . . . . . . . 11
5.3.3. The relationship between packages and datastores . . 11 5.3.3. The relationship between packages and datastores . . 12
5.4. Schema referential completeness . . . . . . . . . . . . . 13 5.4. Schema referential completeness . . . . . . . . . . . . . 13
5.5. Package name scoping and uniqueness . . . . . . . . . . . 14 5.5. Package name scoping and uniqueness . . . . . . . . . . . 14
5.5.1. Globally scoped packages . . . . . . . . . . . . . . 14 5.5.1. Globally scoped packages . . . . . . . . . . . . . . 14
5.5.2. Server scoped packages . . . . . . . . . . . . . . . 14 5.5.2. Server scoped packages . . . . . . . . . . . . . . . 14
5.6. Submodules packages considerations . . . . . . . . . . . 14 5.6. Submodules packages considerations . . . . . . . . . . . 14
5.7. Package tags . . . . . . . . . . . . . . . . . . . . . . 14 5.7. Package tags . . . . . . . . . . . . . . . . . . . . . . 14
5.8. YANG package core definition . . . . . . . . . . . . . . 15 5.8. YANG Package Usage Guidance . . . . . . . . . . . . . . . 15
6. Package Instance Data Documents . . . . . . . . . . . . . . . 16 5.8.1. Use of deviations in YANG packages . . . . . . . . . 15
7. Package Definitions on a Server . . . . . . . . . . . . . . . 17 5.8.2. Use of features in YANG modules and YANG packages . . 16
7.1. Package List . . . . . . . . . . . . . . . . . . . . . . 17 5.9. YANG package core definition . . . . . . . . . . . . . . 16
7.2. Tree diagram . . . . . . . . . . . . . . . . . . . . . . 17 6. Package Instance Data Files . . . . . . . . . . . . . . . . . 17
8. YANG Library Package Bindings . . . . . . . . . . . . . . . . 18 7. Package Definitions on a Server . . . . . . . . . . . . . . . 18
9. YANG packages as schema for YANG instance data document . . . 19 7.1. Package List . . . . . . . . . . . . . . . . . . . . . . 18
10. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 19 7.2. Tree diagram . . . . . . . . . . . . . . . . . . . . . . 19
11. Security Considerations . . . . . . . . . . . . . . . . . . . 40 8. YANG Library Package Bindings . . . . . . . . . . . . . . . . 19
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41 9. YANG packages as schema for YANG instance data document . . . 20
13. Open Questions/Issues . . . . . . . . . . . . . . . . . . . . 43 10. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 20
14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 43 11. Security Considerations . . . . . . . . . . . . . . . . . . . 41
15. References . . . . . . . . . . . . . . . . . . . . . . . . . 43 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42
15.1. Normative References . . . . . . . . . . . . . . . . . . 43 13. Open Questions/Issues . . . . . . . . . . . . . . . . . . . . 44
15.2. Informative References . . . . . . . . . . . . . . . . . 45 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 44
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 45 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 44
A.1. Example IETF Network Device YANG package . . . . . . . . 46 15.1. Normative References . . . . . . . . . . . . . . . . . . 44
A.2. Example IETF Basic Routing YANG package . . . . . . . . . 48 15.2. Informative References . . . . . . . . . . . . . . . . . 46
A.3. Package import conflict resolution example . . . . . . . 51 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 46
Appendix B. Possible alternative solutions . . . . . . . . . . . 54 A.1. Example IETF Network Device YANG package . . . . . . . . 47
B.1. Using module tags . . . . . . . . . . . . . . . . . . . . 54 A.2. Example IETF Basic Routing YANG package . . . . . . . . . 49
B.2. Using YANG library . . . . . . . . . . . . . . . . . . . 55 A.3. Package import conflict resolution example . . . . . . . 52
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 55 Appendix B. Possible alternative solutions . . . . . . . . . . . 55
B.1. Using module tags . . . . . . . . . . . . . . . . . . . . 55
B.2. Using YANG library . . . . . . . . . . . . . . . . . . . 56
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 56
1. Terminology and Conventions 1. Terminology and Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
This document uses terminology introduced in the YANG versioning This document uses terminology introduced in the YANG versioning
requirements draft [I-D.verdt-netmod-yang-versioning-reqs]. requirements draft [I-D.ietf-netmod-yang-versioning-reqs].
This document also makes of the following terminology introduced in This document also makes of the following terminology introduced in
the Network Management Datastore Architecture [RFC8342]: the Network Management Datastore Architecture [RFC8342]:
o datastore schema o datastore schema
This document also makes of the following terminology introduced in This document also makes of the following terminology introduced in
the YANG 1.1 Data Modeling Language [RFC7950]: the YANG 1.1 Data Modeling Language [RFC7950]:
o data node o data node
In addition, this document defines the following terminology: In addition, this document defines the following terminology:
o YANG schema: A datastore schema, not bound to any particular o YANG schema: A datastore schema, not bound to any particular
datastore. datastore.
o YANG package: An organizational structure holding a collection of o YANG package: An organizational structure containing a collection
YANG modules related by some common purpose, normally defined in a of YANG modules, normally defined in a YANG instance data file. A
YANG instance data file. A YANG package defines a YANG schema by YANG package defines a YANG schema by specifying a set of YANG
specifying a set of YANG modules revisions, package versions, modules and their revisions, other packages and their revisions,
mandatory features, and deviations. YANG packages are defined in mandatory features, and deviations. YANG packages are defined in
Section 5. Section 5.
o backwards-compatible (BC) change: When used in the context of a o backwards-compatible (BC) change: When used in the context of a
YANG module, it follows the definition in Section 3.1.1 of YANG module, it follows the definition in Section 3.1.1 of
[I-D.verdt-netmod-yang-module-versioning]. When used in the [I-D.ietf-netmod-yang-module-versioning]. When used in the
context of a YANG package, it follows the definition in context of a YANG package, it follows the definition in
Section 5.2.1.2. Section 5.2.1.2.
o non-backwards-compatible (NBC) change: When used in the context of o non-backwards-compatible (NBC) change: When used in the context of
a YANG module, it follows the definition in Section 3.1.2 of a YANG module, it follows the definition in Section 3.1.2 of
[I-D.verdt-netmod-yang-module-versioning]. When used in the [I-D.ietf-netmod-yang-module-versioning]. When used in the
context of a YANG package, it follows the definition in context of a YANG package, it follows the definition in
Section 5.2.1.2. Section 5.2.1.2.
o editorial change: When used in the context of a YANG module, it o editorial change: When used in the context of a YANG module, it
follows the definition of an 'editorial change' in 3.2 of follows the definition of an 'editorial change' in 3.2 of
[I-D.verdt-netmod-yang-semver]. When used in the context of a [I-D.ietf-netmod-yang-module-versioning]. When used in the
YANG package, it follows the definition in Section 5.2.1.3. context of a YANG package, it follows the definition in
Section 5.2.1.3.
2. Introduction 2. Introduction
This document defines and describes the YANG [RFC7950] constructs This document defines and describes the YANG [RFC7950] constructs
that are used to define and use YANG packages. that are used to define and use YANG packages.
A YANG package is an organizational structure that groups a set of A YANG package is an organizational structure that groups a set of
YANG modules together into a consistent versioned definition to serve YANG modules together into a consistent versioned definition. For
a common purpose. For example, a YANG package could define the set example, a YANG package could define the set of YANG modules required
of YANG modules required to implement an L2VPN service on a network to implement an L2VPN service on a network device. YANG packages can
device. YANG packages can themselves refer to, and reuse, other themselves refer to, and reuse, other package definitions.
package definitions.
Non-normative examples of YANG packages are provided in the Non-normative examples of YANG packages are provided in the
appendices. appendices.
3. Background on YANG packages 3. Background on YANG packages
It has long been acknowledged within the YANG community that network It has long been acknowledged within the YANG community that network
management using YANG requires a unit of organization and conformance management using YANG requires a unit of organization and conformance
that is broader in scope than individual YANG modules. that is broader in scope than individual YANG modules.
skipping to change at page 4, line 49 skipping to change at page 4, line 51
statements, where a YANG package is defined in a file similar to how statements, where a YANG package is defined in a file similar to how
YANG modules are defined, and would require enhancements to YANG YANG modules are defined, and would require enhancements to YANG
compilers to understand the new statements used to define packages. compilers to understand the new statements used to define packages.
OpenConfig [openconfigsemver] describes an approach to versioning OpenConfig [openconfigsemver] describes an approach to versioning
'bundle releases' based on git tags. I.e. a set of modules, at 'bundle releases' based on git tags. I.e. a set of modules, at
particular versions, can be marked with the same release tag to particular versions, can be marked with the same release tag to
indicate that they are known to interoperate together. indicate that they are known to interoperate together.
The NETMOD WG in general, and the YANG versioning design team in The NETMOD WG in general, and the YANG versioning design team in
particular, are exploring solutions [I-D.verdt-netmod-yang-solutions] particular, are exploring solutions [I-D.ietf-netmod-yang-solutions]
to the YANG versioning requirements, to the YANG versioning requirements,
[I-D.verdt-netmod-yang-versioning-reqs]. Solutions to the versioning [I-D.ietf-netmod-yang-versioning-reqs]. Solutions to the versioning
requirements can be split into several distinct areas. requirements can be split into several distinct areas.
[I-D.ietf-netmod-yang-module-versioning] is focused on YANG
[I-D.verdt-netmod-yang-module-versioning] is focused on YANG
versioning scoped to individual modules. The overall solution must versioning scoped to individual modules. The overall solution must
also consider YANG versioning and conformance scoped to YANG schema. also consider YANG versioning and conformance scoped to YANG schema.
YANG packages provide part of the solution for versioning YANG YANG packages provide part of the solution for versioning YANG
schema. schema.
4. Objectives 4. Objectives
The main goals of YANG package definitions include, but are not The main goals of YANG package definitions include, but are not
restricted to: restricted to:
skipping to change at page 5, line 45 skipping to change at page 5, line 47
vendors, and vendor A implements version 1.0.0 of module foo and vendors, and vendor A implements version 1.0.0 of module foo and
version 2.0.0 of module bar, and vendor B implements version 2.0.0 version 2.0.0 of module bar, and vendor B implements version 2.0.0
of module foo and version 1.0.0 of module bar. For a client, of module foo and version 1.0.0 of module bar. For a client,
trying to interoperate with multiple vendors, and many YANG trying to interoperate with multiple vendors, and many YANG
modules, finding a consistent lowest common denominator set of modules, finding a consistent lowest common denominator set of
YANG module versions may be difficult, if not impossible. YANG module versions may be difficult, if not impossible.
Protocol mechanisms of how clients can negotiate which packages or Protocol mechanisms of how clients can negotiate which packages or
package versions are to be used for NETCONF/RESTCONF communications package versions are to be used for NETCONF/RESTCONF communications
are outside the scope of this document, and are defined in are outside the scope of this document, and are defined in
[I-D.wilton-netmod-yang-ver-selection]. [I-D.ietf-netmod-yang-ver-selection].
Finally, the package definitions proposed by this document are Finally, the package definitions proposed by this document are
intended to be relatively basic in their definition and the intended to be relatively basic in their definition and the
functionality that they support. As industry gains experience using functionality that they support. As industry gains experience using
YANG packages, the standard YANG mechanisms of updating, or YANG packages, the standard YANG mechanisms of updating, or
augmenting, YANG modules could also be used to extend the augmenting YANG modules could also be used to extend the
functionality supported by YANG packages, if required. functionality supported by YANG packages, if required.
5. YANG Package Definition 5. YANG Package Definition
This document specifies an approach to defining YANG packages that is This document specifies an approach to defining YANG packages that is
different to either of the approaches described in the background. different to either of the approaches described in the background.
A YANG package is a versioned organizational structure defining a set A YANG package is a versioned organizational structure defining a set
of related YANG modules, packages, features, and deviations. A YANG of related YANG modules, packages, features, and deviations. A YANG
package collectively defines a YANG schema. package collectively defines a YANG schema.
Each YANG package has a name that SHOULD end with the suffix "-pkg". Each YANG package has a name that SHOULD end with the suffix "-pkg".
Package names are normally expected to be globally unique, but in Package names are normally expected to be globally unique, but in
some cases the package name may be locally scoped to a server or some cases the package name may be locally scoped to a server or
device, as described in Section 5.5. device, as described in Section 5.5.
YANG packages are versioned using the same approaches described in YANG packages are versioned using the same approaches described in
[I-D.verdt-netmod-yang-module-versioning] and [I-D.ietf-netmod-yang-module-versioning] and
[I-D.verdt-netmod-yang-semver]. This is described in further detail [I-D.ietf-netmod-yang-semver]. This is described in further detail
in Section 5.2. in Section 5.2.
Each YANG package version, defines: Each YANG package version, defines:
some metadata about the package, e.g., description, tags, scoping, o some metadata about the package, e.g., description, tags, scoping,
referential completeness, location information. referential completeness, location information.
a set of YANG modules, at particular revisions, that are o a set of YANG modules, at particular revisions, that are
implemented by servers that implement the package. The modules implemented by servers that implement the package. The modules
may contain deviations. may contain deviations.
a set of import-only YANG modules, at particular revisions, that o a set of import-only YANG modules, at particular revisions, that
are used 'import-only' by the servers that implement the package. are used 'import-only' by the servers that implement the package.
a set of included YANG packages, at particular revisions, that are o a set of included YANG packages, at particular revisions, that are
also implemented by servers that implement the package. also implemented by servers that implement the package.
a set of YANG module features that must be supported by servers o a set of YANG module features that must be supported by servers
that implement the package. that implement the package.
The structure for YANG package definitions uses existing YANG The structure for YANG package definitions uses existing YANG
language statements, YANG Data Structure Extensions language statements, YANG Data Structure Extensions
[I-D.ietf-netmod-yang-data-ext], and YANG Instance Data File Format [I-D.ietf-netmod-yang-data-ext], and YANG Instance Data File Format
[I-D.ietf-netmod-yang-instance-file-format]. [I-D.ietf-netmod-yang-instance-file-format].
YANG package definitions are available offline in YANG Instance Data YANG package definitions are available offline in YANG instance data
Documents. Client applications can be designed to support particular files. Client applications can be designed to support particular
package versions that they expect to interoperate with. package versions that they expect to interoperate with.
YANG package definitions are available from the server, via YANG package definitions are available from the server via
augmentations to YANG Library [RFC8525]. Rather than client augmentations to YANG Library [RFC8525]. Rather than client
applications downloading the entire contents of YANG library to applications downloading the entire contents of YANG library to
confirm that the server schema is compatible with the client, they confirm that the server schema is compatible with the client, they
can check, or download, a much shorter YANG package definition, and can check, or download, a much shorter YANG package definition, and
validate that it conforms to the expected schema. validate that it conforms to the expected schema.
YANG package definitions can also be used to define the schema YANG package definitions can also be used to define the schema
associated with YANG instance data documents holding other, e.g., non associated with YANG instance data files holding other, e.g., non
packages related, instance data. packages related, instance data.
5.1. Package definition rules 5.1. Package definition rules
The following rules define how packages are defined: Packages are defined using the following rules:
A YANG package MAY represent a complete YANG schema or only part 1. A YANG package MAY represent a complete YANG schema or only part
of a YANG schema with some module import dependencies missing, as of a YANG schema with some module import dependencies missing, as
described in Section 5.4. described in Section 5.4.
Packages definitions are hierarchical. A package can include 2. Packages definitions are hierarchical. A package can include
other packages. Only a single version of a package can be other packages. Only a single version of a package can be
included, and conflicting package includes (e.g. from descendant included, and conflicting package includes (e.g. from descendant
package includes) MUST be explicitly resolved by indicating which package includes) MUST be explicitly resolved by indicating which
version takes precedence, and which versions are being replaced. version takes precedence, and which versions are being replaced.
For each module implemented by a package, only a single revision 3. For each module implemented by a package, only a single revision
of that module MUST be implemented. Multiple revisions of a of that module MUST be implemented. Multiple revisions of a
module MAY be listed as import-only dependencies. module MAY be listed as import-only dependencies.
The revision of a module listed in the package 'module' list 4. The revision of a module listed in the package 'module' list
supersedes any 'implemented' revision of the module listed in an supersedes any 'implemented' revision of the module listed in an
included package module list. The 'replaces-revision' leaf-list included package module list. The 'replaces-revision' leaf-list
is used to indicate which 'implemented' or 'import-only' module is used to indicate which 'implemented' or 'import-only' module
revisions are replaces by this module revision. This allows a revisions are replaces by this module revision. This allows a
package to explicitly resolve conflicts between implemented module package to explicitly resolve conflicts between implemented
revisions in included packages. module revisions in included packages.
The 'replaces-revision' leaf-list in the 'import-only-module' list 5. The 'replaces-revision' leaf-list in the 'import-only-module'
can be used to exclude duplicate revisions of import-only modules list can be used to exclude duplicate revisions of import-only
from included packages. Otherwise, the import-only-modules for a modules from included packages. Otherwise, the import-only-
package are the import-only-modules from all included packages modules for a package are the import-only-modules from all
combined with any modules listed in the packages import-only- included packages combined with any modules listed in the
module list. packages import-only-module list.
6. YANG packages definitions MAY include modules containing
deviation statements, but those deviation statements MUST only be
used in an RFC 7950 compatible way to indicate where a server, or
class of servers, deviates from a published standard. Deviations
MUST NOT be included in a package definition that is part of a
published standard. See section 5.8.1 for further guidance on
the use of deviations in YANG packages.
5.2. Package versioning 5.2. Package versioning
Individual versions of a YANG package are versioned using the Individual versions of a YANG package are versioned using the
"revision-label" scheme defined in section 3.3 of "revision-label" scheme defined in section 3.3 of
[I-D.verdt-netmod-yang-module-versioning]. [I-D.ietf-netmod-yang-module-versioning].
5.2.1. Updating a package with a new version 5.2.1. Updating a package with a new version
Package compatibility is fundamentally defined by how the YANG schema Package compatibility is fundamentally defined by how the YANG schema
between two package versions has changed. between two package versions has changed.
When a package definition is updated, the version associated with the When a package definition is updated, the version associated with the
package MUST be updated appropriately, taking into consideration the package MUST be updated appropriately, taking into consideration the
scope of the changes as defined by the rules below. scope of the changes as defined by the rules below.
A package definition SHOULD define the previous version of the A package definition SHOULD define the previous version of the
package in the 'previous-version' leaf unless it is the initial package in the 'previous-version' leaf unless it is the initial
version of the package. If the 'previous-version' leaf is provided version of the package. If the 'previous-version' leaf is provided
then the package definition MUST set the 'nbc-changes' leaf if the then the package definition MUST set the 'nbc-changes' leaf if the
new version is non-backwards-compatible with respect to the package new version is non-backwards-compatible with respect to the package
version defined in the 'previous-version' leaf. version defined in the 'previous-version' leaf.
5.2.1.1. Non-Backwards-compatible changes 5.2.1.1. Non-Backwards-compatible changes
The following changes classify as NBC changes to a package The following changes classify as non-backwards-compatible changes to
definition: a package definition:
Changing an 'included-package' list entry to select a package o Changing an 'included-package' list entry to select a package
version that is non-backwards-compatible to the prior package version that is non-backwards-compatible to the prior package
version, or removing a previously included package. version, or removing a previously included package.
Changing a 'module' or 'import-only-module' list entry to select a o Changing a 'module' or 'import-only-module' list entry to select a
module revision that is non-backwards-compatible to the prior module revision that is non-backwards-compatible to the prior
module revision, or removing a previously implemented module. module revision, or removing a previously implemented module.
Removing a feature from the 'mandatory-feature' leaf-list. o Removing a feature from the 'mandatory-feature' leaf-list.
Adding, changing, or removing a deviation that is considered a o Adding, changing, or removing a deviation that is considered a
non-backwards-compatible change to the affected data node in the non-backwards-compatible change to the affected data node in the
schema associated with the prior package version. schema associated with the prior package version.
5.2.1.2. Backwards-compatible changes 5.2.1.2. Backwards-compatible changes
The following changes classify as BC changes to a package definition: The following changes classify as backwards-compatible changes to a
package definition:
Changing an 'included-package' list entry to select a package o Changing an 'included-package' list entry to select a package
version that is backwards-compatible to the prior package version, version that is backwards-compatible to the prior package version,
or including a new package that does not conflict with any or including a new package that does not conflict with any
existing included package or module. existing included package or module.
Changing a 'module' or 'import-only-module' list entry to select a o Changing a 'module' or 'import-only-module' list entry to select a
module revision that is backwards-compatible to the prior module module revision that is backwards-compatible to the prior module
revision, or including a new module to the package definition. revision, or including a new module to the package definition.
Adding a feature to the 'mandatory-feature' leaf-list. o Adding a feature to the 'mandatory-feature' leaf-list.
Adding, changing, or removing a deviation that is considered a o Adding, changing, or removing a deviation that is considered a
backwards-compatible change to the affected data node in the backwards-compatible change to the affected data node in the
schema associated with the prior package version. schema associated with the prior package version.
5.2.1.3. Editorial changes 5.2.1.3. Editorial changes
The following changes classify as editorial changes to a package The following changes classify as editorial changes to a package
definition: definition:
Changing a 'included-package' list entry to select a package o Changing a 'included-package' list entry to select a package
version that is classified as an editorial change relative to the version that is classified as an editorial change relative to the
prior package version. prior package version.
Changing a 'module' or 'import-only-module' list entry to select a o Changing a 'module' or 'import-only-module' list entry to select a
module revision that is classified as an editorial change relative module revision that is classified as an editorial change relative
to the prior module revision. to the prior module revision.
Any change to any metadata associated with a package definition o Any change to any metadata associated with a package definition
that causes it to have a different checksum value. that causes it to have a different checksum value.
5.2.2. YANG Semantic Versioning for packages 5.2.2. YANG Semantic Versioning for packages
YANG Semantic Versioning [I-D.verdt-netmod-yang-semver] MAY be used YANG Semantic Versioning [I-D.ietf-netmod-yang-semver] MAY be used as
as an appropriate type of revision-label for the package version an appropriate type of revision-label for the package version leaf.
leaf.
If the format of the leaf matches the 'yangver:version' type If the format of the leaf matches the 'yangver:version' type
specified in ietf-yang-semver.yang, then the package version leaf specified in ietf-yang-semver.yang, then the package version leaf
MUST be interpreted as a YANG semantic version number. MUST be interpreted as a YANG semantic version number.
For YANG packages defined by the IETF, YANG semantic version numbers For YANG packages defined by the IETF, YANG semantic version numbers
MUST be used as the version scheme for YANG packages. MUST be used as the version scheme for YANG packages.
The rules for incrementing the YANG package version number are The rules for incrementing the YANG package version number are
equivalent to the semantic versioning rules used to version equivalent to the semantic versioning rules used to version
individual YANG modules, defined in section 3.2 of individual YANG modules, defined in section 3.2 of
[I-D.verdt-netmod-yang-semver], but use the rules defined previously [I-D.ietf-netmod-yang-semver], but use the rules defined previously
in Section 5.2.1 to determine whether a change is classified as non- in Section 5.2.1 to determine whether a change is classified as non-
backwards-compatible, backwards-compatible, or editorial. Where backwards-compatible, backwards-compatible, or editorial. Where
available, the semantic version number of the referenced elements in available, the semantic version number of the referenced elements in
the package (included packages or modules) can be used to help the package (included packages or modules) can be used to help
determine the scope of changes being made. determine the scope of changes being made.
5.2.3. Revision history 5.2.3. Revision history
YANG packages do not contain a revision history. This is because YANG packages do not contain a revision history. This is because
packages may have many revisions and a long revision history would packages may have many revisions and a long revision history would
skipping to change at page 11, line 11 skipping to change at page 11, line 22
For example, a client coded to support 'foo' package at version 1.0.0 For example, a client coded to support 'foo' package at version 1.0.0
should interoperate with a server implementing 'foo' package at should interoperate with a server implementing 'foo' package at
version 1.3.5, because the YANG semantic versioning rules require version 1.3.5, because the YANG semantic versioning rules require
that package version 1.3.5 is backwards compatible to version 1.0.0. that package version 1.3.5 is backwards compatible to version 1.0.0.
This also has a relevance on servers that are capable of supporting This also has a relevance on servers that are capable of supporting
version selection because they need not support every version of a version selection because they need not support every version of a
YANG package to ensure good client compatibility. Choosing suitable YANG package to ensure good client compatibility. Choosing suitable
minor versions within each major version number should generally be minor versions within each major version number should generally be
sufficient, particular if they can avoid NBC patch level changes sufficient, particular if they can avoid non-backwards-compatible
(i.e. 'M' labeled versions). patch level changes.
5.3.2. Package checksums 5.3.2. Package checksums
Each YANG package definition may have a checksum associated with it Each YANG package definition may have a checksum associated with it
to allow a client to validate that the package definition of the to allow a client to validate that the package definition of the
server matches the expected package definition without downloading server matches the expected package definition without downloading
the full package definition from the server. the full package definition from the server.
The checksum for a package is calculated using the SHA-256 hash (XXX, The checksum for a package is calculated using the SHA-256 hash (XXX,
reference) of the full file contents of the YANG package instance reference) of the full file contents of the YANG package instance
data file. This means that the checksum includes all whitespace and data file. This means that the checksum includes all whitespace and
formatting, encoding, and all meta-data fields associated with the formatting, encoding, and all meta-data fields associated with the
package and the instance data document). package and the instance data file).
The checksum for a module is calculated using the SHA-256 hash of the The checksum for a module is calculated using the SHA-256 hash of the
YANG module file definition. This means that the checksum includes YANG module file definition. This means that the checksum includes
all whitespace, formatting, and comments within the YANG module. all whitespace, formatting, and comments within the YANG module.
Packages that are locally scoped to a server may not have an offline Packages that are locally scoped to a server may not have an offline
instance data document available, and hence MAY not have a checksum. instance data file available, and hence MAY not have a checksum.
The package definition allows URLs and checksums to be specified for The package definition allows URLs and checksums to be specified for
all included packages, modules and submodules within the package all included packages, modules and submodules within the package
definition. Checksums SHOULD be included in package definitions to definition. Checksums SHOULD be included in package definitions to
validate the full integrity of the package. validate the full integrity of the package.
On a server, package checksums SHOULD also be provided for the top On a server, package checksums SHOULD also be provided for the top
level packages associated with the datastore schema. level packages associated with the datastore schema.
5.3.3. The relationship between packages and datastores 5.3.3. The relationship between packages and datastores
As defined by NMDA [RFC8342], each datastore has an associated As defined by NMDA [RFC8342], each datastore has an associated
datastore schema. Sections 5.1 and 5.3 of NMDA defines further datastore schema. Sections 5.1 and 5.3 of NMDA defines further
constraints on the schema associated with datastores. These constraints on the schema associated with datastores. These
constraints can be summarized thus: constraints can be summarized thus:
The schema for all conventional datastores is the same. o The schema for all conventional datastores is the same.
The schema for non conventional configuration datastores (e.g., o The schema for non conventional configuration datastores (e.g.,
dynamic datastores) may completely differ (i.e. no overlap at all) dynamic datastores) may completely differ (i.e. no overlap at all)
from the schema associated with the conventional configuration from the schema associated with the conventional configuration
datastores, or may partially or fully overlap with the schema of datastores, or may partially or fully overlap with the schema of
the conventional configuration datastores. A dynamic datastore, the conventional configuration datastores. A dynamic datastore,
for example, may support different modules than conventional for example, may support different modules than conventional
datastores, or may support a subset or superset of modules, datastores, or may support a subset or superset of modules,
features, or data nodes supported in the conventional features, or data nodes supported in the conventional
configuration datastores. Where a data node exists in multiple configuration datastores. Where a data node exists in multiple
datastore schema it has the same type, properties and semantics. datastore schema it has the same type, properties and semantics.
The schema for the operational datastore is intended to be a o The schema for the operational datastore is intended to be a
superset of all the configuration datastores (i.e. includes all superset of all the configuration datastores (i.e. includes all
the schema nodes from the conventional configuration datastores), the schema nodes from the conventional configuration datastores),
but data nodes can be omitted if they cannot be accurately but data nodes can be omitted if they cannot be accurately
reported. The operational datastore schema can include additional reported. The operational datastore schema can include additional
modules containing only config false data nodes, but there is no modules containing only config false data nodes, but there is no
harm in including those modules in the configuration datastore harm in including those modules in the configuration datastore
schema as well. schema as well.
Given that YANG packages represent a YANG schema, it follows that Given that YANG packages represent a YANG schema, it follows that
each datastore schema can be represented using packages. In each datastore schema can be represented using packages. In
addition, the schema for most datastores on a server are often addition, the schema for most datastores on a server are often
closely related. Given that there are many ways that a datastore closely related. Given that there are many ways that a datastore
schema could be represented using packages, the following guidance schema could be represented using packages, the following guidance
provides a consistent approach to help clients understand the provides a consistent approach to help clients understand the
relationship between the different datastore schema supported by a relationship between the different datastore schema supported by a
device (e.g., which parts of the schema are common and which parts device (e.g., which parts of the schema are common and which parts
have differences): have differences):
Any datastores (e.g., conventional configuration datastores) that o Any datastores (e.g., conventional configuration datastores) that
have exactly the same datastore schema MUST use the same package have exactly the same datastore schema MUST use the same package
definitions. This is to avoid, for example, the creation of a definitions. This is to avoid, for example, the creation of a
'running-cfg' package and a separate 'intended-cfg' package that 'running-cfg' package and a separate 'intended-cfg' package that
have identical schema. have identical schema.
Common package definitions SHOULD be used for those parts of the o Common package definitions SHOULD be used for those parts of the
datastore schema that are common between datastores, when those datastore schema that are common between datastores, when those
datastores do not share exactly the same datastore schema. E.g., datastores do not share exactly the same datastore schema. E.g.,
if a substantial part of the schema is common between the if a substantial part of the schema is common between the
conventional, dynamic, and operational datastores then a single conventional, dynamic, and operational datastores then a single
common package can be used to describe the common parts, along common package can be used to describe the common parts, along
with other packages to describe the unique parts of each datastore with other packages to describe the unique parts of each datastore
schema. schema.
YANG modules that do not contain any configuration data nodes o YANG modules that do not contain any configuration data nodes
SHOULD be included in the package for configuration datastores if SHOULD be included in the package for configuration datastores if
that helps unify the package definitions. that helps unify the package definitions.
The packages for the operational datastore schema MUST include all o The packages for the operational datastore schema MUST include all
packages for all configuration datastores, along with any required packages for all configuration datastores, along with any required
modules defining deviations to mark unsupported data nodes. The modules defining deviations to mark unsupported data nodes. The
deviations MAY be defined directly in the packages defining the deviations MAY be defined directly in the packages defining the
operational datastore schema, or in separate non referentially operational datastore schema, or in separate non referentially
complete packages. complete packages.
The schema for a datastore MAY be represented using a single o The schema for a datastore MAY be represented using a single
package or as the union of a set of compatible packages, i.e., package or as the union of a set of compatible packages, i.e.,
equivalently to a set of non-conflicting packages being included equivalently to a set of non-conflicting packages being included
together in an overarching package definition. together in an overarching package definition.
5.4. Schema referential completeness 5.4. Schema referential completeness
A YANG package may represent a schema that is 'referentially A YANG package may represent a schema that is 'referentially
complete', or 'referentially incomplete', indicated in the package complete', or 'referentially incomplete', indicated in the package
definition by the 'complete' flag. definition by the 'complete' flag.
skipping to change at page 14, line 16 skipping to change at page 14, line 22
YANG package names can be globally unique, or locally scoped to a YANG package names can be globally unique, or locally scoped to a
particular server or device. particular server or device.
5.5.1. Globally scoped packages 5.5.1. Globally scoped packages
The name given to a package MUST be globally unique, and it MUST The name given to a package MUST be globally unique, and it MUST
include an appropriate organization prefix in the name, equivalent to include an appropriate organization prefix in the name, equivalent to
YANG module naming conventions. YANG module naming conventions.
Ideally a YANG instance data document defining a particular package Ideally a YANG instance data file defining a particular package
version would be publicly available at one or more URLs. version would be publicly available at one or more URLs.
5.5.2. Server scoped packages 5.5.2. Server scoped packages
Package definitions may be scoped to a particular server by setting Package definitions may be scoped to a particular server by setting
the 'is-local' leaf to true in the package definition. the 'is-local' leaf to true in the package definition.
Locally scoped packages MAY have a package name that is not globally Locally scoped packages MAY have a package name that is not globally
unique. unique.
Locally scoped packages MAY have a definition that is not available Locally scoped packages MAY have a definition that is not available
offline from the server in a YANG instance data document. offline from the server in a YANG instance data file.
5.6. Submodules packages considerations 5.6. Submodules packages considerations
As defined in [RFC7950] and [I-D.verdt-netmod-yang-semver], YANG As defined in [RFC7950] and [I-D.ietf-netmod-yang-semver], YANG
conformance and versioning is specified in terms of particular conformance and versioning is specified in terms of particular
revisions of YANG modules rather than for individual submodules. revisions of YANG modules rather than for individual submodules.
However, YANG package definitions also include the list of submodules However, YANG package definitions also include the list of submodules
included by a module, primarily to provide a location of where the included by a module, primarily to provide a location of where the
submodule definition can be obtained from, allowing a YANG schema to submodule definition can be obtained from, allowing a YANG schema to
be fully constructed from a YANG package instance-data file be fully constructed from a YANG package instance data file
definition. definition.
5.7. Package tags 5.7. Package tags
[I-D.ietf-netmod-module-tags] defines YANG module tags as a mechanism [I-D.ietf-netmod-module-tags] defines YANG module tags as a mechanism
to annotate a module definition with additional metadata. Tags MAY to annotate a module definition with additional metadata. Tags MAY
also be associated to a package definition via the 'tags' leaf-list. also be associated to a package definition via the 'tags' leaf-list.
The tags use the same registry and definitions used by YANG module The tags use the same registry and definitions used by YANG module
tags. tags.
5.8. YANG package core definition 5.8. YANG Package Usage Guidance
It is RECOMMENDED that organizations that publish YANG modules also
publish YANG package definition that group and version those modules
into units of related functionality. This increases
interoperability, by encouraging implementations to use the same
collections of YANG modules versions. Using packages also makes it
easier to understand relationship between modules, and enables
functionality to be described on a more abstract level than
individual modules.
5.8.1. Use of deviations in YANG packages
[RFC7950] section 5.6.3 defines deviations as the mechanism to allow
servers to indicate where they do not conform to a published YANG
module that is being implemented.
In cases where implementations contain deviations from published
packages, then those implementations SHOULD define a package that
includes both the published packages and all modules containing
deviations. This implementation specific package accurately reflects
the schema used by the device and allows clients to determine how the
implementation differs from the published package schema in an
offline consumable way, e.g., when published in an instance data file
(see section 6).
Organizations may wish to reuse YANG modules and YANG packages
published by other organizations for new functionality. Sometimes,
they may desire to modify the published YANG modules. However, they
MUST NOT use deviations in an attempt to achieve this because such
deviations cause two problems:
They prevent implementations from reporting their own deviations
for the same nodes.
They fracture the ecosystem by preventing implementations from
conforming to the standards specified by both organizations. This
hurts the interoperability in the YANG community, promotes
development of disconnected functional silos, and hurts creativity
in the market.
5.8.2. Use of features in YANG modules and YANG packages
The YANG language supports feature statements as the mechanism to
make parts of a schema optional. Published standard YANG modules
SHOULD make use of appropriate feature statements to provide
flexibility in how YANG modules may be used by implementations and
used by YANG modules published by other organizations.
YANG packages support 'mandatory features' which allow a package to
specify features that MUST be implemented by any conformant
implementation of the package as a mechanism to simplify and manage
the schema represented by a YANG package.
5.9. YANG package core definition
The ietf-yang-package-types.yang module defines a grouping to specify The ietf-yang-package-types.yang module defines a grouping to specify
the core elements of the YANG package structure that is used within the core elements of the YANG package structure that is used within
YANG package instance data documents (ietf-yang-package- YANG package instance data files (ietf-yang-package-instance.yang)
instance.yang) and also on the server (ietf-yang-packages.yang). and also on the server (ietf-yang-packages.yang).
The "ietf-yang-package-types" YANG module has the following The "ietf-yang-package-types" YANG module has the following
structure: structure:
module: ietf-yang-package-types module: ietf-yang-package-types
grouping yang-pkg-identification-leafs grouping yang-pkg-identification-leafs
+-- name pkg-name +-- name pkg-name
+-- version pkg-version +-- version pkg-version
skipping to change at page 16, line 19 skipping to change at page 17, line 32
+-- replaces-revision* rev:revision-date-or-label +-- replaces-revision* rev:revision-date-or-label
+-- namespace? inet:uri +-- namespace? inet:uri
+-- location* inet:uri +-- location* inet:uri
+-- checksum? pkg-types:sha-256-hash +-- checksum? pkg-types:sha-256-hash
+-- submodule* [name] +-- submodule* [name]
+-- name? yang:yang-identifier +-- name? yang:yang-identifier
+-- revision yang:revision-identifier +-- revision yang:revision-identifier
+-- location* inet:uri +-- location* inet:uri
+-- checksum? pkg-types:sha-256-hash +-- checksum? pkg-types:sha-256-hash
6. Package Instance Data Documents 6. Package Instance Data Files
YANG packages SHOULD be available offline from the server, defined as YANG packages SHOULD be available offline from the server, defined as
YANG instance data documents YANG instance data files [I-D.ietf-netmod-yang-instance-file-format]
[I-D.ietf-netmod-yang-instance-file-format] using the YANG schema using the YANG schema below to define the package data.
below to define the package data.
The format of the YANG package instance file MUST follow the The following rules apply to the format of the YANG package instance
following rules: files:
The file SHOULD be encoded in JSON. 1. The file SHOULD be encoded in JSON.
The name of the file SHOULD follow the format "<package- 2. The name of the file SHOULD follow the format "<package-
name>@<version>.json". name>@<version>.json".
The package name MUST be specified in both the instance-data-set 3. The package name MUST be specified in both the instance-data-set
'name' and package 'name' leafs. 'name' and package 'name' leafs.
The 'description' field of the instance-data-set SHOULD be "YANG 4. The 'description' field of the instance-data-set SHOULD be "YANG
package definition". package definition".
The 'timestamp', "organization', 'contact' fields are defined in 5. The 'timestamp', "organization', 'contact' fields are defined in
both the instance-data-set metadata and the YANG package metadata. both the instance-data-set metadata and the YANG package
Package definitions SHOULD only define these fields as part of the metadata. Package definitions SHOULD only define these fields as
package definition. If any of these fields are populated in the part of the package definition. If any of these fields are
instance-data-set metadata then they MUST contain the same value populated in the instance-data-set metadata then they MUST
as the corresponding leaves in the package definition. contain the same value as the corresponding leaves in the package
definition.
The 'revision' list in the instance data document SHOULD NOT be 6. The 'revision' list in the instance data file SHOULD NOT be used,
used, since versioning is handled by the package definition. since versioning is handled by the package definition.
The instance data document for each version of a YANG package 7. The instance data file for each version of a YANG package SHOULD
SHOULD be made available at one of more locations accessible via be made available at one of more locations accessible via URLs.
URLs. If one of the listed locations defines a definitive If one of the listed locations defines a definitive reference
reference implementation for the package definition then it MUST implementation for the package definition then it MUST be listed
be listed as the first entry in the list. as the first entry in the list.
The "ietf-yang-package" YANG module has the following structure: The "ietf-yang-package" YANG module has the following structure:
module: ietf-yang-package module: ietf-yang-package
structure package: structure package:
// Uses the yang-package-instance grouping defined in // Uses the yang-package-instance grouping defined in
// ietf-yang-package-types.yang // ietf-yang-package-types.yang
+-- name pkg-name +-- name pkg-name
+-- version pkg-version +-- version pkg-version
... remainder of yang-package-instance grouping ... ... remainder of yang-package-instance grouping ...
7. Package Definitions on a Server 7. Package Definitions on a Server
7.1. Package List 7.1. Package List
A top level 'packages' container holds the list of all versions of A top level 'packages' container holds the list of all versions of
all packages known to the server. Each list entry uses the common all packages known to the server. Each list entry uses the common
package definition, but with the addition of package location and package definition, but with the addition of package location and
checksum information that cannot be contained within a offline checksum information that cannot be contained within a offline
package definition contained in an instance data document. package definition contained in an instance data file.
The '/packages/package' list MAY include multiple versions of a The '/packages/package' list MAY include multiple versions of a
particular package. E.g. if the server is capable of allowing particular package. E.g. if the server is capable of allowing
clients to select which package versions should be used by the clients to select which package versions should be used by the
server. server.
7.2. Tree diagram 7.2. Tree diagram
The "ietf-yang-packages" YANG module has the following structure: The "ietf-yang-packages" YANG module has the following structure:
module: ietf-yang-packages module: ietf-yang-packages
+--ro packages +--ro packages
+--ro package* [name version] +--ro package* [name version]
// Uses the yang-package-instance grouping defined in // Uses the yang-package-instance grouping defined in
// ietf-yang-package-types.yang, with location and checksum: // ietf-yang-package-types.yang, with location and checksum:
+--ro name pkg-name +--ro name pkg-name
+--ro version pkg-version +--ro version pkg-version
... remainder of yang-package-instance grouping ... ... remainder of yang-package-instance grouping ...
skipping to change at page 18, line 22 skipping to change at page 19, line 25
+--ro version pkg-version +--ro version pkg-version
... remainder of yang-package-instance grouping ... ... remainder of yang-package-instance grouping ...
+--ro location* inet:uri +--ro location* inet:uri
+--ro checksum? pkg-types:sha-256-hash +--ro checksum? pkg-types:sha-256-hash
8. YANG Library Package Bindings 8. YANG Library Package Bindings
The YANG packages module also augments YANG library to allow a server The YANG packages module also augments YANG library to allow a server
to optionally indicate that a datastore schema is defined by a to optionally indicate that a datastore schema is defined by a
package, or a union of compatible packages. Since packages can package, or a union of compatible packages. Since packages can
generally be made available offline in instance data documents, it generally be made available offline in instance data files, it may be
may be sufficient for a client to only check that a compatible sufficient for a client to only check that a compatible version of
version of the package is implemented by the server without fetching the package is implemented by the server without fetching either the
either the package definition, or downloading and comparing the full package definition, or downloading and comparing the full list of
list of modules and enabled features. modules and enabled features.
If a server indicates that a datastore schema maps to a particular If a server indicates that a datastore schema maps to a particular
package, then it MUST exactly match the schema defined by that package, then it MUST exactly match the schema defined by that
package, taking into account enabled features and any deviations. package, taking into account enabled features and any deviations.
If a server cannot faithfully implement a package then it can define If a server cannot faithfully implement a package then it can define
a new package to accurately report what it does implement. The new a new package to accurately report what it does implement. The new
package can include the original package as an included package, and package can include the original package as an included package, and
the new package can define additional modules containing deviations the new package can define additional modules containing deviations
to the modules in the original package, allowing the new package to to the modules in the original package, allowing the new package to
skipping to change at page 19, line 17 skipping to change at page 20, line 17
module: ietf-yl-packages module: ietf-yl-packages
augment /yanglib:yang-library/yanglib:schema: augment /yanglib:yang-library/yanglib:schema:
+--ro package* [name version] +--ro package* [name version]
+--ro name -> /pkgs:packages/package/name +--ro name -> /pkgs:packages/package/name
+--ro version leafref +--ro version leafref
+--ro checksum? leafref +--ro checksum? leafref
9. YANG packages as schema for YANG instance data document 9. YANG packages as schema for YANG instance data document
YANG package definitions can be used as the schema definition for YANG package definitions can be used as the schema definition for
YANG instance data documents. When using a package schema, the name YANG instance data files. When using a package schema, the name and
and version of the package MUST be specified, a package checksum and/ version of the package MUST be specified, a package checksum and/or
or URL to the package definition MAY also be provided. URL to the package definition MAY also be provided.
The "ietf-yang-inst-data-pkg" YANG module has the following The "ietf-yang-inst-data-pkg" YANG module has the following
structure: structure:
module: ietf-yang-inst-data-pkg module: ietf-yang-inst-data-pkg
augment-structure /yid:instance-data-set/yid:content-schema-spec: augment-structure /yid:instance-data-set/yid:content-schema-spec:
+--:(pkg-schema) +--:(pkg-schema)
+-- pkg-schema +-- pkg-schema
+-- name pkg-name +-- name pkg-name
skipping to change at page 41, line 18 skipping to change at page 42, line 18
operations and content. operations and content.
Similarly to YANG library [I-D.ietf-netconf-rfc7895bis], some of the Similarly to YANG library [I-D.ietf-netconf-rfc7895bis], some of the
readable data nodes in these YANG modules may be considered sensitive readable data nodes in these YANG modules may be considered sensitive
or vulnerable in some network environments. It is thus important to or vulnerable in some network environments. It is thus important to
control read access (e.g., via get, get-config, or notification) to control read access (e.g., via get, get-config, or notification) to
these data nodes. these data nodes.
One additional key different to YANG library, is that the 'ietf-yang- One additional key different to YANG library, is that the 'ietf-yang-
package' YANG module defines a schema to allow YANG packages to be package' YANG module defines a schema to allow YANG packages to be
defined in YANG instance data documents, that are outside the defined in YANG instance data files, that are outside the security
security controls of the network management protocols. Hence, it is controls of the network management protocols. Hence, it is important
important to also consider controlling access to these package to also consider controlling access to these package instance data
instance data documents to restrict access to sensitive information. files to restrict access to sensitive information. SHA-256 checksums
SHA-256 checksums are used to ensure the integrity of YANG package are used to ensure the integrity of YANG package definitions,
definitions, imported modules, and sub-modules. imported modules, and sub-modules.
As per the YANG library security considerations, the module, revision As per the YANG library security considerations, the module, revision
and version information in YANG packages may help an attacker and version information in YANG packages may help an attacker
identify the server capabilities and server implementations with identify the server capabilities and server implementations with
known bugs since the set of YANG modules supported by a server may known bugs since the set of YANG modules supported by a server may
reveal the kind of device and the manufacturer of the device. Server reveal the kind of device and the manufacturer of the device. Server
vulnerabilities may be specific to particular modules, module vulnerabilities may be specific to particular modules, module
revisions, module features, or even module deviations. For example, revisions, module features, or even module deviations. For example,
if a particular operation on a particular data node is known to cause if a particular operation on a particular data node is known to cause
a server to crash or significantly degrade device performance, then a server to crash or significantly degrade device performance, then
skipping to change at page 43, line 14 skipping to change at page 44, line 14
Reference: RFC XXXX Reference: RFC XXXX
13. Open Questions/Issues 13. Open Questions/Issues
All issues, along with the draft text, are currently being tracked at All issues, along with the draft text, are currently being tracked at
https://github.com/rgwilton/YANG-Packages-Draft/issues/ https://github.com/rgwilton/YANG-Packages-Draft/issues/
14. Acknowledgements 14. Acknowledgements
Feedback helping shape this document has kindly been provided by Andy Feedback helping shape this document has kindly been provided by Andy
Bierman, Bo Wang, Joe Clarke, James Cumming, Mahesh Jethanandani, Bierman, James Cumming, Mahesh Jethanandani, Balazs Lengyel, Ladislav
Balazs Lengyel, Ladislav Lhotka, Jason Sterne, and Reshad Rahman. Lhotka,and Jan Lindblad.
15. References 15. References
15.1. Normative References 15.1. Normative References
[I-D.ietf-netconf-rfc7895bis] [I-D.ietf-netconf-rfc7895bis]
Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K.,
and R. Wilton, "YANG Library", draft-ietf-netconf- and R. Wilton, "YANG Library", draft-ietf-netconf-
rfc7895bis-07 (work in progress), October 2018. rfc7895bis-07 (work in progress), October 2018.
skipping to change at page 43, line 38 skipping to change at page 44, line 38
Tags", draft-ietf-netmod-module-tags-10 (work in Tags", draft-ietf-netmod-module-tags-10 (work in
progress), February 2020. progress), February 2020.
[I-D.ietf-netmod-yang-data-ext] [I-D.ietf-netmod-yang-data-ext]
Bierman, A., Bjorklund, M., and K. Watsen, "YANG Data Bierman, A., Bjorklund, M., and K. Watsen, "YANG Data
Structure Extensions", draft-ietf-netmod-yang-data-ext-05 Structure Extensions", draft-ietf-netmod-yang-data-ext-05
(work in progress), December 2019. (work in progress), December 2019.
[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.verdt-netmod-yang-module-versioning] [I-D.ietf-netmod-yang-module-versioning]
Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, Wilton, R., Rahman, R., Lengyel, B., Clarke, J., Sterne,
B., Sterne, J., and K. D'Souza, "Updated YANG Module J., Claise, B., and K. D'Souza, "Updated YANG Module
Revision Handling", draft-verdt-netmod-yang-module- Revision Handling", draft-ietf-netmod-yang-module-
versioning-01 (work in progress), October 2019. versioning-01 (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-01 (work in
progress), October 2019. progress), July 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.verdt-netmod-yang-versioning-reqs]
Clarke, J., "YANG Module Versioning Requirements", draft-
verdt-netmod-yang-versioning-reqs-02 (work in progress),
November 2018.
[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.
[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 46, line 13 skipping to change at page 47, line 13
dependencies work. It does not imply that such packages will be dependencies work. It does not imply that such packages will be
defined by IETF, or which modules would be included in those packages defined by IETF, or which modules would be included in those packages
even if they were defined. For brevity, the examples exclude even if they were defined. For brevity, the examples exclude
namespace declarations, and use a shortened URL of "tiny.cc/ietf- namespace declarations, and use a shortened URL of "tiny.cc/ietf-
yang" as a replacement for yang" as a replacement for
"https://raw.githubusercontent.com/YangModels/yang/master/standard/ "https://raw.githubusercontent.com/YangModels/yang/master/standard/
ietf/RFC". ietf/RFC".
A.1. Example IETF Network Device YANG package A.1. Example IETF Network Device YANG package
This section provides an instance data document example of an IETF This section provides an instance data file example of an IETF
Network Device YANG package formatted in JSON. Network Device YANG package formatted in JSON.
This example package is intended to represent the standard set of This example package is intended to represent the standard set of
YANG modules, with import dependencies, to implement a basic network YANG modules, with import dependencies, to implement a basic network
device without any dynamic routing or layer 2 services. E.g., it device without any dynamic routing or layer 2 services. E.g., it
includes functionality such as system information, interface and includes functionality such as system information, interface and
basic IP configuration. basic IP configuration.
As for all YANG packages, all import dependencies are fully resolved. As for all YANG packages, all import dependencies are fully resolved.
Because this example uses YANG modules that have been standardized Because this example uses YANG modules that have been standardized
skipping to change at page 48, line 35 skipping to change at page 49, line 35
} }
] ]
} }
} }
} }
} }
<CODE ENDS> <CODE ENDS>
A.2. Example IETF Basic Routing YANG package A.2. Example IETF Basic Routing YANG package
This section provides an instance data document example of a basic This section provides an instance data file example of a basic IETF
IETF Routing YANG package formatted in JSON. Routing YANG package formatted in JSON.
This example package is intended to represent the standard set of This example package is intended to represent the standard set of
YANG modules, with import dependencies, that builds upon the example- YANG modules, with import dependencies, that builds upon the example-
ietf-network-device YANG package to add support for basic dynamic ietf-network-device YANG package to add support for basic dynamic
routing and ACLs. routing and ACLs.
As for all YANG packages, all import dependencies are fully resolved. As for all YANG packages, all import dependencies are fully resolved.
Because this example uses YANG modules that have been standardized Because this example uses YANG modules that have been standardized
before YANG semantic versioning, they modules are referenced by before YANG semantic versioning, they modules are referenced by
revision date rather than version number. Locations have been revision date rather than version number. Locations have been
skipping to change at page 54, line 40 skipping to change at page 55, line 40
Module tags have been suggested as an alternative solution, and Module tags have been suggested as an alternative solution, and
indeed that can address some of the same requirements as YANG indeed that can address some of the same requirements as YANG
packages but not all of them. packages but not all of them.
Module tags can be used to group or organize YANG modules. However, Module tags can be used to group or organize YANG modules. However,
this raises the question of where this tag information is stored. this raises the question of where this tag information is stored.
Module tags either require that the YANG module files themselves are Module tags either require that the YANG module files themselves are
updated with the module tag information (creating another versioning updated with the module tag information (creating another versioning
problem), or for the module tag information to be hosted elsewhere, problem), or for the module tag information to be hosted elsewhere,
perhaps in a centralize YANG Catalog, or in instance data documents perhaps in a centralize YANG Catalog, or in instance data files
similar to how YANG packages have been defined in this draft. similar to how YANG packages have been defined in this draft.
One of the principle aims of YANG packages is to be a versioned One of the principle aims of YANG packages is to be a versioned
object that defines a precise set of YANG modules versions that work object that defines a precise set of YANG modules versions that work
together. Module tags cannot meet this aim without an explosion of together. Module tags cannot meet this aim without an explosion of
module tags definitions (i.e. a separate module tag must be defined module tags definitions (i.e. a separate module tag must be defined
for each package version). for each package version).
Module tags cannot support the hierachical scheme to construct YANG Module tags cannot support the hierachical scheme to construct YANG
schema that is proposed in this draft. schema that is proposed in this draft.
B.2. Using YANG library B.2. Using YANG library
Another question is whether it is necessary to define new YANG Another question is whether it is necessary to define new YANG
modules to define YANG packages, and whether YANG library could just modules to define YANG packages, and whether YANG library could just
be reused in an instance data document. The use of YANG packages be reused in an instance data file. The use of YANG packages offers
offers several benefits over just using YANG library: several benefits over just using YANG library:
1. Packages allow schema to be built in a hierarchical fashion. 1. Packages allow schema to be built in a hierarchical fashion.
[I-D.ietf-netconf-rfc7895bis] only allows one layer of hierarchy [I-D.ietf-netconf-rfc7895bis] only allows one layer of hierarchy
(using module sets), and there must be no conflicts between (using module sets), and there must be no conflicts between
module revisions in different module-sets. module revisions in different module-sets.
2. Packages can be made available off the box, with a well defined 2. Packages can be made available off the box, with a well defined
unique name, avoiding the need for clients to download, and unique name, avoiding the need for clients to download, and
construct/check the entire YANG schema for each device. Instead construct/check the entire YANG schema for each device. Instead
they can rely on the named packages with secure checksums. YANG they can rely on the named packages with secure checksums. YANG
library's use of a 'content-id' is unique only to the device that library's use of a 'content-id' is unique only to the device that
generated them. generated them.
3. Packages may be versioned using a semantic versioning scheme, 3. Packages may be versioned using a semantic versioning scheme,
YANG library does not provide a schema level semantic version YANG library does not provide a schema level semantic version
number. number.
4. For a YANG library instance data document to contain the 4. For a YANG library instance data file to contain the necessary
necessary information, it probably needs both YANG library and information, it probably needs both YANG library and various
various augmentations (e.g. to include each module's semantic augmentations (e.g. to include each module's semantic version
version number), unless a new version of YANG library is defined number), unless a new version of YANG library is defined
containing this information. The module definition for a YANG containing this information. The module definition for a YANG
package is specified to contain all of the ncessary information package is specified to contain all of the ncessary information
to solve the problem without augmentations to solve the problem without augmentations
5. YANG library is designed to publish information about the 5. YANG library is designed to publish information about the
modules, datastores, and datastore schema used by a server. The modules, datastores, and datastore schema used by a server. The
information required to construct an off box schema is not information required to construct an off box schema is not
precisely the same, and hence the definitions might deviate from precisely the same, and hence the definitions might deviate from
each other over time. each other over time.
skipping to change at page 56, line 19 skipping to change at page 57, line 19
Joe Clarke Joe Clarke
Cisco Systems, Inc. Cisco Systems, Inc.
Email: jclarke@cisco.com Email: jclarke@cisco.com
Jason Sterne Jason Sterne
Nokia Nokia
Email: jason.sterne@nokia.com Email: jason.sterne@nokia.com
Bo Wu Bo Wu (editor)
Huawei Huawei
Email: lana.wubo@huawei.com Email: lana.wubo@huawei.com
 End of changes. 101 change blocks. 
204 lines changed or deleted 270 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/