idnits 2.17.1 draft-ietf-netmod-dsdl-map-10.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 21, 2010) is 4930 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. 'DSDL' -- Possible downref: Non-RFC (?) normative reference: ref. 'DSRL' ** Obsolete normative reference: RFC 4741 (Obsoleted by RFC 6241) ** Obsolete normative reference: RFC 6021 (Obsoleted by RFC 6991) -- Possible downref: Non-RFC (?) normative reference: ref. 'RNG' -- Possible downref: Non-RFC (?) normative reference: ref. 'RNG-CS' -- Possible downref: Non-RFC (?) normative reference: ref. 'RNG-DTD' -- Possible downref: Non-RFC (?) normative reference: ref. 'Schematron' -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' -- Possible downref: Non-RFC (?) normative reference: ref. 'XML-INFOSET' -- Possible downref: Non-RFC (?) normative reference: ref. 'XPath' -- Possible downref: Non-RFC (?) normative reference: ref. 'XSD-D' -- Possible downref: Non-RFC (?) normative reference: ref. 'XSLT' Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 12 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETMOD L. Lhotka, Ed. 3 Internet-Draft CESNET 4 Intended status: Standards Track October 21, 2010 5 Expires: April 24, 2011 7 Mapping YANG to Document Schema Definition Languages and Validating 8 NETCONF Content 9 draft-ietf-netmod-dsdl-map-10 11 Abstract 13 This document specifies the mapping rules for translating YANG data 14 models into Document Schema Definition Languages (DSDL), a 15 coordinated set of XML schema languages standardized as ISO/IEC 16 19757. The following DSDL schema languages are addressed by the 17 mapping: RELAX NG, Schematron and DSRL. The mapping takes one or 18 more YANG modules and produces a set of DSDL schemas for a selected 19 target document type - datastore content, NETCONF message etc. 20 Procedures for schema-based validation of such documents are also 21 discussed. 23 Status of this Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on April 24, 2011. 40 Copyright Notice 42 Copyright (c) 2010 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 58 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 8 59 2.1. Glossary of New Terms . . . . . . . . . . . . . . . . . 11 60 3. Objectives and Motivation . . . . . . . . . . . . . . . . . . 12 61 4. DSDL Schema Languages . . . . . . . . . . . . . . . . . . . . 14 62 4.1. RELAX NG . . . . . . . . . . . . . . . . . . . . . . . . 14 63 4.2. Schematron . . . . . . . . . . . . . . . . . . . . . . . 15 64 4.3. Document Semantics Renaming Language (DSRL) . . . . . . 16 65 5. Additional Annotations . . . . . . . . . . . . . . . . . . . 17 66 5.1. Dublin Core Metadata Elements . . . . . . . . . . . . . 17 67 5.2. RELAX NG DTD Compatibility Annotations . . . . . . . . . 17 68 5.3. NETMOD-Specific Annotations . . . . . . . . . . . . . . 18 69 6. Overview of the Mapping . . . . . . . . . . . . . . . . . . . 20 70 7. NETCONF Content Validation . . . . . . . . . . . . . . . . . 22 71 8. Design Considerations . . . . . . . . . . . . . . . . . . . . 23 72 8.1. Hybrid Schema . . . . . . . . . . . . . . . . . . . . . 23 73 8.2. Modularity . . . . . . . . . . . . . . . . . . . . . . . 25 74 8.3. Granularity . . . . . . . . . . . . . . . . . . . . . . 27 75 8.4. Handling of XML Namespaces . . . . . . . . . . . . . . . 27 76 9. Mapping YANG Data Models to the Hybrid Schema . . . . . . . . 29 77 9.1. Occurrence Rules for Data Nodes . . . . . . . . . . . . 29 78 9.1.1. Optional and Mandatory Nodes . . . . . . . . . . . 30 79 9.1.2. Implicit Nodes . . . . . . . . . . . . . . . . . . 31 80 9.2. Mapping YANG Groupings and Typedefs . . . . . . . . . . 32 81 9.2.1. YANG Refinements and Augments . . . . . . . . . . . 33 82 9.2.2. Type Derivation Chains . . . . . . . . . . . . . . 36 83 9.3. Translation of XPath Expressions . . . . . . . . . . . . 38 84 9.4. YANG Language Extensions . . . . . . . . . . . . . . . . 39 85 10. Mapping YANG Statements to the Hybrid Schema . . . . . . . . 41 86 10.1. The 'anyxml' Statement . . . . . . . . . . . . . . . . . 41 87 10.2. The 'argument' Statement . . . . . . . . . . . . . . . . 42 88 10.3. The 'augment' Statement . . . . . . . . . . . . . . . . 43 89 10.4. The 'base' Statement . . . . . . . . . . . . . . . . . . 43 90 10.5. The 'belongs-to' Statement . . . . . . . . . . . . . . . 43 91 10.6. The 'bit' Statement . . . . . . . . . . . . . . . . . . 43 92 10.7. The 'case' Statement . . . . . . . . . . . . . . . . . . 43 93 10.8. The 'choice' Statement . . . . . . . . . . . . . . . . . 43 94 10.9. The 'config' Statement . . . . . . . . . . . . . . . . . 44 95 10.10. The 'contact' Statement . . . . . . . . . . . . . . . . 44 96 10.11. The 'container' Statement . . . . . . . . . . . . . . . 44 97 10.12. The 'default' Statement . . . . . . . . . . . . . . . . 44 98 10.13. The 'description' Statement . . . . . . . . . . . . . . 46 99 10.14. The 'deviation' Statement . . . . . . . . . . . . . . . 46 100 10.15. The 'enum' Statement . . . . . . . . . . . . . . . . . . 46 101 10.16. The 'error-app-tag' Statement . . . . . . . . . . . . . 46 102 10.17. The 'error-message' Statement . . . . . . . . . . . . . 46 103 10.18. The 'extension' Statement . . . . . . . . . . . . . . . 46 104 10.19. The 'feature' Statement . . . . . . . . . . . . . . . . 46 105 10.20. The 'grouping' Statement . . . . . . . . . . . . . . . . 46 106 10.21. The 'identity' Statement . . . . . . . . . . . . . . . . 47 107 10.22. The 'if-feature' Statement . . . . . . . . . . . . . . . 48 108 10.23. The 'import' Statement . . . . . . . . . . . . . . . . . 49 109 10.24. The 'include' Statement . . . . . . . . . . . . . . . . 49 110 10.25. The 'input' Statement . . . . . . . . . . . . . . . . . 49 111 10.26. The 'key' Statement . . . . . . . . . . . . . . . . . . 49 112 10.27. The 'leaf' Statement . . . . . . . . . . . . . . . . . . 49 113 10.28. The 'leaf-list' Statement . . . . . . . . . . . . . . . 50 114 10.29. The 'length' Statement . . . . . . . . . . . . . . . . . 50 115 10.30. The 'list' Statement . . . . . . . . . . . . . . . . . . 51 116 10.31. The 'mandatory' Statement . . . . . . . . . . . . . . . 52 117 10.32. The 'max-elements' Statement . . . . . . . . . . . . . . 52 118 10.33. The 'min-elements' Statement . . . . . . . . . . . . . . 52 119 10.34. The 'module' Statement . . . . . . . . . . . . . . . . . 52 120 10.35. The 'must' Statement . . . . . . . . . . . . . . . . . . 53 121 10.36. The 'namespace' Statement . . . . . . . . . . . . . . . 53 122 10.37. The 'notification' Statement . . . . . . . . . . . . . . 54 123 10.38. The 'ordered-by' Statement . . . . . . . . . . . . . . . 54 124 10.39. The 'organization' Statement . . . . . . . . . . . . . . 54 125 10.40. The 'output' Statement . . . . . . . . . . . . . . . . . 54 126 10.41. The 'path' Statement . . . . . . . . . . . . . . . . . . 54 127 10.42. The 'pattern' Statement . . . . . . . . . . . . . . . . 54 128 10.43. The 'position' Statement . . . . . . . . . . . . . . . . 55 129 10.44. The 'prefix' Statement . . . . . . . . . . . . . . . . . 55 130 10.45. The 'presence' Statement . . . . . . . . . . . . . . . . 55 131 10.46. The 'range' Statement . . . . . . . . . . . . . . . . . 55 132 10.47. The 'reference' Statement . . . . . . . . . . . . . . . 55 133 10.48. The 'require-instance' Statement . . . . . . . . . . . . 55 134 10.49. The 'revision' Statement . . . . . . . . . . . . . . . . 55 135 10.50. The 'rpc' Statement . . . . . . . . . . . . . . . . . . 55 136 10.51. The 'status' Statement . . . . . . . . . . . . . . . . . 56 137 10.52. The 'submodule' Statement . . . . . . . . . . . . . . . 56 138 10.53. The 'type' Statement . . . . . . . . . . . . . . . . . . 56 139 10.53.1. The "empty" Type . . . . . . . . . . . . . . . . . 57 140 10.53.2. The "boolean" Type . . . . . . . . . . . . . . . . 57 141 10.53.3. The "binary" Type . . . . . . . . . . . . . . . . . 58 142 10.53.4. The "bits" Type . . . . . . . . . . . . . . . . . . 58 143 10.53.5. The "enumeration" and "union" Types . . . . . . . . 58 144 10.53.6. The "identityref" Type . . . . . . . . . . . . . . 58 145 10.53.7. The "instance-identifier" Type . . . . . . . . . . 59 146 10.53.8. The "leafref" Type . . . . . . . . . . . . . . . . 59 147 10.53.9. The Numeric Types . . . . . . . . . . . . . . . . . 59 148 10.53.10. The "string" Type . . . . . . . . . . . . . . . . . 61 149 10.53.11. Derived Types . . . . . . . . . . . . . . . . . . . 62 150 10.54. The 'typedef' Statement . . . . . . . . . . . . . . . . 63 151 10.55. The 'unique' Statement . . . . . . . . . . . . . . . . . 63 152 10.56. The 'units' Statement . . . . . . . . . . . . . . . . . 64 153 10.57. The 'uses' Statement . . . . . . . . . . . . . . . . . . 64 154 10.58. The 'value' Statement . . . . . . . . . . . . . . . . . 64 155 10.59. The 'when' Statement . . . . . . . . . . . . . . . . . . 64 156 10.60. The 'yang-version' Statement . . . . . . . . . . . . . . 64 157 10.61. The 'yin-element' Statement . . . . . . . . . . . . . . 64 158 11. Mapping the Hybrid Schema to DSDL . . . . . . . . . . . . . . 65 159 11.1. Generating RELAX NG Schemas for Various Document Types . 65 160 11.2. Mapping Semantic Constraints to Schematron . . . . . . . 66 161 11.2.1. Constraints on Mandatory Choice . . . . . . . . . . 69 162 11.3. Mapping Default Values to DSRL . . . . . . . . . . . . . 70 163 12. Mapping NETMOD-specific Annotations to DSDL Schema 164 Languages . . . . . . . . . . . . . . . . . . . . . . . . . . 75 165 12.1. The @nma:config Annotation . . . . . . . . . . . . . . . 75 166 12.2. The @nma:default Annotation . . . . . . . . . . . . . . 75 167 12.3. The Annotation . . . . . . . . . . . 75 168 12.4. The Annotation . . . . . . . . . . . 75 169 12.5. The @if-feature Annotation . . . . . . . . . . . . . . . 75 170 12.6. The @nma:implicit Annotation . . . . . . . . . . . . . . 76 171 12.7. The Annotation . . . . . . . . 76 172 12.8. The @nma:key Annotation . . . . . . . . . . . . . . . . 76 173 12.9. The @nma:leaf-list Annotation . . . . . . . . . . . . . 76 174 12.10. The @nma:leafref Annotation . . . . . . . . . . . . . . 77 175 12.11. The @nma:min-elements Annotation . . . . . . . . . . . . 77 176 12.12. The @nma:max-elements Annotation . . . . . . . . . . . . 77 177 12.13. The Annotation . . . . . . . . . . . . . . . 77 178 12.14. The Annotation . . . . . . . . . . . . 78 179 12.15. The Annotation . . . . . . . . . . . . . . 78 180 12.16. The @nma:unique Annotation . . . . . . . . . . . . . . . 78 181 12.17. The @nma:when Annotation . . . . . . . . . . . . . . . . 78 182 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 79 183 14. Security Considerations . . . . . . . . . . . . . . . . . . . 80 184 15. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 81 185 16. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 82 186 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 83 187 17.1. Normative References . . . . . . . . . . . . . . . . . . 83 188 17.2. Informative References . . . . . . . . . . . . . . . . . 84 189 Appendix A. RELAX NG Schema for NETMOD-Specific Annotations . . 86 190 Appendix B. Schema-Independent Library . . . . . . . . . . . . . 91 191 Appendix C. Mapping DHCP Data Model - A Complete Example . . . . 92 192 C.1. Input YANG Module . . . . . . . . . . . . . . . . . . . 92 193 C.2. Hybrid Schema . . . . . . . . . . . . . . . . . . . . . 94 194 C.3. Final DSDL Schemas . . . . . . . . . . . . . . . . . . . 99 195 C.3.1. Main RELAX NG Schema for Reply . . . . . . 100 196 C.3.2. RELAX NG Schema - Global Named Pattern 197 Definitions . . . . . . . . . . . . . . . . . . . . 102 198 C.3.3. Schematron Schema for Reply . . . . . . . 104 199 C.3.4. DSRL Schema for Reply . . . . . . . . . . 106 200 Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 107 201 D.1. Changes Between Versions -07 and -08 . . . . . . . . . . 107 202 D.2. Changes Between Versions -06 and -07 . . . . . . . . . . 107 203 D.3. Changes Between Versions -05 and -06 . . . . . . . . . . 107 204 D.4. Changes Between Versions -04 and -05 . . . . . . . . . . 108 205 D.5. Changes Between Versions -03 and -04 . . . . . . . . . . 108 206 D.6. Changes Between Versions -02 and -03 . . . . . . . . . . 109 207 D.7. Changes Between Versions -01 and -02 . . . . . . . . . . 110 208 D.8. Changes Between Versions -00 and -01 . . . . . . . . . . 110 209 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 112 211 1. Introduction 213 The NETCONF Working Group has completed a base protocol used for 214 configuration management [RFC4741]. This base specification defines 215 protocol bindings and an XML container syntax for configuration and 216 management operations, but does not include a data modeling language 217 or accompanying rules for how to model configuration and state 218 information carried by NETCONF. The IETF Operations Area has a long 219 tradition of defining data for SNMP Management Information Bases 220 (MIB) modules [RFC1157] using the Structure of Management Information 221 (SMI) language [RFC2578] to model its data. While this specific 222 modeling approach has a number of well-understood problems, most of 223 the data modeling features provided by SMI are still considered 224 extremely important. Simply modeling the valid syntax without the 225 additional semantic relationships has caused significant 226 interoperability problems in the past. 228 The NETCONF community concluded that a data modeling framework is 229 needed to support ongoing development of IETF and vendor-defined 230 management information modules. The NETMOD Working Group was 231 chartered to design a modeling language defining the semantics of 232 operational data, configuration data, event notifications and 233 operations, with focus on "human-friendliness", i.e., readability and 234 ease of use. The result is the YANG data modeling language 235 [RFC6020], which now serves for the normative description of NETCONF 236 data models. 238 Since NETCONF uses XML for encoding its messages, it is natural to 239 express the constraints on NETCONF content using standard XML schema 240 languages. For this purpose, the NETMOD WG selected the Document 241 Schema Definition Languages (DSDL) that is being standardized as ISO/ 242 IEC 19757 [DSDL]. The DSDL framework comprises a set of XML schema 243 languages that address grammar rules, semantic constraints and other 244 data modeling aspects, but also, and more importantly, do it in a 245 coordinated and consistent way. While it is true that some DSDL 246 parts have not been standardized yet and are still work in progress, 247 the three parts that the YANG-to-DSDL mapping relies upon - Regular 248 Language for XML Next Generation (RELAX NG), Schematron and Document 249 Schema Renaming Language (DSRL) - already have the status of an ISO/ 250 IEC International Standard and are supported in a number of software 251 tools. 253 This document contains a specification of a mapping that translates 254 YANG data models to XML schemas utilizing a subset of the DSDL schema 255 languages. The mapping procedure is divided into two steps: In the 256 first step, the structure of the data tree, signatures of remote 257 procedure call (RPC) operations and notifications is expressed as the 258 so-called "hybrid schema" - a single RELAX NG schema with annotations 259 representing additional data model information (metadata, 260 documentation, semantic constraints, default values etc.). The 261 second step then generates a coordinated set of DSDL schemas that can 262 be used for validating specific XML documents such as client 263 requests, server responses or notifications, perhaps also taking into 264 account additional context such as active capabilities or features. 266 2. Terminology and Notation 268 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 269 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 270 document are to be interpreted as described in [RFC2119]. 272 The following terms are defined in [RFC4741]: 274 o client 276 o datastore 278 o message 280 o operation 282 o server 284 The following terms are defined in [RFC6020]: 286 o augment 288 o base type 290 o built-in type 292 o configuration data 294 o container 296 o data model 298 o data node 300 o data tree 302 o derived type 304 o device deviation 306 o extension 308 o feature 310 o grouping 312 o instance identifier 313 o leaf-list 315 o list 317 o mandatory node 319 o module 321 o RPC 323 o RPC operation 325 o schema node 327 o schema tree 329 o state data 331 o submodule 333 o top-level data node 335 o uses 337 The following terms are defined in [XML-INFOSET]: 339 o attribute 341 o document 343 o document element 345 o document type declaration (DTD) 347 o element 349 o information set 351 o namespace 353 In the text, the following typographic conventions are used: 355 o YANG statement keywords are delimited by single quotes. 357 o XML element names are delimited by "<" and ">" characters. 359 o Names of XML attributes are prefixed by the "@" character. 361 o Other literal values are delimited by double quotes. 363 XML elements names are always written with explicit namespace 364 prefixes corresponding to the following XML vocabularies: 366 "a" DTD compatibility annotations [RNG-DTD]; 368 "dc" Dublin Core metadata elements [RFC5013]; 370 "dsrl" Document Semantics Renaming Language [DSRL]; 372 "en" NETCONF event notifications [RFC5277]; 374 "nc" NETCONF protocol [RFC4741]; 376 "nma" NETMOD-specific schema annotations (see Section 5.3); 378 "nmf" NETMOD-specific XPath extension functions (see Section 12.7); 380 "rng" RELAX NG [RNG]; 382 "sch" ISO Schematron [Schematron]; 384 "xsd" W3C XML Schema [XSD]. 386 The following table shows the mapping of these prefixes to namespace 387 URIs. 389 +--------+-----------------------------------------------------+ 390 | Prefix | Namespace URI | 391 +--------+-----------------------------------------------------+ 392 | a | http://relaxng.org/ns/compatibility/annotations/1.0 | 393 | | | 394 | dc | http://purl.org/dc/terms | 395 | | | 396 | dsrl | http://purl.oclc.org/dsdl/dsrl | 397 | | | 398 | en | urn:ietf:params:xml:ns:netconf:notification:1.0 | 399 | | | 400 | nc | urn:ietf:params:xml:ns:netconf:base:1.0 | 401 | | | 402 | nma | urn:ietf:params:xml:ns:netmod:dsdl-annotations:1 | 403 | | | 404 | nmf | urn:ietf:params:xml:ns:netmod:xpath-extensions:1 | 405 | | | 406 | rng | http://relaxng.org/ns/structure/1.0 | 407 | | | 408 | sch | http://purl.oclc.org/dsdl/schematron | 409 | | | 410 | xsd | http://www.w3.org/2001/XMLSchema | 411 +--------+-----------------------------------------------------+ 413 Table 1: Used namespace prefixes and corresponding URIs 415 2.1. Glossary of New Terms 417 o ancestor datatype: Any datatype a given datatype is (transitively) 418 derived from. 420 o ancestor built-in datatype: The built-in datatype that is at the 421 start of the type derivation chain for a given datatype. 423 o hybrid schema: A RELAX NG schema with annotations, which embodies 424 the same information as the source YANG module(s). See 425 Section 8.1 for details. 427 o implicit node: A data node that, if it is not instantiated in a 428 data tree, may be added to the information set of that data tree 429 (configuration, RPC input or output, notification) without 430 changing the semantics of the data tree. 432 3. Objectives and Motivation 434 The main objective of this work is to complement YANG as a data 435 modeling language with validation capabilities of DSDL schema 436 languages, namely RELAX NG, Schematron and DSRL. This document 437 describes the correspondence between grammatical, semantic and data 438 type constraints expressed in YANG and equivalent DSDL patterns and 439 rules. The ultimate goal is to be able to capture all substantial 440 information contained in YANG modules and express it in DSDL schemas. 441 While the mapping from YANG to DSDL described in this document may in 442 principle be invertible, the inverse mapping from DSDL to YANG is 443 beyond the scope of this document. 445 XML-based information models and XML-encoded data appear in several 446 different forms in various phases of YANG data modeling and NETCONF 447 workflow - configuration datastore contents, RPC requests and 448 replies, and notifications. Moreover, RPC operations are 449 characterized by an inherent diversity resulting from selective 450 availability of capabilities and features. YANG modules can also 451 define new RPC operations. The mapping should be able to accommodate 452 this variability and generate schemas that are specifically tailored 453 to a particular situation and thus considerably more effective for 454 validation than generic all-encompassing schemas. 456 In order to cope with this variability, we assume that the DSDL 457 schemas will be generated on demand for a particular purpose from the 458 available collection of YANG modules and their lifetime will be 459 relatively short. In other words, we don't envision that any 460 collection of DSDL schemas will be created and maintained over an 461 extended period of time in parallel to YANG modules. 463 The generated schemas are primarily intended as input to existing XML 464 schema validators and other off-the-shelf tools. However, the 465 schemas may also be perused by developers and users as a formal 466 representation of constraints on a particular XML-encoded data 467 object. Consequently, our secondary goal is to keep the schemas as 468 readable as possible. To this end, the complexity of the mapping is 469 distributed into two steps: 471 1. The first step maps one or more YANG modules to the so-called 472 hybrid schema, which is a single RELAX NG schema that describes 473 grammatical constraints for the main data tree as well as for RPC 474 operations and notifications. Semantic constraints and other 475 information appearing in the input YANG modules is recorded in 476 the hybrid schema in the form of foreign namespace annotations. 477 The output of the first step can thus be considered a virtually 478 complete equivalent of the input YANG modules. 480 2. In the second step, the hybrid schema from step 1 is transformed 481 further to a coordinated set of fully conformant DSDL schemas 482 containing constraints for a particular data object and a 483 specific situation. The DSDL schemas are intended mainly for 484 machine validation using off-the-shelf tools. 486 4. DSDL Schema Languages 488 Document Schema Definition Languages (DSDL) is a framework of schema 489 languages that is being developed as the International Standard ISO/ 490 IEC 19757 [DSDL]. Unlike other approaches to XML document 491 validation, most notably W3C XML Schema Definition (XSD) [XSD], the 492 DSDL framework adheres to the principle of "small languages": Each of 493 the DSDL constituents is a stand-alone schema language with a 494 relatively narrow purpose and focus. Together, these schema 495 languages may be used in a coordinated way to accomplish various 496 validation tasks. 498 The mapping described in this document uses three of the DSDL schema 499 languages, namely RELAX NG [RNG], Schematron [Schematron] and DSRL 500 [DSRL]. 502 4.1. RELAX NG 504 RELAX NG (pronounced "relaxing") is an XML schema language for 505 grammar-based validation and Part 2 of the ISO/IEC DSDL family of 506 standards [RNG]. Like the W3C XML Schema language [XSD], it is able 507 to describe constraints on the structure and contents of XML 508 documents. However, unlike the DTD [XML] and XSD schema languages, 509 RELAX NG intentionally avoids any infoset augmentation such as 510 defining default values. In the DSDL architecture, the particular 511 task of defining and applying default values is delegated to another 512 schema language, DSRL (see Section 4.3). 514 As its base datatype library, RELAX NG uses the W3C XML Schema 515 Datatype Library [XSD-D], but unlike XSD, other datatype libraries 516 may be used along with it or even replace it if necessary. 518 RELAX NG is very liberal in accepting annotations from other 519 namespaces. With a few exceptions, such annotations may be placed 520 anywhere in the schema and need no encapsulating elements such as 521 in XSD. 523 RELAX NG schemas can be represented in two equivalent syntaxes: XML 524 and compact. The compact syntax is described in Annex C of the RELAX 525 NG specification [RNG-CS], which was added to the standard in 2006 526 (Amendment 1). Automatic bidirectional conversions between the two 527 syntaxes can be accomplished using several tools, for example Trang 528 [Trang]. 530 For its terseness and readability, the compact syntax is often the 531 preferred form for publishing RELAX NG schemas whereas validators and 532 other software tools usually work with the XML syntax. However, the 533 compact syntax has two drawbacks: 535 o External annotations make the compact syntax schema considerably 536 less readable. While in the XML syntax the annotating elements 537 and attributes are represented in a simple and uniform way (XML 538 elements and attributes from foreign namespaces), the compact 539 syntax uses as many as four different syntactic constructs: 540 documentation, grammar, initial and following annotations. 541 Therefore, the impact of annotations on readability is often much 542 stronger for the compact syntax than it is for the XML syntax. 544 o In a computer program, it is more difficult to generate the 545 compact syntax than the XML syntax. While a number of software 546 libraries exist that make it easy to create an XML tree in the 547 memory and then serialize it, no such aid is available for the 548 compact syntax. 550 For these reasons, the mapping specification in this document uses 551 exclusively the XML syntax. Where appropriate, though, the schemas 552 resulting from the translation MAY be presented in the equivalent 553 compact syntax. 555 RELAX NG elements are qualified with the namespace URI 556 "http://relaxng.org/ns/structure/1.0". The namespace of the W3C 557 Schema Datatype Library is 558 "http://www.w3.org/2001/XMLSchema-datatypes". 560 4.2. Schematron 562 Schematron is Part 3 of DSDL that reached the status of a full ISO/ 563 IEC standard in 2006 [Schematron]. In contrast to the traditional 564 schema languages such as DTD, XSD or RELAX NG, which are based on the 565 concept of a formal grammar, Schematron utilizes a rule-based 566 approach. Its rules may specify arbitrary conditions involving data 567 from different parts of an XML document. Each rule consists of three 568 essential components: 570 o context - an XPath expression that defines the set of locations 571 where the rule is to be applied; 573 o assert or report condition - another XPath expression that is 574 evaluated relative to the location matched by the context 575 expression; 577 o human-readable message that is displayed when the assert condition 578 is false or report condition is true. 580 The difference between the assert and report condition is that the 581 former is positive in that it states a condition that a valid 582 document has to satisfy, whereas the latter specifies an error 583 condition. 585 Schematron draws most of its expressive power from XPath [XPath] and 586 Extensible Stylesheet Language Transformations (XSLT) [XSLT]. ISO 587 Schematron allows for dynamic query language binding so that the 588 following XML query languages can be used: STX, XSLT 1.0, XSLT 1.1, 589 EXSLT, XSLT 2.0, XPath 1.0, XPath 2.0 and XQuery 1.0 (this list may 590 be extended in the future). 592 Human-readable error messages are another feature that sets 593 Schematron apart from other common schema languages. The messages 594 may even contain XPath expressions that are evaluated in the actual 595 context and thus refer to information items in the XML document being 596 validated. 598 Another feature of Schematron that is used by the mapping are 599 abstract patterns. These work essentially as macros and may also 600 contain parameters which are supplied when the abstract pattern is 601 used. 603 Schematron elements are qualified with namespace URI 604 "http://purl.oclc.org/dsdl/schematron". 606 4.3. Document Semantics Renaming Language (DSRL) 608 DSRL (pronounced "disrule") is Part 8 of DSDL that reached the status 609 of a full ISO/IEC standard in 2008 [DSRL]. Unlike RELAX NG and 610 Schematron, DSRL is allowed to modify XML information set of the 611 validated document. While DSRL is primarily intended for renaming 612 XML elements and attributes, it can also define default values for 613 XML attributes and default contents for XML elements or subtrees so 614 that the default contents are inserted if they are missing in the 615 validated documents. The latter feature is used by the YANG-to-DSDL 616 mapping for representing YANG default contents consisting of leaf 617 nodes with default values and their ancestor non-presence containers. 619 DSRL elements are qualified with namespace URI 620 "http://purl.oclc.org/dsdl/dsrl". 622 5. Additional Annotations 624 Besides the DSDL schema languages, the mapping also uses three sets 625 of annotations that are added as foreign-namespace attributes and 626 elements to RELAX NG schemas. 628 Two of the annotation sets - Dublin Core elements and DTD 629 compatibility annotations - are standard vocabularies for 630 representing metadata and documentation, respectively. Although 631 these data model items are not used for formal validation, they quite 632 often carry important information for data model implementers. 633 Therefore, they SHOULD be included in the hybrid schema and MAY also 634 appear in the final validation schemas. 636 The third set are NETMOD-specific annotations. They are specifically 637 designed for the hybrid schema and convey semantic constraints and 638 other information that cannot be expressed directly in RELAX NG. In 639 the second mapping step, these annotations are converted to 640 Schematron and DSRL rules. 642 5.1. Dublin Core Metadata Elements 644 Dublin Core is a system of metadata elements that was originally 645 created for describing metadata of World Wide Web resources in order 646 to facilitate their automated lookup. Later it was accepted as a 647 standard for describing metadata of arbitrary resources. This 648 specification uses the definition from [RFC5013]. 650 Dublin Core elements are qualified with namespace URI 651 "http://purl.org/dc/terms". 653 5.2. RELAX NG DTD Compatibility Annotations 655 DTD compatibility annotations are a part of the RELAX NG DTD 656 Compatibility specification [RNG-DTD]. YANG-to-DSDL mapping uses 657 only the annotation for representing YANG 658 'description' and 'reference' texts. 660 Note that there is no intention to make the resulting schemas DTD- 661 compatible, the main reason for using these annotations is technical: 662 they are well supported and adequately formatted by several RELAX NG 663 tools. 665 DTD compatibility annotations are qualified with namespace URI 666 "http://relaxng.org/ns/compatibility/annotations/1.0". 668 5.3. NETMOD-Specific Annotations 670 NETMOD-specific annotations are XML elements and attributes qualified 671 with the namespace URI 672 "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1" which appear in 673 various locations of the hybrid schema. YANG statements are mapped 674 to these annotations in a straightforward way. In most cases, the 675 annotation attributes and elements have the same name as the 676 corresponding YANG statement. 678 Table 2 lists alphabetically the names of NETMOD-specific annotation 679 attributes (prefixed with "@") and elements (in angle brackets) along 680 with a reference to the section where their use is described. 681 Appendix A contains a RELAX NG schema for this annotation vocabulary. 683 +---------------------------+--------------------+------+ 684 | annotation | section | note | 685 +---------------------------+--------------------+------+ 686 | @nma:config | 10.9 | | 687 | | | | 688 | | 8.1 | 4 | 689 | | | | 690 | @nma:default | 10.12 | | 691 | | | | 692 | | 10.16 | 1 | 693 | | | | 694 | | 10.17 | 1 | 695 | | | | 696 | @nma:if-feature | 10.22 | | 697 | | | | 698 | @nma:implicit | 10.11, 10.7, 10.12 | | 699 | | | | 700 | | 8.1 | 4 | 701 | | | | 702 | | 10.53.7 | 2 | 703 | | | | 704 | @nma:key | 10.26 | | 705 | | | | 706 | @nma:leaf-list | 10.28 | | 707 | | | | 708 | @nma:leafref | 10.53.8 | | 709 | | | | 710 | @nma:mandatory | 10.8 | | 711 | | | | 712 | @nma:max-elements | 10.28 | | 713 | | | | 714 | @nma:min-elements | 10.28 | | 715 | | | | 716 | @nma:module | 10.34 | | 717 | | | | 718 | | 10.35 | 3 | 719 | | | | 720 | | 8.1 | 4 | 721 | | | | 722 | | 8.1 | 4 | 723 | | | | 724 | @nma:ordered-by | 10.38 | | 725 | | | | 726 | | 8.1 | 4 | 727 | | | | 728 | | 8.1 | 4 | 729 | | | | 730 | | 8.1 | 4 | 731 | | | | 732 | @nma:status | 10.51 | | 733 | | | | 734 | @nma:unique | 10.55 | | 735 | | | | 736 | @nma:units | 10.56 | | 737 | | | | 738 | @nma:when | 10.59 | | 739 +---------------------------+--------------------+------+ 741 Table 2: NETMOD-specific annotations 743 Notes: 745 1. Appears only as a subelement of . 747 2. Has an optional attribute @require-instance. 749 3. Has a mandatory attribute @assert and two optional subelements 750 and . 752 4. Marker element in the hybrid schema. 754 6. Overview of the Mapping 756 This section gives an overview of the YANG-to-DSDL mapping, its 757 inputs and outputs. Figure 1 presents an overall structure of the 758 mapping: 760 +----------------+ 761 | YANG module(s) | 762 +----------------+ 763 | 764 |T 765 | 766 +------------------------------------+ 767 | hybrid schema | 768 +------------------------------------+ 769 / | | \ 770 / | | \ 771 Tg/ Tr| |Tn \ 772 / | | \ 773 +---------+ +-----+ +-------+ +------+ 774 |get reply| | rpc | | notif | | .... | 775 +---------+ +-----+ +-------+ +------+ 777 Figure 1: Structure of the mapping 779 The mapping procedure is divided into two steps: 781 1. Transformation T in the first step maps one or more YANG modules 782 to the hybrid schema (see Section 8.1). Constraints that cannot 783 be expressed directly in RELAX NG (list key definitions, 'must' 784 statements etc.) and various documentation texts are recorded in 785 the schema as foreign-namespace annotations. 787 2. In the second step, the hybrid schema may be transformed in 788 multiple ways to a coordinated set of DSDL schemas that can be 789 used for validating a particular data object in a specific 790 context. Figure 1 shows three simple possibilities as examples. 791 In the process, appropriate parts of the hybrid schema are 792 extracted and specific annotations transformed to equivalent, but 793 usually more complex, Schematron patterns, DSRL element maps etc. 795 An implementation of the mapping algorithm MUST accept one or more 796 valid YANG modules as its input. It is important to be able to 797 process multiple YANG modules together since multiple modules may be 798 negotiated for a NETCONF session and the contents of the 799 configuration datastore is then obtained as the union of data trees 800 specified by the individual modules, which may also lead to multiple 801 root nodes of the datastore hierarchy. In addition, the input 802 modules may be further coupled by the 'augment' statement in which 803 one module augments the data tree of another module. 805 It is also assumed that the algorithm has access, perhaps on demand, 806 to all YANG modules that the input modules import (directly or 807 transitively). 809 Other information contained in input YANG modules, such as semantic 810 constraints and default values, are recorded in the hybrid schema as 811 annotations - XML attributes or elements qualified with namespace URI 812 "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1". Metadata 813 describing the YANG modules are mapped to Dublin Core annotations 814 elements (Section 5.1). Finally, documentation strings are mapped to 815 elements belonging to the DTD compatibility 816 vocabulary (Section 5.2). 818 The output of the second step is a coordinated set of three DSDL 819 schemas corresponding to a specific data object and context: 821 o RELAX NG schema describing the grammatical and datatype 822 constraints; 824 o Schematron schema expressing other constraints such as uniqueness 825 of list keys or user-specified semantic rules; 827 o DSRL schema containing the specification of default contents. 829 7. NETCONF Content Validation 831 This section describes how the schemas generated by the YANG-to-DSDL 832 mapping are supposed to be applied for validating XML instance 833 documents such as the contents of a datastore or various NETCONF 834 messages. 836 The validation proceeds in the following steps, which are also 837 illustrated in Figure 2: 839 1. The XML instance document is checked for grammatical and data 840 type validity using the RELAX NG schema. 842 2. Default values for leaf nodes have to be applied and their 843 ancestor containers added where necessary. It is important to 844 add the implicit nodes before the next validation step because 845 YANG specification [RFC6020] requires that the data tree against 846 which XPath expressions are evaluated already has all defaults 847 filled-in. Note that this step modifies the information set of 848 the validated XML document. 850 3. The semantic constraints are checked using the Schematron schema. 852 +----------+ +----------+ 853 | | | XML | 854 | XML | | document | 855 | document |-----------o----------->| with | 856 | | ^ | defaults | 857 | | | | | 858 +----------+ | +----------+ 859 ^ | filling in ^ 860 | grammar, | defaults | semantic 861 | datatypes | | constraints 862 | | | 863 +----------+ +--------+ +------------+ 864 | RELAX NG | | DSRL | | Schematron | 865 | schema | | schema | | schema | 866 +----------+ +--------+ +------------+ 868 Figure 2: Outline of the validation procedure 870 8. Design Considerations 872 YANG data models could in principle be mapped to the DSDL schemas in 873 a number of ways. The mapping procedure described in this document 874 uses several specific design decisions that are discussed in the 875 following subsections. 877 8.1. Hybrid Schema 879 As was explained in Section 6, the first step of the mapping produces 880 an intermediate document - the hybrid schema, which specifies all 881 constraints for the entire data model in a single RELAX NG schema. 883 Every input YANG module corresponds to exactly one embedded grammar 884 in the hybrid schema. This separation of input YANG modules allows 885 each embedded grammar to include named pattern definitions into its 886 own namespace, which is important for mapping YANG groupings (see 887 Section 9.2 for additional details). 889 In addition to grammatical and datatype constraints, YANG modules 890 provide other important information that cannot be expressed in a 891 RELAX NG schema: semantic constraints, default values, metadata, 892 documentation and so on. Such information items are represented in 893 the hybrid schema as XML attributes and elements belonging to the 894 namespace with the following URI: 895 "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1". A complete list 896 of these annotations is given in Section 5.3, detailed rules about 897 their use are then contained in the following sections. 899 YANG modules define data models not only for configuration and state 900 data but also for (multiple) RPC operations [RFC4741] and/or event 901 notifications [RFC5277]. In order to be able to capture all three 902 types of data models in one schema document, the hybrid schema uses 903 special markers that enclose sub-schemas for configuration and state 904 data, individual RPC operations (both input and output part) and 905 individual notifications. 907 The markers are the following XML elements in the namespace of 908 NETMOD-specific annotations (URI 909 urn:ietf:params:xml:ns:netmod:dsdl-annotations:1): 911 +-------------------+---------------------------------------+ 912 | Element name | Role | 913 +-------------------+---------------------------------------+ 914 | nma:data | encloses configuration and state data | 915 | | | 916 | nma:rpcs | encloses all RPC operations | 917 | | | 918 | nma:rpc | encloses an individual RPC operation | 919 | | | 920 | nma:input | encloses an RPC request | 921 | | | 922 | nma:output | encloses an RPC reply | 923 | | | 924 | nma:notifications | encloses all notifications | 925 | | | 926 | nma:notification | encloses an individual notification | 927 +-------------------+---------------------------------------+ 929 Table 3: Marker elements in the hybrid schema 931 For example, consider a data model formed by two YANG modules 932 "example-a" and "example-b" that define nodes in the namespaces 933 "http://example.com/ns/example-a" and 934 "http://example.com/ns/example-b". Module "example-a" defines 935 configuration/state data, RPC methods and notifications, whereas 936 "example-b" defines only configuration/state data. The hybrid schema 937 can then be schematically represented as follows: 939 944 945 947 948 949 ...configuration and state data defined in "example-a"... 950 951 952 953 954 955 ... 956 957 958 959 ... 960 961 962 ... 963 964 965 966 967 ... 968 969 970 ... 971 972 973 ...local named pattern definitions of example-a... 974 975 977 978 979 ...configuration and state data defined in "example-b"... 980 981 982 983 984 ...local named pattern definitions of example-b... 985 986 987 ...global named pattern definitions... 988 990 A complete hybrid schema for the data model of a DHCP server is given 991 in Appendix C.2. 993 8.2. Modularity 995 Both YANG and RELAX NG offer means for modularity, i.e., for 996 splitting the contents of a full schema into separate modules and 997 combining or reusing them in various ways. However, the approaches 998 taken by YANG and RELAX NG differ. Modularity in RELAX NG is 999 suitable for ad hoc combinations of a small number of schemas whereas 1000 YANG assumes a large set of modules similar to SNMP MIB modules. The 1001 following differences are important: 1003 o In YANG, whenever module A imports module B, it gets access to the 1004 definitions (groupings and typedefs) appearing at the top level of 1005 module B. However, no part of data tree from module B is imported 1006 along with it. In contrast, the pattern in RELAX NG 1007 imports both definitions of named patterns and the entire schema 1008 tree from the included schema. 1010 o The names of imported YANG groupings and typedefs are qualified 1011 with the namespace of the imported module. On the other hand, the 1012 names of data nodes contained inside the imported groupings, when 1013 used within the importing module, become part of the importing 1014 module's namespace. In RELAX NG, the names of patterns are 1015 unqualified and so named patterns defined in both the importing 1016 and imported module share the same flat namespace. The contents 1017 of RELAX NG named patterns may either keep the namespace of the 1018 schema where they are defined or inherit the namespace of the 1019 importing module, analogically to YANG. However, in order to 1020 achieve the latter behavior, the definitions of named patterns 1021 must be included from an external schema which has to be prepared 1022 in a special way (see [Vli04], Chapter 11). 1024 In order to map, as much as possible, the modularity of YANG to RELAX 1025 NG, a validating RELAX NG schema (the result of the second mapping 1026 step) has to be split into two files, one of them containing all 1027 global definitions that are mapped from top-level YANG groupings 1028 appearing in all input YANG module. This RELAX NG schema MUST NOT 1029 define any namespace via the @ns attribute. 1031 The other RELAX NG schema file then defines actual data trees mapped 1032 from input YANG modules, each of them enclosed in an own embedded 1033 grammar. Those embedded grammars in which at least one of the global 1034 definitions is used MUST include the first schema with definitions 1035 and also MUST define the local namespace using the @ns attribute. 1036 This way, the global definitions can be used inside different 1037 embedded grammar, each time accepting a different local namespace. 1039 Named pattern definition that are mapped from non-top-level YANG 1040 groupings MUST be placed inside the embedded grammar corresponding to 1041 the YANG module where the grouping is defined. 1043 In the hybrid schema, we need to distinguish the global and non- 1044 global named pattern definitions while still keeping the hybrid 1045 schema in one file. This is accomplished in the following way: 1047 o Every global definition MUST be placed as a child of the the outer 1048 element (the document root of the hybrid schema). 1050 o Every non-global definitions MUST be placed as a child of the 1051 corresponding embedded element. 1053 YANG also allows for splitting a module into a number of submodules. 1054 However, as submodules have no impact on the scope of identifiers and 1055 namespaces, the modularity based on submodules is not mapped in any 1056 way. The contents of submodules is therefore handled as if the 1057 submodule text appeared directly in the main module. 1059 8.3. Granularity 1061 RELAX NG supports different styles of schema structuring: One 1062 extreme, often called "Russian Doll", specifies the structure of an 1063 XML instance document in a single hierarchy. The other extreme, the 1064 flat style, uses a similar approach as the Data Type Definition (DTD) 1065 schema language - every XML element corresponds to a named pattern 1066 definition. In practice, some compromise between the two extremes is 1067 usually chosen. 1069 YANG supports both styles in principle, too, but in most cases the 1070 modules are organized in a way closer to the "Russian Doll" style, 1071 which provides a better insight into the structure of the 1072 configuration data. Groupings are usually defined only for contents 1073 that are prepared for reuse in multiple places via the 'uses' 1074 statement. In contrast, RELAX NG schemas tend to be much flatter, 1075 because finer granularity is also needed in RELAX NG for 1076 extensibility of the schemas - it is only possible to replace or 1077 modify schema fragments that are factored out as named patterns. For 1078 YANG this is not an issue since its 'augment' and 'refine' statements 1079 can delve, by using path expressions, into arbitrary depths of 1080 existing structures. 1082 In general, it not feasible to map YANG's powerful extension 1083 mechanisms to those available in RELAX NG. For this reason, the 1084 mapping essentially keeps the granularity of the original YANG data 1085 model: YANG groupings and definitions of derived types usually have 1086 direct counterparts in definitions of named patterns in the resulting 1087 RELAX NG schema. 1089 8.4. Handling of XML Namespaces 1091 Most modern XML schema languages, including RELAX NG, Schematron and 1092 DSRL, support schemas for so-called compound XML documents which 1093 contain elements from multiple namespaces. This is useful for our 1094 purpose since the YANG-to-DSDL mapping allows for multiple input YANG 1095 modules, which naturally leads to compound document schemas. 1097 RELAX NG offers two alternatives for defining the target namespaces 1098 in the schema: 1100 1. First possibility is the traditional XML way via the @xmlns:xxx 1101 attribute. 1103 2. One of the target namespace URIs may be declared using the @ns 1104 attribute. 1106 In both the hybrid schema and validation RELAX NG schemas generated 1107 in the second step, the namespaces MUST be declared as follows: 1109 1. The root MUST have @xmlns:xxx attributes declaring 1110 prefixes of all namespaces that are used in the data model. The 1111 prefixes SHOULD be identical to those defined in the 'prefix' 1112 statements. An implementation of the mapping MUST resolve all 1113 collisions in the prefixes defined by different input modules, if 1114 there are any. 1116 2. Each embedded element MUST declare the namespace of 1117 the corresponding module using the @ns attribute. This way, the 1118 names of nodes defined by global named patterns are able to adopt 1119 the local namespace of each embedded grammar, as explained in 1120 Section 8.2. 1122 This setup is illustrated by the example at the end of Section 8.1. 1124 DSRL schemas may declare any number of target namespaces via the 1125 standard XML attributes xmlns:xxx. 1127 In contrast, Schematron requires all used namespaces to be defined in 1128 the subelements of the document element . 1130 9. Mapping YANG Data Models to the Hybrid Schema 1132 This section explains the main principles governing the first step of 1133 the mapping. Its result is the hybrid schema which is described in 1134 Section 8.1. 1136 A detailed specification of the mapping of individual YANG statements 1137 is contained in the following Section 10. 1139 9.1. Occurrence Rules for Data Nodes 1141 In DSDL schema languages, occurrence constraints for a node are 1142 always localized together with that node. In a RELAX NG schema, for 1143 example, pattern appears as the parent element of the 1144 pattern defining a leaf or non-leaf element. Similarly, DSRL 1145 specifies default contents separately for every single node, be it a 1146 leaf or non-leaf element. 1148 For leaf nodes in YANG modules, the occurrence constraints are also 1149 easily inferred from the substatements of 'leaf'. On the other hand, 1150 for a YANG container it is often necessary to examine its entire 1151 subtree in order to determine the container's occurrence constraints. 1153 Therefore, one of the goals of the first mapping step is to infer the 1154 occurrence constraints for all data nodes and mark accordingly the 1155 corresponding patterns in the hybrid schema so that any 1156 transformation procedure in the second mapping step can simply use 1157 this information and need not examine the subtree again. 1159 First, it has to be decided whether a given data node must always be 1160 present in a valid configuration. If so, such a node is called 1161 mandatory, otherwise it is called optional. This constraint is 1162 closely related to the notion of mandatory nodes in Section 3.1 in 1163 [RFC6020]. The only difference is that this document also considers 1164 list keys to be mandatory. 1166 The other occurrence constraint has to do with the semantics of the 1167 'default' statement and the possibility of removing empty non- 1168 presence containers. As a result, the information set of a valid 1169 configuration may be modified by adding or removing certain leaf or 1170 container elements without changing the meaning of the configuration. 1171 In this document, such elements are called implicit. In the hybrid 1172 schema, they can be identified as RELAX NG patterns having either 1173 @nma:default or @nma:implicit attribute. 1175 Note that both occurrence constraints apply to containers at the top 1176 level of the data tree, and then also to other containers under the 1177 additional condition that their parent node exists in the instance 1178 document. For example, consider the following YANG fragment: 1180 container outer { 1181 presence 'Presence of "outer" means something.'; 1182 container c1 { 1183 leaf foo { 1184 type uint8; 1185 default 1; 1186 } 1187 } 1188 container c2 { 1189 leaf-list bar { 1190 type uint8; 1191 min-elements 0; 1192 } 1193 } 1194 container c3 { 1195 leaf baz { 1196 type uint8; 1197 mandatory true; 1198 } 1199 } 1200 } 1202 Here, container "outer" has the 'presence' substatement, which means 1203 that it is optional and not implicit. If "outer" is not present in a 1204 configuration, its child containers are not present as well. 1205 However, if "outer" does exist, it makes sense to ask which of its 1206 child containers are optional and which are implicit. In this case, 1207 "c1" is optional and implicit, "c2" is optional but not implicit and 1208 "c3" is mandatory (and therefore not implicit). 1210 The following subsections give precise rules for determining whether 1211 a container is optional or mandatory and whether it is implicit. In 1212 order to simplify the recursive definition of these occurrence 1213 characteristics, it is useful to define them also for other types of 1214 YANG schema nodes, i.e., leaf, list, leaf-list and anyxml and choice. 1216 9.1.1. Optional and Mandatory Nodes 1218 The decision whether a given node is mandatory or optional is 1219 governed by the following rules: 1221 o Leaf, anyxml and choice nodes are mandatory if they contain the 1222 substatement "mandatory true;". For a choice node this means that 1223 at least one node from exactly one case branch must exist. 1225 o In addition, a leaf node is mandatory if it is declared as a list 1226 key. 1228 o A list or leaf-list node is mandatory if it contains the 'min- 1229 elements' substatement with an argument value greater than zero. 1231 o A container node is mandatory if its definition does not contain 1232 the 'presence' substatement and at least one of its child nodes is 1233 mandatory. 1235 A node which is not mandatory is said to be optional. 1237 In RELAX NG, definitions of nodes that are optional must be 1238 explicitly wrapped in the element. The mapping MUST 1239 use the above rules to determine whether a YANG node is optional and 1240 if so, insert the element in the hybrid schema. 1242 However, alternatives in MUST NOT be defined as optional 1243 in the hybrid schema. If a choice in YANG is not mandatory, MUST be used to wrap the entire pattern. 1246 9.1.2. Implicit Nodes 1248 The following rules are used to determine whether a given data node 1249 is implicit: 1251 o List, leaf-list and anyxml nodes are never implicit. 1253 o A leaf node is implicit if and only if it has a default value, 1254 defined either directly or via its datatype. 1256 o A container node is implicit if and only if it does not have the 1257 'presence' substatement, none of its children are mandatory and at 1258 least one child is implicit. 1260 In the hybrid schema, all implicit containers, as well as leafs that 1261 obtain their default value from a typedef and don't have the @nma: 1262 default attribute, MUST be marked with @nma:implicit attribute having 1263 the value of "true". 1265 Note that Section 7.9.3 in [RFC6020] specifies other rules that must 1266 be taken into account when deciding whether a given container or leaf 1267 appearing inside a case of a choice is ultimately implicit or not. 1268 Specifically, a leaf or container under a case can be implicit only 1269 if the case appears in the argument of the choice's 'default' 1270 statement. However, this is not sufficient by itself but also 1271 depends on the particular instance XML document, namely on the 1272 presence or absence of nodes from other (non-default) cases. The 1273 details are explained in Section 11.3. 1275 9.2. Mapping YANG Groupings and Typedefs 1277 YANG groupings and typedefs are generally mapped to RELAX NG named 1278 patterns. There are, however, several caveats that the mapping has 1279 to take into account. 1281 First of all, YANG typedefs and groupings may appear at all levels of 1282 the module hierarchy and are subject to lexical scoping, see Section 1283 5.5 in [RFC6020]. Second, top-level symbols from external modules 1284 may be imported as qualified names represented using the external 1285 module namespace prefix and the name of the symbol. In contrast, 1286 named patterns in RELAX NG (both local and imported via the pattern) share the same namespace and within a grammar they 1288 are always global - their definitions may only appear at the top 1289 level as children of the element. Consequently, 1290 whenever YANG groupings and typedefs are mapped to RELAX NG named 1291 pattern definitions, their names MUST be disambiguated in order to 1292 avoid naming conflicts. The mapping uses the following procedure for 1293 mangling the names of groupings and type definitions: 1295 o Names of groupings and typedefs appearing at the top level of the 1296 YANG module hierarchy are prefixed with the module name and two 1297 underscore characters ("__"). 1299 o Names of other groupings and typedefs, i.e., those that do not 1300 appear at the top level of a YANG module, are prefixed with the 1301 module name, double underscore, and then the names of all ancestor 1302 data nodes separated by double underscore. 1304 o Finally, since the names of groupings and typedefs in YANG have 1305 different namespaces, an additional underscore character is added 1306 to the beginning of the mangled names of all groupings. 1308 An additional complication is caused by the YANG rules for subelement 1309 ordering (see, e.g., Section 7.5.7 in [RFC6020]): In RPC input and 1310 output parameters, subelements must follow the order specified in the 1311 data model, otherwise the order is arbitrary. Consequently, if a 1312 grouping is used both in RPC input/output parameters and elsewhere, 1313 it MUST be mapped to two different named pattern definitions - one 1314 with fixed order and the other with arbitrary order. To distinguish 1315 them, the "__rpc" suffix MUST be appended to the version with fixed 1316 order. 1318 EXAMPLE. Consider the following YANG module which imports the 1319 standard module "ietf-inet-types" [RFC6021]: 1321 module example1 { 1322 namespace "http://example.com/ns/example1"; 1323 prefix ex1; 1324 typedef vowels { 1325 type string { 1326 pattern "[aeiouy]*"; 1327 } 1328 } 1329 grouping "grp1" { 1330 leaf "void" { 1331 type "empty"; 1332 } 1333 } 1334 container "cont" { 1335 leaf foo { 1336 type vowels; 1337 } 1338 uses "grp1"; 1339 } 1340 } 1342 The hybrid schema generated by the first mapping step will then 1343 contain the following two (global) named pattern definitions: 1345 1346 1347 [aeiouy]* 1348 1349 1351 1352 1353 1354 1355 1356 1357 1359 9.2.1. YANG Refinements and Augments 1361 YANG groupings represent a similar concept as named pattern 1362 definitions in RELAX NG and both languages also offer mechanisms for 1363 their subsequent modification. However, in RELAX NG the definitions 1364 themselves are modified whereas YANG provides two substatements of 1365 'uses' which modify expansions of groupings: 1367 o 'refine' statement allows for changing parameters of a schema node 1368 inside the grouping referenced by the parent 'uses' statement; 1370 o 'augment' statement can be used for adding new schema nodes to the 1371 grouping contents. 1373 Both 'refine' and 'augment' statements are quite powerful in that 1374 they can address, using XPath-like expressions as their arguments, 1375 schema nodes that are arbitrarily deep inside the grouping contents. 1376 In contrast, modifications of named pattern definitions in RELAX NG 1377 are applied exclusively at the topmost level of the named pattern 1378 contents. In order to achieve a modifiability of named patterns 1379 comparable to YANG, a RELAX NG schema would have to be extremely flat 1380 (cf. Section 8.3) and very difficult to read. 1382 Since the goal of the mapping described in this document is to 1383 generate ad hoc DSDL schemas, we decided to avoid these complications 1384 and instead expand the grouping and refine and/or augment it "in 1385 place". In other words, every 'uses' statement which has 'refine' 1386 and/or 'augment' substatements is replaced by the contents of the 1387 corresponding grouping, the changes specified in the 'refine' and 1388 'augment' statements are applied and the resulting YANG schema 1389 fragment is mapped as if the 'uses'/'grouping' indirection wasn't 1390 there. 1392 If there are further 'uses' statements inside the grouping contents, 1393 they may require expansion, too: it is necessary if the contained 1394 'uses'/'grouping' pair lies on the "modification path" specified in 1395 the argument of a 'refine' or 'augment' statement. 1397 EXAMPLE. Consider the following YANG module: 1399 module example2 { 1400 namespace "http://example.com/ns/example2"; 1401 prefix ex2; 1402 grouping leaves { 1403 uses fr; 1404 uses es; 1405 } 1406 grouping fr { 1407 leaf feuille { 1408 type string; 1409 } 1410 } 1411 grouping es { 1412 leaf hoja { 1413 type string; 1414 } 1415 } 1416 uses leaves; 1417 } 1418 The resulting hybrid schema contains three global named pattern 1419 definitions corresponding to the three groupings, namely 1421 1422 1423 1424 1425 1426 1428 1429 1430 1431 1432 1433 1434 1436 1437 1438 1439 1440 1441 1442 1444 and the configuration data part of the hybrid schema is a single 1445 named pattern reference: 1447 1448 1449 1451 Now assume that the "uses leaves" statement contains a 'refine' 1452 substatement, for example: 1454 uses leaves { 1455 refine "hoja" { 1456 default "alamo"; 1457 } 1458 } 1460 The resulting hybrid schema now contains just one named pattern 1461 definition - "_example2__fr". The other two groupings "leaves" and 1462 "es" have to be expanded because they both lie on the "modification 1463 path", i.e., contain the leaf "hoja" that is being refined. The 1464 configuration data part of the hybrid schema now looks like this: 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1477 9.2.2. Type Derivation Chains 1479 RELAX NG has no equivalent of the type derivation mechanism in YANG 1480 that allows to restrict a built-in type (perhaps in multiple steps) 1481 by adding new constraints. Whenever a derived YANG type is used 1482 without restrictions - as a substatement of either 'leaf' or another 1483 'typedef' - then the 'type' statement is mapped simply to a named 1484 pattern reference , and the type definition is mapped to a 1485 RELAX NG named pattern definition . However, if any 1486 restrictions are specified as substatements of the 'type' statement, 1487 the type definition MUST be expanded at that point so that only the 1488 ancestor built-in type appears in the hybrid schema, restricted with 1489 facets that correspond to the combination of all restrictions found 1490 along the type derivation chain and also in the 'type' statement. 1492 EXAMPLE. Consider this YANG module: 1494 module example3 { 1495 namespace "http://example.com/ns/example3"; 1496 prefix ex3; 1497 typedef dozen { 1498 type uint8 { 1499 range 1..12; 1500 } 1501 } 1502 leaf month { 1503 type dozen; 1504 } 1505 } 1507 The 'type' statement in "leaf month" has no restrictions and is 1508 therefore mapped simply to the reference and the corresponding named pattern is 1510 defined as follows: 1512 1513 1514 1 1515 12 1516 1517 1519 Assume now that the definition of leaf "month" is changed to 1521 leaf month { 1522 type dozen { 1523 range 7..max; 1524 } 1525 } 1527 The output RELAX NG schema then will not contain any named pattern 1528 definition and the leaf "month" will be mapped directly to 1530 1531 1532 7 1533 12 1534 1535 1537 The mapping of type derivation chains may be further complicated by 1538 the presence of the 'default' statement in type definitions. In the 1539 simple case, when a type definition containing the 'default' 1540 statement is used without restrictions, the 'default' statement is 1541 mapped to the @nma:default attribute attached to the 1542 element. 1544 However, if that type definition has to be expanded due to 1545 restrictions, the @nma:default annotation arising from the expanded 1546 type or ancestor types in the type derivation chain MUST be attached 1547 to the pattern where the expansion occurs. If there are multiple 1548 'default' statements in consecutive steps of the type derivation, 1549 only the 'default' statement that is closest to the expanded type is 1550 used. 1552 EXAMPLE. Consider this variation of the last example: 1554 module example3bis { 1555 namespace "http://example.com/ns/example3bis"; 1556 prefix ex3bis; 1557 typedef dozen { 1558 type uint8 { 1559 range 1..12; 1560 } 1561 default 7; 1562 } 1563 leaf month { 1564 type dozen; 1565 } 1566 } 1568 The 'typedef' statement in this module is mapped to the following 1569 named pattern definition: 1571 1572 1573 1 1574 12 1575 1576 1578 If the "dozen" type is restricted when used in the leaf "month" 1579 definition as in the previous example, the "dozen" type has to be 1580 expanded and @nma:default becomes an attribute of the 1581 element definition: 1583 1584 1585 7 1586 12 1587 1588 1590 However, if the definition of the leaf "month" itself contained the 1591 'default' substatement, the default specified for the "dozen" type 1592 would be ignored. 1594 9.3. Translation of XPath Expressions 1596 YANG uses full XPath 1.0 syntax [XPath] for the arguments of 'must', 1597 'when' and 'path' statements. As the names of data nodes defined in 1598 a YANG module always belong to the namespace of that YANG module, 1599 YANG adopted a simplification similar to the concept of default 1600 namespace in XPath 2.0: node names in XPath expressions needn't carry 1601 a namespace prefix inside the module where they are defined and the 1602 local module's namespace is assumed. 1604 Consequently, all XPath expressions MUST be translated into a fully 1605 conformant XPath 1.0 expression: Every unprefixed node name MUST be 1606 prepended with the local module's namespace prefix as declared by the 1607 'prefix' statement. 1609 XPath expressions appearing inside top-level groupings require 1610 special attention because all unprefixed node names contained in them 1611 must adopt the namespace of each module where the grouping is used 1612 (cf. Section 8.2. In order to achieve this, the local prefix MUST be 1613 represented using the variable "$pref" in the hybrid schema. A 1614 Schematron schema which encounters such an XPath expression then 1615 supplies an appropriate value for this variable via a parameter to an 1616 abstract pattern to which the YANG grouping is mapped (see 1617 Section 11.2). 1619 For example, XPath expression "/dhcp/max-lease-time" appearing in a 1620 YANG module with the "dhcp" prefix will be translated to 1622 o "$pref:dhcp/$pref:max-lease-time", if the expression is inside a 1623 top-level grouping; 1625 o "dhcp:dhcp/dhcp:max-lease-time", otherwise. 1627 YANG also uses other XPath-like expressions, namely key identifiers 1628 and "descendant schema node identifiers" (see the ABNF production for 1629 and "descendant-schema-nodeid" in Section 12 of [RFC6020]). These 1630 expressions MUST be translated by adding local module prefixes as 1631 well. 1633 9.4. YANG Language Extensions 1635 YANG allows for extending its own language in-line by adding new 1636 statements with keywords from special namespaces. Such extensions 1637 first have to be declared using the 'extension' statement and then 1638 they can be used as the standard YANG statements, from which they are 1639 distinguished by a namespace prefix qualifying the extension keyword. 1640 RELAX NG has a similar extension mechanism - XML elements and 1641 attributes with names from foreign namespaces may be inserted at 1642 almost any place of a RELAX NG schema. 1644 YANG language extensions may or may not have a meaning in the context 1645 of DSDL schemas. Therefore, an implementation MAY ignore any or all 1646 of the extensions. However, an extension that is not ignored MUST be 1647 mapped to XML element(s) and/or attribute(s) that exactly match the 1648 YIN form of the extension, see Section 11.1 in [RFC6020]. 1650 EXAMPLE. Consider the following extension defined by the "acme" 1651 module: 1653 extension documentation-flag { 1654 argument number; 1655 } 1657 This extension can then be used in the same or another module, for 1658 instance like this: 1660 leaf folio { 1661 acme:documentation-flag 42; 1662 type string; 1663 } 1665 If this extension is honored by the mapping, it will be mapped to 1667 1668 1669 1670 1672 Note that the 'extension' statement itself is not mapped in any way. 1674 10. Mapping YANG Statements to the Hybrid Schema 1676 Each subsection in this section is devoted to one YANG statement and 1677 provides the specification of how the statement is mapped to the 1678 hybrid schema. The subsections are sorted alphabetically by the 1679 statement keyword. 1681 Each YANG statement is mapped to an XML fragment, typically a single 1682 element or attribute but it may also be a larger structure. The 1683 mapping procedure is inherently recursive, which means that after 1684 finishing a statement the mapping continues with its substatements, 1685 if there are any, and a certain element of the resulting fragment 1686 becomes the parent of other fragments resulting from the mapping of 1687 substatements. Any changes to this default recursive procedure are 1688 explicitly specified. 1690 YANG XML encoding rules translate to the following rules for ordering 1691 multiple subelements: 1693 1. Within the subtree (i.e., for input and output 1694 parameters of an RPC operation) the order of subelements is fixed 1695 and their definitions in the hybrid schema MUST follow the order 1696 specified in the source YANG module. 1698 2. When mapping the 'list' statement, all keys MUST come before any 1699 other subelements and in the same order as they are declared in 1700 the 'key' statement. The order of the remaining (non-key) 1701 subelements is not specified, so their definitions in the hybrid 1702 schema MUST be enclosed in the element. 1704 3. Otherwise, the order of subelements is arbitrary and, 1705 consequently, all definitions of subelements in the hybrid schema 1706 MUST be enclosed in the element. 1708 The following conventions are used in this section: 1710 o The argument of the statement being mapped is denoted by ARGUMENT. 1712 o The element in the RELAX NG schema that becomes the parent of the 1713 resulting XML fragment is denoted by PARENT. 1715 10.1. The 'anyxml' Statement 1717 This statement is mapped to element and ARGUMENT with 1718 prepended local namespace prefix becomes the value of its @name 1719 attribute. The contents of are 1721 1722 Substatements of the 'anyxml' statement, if any, MAY be mapped to 1723 additional children of the element. 1725 If at least one 'anyxml' statement occurs in any of the input YANG 1726 modules, the following pattern definition MUST be added exactly once 1727 to the RELAX NG schema as a child of the root element 1728 (cf. [Vli04], p. 172): 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1745 EXAMPLE: YANG statement in a module with namespace prefix "yam" 1747 anyxml data { 1748 description "Any XML content allowed here."; 1749 } 1751 is mapped to the following fragment: 1753 1754 Any XML content allowed here 1755 1756 1758 An anyxml node is optional if there is no "mandatory true;" 1759 substatement. The element then MUST be wrapped in 1760 , except when the 'anyxml' statement is a child of the 1761 'choice' statement and thus forms a shorthand case for that choice 1762 (see Section 9.1.1 for details). 1764 10.2. The 'argument' Statement 1766 This statement is not mapped to the output schema, but see the rules 1767 for handling extensions in Section 9.4. 1769 10.3. The 'augment' Statement 1771 As a substatement of 'uses', this statement is handled as a part of 1772 'uses' mapping, see Section 10.57. 1774 At the top level of a module or submodule, the 'augment' statement is 1775 used for augmenting the schema tree of another YANG module. If the 1776 augmented module is not processed within the same mapping session, 1777 the top-level 'augment' statement MUST be ignored. Otherwise, the 1778 contents of the statement are added to the foreign module with the 1779 namespace of the module where the 'augment' statement appears. 1781 10.4. The 'base' Statement 1783 This statement is ignored as a substatement of 'identity' and handled 1784 within the 'identityref' type if it appears as a substatement of that 1785 type definition, see Section 10.53.6. 1787 10.5. The 'belongs-to' Statement 1789 This statement is not used since the processing of submodules is 1790 always initiated from the main module, see Section 10.24. 1792 10.6. The 'bit' Statement 1794 This statement is handled within the "bits" type, see 1795 Section 10.53.4. 1797 10.7. The 'case' Statement 1799 This statement is mapped to or element, 1800 depending on whether the statement belongs to an definition of an RPC 1801 operation or not. If the argument of a sibling 'default' statement 1802 equals to ARGUMENT, @nma:implicit attribute with the value of "true" 1803 MUST be added to that or element. The 1804 @nma:implicit attribute MUST NOT be used for nodes at the top-level 1805 of a non-default case (see Section 7.9.3 in [RFC6020]). 1807 10.8. The 'choice' Statement 1809 This statement is mapped to element. 1811 If 'choice' has the 'mandatory' substatement with the value of 1812 "true", the attribute @nma:mandatory MUST be added to the element with the value of ARGUMENT. This case may require 1814 additional handling, see Section 11.2.1. Otherwise, if "mandatory 1815 true;" is not present, the element MUST be wrapped in 1816 . 1818 The alternatives in - mapped from either the 'case' 1819 statement or a shorthand case - MUST NOT be defined as optional. 1821 10.9. The 'config' Statement 1823 This statement is mapped to @nma:config attribute and ARGUMENT 1824 becomes its value. 1826 10.10. The 'contact' Statement 1828 This statement SHOULD NOT be used by the mapping since the hybrid 1829 schema may be mapped from multiple YANG modules created by different 1830 authors. The hybrid schema contains references to all input modules 1831 in the Dublin Core elements , see Section 10.34. The 1832 original YANG modules are the authoritative sources of the authorship 1833 information. 1835 10.11. The 'container' Statement 1837 Using the rules specified in Section 9.1.1, the mapping algorithm 1838 MUST determine whether the statement defines an optional container, 1839 and if so, insert the element and make it the new 1840 PARENT. 1842 The container defined by this statement is then mapped to the element, which becomes a child of PARENT and uses ARGUMENT 1844 with prepended local namespace prefix as the value of its @name 1845 attribute. 1847 Finally, using the rules specified in Section 9.1.2, the mapping 1848 algorithm MUST determine whether the container is implicit, and if 1849 so, add the attribute @nma:implicit with the value of "true" to the 1850 element. 1852 10.12. The 'default' Statement 1854 If this statement is a substatement of 'leaf', it is mapped to the 1855 @nma:default attribute of PARENT and ARGUMENT becomes its value. 1857 As a substatement of 'typedef', the 'default' statement is also 1858 mapped to the @nma:default attribute with the value of ARGUMENT. The 1859 placement of this attribute depends on whether or not the type 1860 definition has to be expanded when it is used: 1862 o If the type definition is not expanded, @nma:default becomes an 1863 attribute of the pattern resulting from the parent 1864 'typedef' mapping. 1866 o Otherwise, @nma:default becomes an attribute of the ancestor RELAX 1867 NG pattern inside which the expansion takes place. 1869 Details and an example are given in Section 9.2.2. 1871 Finally, as a substatement of 'choice', the 'default' statement 1872 identifies the default case and is handled within the 'case' 1873 statement, see Section 10.7. If the default case uses the shorthand 1874 notation where the 'case' statement is omitted, the @nma:implicit 1875 attribute with the value of "true" is either attached to the node 1876 representing the default case in the shorthand notation or, 1877 alternatively, an extra element MAY be inserted and the 1878 @nma:implicit attribute attached to it. In the latter case, the net 1879 result is the same as if the 'case' statement wasn't omitted for the 1880 default case. 1882 EXAMPLE. The following 'choice' statement in a module with namespace 1883 prefix "yam" 1885 choice leaves { 1886 default feuille; 1887 leaf feuille { type empty; } 1888 leaf hoja { type empty; } 1889 } 1891 is either mapped directly to 1893 1894 1895 1896 1897 1898 1899 1900 1902 or the default case may be wrapped in an extra : 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1915 10.13. The 'description' Statement 1917 This statement is mapped to the DTD compatibility element 1918 and ARGUMENT becomes its text. 1920 In order to get properly formatted in the RELAX NG compact syntax, 1921 this element SHOULD be inserted as the first child of PARENT. 1923 10.14. The 'deviation' Statement 1925 This statement is ignored. However, it is assumed that all 1926 deviations are known beforehand and the corresponding changes have 1927 already been applied to the input YANG modules. 1929 10.15. The 'enum' Statement 1931 This statement is mapped to element and ARGUMENT becomes 1932 its text. All substatements except 'status' are ignored because the 1933 element cannot contain annotation elements, see [RNG], 1934 section 6. 1936 10.16. The 'error-app-tag' Statement 1938 This statement is ignored unless it is a substatement of 'must'. In 1939 the latter case it is mapped to the element. See 1940 also Section 10.35. 1942 10.17. The 'error-message' Statement 1944 This statement is ignored unless it is a substatement of 'must'. In 1945 the latter case it is mapped to the element. See 1946 also Section 10.35. 1948 10.18. The 'extension' Statement 1950 This statement is ignored. However, extensions to the YANG language 1951 MAY be mapped as described in Section 9.4. 1953 10.19. The 'feature' Statement 1955 This statement is ignored. 1957 10.20. The 'grouping' Statement 1959 This statement is mapped to a RELAX NG named pattern definition , but only if the grouping defined by this statement is used 1961 without refinements and augments in at least one of the input 1962 modules. In this case, the named pattern definition becomes a child 1963 of the element and its name is ARGUMENT mangled 1964 according to the rules specified in Section 9.2. 1966 As explained in Section 8.2, a named pattern definition MUST be 1967 placed 1969 o as a child of the root element if the corresponding 1970 grouping is defined at the top level of an input YANG module; 1972 o otherwise as a child of the embedded element 1973 corresponding to the module in which the grouping is defined. 1975 Whenever a grouping is used with refinements and/or augments, it is 1976 expanded so that the refinements and augments may be applied in place 1977 to the prescribed schema nodes. See Section 9.2.1 for further 1978 details and an example. 1980 An implementation MAY offer the option of mapping all 'grouping' 1981 statements as named pattern definitions in the output RELAX NG schema 1982 even if they are not referenced. This is useful for mapping YANG 1983 "library" modules that typically contain only 'typedef' and/or 1984 'grouping' statements. 1986 10.21. The 'identity' Statement 1988 This statement is mapped to the following named pattern definition 1989 which is placed as a child of the root element: 1991 1992 1993 PREFIX:ARGUMENT 1994 1995 ... 1996 1997 1999 where 2001 PREFIX is the prefix used in the hybrid schema for the namespace 2002 of the module where the current identity is defined. 2004 IDENTITY1 is the name of of the named pattern corresponding to an 2005 identity which is derived from the current identity. Exactly one 2006 element MUST be present for every such identity. 2008 EXAMPLE ([RFC6020], Section 7.16.3). The identities in the input 2009 YANG modules 2010 module crypto-base { 2011 namespace "http://example.com/crypto-base"; 2012 prefix "crypto"; 2013 identity crypto-alg { 2014 description 2015 "Base identity from which all crypto algorithms 2016 are derived."; 2017 } 2018 } 2020 module des { 2021 namespace "http://example.com/des"; 2022 prefix "des"; 2023 import "crypto-base" { 2024 prefix "crypto"; 2025 } 2026 identity des { 2027 base "crypto:crypto-alg"; 2028 description "DES crypto algorithm"; 2029 } 2030 identity des3 { 2031 base "crypto:crypto-alg"; 2032 description "Triple DES crypto algorithm"; 2033 } 2034 } 2036 will be mapped to the following named pattern definitions: 2038 2039 2040 crypto:crypto-alg 2041 2042 2043 2044 2045 2046 des:des 2047 2048 2049 des:des3 2050 2052 10.22. The 'if-feature' Statement 2054 ARGUMENT together with arguments of all sibling 'if-feature' 2055 statements (with added prefixes, if missing) MUST be collected in a 2056 space-separated list which becomes the value of the @nma:if-feature 2057 attribute. This attribute is attached to PARENT. 2059 10.23. The 'import' Statement 2061 This statement is not specifically mapped. The module whose name is 2062 in ARGUMENT has to be parsed so that the importing module is able to 2063 use its top-level groupings, typedefs and identities, and also 2064 augment the data tree of the imported module. 2066 If the 'import' statement has the 'revision' substatement, the 2067 corresponding revision of the imported module MUST be used. The 2068 mechanism for finding a given module revision is outside the scope of 2069 this document. 2071 10.24. The 'include' Statement 2073 This statement is not specifically mapped. The submodule whose name 2074 is in ARGUMENT has to be parsed and its contents mapped exactly as if 2075 the submodule text appeared directly in the main module text. 2077 If the 'include' statement has the 'revision' substatement, the 2078 corresponding revision of the submodule MUST be used. The mechanism 2079 for finding a given submodule revision is outside the scope of this 2080 document. 2082 10.25. The 'input' Statement 2084 This statement is handled within 'rpc' statement, see Section 10.50. 2086 10.26. The 'key' Statement 2088 This statement is mapped to @nma:key attribute. ARGUMENT MUST be 2089 translated so that every key is prefixed with the namespace prefix of 2090 the local module. The result of this translation then becomes the 2091 value of the @nma:key attribute. 2093 10.27. The 'leaf' Statement 2095 This statement is mapped to the element and ARGUMENT 2096 with prepended local namespace prefix becomes the value of its @name 2097 attribute. 2099 If the leaf is optional, i.e., if there is no "mandatory true;" 2100 substatement and the leaf is not declared among the keys of an 2101 enclosing list, then the element MUST be enclosed in 2102 , except when the 'leaf' statement is a child of the 2103 'choice' statement and thus represents a shorthand case for that 2104 choice (see Section 9.1.1 for details). 2106 10.28. The 'leaf-list' Statement 2108 This statement is mapped to a block enclosed by either or element depending on whether the 2110 argument of 'min-elements' substatement is "0" or positive, 2111 respectively (it is zero by default). This or element becomes the PARENT. 2114 is then added as a child element of PARENT and ARGUMENT 2115 with prepended local namespace prefix becomes the value of its @name 2116 attribute. Another attribute, @nma:leaf-list, MUST also be added to 2117 this element with the value of "true". If the 'leaf- 2118 list' statement has the 'min-elements' substatement and its argument 2119 is greater than one, additional attribute @nma:min-elements is 2120 attached to and the argument of 'min-elements' becomes 2121 the value of this attribute. Similarly, if there is the 'max- 2122 elements' substatement and its argument value is not "unbounded", 2123 attribute @nma:max-elements is attached to this element and the 2124 argument of 'max-elements' becomes the value of this attribute. 2126 EXAMPLE. A leaf-list appearing in a module with the namespace prefix 2127 "yam" 2129 leaf-list foliage { 2130 min-elements 3; 2131 max-elements 6378; 2132 ordered-by user; 2133 type string; 2134 } 2136 is mapped to the following RELAX NG fragment: 2138 2139 2142 2143 2144 2146 10.29. The 'length' Statement 2148 This statement is handled within the "string" type, see 2149 Section 10.53.10. 2151 10.30. The 'list' Statement 2153 This statement is mapped exactly as the 'leaf-list' statement, see 2154 Section 10.28. The only difference is that the @nma:leaf-list 2155 annotation either MUST NOT be present or MUST have the value of 2156 "false". 2158 When mapping the substatements of 'list', the order of children of 2159 the list element MUST be specified so that list keys, if there are 2160 any, always appear in the same order as they are defined in the 'key' 2161 substatement and before other children, see [RFC6020], Section 7.8.5. 2162 In particular, if a list key is defined in a grouping but the list 2163 node itself is not a part of the same grouping, and the position of 2164 the 'uses' statement would violate the above ordering requirement, 2165 the grouping MUST be expanded, i.e., the 'uses' statement replaced by 2166 the grouping contents. 2168 For example, consider the following YANG fragment of a module with 2169 the prefix "yam": 2171 grouping keygrp { 2172 leaf clef { 2173 type uint8; 2174 } 2175 } 2176 list foo { 2177 key clef; 2178 leaf bar { 2179 type string; 2180 } 2181 leaf baz { 2182 type string; 2183 } 2184 uses keygrp; 2185 } 2187 is mapped to the following RELAX NG fragment: 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2205 Note that the "keygrp" grouping is expanded and the definition of 2206 "yam:clef" is moved before the pattern. 2208 10.31. The 'mandatory' Statement 2210 This statement may appear as a substatement of 'leaf', 'choice' or 2211 'anyxml' statement. If ARGUMENT is "true", the parent data node is 2212 mapped as mandatory, see Section 9.1.1. 2214 As a substatement of 'choice', this statement is also mapped to the 2215 @nma:mandatory attribute which is added to PARENT. The value of this 2216 attribute is the argument of the parent 'choice' statement. 2218 10.32. The 'max-elements' Statement 2220 This statement is handled within 'leaf-list' or 'list' statements, 2221 see Section 10.28. 2223 10.33. The 'min-elements' Statement 2225 This statement is handled within 'leaf-list' or 'list' statements, 2226 see Section 10.28. 2228 10.34. The 'module' Statement 2230 This statement is mapped to an embedded pattern having 2231 the @nma:module attribute with the value of ARGUMENT. In addition, a 2232 element SHOULD be created as a child of this element and contain ARGUMENT as a metadata reference to the 2234 input YANG module. See also Section 10.49. 2236 Substatements of the 'module' statement MUST be mapped so that 2237 o statements representing configuration/state data are mapped to 2238 descendants of the element; 2240 o statements representing the contents of RPC requests or replies 2241 are mapped to descendants of the element; 2243 o statements representing the contents of event notifications are 2244 mapped to descendants of the element. 2246 10.35. The 'must' Statement 2248 This statement is mapped to the element. It has one 2249 mandatory attribute @assert (with no namespace) which contains 2250 ARGUMENT transformed into a valid XPath expression (see Section 9.3). 2251 The element may have other subelements resulting from 2252 mapping the 'error-app-tag' and 'error-message' substatements. Other 2253 substatements of 'must', i.e., 'description' and 'reference', are 2254 ignored. 2256 EXAMPLE. YANG statement in the "dhcp" module 2258 must 'current() <= ../max-lease-time' { 2259 error-message 2260 "The default-lease-time must be less than max-lease-time"; 2261 } 2263 is mapped to 2265 2266 2267 The default-lease-time must be less than max-lease-time 2268 2269 2271 10.36. The 'namespace' Statement 2273 This statement is mapped simultaneously in two ways: 2275 1. To the @xmlns:PREFIX attribute of the root element 2276 where PREFIX is the namespace prefix specified by the sibling 2277 'prefix' statement. ARGUMENT becomes the value of this 2278 attribute. 2280 2. To the @ns attribute of PARENT, which is an embedded pattern. ARGUMENT becomes the value of this attribute. 2283 10.37. The 'notification' Statement 2285 This statement is mapped to the following subtree of the element in the hybrid schema (where PREFIX is the 2287 prefix of the local YANG module): 2289 2290 2291 ... 2292 2293 2295 Substatements of 'notification' are mapped under . 2298 10.38. The 'ordered-by' Statement 2300 This statement is mapped to @nma:ordered-by attribute and ARGUMENT 2301 becomes the value of this attribute. See Section 10.28 for an 2302 example. 2304 10.39. The 'organization' Statement 2306 This statement is ignored by the mapping because the hybrid schema 2307 may be mapped from multiple YANG modules authored by different 2308 parties. The hybrid schema SHOULD contain references to all input 2309 modules in the Dublin Core elements, see Section 10.34. 2310 The original YANG modules are the authoritative sources of the 2311 authorship information. 2313 10.40. The 'output' Statement 2315 This statement is handled within the 'rpc' statement, see 2316 Section 10.50. 2318 10.41. The 'path' Statement 2320 This statement is handled within the "leafref" type, see 2321 Section 10.53.8. 2323 10.42. The 'pattern' Statement 2325 This statement is handled within the "string" type, see 2326 Section 10.53.10. 2328 10.43. The 'position' Statement 2330 This statement is ignored. 2332 10.44. The 'prefix' Statement 2334 This statement is handled within the sibling 'namespace' statement, 2335 see Section 10.36, or within the parent 'import' statement, see 2336 Section 10.23. As a substatement of 'belongs-to' (in submodules), 2337 the 'prefix' statement is ignored. 2339 10.45. The 'presence' Statement 2341 This statement influences the mapping of the parent container 2342 (Section 10.11): the parent container definition MUST be wrapped in 2343 , regardless of its contents. See also Section 9.1.1. 2345 10.46. The 'range' Statement 2347 This statement is handled within numeric types, see Section 10.53.9. 2349 10.47. The 'reference' Statement 2351 This statement is mapped to element and its text is 2352 set to ARGUMENT prefixed with "See: ". 2354 10.48. The 'require-instance' Statement 2356 This statement is handled within "instance-identifier" type 2357 (Section 10.53.7). 2359 10.49. The 'revision' Statement 2361 The mapping uses only the most recent instance of the 'revision' 2362 statement, i.e., one with the latest date in ARGUMENT, which 2363 specifies the current revision of the input YANG module [RFC6020]. 2364 This date SHOULD be recorded, together with the name of the YANG 2365 module, in the corresponding Dublin Core element (see 2366 Section 10.34), for example in this form: 2368 YANG module 'foo', revision 2010-03-02 2370 The 'description' substatement of 'revision' is ignored. 2372 10.50. The 'rpc' Statement 2374 This statement is mapped to the following subtree in the RELAX NG 2375 schema (where PREFIX is the prefix of the local YANG module): 2377 2378 2379 2380 ... mapped contents of 'input' ... 2381 2382 2383 2384 ... mapped contents of 'output' ... 2385 2386 2388 As indicated in the schema fragment, contents of the 'input' 2389 substatement (if any) are mapped under . Similarly, contents of the 'output' substatement are 2391 mapped under . If there is no 'output' substatement, the 2392 element MUST NOT be present. 2394 The element is a child of . 2396 10.51. The 'status' Statement 2398 This statement MAY be ignored. Otherwise, it is mapped to @nma: 2399 status attribute and ARGUMENT becomes its value. 2401 10.52. The 'submodule' Statement 2403 This statement is not specifically mapped. Its substatements are 2404 mapped as if they appeared directly in the module the submodule 2405 belongs to. 2407 10.53. The 'type' Statement 2409 Most YANG built-in datatypes have an equivalent in the XSD datatype 2410 library [XSD-D] as shown in Table 4. 2412 +-----------+---------------+--------------------------------+ 2413 | YANG type | XSD type | Meaning | 2414 +-----------+---------------+--------------------------------+ 2415 | int8 | byte | 8-bit integer value | 2416 | | | | 2417 | int16 | short | 16-bit integer value | 2418 | | | | 2419 | int32 | int | 32-bit integer value | 2420 | | | | 2421 | int64 | long | 64-bit integer value | 2422 | | | | 2423 | uint8 | unsignedByte | 8-bit unsigned integer value | 2424 | | | | 2425 | uint16 | unsignedShort | 16-bit unsigned integer value | 2426 | | | | 2427 | uint32 | unsignedInt | 32-bit unsigned integer value | 2428 | | | | 2429 | uint64 | unsignedLong | 64-bit unsigned integer value | 2430 | | | | 2431 | string | string | character string | 2432 | | | | 2433 | binary | base64Binary | binary data in base64 encoding | 2434 +-----------+---------------+--------------------------------+ 2436 Table 4: YANG built-in datatypes with equivalents in the W3C XML 2437 Schema Type Library 2439 Two important datatypes of the XSD datatype library - "dateTime" and 2440 "anyURI" - are not built-in types in YANG but instead are defined as 2441 derived types in the standard modules [RFC6021]: "date-and-time" in 2442 the "ietf-yang-types" module and "uri" in the "ietf-inet-types" 2443 module. However, the formal restrictions in the YANG type 2444 definitions are rather weak. Therefore, implementations of the YANG- 2445 to-DSDL mapping SHOULD detect these derived types in source YANG 2446 modules and map them to "dateType" and "anyURI", respectively. 2448 Details about the mapping of individual YANG built-in types are given 2449 in the following subsections. 2451 10.53.1. The "empty" Type 2453 This type is mapped to . 2455 10.53.2. The "boolean" Type 2457 This built-in type does not allow any restrictions and is mapped to 2458 the following XML fragment: 2460 2461 true 2462 false 2463 2465 Note that the XSD "boolean" type cannot be used here because it 2466 allows, unlike YANG, an alternative numeric representation of boolean 2467 values: 0 for "false" and 1 for "true". 2469 10.53.3. The "binary" Type 2471 This built-in type does not allow any restrictions and is mapped 2472 simply by inserting element whose @type attribute value is 2473 set to "base64Binary" (see also Table 4). 2475 10.53.4. The "bits" Type 2477 This type is mapped to and for each 'bit' substatement the 2478 following XML fragment is inserted as a child of : 2480 2481 bit_name 2482 2484 where bit_name is the name of the bit as found in the argument of a 2485 'bit' substatement. 2487 10.53.5. The "enumeration" and "union" Types 2489 These types are mapped to the element. 2491 10.53.6. The "identityref" Type 2493 This type is mapped to the following named pattern reference: 2495 2497 where PREFIX:BASE is the qualified name of the identity appearing in 2498 the argument of the 'base' substatement. 2500 For example, assume that module "des" in Section 10.21 contains the 2501 following leaf definition: 2503 leaf foo { 2504 type identityref { 2505 base crypto:crypto-alg; 2506 } 2507 } 2508 This leaf would then be mapped to the following element pattern: 2510 2511 2512 2514 10.53.7. The "instance-identifier" Type 2516 This type is mapped to element with @type attribute set to 2517 "string". In addition, an empty element 2518 MUST be inserted as a child of PARENT. 2520 The argument of the 'require-instance' substatement, if it exists, 2521 becomes the value of the @require-instance attribute of the element. 2524 10.53.8. The "leafref" Type 2526 This type is mapped exactly as the type of the leaf given in the 2527 argument of 'path' substatement. However, if the type of the 2528 referred leaf defines a default value, this default value MUST be 2529 ignored by the mapping. 2531 In addition, @nma:leafref attribute MUST be added to PARENT. The 2532 argument of the 'path' substatement, translated according to 2533 Section 9.3, is set as the value of this attribute. 2535 10.53.9. The Numeric Types 2537 YANG built-in numeric types are "int8", "int16", "int32", "int64", 2538 "uint8", "uint16", "uint32", "uint64" and "decimal64". They are 2539 mapped to element with @type attribute set to ARGUMENT 2540 translated according to Table 4 above. 2542 An exception is the "decimal64" type, which is mapped to the 2543 "decimal" type of the XSD datatype library. Its precision and number 2544 of fractional digits are controlled with the following facets, which 2545 MUST always be present: 2547 o "totalDigits" facet set to the value of 19. 2549 o "fractionDigits" facet set to the argument of the 'fraction- 2550 digits' substatement. 2552 The fixed value of "totalDigits" corresponds to the maximum of 19 2553 decimal digits for 64-bit integers. 2555 For example, the statement 2556 type decimal64 { 2557 fraction-digits 2; 2558 } 2560 is mapped to the following RELAX NG datatype: 2562 2563 19 2564 2 2565 2567 All numeric types support the 'range' restriction, which is mapped as 2568 follows: 2570 If the range expression consists of just a single range LO..HI, then 2571 it is mapped to a pair of datatype facets 2573 LO 2575 and 2577 HI 2579 If the range consists of a single number, the values of both facets 2580 are set to this value. If LO is equal to the string "min", the 2581 "minInclusive" facet is omitted. If HI is equal to the string "max", 2582 the "maxInclusive" facet is omitted. 2584 If the range expression has multiple parts separated by "|", then the 2585 parent element must be repeated once for every range part 2586 and all such elements are wrapped in element. 2587 Each element contains the "minInclusive" and 2588 "maxInclusive" facets for one part of the range expression as 2589 described in the previous paragraph. 2591 For the "decimal64" type, the "totalDigits" and "fractionDigits" must 2592 be repeated inside each of the elements. 2594 For example, 2596 type int32 { 2597 range "-6378..0|42|100..max"; 2598 } 2600 is mapped to the following RELAX NG fragment: 2602 2603 2604 -6378 2605 0 2606 2607 2608 42 2609 42 2610 2611 2612 100 2613 2614 2616 See Section 9.2.2 for further details on mapping the restrictions. 2618 10.53.10. The "string" Type 2620 This type is mapped to element with the @type attribute 2621 set to "string". 2623 The 'length' restriction is handled analogically to the 'range' 2624 restriction for the numeric types (Section 10.53.9): 2626 If the length expression has just a single range, then 2628 o if the length range consists of a single number LENGTH, the 2629 following datatype facet is inserted: 2631 LENGTH. 2633 o Otherwise the length range is of the form LO..HI, i.e., it 2634 consists of both the lower and upper bound. The following two 2635 datatype facets are then inserted: 2637 LO 2639 and 2641 HI 2643 If LO is equal to the string "min", the "minLength" facet is 2644 omitted. If HI is equal to the string "max", the "maxLength" 2645 facet is omitted. 2647 If the length expression has of multiple parts separated by "|", then 2648 the parent element must be repeated once for every range 2649 part and all such elements are wrapped in 2650 element. Each element contains the "length" or 2651 "minLength" and "maxLength" facets for one part of the length 2652 expression as described in the previous paragraph. 2654 Every 'pattern' restriction of the "string" datatype is mapped to the 2655 "pattern" facet 2657 ... 2659 with text equal to the argument of the 'pattern' statement. All such 2660 "pattern" facets must be repeated inside each copy of the 2661 element, i.e., once for each length range. 2663 For example, 2665 type string { 2666 length "1|3..8"; 2667 pattern "[A-Z][a-z]*"; 2668 } 2670 is mapped to the following RELAX NG fragment: 2672 2673 2674 1 2675 [A-Z][a-z]* 2676 2677 2678 3 2679 8 2680 [A-Z][a-z]* 2681 2682 2684 10.53.11. Derived Types 2686 If the 'type' statement refers to a derived type, it is mapped in one 2687 of the following ways depending on whether it contains any 2688 restrictions as its substatements: 2690 1. Without restrictions, the 'type' statement is mapped simply to 2691 the element, i.e., a reference to a named pattern. If 2692 the RELAX NG definition of this named pattern has not been added 2693 to the hybrid schema yet, the corresponding type definition MUST 2694 be found and its mapping installed as a subelement of either the 2695 root or an embedded element, see Section 10.54. 2696 Even if a given derived type is used more than once in the input 2697 YANG modules, the mapping of the corresponding 'typedef' MUST be 2698 installed only once. 2700 2. If any restrictions are present, the ancestor built-in type for 2701 the given derived type must be determined and the mapping of this 2702 base type MUST be used. Restrictions appearing at all stages of 2703 the type derivation chain MUST be taken into account and their 2704 conjunction added to the element which defines the 2705 basic type. 2707 See Section 9.2.2 for more details and an example. 2709 10.54. The 'typedef' Statement 2711 This statement is mapped to a RELAX NG named pattern definition , but only if the type defined by this statement is used 2713 without restrictions in at least one of the input modules. In this 2714 case, the named pattern definition becomes a child of either the root 2715 or an embedded element, depending on whether the 2716 'typedef' statement appears at the top level of a YANG module or not. 2717 The name of this named pattern definition is set to ARGUMENT mangled 2718 according to the rules specified in Section 9.2. 2720 Whenever a derived type is used with additional restrictions, the 2721 ancestor built-in type for the derived type is used instead with 2722 restrictions (facets) that are a combination of all restrictions 2723 specified along the type derivation chain. See Section 10.53.11 for 2724 further details and an example. 2726 An implementation MAY offer the option of recording all 'typedef' 2727 statements as named patterns in the output RELAX NG schema even if 2728 they are not referenced. This is useful for mapping YANG "library" 2729 modules containing only 'typedef' and/or 'grouping' statements. 2731 10.55. The 'unique' Statement 2733 This statement is mapped to @nma:unique attribute. ARGUMENT MUST be 2734 translated so that every node identifier in each of its components is 2735 prefixed with the namespace prefix of the local module, unless the 2736 prefix is already present. The result of this translation then 2737 becomes the value of the @nma:unique attribute. 2739 For example, assuming that the local module prefix is "ex", 2741 unique "foo ex:bar/baz" 2743 is mapped to the following attribute/value pair: 2745 nma:unique="ex:foo ex:bar/ex:baz" 2747 10.56. The 'units' Statement 2749 This statement is mapped to @nma:units attribute and ARGUMENT becomes 2750 its value. 2752 10.57. The 'uses' Statement 2754 If this statement has neither 'refine' nor 'augment' substatements, 2755 it is mapped to element, i.e., a reference to a named 2756 pattern, and the value of its @name attribute is set to ARGUMENT 2757 mangled according to Section 9.2. If the RELAX NG definition of the 2758 referenced named pattern has not been added to the hybrid schema yet, 2759 the corresponding grouping MUST be found and its mapping installed as 2760 a subelement of , see Section 10.20. 2762 Otherwise, if the 'uses' statement has any 'refine' or 'augment' 2763 substatements, the corresponding grouping must be looked up and its 2764 contents inserted under PARENT. See Section 9.2.1 for further 2765 details and an example. 2767 10.58. The 'value' Statement 2769 This statement is ignored. 2771 10.59. The 'when' Statement 2773 This statement is mapped to @nma:when attribute and ARGUMENT, 2774 translated according to Section 9.3, becomes it value. 2776 10.60. The 'yang-version' Statement 2778 This statement is not mapped to the output schema. However, an 2779 implementation SHOULD check that it is compatible with the YANG 2780 version declared by the statement (currently version 1). In the case 2781 of a mismatch, the implementation SHOULD report an error and 2782 terminate. 2784 10.61. The 'yin-element' Statement 2786 This statement is not mapped to the output schema, but see the rules 2787 for extension handling in Section 9.4. 2789 11. Mapping the Hybrid Schema to DSDL 2791 As explained in Section 6, the second step of the YANG-to-DSDL 2792 mapping takes the hybrid schema and transforms it to various DSDL 2793 schemas capable of validating instance XML documents. As an input 2794 parameter, this step takes, in the simplest case, just a 2795 specification of the NETCONF XML document type that is to be 2796 validated. These document types can be, for example, the contents of 2797 a datastore, a reply to or , contents of 2798 other RPC requests/replies and event notifications, and so on. 2800 The second mapping step has to accomplish the following three general 2801 tasks: 2803 1. Extract the parts of the hybrid schema that are appropriate for 2804 the requested document type. For example, if a reply is 2805 to be validated, the subtree under has to be selected. 2807 2. The schema must be adapted to the specific encapsulating XML 2808 elements mandated by the RPC layer. These are, for example, and elements in the case of a reply or 2810 for a notification. 2812 3. Finally, NETMOD-specific annotations that are relevant for the 2813 schema language of the generated schema must be mapped to the 2814 corresponding patterns or rules. 2816 These three tasks are together much simpler than the first mapping 2817 step and can be effectively implemented using XSL transformations 2818 [XSLT]. 2820 The following subsections describe the details of the second mapping 2821 step for the individual DSDL schema languages. Section 12 then 2822 contains a detailed specification for the mapping of all NETMOD- 2823 specific annotations. 2825 11.1. Generating RELAX NG Schemas for Various Document Types 2827 With one minor exception, obtaining a validating RELAX NG schema from 2828 the hybrid schema only means taking appropriate parts of the hybrid 2829 schema and assembling them in a new RELAX NG grammar, perhaps after 2830 removing all unwanted annotations. 2832 The structure of the resulting RELAX NG schema is similar to that of 2833 the hybrid schema: The root grammar contains embedded grammars, one 2834 for each input YANG module. However, as explained in Section 8.2, 2835 global named pattern definitions (children of the root 2836 element) MUST be moved to a separate schema file. 2838 Depending on the XML document type that is the target for validation, 2839 such as / reply, RPC operations or 2840 notifications, patterns defining corresponding top-level information 2841 items MUST be added, such as with the @message-id 2842 attribute and so on. 2844 In order to avoid copying common named pattern definitions for common 2845 NETCONF elements and attributes to every single output RELAX NG file, 2846 such schema-independent definitions SHOULD be collected in a library 2847 file which is then included by the validating RELAX NG schemas. 2848 Appendix B has the listing of such a library file. 2850 The minor exception mentioned above is the annotation @nma:config, 2851 which must be observed if the target document type is a reply to . In this case, each element definition that has this 2853 attribute with the value of "false" MUST be removed from the schema 2854 together with its descendants. See Section 12.1 for more details. 2856 11.2. Mapping Semantic Constraints to Schematron 2858 Schematron schemas tend to be much flatter and more uniform compared 2859 to RELAX NG. They have exactly four levels of XML hierarchy: , , and or . 2862 In a Schematron schema generated by the second mapping step, the 2863 basic unit of organization is a rule represented by the 2864 element. The following NETMOD-specific annotations from the hybrid 2865 schema (henceforth called "semantic annotations") are mapped to 2866 corresponding Schematron rules: , @nma:key, @nma:unique, 2867 @nma:max-elements, @nma:min-elements, @nma:when, @nma:leafref, @nma: 2868 leaf-list, and also @nma:mandatory appearing as an attribute of (see Section 11.2.1). 2871 Each input YANG module is mapped to a Schematron pattern whose @id 2872 attribute is set to the module name. Every pattern 2873 containing at least one of the above-mentioned semantic annotations 2874 is then mapped to a Schematron rule: 2876 2877 ... 2878 2880 The value of the mandatory @context attribute of (denoted 2881 as XELEM) MUST be set to the absolute path of the context element in 2882 the data tree. The element contains the mappings of all 2883 contained semantic annotations in the form of Schematron asserts or 2884 reports. 2886 Semantic annotations appearing inside a named pattern definition 2887 (i.e., having among its ancestors) require special 2888 treatment because they may be potentially used in different contexts. 2889 This is accomplished by using Schematron abstract patterns that use 2890 the "$pref" variable in place of the local namespace prefix. The 2891 value of the @id attribute of such an abstract pattern MUST be set to 2892 the name of the named pattern definition which is being mapped (i.e., 2893 the mangled name of the original YANG grouping). 2895 When the abstract pattern is instantiated, the values of the 2896 following two parameters MUST be provided: 2898 o pref: the actual namespace prefix, 2900 o start: XPath expression defining the context in which the grouping 2901 is used. 2903 EXAMPLE. Consider the following YANG module: 2905 module example4 { 2906 namespace "http://example.com/ns/example4"; 2907 prefix ex4; 2908 uses sorted-leaf-list; 2909 grouping sorted-leaf-list { 2910 leaf-list sorted-entry { 2911 must "not(preceding-sibling::sorted-entry > .)" { 2912 error-message "Entries must appear in ascending order."; 2913 } 2914 type uint8; 2915 } 2916 } 2917 } 2919 The resulting Schematron schema for a reply to is then as 2920 follows: 2922 2923 2924 2925 2927 2929 2930 2932 Duplicate leaf-list entry "". 2933 2934 2936 Entries must appear in ascending order. 2937 2938 2939 2940 2941 2942 2943 2944 2945 2947 The "sorted-leaf-list" grouping from the input module is mapped to an 2948 abstract pattern with an @id value of "_example4__sorted-leaf-list" 2949 in which the 'must' statement corresponds to the 2950 element. The abstract pattern is the instantiated by the pattern 2951 with an @id value of "id2802112" which sets the "start" and "pref" 2952 parameters to appropriate values. 2954 Note that another Schematron element, , was automatically 2955 added, checking for duplicate leaf-list entries. 2957 The mapping from the hybrid schema to Schematron proceeds in the 2958 following steps: 2960 1. First, the active subtree(s) of the hybrid schema must be 2961 selected depending on the requested target document type. This 2962 procedure is identical to the RELAX NG case, including the 2963 handling of @nma:config if the target document type is reply. 2966 2. Namespaces of all input YANG modules, together with the 2967 namespaces of base NETCONF ("nc" prefix) or notifications ("en" 2968 prefix) MUST be declared using the element, for example 2970 2972 3. One pattern is created for every input module. In addition, an 2973 abstract pattern is created for every named pattern definition 2974 containing one or more semantic annotations. 2976 4. A element is created for each element pattern 2977 containing semantic annotations. 2979 5. Every such annotation is then mapped to an or element which is installed as a child of the 2981 element. 2983 11.2.1. Constraints on Mandatory Choice 2985 In order to fully represent the semantics of YANG's 'choice' 2986 statement with the "mandatory true;" substatement, the RELAX NG 2987 grammar has to be combined with a special Schematron rule. 2989 EXAMPLE. Consider the following module: 2991 module example5 { 2992 namespace "http://example.com/ns/example5"; 2993 prefix ex5; 2994 choice foobar { 2995 mandatory true; 2996 case foo { 2997 leaf foo1 { 2998 type uint8; 2999 } 3000 leaf foo2 { 3001 type uint8; 3002 } 3003 } 3004 leaf bar { 3005 type uint8; 3006 } 3007 } 3008 } 3010 In this module, all three leaf nodes in both case branches are 3011 optional but because of the "mandatory true;" statement, at least one 3012 of them must be present in a valid configuration. The 'choice' 3013 statement from this module is mapped to the following fragment of the 3014 RELAX NG schema: 3016 3017 3018 3019 3020 3021 3022 3023 3024 3025 3026 3027 3028 3029 3030 3031 3032 3034 In the second case branch, the "ex5:bar" element is defined as 3035 mandatory so that this element must be present in a valid 3036 configuration if this branch is selected. However, the two elements 3037 in the first branch "foo" cannot be both declared as mandatory since 3038 each of them alone suffices for a valid configuration. As a result, 3039 the above RELAX NG fragment would successfully validate 3040 configurations where none of the three leaf elements are present. 3042 Therefore, mandatory choices, which can be recognized in the hybrid 3043 schema as elements with the @nma:mandatory annotation, 3044 have to be handled in a special way: For each mandatory choice where 3045 at least one of the cases contains more than one node, a Schematron 3046 rule MUST be added enforcing the presence of at least one element 3047 from any of the cases. (RELAX NG schema guarantees that elements 3048 from different cases cannot be mixed together, that all mandatory 3049 nodes are present etc.). 3051 For the example module above, the Schematron rule will be as follows: 3053 3054 3055 Node(s) from at least one case of choice "foobar" must exist. 3056 3057 3059 11.3. Mapping Default Values to DSRL 3061 DSRL is the only component of DSDL which is allowed to change the 3062 information set of the validated XML document. While DSRL also has 3063 other functions, YANG-to-DSDL mapping uses it only for specifying and 3064 applying default contents. For XML instance documents based on YANG 3065 data models, insertion of default contents may potentially take place 3066 for all implicit nodes identified by the rules in Section 9.1.2. 3068 In DSRL, the default contents of an element are specified using the 3069 element, which is a child of . Two sibling elements of determine the 3071 context for the application of the default contents, see [DSRL]: 3073 o element contains an XSLT pattern specifying the 3074 parent element; the default contents are applied only if the 3075 parent element exists in the instance document. 3077 o contains the XML name of the element which, if missing 3078 or empty, is inserted together with the contents of . 3081 The element is optional in a general DSRL schema but, 3082 for the purpose of the YANG-to-DSDL mapping, this element MUST be 3083 always present, in order to guarantee a proper application of default 3084 contents. 3086 DSRL mapping only deals with patterns in the hybrid 3087 schema that define implicit nodes (see Section 9.1.2). Such element 3088 patterns are distinguished by having NETMOD-specific annotation 3089 attributes @nma:default or @nma:implicit, i.e., either 3091 3092 ... 3093 3095 or 3097 3098 ... 3099 3101 The former case applies to leaf nodes having the 'default' 3102 substatement, but also to leaf nodes that obtain their default value 3103 from a typedef, if this typedef is expanded according to the rules in 3104 Section 9.2.2 so that the @nma:default annotation is attached 3105 directly to the leaf's element pattern. 3107 The latter case is used for all implicit containers (see Section 9.1) 3108 and for leafs that obtain the default value from a typedef and don't 3109 have the @nma:default annotation. 3111 In the simplest case, both element patterns are mapped to the 3112 following DSRL element map: 3114 3115 XPARENT 3116 ELEM 3117 DEFCONT 3118 3120 where XPARENT is the absolute XPath of ELEM's parent element in the 3121 data tree and DEFCONT is constructed as follows: 3123 o If the implicit node ELEM is a leaf and has the @nma:default 3124 attribute, DEFCONT is set to the value of this attribute (denoted 3125 above as DEFVALUE). 3127 o If the implicit node ELEM is a leaf and has the @nma:implicit 3128 attribute with the value of "true", the default value has to be 3129 determined from the @nma:default attribute of the definition of 3130 ELEM's type (perhaps recursively) and used in place of DEFCONT in 3131 the above DSRL element map. See also Section 9.2.2. 3133 o Otherwise, the implicit node ELEM is a container and DEFCONT is 3134 constructed as an XML fragment containing all descendant elements 3135 of ELEM that have either @nma:implicit or @nma:default attribute. 3137 In addition, when mapping the default case of a choice, it has to be 3138 guaranteed that the default contents are not applied if any node from 3139 any non-default case is present. This is accomplished by setting 3140 in a special way: 3142 XPARENT[not (ELEM1|ELEM2|...|ELEMn)] 3144 where ELEM1, ELEM2, ... ELEMn are the names of all top-level nodes 3145 from all non-default cases. The rest of the element map is exactly 3146 as before. 3148 EXAMPLE. Consider the following YANG module: 3150 module example6 { 3151 namespace "http://example.com/ns/example6"; 3152 prefix ex6; 3153 container outer { 3154 leaf leaf1 { 3155 type uint8; 3156 default 1; 3157 } 3158 choice one-or-two { 3159 default "one"; 3160 container one { 3161 leaf leaf2 { 3162 type uint8; 3163 default 2; 3164 } 3165 } 3166 leaf leaf3 { 3167 type uint8; 3168 default 3; 3169 } 3170 } 3171 } 3172 } 3174 The DSRL schema generated for the "get-reply" target document type 3175 will be: 3177 3178 3181 3182 /nc:rpc-reply/nc:data 3183 ex6:outer 3184 3185 1 3186 3187 2 3188 3189 3190 3191 3192 /nc:rpc-reply/nc:data/ex6:outer 3193 ex6:leaf1 3194 1 3195 3196 3197 3198 /nc:rpc-reply/nc:data/ex6:outer[not(ex6:leaf3)] 3199 3200 ex6:one 3201 3202 2 3203 3204 3205 3206 3207 /nc:rpc-reply/nc:data/ex6:outer/ex6:one 3208 3209 ex6:leaf2 3210 2 3211 3212 3214 Note that the default value for "leaf3" defined in the YANG module is 3215 ignored because "leaf3" represents a non-default alternative of a 3216 choice and as such never becomes an implicit element. 3218 12. Mapping NETMOD-specific Annotations to DSDL Schema Languages 3220 This section contains the mapping specification for the individual 3221 NETMOD-specific annotations. In each case, the result of the mapping 3222 must be inserted into an appropriate context of the target DSDL 3223 schema as described in Section 11. The context is determined by the 3224 element pattern in the hybrid schema to which the annotation is 3225 attached. In the rest of this section, CONTELEM will denote the name 3226 of this context element properly qualified with its namespace prefix. 3228 12.1. The @nma:config Annotation 3230 If this annotation is present with the value of "false", the 3231 following rules MUST be observed for DSDL schemas of 3232 reply: 3234 o When generating RELAX NG, the contents of the CONTELEM definition 3235 MUST be changed to . 3237 o When generating Schematron or DSRL, the CONTELEM definition and 3238 all its descendants in the hybrid schema MUST be ignored. 3240 12.2. The @nma:default Annotation 3242 This annotation is used for generating the DSRL schema as described 3243 in Section 11.3. 3245 12.3. The Annotation 3247 This annotation currently has no mapping defined. 3249 12.4. The Annotation 3251 This annotation is handled within , see Section 12.13. 3253 12.5. The @if-feature Annotation 3255 The information about available features MAY be supplied as an input 3256 parameter to an implementation. In this case, the following changes 3257 MUST be performed for all features that are considered unavailable: 3259 o When generating RELAX NG, the contents of the CONTELEM definition 3260 MUST be changed to . 3262 o When generating Schematron or DSRL, the CONTELEM definition and 3263 all its descendants in the hybrid schema MUST be ignored. 3265 12.6. The @nma:implicit Annotation 3267 This annotation is used for generating the DSRL schema as described 3268 in Section 11.3. 3270 12.7. The Annotation 3272 If this annotation element has the @require-instance attribute with 3273 the value of "false", it is ignored. Otherwise it is mapped to the 3274 following Schematron assert: 3276 3277 The element pointed to by "CONTELEM" must exist. 3278 3280 The nmf:evaluate() function is an XSLT extension function (see 3281 Extension Functions in [XSLT]) that evaluates an XPath expression at 3282 run time. Such an extension function is available in Extended XSLT 3283 (EXSLT) or provided as a proprietary extension by some XSLT 3284 processors, for example Saxon. 3286 12.8. The @nma:key Annotation 3288 Assume this annotation attribute contains "k_1 k_2 ... k_n", i.e., 3289 specifies n children of CONTELEM as list keys. The annotation is 3290 then mapped to the following Schematron report: 3292 3293 Duplicate key of list "CONTELEM" 3294 3296 where CONDITION has this form: 3297 preceding-sibling::CONTELEM[C_1 and C_2 and ... and C_n] 3299 Each sub-expression C_i, for i=1,2,...,n, specifies the condition for 3300 violated uniqueness of the key k_i, namely 3302 k_i=current()/k_i 3304 12.9. The @nma:leaf-list Annotation 3306 This annotation is mapped to the following Schematron rule which 3307 detects duplicate entries of a leaf-list: 3309 3311 Duplicate leaf-list entry "". 3312 3313 See Section 11.2 for a complete example. 3315 12.10. The @nma:leafref Annotation 3317 This annotation is mapped to the following assert: 3319 3320 Leaf "PATH" does not exist for leafref value "VALUE" 3321 3323 where PATH is the value of @nma:leafref and VALUE is the value of the 3324 context element in the instance document for which the referred leaf 3325 doesn't exist. 3327 12.11. The @nma:min-elements Annotation 3329 This annotation is mapped to the following Schematron assert: 3331 3332 List "CONTELEM" - item count must be at least MIN 3333 3335 where MIN is the value of @nma:min-elements. 3337 12.12. The @nma:max-elements Annotation 3339 This annotation is mapped to the following Schematron assert: 3341 3343 Number of list items must be at most MAX 3344 3346 where MAX is the value of @nma:min-elements. 3348 12.13. The Annotation 3350 This annotation is mapped to the following Schematron assert: 3352 3353 MESSAGE 3354 3356 where EXPRESSION is the value of the mandatory @assert attribute of 3357 . If the subelement exists, MESSAGE is 3358 set to its contents, otherwise it is set to the default message 3359 "Condition EXPRESSION must be true". 3361 12.14. The Annotation 3363 This annotation currently has no mapping defined. 3365 12.15. The Annotation 3367 This annotation currently has no mapping defined. 3369 12.16. The @nma:unique Annotation 3371 The mapping of this annotation is almost identical as for @nma:key, 3372 see Section 12.8, with two small differences: 3374 o The value of @nma:unique is a list of descendant schema node 3375 identifiers rather than simple leaf names. However, the XPath 3376 expressions specified in Section 12.8 work without any 3377 modifications if the descendant schema node identifiers are 3378 substituted for k_1, k_2, ..., k_n. 3380 o The message appearing as the text of is different: 3381 "Violated uniqueness for list CONTELEM". 3383 12.17. The @nma:when Annotation 3385 This annotation is mapped to the following Schematron assert: 3387 3388 Node "CONTELEM" is only valid when "EXPRESSION" is true. 3389 3391 where EXPRESSION is the value of @nma:when. 3393 13. IANA Considerations 3395 This document requests the following two registrations of namespace 3396 URIs in the IETF XML registry [RFC3688]: 3398 ----------------------------------------------------- 3399 URI: urn:ietf:params:xml:ns:netmod:dsdl-annotations:1 3401 Registrant Contact: The IESG. 3403 XML: N/A, the requested URI is an XML namespace. 3404 ----------------------------------------------------- 3406 ----------------------------------------------------- 3407 URI: urn:ietf:params:xml:ns:netmod:xpath-extensions:1 3409 Registrant Contact: The IESG. 3411 XML: N/A, the requested URI is an XML namespace. 3412 ----------------------------------------------------- 3414 14. Security Considerations 3416 This document defines a procedure that maps data models expressed in 3417 the YANG language to a coordinated set of DSDL schemas. The 3418 procedure itself has no security impact on the Internet. 3420 DSDL schemas obtained by the mapping procedure may be used for 3421 validating the contents of NETCONF messages or entire datastores and 3422 thus provide additional validity checks above those performed by 3423 NETCONF server and client implementations supporting YANG data 3424 models. The strictness of this validation is directly derived from 3425 the source YANG modules that the validated XML data adhere to. 3427 15. Contributors 3429 The following people contributed significantly to the initial version 3430 of this document: 3432 o Rohan Mahy 3434 o Sharon Chisholm (Ciena) 3436 16. Acknowledgments 3438 The editor wishes to thank the following individuals who provided 3439 helpful suggestions and/or comments on various versions of this 3440 document: Andy Bierman, Martin Bjorklund, Jirka Kosek, Juergen 3441 Schoenwaelder and Phil Shafer. 3443 17. References 3445 17.1. Normative References 3447 [DSDL] ISO/IEC, "Document Schema Definition Languages (DSDL) - 3448 Part 1: Overview", ISO/IEC 19757-1, November 2004. 3450 [DSRL] ISO/IEC, "Information Technology - Document Schema 3451 Definition Languages (DSDL) - Part 8: Document Semantics 3452 Renaming Language - DSRL", ISO/IEC 19757-8:2008(E), 3453 December 2008. 3455 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3456 Requirement Levels", BCP 14, RFC 2119, March 1997. 3458 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3459 January 2004. 3461 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 3462 December 2006. 3464 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 3465 Network Configuration Protocol (NETCONF)", RFC 6020, 3466 September 2010. 3468 [RFC6021] Schoenwaelder, J., Ed., "Common YANG Data Types", 3469 RFC 6021, September 2010. 3471 [RNG] ISO/IEC, "Information Technology - Document Schema 3472 Definition Languages (DSDL) - Part 2: Regular-Grammar- 3473 Based Validation - RELAX NG. Second Edition.", ISO/ 3474 IEC 19757-2:2008(E), December 2008. 3476 [RNG-CS] ISO/IEC, "Information Technology - Document Schema 3477 Definition Languages (DSDL) - Part 2: Regular-Grammar- 3478 Based Validation - RELAX NG. AMENDMENT 1: Compact Syntax", 3479 ISO/IEC 19757-2:2003/Amd. 1:2006(E), January 2006. 3481 [RNG-DTD] Clark, J., Ed. and M. Murata, Ed., "RELAX NG DTD 3482 Compatibility", OASIS Committee Specification 3 December 3483 2001, December 2001. 3485 [Schematron] 3486 ISO/IEC, "Information Technology - Document Schema 3487 Definition Languages (DSDL) - Part 3: Rule-Based 3488 Validation - Schematron", ISO/IEC 19757-3:2006(E), 3489 June 2006. 3491 [XML] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and 3492 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 3493 Edition)", World Wide Web Consortium Recommendation REC- 3494 xml-20081126, November 2008, 3495 . 3497 [XML-INFOSET] 3498 Tobin, R. and J. Cowan, "XML Information Set (Second 3499 Edition)", World Wide Web Consortium Recommendation REC- 3500 xml-infoset-20040204, February 2004, 3501 . 3503 [XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) 3504 Version 1.0", World Wide Web Consortium 3505 Recommendation REC-xpath-19991116, November 1999, 3506 . 3508 [XSD-D] Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes 3509 Second Edition", World Wide Web Consortium 3510 Recommendation REC-xmlschema-2-20041028, October 2004, 3511 . 3513 [XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World 3514 Wide Web Consortium Recommendation REC-xslt-19991116, 3515 November 1999. 3517 17.2. Informative References 3519 [DHCPtut] Bjorklund, M., "DHCP Tutorial", November 2007, . 3522 [RFC1157] Case, J., Fedor, M., Schoffstall, M., and J. Davin, 3523 "Simple Network Management Protocol (SNMP)", STD 15, 3524 RFC 1157, May 1990. 3526 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 3527 Schoenwaelder, Ed., "Structure of Management Information 3528 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 3530 [RFC5013] Kunze, J., "The Dublin Core Metadata Element Set", 3531 RFC 5013, August 2007. 3533 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 3534 Notifications", RFC 5277, July 2008. 3536 [Trang] Clark, J., "Trang: Multiformat schema converter based on 3537 RELAX NG", 2008, 3538 . 3540 [Vli04] van der Vlist, E., "RELAX NG", O'Reilly , 2004. 3542 [XSD] Thompson, H., Beech, D., Maloney, M., and N. Mendelsohn, 3543 "XML Schema Part 1: Structures Second Edition", World Wide 3544 Web Consortium Recommendation REC-xmlschema-1-20041028, 3545 October 2004, 3546 . 3548 [pyang] Bjorklund, M. and L. Lhotka, "pyang: An extensible YANG 3549 validator and converter in Python", 2010, 3550 . 3552 Appendix A. RELAX NG Schema for NETMOD-Specific Annotations 3554 This appendix defines the content model for all NETMOD-specific 3555 annotations in the form of RELAX NG named pattern definitions. 3557 file "nmannot.rng" 3559 3560 3564 3565 3566 3567 3568 3570 3571 3572 3573 3574 3576 3577 3578 3579 3580 3582 3583 3584 3585 3586 3588 3589 3590 3591 3592 3594 3595 3596 3597 3598 3599 3601 3603 3604 3605 3606 3607 3609 3610 3611 3612 3613 3614 3615 3616 3617 3619 3620 3621 3622 3623 3624 3625 3627 3628 3629 3630 3631 3633 3634 3635 3636 3637 3639 3640 3641 3642 3643 3645 3646 3647 3648 3650 3652 3653 3654 3655 3656 3658 3659 3660 3661 3662 3664 3665 3666 3667 3668 3669 3670 3671 3672 3673 3674 3675 3676 3677 3678 3680 3681 3682 3683 3684 3685 3686 3687 3688 3690 3691 3692 3693 3694 3695 3696 3697 3698 3699 3700 3701 3702 3703 3704 3705 3706 3707 3709 3710 3711 3712 user 3713 system 3714 3715 3716 3718 3719 3720 3721 3722 current 3723 deprecated 3724 obsolete 3725 3726 3727 3728 3730 3731 3732 3733 3734 3735 3736 3737 3738 3740 3741 3742 3743 3744 3745 3747 3749 3750 3751 3752 3753 3754 3755 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3767 3768 3769 3770 3772 3774 3776 Appendix B. Schema-Independent Library 3778 In order to avoid copying the common named pattern definitions to 3779 every RELAX NG schema generated in the second mapping step, the 3780 definitions are collected in a library file - schema-independent 3781 library - which is included by the validating schemas under the file 3782 name "relaxng-lib.rng" (XML syntax) and "relaxng-lib.rnc" (compact 3783 syntax). The included definitions cover patterns for common elements 3784 from base NETCONF [RFC4741] and event notifications [RFC5277]. 3786 file "relaxng-lib.rng" 3788 3790 3795 3796 3797 3798 4095 3799 3800 3801 3803 3804 3805 3806 3807 3809 3810 3811 3812 3813 3814 3816 3818 Appendix C. Mapping DHCP Data Model - A Complete Example 3820 This appendix demonstrates both steps of the YANG-to-DSDL mapping 3821 applied to the "canonical" DHCP tutorial [DHCPtut] data model. The 3822 input YANG module is shown in Appendix C.1 and the output schemas in 3823 the following two subsections. 3825 The hybrid schema was obtained by the "dsdl" plugin of the pyang tool 3826 [pyang] and the validating DSDL schemas were obtained by XSLT 3827 stylesheets that are also part of pyang distribution. 3829 Due to the limit of 72 characters per line, a few long strings 3830 required manual editing, in particular the regular expression 3831 patterns for IP addresses etc. These were replaced by the 3832 placeholder string "... regex pattern ...". Also, line breaks were 3833 added to several documentation strings and Schematron messages. 3834 Other than that, the results of the automatic translations were not 3835 changed. 3837 C.1. Input YANG Module 3839 module dhcp { 3840 namespace "http://example.com/ns/dhcp"; 3841 prefix dhcp; 3843 import ietf-yang-types { prefix yang; } 3844 import ietf-inet-types { prefix inet; } 3846 organization 3847 "yang-central.org"; 3848 description 3849 "Partial data model for DHCP, based on the config of 3850 the ISC DHCP reference implementation."; 3852 container dhcp { 3853 description 3854 "configuration and operational parameters for a DHCP server."; 3856 leaf max-lease-time { 3857 type uint32; 3858 units seconds; 3859 default 7200; 3860 } 3862 leaf default-lease-time { 3863 type uint32; 3864 units seconds; 3865 must '. <= ../max-lease-time' { 3866 error-message 3867 "The default-lease-time must be less than max-lease-time"; 3868 } 3869 default 600; 3870 } 3872 uses subnet-list; 3874 container shared-networks { 3875 list shared-network { 3876 key name; 3878 leaf name { 3879 type string; 3880 } 3881 uses subnet-list; 3882 } 3883 } 3885 container status { 3886 config false; 3887 list leases { 3888 key address; 3890 leaf address { 3891 type inet:ip-address; 3892 } 3893 leaf starts { 3894 type yang:date-and-time; 3895 } 3896 leaf ends { 3897 type yang:date-and-time; 3898 } 3899 container hardware { 3900 leaf type { 3901 type enumeration { 3902 enum "ethernet"; 3903 enum "token-ring"; 3904 enum "fddi"; 3905 } 3906 } 3907 leaf address { 3908 type yang:phys-address; 3909 } 3910 } 3911 } 3912 } 3913 } 3914 grouping subnet-list { 3915 description "A reusable list of subnets"; 3916 list subnet { 3917 key net; 3918 leaf net { 3919 type inet:ip-prefix; 3920 } 3921 container range { 3922 presence "enables dynamic address assignment"; 3923 leaf dynamic-bootp { 3924 type empty; 3925 description 3926 "Allows BOOTP clients to get addresses in this range"; 3927 } 3928 leaf low { 3929 type inet:ip-address; 3930 mandatory true; 3931 } 3932 leaf high { 3933 type inet:ip-address; 3934 mandatory true; 3935 } 3936 } 3938 container dhcp-options { 3939 description "Options in the DHCP protocol"; 3940 leaf-list router { 3941 type inet:host; 3942 ordered-by user; 3943 reference "RFC 2132, sec. 3.8"; 3944 } 3945 leaf domain-name { 3946 type inet:domain-name; 3947 reference "RFC 2132, sec. 3.17"; 3948 } 3949 } 3951 leaf max-lease-time { 3952 type uint32; 3953 units seconds; 3954 default 7200; 3955 } 3956 } 3957 } 3958 } 3960 C.2. Hybrid Schema 3961 3962 3969 Pyang 1.0a, DSDL plugin 3970 2010-06-17 3971 3972 3973 YANG module 'dhcp' 3974 3975 3976 3977 3978 3979 3980 configuration and operational parameters for a DHCP server. 3981 3982 3983 3986 3987 3988 3989 3990 3993 3994 3995 3996 The default-lease-time must be less than max-lease-time 3997 3998 3999 4000 4001 4002 4003 4004 4005 4007 4008 4010 4011 4012 4013 4014 4015 4016 4017 4018 4019 4021 4022 4023 4024 4025 4026 4027 4028 4029 4030 4031 4032 4033 4034 4035 4036 4037 4038 4039 4040 4041 ethernet 4042 token-ring 4043 fddi 4044 4045 4046 4047 4048 4049 4050 4051 4052 4053 4054 4055 4056 4057 4059 4060 4061 4062 4063 4064 4065 4066 4067 4068 4069 4070 4071 4072 ([0-9a-fA-F]{2}(:[0-9a-fA-F]{2})*)? 4073 4074 4075 4076 4077 ... regex pattern ... 4078 ... regex pattern ... 4079 4080 4081 4082 4083 4084 4085 4086 4087 4088 4089 4090 4091 4092 4093 4094 4095 ... regex pattern ... 4096 4097 4098 4099 A reusable list of subnets 4100 4101 4102 4103 4104 4105 4106 4107 4108 4109 4110 4111 4112 Allows BOOTP clients to get addresses in this range 4113 4114 4115 4116 4117 4118 4119 4120 4121 4122 4123 4124 4125 4126 4127 4128 4129 4130 Options in the DHCP protocol 4131 4132 4133 4135 4136 See: RFC 2132, sec. 3.8 4137 4138 4139 4140 4141 4142 4143 4144 See: RFC 2132, sec. 3.17 4145 4146 4147 4148 4149 4150 4151 4152 4153 4156 4157 4158 4159 4160 4161 4162 4163 4164 4165 ... regex pattern ... 4166 1 4167 253 4168 4169 4170 4171 4172 ... regex pattern ... 4173 4174 4175 4176 4177 ... regex pattern ... 4178 4179 4180 4181 4182 ... regex pattern ... 4183 ... regex pattern ... 4184 4185 4186 4187 4188 4189 4190 4191 4192 4194 C.3. Final DSDL Schemas 4196 This appendix contains DSDL schemas that were obtained from the 4197 hybrid schema in Appendix C.2 by XSL transformations. These schemas 4198 can be directly used for validating a reply to unfiltered 4199 with the contents corresponding to the DHCP data model. 4201 The RELAX NG schema (in two parts, as explained in Section 8.2) also 4202 includes the schema-independent library from Appendix B. 4204 C.3.1. Main RELAX NG Schema for Reply 4206 4207 4213 4214 4215 4216 4217 4218 4219 4220 4221 4222 4223 4224 4225 4226 4227 4228 4229 4230 4231 4232 4233 4234 4235 4236 4237 4238 4239 4240 4241 4242 4243 4244 4245 4246 4247 4248 4249 4250 4251 4252 4253 4254 4255 4256 4257 4258 4259 4260 4261 4262 4263 4264 4265 4266 4267 4268 4269 4270 4271 4272 ethernet 4273 token-ring 4274 fddi 4275 4276 4277 4278 4279 4280 4281 4282 4283 4284 4285 4286 4287 4288 4289 4290 4291 4292 4293 4294 4295 4296 4297 4298 4299 4301 4303 C.3.2. RELAX NG Schema - Global Named Pattern Definitions 4305 4306 4311 4312 4313 4314 ([0-9a-fA-F]{2}(:[0-9a-fA-F]{2})*)? 4315 4316 4317 4318 4319 4320 ... regex pattern ... 4321 4322 4323 4324 4325 4326 4327 4328 4329 4330 4331 4332 4333 4334 4335 4336 4337 ... regex pattern ... 4338 4339 4340 4341 4342 4343 4344 4345 4346 4347 4348 4349 4350 4351 4352 4353 4354 4355 4356 4357 4358 4359 4360 4361 4362 4363 4364 4365 4366 4367 4368 4369 4370 4371 4372 4373 4374 4375 4376 4377 4378 4379 4380 4381 4382 4383 4384 4385 4386 4387 4388 4389 4390 4391 ... regex pattern ... 4392 1 4393 253 4394 4395 4396 4397 4398 ... regex pattern ... 4399 4400 4401 4402 4403 ... regex pattern ... 4404 4405 4406 4407 4408 ... regex pattern ... 4409 ... regex pattern ... 4410 4411 4412 4413 4414 4415 4416 4417 4418 4420 C.3.3. Schematron Schema for Reply 4422 4423 4424 4425 4426 4427 4428 4430 Duplicate key "net" 4431 4432 4433 4435 4436 Duplicate leaf-list value "" 4437 4438 4439 4440 4441 4443 4444 The default-lease-time must be less than max-lease-time 4446 4447 4448 4450 4452 Duplicate key "dhcp:name" 4453 4454 4455 4457 4459 Duplicate key "dhcp:address" 4460 4461 4462 4463 4464 4465 4466 4467 4468 4471 4472 4473 4475 C.3.4. DSRL Schema for Reply 4477 4478 4482 4483 /nc:rpc-reply/nc:data 4484 dhcp:dhcp 4485 4486 7200 4487 600 4488 4489 4490 4491 /nc:rpc-reply/nc:data/dhcp:dhcp 4492 dhcp:max-lease-time 4493 7200 4494 4495 4496 /nc:rpc-reply/nc:data/dhcp:dhcp 4497 dhcp:default-lease-time 4498 600 4499 4500 4501 4502 /nc:rpc-reply/nc:data/dhcp:dhcp/dhcp:subnet 4503 4504 dhcp:max-lease-time 4505 7200 4506 4507 4508 4509 /nc:rpc-reply/nc:data/dhcp:dhcp/dhcp:shared-networks/ 4510 dhcp:shared-network/dhcp:subnet 4511 4512 dhcp:max-lease-time 4513 7200 4514 4515 4517 Appendix D. Change Log 4519 RFC Editor: remove this section upon publication as an RFC. 4521 D.1. Changes Between Versions -07 and -08 4523 o Edits based on Gen-ART review. 4525 o Added formal templates in Section 13. 4527 o Created the "Contributors" section and moved the former co-authors 4528 there. 4530 o Indicated the location of both global and local named pattern 4531 definitions in the example hybrid schema in Section 8.1. 4533 o Added reference to EXSLT "evaluate" function. 4535 D.2. Changes Between Versions -06 and -07 4537 o Mapping of 'description', 'reference' and 'units' to the hybrid 4538 schema is now mandatory. 4540 o Improvements and fixes of the text based on the AD review 4542 D.3. Changes Between Versions -05 and -06 4544 o Terminology change: "conceptual tree schema" -> "hybrid schema". 4546 o Changed sectioning markers in the hybrid schema into plain NETMOD- 4547 specific annotations. Hence the former "nmt" namespace is not 4548 used at all. 4550 o Added the following NETMOD-specific annotations: @nma:if-feature, 4551 @nma:leaf-list, @nma:mandatory, @nma:module, removed @nma: 4552 presence. 4554 o Changed the structure of RELAX NG schemas by using embedded 4555 grammars and declaration of namespaces via @ns. This was 4556 necessary for enabling the "chameleon" behavior of global 4557 definitions. 4559 o Schematron validation phases are not used. 4561 o If an XPath expression appears inside a top-level grouping, the 4562 local prefix must be represented using the variable $pref. (This 4563 is related to the previous item.) 4565 o DHCP example: All RNG schemas are only in the XML syntax. Added 4566 RNG with global definitions. 4568 o Added [XML-INFOSET] to normative references. 4570 o Listed the terms that are defined in other documents. 4572 o The schema for NETMOD-specific annotation is now given only as RNG 4573 named pattern definitions, no more in NVDL. 4575 D.4. Changes Between Versions -04 and -05 4577 o Leafs that take their default value from a typedef and are not 4578 annotated with @nma:default must have @nma:implicit="true". 4580 o Changed code markers CODE BEGINS/ENDS to the form agreed by the 4581 WG. 4583 o Derived types "date-and-time" and "uri" SHOULD be mapped to XSD 4584 "dateTime" and "anyURI" types, respectively. 4586 o Clarified the notion of implicit nodes under under 'case' in 4587 Section 9.1.2. 4589 o Moved draft-ietf-netmod-yang-types-06 to normative references. 4591 o An extra is no more required for the default case of a 4592 choice in the shorthand notation. 4594 D.5. Changes Between Versions -03 and -04 4596 o Implemented ordering rules for list children - keys must go first 4597 and appear in the same order as in the input YANG module. 4599 o The 'case' statement is now mapped to either (inside 4600 RPC operations) or (otherwise). 4602 o A nma:default annotation coming from a datatype which the mapping 4603 expands is attached to the pattern where the 4604 expansion occurs. Added an example. 4606 o Documentation statements ('description', 'reference', 'status') 4607 MAY be ignored. 4609 o Single-valued numeric or length range parts are mapped to pattern or "length" facet. 4612 o Example for "string" datatype was added. 4614 o Appendix A now uses NVDL for defining NETMOD-specific annotations. 4616 o Added CODE BEGINS/ENDS markers. 4618 o Separated normative and informative references. 4620 o Added URL for XPath extensions namespace. 4622 o Added Section 2 (Terminology and Notation). 4624 o Added Section 14 (Security Considerations). 4626 o Added Section 16 (Acknowledgments). 4628 o Removed compact syntax schema from Appendix B. 4630 o Editorial changes: symbolic citation labels. 4632 D.6. Changes Between Versions -02 and -03 4634 o Changed @nma:default-case to @nma:implicit. 4636 o Changed nma:leafref annotation from element to attribute. 4638 o Added skeleton rule to Section 11.2. 4640 o Reworked Section 11.3, added skeleton element maps,corrected the 4641 example. 4643 o Added section on 'feature' and 'deviation'. 4645 o New Section 9.1 integrating discussion of both optional/mandatory 4646 (was in -02) and implicit nodes (new). 4648 o Reflected that key argument and schema node identifiers are no 4649 more XPath (should be in yang-07). 4651 o Element patterns for implicit containers now must have @nma: 4652 implicit attribute. 4654 o Removed "float32" and "float64" types and added mapping of 4655 "decimal64" with example. 4657 o Removed mapping of 'require-instance' for "leafref" type. 4659 o Updated RELAX NG schema for NETMOD-specific annotations. 4661 o Updated the DHCP example. 4663 D.7. Changes Between Versions -01 and -02 4665 o Moved Section 7 "NETCONF Content Validation" after Section 6. 4667 o New text about mapping defaults to DSRL, especially in Section 7 4668 and Section 11.3. 4670 o Finished the DHCP example by adding the DSRL schema to Appendix C. 4672 o New @nma:presence annotation was added - it is needed for proper 4673 handling of default contents. 4675 o Section 11.2.1 "Constraints on Mandatory Choice" was added because 4676 these constraints require a combination of RELAX NG and 4677 Schematron. 4679 o Fixed the schema for NETMOD-specific annotations by adding 4680 explicit prefix to all defined elements and attributes. 4681 Previously, the attributes had no namespace. 4683 o Handling of 'feature', 'if-feature' and 'deviation' added. 4685 o Handling of nma:instance-identifier via XSLT extension function. 4687 D.8. Changes Between Versions -00 and -01 4689 o Attributes @nma:min-elements and @nma:max-elements are attached to 4690 (list entry) and not to or . 4693 o Keys and all node identifiers in 'key' and 'unique' statements are 4694 prefixed. 4696 o Fixed the mapping of 'rpc' and 'notification'. 4698 o Removed previous sec. 7.5 "RPC Signatures and Notifications" - the 4699 same information is now contained in Section 10.50 and 4700 Section 10.37. 4702 o Added initial "_" to mangled names of groupings. 4704 o Mandated the use of @xmlns:xxx as the only method for declaring 4705 the target namespace. 4707 o Added section "Handling of XML Namespaces" to explain the previous 4708 item. 4710 o Completed DHCP example in Appendix C. 4712 o Almost all text about the second mapping step is new. 4714 Author's Address 4716 Ladislav Lhotka (editor) 4717 CESNET 4719 Email: lhotka@cesnet.cz