Schema Annotation for YANG Models

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 . In some cases there is a need to qualify other YANG models or some schema nodes in other models with additional properties (a.k.a. annotations). This document defines a method to add annotations in the form of YANG extension statements to YANG modules. The annotations are defined in separate files without modifying the text of the original YANG module. Annotations are often specific to the model and/or implementation so they are possible to define in design time. System integrators, people defining configuration ahead of time and others need this information (without reading any data from a live node). Often the basic YANG model and the extra properties are defined separately, possibly by different organizations. Vendors may qualify standard models with extra properties, or even a vendor defined base model, may need different annotations depending on the specific implementation. Vendors are reluctant to modify the standard models (messing up the original file, too many variants of the base model), so it must be possible to define such annotations in a separate file/module.

In YangPush we need to specify for data nodes whether the Yang server supports sending on-change data change notifications for the specific data node or not. Some servers may not support such notifications for specific data nodes because they are meaningless or would result in too many notifications or the server might simply not have implemented them. The support for on-change notifications will be defined using a YANG extension statement. In some cases there is a need to specify the minimum acceptable interval for a periodic subscription for a specific data node or schema branch.

Vendors sometimes want to add extra information to the standard YANG models. Examples include instructions for automatic code generation or formal description of side-effects of manipulating a data node. It would be good for standard SW tools to be at least aware of the vendor extensions, allowing vendor specific plugins to handle these extensions. By providing a standard mechanism to annotate modules generic SW tools might provide somevisibility to vendor specific extensions e.g. providing APIs to fetch the extension, displaying the extension as is.

All solution alternatives use an Absolute schema node identifier to identify which part of the YANG schema is annotated. Absolute schema node identifier is defined in . All alternatives will have the same effect as if the YANG extension statement in the annotation was placed in the base model itself. The process of annotation will consist of the following steps. A base model will be defined. E.g. IETF defined a standard base model like ietf-system. A vendor will define extra data like instance data or annotation/deviation YANG modules (e.g. ericsson-system-ann-router1230-release3.yang). Annotation information MAY be defined once per vendor or for every product/product release separately. Annotation information will be available both in design-time as a document and in run-time.

A new YANG module containing information about schema-annotations is defined and a standard way of loading initial instance data in to that module is specified. (Note the module is only an example to demonstrate the concept. If the solution is selected, further work on the module is needed.)

A standard format to specify initial instance data for a YANG module in a file is defined. The format SHALL be the same as the XML content of the <edit-config> operation inside the <config> element. The <edit-config> format was chosen as that will allow specifying the operation attribute. Both the merge and the replace values might be needed and/or useful. If the instance data represents configuration data it SHALL be loaded by the YANG server at startup into the running datastore of the server before any management interface like CLI, Netconf, Restconf is started. Note this MAY result in overwriting data previously stored in the datastore. If the instance data represents state data it SHALL be loaded by the YANG server at startup into the operation-state datastore before any management interface like CLI, Netconf, Restconf is started. Example:

/sys:system/sys:system-time yp:notifiable-on-change false ]]> Instance data for the module ietf-schema-annotations SHOULD become a design time artifact provided by the model designer just as the YANG modules themselves. The XML instance data defining the annotations would be available in design-time as an XML document and in run-time using the <get> operation.

A new YANG extension "schema-annotation" is defined, that allows adding statement to another module.

The annotating module would be available in design-time as a document and in run-time using the <get-schema> operation.

Deviations already allow adding/modifying model information for another module. If IETF would allow the "deviate" statement to handle YANG extension statements this would allow us to add/remove/modify annotations.

The Instance Data based Solution is the proposed solution. It could be usable for other purposes as well including but not restricted to defining default security rules for access control or defining yang-schema-mounts in design time. It is more simple to read in runtime for management systems (MS). If annotation data was ever changed the MS could get notifications about that. It could easily be linked with references to the ietf-yang-library It introduces a bigger new concept (instance data) although a number of vendors are already using it. The Extension Based Solution works. We do not recommend using the Deviation based Solution as deviations are for documenting unwelcome implementation limitations and are highly discouraged. Adding our extra information is not just acceptable, it is the recommended thing to do. Extending the allowed substatements for the deviate statement can also be considered changing .

defines metadata on the instance data level, here we need metadata on the model/schema level. metadata is transferred in Netconf/Restconf RPCs, here we usually do not need that. metadata is only available in runtime, here we need it to be available in design time.

Set of statements that can be the target. The initial proposal is to allow the same set of schema nodes as "deviation" statement. Is that OK? Set of statements that can be added. The initial proposal allows only YANG extension statements. Do we want to allow anything else like additional "must" statements or restrictions? Probably not as that would allow redefining the base model, which we don't want. We only want to add information to it. Exact data model for module ietf-schema-annotations. Do we need replace and delete operations beside the add? The initial proposal only allows adding annotations. Do we need to be able to replace and remove them as well?

The author wishes to thank Eric Voit, Einar Nilsen-Nygaard and Alexander Clemm for their helpful comments contributing to this draft.

No IANA considerations

This document introduces a mechanism for attaching metadata defined in the form of YANG extensions to the YANG schema of another YANG module. By itself, this mechanism represents no security threat. Security implications of a particular extension and attaching it to a particular YANG module shall be considered in the document defining/attaching the extension.