YANG Packages
draft-ietf-netmod-yang-packages-04
| Document | Type | Active Internet-Draft (netmod WG) | |
|---|---|---|---|
| Authors | Robert Wilton , Reshad Rahman , Joe Clarke , Jason Sterne , Bo Wu | ||
| Last updated | 2024-10-21 | ||
| Replaces | draft-rwilton-netmod-yang-packages | ||
| RFC stream | Internet Engineering Task Force (IETF) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Yang Validation | 1 errors, 8 warnings | ||
| Additional resources |
Yang catalog entry for ietf-yang-inst-data-pkg@2020-01-21.yang
Yang catalog entry for ietf-yang-package-instance@2020-01-21.yang Yang catalog entry for ietf-yang-package-types@2020-01-21.yang Yang catalog entry for ietf-yang-packages@2020-01-21.yang Yang catalog entry for ietf-yl-packages@2020-01-21.yang Yang impact analysis for draft-ietf-netmod-yang-packages Mailing list discussion |
||
| Stream | WG state | WG Document | |
| Document shepherd | (None) | ||
| IESG | IESG state | I-D Exists | |
| Consensus boilerplate | Unknown | ||
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-ietf-netmod-yang-packages-04
Network Working Group R. Wilton, Ed.
Internet-Draft Cisco Systems, Inc.
Intended status: Standards Track R. Rahman
Expires: 24 April 2025 Equinix
J. Clarke
Cisco Systems, Inc.
J. Sterne
Nokia
B. Wu, Ed.
Huawei
21 October 2024
YANG Packages
draft-ietf-netmod-yang-packages-04
Abstract
This document defines YANG packages; a versioned organizational
structure used to manage schema and conformance of YANG modules as a
cohesive set instead of individually.
It describes how packages: are represented on a server, can be
defined in offline YANG instance data files, and can be used to
define the content schema associated with YANG instance data files.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 24 April 2025.
Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the
document authors. All rights reserved.
Wilton, et al. Expires 24 April 2025 [Page 1]
Internet-Draft YANG Packages October 2024
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Terminology and Conventions . . . . . . . . . . . . . . . . . 3
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Background on YANG packages . . . . . . . . . . . . . . . . . 4
4. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 5
5. YANG Package Definition . . . . . . . . . . . . . . . . . . . 6
5.1. Package definition rules . . . . . . . . . . . . . . . . 7
5.2. Package versioning . . . . . . . . . . . . . . . . . . . 8
5.2.1. Updating a package with a new version . . . . . . . . 8
5.2.1.1. Non-Backwards-compatible changes . . . . . . . . 8
5.2.1.2. Backwards-compatible changes . . . . . . . . . . 8
5.2.1.3. Editorial changes . . . . . . . . . . . . . . . . 9
5.2.2. YANG Semantic Versioning for packages . . . . . . . . 9
5.2.3. Guidelines for Package Versions During Package
Development . . . . . . . . . . . . . . . . . . . . . 10
5.3. Package conformance . . . . . . . . . . . . . . . . . . . 10
5.3.1. Use of YANG semantic versioning . . . . . . . . . . . 10
5.3.2. The relationship between packages and datastores . . 11
5.4. Schema referential completeness . . . . . . . . . . . . . 12
5.5. Package name scoping and uniqueness . . . . . . . . . . . 13
5.6. Submodules packages considerations . . . . . . . . . . . 14
5.7. Package tags . . . . . . . . . . . . . . . . . . . . . . 14
5.8. YANG Package Usage Guidance . . . . . . . . . . . . . . . 14
5.8.1. Use of deviations in YANG packages . . . . . . . . . 14
5.8.2. Use of features in YANG modules and YANG packages . . 15
5.9. YANG package core definition . . . . . . . . . . . . . . 15
6. Package Instance Data Files . . . . . . . . . . . . . . . . . 17
7. Package Definitions on a Server . . . . . . . . . . . . . . . 18
7.1. Package List . . . . . . . . . . . . . . . . . . . . . . 18
7.2. Tree diagram . . . . . . . . . . . . . . . . . . . . . . 18
8. YANG Library Package Bindings . . . . . . . . . . . . . . . . 18
9. YANG packages as schema for YANG instance data document . . . 19
10. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 19
11. Security Considerations . . . . . . . . . . . . . . . . . . . 39
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 40
13. Open Questions/Issues . . . . . . . . . . . . . . . . . . . . 41
14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 41
15. References . . . . . . . . . . . . . . . . . . . . . . . . . 42
Wilton, et al. Expires 24 April 2025 [Page 2]
Internet-Draft YANG Packages October 2024
15.1. Normative References . . . . . . . . . . . . . . . . . . 42
15.2. Informative References . . . . . . . . . . . . . . . . . 44
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 45
A.1. Example IETF Network Device YANG package . . . . . . . . 45
A.2. Example IETF Basic Routing YANG package . . . . . . . . . 47
A.3. Package import conflict resolution example . . . . . . . 50
Appendix B. Possible alternative solutions . . . . . . . . . . . 53
B.1. Using module tags . . . . . . . . . . . . . . . . . . . . 54
B.2. Using YANG library . . . . . . . . . . . . . . . . . . . 54
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 55
1. Terminology and Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
This document uses terminology introduced in the YANG versioning
requirements draft [I-D.ietf-netmod-yang-versioning-reqs].
This document also makes of the following terminology introduced in
the Network Management Datastore Architecture [RFC8342]:
* datastore schema
This document also makes of the following terminology introduced in
the YANG 1.1 Data Modeling Language [RFC7950]:
* data node
* schema node
In addition, this document defines the following terminology:
* YANG package: a versioned organizational structure used to manage
a set of YANG modules that collectively define a package schema.
YANG packages are defined in Section 5.
* package schema: The combined set of schema nodes defined by a YANG
package. Package schema can be used to define datastore schema.
* backwards-compatible (BC) change: When used in the context of a
YANG module, it follows the definition in Section 3.1.1 of
[I-D.ietf-netmod-yang-module-versioning]. When used in the
context of a YANG package, it follows the definition in
Section 5.2.1.2.
Wilton, et al. Expires 24 April 2025 [Page 3]
Internet-Draft YANG Packages October 2024
* non-backwards-compatible (NBC) change: When used in the context of
a YANG module, it follows the definition in Section 3.1.2 of
[I-D.ietf-netmod-yang-module-versioning]. When used in the
context of a YANG package, it follows the definition in
Section 5.2.1.2.
* editorial change: When used in the context of a YANG module, it
follows the definition of an 'editorial change' in 3.2 of
[I-D.ietf-netmod-yang-module-versioning]. When used in the
context of a YANG package, it follows the definition in
Section 5.2.1.3.
2. Introduction
This document defines and describes the YANG [RFC7950] constructs
that are used to define and use YANG packages.
A YANG package is a versioned organizational structure used to manage
a set of YANG modules that collectively define a package schema. For
example, a YANG package could contain the set of YANG modules
required to implement an L2VPN service on a network device.
Non-normative examples of YANG packages are provided in the
appendices.
3. Background on YANG packages
It has long been acknowledged within the YANG community that network
management using YANG requires a unit of organization and conformance
that is broader in scope than individual YANG modules.
'The YANG Package Statement' [I-D.bierman-netmod-yang-package]
proposed a YANG package mechanism based on new YANG language
statements, where a YANG package is defined in a file similar to how
YANG modules are defined, and would require enhancements to YANG
compilers to understand the new statements used to define packages.
OpenConfig [openconfigsemver] describes an approach to versioning
'bundle releases' based on git tags. I.e. a set of modules, at
particular versions, can be marked with the same release tag to
indicate that they are known to interoperate together.
The NETMOD WG in general, and the YANG versioning design team in
particular, are exploring solutions [I-D.ietf-netmod-yang-solutions]
to the YANG versioning requirements,
[I-D.ietf-netmod-yang-versioning-reqs]. Solutions to the versioning
requirements can be split into several distinct areas.
[I-D.ietf-netmod-yang-module-versioning] is focused on YANG
Wilton, et al. Expires 24 April 2025 [Page 4]
Internet-Draft YANG Packages October 2024
versioning scoped to individual modules. The overall solution must
also consider YANG versioning and conformance scoped to sets of
modules. YANG packages provide part of the solution for versioning
sets of modules.
4. Objectives
The main goals of YANG package definitions include, but are not
restricted to:
* To provide an alternative, simplified, YANG conformance mechanism.
Rather than conformance being performed against a set of
individual YANG module revisions, features, and deviations,
conformance can be more simply stated in terms of YANG packages,
with a set of modifications (e.g. additional modules, deviations,
or features).
* To allow datastore schema to be specified in a concise way rather
than having each server explicitly list all modules, revisions,
and features. YANG package definitions can be defined in
documents that are available offline, and may be accessible via a
URL, rather than requiring explicit lists of modules to be shared
between client and server. Hence, a YANG package must contain
sufficient information to allow a client or server to precisely
construct the schema associated with the package.
* To define a mainly linear versioned history of sets of modules
versions that are known to work together. I.e. to help mitigate
the problem where a client must manage devices from multiple
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
of module foo and version 1.0.0 of module bar. For a client,
trying to interoperate with multiple vendors, and many YANG
modules, finding a consistent lowest common denominator set of
YANG module versions may be difficult, if not impossible.
Protocol mechanisms of how clients can negotiate which packages or
package versions are to be used for NETCONF/RESTCONF communications
are outside the scope of this document, and are defined in
[I-D.ietf-netmod-yang-ver-selection].
Finally, the package definitions proposed by this document are
intended to be relatively basic in their definition and the
functionality that they support. As industry gains experience using
YANG packages, the standard YANG mechanisms of updating, or
augmenting YANG modules could also be used to extend the
functionality supported by YANG packages, if required.
Wilton, et al. Expires 24 April 2025 [Page 5]
Internet-Draft YANG Packages October 2024
5. YANG Package Definition
This document specifies an approach to defining YANG packages that is
different to either of the approaches described in the background.
A YANG package is a versioned organizational structure used to manage
a set of YANG modules that collectively define a package schema.
Each YANG package has a name that SHOULD end with the suffix "-pkg".
Package names are normally expected to be globally unique, but in
some cases the package name may be locally scoped to a server or
device, as described in Section 5.5.
YANG packages are versioned using the same approaches described in
[I-D.ietf-netmod-yang-module-versioning] and
[I-D.ietf-netmod-yang-semver]. This is described in further detail
in Section 5.2.
Each YANG package version, defines:
* some metadata about the package, e.g., description, tags, scoping,
referential completeness, location information.
* a set of YANG modules, at particular revisions, that are
implemented by servers that implement the package. The modules
may contain deviations.
* a set of import-only YANG modules, at particular revisions, that
are used 'import-only' by the servers that implement the package.
* a set of included YANG packages, at particular revisions, that are
also implemented by servers that implement the package.
* a set of YANG module features that must be supported by servers
that implement the package.
The structure for YANG package definitions uses existing YANG
language statements, YANG Data Structure Extensions
[I-D.ietf-netmod-yang-data-ext], and YANG Instance Data File Format
[I-D.ietf-netmod-yang-instance-file-format].
YANG package definitions are available offline in YANG instance data
files. Client applications can be designed to support particular
package versions that they expect to interoperate with.
YANG package definitions are available from the server via
augmentations to YANG Library [RFC8525]. Rather than client
applications downloading the entire contents of YANG library to
Wilton, et al. Expires 24 April 2025 [Page 6]
Internet-Draft YANG Packages October 2024
confirm that the server's datastore schema are compatible with the
client, they can simply check the names and versions of the packages
advertised in YANG library to know what schema to expect in the
server datastores.
YANG package definitions can also be used to define the content
schema associated with YANG instance data files holding other, e.g.,
non packages related, instance data.
5.1. Package definition rules
Packages are defined using the following rules:
1. A YANG package MAY represent a referentially complete set of
modules or MAY represent a set of modules with some module import
dependencies missing, as described in Section 5.4.
2. Packages definitions are hierarchical. A package can include
other packages. Only a single version of a package can be
included, and conflicting package includes (e.g. from descendant
package includes) MUST be explicitly resolved by indicating which
version takes precedence, and which versions are being replaced.
3. YANG package definitions MAY include modules containing deviation
statements, but those deviation statements MUST only be used in
an [RFC7950] 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 Section 5.8.1 for further
guidance on the use of deviations in YANG packages.
4. For each module implemented by a package, only a single revision
of that module MUST be implemented. Multiple revisions of a
module MAY be listed as import-only dependencies.
5. The revision of a module listed in the package 'module' list
supersedes any 'implemented' revision of the module listed in an
included package module list. The 'replaces-revision' leaf-list
is used to indicate which 'implemented' or 'import-only' module
revisions are replaced by this module revision. This allows a
package to explicitly resolve conflicts between implemented
module revisions in included packages.
Wilton, et al. Expires 24 April 2025 [Page 7]
Internet-Draft YANG Packages October 2024
6. The 'replaces-revision' leaf-list in the 'import-only-module'
list can be used to exclude duplicate revisions of import-only
modules from included packages. Otherwise, the import-only-
modules for a package are the import-only-modules from all
included packages combined with any modules listed in the
packages import-only-module list.
5.2. Package versioning
Individual versions of a YANG package are versioned using the
"revision-label" scheme defined in section 3.3 of
[I-D.ietf-netmod-yang-module-versioning].
5.2.1. Updating a package with a new version
Package compatibility is fundamentally defined by how the package
schema between two package versions has changed.
When a package definition is updated, the version associated with the
package MUST be updated appropriately, taking into consideration the
scope of the changes as defined by the rules below.
5.2.1.1. Non-Backwards-compatible changes
The following changes classify as non-backwards-compatible changes to
a package definition:
* Changing an 'included-package' list entry to select a package
version that is non-backwards-compatible to the prior package
version, or removing a previously included package.
* Changing a 'module' or 'import-only-module' list entry to select a
module revision that is non-backwards-compatible to the prior
module revision, or removing a previously implemented module.
* Removing a feature from the 'mandatory-feature' leaf-list.
* Adding, changing, or removing a module containing one or more
deviations, that when applied to the target module would create a
change that is considered a non-backwards-compatible change to the
affected data node in the schema associated with the prior package
version.
5.2.1.2. Backwards-compatible changes
The following changes classify as backwards-compatible changes to a
package definition:
Wilton, et al. Expires 24 April 2025 [Page 8]
Internet-Draft YANG Packages October 2024
* Changing an 'included-package' list entry to select a package
version that is backwards-compatible to the prior package version,
or including a new package that does not conflict with any
existing included package or module.
* Changing a 'module' or 'import-only-module' list entry to select a
module revision that is backwards-compatible to the prior module
revision, or including a new module to the package definition.
* Adding a feature to the 'mandatory-feature' leaf-list.
* Adding, changing, or removing a module containing one or more
deviations, that when applied to the target module would create a
change that is considered a backwards-compatible change to the
affected data node in the schema associated with the prior package
version.
5.2.1.3. Editorial changes
The following changes classify as editorial changes to a package
definition:
* Changing a 'included-package' list entry to select a package
version that is classified as an editorial change relative to the
prior package version.
* Changing a 'module' or 'import-only-module' list entry to select a
module revision that is classified as an editorial change relative
to the prior module revision.
* Any change to any metadata associated with a package definition.
5.2.2. YANG Semantic Versioning for packages
YANG Semantic Versioning [I-D.ietf-netmod-yang-semver] MAY be used as
an appropriate type of revision-label for the package version leaf.
If the format of the leaf matches the 'ysver:version' type specified
in ietf-yang-semver.yang, then the package version leaf MUST be
interpreted as a YANG semantic version number.
For YANG packages defined by the IETF, YANG semantic version numbers
MUST be used as the version scheme for YANG packages.
The rules for incrementing the YANG package version number are
equivalent to the semantic versioning rules used to version
individual YANG modules, defined in section 3.2 of
[I-D.ietf-netmod-yang-semver], but use the rules defined previously
Wilton, et al. Expires 24 April 2025 [Page 9]
Internet-Draft YANG Packages October 2024
in Section 5.2.1 to determine whether a change is classified as non-
backwards-compatible, backwards-compatible, or editorial. Where
available, the semantic version number of the referenced elements in
the package (included packages or modules) can be used to help
determine the scope of changes being made.
5.2.3. Guidelines for Package Versions During Package Development
During development of a new package, or while updating a previously
released package, special care should be taken with the selection of
the version associated with the package.
If YANG Semver is being used for the package version scheme, then the
guidelines in Section 5 of [RFC YANG SEMVER] MUST be followed for the
package version.
If a revision label scheme other than YANG Semver is being used for
the package version, then that revision label scheme SHOULD define
how the revision label is assigned during development.
5.3. Package conformance
YANG packages allows for conformance to be checked at a package level
rather than requiring a client to download all modules, revisions,
and deviations from the server to ensure that the datastore schema
used by the server is compatible with the client.
YANG package conformance is analogous to how YANG [RFC7950] requires
that servers either implement a module faithfully, or otherwise use
deviations to indicate areas of non-conformance.
For a top level package representing a datastore schema, servers MUST
implement the package definition faithfully, including all mandatory
features.
Package definitions MAY modify the schema for directly or
hierarchically included packages through the use of different module
revisions or module deviations.
5.3.1. Use of YANG semantic versioning
Using the YANG semantic versioning scheme for package version numbers
and module revision labels can help with conformance. In the general
case, clients should be able to determine the nature of changes
between two package versions by comparing the version number.
Wilton, et al. Expires 24 April 2025 [Page 10]
Internet-Draft YANG Packages October 2024
This usually means that a client does not have to be restricted to
working only with servers that advertise exactly the same version of
a package in YANG library. Instead, reasonable clients should be
able to interoperate with any server that supports a package version
that is backwards compatible to version that the client is designed
for, assuming that the client is designed to ignore operational
values for unknown data nodes.
For example, a client coded to support 'foo' package at version 1.0.0
should interoperate with a server implementing 'foo' package at
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.
This also has a relevance on servers that are capable of supporting
version selection because they need not support every version of a
YANG package to ensure good client compatibility. Choosing suitable
minor versions within each major version number should generally be
sufficient, particular if they can avoid non-backwards-compatible
patch level changes.
5.3.2. The relationship between packages and datastores
As defined by NMDA [RFC8342], each datastore has an associated
datastore schema. Sections 5.1 and 5.3 of NMDA defines further
constraints on the schema associated with datastores. These
constraints can be summarized thus:
* The schema for all conventional datastores is the same.
* The schema for non conventional configuration datastores (e.g.,
dynamic datastores) may completely differ (i.e. no overlap at all)
from the schema associated with the conventional configuration
datastores, or may partially or fully overlap with the schema of
the conventional configuration datastores. A dynamic datastore,
for example, may support different modules than conventional
datastores, or may support a subset or superset of modules,
features, or data nodes supported in the conventional
configuration datastores. Where a data node exists in multiple
datastore schema it has the same type, properties and semantics.
* The schema for the operational datastore is intended to be a
superset of all the configuration datastores (i.e. includes all
the schema nodes from the conventional configuration datastores),
but data nodes can be omitted if they cannot be accurately
reported. The operational datastore schema can include additional
modules containing only config false data nodes, but there is no
harm in including those modules in the configuration datastore
schema as well.
Wilton, et al. Expires 24 April 2025 [Page 11]
Internet-Draft YANG Packages October 2024
Given that YANG packages represent a schema, it follows that each
datastore schema can be represented using packages. In addition, the
schema for most datastores on a server are often closely related.
Given that there are many ways that a datastore schema could be
represented using packages, the following guidance provides a
consistent approach to help clients understand the relationship
between the different datastore schema supported by a device (e.g.,
which parts of the schema are common and which parts have
differences):
* Any datastores (e.g., conventional configuration datastores) that
have exactly the same datastore schema MUST use the same package
definitions. This is to avoid, for example, the creation of a
'running-cfg' package and a separate 'intended-cfg' package that
have identical schema.
* Common package definitions SHOULD be used for those parts of the
datastore schema that are common between datastores, when those
datastores do not share exactly the same datastore schema. E.g.,
if a substantial part of the schema is common between the
conventional, dynamic, and operational datastores then a single
common package can be used to describe the common parts, along
with other packages to describe the unique parts of each datastore
schema.
* YANG modules that do not contain any configuration data nodes
SHOULD be included in the package for configuration datastores if
that helps unify the package definitions.
* The packages for the operational datastore schema MUST include all
packages for all configuration datastores, along with any required
modules defining deviations to mark unsupported data nodes. The
deviations MAY be defined directly in the packages defining the
operational datastore schema, or in separate packages (which may
be packages attached to the datastore, or may be packages included
by other packages).
* The schema for a datastore MAY be represented using a single
package or as the union of a set of compatible packages, i.e.,
equivalently to a set of non-conflicting packages being included
together in an overarching package definition.
5.4. Schema referential completeness
A YANG package may represent a schema that is 'referentially
complete', or 'referentially incomplete', indicated in the package
definition by the 'complete' flag.
Wilton, et al. Expires 24 April 2025 [Page 12]
Internet-Draft YANG Packages October 2024
If all import statements in all YANG modules included in the package
(either directly, or through included packages) can be resolved to a
module revision defined with the YANG package definition, then the
package is classified as referentially complete. Conversely, if one
or more import statements cannot be resolved to a module specified as
part of the package definition, then the package is classified as
referentially incomplete.
A package that represents the exact contents of a datastore schema
MUST always be referentially complete.
Referentially incomplete packages can be used, along with locally
scoped packages, to represent an update to a device's datastore
schema as part of an optional software hot fix. E.g., the base
software is made available as a complete globally scoped package.
The hot fix is made available as an incomplete globally scoped
package. A device's datastore schema can define a local package that
implements the base software package updated with the hot fix
package.
Referentially incomplete packages could also be used to group sets of
logically related modules together, but without requiring a fixed
dependency on all imported 'types' modules (e.g., iana-if-
types.yang), instead leaving the choice of specific revisions of
'types' modules to be resolved when the package definition is used.
5.5. Package name scoping and uniqueness
YANG package names SHOULD be globally unique, since two different
package definitions with the same name, but different content, cannot
both be used together within the same package definition.
There are a couple of ways that this uniqueness can be achieved:
* For package definitions that define an public API, or that could
apply to multiple servers exposing the same management API, then
an organization prefix, and perhaps device family name, should be
included in the package name, i.e., following a similar naming
convention as for modules.
* For package definitions that are local to a particular server,
then the sysName of the device, a MAC address, or a UUID should be
used as a suffix to the package name to ensure uniqueness.
Wilton, et al. Expires 24 April 2025 [Page 13]
Internet-Draft YANG Packages October 2024
5.6. Submodules packages considerations
As defined in [RFC7950] and [I-D.ietf-netmod-yang-semver], YANG
conformance and versioning is specified in terms of particular
revisions of YANG modules rather than for individual submodules.
However, YANG package definitions also include the list of submodules
included by a module, primarily to provide a location of where the
submodule definition can be obtained from, allowing a schema to be
fully constructed from a YANG package instance data file definition.
5.7. Package tags
[I-D.ietf-netmod-module-tags] defines YANG module tags as a mechanism
to annotate a module definition with additional metadata. Tags MAY
also be associated to a package definition via the 'tags' leaf-list.
The tags use the same registry and definitions used by YANG module
tags.
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).
Wilton, et al. Expires 24 April 2025 [Page 14]
Internet-Draft YANG Packages October 2024
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 include the 'supported features' leaf-list, which allow
the 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 core elements of the YANG package structure that is used within
YANG package instance data files (ietf-yang-package-instance.yang)
and also on the server (ietf-yang-packages.yang).
The "ietf-yang-package-types" YANG module has the following
structure:
Wilton, et al. Expires 24 April 2025 [Page 15]
Internet-Draft YANG Packages October 2024
module: ietf-yang-package-types
grouping yang-pkg-identification-leafs:
+-- name pkg-name
+-- version pkg-version
grouping yang-pkg-instance:
+-- name pkg-name
+-- version pkg-version
+-- timestamp? yang:date-and-time
+-- organization? string
+-- contact? string
+-- description? string
+-- reference? string
+-- complete? boolean
+-- tag* tags:tag
+-- supported-feature* scoped-feature
+-- included-package* [name]
| +-- name pkg-name
| +-- version pkg-version
| +-- replaces-version* pkg-version
| +-- location* inet:uri
+-- module* [name]
| +-- name yang:yang-identifier
| +-- version version-or-rev-date
| +-- replaces-version* version-or-rev-date
| +-- location* inet:uri
| +-- submodule* [name]
| +-- name? yang:yang-identifier
| +-- version version-or-rev-date
| +-- location* inet:uri
+-- import-only-module* [name revision]
| +-- name? yang:yang-identifier
| +-- version version-or-rev-date
| +-- replaces-version* version-or-rev-date
| +-- location* inet:uri
| +-- submodule* [name]
| +-- name? yang:yang-identifier
| +-- version version-or-rev-date
| +-- location* inet:uri
+-- mounted-package* [mount-path]
+-- mount-path? string
+-- package
| +-- name pkg-name
| +-- version pkg-version
+-- location* inet:uri
Wilton, et al. Expires 24 April 2025 [Page 16]
Internet-Draft YANG Packages October 2024
6. Package Instance Data Files
YANG packages SHOULD be available offline from the server, defined as
YANG instance data files [I-D.ietf-netmod-yang-instance-file-format]
using the schema below to define the package data.
The following rules apply to the format of the YANG package instance
files:
1. The file SHOULD be encoded in JSON.
2. The name of the file SHOULD follow the format "<package-
name>@<version>.json".
3. The package name MUST be specified in both the instance-data-set
'name' and package 'name' leafs.
4. The 'description' field of the instance-data-set SHOULD be "YANG
package definition".
5. The 'timestamp', "organization', 'contact' fields are defined in
both the instance-data-set metadata and the YANG package
metadata. Package definitions SHOULD only define these fields as
part of the package definition. If any of these fields are
populated in the instance-data-set metadata then they MUST
contain the same value as the corresponding leaves in the package
definition.
6. The 'revision' list in the instance data file SHOULD NOT be used,
since versioning is handled by the package definition.
7. The instance data file for each version of a YANG package SHOULD
be made available at one of more locations accessible via URLs.
If one of the listed locations defines a definitive reference
implementation for the package definition then it MUST be listed
as the first entry in the list.
The "ietf-yang-package-instance" YANG module has the following
structure:
module: ietf-yang-package-instance
structure package:
// Uses the yang-package-instance grouping defined in
// ietf-yang-package-types.yang
+-- name pkg-name
+-- version pkg-version
... remainder of yang-package-instance grouping ...
Wilton, et al. Expires 24 April 2025 [Page 17]
Internet-Draft YANG Packages October 2024
7. Package Definitions on a Server
7.1. Package List
A top level 'packages' container holds the list of all versions of
all packages known to the server. Each list entry uses the common
package definition, but with the addition of package location that
cannot be contained within a offline package definition contained in
an instance data file.
The '/packages/package' list MAY include multiple versions of a
particular package. E.g. if the server is capable of allowing
clients to select which package versions should be used by the
server.
7.2. Tree diagram
The "ietf-yang-packages" YANG module has the following structure:
module: ietf-yang-packages
+--ro packages
+--ro package* [name version]
// Uses the yang-package-instance grouping defined in
// ietf-yang-package-types.yang, with location:
+--ro name pkg-name
+--ro version pkg-version
... remainder of yang-package-instance grouping ...
+--ro location* inet:uri
8. YANG Library Package Bindings
The YANG packages module also augments YANG library to allow a server
to optionally indicate that a datastore schema is defined by a
package, or a union of compatible packages. Since packages can
generally be made available offline in instance data files, it may be
sufficient for a client to only check that a compatible version of
the package is implemented by the server without fetching either the
package definition, or downloading and comparing the full list of
modules and enabled features.
If a server indicates that a datastore schema maps to a particular
package, then it MUST exactly match the schema defined by that
package, taking into account enabled features and any deviations.
If a server cannot faithfully implement a package then it can define
a new package to accurately report what it does implement. The new
package can include the original package as an included package, and
Wilton, et al. Expires 24 April 2025 [Page 18]
Internet-Draft YANG Packages October 2024
the new package can define additional modules containing deviations
to the modules in the original package, allowing the new package to
accurately describe the server's behavior. There is no specific
mechanism provided to indicate that a mandatory-feature in package
definition is not supported on a server, but deviations MAY be used
to disable functionality predicated by an if-feature statement.
The "ietf-yl-packages" YANG module has the following structure:
module: ietf-yl-packages
augment /yanglib:yang-library/yanglib:schema:
+--ro package* [name version]
+--ro name -> /pkgs:packages/package/name
+--ro version leafref
9. YANG packages as schema for YANG instance data document
YANG package definitions can be used as the content schema definition
for YANG instance data files. When using a package-based content
schema, the name and version of the package MUST be specified, a
package URL to the package definition MAY also be provided.
The "ietf-yang-inst-data-pkg" YANG module has the following
structure:
module: ietf-yang-inst-data-pkg
augment-structure /yid:instance-data-set/yid:content-schema/yid:content-schema-spec:
+--:(pkg-schema)
+-- pkg-schema
+-- name pkg-name
+-- version pkg-version
+-- location* inet:uri
10. YANG Modules
The YANG module definitions for the modules described in the previous
sections.
<CODE BEGINS>
file "ietf-yang-package-types#0.4.0-draft-ietf-netmod-yang-packages-04.yang"
module ietf-yang-package-types {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-package-types";
prefix "pkg-types";
import ietf-yang-revisions {
Wilton, et al. Expires 24 April 2025 [Page 19]
Internet-Draft YANG Packages October 2024
prefix rev;
reference "XXXX: Updated YANG Module Revision Handling";
}
import ietf-yang-semver {
prefix ys;
reference "XXXX: YANG Semantic Versioning";
}
import ietf-yang-types {
prefix yang;
rev:recommended-min-date 2019-07-21;
reference "RFC 6991bis: Common YANG Data Types.";
}
import ietf-inet-types {
prefix inet;
rev:recommended-min-date 2013-07-15;
reference "RFC 6991: Common YANG Data Types.";
}
import ietf-module-tags {
prefix tags;
// RFC Ed. Fix revision once revision date of
// ietf-module-tags.yang is known.
reference "RFC XXX: YANG Module Tags.";
}
organization
"IETF NETMOD (Network Modeling) Working Group";
contact
"WG Web: <http://tools.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org>
Author: Rob Wilton
<mailto:rwilton@cisco.com>";
description
"This module provides type and grouping definitions for YANG
packages.
Copyright (c) 2024 IETF Trust and the persons identified as
authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
Wilton, et al. Expires 24 April 2025 [Page 20]
Internet-Draft YANG Packages October 2024
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices.
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
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.";
// RFC Ed.: update the date below with the date of RFC publication
// and remove this note.
// RFC Ed.: replace XXXX with actual RFC number and remove this
// note.
revision 2024-10-14 {
ys:version 0.4.0-draft-ietf-netmod-yang-packages-05;
description
"Initial revision";
reference
"RFC XXXX: YANG Packages";
}
/*
* Typedefs
*/
typedef pkg-name {
type yang:yang-identifier;
description
"Package names are typed as YANG identifiers.";
}
typedef pkg-version {
type ys:version;
description
"Packages are versioning used YANG Semver version labels.";
}
typedef version-or-rev-date {
type union {
type rev:revision-date;
type ys:version;
}
description
Wilton, et al. Expires 24 April 2025 [Page 21]
Internet-Draft YANG Packages October 2024
"Identifies a module by YANG semantic version or revision date";
}
typedef scoped-feature {
type string {
pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*:[a-zA-Z_][a-zA-Z0-9\-_.]*';
}
description
"Represents a feature name scoped to a particular module,
identified as the '<module-name>:<feature-name>', where both
<module-name> and <feature-name> are YANG identifier strings,
as defiend by Section 12 or RFC 6020.";
reference
"RFC XXXX, YANG Packages.";
}
/*
* Groupings
*/
grouping yang-pkg-identification-leafs {
description
"Parameters for identifying a specific version of a YANG
package";
leaf name {
type pkg-name;
mandatory true;
description
"The YANG package name.";
}
leaf version {
type pkg-version;
mandatory true;
description
"Uniquely identies a particular version of a YANG package.
Follows the definition for revision labels defined in
draft-verdt-nemod-yang-module-versioning, section XXX";
}
}
grouping yang-pkg-instance {
description
"Specifies the data node for a full YANG package instance
represented either on a server or as a YANG instance data
document.";
Wilton, et al. Expires 24 April 2025 [Page 22]
Internet-Draft YANG Packages October 2024
uses yang-pkg-identification-leafs;
leaf timestamp {
type yang:date-and-time;
description
"An optional timestamp for when this package was created.
This does not need to be unique across all versions of a
package.";
}
leaf organization {
type string;
description "Organization responsible for this package";
}
leaf contact {
type string;
description
"Contact information for the person or organization to whom
queries concerning this package should be sent.";
}
leaf description {
type string;
description "Provides a description of the package";
}
leaf reference {
type string;
description "Allows for a reference for the package";
}
leaf complete {
type boolean;
default true;
description
"Indicates whether the schema defined by this package is
referentially complete. I.e. all module imports can be
resolved to a module explicitly defined in this package or
one of the included packages.";
}
leaf-list tag {
type tags:tag;
description
"Tags associated with a YANG package. Module tags defined in
XXX, ietf-netmod-module-tags can be used here but with the
modification that the tag applies to the entire package
Wilton, et al. Expires 24 April 2025 [Page 23]
Internet-Draft YANG Packages October 2024
rather than a specific module. See the IANA 'YANG Module
Tag Prefix' registry for reserved prefixes and the IANA
'YANG Module IETF Tag' registry for IETF standard tags.";
}
leaf-list supported-feature {
type scoped-feature;
description
"Lists features from any modules included in the package that
MUST be supported by any server implementing the package.
Features already specified in a 'supported-feature' list of
any included package MUST also be supported by server
implementations and do not need to be repeated in this list.
All other features defined in modules included in the
package are OPTIONAL to implement.
Features are identified using <module-name>:<feature-name>.";
}
list included-package {
key "name";
description
"An entry in this list represents a package that is included
as part of the package definition, or an indirectly included
package that is changed in a non backwards compatible way.
It can be used to resolve inclusion of conflicting package
versions by explicitly specifying which package version is
used.
If included packages implement different revisions
of the same module, then an explicit entry in the
module list MUST be provided to select the specific module
revision 'implemented' by this package definition.
For import-only modules, the 'replaces-revision' leaf-list
can be used to select the specific module revisions used by
this package.";
reference
"XXX";
uses yang-pkg-identification-leafs;
leaf-list replaces-version {
type pkg-version;
description
Wilton, et al. Expires 24 April 2025 [Page 24]
Internet-Draft YANG Packages October 2024
"Gives the version of an included package version that
is replaced by this included package version.";
}
leaf-list location {
type inet:uri;
description
"Contains a URL that represents where an instance data file
for this YANG package can be found.
This leaf will only be present if there is a URL available
for retrieval of the schema for this entry.
If multiple locations are provided, then the first
location in the leaf-list MUST be the definitive location
that uniquely identifies this package";
}
}
list module {
key "name";
description
"An entry in this list represents a module that must be
implemented by a server implementing this package, as per
RFC 7950 section 5.6.5, with a particular set of supported
features and deviations.
A entry in this list overrides any module revision
'implemented' by an included package. Any replaced module
revision SHOULD also be listed in the 'replaces-revision'
list.";
reference
"RFC 7950: The YANG 1.1 Data Modeling Language.";
leaf name {
type yang:yang-identifier;
mandatory true;
description
"The YANG module name.";
}
leaf version {
type version-or-rev-date;
mandatory true;
description
"Identifies the module version. If available, the YANG
Wilton, et al. Expires 24 April 2025 [Page 25]
Internet-Draft YANG Packages October 2024
Semantic Version SHOULD be used, otherwise the YANG module
revision date is used.";
}
leaf-list replaces-version {
type version-or-rev-date;
description
"Gives the version of an module (implemented or
import-only) defined in an included package that is
replaced by this implemented module version.";
}
leaf-list location {
type inet:uri;
description
"Contains a URL that represents the YANG schema resource
for this module.
This leaf will only be present if there is a URL available
for retrieval of the schema for this entry.";
}
list submodule {
key "name";
description
"Each entry represents one submodule within the
parent module.";
leaf name {
type yang:yang-identifier;
description
"The YANG submodule name.";
}
leaf version {
type version-or-rev-date;
mandatory true;
description
"The YANG submodule revision date or YANG Semantic version.
If the parent module include statement for this submodule
includes a revision date then it MUST match the revision
date specified here or it MUST match the revision-date
associated with the version specified here.";
}
leaf-list location {
type inet:uri;
Wilton, et al. Expires 24 April 2025 [Page 26]
Internet-Draft YANG Packages October 2024
description
"Contains a URL that represents the YANG schema resource
for this submodule.
This leaf will only be present if there is a URL
available for retrieval of the schema for this entry.";
}
}
}
list import-only-module {
key "name version";
description
"An entry in this list indicates that the server imports
reusable definitions from the specified revision of the
module, but does not implement any protocol accessible
objects from this revision.
Multiple entries for the same module name MAY exist. This
can occur if multiple modules import the same module, but
specify different revision-dates in the import statements.";
leaf name {
type yang:yang-identifier;
description
"The YANG module name.";
}
leaf version {
type version-or-rev-date;
mandatory true;
description
"Identifies the module version. If available, the YANG
Semantic Version SHOULD be used, otherwise the YANG module
revision date is used.";
}
leaf-list replaces-version {
type version-or-rev-date;
description
"Gives the version of an import-only-module defined in an
included package that is replaced by this
import-only-module version.";
}
leaf-list location {
Wilton, et al. Expires 24 April 2025 [Page 27]
Internet-Draft YANG Packages October 2024
type inet:uri;
description
"Contains a URL that represents the YANG schema resource
for this module.
This leaf will only be present if there is a URL available
for retrieval of the schema for this entry.";
}
list submodule {
key "name";
description
"Each entry represents one submodule within the
parent module.";
leaf name {
type yang:yang-identifier;
description
"The YANG submodule name.";
}
leaf version {
type version-or-rev-date;
mandatory true;
description
"The YANG submodule revision date or YANG Semantic version.
If the parent module include statement for this submodule
includes a revision date then it MUST match the revision
date specified here or it MUST match the revision-date
associated with the version specified here.";
}
leaf-list location {
type inet:uri;
description
"Contains a URL that represents the YANG schema resource
for this submodule.
This leaf will only be present if there is a URL
available for retrieval of the schema for this entry.";
}
}
}
list mounted-package {
key "mount-path";
description
Wilton, et al. Expires 24 April 2025 [Page 28]
Internet-Draft YANG Packages October 2024
"An entry in this list represents a package that will be
found mounted at the specified mount path.
The total list of mounted packages is represented by
combining the mounted packages from all included packages, but with
any duplicate mount paths (with or without keys specified) specified
here replacing all equivalent mount paths from included packages.";
leaf "mount-path" {
type string;
description
"This path identifies a mount point in the schema.
This leaf is encoded as a JSON style encoded
instance-identifier (regardless of whether the format
used to encode the YANG instance data), as specified in
RFC 7951, section 6.11, except that keys are optional.
For optional keys, the name and value of the key is
excluded from the key list.
Mount paths MUST only be used for schema mount points
defined in the package schema.
For example, if an example module 'ex-module' defines a
mount point under list entry'/modules/module/' then a
mount path of
- '/modules/module[name=foo]' would indicate the mounted
package schema for only the 'foo' entry in the module
list. Each entry in the list could have a different
mounted schema specified.
- '/modules/module[]' would indicate that the same
mounted package schema is available for all list
entries in the module list.";
}
container package {
description
"The package that will be mounted at the specified mount
path";
uses yang-pkg-identification-leafs;
}
leaf-list location {
type inet:uri;
description
Wilton, et al. Expires 24 April 2025 [Page 29]
Internet-Draft YANG Packages October 2024
"Contains a URL that represents where an instance data file
for this YANG package can be found.
This leaf will only be present if there is a URL available
for retrieval of the schema for this entry.
If multiple locations are provided, then the first
location in the leaf-list MUST be the definitive location.
that uniquely identifies this package";
}
}
}
}
<CODE ENDS>
<CODE BEGINS>
file "ietf-yang-package-instance#0.4.0-draft-ietf-netmod-yang-packages-04.yang"
module ietf-yang-package-instance {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-package-instance";
prefix pkg-inst;
import ietf-yang-semver {
prefix ys;
reference "XXXX: YANG Semantic Versioning";
}
import ietf-yang-package-types {
prefix pkg-types;
ys:recommended-min-version 0.4.0;
reference "RFC XXX: this RFC.";
}
import ietf-yang-structure-ext {
prefix sx;
reference "RFC 8791: YANG Data Structure Extensions.";
}
organization
"IETF NETMOD (Network Modeling) Working Group";
contact
"WG Web: <http://tools.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org>
Author: Rob Wilton
<mailto:rwilton@cisco.com>";
Wilton, et al. Expires 24 April 2025 [Page 30]
Internet-Draft YANG Packages October 2024
description
"This module provides a definition of a YANG package, which is
used as the content schema for an YANG instance data document specifying
a YANG package.
Copyright (c) 2024 IETF Trust and the persons identified as
authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices.
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
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.";
// RFC Ed.: update the date below with the date of RFC publication
// and remove this note.
// RFC Ed.: replace XXXX with actual RFC number and remove this
// note.
revision 2024-10-14 {
ys:version 0.4.0-draft-ietf-netmod-yang-packages-05;
description
"Initial revision";
reference
"RFC XXXX: YANG Packages";
}
/*
* Top-level structure
*/
sx:structure package {
description
"Defines the YANG package structure for use in a YANG instance
data document.";
uses pkg-types:yang-pkg-instance;
Wilton, et al. Expires 24 April 2025 [Page 31]
Internet-Draft YANG Packages October 2024
}
}
<CODE ENDS>
<CODE BEGINS>
file "ietf-yang-package#0.4.0-draft-ietf-netmod-yang-packages-04.yang"
module ietf-yang-packages {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-packages";
prefix pkgs;
import ietf-yang-revisions {
prefix rev;
reference "XXXX: Updated YANG Module Revision Handling";
}
import ietf-yang-semver {
prefix ys;
reference "XXXX: YANG Semantic Versioning";
}
import ietf-yang-package-types {
prefix pkg-types;
ys:recommended-min-version 0.4.0;
reference "RFC XXX: this RFC.";
}
import ietf-inet-types {
prefix inet;
rev:recommended-min-date 2013-07-15;
reference "RFC 6991: Common YANG Data Types.";
}
organization
"IETF NETMOD (Network Modeling) Working Group";
contact
"WG Web: <http://tools.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org>
Author: Rob Wilton
<mailto:rwilton@cisco.com>";
description
"This module defines YANG packages on a server implementation.
Copyright (c) 2024 IETF Trust and the persons identified as
Wilton, et al. Expires 24 April 2025 [Page 32]
Internet-Draft YANG Packages October 2024
authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices.
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
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.";
// RFC Ed.: update the date below with the date of RFC publication
// and remove this note.
// RFC Ed.: replace XXXX with actual RFC number and remove this
// note.
revision 2024-10-14 {
ys:version 0.4.0-draft-ietf-netmod-yang-packages-05;
description
"Initial revision";
reference
"RFC XXXX: YANG Packages";
}
/*
* Groupings
*/
grouping yang-pkg-ref {
description
"Defines the leaves used to reference a single YANG package";
leaf name {
type leafref {
path '/pkgs:packages/pkgs:package/pkgs:name';
}
description
"The name of the references package.";
}
Wilton, et al. Expires 24 April 2025 [Page 33]
Internet-Draft YANG Packages October 2024
leaf version {
type leafref {
path '/pkgs:packages'
+ '/pkgs:package[pkgs:name = current()/../name]'
+ '/pkgs:version';
}
description
"The version of the referenced package.";
}
}
grouping yang-ds-pkg-ref {
description
"Defines the list used to reference a set of YANG packages that
collectively represent a datastore schema.";
list package {
key "name version";
description
"Identifies the YANG packages that collectively defines the
schema for the associated datastore.
The datastore schema is defined as the union of all
referenced packages, that MUST represent a referentially
complete schema.
All of the referenced packages must be compatible with no
conflicting module versions or dependencies.";
uses yang-pkg-ref;
}
}
/*
* Top level data nodes.
*/
container packages {
config false;
description "All YANG package definitions";
list package {
key "name version";
Wilton, et al. Expires 24 April 2025 [Page 34]
Internet-Draft YANG Packages October 2024
description
"YANG package instance";
uses pkg-types:yang-pkg-instance;
leaf-list location {
type inet:uri;
description
"Contains a URL that represents where an instance data file
for this YANG package can be found.
This leaf will only be present if there is a URL available
for retrieval of the schema for this entry.
If multiple locations are provided, then the first
location in the leaf-list MUST be the definitive location
that uniquely identifies this package";
}
}
}
}
<CODE ENDS>
<CODE BEGINS>
file "ietf-yl-package#0.4.0-draft-ietf-netmod-yang-packages-04.yang"
module ietf-yl-packages {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-yl-packages";
prefix yl-pkgs;
import ietf-yang-revisions {
prefix rev;
reference "XXXX: Updated YANG Module Revision Handling";
}
import ietf-yang-semver {
prefix ys;
reference "XXXX: YANG Semantic Versioning";
}
import ietf-yang-packages {
prefix pkgs;
ys:recommended-min-version 0.4.0;
reference "RFC XXX: YANG Packages.";
}
import ietf-yang-library {
Wilton, et al. Expires 24 April 2025 [Page 35]
Internet-Draft YANG Packages October 2024
prefix yanglib;
rev:recommended-min-date 2019-01-04;
reference "RFC 8525: YANG Library";
}
organization
"IETF NETMOD (Network Modeling) Working Group";
contact
"WG Web: <http://tools.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org>
Author: Rob Wilton
<mailto:rwilton@cisco.com>";
description
"This module provides defined augmentations to YANG library to
allow a server to report YANG package information.
Copyright (c) 2024 IETF Trust and the persons identified as
authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices.
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
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.";
// RFC Ed.: update the date below with the date of RFC publication
// and remove this note.
// RFC Ed.: replace XXXX with actual RFC number and remove this
// note.
revision 2024-10-14 {
ys:version 0.4.0-draft-ietf-netmod-yang-packages-05;
description
"Initial revision";
Wilton, et al. Expires 24 April 2025 [Page 36]
Internet-Draft YANG Packages October 2024
reference
"RFC XXXX: YANG Packages";
}
/*
* Augmentations
*/
augment "/yanglib:yang-library/yanglib:schema" {
description
"Allow datastore schema to be related to a set of YANG
packages";
uses pkgs:yang-ds-pkg-ref;
}
}
<CODE ENDS>
<CODE BEGINS>
file "ietf-yang-inst-data-pkg#0.4.0-draft-ietf-netmod-yang-packages-04.yang"
module ietf-yang-inst-data-pkg {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-inst-data-pkg";
prefix yid-pkg;
import ietf-yang-semver {
prefix ys;
reference "XXXX: YANG Semantic Versioning";
}
import ietf-yang-package-types {
prefix pkg-types;
ys:recommended-min-version 0.4.0;
reference "RFC XXX: this RFC.";
}
import ietf-yang-structure-ext {
prefix sx;
reference "RFC 8791: YANG Data Structure Extensions.";
}
import ietf-yang-instance-data {
prefix yid;
reference "RFC XXX: YANG Instance Data File Format.";
}
organization
Wilton, et al. Expires 24 April 2025 [Page 37]
Internet-Draft YANG Packages October 2024
"IETF NETMOD (Network Modeling) Working Group";
contact
"WG Web: <http://tools.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org>
Author: Rob Wilton
<mailto:rwilton@cisco.com>";
description
"The module augments ietf-yang-instance-data to allow package
definitions to be used to define content schema in YANG instance data
documents.
Copyright (c) 2024 IETF Trust and the persons identified as
authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices.
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
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.";
// RFC Ed.: update the date below with the date of RFC publication
// and remove this note.
// RFC Ed.: replace XXXX with actual RFC number and remove this
// note.
revision 2024-10-14 {
ys:version 0.4.0-draft-ietf-netmod-yang-packages-05;
description
"Initial revision";
reference
"RFC XXXX: YANG Packages";
}
/*
* Augmentations
*/
Wilton, et al. Expires 24 April 2025 [Page 38]
Internet-Draft YANG Packages October 2024
sx:augment-structure
"/yid:instance-data-set/yid:content-schema/yid:content-schema-spec" {
description
"Add package reference to instance data set schema
specification";
case pkg-schema {
container pkg-schema {
uses pkg-types:yang-pkg-identification-leafs;
leaf-list location {
type inet:uri;
description
"Contains a URL that represents where an instance data
file for this YANG package can be found.
This leaf will only be present if there is a URL
available for retrieval of the schema for this entry.
If multiple locations are provided, then the first
location in the leaf-list MUST be the definitive
location that uniquely identifies this package";
}
}
}
}
}
<CODE ENDS>
11. Security Considerations
The YANG modules specified in this document defines a schema for data
that is accessed by network management protocols such as NETCONF
[RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer is the
secure transport layer, and the mandatory-to-implement secure
transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer
is HTTPS, and the mandatory-to-implement secure transport is TLS
[RFC5246].
The NETCONF access control model [RFC6536] provides the means to
restrict access for particular NETCONF or RESTCONF users to a
preconfigured subset of all available NETCONF or RESTCONF protocol
operations and content.
Similarly to YANG library [I-D.ietf-netconf-rfc7895bis], some of the
readable data nodes in these YANG modules may be considered sensitive
or vulnerable in some network environments. It is thus important to
control read access (e.g., via get, get-config, or notification) to
these data nodes.
Wilton, et al. Expires 24 April 2025 [Page 39]
Internet-Draft YANG Packages October 2024
One additional key different to YANG library, is that the 'ietf-yang-
package' YANG module defines a schema to allow YANG packages to be
defined in YANG instance data files, that are outside the security
controls of the network management protocols. Hence, it is important
to also consider controlling access to these package instance data
files to restrict access to sensitive information.
As per the YANG library security considerations, the module, revision
information in YANG packages may help an attacker identify the server
capabilities and server implementations with 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 vulnerabilities may be
specific to particular modules, module revisions, module features, or
even module deviations. For example, if a particular operation on a
particular data node is known to cause a server to crash or
significantly degrade device performance, then the YANG packages
information will help an attacker identify server implementations
with such a defect, in order to launch a denial-of-service attack on
the device.
12. IANA Considerations
It is expected that a central registry of standard YANG package
definitions is required to support this solution.
It is unclear whether an IANA registry is also required to manage
specific package versions. It is highly desirable to have a specific
canonical location, under IETF control, where the definitive YANG
package versions can be obtained from.
This document requests IANA to registers a URI in the "IETF XML
Registry" [RFC3688]. Following the format in RFC 3688, the following
registrations are requested.
URI: urn:ietf:params:xml:ns:yang:ietf-yang-package-types.yang
Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace.
URI: urn:ietf:params:xml:ns:yang:ietf-yang-package-instance.yang
Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace.
URI: urn:ietf:params:xml:ns:yang:ietf-yang-packages.yang
Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace.
URI: urn:ietf:params:xml:ns:yang:ietf-yl-packages.yang
Registrant Contact: The IESG.
Wilton, et al. Expires 24 April 2025 [Page 40]
Internet-Draft YANG Packages October 2024
XML: N/A, the requested URI is an XML namespace.
URI: urn:ietf:params:xml:ns:yang:ietf-yang-inst-data-pkg.yang
Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace.
This document requests that the following YANG modules are added in
the "YANG Module Names" registry [RFC6020]:
Name: ietf-yang-package-types.yang
Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-package-
types.yang
Prefix: pkg-types
Reference: RFC XXXX
Name: ietf-yang-package-instance.yang
Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-package-
instance.yang
Prefix: pkg-inst
Reference: RFC XXXX
Name: ietf-yang-packages.yang
Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-packages.yang
Prefix: pkgs
Reference: RFC XXXX
Name: ietf-yl-packages.yang
Namespace: urn:ietf:params:xml:ns:yang:ietf-yl-packages.yang
Prefix: yl-pkgs
Reference: RFC XXXX
Name: ietf-yang-inst-data-pkg.yang
Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-inst-data-
pkg.yang
Prefix: yid-pkg
Reference: RFC XXXX
13. Open Questions/Issues
All issues, along with the draft text, are currently being tracked at
https://github.com/rgwilton/YANG-Packages-Draft/issues/
14. Acknowledgements
Feedback helping shape this document has kindly been provided by Andy
Bierman, James Cumming, Mahesh Jethanandani, Balazs Lengyel, Ladislav
Lhotka,and Jan Lindblad.
Wilton, et al. Expires 24 April 2025 [Page 41]
Internet-Draft YANG Packages October 2024
15. References
15.1. Normative References
[I-D.ietf-netconf-rfc7895bis]
Bierman, A., Björklund, M., Schönwälder, J., Watsen, K.,
and R. Wilton, "YANG Library", Work in Progress, Internet-
Draft, draft-ietf-netconf-rfc7895bis-07, 17 October 2018,
<https://datatracker.ietf.org/doc/html/draft-ietf-netconf-
rfc7895bis-07>.
[I-D.ietf-netmod-module-tags]
Hopps, C., Berger, L., and D. Bogdanović, "YANG Module
Tags", Work in Progress, Internet-Draft, draft-ietf-
netmod-module-tags-10, 29 February 2020,
<https://datatracker.ietf.org/doc/html/draft-ietf-netmod-
module-tags-10>.
[I-D.ietf-netmod-yang-data-ext]
Bierman, A., Björklund, M., and K. Watsen, "YANG Data
Structure Extensions", Work in Progress, Internet-Draft,
draft-ietf-netmod-yang-data-ext-05, 9 December 2019,
<https://datatracker.ietf.org/doc/html/draft-ietf-netmod-
yang-data-ext-05>.
[I-D.ietf-netmod-yang-instance-file-format]
Lengyel, B. and B. Claise, "A File Format for YANG
Instance Data", Work in Progress, Internet-Draft, draft-
ietf-netmod-yang-instance-file-format-21, 8 October 2021,
<https://datatracker.ietf.org/doc/html/draft-ietf-netmod-
yang-instance-file-format-21>.
[I-D.ietf-netmod-yang-module-versioning]
Wilton, R., Rahman, R., Lengyel, B., Clarke, J., and J.
Sterne, "Updated YANG Module Revision Handling", Work in
Progress, Internet-Draft, draft-ietf-netmod-yang-module-
versioning-12, 24 June 2024,
<https://datatracker.ietf.org/doc/html/draft-ietf-netmod-
yang-module-versioning-12>.
[I-D.ietf-netmod-yang-semver]
Clarke, J., Wilton, R., Rahman, R., Lengyel, B., Sterne,
J., and B. Claise, "YANG Semantic Versioning", Work in
Progress, Internet-Draft, draft-ietf-netmod-yang-semver-
17, 2 July 2024, <https://datatracker.ietf.org/doc/html/
draft-ietf-netmod-yang-semver-17>.
Wilton, et al. Expires 24 April 2025 [Page 42]
Internet-Draft YANG Packages October 2024
[I-D.ietf-netmod-yang-solutions]
Wilton, R., "YANG Versioning Solution Overview", Work in
Progress, Internet-Draft, draft-ietf-netmod-yang-
solutions-01, 2 November 2020,
<https://datatracker.ietf.org/doc/html/draft-ietf-netmod-
yang-solutions-01>.
[I-D.ietf-netmod-yang-ver-selection]
Wilton, R., Rahman, R., Clarke, J., Sterne, J., and B. Wu,
"YANG Schema Selection", Work in Progress, Internet-Draft,
draft-ietf-netmod-yang-ver-selection-00, 17 March 2020,
<https://datatracker.ietf.org/doc/html/draft-ietf-netmod-
yang-ver-selection-00>.
[I-D.ietf-netmod-yang-versioning-reqs]
Clarke, J., "YANG Module Versioning Requirements", Work in
Progress, Internet-Draft, draft-ietf-netmod-yang-
versioning-reqs-10, 8 July 2024,
<https://datatracker.ietf.org/doc/html/draft-ietf-netmod-
yang-versioning-reqs-10>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
DOI 10.17487/RFC3688, January 2004,
<https://www.rfc-editor.org/info/rfc3688>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246,
DOI 10.17487/RFC5246, August 2008,
<https://www.rfc-editor.org/info/rfc5246>.
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
the Network Configuration Protocol (NETCONF)", RFC 6020,
DOI 10.17487/RFC6020, October 2010,
<https://www.rfc-editor.org/info/rfc6020>.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
and A. Bierman, Ed., "Network Configuration Protocol
(NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
<https://www.rfc-editor.org/info/rfc6241>.
[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
<https://www.rfc-editor.org/info/rfc6242>.
Wilton, et al. Expires 24 April 2025 [Page 43]
Internet-Draft YANG Packages October 2024
[RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration
Protocol (NETCONF) Access Control Model", RFC 6536,
DOI 10.17487/RFC6536, March 2012,
<https://www.rfc-editor.org/info/rfc6536>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016,
<https://www.rfc-editor.org/info/rfc7950>.
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
<https://www.rfc-editor.org/info/rfc8040>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
and R. Wilton, "Network Management Datastore Architecture
(NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
<https://www.rfc-editor.org/info/rfc8342>.
[RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K.,
and R. Wilton, "YANG Library", RFC 8525,
DOI 10.17487/RFC8525, March 2019,
<https://www.rfc-editor.org/info/rfc8525>.
[RFC8528] Bjorklund, M. and L. Lhotka, "YANG Schema Mount",
RFC 8528, DOI 10.17487/RFC8528, March 2019,
<https://www.rfc-editor.org/info/rfc8528>.
[RFC8791] Bierman, A., Björklund, M., and K. Watsen, "YANG Data
Structure Extensions", RFC 8791, DOI 10.17487/RFC8791,
June 2020, <https://www.rfc-editor.org/info/rfc8791>.
15.2. Informative References
[I-D.bierman-netmod-yang-package]
Bierman, A., "The YANG Package Statement", Work in
Progress, Internet-Draft, draft-bierman-netmod-yang-
package-00, 6 July 2015,
<https://datatracker.ietf.org/doc/html/draft-bierman-
netmod-yang-package-00>.
[I-D.ietf-netmod-artwork-folding]
Watsen, K., Auerswald, E., Farrel, A., and Q. Wu,
"Handling Long Lines in Content of Internet-Drafts and
RFCs", Work in Progress, Internet-Draft, draft-ietf-
Wilton, et al. Expires 24 April 2025 [Page 44]
Internet-Draft YANG Packages October 2024
netmod-artwork-folding-12, 20 January 2020,
<https://datatracker.ietf.org/doc/html/draft-ietf-netmod-
artwork-folding-12>.
[openconfigsemver]
"Semantic Versioning for OpenConfig Models",
<http://www.openconfig.net/docs/semver/>.
[RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module
Classification", RFC 8199, DOI 10.17487/RFC8199, July
2017, <https://www.rfc-editor.org/info/rfc8199>.
Appendix A. Examples
This section provides various examples of YANG packages, and as such
this text is non-normative. The purpose of the examples is to only
illustrate the file format of YANG packages, and how package
dependencies work. It does not imply that such packages will be
defined by IETF, or which modules would be included in those packages
even if they were defined. For brevity, the examples exclude
namespace declarations, and use a shortened URL of "tiny.cc/ietf-
yang" as a replacement for
"https://raw.githubusercontent.com/YangModels/yang/master/standard/
ietf/RFC".
A.1. Example IETF Network Device YANG package
This section provides an instance data file example of an IETF
Network Device YANG package formatted in JSON.
This example package is intended to represent the standard set of
YANG modules, with import dependencies, to implement a basic network
device without any dynamic routing or layer 2 services. E.g., it
includes functionality such as system information, interface and
basic IP configuration.
As for all YANG packages, all import dependencies are fully resolved.
Because this example uses YANG modules that have been standardized
before YANG semantic versioning, the modules are referenced by
revision date rather than revision number.
<CODE BEGINS> file "example-ietf-network-device-pkg.json"
========= NOTE: '\' line wrapping per BCP XX (RFC XXXX) ===========
{
"ietf-yang-instance-data:instance-data-set": {
"name": "example-ietf-network-device-pkg",
"content-schema": {
Wilton, et al. Expires 24 April 2025 [Page 45]
Internet-Draft YANG Packages October 2024
"pkg-schema": {
"name": "ietf-yang-package-defn-pkg",
"version": "0.1.0"
}
},
"description": "YANG package definition",
"content-data": {
"ietf-yang-package-instance:yang-package": {
"name": "example-ietf-network-device-pkg",
"version": "1.1.2",
"timestamp": "2018-12-13T17:00:00Z",
"organization": "IETF NETMOD Working Group",
"contact" : "WG Web: <http://tools.ietf.org/wg/netmod/>, \
WG List: <mailto:netmod@ietf.org>",
"description": "Example IETF network device YANG package.\
\
This package defines a small sample set of \
YANG modules that could represent the basic set of \
modules that a standard network device might be expected \
to support.",
"reference": "XXX, draft-rwilton-netmod-yang-packages",
"location": [ "file://example.org/yang/packages/\
ietf-network-device@v1.1.2.json" ],
"module": [
{
"name": "iana-crypt-hash",
"revision": "2014-08-06",
"location": [ "https://tiny.cc/ietf-yang/\
iana-crypt-hash%402014-08-06.yang" ],
},
{
"name": "ietf-system",
"revision": "2014-08-06",
"location": [ "https://tiny.cc/ietf-yang/\
ietf-system%402014-08-06.yang" ],
},
{
"name": "ietf-interfaces",
"revision": "2018-02-20",
"location": [ "https://tiny.cc/ietf-yang/\
ietf-interfaces%402018-02-20.yang" ],
},
{
"name": "ietf-netconf-acm",
"revision": "2018-02-14",
"location": [ "https://tiny.cc/ietf-yang/\
ietf-netconf-acm%402018-02-14.yang" ],
},
Wilton, et al. Expires 24 April 2025 [Page 46]
Internet-Draft YANG Packages October 2024
{
"name": "ietf-key-chain",
"revision": "2017-06-15",
"location": [ "https://tiny.cc/ietf-yang/\
ietf-key-chain@2017-06-15.yang" ],
},
{
"name": "ietf-ip",
"revision": "2018-02-22",
"location": [ "https://tiny.cc/ietf-yang/\
ietf-ip%402018-02-22.yang" ],
}
],
"import-only-module": [
{
"name": "ietf-yang-types",
"revision": "2013-07-15",
"location": [ "https://tiny.cc/ietf-yang/\
ietf-yang-types%402013-07-15.yang" ],
},
{
"name": "ietf-inet-types",
"revision": "2013-07-15",
"location": [ "https://tiny.cc/ietf-yang/\
ietf-inet-types%402013-07-15.yang" ],
}
]
}
}
}
}
<CODE ENDS>
A.2. Example IETF Basic Routing YANG package
This section provides an instance data file example of a basic IETF
Routing YANG package formatted in JSON.
This example package is intended to represent the standard set of
YANG modules, with import dependencies, that builds upon the example-
ietf-network-device YANG package to add support for basic dynamic
routing and ACLs.
Wilton, et al. Expires 24 April 2025 [Page 47]
Internet-Draft YANG Packages October 2024
As for all YANG packages, all import dependencies are fully resolved.
Because this example uses YANG modules that have been standardized
before YANG semantic versioning, they modules are referenced by
revision date rather than revision number. Locations have been
excluded where they are not currently known, e.g., for YANG modules
defined in IETF drafts. In a normal YANG package, locations would be
expected to be provided for all YANG modules.
<CODE BEGINS> file "example-ietf-routing-pkg.json"
========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) ===========
{
"ietf-yang-instance-data:instance-data-set": {
"name": "example-ietf-routing-pkg",
"content-schema": {
"pkg-schema": {
"name": "ietf-yang-package-defn-pkg",
"version": "0.1.0"
}
},
"description": "YANG package definition",
"content-data": {
"ietf-yang-package-instance:yang-package": {
"name": "example-ietf-routing",
"version": "1.3.1",
"timestamp": "2018-12-13T17:00:00Z",
"description": "This package defines a small sample set of \
IETF routing YANG modules that could represent the set of \
IETF routing functionality that a basic IP network device \
might be expected to support.",
"reference": "XXX, draft-rwilton-netmod-yang-packages",
"imported-packages": [
{
"name": "ietf-network-device",
"version": "1.1.2",
"location": [ "http://example.org/yang/packages/\
ietf-network-device@v1.1.2.json" ],
}
],
"module": [
{
"name": "ietf-routing",
"revision": "2018-03-13",
"location": [ "https://tiny.cc/ietf-yang/\
ietf-routing@2018-03-13.yang" ],
},
{
"name": "ietf-ipv4-unicast-routing",
Wilton, et al. Expires 24 April 2025 [Page 48]
Internet-Draft YANG Packages October 2024
"revision": "2018-03-13",
"location": [ "https://tiny.cc/ietf-yang/\
ietf-ipv4-unicast-routing@2018-03-13.yang" ],
},
{
"name": "ietf-ipv6-unicast-routing",
"revision": "2018-03-13",
"location": [ "https://tiny.cc/ietf-yang/\
ietf-ipv6-unicast-routing@2018-03-13.yang" ],
},
{
"name": "ietf-isis",
"revision": "2018-12-11",
"location": [ "https://tiny.cc/ietf-yang/\
" ],
},
{
"name": "ietf-interfaces-common",
"revision": "2018-07-02",
"location": [ "https://tiny.cc/ietf-yang/\
" ],
},
{
"name": "ietf-if-l3-vlan",
"revision": "2017-10-30",
"location": [ "https://tiny.cc/ietf-yang/\
" ],
},
{
"name": "ietf-routing-policy",
"revision": "2018-10-19",
"location": [ "https://tiny.cc/ietf-yang/\
" ],
},
{
"name": "ietf-bgp",
"revision": "2018-05-09",
"location": [ "https://tiny.cc/ietf-yang/\
" ],
},
{
"name": "ietf-access-control-list",
"revision": "2018-11-06",
"location": [ "https://tiny.cc/ietf-yang/\
" ],
}
],
"import-only-module": [
Wilton, et al. Expires 24 April 2025 [Page 49]
Internet-Draft YANG Packages October 2024
{
"name": "ietf-routing-types",
"revision": "2017-12-04",
"location": [ "https://tiny.cc/ietf-yang/\
ietf-routing-types@2017-12-04.yang" ],
},
{
"name": "iana-routing-types",
"revision": "2017-12-04",
"location": [ "https://tiny.cc/ietf-yang/\
iana-routing-types@2017-12-04.yang" ],
},
{
"name": "ietf-bgp-types",
"revision": "2018-05-09",
"location": [ "https://tiny.cc/ietf-yang/\
" ],
},
{
"name": "ietf-packet-fields",
"revision": "2018-11-06",
"location": [ "https://tiny.cc/ietf-yang/\
" ],
},
{
"name": "ietf-ethertypes",
"revision": "2018-11-06",
"location": [ "https://tiny.cc/ietf-yang/\
" ],
}
]
}
}
}
}
<CODE ENDS>
A.3. Package import conflict resolution example
This section provides an example of how a package can resolve
conflicting module revisions from imported packages.
Wilton, et al. Expires 24 April 2025 [Page 50]
Internet-Draft YANG Packages October 2024
In this example, YANG package 'example-3-pkg' imports both 'example-
import-1' and 'example-import-2' packages. However, the two imported
packages implement different revisions of 'example-module-A' so the
'example-3-pkg' package selects version '1.2.3' to resolve the
conflict. Similarly, for import-only modules, the 'example-3-pkg'
package does not require both revisions of example-types-module-C to
be imported, so it indicates that it only imports revision
'2018-11-26' and not '2018-01-01'.
{
"ietf-yang-instance-data:instance-data-set": {
"name": "example-import-1-pkg",
"content-schema": {
"pkg-schema": {
"name": "ietf-yang-package-defn-pkg",
"version": "0.1.0"
}
},
"description": "First imported example package",
"content-data": {
"ietf-yang-package-instance:yang-package": {
"name": "example-import-1",
"version": "1.0.0",
"reference": "XXX, draft-rwilton-netmod-yang-packages",
"revision-date": "2018-01-01",
"module": [
{
"name": "example-module-A",
"revision": "1.0.0"
},
{
"name": "example-module-B",
"revision": "1.0.0"
}
],
"import-only-module": [
{
"name": "example-types-module-C",
"revision": "2018-01-01"
},
{
"name": "example-types-module-D",
"revision": "2018-01-01"
}
]
}
}
Wilton, et al. Expires 24 April 2025 [Page 51]
Internet-Draft YANG Packages October 2024
}
}
{
"ietf-yang-instance-data:instance-data-set": {
"name": "example-import-2-pkg",
"content-schema": {
"pkg-schema": {
"name": "ietf-yang-package-defn-pkg",
"version": "0.1.0"
}
},
"description": "Second imported example package",
"content-data": {
"ietf-yang-package:yang-package": {
"name": "example-import-2",
"version": "2.0.0",
"reference": "XXX, draft-rwilton-netmod-yang-packages",
"revision-date": "2018-11-26",
"module": [
{
"name": "example-module-A",
"revision": "1.2.3"
},
{
"name": "example-module-E",
"revision": "1.1.0"
}
],
"import-only-module": [
{
"name": "example-types-module-C",
"revision": "2018-11-26"
},
{
"name": "example-types-module-D",
"revision": "2018-11-26"
}
]
}
}
}
}
{
"ietf-yang-instance-data:instance-data-set": {
"name": "example-3-pkg",
"content-schema": {
Wilton, et al. Expires 24 April 2025 [Page 52]
Internet-Draft YANG Packages October 2024
"pkg-schema": {
"name": "ietf-yang-package-defn-pkg",
"version": "0.1.0"
}
},
"description": "Importing example package",
"content-data": {
"ietf-yang-package:yang-package": {
"name": "example-3",
"version": "1.0.0",
"reference": "XXX, draft-rwilton-netmod-yang-packages",
"revision-date": "2018-11-26",
"included-package": [
{
"name": "example-import-1",
"version": "1.0.0"
},
{
"name": "example-import-2",
"version": "2.0.0"
}
],
"module": [
{
"name": "example-module-A",
"revision": "1.2.3"
}
],
"import-only-module": [
{
"name": "example-types-module-C",
"revision": "2018-11-26",
"replaces-revision": [ "2018-01-01 "]
}
]
}
}
}
}
Appendix B. Possible alternative solutions
This section briefly describes some alternative solutions. It can be
removed if this document is adopted as a WG draft.
Wilton, et al. Expires 24 April 2025 [Page 53]
Internet-Draft YANG Packages October 2024
B.1. Using module tags
Module tags have been suggested as an alternative solution, and
indeed that can address some of the same requirements as YANG
packages but not all of them.
Module tags can be used to group or organize YANG modules. However,
this raises the question of where this tag information is stored.
Module tags either require that the YANG module files themselves are
updated with the module tag information (creating another versioning
problem), or for the module tag information to be hosted elsewhere,
perhaps in a centralize YANG Catalog, or in instance data files
similar to how YANG packages have been defined in this draft.
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
together. Module tags cannot meet this aim without an explosion of
module tags definitions (i.e. a separate module tag must be defined
for each package version).
Module tags cannot support the hierachical scheme to construct schema
that is proposed in this draft.
B.2. Using YANG library
Another question is whether it is necessary to define new YANG
modules to define YANG packages, and whether YANG library could just
be reused in an instance data file. The use of YANG packages offers
several benefits over just using YANG library:
1. Packages allow schema to be built in a hierarchical fashion.
[I-D.ietf-netconf-rfc7895bis] only allows one layer of hierarchy
(using module sets), and there must be no conflicts between
module revisions in different module-sets.
2. Packages can be made available off the box, with a well defined
unique name, avoiding the need for clients to download, and
construct/check the entire schema for each datastore. YANG
library's use of a 'content-id' is unique only to the device that
generated them.
3. Packages may be versioned using a semantic versioning scheme,
YANG library does not provide a schema level semantic version
number.
4. For a YANG library instance data file to contain the necessary
information, it probably needs both YANG library and various
augmentations (e.g. to include each module's semantic version
Wilton, et al. Expires 24 April 2025 [Page 54]
Internet-Draft YANG Packages October 2024
number), unless a new version of YANG library is defined
containing this information. The module definition for a YANG
package is specified to contain all of the ncessary information
to solve the problem without augmentations
5. YANG library is designed to publish information about the
modules, datastores, and datastore schema used by a server. The
information required to construct an off box schema is not
precisely the same, and hence the definitions might deviate from
each other over time.
Authors' Addresses
Robert Wilton (editor)
Cisco Systems, Inc.
Email: rwilton@cisco.com
Reshad Rahman
Equinix
Email: reshad@yahoo.com
Joe Clarke
Cisco Systems, Inc.
Email: jclarke@cisco.com
Jason Sterne
Nokia
Email: jason.sterne@nokia.com
Bo Wu (editor)
Huawei
Email: lana.wubo@huawei.com
Wilton, et al. Expires 24 April 2025 [Page 55]