< draft-rwilton-netmod-yang-packages-02.txt   draft-rwilton-netmod-yang-packages-03.txt >
Network Working Group R. Wilton Network Working Group R. Wilton, Ed.
Internet-Draft Cisco Systems, Inc. Internet-Draft R. Rahman
Intended status: Standards Track October 23, 2019 Intended status: Standards Track J. Clarke
Expires: April 25, 2020 Expires: August 22, 2020 Cisco Systems, Inc.
J. Sterne
Nokia
B. Wu
Huawei
February 19, 2020
YANG Packages YANG Packages
draft-rwilton-netmod-yang-packages-02 draft-rwilton-netmod-yang-packages-03
Abstract Abstract
This document defines YANG packages, a versioned organizational This document defines YANG packages, a versioned organizational
structure holding a set of related YANG modules, that collectively structure holding a set of related YANG modules, that collectively
define a YANG schema. It describes how YANG instance data documents define a YANG schema. It describes how packages: are represented on
are used to define YANG packages, and how the YANG library a server, can be defined in offline YANG instance data documents, and
information published by a server can be augmented with packages can be used to define the schema associated with YANG instance data
related information. documents.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 25, 2020. This Internet-Draft will expire on August 22, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2020 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
skipping to change at page 2, line 25 skipping to change at page 2, line 29
5.2. Package versioning . . . . . . . . . . . . . . . . . . . 7 5.2. Package versioning . . . . . . . . . . . . . . . . . . . 7
5.2.1. Updating a package with a new version . . . . . . . . 8 5.2.1. Updating a package with a new version . . . . . . . . 8
5.2.1.1. Non-Backwards-compatible changes . . . . . . . . 8 5.2.1.1. Non-Backwards-compatible changes . . . . . . . . 8
5.2.1.2. Backwards-compatible changes . . . . . . . . . . 8 5.2.1.2. Backwards-compatible changes . . . . . . . . . . 8
5.2.1.3. Editorial changes . . . . . . . . . . . . . . . . 9 5.2.1.3. Editorial changes . . . . . . . . . . . . . . . . 9
5.2.2. YANG Semantic Versioning for packages . . . . . . . . 9 5.2.2. YANG Semantic Versioning for packages . . . . . . . . 9
5.2.3. Revision history . . . . . . . . . . . . . . . . . . 10 5.2.3. Revision history . . . . . . . . . . . . . . . . . . 10
5.3. Package conformance . . . . . . . . . . . . . . . . . . . 10 5.3. Package conformance . . . . . . . . . . . . . . . . . . . 10
5.3.1. Use of YANG semantic versioning . . . . . . . . . . . 10 5.3.1. Use of YANG semantic versioning . . . . . . . . . . . 10
5.3.2. Package checksums . . . . . . . . . . . . . . . . . . 11 5.3.2. Package checksums . . . . . . . . . . . . . . . . . . 11
5.4. Schema referential completeness . . . . . . . . . . . . . 11 5.3.3. The relationship between packages and datastores . . 11
5.5. Package name scoping and uniqueness . . . . . . . . . . . 12 5.4. Schema referential completeness . . . . . . . . . . . . . 13
5.5.1. Globally scoped packages . . . . . . . . . . . . . . 12 5.5. Package name scoping and uniqueness . . . . . . . . . . . 14
5.5.2. Server scoped packages . . . . . . . . . . . . . . . 12 5.5.1. Globally scoped packages . . . . . . . . . . . . . . 14
5.6. Submodules packages considerations . . . . . . . . . . . 13 5.5.2. Server scoped packages . . . . . . . . . . . . . . . 14
5.7. Package tags . . . . . . . . . . . . . . . . . . . . . . 13 5.6. Submodules packages considerations . . . . . . . . . . . 14
6. YANG Packages instance data . . . . . . . . . . . . . . . . . 13 5.7. Package tags . . . . . . . . . . . . . . . . . . . . . . 14
7. YANG Packages additions to YANG library . . . . . . . . . . . 15 5.8. YANG package core definition . . . . . . . . . . . . . . 15
7.1. Package List . . . . . . . . . . . . . . . . . . . . . . 15 6. Package Instance Data Documents . . . . . . . . . . . . . . . 16
7.2. Binding from schema to package . . . . . . . . . . . . . 15 7. Package Definitions on a Server . . . . . . . . . . . . . . . 17
7.3. Tree diagram . . . . . . . . . . . . . . . . . . . . . . 16 7.1. Package List . . . . . . . . . . . . . . . . . . . . . . 17
8. YANG Packages Groupings . . . . . . . . . . . . . . . . . . . 18 7.2. Tree diagram . . . . . . . . . . . . . . . . . . . . . . 17
9. YANG packages as schema for YANG instance data document . . . 18 8. YANG Library Package Bindings . . . . . . . . . . . . . . . . 18
9. YANG packages as schema for YANG instance data document . . . 19
10. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 19 10. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 19
11. Security Considerations . . . . . . . . . . . . . . . . . . . 40 11. Security Considerations . . . . . . . . . . . . . . . . . . . 40
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41
13. Open Questions/Issues . . . . . . . . . . . . . . . . . . . . 42 13. Open Questions/Issues . . . . . . . . . . . . . . . . . . . . 43
14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 42 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 43
15. References . . . . . . . . . . . . . . . . . . . . . . . . . 42 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 43
15.1. Normative References . . . . . . . . . . . . . . . . . . 42 15.1. Normative References . . . . . . . . . . . . . . . . . . 43
15.2. Informative References . . . . . . . . . . . . . . . . . 44 15.2. Informative References . . . . . . . . . . . . . . . . . 45
Appendix A. Tree output for ietf-yang-library with package Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 45
augmentations . . . . . . . . . . . . . . . . . . . 45 A.1. Example IETF Network Device YANG package . . . . . . . . 46
Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 47 A.2. Example IETF Basic Routing YANG package . . . . . . . . . 48
B.1. Example IETF Network Device YANG package . . . . . . . . 47 A.3. Package import conflict resolution example . . . . . . . 51
B.2. Example IETF Basic Routing YANG package . . . . . . . . . 50 Appendix B. Possible alternative solutions . . . . . . . . . . . 54
B.3. Package import conflict resolution example . . . . . . . 53 B.1. Using module tags . . . . . . . . . . . . . . . . . . . . 54
B.2. Using YANG library . . . . . . . . . . . . . . . . . . . 55
Appendix C. Possible alternative solutions . . . . . . . . . . . 56 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 55
C.1. Using module tags . . . . . . . . . . . . . . . . . . . . 56
C.2. Using YANG library . . . . . . . . . . . . . . . . . . . 56
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 57
1. Terminology and Conventions 1. Terminology and Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
This document uses terminology introduced in the YANG versioning This document uses terminology introduced in the YANG versioning
skipping to change at page 11, line 42 skipping to change at page 11, line 42
instance data document available, and hence MAY not have a checksum. instance data document available, and hence MAY not have a checksum.
The package definition allows URLs and checksums to be specified for The package definition allows URLs and checksums to be specified for
all included packages, modules and submodules within the package all included packages, modules and submodules within the package
definition. Checksums SHOULD be included in package definitions to definition. Checksums SHOULD be included in package definitions to
validate the full integrity of the package. validate the full integrity of the package.
On a server, package checksums SHOULD also be provided for the top On a server, package checksums SHOULD also be provided for the top
level packages associated with the datastore schema. level packages associated with the datastore schema.
5.3.3. The relationship between packages and datastores
As defined by NMDA [RFC8342], each datastore has an associated
datastore schema. Sections 5.1 and 5.3 of NMDA defines further
constraints on the schema associated with datastores. These
constraints can be summarized thus:
The schema for all conventional datastores is the same.
The schema for non conventional configuration datastores (e.g.,
dynamic datastores) may completely differ (i.e. no overlap at all)
from the schema associated with the conventional configuration
datastores, or may partially or fully overlap with the schema of
the conventional configuration datastores. A dynamic datastore,
for example, may support different modules than conventional
datastores, or may support a subset or superset of modules,
features, or data nodes supported in the conventional
configuration datastores. Where a data node exists in multiple
datastore schema it has the same type, properties and semantics.
The schema for the operational datastore is intended to be a
superset of all the configuration datastores (i.e. includes all
the schema nodes from the conventional configuration datastores),
but data nodes can be omitted if they cannot be accurately
reported. The operational datastore schema can include additional
modules containing only config false data nodes, but there is no
harm in including those modules in the configuration datastore
schema as well.
Given that YANG packages represent a YANG schema, it follows that
each datastore schema can be represented using packages. In
addition, the schema for most datastores on a server are often
closely related. Given that there are many ways that a datastore
schema could be represented using packages, the following guidance
provides a consistent approach to help clients understand the
relationship between the different datastore schema supported by a
device (e.g., which parts of the schema are common and which parts
have differences):
Any datastores (e.g., conventional configuration datastores) that
have exactly the same datastore schema MUST use the same package
definitions. This is to avoid, for example, the creation of a
'running-cfg' package and a separate 'intended-cfg' package that
have identical schema.
Common package definitions SHOULD be used for those parts of the
datastore schema that are common between datastores, when those
datastores do not share exactly the same datastore schema. E.g.,
if a substantial part of the schema is common between the
conventional, dynamic, and operational datastores then a single
common package can be used to describe the common parts, along
with other packages to describe the unique parts of each datastore
schema.
YANG modules that do not contain any configuration data nodes
SHOULD be included in the package for configuration datastores if
that helps unify the package definitions.
The packages for the operational datastore schema MUST include all
packages for all configuration datastores, along with any required
modules defining deviations to mark unsupported data nodes. The
deviations MAY be defined directly in the packages defining the
operational datastore schema, or in separate non referentially
complete packages.
The schema for a datastore MAY be represented using a single
package or as the union of a set of compatible packages, i.e.,
equivalently to a set of non-conflicting packages being included
together in an overarching package definition.
5.4. Schema referential completeness 5.4. Schema referential completeness
A YANG package may represent a schema that is 'referentially A YANG package may represent a schema that is 'referentially
complete', or 'referentially incomplete', indicated in the package complete', or 'referentially incomplete', indicated in the package
definition by the 'complete' flag. definition by the 'complete' flag.
If all import statements in all YANG modules included in the package If all import statements in all YANG modules included in the package
(either directly, or through included packages) can be resolved to a (either directly, or through included packages) can be resolved to a
module revision defined with the YANG package definition, then the module revision defined with the YANG package definition, then the
package is classified as referentially complete. Conversely, if one package is classified as referentially complete. Conversely, if one
skipping to change at page 13, line 25 skipping to change at page 15, line 5
definition. definition.
5.7. Package tags 5.7. Package tags
[I-D.ietf-netmod-module-tags] defines YANG module tags as a mechanism [I-D.ietf-netmod-module-tags] defines YANG module tags as a mechanism
to annotate a module definition with additional metadata. Tags MAY to annotate a module definition with additional metadata. Tags MAY
also be associated to a package definition via the 'tags' leaf-list. also be associated to a package definition via the 'tags' leaf-list.
The tags use the same registry and definitions used by YANG module The tags use the same registry and definitions used by YANG module
tags. tags.
6. YANG Packages instance data 5.8. YANG package core definition
YANG packages SHOULD be defined as YANG instance data documents The ietf-yang-package-types.yang module defines a grouping to specify
the core elements of the YANG package structure that is used within
YANG package instance data documents (ietf-yang-package-
instance.yang) and also on the server (ietf-yang-packages.yang).
The "ietf-yang-package-types" YANG module has the following
structure:
module: ietf-yang-package-types
grouping yang-pkg-identification-leafs
+-- name pkg-name
+-- version pkg-version
grouping yang-pkg-instance
+-- name pkg-name
+-- version pkg-version
+-- timestamp? yang:date-and-time
+-- organization? string
+-- contact? string
+-- description? string
+-- reference? string
+-- complete? boolean
+-- local? boolean
+-- previous-version? pkg-version
+-- nbc-changes? boolean
+-- tag* tags:tag
+-- mandatory-feature* scoped-feature
+-- included-package* [name version]
| +-- name pkg-name
| +-- version pkg-version
| +-- replaces-version* pkg-version
| +-- nbc-modified? boolean
| +-- location* inet:uri
| +-- checksum? pkg-types:sha-256-hash
+-- module* [name]
| +-- name yang:yang-identifier
| +-- revision? rev:revision-date-or-label
| +-- replaces-revision* rev:revision-date-or-label
| +-- namespace? inet:uri
| +-- location* inet:uri
| +-- checksum? pkg-types:sha-256-hash
| +-- submodule* [name]
| +-- name? yang:yang-identifier
| +-- revision yang:revision-identifier
| +-- location* inet:uri
| +-- checksum? pkg-types:sha-256-hash
+-- import-only-module* [name revision]
+-- name? yang:yang-identifier
+-- revision? rev:revision-date-or-label
+-- replaces-revision* rev:revision-date-or-label
+-- namespace? inet:uri
+-- location* inet:uri
+-- checksum? pkg-types:sha-256-hash
+-- submodule* [name]
+-- name? yang:yang-identifier
+-- revision yang:revision-identifier
+-- location* inet:uri
+-- checksum? pkg-types:sha-256-hash
6. Package Instance Data Documents
YANG packages SHOULD be available offline from the server, defined as
YANG instance data documents
[I-D.ietf-netmod-yang-instance-file-format] using the YANG schema [I-D.ietf-netmod-yang-instance-file-format] using the YANG schema
below to define the package data itself. below to define the package data.
The format of the YANG package instance file MUST follow the The format of the YANG package instance file MUST follow the
following rules: following rules:
The file SHOULD be encoded in JSON. The file SHOULD be encoded in JSON.
The name of the file SHOULD follow the format "<package- The name of the file SHOULD follow the format "<package-
name>@<version>.json". name>@<version>.json".
The package name MUST be specified in both the instance-data-set The package name MUST be specified in both the instance-data-set
skipping to change at page 14, line 19 skipping to change at page 17, line 16
SHOULD be made available at one of more locations accessible via SHOULD be made available at one of more locations accessible via
URLs. If one of the listed locations defines a definitive URLs. If one of the listed locations defines a definitive
reference implementation for the package definition then it MUST reference implementation for the package definition then it MUST
be listed as the first entry in the list. be listed as the first entry in the list.
The "ietf-yang-package" YANG module has the following structure: The "ietf-yang-package" YANG module has the following structure:
module: ietf-yang-package module: ietf-yang-package
structure package: structure package:
+-- name pkg-identifier // Uses the yang-package-instance grouping defined in
+-- version rev:revision-label // ietf-yang-package-types.yang
+-- timestamp? yang:date-and-time +-- name pkg-name
+-- organization? string +-- version pkg-version
+-- contact? string ... remainder of yang-package-instance grouping ...
+-- description? string
+-- reference? string
+-- location* inet:uri
+-- complete? boolean
+-- local? boolean
+-- previous-version? rev:revision-label
+-- nbc-changes? boolean
+-- tag* tags:tag
+-- mandatory-feature* scoped-feature
+-- included-package* [name version]
| +-- name pkg-identifier
| +-- version rev:revision-label
| +-- replaces-version* rev:revision-label
| +-- nbc-modified? boolean
| +-- location* inet:uri
| +-- checksum? pkg-types:sha-256-hash
+-- module* [name]
| +-- name yang:yang-identifier
| +-- revision? rev:revision-date-or-label
| +-- replaces-revision* rev:revision-date-or-label
| +-- namespace? inet:uri
| +-- location* inet:uri
| +-- checksum? pkg-types:sha-256-hash
| +-- submodule* [name]
| +-- name yang:yang-identifier
| +-- revision rev:revision-identifier
| +-- location* inet:uri
| +-- checksum? pkg-types:sha-256-hash
+-- import-only-module* [name revision]
+-- name yang:yang-identifier
+-- revision rev:revision-date-or-label
+-- replaces-revision* rev:revision-date-or-label
+-- namespace? inet:uri
+-- location* inet:uri
+-- checksum? pkg-types:sha-256-hash
+-- submodule* [name]
+-- name yang:yang-identifier
+-- revision rev:revision-identifier
+-- location* inet:uri
+-- checksum? pkg-types:sha-256-hash
7. YANG Packages additions to YANG library 7. Package Definitions on a Server
7.1. Package List 7.1. Package List
The main addition is a top level 'yang-library/package' list that A top level 'packages' container holds the list of all versions of
lists all versions of all packages known to the server. Each package all packages known to the server. Each list entry uses the common
defines a potentially incomplete YANG schema, built from included package definition, but with the addition of package location and
packages and module-sets. The use of module-sets allows the module checksum information that cannot be contained within a offline
definitions to be shared with the existing YANG library schema package definition contained in an instance data document.
definitions. The existing rule of RFC 7995bis related to combining
modules-sets also applies here, i.e. The combined set of modules
defined by the module-sets MUST NOT contain modules implemented at
different revisions. I.e. the module-sets leaf-list is directly
equivalent to the explicit module and import-only-module lists in the
instance data YANG package definition.
The 'yang-library/package' list MAY include multiple versions of a The '/packages/package' list MAY include multiple versions of a
particular package. E.g. if the server is capable of allowing particular package. E.g. if the server is capable of allowing
clients to select which package versions should be used by the clients to select which package versions should be used by the
server. server.
7.2. Binding from schema to package 7.2. Tree diagram
The "ietf-yang-packages" YANG module has the following structure:
The second augmentation is to allow a server to optionally indicate module: ietf-yang-packages
that a schema definition directly relates to a package. Since YANG +--ro packages
packages are available offline, it may be sufficient for a client to +--ro package* [name version]
only check that a compatible version of the YANG package is being // Uses the yang-package-instance grouping defined in
implemented by the server without fetching and comparing the full // ietf-yang-package-types.yang, with location and checksum:
module list. +--ro name pkg-name
+--ro version pkg-version
... remainder of yang-package-instance grouping ...
+--ro location* inet:uri
+--ro checksum? pkg-types:sha-256-hash
If a server indicates that its schema maps to a particular package 8. YANG Library Package Bindings
then it MUST support all features listed in the mandatory-feature
list defined as part of that package, and it MUST NOT have any non- The YANG packages module also augments YANG library to allow a server
backwards-compatible deviations to the modules defined by the to optionally indicate that a datastore schema is defined by a
package. A server MAY implement features not specified in the package, or a union of compatible packages. Since packages can
package's mandatory-feature list. generally be made available offline in instance data documents, it
may be sufficient for a client to only check that a compatible
version of the package is implemented by the server without fetching
either the package definition, or downloading and comparing the full
list of modules and enabled features.
If a server indicates that a datastore schema maps to a particular
package, then it MUST exactly match the schema defined by that
package, taking into account enabled features and any deviations.
If a server cannot faithfully implement a package then it can define If a server cannot faithfully implement a package then it can define
a new package to accurately report what it does implement. The new a new package to accurately report what it does implement. The new
package can include the original package as an included package, and package can include the original package as an included package, and
the new package can define additional modules containing deviations the new package can define additional modules containing deviations
to the modules in the original package, allowing the new package to to the modules in the original package, allowing the new package to
accurately describe the server behavior. There is no specific accurately describe the server's behavior. There is no specific
mechanism provided to indicate that a mandatory-feature is not mechanism provided to indicate that a mandatory-feature in package
supported on a server, but deviations MAY be used to disable definition is not supported on a server, but deviations MAY be used
functionality predicated by an if-feature statement. to disable functionality predicated by an if-feature statement.
7.3. Tree diagram
The "ietf-yang-library-packages" YANG module has the following The "ietf-yl-packages" YANG module has the following structure:
structure:
module: ietf-yl-packages module: ietf-yl-packages
augment /yanglib:yang-library:
+--ro package* [name version]
+--ro name pkg-identifier
+--ro version rev:revision-label
+--ro timestamp? yang:date-and-time
+--ro organization? string
+--ro contact? string
+--ro description? string
+--ro reference? string
+--ro location* inet:uri
+--ro complete? boolean
+--ro local? boolean
+--ro previous-version? rev:revision-label
+--ro nbc-changes? boolean
+--ro tag* tags:tag
+--ro mandatory-feature* scoped-feature
+--ro included-package* [name version]
| +--ro name pkg-identifier
| +--ro version rev:revision-label
| +--ro replaces-version* rev:revision-label
| +--ro nbc-modified? boolean
| +--ro location* inet:uri
| +--ro checksum? pkg-types:sha-256-hash
+--ro module-set*
| -> /yanglib:yang-library/module-set/name
+--ro checksum? pkg-types:sha-256-hash
augment /yanglib:yang-library/yanglib:schema: augment /yanglib:yang-library/yanglib:schema:
+--ro package +--ro package* [name version]
+--ro name? +--ro name -> /pkgs:packages/package/name
| -> /yanglib:yang-library/package/name +--ro version leafref
+--ro version? leafref +--ro checksum? leafref
+--ro checksum? pkg-types:sha-256-hash
+--ro supported-optional-feature* pkg-types:scoped-feature
augment /yanglib:yang-library/yanglib:module-set/yanglib:module:
+--ro replaces-revision* rev:revision-date-or-label
+--ro checksum? pkg-types:sha-256-hash
augment /yanglib:yang-library/yanglib:module-set/yanglib:module
/yanglib:submodule:
+--ro checksum? pkg-types:sha-256-hash
augment /yanglib:yang-library/yanglib:module-set
/yanglib:import-only-module:
+--ro replaces-revision* rev:revision-date-or-label
+--ro checksum? pkg-types:sha-256-hash
augment /yanglib:yang-library/yanglib:module-set
/yanglib:import-only-module/yanglib:submodule:
+--ro checksum? pkg-types:sha-256-hash
8. YANG Packages Groupings
Groupings for YANG packages related constructs are provided in a
'types' module for use by the instance-data and YANG library
constructs described previously. They are also available to be used
by other modules that have a need for YANG packages information.
The "ietf-yang-package-types" YANG module has the following
structure:
module: ietf-yang-package-types
grouping yang-pkg-identification-leafs
+-- name pkg-identifier
+-- version rev:revision-label
grouping yang-pkg-common-leafs
+-- timestamp? yang:date-and-time
+-- organization? string
+-- contact? string
+-- description? string
+-- reference? string
+-- location* inet:uri
+-- complete? boolean
+-- local? boolean
+-- previous-version? rev:revision-label
+-- nbc-changes? boolean
+-- tag* tags:tag
+-- mandatory-feature* scoped-feature
+-- included-package* [name version]
+-- name pkg-identifier
+-- version rev:revision-label
+-- replaces-version* rev:revision-label
+-- nbc-modified? boolean
+-- location* inet:uri
+-- checksum? pkg-types:sha-256-hash
9. YANG packages as schema for YANG instance data document 9. YANG packages as schema for YANG instance data document
YANG package definitions can be used as the schema definition for YANG package definitions can be used as the schema definition for
YANG instance data documents. When using a package schema, the name YANG instance data documents. When using a package schema, the name
of the package MUST be specified, a package checksum and/or URL to and version of the package MUST be specified, a package checksum and/
the package definition MAY also be provided. or URL to the package definition MAY also be provided.
The "ietf-yang-inst-data-pkg" YANG module has the following The "ietf-yang-inst-data-pkg" YANG module has the following
structure: structure:
module: ietf-yang-inst-data-pkg module: ietf-yang-inst-data-pkg
augment-structure /yid:instance-data-set/yid:content-schema-spec: augment-structure /yid:instance-data-set/yid:content-schema-spec:
+--:(pkg-schema) +--:(pkg-schema)
+-- pkg-schema +-- pkg-schema
+-- package pkg-types:pkg-identifier +-- name pkg-name
+-- location* inet:uri +-- version pkg-version
+-- checksum? pkg-types:sha-256-hash +-- location* inet:uri
+-- checksum? pkg-types:sha-256-hash
10. YANG Modules 10. YANG Modules
The YANG module definitions for the modules described in the previous The YANG module definitions for the modules described in the previous
sections. sections.
<CODE BEGINS> file "ietf-yang-package-types@2019-09-11.yang" <CODE BEGINS> file "ietf-yang-package-types@2020-01-21.yang"
module ietf-yang-package-types { module ietf-yang-package-types {
yang-version 1.1; yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-package-types"; namespace "urn:ietf:params:xml:ns:yang:ietf-yang-package-types";
prefix "pkg-types"; prefix "pkg-types";
import ietf-yang-revisions { import ietf-yang-revisions {
prefix rev; prefix rev;
reference "XXXX: Updated YANG Module Revision Handling"; reference "XXXX: Updated YANG Module Revision Handling";
} }
import ietf-yang-types { import ietf-yang-types {
prefix yang; prefix yang;
rev:revision-or-derived 2013-07-15; rev:revision-or-derived 2019-07-21;
reference "RFC 6991: Common YANG Data Types."; reference "RFC 6991bis: Common YANG Data Types.";
} }
import ietf-inet-types { import ietf-inet-types {
prefix inet; prefix inet;
rev:revision-or-derived 2013-07-15;
reference "RFC 6991: Common YANG Data Types."; reference "RFC 6991: Common YANG Data Types.";
} }
import ietf-module-tags { import ietf-module-tags {
prefix tags; prefix tags;
// RFC Ed. Fix revision once revision date of
// ietf-module-tags.yang is known.
reference "RFC XXX: YANG Module Tags."; reference "RFC XXX: YANG Module Tags.";
} }
organization organization
"IETF NETMOD (Network Modeling) Working Group"; "IETF NETMOD (Network Modeling) Working Group";
contact contact
"WG Web: <http://tools.ietf.org/wg/netmod/> "WG Web: <http://tools.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org> WG List: <mailto:netmod@ietf.org>
skipping to change at page 20, line 40 skipping to change at page 21, line 15
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
'MAY', and 'OPTIONAL' in this document are to be interpreted as 'MAY', and 'OPTIONAL' in this document are to be interpreted as
described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
they appear in all capitals, as shown here."; they appear in all capitals, as shown here.";
// RFC Ed.: update the date below with the date of RFC publication // RFC Ed.: update the date below with the date of RFC publication
// and remove this note. // and remove this note.
// RFC Ed.: replace XXXX with actual RFC number and remove this // RFC Ed.: replace XXXX with actual RFC number and remove this
// note. // note.
revision 2019-09-11 { revision 2020-01-21 {
rev:revision-label 0.1.0; rev:revision-label 0.2.0;
description description
"Initial revision"; "Initial revision";
reference reference
"RFC XXXX: YANG Packages"; "RFC XXXX: YANG Packages";
} }
/* /*
* Typedefs * Typedefs
*/ */
typedef pkg-identifier { typedef pkg-name {
type yang:yang-identifier; type yang:yang-identifier;
description description
"Package identifiers are typed as YANG identifiers."; "Package names are typed as YANG identifiers.";
}
typedef pkg-version {
type rev:revision-date-or-label;
description
"Package versions SHOULD be a revision-label (e.g. perhaps a
YANG Semver version string). Package versions MAY also be a
revision-date";
}
typedef pkg-identifier {
type rev:name-revision;
description
"Package identifiers combine a pkg-name and a pkg-version";
} }
typedef scoped-feature { typedef scoped-feature {
type string { type string {
pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*:[a-zA-Z_][a-zA-Z0-9\-_.]*'; pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*:[a-zA-Z_][a-zA-Z0-9\-_.]*';
} }
description description
"Represents a feature name scoped to a particular module, "Represents a feature name scoped to a particular module,
identified as the '<module-name>:<feature-name>', where both identified as the '<module-name>:<feature-name>', where both
<module-name> and <feature-name> are YANG identifier strings, <module-name> and <feature-name> are YANG identifier strings,
skipping to change at page 21, line 46 skipping to change at page 22, line 35
the contents of the YANG file defining the module/submodule. the contents of the YANG file defining the module/submodule.
For packages the SHA-256 hash is calculated on the file For packages the SHA-256 hash is calculated on the file
containing the YANG instance data document holding the package containing the YANG instance data document holding the package
definition"; definition";
} }
/* /*
* Groupings * Groupings
*/ */
grouping yang-pkg-identification-leafs { grouping yang-pkg-identification-leafs {
description description
"Parameters for identifying a specific version of a YANG "Parameters for identifying a specific version of a YANG
package"; package";
leaf name { leaf name {
type pkg-identifier; type pkg-name;
mandatory true; mandatory true;
description description
"The YANG package name."; "The YANG package name.";
} }
leaf version { leaf version {
type rev:revision-label; type pkg-version;
mandatory true; mandatory true;
description description
"Uniquely identies a particular version of a YANG package. "Uniquely identies a particular version of a YANG package.
Follows the definition for revision labels defined in Follows the definition for revision labels defined in
draft-verdt-nemod-yang-module-versioning, section XXX"; draft-verdt-nemod-yang-module-versioning, section XXX";
} }
} }
grouping yang-pkg-common-leafs { grouping yang-pkg-instance {
description description
"Defines definitions common to all YANG package definitions."; "Specifies the data node for a full YANG package instance
represented either on a server or as a YANG instance data
document.";
uses yang-pkg-identification-leafs;
leaf timestamp { leaf timestamp {
type yang:date-and-time; type yang:date-and-time;
description description
"An optional timestamp for when this package was created. "An optional timestamp for when this package was created.
This does not need to be unique across all versions of a This does not need to be unique across all versions of a
package."; package.";
} }
skipping to change at page 23, line 4 skipping to change at page 23, line 43
leaf contact { leaf contact {
type string; type string;
description description
"Contact information for the person or organization to whom "Contact information for the person or organization to whom
queries concerning this package should be sent."; queries concerning this package should be sent.";
} }
leaf description { leaf description {
type string; type string;
description "Provides a description of the package"; description "Provides a description of the package";
} }
leaf reference { leaf reference {
type string; type string;
description "Allows for a reference for the package"; description "Allows for a reference for the package";
} }
leaf-list location {
type inet:uri;
description
"Contains a URL that represents where an instance data file
for this YANG package can be found.
This leaf will only be present if there is a URL
available for retrieval of the schema for this entry.
If multiple locations are provided, then the first location
in the leaf-list MUST be the definitive location that
uniquely identifies this package";
}
leaf complete { leaf complete {
type boolean; type boolean;
default true; default true;
description description
"Indicates whether the schema defined by this package is "Indicates whether the schema defined by this package is
referentially complete. I.e. all module imports can be referentially complete. I.e. all module imports can be
resolved to a module explicitly defined in this package or resolved to a module explicitly defined in this package or
one of the included packages."; one of the included packages.";
} }
skipping to change at page 23, line 51 skipping to change at page 24, line 28
"Defines that the package definition is local to the server, "Defines that the package definition is local to the server,
and the name of the package MAY not be unique, and the and the name of the package MAY not be unique, and the
package definition MAY not be available in an offline file. package definition MAY not be available in an offline file.
Local packages can be used when the schema for the device Local packages can be used when the schema for the device
can be changed at runtime through the addition or removal of can be changed at runtime through the addition or removal of
software packages, or hot fixes."; software packages, or hot fixes.";
} }
leaf previous-version { leaf previous-version {
type rev:revision-label; type pkg-version;
description description
"The previous package version that this version has been "The previous package version that this version has been
derived from. This leaf allows a full version history graph derived from. This leaf allows a full version history graph
to be constructed if required."; to be constructed if required.";
} }
leaf nbc-changes { leaf nbc-changes {
type boolean; type boolean;
default false; default false;
description description
skipping to change at page 25, line 21 skipping to change at page 25, line 46
module list MUST be provided to select the specific module module list MUST be provided to select the specific module
version 'implemented' by this package definition. version 'implemented' by this package definition.
If the schema for any packages that are included, either If the schema for any packages that are included, either
directly or indirectly via another package include, are directly or indirectly via another package include, are
changed in any non-backwards-compatible way then they MUST changed in any non-backwards-compatible way then they MUST
be explicitly listed in the included-packages list with the be explicitly listed in the included-packages list with the
'nbc-modified' leaf set to true. 'nbc-modified' leaf set to true.
For import-only modules, the 'replaces-revision' leaf-list For import-only modules, the 'replaces-revision' leaf-list
can be used to select the specific module versions used can be used to select the specific module versions used by
by this package."; this package.";
reference reference
"XXX"; "XXX";
uses yang-pkg-identification-leafs; uses yang-pkg-identification-leafs;
leaf-list replaces-version { leaf-list replaces-version {
type rev:revision-label; type pkg-version;
description description
"Gives the version of an included package version that "Gives the version of an included package version that
is replaced by this included package revision."; is replaced by this included package revision.";
} }
leaf nbc-modified { leaf nbc-modified {
type boolean; type boolean;
default false; default false;
description description
"Set to true if any data nodes in this package are modified "Set to true if any data nodes in this package are modified
skipping to change at page 26, line 20 skipping to change at page 26, line 45
that uniquely identifies this package"; that uniquely identifies this package";
} }
leaf checksum { leaf checksum {
type pkg-types:sha-256-hash; type pkg-types:sha-256-hash;
description description
"The SHA-256 hash calculated on the textual package "The SHA-256 hash calculated on the textual package
definition, represented as a hexadecimal string."; definition, represented as a hexadecimal string.";
} }
} }
}
}
<CODE ENDS>
<CODE BEGINS> file "ietf-yang-package@2019-09-11.yang"
module ietf-yang-package {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-package";
prefix pkg;
import ietf-yang-revisions {
prefix rev;
reference "XXXX: Updated YANG Module Revision Handling";
}
import ietf-yang-package-types {
prefix pkg-types;
rev:revision-or-derived 0.1.0;
reference "RFC XXX: YANG Schema Versioning.";
}
import ietf-yang-structure-ext {
prefix sx;
reference "RFC XXX: YANG Data Structure Extensions.";
}
import ietf-yang-types {
prefix yang;
rev:revision-or-derived 2013-07-15;
reference "RFC 6991: Common YANG Data Types.";
}
import ietf-inet-types {
prefix inet;
reference "RFC 6991: Common YANG Data Types.";
}
organization
"IETF NETMOD (Network Modeling) Working Group";
contact
"WG Web: <http://tools.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org>
Author: Rob Wilton
<mailto:rwilton@cisco.com>";
description
"This module provides a definition of a YANG package, which is
used as the schema for an YANG instance data document specifying
a YANG package.
Copyright (c) 2019 IETF Trust and the persons identified as
authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices.
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
'MAY', and 'OPTIONAL' in this document are to be interpreted as
described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
they appear in all capitals, as shown here.";
// RFC Ed.: update the date below with the date of RFC publication
// and remove this note.
// RFC Ed.: replace XXXX with actual RFC number and remove this
// note.
revision 2019-09-11 {
rev:revision-label 0.1.0;
description
"Initial revision";
reference
"RFC XXXX: YANG Packages";
}
/*
* Top-level structure
*/
sx:structure package {
description
"Defines a YANG package.
Intended to be used to specify YANG package within an instance
data document.";
uses pkg-types:yang-pkg-identification-leafs;
uses pkg-types:yang-pkg-common-leafs;
list module { list module {
key "name"; key "name";
description description
"An entry in this list represents a module that must be "An entry in this list represents a module that must be
implemented by a server implementing this package, as per implemented by a server implementing this package, as per
RFC 7950 section 5.6.5, with a particular set of supported RFC 7950 section 5.6.5, with a particular set of supported
features and deviations. features and deviations.
A entry in this list overrides any module revision A entry in this list overrides any module revision
skipping to change at page 29, line 27 skipping to change at page 28, line 4
leaf-list location { leaf-list location {
type inet:uri; type inet:uri;
description description
"Contains a URL that represents the YANG schema resource "Contains a URL that represents the YANG schema resource
for this module. for this module.
This leaf will only be present if there is a URL available This leaf will only be present if there is a URL available
for retrieval of the schema for this entry."; for retrieval of the schema for this entry.";
} }
leaf checksum { leaf checksum {
type pkg-types:sha-256-hash; type pkg-types:sha-256-hash;
description description
"The SHA-256 hash calculated on the textual module "The SHA-256 hash calculated on the textual module
definition, represented as a hexadecimal string."; definition, represented as a hexadecimal string.";
} }
list submodule { list submodule {
key "name"; key "name";
description description
"Each entry represents one submodule within the "Each entry represents one submodule within the
parent module."; parent module.";
leaf name { leaf name {
type yang:yang-identifier; type yang:yang-identifier;
description description
"The YANG submodule name."; "The YANG submodule name.";
} }
leaf revision { leaf revision {
type rev:revision-identifier; type yang:revision-identifier;
mandatory true; mandatory true;
description description
"The YANG submodule revision date. If the parent module "The YANG submodule revision date. If the parent module
include statement for this submodule includes a revision include statement for this submodule includes a revision
date then it MUST match this leaf's value."; date then it MUST match this leaf's value.";
} }
leaf-list location { leaf-list location {
type inet:uri; type inet:uri;
description description
skipping to change at page 31, line 51 skipping to change at page 30, line 27
"Each entry represents one submodule within the "Each entry represents one submodule within the
parent module."; parent module.";
leaf name { leaf name {
type yang:yang-identifier; type yang:yang-identifier;
description description
"The YANG submodule name."; "The YANG submodule name.";
} }
leaf revision { leaf revision {
type rev:revision-identifier; type yang:revision-identifier;
mandatory true; mandatory true;
description description
"The YANG submodule revision date. If the parent module "The YANG submodule revision date. If the parent module
include statement for this submodule includes a revision include statement for this submodule includes a revision
date then it MUST match this leaf's value."; date then it MUST match this leaf's value.";
} }
leaf-list location { leaf-list location {
type inet:uri; type inet:uri;
description description
skipping to change at page 32, line 28 skipping to change at page 31, line 4
} }
leaf checksum { leaf checksum {
type pkg-types:sha-256-hash; type pkg-types:sha-256-hash;
description description
"The SHA-256 hash calculated on the textual submodule "The SHA-256 hash calculated on the textual submodule
definition, represented as a hexadecimal string."; definition, represented as a hexadecimal string.";
} }
} }
} }
} }
} }
<CODE ENDS> <CODE ENDS>
<CODE BEGINS> file "ietf-yl-packages@2019-09-11.yang" <CODE BEGINS> file "ietf-yang-package-instance@2020-01-21.yang"
module ietf-yl-packages { module ietf-yang-package-instance {
yang-version 1.1; yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-yl-packages"; namespace "urn:ietf:params:xml:ns:yang:ietf-yang-package-instance";
prefix yl-pkg; prefix pkg-inst;
import ietf-yang-revisions { import ietf-yang-revisions {
prefix rev; prefix rev;
reference "XXXX: Updated YANG Module Revision Handling"; reference "XXXX: Updated YANG Module Revision Handling";
} }
import ietf-yang-package-types { import ietf-yang-package-types {
prefix pkg-types; prefix pkg-types;
reference "RFC XXX: YANG Packages."; rev:revision-or-derived 0.2.0;
reference "RFC XXX: YANG Schema Versioning.";
} }
import ietf-yang-library { import ietf-yang-structure-ext {
prefix yanglib; prefix sx;
reference "RFC 7895bis: YANG Library"; reference "RFC XXX: YANG Data Structure Extensions.";
} }
organization organization
"IETF NETMOD (Network Modeling) Working Group"; "IETF NETMOD (Network Modeling) Working Group";
contact contact
"WG Web: <http://tools.ietf.org/wg/netmod/> "WG Web: <http://tools.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org> WG List: <mailto:netmod@ietf.org>
Author: Rob Wilton Author: Rob Wilton
<mailto:rwilton@cisco.com>"; <mailto:rwilton@cisco.com>";
description description
"This module provides defined augmentations to YANG library to "This module provides a definition of a YANG package, which is
allow a server to report YANG package information. used as the schema for an YANG instance data document specifying
a YANG package.
Copyright (c) 2018 IETF Trust and the persons identified as Copyright (c) 2019 IETF Trust and the persons identified as
authors of the code. All rights reserved. authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents Relating to IETF Documents
(http://trustee.ietf.org/license-info). (http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see This version of this YANG module is part of RFC XXXX; see
skipping to change at page 33, line 44 skipping to change at page 32, line 22
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
'MAY', and 'OPTIONAL' in this document are to be interpreted as 'MAY', and 'OPTIONAL' in this document are to be interpreted as
described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
they appear in all capitals, as shown here."; they appear in all capitals, as shown here.";
// RFC Ed.: update the date below with the date of RFC publication // RFC Ed.: update the date below with the date of RFC publication
// and remove this note. // and remove this note.
// RFC Ed.: replace XXXX with actual RFC number and remove this // RFC Ed.: replace XXXX with actual RFC number and remove this
// note. // note.
revision 2019-09-11 { revision 2020-01-21 {
rev:revision-label 0.1.0; rev:revision-label 0.2.0;
description description
"Initial revision"; "Initial revision";
reference reference
"RFC XXXX: YANG Packages"; "RFC XXXX: YANG Packages";
} }
/* /*
* Augmentations * Top-level structure
*/ */
augment "/yanglib:yang-library" { sx:structure package {
description "Add YANG package definitions into YANG library"; description
"Defines the YANG package structure for use in a YANG instance
data document.";
list package { uses pkg-types:yang-pkg-instance;
key "name version"; }
config "false"; }
<CODE ENDS>
description <CODE BEGINS> file "ietf-yang-package@2020-01-21.yang"
"Defines the package available on this server."; module ietf-yang-packages {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-packages";
prefix pkgs;
import ietf-yang-revisions {
prefix rev;
reference "XXXX: Updated YANG Module Revision Handling";
}
uses pkg-types:yang-pkg-identification-leafs; import ietf-yang-package-types {
uses pkg-types:yang-pkg-common-leafs; prefix pkg-types;
rev:revision-or-derived 0.2.0;
reference "RFC XXX: YANG Packages.";
}
leaf-list module-set { import ietf-inet-types {
type leafref { prefix inet;
path "/yanglib:yang-library/yanglib:module-set/" + rev:revision-or-derived 2013-07-15;
"yanglib:name"; reference "RFC 6991: Common YANG Data Types.";
} }
description
"Describes any modules in addition to, and replacing, and
modules defined in the included packages.
If a non import-only module appears in multiple module organization
sets, then the module revision and the associated features "IETF NETMOD (Network Modeling) Working Group";
and deviations MUST be identical.";
}
leaf checksum { contact
type pkg-types:sha-256-hash; "WG Web: <http://tools.ietf.org/wg/netmod/>
description WG List: <mailto:netmod@ietf.org>
"The SHA-256 hash calculated on the textual package
definition, represented as a hexadecimal string.";
}
}
}
augment "/yanglib:yang-library/yanglib:schema" { Author: Rob Wilton
description <mailto:rwilton@cisco.com>";
"Allow datastore schema to be related to a YANG package";
container package { description
leaf name { "This module defines YANG packages on a server implementation.
type leafref {
path "/yanglib:yang-library/package/name";
} Copyright (c) 2018 IETF Trust and the persons identified as
description authors of the code. All rights reserved.
"The name of the package this schema relates to.
The referenced package MUST represent a referentially Redistribution and use in source and binary forms, with or
complete schema"; without modification, is permitted pursuant to, and subject
} to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
leaf version { This version of this YANG module is part of RFC XXXX; see
type leafref { the RFC itself for full legal notices.
path '/yanglib:yang-library/'
+ 'package[name = current()/../name]/version';
}
description The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
"The version number of the package this schema relates NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
to."; '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.";
leaf checksum { // RFC Ed.: update the date below with the date of RFC publication
type pkg-types:sha-256-hash; // and remove this note.
description // RFC Ed.: replace XXXX with actual RFC number and remove this
"The checksum of the package this schema relates to, // note.
calculated on the 'YANG instance data file' package revision 2020-01-21 {
definition. rev:revision-label 0.2.0;
description
"Initial revision";
reference
"RFC XXXX: YANG Packages";
}
This leaf MAY be omitted if the referenced package is /*
locally scoped without an associated checksum."; * Groupings
} */
leaf-list supported-optional-feature { grouping yang-pkg-ref {
type pkg-types:scoped-feature; description
description "Defines the leaves used to reference a single YANG package";
"Lists all optional module features that are also
supported by the server when implementing the package.
This list SHOULD exclude any features in the leaf name {
'mandatory-feature' list for the package, or any included type leafref {
package. path '/pkgs:packages/pkgs:package/pkgs:name';
}
description
"The name of the references package.";
}
The full set of features supported by the server for this leaf version {
schema is the union of this list and all type leafref {
'mandatory-feature' lists for the package and all path '/pkgs:packages'
included packages. This is equivalent to the information + '/pkgs:package[pkgs:name = current()/../name]'
provided via the 'feature' leaf list in YANG library. + '/pkgs:version';
}
Features are identified using description
'<module-name>:<feature-name>'"; "The version of the referenced package.";
}
} leaf checksum {
type leafref {
path '/pkgs:packages'
+ '/pkgs:package[pkgs:name = current()/../name]'
+ '[pkgs:version = current()/../version]/pkgs:checksum';
}
description description
"Describes which package the schema directly relates to, if "The checksum of the referenced package.";
any.";
} }
} }
augment "/yanglib:yang-library/yanglib:module-set/yanglib:module" { grouping yang-ds-pkg-ref {
description description
"Add 'replaced-revision' and 'checksum' to implemented module "Defines the list used to reference a set of YANG packages that
definitions."; collectively represent a datastore schema.";
list package {
key "name version";
leaf-list replaces-revision {
type rev:revision-date-or-label;
description description
"Gives the revision of an module (implemented or import-only) "Identifies the YANG packages that collectively defines the
defined in an included package that is replaced by this schema for the associated datastore.
implemented module revision.
Only used for YANG package definitions"; The datastore schema is defined as the union of all
} referenced packages, that MUST represent a referentially
complete schema.
leaf checksum { All of the referenced packages must be compatible with no
type pkg-types:sha-256-hash; conflicting module versions or dependencies.";
description
"The SHA-256 hash calculated on the textual module uses yang-pkg-ref;
definition, represented as a hexadecimal string.";
} }
} }
augment /*
"/yanglib:yang-library/yanglib:module-set/" + * Top level data nodes.
"yanglib:module/yanglib:submodule" { */
description container packages {
"Add 'checksum' to implemented modules' submodule config false;
definitions."; description "All YANG package definitions";
list package {
key "name version";
leaf checksum {
type pkg-types:sha-256-hash;
description description
"The SHA-256 hash calculated on the textual submodule "YANG package instance";
definition, represented as a hexadecimal string.";
uses pkg-types:yang-pkg-instance;
leaf-list location {
type inet:uri;
description
"Contains a URL that represents where an instance data file
for this YANG package can be found.
This leaf will only be present if there is a URL available
for retrieval of the schema for this entry.
If multiple locations are provided, then the first
location in the leaf-list MUST be the definitive location
that uniquely identifies this package";
}
leaf checksum {
type pkg-types:sha-256-hash;
description
"The checksum of the package this schema relates to,
calculated on the 'YANG instance data file' package
definition available in the 'location' leaf list.
This leaf MAY be omitted if the referenced package is
locally scoped without an associated checksum.";
}
} }
} }
augment "/yanglib:yang-library/yanglib:module-set/" + }
"yanglib:import-only-module" { <CODE ENDS>
description <CODE BEGINS> file "ietf-yl-package@2020-01-21.yang"
"Add 'replaces-revision' and 'checksum' to import-only-module module ietf-yl-packages {
definitions"; yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-yl-packages";
prefix yl-pkgs;
leaf-list replaces-revision { import ietf-yang-revisions {
type rev:revision-date-or-label; prefix rev;
description reference "XXXX: Updated YANG Module Revision Handling";
"Gives the revision of an import-only-module defined in an }
imported package that is replaced by this import-only-module
revision.
Only used for YANG package definitions"; import ietf-yang-packages {
} prefix pkgs;
rev:revision-or-derived 0.2.0;
reference "RFC XXX: YANG Packages.";
}
import ietf-yang-library {
prefix yanglib;
rev:revision-or-derived 2019-01-04;
reference "RFC 8525: YANG Library";
leaf checksum {
type pkg-types:sha-256-hash;
description
"The SHA-256 hash calculated on the textual module
definition, represented as a hexadecimal string.";
}
} }
augment "/yanglib:yang-library/yanglib:module-set/" + organization
"yanglib:import-only-module/yanglib:submodule" { "IETF NETMOD (Network Modeling) Working Group";
contact
"WG Web: <http://tools.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org>
Author: Rob Wilton
<mailto:rwilton@cisco.com>";
description
"This module provides defined augmentations to YANG library to
allow a server to report YANG package information.
Copyright (c) 2018 IETF Trust and the persons identified as
authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices.
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
'MAY', and 'OPTIONAL' in this document are to be interpreted as
described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
they appear in all capitals, as shown here.";
// RFC Ed.: update the date below with the date of RFC publication
// and remove this note.
// RFC Ed.: replace XXXX with actual RFC number and remove this
// note.
revision 2020-01-21 {
rev:revision-label 0.2.0;
description description
"Add 'checksum' to import-only-modules' submodule "Initial revision";
definitions."; reference
"RFC XXXX: YANG Packages";
}
/*
* Augmentations
*/
leaf checksum { augment "/yanglib:yang-library/yanglib:schema" {
type pkg-types:sha-256-hash; description
description "Allow datastore schema to be related to a set of YANG
"The SHA-256 hash calculated on the textual submodule packages";
definition, represented as a hexadecimal string.";
} uses pkgs:yang-ds-pkg-ref;
} }
} }
<CODE ENDS> <CODE ENDS>
<CODE BEGINS> file "ietf-yang-inst-data-pkg@2019-09-11.yang" <CODE BEGINS> file "ietf-yang-inst-data-pkg@2020-01-21.yang"
module ietf-yang-inst-data-pkg { module ietf-yang-inst-data-pkg {
yang-version 1.1; yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-inst-data-pkg"; namespace "urn:ietf:params:xml:ns:yang:ietf-yang-inst-data-pkg";
prefix yid-pkg; prefix yid-pkg;
import ietf-yang-revisions { import ietf-yang-revisions {
prefix rev; prefix rev;
reference "XXXX: Updated YANG Module Revision Handling"; reference "XXXX: Updated YANG Module Revision Handling";
} }
import ietf-yang-package-types { import ietf-yang-package-types {
prefix pkg-types; prefix pkg-types;
rev:revision-or-derived 0.1.0; rev:revision-or-derived 0.2.0;
reference "RFC XXX: YANG Schema Versioning."; reference "RFC XXX: YANG Schema Versioning.";
} }
import ietf-yang-structure-ext { import ietf-yang-structure-ext {
prefix sx; prefix sx;
reference "RFC XXX: YANG Data Structure Extensions."; reference "RFC XXX: YANG Data Structure Extensions.";
} }
import ietf-yang-instance-data { import ietf-yang-instance-data {
prefix yid; prefix yid;
skipping to change at page 39, line 22 skipping to change at page 39, line 42
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
'MAY', and 'OPTIONAL' in this document are to be interpreted as 'MAY', and 'OPTIONAL' in this document are to be interpreted as
described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
they appear in all capitals, as shown here."; they appear in all capitals, as shown here.";
// RFC Ed.: update the date below with the date of RFC publication // RFC Ed.: update the date below with the date of RFC publication
// and remove this note. // and remove this note.
// RFC Ed.: replace XXXX with actual RFC number and remove this // RFC Ed.: replace XXXX with actual RFC number and remove this
// note. // note.
revision 2019-09-11 { revision 2020-01-21 {
rev:revision-label 0.1.0; rev:revision-label 0.2.0;
description description
"Initial revision"; "Initial revision";
reference reference
"RFC XXXX: YANG Packages"; "RFC XXXX: YANG Packages";
} }
/* /*
* Augmentations * Augmentations
*/ */
sx:augment-structure sx:augment-structure
"/yid:instance-data-set/yid:content-schema-spec" { "/yid:instance-data-set/yid:content-schema-spec" {
description description
"Add package reference to instance data set schema "Add package reference to instance data set schema
specification"; specification";
case pkg-schema { case pkg-schema {
container pkg-schema { container pkg-schema {
leaf pkg-schema { uses pkg-types:yang-pkg-identification-leafs;
type pkg-types:pkg-identifier;
mandatory true;
description
"The package definition that defines the schema for this
file.";
}
leaf checksum { leaf checksum {
type pkg-types:sha-256-hash; type pkg-types:sha-256-hash;
description description
"The SHA-256 hash of the package, calculated on "The SHA-256 hash of the package, calculated on
the textual package definition, represented as a the textual package definition, represented as a
hexadecimal string."; hexadecimal string.";
} }
leaf-list location { leaf-list location {
type inet:uri; type inet:uri;
description description
"Contains a URL that represents where an instance data "Contains a URL that represents where an instance data
file for this YANG package can be found. file for this YANG package can be found.
This leaf will only be present if there is a URL This leaf will only be present if there is a URL
available for retrieval of the schema for this entry. available for retrieval of the schema for this entry.
If multiple locations are provided, then the first If multiple locations are provided, then the first
skipping to change at page 41, line 40 skipping to change at page 42, line 7
package versions can be obtained from. package versions can be obtained from.
This document requests IANA to registers a URI in the "IETF XML This document requests IANA to registers a URI in the "IETF XML
Registry" [RFC3688]. Following the format in RFC 3688, the following Registry" [RFC3688]. Following the format in RFC 3688, the following
registrations are requested. registrations are requested.
URI: urn:ietf:params:xml:ns:yang:ietf-yang-package-types.yang URI: urn:ietf:params:xml:ns:yang:ietf-yang-package-types.yang
Registrant Contact: The IESG. Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace. XML: N/A, the requested URI is an XML namespace.
URI: urn:ietf:params:xml:ns:yang:ietf-yang-package.yang URI: urn:ietf:params:xml:ns:yang:ietf-yang-package-instance.yang
Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace.
URI: urn:ietf:params:xml:ns:yang:ietf-yang-packages.yang
Registrant Contact: The IESG. Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace. XML: N/A, the requested URI is an XML namespace.
URI: urn:ietf:params:xml:ns:yang:ietf-yl-packages.yang URI: urn:ietf:params:xml:ns:yang:ietf-yl-packages.yang
Registrant Contact: The IESG. Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace. XML: N/A, the requested URI is an XML namespace.
URI: urn:ietf:params:xml:ns:yang:ietf-yang-inst-data-pkg.yang
Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace.
This document requests that the following YANG modules are added in This document requests that the following YANG modules are added in
the "YANG Module Names" registry [RFC6020]: the "YANG Module Names" registry [RFC6020]:
Name: ietf-yang-package-types.yang Name: ietf-yang-package-types.yang
Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-package- Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-package-
types.yang types.yang
Prefix: pkg-types Prefix: pkg-types
Reference: RFC XXXX Reference: RFC XXXX
Name: ietf-yang-package.yang Name: ietf-yang-package-instance.yang
Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-package.yang Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-package-
Prefix: pkg instance.yang
Prefix: pkg-inst
Reference: RFC XXXX
Name: ietf-yang-packages.yang
Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-packages.yang
Prefix: pkgs
Reference: RFC XXXX Reference: RFC XXXX
Name: ietf-yl-packages.yang Name: ietf-yl-packages.yang
Namespace: urn:ietf:params:xml:ns:yang:ietf-yl-packages.yang Namespace: urn:ietf:params:xml:ns:yang:ietf-yl-packages.yang
Prefix: yl-pkg Prefix: yl-pkgs
Reference: RFC XXXX
Name: ietf-yang-inst-data-pkg.yang
Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-inst-data-
pkg.yang
Prefix: yid-pkg
Reference: RFC XXXX Reference: RFC XXXX
13. Open Questions/Issues 13. Open Questions/Issues
All issues, along with the draft text, are currently being tracked at All issues, along with the draft text, are currently being tracked at
https://github.com/rgwilton/YANG-Packages-Draft/issues/ https://github.com/rgwilton/YANG-Packages-Draft/issues/
14. Acknowledgements 14. Acknowledgements
Feedback helping shape this document has kindly been provided by Andy Feedback helping shape this document has kindly been provided by Andy
Bierman, Joe Clarke, James Cumming, Mahesh Jethanandani, Balazs Bierman, Bo Wang, Joe Clarke, James Cumming, Mahesh Jethanandani,
Lengyel, Ladislav Lhotka, Jason Sterne, and Reshad Rahman. Balazs Lengyel, Ladislav Lhotka, Jason Sterne, and Reshad Rahman.
15. References 15. References
15.1. Normative References 15.1. Normative References
[I-D.ietf-netconf-rfc7895bis] [I-D.ietf-netconf-rfc7895bis]
Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K.,
and R. Wilton, "YANG Library", draft-ietf-netconf- and R. Wilton, "YANG Library", draft-ietf-netconf-
rfc7895bis-07 (work in progress), October 2018. rfc7895bis-07 (work in progress), October 2018.
[I-D.ietf-netmod-module-tags] [I-D.ietf-netmod-module-tags]
Hopps, C., Berger, L., and D. Bogdanovic, "YANG Module Hopps, C., Berger, L., and D. Bogdanovic, "YANG Module
Tags", draft-ietf-netmod-module-tags-09 (work in Tags", draft-ietf-netmod-module-tags-09 (work in
progress), September 2019. progress), September 2019.
[I-D.ietf-netmod-yang-data-ext] [I-D.ietf-netmod-yang-data-ext]
Bierman, A., Bjorklund, M., and K. Watsen, "YANG Data Bierman, A., Bjorklund, M., and K. Watsen, "YANG Data
Structure Extensions", draft-ietf-netmod-yang-data-ext-04 Structure Extensions", draft-ietf-netmod-yang-data-ext-05
(work in progress), July 2019. (work in progress), December 2019.
[I-D.ietf-netmod-yang-instance-file-format] [I-D.ietf-netmod-yang-instance-file-format]
Lengyel, B. and B. Claise, "YANG Instance Data File Lengyel, B. and B. Claise, "YANG Instance Data File
Format", draft-ietf-netmod-yang-instance-file-format-04 Format", draft-ietf-netmod-yang-instance-file-format-06
(work in progress), August 2019. (work in progress), December 2019.
[I-D.verdt-netmod-yang-module-versioning] [I-D.verdt-netmod-yang-module-versioning]
Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel,
B., Sterne, J., and K. D'Souza, "Updated YANG Module B., Sterne, J., and K. D'Souza, "Updated YANG Module
Revision Handling", draft-verdt-netmod-yang-module- Revision Handling", draft-verdt-netmod-yang-module-
versioning-01 (work in progress), October 2019. versioning-01 (work in progress), October 2019.
[I-D.verdt-netmod-yang-semver] [I-D.verdt-netmod-yang-semver]
Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel,
B., Sterne, J., and K. D'Souza, "YANG Semantic B., Sterne, J., and K. D'Souza, "YANG Semantic
Versioning", draft-verdt-netmod-yang-semver-01 (work in Versioning", draft-verdt-netmod-yang-semver-01 (work in
progress), October 2019. progress), October 2019.
[I-D.verdt-netmod-yang-solutions] [I-D.verdt-netmod-yang-solutions]
Wilton, R., "YANG Versioning Solution Overview", draft- Wilton, R., "YANG Versioning Solution Overview", draft-
verdt-netmod-yang-solutions-01 (work in progress), July verdt-netmod-yang-solutions-02 (work in progress),
2019. November 2019.
[I-D.verdt-netmod-yang-versioning-reqs] [I-D.verdt-netmod-yang-versioning-reqs]
Clarke, J., "YANG Module Versioning Requirements", draft- Clarke, J., "YANG Module Versioning Requirements", draft-
verdt-netmod-yang-versioning-reqs-02 (work in progress), verdt-netmod-yang-versioning-reqs-02 (work in progress),
November 2018. November 2018.
[I-D.wilton-netmod-yang-ver-selection] [I-D.wilton-netmod-yang-ver-selection]
Wilton, R. and R. Rahman, "YANG Schema Version Selection", Wilton, R., Rahman, R., and J. Clarke, "YANG Schema
draft-wilton-netmod-yang-ver-selection-00 (work in Version Selection", draft-wilton-netmod-yang-ver-
progress), March 2019. selection-01 (work in progress), November 2019.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
DOI 10.17487/RFC3688, January 2004, DOI 10.17487/RFC3688, January 2004,
<https://www.rfc-editor.org/info/rfc3688>. <https://www.rfc-editor.org/info/rfc3688>.
skipping to change at page 45, line 6 skipping to change at page 45, line 34
DOI 10.17487/RFC8525, March 2019, DOI 10.17487/RFC8525, March 2019,
<https://www.rfc-editor.org/info/rfc8525>. <https://www.rfc-editor.org/info/rfc8525>.
15.2. Informative References 15.2. Informative References
[I-D.bierman-netmod-yang-package] [I-D.bierman-netmod-yang-package]
Bierman, A., "The YANG Package Statement", draft-bierman- Bierman, A., "The YANG Package Statement", draft-bierman-
netmod-yang-package-00 (work in progress), July 2015. netmod-yang-package-00 (work in progress), July 2015.
[I-D.ietf-netmod-artwork-folding] [I-D.ietf-netmod-artwork-folding]
Watsen, K., Farrel, A., and Q. WU, "Handling Long Lines in Watsen, K., Auerswald, E., Farrel, A., and Q. WU,
Inclusions in Internet-Drafts and RFCs", draft-ietf- "Handling Long Lines in Inclusions in Internet-Drafts and
netmod-artwork-folding-10 (work in progress), September RFCs", draft-ietf-netmod-artwork-folding-12 (work in
2019. progress), January 2020.
[openconfigsemver] [openconfigsemver]
"Semantic Versioning for OpenConfig Models", "Semantic Versioning for OpenConfig Models",
<http://www.openconfig.net/docs/semver/>. <http://www.openconfig.net/docs/semver/>.
[RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module [RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module
Classification", RFC 8199, DOI 10.17487/RFC8199, July Classification", RFC 8199, DOI 10.17487/RFC8199, July
2017, <https://www.rfc-editor.org/info/rfc8199>. 2017, <https://www.rfc-editor.org/info/rfc8199>.
Appendix A. Tree output for ietf-yang-library with package Appendix A. Examples
augmentations
Complete tree output for ietf-yang-library with package
augmentations.
module: ietf-yang-library
+--ro yang-library
| +--ro module-set* [name]
| | +--ro name string
| | +--ro module* [name]
| | | +--ro name yang:yang-identifier
| | | +--ro revision? revision-identifier
| | | +--ro namespace inet:uri
| | | +--ro location* inet:uri
| | | +--ro submodule* [name]
| | | | +--ro name yang:yang-identifier
| | | | +--ro revision? revision-identifier
| | | | +--ro location* inet:uri
| | | | +--ro yl-pkg:checksum? pkg-types:sha-256-hash
| | | +--ro feature* yang:yang-identifier
| | | +--ro deviation* -> ../../module/name
| | | +--ro yl-pkg:replaces-revision*
| | | | yanglib:revision-identifier
| | | +--ro yl-pkg:checksum? pkg-types:sha-256-hash
| | +--ro import-only-module* [name revision]
| | +--ro name yang:yang-identifier
| | +--ro revision union
| | +--ro namespace inet:uri
| | +--ro location* inet:uri
| | +--ro submodule* [name]
| | | +--ro name yang:yang-identifier
| | | +--ro revision? revision-identifier
| | | +--ro location* inet:uri
| | | +--ro pkg:checksum? pkg-types:sha-256-hash
| | +--ro yl-pkg:replaces-revision*
| | | yanglib:revision-identifier
| | +--ro yl-pkg:checksum? pkg-types:sha-256-hash
| +--ro schema* [name]
| | +--ro name string
| | +--ro module-set* -> ../../module-set/name
| | +--ro yl-pkg:package
| | +--ro yl-pkg:name?
| | | -> /yanglib:yang-library/package/name
| | +--ro yl-pkg:version? leafref
| | +--ro yl-pkg:supported-feature* pkg-types:scoped-feature
| +--ro datastore* [name]
| | +--ro name ds:datastore-ref
| | +--ro schema -> ../../schema/name
| +--ro content-id string
| +--ro yl-pkg:package* [name version]
| +--ro yl-pkg:name yang:yang-identifier
| +--ro yl-pkg:version rev:revision-label
| +--ro yl-pkg:timestamp? yang:date-and-time
| +--ro yl-pkg:organization? string
| +--ro yl-pkg:contact? string
| +--ro yl-pkg:description? string
| +--ro yl-pkg:reference? string
| +--ro yl-pkg:complete? boolean
| +--ro yl-pkg:location* inet:uri
| +--ro yl-pkg:local? boolean
| +--ro yl-pkg:previous-version? yang-sem-ver
| +--ro yl-pkg:nbc-changes? boolean
| +--ro yl-pkg:tag* tags:tag
| +--ro yl-pkg:mandatory-feature* string
| +--ro yl-pkg:included-package* [name version]
| | +--ro yl-pkg:name yang:yang-identifier
| | +--ro yl-pkg:version rev:revision-label
| | +--ro yl-pkg:replaces-version* rev:revision-label
| | +--ro yl-pkg:nbc-modified? boolean
| | +--ro yl-pkg:location* inet:uri
| | +--ro yl-pkg:checksum? string
| +--ro yl-pkg:module-set*
| | -> /yanglib:yang-library/module-set/name
| +--ro yl-pkg:checksum? pkg-types:sha-256-hash
x--ro modules-state
x--ro module-set-id string
x--ro module* [name revision]
x--ro name yang:yang-identifier
x--ro revision union
+--ro schema? inet:uri
x--ro namespace inet:uri
x--ro feature* yang:yang-identifier
x--ro deviation* [name revision]
| x--ro name yang:yang-identifier
| x--ro revision union
x--ro conformance-type enumeration
x--ro submodule* [name revision]
x--ro name yang:yang-identifier
x--ro revision union
+--ro schema? inet:uri
notifications:
+---n yang-library-update
| +--ro content-id -> /yang-library/content-id
x---n yang-library-change
x--ro module-set-id -> /modules-state/module-set-id
Appendix B. Examples
This section provides various examples of YANG packages, and as such This section provides various examples of YANG packages, and as such
this text is non-normative. The purpose of the examples is to only this text is non-normative. The purpose of the examples is to only
illustrate the file format of YANG packages, and how package illustrate the file format of YANG packages, and how package
dependencies work. It does not imply that such packages will be dependencies work. It does not imply that such packages will be
defined by IETF, or which modules would be included in those packages defined by IETF, or which modules would be included in those packages
even if they were defined. For brevity, the examples exclude even if they were defined. For brevity, the examples exclude
namespace declarations, and use a shortened URL of "tiny.cc/ietf- namespace declarations, and use a shortened URL of "tiny.cc/ietf-
yang" as a replacement for yang" as a replacement for
"https://raw.githubusercontent.com/YangModels/yang/master/standard/ "https://raw.githubusercontent.com/YangModels/yang/master/standard/
ietf/RFC". ietf/RFC".
B.1. Example IETF Network Device YANG package A.1. Example IETF Network Device YANG package
This section provides an instance data document example of an IETF This section provides an instance data document example of an IETF
Network Device YANG package formatted in JSON. Network Device YANG package formatted in JSON.
This example package is intended to represent the standard set of This example package is intended to represent the standard set of
YANG modules, with import dependencies, to implement a basic network YANG modules, with import dependencies, to implement a basic network
device without any dynamic routing or layer 2 services. E.g., it device without any dynamic routing or layer 2 services. E.g., it
includes functionality such as system information, interface and includes functionality such as system information, interface and
basic IP configuration. basic IP configuration.
skipping to change at page 48, line 16 skipping to change at page 46, line 38
========= NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== ========= NOTE: '\' line wrapping per BCP XX (RFC XXXX) ===========
{ {
"ietf-yang-instance-data:instance-data-set": { "ietf-yang-instance-data:instance-data-set": {
"name": "example-ietf-network-device-pkg", "name": "example-ietf-network-device-pkg",
"pkg-schema": { "pkg-schema": {
package: "ietf-yang-package-defn-pkg@0.1.0.json" package: "ietf-yang-package-defn-pkg@0.1.0.json"
}, },
"description": "YANG package definition", "description": "YANG package definition",
"content-data": { "content-data": {
"ietf-yang-package:yang-package": { "ietf-yang-package-instance:yang-package": {
"name": "example-ietf-network-device-pkg", "name": "example-ietf-network-device-pkg",
"version": "1.1.2", "version": "1.1.2",
"timestamp": "2018-12-13T17:00:00Z", "timestamp": "2018-12-13T17:00:00Z",
"organization": "IETF NETMOD Working Group", "organization": "IETF NETMOD Working Group",
"contact" : "WG Web: <http://tools.ietf.org/wg/netmod/>, \ "contact" : "WG Web: <http://tools.ietf.org/wg/netmod/>, \
WG List: <mailto:netmod@ietf.org>", WG List: <mailto:netmod@ietf.org>",
"description": "Example IETF network device YANG package.\ "description": "Example IETF network device YANG package.\
\ \
This package defines a small sample set of \ This package defines a small sample set of \
YANG modules that could represent the basic set of \ YANG modules that could represent the basic set of \
skipping to change at page 50, line 4 skipping to change at page 48, line 28
{ {
"name": "ietf-inet-types", "name": "ietf-inet-types",
"revision": "2013-07-15", "revision": "2013-07-15",
"location": [ "https://tiny.cc/ietf-yang/\ "location": [ "https://tiny.cc/ietf-yang/\
ietf-inet-types%402013-07-15.yang" ], ietf-inet-types%402013-07-15.yang" ],
"checksum": "12d98b0143a5ca5095b36420f9ebc1ff\ "checksum": "12d98b0143a5ca5095b36420f9ebc1ff\
a61cfd2eaa850080244cadf01b86ddf9" a61cfd2eaa850080244cadf01b86ddf9"
} }
] ]
} }
} }
} }
} }
<CODE ENDS> <CODE ENDS>
B.2. Example IETF Basic Routing YANG package A.2. Example IETF Basic Routing YANG package
This section provides an instance data document example of a basic This section provides an instance data document example of a basic
IETF Routing YANG package formatted in JSON. IETF Routing YANG package formatted in JSON.
This example package is intended to represent the standard set of This example package is intended to represent the standard set of
YANG modules, with import dependencies, that builds upon the example- YANG modules, with import dependencies, that builds upon the example-
ietf-network-device YANG package to add support for basic dynamic ietf-network-device YANG package to add support for basic dynamic
routing and ACLs. routing and ACLs.
As for all YANG packages, all import dependencies are fully resolved. As for all YANG packages, all import dependencies are fully resolved.
skipping to change at page 50, line 37 skipping to change at page 49, line 14
<CODE BEGINS> file "example-ietf-routing-pkg.json" <CODE BEGINS> file "example-ietf-routing-pkg.json"
========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== ========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) ===========
{ {
"ietf-yang-instance-data:instance-data-set": { "ietf-yang-instance-data:instance-data-set": {
"name": "example-ietf-routing-pkg", "name": "example-ietf-routing-pkg",
"module": [ "ietf-yang-package@2019-09-11.yang" ], "module": [ "ietf-yang-package@2019-09-11.yang" ],
"description": "YANG package definition", "description": "YANG package definition",
"content-data": { "content-data": {
"ietf-yang-package:yang-package": { "ietf-yang-package-instance:yang-package": {
"name": "example-ietf-routing", "name": "example-ietf-routing",
"version": "1.3.1", "version": "1.3.1",
"timestamp": "2018-12-13T17:00:00Z", "timestamp": "2018-12-13T17:00:00Z",
"description": "This package defines a small sample set of \ "description": "This package defines a small sample set of \
IETF routing YANG modules that could represent the set of \ IETF routing YANG modules that could represent the set of \
IETF routing functionality that a basic IP network device \ IETF routing functionality that a basic IP network device \
might be expected to support.", might be expected to support.",
"reference": "XXX, draft-rwilton-netmod-yang-packages", "reference": "XXX, draft-rwilton-netmod-yang-packages",
"imported-packages": [ "imported-packages": [
{ {
skipping to change at page 53, line 4 skipping to change at page 51, line 27
"revision": "2018-05-09", "revision": "2018-05-09",
"location": [ "https://tiny.cc/ietf-yang/\ "location": [ "https://tiny.cc/ietf-yang/\
" ], " ],
"checksum": "" "checksum": ""
}, },
{ {
"name": "ietf-packet-fields", "name": "ietf-packet-fields",
"revision": "2018-11-06", "revision": "2018-11-06",
"location": [ "https://tiny.cc/ietf-yang/\ "location": [ "https://tiny.cc/ietf-yang/\
" ], " ],
"checksum": "" "checksum": ""
}, },
{ {
"name": "ietf-ethertypes", "name": "ietf-ethertypes",
"revision": "2018-11-06", "revision": "2018-11-06",
"location": [ "https://tiny.cc/ietf-yang/\ "location": [ "https://tiny.cc/ietf-yang/\
" ], " ],
"checksum": "" "checksum": ""
} }
] ]
} }
} }
} }
} }
<CODE ENDS> <CODE ENDS>
B.3. Package import conflict resolution example A.3. Package import conflict resolution example
This section provides an example of how a package can resolve This section provides an example of how a package can resolve
conflicting module versions from imported packages. conflicting module versions from imported packages.
In this example, YANG package 'example-3-pkg' imports both 'example- In this example, YANG package 'example-3-pkg' imports both 'example-
import-1' and 'example-import-2' packages. However, the two imported import-1' and 'example-import-2' packages. However, the two imported
packages implement different versions of 'example-module-A' so the packages implement different versions of 'example-module-A' so the
'example-3-pkg' package selects version '1.2.3' to resolve the 'example-3-pkg' package selects version '1.2.3' to resolve the
conflict. Similarly, for import-only modules, the 'example-3-pkg' conflict. Similarly, for import-only modules, the 'example-3-pkg'
package does not require both versions of example-types-module-C to package does not require both versions of example-types-module-C to
be imported, so it indicates that it only imports revision be imported, so it indicates that it only imports revision
'2018-11-26' and not '2018-01-01'. '2018-11-26' and not '2018-01-01'.
{ {
"ietf-yang-instance-data:instance-data-set": { "ietf-yang-instance-data:instance-data-set": {
"name": "example-import-1-pkg", "name": "example-import-1-pkg",
"description": "First imported example package", "description": "First imported example package",
"content-data": { "content-data": {
"ietf-yang-package:yang-package": { "ietf-yang-package-instance:yang-package": {
"name": "example-import-1", "name": "example-import-1",
"version": "1.0.0", "version": "1.0.0",
"reference": "XXX, draft-rwilton-netmod-yang-packages", "reference": "XXX, draft-rwilton-netmod-yang-packages",
"revision-date": "2018-01-01", "revision-date": "2018-01-01",
"module": [ "module": [
{ {
"name": "example-module-A", "name": "example-module-A",
"version": "1.0.0" "version": "1.0.0"
}, },
{ {
skipping to change at page 55, line 30 skipping to change at page 54, line 4
"revision-date": "2018-11-26", "revision-date": "2018-11-26",
"included-package": [ "included-package": [
{ {
"name": "example-import-1", "name": "example-import-1",
"version": "1.0.0" "version": "1.0.0"
}, },
{ {
"name": "example-import-2", "name": "example-import-2",
"version": "2.0.0" "version": "2.0.0"
} }
], ],
"module": [ "module": [
{ {
"name": "example-module-A", "name": "example-module-A",
"version": "1.2.3" "version": "1.2.3"
} }
], ],
"import-only-module": [ "import-only-module": [
{ {
"name": "example-types-module-C", "name": "example-types-module-C",
"revision": "2018-11-26", "revision": "2018-11-26",
"replaces-revision": [ "2018-01-01 "] "replaces-revision": [ "2018-01-01 "]
} }
] ]
} }
} }
} }
} }
Appendix C. Possible alternative solutions Appendix B. Possible alternative solutions
This section briefly describes some alternative solutions. It can be This section briefly describes some alternative solutions. It can be
removed if this document is adopted as a WG draft. removed if this document is adopted as a WG draft.
C.1. Using module tags B.1. Using module tags
Module tags have been suggested as an alternative solution, and Module tags have been suggested as an alternative solution, and
indeed that can address some of the same requirements as YANG indeed that can address some of the same requirements as YANG
packages but not all of them. packages but not all of them.
Module tags can be used to group or organize YANG modules. However, Module tags can be used to group or organize YANG modules. However,
this raises the question of where this tag information is stored. this raises the question of where this tag information is stored.
Module tags either require that the YANG module files themselves are Module tags either require that the YANG module files themselves are
updated with the module tag information (creating another versioning updated with the module tag information (creating another versioning
problem), or for the module tag information to be hosted elsewhere, problem), or for the module tag information to be hosted elsewhere,
skipping to change at page 56, line 33 skipping to change at page 55, line 5
One of the principle aims of YANG packages is to be a versioned One of the principle aims of YANG packages is to be a versioned
object that defines a precise set of YANG modules versions that work object that defines a precise set of YANG modules versions that work
together. Module tags cannot meet this aim without an explosion of together. Module tags cannot meet this aim without an explosion of
module tags definitions (i.e. a separate module tag must be defined module tags definitions (i.e. a separate module tag must be defined
for each package version). for each package version).
Module tags cannot support the hierachical scheme to construct YANG Module tags cannot support the hierachical scheme to construct YANG
schema that is proposed in this draft. schema that is proposed in this draft.
C.2. Using YANG library B.2. Using YANG library
Another question is whether it is necessary to define new YANG Another question is whether it is necessary to define new YANG
modules to define YANG packages, and whether YANG library could just modules to define YANG packages, and whether YANG library could just
be reused in an instance data document. The use of YANG packages be reused in an instance data document. The use of YANG packages
offers several benefits over just using YANG library: offers several benefits over just using YANG library:
1. Packages allow schema to be built in a hierarchical fashion. 1. Packages allow schema to be built in a hierarchical fashion.
[I-D.ietf-netconf-rfc7895bis] only allows one layer of hierarchy [I-D.ietf-netconf-rfc7895bis] only allows one layer of hierarchy
(using module sets), and there must be no conflicts between (using module sets), and there must be no conflicts between
module revisions in different module-sets. module revisions in different module-sets.
skipping to change at page 57, line 23 skipping to change at page 55, line 42
containing this information. The module definition for a YANG containing this information. The module definition for a YANG
package is specified to contain all of the ncessary information package is specified to contain all of the ncessary information
to solve the problem without augmentations to solve the problem without augmentations
5. YANG library is designed to publish information about the 5. YANG library is designed to publish information about the
modules, datastores, and datastore schema used by a server. The modules, datastores, and datastore schema used by a server. The
information required to construct an off box schema is not information required to construct an off box schema is not
precisely the same, and hence the definitions might deviate from precisely the same, and hence the definitions might deviate from
each other over time. each other over time.
Author's Address Authors' Addresses
Robert Wilton Robert Wilton (editor)
Cisco Systems, Inc. Cisco Systems, Inc.
Email: rwilton@cisco.com Email: rwilton@cisco.com
Reshad Rahman
Cisco Systems, Inc.
Email: rrahman@cisco.com
Joe Clarke
Cisco Systems, Inc.
Email: jclarke@cisco.com
Jason Sterne
Nokia
Email: jason.sterne@nokia.com
Bo Wu
Huawei
Email: lana.wubo@huawei.com
 End of changes. 128 change blocks. 
628 lines changed or deleted 565 lines changed or added

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