[Docs] [txt|pdf] [Tracker] [Email] [Nits]

Versions: 00

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]


Html markup produced by rfcmarkup 1.123, available from https://tools.ietf.org/tools/rfcmarkup/