idnits 2.17.1 draft-bjorklund-netmod-yang-xpath-extensions-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC6020, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == Couldn't figure out when the document was first submitted -- there may comments or warnings related to the use of a disclaimer for pre-RFC5378 work that could not be issued because of this. Please check the Legal Provisions document at https://trustee.ietf.org/license-info to determine if you need the pre-RFC5378 disclaimer. -- The document date (October 18, 2013) is 3841 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'XPATH' -- Possible downref: Non-RFC (?) normative reference: ref. 'XSD-TYPES' Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Bjorklund 3 Internet-Draft Tail-f Systems 4 Updates: 6020 (if approved) October 18, 2013 5 Intended status: Standards Track 6 Expires: April 21, 2014 8 YANG XPath Extensions 9 draft-bjorklund-netmod-yang-xpath-extensions-00 11 Abstract 13 This document introduces new YANG extension statements for defining 14 XPath functions. These functions can be used in XPath expressions in 15 YANG modules and in NETCONF XPath filters. A set of YANG-specific 16 XPath functions are also defined. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on April 21, 2014. 35 Copyright Notice 37 Copyright (c) 2013 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Defining and Using XPath Functions . . . . . . . . . . . . . . 4 54 2.1. Using an XPath Function in YANG . . . . . . . . . . . . . 4 55 2.2. Using an XPath Function in a NETCONF Filter . . . . . . . 5 56 3. XPath Evaluation Context . . . . . . . . . . . . . . . . . . . 6 57 4. XPath Functions . . . . . . . . . . . . . . . . . . . . . . . 7 58 4.1. Function for the YANG Types "leafref" and 59 "instance-identifier" . . . . . . . . . . . . . . . . . . 7 60 4.2. Function for the YANG Type "identityref" . . . . . . . . . 7 61 4.3. Function for the YANG Type "enumeration" . . . . . . . . . 8 62 4.4. Function for the YANG Type "bits" . . . . . . . . . . . . 9 63 4.5. Function for strings . . . . . . . . . . . . . . . . . . . 10 64 5. YANG XPath Extensions Module . . . . . . . . . . . . . . . . . 11 65 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 66 7. Security Considerations . . . . . . . . . . . . . . . . . . . 18 67 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19 68 8.1. Normative References . . . . . . . . . . . . . . . . . . . 19 69 8.2. Informative References . . . . . . . . . . . . . . . . . . 19 70 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 20 72 1. Introduction 74 Experience with YANG [RFC6020] for data modeling has shown that using 75 XPath for specifying constraints is very useful. Unfortunately, 76 since XPath 1.0 has a limited set of data types, and the functions in 77 the core function library only operates on these data types, using 78 XPath 1.0 with other data types is often not possible, unless new 79 XPath functions are defined. 81 This document defines a mechanism to formally define new XPath 82 functions to be used in YANG modules and NETCONF [RFC6241] XPath 83 filters, and introduces a few such XPath functions to be used for the 84 built-in YANG types that cannot be manipulated efficiently with the 85 core XPath functions. 87 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 88 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 89 "OPTIONAL" in this document are to be interpreted as described in BCP 90 14, [RFC2119]. 92 2. Defining and Using XPath Functions 94 A YANG extension statement "xpath-function" is introduced in the YANG 95 module in Section 5. It is used to define the name, input 96 parameters, and return type of an XPath function. For example: 98 module example-module1 { 99 ... 100 import ietf-yang-xpath-extensions { 101 prefix yangxp; 102 } 104 yangxp:xpath-function string-reverse { 105 yangxp:xpath-argument str { 106 yangxp:xpath-type string; 107 } 108 yangxp:xpath-result string; 109 description 110 "This function reverses the string 'str' and returns 111 the resulting string."; 112 } 113 } 115 2.1. Using an XPath Function in YANG 117 When an XPath function defined in a YANG module is used from another 118 module, the module that defines the function is imported, and the 119 function is invoked using the syntax ":", 120 where is the prefix of the imported module. For example: 122 module example-module2 { 123 namespace "http://example.com/example-module2"; 124 ... 125 import example-module1 { 126 prefix ex1; 127 } 128 ... 129 leaf palindrome-of-the-day { 130 type string; 131 must ". = ex1:string-reverse(.)" { 132 error-message "Not a palindrome."; 133 } 134 } 135 } 137 2.2. Using an XPath Function in a NETCONF Filter 139 An XPath function defined in a YANG module can be used in a NETCONF 140 filter by a client if the NETCONF server advertises the :xpath 141 capability, the capability associated with the YANG module 142 "ietf-yang-xpath-extensions", and the capability associated with the 143 module that defines the XPath function. 145 For example, suppose a NETCONF server advertises the following 146 capabilities in its message: 148 150 151 urn:ietf:params:netconf:capability:xpath:1.0 152 153 154 urn:ietf:params:xml:ns:yang:ietf-yang-xpath-extensions? 155 module=ietf-yang-xpath-extensions 156 157 158 http://example.com/example-module2?module=example-module2 159 161 A client can then send the following request to return only 162 interfaces whose names are palindromes: 164 166 167 169 170 172 3. XPath Evaluation Context 174 This document updates the XPath evaluation context for YANG XPath 175 expressions, defined in Section 6.4.1 in [RFC6020] in the following 176 way: 178 o The function library is the core function library defined in 179 [XPATH], and a function "current()" that returns a node set with 180 the initial context node, and all functions defined by the 181 "yangxp:xpath-function" statement in the current module, all 182 included submodules, and all imported modules. Functions defined 183 by "yangxp:xpath-function" are referenced as ": 184 ", where is the prefix of the module that 185 defines . 187 4. XPath Functions 189 This document defines four YANG type-specific XPath functions, and 190 one generic XPath function. The functions are formally defined in 191 Section 5. 193 4.1. Function for the YANG Types "leafref" and "instance-identifier" 195 The function "deref" returns a node-set containing the node that a 196 node of type "leafref" or "instance-identifier" refers to. For 197 example: 199 list interface { 200 key name; 201 leaf name { ... } 202 leaf enabled { 203 type boolean; 204 } 205 ... 206 } 208 leaf mgmt-interface { 209 type leafref { 210 path "/interface/name"; 211 } 212 must 'yangxp:deref(.)/../enabled = "true"' { 213 error-message 214 "The management interface cannot be disabled."; 215 } 216 } 218 4.2. Function for the YANG Type "identityref" 220 The function "derived-from" checks if a node of type "identityref" is 221 derived from a given identity. For example: 223 module example-interface { 224 ... 226 identity interface-type; 228 identity ethernet { 229 base interface-type; 230 } 232 identity fast-ethernet { 233 base ethernet; 234 } 236 identity gigabit-ethernet { 237 base ethernet; 238 } 240 list interface { 241 key name; 242 ... 243 leaf type { 244 type identityref { 245 base interface-type; 246 } 247 } 248 ... 249 } 251 augment "/interface" { 252 when 'yangxp:derived-from(type, 253 "example-interface", 254 "ethernet")'; 255 // ethernet-specific definitions here 256 } 257 } 259 4.3. Function for the YANG Type "enumeration" 261 The function "enum-value" returns the integer value associated with a 262 node of type "enumeration". For example, with this data model: 264 list alarm { 265 ... 266 leaf severity { 267 type enumeration { 268 enum cleared { 269 value 1; 270 } 271 enum indeterminate { 272 value 2; 273 } 274 enum minor { 275 value 3; 276 } 277 enum warning { 278 value 4; 279 } 280 enum major { 281 value 5; 282 } 283 enum critical { 284 value 6; 285 } 286 } 287 } 288 } 290 the following XPath expression selects only alarms that are of 291 severity "major" or higher: 293 /alarm[yangxp:enum-value(severity) >= 5] 295 4.4. Function for the YANG Type "bits" 297 The function "bit-is-set" checks if a node of type "bits" have a 298 given bit set. For example, if an interface has this leaf: 300 leaf flags { 301 type bits { 302 bit UP; 303 bit PROMISCUOUS 304 bit DISABLED; 305 } 306 } 308 the following XPath expression can be used to select all interfaces 309 with the UP flag set: 311 /interface[bit-is-set(flags, "UP")] 313 4.5. Function for strings 315 The function "re-match" checks if a string matches a given regular 316 expression. The regular expressions used are the XML Schema regular 317 expressions [XSD-TYPES]. Note that this includes implicit anchoring 318 of the regular expression at the head and tail. For example: 320 re-match('1.22.333', '\d{1,3}\.\d{1,3}\.\d{1,3}') 322 returns true. 324 To count all logical interfaces called eth0., do: 326 count(/interface[re-match(name,'eth0\.\d+')]) 328 5. YANG XPath Extensions Module 330 RFC Ed.: update the date below with the date of RFC publication and 331 remove this note. 333 file "ietf-yang-xpath-extensions@2013-10-18.yang" 335 module ietf-yang-xpath-extensions { 337 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-xpath-extensions"; 338 prefix "yangxp"; 340 organization 341 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 343 contact 344 "WG Web: 345 WG List: 347 WG Chair: David Kessens 348 350 WG Chair: Juergen Schoenwaelder 351 353 Editor: Martin Bjorklund 354 "; 356 description 357 "This module contains a collection of YANG extensions 358 for defining XPath functions to be used in XPath 359 expressions in YANG modules and NETCONF filters. 361 Copyright (c) 2013 IETF Trust and the persons identified as 362 authors of the code. All rights reserved. 364 Redistribution and use in source and binary forms, with or 365 without modification, is permitted pursuant to, and subject 366 to the license terms contained in, the Simplified BSD License 367 set forth in Section 4.c of the IETF Trust's Legal Provisions 368 Relating to IETF Documents 369 (http://trustee.ietf.org/license-info). 371 This version of this YANG module is part of RFC XXXX; see 372 the RFC itself for full legal notices."; 374 // RFC Ed.: replace XXXX with actual RFC number and remove this 375 // note. 377 // RFC Ed.: update the date below with the date of RFC publication 378 // and remove this note. 379 revision 2013-10-18 { 380 description 381 "Initial revision."; 382 reference 383 "RFC XXXX: YANG XPath Extensions"; 384 } 386 /* 387 * Extensions 388 */ 390 extension xpath-function { 391 argument name; 392 description 393 "This statement introduces an XPath function that can be 394 used in 'must' and 'when' XPath expression in YANG modules, 395 and in NETCONF filters. 397 The statement's argument specifies the name of the XPath 398 function. 400 When the function is used in a YANG module, the module where 401 the function is defined MUST be imported. The function is 402 referred to using the syntax ':', where 403 is the prefix of the module, and is the name of the 404 XPath function. 406 The following substatements are used: 408 +-----------------------+-------------+ 409 | substatement | cardinality | 410 +-----------------------+-------------+ 411 | yangxp:xpath-argument | 0..n | 412 | yangxp:xpath-result | 1 | 413 | description | 0..1 | 414 | reference | 0..1 | 415 +-----------------------+-------------+ 417 The yangxp:xpath-argument statement defines the arguments to 418 the XPath function. The functions takes the arguments in the 419 order they are defined in the YANG module."; 420 } 422 extension xpath-argument { 423 argument name; 424 description 425 "This statement defines an argument to an XPath function. 427 The statement's argument specifies the name of the XPath 428 function's argument. The mandatory substatement 429 yangxp:xpath-type defines the type of the argument. 431 The following substatements are used: 433 +-----------------------+-------------+ 434 | substatement | cardinality | 435 +-----------------------+-------------+ 436 | yangxp:xpath-type | 1 | 437 +-----------------------+-------------+"; 438 } 440 extension xpath-type { 441 argument type-name; 442 description 443 "This statement defines the type of the parent statement's 444 XPath object. 446 The statement's argument is one of the strings: 447 'node-set', 'number', 'string', or 'boolean'."; 448 } 450 extension xpath-result { 451 argument type; 452 description 453 "This statement defines the type of the XPath function's 454 return value. 456 The statement's argument is one of the strings: 457 'node-set', 'number', 'string', or 'boolean'."; 458 } 460 /* 461 * XPath functions 462 */ 464 /* Function for leafref and instance-identifier */ 466 yangxp:xpath-function deref { 467 yangxp:xpath-argument nodes { 468 yangxp:xpath-type node-set; 469 } 470 yangxp:xpath-result node-set; 471 description 472 "The deref() function follows the reference defined by the 473 first node in document order in the argument 'nodes', and 474 returns the nodes it refers to. 476 If the first argument node is of type instance-identifier, 477 the function returns a node-set that contains the single node 478 that the instance identifier refers to, if it exists. If no 479 such node exists, an empty node-set is returned. 481 If the first argument node is of type leafref, the function 482 returns a node-set that contains the nodes that the leafref 483 refers to. 485 If the first argument node is of any other type, an empty 486 node-set is returned."; 487 reference 488 "RFC 6020: YANG, Section 9.9 and Section 9.13."; 489 } 491 /* Function for identityref */ 493 yangxp:xpath-function derived-from { 494 yangxp:xpath-argument nodes { 495 yangxp:xpath-type node-set; 496 } 497 yangxp:xpath-argument module-name { 498 yangxp:xpath-type string; 499 } 500 yangxp:xpath-argument identity-name { 501 yangxp:xpath-type string; 502 } 503 yangxp:xpath-result boolean; 504 description 505 "The derived-from() function returns true if the first node in 506 document order in the argument 'nodes' is a node of type 507 identityref, and its value is an identity that is derived from 508 the identity 'identity-name' defined in the YANG 509 'module-name'; otherwise it returns false."; 510 reference 511 "RFC 6020: YANG, Section 9.10."; 512 } 514 /* Function for enumeration */ 516 yangxp:xpath-function enum-value { 517 yangxp:xpath-argument nodes { 518 yangxp:xpath-type node-set; 519 } 520 yangxp:xpath-result number; 521 description 522 "The enum-value() function checks if the first node in 523 document order in the argument 'nodes' is a node of type 524 enumeration, and returns the enum's integer value. If the 525 'nodes' node-set is empty, or if the first node 'nodes' is 526 not of type enumeration, it returns NaN."; 527 reference 528 "RFC 6020: YANG, Section 9.6.4.2."; 529 } 531 /* Function for bits */ 533 yangxp:xpath-function bit-is-set { 534 yangxp:xpath-argument nodes { 535 yangxp:xpath-type node-set; 536 } 537 yangxp:xpath-argument bit-name { 538 yangxp:xpath-type string; 539 } 540 yangxp:xpath-result boolean; 541 description 542 "The bit-is-set() function returns true if the first node in 543 document order in the argument 'nodes' is a node of type 544 bits, and its value has the bit 'bit-name' set; otherwise 545 it returns false."; 546 reference 547 "RFC 6020: YANG, Section 9.7.4."; 548 } 550 /* String function */ 552 yangxp:xpath-function re-match { 553 yangxp:xpath-argument subject { 554 yangxp:xpath-type string; 555 } 556 yangxp:xpath-argument pattern { 557 yangxp:xpath-type string; 558 } 559 yangxp:xpath-result boolean; 560 description 561 "The re-match() function returns true if the 'subject' string 562 matches the regular expression 'pattern'; otherwise it 563 returns false. 565 The regular expressions used are the XML Schema regular 566 expressions."; 568 reference 569 "http://www.w3.org/TR/xmlschema-2/#regexs"; 570 } 572 } 574 576 6. IANA Considerations 578 This document registers a URI in the IETF XML registry [RFC3688]. 579 Following the format in RFC 3688, the following registration is 580 requested to be made. 582 URI: urn:ietf:params:xml:ns:yang:ietf-yang-xpath-extensions 584 Registrant Contact: The NETMOD WG of the IETF. 586 XML: N/A, the requested URI is an XML namespace. 588 This document registers a YANG module in the YANG Module Names 589 registry [RFC6020]. 591 name: ietf-yang-xpath-extensions 592 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-xpath-extensions 593 prefix: yangxp 594 reference: RFC XXXX 596 7. Security Considerations 598 This document defines a formal mechanism for defining XPath functions 599 in YANG data models, and has no security impact on the Internet. 601 8. References 603 8.1. Normative References 605 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 606 Requirement Levels", BCP 14, RFC 2119, March 1997. 608 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 609 Network Configuration Protocol (NETCONF)", RFC 6020, 610 October 2010. 612 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 613 and A. Bierman, Ed., "Network Configuration Protocol 614 (NETCONF)", RFC 6241, June 2011. 616 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 617 Version 1.0", World Wide Web Consortium 618 Recommendation REC-xpath-19991116, November 1999, 619 . 621 [XSD-TYPES] 622 Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes 623 Second Edition", World Wide Web Consortium 624 Recommendation REC-xmlschema-2-20041028, October 2004, 625 . 627 8.2. Informative References 629 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 630 January 2004. 632 Author's Address 634 Martin Bjorklund 635 Tail-f Systems 637 Email: mbj@tail-f.com