tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Gloss.     Arch.     IMS     UICC    |    Misc.    |    search     info

RFC 6020

 
 
 

YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)

Part 2 of 7, p. 11 to 34
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 11 
4.  YANG Overview

4.1.  Functional Overview

   YANG is a language used to model data for the NETCONF protocol.  A
   YANG module defines a hierarchy of data that can be used for NETCONF-
   based operations, including configuration, state data, Remote
   Procedure Calls (RPCs), and notifications.  This allows a complete
   description of all data sent between a NETCONF client and server.

   YANG models the hierarchical organization of data as a tree in which
   each node has a name, and either a value or a set of child nodes.
   YANG provides clear and concise descriptions of the nodes, as well as
   the interaction between those nodes.

   YANG structures data models into modules and submodules.  A module
   can import data from other external modules, and include data from
   submodules.  The hierarchy can be augmented, allowing one module to
   add data nodes to the hierarchy defined in another module.  This
   augmentation can be conditional, with new nodes appearing only if
   certain conditions are met.

   YANG models can describe constraints to be enforced on the data,
   restricting the appearance or value of nodes based on the presence or
   value of other nodes in the hierarchy.  These constraints are
   enforceable by either the client or the server, and valid content
   MUST abide by them.

   YANG defines a set of built-in types, and has a type mechanism
   through which additional types may be defined.  Derived types can
   restrict their base type's set of valid values using mechanisms like
   range or pattern restrictions that can be enforced by clients or
   servers.  They can also define usage conventions for use of the
   derived type, such as a string-based type that contains a host name.

   YANG permits the definition of reusable groupings of nodes.  The
   instantiation of these groupings can refine or augment the nodes,
   allowing it to tailor the nodes to its particular needs.  Derived
   types and groupings can be defined in one module or submodule and
   used in either that location or in another module or submodule that
   imports or includes it.

Top      Up      ToC       Page 12 
   YANG data hierarchy constructs include defining lists where list
   entries are identified by keys that distinguish them from each other.
   Such lists may be defined as either sorted by user or automatically
   sorted by the system.  For user-sorted lists, operations are defined
   for manipulating the order of the list entries.

   YANG modules can be translated into an equivalent XML syntax called
   YANG Independent Notation (YIN) (Section 11), allowing applications
   using XML parsers and Extensible Stylesheet Language Transformations
   (XSLT) scripts to operate on the models.  The conversion from YANG to
   YIN is lossless, so content in YIN can be round-tripped back into
   YANG.

   YANG strikes a balance between high-level data modeling and low-level
   bits-on-the-wire encoding.  The reader of a YANG module can see the
   high-level view of the data model while understanding how the data
   will be encoded in NETCONF operations.

   YANG is an extensible language, allowing extension statements to be
   defined by standards bodies, vendors, and individuals.  The statement
   syntax allows these extensions to coexist with standard YANG
   statements in a natural way, while extensions in a YANG module stand
   out sufficiently for the reader to notice them.

   YANG resists the tendency to solve all possible problems, limiting
   the problem space to allow expression of NETCONF data models, not
   arbitrary XML documents or arbitrary data models.  The data models
   described by YANG are designed to be easily operated upon by NETCONF
   operations.

   To the extent possible, YANG maintains compatibility with Simple
   Network Management Protocol's (SNMP's) SMIv2 (Structure of Management
   Information version 2 [RFC2578], [RFC2579]).  SMIv2-based MIB modules
   can be automatically translated into YANG modules for read-only
   access.  However, YANG is not concerned with reverse translation from
   YANG to SMIv2.

   Like NETCONF, YANG targets smooth integration with the device's
   native management infrastructure.  This allows implementations to
   leverage their existing access control mechanisms to protect or
   expose elements of the data model.

Top      Up      ToC       Page 13 
4.2.  Language Overview

   This section introduces some important constructs used in YANG that
   will aid in the understanding of the language specifics in later
   sections.  This progressive approach handles the inter-related nature
   of YANG concepts and statements.  A detailed description of YANG
   statements and syntax begins in Section 7.

