Network Working Group                                       M. Bjorklund
Internet-Draft                                            Tail-f Systems
Updates: 6020 (if approved)                             October 18, 2013
Intended status: Standards Track
Expires: April 21, 2014


                         YANG XPath Extensions
            draft-bjorklund-netmod-yang-xpath-extensions-00

Abstract

   This document introduces new YANG extension statements for defining
   XPath functions.  These functions can be used in XPath expressions in
   YANG modules and in NETCONF XPath filters.  A set of YANG-specific
   XPath functions are also defined.

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 April 21, 2014.

Copyright Notice

   Copyright (c) 2013 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.



Bjorklund                Expires April 21, 2014                 [Page 1]


Internet-Draft            YANG XPath Extensions             October 2013


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
   2.  Defining and Using XPath Functions . . . . . . . . . . . . . .  4
     2.1.  Using an XPath Function in YANG  . . . . . . . . . . . . .  4
     2.2.  Using an XPath Function in a NETCONF Filter  . . . . . . .  5
   3.  XPath Evaluation Context . . . . . . . . . . . . . . . . . . .  6
   4.  XPath Functions  . . . . . . . . . . . . . . . . . . . . . . .  7
     4.1.  Function for the YANG Types "leafref" and
           "instance-identifier"  . . . . . . . . . . . . . . . . . .  7
     4.2.  Function for the YANG Type "identityref" . . . . . . . . .  7
     4.3.  Function for the YANG Type "enumeration" . . . . . . . . .  8
     4.4.  Function for the YANG Type "bits"  . . . . . . . . . . . .  9
     4.5.  Function for strings . . . . . . . . . . . . . . . . . . . 10
   5.  YANG XPath Extensions Module . . . . . . . . . . . . . . . . . 11
   6.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 17
   7.  Security Considerations  . . . . . . . . . . . . . . . . . . . 18
   8.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 19
     8.1.  Normative References . . . . . . . . . . . . . . . . . . . 19
     8.2.  Informative References . . . . . . . . . . . . . . . . . . 19
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 20






























Bjorklund                Expires April 21, 2014                 [Page 2]


Internet-Draft            YANG XPath Extensions             October 2013


1.  Introduction

   Experience with YANG [RFC6020] for data modeling has shown that using
   XPath for specifying constraints is very useful.  Unfortunately,
   since XPath 1.0 has a limited set of data types, and the functions in
   the core function library only operates on these data types, using
   XPath 1.0 with other data types is often not possible, unless new
   XPath functions are defined.

   This document defines a mechanism to formally define new XPath
   functions to be used in YANG modules and NETCONF [RFC6241] XPath
   filters, and introduces a few such XPath functions to be used for the
   built-in YANG types that cannot be manipulated efficiently with the
   core XPath functions.

   The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in BCP
   14, [RFC2119].
































Bjorklund                Expires April 21, 2014                 [Page 3]


Internet-Draft            YANG XPath Extensions             October 2013


2.  Defining and Using XPath Functions

   A YANG extension statement "xpath-function" is introduced in the YANG
   module in Section 5.  It is used to define the name, input
   parameters, and return type of an XPath function.  For example:

     module example-module1 {
         ...
         import ietf-yang-xpath-extensions {
             prefix yangxp;
         }

         yangxp:xpath-function string-reverse {
             yangxp:xpath-argument str {
                 yangxp:xpath-type string;
             }
             yangxp:xpath-result string;
             description
                 "This function reverses the string 'str' and returns
                  the resulting string.";
         }
     }

2.1.  Using an XPath Function in YANG

   When an XPath function defined in a YANG module is used from another
   module, the module that defines the function is imported, and the
   function is invoked using the syntax "<prefix>:<function-name>",
   where <prefix> is the prefix of the imported module.  For example:

     module example-module2 {
         namespace "http://example.com/example-module2";
         ...
         import example-module1 {
             prefix ex1;
         }
         ...
         leaf palindrome-of-the-day {
             type string;
             must ". = ex1:string-reverse(.)" {
                 error-message "Not a palindrome.";
             }
         }
     }







Bjorklund                Expires April 21, 2014                 [Page 4]


Internet-Draft            YANG XPath Extensions             October 2013


2.2.  Using an XPath Function in a NETCONF Filter

   An XPath function defined in a YANG module can be used in a NETCONF
   filter by a client if the NETCONF server advertises the :xpath
   capability, the capability associated with the YANG module
   "ietf-yang-xpath-extensions", and the capability associated with the
   module that defines the XPath function.

   For example, suppose a NETCONF server advertises the following
   capabilities in its <hello> message:

     <!-- lines wrapped for display purposes only -->

     <capability>
       urn:ietf:params:netconf:capability:xpath:1.0
     </capability>
     <capability>
       urn:ietf:params:xml:ns:yang:ietf-yang-xpath-extensions?
          module=ietf-yang-xpath-extensions
     </capability>
     </capability>
       http://example.com/example-module2?module=example-module2
     </capability>

   A client can then send the following request to return only
   interfaces whose names are palindromes:

     <rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
          message-id="1">
       <get xmlns:ex2="http://example.com/example-module2">
         <filter type="xpath"
                 select="/interface[name = ex2:reverse(name)]"/>
       </get>
     </rpc>

















