NETMOD Working Group
INTERNET-DRAFT Anil Kumar S N
Intended Status: Standards Track Gaurav Agrawal
Vinod Kumar S
Huawei Technologies
Expires: January 1, 2017 June 30, 2016
YANG compiler annotation for data structure and inheritance
draft-agv-netmod-yang-annotation-ds-and-derived-00
Abstract
This document defines two new YANG compiler annotations as per draft-
agv-netmod-yang-compiler-metadata-00. First annotation is used to
define the data structure type to be generated corresponding to a
schema node. Second annotation is used to generate a user defined
inherited class corresponding to a schema node in which user can
override the default implementation.
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 January 1, 2017
AGV Expires January 1, 2017 [Page 1]
INTERNET DRAFT Data Structure Selection & Inheritance June 30, 2016
Copyright and License Notice
Copyright (c) 2016 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
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.2 Terms Defined in Other Documents . . . . . . . . . . . . . . 4
2.4 Definitions of New Terms . . . . . . . . . . . . . . . . . . 5
3. Defining @app-data-structure compiler annotations in YANG . . 5
3.1 Example usage . . . . . . . . . . . . . . . . . . . . . . . 5
4 Defining @app-derived compiler annotations in YANG . . . . . . . 6
4.1 Example usage . . . . . . . . . . . . . . . . . . . . . . . 6
5 Security Considerations . . . . . . . . . . . . . . . . . . . . 7
6 IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . 7
8 References . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
8.1 Normative References . . . . . . . . . . . . . . . . . . . . 8
8.2 Informative References . . . . . . . . . . . . . . . . . . . 8
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 9
AGV Expires January 1, 2017 [Page 2]
INTERNET DRAFT Data Structure Selection & Inheritance June 30, 2016
1 Introduction
YANG defines single instance data structure as container or leaf and
multi instance data structure as a list or leaf-list. Mapping of the
YANG single instance constructs to a programming data structure is
straight forward, it can be directly mapped to an object or an
entity.
Mapping of the YANG multi instance construct to a programming data
structure has many option, since it is a collection or objects /
entities. Depending on the application use case and development
environment, it will have other requirements to be considered for
mapping it to a data structure. For example it needs to be optimized
for storage or it need to be optimized for search efficiency or it
may be required to have multiple key combinations for search. Based
on this, we can see that there is no single option to be used by YANG
utilities / compilers to auto generate the code corresponding to a
multi instance construct.
Applications use the YANG to document the external interface
designed. Applications need to design the alternatives for data
structure and choose that is best suited for them. This is part of
typical software engineering activity used by application. YANG
utilities / compilers need to get these design related details to
automate the code generation as per application design. To support
this a new YANG compiler annotation @app-data-structure is defined.
Applications need to extend the auto generated code to suit their
needs, The external world communication using protocol like NETCONF /
RESTONF can be automated by automating the code generation based on
the YANG structure. Applications have additional business logic to be
taken care, wherein they need to extend the generated code. When
applications extends or modifies the generated code, YANG utilities
are unaware of it, and will not be able to correctly update the auto
generated files when the schema changes. In such scenarios, the YANG
utilities / compilers generated code needs to be provide a framework
wherein application can extend the default auto-generated
implementation provided by the utilities which is not impacted even
if YANG utilities / compilers auto generates files for changed
schema. To support this a new YANG compiler annotation @app-derived
is defined.
AGV Expires January 1, 2017 [Page 3]
INTERNET DRAFT Data Structure Selection & Inheritance June 30, 2016
2 Terminology
2.1 Keywords
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 RFC 2119 [RFC2119].
2.2 Terms Defined in Other Documents
The following terms are defined in [RFC6241]:
o capability,
o client,
o datastore,
o message,
o protocol operation,
o server.
The following terms are defined in [I-D.ietf-netmod-rfc6020bis]:
o action,
o anydata,
o anyxml,
o built-in type,
o container,
o data model,
o data node,
o data tree,
o derived type,
o extension,
o leaf,
AGV Expires January 1, 2017 [Page 4]
INTERNET DRAFT Data Structure Selection & Inheritance June 30, 2016
o leaf-list,
o list,
o module,
o RPC input and output.
2.4 Definitions of New Terms
o @app-data-structure: annotations for type of data structure to
be generated for multi instance YANG construct.
o @app-derived: annotation for derived class to be generated for
extending the generated class.
3. Defining @app-data-structure compiler annotations in YANG
@app-data-structure annotation is used to define the data
structure to be used for the corresponding multi-instance
YANG construct.
It has the following parameter.
o data-structure: Its value will specify the data structure
to be used for code generation. It is a mandatory parameter.
o key-fields: This is used to specify the space separated list
of key fields. This is not applicable for leaf-list YANG
construct, it is optional parameter. If it is not defined,
the list's key fields will be used to index the data structure.
3.1 Example usage
Application instructs to use a map data structure for maintaining
servers information.
list server {
ca:compiler-annotation{
@app-data-structure(data-structure="map", key="name");
}
key "name";
unique "ip port";
leaf name {
type string;
}
leaf ip {
AGV Expires January 1, 2017 [Page 5]
INTERNET DRAFT Data Structure Selection & Inheritance June 30, 2016
type inet:ip-address;
}
leaf port {
type inet:port-number;
}
}
4 Defining @app-derived compiler annotations in YANG
@app-derived is used to generate an inherited class, which can be
used by the applications to extend/override the default
implementations of application interface. It has the following
parameter.
o extended-name: It is used to generate the extended class, which can
be used by application for implementation. This is a mandatory
parameter.
4.1 Example usage
Application instructs to generate an inherited class for
implementation.
list server {
ca:compiler-annotation{
@app-data-structure(data-structure="map", key="name");
@app-derived(extended-name=special-server);
}
key "name";
unique "ip port";
leaf name {
type string;
}
leaf ip {
type inet:ip-address;
}
leaf port {
type inet:port-number;
}
}
AGV Expires January 1, 2017 [Page 6]
INTERNET DRAFT Data Structure Selection & Inheritance June 30, 2016
5 Security Considerations
This document introduces two annotations for defining compiler
metadata in YANG modules and attaching them to instances of YANG
schema nodes. By itself, this mechanism represents no security
threat.
6 IANA Considerations
No specific IANA considerations for this document
7. Acknowledgments
AGV Expires January 1, 2017 [Page 7]
INTERNET DRAFT Data Structure Selection & Inheritance June 30, 2016
8 References
8.1 Normative References
[I-D.ietf-netmod-rfc6020bis]
Bjorklund, M., "The YANG 1.1 Data Modeling Language",
draft-ietf-netmod-rfc6020bis-11 (work in progress),
February 2016.
[I-D.ietf-netmod-yang-json]
Lhotka, L., "JSON Encoding of Data Modeled with YANG",
draft-ietf-netmod-yang-json-09 (work in progress), March
2016.
[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>.
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
the Network Configuration Protocol (NETCONF)", RFC 6020,
DOI 10.17487/RFC6020, October 2010,
<http://www.rfc-editor.org/info/rfc6020>.
[RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch,
"Network Time Protocol Version 4: Protocol and Algorithms
Specification", RFC 5905, June 2010.
8.2 Informative References
[I-D.ietf-netconf-restconf]
Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", draft-ietf-netconf-restconf-10 (work in
progress), March 2016.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
and A. Bierman, Ed., "Network Configuration Protocol
(NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
<http://www.rfc-editor.org/info/rfc6241>.
AGV Expires January 1, 2017 [Page 8]
INTERNET DRAFT Data Structure Selection & Inheritance June 30, 2016
Authors' Addresses
Anil Kumar S N
Huawei Technologies India Pvt. Ltd,
Near EPIP Industrial Area,
Kundalahalli Village,
Whitefield,
Bangalore - 560037
EMail: anil.ietf@gmail.com
Gaurav Agrawal
Huawei Technologies India Pvt. Ltd,
Near EPIP Industrial Area,
Kundalahalli Village,
Whitefield,
Bangalore - 560037
EMail: gaurav.agrawal@huawei.com
Vinod Kumar S
Huawei Technologies India Pvt. Ltd,
Near EPIP Industrial Area,
Kundalahalli Village,
Whitefield,
Bangalore - 560037
EMail: vinods.kumar@huawei.com
AGV Expires January 1, 2017 [Page 9]