4.2.1.  Modules and Submodules

   A module contains three types of statements: module-header
   statements, revision statements, and definition statements.  The
   module header statements describe the module and give information
   about the module itself, the revision statements give information
   about the history of the module, and the definition statements are
   the body of the module where the data model is defined.

   A NETCONF server may implement a number of modules, allowing multiple
   views of the same data, or multiple views of disjoint subsections of
   the device's data.  Alternatively, the server may implement only one
   module that defines all available data.

   A module may be divided into submodules, based on the needs of the
   module owner.  The external view remains that of a single module,
   regardless of the presence or size of its submodules.

   The "include" statement allows a module or submodule to reference
   material in submodules, and the "import" statement allows references
   to material defined in other modules.

4.2.2.  Data Modeling Basics

   YANG defines four types of nodes for data modeling.  In each of the
   following subsections, the example shows the YANG syntax as well as a
   corresponding NETCONF XML representation.

4.2.2.1.  Leaf Nodes

   A leaf node contains simple data like an integer or a string.  It has
   exactly one value of a particular type and no child nodes.

   YANG Example:

       leaf host-name {
           type string;
           description "Hostname for this system";
       }

Top      Up      ToC       Page 14 
   NETCONF XML Example:

       <host-name>my.example.com</host-name>

   The "leaf" statement is covered in Section 7.6.

4.2.2.2.  Leaf-List Nodes

   A leaf-list is a sequence of leaf nodes with exactly one value of a
   particular type per leaf.

   YANG Example:

     leaf-list domain-search {
         type string;
         description "List of domain names to search";
     }

   NETCONF XML Example:

     <domain-search>high.example.com</domain-search>
     <domain-search>low.example.com</domain-search>
     <domain-search>everywhere.example.com</domain-search>

   The "leaf-list" statement is covered in Section 7.7.

4.2.2.3.  Container Nodes

   A container node is used to group related nodes in a subtree.  A
   container has only child nodes and no value.  A container may contain
   any number of child nodes of any type (including leafs, lists,
   containers, and leaf-lists).

   YANG Example:

     container system {
         container login {
             leaf message {
                 type string;
                 description
                     "Message given at start of login session";
             }
         }
     }

Top      Up      ToC       Page 15 
   NETCONF XML Example:

     <system>
       <login>
         <message>Good morning</message>
       </login>
     </system>

   The "container" statement is covered in Section 7.5.

4.2.2.4.  List Nodes

   A list defines a sequence of list entries.  Each entry is like a
   structure or a record instance, and is uniquely identified by the
   values of its key leafs.  A list can define multiple key leafs and
   may contain any number of child nodes of any type (including leafs,
   lists, containers etc.).

   YANG Example:

     list user {
         key "name";
         leaf name {
             type string;
         }
         leaf full-name {
             type string;
         }
         leaf class {
             type string;
         }
     }

Top      Up      ToC       Page 16 
   NETCONF XML Example:

     <user>
       <name>glocks</name>
       <full-name>Goldie Locks</full-name>
       <class>intruder</class>
     </user>
     <user>
       <name>snowey</name>
       <full-name>Snow White</full-name>
       <class>free-loader</class>
     </user>
     <user>
       <name>rzell</name>
       <full-name>Rapun Zell</full-name>
       <class>tower</class>
     </user>

   The "list" statement is covered in Section 7.8.

4.2.2.5.  Example Module

   These statements are combined to define the module:

Top      Up      ToC       Page 17 
     // Contents of "acme-system.yang"
     module acme-system {
         namespace "http://acme.example.com/system";
         prefix "acme";

         organization "ACME Inc.";
         contact "joe@acme.example.com";
         description
             "The module for entities implementing the ACME system.";

         revision 2007-06-09 {
             description "Initial revision.";
         }

         container system {
             leaf host-name {
                 type string;
                 description "Hostname for this system";
             }

             leaf-list domain-search {
                 type string;
                 description "List of domain names to search";
             }

             container login {
                 leaf message {
                     type string;
                     description
                         "Message given at start of login session";
                 }

                 list user {
                     key "name";
                     leaf name {
                         type string;
                     }
                     leaf full-name {
                         type string;
                     }
                     leaf class {
                         type string;
                     }
                 }
             }
         }
     }

