YANG Conformance SpecificationYumaWorksandy@yumaworks.com
This document describes conformance specification
and advertisement mechanisms for NETCONF servers
implementing YANG data model modules.
There is a need for standard mechanisms to
allow YANG data model designers to express more
precise and robust conformance levels for
server implementations of a particular YANG module,
or set of YANG modules.
There is also a need for standard mechanisms to
allow NETCONF servers to precisely advertise the
conformance level of each YANG module it supports.
This document describes some problems with the current
conformance specifications mechanisms in YANG and
conformance advertisement mechanisms in NETCONF.
Solution proposals are also presented to address these problems.
The keywords "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, .
The following terms are defined in :
capability
client
datastore
protocol operation
server
The following terms are defined in :
data node
extension
feature
grouping
identity
module
notification
submodule
typedef
The following terms are used within this document:
conditional node: An object that
has one or more "if‑feature" sub-statements associated with it.
Note that objects affected by "when" statements are not considered
conditional for conformance purposes.
conformance profile: A set of requirements that a server must
support to comply with a given service level. These
requirements can be specified in terms of required
YANG modules (possibly with specific YANG features and objects supported),
other conformance profiles, and/or NETCONF capability URIs
(for server functionality that is not specified in YANG modules).
import-by-revision: A YANG import statement that includes
a revision-date statement. This specifies the exact revision
of the YANG module to import, instead of the server picking
the revision to import.
module base: There is an implied "base" version of the module, which includes
all statements which are not conditional. The module base may be empty,
a subset of all statements, or the entire module.
object: a conceptual data structure represented by a
YANG data, rpc, or notification statement.
schema tree: The conceptual tree of all objects derived from
the set of all YANG modules supported by the server. This tree
only includes conditional nodes if all corresponding if-feature
statements are "true". Any deviation statements have also been
conceptually applied to the schema tree as well.
YANG feature set: The set of all objects
from a particular module that contain an if-feature statement
that corresponds to a particular YANG feature statement.
YANG package: A set of conformance profiles that can be extended
over time. Also called "package".
This section describes some perceived deficiencies with
the current data model conformance specification and
server conformance advertisement mechanisms used in NETCONF.
The YANG data modeling language provides many powerful
data modeling constructs to allow the automation of
network configuration protocol operations. However it does not
provide enough control over the precise server
conformance levels that a client can expect.
This has a negative impact on interoperability.
A YANG module is conceptually divided into the module base
and zero or more purely optional YANG feature sets.
This approach does not allow enough flexibility and can
become difficult to use as the module size and
number of YANG feature statements increases. A set of
boolean flags that are logically combined as an "AND" expression
is too simplistic a mechanism for expressing the criteria for
specifying conditional conformance requirements.
YANG provides a mechanism to import an exact revision
of an external module in order to freeze conformance
requirements for a module. If this is not used then
the YANG compiler will most likely use the latest revision
of the imported module that happens to be implemented
by the server.
If new data nodes, notifications, or protocol operations are
added to an imported module over time, then it can appear to
a NETCONF client that the new objects are implemented if
the imported module is updated but not all the modules
that import it. Objects using imported typedefs will
change syntax and semantics if the typedef (or any typedef
it refines) is changed.
Unless import-by-revision is used everywhere an import is used
within the dependency chain, the exact module definition cannot
really be frozen for conformance purposes.
A server is not required to support multiple revisions of the same
module at the same time. This may be very confusing to the client,
and complex to implement as well. Instead, servers usually allow
only one revision of each module to be implemented within the system.
If import-by-revision is used, then creating a new revision of
the imported module requires that the import statements in all
the importing modules be updated to use the new revision
date. This requires a revision change, so any module that imports
those modules also needs to be updated to specify the new revision
date of those importing modules. This ripple effect can cause
a lot of modules to be updated. It may not be possible to
update a module import date in some cases, if that would
incorrectly advertise to the client that new objects
were implemented by the server.
Conformance requirements can change over time.
New use cases and new consensus about optionality can occur.
A conformance statement for each use-case is needed, not
just one or more (implied) conformance statements per module.
There are no mechanisms to clearly specify external module dependencies.
There is no way to indicate the exact portions
of an imported module which are required to comply with
a particular conformance level for the importing module.
There is no way to specify that multiple modules are required
to provide a high-level service.
It is impossible to predict all valid use cases at design time.
Partitioning a module into a base plus purely optional features
can only account for the features and use cases known at the
time. Future designers cannot alter if-feature statements
or add new if-feature statements to an augmented module.
YANG features are purely optional to implement.
There is no way to specify that a set of objects are
conditionally mandatory, based on some data-model specific
criteria. Conditions could be expressed with XPath must
or when expressions, but this has to be repeated everywhere
it is used and the set of objects with the same conditionally
mandatory properties is un-named and hard for the reader to identify.
YANG features are too simplistic.
They are good for a small number of use-cases within one module.
Once there are lots of features, interactions between features, and
refined use-cases, they turn the module into a bowl of boolean spaghetti.
YANG features are not really purely optional in practice.
Sometimes they are used to express separate roles or service subsets within
the module. It is difficult for the reader to identify the valid combinations
of purely optional YANG features that represent high-level roles.
The YANG if-feature statements are logically combined as a
boolean "AND" expression and not very flexible. YANG description
statements are not really machine parsable, so these high-level
roles or service groupings are not easily identifiable.
YANG deviations could possibly be used as a low-level
conformance solution, but they are undesirable and not used
by server vendors. YANG deviation statements provide a fairly
comprehensive "patch" mechanism to conceptually alter
YANG data definition statements. This alteration,
or declaration of non-implementation, describes how a
server deviates from the standard data definitions.
These statements are not allowed to appear in standard YANG modules,
and it turns out that vendors would rather not specify
exactly how their server is non-compliant
to a standard YANG module. A vendor would rarely need a deviation statement
for their own YANG data modules.
YANG deviation statements are too low-level anyway, even if
vendors were willing to use them. They do not fully address the
future use-case problem because they can only be used
to make specific patches to data statements.
YANG conformance applies only to one module.
There are no mechanisms to precisely identify
the conformance relationship between modules.
Since YANG is designed to be modular and reusable,
it is quite likely that a high-level feature or service
will be specified with more than one YANG module.
All the top-level definitions are imported from a module
whether the importing module uses all the definitions or not.
This is too general from a conformance perspective.
Sometimes modules are imported just for typedefs or
identities, which are always part of the base.
If a module augments a node in another module,
it does not imply that it supports all other objects
from that module.
YANG conformance does not actually address any relationship
between modules. There are no mechanisms to express
multi-module conformance requirements.
It is difficult for a client application developer to
identify the high level server capabilities from a large
set of module capabilities. There are no formal mechanisms
to identity the definition of a high-level service across
multiple modules.
NETCONF servers advertise the YANG modules they support
as <capability> URI strings in the <hello> message.
The complete list of modules used by the server needs to
be advertised in order for the client application to correctly parse the
YANG modules and reproduce the schema tree used by the server.
However the client does not really know which modules are advertised
for full conformance, and which are advertised for partial
conformance (such as importing
typedef and identity statements from the module).
The solution in this document attempts to achieve several objectives:
Provide simple documentation mechanisms that are readable
and easy to understand.
Provide simple mechanisms that can scale in usage from one module to
thousands of modules.
Provide per use-case conformance profiles, which allow multiple
conformance levels to be specified for a single module.
Provide per use-case conformance profiles, which allow multiple
modules to be specified for a single conformance profile.
Clarify the usage relationship between an augmented module
and the augmenting module.
Clarify the usage relationship between modules that represent
parts of the same conceptual high-level service.
Provide the ability to specify a stable conformance definition
that cannot implicitly change if YANG modules are updated.
Provide the ability to specify the YANG features that must
be supported by a server to meet conformance requirements.
A YANG package is a conformance definition for one or more
YANG modules and/or NETCONF protocol capabilities. Each package
has one or more conformance profiles that describe the
server implementation requirements to conform to a
specific profile within a package.
YANG packages are static representations of YANG conformance,
meaning there
are no server-dependent variables (e.g, set of purely optional
YANG features selected by the server). Instead a conformance
profile specifies which YANG features a server needs to
support to conform to the profile.
A particular revision of a YANG package can be considered
a snapshot in time of the specific module and profile
revisions required for package conformance.
YANG packages are defined using a text file similar to YANG modules.
However they are separate from YANG modules, since a package can
require more than one YANG module for conformance.
Unlike YANG modules, YANG package definitions do not represent
content that would appear in a protocol message. They represent
server conformance requirements and are therefore separate
from YANG module definitions.
A YANG package is advertised with a <capability> URI string,
similar to a YANG module. A NETCONF server will advertise all
its supported package capability statements in the <hello> message
it sends to each client.
A YANG package file consists of UTF-8 characters.
The basic syntax is exactly the same as for YANG modules.
Several YANG statements are "imported" from the YANG ABNF,
and some new statements are defined. Specifically,
YANG package syntax is the same as RFC 6020, sections 6,
6.1, 6.2, and 6.3.
[FIXME: not all namespaces in sec. 6.2.1 are supported
and a namespace for YANG package names is not defined there.]
At least one revision statement MUST be present in a YANG
package file. A new revision MUST be added each time the
YANG package file is published. This requirement is more
strict than RFC 6020 to ensure that conformance requirements
can be properly identified for each server implementation.
A conformance profile represents a conceptual set of
server implementation requirements to meet one or more use-cases
or variants of the conceptual service represented by the YANG
package.
A conformance profile can overlap or even include other
conformance profiles. It is a data-model specific matter
what requirements make operational sense.
A server can conform to one or more conformance profiles
within a YANG package.
A new NETCONF capability URI is defined to advertise YANG package
conformance. A server will announce conformance for one or more
conformance profiles, for each YANG package it supports.
Refer to for details
on YANG package conformance advertisement.
In this example, 1 conformance profile called "base" is defined
for the YANG package named "ietf‑types‑pkg".
In this example, 3 different conformance profiles are defined
for the YANG package named "ietf‑routing‑pkg":
base: a server that supports the base routing profile. This profile
is probably not useful without adding routing protocols, but it is
needed for extensibility.
ipv4: a server that supports IPv4 routing configuration
ipv6: a server that supports IPv6 routing configuration
In this example, 5 different conformance profiles are defined
for the YANG package named "ietf‑netconf‑pkg":
core: core NETCONF functionality.
running: a server that supports writing directly to
the running datastore.
startup: a server that supports writing directly to
the running datastore and also has a separate startup
datastore.
candidate:- running: a server that supports writing
to the candidate datastore and committing all edits
at once to the running datastore.
confirmed:- running: a server that supports the
candidate conformance profile and also supports
the confirmed commit operations.
The "package" statement defines the YANG package's name, and contains
all YANG package header information and conformance profile statements.
The "package" statement's argument is the name of the YANG package,
followed by a block of substatements that hold detailed
package information. The package name follows the rules
for identifiers in RFC 6020, section 6.2.
A YANG package name is defined in the same conceptual namespace
as YANG module names. The same rules for selecting non-conflicting
names apply as defined in RFC 6020, section 7.1.
An IANA registry for YANG package names will be needed,
similar to mechanism described in RFC 6020, section 14.
SubstatementReferenceCardinalitycontactRFC 6020, 7.1.80..1descriptionRFC 6020, 7.19.30..1namespaceRFC 6020, 7.1.31organizationRFC 6020, 7.1.70..1profile1..nreferenceRFC 6020, 7.19.40..1revisionRFC 6020, 7.1.91..nyangconf-version0..1
The optional "yangconf‑version" statement specifies which version of the
YANG conformance specification language was used in developing the module.
The statement's argument is a string.
If present, it MUST contain the value "1",
which is the current YANG Conformance language version and the default value.
Handling of the "yangconf‑version" statement for versions other than "1"
(the version defined here) is out of scope for this specification.
Any document that defines a higher version will need to define the
backward compatibility of such a higher version.
The "profile" statement is used to define one conformance profile
within a YANG package. It takes as an argument the profile name,
which is followed by a block of substatements that hold detailed
conformance information. The package name follows the rules
for identifiers in RFC 6020, section 6.2.
A conformance profile SHOULD NOT require any capabilities,
modules, definitions, within a module, that have an obsolete
"status" statement value.
If a conformance profile does reference obsolete definitions
then it SHOULD be republished with an obsolete status, or a
new YANG package revision published which updates
the obsolete profile definition.
SubstatementReferenceCardinalitydescriptionRFC 6020, 7.19.30..1include-profile0..nreferenceRFC 6020, 7.19.40..1require-capability0..nrequire-module0..nrequire-package0..nstatusRFC 6020, 7.19.20..1
The "include‑profile" statement is used to combine
multiple conformance profiles from the same YANG package.
It takes as an argument the name of the conformance profile
to include. There are no substatements defined.
All of the requirements in the included profile
are also required in the profile that contains
the include-profile statement.
If any require-module, require-package, and/or
require-capability statements overlap due to multiple
included profiles, then they are logically combined
such that all requirements from all profiles are
included.
A profile MUST NOT include itself or any conformance profile
that would cause itself to be included via a dependency loop.
The "require‑module" statement is used to require
support for some or all of the definitions in a specific module.
It takes as an argument the name of the module
to require, followed by a block of substatements that
hold detailed module server support requirements.
A require-module statement MUST NOT specify the same module name
as another require-module statement in the same profile statement.
Submodules are invisible for conformance purposes,
because they are used as an implementation mechanism,
and are not directly accessible from an external module.
SubstatementReferenceCardinalitydescriptionRFC 6020, 7.19.30..1revision1referenceRFC 6020, 7.19.40..1require-conformance0..1require-feature0..nrequire-object0..n
The "revision" statement is a mandatory statement used to specify the
revision date for the required module needed for compliance
to the conformance profile containing this statement.
It takes as argument a date string in the form "YYYY‑MM‑DD"
where "YYYY" is the year, "MM" is the month, and "DD" is the day.
It is a data-model specific matter whether or not revisions of
the required module released after this date are acceptable for
profile conformance.
The "require‑conformance" statement is used to describe the
type of module conformance that is needed to meet
the conformance profile requirements. Its argument
is an enumerated string value indicating the
type of module conformance required.
There are 4 types of module conformance supported:
full: Full implementation of the module base is required.
This is the default value if the require-conformance
statement is not present.
augment: full implementation of the objects that are augmented
in this module (from the augmenting module) is required.
import: the module is required for meta-data definitions,
which includes extension, typedef, grouping, identity,
and feature statements. No implementation of any objects
in the module is required.
ad-hoc: Partial implementation of the module base and/or
some conditional nodes is required. The require-module
statement SHOULD contain "require‑object" statements
to identify the ad-hoc requirements.
The "require‑feature" statement is used to indicate that
the specified YANG feature set is required for profile conformance.
It takes as argument the name of the YANG feature that is required,
and is followed by a block of substatements that describe the
YANG feature usage within the conformance profile.
SubstatementReferenceCardinalitydescriptionRFC 6020, 7.19.30..1referenceRFC 6020, 7.19.40..1
The "require‑object" statement is used to indicate that
the specified YANG object is required for profile conformance.
It takes as argument the path string identifying the object.
This is similar to a YANG "absolute‑schema‑nodeid" except that
prefixes are not allowed. Only objects defined in the
required module can be specified with this statement.
[FIXME: there is no way to specify that the objects that 1 module
adds to another with augment-stmt are required in ad-hoc mode.]
SubstatementReferenceCardinalitydescriptionRFC 6020, 7.19.30..1referenceRFC 6020, 7.19.40..1
The "require‑package" statement is used to require
support for an external YANG package.
It takes as an argument the name of the YANG package
to require, followed by a block of substatements that
hold detailed server support requirements.
A require-package statement MUST NOT specify the same YANG
package name as another require-package statement in the
same profile statement.
SubstatementReferenceCardinalitydescriptionRFC 6020, 7.19.30..1revision1referenceRFC 6020, 7.19.40..1require-profile0..1
The "require‑profile" statement is used to require
support for a specific conformance profile within an external YANG package.
It takes as an argument the name of the conformance profile
to require. The server MUST advertise support for the specified
conformance profile name within the "profiles" list parameter in the
capability URI for the required package.
The "require‑capability" statement is used to indicate that
the specified NETCONF capability URI is required for profile conformance.
It takes as argument a URI string identifying the NETCONF capability
that is required,
and is followed by a block of substatements that describe the
NETCONF capability usage within the conformance profile.
SubstatementReferenceCardinalitydescriptionRFC 6020, 7.19.30..1referenceRFC 6020, 7.19.40..1require-parameter0..n
The "require‑parameter" statement is used to indicate that
the specified URI parameter for the parent NETCONF capability URI
is required for profile conformance.
It takes as argument a string identifying the parameter name
that is required,
and MAY be followed by a block of substatements that describe the
NETCONF parameter usage within the conformance profile.
If no substatements are present then any value for the parameter
is permitted for conformance.
If this parameter appears more than once within a "require‑capability"
statement then all the specified parameters are required for the server
to meet profile conformance requirements.
SubstatementReferenceCardinalitydescriptionRFC 6020, 7.19.30..1referenceRFC 6020, 7.19.40..1require-value0..n
The "require‑value" statement is used to indicate an
acceptable value for the parent capability parameter
for profile conformance.
It takes as argument a string identifying a parameter value
that is required,
and MAY be followed by a block of substatements that describe the
NETCONF parameter value usage within the conformance profile.
If this parameter appears more than once within a "require‑parameter"
statement then only one of the values is required to match
for the server to meet profile conformance requirements.
SubstatementReferenceCardinalitydescriptionRFC 6020, 7.19.30..1referenceRFC 6020, 7.19.40..1
A YANG conformance profile definition needs to be altered
very carefully after it has been published, in order not
to break old clients that expect certain server behavior.
When a new revision of a YANG package is published,
the following restrictions apply:
An existing conformance profile definition MAY be altered
to correct errors in the definition.
New statements (e.g. new requirements) MAY be added to an existing conformance
profile.
Existing requirements MUST NOT be removed from a conformance
profile.
Existing requirements MUST NOT be altered such that the
existing functionality would be taken away from clients.
Existing requirements MAY be altered such that the
existing functionality appears unaffected to existing clients
that are using a previous revision of the conformance profile.
An existing conformance profile can be split into
multiple new conformance profiles,
if the existing conformance profile adds "include‑profile"
statements such that the required functionality for any
existing conformance profile does not change.
The YANG Package Conformance capability is used to allow the
client to
quickly identify which packages and conformance profiles
are supported by a particular NETCONF server. The server
will advertise each supported YANG package, similar to
the YANG module conformance advertisement in RFC 6020, section 5.6.4.
The YANG package namespace URI MUST be advertised as a capability
in the NETCONF <hello> message to indicate support for a
specific conformance profile within the YANG package.
The capability URI MUST be of the form:
Where:
"package‑name" is the name of the YANG package
"revision‑date" is the revision date of the YANG package
"profile‑list" is a list of the conformance profiles supported by the server
All 3 parameters MUST be present in the capability string.
Refer to for details on the acceptable values
for these parameters.
Example: (capability string wrapped for display purposes only)
<CODE BEGINS> file "yang‑conformance.abnf"
TBD
TBD
How can logical OR expressions be supported for modules,
features, and capabilities? E.g. a "writable‑server"
profile will need a require-capability for the :writable-running
or for the :candidate capabilities. A server will usually advertise
one of these 2 capabilities, but not both of them.
Is some sort of "choice‑stmt" needed within a profile-stmt,
to indicate that 1 of N cases of requirements must
be supported? Does the server need to advertise
the selected cases in every choice it supports?
What package and profile naming conventions are needed?
Do these identifiers need to share the same namespace as YANG modules?
Package file name layout conventions are probably needed like
those in RFC 6020, section 5.2. A file extension for a YANG
package is needed.
Is a media type for a YANG package needed similar to
the definition in RFC 6020, section 14.1?
removed 'min‑revision' and 'max‑revision' statements.
added mandatory revision-stmt for profiles and require-package
statements.
changed package capability to allow the server to
advertise multiple profiles for a YANG package instead of 1.
changed required package contents from 0 to 1.
removed 'category' statement.
add 'require‑parameter' statement to require-capability-stmt.
add 'require‑value' statement to require-parameter-stmt.
removed 'prefix‑stmt' from YANG package.
removed 'header‑stmts' from ABNF so prefix-stmt would be removed.
added 'yangconf‑version‑stmt' to ABNF, cloned from RFC 6020
added 'namespace‑stmt' to ABNF, cloned from RFC 6020
remove conformance profile 'ip' from example, since this is now
achieved by advertising multiple names in the 'profiles' parameter
in the 'package' capability URI.
fixed typos in text and examples
updated ietf-routing-pkg example
added 'require parameters for capabilities' as an open issue
Key words for use in RFCs to Indicate Requirement LevelsHarvard UniversityIn many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents.Network Configuration Protocol (NETCONF)YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)YANG is a data modeling language used to model configuration and state data manipulated by the Network Configuration Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. [STANDARDS TRACK]