Network Working Group A. Bierman Internet-Draft YumaWorks Intended status: Standards Track September 24, 2014 Expires: March 28, 2015 YANG Conformance Specification draft-bierman-netmod-yang-conformance-04 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 March 28, 2015. Copyright Notice Copyright (c) 2014 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 March 28, 2015 [Page 1] Internet-Draft YANG Conformance September 2014 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 1.1.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 6 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.1. Server Implementation Capabilities . . . . . . . . . . . . 7 3. Problems With YANG Conformance Mechanisms . . . . . . . . . . 8 3.1. Incomplete Dependency Tree: Conformance Drift . . . . . . 8 3.1.1. Typedef Drift . . . . . . . . . . . . . . . . . . . . 8 3.1.2. Grouping Drift . . . . . . . . . . . . . . . . . . . . 9 3.1.3. Conformance Drift Example . . . . . . . . . . . . . . 9 3.2. Complete Dependency Tree: Multiple Concurrent Revisions . 13 3.2.1. Conformance Ambiguity Example . . . . . . . . . . . . 14 3.2.2. Augmenting External Data Nodes . . . . . . . . . . . . 14 3.2.3. Identityref Value Sets . . . . . . . . . . . . . . . . 14 3.2.4. Leafref Value Sets . . . . . . . . . . . . . . . . . . 15 3.3. Module Capability Advertisement Issues . . . . . . . . . . 15 4. YANG Conformance Guidelines . . . . . . . . . . . . . . . . . 16 4.1. Conformance is Based on the Module Set, not One Module . . 16 4.2. Import has no Conformance Semantics . . . . . . . . . . . 16 4.3. Only the Most Recent Revision Allowed . . . . . . . . . . 16 4.3.1. YANG Module Capability URIs . . . . . . . . . . . . . 17 4.4. Import and Include By Revision Do Not Really Help . . . . 17 4.5. Limit Protocol Accessible Objects in the Base Module . . . 18 5. YANG Submodule Capability . . . . . . . . . . . . . . . . . . 19 5.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 19 5.1.1. :submodule Capability Example . . . . . . . . . . . . 19 5.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . . 19 5.3. Capability Identifier . . . . . . . . . . . . . . . . . . 19 5.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 20 5.5. Modifications to Existing Operations . . . . . . . . . . . 20 5.6. Interactions with Other Capabilities . . . . . . . . . . . 20 6. YANG Conformance Module . . . . . . . . . . . . . . . . . . . 21 6.1. Identityref Value Set Discovery . . . . . . . . . . . . . 21 6.2. Leafref Value Set Discovery . . . . . . . . . . . . . . . 21 6.3. Schema Conformance Discovery . . . . . . . . . . . . . . . 22 6.4. YANG module . . . . . . . . . . . . . . . . . . . . . . . 22 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 7.1. YANG Module Registry . . . . . . . . . . . . . . . . . . . 28 8. Security Considerations . . . . . . . . . . . . . . . . . . . 29 9. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 30 9.1. YANG Module Advertisement . . . . . . . . . . . . . . . . 30 9.1.1. Capability-ID vs. Module URI List . . . . . . . . . . 30 9.1.2. Full vs. Partial List . . . . . . . . . . 30 Bierman Expires March 28, 2015 [Page 2] Internet-Draft YANG Conformance September 2014 9.2. YANG 1.1 Support . . . . . . . . . . . . . . . . . . . . . 31 9.3. Protocol Independence . . . . . . . . . . . . . . . . . . 31 10. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 32 10.1. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 32 10.2. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 32 10.3. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 32 10.4. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 33 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 34 11.1. Normative References . . . . . . . . . . . . . . . . . . . 34 11.2. Informative References . . . . . . . . . . . . . . . . . . 34 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 35 Bierman Expires March 28, 2015 [Page 3] Internet-Draft YANG Conformance September 2014 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 March 28, 2015 [Page 4] Internet-Draft YANG Conformance September 2014 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 base module: There is an implied "base" subset of a YANG module, which includes all "rpc", "data-def", and "notification" statements which are not conditional. The base module may be empty, a subset of all statements, or the entire module. 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 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 include-by-revision: A YANG include statement that includes a revision-date statement. This specifies the exact revision of the YANG submodule to include, instead of the server picking the revision to include. o object: a conceptual data structure represented by a YANG data, rpc, or notification statement. o revision identifier: a YANG module revision is identified by the revision date value of the most recent revision statement in the module. If there are no revision statements then the empty string is the revision identifier. 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 Bierman Expires March 28, 2015 [Page 5] Internet-Draft YANG Conformance September 2014 conceptually applied to the schema tree as well. o YANG dependency tree: A conceptual tree containing the set of all revision identifiers for all modules and submodules in the schema tree. 1.1.4. Tree Diagrams A simplified graphical representation of the data model is used in this document. The meaning of the symbols in these diagrams is as follows: o Brackets "[" and "]" enclose list keys. o Abbreviations before data node names: "rw" means configuration data (read-write) and "ro" state data (read-only). o Symbols after data node names: "?" means an optional node, "!" means a presence container, and "*" denotes a list and leaf-list. o Parentheses enclose choice and case nodes, and case nodes are also marked with a colon (":"). o Ellipsis ("...") stands for contents of subtrees that are not shown. Bierman Expires March 28, 2015 [Page 6] Internet-Draft YANG Conformance September 2014 2. Overview The YANG module represents a conceptual API contract between the client and server for a management protocol that uses YANG. There are two primary factors that directly impact interoperability. o Client and Server Implementation Requirements o Actual Server Implementation Capabilities The syntax and semantics of a given data model, used within a specific protocol, must be understood by the client and server developers to achieve interoperability. These implementation requirements need to stable, and not change for a given revision of a module. Any changes to the implementation requirements needs to be intentional, and properly identified and understood by client and server developers. 2.1. Server Implementation Capabilities The actual implemented portions of a given data model, used within a specific protocol, must be understood by the client. For YANG, a "YANG Module capability URI" is advertised in the server capabilities, and understood by the client. For improved interoperability, the server must identify its conformance level for each module, and identify and deviations from the advertised conformance level. Bierman Expires March 28, 2015 [Page 7] Internet-Draft YANG Conformance September 2014 3. Problems With YANG Conformance Mechanisms This section describes some perceived deficiencies with the current YANG data model conformance specification and NETCONF server conformance advertisement mechanisms. The engineering trade-off that needs to be considered is the complexity and effort required to specify conformance information and the accuracy and specificity of the conformance information that is defined. The rest of this section discusses the advantages and disadvantages of the two solution paths available in YANG to identify conformance requirements. Option 1: do not use import-by-revision or include-by-revision at all. This approach requires some other mechanism besides the import and include statements to fully identity the dependency tree. Option 2: use import-by-revision and include-by-revision everywhere so the YANG dependency tree is fully specified. 3.1. Incomplete Dependency Tree: Conformance Drift If the import-by-revision and include-by-revision mechanisms are not used everywhere in the dependency tree, then the application compiling the YANG modules must decide somehow which revision to use for any module or submodule without a revision-date statement. When new modules are added which require the revision of a shared module to be updated, the server will need to advertise the updated module. There is ambiguity whether the server needs to advertise all the revisions of all the YANG modules is uses, and what that even means in some cases. Conformance drift occurs when definition updates in an imported module inadvertently change the syntax and/or semantics of statements in the importing module. These changes occur without a change in the revision date for the importing module, which makes them hidden undocumented conformance updates. 3.1.1. Typedef Drift Typedef drift can occur if a leaf or leaf-list "type" statement references a "typedef" statement from an external module. The YANG syntax specified for a leaf or leaf-list will depend on which revision of the external module is used. If the newer revision is used, then the allowed value set will be changed. Bierman Expires March 28, 2015 [Page 8] Internet-Draft YANG Conformance September 2014 There are several ways this is allowed under the conditions described in section 10 of [RFC6020]: o an "enumeration" type can add new "enum" statements o a "bits" type can add new "bit" statements o a "range", "length", or "pattern" statement may expand the allowed value space Note that conformance for "identityref" types are discussed separately. This data type is complex because the value set is distributed, and actual allowed values of this type are node and/or context-specific. 3.1.2. Grouping Drift Grouping drift can occur if a "uses" statement references a "grouping" statement from an external module, and the grouping contents change. New data nodes can be added to a grouping in a new revision of a module under certain conditions, described in section 10 of [RFC6020]: The YANG data nodes that are copied from the grouping will depend on which revision of the external module is used. If the newer revision is used, then any new and/or modified objects will be added to the schema tree. It is not clear how multiple revisions of the same grouping can be used reliably. It depends on the content of the grouping. For example, a grouping may contain objects with "must" or "when" XPath expressions. These expressions can reference objects inside or outside the grouping in a manner that has the desired effect when evaluated with the intended revision of the grouping, but incorrect effect when evaluated against newer modules. It is therefore unsafe for a server to support multiple revisions of a grouping, in a generic manner. 3.1.3. Conformance Drift Example Consider the "first release" where the module set advertised by the server consists of 2 modules: Bierman Expires March 28, 2015 [Page 9] Internet-Draft YANG Conformance September 2014 - module A, revision 2014-01-01 - module B, revision 2014-01-02 module A { namespace "module-A"; prefix A; revision "2014-01-01" { description "First revision"; } typedef knob-range { type int32 { range "1 .. 100"; } } grouping knob-group { leaf knobA { type knob-range; } } leaf which-leaf { type knob-range; } } module B { namespace "module-B"; prefix B; import A { prefix A; } revision "2014-01-02" { description "First revision"; } leaf knob1 { type A:knob-range; } container knobs { uses A:knob-group; } } The server can clearly express the value range allowed for "knob1" in revision "2014-01-02" of the "B" module. There is only 1 leaf ("knobA") in the "knobs" container. There is only 1 possible revision of module "A" that can be advertised by a server, so the definition of the "which-leaf" leaf is clear. Bierman Expires March 28, 2015 [Page 10] Internet-Draft YANG Conformance September 2014 Now consider the "second release" where the module set has been extended to 3 modules, and module "A" has been updated but module "B" has not been updated. The server advertises the latest revision of module "A" instead of both revisions. This module was updated to support module "C". Bierman Expires March 28, 2015 [Page 11] Internet-Draft YANG Conformance September 2014 - module A, revision 2014-02-01 (updated) - module B, revision 2014-01-02 (unchanged) - module C, revision 2014-02-02 (new) module A { namespace "module-A"; prefix A; revision "2014-02-01" { description "Second revision"; } revision "2014-01-01" { description "First revision"; } typedef knob-range { // range expanded and default added! type int32 { range "1 .. 500"; } default 500; } grouping knob-group { leaf knobA { type knob-range; } leaf knobB { // added 1 leaf to grouping! type knob-range; } } leaf which-leaf { type knob-range; // type changed! default 200; // added default! } } module C { namespace "module-C"; prefix C; import A { prefix A; } revision "2014-02-02" { description "First revision"; } leaf knob2 { type A:knob-range; } } Bierman Expires March 28, 2015 [Page 12] Internet-Draft YANG Conformance September 2014 There are unadvertised changes in module "B": o "knob1" leaf range expanded and default added o "knobB" leaf added to the "knobs" container Problems can occur if the client understanding of the dependency tree is not accurate. It might assume the server has updated the instrumentation for the "knob1" leaf so the increased range and new default are supported. The "knob1" syntax used depends on which revision of module "A" that is parsed. Problems can occur if the server instrumentation understanding of the dependency tree is not accurate. It might assume the server validation code will only give it a valid value for leaf "knob1" which fits in one byte. Values from 256 to 500 in this example might cause internal errors in the server. If the server advertises the latest revisions of the YANG modules then syntax of "knob1" and contents of the "knobs" container will change, even though module "B" has not been updated. This can cause the client to send invalid protocol requests or misinterpret data received from the server. 3.2. Complete Dependency Tree: Multiple Concurrent Revisions If exact revision dates are used everywhere then they need to be carefully examined each time any module in the dependency tree is changed. Updating modules just to change the revision date of an updated imported module also changes the revision date of the importing module. This ripple effect creates many revisions that do not even import the particular module, and would add significant complexity to module lifecycle management. If some dependencies are updated but not others, then the client and server will need to support multiple revisions of the same module or submodule at the same time. This is the most likely scenario to occur. NETCONF and YANG do not specify how a server must support multiple revisions of the same module at the same time. This causes interoperability problems which need to be addressed. Consider the previous example, except import-by-revision is used everywhere to fix the conformance drift problem. The only changes at all are the addition of revision dates in the import statements in modules "B" and "C". Bierman Expires March 28, 2015 [Page 13] Internet-Draft YANG Conformance September 2014 3.2.1. Conformance Ambiguity Example If import-by-revision is used everywhere, then the second release in the previous example would contain the following modules and revisions advertised by the server: - module A, revision 2014-01-01 - module A, revision 2014-02-01 - module B, revision 2014-01-02 - module C, revision 2014-02-02 The conformance drift problems in module "B" are fixed. Module "B" use the old definitions from the first revision of module "A", and module "C" uses the new definitions from the updated revision. However, now that 2 revisions of module "A" are advertised by the server, it is not clear what revision of leaf "which-leaf" from module "A" is implemented by the server. This problem applies to all protocol accessible statements (data nodes, "rpc", and "notification" statements). It may also apply to any global reusable statements such as "extension" and "feature". Advertising multiple revisions of any of these statements causes ambiguity in the conformance definition. 3.2.2. Augmenting External Data Nodes The problem of ambiguous conformance affects data nodes derived from external augmentation, i.e., several modules (all using import-by- revision) augment multiple revisions of the same data nodes. The augmenting nodes can change over time, and they can themselves contain imported definitions. The YANG conformance rules do not support different revisions of the same data node instance. The actual implementation matrix cannot be an ad-hoc subset of all possible revision combinations. The client needs to be able to identify the exact revisions of data nodes that are supported by the server. 3.2.3. Identityref Value Sets A server cannot advertise even the complete set of identities that it supports. It actually advertises all of the identities in all modules in the dependency tree. This is a superset of all supported identities by the server. It is not possible for a client to determine the supported identity set at all. In addition, individual identityref leafs may support Bierman Expires March 28, 2015 [Page 14] Internet-Draft YANG Conformance September 2014 different subsets of all possible identities supported by the server. For example, simply importing the "iana-if-types" YANG module does not mean the server supports every possible interface type that has ever been defined. YANG conformance requirements for "identityref" leafs are unclear and need to be clarified. Discovery of agent capabilities of actual supported identities is needed. 3.2.4. Leafref Value Sets YANG conformance requirements for "leafref" leafs are unclear and need to be clarified. Support for discovery of agent capabilities of actual supported identities is needed. The same issues that apply to "identityref" types can occur with "leafref" types. 3.3. Module Capability Advertisement Issues NETCONF servers advertise the YANG modules they support as URI strings in the 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 conformance information that is derived from the YANG module advertisement needs to be clarified. Bierman Expires March 28, 2015 [Page 15] Internet-Draft YANG Conformance September 2014 4. YANG Conformance Guidelines Conformance for the "ietf-yang-conformance" module capability requires implementation of these conformance guidelines. 4.1. Conformance is Based on the Module Set, not One Module The reason conformance drift and conformance ambiguity are currently problems is due to the incorrect assumption that a YANG datastore is allowed to be considered a collection of independent module implementations. This is done in pursuit of module independence and the ability to support off-line validation tools of YANG content. The "individual module" approach does not work for YANG datastores. Instead, the YANG conformance needs to be based on the entire module set, identified by the collection of YANG modules and submodules, features and deviations that the server is using at the moment. The revision date for a specific module or submodule only freezes the definitions within that module or submodule. Any external modules or submodules have their own revision date, that cannot be frozen in the server implementation. It is the responsibility of the YANG module writer to ensure that a new or existing module is syntactically and semantically compatible with the current revision of all external modules imported by that module. It is the responsibility of the NETCONF server developer to ensure that the supported module set is syntactically and semantically self-compatible. 4.2. Import has no Conformance Semantics Simply importing a module implies no conformance relationship between the importing and imported module. There are many ways that YANG can be used so an imported module is not even used. E.g., the only identifiers from the imported module have "if-feature" statements, but the server does not enable any of the features. The "import" statement is only useful for resolving external identifiers used in the current module. 4.3. Only the Most Recent Revision Allowed The server MUST implement the most recent revision of each module it advertises. The vendor cannot upgrade a shared module without updating all the modules that actually depend on the changes. If any of the following statements in the most recent advertised revision of the base module are not supported by the server, then a Bierman Expires March 28, 2015 [Page 16] Internet-Draft YANG Conformance September 2014 YANG module containing the appropriate "deviation" statements MUST be advertised for that module. o augment-stmt o data-def-stmt o notification-stmt o rpc-stmt If a shared module needs to be updated, then the conformance is implicitly updated for the modules that depend on the changes. 4.3.1. YANG Module Capability URIs There are existing NETCONF client applications that assume that all the YANG modules used by the server will be sent in the message. These applications are likely to fail if an incomplete module set is advertised by the server. The server MUST advertise the most recent revision of all YANG modules that it supports, including modules that do not contain any data definitions. If the server uses any modules with submodules, then the "submodule" capability in Section 5 SHOULD be advertised for each submodule used. Only one revision of each submodule SHOULD be advertised. 4.4. Import and Include By Revision Do Not Really Help The simplest solution for fixing the conformance drift problem would be to use import and include by revision everywhere, and make this usage mandatory. Any new YANG statements would cause duplication of the module or submodule name and revision date information. However, this solution is not workable because the ripple effect will require constant updating of many YANG modules just to change the revision- date clause. Multiple concurrent revisions of YANG datastore contents are not supported in a NETCONF server. The server behavior required for import-by-revision has never been specified wrt/ multiple revisions of the same module. The "revision-date" statement SHOULD NOT be used in "import" statements. Conformance for external modules cannot be fixed to a specific revision when used within a NETCONF server. If the "revision-date" statement is used, it SHOULD be interpreted as "the Bierman Expires March 28, 2015 [Page 17] Internet-Draft YANG Conformance September 2014 current revision of the imported module when this module was published". The actual revision used by the server will be advertised in the YANG module capability URI. The hard-wired revision dates in "import" statements are only useful for off-line validation. of protocol requests. Even then, they must be used everywhere to be deterministic. Real NETCONF sessions require not only all the module names and revision dates, but the enabled YANG features and YANG conformance deviations. 4.5. Limit Protocol Accessible Objects in the Base Module YANG module designers SHOULD NOT specify "augment", "rpc", "notification", or any data definition statements in the base module of a YANG module, if it also contains any "typedef", "grouping", "identity", "extension", or "deviation" statements. This will prevent the need for deviations advertisement by the server, just to utilize the definitions designed for reusability. Note that the "feature" statement is not included in this list, otherwise if any optional protocol-accessible statements were needed, then they would all need to be optional. Reusable definitions can be placed in a separate module with no protocol-accessible statements, or the protocol-accessible statements can contain "if-feature" statements to remove them from the base module. Either practice is acceptable. Bierman Expires March 28, 2015 [Page 18] Internet-Draft YANG Conformance September 2014 5. YANG Submodule Capability 5.1. Overview A new capability called "submodule" is defined to identify the specific revisions of all submodules the server is using. When a new session is started, the client can examine the "submodule" URIs sent by the server to determine the specific revision that the server is using for each submodule. Since submodule names share the same namespace as module names, there is no need to add the parent module name and revision to the advertisement. The server is required to support the advertised revision, and only one revision can be advertised. 5.1.1. :submodule Capability Example The following example show just the "submodule" capability for submodule "submod-A" with revision date "2014-09-23", and submodule "submod-B" with revision date "2013-10-01", The URIs are wrapped for display purposes only. urn:ietf:params:netconf:capability:submodule:1.0? name=submod-A&revision=2014-09-23 urn:ietf:params:netconf:capability:submodule:1.0? name=submod-B&revision=2013-10-01 // ... rest of elements 3 5.2. Dependencies The :submodule capability is not dependent on any other capabilities. 5.3. Capability Identifier The :submodule capability is identified by the following capability string: urn:ietf:params:netconf:capability:submodule:1.0 Bierman Expires March 28, 2015 [Page 19] Internet-Draft YANG Conformance September 2014 The :submodule capability SHOULD be sent in every server message, for each submodule used by the server. The "submodule" parameter for the :submodule capability MUST be present, and is set to the name of the submodule. The "revision" parameter for the :submodule capability MUST be present, and is set to the revision date of the submodule. 5.4. New Operations The :submodule capability does not introduce any new protocol operations. 5.5. Modifications to Existing Operations The :submodule capability does not modify any existing protocol operations. 5.6. Interactions with Other Capabilities The :submodule capability does not interact with any other capabilities. Bierman Expires March 28, 2015 [Page 20] Internet-Draft YANG Conformance September 2014 6. YANG Conformance Module The "ietf-yang-conformance" module in Section 6.4 defines 2 protocol operations for retrieving allowed value sets from the server. There is also an augmentation of the "schema" list in the "ietf-netconf-monitoring" module defined in [RFC6022]. augment /ncm:netconf-state/ncm:schemas/ncm:schema: +--ro conformance-type? enumeration +--ro belongs-to-module? string rpcs: +---x get-allowed-identities {get-allowed}? | +--ro input | | +--ro target instance-identifier | +--ro output | +--ro (response)? | | +--:(all) | | | +--ro all? empty | | +--:(identity) | | +--ro identity* string | +--ro support-all? empty +---x get-allowed-leafrefs {get-allowed}? +--ro input | +--ro target instance-identifier +--ro output +--ro (response)? | +--:(all) | | +--ro all? empty | +--:(value) | +--ro value* string +--ro support-all? empty 6.1. Identityref Value Set Discovery A server is not required to support all advertised identity values. The actual values required for a particular "identityref" leaf or leaf-list MAY be specified in the YANG module. If not, then the entire list of identities with a matching "base" definition is used as the superset of all allowed values for the identityref. A new protocol operation called "get-allowed-identities" is defined to allow a client to discover the set of identities actually supported at the moment for a specific leaf or leaf-list. 6.2. Leafref Value Set Discovery A server is not required to support all existing potential instances for a leaf or leaf-list using the "leafref" data type. The entire Bierman Expires March 28, 2015 [Page 21] Internet-Draft YANG Conformance September 2014 list of instances of the data node specified in the "path" statement is used as the superset of all allowed values for the leafref type. A new protocol operation called "get-allowed-leafrefs" is defined to allow a client to discover the set of leafref values actually supported at the moment for a specific leaf or leaf-list. 6.3. Schema Conformance Discovery The "schema" list in the "ietf-netconf-monitoring" module identifies all the YANG modules available to the server. A new leaf called "conformance-type" is defined to augment this list. Two conformance types are defined, called "base" and "reuse". This information allows clients to understand how each module is used, without parsing and and analyzing the "capability" URIs from the "ietf-netconf-monitoring" module. 6.4. YANG module RFC Ed.: update the date below with the date of RFC publication and remove this note. file "ietf-yang-conformance@2014-09-24.yang" module ietf-yang-conformance { namespace "urn:ietf:params:xml:ns:yang:ietf-yang-conformance"; prefix "yangconf"; import ietf-netconf-monitoring { prefix ncm; } organization "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; contact "WG Web: WG List: WG Chair: Thomas Nadeau WG Chair: Juergen Schoenwaelder Editor: Andy Bierman "; description "This module contains RPC statements to identify Bierman Expires March 28, 2015 [Page 22] Internet-Draft YANG Conformance September 2014 the server capabilities for specific data nodes. NETCONF Monitoring extensions are also provided to report YANG conformance information. Copyright (c) 2014 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."; // RFC Ed.: replace XXXX with actual RFC number and remove this // note. // RFC Ed.: remove this note // Note: extracted from draft-bierman-netmod-restconf-01.txt // RFC Ed.: update the date below with the date of RFC publication // and remove this note. revision 2014-09-24 { description "Initial revision."; reference "RFC XXXX: YANG Conformance."; } feature netconf-monitoring { description "Indicates the ietf-netconf-monitoring extensions defined in this module are supported."; } feature get-allowed { description "Indicates the 'get-allowed-identities' and 'get-allowed-leafrefs' protocol operations are supported."; } rpc get-allowed-identities { if-feature get-allowed; description "Returns the set of identity values that are supported for Bierman Expires March 28, 2015 [Page 23] Internet-Draft YANG Conformance September 2014 a specific data node instance. The server will indicate if all instances of the specified data node accept the same value set. The server will return an error with an 'invalid-value' error-tag if the target parameter referenced an invalid instance. The server MAY support this operation for operational data (i.e. config false). If not, then an error with an 'operation-not-supported' error-tag will be returned by the server if the target parameter does not identify a data node in the configuration datastore"; input { leaf target { type instance-identifier { require-instance false; } mandatory true; description "Identifies an instance or possible instance of a data node that uses the identityref data type. The server will return information about the accepted values for this data node."; } } output { choice response { description "Either the 'all' element is returned or one or more 'identity' elements are returned in the response."; leaf all { type empty; description "Indicates all advertised identities with a matching base value are supported for the specified data node."; } leaf-list identity { type string; description "This formatted string contains the value of an acceptable identity for the specified identityref data node. It has the following format: : Bierman Expires March 28, 2015 [Page 24] Internet-Draft YANG Conformance September 2014 The module name is followed by the colon (':') character, which is followed by the identity name. No whitespace is allowed."; } } leaf support-all { type empty; description "Indicates all possible instances of the target data node support the same identities."; } } } rpc get-allowed-leafrefs { if-feature get-allowed; description "Returns the set of leafref values that are supported for a specific data node instance. The server will indicate if all instances of the specified data node accept the same value set. The server will return an error with an 'invalid-value' error-tag if the target parameter referenced an invalid instance. The server MAY support this operation for operational data (i.e. config false). If not, then an error with an 'operation-not-supported' error-tag will be returned by the server if the target parameter does not identify a data node in the configuration datastore"; input { leaf target { type instance-identifier { require-instance false; } mandatory true; description "Identifies an instance or possible instance of a data node that uses the leafref data type. The server will return information about the accepted values for this data node."; } } output { choice response { description Bierman Expires March 28, 2015 [Page 25] Internet-Draft YANG Conformance September 2014 "Either the 'all' element is returned or one or more 'value' elements are returned in the response."; leaf all { type empty; description "Indicates all current instances of the data node identified by the 'path' statement for the target parameter are supported."; } leaf-list value { type string; description "This string contains the value of an acceptable leafref, encoded as a string."; } } leaf support-all { type empty; description "Indicates all possible instances of the target data node support the same leaf values."; } } } augment /ncm:netconf-state/ncm:schemas/ncm:schema { if-feature netconf-monitoring; description "Conformance information added to each 'schema' list entry."; leaf conformance-type { type enumeration { enum base { description "Indicates the entire base module is supported within the server. The server MAY also advertise YANG features and YANG deviations for this module."; } enum reuse { description "Indicates that no data definition, augment, rpc, or notification statements in the base module are used from the module. Only reusable definitions are used, which include the following statements: - extension-stmt - feature-stmt - identity-stmt - typedef-stmt Bierman Expires March 28, 2015 [Page 26] Internet-Draft YANG Conformance September 2014 - grouping-stmt "; } } config false; description "Indicates how the server is claiming conformance for the module represented by this schema."; } leaf belongs-to-module { type string; config false; description "This leaf is only applicable if the schema identified this entry represents a YANG submodule. If so, then this string identifies the parent module name for the submodule."; } } } Bierman Expires March 28, 2015 [Page 27] Internet-Draft YANG Conformance September 2014 7. IANA Considerations 7.1. YANG Module Registry This document registers one URI in the IETF XML registry [RFC3688]. Following the format in RFC 3688, the following registration is requested to be made. URI: urn:ietf:params:xml:ns:yang:ietf-yang-conformance Registrant Contact: The NETMOD WG of the IETF. XML: N/A, the requested URI is an XML namespace. This document registers one YANG module in the YANG Module Names registry [RFC6020]. name: ietf-yang-conformance namespace: urn:ietf:params:xml:ns:yang:ietf-yang-conformance prefix: yangconf // RFC Ed.: replace XXXX with RFC number and remove this note reference: RFC XXXX Bierman Expires March 28, 2015 [Page 28] Internet-Draft YANG Conformance September 2014 8. Security Considerations TBD. Access control may need to be considered. For example, a server may wish to prune values returned from the "get-allowed-identities" or "get-allowed-leafrefs" operations, based on the client user identity. Bierman Expires March 28, 2015 [Page 29] Internet-Draft YANG Conformance September 2014 9. Open Issues 9.1. YANG Module Advertisement 9.1.1. Capability-ID vs. Module URI List Left out of this release: augment /ncm:netconf-state/ncm:capabilities { if-feature netconf-monitoring; leaf capability-set-id { config false; type string; description "Contains the capability set identifier for the current set of capability URIs. The server MUST update this value if any capability URIS are added, modified, or deleted. The server SHOULD select a previously unused value each time the value is changed. This object can enable caching of the capability URI list by a client."; } } The "capability-id" was first introduced in "draft-bierman-netconf-efficiency-extensions-00.txt" in October 2013. Switching from based module set discovery to retrieval-based module set discovery requires a "flag day" upgrade, and the data that is replacing the removed URIs needs to be mandatory-to- implement. If the is really too large, then a single URI could be used instead, so the client could cache the data and reduce bandwidth (at the cost of maintaining a cache). It is not clear that the message is really too large relative to SSH setup and other data. 9.1.2. Full vs. Partial List If only supported modules are advertised in the then the client has an incomplete list and must retrieve the revision dates of all the modules that are just imported. If the client has to retrieve any information at all to complete the module set, then it might as well retrieve all of it. Bierman Expires March 28, 2015 [Page 30] Internet-Draft YANG Conformance September 2014 9.2. YANG 1.1 Support The YANG 1.1 plan for server capability discovery is to only advertise YANG 1.0 modules, and not advertise any YANG 1.1 modules. Instead, a hash or instance-identifier will be used for client caching, and the client will retrieve the module information instead. It is not known if any new mechanisms will be needed in this document. 9.3. Protocol Independence o Should this document be written so it is specific to the NETCONF and RESTCONF protocols? o If protocol independence is required, then what parts of the draft need to be changed? What parts need to be moved to a different document? Bierman Expires March 28, 2015 [Page 31] Internet-Draft YANG Conformance September 2014 10. Change Log -- RFC Ed.: remove this section before publication. 10.1. 03-04 o Massive rewrite to address just the issues of conformance drift and conformance ambiguity within a single YANG module. o Removed package definitions and service profile definitions. Deferred for future work. o Added ietf-yang-conformance YANG module o changed term "module base" to "base module" o Removed term "YANG feature set" o Added terms "import-by-revision", "include-by-revision", "revision-identifier" o Added :submodule capability 10.2. 02-03 o updated routing example 10.3. 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. Bierman Expires March 28, 2015 [Page 32] Internet-Draft YANG Conformance September 2014 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. 10.4. 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 March 28, 2015 [Page 33] Internet-Draft YANG Conformance September 2014 11. References 11.1. 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. [RFC6022] Scott, M. and M. Bjorklund, "YANG Module for NETCONF Monitoring", RFC 6022, October 2010. [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, June 2011. 11.2. Informative References [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004. Bierman Expires March 28, 2015 [Page 34] Internet-Draft YANG Conformance September 2014 Author's Address Andy Bierman YumaWorks Email: andy@yumaworks.com Bierman Expires March 28, 2015 [Page 35]