Top      Up      ToC       Page 18 
4.2.3.  State Data

   YANG can model state data, as well as configuration data, based on
   the "config" statement.  When a node is tagged with "config false",
   its subhierarchy is flagged as state data, to be reported using
   NETCONF's <get> operation, not the <get-config> operation.  Parent
   containers, lists, and key leafs are reported also, giving the
   context for the state data.

   In this example, two leafs are defined for each interface, a
   configured speed and an observed speed.  The observed speed is not
   configuration, so it can be returned with NETCONF <get> operations,
   but not with <get-config> operations.  The observed speed is not
   configuration data, and it cannot be manipulated using <edit-config>.

     list interface {
         key "name";

         leaf name {
             type string;
         }
         leaf speed {
             type enumeration {
                 enum 10m;
                 enum 100m;
                 enum auto;
             }
         }
         leaf observed-speed {
             type uint32;
             config false;
         }
     }

4.2.4.  Built-In Types

   YANG has a set of built-in types, similar to those of many
   programming languages, but with some differences due to special
   requirements from the management domain.  The following table
   summarizes the built-in types discussed in Section 9:

Top      Up      ToC       Page 19 
       +---------------------+-------------------------------------+
       | Name                | Description                         |
       +---------------------+-------------------------------------+
       | binary              | Any binary data                     |
       | bits                | A set of bits or flags              |
       | boolean             | "true" or "false"                   |
       | decimal64           | 64-bit signed decimal number        |
       | empty               | A leaf that does not have any value |
       | enumeration         | Enumerated strings                  |
       | identityref         | A reference to an abstract identity |
       | instance-identifier | References a data tree node         |
       | int8                | 8-bit signed integer                |
       | int16               | 16-bit signed integer               |
       | int32               | 32-bit signed integer               |
       | int64               | 64-bit signed integer               |
       | leafref             | A reference to a leaf instance      |
       | string              | Human-readable string               |
       | uint8               | 8-bit unsigned integer              |
       | uint16              | 16-bit unsigned integer             |
       | uint32              | 32-bit unsigned integer             |
       | uint64              | 64-bit unsigned integer             |
       | union               | Choice of member types              |
       +---------------------+-------------------------------------+

   The "type" statement is covered in Section 7.4.

4.2.5.  Derived Types (typedef)

   YANG can define derived types from base types using the "typedef"
   statement.  A base type can be either a built-in type or a derived
   type, allowing a hierarchy of derived types.

   A derived type can be used as the argument for the "type" statement.

   YANG Example:

     typedef percent {
         type uint8 {
             range "0 .. 100";
         }
         description "Percentage";
     }

     leaf completed {
         type percent;
     }

Top      Up      ToC       Page 20 
   NETCONF XML Example:

     <completed>20</completed>

   The "typedef" statement is covered in Section 7.3.

4.2.6.  Reusable Node Groups (grouping)

   Groups of nodes can be assembled into reusable collections using the
   "grouping" statement.  A grouping defines a set of nodes that are
   instantiated with the "uses" statement:

     grouping target {
         leaf address {
             type inet:ip-address;
             description "Target IP address";
         }
         leaf port {
             type inet:port-number;
             description "Target port number";
         }
     }

     container peer {
         container destination {
             uses target;
         }
     }

   NETCONF XML Example:

     <peer>
       <destination>
         <address>192.0.2.1</address>
         <port>830</port>
       </destination>
     </peer>

   The grouping can be refined as it is used, allowing certain
   statements to be overridden.  In this example, the description is
   refined:

Top      Up      ToC       Page 21 
     container connection {
         container source {
             uses target {
                 refine "address" {
                     description "Source IP address";
                 }
                 refine "port" {
                     description "Source port number";
                 }
             }
         }
         container destination {
             uses target {
                 refine "address" {
                     description "Destination IP address";
                 }
                 refine "port" {
                     description "Destination port number";
                 }
             }
         }
     }

   The "grouping" statement is covered in Section 7.11.

4.2.7.  Choices

   YANG allows the data model to segregate incompatible nodes into
   distinct choices using the "choice" and "case" statements.  The
   "choice" statement contains a set of "case" statements that define
   sets of schema nodes that cannot appear together.  Each "case" may
   contain multiple nodes, but each node may appear in only one "case"
   under a "choice".

   When an element from one case is created, all elements from all other
   cases are implicitly deleted.  The device handles the enforcement of
   the constraint, preventing incompatibilities from existing in the
   configuration.

   The choice and case nodes appear only in the schema tree, not in the
   data tree or NETCONF messages.  The additional levels of hierarchy
   are not needed beyond the conceptual schema.

