idnits 2.17.1 draft-lhotka-yang-dsdl-map-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 18. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 2714. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2725. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2732. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2738. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 296: '... from the translation MAY be presented...' RFC 2119 keyword, line 692: '...sing annotation called "status" SHOULD...' RFC 2119 keyword, line 1226: '...apping algorithm MUST accept as input ...' RFC 2119 keyword, line 1290: '...n implementation SHOULD allow selectio...' RFC 2119 keyword, line 1432: '... pattern definitions, their names MUST...' (3 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (November 03, 2008) is 5646 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 4741 (Obsoleted by RFC 6241) == Outdated reference: A later version (-13) exists of draft-ietf-netmod-yang-00 == Outdated reference: A later version (-09) exists of draft-ietf-netmod-yang-types-00 Summary: 6 errors (**), 0 flaws (~~), 3 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETMOD L. Lhotka 3 Internet-Draft CESNET 4 Intended status: Informational R. Mahy 5 Expires: May 7, 2009 Plantronics 6 S. Chisholm 7 Nortel 8 November 03, 2008 10 NETCONF DSDL and Yang Mapping 11 draft-lhotka-yang-dsdl-map-01 13 Status of this Memo 15 By submitting this Internet-Draft, each author represents that any 16 applicable patent or other IPR claims of which he or she is aware 17 have been or will be disclosed, and any of which he or she becomes 18 aware will be disclosed, in accordance with Section 6 of BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF), its areas, and its working groups. Note that 22 other groups may also distribute working documents as Internet- 23 Drafts. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 The list of current Internet-Drafts can be accessed at 31 http://www.ietf.org/ietf/1id-abstracts.txt. 33 The list of Internet-Draft Shadow Directories can be accessed at 34 http://www.ietf.org/shadow.html. 36 This Internet-Draft will expire on May 7, 2009. 38 Copyright Notice 40 Copyright (C) The IETF Trust (2008). 42 Abstract 44 This draft describes the algorithm and rules for defining NETCONF 45 data modelss using Document Schema Definition Languages (DSDL) with 46 additional annotations and based on a mapping from YANG. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 51 2. Objectives and Motivation . . . . . . . . . . . . . . . . . . 7 52 3. DSDL Schema Languages and Annotations . . . . . . . . . . . . 8 53 3.1. RELAX NG . . . . . . . . . . . . . . . . . . . . . . . . . 8 54 3.2. Schematron . . . . . . . . . . . . . . . . . . . . . . . . 9 55 3.2.1. Embedded and Standalone Schematron . . . . . . . . . . 10 56 3.2.2. Schematron NETCONF Library . . . . . . . . . . . . . . 10 57 3.2.3. Phases of validation . . . . . . . . . . . . . . . . . 12 58 3.3. Document Schema Renaming Language (DSRL) . . . . . . . . . 14 59 3.4. Additional Annotations . . . . . . . . . . . . . . . . . . 14 60 3.4.1. Dublin Core Terms . . . . . . . . . . . . . . . . . . 14 61 3.4.2. RELAX NG DTD Compatibility Annotations . . . . . . . . 15 62 3.4.3. NETCONF-specific Annotations . . . . . . . . . . . . . 15 63 3.5. Conformance . . . . . . . . . . . . . . . . . . . . . . . 16 64 3.5.1. Cardinality . . . . . . . . . . . . . . . . . . . . . 16 65 3.5.2. Operations on managed objects . . . . . . . . . . . . 16 66 3.5.3. Element and Attribute Status . . . . . . . . . . . . . 18 67 3.5.4. Additional Conformance Information . . . . . . . . . . 18 68 3.5.5. Schema Level Conformance - Server-side . . . . . . . . 18 69 3.5.6. Schema Level Conformance - Client-side . . . . . . . . 19 70 3.6. DML Definition . . . . . . . . . . . . . . . . . . . . . . 19 71 4. Design Considerations . . . . . . . . . . . . . . . . . . . . 25 72 4.1. Conceptual Data Tree . . . . . . . . . . . . . . . . . . . 25 73 4.2. Modularity . . . . . . . . . . . . . . . . . . . . . . . . 27 74 4.3. Granularity . . . . . . . . . . . . . . . . . . . . . . . 28 75 4.4. Validation Phases . . . . . . . . . . . . . . . . . . . . 28 76 5. Overview of the Mapping . . . . . . . . . . . . . . . . . . . 30 77 6. Specification of the Mapping . . . . . . . . . . . . . . . . . 34 78 6.1. Optional and Mandatory Content . . . . . . . . . . . . . . 34 79 6.2. Mapping YANG Groupings and Typedefs . . . . . . . . . . . 34 80 6.2.1. Mangled Names of RELAX NG Named Patterns . . . . . . . 34 81 6.2.2. YANG Refinements and Augments . . . . . . . . . . . . 36 82 6.2.3. Type derivation chains . . . . . . . . . . . . . . . . 38 83 6.3. Mapping RPC Signatures . . . . . . . . . . . . . . . . . . 38 84 6.4. Mapping Notifications . . . . . . . . . . . . . . . . . . 38 85 6.5. Default values . . . . . . . . . . . . . . . . . . . . . . 38 86 7. Mapping Rules for YANG Statements . . . . . . . . . . . . . . 39 87 7.1. The anyxml Statement . . . . . . . . . . . . . . . . . . . 40 88 7.2. The argument Statement . . . . . . . . . . . . . . . . . . 40 89 7.3. The augment Statement . . . . . . . . . . . . . . . . . . 41 90 7.4. The belongs-to Statement . . . . . . . . . . . . . . . . . 41 91 7.5. The bit Statement . . . . . . . . . . . . . . . . . . . . 41 92 7.6. The case Statement . . . . . . . . . . . . . . . . . . . . 41 93 7.7. The choice Statement . . . . . . . . . . . . . . . . . . . 41 94 7.8. The config Statement . . . . . . . . . . . . . . . . . . . 41 95 7.9. The contact Statement . . . . . . . . . . . . . . . . . . 41 96 7.10. The container Statement . . . . . . . . . . . . . . . . . 42 97 7.11. The default Statement . . . . . . . . . . . . . . . . . . 42 98 7.12. The description Statement . . . . . . . . . . . . . . . . 42 99 7.13. The enum Statement . . . . . . . . . . . . . . . . . . . . 42 100 7.14. The error-app-tag Statement . . . . . . . . . . . . . . . 42 101 7.15. The error-message Statement . . . . . . . . . . . . . . . 42 102 7.16. The extension Statement . . . . . . . . . . . . . . . . . 42 103 7.17. The grouping Statement . . . . . . . . . . . . . . . . . . 43 104 7.18. The import Statement . . . . . . . . . . . . . . . . . . . 43 105 7.19. The include Statement . . . . . . . . . . . . . . . . . . 43 106 7.20. The input Statement . . . . . . . . . . . . . . . . . . . 43 107 7.21. The key Statement . . . . . . . . . . . . . . . . . . . . 43 108 7.22. The leaf Statement . . . . . . . . . . . . . . . . . . . . 43 109 7.23. The leaf-list Statement . . . . . . . . . . . . . . . . . 43 110 7.24. The length Statement . . . . . . . . . . . . . . . . . . . 44 111 7.25. The list Statement . . . . . . . . . . . . . . . . . . . . 44 112 7.26. The mandatory Statement . . . . . . . . . . . . . . . . . 44 113 7.27. The max-elements Statement . . . . . . . . . . . . . . . . 44 114 7.28. The min-elements Statement . . . . . . . . . . . . . . . . 44 115 7.29. The module Statement . . . . . . . . . . . . . . . . . . . 44 116 7.30. The must Statement . . . . . . . . . . . . . . . . . . . . 44 117 7.31. The namespace Statement . . . . . . . . . . . . . . . . . 44 118 7.32. The notification Statement . . . . . . . . . . . . . . . . 45 119 7.33. The ordered-by Statement . . . . . . . . . . . . . . . . . 45 120 7.34. The organization Statement . . . . . . . . . . . . . . . . 45 121 7.35. The output Statement . . . . . . . . . . . . . . . . . . . 45 122 7.36. The path Statement . . . . . . . . . . . . . . . . . . . . 45 123 7.37. The pattern Statement . . . . . . . . . . . . . . . . . . 45 124 7.38. The position Statement . . . . . . . . . . . . . . . . . . 45 125 7.39. The prefix Statement . . . . . . . . . . . . . . . . . . . 45 126 7.40. The presence Statement . . . . . . . . . . . . . . . . . . 45 127 7.41. The range Statement . . . . . . . . . . . . . . . . . . . 45 128 7.42. The reference Statement . . . . . . . . . . . . . . . . . 45 129 7.43. The revision Statement . . . . . . . . . . . . . . . . . . 46 130 7.44. The rpc Statement . . . . . . . . . . . . . . . . . . . . 46 131 7.45. The status Statement . . . . . . . . . . . . . . . . . . . 46 132 7.46. The submodule Statement . . . . . . . . . . . . . . . . . 46 133 7.47. The type Statement . . . . . . . . . . . . . . . . . . . . 46 134 7.47.1. The empty Type . . . . . . . . . . . . . . . . . . . . 47 135 7.47.2. The boolean and binary Types . . . . . . . . . . . . . 47 136 7.47.3. The instance identifier Type . . . . . . . . . . . . . 48 137 7.47.4. The bits Type . . . . . . . . . . . . . . . . . . . . 48 138 7.47.5. The enumeration and union Types . . . . . . . . . . . 48 139 7.47.6. The keyref type . . . . . . . . . . . . . . . . . . . 48 140 7.47.7. The numeric Types . . . . . . . . . . . . . . . . . . 48 141 7.47.8. The string Type . . . . . . . . . . . . . . . . . . . 49 142 7.48. The typedef Statement . . . . . . . . . . . . . . . . . . 50 143 7.49. The unique Statement . . . . . . . . . . . . . . . . . . . 50 144 7.50. The units Statement . . . . . . . . . . . . . . . . . . . 50 145 7.51. The uses Statement . . . . . . . . . . . . . . . . . . . . 50 146 7.52. The value Statement . . . . . . . . . . . . . . . . . . . 51 147 7.53. The when Statement . . . . . . . . . . . . . . . . . . . . 51 148 7.54. The yang-version Statement . . . . . . . . . . . . . . . . 51 149 7.55. The yin-element Statement . . . . . . . . . . . . . . . . 51 150 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 52 151 Appendix A. DML Definition in Compact Syntax . . . . . . . . . . 54 152 Appendix B. Translation of the DHCP Data Model . . . . . . . . . 57 153 B.1. XML Syntax . . . . . . . . . . . . . . . . . . . . . . . . 57 154 B.2. Compact Syntax . . . . . . . . . . . . . . . . . . . . . . 61 155 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 64 156 Intellectual Property and Copyright Statements . . . . . . . . . . 65 158 1. Introduction 160 The NETCONF Working Group has completed a base protocol [RFC4741] 161 used for configuration management. This base specification defines 162 protocol bindings and an XML [XML] container syntax for configuration 163 and management operations, but does not include a modeling language 164 or accompanying rules for how to model configuration and status 165 information (in XML syntax) carried by NETCONF. The IETF Operations 166 area has a long tradition of defining data for SNMP [RFC1157] 167 Management Information Bases (MIBs) using the SMI [RFC2578] to model 168 its data. While this specific modeling approach has a number of 169 well-understood problems, most of the data modeling features provided 170 by SMI are still considered extremely important. Simply modeling the 171 valid syntax rather than additional semantic relationships has caused 172 significant interoperability problems in the past. 174 The NETCONF community concluded that a data modeling framework is 175 needed to support ongoing development of IETF and vendor-defined 176 management information modules. The NETMOD Working Group was 177 chartered to address this problem, by defining a new human-friendly 178 modeling language based on SMIng [RFC3216] and called YANG [YANG]. 180 Since NETCONF content contain XML data, it is natural to express the 181 constraints on NETCONF content using standard XML schema languages. 182 For this purpose, the NETMOD WG selected the Document Schema 183 Definition Languages (DSDL) that is being standardized as ISO/IEC 184 19757 [DSDL]. The DSDL framework comprises a set of XML schema 185 languages that address grammar rules, semantic constraints and other 186 data modeling aspect but also, and more importantly, do it in a 187 coordinated and consistent way. While it is true that some DSDL 188 parts have not been standardized yet and are still work in progress, 189 the two crucial parts that the YANG-to-DSDL mapping relies upon - 190 RELAX NG and Schematron - already have the status of an ISO/IEC 191 International Standard and are supported in a number of software 192 tools. 194 This document contains the specification and a mapping that 195 translates YANG data models to an XML schema (or multiple schemas) 196 utilizing a subset of the DSDL schema languages together with a 197 limited number of other annotations. The resulting schema(s) can be 198 used (possibly after further processing) for validating NETCONF 199 content and making sure that they are compliant to the original data 200 model. 202 Depending on the architecture of a particular NETCONF implementation, 203 the DSDL schemas may be used directly for validating NETCONF content 204 using existing XML tools and libraries. But even if the schemas are 205 not used for practical validation, the YANG-to-DSDL mapping described 206 in this document should be regarded and perused by implementers as a 207 formal specification of the correspondence between a YANG data model 208 and NETCONF content. 210 In the text, we use the following typographic conventions: 212 o YANG statement keywords are delimited by single quotes. 214 o Literal values are delimited by double quotes. 216 o XML element names are delimited by "<" and ">" characters. 218 o Names of XML attributes are prefixed by the "@" character. 220 2. Objectives and Motivation 221 3. DSDL Schema Languages and Annotations 223 The mapping described in this document uses three of the DSDL schema 224 languages, namely RELAX NG, Schematron and DSRL. In addition, three 225 types of annotations are used in the RELAX NG schema. Two of them 226 are standard annotation vocabularies: Dublin Core metadata terms 227 [DCMI] serve for recording metadata and RELAX NG DTD compatibility 228 annotations are used for documentation strings. Finally, a small set 229 of special annotations were designed in order to convey other 230 semantic information that is important in the context of NETCONF 231 content validation. 233 The DSDL schema languages and annotations are described in the 234 following subsections. 236 Schema-independent Library - Parts of this solution that are the same 237 for all Schema definitions. Conceptually these are written once and 238 used many times. This includes NETCONF specific annotations to Relax 239 NG (DML) and common Schematron rules. 241 Schema-specific Definitions - Parts of this solution that are unique 242 to a specific Schema definition. These are generated or written for 243 each Schema definition 245 ----------------------- 246 | Schema-independent | 247 | Library | 248 | |---------| 249 ------------------------ | 250 |--> Validate 251 ------------------- | NETCONF 252 | Schema-specific | | Content 253 ---> | Definitions |-------------- 254 | | 255 ------------------- 257 3.1. RELAX NG 259 RELAX NG [RNG] is an XML schema language for grammar-based 260 validation. Like the W3C XML Schema language [XSD], it is able to 261 describe constraints on the structure and contents of XML documents. 262 Unlike the DTD [XML] and XSD schema languages, RELAX NG intentionally 263 avoids any infoset augmentation such as defining default values. In 264 the DSDL architecute, this task is delegated to other schema 265 languages, in particular DSRL [DSRL]. 267 As its base datatype library, RELAX NG uses the W3C XML Schema 268 Datatype Library [XSD-D], but unlike XSD, other datatype libraries 269 may be used along with it or even replace it if necessary. 271 RELAX NG is very liberal in accepting annotations from other 272 namespaces. With few exceptions, such annotations may be placed 273 anywhere in the schema and need no encapsulating element such as 274 in XSD. 276 RELAX NG schema can be represented using two equivalent syntaxes: XML 277 and compact. The compact syntax is described in Annex C of the RELAX 278 NG specification [RNG], which was added in 2006 (Amendment 1). 279 Automatic bidirectional conversions between the two syntaxes can be 280 accomplished using for example Trang [1]. 282 For its terseness and readability, the compact syntax is often the 283 preferred form for publishing RELAX NG schemas whereas validator and 284 other software tools generally require the XML syntax. The weak 285 point of the compact syntax is the handling of annotations. While in 286 the XML syntax the annotating elements and attributes are represented 287 in an uniform way, the compact syntax uses four different syntactic 288 constructs (documentation, grammar, initial and following 289 annotations). As a result, the impact on readability resulting from 290 adding annotations is often much stronger for the compact syntax than 291 for the XML syntax. 293 Since the mapping from YANG to DSDL relies heavily on annotations, 294 this document uses exclusively the RELAX NG XML syntax, which is more 295 appropriate for further machine processing. Where appropriate, 296 though, the schemas resulting from the translation MAY be presented 297 in the equivalent compact syntax. 299 3.2. Schematron 301 While the traditional schema languages such as DTD, XSD or RELAX NG 302 are based on the concept of a formal grammar, Schematron [Schematron] 303 utilizes a rules-based approach. Its rules may specify arbitrary 304 conditions involving data from different parts of an XML document. 305 Each rule consists of three essential parts: 307 o Context - an XPath expression that defines the set of locations 308 where the rule is to be applied, 310 o Assert or report condition - another XPath expression that is 311 evaluated relative to the location matched by the context 312 expression. 314 o Human-readable message that is displayed when the assert condition 315 is false or report condition is true. 317 The difference between the assert and report condition is that the 318 former is positive in that it states a condition that a valid 319 document has to satisfy, whereas the latter specifies an error 320 condition. The mapping described in this document uses exclusively 321 the positive (assert) form. 323 Schematron draws most of its expressive power from XPath [XPath] and 324 XSLT [XSLT]. ISO Schematron allows for dynamic query language 325 binding so that the following XML query languages can be used: STX, 326 XSLT 1.0, XSLT 1.1, EXSLT, XSLT 2.0, XPath 1.0, XPath 2.0 and XQuery 327 1.0 (this list may be extended in future). 329 The human-readable error messages are another feature that 330 distinguishes Schematron from other schema langauges such as RELAX NG 331 or XSD. The messages may even contain XPath expressions that are 332 evaluated in the actual context and thus refer to XML document nodes 333 and their content. 335 ISO Schematron introduced the concept of _abstract patterns_ whose 336 purpose is similar to functions in programming languages. The 337 mapping described in this document uses abstract patterns for 338 defining common constraints such as uniqueness of certain leaf values 339 in list items. 341 The rules defined by a Schematron schema may be divided divided into 342 several subsets known as _phases_. Validations may then be set up to 343 include only selected phases. In the context of NETCONF data 344 validation, this is useful for relaxing constraints that may not 345 always apply. For example, the reference integrity may not be 346 enforced for a candidate configuration. 348 3.2.1. Embedded and Standalone Schematron 350 Schematron can either be defined in standalone specifications or 351 embedded in the RELAX NG Schema. This solution is just using 352 standalone Schematron. 354 Design Alternative: Use standalone Schematron to create a library of 355 common rules used to validate any content. and use embedded rules to 356 define Schema specific rules. 358 3.2.2. Schematron NETCONF Library 360 This section outlines the Schematron rules used to validate all 361 NETCONF content. 363 3.2.2.1. Schematron patterns for data model validation 365 The Schematron validator evaluates the context of each rule, then 366 evaluates each assert or report clause within the rule. The 367 following is used for insuring that a key is unique within a list 368 context. 370 371 373 The value ifIndex must be unique among all interfaces. 374 375 377 For every ifIndex element, the 'assert' tests if the number of 378 interfaces which have an ifIndex matching the current one (being 379 evaluated) is one. This XPath expression is rather long. Since we 380 will use this idiom repeatedly, we can define a Schematron abstract 381 pattern to express this more succinctly: 383 384 385 386 The key "" needs to be unique 387 within the list at: . 388 389 390 392 393 394 395 396 398 Likewise, we can write Schematron abstract patterns for validating 399 keyref relationships as well. 401 402 403 404 The contents of "" 405 must be a '' with the key 406 "" in this context: 407 . 408 409 410 412 413 414 415 417 418 419 421 Even the Schematron abstract patterns shown above contain paths that 422 a computer could derive automatically. The XSLT stylesheet described 423 in [Editor's Note: not yet in document] could read the data model 424 processing annotations to automatically generate Schematron patterns 425 that use these abstract patterns. The XSLT stylesheet is just 426 calculating the context XPaths by examining the document structure in 427 the RelaxNG schema. Once generated, these rules can be used to test 428 the validity of instance documents. These Schematron tests can 429 provide different levels of validity checking. 431 3.2.3. Phases of validation 433 Conceptually, an implementation can validate its instance data in 434 different logical phases, adding more tests with each phase. We use 435 three levels or phases for validating an instance document. There is 436 a level of validation which is appropriate even for loose XML 437 document fragments which still maintain their hierarchy (the fragment 438 phase), there is a level of validation appropriate for a cohesive XML 439 document but which may not be able to validate relational integrity 440 checks against some operational state (the standard phase), and there 441 is validation which includes all relational integrity checks (the 442 full validation phase). For example, in Netconf an edit-config 443 operation can cause the replacement a small fragment of XML. A 444 candidate configuration may be waiting for application but can't 445 check the readiness of a piece of hardware that the configuration 446 refers to. 448 From the NETCONF perspective, these three phrases can considered to 449 have the following scope and triggers: 451 1. the fragment phase: This can be run against individual NETCONF 452 operations; should be automatically triggered 454 2. the standard phase: This can be run against the candidate 455 configuration, but won't always pass; should be manually 456 triggered 458 3. the full validation phase: This can be run against a running 459 configuration; should be automatically triggered 461 [Editor's Note: open discussion point on whether all stages, 462 including fragmentation, apply or just the last two via a conceptual 463 tree model. Sharon feels that should be validatable in the tool- 464 friendly language.] 466 During the Fragment phase validation: 468 o Verify that the content is appropriate to the operation (by 469 passing a variable to Schematron with the type of operation). 471 During Standard phase validation (all rules except for keyref 472 checking): 474 o Verify that mustUse items are present 476 o Check the uniqueness for unique and key annotations 478 o Print a warning if any manual validation rules are present 480 During Full phase validation: add keyref checks. 482 All embedded Schematron will run in the standard phase unless the a 483 'dml:phase' attribute is included with the name of a different phase 484 ('fragment' or 'full'). 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 502 3.3. Document Schema Renaming Language (DSRL) 504 DSRL [DSRL] (pronounced "disrule") is Part 8 of DSDL in the stage of 505 FCD (Final Committee Draft). Unlike RELAX NG and Schematron, it 506 specifically designed to modify XML information set of the validated 507 document. The primary application for DSRL is renaming XML elements 508 and attributes. DSRL can also define default values for XML 509 attributes and elements so that elements or attributes with these 510 default values are inserted if they are missing in the validated 511 documents . This latter feature is used by the YANG-to-DSDL mapping 512 for representing YANG defaults for leaf nodes. 514 3.4. Additional Annotations 516 Besides RELAX NG, Schematron and DSRL, the YANG-to-DSDL mapping 517 utilizes three sets of annotations that carry metadata, documentation 518 strings and additional semantics of YANG data models that cannot be 519 fully expressed using the above schema languages. These annotations 520 may be attached to the elements in the RELAX NG schema as either 521 subelements or attributes from different namespaces (see Section 7 522 for details). 524 3.4.1. Dublin Core Terms 526 Dublin Core [2] is a system of metadata terms that was originally 527 created for describing metadata of World Wide Web resources in order 528 to facilitate their automated lookup. Later it was accepted as a 529 standard for describing metadata of arbitrary resources 531 This specification uses the definition found in [RFC5013]. 533 3.4.2. RELAX NG DTD Compatibility Annotations 535 See http://relaxng.org/compatibility-20011203.html 537 These annotations are part of the RELAX NG DTD Compatibility 538 specification [RNG-DTD]. The YANG-to-DSDL mapping uses only the 539 annotation for representing YANG 'description' and 540 'reference' strings, except at the top level of a module where Dublin 541 Core metadata terms are used for this purpose. Note that there is no 542 intention to make the resulting schemas DTD-compatible, the main 543 reason for using this annotation is technical: it is supported and 544 adequately interpreted by many RELAX NG tools. 546 3.4.3. NETCONF-specific Annotations 548 This specification introduces two XML attributes that are convey 549 special semantics that cannot be fully expressed in the standard DSDL 550 schema languages. 552 3.4.3.1. The 'key' annotation 554 When the cardinality of an element is more than one (ie, it is in a 555 list), list keys are important for defining the behavior of the 556 NETCONF method (see [YANG], Sec. 7.8.6): Every 557 operation addressina list item must provide all key nodes and the 558 contents of the keys cannot be changed. A detailed explanation is 559 provided in Section 7.21. The uniqueness constraint can be expressed 560 as a Schematron rule in the same way as for the 'unique' statement 561 (see Section 7.49). 563 3.4.3.2. The 'config' annotation 565 The 'config' annotation indicates the category of data that applies 566 to the annotated element and all its children until another 'config' 567 annotation. The content of the 'config' element is an boolean, where 568 true is the default value. It indicates that the covered data is 569 configuration and that it is at least theoretically possible to 570 include this data in read, write, create, and delete operations. 571 Likewise non-configuration information can be read, but cannot be 572 included in write, create, and delete operations. See Section 7.8 573 for details. 575 3.4.3.3. The 'mustUse' annotation 577 [Editor's Note: Note this is in support of client-side conformance 578 which may not yet be in yang. It is different from the built in 579 and type tags in RelaxNg, which are used for 580 server-side conformance in this solution] 581 An element in the data model tagged with the 'mustUse' annotation 582 indicates that the tagged element needs to appear in the instance 583 document whenever its parent appears. Items with a default value 584 annotation cannot also have a mustUse annotation. 586 In many schemas, there is a facility for using fragments or patches 587 of XML documents. (Netconf uses these fragments extensively in edit- 588 config operations for example). In order to accommodate these 589 fragments, the cardinality of an otherwise "required" element may 590 allow the element to be optional in an XML fragment. The mustUse 591 annotation provides a way to express what is actually required in 592 this situation. 594 See also the client-side conformance discussion in on conformance. 596 3.5. Conformance 598 When defining NETCONF content, it is also necessary to define 599 machine-readable conformance for that content. The conformance 600 method described provides a means of providing information about 601 individual elements which is then used to calculate the schema 602 conformance. There is no separate definition of schema conformance. 603 Previous solutions with separate conformance sections were found to 604 have issues, particularly in keeping them up to date as the schema 605 evolved. They also were not always used outside of standards 606 activities where people did not either fully understand them or see 607 the value in them. 609 Conformance specifies not only whether to object must be supported, 610 but also the level of access, read versus write for example that is 611 minimally required. 613 3.5.1. Cardinality 615 When defining attributes and elements in the XML syntax, the 616 'optional', 'oneOrMore' or 'zeroOrMore' tags are used to specify the 617 cardinality of the element. In the compact syntax, "?" means 618 optional, "+" means one or more, "*" means zero or more. When no 619 cardinality indicator is present, this is interpreted to mean exactly 620 once. 622 3.5.2. Operations on managed objects 624 Operations that can be performed on managed objects fall into one of 625 the following equivalence classes: "create", "delete", "read", 626 "write", and "execute". A value of "create" means it is possible to 627 create new instances of this element. A value of "delete" means it 628 is possible to destroy instances of this element. A value of "read" 629 means that it is possible to view values of this element. A value of 630 "write" means it is possible to modify an instance of this element. 631 A value of "execute" means that there is a side effect execution such 632 as rebooting that is permissible as a result of the command. 634 The kind of access which is allowed for a particular element depends 635 on its dml:config value. The minimum access needed for an 636 implementation for a specific kind of dml:config is that element's 637 'minAccess'. The maximum access allowed is that element's 638 'maxAccess'. Normally these values do not need to be modified. 639 There is a default access class for each dml:config. 641 +---------------+-----------+--------------------------+ 642 | Data Category | minAccess | maxAccess | 643 +---------------+-----------+--------------------------+ 644 | config | read | read,write,create,delete | 645 | | | | 646 | non-config | read | read | 647 +---------------+-----------+--------------------------+ 649 Default access classes for config/non-config elements 651 However, if a specific piece of data needs a different class it can 652 be modified using the config annotation's minAccess and maxAccess 653 attributes. For example, perhaps a 'controller' element can only be 654 created automatically as a side-effect of some other action. The 655 example below documents this by explicitly setting the maxAccess 656 attribute: 658 [Editor's note: this minOccurs/maxOccurs approach is not exactly what 659 is used in yang. A common approach needs to be agreed.] 661 662 663 a bunch of sub-elements of controller ... 665 true 666 667 668 670 To describe how this applies specifically to NETCONF: a value of 671 "create" means it is possible to create new instances of this element 672 using commands like the NETCONF 'edit-config' or copy- config' 673 commands. A value of "delete" means it is possible to destroy 674 instances of this element using commands like the NETCONF 'edit- 675 config', 'copy-config' or 'delete-config' operations. A value of 676 "read" means that it is possible to view values of this element using 677 commands like the 'get-config', 'get' or 'notification' operations. 678 A value of "write" means it is possible to modify an instance of this 679 element using commands like the NETCONF 'edit-config' or 'copy- 680 config' commands. A value of "execute" means that there is a side 681 effect execution such as rebooting that is permissible as a result of 682 the command. For example, commands like the NETCONF 'edit-config' or 683 a 'copy-config' command or the ability to execute a commands like the 684 'lock', 'unlock' or 'kill-session' command. 686 3.5.3. Element and Attribute Status 688 As a schema evolves, certain elements and attributes may no longer be 689 relevant. Simply deleting these from the schema may be acceptable 690 for elements that did not see implementation, but others will require 691 a strategy to allow implementers to migrate away from the old 692 elements. An optional processing annotation called "status" SHOULD 693 be used to provide the status of the element. When not present, it 694 will assume a value of "current". The other value of this object are 695 "deprecated" and "obsolete". A value of "deprecated" indicates that 696 implementations should consider migrating away from this object and 697 that its implementation is no longer required to be considered 698 conformant. A value of "obsolete" means the object should not be 699 implemented. Deprecated and obsolete content is never removed from 700 the document and its element name can never be re-used. 702 current 704 3.5.4. Additional Conformance Information 706 Additional information about conformance should be specified using a 707 documentation tag. 709 Examples of additional conformance information that may be useful to 710 provide includes how implementations can specify specific exceptions 711 to required conformance, dependencies between elements (in order to 712 do A, you need to first do B) and conditional conformance (if BGP, 713 then ...). 715 [Editor's Note: This may need rationalization with yang] 717 3.5.5. Schema Level Conformance - Server-side 719 In order to claim compliance to a schema, all elements and attributes 720 need to conform to their given cardinality definitions and all 721 elements and attributes with a status of "current" and with a 722 cardinality greater than or equal to one need to be supported. In 723 addition, all of the operations listed by the minAccess attribute 724 need to be supported. 726 3.5.6. Schema Level Conformance - Client-side 728 Client-side conformance is a method of indicating whether presence of 729 an object is required in order to be a valid configuration. A new 730 processing annotation is added called mustUse to support this. When 731 present, this object is required in a valid configuration and when 732 not present, it is optional in a valid configuration. Note that 733 optional objects may have default values to enable them to have 734 values in the configuration without being explicitly set by the 735 client. 737 739 3.6. DML Definition 741 This section defines the Relax NG Schema for the NETCONF specific 742 annotations used in this solution. 744 [Editor's Note: some parts of this may need to be rationalized with 745 section 4 of this document.] 747 748 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 1.0 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 815 816 817 818 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 config 860 status 861 statistics 862 action 863 notify 864 865 config 866 867 868 869 870 read 871 write 872 create 873 delete 874 execute 875 876 877 878 879 880 false 881 882 883 884 885 886 887 888 889 890 891 892 any-order 893 user-order 894 895 any-order 896 897 898 899 900 901 902 903 904 905 906 907 [^: \n\r\t]+ 908 909 911 912 ([a-zA-Z][a-zA-Z0-9\-\+\.]*:|\.\./|\./|#).* 914 915 916 920 921 922 926 927 928 929 930 931 932 933 934 935 active 936 deprecated 937 obsolete 938 active 939 940 941 942 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 fragment 963 std 964 full 965 966 967 968 969 970 971 false 972 973 974 975 4. Design Considerations 977 YANG modules can be mapped to DSDL schemas in a number of ways. The 978 mapping prosedure described in this document uses several specific 979 design decision that are discussed in the following subsections. 981 4.1. Conceptual Data Tree 983 DSDL schemas generated from a YANG module using the procedure 984 described in this document are intended to be used for validating 985 contents of NETCONF protocol data units that are exchanged between 986 the client and server. However, every YANG model generates an array 987 of possible PDUs that cannot be described by a single set of DSDL 988 schemas: 990 1. First, besides configuration and status data, a YANG module may 991 also define signatures of new NETCONF RPC methods and 992 notifications. 994 2. Various subtrees of configuration and/or status data may appear 995 in different NETCONF protocol operations - , 996 and , each of them having specific rules for their 997 content. 999 3. Finally, contents of replies to the and may be 1000 modified by filters (based either on subtree filtering specified 1001 in [RFC4741] or XPath expressions [XPath]) 1003 On the other hand, variability of PDU contents resulting from 1004 Paragraph 2 and Paragraph 3 is limited to selecting one or more 1005 specific subtrees from the full data tree specified by a YANG module. 1007 In order to avoid technical complications with specifying the context 1008 for a particular PDU, we introduce the notion of _conceptual data 1009 tree_ containing everything that is defined by one or more YANG 1010 module that are supposed to be used together in a NETCONF session: 1011 full configuration and status data tree, RPC messages and the 1012 corresponding replies, and notifications. For YANG module "foo", the 1013 conceptual data tree may be schematically represented as follows: 1015 1017 1018 ... configuration and status data ... 1019 1020 1021 1022 ... 1023 1024 ... 1025 1026 1027 ... 1028 1029 1030 ... 1031 1032 1033 1034 ... 1035 ... 1036 ... 1037 1038 ... 1039 1040 1042 The namespace URI "urn:ietf:params:xml:ns:netmod:tree:1" identifies a 1043 simple vocabulary consisting of a few elements that encapsulate and 1044 separate the various parts of the conceptual data tree. 1046 The purpose of this construction is to establish a single well- 1047 defined target for the mapping from YANG to DSDL - its output is a 1048 DSDL schema specifying formally the constraints that the conceptual 1049 data tree has to satisfy in order to be compliant with the data model 1050 that served as a preimage for the DSDL schema. 1052 The drawback of this approach is that the DSDL schema(s) generated by 1053 the mapping cannot be directly used for validating any real-life 1054 NETCONF PDU. Nonetheless, given a specific context, such as reply to 1055 with a certain filter, it should be reasonably 1056 straightforward to derive the DSDL schema for validating this 1057 particular PDU from the conceptual data tree schema, for example by 1058 using XSLT. However, this subsequent transformation is outside the 1059 scope of the present document. 1061 Incidentally, by introducing the conceptual data tree we are also 1062 able to resolve the difficulties stemming from the fact that a single 1063 YANG module may define multiple parallel data hierarchies, which is 1064 something that XML does not allow. In the conceptual data tree, the 1065 multiple hierarchies can be easily accomodated under the 1066 element. 1068 4.2. Modularity 1070 Both YANG and RELAX NG offer means for modularity, i.e., for 1071 splitting the contents into separate modules (schemas) and combining 1072 or reusing them in various ways. However, the approaches taken by 1073 YANG and RELAX NG differ. Modularity in RELAX NG is intended more 1074 for ad hoc combinations of a small number of schemas whereas YANG 1075 assumes a large set of modules similar to SNMP MIBs. The following 1076 differences are important: 1078 IN YANG, when module A imports module B, it gets access to the 1079 definitions (groupings and typedefs) appearing at the top level of 1080 module B. However, no part of module B's data tree is imported 1081 along with it. In contrast, the pattern in RELAX NG 1082 imports both definitions of named patterns and the entire schema 1083 tree from the included schema. 1085 The names of imported YANG groupings and typedefs are qualified 1086 with the namespace of the imported module. On the other hand, the 1087 data nodes contained in an imported grouping, when used in the 1088 importing module, become part of the importing namespace. In 1089 RELAX NG, the names of patterns are unqualified and so named 1090 patterns defined in the importing and imported module share the 1091 same flat namespace. The contents of RELAX NG named patterns may 1092 either keep the namespace of the schema where they are defined or 1093 inherit the namespace of the importing module, analogically to 1094 YANG. However, in order to achieve the latter behavior, the 1095 imported module must be prepared in a special way as a library 1096 module that cannot be used as a stand-alone schema. 1098 Hence, the conclusion is that the modularity mechanisms of YANG and 1099 RELAX NG, albeit similar, are incompatible. Therefore, the design 1100 decision for the mapping algorithm was to collect all definitions in 1101 a single DSDL module even if in YANG it is distributed in several 1102 modules. In other words, translations of imported groupings and 1103 typedefs are installed in the translation of importing module - but 1104 only if they are really used there. 1106 However, the 'include' statement that can be used in YANG to include 1107 submodules has the same semantics as the pattern of RELAX 1108 NG: th esubmodule contributes both definitions and data nodes and 1109 inherits the namespace of the parent module. Consequently, the 1110 structure of YANG submodules belonging to the same module can be 1111 retained in RELAX NG. 1113 4.3. Granularity 1115 RELAX NG supports different styles of structuring the schema: One 1116 extreme, often called "Russian Doll", specifies the structure of an 1117 XML instance document in a single hierarchy. The other extreme, the 1118 flat style, uses a similar approach as the Data Type Definition (DTD) 1119 schema language - every XML element is introduced inside a new named 1120 pattern. In practice, some compromise between the two extremes is 1121 usually chosen. 1123 YANG in principle supports both styles, too, but in most cases the 1124 modules are organized in a way that's closer to the "Russian Doll" 1125 style, which provides a better insight into the structure of the 1126 configuration data. Groupings are usually defined only for contents 1127 that are prepared for reuse in multiple places via the 'uses' 1128 statement. In contrast, RELAX NG schemas tend to be much flatter, 1129 because finer granularity is in RELAX NG also needed for 1130 extensibility of the schemas - it is only possible to replace or 1131 modify schema fragments that are factored out as named patterns. For 1132 YANG this is not an issue since its 'augment' statement can delve, by 1133 using path expressions, into arbitrary depths of existing structures. 1135 In general, it not feasible to map YANG extension mechanisms to those 1136 of RELAX NG. For this reason, the mapping essentially keeps the 1137 granularity of the original YANG data model: definitions of named 1138 patterns in the resulting RELAX NG schema usually have direct 1139 counterparts in YANG groupings and definitions of complex types. 1141 4.4. Validation Phases 1143 Validation of the conceptual tree data may occur in different logical 1144 phases, adding more tests with each phase. We use three levels or 1145 phases for validating an instance document. There is a level of 1146 validation which is appropriate even for loose XML document fragments 1147 which still maintain their hierarchy (the fragment phase), there is a 1148 level of validation appropriate for a cohesive XML document but which 1149 may not be able to validate relational integrity checks against some 1150 operational state (the standard phase), and there is validation which 1151 includes all relational integrity checks (the full validation phase). 1152 For example, in NETCONF an edit-config operation can cause the 1153 replacement a small fragment of XML. A candidate configuration may 1154 be waiting for application but can't check the readiness of a piece 1155 of hardware that the configuration refers to. 1157 From the NETCONF perspective, these three phrases can considered to 1158 have the following scope and triggers: 1160 1. the fragment phase: This can be run against individual NETCONF 1161 operations; should be automatically triggered 1163 2. the standard phase: This can be run against the candidate 1164 configuration, but won't always pass; should be manually 1165 triggered 1167 3. the full validation phase: This can be run against a running 1168 configuration; should be automatically triggered 1170 During the Fragment phase validation it is verified that the content 1171 is appropriate to the operation. 1173 During Standard phase validation (all rules except for keyref 1174 checking): 1176 o Verify that mustUse items are present. 1178 o Check the uniqueness for unique and key annotations. 1180 o Print a warning if any manual validation rules are present. 1182 During Full phase validation: add keyref checks. 1184 All embedded Schematron will run in the standard phase unless the a 1185 'dml:phase' attribute is included with the name of a different phase 1186 ('fragment' or 'full'). 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1204 5. Overview of the Mapping 1206 This section gives an overview of the YANG-to-DSDL mapping, its 1207 inputs and outputs, and presents the general goals of this 1208 specification. 1210 As described in Section 2, the mapping process is divided into two 1211 stages. This specification concentrates on the first stage, namely 1212 translating one or more YANG modules into a DSDL schema for the 1213 conceptual tree. The aim is to translate most of the semantics of 1214 the YANG module(s) and express them using the logic of DSDL schema 1215 languages. The schema for the conceptual tree captures grammatical 1216 and syntactic constraints and other information for the configuration 1217 datastore rendered as XML (which can be obtained inside the reply to 1218 NETCONF method without any filters), and contents of both input 1219 and output parts of all RPC methods defined by the module(s). 1221 The second stage, which transforms the schema for the conceptual tree 1222 into multiple schemas for validating the contents of different 1223 NETCONF PDUs under specific circumstances is outside the scope of 1224 this specification and will be addressed in subsequent documents. 1226 An implementation of the mapping algorithm MUST accept as input one 1227 or more valid YANG modules that are already parsed into a tree data 1228 structure, henceforth denoted as the "YANG tree". Each node in the 1229 YANG tree is an object (structure) that corresponds to a single YANG 1230 statement. This object records the essential parameters of the 1231 statement (keyword, argument string) and keeps a pointer to the 1232 parent statement and a list of substatements. 1234 It is important to be able to process multiple YANG modules together 1235 since multiple modules may be negotiated for a NETCONF session and 1236 the contents of the configuration datastore is then obtained as the 1237 union of data trees specified by individual modules, perhaps with 1238 multiple root nodes. In addition, the input modules may be coupled 1239 by the 'augment' statement in which one module augments the data tree 1240 of another module. 1242 It is also assumed that the algorithm has access, perhaps on demand, 1243 to the parsed form of all YANG modules that the module imports 1244 (transitively). 1246 The output of the mapping algorithm is a RELAX NG schema annotated 1247 with XML elements and attributes of the other DSDL schema languages 1248 (Schematron and DSRL) and additional annotations (metadata, 1249 documentation and NETMOD-specific attributes). Therefore, the 1250 resulting schema is an XML document containing qualified names from 1251 the following vocabularies and namespaces: 1253 o _RELAX NG_ (DSDL Part 2 [RNG]) is used for representing 1254 grammatical constraints, simple datatypes (via the W3C XML Schema 1255 Datatype Library [XSD-D]), complex datatypes, restrictions of 1256 datatypes, and YANG groupings. RELAX NG namespace is 1257 "http://relaxng.org/ns/structure/1.0" and the namespace of the W3C 1258 Schema Datatype Library is 1259 "http://www.w3.org/2001/XMLSchema-datatypes". 1261 o _Schematron_ (DSDL Part 3 [Schematron]) is used for specifying 1262 additional semantic constraints that are either inherent to YANG 1263 (e.g., uniqueness of list keys) or specified by the data model 1264 author (e.g., using the 'must' statement). Schematron namespace 1265 is "http://purl.oclc.org/dsdl/schematron". 1267 o _Document Schema Renaming Language_ (DSRL; DSDL Part 8 [DSRL]) is 1268 used for specifying default values for YANG leaf nodes and 1269 typedefs (cf. 'default' statement). DSRL namespace is 1270 "http://purl.oclc.org/dsdl/dsrl". 1272 o _Dublin Core metadata terms_ [DCMI] are used for general data 1273 model metadata such as authorship information, revision date or 1274 model description. The namespace for Dublin Core metadata terms 1275 is "http://purl.org/dc/terms". 1277 o _RELAX NG DTD compatibility annotations_ [RNG-DTD] are used for 1278 'description' and 'reference' strings, except at the top level of 1279 a module where Dublin Core metadata terms are used for this 1280 purpose. The namespace for DTD compatibility annotations is 1281 "http://relaxng.org/ns/compatibility/annotations/1.0". 1283 o _NETMOD-specific annotations_ is a small collection of other 1284 annotations that convey additional semantics expressed by YANG 1285 model. They are always modeled as XML attributes attached to the 1286 RELAX NG elements that they qualify. The namespace for NETMOD- 1287 specific annotations is 1288 "urn:ietf:params:xml:ns:netmod:dsdl-attrib:1". 1290 An implementation SHOULD allow selection of a subset of schema 1291 languages and annotation types to be used for output. For example, a 1292 user might want to select pure RELAX NG without any annotations. 1294 The DSDL architecture assumes that each constituent schema language 1295 is confined to a separate schema document. In contrast, the schema 1296 for the conceptual tree produced by the mapping combines all DSDL 1297 languages and annotations into a single XML tree. This is considered 1298 more appropriate for the following reasons: 1300 1. The conceptual tree adds several artificial nodes. As a result, 1301 the XPath expressions that define the context for Schematron 1302 rules and DSRL default values differ from those that used in 1303 validation schemas and would thus have to be modified in each of 1304 the separate DSDL schemas. 1306 2. Putting all constraints in one place leads to a more compact 1307 representation that is also easier to read. 1309 3. The schema for the conceptual tree is not intended for 1310 validation. 1312 To illustrate the difference, consider the following YANG module: 1314 module dhcp { 1315 namespace "http://example.com/ns/dhcp"; 1316 prefix dhcp; 1317 ... 1318 container dhcp { 1319 ... 1320 leaf max-lease-time { ... }; 1321 leaf default-lease-time { 1322 ... 1323 must '$this <= ../max-lease-time' { 1324 error-message 1325 "default-lease-time must be less than max-lease-time"; 1326 } 1327 default 600; 1328 } 1329 ... 1330 } 1331 ... 1332 } 1334 If multiple schemas for the conceptual tree were generated, i.e., 1335 separate RELAX NG, Schematron and DSRL, the 'must' statement would be 1336 mapped to the following Schematron fragment: 1338 1339 1342 default-lease-time must be less than max-lease-time 1343 1344 1345 1347 Similarly, the 'default' statement results in the following DSRL 1348 fragment: 1350 1351 /nmt:netmod-tree/nmt:data/dhcp:dhcp 1352 dhcp:default-lease-time 1353 600 1354 1356 In both the Schematron and DSRL fragments, the context for the rules 1357 is explicitly specified by means of an XPath expression, which 1358 however always contains the two top-level nodes of the conceptual 1359 tree. If we insert these rules as annotations into the RELAX NG 1360 schema, the context is implicitly defined by the location of the 1361 rules with the RELAX NG schema. For the validation schemas that are 1362 generated in the second stage of the mapping, the correct XPath 1363 expressions can be generated from this implicit information. 1364 Consequently, the resulting RELAX NG for the conceptual tree fragment 1365 is significantly simpler: 1367 1368 ... 1369 1370 The default-lease-time must be less than max-lease-time 1371 1372 600 1373 1375 Since RELAX NG compact syntax [RNG-CS] is often the preferred form 1376 for perusal by human readers, the secondary goal of the mapping is to 1377 guarantee a reasonable level of readability of the resulting RELAX NG 1378 in the compact syntax as well, even if multiple embedded annotation 1379 types are used. 1381 6. Specification of the Mapping 1383 6.1. Optional and Mandatory Content 1385 In YANG, all leaf nodes are optional unless they contain substatement 1387 mandatory true; 1389 or unless they are declared as list keys. 1391 Lists or leaf-lists are optional unless they contain 'min-elements' 1392 substatement with argument value greater than zero. 1394 A slightly more complicated situation arises for YANG containers. 1395 First, containers with the 'presence' substatement are therefore 1396 always optional since their presence or absence carries specific 1397 information. On the other hand, non-presence containers may be 1398 omitted if they are empty. For the purposes of the YANG-to-DSDL 1399 mapping, we declare a non-presence container as optional if and only 1400 if the following two conditions hold: 1402 1. none of its descendant leaf nodes is mandatory or, if such a leaf 1403 exists, it is enclosed in an intervening container with presence; 1405 2. none of its descendant list or leaf-list nodes has 'min-elements' 1406 substatement with argument value greater than zero or, if such a 1407 list or leaf-list exists, it is enclosed in an intervening 1408 container with presence. 1410 In RELAX NG, all elements that are optional must be explicitly 1411 wrapped in the element. The mapping algorithm thus uses 1412 the above rules to determine whether a YANG node is optional and if 1413 so, insert the element in the RELAX NG schema. 1415 6.2. Mapping YANG Groupings and Typedefs 1417 YANG groupings and typedefs are generally translated into RELAX NG 1418 named patterns. There are, however, several caveats that the mapping 1419 has to take into account. 1421 6.2.1. Mangled Names of RELAX NG Named Patterns 1423 YANG typedefs and groupings may appear in all levels of the module 1424 hierarchy and are subject to lexical scoping, see [YANG], Section 1425 5.8. Moreover, top-level symbols from external modules are imported 1426 as qualified names consisting of the external module namespace and 1427 the name of the symbol. In contrast, named patterns in RELAX NG 1428 (both local and imported via the pattern) share the same 1429 namespace and are always global - their definitions may only appear 1430 at the top level of the RELAX NG schema as children of the 1431 element. Consequently, whenever YANG groupings and typedefs are 1432 translated into RELAX NG named pattern definitions, their names MUST 1433 be disambiguated in order to avoid naming conflicts. The mapping 1434 uses the following name mangling procedure: 1436 o Names of groupings and typedefs appearing at the _top level_ of 1437 the YANG module hierarchy are prefixed with the module name and 1438 two underscore characters ("__"). 1440 o Names of other groupings and typedefs, i.e., those that do not 1441 appear at the top level of a YANG module, are prefixed with their 1442 full path that consisting of two underscore characters followed by 1443 the names of all ancestor data nodes separated by double 1444 underscore. 1446 For example, consider the following YANG module which imports the 1447 standard module "inet-types" [Ytypes]: 1449 module foo { 1450 namespace "http://example.com/ns/foo"; 1451 prefix "foo"; 1452 import "inet-types" { 1453 prefix "inet"; 1454 } 1455 typedef vowels { 1456 type string { 1457 pattern "[aeiouy]*"; 1458 } 1459 } 1460 grouping "grp1" { 1461 leaf "void" { 1462 type "empty"; 1463 } 1464 } 1465 container "cont" { 1466 grouping "grp2" { 1467 leaf "address" { 1468 type "inet:ip-address"; 1469 } 1470 } 1471 leaf foo { 1472 type vowels; 1473 } 1474 uses "grp1"; 1475 uses "grp2"; 1476 } 1477 The resulting RELAX NG schema will then contain the following named 1478 patterns: 1480 1481 1482 [aeiouy]* 1483 1484 1486 1487 1488 1489 1490 1491 1492 1494 1495 1496 1497 1498 1500 1501 1502 1503 1504 1505 1507 1508 ... 1509 1511 1512 ... 1513 1515 6.2.2. YANG Refinements and Augments 1517 When a YANG grouping is used, it may be modified in place either by a 1518 refinement or an augment. Refinements (see [YANG], Section 7.12.2) 1519 are specified as substatements of the corresponding 'uses' statement. 1521 The augment mechanism ([YANG], Section 7.15) is slightly different in 1522 that the 'augment' statement is not a substatement of 'uses' - in 1523 most cases it is its sibling. While this can be in principle used 1524 for augmenting a subtree that is specified in the same place (without 1525 a grouping), in virtually all cases the 'augment' statement is really 1526 useful only in connection with 'uses'. 1528 [Editor's note: It is hoped that syntax of both the refinement and 1529 augment will be unified in the future versions of YANG and, in 1530 particular, that the relation of 'augment' and 'usus' statements will 1531 be made explicit.] 1533 In order to correctly map a 'uses' statement with an refinement or 1534 augment, the translated contents of the grouping must be expanded and 1535 the augmenting or refinement nodes added to the subtree. The current 1536 syntax of 'augment' causes the additional complication related to the 1537 fact that it may not be immediately clear which 'uses' statement is 1538 the one to be augmented. To resolve this uncertainty, the mapping 1539 algorithm must find the corresponding groupings for all 'uses' 1540 statements in the local scope and compare their top-level nodes with 1541 the XPath expression in the argument of 'augment'. 1543 For example, consider the grouping 1545 grouping cask-grp { 1546 container cask { 1547 leaf maple { ... } 1548 } 1549 } 1551 First, assume it is used without a refinement or augment: 1553 container barrel { 1554 uses cask-grp; 1555 } 1557 Then the corresponding RELAX NG snippet is an exact analogy of YANG: 1559 1560 1561 1563 On the other hand, if the "cask-grp" grouping is used with a 1564 refinement or augment, for example: 1566 container barrel { 1567 uses cask-grp; 1568 augment "cask" { 1569 leaf linden { ... }; 1570 } 1571 } 1572 Then the grouping is expanded and augmented in place: 1574 1575 1576 1577 ... 1578 1579 1580 ... 1581 1582 1583 1585 6.2.3. Type derivation chains 1587 6.3. Mapping RPC Signatures 1589 6.4. Mapping Notifications 1591 6.5. Default values 1592 7. Mapping Rules for YANG Statements 1594 This section describes in each of its subsections the mapping 1595 procedure for one YANG statement, as it is currently implemented in 1596 the YANG->DSDL translator plug-in for the _pyang_ tool. It is a work 1597 in progress and the implementation is open for diFscussion and 1598 changes. 1600 [Editor's Note: May need to discuss the difference between mapping 1601 and pseudo code.] 1603 In accord with the description of the mapping algorithm in Section 5, 1604 we assume the following context: 1606 o The data structure (or object) representing the YANG statement 1607 being mapped is stored in the "stmt" variable. In particular, 1608 "stmt.arg" is the argument of this statement. 1610 o A pointer to the RELAX NG element that will become parent of the 1611 new XML fragment representing the translation of the current YANG 1612 statement is also available. Schematically, the context in the 1613 RELAX NG tree looks like this: 1615 1616 ... next new schema stuff comes here ... 1617 1619 o When we say here that a new element is inserted, it means that it 1620 becomes a child of . When we say that is inserted and becomes the new parent element, the 1622 situation changes as follows: 1624 1625 1626 ... next new schema stuff comes here ... 1627 1628 1630 Throughout this section, we use qualified names for all XML elements. 1631 The mapping of prefixes to namespace URIs is shown in the table 1632 below. 1634 +--------+-----------------------------------------------------+ 1635 | Prefix | Namespace URI | 1636 +--------+-----------------------------------------------------+ 1637 | a | http://relaxng.org/ns/compatibility/annotations/1.0 | 1638 | | | 1639 | dc | http://purl.org/dc/terms | 1640 | | | 1641 | dsrl | http://purl.oclc.org/dsdl/dsrl | 1642 | | | 1643 | dml | urn:ietf:params:xml:ns:netmod:dsdl-attrib:1 | 1644 | | | 1645 | sch | http://purl.oclc.org/dsdl/schematron | 1646 +--------+-----------------------------------------------------+ 1648 Table 2 1650 In order to avoid unnecessary complications, this section describes 1651 the mapping algorithm for single-file output, i.e., one of the 1652 alternatives in Section 5. 1654 7.1. The anyxml Statement 1656 At the first occurrence of this statement, the following pattern 1657 definition is added to the RELAX NG schema (cf. [Vli04], p. 172): 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1674 Reference to this pattern is then inserted for all 'anyxml' 1675 statements. 1677 7.2. The argument Statement 1679 This statement MAY be ignored if by an implementation or mode that 1680 doesn't map YANG extensions, see Section 6.2.2. Otherwise, the 1681 argument value MUST be used as the name of the extension argument. 1683 It can be represented either as an XML element or attribute, 1684 depending on the "yin-element" statement. See also Section 7.16. 1686 7.3. The augment Statement 1688 There are three cases that require different treatment: 1690 1. This statement MUST be ignored if it appears at the top level of 1691 a YANG module and adds nodes to a foreign module or submodule, 1692 since this additions have no impact on the YANG module where the 1693 statement appears. 1695 2. If the nodes are to be added to a schema subtree that is present 1696 in its entirety in the current context, the new nodes are 1697 inserted directly in the RELAX NG tree. 1699 3. If the subtree to be augmented (or part of it), results from an 1700 expansion of a grouping via the "uses" statement, the grouping 1701 must be expanded first and then the new nodes added. 1703 Section 6.2.2 discusses the mapping of the "augment" statement in 1704 more detail. 1706 7.4. The belongs-to Statement 1708 Insert Dublin Core metadata term . 1710 7.5. The bit Statement 1712 Handled within the "bits" type, see Section 7.47.4. 1714 7.6. The case Statement 1716 Insert element and handle all substatements. 1718 7.7. The choice Statement 1720 Insert element and handle all substatements. 1722 7.8. The config Statement 1724 Attach annotation @dml:config to the parent element and use stmt.arg 1725 as its value. 1727 7.9. The contact Statement 1729 Insert Dublin Core metadata term and use stmt.arg as 1730 its content. 1732 7.10. The container Statement 1734 Using the procedure outlined in Section 6.1, determine whether the 1735 container is optional, and if so, insert the element 1736 and make it the new parent element. 1738 Then insert element at the current position and use 1739 stmt.arg as the value of its @name attribute. 1741 Then handle all substatements. 1743 7.11. The default Statement 1745 Insert element with stmt.arg as its content. 1747 7.12. The description Statement 1749 If the statement is at the module top level, insert Dublin Core 1750 metadata term and use stmt.arg as its content. 1752 Otherwise, insert DTD compatibility element . In 1753 order to get properly formatted in the RELAX NG compact syntax, this 1754 element must be inserted as the first child of the parent element. 1756 7.13. The enum Statement 1758 Insert element and use stmt.arg as its content. 1760 Then handle the 'status' substatement. Other substatements ('value', 1761 'description' and 'reference') are ignored because the 1762 element cannot contain foreign elements, see [RNG], Section 6. 1764 7.14. The error-app-tag Statement 1766 This statement is only handled as a substatement of "must", see 1767 Section 7.30. 1769 7.15. The error-message Statement 1771 Handled only within the "must" statement, see Section 7.30. Ignored 1772 in other contexts. 1774 7.16. The extension Statement 1776 Not implemented. 1778 7.17. The grouping Statement 1780 Insert element and set the value of its @name attribute 1781 to stmt.arg with prepended full path, i.e., names of all ancestor 1782 nodes in the YANG schema tree separated by double underlines - see 1783 Section 6.2.1. 1785 Then handle all substatements. 1787 7.18. The import Statement 1789 Ignored, as it is assumed that all imported modules are processed by 1790 the YANG parser and made available to the mapping algorithm. 1792 7.19. The include Statement 1794 Insert and set the value of its @href attribute to 1795 stmt.arg concatenated with the file extension ".rng". 1797 7.20. The input Statement 1799 Not implemented. 1801 7.21. The key Statement 1803 Attach attribute @dml:key to the parent element and use stmt.arg as 1804 its value. 1806 7.22. The leaf Statement 1808 Unless there is the "mandatory true;" substatement or unless an 1809 enclosing list declares this leaf among its keys, insert element and make it the new parent element. 1812 Then insert element and use stmt.arg as the value of 1813 its @name attribute. 1815 Then handle all substatements. 1817 7.23. The leaf-list Statement 1819 If there is a 'min-elements' substatement with argument value greater 1820 than zero, insert and make it the new parent element. 1821 Otherwise insert and make it the new parent element. 1823 Then insert and use stmt.arg as its value. If there is 1824 a 'min-elements' substatement with argument value greater than zero, 1825 attach attribute @dml:min-elements to the element and 1826 use the argument of the 'min-elements' statement as its value. If 1827 there is a 'max-elements' substatement, attach attribute @dml:max- 1828 elements to the element and use the argument of the 1829 'max-elements' statement as its value. If there is an 'ordered-by' 1830 substatement, attach attribute @dml:ordered-by to the 1831 element and use the argument of the 'ordered-by' statement as its 1832 value. 1834 Then handle all remaining substatements. 1836 7.24. The length Statement 1838 Handled within the "string" type, see Section 7.47.8. 1840 7.25. The list Statement 1842 Handled exactly as the 'leaf-list' statement, see Section 7.23. 1844 7.26. The mandatory Statement 1846 Handled within the 'leaf' statement, see Section 7.22. 1848 7.27. The max-elements Statement 1850 Handled within 'leaf-list' or 'list' statements, see Section 7.23. 1852 7.28. The min-elements Statement 1854 Handled within 'leaf-list' or 'list' statements, see Section 7.23. 1856 7.29. The module Statement 1858 This statement is not specifically handled. The mapping algorithm 1859 starts with its substatements. 1861 7.30. The must Statement 1863 Insert element. The value of its @test attribute is set 1864 to stmt.arg in which all occurrences of the string "$this" are 1865 replaced by "." (single dot). If there is an 'error-message' 1866 substatement, its argument value is used as the content of , otherwise the element is empty. 1869 7.31. The namespace Statement 1871 Attach @ns attribute to the element (the root of the 1872 RELAX NG schema) and use stmt.arg as its value. 1874 7.32. The notification Statement 1876 Not implemented. 1878 7.33. The ordered-by Statement 1880 Handled within 'leaf-list' and 'list' statements, see Section 7.23. 1882 7.34. The organization Statement 1884 Insert Dublin Core metadata term and use stmt.arg as its 1885 content. 1887 7.35. The output Statement 1889 Not implemented. 1891 7.36. The path Statement 1893 Handled within "keyref" type, see Section 7.47.6. 1895 7.37. The pattern Statement 1897 Handled within "string" type, see Section 7.47.8. 1899 7.38. The position Statement 1901 Not implemented. 1903 7.39. The prefix Statement 1905 Not implemented. In RELAX NG, the elements of the target namespace 1906 are unprefixed. 1908 7.40. The presence Statement 1910 Handled within 'container' statement, see Section 7.10 and also 1911 Section 6.1. 1913 7.41. The range Statement 1915 Handled within numeric types, see Section 7.47.7. 1917 7.42. The reference Statement 1919 If this statement is at module top level, insert Dublin Core metadata 1920 term and use stmt.arg as its content. 1922 Otherwise insert and use stmt.arg as its content. 1923 Within parent element children, insert it as the last of 1924 elements (i.e., after translations of 'description' 1925 statements), but before any other subelements. 1927 7.43. The revision Statement 1929 Insert Dublin Core metadata term and use stmt.arg as its 1930 content. 1932 7.44. The rpc Statement 1934 Not implemented. 1936 7.45. The status Statement 1938 Attach attribute @dml:status to the parent element and use stmt.arg 1939 as its value. 1941 7.46. The submodule Statement 1943 This statement is not specifically handled. The mapping algorithm 1944 starts with its substatements. 1946 7.47. The type Statement 1948 References to derived types are handled in the same way as references 1949 to groupings via the 'uses' statement (Section 7.51): 1950 element is inserted with a properly mangled name and definitions of 1951 derived types are copied from external modules as necessary. 1953 Most YANG built-in types have an equivalent in the XSD datatype 1954 library [XSD-D] as shown in Table 3. 1956 +-----------+---------------+----------------------------------+ 1957 | YANG type | XSD type | Meaning | 1958 +-----------+---------------+----------------------------------+ 1959 | int8 | byte | 8-bit integer value | 1960 | | | | 1961 | int16 | short | 16-bit integer value | 1962 | | | | 1963 | int32 | int | 32-bit integer value | 1964 | | | | 1965 | int64 | long | 64-bit integer value | 1966 | | | | 1967 | uint8 | unsignedByte | 8-bit unsigned integer value | 1968 | | | | 1969 | uint16 | unsignedShort | 16-bit unsigned integer value | 1970 | | | | 1971 | uint32 | unsignedInt | 32-bit unsigned integer value | 1972 | | | | 1973 | uint64 | unsignedLong | 64-bit unsigned integer value | 1974 | | | | 1975 | float32 | float | 32-bit IEEE floating-point value | 1976 | | | | 1977 | float64 | double | 64-bit IEEE floating-point value | 1978 | | | | 1979 | string | string | character string | 1980 | | | | 1981 | boolean | boolean | "true" or "false" | 1982 | | | | 1983 | binary | base64Binary | binary data in base64 encoding | 1984 +-----------+---------------+----------------------------------+ 1986 Table 3: Selected datatypes from the W3C XML Schema Type Library 1988 Details about the mapping of individual YANG built-in types are given 1989 in the following subsections. 1991 7.47.1. The empty Type 1993 Insert empty element. 1995 7.47.2. The boolean and binary Types 1997 These two built-in types do not allow any restrictions and are mapped 1998 simply by inserting element whose @type attribute is set 1999 to stmt.arg mapped according to Table 3. 2001 7.47.3. The instance identifier Type 2003 This YANG built-in type has no equivalent in the XSD datatype library 2004 and is mapped to the RELAX NG "string" type: 2006 2008 7.47.4. The bits Type 2010 Insert element and insert under it for each 'bit' 2011 substatement the following XML fragment: 2013 2014 bit_name 2015 2017 where bit_name is the name of the bit as found in the argument of the 2018 corresponding 'bit' statement. 2020 7.47.5. The enumeration and union Types 2022 Insert and handle all substatements. 2024 7.47.6. The keyref type 2026 As there is no suitable counterpart for the YANG built-in "keyref" 2027 type in the XSD datatype library, this type is mapped to "string" by 2028 inserting element with @type attribute set to "string". 2029 In addition, element is inserted as child of 2030 which checks that a 'list' entry with the corresponding value of the 2031 key exists. 2033 7.47.7. The numeric Types 2035 YANG built-in numeric types are "int8", "int16", "int32", "int64", 2036 "uint8", "uint16", "uint32", "uint64", "float32" and "float64". They 2037 are handled by inserting element with @type attribute set 2038 to stmt.arg mapped according to Table 3. 2040 All numeric types support the 'range' restriction, which is handled 2041 in the following way: 2043 o If the range expression consists of a single range part, insert 2044 the pair of RELAX NG facets 2046 ... 2047 and 2049 ... 2050 Their contents are the lower and upper bound of the range part, 2051 respectively. If the range part consists of a single number, both 2052 "minInclusive" and "maxInclusive" facets use this value as their 2053 content. If the lower bound is "min", the "minInclusive" facet is 2054 omitted and if the upper bound is "max", the "maxInclusive" facet 2055 is omitted. 2057 o If the range expression has multiple parts separated by "|", then 2058 repeat the element once for every range part and wrap 2059 them all in element. Inside each element, 2060 the corresponding range part is handled as described in the 2061 previous item. 2063 For example, the 'typedef' statement 2065 typedef rt { 2066 type int32 { 2067 range "-6378..0|42|100..max"; 2068 } 2069 } 2071 translates to the following RELAX NG fragment: 2073 2074 2075 2076 -6378 2077 0 2078 2079 2080 42 2081 42 2082 2083 2084 100 2085 2086 2087 2089 7.47.8. The string Type 2091 This type is mapped by inserting the element with the 2092 @type attribute set to "string". 2094 For the 'pattern' restriction, insert element with @name 2095 attribute set to "pattern". The argument of the 'pattern' statement 2096 (regular expression) becomes the content of this element. 2098 The 'length' restriction is handled in the same way as the 'range' 2099 restriction for the numeric types, with the additional twist that if 2100 the length expression has multiple parts, the "pattern" facet 2102 ... 2103 if there is any, must be repeated inside each copy of the 2104 element, i.e., for each length part. 2106 7.48. The typedef Statement 2108 Handled exactly as the 'grouping' statement, see Section 7.17. 2110 7.49. The unique Statement 2112 Insert element. Its test checks that no two list items 2113 (sibling elements) have the same combination of values of leafs 2114 listed in stmt.arg. The content of the element, i.e., 2115 the error message, is formed by a concatenation of "Not unique: " and 2116 stmt.arg. 2118 This works in conjunction with the dml:unique annotation. 2120 7.50. The units Statement 2122 Attach attribute @dml:units to the parent element and use stmt.arg as 2123 its value. 2125 7.51. The uses Statement 2127 1. Check whether the grouping that the statement refers to is 2128 defined in the same module that is being translated. If it is 2129 so, go to step 4. 2131 2. [the grouping is defined in another module] If the same grouping 2132 has been already used in the module that is being translated, go 2133 to step 4. 2135 3. [first use of an external grouping] Copy the grouping definition 2136 from the external module and install its translation according to 2137 Section 7.17 with a properly mangled name (see Section 6.2.1). 2139 4. Insert element and set its @name attribute to stmt.arg 2140 after performing the name mangling procedure described in 2141 Section 6.2.1, taking into account whether the grouping is local 2142 or external. 2144 Handling of substatements, and in particular the refinement 2145 statements, is not implemented yet. 2147 7.52. The value Statement 2149 Not implemented. 2151 7.53. The when Statement 2153 Not implemented. 2155 7.54. The yang-version Statement 2157 Not implemented. Its stmt.arg may be checked by the mapping 2158 algorithm in order to make sure that the module is compatible. 2160 7.55. The yin-element Statement 2162 Not implemented. 2164 8. References 2166 [DCMI] DCMI, "DCMI Metadata Terms", January 2008. 2168 [DSDL] ISO/IEC, "Document Schema Definition Languages (DSDL) - 2169 Part 1: Overview", ISO/IEC 19757-1, 11 2004. 2171 [DSRL] ISO/IEC, "Document Schema Definition Languages (DSDL) - 2172 Part 8: Document Schema Renaming Language - DSRL", ISO/ 2173 IEC 19757-8, 2006. 2175 [RFC1157] Case, J., Fedor, M., Schoffstall, M., and J. Davin, 2176 "Simple Network Management Protocol (SNMP)", STD 15, 2177 RFC 1157, May 1990. 2179 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 2180 Schoenwaelder, Ed., "Structure of Management Information 2181 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 2183 [RFC3216] Elliott, C., Harrington, D., Jason, J., Schoenwaelder, J., 2184 Strauss, F., and W. Weiss, "SMIng Objectives", RFC 3216, 2185 December 2001. 2187 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 2188 December 2006. 2190 [RFC5013] Kunze, J., "The Dublin Core Metadata Element Set", 2191 RFC 5013, August 2007. 2193 [RNG] ISO/IEC, "Document Schema Definition Languages (DSDL) - 2194 Part 2: Regular-Grammar-Based Validation - RELAX NG", ISO/ 2195 IEC 19757-2:2003, 2002. 2197 [RNG-CS] Clark, J., Ed., "RELAX NG Compact Syntax", OASIS Committee 2198 Specification 21 November 2002, November 2002. 2200 [RNG-DTD] Clark, J., Ed. and M. Murata, Ed., "RELAX NG DTD 2201 Compatibility", OASIS Committee Specification 3 December 2202 2001, December 2001. 2204 [Schematron] 2205 ISO/IEC, "Document Schema Definition Languages (DSDL) - 2206 Part 3: Rule-Based Validation - Schematron", ISO/ 2207 IEC 19757-3:2006, 2006. 2209 [Vli04] van der Vlist, E., "RELAX NG", O'Reilly , 2004. 2211 [XML] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and 2212 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fourth 2213 Edition)", World Wide Web Consortium Recommendation REC- 2214 xml-20060816, August 2006, 2215 . 2217 [XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) 2218 Version 1.0", World Wide Web Consortium 2219 Recommendation REC-xpath-19991116, November 1999, 2220 . 2222 [XSD] Thompson, H., Beech, D., Maloney, M., and N. Mendelsohn, 2223 "XML Schema Part 1: Structures Second Edition", World Wide 2224 Web Consortium Recommendation REC-xmlschema-1-20041028, 2225 October 2004, 2226 . 2228 [XSD-D] Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes 2229 Second Edition", World Wide Web Consortium 2230 Recommendation REC-xmlschema-2-20041028, October 2004, 2231 . 2233 [XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World 2234 Wide Web Consortium Recommendation REC-xslt-19991116, 2235 November 1999. 2237 [YANG] Bjorklund, M., Ed., "YANG - A data modeling language for 2238 NETCONF", draft-ietf-netmod-yang-00 (work in progress), 2239 May 2008. 2241 [Ytypes] Schoenwaelder, J., Ed., "Common YANG Data Types", 2242 draft-ietf-netmod-yang-types-00 (work in progress), 2243 September 2008. 2245 [1] 2247 [2] 2249 [3] 2251 [4] 2253 Appendix A. DML Definition in Compact Syntax 2255 namespace rng = "http://relaxng.org/ns/structure/1.0" 2256 datatypes xsd = "http://www.w3.org/2001/XMLSchema-datatypes" 2257 namespace xml = "http://www.w3.org/XML/1998/namespace" 2258 namespace dsrl = "http://purl.oclc.org/dsdl/dsrl" 2259 default namespace = "http://example.org/ns/dml" 2261 start = element-dml 2263 element-dml = element dml { 2264 dmlVersionAttribute? & 2265 dml-contents 2266 } 2268 dmlVersionAttribute = attribute dmlVersion { "1.0" } 2270 dml-contents = ( 2271 dataModelVersion & 2272 organization* & 2273 contact-info* & 2274 list-order* & 2275 data-category* & 2276 mustUse-flag* & 2277 container-existence* & 2278 manual-validation* & 2279 units* & 2280 conformStatus* & 2281 mustUnderstand* 2282 ) 2284 # Each data model needs a version string 2285 dataModelVersion = element version { xsd:string } 2287 # Information about the data model author(s). 2288 # Seems like this should be in Dublin Core 2289 organization = element organization { string-with-lang } 2290 contact-info = element contact { xsd:anyURI } 2292 # Processing annotations 2293 unique = element unique { xsd:anyURI } 2294 key = element key { xsd:anyURI } 2295 keyref = element keyref { xsd:anyURI } 2297 data-category = element infoType { 2298 attribute minAccess { list { access-strings }}?, 2299 attribute maxAccess { list { access-strings }}?, 2300 ("config" | "status" | "statistics" | "action" | "notify") 2301 >> dsrl:default-content ["config"] 2302 } 2303 access-strings = ( "read" | "write" | "create" | "delete" | "execute" ) 2305 mustUse-flag = element mustUse { xsd:boolean 2306 >> dsrl:default-content ["false"] 2307 } 2309 manual-validation = element manual-validation-rule { string-with-lang } 2311 # Semantic hints 2312 list-order = element order { 2313 ("any-order" | "user-order") 2314 >> dsrl:default-content ["any-order"] 2315 } 2317 container-existence = element existence { empty } 2319 units = element units { 2320 xsd:string { pattern="[^: \n\r\t]+" } 2321 # allow familiar units, but no whitespace or absolute URIs here 2322 | 2323 xsd:anyURI { pattern="([a-zA-Z][a-zA-Z0-9\-\+\.]*:|\.\./|\./|#).*" } 2324 # allow absolute URIs, plus relative URIs with ./ or ../ 2325 # prohibit relative URIs that could look like a unit, ex: m/s 2326 } 2327 # Definition copied from definition of gml:Uomidentifier from 2328 # Section 8.2.3.6 of Geography Markup Language (GML) v3.2.1 2330 string-with-lang = ( 2331 attribute xml:lang { xsd:language }, 2332 xsd:string 2333 ) 2335 conformStatus = element status { 2336 "active" | "deprecated" | "obsolete" 2337 >> dsrl:default-content ["active"] 2338 } 2340 # the mustUnderstand element contains space separated list of namespace 2341 # tokens that need to be supported to correctly process the data model 2342 mustUnderstand = element mustUnderstand { list { xsd:NCName } } 2344 dml-netconf-error-app-tag = 2345 attribute netconf-error-app-tag { xsd:string } 2347 dml-phase-attribute = attribute phase { "fragment" | "std" | "full" } 2348 dml-moduleDefault = attribute moduleDefault { 2349 xsd:boolean >> dsrl:default-content ["false"] 2350 } 2352 Appendix B. Translation of the DHCP Data Model 2354 This appendix demonstrates output of the YANG->DSDL mapping algorithm 2355 applied to the "canonical" DHCP tutorial [3] data model. It is 2356 presented as a single-file annotated RELAX NG schema (output 2357 alternative in Section 5). 2359 Appendix B.1 shows the result of the mapping algorithm in the RELAX 2360 NG XML syntax and Appendix B.2 the same in the compact syntax, which 2361 was obtained using the Trang tool [4]. 2363 The long regular expressions for IP addresses etc. would exceed the 2364 limit of 72 characters per line, so they were replaced by a dummy 2365 text. Other than that, the results of the automatic translations 2366 were not changed. 2368 B.1. XML Syntax 2370 2371 2379 yang-central.org 2380 Partial data model for DHCP, based on the config of 2381 the ISC DHCP reference implementation. 2382 YANG module 'dhcp' (automatic translation) 2383 2384 2385 2386 configuration and operational parameters for 2387 a DHCP server. 2388 2389 2390 2391 7200 2392 2393 2394 2395 2396 2397 The 2398 default-lease-time must be less than 2399 max-lease-time 2400 600 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 false 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 2431 2432 2433 2434 2435 2436 2437 2438 2439 ethernet 2440 token-ring 2441 fddi 2442 2443 2444 2445 2446 2447 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 ... IPv4 address regexp ... 2469 2470 2471 2472 2473 ... IPv6 address regexp ... 2474 2475 2476 2477 2478 ... date-and-time regexp ... 2479 2480 2481 2482 2483 2484 2485 A reusable list of subnets 2486 2487 2488 2489 2490 2491 2492 2493 2494 Allows BOOTP clients to get addresses 2495 in this range 2496 2498 2499 2500 2501 2502 2503 2504 2505 2506 2507 2508 2509 2510 Options in the DHCP protocol 2511 2512 2513 2514 2515 See: RFC 2132, sec. 3.8 2516 2517 2518 2519 2520 2521 2522 2523 See: RFC 2132, sec. 3.17 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 7200 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 ... IPv4 prefix regexp ... 2548 2549 2550 2551 2552 ... IPv6 prefix regexp ... 2553 2554 2555 2556 2557 2558 2559 2560 2561 2562 2563 ([\p{L}\p{N}]+\.)*[\p{L}\p{N}] 2564 2565 2566 2568 B.2. Compact Syntax 2570 default namespace = "http://example.com/ns/dhcp" 2571 namespace a = "http://relaxng.org/ns/compatibility/annotations/1.0" 2572 namespace dc = "http://purl.org/dc/terms" 2573 namespace dsrl = "http://purl.oclc.org/dsdl/dsrl" 2574 namespace dml = "urn:ietf:params:xml:ns:netmod:dsdl-attrib:1" 2575 namespace sch = "http://purl.oclc.org/dsdl/schematron" 2577 dc:creator [ "yang-central.org" ] 2578 dc:description [ 2579 "Partial data model for DHCP, based on the config of\x{a}" ~ 2580 "the ISC DHCP reference implementation." 2581 ] 2582 dc:source [ "YANG module 'dhcp' (automatic translation)" ] 2583 start = 2585 ## configuration and operational parameters for a DHCP server. 2586 element dhcp { 2587 [ dml:units = "seconds" ] 2588 element max-lease-time { 2589 xsd:unsignedInt >> dsrl:default-content [ "7200" ] 2590 }?, 2591 [ dml:units = "seconds" ] 2592 element default-lease-time { 2593 xsd:unsignedInt 2594 >> sch:assert [ 2595 test = ". <= ../max-lease-time" 2596 "The default-lease-time must be less than max-lease-time" 2597 ] 2598 >> dsrl:default-content [ "600" ] 2599 }?, 2600 __subnet-list, 2601 element shared-networks { 2602 [ dml:key = "name" ] 2603 element shared-network { 2604 element name { xsd:string }, 2605 __subnet-list 2606 }* 2607 }?, 2608 element status { 2609 [ dml:key = "address" ] 2610 element leases { 2611 element address { inet-types__ip-address }, 2612 element starts { yang-types__date-and-time }?, 2613 element ends { yang-types__date-and-time }?, 2614 element hardware { 2615 element type { "ethernet" | "token-ring" | "fddi" }?, 2616 element address { yang-types__phys-address }? 2617 }? 2618 }* 2619 }? >> dml:config [ "false" ] 2620 }? 2621 inet-types__ip-address = 2622 inet-types__ipv4-address | inet-types__ipv6-address 2623 inet-types__ipv4-address = 2624 xsd:string { 2625 pattern = 2626 "... IPv4 address regexp ..." 2627 } 2628 inet-types__ipv6-address = 2629 xsd:string { 2630 pattern = 2631 "... IPv6 address regexp ..." 2632 } 2633 yang-types__date-and-time = 2634 xsd:string { 2635 pattern = 2636 "... date-and-time regexp ..." 2637 } 2638 yang-types__phys-address = xsd:string 2639 ## A reusable list of subnets 2640 __subnet-list = 2641 [ dml:key = "net" ] 2642 element subnet { 2643 element net { inet-types__ip-prefix }, 2644 element range { 2646 ## Allows BOOTP clients to get addresses in this range 2647 element dynamic-bootp { empty }?, 2648 element low { inet-types__ip-address }, 2649 element high { inet-types__ip-address } 2650 }, 2652 ## Options in the DHCP protocol 2653 element dhcp-options { 2654 [ dml:ordered-by = "user" ] 2655 ( 2656 ## See: RFC 2132, sec. 3.8 2657 element router { inet-types__host }*), 2659 ## See: RFC 2132, sec. 3.17 2660 element domain-name { inet-types__domain-name }? 2661 }?, 2662 [ dml:units = "seconds" ] 2663 element max-lease-time { 2664 xsd:unsignedInt >> dsrl:default-content [ "7200" ] 2665 }? 2666 }* 2667 inet-types__ip-prefix = 2668 inet-types__ipv4-prefix | inet-types__ipv6-prefix 2669 inet-types__ipv4-prefix = 2670 xsd:string { 2671 pattern = 2672 "... IPv4 prefix regexp ..." 2673 } 2674 inet-types__ipv6-prefix = 2675 xsd:string { 2676 pattern = 2677 "... IPv6 prefix regexp ..." 2678 } 2679 inet-types__host = inet-types__ip-address | inet-types__domain-name 2680 inet-types__domain-name = 2681 xsd:string { pattern = "([\p{L}\p{N}]+\.)*[\p{L}\p{N}]" } 2683 Authors' Addresses 2685 Ladislav Lhotka 2686 CESNET 2688 Email: lhotka@cesnet.cz 2690 Rohan Mahy 2691 Plantronics 2693 Email: rohan@ekabal.com 2695 Sharon Chisholm 2696 Nortel 2698 Email: schishol@nortel.com 2700 Full Copyright Statement 2702 Copyright (C) The IETF Trust (2008). 2704 This document is subject to the rights, licenses and restrictions 2705 contained in BCP 78, and except as set forth therein, the authors 2706 retain all their rights. 2708 This document and the information contained herein are provided on an 2709 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 2710 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 2711 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 2712 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 2713 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2714 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2716 Intellectual Property 2718 The IETF takes no position regarding the validity or scope of any 2719 Intellectual Property Rights or other rights that might be claimed to 2720 pertain to the implementation or use of the technology described in 2721 this document or the extent to which any license under such rights 2722 might or might not be available; nor does it represent that it has 2723 made any independent effort to identify any such rights. Information 2724 on the procedures with respect to rights in RFC documents can be 2725 found in BCP 78 and BCP 79. 2727 Copies of IPR disclosures made to the IETF Secretariat and any 2728 assurances of licenses to be made available, or the result of an 2729 attempt made to obtain a general license or permission for the use of 2730 such proprietary rights by implementers or users of this 2731 specification can be obtained from the IETF on-line IPR repository at 2732 http://www.ietf.org/ipr. 2734 The IETF invites any interested party to bring to its attention any 2735 copyrights, patents or patent applications, or other proprietary 2736 rights that may cover technology that may be required to implement 2737 this standard. Please address the information to the IETF at 2738 ietf-ipr@ietf.org. 2740 Acknowledgment 2742 Funding for the RFC Editor function is provided by the IETF 2743 Administrative Support Activity (IASA).