Defining and Using Metadata with YANG
updates
- rfc-6110 — Mapping YANG to Document Schema Definition Languages and Validating NETCONF Content
Extracted elements (25)
A new built-in YANG statement for annotations was considered but rejected as too major a change for YANG 1.1, which was chartered as a maintenance revision. The extension mechanism was chosen instead, with the possibility of a built-in statement in a future YANG revision.
Annotations are restricted to scalar values only, and cannot be attached to a whole list or leaf-list (only to individual entries). This deliberate restriction preserves compatibility with XML encoding of YANG data nodes and limitations of XML attributes.
Defining annotations in YANG modules was chosen so each annotation is bound to a namespace URI (enabling consistent XML/JSON encoding), annotations are discoverable via YANG module advertisement (e.g., NETCONF hello), and semantics are formally specified via 'description' and 'reference' statements.
XML attributes were chosen as the natural encoding for metadata in XML instance documents. For JSON, a special encoding using '@'-prefixed member names was introduced because JSON has no established convention for metadata, while remaining consistent with RFC 7951 YANG-JSON encoding.
Annotations sent by a server should not break clients that do not support them. Safe use cases include: annotations that are integral to a negotiated capability, auxiliary non-critical annotations, or annotations explicitly requested by the client via a protocol operation parameter.
This document updates RFC 6110 by specifying how the DSDL mapping procedure is modified to handle 'md:annotation' statements, enabling validation of XML instance documents that contain metadata annotations.
A client MUST NOT add a specific annotation to data node instances if the server did not advertise the YANG module defining that annotation. Servers advertise support via NETCONF hello or YANG library.
An annotation MUST NOT change the data tree semantics defined by YANG. For example, it is illegal to define an annotation that overrides the uniqueness of leaf-list entries.
For XML encoding: the local name of the attribute SHALL be the annotation name; the namespace SHALL be identified by the module's namespace URI; and the attribute value SHALL be encoded as a YANG leaf instance of the same type.
In DSDL mapping, each 'md:annotation' definition MUST be mapped to an optional RELAX NG attribute pattern inserted as a child of the named metadata pattern, with the attribute name using the module's prefix.
The semantics and usage rules for an annotation SHOULD be fully specified in 'description', 'reference', and 'units' statements. A module containing 'md:annotation' SHOULD NOT define data nodes or groupings.
The 'type' substatement MUST be present in every 'md:annotation' statement, and the value of the annotation MUST match that type. Any YANG built-in or derived type usable for leaf or leaf-list nodes is permitted.
The value of a metadata annotation in JSON SHALL be encoded in exactly the same way as the value of a YANG leaf node having the same type, as specified in RFC 7951 Section 6.
For DSDL schema mapping, if the data model contains at least one 'md:annotation' statement, a RELAX NG named pattern (recommended name '__yang_metadata__') MUST be added as a child of the root grammar element, and a reference to it MUST appear in every element pattern for anydata, container, leaf, leaf-list, or list nodes.
Substatements of 'md:annotation' are: 'type' (cardinality 1, mandatory), 'description' (0..1), 'if-feature' (0..n), 'reference' (0..1), 'status' (0..1), and 'units' (0..1). All are standard YANG statements.
The 'md:annotation' YANG extension, defined in module 'ietf-yang-metadata', is the mechanism for declaring metadata annotations. It appears only at the top level of a YANG module and takes an annotation name as its argument, inheriting the module's namespace.
This document registers the URI 'urn:ietf:params:xml:ns:yang:ietf-yang-metadata' in the IANA 'IETF XML Registry' (RFC 3688) as an XML namespace for the ietf-yang-metadata module.
This document registers the YANG module 'ietf-yang-metadata' in the IANA 'YANG Module Names' registry (RFC 6020), with namespace 'urn:ietf:params:xml:ns:yang:ietf-yang-metadata' and prefix 'md'.
An annotation SHOULD be subject to the same or stricter access control rules as the data node instance to which it is attached. Security-sensitive or privacy-sensitive data is RECOMMENDED to be modeled as regular YANG data nodes rather than annotations.
The annotation mechanism itself poses no security threat, but the security implications of any particular annotation MUST be duly considered and documented in the annotation's definition.
For anyxml and leaf instances in JSON, the metadata object is added as a sibling member named '@' concatenated with the member name being annotated (e.g., '@foo:flag'). The namespace prefix is included if and only if it appears in the annotated member's name.
For leaf-list entries in JSON, a sibling array named '@' + leaf-list-name is added; its i-th element is the metadata object for the i-th leaf-list entry, or null if that entry has no annotations. Trailing null values MAY be omitted.
In JSON encoding, all annotations for a data node instance are collected into a single metadata object. For containers, list entries, and anydata nodes (encoded as JSON objects), the metadata object is added as the member named '@'.
In XML encoding, annotations are encoded as XML attributes on the data node element. The attribute's local name is the annotation name, its namespace URI is the defining module's namespace, and its value is encoded as a YANG leaf value of the same type.
The JSON annotation name inside the metadata object uses the ABNF form 'module-name:annotation-name', where the module name serves as the explicit namespace identifier. Unlike YANG data node members, the module name is always required for annotations.