Top      Up      ToC       Page 22 
   YANG Example:

     container food {
       choice snack {
           case sports-arena {
               leaf pretzel {
                   type empty;
               }
               leaf beer {
                   type empty;
               }
           }
           case late-night {
               leaf chocolate {
                   type enumeration {
                       enum dark;
                       enum milk;
                       enum first-available;
                   }
               }
           }
       }
    }

   NETCONF XML Example:

     <food>
       <pretzel/>
       <beer/>
     </food>

   The "choice" statement is covered in Section 7.9.

4.2.8.  Extending Data Models (augment)

   YANG allows a module to insert additional nodes into data models,
   including both the current module (and its submodules) or an external
   module.  This is useful for example for vendors to add vendor-
   specific parameters to standard data models in an interoperable way.

   The "augment" statement defines the location in the data model
   hierarchy where new nodes are inserted, and the "when" statement
   defines the conditions when the new nodes are valid.

Top      Up      ToC       Page 23 
   YANG Example:

     augment /system/login/user {
         when "class != 'wheel'";
         leaf uid {
             type uint16 {
                 range "1000 .. 30000";
             }
         }
     }

   This example defines a "uid" node that only is valid when the user's
   "class" is not "wheel".

   If a module augments another module, the XML representation of the
   data will reflect the prefix of the augmenting module.  For example,
   if the above augmentation were in a module with prefix "other", the
   XML would look like:

   NETCONF XML Example:

     <user>
       <name>alicew</name>
       <full-name>Alice N. Wonderland</full-name>
       <class>drop-out</class>
       <other:uid>1024</other:uid>
     </user>

   The "augment" statement is covered in Section 7.15.

4.2.9.  RPC Definitions

   YANG allows the definition of NETCONF RPCs.  The operations' names,
   input parameters, and output parameters are modeled using YANG data
   definition statements.

Top      Up      ToC       Page 24 
   YANG Example:

     rpc activate-software-image {
         input {
             leaf image-name {
                 type string;
             }
         }
         output {
             leaf status {
                 type string;
             }
         }
     }

   NETCONF XML Example:

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <activate-software-image xmlns="http://acme.example.com/system">
         <image-name>acmefw-2.3</image-name>
      </activate-software-image>
     </rpc>

     <rpc-reply message-id="101"
                xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <status xmlns="http://acme.example.com/system">
         The image acmefw-2.3 is being installed.
       </status>
     </rpc-reply>

   The "rpc" statement is covered in Section 7.13.

4.2.10.  Notification Definitions

   YANG allows the definition of notifications suitable for NETCONF.
   YANG data definition statements are used to model the content of the
   notification.

Top      Up      ToC       Page 25 
   YANG Example:

     notification link-failure {
         description "A link failure has been detected";
         leaf if-name {
             type leafref {
                 path "/interface/name";
             }
         }
         leaf if-admin-status {
             type admin-status;
         }
         leaf if-oper-status {
             type oper-status;
         }
     }

   NETCONF XML Example:

     <notification
         xmlns="urn:ietf:params:netconf:capability:notification:1.0">
       <eventTime>2007-09-01T10:00:00Z</eventTime>
       <link-failure xmlns="http://acme.example.com/system">
         <if-name>so-1/2/3.0</if-name>
         <if-admin-status>up</if-admin-status>
         <if-oper-status>down</if-oper-status>
       </link-failure>
     </notification>

   The "notification" statement is covered in Section 7.14.

5.  Language Concepts

5.1.  Modules and Submodules

   The module is the base unit of definition in YANG.  A module defines
   a single data model.  A module can define a complete, cohesive model,
   or augment an existing data model with additional nodes.

   Submodules are partial modules that contribute definitions to a
   module.  A module may include any number of submodules, but each
   submodule may belong to only one module.

   The names of all standard modules and submodules MUST be unique.
   Developers of enterprise modules are RECOMMENDED to choose names for
   their modules that will have a low probability of colliding with
   standard or other enterprise modules, e.g., by using the enterprise
   or organization name as a prefix for the module name.

