The YANG 1.1 Data Modeling LanguageTail-f Systemsmbj@tail-f.comNETCONFXMLdata modeling
YANG is a data modeling language used to model configuration data,
state data, remote procedure calls, and notifications for network
management protocols. This document describes the syntax and
semantics of version 1.1 of the YANG language. YANG version 1.1 is
a maintenance release of the YANG language, addressing ambiguities
and defects in the original specification. There are a small number
of backward incompatibilities from YANG version 1. This document
also specifies the YANG mappings to the Network Configuration
Protocol (NETCONF).
YANG is a data modeling language originally designed to model
configuration and state data manipulated by the Network Configuration
Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF
notifications . Since the publication of YANG version 1
, YANG has been used or proposed to be used for other
protocols (e.g., RESTCONF and CoMI
). Further, other encodings than XML have
been proposed (e.g., JSON ).
This document describes the syntax and semantics of version 1.1 of the
YANG language. It also describes how a data model defined in a YANG
module is encoded in the Extensible Markup Language (XML), and how
NETCONF operations are used to manipulate the data. Other protocols
and encodings are possible, but out of scope for this specification.
In terms of developing YANG data models,
provides some guidelines and recommendations.
Note that this document does not obsolete RFC 6020 .
This document defines version 1.1 of the YANG language. YANG version
1.1 is a maintenance release of the YANG language, addressing
ambiguities and defects in the original specification .
The following changes are not backwards compatible with YANG version
1:
Changed the rules for the interpretation of escaped characters in
double quoted strings. This is an backwards incompatible change
from YANG version 1. When updating a YANG version 1 module to 1.1,
and the module uses a character sequence that is now illegal, the
string must be changed to match the new rules. See for
details.
An unquoted string cannot contain any single or double quote
characters. This is an backwards incompatible change from YANG
version 1. When updating a YANG version 1 module to 1.1, and the
module uses such quote characters, the string must be changed to match
the new rules. See for details.
Made "when" and "if‑feature" illegal on list keys. This is an
backwards incompatible change from YANG version 1. When updating a
YANG version 1 module to 1.1, and the module uses these constructs,
they must be removed to match the new rules.
Defined the legal characters in YANG modules. When updating a
YANG version 1 module to 1.1, any characters that are now illegal
must be removed. See for details.
Made noncharacters illegal in the built-in type "string". This
change affects the run-time behavior of YANG-based protocols.
The following additional changes have been done to YANG:
Changed the YANG version from "1" to "1.1".
Made the "yang‑version" statement mandatory in YANG version "1.1".
Extended the "if‑feature" syntax to be a boolean expression over
feature names.
Allow "if‑feature" in "bit", "enum", and "identity".
Allow "if‑feature" in "refine".
Allow "choice" as a shorthand case statement (see ).
Added a new substatement "modifier" to pattern (see ).
Allow "must" in "input", "output", and "notification".
Allow "require‑instance" in leafref.
Allow "description" and "reference" in "import" and "include".
Allow imports of multiple revisions of a module.
Allow "augment" to add conditionally mandatory nodes (see ).
Added a set of new XPath functions in .
Clarified the XPath context's tree in .
Defined the string value of an identityref in XPath expressions
(see ).
Clarified what unprefixed names mean in leafrefs in typedefs (see
and ).
Allow identities to be derived from multiple base identities (see
and ).
Allow enumerations and bits to be subtyped (see and
).
Allow leaf-lists to have default values (see
).
Allow non-unique values in non-configuration leaf-lists (see
).
Use syntax for case-sensitive strings in the grammar.
Changed the module advertisement mechanism (see ).
Changed the scoping rules for definitions in submodules. A
submodule can now reference all definitions in all submodules that
belong to the same module, without using the "include" statement.
Added a new statement "action" that is used to define operations
tied to data nodes.
Allow notifications to be tied to data nodes.
Added a new data definition statement "anydata" (see )
which is RECOMMENDED to be used instead of "anyxml" when the data
can be modeled in YANG
Allow types empty and leafref in unions.
Allow type empty in a key.
The following changes have been done to the NETCONF mapping:
A server advertises support for YANG 1.1 modules by using
ietf-yang-library instead of listing
them as capabilities in the <hello> message.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14, .
The following terms are used within this document:
action: An operation defined for a node in the data tree.
anydata: A data node that can contain an unknown set of nodes that
can be modelled by YANG, except anyxml.
anyxml: A data node that can contain an unknown chunk of XML data.
augment: Adds new schema nodes to a previously defined schema node.
base type: The type from which a derived type was derived,
which may be either a built-in type or another derived type.
built-in type: A YANG data type defined in the YANG language,
such as uint32 or string.
choice: A schema node where only one of a number of identified
alternatives is valid.
client: An entity that can access YANG-defined data on a server,
over some network management protocol.
conformance: A measure of how accurately a server follows a data
model.
container: An interior data node that exists in at most one
instance in the data tree. A container has no value, but rather a
set of child nodes.
data definition statement: A statement that defines new data
nodes. One of container, leaf, leaf-list, list, choice, case,
augment, uses, anydata, and anyxml.
data model: A data model describes how data is represented and
accessed.
data node: A node in the schema tree that can be instantiated in a
data tree. One of container, leaf, leaf-list, list, anydata, and
anyxml.
data tree: An instantiated tree of any data modeled with YANG, e.g.,
configuration data, state data, combined configuration and state
data, RPC or action input, RPC or action output, or notification.
derived type: A type that is derived from a built-in type (such as
uint32), or another derived type.
extension: An extension attaches non-YANG semantics to statements. The
extension statement defines new statements to express these
semantics.
feature: A mechanism for marking a portion of the model as optional.
Definitions can be tagged with a feature name and are only valid on
servers that support that feature.
grouping: A reusable set of schema nodes, which may be used locally
in the module and by other modules that import from it. The
grouping statement is not a data definition statement and, as such,
does not define any nodes in the schema tree.
identifier: A string used to identify different kinds of YANG items
by name.
identity: A globally unique, abstract, and untyped name.
instance identifier: A mechanism for identifying a particular
node in a data tree.
interior node: Nodes within a hierarchy that are not leaf nodes.
leaf: A data node that exists in at most one instance in the data
tree. A leaf has a value but no child nodes.
leaf-list: Like the leaf node but defines a set of
uniquely identifiable nodes rather than a single node.
Each node has a value but no child nodes.
list: An interior data node that may exist in multiple instances in
the data tree. A list has no value, but rather a set of child
nodes.
mandatory node: A mandatory node is one of:
A leaf, choice, anydata, or anyxml node with a "mandatory" statement
with the value "true".
A list or leaf-list node with a "min‑elements" statement with a
value greater than zero.
A container node without a "presence" statement and which has at
least one mandatory node as a child.
module: A YANG module defines hierarchies of schema nodes. With its
definitions and the definitions it imports or includes from
elsewhere, a module is self-contained and "compilable".
non-presence container: A container that has no meaning of its own,
existing only to contain child nodes.
presence container: A container where the presence of the container
itself carries some meaning.
RPC: A Remote Procedure Call.
RPC operation: A specific Remote Procedure Call.
schema node: A node in the schema tree. One of action, container, leaf,
leaf-list, list, choice, case, rpc, input, output,
notification, anydata, and anyxml.
schema node identifier: A mechanism for identifying a particular
node in the schema tree.
schema tree: The definition hierarchy specified within a module.
server: An entity that provides access to YANG-defined data to a
client, over some network management protocol.
server deviation: A failure of the server to implement a module
faithfully.
submodule: A partial module definition that contributes derived
types, groupings, data nodes, RPCs, actions, and notifications to a
module. A YANG module can be constructed from a number of
submodules.
top-level data node: A data node where there is no other data node
between it and a module or submodule statement.
uses: The "uses" statement is used to instantiate the set of schema
nodes defined in a grouping statement. The instantiated nodes may
be refined and augmented to tailor them to any specific needs.
value space: For a data type; the set of values permitted by
the data type. For a leaf or leaf-list instance; the value
space of its data type.
The following terms are defined in :
configuration data
configuration datastore
datastore
state data
When modelled with YANG, a datastore is realized as an instantiated
data tree.
When modelled with YANG, a configuration datastore is realized as an
instantiated data tree with configuration data.
Throughout this document there are many examples of YANG statements.
These examples are supposed to illustrate certain features, and are
not supposed to be complete, valid YANG modules.
This non-normative section is intended to give a high-level
overview of YANG to first-time readers.
YANG is a language originally designed to model data for the NETCONF
protocol. A YANG module defines hierarchies 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. Although out of scope for this specification, YANG can also be
used with other protocols than NETCONF.
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 definitions from other external modules, and include
definitions 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 data models can describe constraints to be enforced on the data,
restricting the presence 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.
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
usage 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 and used in either
the same module or in another module that imports it.
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) (), allowing applications using
XML parsers and Extensible Stylesheet Language Transformations (XSLT)
scripts to operate on the models. The conversion from YANG to YIN is
semantically lossless, so content in YIN can be round-tripped back
into YANG.
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 data models for network
management protocols such as NETCONF, not arbitrary XML documents or
arbitrary data models.
To the extent possible, YANG maintains compatibility with Simple
Network Management Protocol's (SNMP's) SMIv2 (Structure of Management
Information version 2 , ). 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.
This section introduces some important constructs used in YANG that
will aid in the understanding of the language specifics in later
sections.
YANG data models are defined in modules. A module contains a
collection of related definitions.
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 server may implement a number of modules, allowing multiple
views of the same data, or multiple views of disjoint subsections of
the server's data. Alternatively, the server may implement only one
module that defines all available data.
A module may have portions of its definitions separated into
submodules, based on the needs of the module designer. The external
view remains that of a single module, regardless of the presence or
size of its submodules.
The "import" statement allows a module or submodule to reference
definitions defined in other modules.
The "include" statement is used in a module to identify each
submodule that belongs to it.
YANG defines four main types of data nodes for data modeling. In each
of the following subsections, the examples show the YANG syntax as
well as a corresponding XML encoding. The syntax of YANG statements
is defined in .
A leaf instance contains simple data like an integer or a string. It has
exactly one value of a particular type and no child nodes.
YANG Example:
XML Encoding Example:
my.example.com
]]>
The "leaf" statement is covered in .
A leaf-list defines a sequence of values of a particular type.
YANG Example:
XML Encoding Example:
high.example.com
low.example.comeverywhere.example.com
]]>
The "leaf‑list" statement is covered in .
A container 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 (leafs, lists, containers,
leaf-lists, actions, and notifications).
YANG Example:
XML Encoding Example:
Good morning
]]>
The "container" statement is covered in .
A list defines a sequence of list entries. Each entry is like a
container, and is uniquely identified by the values of its key leafs,
if it has any key leafs defined. 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:
XML Encoding Example:
glocksGoldie LocksintrudersnoweySnow Whitefree-loaderrzellRapun Zelltower
]]>
The "list" statement is covered in .
These statements are combined to define the module:
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. If it is tagged with "config
true", its subhierarchy is flagged as configuration data. 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 "config" statement is covered in .
YANG has a set of built-in types, similar to those of many programming
languages, but with some differences due to special requirements of
network management. The following table summarizes the built-in
types discussed in :
NameDescriptionbinaryAny binary databitsA set of bits or flagsboolean"true" or "false"decimal6464-bit signed decimal numberemptyA leaf that does not have any valueenumerationOne of an enumerated set of stringsidentityrefA reference to an abstract identityinstance-identifierA reference to a data tree nodeint88-bit signed integerint1616-bit signed integerint3232-bit signed integerint6464-bit signed integerleafrefA reference to a leaf instancestringA character stringuint88-bit unsigned integeruint1616-bit unsigned integeruint3232-bit unsigned integeruint6464-bit unsigned integerunionChoice of member types
The "type" statement is covered in .
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:
XML Encoding Example:
20
]]>
The "typedef" statement is covered in .
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.
YANG Example:
XML Encoding Example:
2001:db8::2
830
]]>
The grouping can be refined as it is used, allowing certain statements
to be overridden. In this example, the description is refined:
The "grouping" statement is covered in .
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".
The choice and case nodes appear only in the schema tree but not in
the data tree. The additional levels of hierarchy are not needed
beyond the conceptual schema. The presence of a case is indicated by
the presence of one or more of the nodes within it.
Since only one of the choice's cases can be valid at any time, when a
node from one case is created in the data tree, all nodes from all
other cases are implicitly deleted. The server handles the
enforcement of the constraint, preventing incompatibilities from
existing in the configuration.
YANG Example:
XML Encoding Example:
]]>
The "choice" statement is covered in .
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.
When a server implements a module containing an "augment" statement,
that implies that the server's implementation of the augmented module
contains the additional nodes.
YANG Example:
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 elements that are added
to the encoding are in the namespace of the augmenting module. For
example, if the above augmentation were in a module with prefix
"other", the XML would look like:
XML Encoding Example:
alicewAlice N. Wonderlanddrop-out1024
]]>
The "augment" statement is covered in .
YANG allows the definition of operations. The operations' name, input
parameters, and output parameters are modeled using YANG data
definition statements. Operations on the top-level in a module are
defined with the "rpc" statement. Operations can also be tied to a
container or list data node. Such operations are defined with the
"action" statement.
YANG Example for an operation at the top-level:
NETCONF XML Example:
example-fw-2.3
The image example-fw-2.3 is being installed.
]]>
YANG Example for an operation tied to a list data node:
NETCONF XML Example:
eth1192.0.2.160
]]>
The "rpc" statement is covered in , and the "action" statement in
.
YANG allows the definition of notifications. YANG data definition
statements are used to model the content of the notification.
YANG Example:
NETCONF XML Example:
2007-09-01T10:00:00Zso-1/2/3.0updown
]]>
The "notification" statement is covered in .
The module is the base unit of definition in YANG. A module defines a
single data model. A module can also 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.
Developers of YANG modules and submodules 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.
Within a server, all module names MUST be unique.
A module uses the "include" statement to list all its submodules. A
module, or submodule belonging to that module, can reference
definitions in the module and all submodules included by the module.
A module or submodule uses the "import" statement to reference
external modules. Statements in the module or submodule can
reference definitions in the external module using the prefix
specified in the "import" statement.
For backward compatibility with YANG version 1, a submodule
MAY use the "include" statement to reference other submodules
within its module, but this is not necessary in YANG version 1.1. A
submodule can reference any definition in the module it belongs to and
in all submodules included by the module. A submodule MUST NOT
include different revisions of other submodules than the revisions
that its module includes.
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 from other modules:
For a module or submodule to reference definitions in an external
module, the external module MUST be imported.
A module MUST include all its submodules.
A module, or submodule belonging to that module, MAY reference
definitions in the module and all submodules included by the module.
There MUST NOT be any circular chains of imports. For
example, if module "a" imports module "b", "b" cannot import
"a".
When a definition in an external module is referenced, a locally
defined prefix MUST be used, followed by a colon (":"), 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. The syntax for a reference to
a definition is formally defined by the rule "identifier‑ref" in
.
Published modules evolve independently over time. In order to allow
for this evolution, modules can be imported using specific revisions.
Initially, a module imports the revisions of other modules that are
current when the module is written. 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.
For submodules, the issue is related but simpler. A module or
submodule that includes submodules may specify the revision of the
included submodules. If a submodule changes, any module or submodule
that includes it by revision needs to be updated to reference the new
revision.
For example, module "b" imports module "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.
If a module is not imported with a specific revision, it is undefined
which revision is used.
YANG allows modeling of data in multiple hierarchies, where data may
have more than one top-level node. Each top-level data node in a
module defines a separate hierarchy. 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.
For example, an instance of:
could be encoded in NETCONF as:
]]>
YANG modules and submodules are typically stored in files, one module
or submodule statement per file. The name of the file SHOULD be of
the form:
"module‑or‑submodule‑name" is the name of the module or submodule, and
the optional "revision‑date" is the latest revision of the module or
submodule, as defined by the "revision" statement ().
The file extension ".yang" denotes that the contents of the file is
written with YANG syntax (), and ".yin" denotes that it is
written with YIN syntax ().
YANG parsers can find imported modules and included submodules via
this convention.
All YANG definitions are specified within a module. Each module is
bound to a distinct XML namespace , which is a globally
unique URI . A NETCONF client or server uses the namespace
during XML encoding of data.
XML namespaces for modules published in RFC streams MUST be
assigned by IANA, see section 14 in .
XML 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 .
YANG defines an XML namespace for NETCONF <edit‑config> operations,
<error‑info> content, and the <action> element. The name of this
namespace is "urn:ietf:params:xml:ns:yang:1".
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 ambiguity if both modules define the type,
since there is no ambiguity.
Typedefs and groupings may appear nested under many YANG statements,
allowing these to be lexically scoped by the statement 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.
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 statement
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
matching "typedef" or "grouping" statement among the immediate
substatements of each ancestor statement.
Conformance to a model is a measure of how accurately a server follows the
model. Generally speaking, servers are responsible for implementing
the model faithfully, allowing applications to treat servers 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:
the basic behavior of the model
optional features that are part of the model
deviations from the model
We will consider each of these in sequence.
The model defines a contract between a YANG-based 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.
In many models, the modeler will allow sections of the model to be
conditional. The server controls whether these conditional portions
of the model are supported or valid for that particular server.
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 server has local storage. If there is no local
storage, an application should not tell the server 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
server. The model can express constructs that are not universally
present in all servers. 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
server.
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 server supports a feature, then the corresponding
portions of the module are valid for that server. If the server
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.
Further details are available in .
In an ideal world, all servers would be required to implement the
model exactly as defined, and deviations from the model would not be
allowed. But in the real world, servers are often not able or
designed to implement the model as written. For YANG-based
automation to deal with these server deviations, a mechanism must
exist for servers to inform applications of the specifics of such
deviations.
For example, a BGP module may allow any number of BGP peers, but a
particular server 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.
Server 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 server
implementation deviates from the contract as defined in the module.
Further details are available in .
This document defines the following mechanism for announcing
conformance information. Other mechanisms may be defined by future
specifications.
A NETCONF server MUST announce the modules it implements (see
) by implementing the YANG module "ietf‑yang‑library"
defined in , and listing all
implemented modules in the "/modules‑state/module" list.
The server also MUST advertise the following capability in the <hello>
message (line-breaks and whitespaces are used for formatting reasons
only):
&module-set-id=
]]>
The parameter "revision" has the same value as the revision date of
the "ietf‑yang‑library" module implemented by the server. This
parameter MUST be present.
The parameter "module‑set‑id" has the same value as the leaf
"/modules‑state/module‑set‑id" from "ietf‑yang‑library". This
parameter MUST be present.
With this mechanism, a client can cache the supported modules for a
server, and only update the cache if the "module‑set‑id" value in the
<hello> message changes.
A server implements a module if it implements the module's data nodes,
rpcs, actions, notifications, and deviations.
A server MUST NOT implement more than one revision of a module.
If a server implements a module A that imports a module B, and A
uses any node from B in an "augment" or "path" statement that the
server supports, then the server MUST implement a revision of module
B that has these nodes defined. This is regardless of if module B
is imported by revision or not.
If a server implements a module A that imports a module C without
specifying the revision date of module C, and the server does not
implement C (e.g., if C only defines some typedefs), the server MUST
list module C in the "/modules‑state/module" list from
"ietf‑yang‑library" , and it MUST set
the leaf "conformance‑type" to "import" for this module.
If a server lists a module C in the "/modules‑state/module" list from
"ietf‑yang‑library", and there are other modules Ms listed that import
C without specifying the revision date of module C, the server MUST
use the definitions from the most recent revision of C listed for
modules Ms.
The reason for these rules is that clients need to be able to know the
specific data model structure and types of all leafs and leaf-lists
implemented in a server.
For example, with these modules:
A server that implements revision "2015‑01‑01" of module "a" and
supports feature "foo" can implement revision "2015‑01‑01" or
"2015‑04‑04" of module "b". Since "b" was imported by revision, the
type of leaf "/b:x/a:y" is the same regardless of which revision of
"b" the server implements.
A server that implements module "a", but does not support feature
"foo" does not have to implement module "b".
A server that implements revision "2015‑01‑01" of module "a" picks
any revision of module "c", and list it in the "/modules‑state/module"
list from "ietf‑yang‑library".
The following XML encoding example shows valid data for the
"/modules‑state/module" list for a server that implements module "a":
ee1ecb017370cafda2015-01-01urn:example:afooimplementb2015-04-04urn:example:bimplementc2015-02-02urn:example:cimport
]]>
Data models may allow the server to alter the configuration datastore
in ways not explicitly directed via network management 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.
The YANG syntax is similar to that of SMIng and
programming languages like C and C++. This C-like syntax was
chosen specifically for its readability, since YANG values the time
and effort of the readers of models above those of modules writers and
YANG tool-chain developers. This section introduces the YANG
syntax.
Legal characters in YANG modules are the Unicode and ISO/IEC 10646
characters, including tab, carriage return, and line feed
but excluding the other C0 control characters, the surrogate blocks,
and the noncharacters. The character syntax is formally defined by
the rule "yang‑char" in .
YANG modules and submodules are stored in files using the UTF-8
character encoding.
Lines in a YANG module end with a carriage return-line feed
combination or with a line feed alone. A carriage return that is not
followed by a line feed may only appear inside a quoted string
(). Note that carriage returns and line feeds that appear
inside quoted strings become part of the value of the string without
modification; the value of a multi-line quoted string contains the
same form of line ends as those lines of the YANG module.
YANG modules are parsed as a series of tokens. This section details
the rules for recognizing tokens from an input stream. YANG
tokenization rules are both simple and powerful. The simplicity is
driven by a need to keep the parsers easy to implement, while the
power is driven by the fact that modelers need to express their models
in readable formats.
Comments are C++ style. A single line comment starts with "//" and
ends at the end of the line. A block comment starts with "/*" and
ends with the nearest following "*/".
Note that inside a quoted string (), these character
pairs are never interpreted as the start or end of a comment.
A token in YANG is either a keyword, a string, a semicolon (";"), or
braces ("{" or "}"). A string can be quoted or unquoted. A keyword
is either one of the YANG keywords defined in this document, or a
prefix identifier, followed by a colon (":"), followed by a language extension
keyword. Keywords are case sensitive. See for a formal
definition of identifiers.
An unquoted string is any sequence of characters that does not contain
any space, tab, carriage return, or line feed characters, a single or
double quote character, a semicolon (";"), braces ("{" or "}"), or
comment sequences ("//", "/*", or "*/").
Note that any keyword can legally appear as an unquoted string.
Within an unquoted string, every character is preserved. Note that
this means that the backslash character does not have any special
meaning in an unquoted string.
If a double-quoted string contains a line break followed by space or
tab characters that are used to indent the text according to the
layout in the YANG file, this leading whitespace is stripped from the
string, up to and including the column of the starting double quote
character, or to the first non-whitespace character, whichever occurs
first. Any tab character in a succeeding line that must be examined
for stripping is first converted into 8 space characters.
If a double-quoted string contains space or tab characters before a
line break, this trailing whitespace is stripped from the string.
A single-quoted string (enclosed within ' ') preserves each character
within the quotes. A single quote character cannot occur in a
single-quoted string, even when preceded by a backslash.
Within a double-quoted string (enclosed within " "), a backslash
character introduces a representation of a special character, which
depends on the character that immediately follows the backslash:
The backslash MUST NOT be followed by any other character.
If a quoted string is followed by a plus character ("+"), followed by
another quoted string, the two strings are concatenated into one
string, allowing multiple concatenations to build one string.
Whitespace, line breaks, and comments are allowed between the quoted
strings and the plus character.
In double-quoted strings, whitespace trimming is done before
substitution of backslash-escaped characters. Concatenation is
performed as the last step.
The following strings are equivalent:
The following examples show some special strings:
The following examples show some illegal strings:
The following strings are equivalent:
Identifiers are used to identify different kinds of YANG items by
name. Each identifier starts with an uppercase or lowercase ASCII
letter or an underscore character, followed by zero or more ASCII
letters, digits, underscore characters, hyphens, and dots.
Implementations MUST support identifiers up to 64 characters in
length, and MAY support longer identifiers. Identifiers are case
sensitive. The identifier syntax is formally defined by the rule
"identifier" in . Identifiers can be specified as quoted or
unquoted strings.
Each identifier is valid in a namespace that depends on the type of
the YANG item being defined. All identifiers defined in a namespace
MUST be unique.
All module and submodule names share the same global module
identifier namespace.
All extension names defined in a module and its submodules share the
same extension identifier namespace.
All feature names defined in a module and its submodules share the
same feature identifier namespace.
All identity names defined in a module and its submodules share the
same identity identifier namespace.
All derived type names defined within a parent node or at the
top level of the module or its submodules share the same type
identifier namespace. This namespace is scoped to all descendant
nodes of the parent node or module. This means that any descendent
node may use that typedef, and it MUST NOT define a typedef with the
same name.
All grouping names defined within a parent node or at the top level of
the module or its submodules share the same grouping identifier
namespace. This namespace is scoped to all descendant nodes of the
parent node or module. This means that any descendent node may use
that grouping, and it MUST NOT define a grouping with the same name.
All leafs, leaf-lists, lists, containers, choices, rpcs, actions,
notifications, anydatas, and anyxmls defined (directly or through a uses
statement) within a parent node or at the top level of the module or
its submodules share the same identifier namespace. This namespace
is scoped to the parent node or module, unless the parent node is a
case node. In that case, the namespace is scoped to the closest
ancestor node that is not a case or choice node.
All cases within a choice share the same case identifier namespace.
This namespace is scoped to the parent choice node.
Forward references are allowed in YANG.
A YANG module contains a sequence of statements. Each statement
starts with a keyword, followed by zero or one argument, followed
either by a semicolon (";") or a block of substatements enclosed
within braces ("{ }"):
The argument is a string, as defined in .
A module can introduce YANG extensions by using the "extension"
keyword (see ). The extensions can be imported by other
modules with the "import" statement (see ). When an imported
extension is used, the extension's keyword MUST be qualified using the
prefix with which the extension's module was imported. If an
extension is used in the module where it is defined, the extension's
keyword MUST be qualified with the prefix of this module.
The processing of extensions depends on whether support for those
extensions is claimed for a given YANG parser or the tool set in which
it is embedded. An unsupported extension, appearing in a YANG module
as an unknown-statement (see ) MAY be ignored in its
entirety. Any supported extension MUST be processed in accordance
with the specification governing that extension.
Care must be taken when defining extensions so that modules that use
the extensions are meaningful also for applications that do not
support the extensions.
YANG relies on XML Path Language (XPath) 1.0 as a notation for
specifying many inter-node references and dependencies. An
implementation is not required to implement an XPath interpreter, but
MUST ensure that the requirements encoded in the data model are
enforced. The manner of enforcement is an implementation decision.
The XPath expressions MUST be syntactically correct, and all prefixes
used MUST be present in the XPath context (see ). An
implementation may choose to implement them by hand, rather than using
the XPath expression directly.
The data model used in the XPath expressions is the same as that used
in XPath 1.0 , with the same extension for root node children
as used by XSLT 1.0 (Section 3.1). Specifically, it means that
the root node may have any number of element nodes as its children.
The data tree has no concept of document order. An implementation
needs to choose some document order but how it is done is an
implementation decision. This means that XPath expressions in YANG
modules SHOULD NOT rely on any specific document order.
Numbers in XPath 1.0 are IEEE 754 double-precision floating-point
values, see Section 3.5 in . This means that some values of
int64, uint64 and decimal64 types (see and )
cannot be exactly represented in XPath expressions. Therefore, due
caution should be exercised when using nodes with 64-bit numeric
values in XPath expressions. In particular, numerical comparisons
involving equality may yield unexpected results.
For example, consider the following definition:
An instance of the "lxiv" leaf having the value of 10.0000000000000001
will then successfully pass validation.
All YANG XPath expressions share the following XPath context
definition:
The set of namespace declarations is the set of all "import"
statements' prefix and namespace pairs in the module where the XPath
expression is specified, and the "prefix"
statement's prefix for the "namespace" statement's URI.
Names without a namespace prefix belong to the same namespace as
the identifier of the current node. Inside a grouping, that
namespace is affected by where the grouping is used (see
). Inside a typedef, that namespace is affected by
where the typedef is referenced. If a typedef is defined and
referenced within a grouping, the namespace is affected by where the
grouping is used (see ).
The function library is the core function library defined in
, and the functions defined in .
The set of variable bindings is empty.
The mechanism for handling unprefixed names is adopted from XPath 2.0
, and helps simplify XPath expressions in YANG. No
ambiguity may ever arise because YANG node identifiers are always
qualified names with a non-null namespace URI.
The accessible tree depends on where the statement with the XPath
expression is defined:
If the XPath expression is defined in substatement to a data node
that represents configuration, the accessible tree is the data in
the datastore where the context node exists. The root node
has all top-level configuration data nodes in all modules as
children.
If the XPath expression is defined in a substatement to a data node
that represents state data, the accessible tree is all state
data in the server, and the running configuration datastore. The
root node has all top-level data nodes in all modules as children.
If the XPath expression is defined in a substatement to a
"notification" statement, the accessible tree is the notification
instance, all state data in the server, and the running
configuration datastore.
If the notification is defined on the top-level in a module, then
the root node has the node representing the notification being
defined and all top-level data nodes in all modules as children.
Otherwise, the root node has all top-level data nodes in all modules
as children.
If the XPath expression is defined in a substatement to an "input"
statement in an "rpc" or "action" statement, the accessible tree is
the RPC or action operation instance, all state data in the server,
and the running configuration datastore. The root node has
top-level data nodes in all modules as children. Additionally, for
an RPC, the root node also has the node representing the RPC
operation being defined as a child. The node representing the
operation being defined has the operation's input parameters as
children.
If the XPath expression is defined in a substatement to an "output"
statement in an "rpc" or "action" statement, the accessible tree is
the RPC or action operation instance, all state data in the server,
and the running configuration datastore. The root node has
top-level data nodes in all modules as children. Additionally, for
an RPC, the root node also has the node representing the RPC
operation being defined as a child. The node representing the
operation being defined has the operation's output parameters as
children.
In the accessible tree, all leafs and leaf-lists with default values
in use exist (See and ).
If a node that exists in the accessible tree has a non-presence
container as a child, then the non-presence container also exists in
the tree.
The context node varies with the YANG XPath expression, and is
specified where the YANG statement with the XPath expression is
defined.
Given the following module:
And given the following data tree, specified in XML:
12
]]>
The accessible tree for a notification "down" on /a/b[id="2"] is:
12error
// possibly other top-level nodes here
]]>
The accessible tree for an action invocation of "reset" on /a/b[id="1"]
with the "when" parameter set to "10" would be:
1102
// possibly other top-level nodes here
]]>
The accessible tree for the action output of this action is:
1ok2
// possibly other top-level nodes here
]]>
The accessible tree for a notification "failure" could be:
122
// possibly other top-level nodes here
]]>
A schema node identifier is a string that identifies a node in the
schema tree. It has two forms, "absolute" and "descendant", defined
by the rules "absolute‑schema‑nodeid" and "descendant‑schema‑nodeid"
in , respectively. A schema node identifier consists of a
path of identifiers, separated by slashes ("/"). In an absolute
schema node identifier, the first identifier after the leading slash
is any top-level schema node in the local module or in an imported
module.
References to identifiers defined in external modules MUST be
qualified with appropriate prefixes, and references to identifiers
defined in the current module and its submodules MAY use a prefix.
For example, to identify the child node "b" of top-level node "a", the
string "/a/b" can be used.
The following sections describe all of the YANG statements.
Note that even a statement that does not have any substatements
defined in YANG can have vendor-specific extensions as
substatements. For example, the "description" statement does not
have any substatements defined in YANG, but the following is
legal:
The "module" statement defines the module's name, and groups all
statements that belong to the module together. The "module"
statement's argument is the name of the module, followed by a block of
substatements that hold detailed module information. The module name
is an identifier (see ).
Names of modules published in RFC streams MUST be assigned by IANA,
see section 14 in .
Private module names are assigned by the organization owning the
module without a central registry. See for recommendations
on how to name modules.
A module typically has the following layout:
{
// header information
// linkage statements
// meta information
// revision history
// module definitions
}
]]>substatementsectioncardinalityanydata0..nanyxml0..naugment0..nchoice0..ncontact0..1container0..ndescription0..1deviation0..nextension0..nfeature0..ngrouping0..nidentity0..nimport0..ninclude0..nleaf0..nleaf-list0..nlist0..nnamespace1notification0..norganization0..1prefix1reference0..1revision0..nrpc0..ntypedef0..nuses0..nyang-version1
The "yang‑version" statement specifies which version of the YANG
language was used in developing the module. The statement's argument
is a string. It MUST contain the value "1.1" for YANG modules defined
based on this specification.
A module or submodule that doesn't contain the "yang‑version"
statement, or one that contains the value "1", is developed for YANG
version 1, defined in .
Handling of the "yang‑version" statement for versions other than "1.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.
For compatibility between YANG version 1 and 1.1, see .
The "namespace" statement defines the XML namespace that all
identifiers defined by the module are qualified by in the XML
encoding, with the exception of identifiers for data nodes, action
nodes, and notification nodes defined inside a grouping (see
for details). The argument to the "namespace" statement is the URI of
the namespace.
See also .
The "prefix" statement is used to define the prefix associated with
the module and its namespace. The "prefix" statement's argument is the
prefix string that is used as a prefix to access a module. The prefix
string MAY be used with the module to refer to definitions contained
in the module, e.g., "if:ifName". A prefix is an identifier (see
).
When used inside the "module" statement, the "prefix" statement
defines the prefix suggested to be used when this module is imported.
To improve readability of the NETCONF XML, a NETCONF client or server
that generates XML or XPath that use prefixes SHOULD use the prefix
defined by the module as the XML namespace prefix, unless there is a
conflict.
When used inside the "import" statement, the "prefix" statement
defines the prefix to be used when accessing definitions inside the
imported module. When a reference to an identifier from the imported
module is used, the prefix string for the imported module followed by
a colon (":") and the identifier is used, e.g., "if:ifIndex". To
improve readability of YANG modules, the prefix defined by a module
SHOULD be used when the module is imported, unless there is a
conflict. If there is a conflict, i.e., two different modules that
both have defined the same prefix are imported, at least one of them
MUST be imported with a different prefix.
All prefixes, including the prefix for the module itself MUST be
unique within the module or submodule.
The "import" statement makes definitions from one module available
inside another module or submodule. The argument is the name of the
module to import, and the statement is followed by a block of
substatements that holds detailed import information. When a module
is imported, the importing module may:
use any grouping and typedef defined at the top level in the
imported module or its submodules.
use any extension, feature, and identity defined in the imported
module or its submodules.
use any node in the imported module's schema tree in
"must", "path", and "when" statements, or as the target node in
"augment" and "deviation" statements.
The mandatory "prefix" substatement assigns a prefix for the imported
module that is scoped to the importing module or submodule. Multiple
"import" statements may be specified to import from different modules.
When the optional "revision‑date" substatement is present, any
typedef, grouping, extension, feature, and identity referenced by
definitions in the local module are taken from the specified revision
of the imported module. It is an error if the specified revision of
the imported module does not exist. If no "revision‑date"
substatement is present, it is undefined from which revision of the
module they are taken.
Multiple revisions of the same module can be imported, provided that
different prefixes are used.
substatementsectioncardinalityprefix1revision-date0..1description0..1reference0..1
The import's "revision‑date" statement is used to specify the
version of the module to import.
The "include" statement is used to make content from a submodule
available to that submodule's parent module. The argument is an
identifier that is the name of the submodule to include. Modules are
only allowed to include submodules that belong to that module, as
defined by the "belongs‑to" statement (see ).
When a module includes a submodule, it incorporates the contents of
the submodule into the node hierarchy of the module.
For backward compatibility with YANG version 1, a submodule is
allowed to include another submodule belonging to the same module, but
this is not necessary in YANG version 1.1 (see ).
When the optional "revision‑date" substatement is present, the
specified revision of the submodule is included in the module. It is
an error if the specified revision of the submodule does not exist.
If no "revision‑date" substatement is present, it is undefined which
revision of the submodule is included.
Multiple revisions of the same submodule MUST NOT be included.
substatementsectioncardinalityrevision-date0..1description0..1reference0..1
The "organization" statement defines the party responsible for this
module. The argument is a string that is used to specify a textual
description of the organization(s) under whose auspices this module
was developed.
The "contact" statement provides contact information for the module.
The argument is a string that is used to specify contact information
for the person or persons to whom technical queries concerning this
module should be sent, such as their name, postal address, telephone
number, and electronic mail address.
The "revision" statement specifies the editorial revision history of
the module, including the initial revision. A series of revision
statements detail the changes in the module's definition. The
argument is a date string in the format "YYYY‑MM‑DD", followed by a
block of substatements that holds detailed revision information. A
module SHOULD have at least one "revision" statement. For
every published editorial change, a new one SHOULD be added in front
of the revisions sequence, so that all revisions are in reverse
chronological order.
substatementsectioncardinalitydescription0..1reference0..1
While the primary unit in YANG is a module, a YANG module can itself
be constructed out of several submodules. Submodules allow a module
designer to split a complex model into several pieces where all the
submodules contribute to a single namespace, which is defined by the
module that includes the submodules.
The "submodule" statement defines the submodule's name, and groups all
statements that belong to the submodule together. The "submodule"
statement's argument is the name of the submodule, followed by a block
of substatements that hold detailed submodule information. The
submodule name is an identifier (see ).
Names of submodules published in RFC streams MUST be assigned by
IANA, see section 14 in .
Private submodule names are assigned by the organization owning the
submodule without a central registry. See for recommendations
on how to name submodules.
A submodule typically has the following layout:
{
]]>
]]>
// linkage statements
// meta information
// revision history
// module definitions
}
]]>substatementsectioncardinalityanydata0..nanyxml0..naugment0..nbelongs-to1choice0..ncontact0..1container0..ndescription0..1deviation0..nextension0..nfeature0..ngrouping0..nidentity0..nimport0..ninclude0..nleaf0..nleaf-list0..nlist0..nnotification0..norganization0..1reference0..1revision0..nrpc0..ntypedef0..nuses0..nyang-version1
The "belongs‑to" statement specifies the module to which the submodule
belongs. The argument is an identifier that is the name of the
module.
A submodule MUST only be included by the module to which it belongs, or
by another submodule that belongs to that module.
The mandatory "prefix" substatement assigns a prefix for the module to
which the submodule belongs. All definitions in the module that the
submodule belongs to and all its submodules can be accessed by using
the prefix.
substatementsectioncardinalityprefix1
The "typedef" statement defines a new type that may be used locally in
the module or submodule, and by other modules that import from it,
according to the rules in . The new type is called
the "derived type", and the type from which it was derived is called
the "base type". All derived types can be traced back to a YANG
built-in type.
The "typedef" statement's argument is an identifier that is the name
of the type to be defined, and MUST be followed by a block of
substatements that holds detailed typedef information.
The name of the type MUST NOT be one of the YANG built-in types. If
the typedef is defined at the top level of a YANG module or submodule,
the name of the type to be defined MUST be unique within the module.
substatementsectioncardinalitydefault0..1description0..1reference0..1status0..1type1units0..1
The "type" statement, which MUST be present, defines the base type
from which this type is derived. See for details.
The "units" statement, which is optional, takes as an argument a string
that contains a textual definition of the units associated with the
type.
The "default" statement takes as an argument a string that contains a
default value for the new type.
The value of the "default" statement MUST be valid according to the type
specified in the "type" statement.
If the base type has a default value, and the new derived type does
not specify a new default value, the base type's default value is also
the default value of the new derived type.
If the type's default value is not valid according to the new
restrictions specified in a derived type or leaf definition, the
derived type or leaf definition MUST specify a new default value
compatible with the restrictions.
The "type" statement takes as an argument a string that is the
name of a YANG built-in type (see ) or a derived type (see
), followed by an optional block of substatements that are
used to put further restrictions on the type.
The restrictions that can be applied depend on the type being
restricted. The restriction statements for all built-in types are
described in the subsections of .
substatementsectioncardinalitybase0..nbit0..nenum0..nfraction-digits0..1length0..1path0..1pattern0..nrange0..1require-instance0..1type0..n
The "container" statement is used to define an interior data node
in the schema tree. It takes one argument, which is an identifier,
followed by a block of substatements that holds detailed container
information.
A container node does not have a value, but it has a list of child
nodes in the data tree. The child nodes are defined in the
container's substatements.
YANG supports two styles of containers, those that exist only for
organizing the hierarchy of data nodes, and those whose presence in
the data tree has an explicit meaning.
In the first style, the container has no meaning of its own, existing
only to contain child nodes. In particular, the presence of the
container node with no child nodes is semantically equivalent to the
absence of the container node. YANG calls this style a "non-presence
container". This is the default style.
For example, the set of scrambling options for Synchronous
Optical Network (SONET) interfaces may be placed inside a "scrambling"
container to enhance the organization of the configuration hierarchy,
and to keep these nodes together. The "scrambling" node itself has no
meaning, so removing the node when it becomes empty relieves the user
from performing this task.
In the second style, the presence of the container itself carries some
meaning, representing a single bit of data.
For configuration data, the container acts as both a configuration knob
and a means of organizing related configuration. These containers are
explicitly created and deleted.
YANG calls this style a "presence container" and it is indicated
using the "presence" statement, which takes as its argument a text
string indicating what the presence of the node means.
For example, an "ssh" container may turn on the ability to log into
the server using ssh, but can also contain any ssh-related
configuration knobs, such as connection rates or retry limits.
The "presence" statement (see ) is used to give semantics to
the existence of the container in the data tree.
substatementsectioncardinalityaction0..nanydata0..nanyxml0..nchoice0..nconfig0..1container0..ndescription0..1grouping0..nif-feature0..nleaf0..nleaf-list0..nlist0..nmust0..nnotification0..npresence0..1reference0..1status0..1typedef0..nuses0..nwhen0..1
The "must" statement, which is optional, takes as an argument a string
that contains an XPath expression (see ). It is used to
formally declare a constraint on valid data. The constraint is
enforced according to the rules in .
When a datastore is validated, all "must" constraints are conceptually
evaluated once for each node in the accessible tree (see
).
All such constraints MUST evaluate to "true" for the data to be valid.
The XPath expression is conceptually evaluated in the following
context, in addition to the definition in :
The context node is the node in the accessible tree for which
the "must" statement is defined.
The result of the XPath expression is converted to a boolean value
using the standard XPath rules.
Note that since all leaf values in the data tree are conceptually
stored in their canonical form (see ), any XPath
comparisons are done on the canonical value.
Also note that the XPath expression is conceptually evaluated. This means
that an implementation does not have to use an XPath evaluator in the
server. How the evaluation is done in practice is an
implementation decision.
substatementsectioncardinalitydescription0..1error-app-tag0..1error-message0..1reference0..1
The "error‑message" statement, which is optional, takes a string
as an argument. If the constraint evaluates to "false", the string is
passed as <error‑message> in the <rpc‑error> in NETCONF.
The "error‑app‑tag" statement, which is optional, takes a string
as an argument. If the constraint evaluates to "false", the string is
passed as <error‑app‑tag> in the <rpc‑error> in NETCONF.
= 64)' {
error-message "An atm MTU must be 64 .. 17966";
}
}
]]>
The "presence" statement assigns a meaning to the presence of a
container in the data tree. It takes as an argument a string that
contains a textual description of what the node's presence means.
If a container has the "presence" statement, the container's existence
in the data tree carries some meaning. Otherwise, the container is
used to give some structure to the data, and it carries no meaning by
itself.
See for additional information.
Within a container, the "container", "leaf", "list", "leaf‑list",
"uses", "choice", "anydata", and "anyxml" statements can be used to
define child nodes to the container.
A container node is encoded as an XML element. The element's local
name is the container's identifier, and its namespace is the
module's XML namespace (see ).
The container's child nodes are encoded as subelements to the
container element. If the container defines RPC or
action input or output parameters, these subelements are encoded in
the same order as they are defined within the "container" statement.
Otherwise, the subelements are encoded in any order.
Any whitespace between the subelements to the container is
insignificant, i.e., an implementation MAY insert whitespace
characters between subelements.
If a non-presence container does not have any child nodes, the
container may or may not be present in the XML encoding.
Containers can be created, deleted, replaced, and modified through
<edit‑config>, by using the "operation" attribute (see ,
Section 7.2) in the container's XML element.
If a container does not have a "presence" statement and the last child
node is deleted, the NETCONF server MAY delete the container.
When a NETCONF server processes an <edit‑config> request, the
elements of procedure for the container node are:
If the operation is "merge" or "replace", the node is created if it
does not exist.
If the operation is "create", the node is created if it does not
exist. If the node already exists, a "data‑exists" error is
returned.
If the operation is "delete", the node is deleted if it exists. If
the node does not exist, a "data‑missing" error is returned.
Given the following container definition:
A corresponding XML instance example:
]]>
Since the <ssh> element is present, ssh is enabled.
To delete a container with an <edit‑config>:
]]>
The "leaf" statement is used to define a leaf node in the schema tree.
It takes one argument, which is an identifier, followed by a block of
substatements that holds detailed leaf information.
A leaf node has a value, but no child nodes in the data tree.
Conceptually, the value in the data tree is always in the canonical
form (see ).
A leaf node exists in zero or one instances in the data tree.
The "leaf" statement is used to define a scalar variable of a
particular built-in or derived type.
The default value of a leaf is the value that the server uses if the
leaf does not exist in the data tree. The usage of the default value
depends on the leaf's closest ancestor node in the schema tree that
is not a non-presence container (see ):
If no such ancestor exists in the schema tree, the default value
MUST be used.
Otherwise, if this ancestor is a case node, the default value
MUST be used if any node from the case exists in the data tree, or
if the case node is the choice's default case, and no
nodes from any other case exist in the data tree.
Otherwise, the default value MUST be used if the ancestor node
exists in the data tree.
In these cases, the default value is said to be in use.
Note that if the leaf or any of its ancestors has a "when" condition
or "if‑feature" expression that evaluates to "false", then the default
value is not in use.
When the default value is in use, the server MUST operationally
behave as if the leaf was present in the data tree with the default
value as its value.
If a leaf has a "default" statement, the leaf's default value is
the value of the "default" statement. Otherwise, if the leaf's
type has a default value, and the leaf is not mandatory, then the
leaf's default value is the type's default value. In all other
cases, the leaf does not have a default value.
substatementsectioncardinalityconfig0..1default0..1description0..1if-feature0..nmandatory0..1must0..nreference0..1status0..1type1units0..1when0..1
The "type" statement, which MUST be present, takes as an argument the
name of an existing built-in or derived type. The optional substatements
specify restrictions on this type. See for details.
The "default" statement, which is optional, takes as an argument a
string that contains a default value for the leaf.
The value of the "default" statement MUST be valid according to the
type specified in the leaf's "type" statement.
The "default" statement MUST NOT be present on nodes where
"mandatory" is "true".
The definition of the default value MUST NOT be marked with an
"if‑feature" statement. For example, the following is illegal:
The "mandatory" statement, which is optional, takes as an argument the
string "true" or "false", and puts a constraint on valid data. If not
specified, the default is "false".
If "mandatory" is "true", the behavior of the constraint depends on
the type of the leaf's closest ancestor node in the schema tree that
is not a non-presence container (see ):
If no such ancestor exists in the schema tree, the leaf MUST exist.
Otherwise, if this ancestor is a case node, the leaf MUST exist if
any node from the case exists in the data tree.
Otherwise, the leaf MUST exist if the ancestor node exists in the
data tree.
This constraint is enforced according to the rules in .
A leaf node is encoded as an XML element. The element's local name is
the leaf's identifier, and its namespace is the module's XML
namespace (see ).
The value of the leaf node is encoded to XML according to the type,
and sent as character data in the element.
See for an example.
When a NETCONF server processes an <edit‑config> request, the
elements of procedure for the leaf node are:
If the operation is "merge" or "replace", the node is created if it
does not exist, and its value is set to the value found in the XML
RPC data.
If the operation is "create", the node is created if it does not
exist. If the node already exists, a "data‑exists" error is
returned.
If the operation is "delete", the node is deleted if it exists. If
the node does not exist, a "data‑missing" error is returned.
Given the following "leaf" statement, placed in the previously defined
"ssh" container (see ):
A corresponding XML instance example:
2022
]]>
To set the value of a leaf with an <edit‑config>:
2022
]]>
Where the "leaf" statement is used to define a simple scalar variable
of a particular type, the "leaf‑list" statement is used to define an
array of a particular type. The "leaf‑list" statement takes one
argument, which is an identifier, followed by a block of substatements
that holds detailed leaf-list information.
In configuration data, the values in a leaf-list MUST be unique.
The definitions of the default values MUST NOT be marked with an
"if‑feature" statement.
Conceptually, the values in the data tree MUST be in the canonical
form (see ).
YANG supports two styles for ordering the entries within lists and
leaf-lists. In many lists, the order of list entries does not impact
the implementation of the list's configuration, and the server is free
to sort the list entries in any reasonable order. The "description"
string for the list may suggest an order to the server implementor.
YANG calls this style of list "system ordered" and they are indicated
with the statement "ordered-by system".
For example, a list of valid users would typically be sorted
alphabetically, since the order in which the users appeared in
the configuration would not impact the creation of those users'
accounts.
In the other style of lists, the order of list entries matters for
the implementation of the list's configuration and the user is
responsible for ordering the entries, while the server maintains that
order. YANG calls this style of list "user ordered" and they are
indicated with the statement "ordered-by user".
For example, the order in which packet filters entries are applied
to incoming traffic may affect how that traffic is filtered. The user
would need to decide if the filter entry that discards all TCP traffic
should be applied before or after the filter entry that allows all
traffic from trusted interfaces. The choice of order would be
crucial.
YANG provides a rich set of facilities within NETCONF's <edit‑config>
operation that allows the order of list entries in user-ordered lists
to be controlled. List entries may be inserted or rearranged,
positioned as the first or last entry in the list, or positioned
before or after another specific entry.
The "ordered‑by" statement is covered in .
The default values of a leaf-list are the values that the server uses if the
leaf-list does not exist in the data tree. The usage of the default values
depends on the leaf-list's closest ancestor node in the schema tree that
is not a non-presence container (see ):
If no such ancestor exists in the schema tree, the default values
MUST be used.
Otherwise, if this ancestor is a case node, the default values
MUST be used if any node from the case exists in the data tree, or
if the case node is the choice's default case, and no
nodes from any other case exist in the data tree.
Otherwise, the default values MUST be used if the ancestor node
exists in the data tree.
In these cases, the default values are said to be in use.
Note that if the leaf-list or any of its ancestors has a "when"
condition or "if‑feature" expression that evaluates to "false", then
the default values are not in use.
When the default values are in use, the server MUST operationally
behave as if the leaf-list was present in the data tree with the default
values as its values.
If a leaf-list has one or more "default" statement, the leaf-list's
default values are the values of the "default" statements, and if the
leaf-list is user-ordered, the default values are used in the order of
the "default" statements. Otherwise, if the leaf-list's type has a
default value, and the leaf-list does not have a "min‑elements"
statement with a value greater than or equal to one, then the
leaf-list's default value is one instance of the type's default value.
In all other cases, the leaf-list does not have any default values.
substatementsectioncardinalityconfig0..1default0..ndescription0..1if-feature0..nmax-elements0..1min-elements0..1must0..nordered-by0..1reference0..1status0..1type1units0..1when0..1
The "default" statement, which is optional, takes as an argument a
string that contains a default value for the leaf-list.
The value of the "default" statement MUST be valid according to the
type specified in the leaf-list's "type" statement.
The "default" statement MUST NOT be present on nodes where
"min‑elements" has a value greater than or equal to one.
The "min‑elements" statement, which is optional, takes as an argument
a non-negative integer that puts a constraint on valid list entries.
A valid leaf-list or list MUST have at least min-elements entries.
If no "min‑elements" statement is present, it defaults to zero.
The behavior of the constraint depends on the type of the leaf-list's
or list's closest ancestor node in the schema tree that is not a
non-presence container (see ):
If no such ancestor exists in the schema tree, the constraint is
enforced.
Otherwise, if this ancestor is a case node, the constraint is
enforced if any other node from the case exists.
Otherwise, it is enforced if the ancestor node exists.
The constraint is further enforced according to the rules in
.
The "max‑elements" statement, which is optional, takes as an argument a
positive integer or the string "unbounded", which puts a constraint on
valid list entries. A valid leaf-list or list always has at most
max-elements entries.
If no "max‑elements" statement is present, it defaults to "unbounded".
The "max‑elements" constraint is enforced according to the rules in
.
The "ordered‑by" statement defines whether the order of entries within
a list are determined by the user or the system. The argument is one
of the strings "system" or "user". If not present, order defaults to
"system".
This statement is ignored if the list represents state data, RPC
output parameters, or notification content.
See for additional information.
The entries in the list are ordered according to an order determined by
the system. The "description" string for the list may suggest an
order to the server implementor. If not, an implementation is free to
order the entries in any order. An implementation
SHOULD use the same order for the same data, regardless of how the
data were created. Using a deterministic order will make comparisons
possible using simple tools like "diff".
This is the default order.
The entries in the list are ordered according to an order defined by
the user. In NETCONF, this order is controlled by using special XML
attributes in the <edit‑config> request. See for details.
A leaf-list node is encoded as a series of XML elements. Each
element's local name is the leaf-list's identifier, and its namespace
is the module's XML namespace (see ).
The value of each leaf-list entry is encoded to XML according to the
type, and sent as character data in the element.
The XML elements representing leaf-list entries MUST appear in the
order specified by the user if the leaf-list is "ordered-by user";
otherwise, the order is implementation-dependent. The XML elements
representing leaf-list entries MAY be interleaved with elements for
siblings of the leaf-list, unless the leaf-list defines RPC or action
input or output parameters.
See for an example.
Leaf-list entries can be created and deleted, but not modified,
through <edit‑config>, by using the "operation" attribute in the
leaf-list entry's XML element.
In an "ordered-by user" leaf-list, the attributes "insert" and "value"
in the YANG XML namespace () can be used to control where
in the leaf-list the entry is inserted. These can be used during
"create" operations to insert a new leaf-list entry, or during "merge"
or "replace" operations to insert a new leaf-list entry or move an
existing one.
The "insert" attribute can take the values "first", "last", "before",
and "after". If the value is "before" or "after", the "value"
attribute MUST also be used to specify an existing entry in the
leaf-list.
If no "insert" attribute is present in the "create" operation, it
defaults to "last".
If several entries in an "ordered-by user" leaf-list are modified in
the same <edit‑config> request, the entries are modified one at the
time, in the order of the XML elements in the request.
In a <copy‑config>, or an <edit‑config> with a "replace" operation
that covers the entire leaf-list, the leaf-list order is the same as
the order of the XML elements in the request.
When a NETCONF server processes an <edit‑config> request, the
elements of procedure for a leaf-list node are:
If the operation is "merge" or "replace", the leaf-list entry is
created if it does not exist.
If the operation is "create", the leaf-list entry is created if it
does not exist. If the leaf-list entry already exists, a
"data‑exists" error is returned.
If the operation is "delete", the entry is deleted from the
leaf-list if it exists. If the leaf-list entry does not exist, a
"data‑missing" error is returned.
A corresponding XML instance example:
alice
bob
]]>
To create a new element in this list, using the default <edit‑config>
operation "merge":
eric
]]>
Given the following ordered-by user leaf-list:
The following would be used to insert a new cipher "blowfish‑cbc" after
"3des‑cbc":
blowfish-cbc
]]>
The "list" statement is used to define an interior data node in the
schema tree. A list node may exist in multiple instances in the data
tree. Each such instance is known as a list entry. The "list"
statement takes one argument, which is an identifier, followed by a
block of substatements that holds detailed list information.
A list entry is uniquely identified by the values of the list's keys,
if defined.
substatementsectioncardinalityaction0..nanydata0..nanyxml0..nchoice0..nconfig0..1container0..ndescription0..1grouping0..nif-feature0..nkey0..1leaf0..nleaf-list0..nlist0..nmax-elements0..1min-elements0..1must0..nnotification0..nordered-by0..1reference0..1status0..1typedef0..nunique0..nuses0..nwhen0..1
The "key" statement, which MUST be present if the list represents
configuration, and MAY be present otherwise, takes as an argument a
string that specifies a space-separated list of one or more leaf
identifiers of this list. A leaf identifier MUST NOT appear more than
once in the key. Each such leaf identifier MUST refer to a child leaf
of the list. The leafs can be defined directly in substatements to
the list, or in groupings used in the list.
The combined values of all the leafs specified in the key are used to
uniquely identify a list entry. All key leafs MUST be given values
when a list entry is created. Thus, any default values in the key
leafs or their types are ignored. It also implies that any mandatory
statement in the key leafs are ignored.
A leaf that is part of the key can be of any built-in or derived type.
All key leafs in a list MUST have the same value for their "config" as
the list itself.
The key string syntax is formally defined by the rule "key‑arg" in
.
The "unique" statement is used to put constraints on valid list
entries. It takes as an argument a string that contains a
space-separated list of schema node identifiers, which MUST be given
in the descendant form (see the rule "descendant‑schema‑nodeid" in
). Each such schema node identifier MUST refer to a leaf.
If one of the referenced leafs represents configuration data, then all
of the referenced leafs MUST represent configuration data.
The "unique" constraint specifies that the combined values of all the
leaf instances specified in the argument string, including leafs with
default values, MUST be unique within all list entry instances in
which all referenced leafs exist or have default values. The
constraint is enforced according to the rules in .
The unique string syntax is formally defined by the rule "unique‑arg"
in .
With the following list:
The following configuration is not valid:
smtp192.0.2.125http192.0.2.125
]]>
The following configuration is valid, since the "http" and "ftp" list
entries do not have a value for all referenced leafs, and are thus not
taken into account when the "unique" constraint is enforced:
smtp192.0.2.125http192.0.2.1ftp192.0.2.1
]]>
Within a list, the "container", "leaf", "list", "leaf‑list", "uses",
"choice", "anydata", and "anyxml" statements can be used to define
child nodes to the list.
A list is encoded as a series of XML elements, one for each entry in
the list. Each element's local name is the list's identifier, and its
namespace is the module's XML namespace (see ). There is
no XML element surrounding the list as a whole.
The list's key nodes are encoded as subelements to the list's
identifier element, in the same order as they are defined within the
"key" statement.
The rest of the list's child nodes are encoded as subelements to the
list element, after the keys. If the list defines RPC or action input or output
parameters, the subelements are encoded in the same order as they are
defined within the "list" statement. Otherwise, the subelements are
encoded in any order.
Any whitespace between the subelements to the list entry is
insignificant, i.e., an implementation MAY insert whitespace
characters between subelements.
The XML elements representing list entries MUST appear in the order
specified by the user if the list is "ordered-by user", otherwise the
order is implementation-dependent. The XML elements representing list
entries MAY be interleaved with elements for siblings of the list,
unless the list defines RPC or action input or output parameters.
List entries can be created, deleted, replaced, and modified through
<edit‑config>, by using the "operation" attribute in the list's XML
element. In each case, the values of all keys are used to
uniquely identify a list entry. If all keys are not specified for a
list entry, a "missing‑element" error is returned.
In an "ordered-by user" list, the attributes "insert" and "key" in the
YANG XML namespace () can be used to control where in the
list the entry is inserted. These can be used during "create"
operations to insert a new list entry, or during "merge" or "replace"
operations to insert a new list entry or move an existing one.
The "insert" attribute can take the values "first", "last", "before",
and "after". If the value is "before" or "after", the "key" attribute
MUST also be used, to specify an existing element in the list. The
value of the "key" attribute is the key predicates of the full
instance identifier (see ) for the list entry.
If no "insert" attribute is present in the "create" operation, it
defaults to "last".
If several entries in an "ordered-by user" list are modified in
the same <edit‑config> request, the entries are modified one at the
time, in the order of the XML elements in the request.
In a <copy‑config>, or an <edit‑config> with a "replace" operation
that covers the entire list, the list entry order is the same as the
order of the XML elements in the request.
When a NETCONF server processes an <edit‑config> request, the
elements of procedure for a list node are:
If the operation is "merge" or "replace", the list entry is created
if it does not exist. If the list entry already exists and the
"insert" and "key" attributes are present, the list entry is moved
according to the values of the "insert" and "key" attributes. If
the list entry exists and the "insert" and "key" attributes are not
present, the list entry is not moved.
If the operation is "create", the list entry is created if it does
not exist. If the list entry already exists, a "data‑exists" error
is returned.
If the operation is "delete", the entry is deleted from the list if
it exists. If the list entry does not exist, a "data‑missing"
error is returned.
Given the following list:
A corresponding XML instance example:
fredadminFred Flintstone
]]>
To create a new user "barney":
barneyadminBarney Rubble
]]>
To change the type of "fred" to "superuser":
fredsuperuser
]]>
Given the following ordered-by user list:
The following would be used to insert a new user "barney rubble" after
the user "fred flintstone":
barneyrubbleadmin
]]>
The following would be used to move the user "barney rubble" before the user
"fred flintstone":
barneyrubble
]]>
The "choice" statement defines a set of alternatives, only one of
which may be present in any one data tree. The argument is an
identifier, followed by a block of substatements that holds detailed
choice information. The identifier is used to identify the choice
node in the schema tree. A choice node does not exist in the data
tree.
A choice consists of a number of branches, each defined with a "case"
substatement. Each branch contains a number of child nodes. The
nodes from at most one of the choice's branches exist at the same
time.
Since only one of the choice's cases can be valid at any time in the
data tree, the creation of a node from one case implicitly deletes all
nodes from all other cases. If a request creates a node from a case,
the server will delete any existing nodes that are defined in other
cases inside the choice.
substatementsectioncardinalityanydata0..nanyxml0..ncase0..nchoice0..nconfig0..1container0..ndefault0..1description0..1if-feature0..nleaf0..nleaf-list0..nlist0..nmandatory0..1reference0..1status0..1when0..1
The "case" statement is used to define branches of the choice. It
takes as an argument an identifier, followed by a block of
substatements that holds detailed case information.
The identifier is used to identify the case node in the schema
tree. A case node does not exist in the data tree.
Within a "case" statement, the "anydata", "anyxml", "choice", "container",
"leaf", "list", "leaf‑list", and "uses" statements can be used to
define child nodes to the case node. The identifiers of all these
child nodes MUST be unique within all cases in a choice. For example,
the following is illegal:
As a shorthand, the "case" statement can be omitted if the branch
contains a single "anydata", "anyxml", "choice", "container", "leaf",
"list", or "leaf‑list" statement. In this case, the case node still
exists in the schema tree, and its identifier is the same as the
identifier of the child node. Schema node identifiers
() MUST always explicitly include case node
identifiers. The following example:
is equivalent to:
The case identifier MUST be unique within a choice.
substatementsectioncardinalityanydata0..nanyxml0..nchoice0..ncontainer0..ndescription0..1if-feature0..nleaf0..nleaf-list0..nlist0..nreference0..1status0..1uses0..nwhen0..1
The "default" statement indicates if a case should be considered as
the default if no child nodes from any of the choice's cases exist.
The argument is the identifier of the default "case" statement. If
the "default" statement is missing, there is no default case.
The "default" statement MUST NOT be present on choices where
"mandatory" is "true".
The default case is only important when considering the default
statements of nodes under the cases (i.e., default values of leafs and
leaf-lists, and default cases of nested choices). The default values
and nested default cases under the default case are used if none of
the nodes under any of the cases are present.
There MUST NOT be any mandatory nodes () directly
under the default case.
Default values for child nodes under a case are only used if one
of the nodes under that case is present, or if that case is the default
case. If none of the nodes under a case are present and the case is
not the default case, the default values of the cases' child nodes are
ignored.
In this example, the choice defaults to "interval", and the default
value will be used if none of "daily", "time‑of‑day", or "manual" are
present. If "daily" is present, the default value for "time‑of‑day"
will be used.
The "mandatory" statement, which is optional, takes as an argument the
string "true" or "false", and puts a constraint on valid data. If
"mandatory" is "true", at least one node from exactly one of the
choice's case branches MUST exist.
If not specified, the default is "false".
The behavior of the constraint depends on the type of the choice's
closest ancestor node in the schema tree that is not a
non-presence container (see ):
If no such ancestor exists in the schema tree, the constraint is
enforced.
Otherwise, if this ancestor is a case node, the constraint is
enforced if any other node from the case exists.
Otherwise, it is enforced if the ancestor node exists.
The constraint is further enforced according to the rules in
.
The choice and case nodes are not visible in XML.
The child nodes of the selected "case" statement MUST be encoded in
the same order as they are defined in the "case" statement if they are
part of an RPC or action input or output parameter definition.
Otherwise, the subelements are encoded in any order.
Given the following choice:
A corresponding XML instance example:
]]>
To change the protocol from tcp to udp:
]]>
The "anydata" statement defines an interior node in the schema tree.
It takes one argument, which is an identifier, followed by a block of
substatements that holds detailed anydata information.
The "anydata" statement is used to represent an unknown set of nodes
that can be modelled with YANG, except anyxml, but for which the data
model is not known at module design time. It is possible, though not
required, for the data model for "anydata" content to become known
through protocol signalling or other means that are outside the scope
of this document.
An example of where anydata can be useful is a list of received
notifications, where the specific notifications are not known at design
time.
An anydata node cannot be augmented (see ).
An anydata node exists in zero or one instances in the data tree.
An implementation may or may not know the data model used to model a
specific instance of an anydata node.
Since the use of anydata limits the manipulation of the content,
the "anydata" statement SHOULD NOT be used to define
configuration data.
substatementsectioncardinalityconfig0..1description0..1if-feature0..nmandatory0..1must0..nreference0..1status0..1when0..1
An anydata node is encoded as an XML element. The element's local name
is the anydata's identifier, and its namespace is the module's XML
namespace (see ). The value of the anydata node is a set
of nodes, which are encoded as XML subelements to the
anydata element.
An anydata node is treated as an opaque chunk of data. This data can
be modified in its entirety only.
Any "operation" attributes present on subelements of an anydata node
are ignored by the NETCONF server.
When a NETCONF server processes an <edit‑config> request, the
elements of procedure for the anydata node are:
If the operation is "merge" or "replace", the node is created if it
does not exist, and its value is set to the subelements of the
anydata node found in the XML RPC data.
If the operation is "create", the node is created if it does not
exist, and its value is set to the subelements of the anydata node
found in the XML RPC data. If the node already exists, a
"data‑exists" error is returned.
If the operation is "delete", the node is deleted if it exists. If
the node does not exist, a "data‑missing" error is returned.
Given the following "anydata" statement:
The following is a valid encoding of such a list instance:
2014-07-29T13:43:01ZfaultEthernet0major
]]>
The "anyxml" statement defines an interior node in the schema tree.
It takes one argument, which is an identifier, followed by a block of
substatements that holds detailed anyxml information.
The "anyxml" statement is used to represent an unknown chunk of XML. No
restrictions are placed on the XML. This can be useful, for example,
in RPC replies. An example is the <filter> parameter in the
<get‑config> operation in NETCONF.
An anyxml node cannot be augmented (see ).
An anyxml node exists in zero or one instances in the data tree.
Since the use of anyxml limits the manipulation of the content,
the "anyxml" statement SHOULD NOT be used to define
configuration data.
It should be noted that in YANG version 1, anyxml was the only
statement that could model an unknown hierarchy of data. In many
cases this unknown hierarchy of data is actually modelled in YANG, but
the specific YANG data model is not known at design time. In these
situations, it is RECOMMENDED to use anydata () instead of
anyxml.
substatementsectioncardinalityconfig0..1description0..1if-feature0..nmandatory0..1must0..nreference0..1status0..1when0..1
An anyxml node is encoded as an XML element. The element's local name
is the anyxml's identifier, and its namespace is the module's XML
namespace (see ). The value of the anyxml node is encoded
as XML content of this element.
Note that any XML prefixes used in the encoding are local to each
instance encoding. This means that the same XML may be encoded
differently by different implementations.
An anyxml node is treated as an opaque chunk of data. This data can
be modified in its entirety only.
Any "operation" attributes present on subelements of an anyxml node
are ignored by the NETCONF server.
When a NETCONF server processes an <edit‑config> request, the
elements of procedure for the anyxml node are:
If the operation is "merge" or "replace", the node is created if it
does not exist, and its value is set to the XML content of the
anyxml node found in the XML RPC data.
If the operation is "create", the node is created if it does not
exist, and its value is set to the XML content of the anyxml node
found in the XML RPC data. If the node already exists, a
"data‑exists" error is returned.
If the operation is "delete", the node is deleted if it exists. If
the node does not exist, a "data‑missing" error is returned.
Given the following "anyxml" statement:
The following are two valid encodings of the same anyxml value:
This is very cool.
This is very cool.
]]>
The "grouping" statement is used to define a reusable block of nodes,
which may be used locally in the module or submodule, and by other
modules that import from it, according to the rules in
. It takes one argument, which is an identifier,
followed by a block of substatements that holds detailed grouping
information.
The "grouping" statement is not a data definition statement and, as such,
does not define any nodes in the schema tree.
A grouping is like a "structure" or a "record" in conventional
programming languages.
Once a grouping is defined, it can be referenced in a "uses"
statement (see ). A grouping MUST NOT reference itself, neither
directly nor indirectly through a chain of other groupings.
If the grouping is defined at the top level of a YANG module or
submodule, the grouping's identifier MUST be unique within the module.
A grouping is more than just a mechanism for textual substitution, but
defines a collection of nodes. Identifiers appearing inside the
grouping are resolved relative to the scope in which the grouping is
defined, not where it is used. Prefix mappings, type names, grouping
names, and extension usage are evaluated in the hierarchy where the
"grouping" statement appears. For extensions, this means that
extensions defined as direct children to a "grouping" statement are
applied to the grouping itself.
Note that if a grouping defines an "action" or a "notification" node
in its hierarchy, then it cannot be used in all contexts. For example,
it cannot be used in an rpc definition. See and
.
substatementsectioncardinalityaction0..nanydata0..nanyxml0..nchoice0..ncontainer0..ndescription0..1grouping0..nleaf0..nleaf-list0..nlist0..nnotification0..nreference0..1status0..1typedef0..nuses0..n
The "uses" statement is used to reference a "grouping" definition. It
takes one argument, which is the name of the grouping.
The effect of a "uses" reference to a grouping is that the nodes
defined by the grouping are copied into the current schema tree, and
then updated according to the "refine" and "augment" statements.
The identifiers defined in the grouping are not bound to a namespace
until the contents of the grouping are added to the schema tree via a
"uses" statement that does not appear inside a "grouping" statement,
at which point they are bound to the namespace of the current module.
substatementsectioncardinalityaugment0..ndescription0..1if-feature0..nrefine0..nreference0..1status0..1when0..1
Some of the properties of each node in the grouping can be refined
with the "refine" statement. The argument is a string that
identifies a node in the grouping. This node is called the refine's
target node. If a node in the grouping is not present as a target
node of a "refine" statement, it is not refined, and thus used exactly
as it was defined in the grouping.
The argument string is a descendant schema node identifier (see
).
The following refinements can be done:
A leaf or choice node may get a default value, or a new default
value if it already had one.
A leaf-list node may get a set of default values, or a new set of
default values if it already had defaults; i.e., the set of refined
default values replaces the defaults already given.
Any node may get a specialized "description" string.
Any node may get a specialized "reference" string.
Any node may get a different "config" statement.
A leaf, anydata, anyxml, or choice node may get a different
"mandatory" statement.
A container node may get a "presence" statement.
A leaf, leaf-list, list, container, anydata, or anyxml node may get
additional "must" expressions.
A leaf-list or list node may get a different "min‑elements" or
"max‑elements" statement.
A leaf, leaf-list, list, container, choice, case, anydata, or anyxml
node may get additional "if‑feature" expressions.
Any node can get refined extensions, if the extension allows
refinement. See for details.
Each node in the grouping is encoded as if it was defined inline,
even if it is imported from another module with another XML
namespace.
To use the "endpoint" grouping defined in in a
definition of an HTTP server in some other module, we can do:
A corresponding XML instance example:
extern-web192.0.2.180
]]>
If port 80 should be the default for the HTTP server, default
can be added:
If we want to define a list of servers, and each server has the ip and
port as keys, we can do:
The following is an error:
The "rpc" statement is used to define an RPC operation. It takes
one argument, which is an identifier, followed by a block of
substatements that holds detailed rpc information. This argument is
the name of the RPC.
The "rpc" statement defines an rpc node in the schema tree. Under the
rpc node, a schema node with the name "input", and a schema node with
the name "output" are also defined. The nodes "input" and "output" are
defined in the module's namespace.
substatementsectioncardinalitydescription0..1grouping0..nif-feature0..ninput0..1output0..1reference0..1status0..1typedef0..n
The "input" statement, which is optional, is used to define input
parameters to the operation. It does not take an argument. The
substatements to "input" define nodes under the operation's input node.
If a leaf in the input tree has a "mandatory" statement with the value
"true", the leaf MUST be present in an RPC invocation.
If a leaf in the input tree has a default value, the server
MUST use this value in the same cases as described in
. In these cases, the server MUST operationally
behave as if the leaf was present in the RPC invocation with
the default value as its value.
If a leaf-list in the input tree has one or more default values, the
server MUST use these values in the same cases as described in
. In these cases, the server MUST
operationally behave as if the leaf-list was present in the
RPC invocation with the default values as its values.
Since the input tree is not part of any datastore, all "config"
statements for nodes in the input tree are ignored.
If any node has a "when" statement that would evaluate to
"false", then this node MUST NOT be present in the input tree.
substatementsectioncardinalityanydata0..nanyxml0..nchoice0..ncontainer0..ngrouping0..nleaf0..nleaf-list0..nlist0..nmust0..ntypedef0..nuses0..n
The "output" statement, which is optional, is used to define output
parameters to the RPC operation. It does not take an argument. The
substatements to "output" define nodes under the operation's output
node.
If a leaf in the output tree has a "mandatory" statement with the
value "true", the leaf MUST be present in an RPC
reply.
If a leaf in the output tree has a default value, the client
MUST use this value in the same cases as described in
. In these cases, the client MUST operationally
behave as if the leaf was present in the RPC reply with
the default value as its value.
If a leaf-list in the output tree has one or more default values, the
client MUST use these values in the same cases as described in
. In these cases, the client MUST
operationally behave as if the leaf-list was present in the
RPC reply with the default values as its values.
Since the output tree is not part of any datastore, all "config"
statements for nodes in the output tree are ignored.
If any node has a "when" statement that would evaluate to
"false", then this node MUST NOT be present in the output tree.
substatementsectioncardinalityanydata0..nanyxml0..nchoice0..ncontainer0..ngrouping0..nleaf0..nleaf-list0..nlist0..nmust0..ntypedef0..nuses0..n
An rpc node is encoded as a child XML element to the <rpc> element, as
designated by the substitution group "rpcOperation" in . The
element's local name is the rpc's identifier, and its namespace is the
module's XML namespace (see ).
Input parameters are encoded as child XML elements to the rpc node's
XML element, in the same order as they are defined within the
"input" statement.
If the RPC operation invocation succeeded, and no output parameters are
returned, the <rpc‑reply> contains a single <ok/> element defined in
. If output parameters are returned, they are encoded as
child elements to the <rpc‑reply> element defined in , in the
same order as they are defined within the "output" statement.
The following example defines an RPC operation:
A corresponding XML instance example of the complete rpc and rpc-reply:
27606-0100
]]>
The "action" statement is used to define an operation connected to a
specific container or list data node. It takes one argument, which is
an identifier, followed by a block of substatements that holds
detailed action information. The argument is the name of the action.
The "action" statement defines an action node in the schema tree.
Under the action node, a schema node with the name "input", and a
schema node with the name "output" are also defined. The nodes
"input" and "output" are defined in the module's namespace.
An action MUST NOT be defined within an rpc, another action or a
notification, i.e., an action node MUST NOT have an rpc, action, or a
notification node as one of its ancestors in the schema tree. For
example, this means that it is an error if a grouping that contains an
action somewhere in its node hierarchy is used in a notification
definition.
An action MUST NOT have any ancestor node that is a list node without
a "key" statement.
Since an action cannot be defined at the top-level of a module or in a
case statement, it is an error if a grouping that contains an action
at the top of its node hierarchy is used at the top-level of a module
or in a case definition.
The difference between an action and an rpc is that an action is tied
to a node in the datastore, whereas an rpc is not. When an action is
invoked, the node in the datastore is specified along with the name of
the action and the input parameters.
substatementsectioncardinalitydescription0..1grouping0..nif-feature0..ninput0..1output0..1reference0..1status0..1typedef0..n
When an action is invoked, an element with the local name "action" in
the namespace "urn:ietf:params:xml:ns:yang:1" (see )
is encoded as a child XML element to the <rpc> element defined in
, as designated by the substitution group "rpcOperation" in
.
The "action" element contains an hierarchy of nodes that identifies
the node in the datastore. It MUST contain all containers and list
nodes in the direct path from the top level down to the list or
container containing the action. For lists, all key leafs MUST also
be included. The innermost container or list contains an XML element that
carries the name of the defined action. Within this element the input
parameters are encoded as child XML elements, in the same order as
they are defined within the "input" statement.
Only one action can be invoked in one <rpc>. If more than one action
is present in the <rpc>, the server MUST reply with an "bad‑element"
error-tag in the <rpc‑error>.
If the action operation invocation succeeded, and no output parameters are
returned, the <rpc‑reply> contains a single <ok/> element defined in
. If output parameters are returned, they are encoded as
child elements to the <rpc‑reply> element defined in , in the
same order as they are defined within the "output" statement.
The following example defines an action to reset one server at a
server farm:
A corresponding XML instance example of the complete rpc and rpc-reply:
apache-12014-07-29T13:42:00Z
2014-07-29T13:42:12Z
]]>
The "notification" statement is used to define a notification.
It takes one argument, which is an identifier, followed by a block of
substatements that holds detailed notification information. The
"notification" statement defines a notification node in the schema
tree.
A notification can be defined at the top-level of a module, or
connected to a specific container or list data node in the schema
tree.
A notification MUST NOT be defined within an rpc, action or another
notification, i.e., a notification node MUST NOT have an rpc, action,
or a notification node as one of its ancestors in the schema tree.
For example, this means that it is an error if a grouping that
contains an notification somewhere in its node hierarchy is used in an
rpc definition.
A notification MUST NOT have any ancestor node that is a list node
without a "key" statement.
Since a notification cannot be defined in a case statement, it is an
error if a grouping that contains a notification at the top of its
node hierarchy is used in a case definition.
If a leaf in the notification tree has a "mandatory" statement with
the value "true", the leaf MUST be present in a notification instance.
If a leaf in the notification tree has a default value, the client
MUST use this value in the same cases as described in
. In these cases, the client MUST operationally
behave as if the leaf was present in the notification instance with
the default value as its value.
If a leaf-list in the notification tree has one or more default
values, the client MUST use these values in the same cases as
described in . In these cases, the client
MUST operationally behave as if the leaf-list was present in the
notification instance with the default values as its values.
Since the notification tree is not part of any datastore, all "config"
statements for nodes in the notification tree are ignored.
substatementsectioncardinalityanydata0..nanyxml0..nchoice0..ncontainer0..ndescription0..1grouping0..nif-feature0..nleaf0..nleaf-list0..nlist0..nmust0..nreference0..1status0..1typedef0..nuses0..n
A notification node that is defined on the top-level of a module is
encoded as a child XML element to the <notification> element defined
in NETCONF Event Notifications . The element's local name is
the notification's identifier, and its namespace is the module's XML
namespace (see ).
When a notification node is defined as a child to a data node, the
<notification> element defined in NETCONF Event Notifications
contains an hierarchy of nodes that identifies the node in
the datastore. It MUST contain all containers and list nodes from the
top level down to the list or container containing the notification.
For lists, all key leafs MUST also be included. The innermost
container or list contains an XML element that carries the name of the
defined notification.
The notification's child nodes are encoded as subelements to the
notification node's XML element, in any order.
The following example defines a notification at the top-level of a
module:
A corresponding XML instance example of the complete notification:
2008-07-08T00:01:00Zfault
/ex:interface[ex:name='Ethernet0']
major
]]>
The following example defines a notification in a data node:
A corresponding XML instance example of the complete notification:
2008-07-08T00:01:00Zeth1fred
]]>
The "augment" statement allows a module or submodule to add to a
schema tree defined in an external module, or in the current module and
its submodules, and to add to the nodes from a grouping in a "uses"
statement. The argument is a string that identifies a node in the
schema tree. This node is called the augment's target node. The
target node MUST be either a container, list, choice, case, input,
output, or notification node. It is augmented with the nodes defined
in the substatements that follow the "augment" statement.
The argument string is a schema node identifier (see
). If the "augment" statement is on the top level in
a module or submodule, the absolute form (defined by the rule
"absolute‑schema‑nodeid" in ) of a schema node identifier
MUST be used. If the "augment" statement is a substatement to the
"uses" statement, the descendant form (defined by the rule
"descendant‑schema‑nodeid" in ) MUST be used.
If the target node is a container, list, case, input, output, or
notification node, the "container", "leaf", "list", "leaf‑list",
"uses", and "choice" statements can be used within the "augment"
statement.
If the target node is a container or list node, the "action" and
"notification" statements can be used within the "augment"
statement.
If the target node is a choice node, the "case" statement, or a case
shorthand statement (see ) can be used within the "augment"
statement.
The "augment" statement MUST NOT add multiple nodes with the same name
from the same module to the target node.
If the augmentation adds mandatory nodes (see ) that
represent configuration to a target node in another module, the
augmentation MUST be conditional with a "when" statement. Care must
be taken when defining the "when" expression, so that clients that do
not know about the augmenting module do not break.
In the following example, it is OK to augment the "interface" entry
with "mandatory‑leaf" because the augmentation depends on support for
"some‑new‑iftype". The old client does not know about this type so it
would never select this type, and therefore not be adding a mandatory
data node.
substatementsectioncardinalityaction0..nanydata0..nanyxml0..ncase0..nchoice0..ncontainer0..ndescription0..1if-feature0..nleaf0..nleaf-list0..nlist0..nnotification0..nreference0..1status0..1uses0..nwhen0..1
All data nodes defined in the "augment" statement are defined as XML
elements in the XML namespace of the module where the "augment" is
specified.
When a node is augmented, the augmenting child nodes are encoded as
subelements to the augmented node, in any order.
In namespace urn:example:interface-module, we have:
Then, in namespace urn:example:ds0, we have:
A corresponding XML instance example:
1Flintstone Inc Ethernet A562ethernetCsmacd15002Flintstone Inc DS0ds01
]]>
As another example, suppose we have the choice defined in
. The following construct can be used to extend the
protocol definition:
A corresponding XML instance example:
]]>
or
]]>
The "identity" statement is used to define a new globally unique,
abstract, and untyped identity. The identity's only purpose is to
denote its name, semantics, and existence. An identity can either be
defined from scratch or derived from one or more base identities. The
identity's argument is an identifier that is the name of the identity.
It is followed by a block of substatements that holds detailed
identity information.
The built-in datatype "identityref" (see ) can be used to
reference identities within a data model.
substatementsectioncardinalitybase0..ndescription0..1if-feature0..nreference0..1status0..1
The "base" statement, which is optional, takes as an argument a string
that is the name of an existing identity, from which the new identity
is derived. If no "base" statement is present, the identity is defined
from scratch. If multiple "base" statements are present, the
identity is derived from all of them.
If a prefix is present on the base name, it refers to an identity
defined in the module that was imported with that prefix, or the local
module if the prefix matches the local module's prefix. Otherwise, an
identity with the matching name MUST be defined in the current module
or an included submodule.
An identity MUST NOT reference itself, neither directly nor indirectly
through a chain of other identities.
The derivation of identities has the following properties:
It is irreflexive, which means that an identity is not derived from
itself.
It is transitive, which means that if identity B is derived from A
and C is derived from B, then C is also derived from A.
The "extension" statement allows the definition of new statements
within the YANG language. This new statement definition can be
imported and used by other modules.
The "extension" statement's argument is an identifier that is the new
keyword for the extension and must be followed by a block of
substatements that holds detailed extension information. The purpose
of the "extension" statement is to define a keyword, so that it can be
imported and used by other modules.
The extension can be used like a normal YANG statement, with the
statement name followed by an argument if one is defined by the
"extension" statement, and an optional block of substatements. The
statement's name is created by combining the prefix of the module in
which the extension was defined, a colon (":"), and the extension's
keyword, with no interleaving whitespace. The substatements of an
extension are defined by the "extension" statement, using some
mechanism outside the scope of this specification. Syntactically, the
substatements MUST be YANG statements, or also extensions defined
using "extension" statements. YANG statements in extensions MUST
follow the syntactical rules in .
An extension can allow refinement (see ) and deviations
(), but the mechanism for how this is defined is outside the
scope of this specification.
substatementsectioncardinalityargument0..1description0..1reference0..1status0..1
The "argument" statement, which is optional, takes as an argument a
string that is the name of the argument to the keyword. If no
argument statement is present, the keyword expects no argument when it
is used.
The argument's name is used in the YIN mapping, where it is used as an
XML attribute or element name, depending on the argument's "yin‑element"
statement.
substatementsectioncardinalityyin-element0..1
The "yin‑element" statement, which is optional, takes as an argument
the string "true" or "false". This statement indicates if the
argument is mapped to an XML element in YIN or to an XML
attribute (see ).
If no "yin‑element" statement is present, it defaults to "false".
To define an extension:
To use the extension:
This section defines statements related to conformance, as described
in .
The "feature" statement is used to define a mechanism by which
portions of the schema are marked as conditional. A feature name is
defined that can later be referenced using the "if‑feature" statement
(see ). Schema nodes tagged with an "if‑feature"
statement are ignored by the server unless the server supports the
given feature expression. This allows portions of the YANG module to
be conditional based on conditions in the server. The model can
represent the abilities of the server within the model, giving a
richer model that allows for differing server abilities and roles.
The argument to the "feature" statement is the name of the new
feature, and follows the rules for identifiers in . This
name is used by the "if‑feature" statement to tie the schema nodes to
the feature.
In this example, a feature called "local‑storage" represents the
ability for a server to store syslog messages on local storage of some
sort. This feature is used to make the "local‑storage‑limit" leaf
conditional on the presence of some sort of local storage. If the
server does not report that it supports this feature, the
"local‑storage‑limit" node is not supported.
The "if‑feature" statement can be used in many places within the YANG
syntax. Definitions tagged with "if‑feature" are ignored when the
server does not support that feature.
A feature MUST NOT reference itself, neither directly nor indirectly
through a chain of other features.
In order for a server to support a feature that is dependent on any
other features (i.e., the feature has one or more "if‑feature"
substatements), the server MUST also support all the dependant
features.
substatementsectioncardinalitydescription0..1if-feature0..nstatus0..1reference0..1
The "if‑feature" statement makes its parent statement conditional.
The argument is a boolean expression over feature names. In this
expression, a feature name evaluates to "true" if and only if the
feature is supported by the server. The parent statement is
implemented by servers where the boolean expression evaluates to
"true".
The if-feature boolean expression syntax is formally defined by the
rule "if‑feature‑expr" in . Parenthesis are used to group
expressions. When the expression is
evaluated, the order of precedence is (highest precedence
first): grouping (parenthesis), "not", "and", "or".
If a prefix is present on a feature name in the boolean expression,
the prefixed name refers to a feature defined in the module that was
imported with that prefix, or the local module if the prefix matches
the local module's prefix. Otherwise, a feature with the matching
name MUST be defined in the current module or an included submodule.
A leaf that is a list key MUST NOT have any "if‑feature" statements.
In this example, the container "target" is implemented if either of the
features "outbound‑tls" or "outbound‑ssh" are supported by the
server.
The following examples are equivalent:
The "deviation" statement defines a hierarchy of a module that the
server does not implement faithfully. The argument is a string that
identifies the node in the schema tree where a deviation from the
module occurs. This node is called the deviation's target node. The
contents of the "deviation" statement give details about the deviation.
The argument string is an absolute schema node identifier (see
).
Deviations define the way a server or class of servers deviate from
a standard. This means that deviations MUST never be part of a
published standard, since they are the mechanism for learning how
implementations vary from the standards.
Server deviations are strongly discouraged and MUST only be used as a
last resort. Telling the application how a server fails to follow a
standard is no substitute for implementing the standard correctly. A
server that deviates from a module is not fully compliant with the
module.
However, in some cases, a particular device may not have the hardware
or software ability to support parts of a standard module. When this
occurs, the server makes a choice either to treat attempts to
configure unsupported parts of the module as an error that is
reported back to the unsuspecting application or ignore those incoming
requests. Neither choice is acceptable.
Instead, YANG allows servers to document portions of a base module
that are not supported or supported but with different syntax, by
using the "deviation" statement.
After applying all deviations announced by a server, in any order, the
resulting data model MUST still be valid.
substatementsectioncardinalitydescription0..1deviate1..nreference0..1
The "deviate" statement defines how the server's implementation of the
target node deviates from its original definition. The argument is
one of the strings "not‑supported", "add", "replace", or "delete".
The argument "not‑supported" indicates that the target node is not
implemented by this server.
The argument "add" adds properties to the target node. The properties
to add are identified by substatements to the "deviate" statement.
If a property can only appear once, the property MUST NOT exist in
the target node.
The argument "replace" replaces properties of the target node. The
properties to replace are identified by substatements to the "deviate"
statement. The properties to replace MUST exist in the target node.
The argument "delete" deletes properties from the target node. The
properties to delete are identified by substatements to the "delete"
statement. The substatement's keyword MUST match a corresponding
keyword in the target node, and the argument's string MUST be equal to
the corresponding keyword's argument string in the target node.
substatementsectioncardinalityconfig0..1default0..nmandatory0..1max-elements0..1min-elements0..1must0..ntype0..1unique0..nunits0..1
If the target node has a property defined by an extension, this
property can be deviated if the extension allows deviations. See
for details.
In this example, the server is informing client applications that it
does not support the "daytime" service in the style of RFC 867.
A server would advertise both modules "example‑base" and "example‑deviations".
The following example sets a server-specific default value to a leaf
that does not have a default value defined:
In this example, the server limits the number of name servers to 3:
If the original definition is:
a server might remove this must constraint by doing:
This section defines substatements common to several other
statements.
The "config" statement takes as an argument the string "true" or
"false". If "config" is "true", the definition represents
configuration. Data nodes representing configuration are part of
configuration datastores.
If "config" is "false", the definition represents state data. Data
nodes representing state data are not part of configuration datastores.
If "config" is not specified, the default is the same as the parent
schema node's "config" value. If the parent node is a "case" node,
the value is the same as the "case" node's parent "choice" node.
If the top node does not specify a "config" statement, the default is
"true".
If a node has "config" set to "false", no node underneath it can have
"config" set to "true".
The "status" statement takes as an argument one of the strings "current",
"deprecated", or "obsolete".
"current" means that the definition is current and valid.
"deprecated" indicates an obsolete definition, but it permits
new/continued implementation in order to foster
interoperability with older/existing implementations.
"obsolete" means the definition is obsolete and SHOULD NOT be
implemented and/or can be removed from implementations.
If no status is specified, the default is "current".
If a definition is "current", it MUST NOT reference a "deprecated" or
"obsolete" definition within the same module.
If a definition is "deprecated", it MUST NOT reference an "obsolete"
definition within the same module.
For example, the following is illegal:
The "description" statement takes as an argument a string that
contains a human-readable textual description of this
definition. The text is provided in a language (or languages) chosen
by the module developer; for the sake of interoperability, it is
RECOMMENDED to choose a language that is widely understood among the
community of network administrators who will use the module.
The "reference" statement takes as an argument a string that is a
human-readable cross-reference to an external document, either another
module that defines related management information, or a document that
provides additional information relevant to this definition.
For example, a typedef for a "uri" data type could look like:
The "when" statement makes its parent data definition statement
conditional. The node defined by the parent data definition statement
is only valid when the condition specified by the "when" statement is
satisfied. The statement's argument is an XPath expression (see
), which is used to formally specify this condition. If the
XPath expression conceptually evaluates to "true" for a particular
instance, then the node defined by the parent data definition
statement is valid; otherwise, it is not.
A leaf that is a list key MUST NOT have a "when" statement.
If a leaf key is defined in a grouping that is used in a list, the
"uses" statement MUST NOT have a "when" statement.
See for additional information.
The XPath expression is conceptually evaluated in the following
context, in addition to the definition in :
If the "when" statement is a child of an "augment" statement, then
the context node is the augment's target node in the data tree, if
the target node is a data node. Otherwise, the context node is the
closest ancestor node to the target node that is also a data
node. If no such node exists, the context node is the root node.
The accessible tree is tentatively altered during the
processing of the XPath expression by removing all instances (if
any) of the nodes added by the "augment" statement.
If the "when" statement is a child of a "uses", "choice", or "case"
statement, then the context node is the closest ancestor node to the
"uses", "choice", or "case" node that is also a data node. If no
such node exists, the context node is the root node.
The accessible tree is tentatively altered during the
processing of the XPath expression by removing all instances (if
any) of the nodes added by the "uses", "choice", or "case"
statement.
If the "when" statement is a child of any other data definition
statement, the accessible tree is tentatively altered during the
processing of the XPath expression by replacing all instances of the
data node for which the "when" statement is defined with a single
dummy node with the same name, but with no value and no children.
If no such instance exists, the dummy node is tentatively created.
The context node is this dummy node.
The result of the XPath expression is converted to a boolean value
using the standard XPath rules.
If the XPath expression references any node that also has associated
"when" statements, those "when" expressions MUST be evaluated first.
There MUST NOT be any circular dependencies among "when"
expressions.
Note that the XPath expression is conceptually evaluated. This means
that an implementation does not have to use an XPath evaluator in the
server. The "when" statement can very well be implemented with
specially written code.
Several YANG statements define constraints on valid data. These
constraints are enforced in different ways, depending on what type of
data the statement defines.
If the constraint is defined on configuration data, it MUST be true in
a valid configuration data tree.
If the constraint is defined on state data, it MUST be true in a
valid state data tree.
If the constraint is defined on notification content, it MUST be true
in any notification data tree.
If the constraint is defined on RPC or action input parameters, it
MUST be true in an invocation of the RPC or action operation.
If the constraint is defined on RPC or action output parameters, it
MUST be true in the RPC or action reply.
The following properties are true in all data trees:
All leaf data values MUST match the type constraints for the leaf,
including those defined in the type's "range", "length", and
"pattern" properties.
All key leafs MUST be present for all list entries.
Nodes MUST be present for at most one case branch in all choices.
There MUST be no nodes tagged with "if‑feature" present if the
"if‑feature" expression evaluates to "false" in the server.
There MUST be no nodes tagged with "when" present if the "when"
condition evaluates to "false" in the data tree.
The following properties are true in a valid data tree:
All "must" constraints MUST evaluate to "true".
All referential integrity constraints defined via the "path"
statement MUST be satisfied.
All "unique" constraints on lists MUST be satisfied.
The "mandatory" constraint is enforced for leafs and choices, unless
the node or any of its ancestors has a "when" condition or "if‑feature"
expression that evaluates to "false".
The "min‑elements" and "max‑elements" constraints are enforced for
lists and leaf-lists, unless the node or any of its ancestors has a
"when" condition or "if‑feature" expression that evaluates to
"false".
The running configuration datastore MUST always be valid.
If a request creates configuration data nodes under a "choice", any
existing nodes from other "case" branches in the data tree are
deleted by the server.
If a request modifies a configuration data node such that any node's
"when" expression becomes false, then the node in the data tree with
the "when" expression is deleted by the server.
For configuration data, there are three windows when constraints MUST
be enforced:
during parsing of RPC payloads
during processing of the <edit‑config> operation
during validation
Each of these scenarios is considered in the following sections.
When content arrives in RPC payloads, it MUST be well-formed XML,
following the hierarchy and content rules defined by the set of models
the server implements.
If a leaf data value does not match the type constraints for the
leaf, including those defined in the type's "range", "length", and
"pattern" properties, the server MUST reply with an "invalid‑value"
error-tag in the rpc-error, and with the error-app-tag and
error-message associated with the constraint, if any exist.
If all keys of a list entry are not present, the server MUST reply
with a "missing‑element" error-tag in the rpc-error.
If data for more than one case branch of a choice is present, the
server MUST reply with a "bad‑element" in the rpc-error.
If data for a node tagged with "if‑feature" is present, and the
if-feature expression evaluates to "false" in the server, the server
MUST reply with an "unknown‑element" error-tag in the rpc-error.
If data for a node tagged with "when" is present, and the "when"
condition evaluates to "false", the server MUST reply with an
"unknown‑element" error-tag in the rpc-error.
For insert handling, if the value for the attributes "before" and
"after" are not valid for the type of the appropriate key leafs, the
server MUST reply with a "bad‑attribute" error-tag in the rpc-error.
If the attributes "before" and "after" appears in any element that
is not a list whose "ordered‑by" property is "user", the server
MUST reply with an "unknown‑attribute" error-tag in the rpc-error.
After the incoming data is parsed, the NETCONF server performs the
<edit‑config> operation by applying the data to the configuration
datastore. During this processing, the following errors MUST be
detected:
Delete requests for non-existent data.
Create requests for existent data.
Insert requests with "before" or "after" parameters that do not
exist.
Modification requests for nodes tagged with "when", and the "when"
condition evaluates to "false". In this case the server MUST reply
with an "unknown‑element" error-tag in the rpc-error.
When datastore processing is complete, the final contents MUST obey
all validation constraints. This validation processing is performed
at differing times according to the datastore. If the datastore is
"running" or "startup", these constraints MUST be enforced at the
end of the <edit‑config> or <copy‑config> operation. If the datastore
is "candidate", the constraint enforcement is delayed until a <commit>
or <validate> operation.
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 information model.
Additional types may be defined, derived from those built-in types or
from other derived types. Derived types may use subtyping to formally
restrict the set of possible values.
The different built-in types and their derived types allow different kinds
of subtyping, namely length and regular expression restrictions of
strings (, ) and range restrictions of numeric types
().
The lexical representation of a value of a certain type is used
in the XML encoding and when specifying default values
and numerical ranges in YANG modules.
For most types, there is a single canonical representation of the
type's values. Some types allow multiple lexical representations of
the same value, for example, the positive integer "17" can be
represented as "+17" or "17". Implementations MUST support all
lexical representations specified in this document.
When a server sends XML encoded data, it MUST use the canonical
form defined in this section. Other encodings may introduce alternate
representations. Note, however, that values in the data tree are
conceptually stored in the canonical representation as defined in this
section. In particular, any XPath expression evaluations are done
using the canonical form, if the data type has a canonical form. If
the data type does not have a canonical form, the format of the value
MUST match the data type's lexical representation, but the exact
format is implementation dependent.
Some types have a lexical representation that depends on the encoding,
e.g., the XML context in which they occur. These types do not have a
canonical form.
The integer built-in types are int8, int16, int32, int64, uint8, uint16,
uint32, and uint64. They represent signed and unsigned integers of
different sizes:
represents integer values between -128 and 127, inclusively.
represents integer values between -32768 and 32767, inclusively.
represents integer values between -2147483648 and 2147483647, inclusively.
represents integer values between -9223372036854775808 and
9223372036854775807, inclusively.
represents integer values between 0 and 255, inclusively.
represents integer values between 0 and 65535, inclusively.
represents integer values between 0 and 4294967295, inclusively.
represents integer values between 0 and 18446744073709551615, inclusively.
An integer value is lexically represented as an optional sign
("+" or "‑"), followed by a sequence of decimal digits. If no sign is
specified, "+" is assumed.
For convenience, when specifying a default value for an integer in a
YANG module, an alternative lexical representation can be used,
which represents the value in a hexadecimal or octal notation. The
hexadecimal notation consists of an optional sign ("+" or "‑"), the
characters "0x" followed a number of hexadecimal digits, where letters
may be uppercase or lowercase. The octal notation consists of an
optional sign ("+" or "‑"), the character "0" followed a number of
octal digits.
Note that if a default value in a YANG module has a leading zero
("0"), it is interpreted as an octal number. In the XML encoding, an
integer is always interpreted as a decimal number, and leading zeros
are allowed.
Examples:
The canonical form of a positive integer does not include the sign
"+". Leading zeros are prohibited. The value zero is represented as
"0".
All integer types can be restricted with the "range" statement ().
The "range" statement, which is an optional substatement to the "type"
statement, takes as an argument a range expression string. It is used
to restrict integer and decimal built-in types, or types
derived from those.
A range consists of an explicit value, or a lower-inclusive bound, two
consecutive dots "..", and an upper-inclusive bound. Multiple values
or ranges can be given, separated by "|". If multiple values or
ranges are given, they all MUST be disjoint and MUST be in ascending
order. If a range restriction is applied to an already range-restricted
type, the new restriction MUST be equal or more limiting, that is
raising the lower bounds, reducing the upper bounds, removing explicit
values or ranges, or splitting ranges into multiple ranges with
intermediate gaps. Each explicit value and range boundary value given
in the range expression MUST match the type being restricted, or be
one of the special values "min" or "max". "min" and "max" mean the
minimum and maximum value accepted for the type being restricted,
respectively.
The range expression syntax is formally defined by the rule
"range‑arg" in .
substatementsectioncardinalitydescription0..1error-app-tag0..1error-message0..1reference0..1
The decimal64 type represents a subset of the real numbers, which can
be represented by decimal numerals. The value space of decimal64 is
the set of numbers that can be obtained by multiplying a 64-bit signed
integer by a negative power of ten, i.e., expressible as
"i x 10^-n" where i is an integer64 and n is an integer
between 1 and 18, inclusively.
A decimal64 value is lexically represented as an optional sign
("+" or "‑"), followed by a sequence of decimal digits, optionally
followed by a period ('.') as a decimal indicator and a sequence of
decimal digits. If no sign is specified, "+" is assumed.
The canonical form of a positive decimal64 does not include the sign
"+". The decimal point is required. Leading and trailing zeros are
prohibited, subject to the rule that there MUST be at least one digit
before and after the decimal point. The value zero is represented as
"0.0".
A decimal64 type can be restricted with the "range" statement
().
The "fraction‑digits" statement, which is a substatement to the
"type" statement, MUST be present if the type is "decimal64". It
takes as an argument an integer between 1 and 18, inclusively. It
controls the size of the minimum difference between values of a
decimal64 type, by restricting the value space to numbers that are
expressible as "i x 10^-n" where n is the fraction-digits
argument.
The following table lists the minimum and maximum value for each
fraction-digit value:
fraction-digitminmax1-922337203685477580.8922337203685477580.72-92233720368547758.0892233720368547758.073-9223372036854775.8089223372036854775.8074-922337203685477.5808922337203685477.58075-92233720368547.7580892233720368547.758076-9223372036854.7758089223372036854.7758077-922337203685.4775808922337203685.47758078-92233720368.5477580892233720368.547758079-9223372036.8547758089223372036.85477580710-922337203.6854775808922337203.685477580711-92233720.3685477580892233720.3685477580712-9223372.0368547758089223372.03685477580713-922337.2036854775808922337.203685477580714-92233.7203685477580892233.7203685477580715-9223.3720368547758089223.37203685477580716-922.3372036854775808922.337203685477580717-92.2337203685477580892.2337203685477580718-9.2233720368547758089.223372036854775807
The string built-in type represents human-readable strings in YANG.
Legal characters are the Unicode and ISO/IEC 10646
characters, including tab, carriage return, and line feed
but excluding the other C0 control characters, the surrogate blocks,
and the noncharacters. The string syntax is formally defined by
the rule "yang‑string" in .
A string value is lexically represented as character data in
the XML encoding.
The canonical form is the same as the lexical representation.
No Unicode normalization is performed of string values.
A string can be restricted with the "length" () and "pattern"
() statements.
The "length" statement, which is an optional substatement to the
"type" statement, takes as an argument a length expression string. It
is used to restrict the built-in types "string" and "binary" or types
derived from them.
A "length" statement restricts the number of Unicode characters in the
string.
A length range consists of an explicit value, or a lower bound, two
consecutive dots "..", and an upper bound. Multiple values or ranges
can be given, separated by "|". Length-restricting values MUST NOT be
negative. If multiple values or ranges are given, they all MUST be
disjoint and MUST be in ascending order. If a length restriction is
applied to an already length-restricted type, the new restriction MUST
be equal or more limiting, that is, raising the lower bounds, reducing
the upper bounds, removing explicit length values or ranges, or
splitting ranges into multiple ranges with intermediate gaps. A
length value is a non-negative integer, or one of the special values
"min" or "max". "min" and "max" mean the minimum and maximum length
accepted for the type being restricted, respectively. An
implementation is not required to support a length value larger than
18446744073709551615.
The length expression syntax is formally defined by the rule
"length‑arg" in .
substatementsectioncardinalitydescription0..1error-app-tag0..1error-message0..1reference0..1
The "pattern" statement, which is an optional substatement to the
"type" statement, takes as an argument a regular expression string, as
defined in . It is used to restrict the built-in type
"string", or types derived from "string", to values that match the
pattern.
If the type has multiple "pattern" statements, the expressions are
ANDed together, i.e., all such expressions have to match.
If a pattern restriction is applied to an already pattern-restricted
type, values must match all patterns in the base type, in addition to
the new patterns.
substatementsectioncardinalitydescription0..1error-app-tag0..1error-message0..1modifier0..1reference0..1
The "modifier" statement, which is an optional substatement to the
"pattern" statement, takes as an argument the string "invert‑match".
If a pattern has the "invert‑match" modifier present, the type is
restricted to values that do not match the pattern.
With the following typedef:
the following refinement is legal:
and the following refinement is illegal:
With the following type:
the following strings match:
and the following strings do not match:
With the following type:
the following string match:
and the following strings do not match:
The boolean built-in type represents a boolean value.
The lexical representation of a boolean value is a string with a value
of "true" or "false". These values MUST be in lowercase.
The canonical form is the same as the lexical representation.
A boolean cannot be restricted.
The enumeration built-in type represents values from a set of assigned
names.
The lexical representation of an enumeration value is the
assigned name string.
The canonical form is the assigned name string.
An enumeration can be restricted with one or more "enum" ()
statements, which enumerate a subset of the values for the base type.
The "enum" statement, which is a substatement to the "type" statement,
MUST be present if the type is "enumeration". It is repeatedly used
to specify each assigned name of an enumeration type. It takes as an
argument a string which is the assigned name. The string MUST NOT be
zero-length and MUST NOT have any leading or trailing whitespace characters
(any Unicode character with the "White_Space" property). The use of
Unicode control codes SHOULD be avoided.
The statement is optionally followed by a block of substatements that
holds detailed enum information.
All assigned names in an enumeration MUST be unique.
When an existing enumeration type is restricted, the set of assigned
names in the new type MUST be a subset of the base type's set of
assigned names. The value of such an assigned name MUST NOT be
changed.
substatementsectioncardinalitydescription0..1if-feature0..nreference0..1status0..1value0..1
The "value" statement, which is optional, is used to associate an
integer value with the assigned name for the enum. This integer value
MUST be in the range -2147483648 to 2147483647, and it MUST be unique
within the enumeration type.
If a value is not specified, then one will be automatically assigned.
If the "enum" substatement is the first one defined, the assigned
value is zero (0); otherwise, the assigned value is one greater than
the current highest enum value (i.e., the highest enum value,
implicit or explicit, prior to the current "enum" substatement in the
parent "type" statement).
Note that the the presence of an "if‑feature" statement in an "enum"
statement does not affect the automatically assigned value.
If the current highest value is equal to 2147483647,
then an enum value MUST be specified for "enum" substatements
following the one with the current highest value.
When an existing enumeration type is restricted, the "value" statement
MUST either have the same value as in the base type or not be
present, in which case the value is the same as in the base type.
The lexical representation of the leaf "myenum" with value
"seven" is:
seven
]]>
With the following typedef:
the following refinement is legal:
and the following refinement is illegal:
The following example shows how an "enum" can be tagged with
"if‑feature", making the value legal only on servers that advertise
the corresponding feature:
The bits built-in type represents a bit set. That is, a bits value is
a set of flags identified by small integer position numbers starting
at 0. Each bit number has an assigned name.
When an existing bits type is restricted, the set of assigned
names in the new type MUST be a subset of the base type's set of
assigned names. The bit position of such an assigned name MUST NOT be
changed.
A bits type can be restricted with the "bit" () statement.
The lexical representation of the bits type is a space-separated list
of the names of the bits that are set. A zero-length string thus
represents a value where no bits are set.
In the canonical form, the bit values are separated by a single space
character and they appear ordered by their position (see ).
The "bit" statement, which is a substatement to the "type" statement,
MUST be present if the type is "bits". It is repeatedly used to
specify each assigned named bit of a bits type. It takes as an
argument a string that is the assigned name of the bit. It is
followed by a block of substatements that holds detailed bit
information. The assigned name follows the same syntax rules as an
identifier (see ).
All assigned names in a bits type MUST be unique.
substatementsectioncardinalitydescription0..1if-feature0..nreference0..1status0..1position0..1
The "position" statement, which is optional, takes as an argument
a non-negative integer value that specifies the bit's position within
a hypothetical bit field. The position value MUST be
in the range 0 to 4294967295, and it MUST be unique within
the bits type.
If a bit position is not specified, then one will be automatically
assigned. If the "bit" substatement is the first one defined, the
assigned value is zero (0); otherwise, the assigned value is one
greater than the current highest bit position (i.e., the highest bit
position, implicit or explicit, prior to the current "bit"
substatement in the parent "type" statement).
Note that the the presence of an "if‑feature" statement in an "bit"
statement does not affect the automatically assigned position.
If the current highest bit position value is equal to 4294967295,
then a position value MUST be specified for "bit" substatements
following the one with the current highest position value.
When an existing bits type is restricted, the "position" statement
MUST either have the same value as in the base type or not be
present, in which case the value is the same as in the base type.
Given the following typedef and leaf:
The lexical representation of this leaf
with bit values disable-nagle and ten-mb-only set would be:
disable-nagle ten-mb-only
]]>
The following example shows a legal refinement of this type:
and the following refinement is illegal:
The binary built-in type represents any binary data, i.e., a sequence
of octets.
A binary type can be restricted with the "length" ()
statement. The length of a binary value is the number of octets it
contains.
Binary values are encoded with the base64 encoding scheme (see
, Section 4).
The canonical form of a binary value follows the rules of "Base 64
Encoding" in .
The leafref type is restricted to the value space of some leaf or
leaf-list node in the schema tree and optionally further restricted by
corresponding instance nodes in the data tree. The "path"
substatement () is used to identify the referred leaf or
leaf-list node in the schema tree. The value space of the referring
node is the value space of the referred node.
If the "require‑instance" property () is "true",
there MUST exist an node in the data tree, or a node with a default
value in use (see and ),
of the referred schema tree leaf or leaf-list node with the same value
as the leafref value in a valid data tree.
If the referring node represents configuration data, and the
"require‑instance" property () is "true", the
referred node MUST also represent configuration.
There MUST NOT be any circular chains of leafrefs.
If the leaf that the leafref refers to is conditional based on one or
more features (see ), then the leaf with the leafref type MUST
also be conditional based on at least the same set of features.
A leafref can be restricted with the "require‑instance" statement
().
The "path" statement, which is a substatement to the "type" statement,
MUST be present if the type is "leafref". It takes as an argument a
string that MUST refer to a leaf or leaf-list node.
The syntax for a path argument is a subset of the XPath abbreviated
syntax. Predicates are used only for constraining the values for the
key nodes for list entries. Each predicate consists of exactly one
equality test per key, and multiple adjacent predicates MAY be present
if a list has multiple keys. The syntax is formally defined by the
rule "path‑arg" in .
The predicates are only used when more than one key reference is
needed to uniquely identify a leaf instance. This occurs if a list
has multiple keys, or a reference to a leaf other than the key in a
list is needed. In these cases, multiple leafrefs are typically
specified, and predicates are used to tie them together.
The "path" expression evaluates to a node set consisting of zero, one,
or more nodes. If the leaf with the leafref type represents
configuration data, this node set MUST be non-empty.
The "path" XPath expression is conceptually evaluated in the following
context, in addition to the definition in :
If the "path" statement is defined within a typedef, the context
node is the leaf or leaf-list node in the data tree that references
the typedef.
Otherwise, the context node is the node in the data tree for
which the "path" statement is defined.
The "require‑instance" statement, which is a substatement to the
"type" statement, MAY be present if the type is "instance‑identifier"
or "leafref". It takes as an argument the string "true" or "false".
If this statement is not present, it defaults to "true".
If "require‑instance" is "true", it means that the instance being
referred to MUST exist for the data to be valid. This constraint is
enforced according to the rules in .
If "require‑instance" is "false", it means that the instance being
referred to MAY exist in valid data.
A leafref value is lexically represented the same way as the leaf it
references represents its value.
The canonical form of a leafref is the same as the canonical form of
the leaf it references.
With the following list:
The following leafref refers to an existing interface:
An example of a corresponding XML snippet:
eth0loeth0
]]>
The following leafrefs refer to an existing address of an interface:
An example of a corresponding XML snippet:
eth0up192.0.2.1192.0.2.2loup127.0.0.1eth0
192.0.2.2
]]>
The following list uses a leafref for one of its keys. This is
similar to a foreign key in a relational database.
An example of a corresponding XML snippet:
eth0up192.0.2.1192.0.2.2eth01
...
eth02
...
]]>
The following notification defines two leafrefs to refer to an
existing admin-status:
An example of a corresponding XML notification:
2008-04-01T00:01:00Zeth0up
]]>
The identityref type is used to reference an existing identity (see
).
An identityref cannot be restricted.
The "base" statement, which is a substatement to the "type" statement,
MUST be present at least once if the type is "identityref". The
argument is the name of an identity, as defined by an "identity"
statement. If a prefix is present on the identity name, it refers to
an identity defined in the module that was imported with that prefix.
Otherwise, an identity with the matching name MUST be defined in the
current module or an included submodule.
Valid values for an identityref are any identities derived from all
the identityref's base identities. On a particular server, the valid
values are further restricted to the set of identities defined in the
modules implemented by the server.
An identityref is lexically represented as the referred identity's
qualified name as defined in . If the
prefix is not present, the namespace of the identityref is the default
namespace in effect on the element that contains the identityref
value.
When an identityref is given a default value using the "default"
statement, the identity name in the default value MAY have a prefix.
If a prefix is present on the identity name, it refers to an identity
defined in the module that was imported with that prefix, or the
prefix for the current module if the identity is defined in the
current module or one of its submodules. Otherwise, an identity with
the matching name MUST be defined in the current module or one of its
submodules.
The string value of a node of type identityref in a "must" or "when"
XPath expression is the referred identity's qualified name with the
prefix present. If the referred identity is defined in an imported
module, the prefix in the string value is the prefix defined in the
corresponding "import" statement. Otherwise, the prefix in the string
value is the prefix for the current module.
Since the lexical form depends on the XML context in which the
value occurs, this type does not have a canonical form.
With the identity definitions in and the following
module:
the following is an example how the leaf "crypto" can be encoded, if
the value is the "des3" identity defined in the "des" module:
des:des3
]]>
Any prefixes used in the encoding are local to each instance encoding.
This means that the same identityref may be encoded differently by
different implementations. For example, the following example encodes
the same leaf as above:
x:des3
]]>
If the "crypto" leaf's value instead is "aes" defined in the
"example‑my‑crypto" module, it can be encoded as:
mc:aes
]]>
or, using the default namespace:
aes
]]>
The empty built-in type represents a leaf that does not have any value,
it conveys information by its presence or absence.
An empty type cannot have a default value.
An empty type cannot be restricted.
Not applicable.
Not applicable.
With the following leaf
the following is an example of a valid encoding
]]>
if the leaf exists.
The union built-in type represents a value that corresponds to one of
its member types.
When the type is "union", the "type" statement () MUST be
present. It is repeatedly used to specify each member type of the
union. It takes as an argument a string that is the name of a member
type.
A member type can be of any built-in or derived type.
When generating an XML encoding, a value is encoded according to the
rules of the member type to which the value belongs. When
interpreting an XML encoding, a value is validated consecutively
against each member type, in the order they are specified in the
"type" statement, until a match is found. The type that matched will
be the type of the value for the node that was validated, and the
encoding is interpreted according to the rules for that type.
Any default value or "units" property defined in the member types is
not inherited by the union type.
A union cannot be restricted. However, each member type can be
restricted, based on the rules defined in .
The lexical representation of a union is a value that
corresponds to the representation of any one of the member types.
The canonical form of a union value is the same as the canonical form
of the member type of the value.
The following is a union of an int32 and an enumeration:
Care must be taken when a member type is a leafref where
the "require‑instance" property () is
"true". If a leaf of such a type refers to an
existing instance, the leaf's value must be re-validated if the
target instance is deleted. For example, with the following
definitions:
assume that there exists an entry in the filter list with the name
"http", and that the outbound-filter leaf has this value:
httphttp
]]>
If the filter entry "http" is removed, the outbound-filter
leaf's value doesn't match the leafref, and the next member type is
checked. The current value ("http") doesn't match the enumeration,
so the resulting configuration is invalid.
If the second member type in the union had been of type "string"
instead of an enumeration, the current value would have matched, and
the resulting configuration would have been valid.
The instance-identifier built-in type is used to uniquely identify a
particular instance node in the data tree.
The syntax for an instance-identifier is a subset of the XPath
abbreviated syntax, formally defined by the rule "instance‑identifier"
in . It is used to uniquely identify a node in the data
tree. Predicates are used only for specifying the values for the key
nodes for list entries, a value of a leaf-list entry, or a positional
index for a list without keys. For identifying list entries with keys,
each predicate consists of one equality test per key, and each key
MUST have a corresponding predicate. If a key is of type "empty", it
is represented as a zero-length string ("").
If the leaf with the instance-identifier type represents configuration
data, and the "require‑instance" property () is
"true", the node it refers to MUST also represent configuration. Such
a leaf puts a constraint on valid data. All such leaf nodes MUST
reference existing nodes or leaf or leaf-list nodes with their default
value in use (see and )
for the data to be valid. This constraint is enforced according to
the rules in .
The "instance‑identifier" XPath expression is conceptually evaluated
in the following context, in addition to the definition in
:
The context node is the root node in the accessible tree.
An instance-identifier can be restricted with the "require‑instance"
statement ().
An instance-identifier value is lexically represented as a
string. All node names in an instance-identifier value MUST be
qualified with explicit namespace prefixes, and these prefixes MUST be
declared in the XML namespace scope in the instance-identifier's XML
element.
Any prefixes used in the encoding are local to each instance encoding.
This means that the same instance-identifier may be encoded
differently by different implementations.
Since the lexical form depends on the XML context in which the
value occurs, this type does not have a canonical form.
The following are examples of instance identifiers:
This document defines two generic XPath functions and five YANG
type-specific XPath functions. The function signatures are specified
with the syntax used in .
The function current() takes no input parameters, and returns a node
set with the initial context node as its only member.
With this list:
the following leaf defines a must expression that ensures that the
referred interface is enabled:
The re-match() function returns "true" if the "subject" string matches
the regular expression "pattern"; otherwise it returns "false".
The function "re‑match" checks if a string matches a given regular
expression. The regular expressions used are the XML Schema regular
expressions . Note that this includes implicit anchoring
of the regular expression at the head and tail.
The expression:
returns "true".
To count all logical interfaces called eth0.<number>, do:
The deref() function follows the reference defined by the first node
in document order in the argument "nodes", and returns the nodes it
refers to.
If the first argument node is of type instance-identifier, the
function returns a node set that contains the single node that the
instance identifier refers to, if it exists. If no such node exists,
an empty node-set is returned.
If the first argument node is of type leafref, the function returns a
node set that contains the nodes that the leafref refers to.
Specifically, this set contains the nodes selected by the leafref's
"path" statement () that have the same value as the first
argument node.
If the first argument node is of any other type, an empty
node set is returned.
The derived-from() function returns "true" if any node in the argument
"nodes" is a node of type identityref, and its value is an identity
that is derived from (see ) the identity "identity"; otherwise
it returns "false".
The parameter "identity" is a string matching the rule
"identifier‑ref" in . If a prefix is present on the
identity, it refers to an identity defined in the module that was
imported with that prefix, or the local module if the prefix matches
the local module's prefix. If no prefix is present, the identity
refers to an identity defined in the current module or an included
submodule.
The derived-from-or-self() function returns "true" if any node in the
argument "nodes" is a node of type identityref, and its value is an
identity that is equal to or derived from (see ) the identity
"identity"; otherwise it returns "false".
The parameter "identity" is a string matching the rule
"identifier‑ref" in . If a prefix is present on the
identity, it refers to an identity defined in the module that was
imported with that prefix, or the local module if the prefix matches
the local module's prefix. If no prefix is present, the identity
refers to an identity defined in the current module or an included
submodule.
The module defined in might also have:
The enum-value() function checks if the first node in document order
in the argument "nodes" is a node of type enumeration, and returns the
enum's integer value. If the "nodes" node set is empty, or if the
first node in "nodes" is not of type enumeration, it returns NaN.
With this data model:
the following XPath expression selects only alarms that are of severity
"major" or higher:
= 5]
]]>
The bit-is-set() function returns "true" if the first node in document
order in the argument "nodes" is a node of type bits, and its value
has the bit "'bit‑name" set; otherwise it returns "false".
If an interface has this leaf:
the following XPath expression can be used to select all interfaces with the
UP flag set:
As experience is gained with a module, it may be desirable to revise
that module. However, changes to published modules are not allowed if
they have any potential to cause interoperability problems between a
client using an original specification and a server using an updated
specification.
For any published change, a new "revision" statement () MUST
be included in front of the existing "revision" statements. If there
are no existing "revision" statements, then one MUST be added to
identify the new revision. Furthermore, any necessary changes MUST be
applied to any meta-data statements, including the "organization" and
"contact" statements (, ).
Note that definitions contained in a module are available to be
imported by any other module, and are referenced in "import"
statements via the module name. Thus, a module name MUST NOT be
changed. Furthermore, the "namespace" statement MUST NOT be changed,
since all XML elements are qualified by the namespace.
Obsolete definitions MUST NOT be removed from published modules since
their identifiers may still be referenced by other modules.
A definition in a published module may be revised in any of the
following ways:
An "enumeration" type may have new enums added, provided the old
enums's values do not change. Note that inserting a new enum before
an existing enum or reordering existing enums will result in new
values for the existing enums, unless they have explicit values
assigned to them.
A "bits" type may have new bits added, provided the old bit
positions do not change. Note that inserting a new bit before an
existing bit or reordering existing bit will result in new positions
for the existing bits, unless they have explicit positions assigned
to them.
A "range", "length", or "pattern" statement may expand the allowed
value space.
A "default" statement may be added to a leaf that does not have a
default value (either directly or indirectly through its type).
A "units" statement may be added.
A "reference" statement may be added or updated.
A "must" statement may be removed or its constraint relaxed.
A "when" statement may be removed or its constraint relaxed.
A "mandatory" statement may be removed or changed from "true" to
"false".
A "min‑elements" statement may be removed, or changed to require fewer
elements.
A "max‑elements" statement may be removed, or changed to allow more
elements.
A "description" statement may be added or changed without changing
the semantics of the definition.
A "base" statement may be added to an "identity" statement.
A "base" statement may be removed from an "identityref" type,
provided there is at least one "base" statement left.
New typedefs, groupings, rpcs, notifications, extensions, features,
and identities may be added.
New data definition statements may be added if they do not add
mandatory nodes () to existing nodes or at the
top level in a module or submodule, or if they are conditionally
dependent on a new feature (i.e., have an "if‑feature" statement that
refers to a new feature).
A new "case" statement may be added.
A node that represented state data may be changed to represent
configuration, provided it is not mandatory ().
An "if‑feature" statement may be removed, provided its node is not
mandatory ().
A "status" statement may be added, or changed from "current" to
"deprecated" or "obsolete", or from "deprecated" to "obsolete".
A "type" statement may be replaced with another "type" statement
that does not change the syntax or semantics of the type. For
example, an inline type definition may be replaced with a typedef,
but an int8 type cannot be replaced by an int16, since the syntax
would change.
Any set of data definition nodes may be replaced with another set of
syntactically and semantically equivalent nodes. For example, a set
of leafs may be replaced by a uses of a grouping with the same
leafs.
A module may be split into a set of submodules, or a submodule may be
removed, provided the definitions in the module do not change in any
other way than allowed here.
The "prefix" statement may be changed, provided all local uses of the
prefix also are changed.
Otherwise, if the semantics of any previous definition are changed
(i.e., if a non-editorial change is made to any definition other than
those specifically allowed above), then this MUST be achieved by a new
definition with a new identifier.
In statements that have any data definition statements as
substatements, those data definition substatements MUST NOT be
reordered. If new data definition statements are added, they can be
added anywhere in the sequence of existing substatement.
A YANG version 1.1 module MUST NOT include a YANG version 1 submodule,
and a YANG version 1 module MUST NOT include a YANG version 1.1
submodule.
A YANG version 1 module or submodule MUST NOT import a YANG version
1.1 module by revision.
A YANG version 1.1 module or submodule MAY import a YANG version
1 module by revision.
If a YANG version 1 module A imports module B without revision, and
module B is updated to YANG version 1.1, a server MAY implement both
these modules (A and B) at the same time. In such cases, a NETCONF
server MUST advertise both modules using the rules defined in
, and SHOULD advertise module A and the latest revision of
module B that is specified with YANG version 1 according to the rules
defined in .
This rule exists in order to allow implementations of existing YANG
version 1 modules together with YANG version 1.1 modules. Without
this rule, updating a single module to YANG version 1.1 would have a
cascading effect on modules that import it, requiring all of them to
also be updated to YANG version 1.1, and so on.
A YANG module can be translated into an alternative XML-based
syntax called YIN. The translated module is called a YIN
module. This section describes bidirectional mapping rules between the
two formats.
The YANG and YIN formats contain equivalent information using
different notations. The YIN notation enables developers to represent
YANG data models in XML and therefore use the rich set of XML-based
tools for data filtering and validation, automated generation of code
and documentation, and other tasks. Tools like XSLT or XML validators
can be utilized.
The mapping between YANG and YIN does not modify the information
content of the model. Comments and whitespace are not preserved.
There is a one-to-one correspondence between YANG keywords and YIN
elements. The local name of a YIN element is identical to the
corresponding YANG keyword. This means, in particular, that the
document element (root) of a YIN document is always <module> or
<submodule>.
YIN elements corresponding to the YANG keywords belong to the
namespace whose associated URI is "urn:ietf:params:xml:ns:yang:yin:1".
YIN elements corresponding to extension keywords belong to the
namespace of the YANG module where the extension keyword is declared
via the "extension" statement.
The names of all YIN elements MUST be properly qualified with their
namespaces specified above using the standard mechanisms of
, i.e., "xmlns" and "xmlns:xxx"
attributes.
The argument of a YANG statement is represented in YIN either as an XML
attribute or a subelement of the keyword element. defines the
mapping for the set of YANG keywords. For extensions, the
argument mapping is specified within the "extension" statement (see
). The following rules hold for arguments:
If the argument is represented as an attribute, this attribute has
no namespace.
If the argument is represented as an element, it is qualified by the
same namespace as its parent keyword element.
If the argument is represented as an element, it MUST be the first
child of the keyword element.
Substatements of a YANG statement are represented as (additional) children
of the keyword element and their relative order MUST be the same as
the order of substatements in YANG.
Comments in YANG MAY be mapped to XML comments.
keywordargument nameyin-elementactionnamefalseanydatanamefalseanyxmlnamefalseargumentnamefalseaugmenttarget-nodefalsebasenamefalsebelongs-tomodulefalsebitnamefalsecasenamefalsechoicenamefalseconfigvaluefalsecontacttexttruecontainernamefalsedefaultvaluefalsedescriptiontexttruedeviatevaluefalsedeviationtarget-nodefalseenumnamefalseerror-app-tagvaluefalseerror-messagevaluetrueextensionnamefalsefeaturenamefalsefraction-digitsvaluefalsegroupingnamefalseidentitynamefalseif-featurenamefalseimportmodulefalseincludemodulefalseinput<no argument>n/akeyvaluefalseleafnamefalseleaf-listnamefalselengthvaluefalselistnamefalsemandatoryvaluefalsemax-elementsvaluefalsemin-elementsvaluefalsemodifiervaluefalsemodulenamefalsemustconditionfalsenamespaceurifalsenotificationnamefalseordered-byvaluefalseorganizationtexttrueoutput<no argument>n/apathvaluefalsepatternvaluefalsepositionvaluefalseprefixvaluefalsepresencevaluefalserangevaluefalsereferencetexttruerefinetarget-nodefalserequire-instancevaluefalserevisiondatefalserevision-datedatefalserpcnamefalsestatusvaluefalsesubmodulenamefalsetypenamefalsetypedefnamefalseuniquetagfalseunitsnamefalseusesnamefalsevaluevaluefalsewhenconditionfalseyang-versionvaluefalseyin-elementvaluefalse
The following YANG module:
where the extension "c‑define" is defined in , is
translated into the following YIN:
The MTU of the interface.
]]>
In YANG, almost all statements are unordered. The ABNF grammar
defines the canonical order. To improve module
readability, it is RECOMMENDED that clauses be entered in this order.
Within the ABNF grammar, unordered statements are marked with
comments.
This grammar assumes that the scanner replaces YANG comments with a
single space character.
<CODE BEGINS> file "yang.abnf"
< yang-version-arg >
yang-version-arg = "1.1"
import-stmt = import-keyword sep identifier-arg-str optsep
"{" stmtsep
;; these stmts can appear in any order
prefix-stmt
[revision-date-stmt]
[description-stmt]
[reference-stmt]
"}" stmtsep
include-stmt = include-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[revision-date-stmt]
[description-stmt]
[reference-stmt]
"}") stmtsep
namespace-stmt = namespace-keyword sep uri-str stmtend
uri-str = < a string that matches the rule >
< URI in RFC 3986 >
prefix-stmt = prefix-keyword sep prefix-arg-str stmtend
belongs-to-stmt = belongs-to-keyword sep identifier-arg-str
optsep
"{" stmtsep
prefix-stmt
"}" stmtsep
organization-stmt = organization-keyword sep string stmtend
contact-stmt = contact-keyword sep string stmtend
description-stmt = description-keyword sep string stmtend
reference-stmt = reference-keyword sep string stmtend
units-stmt = units-keyword sep string stmtend
revision-stmt = revision-keyword sep revision-date optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[description-stmt]
[reference-stmt]
"}") stmtsep
revision-date = date-arg-str
revision-date-stmt = revision-date-keyword sep revision-date stmtend
extension-stmt = extension-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[argument-stmt]
[status-stmt]
[description-stmt]
[reference-stmt]
"}") stmtsep
argument-stmt = argument-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
[yin-element-stmt]
"}") stmtsep
yin-element-stmt = yin-element-keyword sep yin-element-arg-str
stmtend
yin-element-arg-str = < a string that matches the rule >
< yin-element-arg >
yin-element-arg = true-keyword / false-keyword
identity-stmt = identity-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
*if-feature-stmt
*base-stmt
[status-stmt]
[description-stmt]
[reference-stmt]
"}") stmtsep
base-stmt = base-keyword sep identifier-ref-arg-str
stmtend
feature-stmt = feature-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
*if-feature-stmt
[status-stmt]
[description-stmt]
[reference-stmt]
"}") stmtsep
if-feature-stmt = if-feature-keyword sep if-feature-expr-str
stmtend
if-feature-expr-str = < a string that matches the rule >
< if-feature-expr >
if-feature-expr = if-feature-term
[sep or-keyword sep if-feature-expr]
if-feature-term = if-feature-factor
[sep and-keyword sep if-feature-term]
if-feature-factor = not-keyword sep if-feature-factor /
"(" sep if-feature-expr sep ")" /
identifier-ref-arg
boolean-operator = and-keyword / or-keyword
typedef-stmt = typedef-keyword sep identifier-arg-str optsep
"{" stmtsep
;; these stmts can appear in any order
type-stmt
[units-stmt]
[default-stmt]
[status-stmt]
[description-stmt]
[reference-stmt]
"}" stmtsep
type-stmt = type-keyword sep identifier-ref-arg-str optsep
(";" /
"{" stmtsep
[type-body-stmts]
"}") stmtsep
type-body-stmts = numerical-restrictions /
decimal64-specification /
string-restrictions /
enum-specification /
leafref-specification /
identityref-specification /
instance-identifier-specification /
bits-specification /
union-specification /
binary-specification
numerical-restrictions = [range-stmt]
range-stmt = range-keyword sep range-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[error-message-stmt]
[error-app-tag-stmt]
[description-stmt]
[reference-stmt]
"}") stmtsep
decimal64-specification = ;; these stmts can appear in any order
fraction-digits-stmt
[range-stmt]
fraction-digits-stmt = fraction-digits-keyword sep
fraction-digits-arg-str stmtend
fraction-digits-arg-str = < a string that matches the rule >
< fraction-digits-arg >
fraction-digits-arg = ("1" ["0" / "1" / "2" / "3" / "4" /
"5" / "6" / "7" / "8"])
/ "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9"
string-restrictions = ;; these stmts can appear in any order
[length-stmt]
*pattern-stmt
length-stmt = length-keyword sep length-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[error-message-stmt]
[error-app-tag-stmt]
[description-stmt]
[reference-stmt]
"}") stmtsep
pattern-stmt = pattern-keyword sep string optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[modifier-stmt]
[error-message-stmt]
[error-app-tag-stmt]
[description-stmt]
[reference-stmt]
"}") stmtsep
modifier-stmt = modifier-keyword sep modifier-arg-str stmtend
modifier-arg-str = < a string that matches the rule >
< modifier-arg >
modifier-arg = invert-match-keyword
default-stmt = default-keyword sep string stmtend
enum-specification = 1*enum-stmt
enum-stmt = enum-keyword sep string optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
*if-feature-stmt
[value-stmt]
[status-stmt]
[description-stmt]
[reference-stmt]
"}") stmtsep
leafref-specification =
;; these stmts can appear in any order
path-stmt
[require-instance-stmt]
path-stmt = path-keyword sep path-arg-str stmtend
require-instance-stmt = require-instance-keyword sep
require-instance-arg-str stmtend
require-instance-arg-str = < a string that matches the rule >
< require-instance-arg >
require-instance-arg = true-keyword / false-keyword
instance-identifier-specification =
[require-instance-stmt]
identityref-specification =
1*base-stmt
union-specification = 1*type-stmt
binary-specification = [length-stmt]
bits-specification = 1*bit-stmt
bit-stmt = bit-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
*if-feature-stmt
[position-stmt]
[status-stmt]
[description-stmt]
[reference-stmt]
"}") stmtsep
position-stmt = position-keyword sep
position-value-arg-str stmtend
position-value-arg-str = < a string that matches the rule >
< position-value-arg >
position-value-arg = non-negative-integer-value
status-stmt = status-keyword sep status-arg-str stmtend
status-arg-str = < a string that matches the rule >
< status-arg >
status-arg = current-keyword /
obsolete-keyword /
deprecated-keyword
config-stmt = config-keyword sep
config-arg-str stmtend
config-arg-str = < a string that matches the rule >
< config-arg >
config-arg = true-keyword / false-keyword
mandatory-stmt = mandatory-keyword sep
mandatory-arg-str stmtend
mandatory-arg-str = < a string that matches the rule >
< mandatory-arg >
mandatory-arg = true-keyword / false-keyword
presence-stmt = presence-keyword sep string stmtend
ordered-by-stmt = ordered-by-keyword sep
ordered-by-arg-str stmtend
ordered-by-arg-str = < a string that matches the rule >
< ordered-by-arg >
ordered-by-arg = user-keyword / system-keyword
must-stmt = must-keyword sep string optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[error-message-stmt]
[error-app-tag-stmt]
[description-stmt]
[reference-stmt]
"}") stmtsep
error-message-stmt = error-message-keyword sep string stmtend
error-app-tag-stmt = error-app-tag-keyword sep string stmtend
min-elements-stmt = min-elements-keyword sep
min-value-arg-str stmtend
min-value-arg-str = < a string that matches the rule >
< min-value-arg >
min-value-arg = non-negative-integer-value
max-elements-stmt = max-elements-keyword sep
max-value-arg-str stmtend
max-value-arg-str = < a string that matches the rule >
< max-value-arg >
max-value-arg = unbounded-keyword /
positive-integer-value
value-stmt = value-keyword sep integer-value-str stmtend
integer-value-str = < a string that matches the rule >
< integer-value >
grouping-stmt = grouping-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[status-stmt]
[description-stmt]
[reference-stmt]
*(typedef-stmt / grouping-stmt)
*data-def-stmt
*action-stmt
*notification-stmt
"}") stmtsep
container-stmt = container-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[when-stmt]
*if-feature-stmt
*must-stmt
[presence-stmt]
[config-stmt]
[status-stmt]
[description-stmt]
[reference-stmt]
*(typedef-stmt / grouping-stmt)
*data-def-stmt
*action-stmt
*notification-stmt
"}") stmtsep
leaf-stmt = leaf-keyword sep identifier-arg-str optsep
"{" stmtsep
;; these stmts can appear in any order
[when-stmt]
*if-feature-stmt
type-stmt
[units-stmt]
*must-stmt
[default-stmt]
[config-stmt]
[mandatory-stmt]
[status-stmt]
[description-stmt]
[reference-stmt]
"}" stmtsep
leaf-list-stmt = leaf-list-keyword sep identifier-arg-str optsep
"{" stmtsep
;; these stmts can appear in any order
[when-stmt]
*if-feature-stmt
type-stmt stmtsep
[units-stmt]
*must-stmt
*default-stmt
[config-stmt]
[min-elements-stmt]
[max-elements-stmt]
[ordered-by-stmt]
[status-stmt]
[description-stmt]
[reference-stmt]
"}" stmtsep
list-stmt = list-keyword sep identifier-arg-str optsep
"{" stmtsep
;; these stmts can appear in any order
[when-stmt]
*if-feature-stmt
*must-stmt
[key-stmt]
*unique-stmt
[config-stmt]
[min-elements-stmt]
[max-elements-stmt]
[ordered-by-stmt]
[status-stmt]
[description-stmt]
[reference-stmt]
*(typedef-stmt / grouping-stmt)
1*data-def-stmt
*action-stmt
*notification-stmt
"}" stmtsep
key-stmt = key-keyword sep key-arg-str stmtend
key-arg-str = < a string that matches the rule >
< key-arg >
key-arg = node-identifier *(sep node-identifier)
unique-stmt = unique-keyword sep unique-arg-str stmtend
unique-arg-str = < a string that matches the rule >
< unique-arg >
unique-arg = descendant-schema-nodeid
*(sep descendant-schema-nodeid)
choice-stmt = choice-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[when-stmt]
*if-feature-stmt
[default-stmt]
[config-stmt]
[mandatory-stmt]
[status-stmt]
[description-stmt]
[reference-stmt]
*(short-case-stmt / case-stmt)
"}") stmtsep
short-case-stmt = choice-stmt /
container-stmt /
leaf-stmt /
leaf-list-stmt /
list-stmt /
anydata-stmt /
anyxml-stmt
case-stmt = case-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[when-stmt]
*if-feature-stmt
[status-stmt]
[description-stmt]
[reference-stmt]
*data-def-stmt
"}") stmtsep
anydata-stmt = anydata-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[when-stmt]
*if-feature-stmt
*must-stmt
[config-stmt]
[mandatory-stmt]
[status-stmt]
[description-stmt]
[reference-stmt]
"}") stmtsep
anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[when-stmt]
*if-feature-stmt
*must-stmt
[config-stmt]
[mandatory-stmt]
[status-stmt]
[description-stmt]
[reference-stmt]
"}") stmtsep
uses-stmt = uses-keyword sep identifier-ref-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[when-stmt]
*if-feature-stmt
[status-stmt]
[description-stmt]
[reference-stmt]
*refine-stmt
*uses-augment-stmt
"}") stmtsep
refine-stmt = refine-keyword sep refine-arg-str optsep
"{" stmtsep
;; these stmts can appear in any order
*if-feature-stmt
*must-stmt
[presence-stmt]
*default-stmt
[config-stmt]
[mandatory-stmt]
[min-elements-stmt]
[max-elements-stmt]
[description-stmt]
[reference-stmt]
"}" stmtsep
refine-arg-str = < a string that matches the rule >
< refine-arg >
refine-arg = descendant-schema-nodeid
uses-augment-stmt = augment-keyword sep uses-augment-arg-str optsep
"{" stmtsep
;; these stmts can appear in any order
[when-stmt]
*if-feature-stmt
[status-stmt]
[description-stmt]
[reference-stmt]
1*(data-def-stmt / case-stmt /
action-stmt / notification-stmt)
"}" stmtsep
uses-augment-arg-str = < a string that matches the rule >
< uses-augment-arg >
uses-augment-arg = descendant-schema-nodeid
augment-stmt = augment-keyword sep augment-arg-str optsep
"{" stmtsep
;; these stmts can appear in any order
[when-stmt]
*if-feature-stmt
[status-stmt]
[description-stmt]
[reference-stmt]
1*(data-def-stmt / case-stmt /
action-stmt / notification-stmt)
"}" stmtsep
augment-arg-str = < a string that matches the rule >
< augment-arg >
augment-arg = absolute-schema-nodeid
when-stmt = when-keyword sep string optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[description-stmt]
[reference-stmt]
"}") stmtsep
rpc-stmt = rpc-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
*if-feature-stmt
[status-stmt]
[description-stmt]
[reference-stmt]
*(typedef-stmt / grouping-stmt)
[input-stmt]
[output-stmt]
"}") stmtsep
action-stmt = action-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
*if-feature-stmt
[status-stmt]
[description-stmt]
[reference-stmt]
*(typedef-stmt / grouping-stmt)
[input-stmt]
[output-stmt]
"}") stmtsep
input-stmt = input-keyword optsep
"{" stmtsep
;; these stmts can appear in any order
*must-stmt
*(typedef-stmt / grouping-stmt)
1*data-def-stmt
"}" stmtsep
output-stmt = output-keyword optsep
"{" stmtsep
;; these stmts can appear in any order
*must-stmt
*(typedef-stmt / grouping-stmt)
1*data-def-stmt
"}" stmtsep
notification-stmt = notification-keyword sep
identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
*if-feature-stmt
*must-stmt
[status-stmt]
[description-stmt]
[reference-stmt]
*(typedef-stmt / grouping-stmt)
*data-def-stmt
"}") stmtsep
deviation-stmt = deviation-keyword sep
deviation-arg-str optsep
"{" stmtsep
;; these stmts can appear in any order
[description-stmt]
[reference-stmt]
(deviate-not-supported-stmt /
1*(deviate-add-stmt /
deviate-replace-stmt /
deviate-delete-stmt))
"}" stmtsep
deviation-arg-str = < a string that matches the rule >
< deviation-arg >
deviation-arg = absolute-schema-nodeid
deviate-not-supported-stmt =
deviate-keyword sep
not-supported-keyword-str stmtend
deviate-add-stmt = deviate-keyword sep add-keyword-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[units-stmt]
*must-stmt
*unique-stmt
*default-stmt
[config-stmt]
[mandatory-stmt]
[min-elements-stmt]
[max-elements-stmt]
"}") stmtsep
deviate-delete-stmt = deviate-keyword sep delete-keyword-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[units-stmt]
*must-stmt
*unique-stmt
*default-stmt
"}") stmtsep
deviate-replace-stmt = deviate-keyword sep replace-keyword-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[type-stmt]
[units-stmt]
[default-stmt]
[config-stmt]
[mandatory-stmt]
[min-elements-stmt]
[max-elements-stmt]
"}") stmtsep
not-supported-keyword-str = < a string that matches the rule >
< not-supported-keyword >
add-keyword-str = < a string that matches the rule >
< add-keyword >
delete-keyword-str = < a string that matches the rule >
< delete-keyword >
replace-keyword-str = < a string that matches the rule >
< replace-keyword >
;; represents the usage of an extension statement
unknown-statement = prefix ":" identifier [sep string] optsep
(";" /
"{" optsep
*((yang-stmt / unknown-statement) optsep)
"}") stmtsep
yang-stmt = action-stmt /
anydata-stmt /
anyxml-stmt /
argument-stmt /
augment-stmt /
base-stmt /
belongs-to-stmt /
bit-stmt /
case-stmt /
choice-stmt /
config-stmt /
contact-stmt /
container-stmt /
default-stmt /
description-stmt /
deviate-add-stmt /
deviate-delete-stmt /
deviate-not-supported-stmt /
deviate-replace-stmt /
deviation-stmt /
enum-stmt /
error-app-tag-stmt /
error-message-stmt /
extension-stmt /
feature-stmt /
fraction-digits-stmt /
grouping-stmt /
identity-stmt /
if-feature-stmt /
import-stmt /
include-stmt /
input-stmt /
key-stmt /
leaf-list-stmt /
leaf-stmt /
length-stmt /
list-stmt /
mandatory-stmt /
max-elements-stmt /
min-elements-stmt /
modifier-stmt /
module-stmt /
must-stmt /
namespace-stmt /
notification-stmt /
ordered-by-stmt /
organization-stmt /
output-stmt /
path-stmt /
pattern-stmt /
position-stmt /
prefix-stmt /
presence-stmt /
range-stmt /
reference-stmt /
refine-stmt /
require-instance-stmt /
revision-date-stmt /
revision-stmt /
rpc-stmt /
status-stmt /
submodule-stmt /
typedef-stmt /
type-stmt /
unique-stmt /
units-stmt /
uses-augment-stmt /
uses-stmt /
value-stmt /
when-stmt /
yang-version-stmt /
yin-element-stmt
;; Ranges
range-arg-str = < a string that matches the rule >
< range-arg >
range-arg = range-part *(optsep "|" optsep range-part)
range-part = range-boundary
[optsep ".." optsep range-boundary]
range-boundary = min-keyword / max-keyword /
integer-value / decimal-value
;; Lengths
length-arg-str = < a string that matches the rule >
< length-arg >
length-arg = length-part *(optsep "|" optsep length-part)
length-part = length-boundary
[optsep ".." optsep length-boundary]
length-boundary = min-keyword / max-keyword /
non-negative-integer-value
;; Date
date-arg-str = < a string that matches the rule >
< date-arg >
date-arg = 4DIGIT "-" 2DIGIT "-" 2DIGIT
;; Schema Node Identifiers
schema-nodeid = absolute-schema-nodeid /
descendant-schema-nodeid
absolute-schema-nodeid = 1*("/" node-identifier)
descendant-schema-nodeid =
node-identifier
[absolute-schema-nodeid]
node-identifier = [prefix ":"] identifier
;; Instance Identifiers
instance-identifier = 1*("/" (node-identifier
[1*key-predicate /
leaf-list-predicate /
pos]))
key-predicate = "[" *WSP key-predicate-expr *WSP "]"
key-predicate-expr = node-identifier *WSP "=" *WSP quoted-string
leaf-list-predicate = "[" *WSP leaf-list-predicate-expr *WSP "]"
leaf-list-predicate-expr = "." *WSP "=" *WSP quoted-string
pos = "[" *WSP positive-integer-value *WSP "]"
quoted-string = (DQUOTE string DQUOTE) / (SQUOTE string SQUOTE)
;; leafref path
path-arg-str = < a string that matches the rule >
< path-arg >
path-arg = absolute-path / relative-path
absolute-path = 1*("/" (node-identifier *path-predicate))
relative-path = 1*("../") descendant-path
descendant-path = node-identifier
[*path-predicate absolute-path]
path-predicate = "[" *WSP path-equality-expr *WSP "]"
path-equality-expr = node-identifier *WSP "=" *WSP path-key-expr
path-key-expr = current-function-invocation *WSP "/" *WSP
rel-path-keyexpr
rel-path-keyexpr = 1*(".." *WSP "/" *WSP)
*(node-identifier *WSP "/" *WSP)
node-identifier
;;; Keywords, using RFC 7405 syntax for case-sensitive strings
;; statement keywords
action-keyword = %s"action"
anydata-keyword = %s"anydata"
anyxml-keyword = %s"anyxml"
argument-keyword = %s"argument"
augment-keyword = %s"augment"
base-keyword = %s"base"
belongs-to-keyword = %s"belongs-to"
bit-keyword = %s"bit"
case-keyword = %s"case"
choice-keyword = %s"choice"
config-keyword = %s"config"
contact-keyword = %s"contact"
container-keyword = %s"container"
default-keyword = %s"default"
description-keyword = %s"description"
enum-keyword = %s"enum"
error-app-tag-keyword = %s"error-app-tag"
error-message-keyword = %s"error-message"
extension-keyword = %s"extension"
deviation-keyword = %s"deviation"
deviate-keyword = %s"deviate"
feature-keyword = %s"feature"
fraction-digits-keyword = %s"fraction-digits"
grouping-keyword = %s"grouping"
identity-keyword = %s"identity"
if-feature-keyword = %s"if-feature"
import-keyword = %s"import"
include-keyword = %s"include"
input-keyword = %s"input"
key-keyword = %s"key"
leaf-keyword = %s"leaf"
leaf-list-keyword = %s"leaf-list"
length-keyword = %s"length"
list-keyword = %s"list"
mandatory-keyword = %s"mandatory"
max-elements-keyword = %s"max-elements"
min-elements-keyword = %s"min-elements"
modifier-keyword = %s"modifier"
module-keyword = %s"module"
must-keyword = %s"must"
namespace-keyword = %s"namespace"
notification-keyword = %s"notification"
ordered-by-keyword = %s"ordered-by"
organization-keyword = %s"organization"
output-keyword = %s"output"
path-keyword = %s"path"
pattern-keyword = %s"pattern"
position-keyword = %s"position"
prefix-keyword = %s"prefix"
presence-keyword = %s"presence"
range-keyword = %s"range"
reference-keyword = %s"reference"
refine-keyword = %s"refine"
require-instance-keyword = %s"require-instance"
revision-keyword = %s"revision"
revision-date-keyword = %s"revision-date"
rpc-keyword = %s"rpc"
status-keyword = %s"status"
submodule-keyword = %s"submodule"
type-keyword = %s"type"
typedef-keyword = %s"typedef"
unique-keyword = %s"unique"
units-keyword = %s"units"
uses-keyword = %s"uses"
value-keyword = %s"value"
when-keyword = %s"when"
yang-version-keyword = %s"yang-version"
yin-element-keyword = %s"yin-element"
;; other keywords
add-keyword = %s"add"
current-keyword = %s"current"
delete-keyword = %s"delete"
deprecated-keyword = %s"deprecated"
false-keyword = %s"false"
invert-match-keyword = %s"invert-match"
max-keyword = %s"max"
min-keyword = %s"min"
not-supported-keyword = %s"not-supported"
obsolete-keyword = %s"obsolete"
replace-keyword = %s"replace"
system-keyword = %s"system"
true-keyword = %s"true"
unbounded-keyword = %s"unbounded"
user-keyword = %s"user"
and-keyword = %s"and"
or-keyword = %s"or"
not-keyword = %s"not"
current-function-invocation = current-keyword *WSP "(" *WSP ")"
;;; Basic Rules
prefix-arg-str = < a string that matches the rule >
< prefix-arg >
prefix-arg = prefix
prefix = identifier
identifier-arg-str = < a string that matches the rule >
< identifier-arg >
identifier-arg = identifier
;; An identifier MUST NOT start with (('X'|'x') ('M'|'m') ('L'|'l'))
identifier = (ALPHA / "_")
*(ALPHA / DIGIT / "_" / "-" / ".")
identifier-ref-arg-str = < a string that matches the rule >
< identifier-ref-arg >
identifier-ref-arg = identifier-ref
identifier-ref = [prefix ":"] identifier
string = < an unquoted string as returned by >
< the scanner, that matches the rule >
< yang-string >
yang-string = *yang-char
;; any Unicode or ISO/IEC 10646 character including tab, carriage
;; return, and line feed, but excluding the other C0 control
;; characters, the surrogate blocks, and the noncharacters.
yang-char = %x09 / %x0A / %x0D / %x20-D7FF /
; exclude surrogate blocks %xD800-DFFF
%xE000-FDCF / ; exclude noncharacters %xFDD0-FDEF
%xFDF0-FFFD / ; exclude noncharacters %xFFFE-FFFF
%x10000-1FFFD / ; exclude noncharacters %x1FFFE-1FFFF
%x20000-2FFFD / ; exclude noncharacters %x2FFFE-2FFFF
%x30000-3FFFD / ; exclude noncharacters %x3FFFE-3FFFF
%x40000-4FFFD / ; exclude noncharacters %x4FFFE-4FFFF
%x50000-5FFFD / ; exclude noncharacters %x5FFFE-5FFFF
%x60000-6FFFD / ; exclude noncharacters %x6FFFE-6FFFF
%x70000-7FFFD / ; exclude noncharacters %x7FFFE-7FFFF
%x80000-8FFFD / ; exclude noncharacters %x8FFFE-8FFFF
%x90000-9FFFD / ; exclude noncharacters %x9FFFE-9FFFF
%xA0000-AFFFD / ; exclude noncharacters %xAFFFE-AFFFF
%xB0000-BFFFD / ; exclude noncharacters %xBFFFE-BFFFF
%xC0000-CFFFD / ; exclude noncharacters %xCFFFE-CFFFF
%xD0000-DFFFD / ; exclude noncharacters %xDFFFE-DFFFF
%xE0000-EFFFD / ; exclude noncharacters %xEFFFE-EFFFF
%xF0000-FFFFD / ; exclude noncharacters %xFFFFE-FFFFF
%x100000-10FFFD ; exclude noncharacters %x10FFFE-10FFFF
integer-value = ("-" non-negative-integer-value) /
non-negative-integer-value
non-negative-integer-value = "0" / positive-integer-value
positive-integer-value = (non-zero-digit *DIGIT)
zero-integer-value = 1*DIGIT
stmtend = optsep (";" / "{" stmtsep "}") stmtsep
sep = 1*(WSP / line-break)
; unconditional separator
optsep = *(WSP / line-break)
stmtsep = *(WSP / line-break / unknown-statement)
line-break = CRLF / LF
non-zero-digit = %x31-39
decimal-value = integer-value ("." zero-integer-value)
SQUOTE = %x27
; single quote
;;; RFC 5234 core rules.
ALPHA = %x41-5A / %x61-7A
; A-Z / a-z
CR = %x0D
; carriage return
CRLF = CR LF
; Internet standard new line
DIGIT = %x30-39
; 0-9
DQUOTE = %x22
; double quote
HTAB = %x09
; horizontal tab
LF = %x0A
; linefeed
SP = %x20
; space
WSP = SP / HTAB
; whitespace
]]><CODE ENDS>
A number of NETCONF error responses are defined for error cases
related to the data-model handling. If the relevant YANG statement has
an "error‑app‑tag" substatement, that overrides the default value
specified below.
If a NETCONF operation would result in configuration data where a
unique constraint is invalidated, the following error MUST be returned:
: Contains an instance identifier that
points to a leaf that invalidates the unique
constraint. This element is present once for each
non-unique leaf.
The element is in the YANG
namespace ("urn:ietf:params:xml:ns:yang:1").
]]>
If a NETCONF operation would result in configuration data where a list
or a leaf-list would have too many entries the following error MUST be
returned:
This error is returned once, with the error-path identifying the list
node, even if there are more than one extra child present.
If a NETCONF operation would result in configuration data where a list
or a leaf-list would have too few entries the following error MUST be
returned:
This error is returned once, with the error-path identifying the list
node, even if there are more than one child missing.
If a NETCONF operation would result in configuration data where the
restrictions imposed by a "must" statement is violated the following
error MUST be returned, unless a specific "error‑app‑tag" substatement is
present for the "must" statement.
If a NETCONF operation would result in configuration data where a leaf
of type "instance‑identifier" or "leafref" marked with
require-instance "true" refers to a non-existing instance, the
following error MUST be returned:
If a NETCONF operation would result in configuration data where no
nodes exists in a mandatory choice, the following error MUST be returned:
: Contains the name of the missing
mandatory choice.
The element is in the YANG
namespace ("urn:ietf:params:xml:ns:yang:1").
]]>
If the "insert" and "key" or "value" attributes are used in an
<edit‑config> for a list or leaf-list node, and the "key" or "value"
refers to a non-existing instance, the following error MUST be returned:
This document registers one capability identifier URN from the
"Network Configuration Protocol (NETCONF) Capability URNs" registry:
This document defines a language with which to write and read
descriptions of management information. The language itself has no
security impact on the Internet.
The same considerations are relevant as for the base NETCONF protocol
(see , Section 9).
Data modeled in YANG might contain sensitive information. RPCs
or notifications defined in YANG might transfer sensitive information.
Security issues are related to the usage of data modeled
in YANG. Such issues shall be dealt with in documents
describing the data models and documents about the
interfaces used to manipulate the data e.g.,
the NETCONF documents.
Data modeled in YANG is dependent upon:
the security of the transmission infrastructure used
to send sensitive information.
the security of applications that store or release
such sensitive information.
adequate authentication and access control mechanisms
to restrict the usage of sensitive data.
YANG parsers need to be robust with respect to malformed documents.
Reading malformed documents from unknown or untrusted sources could
result in an attacker gaining privileges of the user running the YANG
parser. In an extreme situation, the entire machine could be
compromised.
The following people all contributed significantly to the initial
YANG document:
The editor wishes to thank the following individuals, who all provided
helpful comments on various versions of this document: Mehmet Ersue,
Washam Fan, Joel Halpern, Per Hedeland, Leif Johansson, Ladislav
Lhotka, Lionel Morand, Gerhard Muenz, Peyman Owladi, Tom Petch, Randy
Presuhn, David Reid, Jernej Tuljak, Kent Watsen, Bert Wijnen, Robert
Wilton, and Dale Worley.
RFC Editor: remove this section upon publication as an RFC.
Made single and double quote characters illegal in unquoted
strings.
Allow "description" and "reference" in "import" and "include".
Removed redundant NETCONF Error Message subsection.
Editorial fixes and clarifications after second WGLC reviews.
Editorial fixes and clarifications after WGLC reviews.
when statement context clarification.
Allow "augment" to add conditionally mandatory nodes (see
).
Allow non-unique config false leaf-lists.
Made handling of choice and false "when" expressions non-NETCONF
specific.
Changed the function signatures for "derived‑from" and
"derived‑from‑or‑self".
Fixes after WGLC reviews.
Fixes after WG review.
Included solution Y60-01.
Included solution Y45-05.
Included solution Y18-01.
Included solution Y25-02 (parts of it was included in -04).
Included solution Y34-05.
Included solution Y36-03.
Incorporated changes to ABNF grammar after review and errata
for RFC 6020.
Included solution Y16-03.
Included solution Y49-04.
Included solution Y58-01.
Included solution Y59-01.
Incorporated changes from WG reviews.
Included solution Y05-01.
Included solution Y10-01.
Included solution Y13-01.
Included solution Y28-02.
Included solution Y55-01 (parts of it was included in -01).
Included solution Y02-01.
Included solution Y04-02.
Included solution Y11-01.
Included solution Y41-01.
Included solution Y56-01.
Included solution Y01-01.
Included solution Y03-01.
Included solution Y06-02.
Included solution Y07-01.
Included solution Y14-01.
Included solution Y20-01.
Included solution Y23-01.
Included solution Y29-01.
Included solution Y30-01.
Included solution Y31-01.
Included solution Y35-01.
Applied all reported errata for RFC 6020.
Updated YANG version to 1.1, and made the "yang‑version" statement
mandatory.
Key words for use in RFCs to Indicate Requirement LevelsIn many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.UTF-8, a transformation format of ISO 10646ISO/IEC 10646-1 defines a large character set called the Universal Character Set (UCS) which encompasses most of the world's writing systems. The originally proposed encodings of the UCS, however, were not compatible with many current applications and protocols, and this has led to the development of UTF-8, the object of this memo. UTF-8 has the characteristic of preserving the full US-ASCII range, providing compatibility with file systems, parsers and other software that rely on US-ASCII values but are transparent to other values. This memo obsoletes and replaces RFC 2279.Uniform Resource Identifier (URI): Generic SyntaxA Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK]The Base16, Base32, and Base64 Data EncodingsThis document describes the commonly used base 64, base 32, and base 16 encoding schemes. It also discusses the use of line-feeds in encoded data, use of padding in encoded data, use of non-alphabet characters in encoded data, use of different encoding alphabets, and canonical encodings. [STANDARDS-TRACK]Network Configuration Protocol (NETCONF)The Network Configuration Protocol (NETCONF) defined in this document provides mechanisms to install, manipulate, and delete the configuration of network devices. It uses an Extensible Markup Language (XML)-based data encoding for the configuration data as well as the protocol messages. The NETCONF protocol operations are realized as remote procedure calls (RPCs). This document obsoletes RFC 4741. [STANDARDS-TRACK]Augmented BNF for Syntax Specifications: ABNFInternet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK]Case-Sensitive String Support in ABNFThis document extends the base definition of ABNF (Augmented Backus-Naur Form) to include a way to specify US-ASCII string literals that are matched in a case-sensitive manner.NETCONF Event NotificationsThis document defines mechanisms that provide an asynchronous message notification delivery service for the Network Configuration protocol (NETCONF). This is an optional capability built on top of the base NETCONF definition. This document defines the capabilities and operations necessary to support this service. [STANDARDS-TRACK]YANG Module LibraryThis document describes a YANG library, which provides information about all the YANG modules used by a network management server (e.g., a Network Configuration Protocol (NETCONF) server). Simple caching mechanisms are provided to allow clients to minimize retrieval of this information.Namespaces in XML 1.0 (Third Edition)XML Schema Part 2: Datatypes Second EditionXML Path Language (XPath) Version 1.0Information Technology - Universal Multiple-Octet Coded Character Set (UCS)International Organization for StandardizationStructure of Management Information Version 2 (SMIv2)It is the purpose of this document, the Structure of Management Information Version 2 (SMIv2), to define that adapted subset, and to assign a set of associated administrative values. [STANDARDS-TRACK]Textual Conventions for SMIv2It is the purpose of this document to define the initial set of textual conventions available to all MIB modules. [STANDARDS-TRACK]SMIng - Next Generation Structure of Management InformationThis memo defines the base SMIng (Structure of Management Information, Next Generation) language. SMIng is a data definition language that provides a protocol-independent representation for management information. Separate RFCs define mappings of SMIng to specific management protocols, including SNMP. This memo defines an Experimental Protocol for the Internet community.The RFC Series and RFC EditorInternet Architecture BoardThis document describes the framework for an RFC Series and an RFC Editor function that incorporate the principles of organized community involvement and accountability that has become necessary as the Internet technical community has grown, thereby enabling the RFC Series to continue to fulfill its mandate. This memo provides information for the Internet community.YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)YANG is a data modeling language used to model configuration and state data manipulated by the Network Configuration Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. [STANDARDS-TRACK]Translation of Structure of Management Information Version 2 (SMIv2) MIB Modules to YANG ModulesYANG is a data modeling language used to model configuration and state data manipulated by the Network Configuration Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. The Structure of Management Information (SMIv2) defines fundamental data types, an object model, and the rules for writing and revising MIB modules for use with the Simple Network Management Protocol (SNMP). This document defines a translation of SMIv2 MIB modules into YANG modules, enabling read-only (config false) access to data objects defined in SMIv2 MIB modules via NETCONF. [STANDARDS-TRACK]TCP Options and Maximum Segment Size (MSS)This memo discusses what value to use with the TCP Maximum Segment Size (MSS) option, and updates RFC 879 and RFC 2385. This document is not an Internet Standards Track specification; it is published for informational purposes.JSON Encoding of Data Modeled with YANGThis document defines encoding rules for representing configuration data, state data, parameters of RPC operations or actions, and notifications defined using YANG as JavaScript Object Notation (JSON) text.Guidelines for Authors and Reviewers of YANG Data Model DocumentsThis memo provides guidelines for authors and reviewers of Standards Track specifications containing YANG data model modules. Applicable portions may be used as a basis for reviews of other YANG data model documents. Recommendations and procedures are defined, which are intended to increase interoperability and usability of Network Configuration Protocol (NETCONF) implementations that utilize YANG data model modules.RESTCONF ProtocolThis document describes an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG, using the datastores defined in NETCONF.CoAP Management InterfaceThis document describes a network management interface for constrained devices, called CoMI. CoMI is an adaptation of the RESTCONF protocol for use in constrained devices and networks. The Constrained Application Protocol (CoAP) is used to access management data resources specified in YANG, or SMIv2 converted to YANG. CoMI use the YANG to CBOR mapping and encodes YANG names to reduce payload size. Note Discussion and suggestions for improvement are requested, and should be sent to core@ietf.org.XSL Transformations (XSLT) Version 1.0XML Path Language (XPath) 2.0 (Second Edition)