Defining and Using Metadata with YANGCZ.NIClhotka@nic.czmetadata annotationsYANG extensionThis document defines a YANG extension that allows for
defining metadata annotations in YANG modules. The document also
specifies XML and JSON encoding of annotations and other rules
for annotating instances of YANG data nodes.There is a need to be able to annotate instances of
YANG data nodes with metadata. Typical
use cases are as follows:
Complementing regular data model information with
instance&nbhy;specific metadata, comments, etc.Providing information about the rendering of data in user
interfaces.Deactivating a subtree in a configuration datastore while
keeping the data in place.Network management protocols often use metadata annotations
for various purposes in both operation requests and
responses. For example, the <edit-config> operation in
the Network Configuration Protocol (NETCONF) (see Section 7.2 of
) uses annotations in the form of XML
attributes for identifying the location in a configuration
datastore and the type of the operation.However, metadata annotations could potentially lead to
interoperability problems if they are used in an ad hoc fashion
by different parties and/or without proper documentation. A
sound metadata framework for YANG should therefore satisfy these
requirements:
The set of annotations must be extensible in a
decentralized manner so as to allow for defining new
annotations without running the risk of collisions with
annotations defined and used by others.The syntax and semantics of annotations must be documented, and
the documentation must be easily accessible.Clients of network management protocols such as
NETCONF or
RESTCONF must be able to discover
all annotations supported by a given server and identify each
of them correctly.Annotations sent by a server should not break clients that
don't support them.This document proposes a systematic way to define metadata
annotations. For this purpose, the YANG extension
"annotation" is defined in the module "ietf-yang-metadata"
(). Other YANG modules
importing this module can use the "annotation" statement for
defining one or more annotations.The benefits of defining the metadata annotations in a YANG
module are the following:
Each annotation is bound to a YANG module name and
namespace URI. This makes its encoding in instance documents
(both XML and JSON) straightforward and consistent with the
encoding of YANG data node instances.Annotations defined in IETF Standards Track documents are
indirectly registered through IANA in the "YANG Module Names"
registry .Annotations are included in the data model. YANG compilers
and tools supporting a certain annotation can thus take them
into account and modify their behavior accordingly.The semantics of an annotation are defined in the "description"
and "reference" statements.An annotation can be declared as conditional by using the
"if&nbhy;feature" statement.The type of each annotation is explicitly specified; any
YANG built-in or derived type that is available for leaf or
leaf-list data nodes may be specified for annotations as
well.In the XML encoding, XML attributes are a natural instrument
for attaching annotations to data node instances. This document
deliberately adopts some restrictions in order to remain
compatible with the XML encoding of YANG data node instances and
limitations of XML attributes. Specifically,
annotations can only be scalar values.annotations cannot be attached to a whole list or leaf-list
instance, only to individual list or leaf-list entries.Due to the rules for YANG extensions (see Section 6.3.1
in ), annotation definitions posit
relatively weak conformance requirements. The alternative
of introducing a new built-in YANG statement for defining
annotations was considered, but it was seen as a major change to
the language that is inappropriate for YANG 1.1, which was
chartered as a maintenance revision. After evaluating real-life
usage of metadata annotations, it is conceivable that such a new
built-in statement might be added in a future revision of
YANG.The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
"SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described
in .The following terms are defined in :
capabilityclientdatastoremessageprotocol operationserverThe following terms are defined in :
actionanydataanyxmlbuilt-in typecontainerdata modeldata nodedata treederived typeextensionleafleaf-listlistmoduleRemote Procedure Call (RPC) input and outputThe following terms are defined in :
attributedocumentelementThe following terms are defined in :
local namenamespace nameprefixqualified nameThe following terms are defined in :
arraymemberobjectprimitive typeIn the following text, XML element names and YANG extension
statements are always written with explicit namespace prefixes
that are assumed to be bound to URI references as shown in .PrefixURI Referenceelmhttp://example.org/example-last-modifiedmdurn:ietf:params:xml:ns:yang:ietf-yang-metadatarnghttp://relaxng.org/ns/structure/1.0annotation: a single item of metadata that is attached to
YANG data node instances.metadata: additional information that complements a data
tree.metadata object: an object in JSON encoding that contains
all annotations attached to a given data node instance.Metadata annotations are defined by the YANG extension
"md:annotation". This YANG language extension is defined in the
module "ietf-yang-metadata" ().Substatements of "md:annotation" are shown in . They are all core YANG statements, and
the numbers in the second column refer to the corresponding
section in where each
statement is described.substatementsection in RFC 7950cardinalitydescription7.21.30..1if-feature7.20.20..nreference7.21.40..1status7.21.20..1type7.6.31units7.3.30..1An annotation carries a single value. The "type" substatement,
which MUST be present, takes as an argument the name of an
existing built&nbhy;in or derived type, and the value of the
annotation MUST match this type. See Section 7.4
of for details.An annotation can be made conditional by using one or more
"if&nbhy;feature" statements; the annotation is then supported only
by servers that advertise the corresponding feature.The semantics and usage rules for an annotation SHOULD be
fully specified in "description", "reference", and "units"
statements.An annotation MUST NOT change the data tree semantics defined
by YANG. For example, it is illegal to define and use an
annotation that allows for overriding uniqueness of leaf-list
entries.The "status" statement can be used exactly as it is used for
YANG data nodes.A YANG module containing one or more "md:annotation"
statements SHOULD NOT be used for defining data nodes
or groupings. Also, derived types, identities, and features
SHOULD NOT be defined in such a module unless they are used by
the definitions of annotations in that module.The following module defines the "last-modified"
annotation:By advertising a YANG module in which a metadata annotation
is defined using the "md:annotation" statement, a server
indicates that it is prepared to handle that annotation
according to the annotation's definition. That is, an
annotation advertised by the server may be attached to an
instance of a data node defined in any YANG module that is
implemented by the server.Depending on its semantics, an annotation may have an effect
only in certain data trees and/or on instances of specific types
of data nodes.A client MUST NOT add a specific annotation to data node
instances if the server didn't advertise it.Due care has to be exercised when introducing annotations in
network management systems in order to avoid interoperability
problems and software failures caused by a client that does not
understand the annotations' semantics. Generally, it is safe for
a server to use annotations in the following cases:
An annotation is an integral part of a built-in or
negotiated protocol capability.An annotation contains auxiliary information that is not
critical for protocol operation.The client explicitly asks the server, e.g., via a
parameter of a protocol operation request, to include an
annotation in the response.XML attributes are a natural choice for encoding metadata in
XML instance documents. For JSON , there
is no generally established method for encoding metadata. This
document thus introduces a special encoding method that is
consistent with the JSON encoding of YANG data node instances as
defined in .Metadata annotations are added to XML-encoded instances of
YANG data nodes as XML attributes according to these rules:
The local name of the attribute SHALL be the same as the
name of the annotation specified in the argument of the
corresponding "md:annotation" statement.The namespace of the attribute SHALL be identified by the
URI that appears as the argument of the "namespace"
statement in the YANG module where the annotation is
defined. It is RECOMMENDED that the prefix specified by the
"prefix" statement in the same module be used in the
qualified name of the attribute.The attribute value SHALL be encoded in the same way as
the value of a YANG leaf instance having the same type;
see Section 9 of .For example, the "last-modified" annotation defined
in may be encoded as follows:The JSON metadata encoding defined in this section has the
following properties:
The encoding of YANG data node instances as defined in
does not change.Namespaces of metadata annotations are encoded in the same
way as namespaces of YANG data node instances; see .All metadata annotations assigned to a YANG data node
instance are encoded as members (name/value pairs) of a
single JSON object, henceforth denoted as the metadata
object. The placement and name of this object depend on the
type of the data node as specified in the following
subsections.The name of a metadata annotation (as a member of the
metadata object) has the following ABNF syntax , where the production for "identifier" is
defined in Section 14 of :
where the left identifier is the name of the YANG module in
which the annotation is defined and the identifier on the
right is the name of the annotation specified in the
argument of the corresponding "md:annotation" statement.Note that unlike member names of YANG data node instances
in JSON encoding (see Section 4 in ),
for annotations the explicit namespace identifier (module name)
must always be present.The value of a metadata annotation SHALL be encoded in
exactly the same way as the value of a YANG leaf node having
the same type as the annotation;
see Section 6 of .For a data node instance that is encoded as a JSON object
(i.e., a container, list entry, or anydata node), the
metadata object is added as a new member of that object with
the name "@".Examples:
"cask" is a container or anydata node:
"seq" is a list whose key is "name"; annotation
"last-modified" is added only to the first entry:
For an anyxml or leaf instance, the metadata object is
added as a sibling name/value pair whose name is the symbol
"@" concatenated with the name of the leaf or anyxml member
that is being annotated. The namespace part (module name) is
included if and only if it is in the name of the annotated
member.Examples:
"flag" is a leaf node of the "boolean" type defined in
module "foo", and we assume that the namespace name has to be
expressed in its JSON encoding:
"stuff" is an anyxml node:
For a leaf-list entry, which is represented as a JSON
array with values of a primitive type, annotations may be
assigned to one or more entries by adding a name/array pair
as a sibling of the leaf&nbhy;list entry, where the name is
the symbol "@" concatenated with the name of the leaf-list that
is being annotated, and the value is a JSON array whose i-th
element is the metadata object with annotations assigned to
the i-th entry of the leaf-list entry, or null if the i-th
entry has no annotations.Trailing null values in that array, i.e., those following
the last non-null metadata object, MAY be omitted.For example, in the following leaf-list instance with
four entries, the "last-modified" annotation is added to the
second and third entries in the following way:
defines the standard mapping of YANG
data models to Document Schema Definition Languages (DSDL) . This section specifies the mapping for
the extension statement "md:annotation" (), which enables validation of XML
instance documents containing metadata annotations.The first step of the DSDL mapping procedure, i.e., the
transformation of the YANG data model to the hybrid schema (see
Section 6 in ), is modified as follows:
If the data model contains at least one
"md:annotation" statement, then a RELAX NG
named pattern definition MUST be
added as a child of the root <rng:grammar> element in the
hybrid schema. It is RECOMMENDED to use the name
"__yang_metadata__" for this named pattern.A reference to the named pattern described
in item MUST be
included as a child of every <rng:element> pattern that
corresponds to an anydata, container, leaf, leaf-list, or list
data node.Every metadata annotation definition in the form
is mapped to the following RELAX NG
pattern:
where PREFIX is the prefix bound to the namespace URI of the
YANG module that contains the "md:annotation" statement. The
above pattern SHALL be inserted as a child of the named
pattern described in item .Substatements of "md:annotation" SHALL be mapped to
children of the "rng:attribute" pattern exactly as described
in Section 10 of .For example, the named pattern (item ), when constructed only for the
"last-modified" annotation, will have the following
definition:Every "rng:element" pattern that corresponds to an anydata,
container, leaf, list, or leaf-list data node will then contain a
reference to the above named pattern; for example:Note that it is not necessary to use such a reference for
"rng:element" patterns corresponding to anyxml data nodes
because they already permit any XML attributes to be attached to
their instances.The second step of the DSDL mapping procedure, i.e., the
transformation of the hybrid schema to RELAX NG
, Schematron ,
and Document Semantics Renaming Language (DSRL)
schemas, is unaffected by the
inclusion of "md:annotation".This document registers a URI in the "IETF XML Registry"
. Following the format in RFC 3688, the
following registration has been made.This document registers a YANG module in the "YANG Module
Names" registry .This document introduces a mechanism for defining metadata
annotations in YANG modules and attaching them to instances of
YANG data nodes. By itself, this mechanism represents no
security threat. Security implications of a particular
annotation defined using this mechanism MUST be duly
considered and documented in the annotation's definition.An annotation SHOULD be subject to the same or stricter
access control rules as the data node instance to which the
annotation is attached. It is RECOMMENDED that
security-sensitive or privacy-sensitive data be modeled as
regular YANG data nodes rather than annotations.The YANG 1.1 Data Modeling LanguageJSON Encoding of Data Modeled with YANGXML Information Set (Second Edition)Namespaces in XML 1.0 (Third Edition)
Information Technology - Document Schema Definition Languages (DSDL) - Part 1: Overview
International Organization for Standardization
Information technology -- Document Schema Definition Language (DSDL) -- Part
2: Regular-grammar-based validation -- RELAX NG
International Organization for Standardization
Information technology -- Document Schema Definition Languages (DSDL) -- Part
3: Rule-based validation -- Schematron
International Organization for StandardizationInformation Technology - Document Schema Definition
Languages (DSDL) - Part 8: Document Semantics Renaming
Language - DSRLInternational Organization for StandardizationRESTCONF ProtocolThe author wishes to thank Andy Bierman, Martin Bjorklund,
Benoit Claise, Juergen Schoenwaelder, and Kent Watsen for their
helpful comments and suggestions.