Top      Up      ToC       Page 26 
   A module uses the "include" statement to include its submodules, and
   the "import" statement to reference external modules.  Similarly, a
   submodule uses the "import" statement to reference other modules, and
   uses the "include" statement to reference other submodules within its
   module.  A module or submodule MUST NOT include submodules from other
   modules, and a submodule MUST NOT import its own module.

   The import and include statements are used to make definitions
   available to other modules and submodules:

   o  For a module or submodule to reference definitions in an external
      module, the external module MUST be imported.

   o  For a module to reference definitions in one of its submodules,
      the module MUST include the submodule.

   o  For a submodule to reference definitions in a second submodule of
      the same module, the first submodule MUST include the second
      submodule.

   There MUST NOT be any circular chains of imports or includes.  For
   example, if submodule "a" includes submodule "b", "b" cannot include
   "a".

   When a definition in an external module is referenced, a locally
   defined prefix MUST be used, followed by ":", and then the external
   identifier.  References to definitions in the local module MAY use
   the prefix notation.  Since built-in data types do not belong to any
   module and have no prefix, references to built-in data types (e.g.,
   int32) cannot use the prefix notation.

5.1.1.  Import and Include by Revision

   Published modules evolve independently over time.  In order to allow
   for this evolution, modules need to be imported using specific
   revisions.  When a module is written, it uses the current revisions
   of other modules, based on what is available at the time.  As future
   revisions of the imported modules are published, the importing module
   is unaffected and its contents are unchanged.  When the author of the
   module is prepared to move to the most recently published revision of
   an imported module, the module is republished with an updated
   "import" statement.  By republishing with the new revision, the
   authors explicitly indicate their acceptance of any changes in the
   imported module.

Top      Up      ToC       Page 27 
   For submodules, the issue is related but simpler.  A module or
   submodule that includes submodules needs to specify the revision of
   the included submodules.  If a submodule changes, any module or
   submodule that includes it needs to be updated.

   For example, module "b" imports module "a".

     module a {
         revision 2008-01-01 { ... }
         grouping a {
             leaf eh { .... }
         }
     }

     module b {
         import a {
             prefix p;
             revision-date 2008-01-01;
         }

         container bee {
             uses p:a;
         }
     }

   When the author of "a" publishes a new revision, the changes may not
   be acceptable to the author of "b".  If the new revision is
   acceptable, the author of "b" can republish with an updated revision
   in the "import" statement.

5.1.2.  Module Hierarchies

   YANG allows modeling of data in multiple hierarchies, where data may
   have more than one top-level node.  Models that have multiple top-
   level nodes are sometimes convenient, and are supported by YANG.

   NETCONF is capable of carrying any XML content as the payload in the
   <config> and <data> elements.  The top-level nodes of YANG modules
   are encoded as child elements, in any order, within these elements.
   This encapsulation guarantees that the corresponding NETCONF messages
   are always well-formed XML documents.

Top      Up      ToC       Page 28 
   For example:

     module my-config {
         namespace "http://example.com/schema/config";
         prefix "co";

         container system { ... }
         container routing { ... }
     }

   could be encoded in NETCONF as:

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
          xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
       <edit-config>
         <target>
           <running/>
         </target>
         <config>
           <system xmlns="http://example.com/schema/config">
             <!-- system data here -->
           </system>
           <routing xmlns="http://example.com/schema/config">
             <!-- routing data here -->
           </routing>
         </config>
       </edit-config>
     </rpc>

5.2.  File Layout

   YANG modules and submodules are typically stored in files, one module
   or submodule per file.  The name of the file SHOULD be of the form:

     module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' )

   YANG compilers can find imported modules and included submodules via
   this convention.  While the YANG language defines modules, tools may
   compile submodules independently for performance and manageability
   reasons.  Errors and warnings that cannot be detected during
   submodule compilation may be delayed until the submodules are linked
   into a cohesive module.

