One document matched: draft-bierman-netmod-yang-conformance-02.txt
Differences from draft-bierman-netmod-yang-conformance-01.txt
Network Working Group A. Bierman
Internet-Draft YumaWorks
Intended status: Standards Track December 23, 2013
Expires: June 26, 2014
YANG Conformance Specification
draft-bierman-netmod-yang-conformance-02
Abstract
This document describes conformance specification and advertisement
mechanisms for NETCONF servers implementing YANG data model modules.
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on June 26, 2014.
Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Bierman Expires June 26, 2014 [Page 1]
Internet-Draft YANG Conformance December 2013
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.2. YANG . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.3. Terms . . . . . . . . . . . . . . . . . . . . . . . . 5
2. Problems With YANG Conformance Mechanisms . . . . . . . . . . 7
2.1. YANG Conformance Specification Issues . . . . . . . . . . 7
2.1.1. Import by Revision is Unusable for Conformance . . . . 7
2.1.2. YANG Conformance Specification is Too Simplistic . . . 8
2.1.3. YANG Deviation Statements Do Not Help . . . . . . . . 9
2.1.4. Single Module Conformance in Not Expressive Enough . . 9
2.2. Module Capability Advertisement Issues . . . . . . . . . . 10
3. Solution Overview . . . . . . . . . . . . . . . . . . . . . . 11
3.1. Objectives . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2. YANG Package . . . . . . . . . . . . . . . . . . . . . . . 11
3.3. YANG Package File . . . . . . . . . . . . . . . . . . . . 12
3.4. Conformance Profile . . . . . . . . . . . . . . . . . . . 12
3.5. Conformance Profile Capability . . . . . . . . . . . . . . 12
3.6. YANG Conformance Examples . . . . . . . . . . . . . . . . 12
4. YANG Conformance Statements . . . . . . . . . . . . . . . . . 20
4.1. The package Statement . . . . . . . . . . . . . . . . . . 20
4.1.1. The package Substatements . . . . . . . . . . . . . . 20
4.2. The yangconf-version Statement . . . . . . . . . . . . . . 20
4.3. The profile Statement . . . . . . . . . . . . . . . . . . 21
4.3.1. The profile Substatements . . . . . . . . . . . . . . 21
4.4. The include-profile Statement . . . . . . . . . . . . . . 21
4.5. The require-module Statement . . . . . . . . . . . . . . . 22
4.5.1. The require-module Substatements . . . . . . . . . . . 22
4.6. The revision Statement . . . . . . . . . . . . . . . . . . 22
4.7. The require-conformance Statement . . . . . . . . . . . . 22
4.8. The require-feature Statement . . . . . . . . . . . . . . 23
4.8.1. The require-feature Substatements . . . . . . . . . . 23
4.8.2. Usage Example . . . . . . . . . . . . . . . . . . . . 23
4.9. The require-object Statement . . . . . . . . . . . . . . . 24
4.9.1. The require-object Substatements . . . . . . . . . . . 24
4.9.2. Usage Example . . . . . . . . . . . . . . . . . . . . 24
4.10. The require-package Statement . . . . . . . . . . . . . . 24
4.10.1. The require-package Substatements . . . . . . . . . . 25
4.10.2. Usage Example . . . . . . . . . . . . . . . . . . . . 25
4.11. The require-profile Statement . . . . . . . . . . . . . . 25
4.12. The require-capability Statement . . . . . . . . . . . . . 25
4.12.1. The require-capability Substatements . . . . . . . . . 25
4.12.2. Usage Example . . . . . . . . . . . . . . . . . . . . 26
4.13. The require-parameter Statement . . . . . . . . . . . . . 26
4.13.1. The require-parameter Substatements . . . . . . . . . 26
4.13.2. Usage Example . . . . . . . . . . . . . . . . . . . . 27
Bierman Expires June 26, 2014 [Page 2]
Internet-Draft YANG Conformance December 2013
4.14. The require-value Statement . . . . . . . . . . . . . . . 27
4.14.1. The require-value Substatements . . . . . . . . . . . 27
4.14.2. Usage Example . . . . . . . . . . . . . . . . . . . . 28
5. Updating a YANG Package . . . . . . . . . . . . . . . . . . . 29
6. YANG Package Conformance Advertisement . . . . . . . . . . . . 30
7. YANG Conformance ABNF . . . . . . . . . . . . . . . . . . . . 31
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35
9. Security Considerations . . . . . . . . . . . . . . . . . . . 36
10. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 37
11. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 38
11.1. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 38
11.2. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 38
12. Normative References . . . . . . . . . . . . . . . . . . . . . 39
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 40
Bierman Expires June 26, 2014 [Page 3]
Internet-Draft YANG Conformance December 2013
1. Introduction
There is a need for standard mechanisms to allow YANG [RFC6020] 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
[RFC6241] 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.
1.1. Terminology
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, [RFC2119].
1.1.1. NETCONF
The following terms are defined in [RFC6241]:
o capability
o client
o datastore
o protocol operation
o server
1.1.2. YANG
The following terms are defined in [RFC6020]:
o data node
o extension
o feature
Bierman Expires June 26, 2014 [Page 4]
Internet-Draft YANG Conformance December 2013
o grouping
o identity
o module
o notification
o submodule
o typedef
1.1.3. Terms
The following terms are used within this document:
o 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.
o 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).
o 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.
o 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.
o object: a conceptual data structure represented by a YANG data,
rpc, or notification statement.
o 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.
Bierman Expires June 26, 2014 [Page 5]
Internet-Draft YANG Conformance December 2013
o 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.
o YANG package: A set of conformance profiles that can be extended
over time. Also called "package".
Bierman Expires June 26, 2014 [Page 6]
Internet-Draft YANG Conformance December 2013
2. Problems With YANG Conformance Mechanisms
This section describes some perceived deficiencies with the current
data model conformance specification and server conformance
advertisement mechanisms used in NETCONF.
2.1. YANG Conformance Specification Issues
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.
2.1.1. Import by Revision is Unusable for Conformance
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.
Bierman Expires June 26, 2014 [Page 7]
Internet-Draft YANG Conformance December 2013
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.
2.1.2. YANG Conformance Specification is Too Simplistic
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
Bierman Expires June 26, 2014 [Page 8]
Internet-Draft YANG Conformance December 2013
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.
2.1.3. YANG Deviation Statements Do Not Help
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.
2.1.4. Single Module Conformance in Not Expressive Enough
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.
Bierman Expires June 26, 2014 [Page 9]
Internet-Draft YANG Conformance December 2013
2.2. Module Capability Advertisement Issues
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).
Bierman Expires June 26, 2014 [Page 10]
Internet-Draft YANG Conformance December 2013
3. Solution Overview
3.1. Objectives
The solution in this document attempts to achieve several objectives:
o Provide simple documentation mechanisms that are readable and easy
to understand.
o Provide simple mechanisms that can scale in usage from one module
to thousands of modules.
o Provide per use-case conformance profiles, which allow multiple
conformance levels to be specified for a single module.
o Provide per use-case conformance profiles, which allow multiple
modules to be specified for a single conformance profile.
o Clarify the usage relationship between an augmented module and the
augmenting module.
o Clarify the usage relationship between modules that represent
parts of the same conceptual high-level service.
o Provide the ability to specify a stable conformance definition
that cannot implicitly change if YANG modules are updated.
o Provide the ability to specify the YANG features that must be
supported by a server to meet conformance requirements.
3.2. YANG Package
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
Bierman Expires June 26, 2014 [Page 11]
Internet-Draft YANG Conformance December 2013
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.
3.3. YANG Package File
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.
3.4. Conformance Profile
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.
3.5. Conformance Profile Capability
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
Section 6 for details on YANG package conformance advertisement.
3.6. YANG Conformance Examples
In this example, 1 conformance profile called "base" is defined for
the YANG package named "ietf-types-pkg".
Bierman Expires June 26, 2014 [Page 12]
Internet-Draft YANG Conformance December 2013
package ietf-types-pkg {
namespace "urn:ietf:params:xml:ns:yang:ietf-types-pkg";
organization
"IETF NETMOD (NETCONF Data Modeling Language) Working Group";
contact " ** WG Chairs ** ";
description
"This package defines a conformance profile for the standard
typedef statements.";
revision 2013-12-23 {
description "First revision";
reference "TBD";
}
profile base {
description "Basic requirements for YANG types.";
require-module ietf-yang-types {
revision 2013-07-15;
require-conformance import;
description
"Support for YANG types is required.";
reference "RFC 6991, section 3.";
}
require-module ietf-inet-types {
revision 2013-07-15;
require-conformance import;
description
"Support for INET types is required.";
reference "RFC 6991, section 4.";
}
}
}
In this example, 3 different conformance profiles are defined for the
YANG package named "ietf-routing-pkg":
o 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.
o ipv4: a server that supports IPv4 routing configuration
o ipv6: a server that supports IPv6 routing configuration
Bierman Expires June 26, 2014 [Page 13]
Internet-Draft YANG Conformance December 2013
package ietf-routing-pkg {
namespace "urn:ietf:params:xml:ns:yang:ietf-routing-pkg";
organization
"IETF NETMOD (NETCONF Data Modeling Language) Working Group";
contact " ** WG Chairs ** ";
description
"This package defines conformance profiles for IPv4 and IPv6
routers.";
revision 2013-12-23 {
description "First revision";
reference "TBD";
}
profile base {
description "Base module requirements for routing";
require-package ietf-types-pkg {
revision 2013-12-23;
}
require-module ietf-routing {
revision 2013-11-07;
require-conformance full;
description "The base routing module is required";
reference "draft-ietf-netmod-routing-cfg-12.txt";
}
require-module ietf-interfaces {
revision 2013-12-23;
require-conformance augment;
description
"The interface and interface-state tables are augmented.";
reference "draft-ietf-netmod-interfaces-cfg-15.txt";
}
}
profile ipv4 {
description "Base module requirements for routing";
include-profile base;
require-module ietf-ipv4-unicast-routing {
revision 2013-11-07;
require-conformance full;
description "Require IPv4 unicast routing support";
reference "draft-ietf-netmod-routing-cfg-12.txt";
Bierman Expires June 26, 2014 [Page 14]
Internet-Draft YANG Conformance December 2013
}
}
profile ipv6 {
description "Base module requirements for routing";
include-profile base;
require-module ietf-ipv6-unicast-routing {
revision 2013-11-07;
require-conformance full;
description "Require IPv6 unicast routing support";
reference "draft-ietf-netmod-routing-cfg-12.txt";
}
}
}
In this example, 5 different conformance profiles are defined for the
YANG package named "ietf-netconf-pkg":
o core: core NETCONF functionality.
o running: a server that supports writing directly to the running
datastore.
o startup: a server that supports writing directly to the running
datastore and also has a separate startup datastore.
o candidate:- running: a server that supports writing to the
candidate datastore and committing all edits at once to the
running datastore.
o confirmed:- running: a server that supports the candidate
conformance profile and also supports the confirmed commit
operations.
package ietf-netconf-pkg {
namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-pkg";
organization
"IETF NETMOD (NETCONF Data Modeling Language) Working Group";
contact " ** WG Chairs ** ";
description
"This package defines some conformance profiles for the
NETCONF protocol.";
revision 2013-12-23 {
Bierman Expires June 26, 2014 [Page 15]
Internet-Draft YANG Conformance December 2013
description "First revision";
reference "TBD";
}
profile core {
description
"Basic requirements for complete NETCONF servers.";
require-package ietf-types-pkg {
revision 2013-12-23;
}
require-capability "urn:ietf:params:netconf:base:1.1" {
description "NETCONF base protocol is required.";
reference "RFC 6241, section 8.1";
}
require-capability
"urn:ietf:params:netconf:capability:xpath:1.0" {
description "XPath filtering is required.";
reference "RFC 6241, section 8.9";
}
require-capability
"urn:ietf:params:netconf:capability:validate:1.1" {
description "NETCONF :validate capability is required.";
reference "RFC 6241, section 8.6";
}
require-capability
"urn:ietf:params:xml:ns:netconf:partial-lock:1.0" {
description
"Partial lock capability is required. The YANG module
ietf-netconf-partial-lock.yang is non-normative
so a require-module statement is not used instead.";
reference "RFC 5717, section 4";
}
require-capability
"urn:ietf:params:netconf:capability:with-defaults:1.0" {
description
"With defaults capability advertisement is required.";
reference "RFC 6243, section 4.3";
}
require-capability
"urn:ietf:params:netconf:capability:notification:1.0" {
description
Bierman Expires June 26, 2014 [Page 16]
Internet-Draft YANG Conformance December 2013
"Notification delivery support is required.";
reference "RFC 5277, section 3.1";
}
require-capability
"urn:ietf:params:netconf:capability:interleave:1.0" {
description
"Interleave of commands is required while notification
delivery is active .";
reference "RFC 5277, section 6";
}
require-module ietf-netconf-with-defaults {
revision 2011-06-01;
description
"Support for <with-defaults> RPC parameter is required.";
reference "RFC 6243, section 5";
}
require-module ietf-netconf-acm {
revision 2012-02-22;
description
"Base module implementation of NACM is required.";
reference "RFC 6536, section 3.5.2";
}
require-module ietf-netconf-monitoring {
revision 2010-10-04;
description
"Implementation of NETCONF monitoring is required.";
reference "RFC 6022, section 5";
}
require-module ietf-netconf-notifications {
revision 2012-02-06;
description
"Implementation of NETCONF base notifications is
required.";
reference "RFC 6470, section 2.2";
}
}
profile running {
description
"Basic requirements for a complete NETCONF server
that supports writing directly to the the running
datastore.";
Bierman Expires June 26, 2014 [Page 17]
Internet-Draft YANG Conformance December 2013
include-profile core;
require-capability
"urn:ietf:params:netconf:capability:writable-running:1.0" {
description
"NETCONF :writable-running capability is required.";
reference "RFC 6241, section 8.2";
}
require-capability
"urn:ietf:params:netconf:capability:rollback-on-error:1.0" {
description
"NETCONF :rollback-on-error capability is required.";
reference "RFC 6241, section 8.5";
}
}
profile startup {
description
"Basic requirements for a complete NETCONF server
that supports writing directly to the the running
datastore and also have a distinct startup datastore.";
include-profile running;
require-capability
"urn:ietf:params:netconf:capability:startup:1.0" {
description
"NETCONF distinct startup capability is required.";
reference "RFC 6241, section 8.7";
}
}
profile candidate {
description
"Basic requirements for a complete NETCONF server
that supports the candidate datastore.";
include-profile core;
require-capability
"urn:ietf:params:netconf:capability:candidate:1.0" {
description "NETCONF :candidate capability is required.";
reference "RFC 6241, section 8.3";
}
}
profile confirmed {
Bierman Expires June 26, 2014 [Page 18]
Internet-Draft YANG Conformance December 2013
description
"Basic requirements for a complete NETCONF server
that supports the candidate datastore, and confirmed
commit functionality.";
include-profile candidate;
require-capability
"urn:ietf:params:netconf:capability:confirmed-commit:1.1" {
description
"NETCONF :confirmed-commit capability is required.";
reference "RFC 6241, section 8.4";
}
}
}
Bierman Expires June 26, 2014 [Page 19]
Internet-Draft YANG Conformance December 2013
4. YANG Conformance Statements
4.1. The package Statement
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.
4.1.1. The package Substatements
+------------------+------------------+-------------+
| Substatement | Reference | Cardinality |
+------------------+------------------+-------------+
| contact | RFC 6020, 7.1.8 | 0..1 |
| description | RFC 6020, 7.19.3 | 0..1 |
| namespace | RFC 6020, 7.1.3 | 1 |
| organization | RFC 6020, 7.1.7 | 0..1 |
| profile | 4.3 | 1..n |
| reference | RFC 6020, 7.19.4 | 0..1 |
| revision | RFC 6020, 7.1.9 | 1..n |
| yangconf-version | 4.2 | 0..1 |
+------------------+------------------+-------------+
4.2. The yangconf-version Statement
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.
Bierman Expires June 26, 2014 [Page 20]
Internet-Draft YANG Conformance December 2013
4.3. The profile Statement
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.
4.3.1. The profile Substatements
+--------------------+------------------+-------------+
| Substatement | Reference | Cardinality |
+--------------------+------------------+-------------+
| description | RFC 6020, 7.19.3 | 0..1 |
| include-profile | 4.4 | 0..n |
| reference | RFC 6020, 7.19.4 | 0..1 |
| require-capability | 4.12 | 0..n |
| require-module | 4.5 | 0..n |
| require-package | 4.10 | 0..n |
| status | RFC 6020, 7.19.2 | 0..1 |
+--------------------+------------------+-------------+
4.4. The include-profile Statement
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.
Bierman Expires June 26, 2014 [Page 21]
Internet-Draft YANG Conformance December 2013
4.5. The require-module Statement
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.
4.5.1. The require-module Substatements
+---------------------+------------------+-------------+
| Substatement | Reference | Cardinality |
+---------------------+------------------+-------------+
| description | RFC 6020, 7.19.3 | 0..1 |
| revision | 4.6 | 1 |
| reference | RFC 6020, 7.19.4 | 0..1 |
| require-conformance | 4.7 | 0..1 |
| require-feature | 4.8 | 0..n |
| require-object | 4.9 | 0..n |
+---------------------+------------------+-------------+
4.6. The revision Statement
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.
4.7. The require-conformance Statement
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:
Bierman Expires June 26, 2014 [Page 22]
Internet-Draft YANG Conformance December 2013
o full: Full implementation of the module base is required. This is
the default value if the require-conformance statement is not
present.
o augment: full implementation of the objects that are augmented in
this module (from the augmenting module) is required.
o 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.
o 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.
4.8. The require-feature Statement
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.
4.8.1. The require-feature Substatements
+--------------+------------------+-------------+
| Substatement | Reference | Cardinality |
+--------------+------------------+-------------+
| description | RFC 6020, 7.19.3 | 0..1 |
| reference | RFC 6020, 7.19.4 | 0..1 |
+--------------+------------------+-------------+
4.8.2. Usage Example
require-module ietf-ip {
revision 2013-02-11;
require-conformance full;
require-feature ipv4-non-contiguous-netmasks {
description
"Configuration of non-contiguous subnet masks
is required.";
reference
"RFC XXXX; Section XXXX";
}
}
Bierman Expires June 26, 2014 [Page 23]
Internet-Draft YANG Conformance December 2013
4.9. The require-object Statement
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.]
4.9.1. The require-object Substatements
+--------------+------------------+-------------+
| Substatement | Reference | Cardinality |
+--------------+------------------+-------------+
| description | RFC 6020, 7.19.3 | 0..1 |
| reference | RFC 6020, 7.19.4 | 0..1 |
+--------------+------------------+-------------+
4.9.2. Usage Example
require-module ietf-system {
revision 2013-07-4;
require-conformance ad-hoc;
require-object /system-state/clock/current-datetime {
description
"The current system time must be provided.";
reference
"RFC XXXX; Section XXXX";
}
}
4.10. The require-package Statement
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.
Bierman Expires June 26, 2014 [Page 24]
Internet-Draft YANG Conformance December 2013
4.10.1. The require-package Substatements
+-----------------+------------------+-------------+
| Substatement | Reference | Cardinality |
+-----------------+------------------+-------------+
| description | RFC 6020, 7.19.3 | 0..1 |
| revision | 4.6 | 1 |
| reference | RFC 6020, 7.19.4 | 0..1 |
| require-profile | 4.11 | 0..1 |
+-----------------+------------------+-------------+
4.10.2. Usage Example
require-package ietf-routing-pkg {
revision 2013-12-23;
require-profile ipv4;
description
"Support for IPv4 routing configuration is required.";
}
4.11. The require-profile Statement
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.
4.12. The require-capability Statement
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.
4.12.1. The require-capability Substatements
+-------------------+------------------+-------------+
| Substatement | Reference | Cardinality |
+-------------------+------------------+-------------+
| description | RFC 6020, 7.19.3 | 0..1 |
| reference | RFC 6020, 7.19.4 | 0..1 |
| require-parameter | 4.13 | 0..n |
+-------------------+------------------+-------------+
Bierman Expires June 26, 2014 [Page 25]
Internet-Draft YANG Conformance December 2013
4.12.2. Usage Example
profile full-notifications {
description
"A profile for requiring full standard NETCONF
notification functionality.";
require-capability
"urn:ietf:params:netconf:capability:notification:1.0" {
description
"Support for NETCONF notifications is required.";
reference "RFC 5277, section 3.1.1";
}
require-capability
"urn:ietf:params:netconf:capability:interleave:1.0" {
description
"Support for the ability to accept <rpc> requests when
NETCONF notification delivery is active is required.";
reference "RFC 5277, section 6.3";
}
}
4.13. The require-parameter Statement
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.
4.13.1. The require-parameter Substatements
+---------------+------------------+-------------+
| Substatement | Reference | Cardinality |
+---------------+------------------+-------------+
| description | RFC 6020, 7.19.3 | 0..1 |
| reference | RFC 6020, 7.19.4 | 0..1 |
| require-value | 4.14 | 0..n |
+---------------+------------------+-------------+
Bierman Expires June 26, 2014 [Page 26]
Internet-Draft YANG Conformance December 2013
4.13.2. Usage Example
profile valid-url {
description
"A profile for requiring that the scheme parameter
be present in the :url capability. Any value is
allowed.";
require-capability
"urn:ietf:params:netconf:capability:url:1.0" {
description
"Support for the :url capability is required.";
reference "RFC 6241, section 8.8";
require-parameter scheme {
description
"Support for the scheme parameter is required.";
reference "RFC 6241, section 8.8.3";
}
}
4.14. The require-value Statement
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.
4.14.1. The require-value Substatements
+--------------+------------------+-------------+
| Substatement | Reference | Cardinality |
+--------------+------------------+-------------+
| description | RFC 6020, 7.19.3 | 0..1 |
| reference | RFC 6020, 7.19.4 | 0..1 |
+--------------+------------------+-------------+
Bierman Expires June 26, 2014 [Page 27]
Internet-Draft YANG Conformance December 2013
4.14.2. Usage Example
profile ftp-support {
description
"A profile for requiring FTP support for the 'url'
capability.";
require-capability
"urn:ietf:params:netconf:capability:url:1.0" {
description
"Support for the :url capability is required.";
reference "RFC 6241, section 8.8";
require-parameter scheme {
description
"Support for the 'scheme' parameter is required.";
reference "RFC 6241, section 8.8.3";
require-value ftp {
description
"Support for 'ftp' transfer is required.";
}
}
}
}
Bierman Expires June 26, 2014 [Page 28]
Internet-Draft YANG Conformance December 2013
5. Updating a YANG Package
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:
o An existing conformance profile definition MAY be altered to
correct errors in the definition.
o New statements (e.g. new requirements) MAY be added to an existing
conformance profile.
o Existing requirements MUST NOT be removed from a conformance
profile.
o Existing requirements MUST NOT be altered such that the existing
functionality would be taken away from clients.
o 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.
o 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.
Bierman Expires June 26, 2014 [Page 29]
Internet-Draft YANG Conformance December 2013
6. YANG Package Conformance Advertisement
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:
conf-capability-string = namespace-uri [ parameter-list ]
parameter-list = "?" parameter *( "&" parameter )
parameter = package-parameter /
revision-parameter /
profile-parameter
package-parameter = "package=" package-name
revision-parameter = "revision=" revision-date
profile-parameter = "profiles=" profile-list
profile-list = profile-name *("," profile-name)
Where:
o "package-name" is the name of the YANG package
o "revision-date" is the revision date of the YANG package
o "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
Section 4.1 for details on the acceptable values for these
parameters.
Example: (capability string wrapped for display purposes only)
<capability>urn:ietf:params:xml:ns:yang:ietf-routing-pkg?package=
ietf-routing-pkg&revision=2013-12-23&profiles=ipv4,ipv6
</capability>
Bierman Expires June 26, 2014 [Page 30]
Internet-Draft YANG Conformance December 2013
7. YANG Conformance ABNF
<CODE BEGINS> file "yang-conformance.abnf"
package-stmt = optsep package-keyword sep identifier-arg-str
optsep
"{" stmtsep
[yangconf-version-stmt]
namespace-stmt
meta-stmts
revision-stmts
package-body-stmts
"}" optsep
yangconf-version-stmt = yangconf-version-keyword sep
yangconf-version-arg-str
optsep stmtend
yangconf-version-arg-str = < a string that matches the rule
yangconf-version-arg >
yangconf-version-arg = "1"
namespace-stmt = namespace-keyword sep uri-str
optsep stmtend
package-body-stmts = 1*(profile-stmt stmtsep)
profile-stmt = profile-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[status-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
*(include-profile-stmt stmtsep)
*(require-package-stmt stmtsep)
*(require-capability-stmt stmtsep)
*(require-module-stmt stmtsep)
"}")
include-profile-stmt = include-profile-keyword sep
identifier-arg-str stmtend
require-module-stmt = require-module-keyword sep
identifier-arg-str optsep
(";" /
"{" stmtsep
Bierman Expires June 26, 2014 [Page 31]
Internet-Draft YANG Conformance December 2013
;; these stmts can appear in any order
revision-stmt stmtsep
[require-conformance-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
*(require-feature-stmt stmtsep)
*(require-object-stmt stmtsep)
"}")
require-object-stmt = require-object-keyword sep
require-object-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[description-stmt stmtsep]
[reference-stmt stmtsep]
"}")
require-object-arg-str = < a string that matches the rule
require-object-arg >
require-object-arg = pkg-absolute-schema-nodeid
require-package-stmt = require-package-keyword sep
identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
revision-stmt stmtsep
[require-profile-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
"}")
require-profile-stmt = require-profile-keyword sep
identifier-arg-str stmtend
require-capability-stmt = require-capability-keyword sep
uri-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[description-stmt stmtsep]
[reference-stmt stmtsep]
*(require-parameter-stmt stmtsep)
"}")
require-parameter-stmt = require-parameter-keyword sep
Bierman Expires June 26, 2014 [Page 32]
Internet-Draft YANG Conformance December 2013
identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[description-stmt stmtsep]
[reference-stmt stmtsep]
*(require-value-stmt stmtsep)
"}")
require-value-stmt = require-value-keyword sep
value-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[description-stmt stmtsep]
[reference-stmt stmtsep]
"}")
value-arg-str = <string containing allowed value>
revision-stmt = revision-keyword sep date-arg-str stmtend
require-feature-stmt = require-feature-keyword sep
identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[description-stmt stmtsep]
[reference-stmt stmtsep]
"}")
require-conformance-stmt = require-conformance-keyword sep
require-conformance-arg-str stmtend
require-conformance-arg-str =
< a string that matches the rule
require-conformance-arg >
require-conformance-arg = full-keyword /
augment-keyword /
import-keyword /
ad-hoc-keyword
pkg-schema-nodeid = pkg-absolute-schema-nodeid /
pkg-descendant-schema-nodeid
pkg-absolute-schema-nodeid = 1*("/" pkg-node-identifier)
Bierman Expires June 26, 2014 [Page 33]
Internet-Draft YANG Conformance December 2013
pkg-descendant-schema-nodeid =
pkg-node-identifier
pkg-absolute-schema-nodeid
pkg-node-identifier = identifier
;; new keywords
ad-hoc-keyword = 'ad-hoc'
augment-keyword = 'augment'
conformance-keyword = 'conformance'
full-keyword = 'full'
include-profile-keyword = 'include-profile'
package-keyword = 'package'
profile-keyword = 'profile'
require-capability-keyword = 'require-capability'
require-module-keyword = 'require-module'
require-feature-keyword = 'require-feature'
require-package-keyword = 'require-package'
require-parameter-keyword = 'require-parameter'
require-profile-keyword = 'require-profile'
require-value-keyword = 'require-value'
revision-keyword = 'revision'
yangconf-version-keyword = 'yangconf-version'
;; all other symbols are defined in RFC 6020, section 12
<CODE ENDS>
Bierman Expires June 26, 2014 [Page 34]
Internet-Draft YANG Conformance December 2013
8. IANA Considerations
TBD
Bierman Expires June 26, 2014 [Page 35]
Internet-Draft YANG Conformance December 2013
9. Security Considerations
TBD
Bierman Expires June 26, 2014 [Page 36]
Internet-Draft YANG Conformance December 2013
10. Open Issues
o 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.
o 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?
o What package and profile naming conventions are needed? Do these
identifiers need to share the same namespace as YANG modules?
o 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.
o Is a media type for a YANG package needed similar to the
definition in RFC 6020, section 14.1?
Bierman Expires June 26, 2014 [Page 37]
Internet-Draft YANG Conformance December 2013
11. Change Log
-- RFC Ed.: remove this section before publication.
11.1. 01-02
o removed 'min-revision' and 'max-revision' statements.
o added mandatory revision-stmt for profiles and require-package
statements.
o changed package capability to allow the server to advertise
multiple profiles for a YANG package instead of 1.
o changed required package contents from 0 to 1.
o removed 'category' statement.
o add 'require-parameter' statement to require-capability-stmt.
o add 'require-value' statement to require-parameter-stmt.
o removed 'prefix-stmt' from YANG package.
o removed 'header-stmts' from ABNF so prefix-stmt would be removed.
o added 'yangconf-version-stmt' to ABNF, cloned from RFC 6020
o added 'namespace-stmt' to ABNF, cloned from RFC 6020
o remove conformance profile 'ip' from example, since this is now
achieved by advertising multiple names in the 'profiles' parameter
in the 'package' capability URI.
11.2. 00-01
o fixed typos in text and examples
o updated ietf-routing-pkg example
o added 'require parameters for capabilities' as an open issue
Bierman Expires June 26, 2014 [Page 38]
Internet-Draft YANG Conformance December 2013
12. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the
Network Configuration Protocol (NETCONF)", RFC 6020,
October 2010.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
and A. Bierman, Ed., "Network Configuration Protocol
(NETCONF)", RFC 6241, June 2011.
Bierman Expires June 26, 2014 [Page 39]
Internet-Draft YANG Conformance December 2013
Author's Address
Andy Bierman
YumaWorks
Email: andy@yumaworks.com
Bierman Expires June 26, 2014 [Page 40]
| PAFTECH AB 2003-2026 | 2026-04-24 05:44:30 |