YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)
updated by
- rfc-9890 — An Update to YANG Module Names Registration
Extracted elements (29)
Grouping, type, and identity names are resolved in the context where they are defined (static scoping), not where they are used. This eliminates ambiguity when two importing modules define the same local name, and means users of a grouping do not need to import all modules the grouping internally references.
YANG syntax was deliberately modeled on SMIng and C/C++ rather than XML because readability was prioritized above the convenience of module writers and tool-chain developers. The C-like syntax with braces and semicolons makes models more accessible to human readers.
YIN (YANG Independent Notation) provides a lossless XML representation of YANG modules, enabling XSLT scripts and XML-based tools to operate on YANG models. The YANG-to-YIN conversion is lossless and round-trippable, making it possible to author in either syntax.
Modules should be imported using specific revision dates via the 'revision-date' substatement. Without a revision-date, it is undefined from which revision definitions are taken, which can cause inconsistencies between implementations. When an author publishes a new module revision, importers must explicitly update their import statement to accept the changes.
YANG maintains compatibility with SMIv2 to the extent possible; SMIv2-based MIB modules can be automatically translated into YANG modules for read-only access. However, reverse translation from YANG to SMIv2 is out of scope and not supported.
A NETCONF server MUST advertise all revisions of all modules it implements in the <hello> message. Module namespaces are encoded as the base URI, and the module name is encoded as the 'module' parameter.
If a string contains any space or tab characters, a semicolon, braces, or comment sequences, it MUST be enclosed within double or single quotes.
Implementations MUST support identifiers up to 64 characters in length. All identifiers defined in a namespace MUST be unique; identifiers are case sensitive.
Multiple revisions of the same module MUST NOT be imported. When the optional 'revision-date' substatement is absent, it is undefined from which revision definitions are taken.
Namespaces for modules published in RFC streams MUST be assigned by IANA. Names of modules published in RFC streams MUST also be assigned by IANA.
Scoped definitions MUST NOT shadow definitions at a higher scope. A type or grouping cannot be defined if a higher level in the schema hierarchy already has a definition with a matching identifier.
The namespace URI of a YANG module MUST be advertised as a capability in the NETCONF <hello> message. The capability URI MUST follow the form: namespace-uri with optional query parameters for revision, module name, features, and deviations; each named parameter MUST occur at most once.
The optional 'yang-version' statement, if present, MUST contain the value '1', which is the current YANG version. Handling of values other than '1' is out of scope for this specification.
There MUST NOT be any circular chains of imports or includes. A module or submodule MUST NOT include submodules from other modules, and a submodule MUST NOT import its own module.
YANG XPath expressions MUST be syntactically correct, and all prefixes used MUST be present in the XPath context. Clients and servers are not required to implement an XPath interpreter but MUST ensure that the encoded requirements are enforced.
The augment statement inserts additional nodes into a data model hierarchy defined in the same or another module. The when statement can make the augmented nodes conditional, appearing only when an XPath expression evaluates to true. Augmented nodes in XML carry the augmenting module's namespace prefix.
The choice and case statements model mutually exclusive sets of schema nodes. When a node from one case is created, all nodes from all other cases are implicitly deleted by the device. Choice and case nodes appear only in the schema tree, not in XML data or NETCONF messages.
The config statement with value 'false' marks a node's subtree as state data. State data is returned by NETCONF <get> but not by <get-config>, and it cannot be manipulated with <edit-config>. Parent containers, lists, and key leafs of state data are also reported to provide context.
The deviation statement allows a device to declare specific ways it diverges from a module's contract (e.g., a reduced max-elements). Deviations are announced in the NETCONF <hello> via the 'deviations' parameter referencing a module that enumerates the deviations.
The feature and if-feature statements implement an optional-capability mechanism. A module declares named features; portions of the schema tagged with if-feature are only valid on devices that announce support for that feature in the <hello> message 'features' parameter.
The grouping statement defines a reusable set of schema nodes. The uses statement instantiates a grouping and may include refine substatements to override specific properties such as description, default, mandatory, or must constraints in the instantiated copy.
The identity statement defines an abstract, extensible identity with an optional base. The identityref built-in type references a specific identity by its module prefix and name; valid values must be derived from the base identity declared in the type's 'base' statement.
The notification statement models NETCONF notifications. Its child data nodes define the notification's content and are XML-encoded inside the NETCONF <notification> envelope alongside the mandatory <eventTime> element.
The rpc statement models NETCONF RPC operations with optional input and output child containers. The operation maps to NETCONF <rpc> and <rpc-reply> messages; the rpc node's children are XML-encoded as children of the operation element inside the NETCONF envelope.
YANG defines four fundamental data node types: leaf (single value, no children), leaf-list (sequence of uniquely identifiable values), container (child nodes only, no value), and list (multiple instances identified by one or more key leafs). These map directly to XML elements in NETCONF messages.
YANG provides 20 built-in types: integer types (int8/16/32/64, uint8/16/32/64), decimal64, string, boolean, enumeration, bits, binary, leafref, identityref, empty, union, and instance-identifier. Derived types can be created from built-in or other derived types via the typedef statement.
This document registers two MIME media types: 'application/yang' for YANG module text files and 'application/yin+xml' for YIN (the XML encoding of YANG). Both are registered with IANA in Section 14.
YANG data models can expose sensitive configuration and state data via NETCONF. Implementations should leverage existing device access control mechanisms to protect or expose elements of the data model. YANG itself does not define security mechanisms but targets smooth integration with native management infrastructure.
The NETCONF capability URI for a YANG module is formed as: namespace-uri['?'revision=<date>['&'module=<name>]['&'features=<f1,f2,...>]['&'deviations=<d1,d2,...>]]. All YANG modules use UTF-8 character encoding; YANG defines the XML namespace 'urn:ietf:params:xml:ns:yang:1' for <edit-config> operations and <error-info> content.