Top      Up      ToC       Page 29 
5.3.  XML Namespaces

   All YANG definitions are specified within a module that is bound to a
   particular XML namespace [XML-NAMES], which is a globally unique URI
   [RFC3986].  A NETCONF client or server uses the namespace during XML
   encoding of data.

   Namespaces for modules published in RFC streams [RFC4844] MUST be
   assigned by IANA, see Section 14.

   Namespaces for private modules are assigned by the organization
   owning the module without a central registry.  Namespace URIs MUST be
   chosen so they cannot collide with standard or other enterprise
   namespaces, for example by using the enterprise or organization name
   in the namespace.

   The "namespace" statement is covered in Section 7.1.3.

5.3.1.  YANG XML Namespace

   YANG defines an XML namespace for NETCONF <edit-config> operations
   and <error-info> content.  The name of this namespace is
   "urn:ietf:params:xml:ns:yang:1".

5.4.  Resolving Grouping, Type, and Identity Names

   Grouping, type, and identity names are resolved in the context in
   which they are defined, rather than the context in which they are
   used.  Users of groupings, typedefs, and identities are not required
   to import modules or include submodules to satisfy all references
   made by the original definition.  This behaves like static scoping in
   a conventional programming language.

   For example, if a module defines a grouping in which a type is
   referenced, when the grouping is used in a second module, the type is
   resolved in the context of the original module, not the second
   module.  There is no worry over conflicts if both modules define the
   type, since there is no ambiguity.

5.5.  Nested Typedefs and Groupings

   Typedefs and groupings may appear nested under many YANG statements,
   allowing these to be lexically scoped by the hierarchy under which
   they appear.  This allows types and groupings to be defined near
   where they are used, rather than placing them at the top level of the
   hierarchy.  The close proximity increases readability.

Top      Up      ToC       Page 30 
   Scoping also allows types to be defined without concern for naming
   conflicts between types in different submodules.  Type names can be
   specified without adding leading strings designed to prevent name
   collisions within large modules.

   Finally, scoping allows the module author to keep types and groupings
   private to their module or submodule, preventing their reuse.  Since
   only top-level types and groupings (i.e., those appearing as
   substatements to a module or submodule statement) can be used outside
   the module or submodule, the developer has more control over what
   pieces of their module are presented to the outside world, supporting
   the need to hide internal information and maintaining a boundary
   between what is shared with the outside world and what is kept
   private.

   Scoped definitions MUST NOT shadow definitions at a higher scope.  A
   type or grouping cannot be defined if a higher level in the schema
   hierarchy has a definition with a matching identifier.

   A reference to an unprefixed type or grouping, or one which uses the
   prefix of the current module, is resolved by locating the closest
   matching "typedef" or "grouping" statement among the immediate
   substatements of each ancestor statement.

5.6.  Conformance

   Conformance is a measure of how accurately a device follows the
   model.  Generally speaking, devices are responsible for implementing
   the model faithfully, allowing applications to treat devices which
   implement the model identically.  Deviations from the model can
   reduce the utility of the model and increase fragility of
   applications that use it.

   YANG modelers have three mechanisms for conformance:

   o  the basic behavior of the model

   o  optional features that are part of the model

   o  deviations from the model

   We will consider each of these in sequence.

Top      Up      ToC       Page 31 
5.6.1.  Basic Behavior

   The model defines a contract between the NETCONF client and server,
   which allows both parties to have faith the other knows the syntax
   and semantics behind the modeled data.  The strength of YANG lies in
   the strength of this contract.

5.6.2.  Optional Features

   In many models, the modeler will allow sections of the model to be
   conditional.  The device controls whether these conditional portions
   of the model are supported or valid for that particular device.

   For example, a syslog data model may choose to include the ability to
   save logs locally, but the modeler will realize that this is only
   possible if the device has local storage.  If there is no local
   storage, an application should not tell the device to save logs.

   YANG supports this conditional mechanism using a construct called
   "feature".  Features give the modeler a mechanism for making portions
   of the module conditional in a manner that is controlled by the
   device.  The model can express constructs that are not universally
   present in all devices.  These features are included in the model
   definition, allowing a consistent view and allowing applications to
   learn which features are supported and tailor their behavior to the
   device.

   A module may declare any number of features, identified by simple
   strings, and may make portions of the module optional based on those
   features.  If the device supports a feature, then the corresponding
   portions of the module are valid for that device.  If the device
   doesn't support the feature, those parts of the module are not valid,
   and applications should behave accordingly.

   Features are defined using the "feature" statement.  Definitions in
   the module that are conditional to the feature are noted by the
   "if-feature" statement with the name of the feature as its argument.

   Further details are available in Section 7.18.1.

