Internet DRAFT - draft-lengyel-netmod-schema-annotation
draft-lengyel-netmod-schema-annotation
Netmod B. Lengyel
Internet-Draft Ericsson
Intended status: Standards Track January 24, 2017
Expires: July 28, 2017
Schema Annotation for YANG Models
draft-lengyel-netmod-schema-annotation-00
Abstract
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.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on July 28, 2017.
Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
Lengyel Expires July 28, 2017 [Page 1]
Internet-Draft Yang Schema Annotation January 2017
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Use Case - Yangpush . . . . . . . . . . . . . . . . . . . 3
1.2. Use Case - Vendor Annotation of a Standard Model . . . . 3
2. Possible solutions . . . . . . . . . . . . . . . . . . . . . 3
2.1. Instance Data based Solution . . . . . . . . . . . . . . 4
2.2. Extension based Solution . . . . . . . . . . . . . . . . 5
2.3. Deviation based Solution . . . . . . . . . . . . . . . . 6
2.4. Pros and Cons . . . . . . . . . . . . . . . . . . . . . . 6
3. How is this different from RFC7952 "Defining and Using
Metadata with YANG?" . . . . . . . . . . . . . . . . . . . . 7
4. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 7
5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
7. Security Considerations . . . . . . . . . . . . . . . . . . . 8
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 8
8.1. Normative References . . . . . . . . . . . . . . . . . . 8
8.2. Informative References . . . . . . . . . . . . . . . . . 8
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9
1. Introduction
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 [RFC2119].
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 [RFC7950] 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),
Lengyel Expires July 28, 2017 [Page 2]
Internet-Draft Yang Schema Annotation January 2017
so it must be possible to define such annotations in a separate file/
module.
1.1. Use Case - Yangpush
In YangPush [I-D.ietf-netconf-yang-push] 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.
1.2. Use Case - Vendor Annotation of a Standard Model
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.
2. Possible solutions
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 [RFC7950].
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.
Lengyel Expires July 28, 2017 [Page 3]
Internet-Draft Yang Schema Annotation January 2017
2.1. Instance Data based Solution
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.)
module ietf-schema-annotations {
list schema-annotations {
key target;
config false;
leaf target {
type schema-node-id;
description "identifies the node in the schema tree
that is annotated.";
}
list annotation {
key statement;
min-elements 1;
leaf statement {
type yang:yang-identifier;
description "The statement to be conceptually
added to the target schema node.";
}
leaf argument {
type string;
description "Argument to the annotation
statement if any.";
}
}
}
}
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-
Lengyel Expires July 28, 2017 [Page 4]
Internet-Draft Yang Schema Annotation January 2017
state datastore before any management interface like CLI, Netconf,
Restconf is started.
Example:
<model-annotations xmlns:...>
<target xmlns:sys=...>/sys:system/sys:system-time</target>
<annotation>
<statement xmlns:yp=...>yp:notifiable-on-change</statement>
<argument>false</argument>
</annotation>
</model-annotations>
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.
2.2. Extension based Solution
A new YANG extension "schema-annotation" is defined, that allows
adding statement to another module.
Lengyel Expires July 28, 2017 [Page 5]
Internet-Draft Yang Schema Annotation January 2017
extension schema-annotation {
description
"Annotates an existing statement with a YANG extension
statement defined in some module. Useful for
adding extension statements to a module without touching the
module source.
Substatements to this statements are conceptually added
to the target statement.
The argument is a 'absolute schema node identifier'.
It identifies a target node in the schema tree to
annotate with new statements.";
argument target;
}
Example:
sann:schema-annotation /sys:system/sys:system-time {
yp:notifiable-on-change false;
}
The annotating module would be available in design-time as a document
and in run-time using the <get-schema> operation.
2.3. Deviation based Solution
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.
2.4. Pros and Cons
The Instance Data based Solution is the proposed solution.
o It could be usable for other purposes as well including but not
restricted to defining default security rules for access control
[RFC6536] or defining yang-schema-mounts
[I-D.ietf-netmod-schema-mount] in design time.
o It is more simple to read in runtime for management systems (MS).
o If annotation data was ever changed the MS could get notifications
about that.
Lengyel Expires July 28, 2017 [Page 6]
Internet-Draft Yang Schema Annotation January 2017
o It could easily be linked with references to the ietf-yang-library
o 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 [RFC7950].
3. How is this different from RFC7952 "Defining and Using Metadata with
YANG?"
[RFC7952] defines metadata on the instance data level, here we need
metadata on the model/schema level.
[RFC7952] metadata is transferred in Netconf/Restconf RPCs, here we
usually do not need that.
[RFC7952] metadata is only available in runtime, here we need it to
be available in design time.
4. Open Issues
o 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?
o 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.
o Exact data model for module ietf-schema-annotations.
o 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?
Lengyel Expires July 28, 2017 [Page 7]
Internet-Draft Yang Schema Annotation January 2017
5. Acknowledgements
The author wishes to thank Eric Voit, Einar Nilsen-Nygaard and
Alexander Clemm for their helpful comments contributing to this
draft.
6. IANA Considerations
No IANA considerations
7. Security 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.
8. References
8.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration
Protocol (NETCONF) Access Control Model", RFC 6536,
DOI 10.17487/RFC6536, March 2012,
<http://www.rfc-editor.org/info/rfc6536>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016,
<http://www.rfc-editor.org/info/rfc7950>.
[RFC7952] Lhotka, L., "Defining and Using Metadata with YANG",
RFC 7952, DOI 10.17487/RFC7952, August 2016,
<http://www.rfc-editor.org/info/rfc7952>.
8.2. Informative References
[I-D.ietf-netconf-yang-push]
Clemm, A., Voit, E., Prieto, A., Tripathy, A., Nilsen-
Nygaard, E., Bierman, A., and B. Lengyel, "Subscribing to
YANG datastore push updates", draft-ietf-netconf-yang-
push-04 (work in progress), October 2016.
Lengyel Expires July 28, 2017 [Page 8]
Internet-Draft Yang Schema Annotation January 2017
[I-D.ietf-netmod-schema-mount]
Bjorklund, M. and L. Lhotka, "YANG Schema Mount", draft-
ietf-netmod-schema-mount-03 (work in progress), October
2016.
Author's Address
Balazs Lengyel
Ericsson
Email: balazs.lengyel@ericsson.com
Lengyel Expires July 28, 2017 [Page 9]