Bjorklund                Expires April 21, 2014                 [Page 5]


Internet-Draft            YANG XPath Extensions             October 2013


3.  XPath Evaluation Context

   This document updates the XPath evaluation context for YANG XPath
   expressions, defined in Section 6.4.1 in [RFC6020] in the following
   way:

   o  The function library is the core function library defined in
      [XPATH], and a function "current()" that returns a node set with
      the initial context node, and all functions defined by the
      "yangxp:xpath-function" statement in the current module, all
      included submodules, and all imported modules.  Functions defined
      by "yangxp:xpath-function" are referenced as "<prefix>:
      <function-name>", where <prefix> is the prefix of the module that
      defines <function-name>.





































Bjorklund                Expires April 21, 2014                 [Page 6]


Internet-Draft            YANG XPath Extensions             October 2013


4.  XPath Functions

   This document defines four YANG type-specific XPath functions, and
   one generic XPath function.  The functions are formally defined in
   Section 5.

4.1.  Function for the YANG Types "leafref" and "instance-identifier"

   The function "deref" returns a node-set containing the node that a
   node of type "leafref" or "instance-identifier" refers to.  For
   example:

     list interface {
         key name;
         leaf name { ... }
         leaf enabled {
             type boolean;
         }
         ...
     }

     leaf mgmt-interface {
         type leafref {
             path "/interface/name";
         }
         must 'yangxp:deref(.)/../enabled = "true"' {
             error-message
                 "The management interface cannot be disabled.";
         }
     }

4.2.  Function for the YANG Type "identityref"

   The function "derived-from" checks if a node of type "identityref" is
   derived from a given identity.  For example:
















Bjorklund                Expires April 21, 2014                 [Page 7]


Internet-Draft            YANG XPath Extensions             October 2013


     module example-interface {
         ...

         identity interface-type;

         identity ethernet {
             base interface-type;
         }

         identity fast-ethernet {
             base ethernet;
         }

         identity gigabit-ethernet {
             base ethernet;
         }

         list interface {
             key name;
             ...
             leaf type {
                 type identityref {
                     base interface-type;
                 }
             }
             ...
         }

         augment "/interface" {
             when 'yangxp:derived-from(type,
                                       "example-interface",
                                       "ethernet")';
             // ethernet-specific definitions here
         }
     }

4.3.  Function for the YANG Type "enumeration"

   The function "enum-value" returns the integer value associated with a
   node of type "enumeration".  For example, with this data model:











Bjorklund                Expires April 21, 2014                 [Page 8]


Internet-Draft            YANG XPath Extensions             October 2013


     list alarm {
         ...
         leaf severity {
             type enumeration {
                 enum cleared {
                     value 1;
                 }
                 enum indeterminate {
                     value 2;
                 }
                 enum minor {
                     value 3;
                 }
                 enum warning {
                     value 4;
                 }
                 enum major {
                     value 5;
                 }
                 enum critical {
                     value 6;
                 }
             }
         }
     }

   the following XPath expression selects only alarms that are of
   severity "major" or higher:

     /alarm[yangxp:enum-value(severity) >= 5]

4.4.  Function for the YANG Type "bits"

   The function "bit-is-set" checks if a node of type "bits" have a
   given bit set.  For example, if an interface has this leaf:

     leaf flags {
         type bits {
             bit UP;
             bit PROMISCUOUS
             bit DISABLED;
         }
      }

   the following XPath expression can be used to select all interfaces
   with the UP flag set:

     /interface[bit-is-set(flags, "UP")]



Bjorklund                Expires April 21, 2014                 [Page 9]


Internet-Draft            YANG XPath Extensions             October 2013


4.5.  Function for strings

   The function "re-match" checks if a string matches a given regular
   expression.  The regular expressions used are the XML Schema regular
   expressions [XSD-TYPES].  Note that this includes implicit anchoring
   of the regular expression at the head and tail.  For example:

     re-match('1.22.333', '\d{1,3}\.\d{1,3}\.\d{1,3}')

   returns true.

   To count all logical interfaces called eth0.<number>, do:

     count(/interface[re-match(name,'eth0\.\d+')])





































Bjorklund                Expires April 21, 2014                [Page 10]


Internet-Draft            YANG XPath Extensions             October 2013