5.6.3.  Deviations

   In an ideal world, all devices would be required to implement the
   model exactly as defined, and deviations from the model would not be
   allowed.  But in the real world, devices are often not able or
   designed to implement the model as written.  For YANG-based

Top      Up      ToC       Page 32 
   automation to deal with these device deviations, a mechanism must
   exist for devices to inform applications of the specifics of such
   deviations.

   For example, a BGP module may allow any number of BGP peers, but a
   particular device may only support 16 BGP peers.  Any application
   configuring the 17th peer will receive an error.  While an error may
   suffice to let the application know it cannot add another peer, it
   would be far better if the application had prior knowledge of this
   limitation and could prevent the user from starting down the path
   that could not succeed.

   Device deviations are declared using the "deviation" statement, which
   takes as its argument a string that identifies a node in the schema
   tree.  The contents of the statement details the manner in which the
   device implementation deviates from the contract as defined in the
   module.

   Further details are available in Section 7.18.3.

5.6.4.  Announcing Conformance Information in the <hello> Message

   The namespace URI MUST be advertised as a capability in the NETCONF
   <hello> message to indicate support for the YANG module by a NETCONF
   server.  The capability URI advertised MUST be of the form:

     capability-string   = namespace-uri [ parameter-list ]
     parameter-list      = "?" parameter *( "&" parameter )
     parameter           = revision-parameter /
                           module-parameter /
                           feature-parameter /
                           deviation-parameter
     revision-parameter  = "revision=" revision-date
     module-parameter    = "module=" module-name
     feature-parameter   = "features=" feature *( "," feature )
     deviation-parameter = "deviations=" deviation *( "," deviation )

   Where "revision-date" is the revision of the module (see
   Section 7.1.9) that the NETCONF server implements, "module-name" is
   the name of module as it appears in the "module" statement (see
   Section 7.1), "namespace-uri" is the namespace URI for the module as
   it appears in the "namespace" statement (see Section 7.1.3),
   "feature" is the name of an optional feature implemented by the
   device (see Section 7.18.1), and "deviation" is the name of a module
   defining device deviations (see Section 7.18.3).

   In the parameter list, each named parameter MUST occur at most once.

Top      Up      ToC       Page 33 
5.6.4.1.  Modules

   Servers indicate the names of supported modules via the <hello>
   message.  Module namespaces are encoded as the base URI in the
   capability string, and the module name is encoded as the "module"
   parameter to the base URI.

   A server MUST advertise all revisions of all modules it implements.

   For example, this <hello> message advertises one module "syslog".

   <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
     <capability>
       http://example.com/syslog?module=syslog&amp;revision=2008-04-01
     </capability>
   </hello>

5.6.4.2.  Features

   Servers indicate the names of supported features via the <hello>
   message.  In <hello> messages, the features are encoded in the
   "features" parameter within the URI.  The value of this parameter is
   a comma-separated list of feature names that the device supports for
   the specific module.

   For example, this <hello> message advertises one module, informing
   the client that it supports the "local-storage" feature of module
   "syslog".
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <capability>
    http://example.com/syslog?module=syslog&amp;features=local-storage
  </capability>
</hello>

5.6.4.3.  Deviations

   Device deviations are announced via the "deviations" parameter.  The
   value of the "deviations" parameter is a comma-separated list of
   modules containing deviations from the capability's module.

   For example, this <hello> message advertises two modules, informing
   the client that it deviates from module "syslog" according to the
   deviations listed in the module "my-devs".

Top      Up      ToC       Page 34 
   <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <capability>
         http://example.com/syslog?module=syslog&amp;deviations=my-devs
       </capability>
       <capability>
         http://example.com/my-deviations?module=my-devs
       </capability>
     </hello>

5.7.  Data Store Modification

   Data models may allow the server to alter the configuration data
   store in ways not explicitly directed via NETCONF protocol messages.
   For example, a data model may define leafs that are assigned system-
   generated values when the client does not provide one.  A formal
   mechanism for specifying the circumstances where these changes are
   allowed is out of scope for this specification.



(page 34 continued on part 3)

Next RFC Part