| Internet-Draft | YANG Packages | October 2026 |
| Wilton, et al. | Expires 23 April 2027 | [Page] |
This document defines YANG packages: versioned organizational structures used to manage the schema and conformance of a set of YANG modules as a cohesive unit.¶
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 23 April 2027.¶
Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶
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.¶
This document defines and describes the YANG [RFC7950] constructs that are used to define and use YANG packages.¶
A YANG package is a versioned hierarchical organizational structure used to manage a set of YANG modules that collectively define a package schema. For example, a YANG package could define the set of YANG modules required to implement an L2VPN service on a network device.¶
YANG packages can be:¶
exported from a server,¶
resolved into a YANG schema,¶
accessed as YANG package files with a dedicated .ypkg file suffix,¶
used to define the schema of data in instance data files,¶
and used by tooling to compare and manage YANG schema.¶
Examples of YANG packages are provided in the appendices.¶
The main goals of YANG package definitions include, but are not restricted to:¶
Providing 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).¶
Allowing datastore schema to be specified concisely rather than having each server explicitly list all modules, deviations, 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.¶
YANG packages should be able to represent the equivalent structure as YANG library, but making use of a hierarchical resolution mechanism.¶
YANG packages should be flexible enough to provide usable definitions representing collections of IETF YANG modules, OpenConfig YANG modules, and other bespoke sets of YANG modules, e.g., covering sets of vendor native YANG models.¶
YANG packages should be flexible enough to represent the conformance and server implementations of standard or industry defined YANG package definitions. E.g., it should be possible for a server implementation to indicate that it does not faithfully implement a package schema, e.g., by excluding modules, implementing different module versions/revisions, and/or having deviations applied.¶
Tooling should be able to easily work with YANG package definitions to compare YANG package versions and to compare server conformance against expected package definitions.¶
Protocol mechanisms of how clients can negotiate which YANG packages or YANG package versions are to be used for NETCONF/RESTCONF communications are outside the scope of this document. One potential mechanism is 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 the 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.¶
There are several alternative approaches to managing YANG schema. These include:¶
Using YANG library, along with YANG Instance Data files [RFC9195],¶
Using git tags and version labels for modules maintained on a public git repository,¶
As collections of YANG modules in a zip file or at a directory folder. E.g., at time of publication, this method is used to represent the set of YANG modules associated with a particular vendor release at the GitHub repository at https://github.com/YangModels/yang¶
Although these methods are quite simple, there are some disadvantages with various aspects of these methods: They are verbose, they don't advertise supported features or support mounts, and they can be awkward to compare, particularly if YANG modules haven't been versioned correctly.¶
RFC Editor, please remove this section before publication.¶
All issues, along with the draft text, are currently being tracked at https://github.com/netmod-wg/yang-ver-dt/issues/¶
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 the following terminology introduced in YANG Semantic Versioning [I-D.ietf-netmod-yang-semver]:¶
This document uses the following terminology introduced in the Network Management Datastore Architecture [RFC8342]:¶
datastore schema¶
This document uses the following terminology introduced in the YANG 1.1 Data Modeling Language [RFC7950]:¶
Tree diagrams used in this document follow the notation defined in [RFC8340].¶
In addition, this document defines the following terminology:¶
version (module): In the context of a YANG module, it is used as shorthand to reference a particular revision of a YANG module, potentially identified by a YANG Semver version label or a revision-date.¶
version (package): In the context of a YANG package, it refers to a particular version of a YANG package definition, identified by its package name and version field.¶
YANG schema: The combined set of schema nodes for a set of modules taking into account implemented modules, import-only modules, deviations, features and mount-points. A more complete definition is provided in Section 4.¶
YANG package: The versioned organizational structure defined in Section 3. Depending on context, this term can refer to a specific package version or to the collective set of package versions uniquely identified by its name.¶
package: A shortened form of 'YANG package'.¶
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 6.1.1.2.¶
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 6.1.1.1.¶
editorial change: When used in the context of a YANG module, it follows the definition of an 'editorial change' in 4.4 of [I-D.ietf-netmod-yang-semver]. When used in the context of a YANG package, it follows the definition in Section 6.1.1.3.¶
resolved package schema: The resolved package schema is the YANG schema defined by a package after package resolution has been performed, as defined in Section 4. The resolved package schema identifies the implemented modules (with any deviations applied), import-only modules, enabled features, and schema mount points.¶
package schema: An alternative term for 'resolved package schema'.¶
referentially complete: A property of a resolved package schema in which all module import dependencies can be resolved within that schema, as defined in Section 3.3.¶
enabled feature: A YANG module feature that a resolved package schema identifies as mandatory to enable for all implementations that conform to the package definition.¶
A YANG package is a versioned hierarchical organizational structure used to manage a set of YANG modules that collectively define a package schema.¶
Each YANG package defines:¶
YANG package meta-data, such as "name", "version", "organization", "description", "complete" flag, etc.¶
An "includes" container holding a list of included packages. It also contains lists of any implemented modules and import-only modules that are used in addition to, or with different version to, the modules defined in the included packages. Finally, it lists enabled features in addition to those defined in included packages.¶
An "excludes" container comprising modules and features that are included via the resolved packages of entries in the "includes/package" list, but that are excluded from this package definition. It is not possible to exclude packages.¶
Lists of YANG packages that will be found at particular mount points by any server implementing this package, used in conjunction with mount points defined by any included packages.¶
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 files (ietf-ypkg.yang) and also on the server (ietf-yang-packages.yang).¶
The "yang-pkg-instance" grouping in the "ietf-yang-package-types" YANG module has the following structure:¶
module: ietf-yang-package-types
grouping yang-pkg-instance:
+-- name pkg-name
+-- version pkg-version
+-- version-description? string
+-- timestamp? yang:date-and-time
+-- organization? string
+-- contact? string
+-- description? string
+-- reference? string
+-- complete? boolean
+-- includes
| +-- package* [name version]
| | +-- name pkg-name
| | +-- version pkg-version
| | +-- location* inet:uri
| +-- module* [name]
| | +-- name module-name
| | +-- version version-or-rev-date
| | +-- location* inet:uri
| | +-- submodule* [name]
| | +-- name module-name
| | +-- version version-or-rev-date
| | +-- location* inet:uri
| +-- import-only-module* [name version]
| | +-- name module-name
| | +-- version version-or-rev-date
| | +-- location* inet:uri
| | +-- submodule* [name]
| | +-- name module-name
| | +-- version version-or-rev-date
| | +-- location* inet:uri
| +-- feature* scoped-feature
+-- excludes
| +-- module* module-name
| +-- import-only-module* [name]
| | +-- name module-name
| | +-- version* version-or-rev-date
| +-- feature* scoped-feature
+-- depends-on
| +-- package* [name version]
| +-- name pkg-name
| +-- version pkg-version
| +-- location* inet:uri
+-- mount* [mount-path]
+-- mount-path pkg-ypath
+-- inherit-mounted-schema? boolean
+-- read-only? boolean
+-- mount-mode? enumeration
+-- package* [name version]
| +-- name pkg-name
| +-- version pkg-version
| +-- location* inet:uri
+-- feature* scoped-feature
+-- parent-reference* pkg-ypath
¶
For a YANG package to be valid, it MUST conform to all the following rules:¶
Each (package name, version) pairing MUST define a globally unique version of that package definition.¶
Each YANG package name MUST be globally unique to avoid issues with tools and caching, e.g., using the mechanisms specified in Section 5.1.¶
YANG packages MUST be versioned using YANG Semver, [I-D.ietf-netmod-yang-semver]. Versioning YANG packages is further described in Section 6.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 3.3.¶
If the resolved package schema is not referentially complete, as defined in Section 3.3, the package definition's 'complete' flag MUST be set to 'false'.¶
Package definitions are hierarchical because a package can include other packages. A package MUST NOT include itself at any version, directly or indirectly, including through packages referenced at mount points.¶
A package definition MAY directly include multiple versions of the same package in the "includes/package" list, but normally only a single package version is expected. Multiple package versions can be listed, for example, to update location information for package versions included through other packages.¶
If the same package version, module version, import-only module version, or submodule version is referenced via multiple included packages, then the referenced content and metadata are expected to be equivalent, and hence either reference can be used for resolution. Tools MAY issue a warning or report an error if they detect conflicting content. Location information MAY differ and is merged as defined by the package resolution rules in Section 4.¶
A package definition MUST NOT list the same package version under both the 'includes/package' and 'depends-on/package' lists.¶
If a location leaf-list for a package, implemented module, import-only module, or submodule includes a canonical location used to retrieve that YANG artifact, it MUST be the first entry in the leaf-list.¶
For each module implemented by a package, only a single version/revision of that module MUST be implemented. Conflicting module versions (e.g. from package includes) MAY be resolved explicitly (via "includes/module") or using automatic module version resolution, as described in Section 4.1.¶
Multiple versions/revisions of an import-only module MAY be listed, but any extraneous import-only module versions SHOULD be removed. For a given module, each import-only revision retained in the resolved package schema with a YANG Semver label MUST have a unique version when modifiers, pre-release metadata, and build metadata are ignored.¶
A package definition MUST NOT include the same module name in the 'includes/module' list and the 'excludes/module' leaf-list.¶
A package definition MUST NOT include and exclude the same import-only module version. If an 'excludes/import-only-module' entry does not list any versions, then it excludes all versions of that import-only module and MUST NOT be used with any 'includes/import-only-module' entry for the same module name.¶
A package definition MUST NOT include the same feature name in both the 'includes/feature' and 'excludes/feature' leaf-lists.¶
A package definition MUST NOT exclude a module and list features defined by that module in the 'includes/feature' leaf-list.¶
A package definition MAY include redundant information, e.g., including a module or package version that is already present by an included package, or excluding a module that is not included by any included package. However, such redundant information might be confusing to readers. Although the resolved package schema is unambiguous, it is best to minimize redundant information where possible.¶
Finally, standard YANG validation rules apply. E.g., entries in the various lists MUST be unique by any list key.¶
The "depends-on/package" list can identify other packages that a package depends on, but that are not included as part of the package definition, and hence do not form part of the resolved package schema.¶
The main anticipated use is for referentially incomplete packages, where the dependencies identify packages that are expected to be resolved along with the incomplete package. The same mechanism can also be used by a referentially complete package to provide additional machine-readable dependency metadata.¶
Dependency metadata is not inherited and does not participate in ordinary package resolution. For version compatibility assessment of referentially incomplete packages, it provides the comparison context defined in Section 6.1.1.¶
A YANG package may represent a schema that is 'referentially complete', or 'referentially incomplete', indicated in the package definition by the 'complete' flag.¶
If all import statements in all YANG modules in the resolved package schema can be resolved to a module version in that schema, then the package is classified as being referentially complete. Conversely, if one or more import statements cannot be resolved to a module version in the resolved package schema, then the package is classified as being referentially incomplete.¶
A package is referentially complete only if every resolved mounted schema is also referentially complete, recursively; imports in a mounted schema are resolved within that schema rather than the parent schema.¶
If the packages needed to resolve a referentially incomplete package definition are known, and can be expressed without excessive complexity, then the package definition SHOULD include "depends-on/package" entries to help a client resolve a complete schema in a machine-readable way. The server MAY provide the additional schema information in another way, e.g., via user documentation, or if the dependencies are more complex.¶
Also see Section 5.3 for details on cases when referentially incomplete packages are helpful.¶
As defined in [RFC7950] and [I-D.ietf-netmod-yang-semver], YANG conformance and versioning is specified in terms of particular versions 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 user-ordered locations where each submodule definition can be obtained from. If a canonical location for a submodule is provided, it MUST be listed first.¶
YANG Schema Mount [RFC8528] defines a mechanism for YANG modules to be mounted at specific mount points in the schema tree. This mechanism is required to instantiate the full schema for some common networking use cases, e.g., [RFC8529] defines a YANG Model for Network Instances, that uses YANG mount points to mount IETF routing protocol YANG modules within the network instance list.¶
[RFC8528] declares that it provides support for mounted schema at "Implementation time" and "Run time", but does not cover mounting schema at "Design time". YANG package definitions do not give YANG language level "Design time" guarantees, but they are able to give a stronger "Implementation time" guarantee through the use of offline YANG package definitions. They can also be used to report "Run time" mounted schema behavior, if the server is able to report the packages implemented by the device.¶
Each YANG package definition defines the package schema, additional features, and parent-references found at a particular mount point, via two mechanisms:¶
Mounted packages, additional features, and parent-references that are exported from any included packages are also exported at the same mount point for this specific package, unless package inheritance is explicitly disabled by a 'mount' list entry for the same mount point with 'inherit-mounted-schema' set to 'false'.¶
A package definition can add mounted packages, additional features, and parent-references to a mount point by listing them in the 'mount' list entry. These entries are additive, like entries in the 'includes/package' list. If the same package name is listed with a different version, then both package versions are retained. I.e., a package definition can remove inherited mounted packages, modules, enabled features, or parent-references only by setting 'inherit-mounted-schema' to 'false' and explicitly listing the packages, features, and parent-references that define the complete mounted schema. Examples of this are given in Appendix A.6.2.¶
A package mount entry specifies the schema required at the mount instances identified by its mount-path. The 'mount/mount-mode' leaf selects the "inline" or "shared-schema" mode defined by [RFC8528], with inheritance and resolution specified in Section 4. The server's Schema Mount advertisement MUST be consistent with the package definition and the requirements of the selected mode.¶
The 'mount/read-only' leaf specifies whether the mounted schema is read-only, with inheritance and resolution specified in Section 4. When advertising the mount using Schema Mount, the mount-level 'config' leaf MUST be 'false' if the mount is read-only and 'true' otherwise. A read-write mount retains the config properties of the nodes in the mounted schema.¶
Each package parent-reference MUST identify the same nodes as an equivalent XPath expression evaluated in the context specified by Section 4 of [RFC8528]. The server's Schema Mount advertisement MUST provide parent-reference expressions whose combined selection is equivalent to that specified by the resolved package.¶
If a server implements the YANG library package bindings defined in Section 5.4.3 for a mounted schema, then the YANG library data provided at the mount point MUST include the 'package' list, and any applicable 'feature' leaf-list entries, defined by the "ietf-yl-packages" module, Section 5.4.3. The mounted schema MUST also include the "ietf-yang-packages" module, and its '/packages/package' list at the mount point MUST contain an entry matching each package name and version referenced by the "ietf-yl-packages" 'package' list. This ensures that the leafrefs in the package bindings resolve.¶
A package definition may exclude modules or enabled features. The mechanism for this is described in Section 4, and the conformance implications are described in Section 7.¶
Excluding a module can leave module import dependencies unresolved and make the resolved package schema referentially incomplete, as defined in Section 3.3. The 'complete' flag MUST be set appropriately, as required by Section 3.1. Referentially incomplete packages are permitted, but the resolved schema used for a datastore must be referentially complete, as required by Section 5.4.3 and Section 7.7.¶
Package resolution is the process of taking a YANG package definition and converting it to a specification for a YANG schema, e.g., as may be implemented by a device for a particular datastore. A YANG schema can be thought of as comprising:¶
that can be collectively compiled into a YANG schema tree.¶
The YANG schema generated by a package definition can be converted into an equivalent instance in YANG library [RFC8525], with Schema Mount [RFC8528] if mount points are used. Package resolution determines the module sets, enabled features, parent-references, read-only status, and mount mode of mounted schemas. E.g., see Section 5.4.3.¶
References to module versions, e.g., when applying exclusions, are matched using their module names and revisions. A YANG Semver version label and its associated revision-date identify the same module revision and MUST be treated as equivalent during package resolution.¶
The following process defines how a YANG package definition is resolved, using two explicit steps:¶
Step 1: recursively resolve each package in the "includes/package" list using this same two-step process.¶
Step 2: merge the resolved package schemas from those included packages with the local entries defined directly by this package. The local entries are the contents of the "includes" and "excludes" containers and the "mount" list in this package. The merge is performed using the following rules:¶
included packages: The set of
included package references is the union of all included package
references in the resolved included packages, then overwritten,
including location information, by any entries in the local
"includes/package" list with the same package name and version.
Location leaf-lists for duplicate inherited package references are
merged using the location lists
rule.¶
implemented modules: The set of
implemented modules is the union of all
implemented modules in the resolved included packages. Conflicting
module versions can be resolved automatically as per
Section 4.1, then overwritten
(including submodule and location information) by any entries in the
"includes/module" list, and finally filtered by any entries in
the "excludes/module" leaf-list. Location leaf-lists for duplicate
inherited module references are merged using the
location lists rule.¶
import-only modules: The set of
import-only modules is the union of all import-only modules in the
resolved included packages. Location leaf-lists for duplicate
inherited import-only module references are merged using the
location lists rule. The set is then
overwritten (including submodule and location information) by any
entries in the "includes/import-only-module" list with the same
module name and version, and finally filtered by any entries in the
"excludes/import-only-module" list. Any import-only module entry
with the same module name and version as a resolved implemented
module entry is also filtered out.¶
enabled features: The set of
enabled features is the union of the enabled features from the
resolved included packages, with any
"includes/feature" entries added, and any
"excludes/feature" entries removed. If a module is
excluded by "excludes/module" then all features associated with
that module are also implicitly removed. A package definition is
invalid if, after resolution, an enabled feature is not defined by
its named implemented module in the resolved package schema.
Consequently, a feature defined only by an import-only module
cannot be enabled by a package.¶
mounts: The set of mounts is the
union of the mounts in the resolved included packages. Mount paths
MUST be normalized using the normalization rules defined in
[I-D.jgc-netmod-yang-path] before comparison, and
matching is based on their normalized values. Only exact matches
between normalized mount paths are considered during package
resolution; overlapping selections from different normalized paths
are permitted and are not checked. For a
given mount-path that is present in more than one included package
the resolved mount takes the union of
the mounted packages, "mount/feature" entries, and mount
parent-references. The mounts are then updated by processing any
entries in the package's "mount" list. If "inherit-mounted-schema" is
true, or absent, the local "mount/package",
"mount/feature", and "mount/parent-reference" entries
are added to the inherited mounted schema for that mount point.
Thus, local "mount/feature" entries add to features enabled by
inherited mounted packages and inherited "mount/feature" entries,
as well as features enabled by locally listed mounted packages. If
the same package version is present in both the inherited and local
"mount/package" entries, then the local entry overwrites the
inherited entry, including location information. If the same
package name is present with different package versions, then all
package versions are retained. If "inherit-mounted-schema" is false, the
inherited mounted packages, additional features,
parent-references, read-only status, and mount mode for that mount
point are discarded, and the local
"mount" entry defines the mounted schema for that mount point.
If that local entry lists no packages, the mount is removed from
the resolved package schema and no schema is mounted there. The
corresponding Schema Mount 'mount-point' entry is omitted, as
described in Section 3.3 of [RFC8528].¶
mount read-only status: A mount is
read-only if an inherited mount at the same mount-path is read-only,
or if the local 'mount/read-only' leaf is 'true'. An explicit local
'false' value conflicts with inherited read-only status and causes
schema resolution to fail. If no read-only status is inherited
and the leaf is absent, the mount is read-write. All data
nodes in a read-only mounted schema have an effective config
property of 'false', as specified in Section 3.3 of [RFC8528].¶
mount mode: The mode is inherited
from mounts at the same mount-path in included packages. If
inherited modes conflict, or an explicit local 'mount/mount-mode'
value differs from the inherited mode, schema resolution fails.
If no mode is inherited and the local leaf is absent, the mode is
'shared-schema'. A resolved mount using 'inline' mode MUST NOT
contain parent-references.¶
submodules: Submodules are ignored
for resolution purposes, only the module version is considered and
compared. For duplicate inherited references to the same submodule
version, location leaf-lists are merged using the
location lists rule.¶
location lists: This rule applies
when duplicate inherited package, module, import-only module, or
submodule references identify the same version but have different
location leaf-list values. The referenced content and metadata are
expected to be equivalent. The location leaf-lists are merged
pairwise in the order that the included package entries are listed.
For each pairwise merge, values from the second location leaf-list are
appended to the first location leaf-list, except that values already
present in the first location leaf-list are ignored. Hence, the
first occurrence of each location is retained and the relative order
of non-duplicate locations is preserved.¶
Section 5.6.5 of [RFC7950] requires imports without a revision-date to use the most recent revision of the imported module advertised in YANG library. For a resolved package schema, an import without a revision-date MUST use the rules in Section 4.1 to select the highest version or most recent revision from the implemented and import-only versions of that module in the resolved package schema.¶
With branched module development, the highest YANG Semver version can have an earlier revision date than another available version, so these selection rules can give different results to Section 5.6.5 of [RFC7950]. To avoid any potential ambiguity in the resolved schema, it is RECOMMENDED that a resolved package schema contains only a single version of each module across its implemented and import-only module sets.¶
Package resolution MUST check that each package definition conforms to the rules in Section 3.1. Rules that depend on the resolved package schema MUST be checked after Step 2 for that package, e.g., checking that the 'complete' flag is 'false' if the resolved schema is referentially incomplete.¶
A resolved package schema can only implement a single version of a module, and hence when conflicting module versions arise from included packages that resolve to different versions of a given module then a single version has to be chosen. The following rules are used, in the order given, to automatically select the chosen version by comparing the version leaves of the module versions from the resolved included packages:¶
If both version leaves match the YANG Semver format, then they are first compared using only the MAJOR, MINOR, and PATCH version components, as described in Section 4.3 of [I-D.ietf-netmod-yang-semver] and Section 4.4 of [I-D.ietf-netmod-yang-semver]. Any "_compatible" or "_non_compatible" modifier, pre-release metadata, and build metadata are ignored for this numeric comparison:¶
The module with the highest MAJOR version component is chosen.¶
Otherwise, if the MAJOR version components are the same, then the module with the highest MINOR version component is chosen.¶
Otherwise, the module with the highest PATCH version component is chosen.¶
If two or more candidates classify to the same highest version but have different "version" leaf content (e.g., differing metadata), automatic module version resolution fails and the module version MUST be explicitly selected through an 'includes/module' entry.¶
If one module has a version statement that matches the YANG Semver format but the other does not, then the module with the version statement matching the YANG Semver format is chosen.¶
If neither module has a version statement that matches the YANG Semver format, then the module with the most recent revision-date is chosen.¶
If two module references identify the same module revision then:¶
This section provides information and guidance on how YANG packages can be used.¶
YANG packages can be defined and used for different purposes:¶
By standards development organizations and industry organizations - to specify common sets of YANG data models that can be used together to manage network devices, or even just particular functionality on network devices (e.g., L3VPN services). Since package definitions can be defined hierarchically, packages defining different functionalities can be combined into larger package definitions that define more complex and complete behavior and YANG schema. These package definitions may be published by the organizations as package files.¶
For devices:¶
to describe the YANG schema associated with the device or a datastore schema on the device. These package schemas can be made available both from the device and also in offline package files.¶
to define different optional YANG schemas that can be used by the device and where clients can select which YANG schema can be used via configuration.¶
to refine standards based and industry packages to accurately report how the device does not fully conform to the package schema definition.¶
To manage and report the schema available at YANG schema mounts points.¶
It is RECOMMENDED that organizations publishing YANG modules also publish YANG package definitions that group and version those modules into units of related functionality. This increases interoperability by encouraging different implementations to coalesce around using the same collections of YANG modules versions. Using packages also makes it easier to understand the relationship between modules, and enables functionality to be described on a more abstract level than individual modules.¶
Where possible, package definitions SHOULD be made available offline in YANG package files, see Section 5.5, but also on the device as a list of known packages and relationships between YANG library datastore schema and equivalent YANG package definitions, e.g., see Section 5.4.¶
As specified in Section 3.1, YANG package names are globally unique. Different versions of the same package share its name, while the name and version together uniquely identify a package definition.¶
There are a couple of ways of achieving this uniqueness requirement:¶
For package definitions that define a 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 entirely local to a particular server or device, the sysName of the device, a MAC address, or a UUID should be used as a suffix to the package name to ensure uniqueness. If possible, a stable identifier that persists across reboots or reprovisioning can help clients recognize the same package.¶
Some YANG modules do not define any implementable data nodes, RPCs, Actions, or Notifications. These YANG modules often include 'types' in the name of the YANG Module. For YANG package definitions, there is a choice whether to include these types modules in the packages list of implemented modules, or as import-only modules. This document does not specify how these should be declared, but instead gives some points of consideration that may be helpful when choosing. These are:¶
Listing a "types-only" module as implemented allows for simpler automatic module version selection between different packages, as per Section 4.1.¶
As per [RFC7950] section 9.10.2, identities are only available for use by the server for implemented modules.¶
If a module defines data nodes and types and the server only wants to use the types but not implement any data nodes from the module then listing the module as import-only is clearer and simpler than marking it as implemented with a separate deviation file that deviates all data nodes as not-supported.¶
If a module imports a module at an exact revision (which, as per [I-D.ietf-netmod-yang-module-versioning], is not recommended) then it may be helpful to list that module in the import-only module list (even if implemented) to ensure that the import dependency is always satisfied.¶
Referentially incomplete packages can be used to represent updates to a device's datastore schema, including optional software hot fixes. For example, the base software can be represented by a complete package and a hot fix by an incomplete package. An example is provided in Appendix A.2.3.¶
An incomplete package, e.g., a hot fix package, can provide "depends-on/package" entries to identify the package versions that the incomplete package is intended to be used with.¶
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 versions of 'types' modules to be resolved when the package definition is used.¶
A client discovers the package definitions for a datastore schema by first retrieving YANG Library. For each YANG Library schema entry, the augmented 'package' list, if present, identifies the top-level package name/version pairs that define that datastore schema. Those package references identify entries in the server's top-level '/packages/package' list. A client can use the package definition advertised by the server, retrieve a package file from one of the advertised 'location' URIs, or use a cached package instance data file for the same package name and version. The client then resolves the listed packages, together with any 'feature' entries to construct the complete datastore schema, as described in Section 5.4.3.¶
A top level 'packages' container holds the list of all versions of all packages known to the server. Entries in this list do not necessarily mean that the package is implemented by the server or currently active for any datastore. Instead, the YANG Library package bindings in Section 5.4.3 are used to indicate which of the advertised packages are supported by each datastore schema.¶
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, or if package versions have been changed via applying different software packages or hot fixes.¶
The "ietf-yang-packages" YANG module has the following structure:¶
module: ietf-yang-packages
+--ro packages
+--ro package* [name version]
// Uses the yang-pkg-instance grouping defined in
// ietf-yang-package-types.yang.
+--ro name pkg-name
+--ro version pkg-version
... remainder of yang-pkg-instance grouping ...
¶
The ietf-yl-packages module augments YANG library to provide a concise alternative approach of using hierarchical packages to define datastore schema compared to constructing the schema using a union of more verbose module definitions defined in module-sets.¶
Since packages can be made available offline in YANG package files, and cached, it may be sufficient for a client to only fetch the names/versions of the top level packages, along with the list of feature entries to construct the full datastore schema.¶
If multiple packages are listed for a datastore schema then they are resolved as if the packages were all directly included in a single package definition, including all feature entries, and following the standard package resolution rules in Section 4.¶
This means that conflicting module versions between the listed packages are resolved using the automatic module version resolution rules in Section 4.1. As a result, the version that wins those rules is selected in the resolved package schema. This allows an extra 'hot fix' package to be added to the list of packages defining a schema to provide a later module version, but it cannot be used to select an older module version. Instead, a package that explicitly includes and refines the referenced packages would need to be defined to select the older module version (see Section 7.1).¶
If populated, the set of packages listed for a datastore schema combined with the leaf-list of feature entries MUST resolve to a schema that exactly matches the schema defined by the YANG library 'schema/module-set' leaf-list, and the resolved package schema MUST be referentially complete.¶
Since these nodes augment into YANG library, then as per [RFC8525], the "/yang-library/content-id" leaf is updated if the packages or feature entries change.¶
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
| +--ro location* inet:uri
+--ro feature* pkg-types:scoped-feature
¶
YANG packages SHOULD be made available offline from the server as YANG package files defined by the "ietf-ypkg" module.¶
The following rules apply to YANG package files:¶
A file MUST contain exactly one "ietf-ypkg:yang-package" structure with exactly one complete package definition in its 'pkg-defn' container. All applicable YANG constraints and package definition rules MUST be satisfied. A package definition may describe a referentially incomplete package schema using 'complete: false'.¶
The file MUST use the JSON encoding defined in [RFC7951] and UTF-8 character encoding.¶
The file MUST use the ".ypkg" extension and the "application/yang-package+json" media type defined in Section 12.3.¶
The filename MUST be "<package-name>@<version>.ypkg", with the name and version matching the 'pkg-defn/name' and 'pkg-defn/version' leafs.¶
The optional top-level 'schema' leaf identifies the package defining the schema of the entire file, including its envelope and any extensions. Its value MUST have the form "<package-name>@<version>". The default reference schema is "ietf-ypkg-schema@0.1.0", defined in Section 9, and MUST be used if 'schema' is absent. A different schema MUST be explicitly identified. The referenced schema MUST be referentially complete. The schema package version identifies the file format version; no separate format version field is defined.¶
The optional top-level 'schema-location' leaf-list provides URLs for retrieving the explicitly identified or default schema package. The retrieved package's name and version MUST match the schema reference. A canonical location, if provided, MUST be the first entry in this user-ordered leaf-list. If no location is specified, the schema package MUST be available to download at "https://www.iana.org/assignments/yang-parameters/<pkg-name>@<pkg-version>.ypkg", using the name and version of the explicitly identified or default schema package. Otherwise, at least one download URL MUST be provided in 'schema-location'.¶
Values equal to their applicable YANG defaults MAY be explicitly encoded. Producers SHOULD omit such values to encourage a consistent style.¶
The package file for each package version SHOULD be available at one or more URLs.¶
RFC Editor note: Before publication, update the default reference schema identifier to "ietf-ypkg-schema@1.0.0" throughout this document. Confirm the implicit schema download URL with IANA and update the URL prefix here and in the "ietf-ypkg" module if needed. Remove this note before publication.¶
The "ietf-ypkg" module has the following structure:¶
module: ietf-ypkg
structure yang-package:
+-- schema? pkg-types:pkg-reference
+-- schema-location* inet:uri
+-- pkg-defn
// Uses the yang-pkg-instance grouping defined in
// ietf-yang-package-types.yang
+-- name pkg-name
+-- version pkg-version
... remainder of yang-pkg-instance grouping ...
¶
Section 5.5 defines how YANG packages can be published in off-device files. A device may support multiple datastores, each with a different schema defined by a set of packages. The "ietf-yang-device-schema" module binds these datastores, schemas, and package references into a complete device schema, equivalent to that which could be advertised by YANG library [RFC8525] in an instance data set [RFC9195]. Packages are resolved as described in Section 5.4.3, including any additional enabled features.¶
The following requirements apply:¶
The "device-schema" read-only container MUST be carried in the "content-data" of an instance data set conforming to [RFC9195].¶
Contact, organization, description, and document revision metadata are carried in the enclosing instance data set metadata.¶
A reference to a YANG library instance data document MAY be provided in "yang-library". If provided, its datastore bindings and schemas MUST match those obtained by package resolution, including any additional enabled features.¶
This container is primarily intended for off-device publication. Servers are expected to use YANG library and its package extensions to advertise their current schemas.¶
The module has the following structure:¶
module: ietf-yang-device-schema
+--ro device-schema
+--ro device string
+--ro release string
+--ro yang-library? inet:uri
+--ro schema* [name]
| +--ro name string
| +--ro package* [name version]
| | +--ro name pkg-name
| | +--ro version pkg-version
| | +--ro location* inet:uri
| +--ro feature* pkg-types:scoped-feature
+--ro datastore* [name]
+--ro name ds:datastore-ref
+--ro schema -> ../../schema/name
¶
The "ietf-device-schema" package defines a minimal, referentially complete content schema for carrying "ietf-yang-device-schema" data in a YANG instance data document. It implements "ietf-yang-device-schema" and "ietf-datastores" and lists the remaining imports as import-only modules.¶
A datastore schema instance data set can reference this package as described in Section 5.7, or list the modules directly using the simplified-inline method of [RFC9195].¶
The following package defines the content schema:¶
<CODE BEGINS> file "ietf-device-schema@0.1.0.ypkg"
=============== NOTE: '\' line wrapping per RFC 8792 ================
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "ietf-device-schema",
"version": "0.1.0",
"timestamp": "2026-10-13T00:00:00Z",
"organization": "IETF",
"contact": "IESG",
"description": "This package defines the 'content-schema' \
[RFC 9195] for off-device definitions of a device's datastore \
schemas.",
"reference": "RFC XXXX: YANG Packages",
"includes": {
"module": [
{
"name": "ietf-yang-device-schema",
"version": "0.1.0",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-yang-device-schema@0.1.0.yang"
]
},
{
"name": "ietf-datastores",
"version": "2018-01-11",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-datastores@2018-01-11.yang"
]
}
],
"import-only-module": [
{
"name": "ietf-yang-package-types",
"version": "0.10.0",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-yang-package-types@0.10.0.yang"
]
},
{
"name": "ietf-yang-revisions",
"version": "2026-06-26",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-yang-revisions@2026-06-26.yang"
]
},
{
"name": "ietf-yang-semver",
"version": "0.25.0",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-yang-semver@0.25.0.yang"
]
},
{
"name": "ietf-yang-types",
"version": "2025-12-22",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-yang-types@2025-12-22.yang"
]
},
{
"name": "ietf-inet-types",
"version": "2025-12-22",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-inet-types@2025-12-22.yang"
]
}
]
}
}
}
}
<CODE ENDS>¶
The following instance data set uses the package defined in Section 5.6.1 to identify its content schema. The running and operational datastores share a schema defined by a separate device-routing package file.¶
<CODE BEGINS> file "example-device-schema.json"
=============== NOTE: '\' line wrapping per RFC 8792 ================
{
"ietf-yang-instance-data:instance-data-set": {
"name": "example-device-schema",
"content-schema": {
"ietf-yang-inst-data-pkg:pkg-schema": {
"schema": "ietf-device-schema@0.1.0",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-device-schema@0.1.0.ypkg"
]
}
},
"contact": "Example Networks support <support@example.org>",
"organization": "Example Networks",
"description": [
"Datastore schemas for ExampleOS 1.0.0."
],
"revision": [
{
"date": "2026-10-12",
"description": "Initial advertisement."
}
],
"content-data": {
"ietf-yang-device-schema:device-schema": {
"device": "Example Router / ExampleOS",
"release": "1.0.0",
"yang-library": "https://example.org/yang/\
exampleos-library.json",
"schema": [
{
"name": "device-routing datastore schema",
"package": [
{
"name": "device-routing",
"version": "1.0.0",
"location": [
"https://example.org/yang/packages/\
device-routing@1.0.0.ypkg"
]
}
]
}
],
"datastore": [
{
"name": "ietf-datastores:running",
"schema": "device-routing datastore schema"
},
{
"name": "ietf-datastores:operational",
"schema": "device-routing datastore schema"
}
]
}
}
}
}
<CODE ENDS>¶
Alternatively, the "content-schema" member in example-device-schema.json can be replaced by the following module list, including all direct and transitive import dependencies. The rest of the instance data set is unchanged.¶
{
"content-schema": {
"module": [
"ietf-yang-device-schema@2026-10-12",
"ietf-datastores@2018-01-11",
"ietf-inet-types@2025-12-22",
"ietf-yang-package-types@2026-07-06",
"ietf-yang-revisions@2026-06-26",
"ietf-yang-semver@2026-03-03",
"ietf-yang-types@2025-12-22"
]
}
}
¶
YANG package definitions can be used to define the content schema for YANG instance data files, extending the content schema definition in Section 3.2 of [RFC9195]. When using a package-based content schema, the 'schema' leaf MUST identify the schema package as "<package-name>@<version>", using the 'pkg-reference' typedef. One or more location URLs for retrieving the package definition in the .ypkg format defined in Section 5.5 MAY also be provided. The resolved package schema provides the exact specification for the content schema, taking into consideration all implemented modules, import-only modules, augmentations, enabled features and any deviations.¶
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
+-- schema pkg-types:pkg-reference
+-- location* inet:uri
¶
The following example shows how the example in Section 2.2.3 of [RFC9195] could alternatively use example-diagnostics-schema@1.0.0.ypkg to define the content schema for NETCONF monitoring state data.¶
Example of YANG instance data file using a schema defined by a YANG package.¶
========== NOTE: '\' line wrapping per RFC 8792 ===========
{
"ietf-yang-instance-data:instance-data-set": {
"name": "example-router-netconf-diagnostics",
"content-schema": {
"ietf-yang-inst-data-pkg:pkg-schema": {
"schema": "example-diagnostics-schema@1.0.0",
"location": [
"https://example.org/\
example-diagnostics-schema@1.0.0.ypkg"
]
}
},
"timestamp": "2026-10-07T10:23:14Z",
"description": ["NETCONF statistics, \
The data may change at any time."],
"content-data": {
"ietf-netconf-monitoring:netconf-state": {
"statistics": {
"netconf-start-time ": "2018-12-05T17:45:00Z",
"in-bad-hellos ": "32",
"in-sessions ": "397",
"dropped-sessions ": "87",
"in-rpcs ": "8711",
"in-bad-rpcs ": "408",
"out-rpc-errors ": "408",
"out-notifications": "39007"
}
}
}
}
}
¶
Example package definition used as the content schema for the NETCONF monitoring instance data above.¶
<CODE BEGINS> file "example-diagnostics-schema@1.0.0.ypkg"
=============== NOTE: '\' line wrapping per RFC 8792 ================
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "example-diagnostics-schema",
"version": "1.0.0",
"timestamp": "2026-10-07T10:23:14Z",
"description": "Example schema package for NETCONF monitoring \
instance data.",
"reference": "RFC 6022",
"includes": {
"module": [
{
"name": "ietf-netconf-monitoring",
"version": "2010-10-04",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-netconf-monitoring@2010-10-04.yang"
]
}
],
"import-only-module": [
{
"name": "ietf-yang-types",
"version": "2025-12-22",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-yang-types@2025-12-22.yang"
]
},
{
"name": "ietf-inet-types",
"version": "2025-12-22",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-inet-types@2025-12-22.yang"
]
}
]
}
}
}
}
<CODE ENDS>¶
As defined in Section 3.1, YANG packages are versioned using [I-D.ietf-netmod-yang-semver]. This section describes how those rules apply to YANG package definitions.¶
Package version compatibility is determined by comparing the resolved package schemas of the prior and updated package versions. The comparison MUST use the YANG schema tree comparison algorithm defined in [I-D.ietf-netmod-yang-schema-comparison], applied to the compiled schema tree (i.e., the fully resolved schema representation, with deviations applied). For this comparison, 'feature' and 'if-feature' statements MUST be ignored when constructing the compiled schema tree, retaining all conditional schema nodes regardless of feature enablement. The comparison also covers all schemas mounted by the package, at their respective mount points.¶
For compatibility assessment, each referentially incomplete package version MUST identify sufficient dependency packages in its 'depends-on/package' list to construct a referentially complete schema, including all mounted schemas recursively. The package and its listed dependencies MUST be resolved as if directly included in a single package definition, following Section 4.¶
The prior and updated package versions MUST each use their own listed dependencies for this assessment; changes contributed by those dependencies are included in the comparison.¶
Changes to the resolved set of mandatory enabled features, including those at mount points, MUST be assessed separately. Adding a feature to this set is a BC change; removing a feature from this set is an NBC change.¶
Changes to the resolved set of parent-references at each mount point MUST also be assessed separately. Adding a parent-reference is a BC change; changing or removing a parent-reference is an NBC change.¶
Changing a mount from read-write to read-only is an NBC change. Changes between 'shared-schema' and 'inline' mount modes MUST be assessed separately and are BC changes.¶
When a package definition is updated, the version associated with the package MUST be updated according to the YANG semantic version update rules in Section 4.5 of [I-D.ietf-netmod-yang-semver], using the scope of changes determined by the schema comparison and the separate assessment of mandatory enabled features, parent-references, and mount properties, as described below.¶
Note, an NBC change to a YANG module does not necessarily result in an NBC change to a package that uses that module. For example, renaming a grouping and updating all uses of that grouping in the package schema can leave the compiled schema tree unchanged. Such a change does not require an NBC package version update, even though the module change is NBC for other modules that reference the old grouping name.¶
A package publisher MAY choose a more significant version update than these assessments require, as permitted by [I-D.ietf-netmod-yang-semver]. For example, a publisher may choose a major version update to highlight changes to groupings intended for reuse by modules outside the package, even if the compiled schema tree is unchanged. The publisher SHOULD explain the reason for such an update in the 'version-description' leaf.¶
A package update is non-backwards-compatible if the comparison reports any NBC change to the resolved package schema, including any mounted schema, or if any mandatory enabled feature is removed from the resolved set, or if any parent-reference is changed or removed, or if a mount changes from read-write to read-only.¶
A package update is backwards-compatible if there are no NBC changes, as defined in Section 6.1.1.1, and either the comparison reports at least one BC change or a mandatory enabled feature or parent-reference is added to the resolved set, or a mount mode changes between 'shared-schema' and 'inline'. This includes changes to mounted schemas.¶
A package update is editorial if the comparison reports only editorial changes or no changes to the resolved package schema, including any mounted schema, and the resolved set of mandatory enabled features and parent-references is unchanged, and mount modes are unchanged. Changes to package metadata or location information that do not affect that schema are also editorial.¶
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.¶
General YANG Semver versioning guidance from Section 6 of [I-D.ietf-netmod-yang-semver] may be helpful, additional IETF specific guidance for managing IETF package definitions may be provided in a future RFC, pending the output of [I-D.mahesh-opsawg-veloce-yang].¶
Better and easier conformance is a major design goal for YANG packages. YANG package conformance is similar to how YANG [RFC7950] requires that servers either implement a module faithfully, or otherwise use deviations to indicate areas of non-conformance. Ultimately, each version of a YANG package resolves, as per (Section 4), to a YANG schema that is defined as a set of implemented modules and import-only modules, deviations, features, and mounted schema. For YANG package conformance, it is necessary to determine whether an implementation faithfully conforms to the full YANG schema defined by a resolved YANG package.¶
The YANG packaging solution is designed to allow for conformance to be checked at a package level, potentially using cached offline package definitions, rather than requiring a client to download all modules, supported features, and deviations from the server to ensure that the datastore schema used by the server is compatible with the client.¶
In the case where a device does not completely conform to a standard or industry defined YANG package definition, then there are a few suggestions on how this can be handled:¶
Automatic module version resolution rules can be used to select the latest module version between packages.¶
Server implementation packages can be defined that include and refine standard/industry packages to accurately report the device's schema and any variations from the standard.¶
Sometimes a package definition may include multiple packages that implement different versions of a module.¶
As per the package definition rules in Section 3.1, a package can only implement a single version of a module, and hence in cases of conflicting versions in included packages/modules it is necessary to resolve which version of the module is used. The default behavior, defined in Section 4.1 is to use automatic resolution, which is generally the best choice. Manual resolution could be used to select a different module version instead, or even remove the module from the package entirely. However, care must be taken if an older module version is chosen, or a non-backwards-compatible newer version is chosen, because, in both cases, this may affect conformance in one of the included packages.¶
Unlike modules in a package definition, where there can only be a single version of a module in a resolved package schema, this does not apply to included packages. As per the package resolution rules in Section 4, when multiple included packages define different versions of the same package, then both versions are retained in the resolved package schema.¶
Package authors should try to align included package versions so that the transitive inclusion graph contains at most one version of each package name within a resolved schema. Multiple versions MAY be included when needed to compose independently maintained packages, but this may make the resolved schema harder to use and make package conformance more complicated for clients to consume.¶
Package and schema comparison tooling can be used to determine what level of package conformance has been achieved for each of the recursively included packages.¶
Whenever possible, servers should aim to implement standards defined packages or industry defined packages accurately since this maximizes interoperability for clients. However, if a server does not faithfully implement a YANG package then it can define a new server specific package to accurately report what it does implement. The RECOMMENDED approach to achieve this is to define and advertise a separate "server implementation" package which incorporates the package to be conformed to via including it in "/includes/package", and then excludes modules or selects different versions, adds deviation modules, and excludes enabled features to indicate the actual conformance of the server implementation.¶
Modules containing deviations are listed and treated like any other implemented YANG module, with no special annotation in the package definition; their names often indicate that they contain deviations, which is a sensible and helpful naming convention.¶
An example of this approach is provided in Appendix A.2.1.¶
If an implementation doesn't support any functionality in a module then it should exclude the module rather than using deviations to exclude all data nodes added by the module to the resolved package schema. This gives a clearer indication to users of the package definition as to the intent. However, be aware when combining two included packages, that a module removed by one package could still be re-added by another included package. If deviations are used this won't happen unless the module defining the deviations is explicitly removed.¶
If an alternative version of a module is used then it is RECOMMENDED to use a newer module version, if possible, rather than an older version. Selecting a backwards-compatible version is also helpful because it maximizes the chance that clients will be able to easily interoperate with the server.¶
The YANG language, [RFC7950] section 5.6.2, supports feature statements as the mechanism to make parts of a schema optional. Published standard YANG modules 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 'includes/feature' leaf-list, which allows the package to define a set of features that MUST be enabled by any conformant implementation of the package as a mechanism to simplify and manage the schema represented by a YANG package.¶
Using the YANG semantic versioning scheme for package version numbers and module version 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.¶
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 with the 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 'example-foo' package at version 1.0.0 should interoperate with a server implementing 'example-foo' package at version 1.3.5, because the YANG semantic versioning rules require that package version 1.3.5 is backwards compatible with 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, particularly if they can avoid non-backwards-compatible patch level changes.¶
[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.¶
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:¶
Hence, YANG modules and packages published to define standard or reusable functionality MUST NOT use deviation statements to modify definitions in other published YANG modules. This restriction does not apply to server implementation packages that use deviation modules to report implementation non-conformance, as described in Section 7.3.¶
As defined by NMDA [RFC8342], each datastore has an associated datastore schema. These datastore schemas can be advertised by servers using YANG Library [RFC8525], augmented with the associated YANG package information, as per Section 5.4.3. Sections 5.1 and 5.3 of NMDA define 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 schemas 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.¶
Given that YANG packages represent a schema, it follows that each datastore schema can be represented using packages. In addition, the schemas 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 schemas 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 MAY be included in the package for configuration datastores if that helps unify the package definitions.¶
The packages for the operational datastore schema SHOULD 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 that relies on the automatic resolution of module versions.¶
The resolved package schema representing a datastore MUST be referentially complete.¶
Clients fetch the package information from the server (if required), and then can use tools to generate the resolved package schema. The resolved package schema may list multiple versions of the same package (if included with different versions), and it may list package versions that are not completely implemented by the device. By using package schema comparison, as described below, tooling can report on the level of conformance for each package and included package version advertised by the device.¶
YANG package schema comparison tools (and also documentation) can be used to determine how closely a device implements particular YANG package definitions advertised by the device. The tooling, by resolving the package definition and comparing the resulting compiled schema trees using [I-D.ietf-netmod-yang-schema-comparison], can determine the compatibility of the implemented schema with the package schema. Comparisons between package versions are described in Section 6.1. Tools can also report differences in the module versions, features, deviations and mounts to help explain the comparison results.¶
The YANG module definitions for the modules described in the previous sections follow. Some of these modules use the YANG Data Structure Extensions defined in [RFC8791]. The module file names follow the convention defined in [I-D.ietf-netmod-yang-module-filename].¶
RFC Editor note: Before publication, update the revision dates of all YANG modules in this section to the RFC publication date. Check the modules for "RFC XXXX" placeholders and replace each with the assigned RFC number. References titled "YANG Packages" and unqualified occurrences refer to this document. References titled "Updated YANG Module Revision Handling" or "YANG Semantic Versioning" refer to the corresponding documents. Verify referenced section numbers. When updating the modules to version 1.0.0, remove each "ys:recommended-min-version" statement whose imported module has only one published version. Remove this note before publication.¶
The "ietf-yang-package-types" module imports "ietf-yang-revisions" [I-D.ietf-netmod-yang-module-versioning], "ietf-yang-semver" [I-D.ietf-netmod-yang-semver], "ietf-yang-types" [RFC9911], and "ietf-inet-types" [RFC9911].¶
The 'pkg-ypath' typedef uses the Ypath definition from [I-D.jgc-netmod-yang-path].¶
<CODE BEGINS> file "ietf-yang-package-types@0.10.0.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 {
prefix rev;
reference "RFC XXXX: Updated YANG Module Revision Handling";
}
import ietf-yang-semver {
prefix ys;
reference "RFC XXXX: YANG Semantic Versioning";
}
import ietf-yang-types {
prefix yang;
rev:recommended-min-date 2025-12-22;
reference "RFC 9911: Common YANG Data Types.";
}
import ietf-inet-types {
prefix inet;
rev:recommended-min-date 2025-12-22;
reference "RFC 9911: Common YANG Data Types.";
}
organization
"IETF NETMOD (Network Modeling) Working Group";
contact
"WG Web: <https://datatracker.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org>
Editor: Robert Wilton
<mailto:rwilton@cisco.com>";
description
"This module provides type and grouping definitions for YANG
packages.
Copyright (c) 2026 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 Revised BSD License set
forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(https://trustee.ietf.org/license-info).
All revisions of IETF and IANA published modules can be found
at the YANG Parameters registry group
(https://www.iana.org/assignments/yang-parameters).
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.";
revision 2026-07-06 {
ys:version 0.10.0;
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 versioned using YANG Semver version labels.";
}
typedef pkg-reference {
type string {
pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*@'
+ '[0-9]+[.][0-9]+[.][0-9]+(_(non_)?compatible)?'
+ '(-[A-Za-z0-9.-]+)?([+][A-Za-z0-9.-]+)?';
pattern '[^@]+@.{5,128}';
}
description
"Identifies an exact package version as
'<package-name>@<version>'.
The name MUST conform to pkg-name and the version MUST conform
to pkg-version. Exactly one '@' separates the two components.
The reference does not include a filename extension
or location.";
}
typedef module-name {
type yang:yang-identifier;
description
"Module names are typed as YANG identifiers.";
}
typedef version-or-rev-date {
type union {
type rev:revision-date;
type ys:version;
}
description
"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 defined by Section 12 of RFC 6020.";
reference
"RFC XXXX: YANG Packages";
}
typedef pkg-ypath {
type string;
description
"A Ypath, as defined in draft-jgc-netmod-yang-path, that
identifies a set of data nodes in the schema tree.
TODO - Check whether any further constraints on the Ypath
definition are required for use in YANG packages.";
reference
"draft-jgc-netmod-yang-path: YANG path format (ypath)";
}
/*
* 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 identifies a particular version of a YANG package.
Follows the definition of YANG Semver version identifiers.";
reference
"RFC XXXX: YANG Semantic Versioning, Section 4.3";
}
}
grouping yang-pkg-exclusions {
description
"Parameters for excluding modules and packages from a YANG
package definition";
container excludes {
description
"Contains parameters for excluding modules and packages
from a YANG package definition";
leaf-list module {
type module-name;
must "not(. = ../../includes/module/name)" {
error-message
"A module cannot be both included and excluded.";
}
description
"Lists implemented modules, of any version, that may
have been brought in by included packages, but are
explicitly excluded from this package definition.
Excluding a module can affect the compliance and
correctness of any included packages that expect that
module to be implemented.
Excluding a module also implicitly excludes any submodules
and enabled features defined in the excluded module.
It is an error to list a module in both this list and the
'includes/module' list.";
}
list import-only-module {
must
"not(../../includes/import-only-module"
+ "[name = current()/name]"
+ "[version = current()/version])" {
error-message
"An import-only module cannot be included and excluded"
+ " with the same name and version values.";
}
must
"version or not(../../includes/import-only-module"
+ "[name = current()/name])" {
error-message
"An exclusion of all versions conflicts with an included"
+ " import-only module with the same name.";
}
key "name";
description
"Lists import-only modules that may have been brought
in by included packages, but are explicitly excluded from
this package definition.
It is an error to list the same module version in both
this list and the 'includes/import-only-module' list. If
no versions are listed for an entry in this list, then
that entry excludes all versions of the import-only
module and it is an error to list the same module name in
the 'includes/import-only-module' list.";
leaf name {
type module-name;
mandatory true;
description
"The name of the import-only module to exclude some
versions of.";
}
leaf-list version {
type version-or-rev-date;
description
"Lists specific versions of the import-only module being
excluded. If no versions are listed, all versions of
the import-only module are excluded.
If required, the YANG Semantic Version SHOULD be used
to identify the module version, otherwise the YANG
module revision date is used.";
}
}
leaf-list feature {
type scoped-feature;
must "not(. = ../../includes/feature)" {
error-message
"A feature cannot be both included and excluded.";
}
description
"Lists features from the 'includes/feature' leaf-list
exported by an included package that are reclassified as
being OPTIONAL to support by any server implementing the
package, overriding the behavior specified by the included
package.
It is an error to list a feature in both this leaf-list and
the 'includes/feature' leaf-list.";
}
}
}
grouping yang-pkg-location {
description
"Parameters for locating a YANG package instance";
leaf-list location {
type inet:uri;
ordered-by user;
description
"Contains a URL that represents where a YANG package file
(.ypkg) 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 a canonical location for this package is provided,
it MUST be the first entry in the leaf-list.";
}
}
grouping submodule-identification-leafs {
description
"Defines the data nodes for representing a submodule reference
in a YANG package definition.";
list submodule {
key "name";
description
"Each entry represents one submodule within the
parent module.";
leaf name {
type module-name;
mandatory true;
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;
ordered-by user;
description
"Contains a URL from where the YANG schema resource for
this submodule can be retrieved.
If a canonical location for this submodule is provided,
it MUST be the first entry in the leaf-list.";
}
}
}
grouping module-and-submodule-identification-leafs {
description
"Defines the data nodes for representing a module reference
with its associated submodules.";
leaf name {
type module-name;
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
Semantic Version SHOULD be used, otherwise the YANG module
revision date is used.";
}
leaf-list location {
type inet:uri;
ordered-by user;
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.
If a canonical location for this module is provided,
it MUST be the first entry in the leaf-list.";
}
uses submodule-identification-leafs;
}
grouping yang-pkg-instance {
description
"Specifies the data node for a full YANG package instance
represented either on a server or in a YANG package file.";
uses yang-pkg-identification-leafs;
leaf version-description {
type string;
description
"An optional description of the package version. E.g.,
perhaps tying it to a software release or a description
of what key changes have occurred compared to the
previous version.";
}
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 this package's resolved schema is
referentially complete. I.e. all module imports can be
resolved to a module version in the resolved package
schema.";
reference
"RFC XXXX: YANG Packages, Section 3.3";
}
container includes {
description
"Lists package and modules that are included in the package
definition.";
list package {
key "name version";
ordered-by user;
description
"An entry in this list represents a package that is
included as part of the package definition.
A package MAY directly include multiple versions of the
same package, but normally only a single package version
is expected. Multiple package versions can be listed,
for example, to update location information for package
versions included through other packages.";
reference
"RFC XXXX: YANG Packages, Section 4";
uses yang-pkg-identification-leafs;
uses yang-pkg-location;
}
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.
An entry in this list overrides any module version
'implemented' by an included package.";
reference
"RFC 7950: The YANG 1.1 Data Modeling Language.";
uses module-and-submodule-identification-leafs;
}
list import-only-module {
key "name version";
description
"An entry in this list indicates that the server imports
reusable definitions from the specified version of the
module, but does not implement any protocol accessible
objects from this version.
This entry overrides any import-only module definition
with the same module name and version from an included
package.
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.";
uses module-and-submodule-identification-leafs;
}
leaf-list feature {
type scoped-feature;
description
"Lists features that MUST be supported by any server
implementing the package. Each feature MUST be defined
by the selected implemented version of its named module
in the resolved package schema, including any selected
submodules.
Enabled features specified by any directly included
packages MUST also be supported by server
implementations, unless excluded by an entry in the
'excludes/feature' leaf-list, and do not need to be
repeated in this leaf-list.
All other features defined in modules included in the
package are OPTIONAL to implement.";
}
}
uses yang-pkg-exclusions;
container depends-on {
description
"Provides metadata identifying packages that
this package depends on, but that do not form part of the
resolved package schema.
Dependency metadata is not inherited from included packages,
so dependencies applicable to this package must be stated
explicitly in this list.
For an incomplete package definition, this list can help a
client resolve a complete schema in a machine readable
way.";
reference
"RFC XXXX: YANG Packages, Section 3.2";
list package {
key "name version";
description
"An entry in this list represents a package that is
depended on by this package definition.";
uses yang-pkg-identification-leafs;
uses yang-pkg-location;
}
}
list mount {
key "mount-path";
description
"An entry in this list represents additions to the schema
found at the specified mount point, or, if
'inherit-mounted-schema' is 'false', replacement of the
inherited schema found at the specified mount point.";
leaf mount-path {
type pkg-ypath;
mandatory true;
description
"A Ypath, as defined in draft-jgc-netmod-yang-path, that
identifies a mount point within the package schema. If
this package is itself mounted, the path is interpreted
within that mounted schema, with its mount point as the
root, as specified in RFC 8528, Sections 3.4 and 4.
Mount paths MUST only be used for schema mount points
defined in the package schema.";
reference
"RFC XXXX: YANG Packages, Section 4;
draft-jgc-netmod-yang-path: YANG path format (ypath);
RFC 8528: YANG Schema Mount";
}
leaf inherit-mounted-schema {
type boolean;
default true;
description
"Indicates whether the mounted schema and all its
properties are inherited from mounts at the same
mount-path in 'includes/package' entries.
If set to true (the default), the schema is defined
as the union of the resolved package schema at the mount
point by any packages in the 'includes/package' list
combined with the resolved package schema of all packages
listed in the 'package' list, plus any additional
features and parent-references defined for the same
mount point. Read-only status and mount mode are also
inherited.
If set to false, then the mounted schema starts from a
blank slate and only packages, additional features, and
parent-references listed in this 'mount' entry are
included. If no packages are listed, no schema is mounted
at this mount point. This allows the definitions in the
mounted packages to be modified (e.g., remove or change
module versions). To help conformance, the packages
listed here SHOULD include all the packages that would
have been automatically included.
";
}
leaf read-only {
type boolean;
description
"If true, all data nodes in the mounted schema are
read-only. An explicit false value is a schema resolution
error if the inherited mount is read-only. If no value is
inherited or specified, the mount is read-write, subject
to the configuration restrictions of RFC 8528.
See 'inherit-mounted-schema' for inheritance behavior.";
reference
"RFC XXXX: YANG Packages, Sections 3.5 and 4;
RFC 8528: YANG Schema Mount, Section 3.3";
}
leaf mount-mode {
type enumeration {
enum inline {
description
"Mount instances may use different schemas, as defined
by the 'inline' case in RFC 8528.";
}
enum shared-schema {
description
"All instances of the mount point use the same schema,
as defined by the 'shared-schema' case in RFC 8528.";
}
}
description
"The Schema Mount mode for this mount point. An explicit
value that conflicts with an inherited mode is a schema
resolution error. If no mode is inherited or specified,
'shared-schema' is used.
See 'inherit-mounted-schema' for inheritance behavior.";
reference
"RFC XXXX: YANG Packages, Section 4;
RFC 8528: YANG Schema Mount, Section 3.3";
}
list package {
key "name version";
ordered-by user;
description
"The packages that will be mounted at the specified mount
path.
A mount point MAY directly list multiple versions of the
same package, but normally only a single package version
is expected. Multiple package versions can be listed,
for example, to update location information for package
versions inherited from included packages.
With mounted-package inheritance enabled (the default),
these packages are mounted in addition to the mounted
packages from the 'includes/package' list.
With mounted-package inheritance disabled, these packages,
together with any additional features and parent-references
in the same 'mount' entry, define the mounted package
schema at this mount point.
Also see the 'inherit-mounted-schema' leaf.";
reference
"RFC XXXX: YANG Packages, Section 4";
uses yang-pkg-identification-leafs;
uses yang-pkg-location;
}
leaf-list feature {
type scoped-feature;
description
"Features listed here are enabled at the mount point in
addition to those enabled by the resolved mounted packages
and, when 'inherit-mounted-schema' is true, by inherited
'mount/feature' entries.
This list does not identify the complete set of supported
features but features already enabled by the resolved
inherited mounts MAY be listed.
The features listed here MUST be defined by implemented
modules in the resolved mounted package schema.
Features are identified using
<module-name>:<feature-name>.
";
}
leaf-list parent-reference {
type pkg-ypath;
description
"A Ypath, as defined in draft-jgc-netmod-yang-path, that
identifies data nodes in the schema containing the mount
point, accessible from the mounted schema for the
evaluation of XPath expressions.
Parent-references apply only to shared-schema mounts.
See parent-reference in Schema Mount (RFC 8528) for a
more detailed description of the accessible data nodes.";
reference
"draft-jgc-netmod-yang-path: YANG path format (ypath);
RFC 8528: YANG Schema Mount";
}
}
}
}
<CODE ENDS>¶
The "ietf-ypkg" module imports "ietf-yang-semver" [I-D.ietf-netmod-yang-semver], "ietf-yang-package-types" defined in this document, "ietf-yang-structure-ext" [RFC8791], and "ietf-inet-types" [RFC9911].¶
RFC Editor note: Before publication, confirm with IANA the implicit schema download location described in the "ietf-ypkg" module below and Section 5.5. Update the URL prefix to the agreed IANA location if needed, and update the default reference schema identifier to "ietf-ypkg-schema@1.0.0". Remove this note before publication.¶
<CODE BEGINS> file "ietf-ypkg@0.10.0.yang"
module ietf-ypkg {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-ypkg";
prefix ypkg;
import ietf-yang-semver {
prefix ys;
reference "RFC XXXX: YANG Semantic Versioning";
}
import ietf-yang-package-types {
prefix pkg-types;
ys:recommended-min-version 0.10.0;
reference "RFC XXXX: YANG Packages";
}
import ietf-yang-structure-ext {
prefix sx;
reference "RFC 8791: YANG Data Structure Extensions.";
}
import ietf-inet-types {
prefix inet;
reference "RFC 9911: Common YANG Data Types";
}
organization
"IETF NETMOD (Network Modeling) Working Group";
contact
"WG Web: <https://datatracker.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org>
Editor: Robert Wilton
<mailto:rwilton@cisco.com>";
description
"This module defines the structure of a YANG package file
encoded using the JSON encoding specified in RFC 7951.
Copyright (c) 2026 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 Revised BSD License set
forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(https://trustee.ietf.org/license-info).
All revisions of IETF and IANA published modules can be found
at the YANG Parameters registry group
(https://www.iana.org/assignments/yang-parameters).
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.";
revision 2026-07-06 {
ys:version 0.10.0;
description
"Initial revision";
reference
"RFC XXXX: YANG Packages";
}
/*
* Package file grouping and structure
*/
grouping yang-package-file {
description
"Defines a schema reference and a complete
package definition.";
leaf schema {
type pkg-types:pkg-reference;
description
"Identifies the package defining the schema for the entire
package file as '<package-name>@<version>', including the
envelope and any extensions. The referenced schema MUST be
referentially complete. If absent, the reference schema
defined in RFC XXXX applies. The schema package version
identifies the file format; no separate format version
is required.";
}
leaf-list schema-location {
type inet:uri;
ordered-by user;
description
"URLs from which the schema package identified by 'schema',
or the default reference schema when 'schema' is absent,
can be retrieved. A retrieved package's name and version
MUST match the schema package reference. If a canonical
location is provided, it MUST be the first entry.
If no location is specified, the schema package MUST be
available to download at the URL formed by appending
'<pkg-name>@<pkg-version>.ypkg' to
'https://www.iana.org/assignments/yang-parameters/', using
the name and version of the explicitly identified or
default schema package. Otherwise, at least one download
URL MUST be provided in this leaf-list.";
}
container pkg-defn {
description
"The complete package definition carried by this file.";
uses pkg-types:yang-pkg-instance;
}
}
sx:structure yang-package {
must "pkg-defn" {
error-message
"A package file must contain a package definition.";
}
description
"Defines a YANG package file. All applicable YANG constraints
and package definition rules MUST be satisfied.
Values equal to their applicable YANG defaults MAY be
explicitly encoded, but SHOULD be omitted.";
uses yang-package-file;
}
}
<CODE ENDS>¶
The "ietf-yang-package" module imports "ietf-yang-semver" [I-D.ietf-netmod-yang-semver] and "ietf-yang-package-types" defined in this document.¶
<CODE BEGINS> file "ietf-yang-packages@0.10.0.yang"
module ietf-yang-packages {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-packages";
prefix pkgs;
import ietf-yang-semver {
prefix ys;
reference "RFC XXXX: YANG Semantic Versioning";
}
import ietf-yang-package-types {
prefix pkg-types;
ys:recommended-min-version 0.10.0;
reference "RFC XXXX: YANG Packages";
}
organization
"IETF NETMOD (Network Modeling) Working Group";
contact
"WG Web: <https://datatracker.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org>
Editor: Robert Wilton
<mailto:rwilton@cisco.com>";
description
"This module defines YANG packages on a server implementation.
Copyright (c) 2026 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 Revised BSD License set
forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(https://trustee.ietf.org/license-info).
All revisions of IETF and IANA published modules can be found
at the YANG Parameters registry group
(https://www.iana.org/assignments/yang-parameters).
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.";
revision 2026-07-06 {
ys:version 0.10.0;
description
"Initial revision";
reference
"RFC XXXX: YANG Packages";
}
/*
* Groupings
*/
grouping yang-pkg-ref {
description
"Defines the leaves used to reference a single entry in the
top-level '/pkgs:packages/pkgs:package' list.";
leaf name {
type leafref {
path '/pkgs:packages/pkgs:package/pkgs:name';
}
description
"The name of the referenced package in the top-level
'/pkgs:packages/pkgs:package' list.";
}
leaf version {
type leafref {
path '/pkgs:packages'
+ '/pkgs:package[pkgs:name = current()/../name]'
+ '/pkgs:version';
}
description
"The version of the referenced package in the top-level
'/pkgs:packages/pkgs:package' list.";
}
}
/*
* Top level data nodes.
*/
container packages {
config false;
description "All YANG package definitions";
list package {
key "name version";
description
"YANG package instance";
uses pkg-types:yang-pkg-instance;
}
}
}
<CODE ENDS>¶
The "ietf-yl-packages" module imports "ietf-yang-revisions" [I-D.ietf-netmod-yang-module-versioning], "ietf-yang-semver" [I-D.ietf-netmod-yang-semver], "ietf-yang-package-types" and "ietf-yang-packages" defined in this document, and "ietf-yang-library" [RFC8525].¶
<CODE BEGINS> file "ietf-yl-packages@0.10.0.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 "RFC XXXX: Updated YANG Module Revision Handling";
}
import ietf-yang-semver {
prefix ys;
reference "RFC XXXX: YANG Semantic Versioning";
}
import ietf-yang-package-types {
prefix pkg-types;
ys:recommended-min-version 0.10.0;
reference "RFC XXXX: YANG Packages";
}
import ietf-yang-packages {
prefix pkgs;
ys:recommended-min-version 0.10.0;
reference "RFC XXXX: YANG Packages";
}
import ietf-yang-library {
prefix yanglib;
rev:recommended-min-date 2019-01-04;
reference "RFC 8525: YANG Library";
}
organization
"IETF NETMOD (Network Modeling) Working Group";
contact
"WG Web: <https://datatracker.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org>
Editor: Robert 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) 2026 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 Revised BSD License set
forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(https://trustee.ietf.org/license-info).
All revisions of IETF and IANA published modules can be found
at the YANG Parameters registry group
(https://www.iana.org/assignments/yang-parameters).
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.";
revision 2026-07-06 {
ys:version 0.10.0;
description
"Initial revision";
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.
Features enabled by the server in addition to the mandatory
features from the package definitions are listed in the
'feature' list.
";
list package {
key "name version";
ordered-by user;
description
"Identifies the YANG packages that collectively define the
schema for the associated datastore.
The referenced packages are resolved as if they were all
directly included in a single package definition, as
described in RFC XXXX, Section 5.4.3.
The resolved datastore schema MUST be referentially
complete.";
reference
"RFC XXXX: YANG Packages, Section 5.4.3";
uses pkgs:yang-pkg-ref;
uses pkg-types:yang-pkg-location;
}
leaf-list feature {
type pkg-types:scoped-feature;
description
"The name of YANG features enabled by the server in addition
to the enabled features from the resolved package
definitions associated with this datastore schema.
Although this list identifies additional features rather
than the complete set of supported features, features
already enabled by the resolved packages MAY be listed.
The features listed here MUST be defined by implemented
modules in the datastore schema.
Features are identified using <module-name>:<feature-name>.
This list, combined with the enabled features from the
resolved package schemas, MUST be equivalent to the
list of supported features advertised in YANG library.";
}
}
}
<CODE ENDS>¶
The "ietf-yang-inst-data-pkg" module imports "ietf-yang-semver" [I-D.ietf-netmod-yang-semver], "ietf-yang-package-types" defined in this document, "ietf-yang-structure-ext" [RFC8791], and "ietf-yang-instance-data" [RFC9195].¶
<CODE BEGINS> file "ietf-yang-inst-data-pkg@0.10.0.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 "RFC XXXX: YANG Semantic Versioning";
}
import ietf-yang-package-types {
prefix pkg-types;
ys:recommended-min-version 0.10.0;
reference "RFC XXXX: YANG Packages";
}
import ietf-yang-structure-ext {
prefix sx;
reference "RFC 8791: YANG Data Structure Extensions.";
}
import ietf-yang-instance-data {
prefix yid;
reference "RFC 9195: YANG Instance Data File Format.";
}
organization
"IETF NETMOD (Network Modeling) Working Group";
contact
"WG Web: <https://datatracker.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org>
Editor: Robert 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) 2026 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 Revised BSD License set
forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(https://trustee.ietf.org/license-info).
All revisions of IETF and IANA published modules can be found
at the YANG Parameters registry group
(https://www.iana.org/assignments/yang-parameters).
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.";
revision 2026-07-06 {
ys:version 0.10.0;
description
"Initial revision";
reference
"RFC XXXX: YANG Packages";
}
/*
* Augmentations
*/
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 {
description
"Identifies the YANG package that defines the content
schema for this instance data set.";
leaf schema {
type pkg-types:pkg-reference;
mandatory true;
description
"Identifies the exact schema package as
'<package-name>@<version>'.";
}
uses pkg-types:yang-pkg-location;
}
}
}
}
<CODE ENDS>¶
The "ietf-yang-device-schema" module imports "ietf-yang-semver" [I-D.ietf-netmod-yang-semver], "ietf-yang-package-types" defined in this document, "ietf-datastores" [RFC8342], and "ietf-inet-types" [RFC9911].¶
<CODE BEGINS> file "ietf-yang-device-schema@0.1.0.yang"
module ietf-yang-device-schema {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-device-schema";
prefix yds;
import ietf-yang-semver {
prefix ys;
reference "RFC XXXX: YANG Semantic Versioning";
}
import ietf-yang-package-types {
prefix pkg-types;
ys:recommended-min-version 0.10.0;
reference "RFC XXXX: YANG Packages";
}
import ietf-datastores {
prefix ds;
reference "RFC 8342: Network Management Datastore Architecture";
}
import ietf-inet-types {
prefix inet;
reference "RFC 9911: Common YANG Data Types";
}
organization
"IETF NETMOD (Network Modeling) Working Group";
contact
"WG Web: <https://datatracker.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org>
Editor: Robert Wilton
<mailto:rwilton@cisco.com>";
description
"This module defines an advertisement of datastore schemas for
a device or operating system release, using references to
separate YANG package files. This module is generally expected
to be used within an RFC 9195 YANG instance data set.
Contact, organization, description, and document revision
metadata are carried in that instance data set.
Copyright (c) 2026 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 Revised BSD License set
forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(https://trustee.ietf.org/license-info).
All revisions of IETF and IANA published modules can be found
at the YANG Parameters registry group
(https://www.iana.org/assignments/yang-parameters).
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.";
revision 2026-10-12 {
ys:version 0.1.0;
description
"Initial revision";
reference
"RFC XXXX: YANG Packages";
}
container device-schema {
config false;
description
"A description of the datastore schemas for one device or
operating system release.";
leaf device {
type string;
mandatory true;
description
"The device, device family, or operating system schema
that is being specified.";
}
leaf release {
type string;
mandatory true;
description
"The software release or version to which this
advertisement applies. This is an opaque string and need
not be a YANG Semantic Version.";
}
leaf yang-library {
type inet:uri;
description
"A URI for an RFC 9195 instance data document containing
equivalent RFC 8525 YANG library data for this device and
release. Its datastore bindings and resolved schemas MUST
match this advertisement.";
}
list schema {
key "name";
min-elements 1;
description
"A referentially complete datastore schema that may be
shared by multiple datastores.";
leaf name {
type string;
description
"The name of the schema. This MUST be the same as the
name advertised by the device in YANG library.";
}
list package {
key "name version";
min-elements 1;
ordered-by user;
description
"References to separate YANG package files that
collectively define this schema. The resolved package
schema is constructed as per RFC XXXX, Section 5.4.3.
The resolved schema MUST be referentially complete.";
reference
"RFC XXXX: YANG Packages, Section 5.4.3";
uses pkg-types:yang-pkg-identification-leafs;
uses pkg-types:yang-pkg-location;
}
leaf-list feature {
type pkg-types:scoped-feature;
description
"Features enabled in addition to those enabled by the
resolved packages, identified as
'<module-name>:<feature-name>'. Each feature MUST be
defined by an implemented module in this schema.
Features already enabled by the packages MAY be listed.";
}
}
list datastore {
key "name";
min-elements 1;
description
"All datastores supported by this device or operating
system release, and their associated schemas. Datastores
with the same schema SHOULD reference the same entry.";
leaf name {
type ds:datastore-ref;
description
"The identity of the datastore.";
}
leaf schema {
type leafref {
path "../../schema/name";
}
mandatory true;
description
"The schema supported by this datastore.";
}
}
}
}
<CODE ENDS>¶
This section defines the default reference schema for YANG package files. It defines the entire "ietf-ypkg:yang-package" structure and MUST be referentially complete. Tools SHOULD recognize the root and schema reference defined by "ietf-ypkg" to select the schema before validating the package definition. This reference package omits its own schema reference and is interpreted using this default schema; recursive retrieval of a schema package is not required.¶
RFC Editor note: Before publication, check that every implemented and import-only module in this package definition references its latest published version, including the modules published in this document. Update the module version identifiers and location URLs as necessary, and check that all transitive imports are included so that the reference schema remains referentially complete. In particular, check that the revision dates for "ietf-yang-semver" and "ietf-yang-revisions" match the published YANG Semantic Versioning and Updated YANG Module Revision Handling modules. The authors and editors are willing to assist with checking and updating these module references and the package definition. Update this package's version and the versions of the YANG modules defined in this document to 1.0.0, and update references to those versions throughout the document, including package definitions and location URLs. This instruction applies to non-example versions starting with 0.x.y; retain the versions of example packages and modules. Remove this note before publication.¶
<CODE BEGINS> file "ietf-ypkg-schema@0.1.0.ypkg"
=============== NOTE: '\' line wrapping per RFC 8792 ================
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "ietf-ypkg-schema",
"version": "0.1.0",
"timestamp": "2026-10-08T10:29:15Z",
"organization": "IETF",
"contact": "IESG",
"description": "Reference schema for YANG package files.",
"includes": {
"module": [
{
"name": "ietf-ypkg",
"version": "0.10.0",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-ypkg@0.10.0.yang"
]
}
],
"import-only-module": [
{
"name": "ietf-yang-package-types",
"version": "0.10.0",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-yang-package-types@0.10.0.yang"
]
},
{
"name": "ietf-yang-revisions",
"version": "2026-06-26",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-yang-revisions@2026-06-26.yang"
]
},
{
"name": "ietf-yang-semver",
"version": "0.25.0",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-yang-semver@0.25.0.yang"
]
},
{
"name": "ietf-yang-types",
"version": "2025-12-22",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-yang-types@2025-12-22.yang"
]
},
{
"name": "ietf-inet-types",
"version": "2025-12-22",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-inet-types@2025-12-22.yang"
]
},
{
"name": "ietf-yang-structure-ext",
"version": "2020-06-17",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-yang-structure-ext@2020-06-17.yang"
]
}
]
}
}
}
}
<CODE ENDS>¶
This document defines YANG modules for defining YANG schema, that are often used to configure and monitor network devices.¶
The document defines three YANG modules that are accessible from devices, and the normal YANG network management security considerations apply, which are further described below, in Section 10.1.¶
YANG packages also offer an alternative mechanism to YANG Library [RFC8525] for reporting YANG schema, and hence the security considerations from that document also apply to the use of YANG packages. As per the YANG library security considerations, the module and version 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.¶
The "ietf-ypkg" module defines YANG package files, which are outside the security controls of network management protocols. Access to these files should be controlled where they expose sensitive information, and consumers should verify their source and integrity. The "ietf-yang-inst-data-pkg" module allows packages to define schemas for RFC 9195 instance data files, for which the security considerations of [RFC9195] apply. The "ietf-yang-device-schema" module likewise defines off-device instance data, outside network management protocol security controls. Consumers should verify the source and integrity of advertisements and referenced package and YANG library files before relying on their contents.¶
This section is modeled after the template described in Section 3.7 of [RFC9907].¶
The "ietf-yang-package-types", "ietf-yang-packages" and "ietf-yl-packages" YANG modules define data models that are designed to be accessed via YANG-based management protocols, such as NETCONF [RFC6241] and RESTCONF [RFC8040]. These YANG-based management protocols (1) have to use a secure transport layer (e.g., SSH [RFC6242], TLS [RFC8446], and QUIC [RFC9000]) and (2) have to use mutual authentication.¶
The Network Configuration Access Control Model (NACM) [RFC8341] 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.¶
Some of the readable data nodes in this YANG module 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. Specifically, the following subtrees and data nodes have particular sensitivities/ vulnerabilities:¶
There are no particularly sensitive readable data nodes.¶
Modules that use the groupings that are defined in this document should identify the corresponding security considerations. For example, reusing some of these groupings will expose privacy-related information (e.g., 'yang-pkg-instance').¶
YANG packages provide an alternative mechanism to YANG Library [RFC8525] for describing a server's implemented YANG schema. However, package support is not expected to replace YANG Library on servers. Devices are expected to continue supporting YANG Library for clients that are not package-aware, and package-aware clients may still use YANG Library information when resolving or validating the effective datastore schema.¶
Device vendors and package publishers should take care when making non-backwards-compatible (NBC) package changes, since such changes can be impactful to clients that depend on the prior package schema. Where NBC changes are necessary, it is better to make them clear and transparent through the package version number. The "version-description" leaf can also be used to highlight important NBC changes, such as removed modules, removed enabled features, down-referenced modules or packages, or new deviations that restrict the schema. NBC changes should still be minimized where practical.¶
Package resolution is generally expected to be performed off-device using tooling rather than by the managed device itself. To support this, package definitions should be made available off-device as ".ypkg" package files using stable URIs. Stable locations allow operators, clients, and tooling to retrieve package definitions, resolve package dependencies, compare package versions, and validate schemas without relying on repeated retrieval of schema information from the device.¶
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¶
Registrant Contact: The IESG.¶
XML: N/A, the requested URI is an XML namespace.¶
URI: urn:ietf:params:xml:ns:yang:ietf-ypkg¶
Registrant Contact: The IESG.¶
XML: N/A, the requested URI is an XML namespace.¶
URI: urn:ietf:params:xml:ns:yang:ietf-yang-packages¶
Registrant Contact: The IESG.¶
XML: N/A, the requested URI is an XML namespace.¶
URI: urn:ietf:params:xml:ns:yang:ietf-yl-packages¶
Registrant Contact: The IESG.¶
XML: N/A, the requested URI is an XML namespace.¶
URI: urn:ietf:params:xml:ns:yang:ietf-yang-inst-data-pkg¶
Registrant Contact: The IESG.¶
XML: N/A, the requested URI is an XML namespace.¶
URI: urn:ietf:params:xml:ns:yang:ietf-yang-device-schema¶
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¶
Maintained by IANA? N¶
Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-package-types¶
Prefix: pkg-types¶
Reference: RFC XXXX¶
Name: ietf-ypkg¶
Maintained by IANA? N¶
Namespace: urn:ietf:params:xml:ns:yang:ietf-ypkg¶
Prefix: ypkg¶
Reference: RFC XXXX¶
Name: ietf-yang-packages¶
Maintained by IANA? N¶
Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-packages¶
Prefix: pkgs¶
Reference: RFC XXXX¶
Name: ietf-yl-packages¶
Maintained by IANA? N¶
Namespace: urn:ietf:params:xml:ns:yang:ietf-yl-packages¶
Prefix: yl-pkgs¶
Reference: RFC XXXX¶
This document requests that IANA create a registry for IETF YANG packages, that lists all versions of all YANG package definitions published by the IETF, and provides a reliable location to store the YANG package definitions.¶
The name of the registry is "YANG Package Names" in the "YANG Parameters" registry group.¶
IANA is requested to establish a known, stable HTTPS download location for the registered YANG package files. Each registered package version should be available at a stable URL, with its filename following the rules in Section 5.5. The requested URL format is "https://www.iana.org/assignments/yang-parameters/<pkg-name>@<pkg-version>.ypkg". The registry should link to these URLs. IANA is requested to confirm this download location, including that of the initial "ietf-ypkg-schema" package, before RFC publication so that the implicit schema download URL in Section 5.5 and the "ietf-ypkg" module can be updated if necessary.¶
The registry shall record for each entry:¶
the name of the YANG package¶
a brief description of the package purpose¶
The latest published package version¶
A list of all published package versions, each hyperlinked to the location where a package file, Section 5.5, for that package definition may be retrieved from.¶
a reference to the package documentation (e.g., the RFC number)¶
On creation of the registry, the following packages should be added:¶
ietf-device-schema@0.1.0.ypkg, defined in Section 5.6.1.¶
For allocation, the registration policy is Specification Required, as defined in [RFC8126]. All registered YANG package names must comply with the rules for identifiers stated in Section 6.2, and must have a package name prefix.¶
Designated experts should verify that the specification clearly explains the purpose of the package and describes its main content.¶
The package name prefix 'ietf-' is reserved for YANG packages managed and published under the IETF stream [RFC4844], while the package name prefix 'irtf-' is reserved for YANG packages defined by the IRTF stream. Packages published in other RFC streams must use a similar suitable prefix.¶
All package names in the registry must be unique.¶
This document requests IANA to register the following media type, following the procedures of [RFC6838]:¶
Type name: application¶
Subtype name: yang-package+json¶
Required parameters: N/A¶
Optional parameters: N/A¶
Encoding considerations: 8bit; YANG package files are encoded in UTF-8.¶
Security considerations: See the Security Considerations section of RFC XXXX.¶
Interoperability considerations: N/A¶
Published specification: RFC XXXX¶
Applications that use this media type: YANG tooling and servers that generate or consume YANG package files.¶
Additional information:¶
Person & Email address to contact for further information: NETMOD WG (mailto:netmod@ietf.org)¶
Intended usage: COMMON¶
Restrictions on usage: N/A¶
Author: IETF¶
Change controller: IESG¶
Feedback helping shape this document has kindly been provided by Andy Bierman, James Cumming, Mahesh Jethanandani, Maria Matějka, Balazs Lengyel, Ladislav Lhotka, and Jan Lindblad.¶
Bo Wu acted as a temporary editor for earlier versions of this work.¶
This document has been reviewed by large language models (LLMs), including Anthropic Claude and ChatGPT Codex. Markup and prose have been produced using ChatGPT Codex and reviewed by the authors. The final content remains the responsibility of the authors.¶
This section provides various examples of YANG packages, and as such this text is non-normative. The purpose of the examples is to illustrate the file format of YANG packages, how package dependencies, exclusions, and package mounts 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.¶
The initial examples, in Appendix A.1, illustrate small, but complete YANG package definitions. For the remaining examples, the focus is on illustrating particular features of YANG packages, and so whilst the packages are complete and will compile, they leave out some of the optional fields. Locations may be omitted for clarity where they do not help illustrate the example. The complete examples linked from this appendix retain location information.¶
Long lines in examples are wrapped using the mechanism defined in [RFC8792].¶
This section provides some very simple examples of YANG package definitions that may be published by an SDO, illustrated using the YANG package file format defined in Section 5.5. The version numbers chosen are somewhat arbitrary, and illustrative. Locations are shown for both versions of the basic types package and omitted from the other definitions for clarity.¶
| Package | Versions | Content Overview |
|---|---|---|
| example-base-types | 1.0.0, 1.1.0 | Base IETF and IANA type modules. |
| example-network-device | 1.1.2 | Basic network device system, interface, access control, key chain, IP, NETCONF with NMDA support, YANG library, and package advertisement modules. |
| example-routing-types | 1.0.0 | Routing and BGP type modules. |
| example-routing | 1.3.1 | Basic routing, routing policy, BGP, and ACL modules. |
A very simple package with no dependencies on other packages that illustrates how a basic types package might be defined. In this case, the module dependencies have been declared as import-only, but they could also have been declared as implemented modules.¶
<CODE BEGINS> file "example-base-types@1.0.0.ypkg"
=============== NOTE: '\' line wrapping per RFC 8792 ================
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "example-base-types",
"version": "1.0.0",
"timestamp": "2026-03-20T17:52:47.188322Z",
"organization": "IETF NETMOD Working Group",
"contact": "WG Web: <http://tools.ietf.org/wg/netmod/>, WG \
List: <mailto:netmod@ietf.org>",
"description": "Example package containing base IETF and IANA \
type modules",
"reference": "XXX, draft-ietf-netmod-yang-packages",
"includes": {
"import-only-module": [
{
"name": "ietf-yang-types",
"version": "2010-09-24",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-yang-types@2010-09-24.yang"
]
},
{
"name": "ietf-inet-types",
"version": "2010-09-24",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-inet-types@2010-09-24.yang"
]
},
{
"name": "ietf-netconf-acm",
"version": "2012-02-22",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-netconf-acm@2012-02-22.yang"
]
}
]
}
}
}
}
<CODE ENDS>¶
An updated version of the basic types package that includes updated versions of the types modules and follows the YANG Semver versioning rules.¶
<CODE BEGINS> file "example-base-types@1.1.0.ypkg"
=============== NOTE: '\' line wrapping per RFC 8792 ================
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "example-base-types",
"version": "1.1.0",
"version-description": "Updated to 2025 RFC module versions",
"timestamp": "2026-03-20T17:52:47.188373Z",
"description": "Example package containing base IETF and IANA \
type modules",
"reference": "XXX, draft-ietf-netmod-yang-packages",
"includes": {
"import-only-module": [
{
"name": "ietf-yang-types",
"version": "2025-12-22",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-yang-types@2025-12-22.yang"
]
},
{
"name": "ietf-inet-types",
"version": "2025-12-22",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-inet-types@2025-12-22.yang"
]
},
{
"name": "ietf-netconf-acm",
"version": "2018-02-14",
"location": [
"https://www.iana.org/assignments/yang-parameters/\
ietf-netconf-acm@2018-02-14.yang"
]
}
]
}
}
}
}
<CODE ENDS>¶
This section provides a YANG package file example of a Network Device YANG package.¶
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, NETCONF with NMDA support, YANG library, and package advertisement. It includes the package (and hence all modules, enabled features, etc.) from the example-base-types package. This package also enables the NETCONF writable-running feature, features for system authentication, including local users and RADIUS-based authentication, and enables IPv6 privacy autoconfiguration for the IP module.¶
As for all 'complete' YANG packages, all import dependencies are fully resolved. Modules standardized before YANG semantic versioning are referenced by revision date; modules with YANG Semver labels are referenced by those labels.¶
<CODE BEGINS> file "example-network-device@1.1.2.ypkg"
=============== NOTE: '\' line wrapping per RFC 8792 ================
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "example-network-device",
"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-ietf-netmod-yang-packages",
"includes": {
"package": [
{
"name": "example-base-types",
"version": "1.0.0"
}
],
"module": [
{
"name": "iana-crypt-hash",
"version": "2014-08-06"
},
{
"name": "ietf-system",
"version": "2014-08-06"
},
{
"name": "iana-if-type",
"version": "2026-03-17"
},
{
"name": "ietf-interfaces",
"version": "2018-02-20"
},
{
"name": "ietf-netconf-acm",
"version": "2018-02-14"
},
{
"name": "ietf-netconf",
"version": "2011-06-01"
},
{
"name": "ietf-netconf-nmda",
"version": "2019-01-07"
},
{
"name": "ietf-key-chain",
"version": "2017-06-15"
},
{
"name": "ietf-ip",
"version": "2018-02-22"
},
{
"name": "ietf-yang-library",
"version": "2019-01-04"
},
{
"name": "ietf-datastores",
"version": "2018-02-14"
},
{
"name": "ietf-yang-packages",
"version": "0.10.0"
},
{
"name": "ietf-yl-packages",
"version": "0.10.0"
},
{
"name": "ietf-yang-library-semver",
"version": "0.24.0"
}
],
"import-only-module": [
{
"name": "ietf-netconf-with-defaults",
"version": "2011-06-01"
},
{
"name": "ietf-origin",
"version": "2018-02-14"
},
{
"name": "ietf-yang-metadata",
"version": "2016-08-05"
},
{
"name": "ietf-yang-package-types",
"version": "0.10.0"
},
{
"name": "ietf-yang-revisions",
"version": "2026-06-26"
},
{
"name": "ietf-yang-semver",
"version": "0.25.0"
},
{
"name": "ietf-yang-types",
"version": "2025-12-22"
},
{
"name": "ietf-inet-types",
"version": "2025-12-22"
}
],
"feature": [
"ietf-netconf:writable-running",
"ietf-system:authentication",
"ietf-system:local-users",
"ietf-system:radius",
"ietf-system:radius-authentication",
"ietf-ip:ipv6-privacy-autoconf"
]
}
}
}
}
<CODE ENDS>¶
An example package that contains routing type modules used by the example routing package.¶
The package includes the updated basic types package for common IETF and IANA type modules.¶
The "ietf-routing-types" and "ietf-bgp-types" modules are included as implemented modules, rather than import-only modules, because they define identities that may be referenced at runtime. An alternative design would be to include them as import-only modules and then require any package containing modules that reference those identities to re-include them as implemented modules.¶
<CODE BEGINS> file "example-routing-types@1.0.0.ypkg"
=============== NOTE: '\' line wrapping per RFC 8792 ================
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "example-routing-types",
"version": "1.0.0",
"timestamp": "2026-03-20T17:52:47.202513Z",
"description": "Example package containing routing types \
modules",
"includes": {
"package": [
{
"name": "example-base-types",
"version": "1.1.0"
}
],
"module": [
{
"name": "ietf-routing-types",
"version": "2017-12-04"
},
{
"name": "ietf-bgp-types",
"version": "2018-05-09"
}
],
"import-only-module": [
{
"name": "iana-routing-types",
"version": "2017-12-04"
}
]
}
}
}
}
<CODE ENDS>¶
This section provides a YANG package file example of a basic 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-network-device and example-routing-types YANG packages to add support for basic dynamic routing and ACLs. The package also enables ACL features for matching IPv6 packet fields and configuring IPv6 ACL entries, with the expectation that all devices that implement this package will support these features.¶
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 version.¶
<CODE BEGINS> file "example-routing@1.3.1.ypkg"
=============== NOTE: '\' line wrapping per RFC 8792 ================
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "example-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-ietf-netmod-yang-packages",
"includes": {
"package": [
{
"name": "example-network-device",
"version": "1.1.2"
},
{
"name": "example-routing-types",
"version": "1.0.0"
}
],
"module": [
{
"name": "ietf-routing",
"version": "2018-03-13"
},
{
"name": "ietf-ipv4-unicast-routing",
"version": "2018-03-13"
},
{
"name": "ietf-ipv6-unicast-routing",
"version": "2018-03-13"
},
{
"name": "ietf-isis",
"version": "2018-12-11"
},
{
"name": "ietf-interfaces-common",
"version": "2018-07-02"
},
{
"name": "ietf-if-l3-vlan",
"version": "2017-10-30"
},
{
"name": "ietf-routing-policy",
"version": "2018-10-19"
},
{
"name": "ietf-bgp",
"version": "2018-05-09"
},
{
"name": "ietf-access-control-list",
"version": "2018-11-06"
}
],
"import-only-module": [
{
"name": "ietf-packet-fields",
"version": "2018-11-06"
},
{
"name": "ietf-ethertypes",
"version": "2018-11-06"
}
],
"feature": [
"ietf-access-control-list:match-on-ipv6",
"ietf-access-control-list:ipv6"
]
}
}
}
}
<CODE ENDS>¶
This section provides examples of how a device may implement YANG packages, and advertise them to clients. It reuses some of the example packages defined in Appendix A.1, but extended with device implementation specific modifications to those packages.¶
This example illustrates a vendor's device-routing package that includes the example-routing package, and hence all its dependencies, but also removes a YANG module that is not implemented on the device, removes enabled features that are not supported, adds a YANG module containing deviations to other YANG modules, and adds a vendor device-isis-extensions YANG module, version 1.2.3, that augments the base ietf-isis module. Locations are omitted for clarity.¶
<CODE BEGINS> file "device-routing@1.0.0.ypkg"
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "device-routing",
"version": "1.0.0",
"timestamp": "2026-06-22T00:00:00Z",
"description": "Example vendor device routing package",
"reference": "XXX, draft-ietf-netmod-yang-packages",
"includes": {
"package": [
{
"name": "example-routing",
"version": "1.3.1"
}
],
"module": [
{
"name": "vendor-ietf-bgp-deviations",
"version": "2026-06-22"
},
{
"name": "device-isis-extensions",
"version": "1.2.3"
}
]
},
"excludes": {
"module": [
"ietf-if-l3-vlan"
],
"feature": [
"ietf-system:radius",
"ietf-system:radius-authentication"
]
}
}
}
}
<CODE ENDS>¶
The following abbreviated JSON shows the device's operational YANG library and package advertisement. The schema is bound to "device-routing" for both the running and operational datastores, and the package catalogue lists that package and its recursively included packages. Module and import-only module details are elided. Package entries retain their names, versions, and descriptions; all other package fields are elided. The deprecated "/modules-state" subtree is also omitted. Ellipsis strings indicate omitted data and are not literal values returned by the device. Complete package definitions are shown in the earlier examples.¶
The resolved package schema and the advertised module-set include the management modules used by this advertisement and match as required by Section 5.4.3.¶
The schema binding includes a package retrieval location. Other location information is omitted for clarity.¶
<CODE BEGINS> file "device-routing-library.json"
=============== NOTE: '\' line wrapping per RFC 8792 ================
{
"ietf-yang-library:yang-library": {
"module-set": [
{
"name": "device-module-set",
"module": [
"... implemented module details elided ..."
],
"import-only-module": [
"... import-only module details elided ..."
]
}
],
"schema": [
{
"name": "device-routing datastore schema",
"module-set": [
"device-module-set"
],
"ietf-yl-packages:package": [
{
"name": "device-routing",
"version": "1.0.0",
"location": [
"https://example.org/yang/packages/\
device-routing@1.0.0.ypkg"
]
}
]
}
],
"datastore": [
{
"name": "ietf-datastores:running",
"schema": "device-routing datastore schema"
},
{
"name": "ietf-datastores:operational",
"schema": "device-routing datastore schema"
}
],
"content-id": "924ff3012f0d1fef"
},
"ietf-yang-packages:packages": {
"package": [
{
"name": "device-routing",
"version": "1.0.0",
"description": "Example vendor device routing package",
"...": "package details elided"
},
{
"name": "example-routing",
"version": "1.3.1",
"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.",
"...": "package details elided"
},
{
"name": "example-network-device",
"version": "1.1.2",
"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.",
"...": "package details elided"
},
{
"name": "example-routing-types",
"version": "1.0.0",
"description": "Example package containing routing types \
modules",
"...": "package details elided"
},
{
"name": "example-base-types",
"version": "1.1.0",
"description": "Example package containing base IETF and \
IANA type modules",
"...": "package details elided"
},
{
"name": "example-base-types",
"version": "1.0.0",
"description": "Example package containing base IETF and \
IANA type modules",
"...": "package details elided"
}
]
}
}
<CODE ENDS>¶
RFC Editor note: Please confirm whether the GitHub link to the complete example below is permitted in the published RFC. The hotfix and example-c examples later in this appendix contain similar links; please review them consistently.¶
This example illustrates how a vendor can advertise a small hotfix package that updates one module in the device schema without publishing a complete replacement for the baseline device package. The hotfix package is marked as incomplete (i.e., "complete" = "false") because it contains only the updated device-isis-extensions module, and relies on the other packages bound to the datastore schema to provide the rest of the schema. The hotfix package lists the "device-routing" package in its "depends-on/package" list to identify the baseline device package that the hotfix applies to, without including that baseline package as part of the hotfix package definition.¶
The updated device-isis-extensions module uses version 1.2.4_compatible. This follows the YANG Semver versioning rules described in [I-D.ietf-netmod-yang-semver]. In this example, it is assumed that version 1.3.0 was not usable because it had previously been published with different content.¶
<CODE BEGINS> file "vendor-isis-hotfix@1.0.0.ypkg"
=============== NOTE: '\' line wrapping per RFC 8792 ================
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "vendor-isis-hotfix",
"version": "1.0.0",
"timestamp": "2026-06-22T00:00:00Z",
"description": "Example vendor ISIS hotfix package",
"reference": "XXX, draft-ietf-netmod-yang-packages;",
"complete": false,
"includes": {
"module": [
{
"name": "device-isis-extensions",
"version": "1.2.4_compatible",
"location": [
"https://example.org/yang/modules/\
device-isis-extensions@1.2.4_compatible.yang"
]
}
]
},
"depends-on": {
"package": [
{
"name": "device-routing",
"version": "1.0.0",
"location": [
"https://example.org/yang/packages/\
device-routing@1.0.0.ypkg"
]
}
]
}
}
}
}
<CODE ENDS>¶
When the hotfix package is used, the YANG library schema package binding lists both the baseline device package and the hotfix package, making use of automatic conflict resolution, as per Section 4.1, to automatically select the later version (1.2.4_compatible) of the device-isis-extensions YANG module. Both running and operational continue to reference the same datastore schema. The YANG library module-set contents would be updated so that the "device-module-set" contains device-isis-extensions version "1.2.4_compatible" rather than previous version, "1.2.3". The YANG library "content-id" would also change because the YANG library content has changed, and a yang-library-update notification would be generated.¶
The following abbreviated JSON shows the device's operational YANG library after applying the hotfix. Module and import-only module details are elided. Package entries retain their names, versions, and descriptions; all other package fields, including the hotfix's completeness flag, are elided. The deprecated "/modules-state" subtree is also omitted. Only the changed module and hotfix package are shown; other modules and package entries are elided. Ellipsis strings indicate omitted data and are not literal values returned by the device. Complete package definitions are shown in the earlier examples.¶
However, the goal is that the client doesn't need to fetch the updated YANG library information at all, and just rely on the advertised schema package bindings and the location URLs to fetch the packages and modules and fully resolve the schema off the device.¶
The hotfix package definition includes retrieval locations. Locations are omitted from its YANG library advertisement for clarity.¶
<CODE BEGINS> file "device-routing-hotfix-library.json"
{
"ietf-yang-library:yang-library": {
"module-set": [
{
"name": "device-module-set",
"module": [
{
"name": "device-isis-extensions",
"revision": "2026-06-22",
"namespace": "urn:example:yang:device-isis-extensions",
"ietf-yang-library-semver:version": "1.2.4_compatible"
},
"... other implemented module details elided ..."
],
"import-only-module": [
"... import-only module details elided ..."
]
}
],
"schema": [
{
"name": "device-routing datastore schema",
"module-set": [
"device-module-set"
],
"ietf-yl-packages:package": [
{
"name": "device-routing",
"version": "1.0.0"
},
{
"name": "vendor-isis-hotfix",
"version": "1.0.0"
}
]
}
],
"datastore": [
{
"name": "ietf-datastores:running",
"schema": "device-routing datastore schema"
},
{
"name": "ietf-datastores:operational",
"schema": "device-routing datastore schema"
}
],
"content-id": "9eadf0b2557adc16"
},
"ietf-yang-packages:packages": {
"package": [
{
"name": "vendor-isis-hotfix",
"version": "1.0.0",
"description": "Example vendor ISIS hotfix package",
"...": "package details elided"
},
"... other advertised package entries elided ..."
]
}
}
<CODE ENDS>¶
This section provides examples of versioning packages. The examples are non-normative, and for brevity only the relevant package definition fields are shown in the package files. Locations are omitted except for "example-routing-core" in versions 4.0.0 and 4.0.1, which illustrate adding a retrieval location.¶
The examples illustrate the history of a single package, "example-versioned-routing". Each example highlights whether the resolved package schema changes are backwards-compatible (BC), non-backwards-compatible (NBC), or editorial, based on the compiled schema tree comparison and separate assessment of mandatory enabled features in Section 6.1.1.¶
The following diagram summarizes the version lineage illustrated by the examples. The lineage is linear because these examples focus on successive updates to a single package definition.¶
1.0.0 - Initial published version
|
1.1.0 - BC: add package, module, and mandatory features
|
2.0.0 - NBC: downref package and remove module
|
3.0.0 - NBC: add module containing deviations
|
4.0.0 - NBC: remove IPv4 feature, downref module, and add module
|
4.0.1 - Editorial: update module location information
¶
The initial package version defines a small routing schema. This version is used as the starting point for the later examples.¶
<CODE BEGINS> file "example-versioned-routing@1.0.0.ypkg"
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "example-versioned-routing",
"version": "1.0.0",
"timestamp": "2026-06-22T00:00:00Z",
"description": "Example versioned routing package",
"reference": "XXX, draft-ietf-netmod-yang-packages",
"includes": {
"package": [
{
"name": "example-network-device",
"version": "1.1.2"
}
],
"module": [
{
"name": "example-routing-core",
"version": "2.0.0"
},
{
"name": "example-routing-acl",
"version": "1.0.0"
}
],
"feature": [
"example-routing-core:ipv4"
]
}
}
}
}
<CODE ENDS>¶
In version 1.1.0, a new included package, a new module, and new mandatory features are added. In this example, the compiled schema tree comparison reports only BC additions to the resolved package schema. The additions to the resolved set of mandatory enabled features are assessed separately and are also BC changes, so the minor version is incremented.¶
<CODE BEGINS> file "example-versioned-routing@1.1.0.ypkg"
=============== NOTE: '\' line wrapping per RFC 8792 ================
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "example-versioned-routing",
"version": "1.1.0",
"version-description": "Adds telemetry, policy, and new \
features.",
"timestamp": "2026-06-22T00:00:00Z",
"description": "Example versioned routing package",
"reference": "XXX, draft-ietf-netmod-yang-packages",
"includes": {
"package": [
{
"name": "example-network-device",
"version": "1.1.2"
},
{
"name": "example-routing-telemetry",
"version": "1.0.0"
}
],
"module": [
{
"name": "example-routing-core",
"version": "2.0.0"
},
{
"name": "example-routing-acl",
"version": "1.0.0"
},
{
"name": "example-routing-policy",
"version": "1.0.0"
}
],
"feature": [
"example-routing-core:ipv4",
"example-routing-core:ipv6",
"example-routing-policy:statistics"
]
}
}
}
}
<CODE ENDS>¶
In version 2.0.0, the "example-network-device" package reference is changed to an older package version, and the previously included "example-routing-acl" module is removed. In this example, the compiled schema tree comparison reports the removal of data nodes, making the package update NBC, so the major version is incremented. Selecting an older included package version does not by itself determine the compatibility of the package update.¶
<CODE BEGINS> file "example-versioned-routing@2.0.0.ypkg"
=============== NOTE: '\' line wrapping per RFC 8792 ================
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "example-versioned-routing",
"version": "2.0.0",
"version-description": "Downrefs a package and removes the \
ACL module.",
"timestamp": "2026-06-22T00:00:00Z",
"description": "Example versioned routing package",
"reference": "XXX, draft-ietf-netmod-yang-packages",
"includes": {
"package": [
{
"name": "example-network-device",
"version": "1.0.0"
},
{
"name": "example-routing-telemetry",
"version": "1.0.0"
}
],
"module": [
{
"name": "example-routing-core",
"version": "2.0.0"
},
{
"name": "example-routing-policy",
"version": "1.0.0"
}
],
"feature": [
"example-routing-core:ipv4",
"example-routing-core:ipv6",
"example-routing-policy:statistics"
]
}
}
}
}
<CODE ENDS>¶
In version 3.0.0, a new module containing deviations that modified some data nodes and marked other data nodes as not-supported. The deviations remove or restrict nodes that were present in the previous resolved package schema. The change is therefore NBC, and the major version is incremented.¶
<CODE BEGINS> file "example-versioned-routing@3.0.0.ypkg"
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "example-versioned-routing",
"version": "3.0.0",
"version-description": "Adds NBC vendor deviations.",
"timestamp": "2026-06-22T00:00:00Z",
"description": "Example versioned routing package",
"reference": "XXX, draft-ietf-netmod-yang-packages",
"includes": {
"package": [
{
"name": "example-network-device",
"version": "1.0.0"
},
{
"name": "example-routing-telemetry",
"version": "1.0.0"
}
],
"module": [
{
"name": "example-routing-core",
"version": "2.0.0"
},
{
"name": "example-routing-policy",
"version": "1.0.0"
},
{
"name": "vendor-routing-deviations",
"version": "2026-06-22"
}
],
"feature": [
"example-routing-core:ipv4",
"example-routing-core:ipv6",
"example-routing-policy:statistics"
]
}
}
}
}
<CODE ENDS>¶
In version 4.0.0, the mandatory "example-routing-core:ipv4" feature is removed and the "example-routing-core" module is changed to an older version. A new "example-isis" module is also added. Removing the mandatory feature is assessed separately as an NBC change; it does not remove the feature's conditional nodes from the schema comparison. In this example, the compiled schema tree comparison also reports NBC removals of data nodes from the module version change, as well as BC additions. The overall package update is therefore NBC, so the major version is incremented.¶
<CODE BEGINS> file "example-versioned-routing@4.0.0.ypkg"
=============== NOTE: '\' line wrapping per RFC 8792 ================
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "example-versioned-routing",
"version": "4.0.0",
"version-description": "Removes IPv4, downrefs core, adds \
ISIS.",
"timestamp": "2026-06-22T00:00:00Z",
"description": "Example versioned routing package",
"reference": "XXX, draft-ietf-netmod-yang-packages",
"includes": {
"package": [
{
"name": "example-network-device",
"version": "1.0.0"
},
{
"name": "example-routing-telemetry",
"version": "1.0.0"
}
],
"module": [
{
"name": "example-routing-core",
"version": "1.5.0",
"location": [
"https://example.org/yang/\
example-routing-core@1.5.0.yang"
]
},
{
"name": "example-routing-policy",
"version": "1.0.0"
},
{
"name": "vendor-routing-deviations",
"version": "2026-06-22"
},
{
"name": "example-isis",
"version": "1.0.0"
}
],
"feature": [
"example-routing-core:ipv6",
"example-routing-policy:statistics"
]
}
}
}
}
<CODE ENDS>¶
In version 4.0.1, the referenced module versions are unchanged, but an additional retrieval location for "example-routing-core" is added. The original location is retained. Both locations retrieve the same module file, so the module version is unchanged. This does not change the resolved package schema, so it is an editorial package update. The same classification would apply if the module version had already been resolved from an included package and the package explicitly listed that same module version only to provide updated location information.¶
<CODE BEGINS> file "example-versioned-routing@4.0.1.ypkg"
=============== NOTE: '\' line wrapping per RFC 8792 ================
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "example-versioned-routing",
"version": "4.0.1",
"version-description": "Updates module location information.",
"timestamp": "2026-06-22T00:00:00Z",
"description": "Example versioned routing package",
"reference": "XXX, draft-ietf-netmod-yang-packages",
"includes": {
"package": [
{
"name": "example-network-device",
"version": "1.0.0"
},
{
"name": "example-routing-telemetry",
"version": "1.0.0"
}
],
"module": [
{
"name": "example-routing-core",
"version": "1.5.0",
"location": [
"https://example.org/yang/\
example-routing-core@1.5.0.yang",
"https://mirror.example.org/yang/\
example-routing-core@1.5.0.yang"
]
},
{
"name": "example-routing-policy",
"version": "1.0.0"
},
{
"name": "vendor-routing-deviations",
"version": "2026-06-22"
},
{
"name": "example-isis",
"version": "1.0.0"
}
],
"feature": [
"example-routing-core:ipv6",
"example-routing-policy:statistics"
]
}
}
}
}
<CODE ENDS>¶
This section provides examples of package resolution. The examples are non-normative. Locations are omitted for clarity.¶
As described in Section 4, resolving a set of packages produces a YANG schema: a set of implemented modules, import-only modules, enabled features, deviations, and mount points. Included packages are recursively resolved first. The resulting package schemas are then combined using automatic module resolution, and finally any local module, import-only-module, feature, or exclusion entries in the including package are applied.¶
The following examples define two versions of a common package. The access package includes version 1.0.0 of that common package, while the routing package includes version 1.4.0. This illustrates that package resolution is performed on the resolved module sets, not by choosing one package version and discarding the other package version.¶
<CODE BEGINS> file "example-resolution-common@1.0.0.ypkg"
=============== NOTE: '\' line wrapping per RFC 8792 ================
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "example-resolution-common",
"version": "1.0.0",
"timestamp": "2026-06-22T00:00:00Z",
"description": "Example common package for resolution \
examples",
"reference": "XXX, draft-ietf-netmod-yang-packages",
"includes": {
"module": [
{
"name": "example-resolution-base",
"version": "1.0.0"
}
],
"import-only-module": [
{
"name": "example-resolution-types",
"version": "1.0.0"
}
],
"feature": [
"example-resolution-base:basic"
]
}
}
}
}
<CODE ENDS>¶
Resolved contents for "example-resolution-common" version 1.0.0:¶
Implemented modules: example-resolution-base@1.0.0.¶
Import-only modules: example-resolution-types@1.0.0.¶
Enabled features: example-resolution-base:basic.¶
Since this package does not include any other packages, the resolved package schema is the module, import-only module, and feature set that it directly defines.¶
<CODE BEGINS> file "example-resolution-common@1.4.0.ypkg"
=============== NOTE: '\' line wrapping per RFC 8792 ================
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "example-resolution-common",
"version": "1.4.0",
"timestamp": "2026-06-22T00:00:00Z",
"description": "Updated common package for resolution \
examples",
"reference": "XXX, draft-ietf-netmod-yang-packages",
"includes": {
"module": [
{
"name": "example-resolution-base",
"version": "1.4.0"
},
{
"name": "example-resolution-telemetry",
"version": "1.2.0"
}
],
"import-only-module": [
{
"name": "example-resolution-types",
"version": "1.4.0"
}
],
"feature": [
"example-resolution-base:basic",
"example-resolution-telemetry:events"
]
}
}
}
}
<CODE ENDS>¶
Resolved contents for "example-resolution-common" version 1.4.0:¶
Implemented modules: example-resolution-base@1.4.0, example-resolution-telemetry@1.2.0.¶
Import-only modules: example-resolution-types@1.4.0.¶
Enabled features: example-resolution-base:basic, example-resolution-telemetry:events.¶
This newer package version selects newer versions of the base and types modules, and adds the telemetry module and its enabled feature.¶
<CODE BEGINS> file "example-resolution-access@2.0.0.ypkg"
=============== NOTE: '\' line wrapping per RFC 8792 ================
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "example-resolution-access",
"version": "2.0.0",
"timestamp": "2026-06-22T00:00:00Z",
"description": "Example access package for resolution \
examples",
"reference": "XXX, draft-ietf-netmod-yang-packages",
"includes": {
"package": [
{
"name": "example-resolution-common",
"version": "1.0.0"
}
],
"module": [
{
"name": "example-resolution-acl",
"version": "1.1.0"
},
{
"name": "example-resolution-transport",
"version": "1.2.0"
}
],
"feature": [
"example-resolution-acl:ipv4"
]
}
}
}
}
<CODE ENDS>¶
Resolved contents for "example-resolution-access" version 2.0.0:¶
Included packages: example-resolution-common@1.0.0.¶
Implemented modules: example-resolution-base@1.0.0, example-resolution-acl@1.1.0, example-resolution-transport@1.2.0.¶
Import-only modules: example-resolution-types@1.0.0.¶
Enabled features: example-resolution-base:basic, example-resolution-acl:ipv4.¶
The included common package is resolved first, then the local ACL and transport modules and ACL feature are added.¶
<CODE BEGINS> file "example-resolution-routing@3.0.0.ypkg"
=============== NOTE: '\' line wrapping per RFC 8792 ================
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "example-resolution-routing",
"version": "3.0.0",
"timestamp": "2026-06-22T00:00:00Z",
"description": "Example routing package for resolution \
examples",
"reference": "XXX, draft-ietf-netmod-yang-packages",
"includes": {
"package": [
{
"name": "example-resolution-common",
"version": "1.4.0"
}
],
"module": [
{
"name": "example-resolution-acl",
"version": "1.3.0"
},
{
"name": "example-resolution-routing",
"version": "1.3.0"
},
{
"name": "example-resolution-transport",
"version": "1.2.0"
}
],
"feature": [
"example-resolution-routing:statistics"
]
}
}
}
}
<CODE ENDS>¶
Resolved contents for "example-resolution-routing" version 3.0.0:¶
Included packages: example-resolution-common@1.4.0.¶
Implemented modules: example-resolution-base@1.4.0, example-resolution-telemetry@1.2.0, example-resolution-acl@1.3.0, example-resolution-routing@1.3.0, example-resolution-transport@1.2.0.¶
Import-only modules: example-resolution-types@1.4.0.¶
Enabled features: example-resolution-base:basic, example-resolution-telemetry:events, example-resolution-routing:statistics.¶
The routing package includes the newer common package version, so its resolved package schema contains the newer base and import-only type modules, plus telemetry, routing, ACL, and transport modules. The transport module is the same version as in the access package.¶
The top-level device package includes both the access and routing packages. Recursively, this also brings in both versions of "example-resolution-common". There is no mechanism to exclude an included package. Instead, resolution operates on the modules and features contributed by those packages. This package locally selects version 1.1.0 of "example-resolution-acl", excludes the telemetry module, and excludes the routing statistics feature.¶
<CODE BEGINS> file "example-resolution-device@4.0.0.ypkg"
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "example-resolution-device",
"version": "4.0.0",
"timestamp": "2026-06-22T00:00:00Z",
"description": "Top-level package for resolution examples",
"reference": "XXX, draft-ietf-netmod-yang-packages",
"includes": {
"package": [
{
"name": "example-resolution-access",
"version": "2.0.0"
},
{
"name": "example-resolution-routing",
"version": "3.0.0"
}
],
"module": [
{
"name": "example-resolution-acl",
"version": "1.1.0"
}
]
},
"excludes": {
"module": [
"example-resolution-telemetry"
],
"feature": [
"example-resolution-routing:statistics"
]
}
}
}
}
<CODE ENDS>¶
Resolved contents for "example-resolution-device" version 4.0.0:¶
Included packages: example-resolution-access@2.0.0, example-resolution-routing@3.0.0, example-resolution-common@1.0.0, example-resolution-common@1.4.0.¶
Implemented modules: example-resolution-base@1.4.0, example-resolution-transport@1.2.0, example-resolution-acl@1.1.0, example-resolution-routing@1.3.0.¶
Import-only modules: example-resolution-types@1.0.0, example-resolution-types@1.4.0.¶
Enabled features: example-resolution-base:basic, example-resolution-acl:ipv4.¶
The common package is still listed at both versions because packages themselves are not excluded during resolution; instead, automatic module resolution selects example-resolution-base@1.4.0 from the two common package versions. The local module entry for example-resolution-acl@1.1.0 overrides the newer ACL version inherited from the routing package. The telemetry module is removed by the excludes/module leaf-list, which also removes its enabled feature. The routing statistics feature is explicitly removed by the excludes/feature leaf-list.¶
The "example-resolution-transport" module at version 1.2.0 is included via both the access and routing packages. The resolved package schema includes this module version only once.¶
This section provides examples of how to exclude implemented modules, import-only modules, and enabled features in a package definition. The examples are non-normative. Locations are omitted throughout this section for clarity.¶
The following example defines two YANG packages.¶
The first package, "example-ab", implements two example modules, "example-module-a" and "example-module-b", imports two related types modules, and declares two enabled features.¶
The second package, "example-c", includes the first package, but excludes the implemented "example-module-b" module, the import-only "example-module-b-types" module, and the enabled feature "foo" from "example-module-a". Excluding "example-module-b" also implicitly removes its enabled feature "bar"; the explicit feature exclusion is needed for "foo" because "example-module-a" remains implemented. The package also adds the implemented "example-module-c" module.¶
The third figure shows the resulting schema in YANG Library format, but with locations elided for brevity.¶
<CODE BEGINS> file "example-ab@0.1.0.ypkg"
=============== NOTE: '\' line wrapping per RFC 8792 ================
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "example-ab",
"version": "0.1.0",
"timestamp": "2026-03-20T17:52:47.188303Z",
"description": "Example package defining modules A, B and \
associated types",
"includes": {
"module": [
{
"name": "example-module-a",
"version": "1.0.0"
},
{
"name": "example-module-b",
"version": "1.1.0"
}
],
"import-only-module": [
{
"name": "example-module-a-types",
"version": "1.0.0"
},
{
"name": "example-module-b-types",
"version": "1.1.0"
}
],
"feature": [
"example-module-a:foo",
"example-module-b:bar"
]
}
}
}
}
<CODE ENDS>¶
The "example-c" YANG package example illustrates exclusions of modules, import-only-modules and features.¶
<CODE BEGINS> file "example-c@0.1.0.ypkg"
=============== NOTE: '\' line wrapping per RFC 8792 ================
{
"ietf-ypkg:yang-package": {
"pkg-defn": {
"name": "example-c",
"version": "0.1.0",
"timestamp": "2026-03-20T17:52:47.202747Z",
"description": "Includes AB, removes B and its types, \
disables foo, and adds C",
"includes": {
"package": [
{
"name": "example-ab",
"version": "0.1.0"
}
],
"module": [
{
"name": "example-module-c",
"version": "2.0.0"
}
]
},
"excludes": {
"module": [
"example-module-b"
],
"import-only-module": [
{
"name": "example-module-b-types"
}
],
"feature": [
"example-module-a:foo"
]
}
}
}
}
<CODE ENDS>¶
The following abbreviated JSON shows the device's operational YANG library and package advertisement after resolving "example-c". The deprecated "/modules-state" subtree is omitted. The package entry retains its name, version, and description; all other package fields are elided. The namespaces and revision dates for the fictional modules are illustrative; their semantic versions are reported separately.¶
Location information is omitted throughout this example.¶
<CODE BEGINS> file "example-c-library@0.1.0.json"
=============== NOTE: '\' line wrapping per RFC 8792 ================
{
"ietf-yang-library:yang-library": {
"content-id": "7ef8eef0e645ece0",
"datastore": [
{
"name": "ietf-datastores:running",
"schema": "Package example-c@0.1.0"
}
],
"module-set": [
{
"import-only-module": [
{
"ietf-yang-library-semver:version": "1.0.0",
"name": "example-module-a-types",
"namespace": "https://example.org/yang/\
example-module-a-types",
"revision": "2026-01-01"
}
],
"module": [
{
"ietf-yang-library-semver:version": "1.0.0",
"name": "example-module-a",
"namespace": "https://example.org/yang/example-module-a",
"revision": "2026-01-01"
},
{
"ietf-yang-library-semver:version": "2.0.0",
"name": "example-module-c",
"namespace": "https://example.org/yang/example-module-c",
"revision": "2026-02-01"
}
],
"name": "Package example-c@0.1.0"
}
],
"schema": [
{
"ietf-yl-packages:package": [
{
"name": "example-c",
"version": "0.1.0"
}
],
"module-set": [
"Package example-c@0.1.0"
],
"name": "Package example-c@0.1.0"
}
]
},
"ietf-yang-packages:packages": {
"package": [
{
"name": "example-c",
"version": "0.1.0",
"description": "Example package importing A, removing B and \
adding C"
},
{
"name": "example-ab",
"version": "0.1.0",
"description": "Example package defining modules A, B and \
associated types"
}
]
}
}
<CODE ENDS>¶
An exclusion is applied while resolving the package that contains it. It does not remove the same module contributed independently by another package included at a higher level. The following abbreviated example illustrates this rule; each "includes" line denotes a package or module entry, and each "excludes" line denotes an "excludes/module" entry.¶
Package PA includes module MX@2.0.0 Package PB includes module MX@3.0.0 Package PC includes package PA but excludes module MX Package PD includes package PB and package PC Resolved package PA: module MX@2.0.0, included directly Resolved package PB: module MX@3.0.0, included directly Resolved package PC: no module MX, excluded after resolving PA Resolved package PD: module MX@3.0.0, contributed by package PB¶
Packages PA and PB resolve to module MX@2.0.0 and MX@3.0.0, respectively, because each includes that module version directly. Package PC first inherits MX@2.0.0 from package PA, then removes it using its own "excludes/module" entry. Package PD therefore receives MX@3.0.0 from package PB and no version of MX from package PC; no module version conflict needs to be resolved. Package PC's exclusion does not remove the module contributed by package PB. If package PD must exclude module MX entirely, package PD needs its own "excludes/module" entry.¶
This section provides examples of XXX when using mounted packages. The examples are non-normative, and for brevity, some expected information (e.g., locations) are omitted.¶
This example illustrates a YANG package representing a network device that mounts a routing package at the network-instance mount point.¶
TODO - Can we use example that is the same, or very similar, to the network-instances example?¶
TODO - Indicate that this is a minimal example to illustrate a concept, and leaves out some optional elements that would be expected in a full implementation.¶
This example illustrates an implementation of the mounted package defined in XXX, but that modifies the mounted package.¶
Although this example illustrates applying deviations to the schema of a mounted package, the same mechanism can be used to change the implemented package version, remove a mounted package in its entirety, remove modules from a mounted package, change enabled features, change the behavior of recursive mounts, etc.¶
TODO - Probably need more than one example.¶