5.  YANG XPath Extensions Module

   RFC Ed.: update the date below with the date of RFC publication and
   remove this note.

   <CODE BEGINS> file "ietf-yang-xpath-extensions@2013-10-18.yang"

   module ietf-yang-xpath-extensions {

     namespace "urn:ietf:params:xml:ns:yang:ietf-yang-xpath-extensions";
     prefix "yangxp";

     organization
       "IETF NETMOD (NETCONF Data Modeling Language) Working Group";

     contact
       "WG Web:   <http://tools.ietf.org/wg/netmod/>
        WG List:  <mailto:netmod@ietf.org>

        WG Chair: David Kessens
                  <mailto:david.kessens@nsn.com>

        WG Chair: Juergen Schoenwaelder
                  <mailto:j.schoenwaelder@jacobs-university.de>

        Editor:   Martin Bjorklund
                  <mailto:mbj@tail-f.com>";

     description
       "This module contains a collection of YANG extensions
        for defining XPath functions to be used in XPath
        expressions in YANG modules and NETCONF filters.

        Copyright (c) 2013 IETF Trust and the persons identified as
        authors of the code.  All rights reserved.

        Redistribution and use in source and binary forms, with or
        without modification, is permitted pursuant to, and subject
        to the license terms contained in, the Simplified BSD License
        set forth in Section 4.c of the IETF Trust's Legal Provisions
        Relating to IETF Documents
        (http://trustee.ietf.org/license-info).

        This version of this YANG module is part of RFC XXXX; see
        the RFC itself for full legal notices.";

     // RFC Ed.: replace XXXX with actual RFC number and remove this
     // note.



Bjorklund                Expires April 21, 2014                [Page 11]


Internet-Draft            YANG XPath Extensions             October 2013


     // RFC Ed.: update the date below with the date of RFC publication
     // and remove this note.
     revision 2013-10-18 {
       description
         "Initial revision.";
       reference
         "RFC XXXX: YANG XPath Extensions";
     }

     /*
      * Extensions
      */

     extension xpath-function {
       argument name;
       description
         "This statement introduces an XPath function that can be
          used in 'must' and 'when' XPath expression in YANG modules,
          and in NETCONF filters.

          The statement's argument specifies the name of the XPath
          function.

          When the function is used in a YANG module, the module where
          the function is defined MUST be imported.  The function is
          referred to using the syntax '<prefix>:<name>', where <prefix>
          is the prefix of the module, and <name> is the name of the
          XPath function.

          The following substatements are used:

            +-----------------------+-------------+
            | substatement          | cardinality |
            +-----------------------+-------------+
            | yangxp:xpath-argument | 0..n        |
            | yangxp:xpath-result   | 1           |
            | description           | 0..1        |
            | reference             | 0..1        |
            +-----------------------+-------------+

          The yangxp:xpath-argument statement defines the arguments to
          the XPath function.  The functions takes the arguments in the
          order they are defined in the YANG module.";
     }

     extension xpath-argument {
       argument name;
       description



Bjorklund                Expires April 21, 2014                [Page 12]


Internet-Draft            YANG XPath Extensions             October 2013


         "This statement defines an argument to an XPath function.

          The statement's argument specifies the name of the XPath
          function's argument.  The mandatory substatement
          yangxp:xpath-type defines the type of the argument.

          The following substatements are used:

            +-----------------------+-------------+
            | substatement          | cardinality |
            +-----------------------+-------------+
            | yangxp:xpath-type     | 1           |
            +-----------------------+-------------+";
     }

     extension xpath-type {
       argument type-name;
       description
         "This statement defines the type of the parent statement's
          XPath object.

          The statement's argument is one of the strings:
          'node-set', 'number', 'string', or 'boolean'.";
     }

     extension xpath-result {
       argument type;
       description
         "This statement defines the type of the XPath function's
          return value.

          The statement's argument is one of the strings:
          'node-set', 'number', 'string', or 'boolean'.";
     }

     /*
      * XPath functions
      */

     /* Function for leafref and instance-identifier */

     yangxp:xpath-function deref {
       yangxp:xpath-argument nodes {
         yangxp:xpath-type node-set;
       }
       yangxp:xpath-result node-set;
       description
         "The deref() function follows the reference defined by the



Bjorklund                Expires April 21, 2014                [Page 13]


Internet-Draft            YANG XPath Extensions             October 2013


          first node in document order in the argument 'nodes', and
          returns the nodes it refers to.

          If the first argument node is of type instance-identifier,
          the function returns a node-set that contains the single node
          that the instance identifier refers to, if it exists. If no
          such node exists, an empty node-set is returned.

          If the first argument node is of type leafref, the function
          returns a node-set that contains the nodes that the leafref
          refers to.

          If the first argument node is of any other type, an empty
          node-set is returned.";
       reference
         "RFC 6020: YANG, Section 9.9 and Section 9.13.";
     }

     /* Function for identityref */

     yangxp:xpath-function derived-from {
       yangxp:xpath-argument nodes {
         yangxp:xpath-type node-set;
       }
       yangxp:xpath-argument module-name {
         yangxp:xpath-type string;
       }
       yangxp:xpath-argument identity-name {
         yangxp:xpath-type string;
       }
       yangxp:xpath-result boolean;
       description
         "The derived-from() function returns true if the first node in
          document order in the argument 'nodes' is a node of type
          identityref, and its value is an identity that is derived from
          the identity 'identity-name' defined in the YANG
          'module-name'; otherwise it returns false.";
       reference
         "RFC 6020: YANG, Section 9.10.";
     }

     /* Function for enumeration */

     yangxp:xpath-function enum-value {
       yangxp:xpath-argument nodes {
         yangxp:xpath-type node-set;
       }
       yangxp:xpath-result number;



Bjorklund                Expires April 21, 2014                [Page 14]


Internet-Draft            YANG XPath Extensions             October 2013


       description
         "The enum-value() function checks if the first node in
          document order in the argument 'nodes' is a node of type
          enumeration, and returns the enum's integer value.  If the
          'nodes' node-set is empty, or if the first node 'nodes' is
          not of type enumeration, it returns NaN.";
       reference
         "RFC 6020: YANG, Section 9.6.4.2.";
     }

     /* Function for bits */

     yangxp:xpath-function bit-is-set {
       yangxp:xpath-argument nodes {
         yangxp:xpath-type node-set;
       }
       yangxp:xpath-argument bit-name {
         yangxp:xpath-type string;
       }
       yangxp:xpath-result boolean;
       description
         "The bit-is-set() function returns true if the first node in
          document order in the argument 'nodes' is a node of type
          bits, and its value has the bit 'bit-name' set; otherwise
          it returns false.";
       reference
         "RFC 6020: YANG, Section 9.7.4.";
     }

     /* String function */

     yangxp:xpath-function re-match {
       yangxp:xpath-argument subject {
         yangxp:xpath-type string;
       }
       yangxp:xpath-argument pattern {
         yangxp:xpath-type string;
       }
       yangxp:xpath-result boolean;
       description
         "The re-match() function returns true if the 'subject' string
          matches the regular expression 'pattern'; otherwise it
          returns false.

          The regular expressions used are the XML Schema regular
          expressions.";

       reference



Bjorklund                Expires April 21, 2014                [Page 15]


Internet-Draft            YANG XPath Extensions             October 2013


         "http://www.w3.org/TR/xmlschema-2/#regexs";
     }

   }

   <CODE ENDS>













































Bjorklund                Expires April 21, 2014                [Page 16]


Internet-Draft            YANG XPath Extensions             October 2013


6.  IANA Considerations

   This document registers a URI in the IETF XML registry [RFC3688].
   Following the format in RFC 3688, the following registration is
   requested to be made.

        URI: urn:ietf:params:xml:ns:yang:ietf-yang-xpath-extensions

        Registrant Contact: The NETMOD WG of the IETF.

        XML: N/A, the requested URI is an XML namespace.

   This document registers a YANG module in the YANG Module Names
   registry [RFC6020].

     name:        ietf-yang-xpath-extensions
     namespace:   urn:ietf:params:xml:ns:yang:ietf-yang-xpath-extensions
     prefix:      yangxp
     reference:   RFC XXXX
































Bjorklund                Expires April 21, 2014                [Page 17]


Internet-Draft            YANG XPath Extensions             October 2013


7.  Security Considerations

   This document defines a formal mechanism for defining XPath functions
   in YANG data models, and has no security impact on the Internet.















































Bjorklund                Expires April 21, 2014                [Page 18]


Internet-Draft            YANG XPath Extensions             October 2013


8.  References

8.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC6020]  Bjorklund, M., "YANG - A Data Modeling Language for the
              Network Configuration Protocol (NETCONF)", RFC 6020,
              October 2010.

   [RFC6241]  Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
              and A. Bierman, Ed., "Network Configuration Protocol
              (NETCONF)", RFC 6241, June 2011.

   [XPATH]    Clark, J. and S. DeRose, "XML Path Language (XPath)
              Version 1.0", World Wide Web Consortium
              Recommendation REC-xpath-19991116, November 1999,
              <http://www.w3.org/TR/1999/REC-xpath-19991116>.

   [XSD-TYPES]
              Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes
              Second Edition", World Wide Web Consortium
              Recommendation REC-xmlschema-2-20041028, October 2004,
              <http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.

8.2.  Informative References

   [RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
              January 2004.





















Bjorklund                Expires April 21, 2014                [Page 19]


Internet-Draft            YANG XPath Extensions             October 2013


Author's Address

   Martin Bjorklund
   Tail-f Systems

   Email: mbj@tail-f.com













































Bjorklund                Expires April 21, 2014                [Page 20]