NETMOD L. Lhotka Internet-Draft CESNET Intended status: Standards Track R. Mahy Expires:September 3,December 21, 2010 Plantronics S. Chisholm NortelMarch 2,June 19, 2010 Mapping YANG to Document Schema Definition Languages and Validating NETCONF Contentdraft-ietf-netmod-dsdl-map-05draft-ietf-netmod-dsdl-map-06 Abstract This draft specifies the mapping rules for translating YANG data models into Document Schema Definition Languages (DSDL), a coordinated set of XML schema languages standardized as ISO 19757. The following DSDL schema languages areusedaddressed by the mapping: RELAX NG, Schematron and DSRL. The mapping takes one or more YANG modules and produces a set of DSDL schemas for a selected target document type - datastore content, NETCONFPDUmessage etc. Procedures forschema- basedschema-based validation of such documents are also discussed. Status of this Memo This Internet-Draft is submittedto IETFin full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force(IETF), its areas, and its working groups.(IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts.Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.This Internet-Draft will expire onSeptember 3,December 21, 2010. Copyright Notice Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 7 2.1. Glossary of New Terms . . . . . . . . . . . . . . . . .810 3. Objectives and Motivation . . . . . . . . . . . . . . . . . .1011 4. DSDL Schema Languages . . . . . . . . . . . . . . . . . . . .1213 4.1. RELAX NG . . . . . . . . . . . . . . . . . . . . . . . .1213 4.2. Schematron . . . . . . . . . . . . . . . . . . . . . . .1314 4.3. Document Semantics Renaming Language (DSRL) . . . . . .1415 5. Additional Annotations . . . . . . . . . . . . . . . . . . .1516 5.1. Dublin Core Metadata Elements . . . . . . . . . . . . .1516 5.2. RELAX NG DTD Compatibility Annotations . . . . . . . . .1516 5.3. NETMOD-Specific Annotations . . . . . . . . . . . . . .1617 6. Overview of the Mapping . . . . . . . . . . . . . . . . . . .1819 7. NETCONF Content Validation . . . . . . . . . . . . . . . . .2021 8. Design Considerations . . . . . . . . . . . . . . . . . . . .2122 8.1.Conceptual Data TreeHybrid Schema . . . . . . . . . . . . . . . . . .21. . . 22 8.2. Modularity . . . . . . . . . . . . . . . . . . . . . . .2325 8.3. Granularity . . . . . . . . . . . . . . . . . . . . . .2426 8.4. Handling of XML Namespaces . . . . . . . . . . . . . . .24 8.5. Features and Deviations . . . . . . . . . . . . . . . . 2527 9. Mapping YANG Data Models to theConceptual TreeHybrid Schema . . .26. . . . . 28 9.1. Occurrence Rules for Data Nodes . . . . . . . . . . . .2628 9.1.1. Optional and Mandatory Nodes . . . . . . . . . . .2729 9.1.2. Implicit Nodes . . . . . . . . . . . . . . . . . .2830 9.2. Mapping YANG Groupings and Typedefs . . . . . . . . . .2931 9.2.1. YANG Refinements and Augments . . . . . . . . . . .3132 9.2.2. Type Derivation Chains . . . . . . . . . . . . . .3435 9.3. Translation of XPath Expressions . . . . . . . . . . . . 37 9.4. YANG Language Extensions . . . . . . . . . . . . . . . .3738 10. MappingConceptual Tree SchemaYANG Statements toDSDLthe Hybrid Schema . . . . . . . . 40 10.1. The anyxml Statement . . . . . . .39 10.1. Generating RELAX NG Schemas for Various Document Types.39 10.1.1. Reply to <get> or <get-config>. . . . . . . . . . 4010.1.2. Remote Procedure Calls10.2. The argument Statement . . . . . . . . . . . . . .40 10.1.3. Notifications. . . 41 10.3. The augment Statement . . . . . . . . . . . . . . . .41 10.2. Mapping Semantic Constraints to Schematron. 42 10.4. The base Statement . . . . . .42 10.2.1. Validation Phases. . . . . . . . . . . . . 42 10.5. The belongs-to Statement . . . .45 10.3. Constraints on Mandatory Choice. . . . . . . . . . . .46 10.4. Mapping Default Values to DSRL42 10.6. The bit Statement . . . . . . . . . . . . .48 11. Mapping YANG Statements to Conceptual Tree Schema. . . . . .52 11.1.42 10.7. Theanyxmlcase Statement . . . . . . . . . . . . . . . . . .52 11.2.. 42 10.8. Theargumentchoice Statement . . . . . . . . . . . . . . . . .53 11.3.. 42 10.9. Theaugmentconfig Statement . . . . . . . . . . . . . . . . .54 11.4.. 43 10.10. Thebasecontact Statement . . . . . . . . . . . . . . . . .. . 54 11.5.43 10.11. Thebelongs-tocontainer Statement . . . . . . . . . . . . . . . .54 11.6.43 10.12. Thebitdefault Statement . . . . . . . . . . . . . . . . .. . 54 11.7.43 10.13. Thecasedescription Statement . . . . . . . . . . . . . . .. . . . 54 11.8.45 10.14. Thechoicedeviation Statement . . . . . . . . . . . . . . . .. . 54 11.9.45 10.15. Theconfigenum Statement . . . . . . . . . . . . . . . . . .55 11.10.. 45 10.16. Thecontacterror-app-tag Statement . . . . . . . . . . . . . .. . . 55 11.11.45 10.17. Thecontainererror-message Statement . . . . . . . . . . . . . .. . 55 11.12.45 10.18. Thedefaultextension Statement . . . . . . . . . . . . . . . .. 55 11.13.45 10.19. Thedescriptionfeature Statement . . . . . . . . . . . . . . .57 11.14.. . 45 10.20. Thedeviationgrouping Statement . . . . . . . . . . . . . . . .57 11.15. The enum Statement . . . . . . . . . . . . . . . . . . . 57 11.16. The error-app-tag Statement . . . . . . . . . . . . . . 57 11.17. The error-message Statement . . . . . . . . . . . . . . 57 11.18. The extension Statement . ... . . . . . . . . . . . . 57 11.19. The feature Statement . . . . . . . . . . . . . . . . . 57 11.20. The grouping Statement . . . . . . . . . . . . . . . . . 57 11.21.45 10.21. The identity Statement . . . . . . . . . . . . . . . . .58 11.22.46 10.22. The if-feature Statement . . . . . . . . . . . . . . . .58 11.23.47 10.23. The import Statement . . . . . . . . . . . . . . . . . .58 11.24.48 10.24. The include Statement . . . . . . . . . . . . . . . . .58 11.25.48 10.25. The input Statement . . . . . . . . . . . . . . . . . .59 11.26.48 10.26. The key Statement . . . . . . . . . . . . . . . . . . .59 11.27.48 10.27. The leaf Statement . . . . . . . . . . . . . . . . . . .59 11.28.48 10.28. The leaf-list Statement . . . . . . . . . . . . . . . .59 11.29.49 10.29. The length Statement . . . . . . . . . . . . . . . . . .60 11.30.49 10.30. The list Statement . . . . . . . . . . . . . . . . . . .60 11.31.50 10.31. The mandatory Statement . . . . . . . . . . . . . . . .61 11.32.51 10.32. The max-elements Statement . . . . . . . . . . . . . . .61 11.33.51 10.33. The min-elements Statement . . . . . . . . . . . . . . .62 11.34.51 10.34. The module Statement . . . . . . . . . . . . . . . . . .62 11.35.51 10.35. The must Statement . . . . . . . . . . . . . . . . . . .62 11.36.52 10.36. The namespace Statement . . . . . . . . . . . . . . . .63 11.37.52 10.37. The notification Statement . . . . . . . . . . . . . . .63 11.38.53 10.38. The ordered-by Statement . . . . . . . . . . . . . . . .63 11.39.53 10.39. The organization Statement . . . . . . . . . . . . . . .63 11.40.53 10.40. The output Statement . . . . . . . . . . . . . . . . . .63 11.41.53 10.41. The path Statement . . . . . . . . . . . . . . . . . . .63 11.42.53 10.42. The pattern Statement . . . . . . . . . . . . . . . . .64 11.43.53 10.43. The position Statement . . . . . . . . . . . . . . . . .64 11.44.54 10.44. The prefix Statement . . . . . . . . . . . . . . . . . .64 11.45.54 10.45. The presence Statement . . . . . . . . . . . . . . . . .64 11.46.54 10.46. The range Statement . . . . . . . . . . . . . . . . . .64 11.47.54 10.47. The reference Statement . . . . . . . . . . . . . . . .64 11.48.54 10.48. The require-instance Statement . . . . . . . . . . . . .64 11.49.54 10.49. The revision Statement . . . . . . . . . . . . . . . . .64 11.50.54 10.50. The rpc Statement . . . . . . . . . . . . . . . . . . .65 11.51.55 10.51. The status Statement . . . . . . . . . . . . . . . . . .65 11.52.55 10.52. The submodule Statement . . . . . . . . . . . . . . . .65 11.53.55 10.53. The type Statement . . . . . . . . . . . . . . . . . . .65 11.53.1.55 10.53.1. The empty Type . . . . . . . . . . . . . . . . . .66 11.53.2.56 10.53.2. The boolean and binary Types . . . . . . . . . . .67 11.53.3.57 10.53.3. The bits Type . . . . . . . . . . . . . . . . . . .67 11.53.4.57 10.53.4. The enumeration and union Types . . . . . . . . . .67 11.53.5.57 10.53.5. The identityref Type . . . . . . . . . . . . . . .67 11.53.6.57 10.53.6. The instance-identifier Type . . . . . . . . . . .69 11.53.7.58 10.53.7. The leafref Type . . . . . . . . . . . . . . . . .69 11.53.8.58 10.53.8. The numeric Types . . . . . . . . . . . . . . . . .69 11.53.9.58 10.53.9. The string Type . . . . . . . . . . . . . . . . . .71 11.53.10.60 10.53.10. Derived Types . . . . . . . . . . . . . . . . . . .72 11.54.61 10.54. The typedef Statement . . . . . . . . . . . . . . . . .73 11.55.62 10.55. The unique Statement . . . . . . . . . . . . . . . . . .73 11.56.62 10.56. The units Statement . . . . . . . . . . . . . . . . . .73 11.57.63 10.57. The uses Statement . . . . . . . . . . . . . . . . . . .74 11.58.63 10.58. The value Statement . . . . . . . . . . . . . . . . . .74 11.59.63 10.59. The when Statement . . . . . . . . . . . . . . . . . . .74 11.60.63 10.60. The yang-version Statement . . . . . . . . . . . . . . .74 11.61.63 10.61. The yin-element Statement . . . . . . . . . . . . . . .74 12.63 11. MappingNETMOD-specific annotationsthe Hybrid Schema to DSDLSchema Languages. . . . . . . . . . . . . . 64 11.1. Generating RELAX NG Schemas for Various Document Types . 64 11.2. Mapping Semantic Constraints to Schematron . . . . . . . 65 11.2.1. Constraints on Mandatory Choice . . . .75 12.1. The @nma:config Annotation. . . . . . 68 11.3. Mapping Default Values to DSRL . . . . . . . . .75 12.2. The @nma:default Annotation. . . . 69 12. Mapping NETMOD-specific Annotations to DSDL Schema Languages . . . . . . . . . . . .75 12.3. The @nma:implicit Annotation. . . . . . . . . . . . . . 7512.4.12.1. The @nma:config Annotation . . . . . . . . . . . . . . . 75 12.2. The @nma:default Annotation . . . . . . . . . . . . . . 75 12.3. The <nma:error-app-tag> Annotation . . . . . . . . . . . 7512.5.12.4. The <nma:error-message> Annotation . . . . . . . . . . . 7512.6.12.5. The<nma:instance-identifier>@if-feature Annotation . . . . . . . . . . . . . . . 7512.7.12.6. The@nma:key@nma:implicit Annotation . . . . . . . . . . . . . . 76 12.7. The <nma:instance-identifier> Annotation . . . . . . . . 76 12.8. The@nma:leafref@nma:key Annotation . . . . . . . . . . . . . . . . 76 12.9. The@nma:min-elements@nma:leaf-list Annotation . . . . . . . . . . . . . 76 12.10. The@nma:max-elements@nma:leafref Annotation . . . . . . . . . . . . . . 77 12.11. The @nma:min-elements Annotation . . . . . . . . . . . . 77 12.12. The @nma:max-elements Annotation . . . . . . . . . . . . 77 12.13. The <nma:must> Annotation . . . . . . . . . . . . . . . 7712.12.12.14. The <nma:ordered-by> Annotation . . . . . . . . . . . .77 12.13.78 12.15. The <nma:status> Annotation . . . . . . . . . . . . . .77 12.14.78 12.16. The @nma:unique Annotation . . . . . . . . . . . . . . .77 12.15.78 12.17. The @nma:when Annotation . . . . . . . . . . . . . . . . 78 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 79 14. Security Considerations . . . . . . . . . . . . . . . . . . . 80 15. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 81 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 82 16.1. Normative References . . . . . . . . . . . . . . . . . . 82 16.2. Informative References . . . . . . . . . . . . . . . . . 83 Appendix A.SchemasRELAX NG Schema for NETMOD-Specific Annotations . . 86 Appendix B. Schema-Independent Library . . . .86 A.1. NVDL Schema . .. . . . . . . . . 91 Appendix C. Mapping DHCP Data Model - A Complete Example . . . . 92 C.1. Input YANG Module . . . . . . .86 A.2. Annotation Attributes for define Pattern. . . . . . . .88 A.3. Annotation Elements for element Pattern. . . . 92 C.2. Hybrid Schema . . . .88 A.4. Annotation Attributes for element Pattern. . . . . . .89 A.5. Annotation attributes for group Pattern. . . . . . . .89 A.6. Annotation attributes for choice and ref Patterns. . 94 C.3. Final DSDL Schemas .90 A.7. Annotation attributes for element Pattern in the List Context. . . . . . . . . . . . . . . . . . 99 C.3.1. Main RELAX NG Schema for <nc:get> Reply . . . . . .90 A.8. Annotation attributes for value100 C.3.2. RELAX NG Schema - Global Named Pattern Definitions . . . . . . . .91 A.9. Named Patterns for All NETMOD-Specific Annotations. . .91 Appendix B. Schema-Independent Library. . . . . . . . . 102 C.3.3. Schematron Schema for <nc:get> Reply . . . .95 Appendix C. Mapping DHCP Data Model - A Complete Example. . . 104 C.3.4. DSRL Schema for <nc:get> Reply .96 C.1. Input YANG Module. . . . . . . . . 106 Appendix D. Change Log . . . . . . . . . .96 C.2. Conceptual Tree Schema. . . . . . . . . . .. . . . . . 99 C.2.1. XML Syntax . . . . . . . . . . . . . . . . . . . . 99 C.2.2. Compact Syntax . . . . . . . . . . . . . . . . . . 104 C.3. Final DSDL Schemas . . . . . . . . . . . . . . . . . . . 106 C.3.1. RELAX NG Schema for <get> Reply - XML Syntax . . .107C.3.2. RELAX NG Schema for <get> Reply - Compact Syntax . 111 C.4. Schematron Schema for <get> Reply . . . . . . . . . . . 113 C.5. DSRL Schema for <get> Reply . . . . . . . . . . . . . . 115 Appendix D. Change Log .D.1. Changes Between Versions -05 and -06 . . . . . . . . . . 107 D.2. Changes Between Versions -04 and -05 . . . . . . . . . .116 D.1.107 D.3. Changes Between Versions -04 and -05 . . . . . . . . . .116 D.2.107 D.4. Changes Between Versions -03 and -04 . . . . . . . . . .116 D.3.108 D.5. Changes Between Versions -02 and -03 . . . . . . . . . .117 D.4.109 D.6. Changes Between Versions -01 and -02 . . . . . . . . . .117 D.5.109 D.7. Changes Between Versions -00 and -01 . . . . . . . . . .118110 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . .119111 1. Introduction The NETCONF Working Group has completed a base protocol used for configuration management [RFC4741]. This base specification defines protocol bindings and an XML container syntax for configuration and management operations, but does not include a data modeling language or accompanying rules for how to model configuration andstatusstate information(in XML syntax)carried by NETCONF. The IETF Operations Area has a long tradition of defining data for SNMP Management Information Bases (MIBs) [RFC1157] using the SMI language [RFC2578] to model its data. While this specific modeling approach has a number of well-understood problems, most of the data modeling features provided by SMI are still considered extremely important. Simply modeling the valid syntax without the additional semantic relationships has caused significant interoperability problems in the past. The NETCONF community concluded that a data modeling framework is needed to support ongoing development of IETF and vendor-defined management information modules. The NETMOD Working Group was chartered to address this problem by defining a new human-friendly modeling language based on SMIng [RFC3216] and called YANG [YANG]. Since NETCONF uses XML for encoding itsprotocol data units (PDU),messages, it is natural to express the constraints on NETCONF content using standard XML schema languages. For this purpose, the NETMOD WG selected the Document Schema Definition Languages (DSDL) that is being standardized asISO/IECISO/ IEC 19757 [DSDL]. The DSDL framework comprises a set of XML schema languages that address grammar rules, semantic constraints and other data modelingaspectsaspects, but also, and more importantly, do it in a coordinated and consistent way. While it is true that some DSDL parts have not been standardized yet and are still work in progress, the three parts that the YANG-to-DSDL mapping relies upon - RELAX NG, Schematron and DSRL - already have the status of an ISO/IEC International Standard and are supported in a number of software tools. This document contains a specification of a mapping that translates YANG data models to XML schemas utilizing a subset of the DSDL schema languages. The mapping procedure is divided into two steps: In the first step, the structure of the data tree,RPCsignatures of RPC operations and notifications is expressed as the so-called "hybrid schema" - a single RELAX NGgrammarschema withsimpleannotations representing additional data model information (metadata, documentation, semantic constraints, default values etc.). The second step then generates a coordinated set of DSDL schemas that canvalidatebe used for validating specific XML documents such as client requests, server responses or notifications, perhaps also taking into account additional context such as activecapabilities.capabilities or features. 2. Terminology and NotationThis document relies on many terms that are defined in the specifications of the NETCONF protocol [RFC4741] and YANG data modeling language [YANG]. Also, the common terminology of XML and DSDL schema languages is used as defined in the respective standards [XML], [DSDL], [NVDL], [RNG], [Schematron] and [DSRL].The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].In the text, we use theThe followingtypographic conventions: o YANG statement keywordsterms aredelimited by single quotes.defined in [RFC4741]: oXML element names are delimited by "<" andclient o datastore o message o operation o server The following terms are defined in [YANG]: o augment o base type o built-in type o configuration data o container o data model o data node o data tree o derived type o device deviation o extension o feature o grouping o instance identifier o leaf-list o list o mandatory node o module o RPC o RPC operation o schema node o schema tree o state data o submodule o top-level data node o uses The following terms are defined in [XML-INFOSET]: o attribute o document o document element o document type declaration (DTD) o element o information set o namespace In the text, the following typographic conventions are used: o YANG statement keywords are delimited by single quotes. o XML element names are delimited by "<" and ">" characters. o Names of XML attributes are prefixed by the "@" character. o Other literal values are delimited by double quotes. XML elements names are always written with explicit namespace prefixes corresponding to the following XML vocabularies: "a" DTD compatibility annotations [RNG-DTD]; "dc" Dublin Core metadata elements [RFC5013]; "dsrl" Document Semantics Renaming Language [DSRL]; "en" NETCONF event notifications [RFC5277]; "nc" NETCONF protocol [RFC4741]; "nma" NETMOD-specific schema annotations (see Section 5.3); "nmf" NETMOD-specific XPath extension functions (see Section12.6); "nmt" Conceptual tree (see Section 8.1);12.7); "rng" RELAX NG [RNG]; "sch" ISO Schematron [Schematron]; "xsd" W3C XML Schema [XSD]. The following table shows the mapping of these prefixes to namespace URIs. +--------+-----------------------------------------------------+ | Prefix | Namespace URI | +--------+-----------------------------------------------------+ | a | http://relaxng.org/ns/compatibility/annotations/1.0 | | | | | dc | http://purl.org/dc/terms | | | | | dsrl | http://purl.oclc.org/dsdl/dsrl | | | | | en | urn:ietf:params:xml:ns:netconf:notification:1.0 | | | | | nc | urn:ietf:params:xml:ns:netconf:base:1.0 | | | | | nma | urn:ietf:params:xml:ns:netmod:dsdl-annotations:1 | | | | | nmf | urn:ietf:params:xml:ns:netmod:xpath-extensions:1 | | | | |nmt | urn:ietf:params:xml:ns:netmod:conceptual-tree:1 | | | | |rng | http://relaxng.org/ns/structure/1.0 | | | | | sch | http://purl.oclc.org/dsdl/schematron | | | | | xsd | http://www.w3.org/2001/XMLSchema | +--------+-----------------------------------------------------+ Table 1: Used namespace prefixes and corresponding URIs 2.1. Glossary of New Terms o ancestor datatype: Anydatytypedatatype a given datatype is (transitively) derived from. o ancestor built-in datatype: The built-in datatype that is at the start of the type derivation chain for a given datatype. oconceptual data tree:hybrid schema: Avirtual XML document integrating all components of a YANG data model, i.e., configuration datastore, RPC methods (both requests and replies) and notifications. The conceptual tree is normally not instantiated, it only servesRELAX NG schema with annotations, which embodies the same information asa conceptual target for its schema.the source YANG module(s). See Section 8.1 for details. o implicit node: A node that, if missing, may be added to the information set of an XML document (configuration, RPC input or output, notification) without changing the meaning of that XML document. 3. Objectives and Motivation The main objective of this work is to complement YANG as a data modeling language by validation capabilities of DSDL schema languages, namely RELAX NG, Schematron and DSRL. This document describes the correspondence between grammatical, semantic and data type constraints expressed in YANG and equivalent DSDLconstructs.patterns and rules. The ultimate goal is to be able to capture all substantial information contained in YANG modules and express it in DSDL schemas. While the mapping from YANG to DSDL described in this documentismay in principle be invertible, the inverse mapping from DSDL to YANGis not in its scope.beyond the scope of this document. XML-based information models and XML-encoded data appear in several different forms in various phases of YANG data modeling and NETCONF workflow - configuration datastore contents, RPC requests and replies, and notifications. Moreover, RPCmethodsoperations are characterized by an inherent diversity resulting from selective availability of capabilities and features. YANG modules can also define new RPCmethods.operations. The mapping should be able to accommodate this variability and generate schemas that are specifically tailored to a particular situation and thus considerably more effective for validation than generic all-encompassing schemas. In order to cope with this variability, we assume that the DSDL schemascanwill be generated on demand for a particular purpose from the available collection of YANG modules and their lifetime will be relatively short. In other words, we don't envision that any collection of DSDL schemas will be created and maintained over an extended period of time in parallel to YANG modules. The generated schemas are primarily intended as input totheexisting XML schema validators and other off-the-shelf tools. However, the schemas may also be perused by developers and users as a formal representation of constraints on a particular XML-encoded data object. Consequently, our secondary goal is to keep the schemas as readable as possible. To this end, the complexity of the mapping is distributed into two steps: 1. The first step maps one or more YANG modules to the so-called hybrid schema, which is a single RELAX NG schemaof the so-called "conceptual tree", which containsthat describes grammatical constraints for the main data tree as well asRPCsfor RPC operations and notifications.In order to record additionalSemantic constraintsthat appearand other information appearing in the input YANG modulesbut cannot be expressedis recorded inRELAX NG,the hybrid schemais augmented by simplein the form of foreign namespace annotations. The output of the first step can thus be considered areasonably readablevirtually complete equivalent of the input YANG modules. 2. In the second step, theannotated RELAX NGhybrid schema from step 1 is transformed further to a coordinated set of fully conformant DSDL schemas containing constraints for a particular data object and a specific situation. The DSDL schemas are intended mainly for machine validation using off-the-shelf tools. 4. DSDL Schema Languages Document Schema Definition Languages (DSDL) is a framework of schema languages that is being developed asan international standardthe International Standard ISO/ IEC 19757. Unlike other approaches to XML document validation, most notably W3C XML Schema (XSD) [XSD], the DSDL framework adheres to the principle of "small languages": Each of the DSDL constituents is a stand-alone schema language with a relatively narrow purpose and focus. Together, these schema languages may be used in a coordinated way to accomplish various validation tasks. The mapping described in this document uses three of the DSDL schema languages, namely RELAX NG, Schematron and DSRL. 4.1. RELAX NG RELAX NG (pronounced "relaxing") is an XML schema language for grammar-based validation and Part 2 of the ISO/IEC DSDL family of standards [RNG]. Like the W3C XML Schema language [XSD], it is able to describe constraints on the structure andcontentcontents of XML documents. However, unlike the DTD [XML] and XSD schema languages, RELAX NG intentionally avoids any infoset augmentation such as defining default values. In the DSDL architecture, the particular task of defining and applying default values is delegated to another schema language, DSRL (see Section 4.3). As its base datatype library, RELAX NG uses the W3C XML Schema Datatype Library [XSD-D], but unlike XSD, other datatype libraries may be used along with it or even replace it if necessary. RELAX NG is very liberal in accepting annotations from other namespaces. With a few exceptions, such annotations may be placed anywhere in the schema and need no encapsulating elements such as <xsd:annotation> in XSD. RELAX NG schemas can be represented in two equivalent syntaxes: XML and compact. The compact syntax is described in Annex C of the RELAX NG specification [RNG-CS], which was added to the standard in 2006 (Amendment 1). Automatic bidirectional conversions between the two syntaxes can be accomplished using several tools, for example Trang [1]. For its terseness and readability, the compact syntax is often the preferred form for publishing RELAX NG schemas whereas validators and other software tools usually work with the XML syntax. However, the compact syntax has two drawbacks: o External annotations make the compact syntax schema considerably less readable. While in the XML syntax the annotating elements and attributes are represented in a simple and uniform way (XML elements and attributes from foreign namespaces), the compact syntax uses as many as four different syntactic constructs: documentation, grammar, initial and following annotations. Therefore, the impact of annotations on readability is often much stronger for the compact syntax than it is for the XML syntax. o In a computer program, it is more difficult to generate the compact syntax than the XML syntax. While a number of software libraries exist that make it easy to create an XML tree in the memory and then serialize it, no such aid is available for the compact syntax. For these reasons, the mapping specification in this document uses exclusively the XML syntax. Where appropriate, though, the schemas resulting from the translationmayMAY be presented in the equivalent compact syntax. RELAX NG elements are qualified with the namespace URI "http://relaxng.org/ns/structure/1.0". The namespace of the W3C Schema Datatype Library is "http://www.w3.org/2001/XMLSchema-datatypes". 4.2. Schematron Schematron is Part 3 of DSDL that reached the status of a full ISO/ IEC standard in 2006 [Schematron]. In contrast to the traditional schema languages such as DTD, XSD or RELAX NG, which are based on the concept of a formal grammar, Schematron utilizes a rule-based approach. Its rules may specify arbitrary conditions involving data from different parts of an XML document. Each rule consists of three essential components: o context - an XPath expression that defines the set of locations where the rule is to be applied; o assert or report condition - another XPath expression that is evaluated relative to the location matched by the context expression; o human-readable message that is displayed when the assert condition is false or report condition is true. The difference between the assert and report condition is that the former is positive in that it states a condition that a valid document has to satisfy, whereas the latter specifies an error condition. Schematron draws most of its expressive power from XPath [XPath] and XSLT [XSLT]. ISO Schematron allows for dynamic query language binding so that the following XML query languages can be used: STX, XSLT 1.0, XSLT 1.1, EXSLT, XSLT 2.0, XPath 1.0, XPath 2.0 and XQuery 1.0 (this list may be extended in the future).The human-readableHuman-readable error messages are another feature thatdistinguishessets Schematron apart from other common schema languages. The messages may even contain XPath expressions that are evaluated in the actual context and thus refer toexistinginformation items in the XML documentnodes and their contents. The rules defined by abeing validated. Another feature of Schematronschema may be divided into several subsets knownthat is used by the mapping are abstract patterns. These work essentially asphases. Validationsmacros and maythen be set up to include only selected phases. Inalso contain parameters which are supplied when thecontext of NETCONF data validation, thisabstract pattern isuseful for relaxing constraints that may not always apply. For example, the reference integrity may not be enforced for a candidate configuration.used. Schematron elements are qualified with namespace URI "http://purl.oclc.org/dsdl/schematron". 4.3. Document Semantics Renaming Language (DSRL) DSRL (pronounced "disrule") is Part 8 of DSDL that reached the status of a full ISO/IEC standard in 2008 [DSRL]. Unlike RELAX NG and Schematron,itDSRL isspecifically designedallowed to modify XML information set of the validated document. While DSRL is primarily intended for renaming XML elements and attributes, it can also define default values for XML attributes and defaultcontentcontents for XML elements or subtrees so thatelements or attributes with thesethe defaultvaluescontents are inserted if they are missing(or present and empty)in the validated documents. The latter feature is used by the YANG-to-DSDL mapping for representing YANG default contents consisting of leaf nodes with default values and their ancestor non-presence containers. DSRL elements are qualified with namespace URI "http://purl.oclc.org/dsdl/dsrl". 5. Additional Annotations Besides the DSDL schema languages, the mapping also uses three sets of annotations that are added as foreign-namespace attributes and elements to RELAX NG schemas. Two of the annotation sets - Dublin Core elements and DTD compatibility annotations - are standard vocabularies for representing metadata and documentation, respectively. Although these data model items are not used for formal validation, they quite often carry important information for data model implementers. Therefore, they SHOULD be included in theconceptual treehybrid schema and MAY also appear in the final validation schemas. The third set are NETMOD-specificannotations conveying YANGannotations. They are specifically designed for the hybrid schema and convey semantic constraints and other information that cannot be expressed directly in RELAX NG.These annotations are only used in the first step of the mapping, i.e., in the conceptual tree schema.In the second mapping step, these annotations are converted to Schematron and DSRL rules. 5.1. Dublin Core Metadata Elements Dublin Core [2] is a system of metadata elements that was originally created for describing metadata of World Wide Web resources in order to facilitate their automated lookup. Later it was accepted as a standard for describing metadata of arbitrary resources. This specification uses the definition from [RFC5013]. Dublin Core elements are qualified with namespace URI "http://purl.org/dc/terms". 5.2. RELAX NG DTD Compatibility Annotations DTD compatibility annotations are a part of the RELAX NG DTD Compatibility specification [RNG-DTD]. YANG-to-DSDL mapping uses only the <a:documentation> annotation for representing YANG 'description' and 'reference' texts. Note that there is no intention to make the resulting schemas DTD- compatible, the main reason for using these annotations is technical: they are well supported and adequatelyinterpretedformatted by several RELAX NG tools. DTD compatibility annotations are qualified with namespace URI "http://relaxng.org/ns/compatibility/annotations/1.0". 5.3. NETMOD-Specific Annotations NETMOD-specific annotations are XML elements and attributes qualified with the namespace URI "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1"thatwhich appear in various locations of theconceptual treehybrid schema. YANG statements are mapped to these annotations in a straightforward way. In most cases, the annotation attributes and elements have the same name as the corresponding YANG statement. Table 2 lists alphabetically the names of NETMOD-specific annotation attributes (prefixed with "@") and elements (in angle brackets) along with a reference to the section where their use is described. Appendix A containsthe formal specification ofa RELAX NG schema for this annotation vocabulary. +---------------------------+--------------------+------+ | annotation | section | note | +---------------------------+--------------------+------+ | @nma:config |11.910.9 | | | | | | |@nma:default<nma:data> |11.12Section 8.1 | 4 | | | | | |@nma:implicit@nma:default |11.11, 11.7, 11.1210.12 | | | | | | | <nma:error-app-tag> |11.1610.16 | 1 | | | | | | <nma:error-message> |11.1710.17 | 1 | | | | | | @nma:if-feature | 10.22 | | | | | | | @nma:implicit | 10.11, 10.7, 10.12 | | | | | | | <nma:input> | Section 8.1 | 4 | | | | | | <nma:instance-identifier> |11.53.610.53.6 | 2 | | | | | | @nma:key |11.2610.26 | | | | | | | @nma:leaf-list | 10.28 | | | | | | | @nma:leafref |11.53.710.53.7 | | | | | | |@nma:min-elements@nma:mandatory |11.2810.8 | | | | | | | @nma:max-elements |11.2810.28 | | | | | | | @nma:min-elements | 10.28 | | | | | | | @nma:module | 10.34 | | | | | | | <nma:must> |11.3510.35 | 3 | | | | | |@nma:ordered-by<nma:notification> |11.38Section 8.1 | 4 | | | | | |@nma:presence<nma:notifications> |11.45Section 8.1 | 4 | | | | | |@nma:status@nma:ordered-by |11.5110.38 | | | | | | |@nma:unique<nma:output> |11.55Section 8.1 | 4 | | | | | |@nma:units<nma:rpc> |11.56Section 8.1 | 4 | | | | | |@nma:when<nma:rpcs> |11.59Section 8.1 | 4 |+---------------------------+--------------------+------+ Table 2: NETMOD-specific annotations Notes: 1. Appears only as| | | | | @nma:status | 10.51 | | | | | | | @nma:unique | 10.55 | | | | | | | @nma:units | 10.56 | | | | | | | @nma:when | 10.59 | | +---------------------------+--------------------+------+ Table 2: NETMOD-specific annotations Notes: 1. Appears only as a subelement of <nma:must>. 2. Has an optional attribute @require-instance. 3. Has a mandatory attribute @assert and two optional subelements <nma:error-app-tag> and <nma:error-message>. 4. Marker element in the hybrid schema. 6. Overview of the Mapping This section gives an overview of the YANG-to-DSDL mapping, its inputs and outputs. Figure 1 presents an overall structure of the mapping: +----------------+ | YANG module(s) | +----------------+ | |T |+-------------------------------------++------------------------------------+ |RELAX NGhybrid schemafor conceptual tree|+-------------------------------------++------------------------------------+ / | | \ / | | \+-------+Tg/ Tr| |Tn \|library|/ | | \+-------++---------+ +-----+ +-------+ +------+ |get reply| | rpc | | notif | | .... | +---------+ +-----+ +-------+ +------+ Figure 1: Structure of the mapping The mapping procedure is divided into two steps: 1. Transformation T in the first step maps one or more YANG modules toa single RELAX NG schema fortheconceptual treehybrid schema (see Section 8.1). Constraints that cannot be expressed directly in RELAX NG (list key definitions, 'must' statements etc.) and various documentation texts are recorded in the schema as foreign-namespace annotations. 2. In the second step, theconceptual treehybrid schemaismay be transformed in multiple ways to a coordinated set of DSDL schemas that can be used for validating a particular data object in a specific context. Figure 1 showsjustthree simple possibilities as examples. In the process, appropriate parts of theconceptual treehybrid schema are extracted and specific annotations transformed to equivalent, but usually more complex, Schematron patterns, DSRL element maps etc.3. As indicated in Figure 1, the second step of the mapping also uses a schema-independent library that contains common schema objects such as RELAX NG named pattern definitions.An implementation of the mapping algorithmis supposed toMUST accept one or more valid YANG modules as its input. It is important to be able to process multiple YANG modules together since multiple modules may be negotiated for a NETCONF session and the contents of the configuration datastore is then obtained as the union of data trees specified by the individual modules, which may also lead to multipleroots.root nodes of the datastore hierarchy. In addition, the input modules may be further coupled by the 'augment' statement in which one module augments the data tree of another module. It is also assumed that the algorithm has access, perhaps on demand, to all YANG modules that the input modules import(perhaps(directly or transitively).The output of the first mapping step is an annotated RELAX NG schema for the conceptual tree - a virtual XML document containing, in its different subtrees, the entire datastore, all RPC requests and replies, and notifications as defined by the input YANG modules. By "virtual" we mean that such an XML document need not correspond to the actual layout of the configuration database in a NETCONF server, and will certainly never appear on the wire as the content of a NETCONF PDU. Hence, the RELAX NG schema for the conceptual tree is not intended for any direct validations but rather as a representation of a particular data model expressed in annotated RELAX NG and the common starting point for subsequent transformations that may produce practical validation schemas. The conceptual tree is further described in Section 8.1.Other information contained in input YANG modules, such as semantic constraintsorand default values, are recorded in theconceptual treehybrid schema as annotations - XML attributes or elements qualified with namespace URI "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1". Metadata describing the YANG modules are mapped toannotations utilizingDublin Core annotations elements (Section 5.1). Finally, documentation strings are mapped to <a:documentation> elements belonging to the DTD compatibility vocabulary (Section 5.2). The outputfromof the second step is a coordinated set of three DSDL schemas corresponding to a specific data object and context: o RELAX NG schema describing the grammatical and datatype constraints; o Schematron schema expressing other constraints such as uniqueness of list keys or user-specified semantic rules; o DSRL schema containing the specification of default contents. 7. NETCONF Content Validation This section describes how the schemas generated by the YANG-to-DSDL mapping are supposed to be applied for validating XML instance documents such as thecontentcontents of a datastore or various NETCONFPDUs.messages. The validation proceeds in the following steps, which are also illustrated in Figure 2: 1. The XML instance documentcan be immediatelyis checked for grammatical and data type validity using the RELAX NG schema. 2.Second, defaultDefault values for leaf nodes have to be applied and their ancestor containers added where necessary. It is important to add the implicit nodes before the next validation step because YANG specification [YANG]statesrequires that the data tree against which XPath expressions are evaluated already has all defaults filled-in. Note that this step modifies the information set of the validated XML document. 3. The semantic constraints are checked using the Schematron schema. +----------+ +----------+ | | | XML | | XML | | document | | document |-----------o----------->| with | | | ^ | defaults | | | | | | +----------+ | +----------+ ^ |filling-infilling in ^ | grammar, | defaults | semantic | datatypes | | constraints | | | +----------+ +--------+ +------------+ | RELAX NG | | DSRL | | Schematron | | schema | | schema | | schema | +----------+ +--------+ +------------+ Figure 2: Outline of the validation procedure 8. Design Considerations YANGmodulesdata models could in principle be mapped to the DSDL schemas in a number of ways. The mapping procedure described in this document uses several specific design decisions that are discussed in the following subsections. 8.1.Conceptual Data Tree DSDL schemas generated from YANG modules using the procedure describedHybrid Schema As was explained inthisSection 6, the first step of the mapping produces an intermediate documentare intended to be used- the hybrid schema, which specifies all constraints forvalidating XML-encoded NETCONFthe entire datain various forms: every YANG-basedmodelrepresents the contents ofin adatastore but also implies an arraysingle RELAX NG schema. Every input YANG module corresponds to exactly one embedded grammar in the hybrid schema. This separation ofschemasinput YANG modules allows each embedded grammar to include named pattern definitions into its own namespace, which is important forall types of NETCONF PDUs. For a reasonably strict validation of a given data object, the schemas havemapping YANG groupings (see Section 9.2 for additional details). In addition to grammatical and datatype constraints, YANG modules provide other important information that cannot bequite specific. To begin with, effective validation of NETCONF PDU content requires separation of clientexpressed in a RELAX NG schema: semantic constraints, default values, metadata, documentation andserver schemas. Whileso on. Such information items are represented in thedecision about proper structuring of all PDU-validating schemas is beyondhybrid schema as XML attributes and elements belonging to thescope of this document,namespace with themapping procedure is designed to accommodate any foreseeable validation needs. An essential partfollowing URI: "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1". A complete list ofthe YANG-to-DSDL mapping procedurethese annotations isnonetheless common to all validation needs:given in Section 5.3, detailed rules about their use are then contained in thegrammar and datatype specificationsfollowing sections. YANG modules define data models not only forthe datastore, RPCsconfiguration and state data but also for (multiple) RPC operations [RFC4741] and/or event notificationsexpressed by one or more YANG modules have to be translated to RELAX NG.[RFC5277]. In order to be able toseparate this common step, we introduce the notioncapture all three types ofconceptualdatatree: it is a virtual XML treemodels in one schema document, the hybrid schema uses special markers thatcontains full datastore,enclose sub-schemas for configuration and state data, individual RPCrequests with corresponding repliesoperations (both input and output part) and individual notifications. Theschema for the conceptual tree - a single RELAX NG schema with annotations - therefore has a quite similar logic asmarkers are theinput YANG module(s),following XML elements in theonly major difference beingnamespace of NETMOD-specific annotations (URI urn:ietf:params:xml:ns:netmod:dsdl-annotations:1): +-------------------+---------------------------------------+ | Element name | Role | +-------------------+---------------------------------------+ | nma:data | encloses configuration and state data | | | | | nma:rpcs | encloses all RPC operations | | | | | nma:rpc | encloses an individual RPC operation | | | | | nma:input | encloses an RPC request | | | | | nma:output | encloses an RPC reply | | | | | nma:notifications | encloses all notifications | | | | | nma:notification | encloses an individual notification | +-------------------+---------------------------------------+ Table 3: Marker elements in theRELAX NGhybrid schemalanguage.For example,the conceptual data tree forconsider a data model formed by two YANGmodule definingmodules "example-a" and "example-b" that define nodes in thenamespace "http://example.com/ns/example" maynamespaces "http://example.com/ns/example-a" and "http://example.com/ns/example-b". Module "example-a" defines configuration/state data, RPC methods and notifications, whereas "example-b" defines only configuration/state data. The hybrid schema can then be schematically represented as follows:<nmt:netmod-tree xmlns:nmt="urn:ietf:params:xml:ns:netmod:conceptual-tree:1" xmlns:ex="http://example.com/ns/example"> <nmt:top> ... configuration<grammar xmlns="http://relaxng.org/ns/structure/1.0" xmlns:nma="urn:ietf:params:xml:ns:netmod:dsdl-annotations:1" xmlns:exa="http://example.com/ns/example-a" xmlns:exb="http://example.com/ns/example-b" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"> <start> <grammar nma:module="example-a" ns="http://example.com/ns/example-a"> <start> <nma:data> ...configuration andstatusstate data defined in "example-a"... </nma:data> <nma:rpcs> <nma:rpc> <nma:input> <element name="exa:myrpc"> ...</nmt:top> <nmt:rpc-methods> <nmt:rpc-method> <nmt:input> <ex:myrpc ...> ... </myrpc> </nmt:input> <nmt:output></element> </nma:input> <nma:output> ...</nmt:output> </nmt:rpc-method></nma:output> </nma:rpc> ...</nmt:rpc-methods> <nmt:notifications> <nmt:notification> <ex:mynotif></nma:rpcs> <nma:notifications> <nma:notification> <element name="exa:mynotif"> ...</mynotif> </nmt:notification></element> </nma:notification> ...</nmt:notifications> </nmt:netmod> The namespace URI "urn:ietf:params:xml:ns:netmod:conceptual-tree:1" identifies a simple vocabulary consisting of a few elements that encapsulate</nma:notifications> </start> </grammar> <grammar nma:module="example-b" ns="http://example.com/ns/example-a"> <start> <nma:data> ...configuration andseparate the various parts of the conceptualstate datatree. The conceptual treedefined in "example-b"... </nma:data> <nma:rpcs/> <nma:notifications/> </start> </grammar> </start> </grammar> A complete hybrid schemais not intendedfordirect validation but rather serves asthe data model of awell-defined starting point for subsequent transformations that generate validation schemas. In general, these transformations should be relatively simple - they will typically extract one or more subtrees from the conceptual tree schema, modify them as necessary and add encapsulating elements such as those from the NETCONF RPC layer. Additional information contained in the source YANG module(s), such as semantic constraints and default values,DHCP server isrepresented in the form of interim NETMOD-specific annotations that are included as foreign-namespace elements or attributes in the RELAX NG schema for the conceptual tree. In the second phase of the mapping, these annotations are typically translated to equivalent Schematron and DSRL rules. As a useful side effect, by introducing the conceptual data tree we are also able to resolve the difficulties arising from the fact that a single datastore may consist of multiple parallel data hierarchies definedgiven inone or more YANG modules, which cannot be mapped to a valid XML document. In the conceptual data tree, such multiple hierarchies appear under the single <nmt:top> element.Appendix C.2. 8.2. Modularity Both YANG and RELAX NG offer means for modularity, i.e., for splitting the contents of a full schema into separate modules and combining or reusing them in various ways. However, the approaches taken by YANG and RELAX NG differ. Modularity in RELAX NG is suitable for ad hoc combinations of a small number of schemas whereas YANG assumes a large set of modules similar to SNMP MIBs. The following differences are important: o In YANG, whenever module A imports module B, it gets access to the definitions (groupings and typedefs) appearing at the top level of module B. However, no part of data tree from module B is imported along with it. In contrast, the <rng:include> pattern in RELAX NG imports both definitions of named patterns and the entire schema tree from the included schema. o The names of imported YANG groupings and typedefs are qualified with the namespace of the imported module. On the other hand, the names of data nodes contained inside the imported groupings, when used within the importing module, become part of the importing module's namespace. In RELAX NG, the names of patterns are unqualified and so named patterns defined in both the importing and imported module share the same flat namespace. The contents of RELAX NG named patterns may either keep the namespace of the schema where they are defined or inherit the namespace of the importing module, analogically to YANG. However, in order to achieve the latter behavior, theimported moduledefinitions of named patterns must be included from an external schema which has to be prepared in a special way (see [Vli04], Chapter 11). In order to map, asa library module that cannot be usedmuch asa stand-alone schema. So the conclusion is thatpossible, the modularitymechanismsof YANGandto RELAX NG,albeit similar, are not directly compatible. Therefore, the corresponding design decision fora validating RELAX NG schema (the result of the second mappingalgorithm isstep) has tocollectbe split into two files, one of them containing allinformation in a single schema for the conceptual tree, even if it comesglobal definitions that are mapped frommultipletop-level YANGmodules or submodules. In other words, translations of importedgroupingsand typedefs are installedappearing in all input YANG module. This RELAX NG schema MUST NOT define any namespace via thetranslation of importing module - but only if they are really used there. NOTE:@ns attribute. The'include' statement thatother RELAX NG schema file then defines actual data trees mapped from input YANG modules, each of them enclosed in an own embedded grammar. Those embedded grammars in which at least one of the global definitions is usedinMUST include the first schema with definitions and also MUST define the local namespace using the @ns attribute. This way, the global definitions can be used inside different embedded grammar, each time accepting a different local namespace. Named pattern definition that are mapped from non-top-level YANGfor including submodules hasgroupings MUST be placed inside the embedded grammar corresponding to the YANG module where the grouping is defined. In the hybrid schema, we need to distinguish the global and non- global named pattern definitions while still keeping the hybrid schema in one file. This is accomplished infactthesame semanticsfollowing way: o Every global definition MUST be placed as a child of the<rng:include> pattern. However, since we don't mapthemodular structure forouter <rng:grammar> element (the document root of the hybrid schema). o Every non-global definitions MUST be placed as a child of the corresponding embedded <rng:grammar> element. YANGmodules, it seems to have little sense to do italso allows for splitting a module into a number of submodules.Consequently,However, as submodules have no impact on the scope of identifiers and namespaces, the modularity based on submodules is not mapped in any way. The contents of submodulesappearis therefore handled as if the submodule text appeared directly in theconceptual tree schema, too.main module. 8.3. Granularity RELAX NG supports different styles of schema structuring: One extreme, often called "Russian Doll", specifies the structure of an XML instance document in a single hierarchy. The other extreme, the flat style, uses a similar approach as the Data Type Definition (DTD) schema language - every XML element corresponds to a named pattern definition. In practice, some compromise between the two extremes is usually chosen. YANG supports both styles in principle, too, but in most cases the modules are organized in a waythat'scloser to the "Russian Doll" style, which provides a better insight into the structure of the configuration data. Groupings are usually defined only for contents that are prepared for reuse in multiple places via the 'uses' statement. In contrast, RELAX NG schemas tend to be much flatter, because finer granularity is also needed in RELAX NG for extensibility of the schemas - it is only possible to replace or modify schema fragments that are factored out as named patterns. For YANG this is not an issue since its 'augment' and 'refine' statements can delve, by using path expressions, into arbitrary depths of existing structures. In general, it not feasible to mapYANGYANG's powerful extension mechanisms to thoseofavailable in RELAX NG. For this reason, the mapping essentially keeps the granularity of the original YANG data model: YANG groupings and definitions of derived types usually have direct counterparts in definitions of named patterns in the resulting RELAX NGschema usually have direct counterparts in YANG groupings and definitions of derived types.schema. 8.4. Handling of XML Namespaces Most modern XML schemalanguageslanguages, including RELAX NG, Schematron andDSRLDSRL, support schemas for so-called compound XMLdocuments,documents which contain elements from multiple namespaces. This is useful for our purpose since the YANG-to-DSDL mapping allows for multiple input YANGmodules thatmodules, which naturally leads to compound document schemas. RELAX NG offers two alternatives for defining the target namespaces in the schema: 1. First possibility is the traditional XML way via the @xmlns:xxx attribute. 2. One of the target namespace URIs may be declared using the @ns attribute. In bothcases, thesethe hybrid schema and validation RELAX NG schemas generated in the second step, the namespaces MUST be declared as follows: 1. The root <rng:grammar> MUST have @xmlns:xxx attributes declaring prefixes of all namespaces that aretypically attached toused in the<rng: grammar> element but may also appear elsewhere.data model. Thedesign decision for the mapping isprefixes SHOULD be identical touse exclusively the alternative 1, sincethose defined inthis case all YANG modules are represented symmetrically, which makes further processing oftheconceptual tree schema considerably easier. Moreover, this way'prefix' statements. An implementation of thenamespace prefixes declaredmapping MUST resolve all collisions in the prefixes defined by different inputmodulesmodules, if there arerecorded in the resulting schema - the prefix forany. 2. Each embedded <rng:grammar> element must declare the namespacedeclaredof the corresponding module using the @nswould be lost.attribute. This way, the names of nodes defined by global named patterns are able to adopt the local namespace of each embedded grammar, as explained in Section 8.2. This setup is illustrated by the example at the end of Section 8.1. DSRL schemascanmay declare any number of target namespaces via the standard XML attributes xmlns:xxx. In contrast, Schematron requires alltargetused namespaces to be defined in the <sch:ns> subelements of theroot <sch:schema> element. 8.5. Features and Deviations YANG provides statements that allow for marking parts of the schema as conditional ('feature' and 'if-feature' statements) or declaring deviations from a data model ('deviation' statement). These statements are not handled by the YANG-to-DSDL mapping. Instead, it is assumed that all features and deviations are specified beforehand and the corresponding changes in the input YANG modules are already applied.document element <sch:schema>. 9. Mapping YANG Data Models to theConceptual TreeHybrid Schema This section explains the main principlesunderlyinggoverning the first step of the mapping. Its result isan annotated RELAX NG schema oftheconceptual tree,hybrid schema which is described in Section 8.1.As a special case, if the input YANG modules contain no data nodes (this is typical, e.g., for datatype library modules), an implementation MAY entirely remove the schema of the (empty) conceptual tree - the <rng:start> element with all its contents. The output RELAX NG schema will then contain only named pattern definitions translated from YANG groupings and typedefs. DetailedA detailed specification of the mapping of individual YANG statements is contained in the following Section11.10. 9.1. Occurrence Rules for Data Nodes In DSDL schema languages, occurrence constraints for a node are always localized together with that node. In a RELAX NG schema, for example, <rng:optional> pattern appears as the parent element of the pattern defining a leaf or non-leaf element. Similarly, DSRL specifies defaultcontentcontents separately for every single node, be it a leaf or non-leaf element. For leaf nodes in YANG modules, the occurrence constraints are also easily inferred from the substatements of 'leaf'.In contrast,On the other hand, for a YANG container it is often necessary to examine its entire subtree in order to determine the container's occurrence constraints. Therefore, one of the goals of the first mapping step is to infer the occurrence constraints for allcontainersdata nodes and mark accordingly the corresponding <rng:element> patterns in theconceptual treehybrid schema so that any transformation procedure in the second mapping step can simply use this information and need not examine the subtree again. First, it has to be decided whether a givencontainer elementdata node must always be present in a valid configuration. If so, such acontainer elementnode is called mandatory, otherwise it is called optional. This constraint is closely related to the notion of mandatory nodes in Section 3.1 in [YANG]. The only difference is thatwethis document alsoconsiderconsiders list keys to be mandatory. The other occurrence constraint has to do with the semantics of the 'default' statement and the possibility of removing empty non- presence containers. As a result, the information set of a valid configuration may be modified by adding or removing certain leaf or container elements without changing the meaning of the configuration. In this document, such elements are called implicit. In the hybrid schema, they can be identified as RELAX NG patterns having either @nma:default or @nma:implicit attribute. Note that both occurrence constraints apply to containers at the top level of the data tree, and then also to other containers under the additional condition that their parent node exists in the instance document. For example, consider the following YANG fragment: container outer { presence 'Presence of "outer" means something.'; container c1 { leaf foo { type uint8; default 1; } } container c2 { leaf-list bar { type uint8; min-elements 0; } } container c3 { leaf baz { type uint8; mandatory true; } } } Here, container "outer" has the 'presence' substatement, which means that it is optional and not implicit. If "outer" is not present in a configuration, its child containers are not present as well. However, if "outer" does exist, it makes sense to ask which of its child containers are optional and which are implicit. In this case, "c1" is optional and implicit, "c2" is optional but not implicit and "c3" is mandatory (and therefore not implicit). The following subsections give precise rules for determining whether a container is optional or mandatory and whether it is implicit. In order to simplify the recursive definition of these occurrence characteristics, it is useful to define them also for other types ofdataYANG schema nodes, i.e., leaf, list, leaf-list andanyxml.anyxml and choice. 9.1.1. Optional and Mandatory Nodes The decision whether a given node is mandatory or optional is governed by the following rules: o Leaf, anyxml and choice nodes are mandatory if they contain the substatement "mandatory true;". For a choice node this means that at least one node from exactly one case branch must exist. o In addition, a leafnodes arenode is mandatory ifthey areit is declared as a listkeys.key. oListA list or leaf-listnodes arenode is mandatory ifthey containit contains the 'min- elements' substatement with an argument value greater than zero. o A container node is mandatory if its definition does not contain the 'presence' substatement and at least one of its child nodes is mandatory. A node is optional if and only if it is not mandatory. In RELAX NG, definitions of nodes that are optional must be explicitly wrapped in the <rng:optional> element. The mapping MUST use the above rules to determine whether a YANG node is optional and if so, insert the <rng:optional> element in theconceptual treehybrid schema. However, alternatives in <rng:choice>are neverMUST NOT be defined as optional in theconceptual treehybrid schema.Therefore, 'anyxml', 'container', 'leaf', 'list' and 'leaf-list' statements appearing as children of 'choice' (so-called shorthand cases) are always mapped to mandatory RELAX NG patterns.If a choice in YANG is not mandatory, <rng: optional>isMUST be used to wrap the entire <rng:choice> pattern. 9.1.2. Implicit Nodes The following rules are used to determine whether a given node is implicit: o List, leaf-list and anyxml nodes are never implicit. o A leaf node is implicit if and only if it has aspecifieddefaultvalue (eithervalue, defined either directly or via itsdatatype).datatype. o A container node is implicit if and only if it does not have the 'presence' substatement, none of its childrenisare mandatory and at least one child is implicit. In theconceptual treehybrid schema, all implicit containers, as well as leafs that obtain their default value from a typedef and don't have the@nma:default@nma: default attribute, MUST be marked with @nma:implicit attribute having the value of "true". Note that Section 7.9.3 in [YANG] specifies other rules that must be taken into account when deciding whether a given container or leaf appearing inside a case of a choice is ultimately implicit or not. Specifically, a leaf or container under a case can be implicit only if the case appears in the argument of the choice's 'default' statement. However, this is not sufficient by itself but also depends on the particular instance XML document, namely on the presence or absence of nodes from other (non-default) cases. The details are explained in Section10.4.11.3. 9.2. Mapping YANG Groupings and Typedefs YANG groupings and typedefs are generally mapped to RELAX NG named patterns. There are, however, several caveats that the mapping has to take into account. First of all, YANG typedefs and groupings may appear at all levels of the module hierarchy and are subject to lexical scoping, see Section 5.5 in [YANG]. Second, top-level symbols from external modulesaremay be imported as qualified names represented using the external module namespace prefix and the name of the symbol. In contrast, named patterns in RELAX NG (both local and imported via the <rng:include> pattern) share the same namespace and within a grammar they are always global - their definitions may only appear at the top level as children of the <rng:grammar> element. Consequently, whenever YANG groupings and typedefs are mapped to RELAX NG named pattern definitions, their names MUST be disambiguated in order to avoid naming conflicts. The mapping uses the following procedure for mangling the names of groupings and type definitions: o Names of groupings and typedefs appearing at the top level of the YANG module hierarchy are prefixed with the module name and two underscore characters ("__"). o Names of other groupings and typedefs, i.e., those that do not appear at the top level of a YANG module, are prefixed with the module name, double underscore, and then the names of all ancestor data nodes separated by double underscore. oSinceFinally, since the names of groupings and typedefs in YANG have different namespaces, an additionalunderlineunderscore character is added to the beginning of the mangled names of all groupings. An additional complication is caused by the YANG rules for subelement ordering (see, e.g., Section 7.5.7 in [YANG]): In RPC input and output parameters, subelements must follow the order specified in the data model, otherwise the order is arbitrary. Consequently, if a grouping is used both in RPC input/output parameters and elsewhere, it MUST be mapped to two different named pattern definitions - one with fixed order and the other with arbitrary order. To distinguish them, the "__rpc" suffix MUST be appended to the version with fixed order. EXAMPLE. Consider the following YANG module which imports the standard module "ietf-inet-types" [Ytypes]: module example1 { namespace "http://example.com/ns/example1"; prefix ex1;import "ietf-inet-types" { prefix "inet"; }typedef vowels { type string { pattern "[aeiouy]*"; } } grouping "grp1" { leaf "void" { type "empty"; } } container "cont" {grouping "grp2" {leaf"address"foo { type"inet:ip-address"; } } leaf foo { type vowels;vowels; } uses "grp1";uses "grp2";} } Theresulting RELAX NGhybrid schema generated by the first mapping step will then contain the following two (global) named patterndefinitions (long regular expression patterns for IPv4 and IPv6 addresses are not shown):definitions: <rng:define name="example1__vowels"> <rng:data type="string"> <rng:paramname="pattern">[aeiouy]*</param>name="pattern">[aeiouy]*</rng:param> </rng:data> </rng:define> <rng:define name="_example1__grp1"> <rng:optional> <rng:elementname="ex1:void">name="void"> <rng:empty/> </rng:element> </rng:optional> </rng:define><rng:define name="_example1__cont__grp2"> <rng:optional> <rng:element name="ex1:address"> <rng:ref name="ietf-inet-types__ip-address"/> </rng:element> </rng:optional> </rng:define> <rng:define name="ietf-inet-types__ip-address"> <rng:choice> <rng:ref name="ietf-inet-types__ipv4-address"/> <rng:ref name="ietf-inet-types__ipv6-address"/> </rng:choice> </rng:define> <rng:define name="ietf-inet-types__ipv4-address"> <rng:data type="string"> <rng:param name="pattern">... regex pattern ...</param> </rng:data> </rng:define> <rng:define name="ietf-inet-types__ipv6-address"> <rng:data type="string"> <rng:param name="pattern">... regex pattern ...</param> </rng:data> </rng:define> Note that type definitions from the "ietf-inet-types" module are mapped directly to the conceptual tree schema.9.2.1. YANG Refinements and Augments YANG groupings represent a similar concept as named pattern definitions in RELAX NG and both languages also offer mechanisms for their subsequent modification. However, in RELAX NG the definitions themselves are modified whereas YANGallows for modifying expansions of groupings. Specifically, YANGprovides twostatements for this purpose that may appear assubstatements of'uses':'uses' which modify expansions of groupings: o 'refine' statement allows for changing parameters of a schema node inside the grouping referenced by the parent 'uses' statement; o 'augment' statement can be used for adding new schema nodes to the groupingcontent.contents. Both 'refine' and 'augment' statements are quite powerful in that they can address, using XPath-like expressions as their arguments, schema nodes that are arbitrarily deep inside the groupingcontent.contents. In contrast, modifications of named pattern definitions in RELAX NG are applied exclusively at the topmost level of the named patterncontent.contents. In order to achieve a modifiability of named patterns comparable to YANG,thea RELAX NG schema would have to be extremely flat (cf. Section 8.3) and very difficult to read. Since the goal of the mapping described in this document is to generate ad hoc DSDL schemas, we decided to avoid these complications and instead expand the grouping and refine and/or augment it "in place". In other words, every 'uses' statement which has 'refine' and/or 'augment' substatements is replaced by thecontentcontents of the corresponding grouping, the changes specified in the 'refine' and 'augment' statements are applied and the resulting YANG schema fragment is mapped as if the 'uses'/'grouping' indirection wasn't there. If there are further 'uses' statements inside the groupingcontent,contents, they may require expansion, too: it is necessary if the contained 'uses'/'grouping' pair lies on the "modification path" specified in the argument of a 'refine' or 'augment' statement. EXAMPLE. Consider the following YANG module: module example2 { namespace "http://example.com/ns/example2"; prefix ex2; grouping leaves { uses fr; uses es; } grouping fr { leaf feuille { type string; } } grouping es { leaf hoja { type string; } } uses leaves; } The resultingconceptual treehybrid schema contains three global named pattern definitions corresponding to the three groupings, namely <rng:define name="_example2__leaves"> <rng:interleave> <rng:ref name="_example2__fr"/> <rng:ref name="_example2__es"/> </rng:interleave> </rng:define> <rng:define name="_example2__fr"> <rng:optional> <rng:elementname="ex2:feuille">name="feuille"> <rng:data type="string"/> </rng:element> </rng:optional> </rng:define> <rng:define name="_example2__es"> <rng:optional> <rng:elementname="ex2:hoja">name="hoja"> <rng:data type="string"/> </rng:element> </rng:optional> </rng:define> and the configuration data part of theconceptual treehybrid schema is a single named pattern reference: <nma:data> <rng:ref name="_example2__leaves"/> </nma:data> Now assume that the "uses leaves" statement contains a 'refine' substatement, for example: uses leaves { refine "hoja" { default "alamo"; } } The resultingconceptual treehybrid schema now contains just one named pattern definition - "_example2__fr". The other two groupings "leaves" and "es" have to be expanded because they both lie on the "modification path", i.e., contain the leaf "hoja" that is being refined. The configuration data part of theconceptual treehybrid schema now looks like this: <nma:data> <rng:interleave> <rng:ref name="_example2__fr"/> <rng:optional> <rng:element name="ex2:hoja" nma:default="alamo"> <rng:data type="string"/> </rng:element> </rng:optional> </rng:interleave> </nma:data> 9.2.2. Type Derivation Chains RELAX NG has no equivalent of the type derivation mechanism in YANG that allows tomodifyrestrict a built-in type (perhaps in multiple steps) by adding newrestrictions. Whenconstraints. Whenever a derived YANG type is used without restrictions - as a substatement of either 'leaf' or another 'typedef' - then the 'type' statement is mapped simply tothe <rng:ref> element, i.e.,a named patternreference,reference <rng:ref>, and the type definition is mapped to a RELAX NG named patterndefinition.definition <rng:define>. However, if any restrictions are specified as substatements of the 'type' statement, the type definition MUST be expanded at that point so that only the ancestor built-in type appears in theoutputhybrid schema, restricted with facets that correspond to the combination of all restrictions found along the type derivation chain and also in the 'type' statement. EXAMPLE. Consider this YANG module: module example3 { namespace "http://example.com/ns/example3"; prefix ex3; typedef dozen { type uint8 { range 1..12; } } leaf month { type dozen; } } The 'type' statement in "leaf month" has no restrictions and is therefore mapped simply to the reference <rng:ref name="example3__dozen"/> and the corresponding named pattern is defined as follows: <rng:define name="example3__dozen"> <rng:data type="unsignedByte"> <rng:paramname="minInclusive">1</param>name="minInclusive">1</rng:param> <rng:paramname="maxInclusive">12</param>name="maxInclusive">12</rng:param> </rng:data> </rng:define> Assume now that the definition of leaf "month" is changed to leaf month { type dozen { range 7..max; } } The output RELAX NG schema thenwon'twill not contain any named pattern definition and the leaf "month" will be mapped directly to <rng:element name="ex3:month"> <rng:data type="unsignedByte"> <rng:paramname="minInclusive">7</param>name="minInclusive">7</rng:param> <rng:paramname="maxInclusive">12</param>name="maxInclusive">12</rng:param> </rng:data> </rng:element> The mapping of type derivation chains may be further complicated by the presence of the 'default' statement in type definitions. In the simple case, when a type definition containing the 'default' statement is used without restrictions, the 'default' statement is mapped to the @nma:default attribute attached to the <rng:define> element. However, if that type definition has to beexpanded,expanded due to restrictions, the @nma:default annotation arising from the expanded type or ancestor types in the type derivation chain MUST be attached to theelementpattern where the expansion occurs. If there are multiple 'default' statements in consecutive steps of the type derivation, only the 'default' statement that is closest to the expanded type is used. EXAMPLE. Consider this variation of the last example: module example3bis { namespace "http://example.com/ns/example3bis"; prefix ex3bis; typedef dozen { type uint8 { range 1..12; } default 7; } leaf month { type dozen; } } The 'typedef' statement in this module is mapped to the following named pattern definition: <rng:define name="example3bis__dozen" @nma:default="7"> <rng:data type="unsignedByte"> <rng:paramname="minInclusive">1</param>name="minInclusive">1</rng:param> <rng:paramname="maxInclusive">12</param>name="maxInclusive">12</rng:param> </rng:data> </rng:define> If the "dozen" type is restricted when used in the leaf "month" definition as in the previous example, the "dozen" type has to be expanded and @nma:default becomes an attribute of the <ex3bis:month> element definition: <rng:element name="ex3bis:month" @nma:default="7"> <rng:data type="unsignedByte"> <rng:paramname="minInclusive">7</param>name="minInclusive">7</rng:param> <rng:paramname="maxInclusive">12</param>name="maxInclusive">12</rng:param> </rng:data> </rng:element> However, if the definition of the leaf "month" itself contained the 'default' substatement, the default specified for the "dozen" typewillwould be ignored. 9.3. Translation of XPath Expressions YANG uses full XPath 1.0 syntax [XPath] for the arguments of 'must', 'when' and 'path' statements. As the names of data nodes defined in a YANG module always belong to the namespace of that YANG module, YANG adopted a simplification similar to the concept of default namespace in XPath 2.0: node names in XPath expressions needn't carry a namespace prefix inside the module where they are defined and the local module's namespace is assumed.If anConsequently, all XPathexpression is carried over to a NETMOD-specific annotation in the conceptual tree schema, itexpressions MUST be translated into a fully conformant XPath 1.0expression that also reflects the hierarchy of the conceptual data tree: 1. Eachexpression: Every unprefixed node name MUST be prepended with the local module's namespace prefix as declared by the 'prefix' statement.2. AbsoluteXPathexpressions, i.e., those starting with a slash, MUST be prepended with appropriate pathexpressions appearing inside top-level groupings require special attention because all unprefixed node names contained in them must adopt theconceptual tree, accordingnamespace of each module where the grouping is used (cf. Section 8.2. In order to achieve this, theYANG specification of context forlocal prefix MUST be represented using the variable "$pref" in the hybrid schema. A Schematron schema which encounters such an XPathexpressions, see [YANG], Sections 7.5.3 and 7.19.5. Translation rule 2 meansexpression then supplies an appropriate value forexample that absolute XPath expressions appearing in the main configuration data tree always start with "nmt: netmod-tree/nmt:top/", those appearing inthis variable via anotification always start with "nmt:netmod-tree/nmt:notifications/nmt:notification/", etc. EXAMPLE.parameter to an abstract pattern to which the YANG grouping is mapped (see Section 11.2). For example, XPath expression "/dhcp/max-lease-time" appearing in a YANG module with themain configuration data"dhcp" prefix will be translated to"nmt:netmod-tree/ nmt:top/dhcp:dhcp/dhcp:max-lease-time". Theo "$pref:dhcp/$pref:max-lease-time", if the expression is inside a top-level grouping; o "dhcp:dhcp/dhcp:max-lease-time", otherwise. YANG also uses other XPath-like expressions, namely key identifiers and "descendant schema node identifiers" (see the ABNF production for and "descendant-schema-nodeid" in Section 12 of[YANG]) are not XPath[YANG]). These expressionsbut SHOULDMUST be translated by adding local module prefixes as well. 9.4. YANG Language Extensions YANG allows for extending its own language in-line by adding new statements with keywords from special namespaces. Such extensions first have to be declared using the 'extension' statement and then they can be used as the standard YANG statements, from which they are distinguished by a namespace prefix qualifying the extension keyword. RELAX NG has a similar extension mechanism - XML elements and attributes with names from foreign namespaces may be inserted at almost any place of a RELAX NG schema. YANG language extensions may or may not have a meaning in the context of DSDL schemas. Therefore, an implementation MAY ignore any or all of the extensions. However, an extension that is not ignored MUST be mapped to XML element(s) and/or attribute(s) that exactly match the YIN form of the extension, see Section 11.1 in [YANG]. EXAMPLE. Consider the following extension defined by the "acme" module: extension documentation-flag { argument number; } This extension can then be used in the same or another module, for instance like this: leaf folio { acme:documentation-flag 42; type string; } If this extension is honored by the mapping, it will be mapped to <rng:element name="acme:folio"> <acme:documentation-flag number="42"/> <rng:data type="string"/> </rng:element> Note that the 'extension' statement itself is not mapped in any way. 10. MappingConceptual Tree SchemaYANG Statements toDSDL As explained in Section 6, the second step of the YANG-to-DSDL mapping takestheconceptual tree schema and transforms it to various DSDL schemas prepared for validating instance XML documents. As an input parameter, this step takesHybrid Schema Each subsection in this section is devoted to one YANG statement and provides thesimplest case just aspecification of how theNETCONF XML document type (or combination of multiple types) thatstatement is mapped tobe validated. These document type can be, for example,thecontent of a datastore, replyhybrid schema. The subsections are sorted alphabetically by the statement keyword. Each YANG statement is mapped to<nc:get> or <nc: get-config>, other RPC requestsan XML fragment, typically a single element orreplies and notifications. In general,attribute but it may also be a larger structure. The mapping procedure is inherently recursive, which means that after finishing a statement thesecondmappingstep has to accomplishcontinues with its substatements, if there are any, and a certain element of thefollowing three tasks: 1. Extractresulting fragment becomes thepart(s)parent of other fragments resulting from theconceptual tree schema that are appropriate for the requested document type. For example, if a <get> reply ismapping of substatements. Any changes tobe validated, the subtree under <nmt:top> must be selected. 2. The schema must be adaptedthis default recursive procedure are explicitly specified. YANG XML encoding rules translate to thespecific encapsulating XML elements mandated byfollowing rules for ordering multiple subelements: 1. Within theRPC layer. These are,<nma:rpcs> subtree (i.e., forexample, <nc: rpc>input and<nc:data> elements in the caseoutput parameters ofa <get> reply or <en: notification> for a notification. 3. Finally, NETMOD-specific annotations that are relevant foran RPC operation) theschema languageorder of subelements is fixed and their definitions in thegeneratedhybrid schemamust be mapped toMUST follow thecorresponding rules. These three tasks are together much simpler thanorder specified in thefirstsource YANG module. 2. When mappingstepthe 'list' statement, all keys MUST come before any other subelements andcan be effectively implemented using XSL transformations [XSLT]. The following subsections describein thedetailssame order as they are declared in the 'key' statement. The order of thesecond mapping step forremaining (non-key) subelements is not specified, so their definitions in theindividual DSDLhybrid schemalanguages. Section 12 then contains a detailed specification forMUST be enclosed in themapping<rng:interleave> element. 3. Otherwise, the order of subelements is arbitrary and, consequently, allNETMOD- specific annotations. 10.1. Generating RELAX NG Schemas for Various Document Types With one minor exception, obtaining a validating RELAX NG schema from the conceptual tree schema really means only taking appropriate partsdefinitions of subelements in theconceptual treehybrid schemaand assembling themMUST be enclosed ina new RELAX NG grammar, perhaps after removing all unwanted annotations. Depending ontheXML document type that is the target for validation (<get>/ <get-config> reply, RPC or notification) a corresponding top-level part of the grammar MUST be added as described in the following subsections. Schemas for multiple alternative target document types can also be easily generated by enclosing the definitions for requested type in <rng:choice><rng:interleave> element.In order to avoid copying common named pattern definitions to every single output RELAX NG file, these schema-independent definitions SHOULD be collectedThe following conventions are used ina library file whichthis section: o The argument of the statement being mapped isthen includeddenoted by ARGUMENT. o The element in thevalidatingRELAX NGschemas. Appendix B hasschema that becomes thelistingparent ofthis library file. The minor exception mentioned above is the annotation @nma:config, which must be observed ifthetarget document typeresulting XML fragment is<get-config> reply. In this case, eachdenoted by PARENT. 10.1. The anyxml Statement This statement is mapped to <rng:element> elementdefinition that has this attributeand ARGUMENT with prepended local namespace prefix becomes the value"false" MUST be removed from the schema together withof itsdescendants. See Section 12.1 for more details. 10.1.1. Reply to <get> or <get-config> For a reply to <get> or <get-config>,@name attribute. The contents of <rng:element> are <rng:ref name="__anyxml__"/> Substatements of themapping must take'anyxml' statement, if any, MAY be mapped to additional children of thepart<rng:element> element. If at least one 'anyxml' statement occurs in any of theconceptual tree schema underinput YANG modules, the following pattern definition MUST be added exactly once to the RELAX NG schema as a child of<nmt:top> and insert it inthefollowing grammar: <rng:grammar ... namespaces etc. ...> <rng:include href="relaxng-lib.rng"/> <rng:start> <rng:element name="nc:rpc-reply"> <rng:ref name="message-id-attribute"/> <rng:element name="nc:data"> ... patterns defining contents of "nmt:top" subtree ... </rng:element>root <rng:grammar> element (cf. [Vli04], p. 172): <rng:define name="__anyxml__"> <rng:zeroOrMore> <rng:choice> <rng:attribute> <rng:anyName/> </rng:attribute> <rng:element> <rng:anyName/> <rng:ref name="__anyxml__"/> </rng:element></rng:start> ... named pattern definitions ... </rng:grammar> The definition for the named pattern "message-id-attribute" is found<rng:text/> </rng:choice> </rng:zeroOrMore> </rng:define> EXAMPLE: YANG statement inthe library file "relaxng-lib.rng" whicha module with namespace prefix "yam" anyxml data { description "Any XML content allowed here."; } isincluded onmapped to thesecond line (see Appendix B). Definitions of other named patternsfollowing fragment: <rng:element name="yam:data"> <a:documentation>Any XML content allowed here</a:documentation> <rng:ref name="__anyxml__"/> </rng:element> An anyxml node is optional if there is no "mandatory true;" substatement. The <rng:element> element then MUST becopied literally fromwrapped in <rng:optional>, except when theconceptual tree schema to'anyxml' statement is a child of theresulting grammar. However, an implementation MAY choose to copy only those definitions'choice' statement and thus forms a shorthand case for thatare really used inchoice (see Section 9.1.1 for details). 10.2. The argument Statement This statement is not mapped to theparticularoutputgrammar. 10.1.2. Remote Procedure Calls For an RPC method named "myrpc" and definedschema, but see the rules for handling extensions in Section 9.4. 10.3. The augment Statement As a substatement of 'uses', this statement is handled as a part of 'uses' mapping, see Section 10.57. At the top level of aYANGmodulewith prefix "yam",or submodule, thecorresponding schema subtree'augment' statement isidentified byused for augmenting thedefinitionschema tree of<nmt:rpc-method> element whose <nmt:input> subelement has <yam:myrpc> asanother YANG module. If theonly child. Theaugmented module is not processed within the same mappingmust also take into account whethersession, thetarget document type is an RPC request or reply. For "yam:myrpc" request,top-level 'augment' statement MUST be ignored. Otherwise, theresulting grammar looks as follows: <rng:grammar ... namespaces etc. ...> <rng:include href="relaxng-lib.rng"/> <rng:start> <rng:element name="nc:rpc"> <rng:ref name="message-id-attribute"/> <rng:element name="yam:myrpc"> ... patterns definingcontents of thesubtree ... ... "nmt:rpc-method/nmt:input/yam:myrpc" ... </rng:element> </rng:element> </rng:start> ... named pattern definitions ... </rng:grammar> For "yam:myrpc" reply,statement are added to theoutput grammar is <rng:grammar ... namespaces etc. ...> <rng:include href="relaxng-lib.rng"/> <rng:start> <rng:element name="nc:rpc-reply"> <rng:ref name="message-id-attribute"/> ... patterns defining contents offoreign module with thecorresponding ... ... "nmt:rpc-method/nmt:output" subtree ... </rng:element> </rng:start> ... named pattern definitions ... </rng:grammar> In both cases, exact copiesnamespace ofnamed pattern definitions from the conceptual tree schema MUST be inserted, but an implementation MAY choose to include only those used forthegiven RPC. 10.1.3. Notifications For a notification named "mynotif" and defined in a YANGmodulewith prefix "yam",where thecorresponding schema subtree'augment' statement appears. 10.4. The base Statement This statement isidentified by the definitionignored as a substatement of<nmt:notification> element that has'identity' and handled within thesingle child <yam:mynotif>. The resulting grammar looks'identityref' type if it appears asfollows: <rng:grammar ... namespaces etc. ...> <rng:include href="relaxng-lib.rng"/> <rng:start> <rng:element name="en:notification"> <rng:ref name="eventTime-element"/> <rng:element name="yam:mynotif"> <!-- patterns defining contentsa substatement of"nmt:rpc-notification/yam:mynotif" subtree --> </rng:element> </rng:element> </rng:start> <!-- named pattern definitions --> </rng:grammar>that type definition, see Section 10.53.5. 10.5. Thedefinition of the named pattern "eventTime-element"belongs-to Statement This statement isfound innot used since the"relaxng-lib.rng" library file, see Appendix B. Again, exact copiesprocessing ofnamed pattern definitionssubmodules is always initiated from theconceptual tree schema MUST be inserted, but an implementation MAY choosemain module, see Section 10.24. 10.6. The bit Statement This statement is handled within the "bits" type, see Section 10.53.3. 10.7. The case Statement This statement is mapped toinclude only those used for<rng:group> or <rng:interleave> element, depending on whether thegiven notification. 10.2. Mapping Semantic Constraintsstatement belongs toSchematron Schematron schemas tend to be much flatter and more uniform compared to RELAX NG. They have exactly four levelsan definition ofXML hierarchy: <sch: schema>, <sch:pattern>, <sch:rule> and <sch:assert>an RPC operation or<sch:report>. In a Schematron schema generated by the second mapping step,not. If thebasic unitargument oforganization isarule represented by the <sch:rule> element. Every rule correspondssibling 'default' statement equals toexactly one element definition pattern inARGUMENT, @nma:implicit attribute with theconceptual tree schema: <sch:rule context="XELEM"> ... </sch:rule> Thevalue ofthe mandatory @context attribute of <sch:rule> (denoted as XELEM)"true" MUST besetadded to that <rng:group> or <rng:interleave> element. The @nma:implicit attribute MUST NOT be used for nodes at theabsolute pathtop-level ofthe context elementa non-default case (see Section 7.9.3 inthe data tree.[YANG]). 10.8. The<sch:rule> element containschoice Statement This statement is mapped to <rng:choice> element. If 'choice' has themappings of one or more'mandatory' substatement with the value of "true", thefollowing NETMOD-specific annotations, if they are attachedattribute @nma:mandatory MUST be added to thecontext element: <nma:instance-identifier>, @nma:key, @nma:leafref, @nma:min-elements, @nma:max-elements, <nma:must>, @nma: unique and <nma:when>. In<rng: choice> element with theopposite direction, however,value of ARGUMENT. This case may require additional handling, see Section 11.2.1. Otherwise, if "mandatory true;" is noteverypresent, the <rng:choice> elementdefinition patternMUST be wrapped inthe conceptual tree schema has a corresponding rule<rng:optional>. The alternatives in <rng:choice> - mapped from either theSchematron schema: definitions of elements the carry none of the above annotations are omitted. Schematron rules may'case' statement or a shorthand case - MUST NOT befurther grouped into patterns represented by the <sch:pattern> element.defined as optional. 10.9. Themapping uses patterns only for discriminating between subsets of rules that belongconfig Statement This statement is mapped todifferent validation phases, see Section 10.2.1. Therefore, the <sch:schema> always has exactly two <sch:pattern> children: one named "standard" contains rules for all annotations except <nma:instance-identifier> and @nma:leafref,@nma:config attribute andanother named "ref-integrity" containing rules for these two remaining annotations, i.e., referential integrity checks. Element definitions in the conceptual tree schema that appear inside a named pattern definition (i.e., have <rng:define> amongARGUMENT becomes itsancestors) are subject to a different treatment.value. 10.10. The contact Statement Thisis because their path instatement SHOULD NOT be used by thedata tree is not fixed -mapping since thenamed patternhybrid schema may bereferred to inmapped from multipleplaces.YANG modules created by different authors. Themapping uses Schematron abstract rules to handle this case: An element definition inside a named pattern is mappedhybrid schema contains references toan abstract rule and every useall input modules in the Dublin Core elements <dc:source>, see Section 10.34. The original YANG modules are the authoritative sources of thenamed pattern then extends (uses) this abstract ruleauthorship information. 10.11. The container Statement Using the rules specified in Section 9.1.1, theconcrete context. EXAMPLE. Consider this element pattern annotated with <nma:must>: <rng:element name="dhcp:default-lease-time"> <rng:data type="unsignedInt"/> <nma:must assert=". <= ../dhcp:max-lease-time"> <nma:error-message> The default-lease-time must be less than max-lease-time </nma:error-message> </nma:must> </rng:element> If thismapping algorithm MUST determine whether the statement defines an optional container, and if so, insert the <rng:optional> elementpattern appears outside any named patternandas a child of <dhcp:dhcp> (asmake itdoes intheDHCP schema, see Appendix C.2), itnew PARENT. The container defined by this statement is then mapped to thefollowing Schematron rule: <sch:rule context="/nc:rpc-reply/nc:data/dhcp:dhcp/ dhcp:default-lease-time"> <sch:assert test=". <= ../dhcp:max-lease-time"> The default-lease-time must be less than max-lease-time </sch:assert> </sch:rule> Now assume the element definition is inside<rng: element> element, which becomes anamed pattern definition, say <rng:define name="_dhcp__default-lease-time"> <rng:element name="dhcp:default-lease-time"> ... same content ... </rng:element> </rng:define> In this case it is mapped to an abstract rule, for instance <sch:rule id="id31415926" abstract="true"> <sch:assert test=". <= ../dhcp:max-lease-time"> The default-lease-time must be less than max-lease-time </sch:assert> </sch:rule> Any usechild ofthe named pattern definition via <rng:ref name="_dhcp__default-lease-time"/> then results in a new rule extending the abstract one, for example <sch:rule context="/nc:rpc-reply/nc:data/dhcp:dhcp/ dhcp:default-lease-time"> <sch:extends rule="id31415926"/> </sch:rule> Care must be taken thatPARENT and uses ARGUMENT with prepended local namespace prefix as the value ofthe @context attribute in general consists of two parts in this case:itsbeginning is determined by the location of@name attribute. Finally, using the<rng:ref> elementrules specified in Section 9.1.2, themain schema tree andmapping algorithm MUST determine whether therest ofcontainer is implicit, and if so, add thepath comes fromattribute @nma:implicit with therelative positionvalue of "true" to theannotated element definition inside the named pattern.<rng:element> element. 10.12. Thesituation becomes even more complex when the mapping has to deal with chained definitionsdefault Statement If this statement is a substatement ofnamed patterns (<rng:ref> inside <rng: define>). The @context value then must be recursively glued together from multiple parts. The mapping from the conceptual tree schema'leaf', it is mapped toSchematron proceeds in the following steps: 1. First,theactive subtree(s)@nma:default attribute of PARENT and ARGUMENT becomes its value. As a substatement of 'typedef', theconceptual tree schema must be selected depending on the requested target document type. This procedure'default' statement isidenticalalso mapped to theRELAX NG case, including@nma:default attribute with thehandlingvalue of@nma:config ifARGUMENT. The placement of this attribute depends on whether or not thetarget documenttype definition has to be expanded when it is<get- config> reply. 2. Namespacesused: o If the type definition is not expanded, @nma:default becomes an attribute ofall input YANG modules, together withthenamespaces<rng:define> pattern resulting from the parent 'typedef' mapping. o Otherwise, @nma:default becomes an attribute ofbase NETCONF ("nc" prefix) or notifications ("en" prefix) MUST be declared usingthe<sch:ns> element, forancestor RELAX NG pattern inside which the expansion takes place. Details and an example<sch:ns uri="http://example.com/ns/dhcp" prefix="dhcp"/> 3. Validation phasesaredefined (seegiven in Section10.2.1) and their constituting patterns "standard" and "ref-integrity" created. 4. For either validation phase,9.2.2. Finally, as a substatement of 'choice', theinput conceptual tree schema is scanned and element definitions with annotations relevant for'default' statement identifies thegiven phase are selecteddefault case anda <sch:rule>iscreated for each of them. As explained above,handled within therule'case' statement, see Section 10.7. If the default case uses the shorthand notation where the 'case' statement isabstract ifomitted, theelement definition appears inside a named pattern. 5. All annotations@nma:implicit attribute with the value of "true" is either attached to thegiven element definition are then mapped usingnode representing themapping rules specifieddefault case inSection 12. The resulting <sch:assert> or <sch:report> elements aretheinstalled as children ofshorthand notation or, alternatively, an extra <rng:group> element MAY be inserted and the<sch:rule> element. 10.2.1. Validation Phases@nma:implicit attribute attached to it. Incertain situations itthe latter case, the net result isuseful to validate XML instance documents without enforcingthereferential integrity constraints represented bysame as if the@nma:leafref and <nma:instance-identifier> annotations. For example, a candidate configuration referring to configuration parameters or state data of certain hardware will not pass full validation before the hardware is installed. To handle this, the Schematron mapping introduces two validation phases: o Validation phase "full", which is the default, checks all semantic constraints. o Validation phase "noref" is the same as "full" except it doesn't check referential integrity constraints. A parameter identifying the validation phase to use has to be passed to the Schematron processor or otherwise "full" phase is assumed by default. How this is exactly done depends on the concrete Schematron processor and is outside the scope of this document. The validation phases are defined in Schematron by listing the patterns that are to be applied'case' statement wasn't omitted foreach phase. Therefore,themapping puts the rules for referential integrity checking to a special <sch:pattern> with @id attribute set to "ref-integrity".default case. EXAMPLE. Therules mapped from the remaining semantic constraints are put to another <sch:pattern> with @id attributes set to "standard". With validation phases, the resulting Schematron schema has thefollowingoverall structure: <sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron"> <sch:ns uri="..." prefix="..."/> ... more NS declarations ... <sch:phase id="full"> <sch:active pattern="standard"/> <sch:active pattern="ref-integrity"/> </sch:phase> <sch:phase id="noref"> <sch:active pattern="standard"/> </sch:phase> <sch:pattern id="standard"> ... all rules except ref. integrity checks ... </sch:pattern> <sch:pattern id="ref-integrity"> ... rules for ref. integrity checks ... </sch:pattern> </sch:schema> 10.3. Constraints on Mandatory Choice In order to fully represent the semantics of YANG'choice' statementwith "mandatory true;" substatement, the RELAX NG grammar has to be combined within aspecial Schematron rule. EXAMPLE. Consider the following module:moduleexample4 {with namespace"http://example.com/ns/example4";prefixex4;"yam" choicefoobar { mandatory true; case foo { leaf foo1leaves {type uint8; }default feuille; leaffoo2feuille { typeuint8; }empty; } leafbarhoja { typeuint8; }empty; } }In this module, all three leaf nodes in both case branches are optional but because of the "mandatory true;" statement, at least one of them must be present in a valid configuration. The 'choice' statement from this moduleis either mapped directly tothe following fragment of the conceptual tree schema:<rng:choice><rng:interleave> <rng:optional> <rng:element name="ex4:foo1"> <rng:data type="unsignedByte"/> </rng:element> </rng:optional> <rng:optional><rng:elementname="ex4:foo2"> <rng:data type="unsignedByte"/>name="yam:feuille" nma:implicit="true"> <rng:empty/> </rng:element></rng:optional> </rng:interleave><rng:elementname="ex4:bar"> <rng:data type="unsignedByte"/> </rng:element>name="yam:hoja"> <rng:empty/> </rng:element/> </rng:choice>Inor theseconddefault casebranch, the "ex4:bar" element is defined as mandatory so that this element mustmay bepresentwrapped ina valid configuration if this branchan extra <rng:group>: <rng:choice> <rng:group nma:implicit="true"> <rng:element name="yam:feuille"> <rng:empty/> </rng:element> </rng:group> <rng:element name="yam:hoja"> <rng:empty/> </rng:element/> </rng:choice> 10.13. The description Statement This statement MAY be ignored. Otherwise, it isselected. However,mapped to thetwo elementsDTD compatibility element <a:documentation> and ARGUMENT becomes its text. In order to get properly formatted in thefirst branch "foo" cannotRELAX NG compact syntax, this element SHOULD beboth declaredinserted asmandatory since each of them alone suffices for a valid configuration. As a result,theabove RELAX NG fragment would successfully validate configurations where nonefirst child ofthe three leaf elementsPARENT. 10.14. The deviation Statement This statement ispresent. Therefore, mandatory choices, which can be recognized in the conceptual tree schema as <rng:choice> elementsignored. However, it is assumed thatdo not have <optional> as their parent,all deviations are known beforehand and the corresponding changes have already been applied tobe handled in a special way: For each mandatory choice where at least one of the cases contains more than one node, a rule MUST be present in the "standard" pattern oftheSchematron schema enforcinginput YANG modules. 10.15. The enum Statement This statement is mapped to <rng:value> element and ARGUMENT becomes its text. All substatements except 'status' are ignored because thepresence of at least one<rng:value> elementfrom any of the cases. (RELAX NG schema guarantees that elements from different casescannotbe mixed together, that all mandatory nodes are present etc.). For the example module above,contain annotation elements, see [RNG], section 6. 10.16. The error-app-tag Statement This statement is ignored unless it is a substatement of 'must'. In theSchematron rule will be as follows: <sch:rule context="/nc:rpc-reply/nc:data"> <sch:assert test="ex4:foo1 or ex4:foo2 or ex4:bar"> Node(s) from at least onelatter caseof choice "foobar" must exist. </sch:assert> </sch:rule> 10.4. Mapping Default Values to DSRL DSRLit is mapped to theonly component<nma:error-app-tag> element. See also Section 10.35. 10.17. The error-message Statement This statement is ignored unless it is a substatement ofDSDL that'must'. In the latter case it isallowedmapped tochange the information set ofthevalidated XML document. While DSRL<nma:error-message> element. See alsohas other functions, YANG-to-DSDL mapping uses it only for specifying and applying default content. For XML instance documents based on YANG data models, insertion of default content may potentially take place for all implicit nodes defined bySection 10.35. 10.18. The extension Statement This statement is ignored. However, extensions to therulesYANG language MAY be mapped as described in Section9.1.2. In DSRL, the default content of an element9.4. 10.19. The feature Statement This statement isspecified using the <dsrl:default-content> element, whichignored. 10.20. The grouping Statement This statement is mapped to achild of <dsrl:element- map>. Two sibling elements of <dsrl:default-content> determine the context for application of the default content, see [DSRL]: o <dsrl:parent> element contains an XSLTRELAX NG named patternspecifying the parent element; the default content is applieddefinition <rng: define>, but only if theparent element exists ingrouping defined by this statement is used without refinements and augments in at least one of theinstance document. o <dsrl:name> containsinput modules. In this case, theXML namenamed pattern definition becomes a child of the <rng:grammar> elementwhich, if missing or empty,and its name isinserted together withARGUMENT mangled according to thecontent of <dsrl:default- content>. The <dsrl:parent> element is optionalrules specified in Section 9.2. As explained in Section 8.2, ageneral DSRL schema but for the purpose of the YANG-to-DSDL mapping this elementnamed pattern definition MUST bealways present in order to guarantee proper applicationplaced o as a child ofdefault content. DSRL mapping only deals withthe root <rng:grammar> elementpatterns defining implicit nodes (see Section 9.1.2). Inif theconceptual tree schema, suchcorresponding grouping is defined at the top level of an input YANG module; o otherwise as a child of the embedded <rng:grammar> elementpatterns are distinguished by having NETMOD-specific annotation attributes @nma:default or @nma:implicit, i.e., either <rng:element name="ELEM" nma:default="DEFVALUE"> ... </rng:element> or <rng:element name="ELEM" nma:implicit="true"> ... </rng:element> The former case appliescorresponding toleaf nodes havingthe'default' substatement, but also to leaf nodes that obtain their default value frommodule in which the grouping is defined. Whenever atypedef, if this typedefgrouping is used with refinements and/or augments, it is expandedaccording to the rules in Section 9.2.2so that the@nma:default annotation is attached directlyrefinements and augments may be applied in place to theleaf's element pattern. The latter case is used for all implicit containers (seeprescribed schema nodes. See Section9.1) and9.2.1 forleafs that obtain the default value from a typedeffurther details anddon't havean example. An implementation MAY offer the@nma:default annotation. Inoption of mapping all 'grouping' statements as named pattern definitions in thesimplest case, both element patternsoutput RELAX NG schema even if they are not referenced. This is useful for mapping YANG "library" modules that typically contain only 'typedef' and/or 'grouping' statements. 10.21. The identity Statement This statement is mapped to the followingDSRL element map: <dsrl:element-map> <dsrl:parent>XPARENT</dsrl:parent> <dsrl:name>ELEM</dsrl:name> <dsrl:default-content>DEFCONT</dsrl:default-content> </dsrl:element-map> where XPARENTnamed pattern definition which isthe absolute XPathplaced as a child ofELEM's parent element inthedata tree and DEFCONTroot <rng:grammar> element: <rng:define name="__PREFIX_ARGUMENT"> <rng:choice> <rng:value type="QName">PREFIX:ARGUMENT</rng:value> <rng:ref name="IDENTITY1"/> ... </rng:choice> </rng:define> where PREFIX isconstructed as follows: o Iftheimplicit node ELEM is a leaf and hasprefix used in the@nma:default attribute, DEFCONT is set tohybrid schema for thevaluenamespace ofthis attribute (denoted above as DEFVALUE). o Iftheimplicit node ELEM is a leaf and hasmodule where the@nma:implicit attribute withcurrent identity is defined. IDENTITY1 is thevalue "true",name of of thedefault value hasnamed pattern corresponding tobe determinedan identity which is derived from the@nma:default attribute of the definition of ELEM's type (perhaps recursively) and used in place of DEFCONT in the above DSRLcurrent identity. Exactly one <rng:ref> elementmap. See alsoMUST be present for every such identity. EXAMPLE ([YANG], Section9.2.2. o Otherwise, the implicit node ELEM is a container and DEFCONT is constructed as an XML fragment containing all descendant elements of ELEM that have either @nma:implicit or @nma:default attribute.7.16.3). The<rng:element>, <rng:group> or <rng:interleave>patterns appearing directly under <rng:choice> MUST NOT have either @nma:default or @nma:implicit annotation unless they belong toidentities in thedefault case of a YANG choice (see Section 11.12). In addition, when mapping the default case of a choice, it has to be guaranteed that the default content is not applied if any node from any non-default case is present. This is accomplished by setting <dsrl:parent> in a special way: <dsrl:parent>XPARENT[not (ELEM1|ELEM2|...|ELEMn)]</dsrl:parent> where ELEM1, ELEM2, ... ELEMn are the names of all top-level nodes from all non-default cases. The rest of the element map is exactly as before. EXAMPLE. Consider the followinginput YANGmodule:modules moduleexample5crypto-base { namespace"http://example.com/ns/example5";"http://example.com/crypto-base"; prefixex5; container outer { leaf leaf1"crypto"; identity crypto-alg {type uint8; default 1;description "Base identity from which all crypto algorithms are derived."; }choice one-or-two { default "one"; container one} module des {leaf leaf2namespace "http://example.com/des"; prefix "des"; import "crypto-base" {type uint8; default 2; }prefix "crypto"; }leaf leaf3identity des {type uint8; default 3; }base "crypto:crypto-alg"; description "DES crypto algorithm"; } identity des3 { base "crypto:crypto-alg"; description "Triple DES crypto algorithm"; } }The DSRL schema generated for the "get-reply" target document typewillbe: <dsrl:maps xmlns:dsrl="http://purl.oclc.org/dsdl/dsrl" xmlns:ex5="http://example.com/ns/example5" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"> <dsrl:element-map> <dsrl:parent>/nc:rpc-reply/nc:data</dsrl:parent> <dsrl:name>ex5:outer</dsrl:name> <dsrl:default-content> <ex5:leaf1>1</ex5:leaf1> <ex5:one><ex5:leaf2>2</ex5:leaf2></ex5:one> </dsrl:default-content> </dsrl:element-map> <dsrl:element-map> <dsrl:parent> /nc:rpc-reply/nc:data/ex5:outer[not(ex5:leaf3)] </dsrl:parent> <dsrl:name>ex5:one</dsrl:name> <dsrl:default-content> <ex5:leaf2>2</ex5:leaf2> </dsrl:default-content> </dsrl:element-map> <dsrl:element-map> <dsrl:parent>/nc:rpc-reply/nc:data/ex5:outer</dsrl:parent> <dsrl:name>ex5:leaf1</dsrl:name> <dsrl:default-content>1</dsrl:default-content> </dsrl:element-map> <dsrl:element-map> <dsrl:parent>/nc:rpc-reply/nc:data/ex5:outer</dsrl:parent> <dsrl:name>ex5:one</dsrl:name> <dsrl:default-content> <ex5:leaf2>2</ex5:leaf2> </dsrl:default-content> </dsrl:element-map> <dsrl:element-map> <dsrl:parent>/nc:rpc-reply/nc:data/ex5:outer/ex5:one</dsrl:parent> <dsrl:name>ex5:leaf2</dsrl:name> <dsrl:default-content>2</dsrl:default-content> </dsrl:element-map> </dsrl:maps> Note thatbe mapped to thedefault value for "leaf3" definedfollowing named pattern definitions: <define name="__crypto_crypto-alg"> <choice> <value type="QName">crypto:crypto-alg</value> <ref name="__des_des"/> <ref name="__des_des3"/> </choice> </define> <define name="__des_des"> <value type="QName">des:des</value> </define> <define name="__des_des3"> <value type="QName">des:des3</value> </define> 10.22. The if-feature Statement ARGUMENT together with arguments of all sibling 'if-feature' statements (with added prefixes, if missing) MUST be collected inthe YANG module is ignored because "leaf3" representsanon-default alternativespace-separated list which becomes the value ofa choice and as such never becomes an implicit element. 11. Mapping YANG Statements to Conceptual Tree Schema Each subsection in this section is devoted to one YANG statement and provides the specification howthestatement@nma:if-feature attribute. This attribute ismappedattached tothe annotated RELAX NG schema of the conceptual tree.PARENT. 10.23. The import Statement This statement isthe first step of the mapping procedure as explained in Section 6.not specifically mapped. Thesubsections are sorted alphabetically by the statement keyword. Each YANG statementmodule whose name ismappedin ARGUMENT has toan XML fragment, typically a single element or attribute but it may alsobea larger structure. The mapping procedure is inherently recursive, which meansparsed so thatafter finishing a statementthemapping continues withimporting module is able to use itssubstatements, if there are any,top-level groupings, typedefs anda certain elementidentities, and also augment the data tree of theresulting fragment becomesimported module. If theparent of other fragments resulting from'import' statement has themapping of substatements. Any changes to this default recursive procedure are explicitly specified. YANG XML encoding rules translate to'revision' substatement, thefollowing rules for ordering multiple subelements: 1. Withincorresponding revision of the<nmt:rpc-methods> subtree (i.e.,imported module MUST be used. The mechanism forRPC input and output parameters)finding a given module revision is outside theorderscope ofsubelementsthis document. 10.24. The include Statement This statement isfixednot specifically mapped. The submodule whose name is in ARGUMENT has to be parsed andtheir definitionsits contents mapped exactly as if the submodule text appeared directly in theconceptual tree schema MUST followmain module text. If theorder specified in'include' statement has thesource YANG module. 2. When mapping the 'list' statement, all keys MUST come before any other subelements and in the same order as they are declared in'revision' substatement, the'key' statement. The ordercorresponding revision of theremaining (non-key) subelements is not specified, so their definitions in the conceptual tree schemasubmodule MUST beenclosed inused. The mechanism for finding a given submodule revision is outside the<rng:interleave> element. 3. Otherwise, all definitionsscope ofsubelements in the conceptual tree schemathis document. 10.25. The input Statement This statement is handled within 'rpc' statement, see Section 10.50. 10.26. The key Statement This statement is mapped to @nma:key attribute. ARGUMENT MUST beenclosed in the <rng:interleave> element. We usetranslated so that every key is prefixed with thefollowing conventions: o The argumentnamespace prefix of thestatement being mapped is denoted by ARGUMENT. olocal module. Theelement in the RELAX NG schema thatresult of this translation then becomes theparentvalue of theresulting XML fragment is denoted by PARENT. 11.1.@nma:key attribute. 10.27. Theanyxmlleaf Statement This statement is mapped to the <rng:element> element and ARGUMENT with prepended local namespace prefix becomes the value of its @name attribute.The content of <rng:element> is <rng:ref name="__anyxml__"/> Substatements ofIf the'anyxml' statement,leaf is optional, i.e., ifany, MAY be mapped to additional children ofthere is no "mandatory true;" substatement and theRELAX NG element definition. Ifleaf is not declared among the'anyxml' statement occurs in anykeys of an enclosing list, then theinput YANG modules, the following pattern definition<rng:element> element MUST beadded exactly once toenclosed in <rng:optional>, except when theRELAX NG schema as'leaf' statement is a child of the<rng:grammar> element (cf. [Vli04], p. 172): <rng:define name="__anyxml__"> <rng:zeroOrMore> <rng:choice> <rng:attribute> <rng:anyName/> </rng:attribute> <rng:element> <rng:anyName/> <rng:ref name="__anyxml__"/> </rng:element> <rng:text/> </rng:choice> </rng:zeroOrMore> </rng:define> EXAMPLE: YANG statement in a module with namespace prefix "yam" anyxml data { description "Any XML content allowed here."; } is mapped to the following fragment: <rng:element name="yam:data"> <a:documentation>Any XML content allowed here</a:documentation> <rng:ref name="__anyxml__"/> </rng:element> An anyxml node is optional if there is no "mandatory true;" substatement. The <rng:element> element then MUST be wrapped in <rng:optional>, except when the 'anyxml' statement is a child of the 'choice''choice' statement and thusformsrepresents a shorthand case for that choice (see Section 9.1.1 for details).11.2.10.28. Theargumentleaf-list Statement This statement isnotmapped tothe output schema, but see the rules for handling extensions in Section 9.4. 11.3. The augment Statement As a substatement of 'uses', this statement is handled asapart of 'uses' mapping, see Section 11.57. Atblock enclosed by either <rng: zeroOrMore> or <rng:oneOrMore> element depending on whether thetop levelargument ofa module'min-elements' substatement is "0" orsubmodule, the 'augment' statementpositive, respectively (it isused for augmenting the schema tree of another YANG module. Ifzero by default). This <rng:zeroOrMore> or <rng: oneOrMore> element becomes thelatter modulePARENT. <rng:element> isnot processed within the same mapping session,then added as a child element of PARENT and ARGUMENT with prepended local namespace prefix becomes thetop-level 'augment' statementvalue of its @name attribute. Another attribute, @nma:leaf-list, MUST also beignored. Otherwise, the contents of the statement areadded tothe foreign modulethis <rng:element> element with thenamespacevalue of "true". If themodule where the 'augment' statement appears. 11.4. The base Statement This'leaf- list' statementis ignored as ahas the 'min-elements' substatementof 'identity'andhandled withinits argument is greater than one, additional attribute @nma:min-elements is attached to <rng:element> and the'identityref' type if it appears as a substatementargument ofthat type definition, see Section 11.53.5. 11.5. The belongs-to Statement This statement'min-elements' becomes the value of this attribute. Similarly, if there is the 'max- elements' substatement and its argument value is notused since processing"unbounded", attribute @nma:max-elements is attached to this element and the argument ofsubmodules'max-elements' becomes the value of this attribute. EXAMPLE. A leaf-list appearing in a module with the namespace prefix "yam" leaf-list foliage { min-elements 3; max-elements 6378; ordered-by user; type string; } isalways initiated frommapped to themain module, see Section 11.24. 11.6.following RELAX NG fragment: <rng:oneOrMore> <rng:element name="yam:foliage" nma:leaf-list="true" nma:ordered-by="user" nma:min-elements="3" nma:max-elements="6378"> <rng:data type="string"/> </rng:element> </rng:oneOrMore> 10.29. Thebitlength Statement This statement is handled within the"bits""string" type, see Section11.53.3. 11.7.10.53.9. 10.30. Thecaselist Statement This statement is mappedto <rng:group> or <rng:interleave> element, depending on whether the statement belongs to an RPC definition or not. Ifexactly as theargument of a sibling 'default' statement equals to ARGUMENT, @nma:implicit attribute with'leaf-list' statement, see Section 10.28. The only difference is that thevalue "true"@nma:leaf-list annotation either MUST NOT beadded to that <rng:group>present or<rng:interleave> element. The @nma:implicit attributeMUSTNOT be used for nodes athave thetop-levelvalue ofa non- default case (see Section 7.9.3 in [YANG]). 11.8. The choice Statement This statement is mapped to <rng:choice> element. Unless 'choice' has"false". When mapping the'mandatory' substatement withsubstatements of 'list', thevalue "true",order of children of the<rng:choice>list element MUST bewrappedspecified so that list keys, if there are any, always appear in<rng:optional>. The 'choice' statement with "mandatory true;" may require additional handling,the same order as they are defined in the 'key' substatement and before other children, see [YANG], Section10.3. The alternatives7.8.5. In particular, if a list key is defined in<rng:choice> - mapped from eithera grouping but the'case' statement orlist node itself is not ashorthand case -part of the same grouping, and the position of the 'uses' statement would violate the above ordering requirement, the grouping MUSTNOTbedefined as optional. 11.9. The config Statement Thisexpanded, i.e., the 'uses' statement replaced by the grouping contents. For example, consider the following YANG fragment of a module with the prefix "yam": grouping keygrp { leaf clef { type uint8; } } list foo { key clef; leaf bar { type string; } leaf baz { type string; } uses keygrp; } is mapped to@nma:config attributethe following RELAX NG fragment: <rng:zeroOrMore> <rng:element name="yam:foo" nma:key="yam:clef"> <rng:element name="yam:clef"> <rng:data type="unsignedByte"/> </rng:element> <rng:interleave> <rng:element name="yam:bar"> <rng:data type="string"/> </rng:element> <rng:element name="yam:baz"> <rng:data type="string"/> </rng:element> </rng:interleave> </rng:element> </rng:zeroOrMore> Note that the "keygrp" grouping is expanded andARGUMENT becomes its value. 11.10.the definition of "yam:clef" is moved before the <rng:interleave> pattern. 10.31. Thecontactmandatory Statement This statementSHOULD NOT be used by the mapping since the output RELAX NG schemamayresult from multiple YANG modules created by different authors. The schema contains references to all input modules inappear as a substatement of 'leaf', 'choice' or 'anyxml' statement. If ARGUMENT is "true", theDublin Core elements <dc:source>,parent data node is mapped as mandatory, see Section11.34.9.1.1. As a substatement of 'choice', this statement is also mapped to the @nma:mandatory attribute which is added to PARENT. Theoriginal YANG modules arevalue of this attribute is theauthoritative sourcesargument of theauthorship information. 11.11.parent 'choice' statement. 10.32. Thecontainermax-elements StatementUsing the rules specified in Section 9.1.1, the mapping algorithm MUST determine whether theThis statementdefines an optional container, and if so, insert the <rng:optional> element and make it the new PARENT.is handled within 'leaf-list' or 'list' statements, see Section 10.28. 10.33. Thecontainer defined by thismin-elements Statement This statement is handled within 'leaf-list' or 'list' statements, see Section 10.28. 10.34. The module Statement This statement isthenmapped to an embedded <rng:grammar> pattern having the<rng: element> element, which becomes@nma:module attribute with the value of ARGUMENT. In addition, a <dc:source> element SHOULD be created as a child ofPARENTthis <rng: grammar> element andusescontain ARGUMENTwith prepended local namespace prefixas a metadata reference to thevalue of its @name attribute. Finally, using the rules specified ininput YANG module. See also Section9.1.2,10.49. Substatements of themapping algorithm'module' statement MUSTdetermine whetherbe mapped so that o statements representing configuration/state data are mapped to descendants of thecontainer is implicit, and if so, add<nma:data> element; o statements representing theattribute @nma:implicit withcontents of RPC requests or replies are mapped to descendants of thevalue "true"<nma:rpcs> element; o statements representing the contents of event notifications are mapped to descendants of the<rng:element><nma:notifications> element.11.12.10.35. Thedefaultmust StatementIf thisThis statement isa substatement of 'leaf', it ismapped to the@nma:default<nma:must> element. It has one mandatory attributeof PARENT and@assert (with no namespace) which contains ARGUMENTbecomes its value. Astransformed into asubstatement of 'typedef',valid XPath expression (see Section 9.3). The <nma:must> element may have other subelements resulting from mapping the'default''error-app-tag' and 'error-message' substatements. Other substatements of 'must', i.e., 'description' and 'reference', are ignored. EXAMPLE. YANG statementis also mapped to the @nma:default attribute within thevalue of ARGUMENT. The placement of this attribute depends on whether or not the type definition has"dhcp" module must 'current() <= ../max-lease-time' { error-message "The default-lease-time must be less than max-lease-time"; } is mapped to <nma:must assert="current()<=../dhcp:max-lease-time"> <nma:error-message> The default-lease-time must beexpanded when itless than max-lease-time </nma:error-message> </nma:must> 10.36. The namespace Statement This statement isused: o Ifmapped in two ways: 1. To thetype definition is not expanded, @nma:default becomes an@xmlns:PREFIX attribute of the<rng:define> pattern resulting fromroot <rng:grammar> element where PREFIX is theparent 'typedef' mapping. o Otherwise, @nma:defaultnamespace prefix specified by the sibling 'prefix' statement. ARGUMENT becomesan attributethe value of this attribute. 2. To theancestor RELAX NG pattern inside@ns attribute of PARENT, whichthe expansion takes place. Details andis anexample are given in Section 9.2.2. Finally, as a substatement of 'choice',embedded <rng: grammar> pattern. ARGUMENT becomes the'default'value of this attribute. 10.37. The notification Statement This statementidentifies the default case andishandled withinmapped to the'case' statement, see Section 11.7. Iffollowing subtree of thedefault case uses<nma: notifications> element in theshorthand notation wherehybrid schema (where PREFIX is the'case'prefix of the local YANG module): <nma:notification> <rng:element name="PREFIX:ARGUMENT"> ... </rng:element> </nma:notification> Substatements of 'notification' are mapped under <rng:element name="PREFIX:ARGUMENT">. 10.38. The ordered-by Statement This statement isomitted, the @nma:implicitmapped to @nma:ordered-by attributewithand ARGUMENT becomes the value"true"of this attribute. See Section 10.28 for an example. 10.39. The organization Statement This statement iseither attached to the node representingignored by thedefault case inmapping because theshorthand notation or, alternatively, an extra <rng:group> element MAYhybrid schema may beinserted and the @nma:implicit attribute attachedmapped from multiple YANG modules authored by different parties. The hybrid schema SHOULD contain references toit. In the latter case, the net result isall input modules in thesame as ifDublin Core <dc:source> elements, see Section 10.34. The original YANG modules are the'case' statement wasn't omitted forauthoritative sources of thedefault case. EXAMPLE.authorship information. 10.40. Thefollowing 'choice'output Statement This statementin a module with namespace prefix "yam" choice leaves { default feuille; leaf feuille { type empty; } leaf hoja { type empty; } }iseither mapped directly to <rng:choice> <rng:element name="yam:feuille" nma:implicit="true"> <rng:empty/> </rng:element> <rng:element name="yam:hoja"> <rng:empty/> </rng:element/> </rng:choice> orhandled within thedefault case may be wrapped in an extra <rng:group>: <rng:choice> <rng:group nma:implicit="true"> <rng:element name="yam:feuille"> <rng:empty/> </rng:element> </rng:group> <rng:element name="yam:hoja"> <rng:empty/> </rng:element/> </rng:choice> 11.13.'rpc' statement, see Section 10.50. 10.41. Thedescriptionpath Statement This statementMAY be ignored. Otherwise, itismapped to the DTD compatibility element <a:documentation> and ARGUMENT becomes its text. In order to get properly formatted in the RELAX NG compact syntax, this element SHOULD be inserted ashandled within thefirst child of PARENT. 11.14."leafref" type, see Section 10.53.7. 10.42. Thedeviationpattern Statement This statement isignored,handled within the "string" type, see Section8.5. 11.15.10.53.9. 10.43. Theenumposition Statement This statement ismapped to <rng:value> element and ARGUMENT becomes its text. All substatements except 'status' are ignored because the <rng:value> element cannot contain annotation elements, see [RNG], section 6. 11.16.ignored. 10.44. Theerror-app-tagprefix Statement This statement isignored unless it ishandled within the sibling 'namespace' statement, see Section 10.36, or within the parent 'import' statement, see Section 10.23. As a substatement of'must'. In'belongs-to' (in submodules), thelatter case it'prefix' statement ismapped to the <nma:error-app-tag> element. See also Section 11.35. 11.17.ignored. 10.45. Theerror-messagepresence Statement This statementis ignored unless it is a substatementinfluences the mapping of'must'. Inthelatter case it is mapped toparent container (Section 10.11): the<nma:error-message> element.parent container definition MUST be wrapped in <rng:optional>, regardless of its contents. See also Section11.35. 11.18.9.1.1. 10.46. Theextensionrange Statement This statement isignored. However, extensions to the YANG language MAY be mapped as described inhandled within numeric types, see Section9.4. 11.19.10.53.8. 10.47. Thefeaturereference Statement This statement MAY be ignored. Otherwise, it isignored, see Section 8.5. 11.20.mapped to <a:documentation> element and its text is set to ARGUMENT prefixed with "See: ". 10.48. Thegroupingrequire-instance Statement This statement ismapped to a RELAX NG named pattern definition <rng: define>, buthandled within "instance-identifier" type (Section 10.53.6). 10.49. The revision Statement The mapping uses onlyifthegrouping defined by this statement is used without refinements and augments in at least onemost recent instance of theinput modules. In this case,'revision' statement, i.e., one with thenamed pattern definition becomes a child oflatest date in ARGUMENT, which specifies the<rng:grammar> element and its name is ARGUMENT mangled according tocurrent revision of therules specified in Section 9.2. Whenever a grouping is usedinput YANG module [YANG]. This date SHOULD be recorded, together withadditional refinements and/or augments,thegrouping is expanded so thatname of therefinements and augments may be appliedYANG module, inplace totheprescribed schema nodes. Seecorresponding Dublin Core <dc:source> element (see Section9.2.110.34), forfurther details and an example. An implementation MAY offer the optionexample in this form: <dc:source>YANG module 'foo', revision 2010-03-02</dc:source> The 'description' substatement ofrecording all 'grouping' statements as named patterns'revision' is ignored. 10.50. The rpc Statement This statement is mapped to the following subtree in theoutputRELAX NG schemaeven if they are not referenced. This(where PREFIX isuseful for mappingthe prefix of the local YANG"library" modules containing only 'typedef' and/or 'grouping' statements. 11.21. The identity Statement This statement is not specifically mapped. However, if the identity defined by this statement is used as the base for an "identityref" type in any of the input modules, or is derived from this base, ARGUMENT will appear as the textmodule): <nma:rpc> <nma:input> <rng:element name="PREFIX:ARGUMENT"> ... mapped contents ofone'input' ... </rng:element> </nma:input> <nma:output"> ... mapped contents ofthe <rng:value> elements'output' ... </nma:output> </nma:rpc> As indicated in themappingschema fragment, contents ofthat "identityref" type. See Section 11.53.5 for more details and an example. 11.22. The if-feature Statement This statement is ignored, see Section 8.5. 11.23. The import Statement This statement is not specifically mapped. The module whose name is in ARGUMENT has to be parsed so thattheimporting module be able to use its top-level groupings and typedefs and also augment the data tree'input' substatement (if any) are mapped under <rng:element name="PREFIX: ARGUMENT">. Similarly, contents of theimported module.'output' substatement are mapped under <nma:output>. Ifthe 'import' statement has the 'revision'there is no 'output' substatement, thecorresponding revision of the imported module<nma:output> element MUST NOT beused.present. Themechanism for finding a given module revision<nma:rpc> element isoutside the scopea child ofthis document. 11.24.<nma:rpcs>. 10.51. Theincludestatus Statement This statement MAY be ignored. Otherwise, it isnot specifically mapped. The submodule whose name is in ARGUMENT hasmapped tobe parsed@nma: status attribute and ARGUMENT becomes itscontentsvalue. 10.52. The submodule Statement This statement is not specifically mapped. Its substatements are mappedexactlyas if they appeared directly in thesubmodule text was a subset of the mainmoduletext. If the 'include' statement has the 'revision' substatement, the corresponding revision ofthe submoduleMUST be used.belongs to. 10.53. Themechanism for finding a given submodule revision is outside the scope of this document. 11.25. The input Statement This statement is handled within 'rpc' statement, see Section 11.50. 11.26. The key Statement This statement is mapped to @nma:key attribute. ARGUMENT MUST be translated so that every key is prefixed with the namespace prefix of the local module. The result of this translation then becomes the value of the @nma:key attribute. 11.27. The leaftype StatementThis statement is mapped to the <rng:element> element and ARGUMENT with prepended local namespace prefix becomes the value of its @name attribute. A leaf is optional if there is no "mandatory true;" substatement and if the leaf is not declared among the keys ofMost YANG built-in datatypes have anenclosing list. The <rng:element> element then MUST be wrappedequivalent in<rng:optional>, except whenthe'leaf' statement is a child of the 'choice' statement and thus forms a shorthand case for that choice (see Section 9.1.1 for details). 11.28. The leaf-list Statement This statement is mapped to a block enclosed by either <rng: zeroOrMore> or <rng:oneOrMore> element depending on whether the argument of 'min-elements' substatement is "0" or positive, respectively (it is zero by default). This <rng:zeroOrMore> or <rng: oneOrMore> element becomes the PARENT. <rng:element> is then addedXSD datatype library [XSD-D] asa child element of PARENT and ARGUMENT with prepended local namespace prefix becomes theshown in Table 4. +-----------+---------------+--------------------------------+ | YANG type | XSD type | Meaning | +-----------+---------------+--------------------------------+ | int8 | byte | 8-bit integer valueof its @name attribute. If the 'leaf-list' statement has the 'min-elements' substatement and its argument is greater than one, additional attribute @nma:min-elements is attached to <rng:element> and the argument of 'min-elements' becomes the| | | | | | int16 | short | 16-bit integer value | | | | | | int32 | int | 32-bit integer value | | | | | | int64 | long | 64-bit integer value | | | | | | uint8 | unsignedByte | 8-bit unsigned integer value | | | | | | uint16 | unsignedShort | 16-bit unsigned integer value | | | | | | uint32 | unsignedInt | 32-bit unsigned integer value | | | | | | uint64 | unsignedLong | 64-bit unsigned integer value | | | | | | string | string | character string | | | | | | boolean | boolean | "true" or "false" | | | | | | binary | base64Binary | binary data in base64 encoding | +-----------+---------------+--------------------------------+ Table 4: YANG built-in datatypes with equivalents in the W3C XML Schema Type Library Two important datatypes ofthis attribute. Similarly, if there isthe'max-elements' substatementXSD datatype library - "dateTime" andits argument value is"anyURI" - are not"unbounded", attribute @nma:max-elements is attached to this elementbuilt-in types in YANG but instead are defined as derived types in the standard modules [Ytypes]: "date-and-time" in the "ietf-yang-types" module and "uri" in theargument of 'max-elements' becomes"ietf-inet-types" module. However, thevalue of this attribute. EXAMPLE. YANG leaf-listformal restrictions ina module with namespace prefix "yam" leaf-list foliage { min-elements 3; max-elements 6378; ordered-by user;the YANG typestring; } is mappeddefinitions are rather weak. Therefore, implementations of the YANG- to-DSDL mapping SHOULD detect these derived types in source YANG modules and map them to "dateType" and "anyURI", respectively. Details about the mapping of individual YANG built-in types are given in the followingRELAX NG fragment: <rng:oneOrMore> <rng:element name="yam:foliage" nma:ordered-by="user" nma:min-elements="3" nma:max-elements="6378"> <rng:data type="string"/> </rng:element> </rng:oneOrMore> 11.29.subsections. 10.53.1. Thelength Statementempty Type Thisstatementtype ishandled within the "string" type, see Section 11.53.9. 11.30.mapped to <rng:empty/>. 10.53.2. Thelist Statementboolean and binary Types These two built-in types do not allow any restrictions and are mapped simply by inserting <rng:data> element whose @type attribute is set to ARGUMENT mapped according to Table 4 above. 10.53.3. The bits Type Thisstatementtype is mappedexactly as the 'leaf-list' statement, see Section 11.28. When mappingto <rng:list> and for each 'bit' substatement thesubstatementsfollowing XML fragment is inserted as a child of'list',<rng:list>: <rng:optional> <rng:value>bit_name</rng:value> </rng:optional> where bit_name is theorder of childrenname of thelist element MUST be specified so that list keys, if there are any, always appear in the same orderbit asthey are definedfound in theinput YANG moduleargument of a 'bit' substatement. 10.53.4. The enumeration andbefore other children, see [YANG], Section 7.8.5. In particular, if any list keyunion Types These types are mapped to the <rng:choice> element. 10.53.5. The identityref Type This type isdefined in a grouping butmapped to thelist node itselffollowing named pattern reference: <rng:ref name="__PREFIX_BASE"/> where PREFIX:BASE isnot a partthe qualified name of thesame grouping, andidentity appearing in thepositionargument of the'uses' statement would violate the above ordering requirement, the grouping MUST be expanded, i.e., the 'uses' statement replaced by the grouping contents. For example, consider'base' substatement. For example, assume that module "des" in Section 10.21 contains the followingYANG fragment of a module with prefix "yam": grouping keygrp {leafclef { type uint8; } } list foo { key clef;definition: leafbarfoo { typestring; } leaf bazidentityref {type string;base crypto:crypto-alg; }uses keygrp;}isThis leaf would then be mapped to the followingRELAX NG fragment: <rng:zeroOrMore> <rng:element name="yam:foo" nma:key="yam:clef"> <rng:element name="yam:clef"> <rng:data type="unsignedByte"/> </rng:element> <rng:interleave> <rng:element name="yam:bar"> <rng:data type="string"/> </rng:element> <rng:element name="yam:baz"> <rng:data type="string"/> </rng:element> </rng:interleave> </rng:element> </rng:zeroOrMore> Note that the "keygrp" grouping is expanded and the "yam:clef" definition moved before the <rng:interleave> pattern. 11.31. The mandatory Statement This statement may appear as a substatement of 'leaf', 'choice' or 'anyxml' statement. If ARGUMENT is "true", the parent data node is mapped as mandatory, see Section 9.1.1. 11.32. The max-elements Statement This statement is handled within 'leaf-list' or 'list' statements, see Section 11.28. 11.33. The min-elements Statement This statement is handled within 'leaf-list' or 'list' statements, see Section 11.28. 11.34.element pattern: <element name="des:foo"> <ref name="__crypto_crypto-alg"/> </element> 10.53.6. Themodule Statementinstance-identifier Type Thisstatementtype isnot specificallymappedexcept that a <dc:source>to <rng:data> elementSHOULDwith @type attribute set to "string". In addition, an empty <nma:instance-identifier> element MUST becreatedinserted as a child of<rng:grammar> and contain ARGUMENT as a reference toPARENT. The argument of theinput YANG module. See also Section 11.49. With respect to'require-instance' substatement, if it exists, becomes theconceptual tree schema, substatementsvalue of'module' MUST bethe @require-instance attribute of the <nma: instance-identifier> element. 10.53.7. The leafref Type This type is mappedso that o top level data elements be definedexactly asdescendantsthe type of the<nmt:top> element; o elements mapped from 'rpc' statements be defined as descendantsleaf given in the argument of 'path' substatement. However, if the<nmt:rpc-methods> element; o elements mapped from 'notification' statements be defined as descendantstype of the<nmt:notifications> element. 11.35. The must Statement This statement is mapped toreferred leaf defines a default value, this default value MUST be ignored by the<nma:must> element. It has one mandatorymapping. In addition, @nma:leafref attribute@assert (with no namespace), which contains ARGUMENT transformed into a valid XPath expression (see Section 9.3). The <nma:must> element may get other subelements resulting from mapping 'error-app-tag' and 'error-message' substatements. Other substatements of 'must', i.e., 'description' and 'reference', are ignored. EXAMPLE. YANG statement must 'current() <= ../max-lease-time' { error-message "The default-lease-time mustMUST beless than max-lease-time"; } is mappedadded to<nma:must assert="current()<=../dhcp:max-lease-time"> <nma:error-message> The default-lease-time must be less than max-lease-time </nma:error-message> </nma:must> 11.36.PARENT. Thenamespace Statement This statement is mapped to @xmlns:xxx attributeargument of the<rng:grammar> element where "xxx"'path' substatement, translated according to Section 9.3, isthe namespace prefix specified by the sibling 'prefix' statement. ARGUMENT becomesset as the value of this attribute.11.37.10.53.8. Thenotification Statement This statement is mapped to the following subtree in the RELAX NG schema ("yam" is the prefix of the localnumeric Types YANGmodule): <rng:element name="nmt:notification"> <rng:element name="yam:ARGUMENT"> ... </rng:element> </rng:element> Substatements of 'notification'built-in numeric types are "int8", "int16", "int32", "int64", "uint8", "uint16", "uint32", "uint64" and "decimal64". They are mappedunder <rng:element name="yam:ARGUMENT">. The <rng:element name="nmt:rpc-notification">to <rng:data> element with @type attribute set to ARGUMENT translated according to Table 4 above. An exception isa child of <rng:element name="nmt:notifications">. 11.38. The ordered-by Statement This statementthe "decimal64" type, which is mapped to@nma:ordered-by attribute and ARGUMENT becomesthevalue"decimal" type ofthis attribute. See Section 11.28 for an example. 11.39. The organization Statement This statement is not used bythemapping sinceXSD datatype library. Its precision and number of fractional digits are controlled with theoutput conceptual tree schema may result from multiple YANG modules authored by different parties. The schema contains referencesfollowing facets, which MUST always be present: o "totalDigits" facet set toall input modules intheDublin Core elements <dc:source>, see Section 11.34. The original modules arevalue of 19. o "fractionDigits" facet set to theauthoritative sourcesargument of theauthorship information. 11.40. The output Statement This statement is handled within 'rpc' statement, see Section 11.50. 11.41. The path Statement This statement is handled within "leafref" type, see Section 11.53.7. 11.42. The pattern Statement This statement is handled within "string" type, see Section 11.53.9. 11.43. The position Statement This statement is ignored. 11.44.'fraction- digits' substatement. Theprefix Statement This statement is handled within the sibling 'namespace' statement, see Section 11.36, or withinfixed value of "totalDigits" corresponds to theparent 'import' statement, see Section 11.23. As a substatementmaximum of'belongs-to' (in submodules),19 decimal digits for 64-bit integers. For example, the'prefix' statement is ignored. 11.45. The presence Statement Thisstatement type decimal64 { fraction-digits 2; } is mapped to theannotation attribute @nma:presence withfollowing RELAX NG datatype: <rng:data type="decimal"> <rng:param name="totalDigits">19</rng:param> <rng:param name="fractionDigits">2</rng:param> </rng:data> All numeric types support thevalue "true". In addition,'range' restriction, which is mapped as follows: If the range expression consists of just a single range LO..HI, then itinfluencesis mapped to a pair of datatype facets <rng:param name="minInclusive">LO</rng:param> and <rng:param name="maxInclusive">HI</rng:param> If themappingrange consists of'container' (Section 11.11):a single number, theparent container definition MUST be wrapped in <rng:optional>, regardlessvalues ofits content. See also Section 9.1.1. 11.46. The range Statement This statement is handled within numeric types, see Section 11.53.8. 11.47. The reference Statement This statement MAY be ignored. Otherwise, itboth facets are set to this value. If LO ismappedequal to<a:documentation> element and its textthe string "min", the "minInclusive" facet issetomitted. If HI is equal toARGUMENT prefixed with "See: ". 11.48. The require-instance Statement This statementthe string "max", the "maxInclusive" facet ishandled within "instance-identifier" type (Section 11.53.6). 11.49. The revision Statement The mapping uses onlyomitted. If themost recent instance ofrange expression has multiple parts separated by "|", then the'revision' statement, i.e.,parent <rng:data> element must be repeated once for every range part and all such <rng:data> elements are wrapped in <rng:choice> element. Each <rng:data> element contains the "minInclusive" and "maxInclusive" facets for onewithpart of thelatest daterange expression as described inARGUMENT, which specifiesthecurrent revision ofprevious paragraph. For theinput YANG module [YANG]. This date SHOULD be recorded, together with"decimal64" type, thename"totalDigits" and "fractionDigits" must be repeated inside each of theYANG module, in<rng:data> elements. For example, type int32 { range "-6378..0|42|100..max"; } is mapped to thecorresponding Dublin Core element <dc:source> (seefollowing RELAX NG fragment: <rng:choice> <rng:data type="int"> <rng:param name="minInclusive">-6378</rng:param> <rng:param name="maxInclusive">0</rng:param> </rng:data> <rng:data type="int"> <rng:param name="minInclusive">42</rng:param> <rng:param name="maxInclusive">42</rng:param> </rng:data> <rng:data type="int"> <rng:param name="minInclusive">100</rng:param> </rng:data> </rng:choice> See Section11.34),9.2.2 forexample in this form: <dc:source>YANG module 'foo', revision 2010-03-02</dc:source> The 'description' substatement of 'revision' is ignored. 11.50.further details on mapping the restrictions. 10.53.9. Therpc Statementstring Type Thisstatementtype is mapped to <rng:data> element with thefollowing subtree in the RELAX NG schema ("yam" is@type attribute set to "string". The 'length' restriction is handled analogically to theprefix of'range' restriction for thelocal YANG module): <rng:element name="nmt:rpc-method"> <rng:element name="nmt:input"> <rng:element name="yam:ARGUMENT"> ... mapped content of 'input' ... </rng:element> </rng:element> <rng:element name="nmt:output"> ... mapped contentnumeric types (Section 10.53.8): If the length expression has just a single range, then o if the length range consists of'output' ... </rng:element> </rng:element> As indicated ina single number LENGTH, theschema fragment, contentsfollowing datatype facet is inserted: <rng:param name="length">LENGTH</rng:param>. o Otherwise the length range is of the'input' substatement (if any) are mapped under <rng:element name="yam: ARGUMENT">. Similarly, contentsform LO..HI, i.e., it consists of both the'output' substatementlower and upper bound. The following two datatype facets aremapped under <rng:element name="nmt:output">.then inserted: <rng:param name="minLength">LO</rng:param> and <rng:param name="maxLength">HI</rng:param> IfthereLO isno 'output' substatement,equal to the<rng:element name="nmt:output"> MUST NOT be present. The <rng:element name="nmt:rpc-method"> elementstring "min", the "minLength" facet isa childomitted. If HI is equal to the string "max", the "maxLength" facet is omitted. If the length expression has of<rng:multiple parts separated by "|", then the parent <rng:data> elementname="nmt:rpc-methods">. 11.51. The status Statement This statement MAYmust beignored. Otherwise, it is mapped to @nma: status attributerepeated once for every range part andARGUMENT becomes its value. 11.52. The submodule Statement This statement is not specifically mapped. Its substatementsall such <rng:data> elements aremapped as if they appeared directlywrapped in <rng:choice> element. Each <rng:data> element contains themodule"length" or "minLength" and "maxLength" facets for one part of thesubmodule belongs to. 11.53. The type Statement Most YANG built-in datatypes have an equivalentlength expression as described in theXSDprevious paragraph. Every 'pattern' restriction of the "string" datatypelibrary [XSD-D] as shown in Table 3. +-----------+---------------+--------------------------------+ | YANG type | XSD type | Meaning | +-----------+---------------+--------------------------------+ | int8 | byte | 8-bit integer value | | | | | | int16 | short | 16-bit integer value | | | | | | int32 | int | 32-bit integer value | | | | | | int64 | long | 64-bit integer value | | | | | | uint8 | unsignedByte | 8-bit unsigned integer value | | | | | | uint16 | unsignedShort | 16-bit unsigned integer value | | | | | | uint32 | unsignedInt | 32-bit unsigned integer value | | | | | | uint64 | unsignedLong | 64-bit unsigned integer value | | | | | | string | string | character string | | | | | | boolean | boolean | "true" or "false" | | | | | | binary | base64Binary | binary data in base64 encoding | +-----------+---------------+--------------------------------+ Table 3: YANG built-in datatypesis mapped to the "pattern" facet <rng:param name="pattern">...</rng:param> withequivalents intext equal to theW3C XML Schema Type Library Two important datatypesargument of theXSD datatype library - "dateTime" and "anyURI" - are not built-in in YANG but defined as derived types in the standard modules [Ytypes]: "date-and-time" in the "ietf-yang- types" module and "uri" in the "ietf-inet-types" module. However, the formal restrictions in the YANG type definitions are rather weak. Therefore, implementations'pattern' statement. All such "pattern" facets must be repeated inside each copy of theYANG-to-DSDL mapping SHOULD detect these derived types in source YANG modules and map them to "dateType" and "anyURI", respectively. Details about the mapping of individual YANG built-in types are given in the following subsections. 11.53.1. The empty Type This type is mapped to <rng:empty/>. 11.53.2. The boolean and binary Types These two built-in types do not allow any restrictions and are mapped simply by inserting<rng:data>element whose @type attribute is set to ARGUMENT mapped according to Table 3 above. 11.53.3. The bits Type Thiselement, i.e., once for each length range. For example, type string { length "1|3..8"; pattern "[A-Z][a-z]*"; } is mapped to<rng:list> and for each 'bit' substatementthe followingXML fragment is inserted asRELAX NG fragment: <rng:choice> <rng:data type="string"> <rng:param name="length">1</rng:param> <rng:param name="pattern">[A-Z][a-z]*</rng:param> </rng:data> <rng:data type="string"> <rng:param name="minLength">3</rng:param> <rng:param name="maxLength">8</rng:param> <rng:param name="pattern">[A-Z][a-z]*</rng:param> </rng:data> </rng:choice> 10.53.10. Derived Types If the 'type' statement refers to achild of <rng:list>: <rng:optional> <rng:value>bit_name</rng:value> </rng:optional> where bit_namederived type, it isthe namemapped in one of thebitfollowing ways depending on whether it contains any restrictions asfound in the argument ofits substatements: 1. Without restrictions, thecorresponding 'bit' statement. 11.53.4. The enumeration and union Types These types are mapped to <rng:choice> element. 11.53.5. The identityref Type This type'type' statement is mapped simply to<rng:choice> element with one or more <rng: value> subelements. Each ofthe<rng:value> subelements MUST have<rng:ref> element, i.e., a reference to a named pattern. If the@type attribute and its value setRELAX NG definition of this named pattern has not been added to"QName". One <rng:value> subelement forthebase identityhybrid schema yet, the corresponding type definition MUSTalwaysbepresent - it contains the argumentfound and its mapping installed as a subelement of either the'base' substatement as its text. In addition, one <rng:value> substatement MUST be added for each identity declared locallyroot orinanimported module that isembedded <rng:grammar> element, see Section 10.54. Even if a given derivedfrom this base identity. All namespace prefixes that aretype is usedfor identities from imported modules MUST be appropriately defined. EXAMPLE (taken from Section 7.16.3 of [YANG]). Considermore than once in thefollowing twoinput YANGmodules: module crypto-base { namespace "http://example.com/crypto-base"; prefix "crypto"; identity crypto-alg { description "Base identity from which all crypto algorithms are derived."; } } module des { namespace "http://example.com/des"; prefix "des"; import "crypto-base" { prefix "crypto"; } identity des { base "crypto:crypto-alg"; description "DES crypto algorithm"; } identity des3 { base "crypto:crypto-alg"; description "Triple DES crypto algorithm"; } }modules, the mapping of the corresponding 'typedef' MUST be installed only once. 2. Ifthese two modulesany restrictions areimported to another module with namespace prefix "yam", leaf definition leaf crypto {present, the ancestor built-in typeidentityref { base "crypto:crypto-alg"; } } is mapped to <rng:element name="yam:crypto"> <rng:choice> <rng:value type="QName">crypto:crypto-alg</value> <rng:value type="QName">des:des</value> <rng:value type="QName">des:des3</value> </rng:choice> </rng:element> The "crypto" and "des" prefixes will typicallyfor the given derived type must bedefined via attributes ofdetermined and the<rng:grammar> element. 11.53.6. The instance-identifier Type Thismapping of this base typeis mapped to <rng:data> element with @type attribute set to "string". In addition, empty <nma:instance-identifier> elementMUST beinserted as a child of PARENT. The argumentused. Restrictions appearing at all stages of the'require-instance' substatement, if it exists, becomestype derivation chain MUST be taken into account and their conjunction added to thevalue of<rng:data> element which defines the@require-instance attribute of <nma: instance-identifier>. 11.53.7.basic type. See Section 9.2.2 for more details and an example. 10.54. Theleafref Typetypedef Statement Thistypestatement is mappedexactly asto a RELAX NG named pattern definition <rng: define>, but only if the typeof the leaf givendefined by this statement is used without restrictions inthe argumentat least one of'path' substatement.the input modules. Inaddition, @nma:leafref attribute MUST be added to PARENT. The argumentthis case, the named pattern definition becomes a child of either the'path' substatement, translated according to Section 9.3, is set asroot or an embedded <rng:grammar> element, depending on whether thevalue'typedef' statement appears at the top level ofthis attribute. 11.53.8. The numeric Typesa YANGbuilt-in numeric types are "int8", "int16", "int32", "int64", "uint8", "uint16", "uint32", "uint64" and "decimal64". They are mapped to <rng:data> element with @type attributemodule or not. The name of this named pattern definition is set to ARGUMENTtranslatedmangled according toTable 3 above. An exception isthe"decimal64" type, whichrules specified in Section 9.2. Whenever a derived type ismapped toused with additional restrictions, the"decimal"ancestor built-in typeoffor theXSD datatype library. Its precision and number of fractional digits are controlledderived type is used instead withthe following facets, which MUST always be present: o "totalDigits" facet set to the value of 19. o "fractionDigits" facet set to the argumentrestrictions (facets) that are a combination of all restrictions specified along the'fraction- digits' substatement. The fixed value of "totalDigits" corresponds totype derivation chain. See Section 10.53.10 for further details and an example. An implementation MAY offer themaximumoption of19 decimal digits for 64-bit integers. For example,recording all 'typedef' statements as named patterns in the output RELAX NG schema even if they are not referenced. This is useful for mapping YANG "library" modules containing only 'typedef' and/or 'grouping' statements. 10.55. The unique Statement This statementtype decimal64 { fraction-digits 2; }is mapped tothe following RELAX NG datatype: <rng:data type="decimal"> <rng:param name="totalDigits">19</rng:param> <rng:param name="fractionDigits">2</rng:param> </rng:data> All numeric types support the 'range' restriction, which@nma:unique attribute. ARGUMENT MUST be translated so that every node identifier in each of its components ishandled as follows: If the range expression has just a single range, then o ifprefixed with therange consistsnamespace prefix ofa single number,the<rng:value> pattern is inserted and its content set to this number. o Otherwiselocal module, unless therange consistsprefix is already present. The result ofboth lower and upper bound andthis translation then becomes thefollowing pairvalue ofdatatype facets are inserted: <rng:param name="minInclusive">...</rng:param> and <rng:param name="maxInclusive">...</rng:param> Their contents arethelower and upper bound, respectively. If@nma:unique attribute. For example, assuming that thelower boundlocal module prefix is"min","ex", unique "foo ex:bar/baz" is mapped to the"minInclusive" facetfollowing attribute/value pair: nma:unique="ex:foo ex:bar/ex:baz" 10.56. The units Statement This statement isomittedmapped to @nma:units attribute andif the upper boundARGUMENT becomes its value. Implementations MAY ignore this statement. 10.57. The uses Statement If this statement has neither 'refine' nor 'augment' substatements, it is"max",mapped to <rng:ref> element, i.e., a reference to a named pattern, and the"maxInclusive" facetvalue of its @name attribute isomitted.set to ARGUMENT mangled according to Section 9.2. If therange expressionRELAX NG definition of the referenced named pattern hasmultiple parts separated by "|", thennot been added to theparent <rng:data> element musthybrid schema yet, the corresponding grouping MUST berepeated once for every range partfound andall such <rng:data> elements are wrapped in <rng:choice> element. Each <rng:data> element containsits mapping installed as a subelement of <rng:grammar>, see Section 10.20. Otherwise, if the<rng:value> pattern'uses' statement has any 'refine' or 'augment' substatements, the"minInclusive"corresponding grouping must be looked up and"maxInclusive" facetsits contents inserted under PARENT. See Section 9.2.1 forone part of the range expression as described in the previous paragraph. For the "decimal64" type, the "totalDigits"further details and"fractionDigits" must be repeated inside each of the <rng:data> elements. For example, type int32 { range "-6378..0|42|100..max"; }an example. 10.58. The value Statement This statement is ignored. 10.59. The when Statement This statement is mapped tothe following RELAX NG fragment: <rng:choice> <rng:data type="int"> <rng:param name="minInclusive">-6378</rng:param> <rng:param name="maxInclusive">0</rng:param> </rng:data> <rng:data type="int"> <rng:value>42</rng:value> </rng:data> <rng:data type="int"> <rng:param name="minInclusive">100</rng:param> </rng:data> </rng:choice> 11.53.9.@nma:when attribute and ARGUMENT, translated according to Section 9.3, becomes it value. 10.60. Thestring Typeyang-version Statement Thistypestatement is not mapped to<rng:data> elementthe output schema. However, an implementation SHOULD check that it is compatible with the@type attribute set to "string".YANG version declared by the statement (currently version 1). 10.61. The'length' restrictionyin-element Statement This statement ishandled analogicallynot mapped to the'range' restriction foroutput schema, but see thenumeric types (Section 11.53.8): Ifrules for extension handling in Section 9.4. 11. Mapping thelength expression has just a single range, then o ifHybrid Schema to DSDL As explained in Section 6, thelength range consistssecond step ofa single number L,thefollowing datatype facetYANG-to-DSDL mapping takes the hybrid schema and transforms it to various DSDL schemas capable of validating instance XML documents. As an input parameter, this step takes, in the simplest case, just a specification of the NETCONF XML document type that isinserted: <rng:param name="length">L</rng:param>. o Otherwiseto be validated. These document types can be, for example, thelength range consistscontents ofboth lowera datastore, a reply to <nc:get> or <nc:get-config>, contents of other RPC requests/replies andupper boundevent notifications, and so on. In general, the second mapping step has to accomplish the followingpair of datatype facets are inserted: <rng:param name="minLength">...</rng:param> and <rng:param name="maxLength">...</rng:param> Their contents arethree tasks: 1. Extract thelower and upper boundparts of thelength range, respectively. If the lower bound is "min",hybrid schema that are appropriate for the"minLength" facet is omitted andrequested document type. For example, ifthe upper bound is "max", the "maxLength" faceta <nc:get> reply isomitted. Ifto be validated, thelength expressionsubtree under <nma:data> hasof multiple parts separated by "|", then the parent <rng:data> elementto be selected. 2. The schema must berepeated onceadapted to the specific encapsulating XML elements mandated by the RPC layer. These are, forevery range partexample, <nc: rpc> andall such <rng:data><nc:data> elementsare wrappedin<rng:choice> element. Each <rng:data> element containsthe"length"case of a <nc:get> reply or"minLength" and "maxLength" facets<en:notification> for a notification. 3. Finally, NETMOD-specific annotations that are relevant forone part of the length expression as described intheprevious paragraph. Every 'pattern' restrictionschema language of the"string" datatype isgenerated schema must be mapped to the"pattern" facet <rng:param name="pattern">...</rng:param> with content equal to the argument of the 'pattern' statement. All such "pattern" facets mustcorresponding patterns or rules. These three tasks are together much simpler than the first mapping step and can berepeated inside each copyeffectively implemented using XSL transformations [XSLT]. The following subsections describe the details of the<rng: data> element, i.e., oncesecond mapping step foreach length range. For example, type string { length "1|3..8"; pattern "[A-Z][a-z]*"; } is mapped tothefollowingindividual DSDL schema languages. Section 12 then contains a detailed specification for the mapping of all NETMOD- specific annotations. 11.1. Generating RELAX NGfragment: <rng:choice> <rng:data type="string"> <rng:param name="length">1</rng:param> <rng:param name="pattern">[A-Z][a-z]*</rng:param> </rng:data> <rng:data type="string"> <rng:param name="minLength">3</rng:param> <rng:param name="maxLength">8</rng:param> <rng:param name="pattern">[A-Z][a-z]*</rng:param> </rng:data> </rng:choice> 11.53.10. DerivedSchemas for Various Document TypesIf the 'type' statement refers to a derived type, it is mapped inWith oneof the following ways depending on whether it contains any restrictions as its substatements: 1. Without restrictions, the 'type' statement is mapped simply to the <rng:ref> element, i.e., a reference tominor exception, obtaining anamed pattern. If thevalidating RELAX NGdefinition of this named pattern has not been added toschema from theoutputhybrid schemayet,only means taking appropriate parts of thecorresponding type definition MUST be foundhybrid schema andits mapping installed asassembling them in asubelementnew RELAX NG grammar, perhaps after removing all unwanted annotations. The structure of<rng: grammar>, see Section 11.54. Even if a given derived typethe resulting RELAX NG schema isused more than once insimilar to that of the hybrid schema: The root grammar contains embedded grammars, one for each input YANGmodules, the mappingmodule. However, as explained in Section 8.2, global named pattern definitions (children of thecorresponding 'typedef'root <rng:grammar> element) MUST beinstalled only once. 2. If any restrictions are present, the ancestor built-in type formoved to a separate schema file. Depending on thegiven derivedXML document typemust be determined andthat is themapping of this base typetarget for validation, such as <nc:get>/<nc:get-config> reply, RPC operations or notifications, patterns defining corresponding top-level information items MUST beused. Restrictions appearing at all stages ofadded, such as <nc:rpc-reply> with thetype derivation chain MUST be taken into account@message-id attribute andtheir conjunction addedso on. In order tothe <rng:data> element which defines the basic type. See Section 9.2.2avoid copying common named pattern definitions formore detailscommon NETCONF elements andan example. 11.54. The typedef Statement This statement is mappedattributes toaevery single output RELAX NGnamed pattern definition <rng: define>, but only if the type defined by this statement is used without restrictionsfile, such schema-independent definitions SHOULD be collected inat least one of the input modules. In this case, the named pattern definition becomesachild of the <rng: grammar> element and its namelibrary file which isARGUMENT mangled according tothen included by therules specified in Section 9.2. Whenevervalidating RELAX NG schemas. Appendix B has the listing of such aderived typelibrary file. The minor exception mentioned above isused with additional restrictions,theancestor built-in type forannotation @nma:config, which must be observed if thederivedtarget document type isused instead with restrictions (facets) that areacombinationreply to <nc: get-config>. In this case, each element definition that has this attribute with the value ofall restrictions specified along"false" MUST be removed from thetype derivation chain.schema together with its descendants. See Section11.53.1012.1 forfurther detailsmore details. 11.2. Mapping Semantic Constraints to Schematron Schematron schemas tend to be much flatter andan example. An implementation MAY offermore uniform compared to RELAX NG. They have exactly four levels of XML hierarchy: <sch: schema>, <sch:pattern>, <sch:rule> and <sch:assert> or <sch:report>. In a Schematron schema generated by theoptionsecond mapping step, the basic unit ofrecording all 'typedef' statements as named patterns inorganization is a rule represented by theoutput RELAX NG<sch:rule> element. The following NETMOD-specific annotations from the hybrid schemaeven if they(henceforth called "semantic annotations") arenot referenced. This is useful for mappingmapped to corresponding Schematron rules: <nma:must>, @nma:key, @nma:unique, @nma:max-elements, @nma:min-elements, @nma:when, @nma:leafref, @nma: leaf-list, and also @nma:mandatory appearing as an attribute of <rng: choice> (see Section 11.2.1). Each input YANG"library" modules containing only 'typedef' and/or 'grouping' statements. 11.55. The unique Statement This statementmodule is mapped to@nma:unique attribute. ARGUMENT is translated so that every node identifier in each of its componentsa Schematron pattern whose @id attribute isprefixed withset to thenamespace prefixmodule name. Every <rng:element> pattern containing at least one of thelocal module, unless the prefixabove-mentioned semantic annotations isalready present.then mapped to a Schematron rule: <sch:rule context="XELEM"> ... </sch:rule> Theresultvalue ofthis translation then becomesthevaluemandatory @context attribute of <sch:rule> (denoted as XELEM) MUST be set to the@nma:unique attribute. For example, assuming thatabsolute path of thelocal module prefix is "ex", unique "foo ex:bar/baz" is mapped tocontext element in thefollowing attribute/value pair: nma:unique="ex:foo ex:bar/ex:baz" 11.56. The units Statement This statement is mapped to @nma:units attribute and ARGUMENT becomes its value. Implementations MAY ignore this statement. 11.57.data tree. Theuses Statement If this statement has neither 'refine' nor 'augment' substatements, it is mapped to <rng:ref> element, i.e., a reference to<sch:rule> element contains the mappings of all contained semantic annotations in the form of Schematron asserts or reports. Semantic annotations appearing inside a namedpattern, andpattern definition (i.e., having <rng:define> among its ancestors) require special treatment because they may be potentially used in different contexts. This is accomplished by using Schematron abstract patterns that use the "$pref" variable in place of the local namespace prefix. The value ofits @namethe @id attributeisof such an abstract pattern MUST be set toARGUMENT mangled according to Section 9.2. IftheRELAX NG definitionname of thereferencednamed patternhas not been added todefinition which is being mapped (i.e., theoutput schema yet,mangled name of thecorresponding groupingoriginal YANG grouping). When the abstract pattern is instantiated, the values of the following two parameters MUST befound and its mapping installed as a subelement of <rng:grammar>, see Section 11.20. Otherwise, ifprovided: o pref: the'uses' statement has any 'refine' or 'augment' substatements,actual namespace prefix, o start: XPath expression defining the context in which thecorrespondinggroupingmust be looked up and its contents is inserted under PARENT. See Section 9.2.1 for further details and an example. 11.58. The value Statement This statementisignored. 11.59.used. EXAMPLE. Consider the following YANG module: module example4 { namespace "http://example.com/ns/example4"; prefix ex4; uses sorted-leaf-list; grouping sorted-leaf-list { leaf-list sorted-entry { must "not(preceding-sibling::sorted-entry > .)" { error-message "Entries must appear in ascending order."; } type uint8; } } } Thewhen Statement This statement is mapped to @nma:when attribute and ARGUMENT, translated accordingresulting Schematron schema for a reply toSection 9.3, becomes it value. 11.60. The yang-version Statement This statement<nc:get> isnot mapped tothen as follows: <?xml version="1.0" encoding="utf-8"?> <sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron"> <sch:ns uri="http://example.com/ns/example4" prefix="ex4"/> <sch:ns uri="urn:ietf:params:xml:ns:netconf:base:1.0" prefix="nc"/> <sch:pattern abstract="true" id="_example4__sorted-leaf-list"> <sch:rule context="$start/$pref:sorted-entry"> <sch:report test=". = preceding-sibling::$pref:sorted-entry"> Duplicate leaf-list entry "<sch:value-of select="."/>". </sch:report> <sch:assert test="not(preceding-sibling::$pref:sorted-entry > .)"> Entries must appear in ascending order. </sch:assert> </sch:rule> </sch:pattern> <sch:pattern id="example4"/> <sch:pattern id="id2573371" is-a="_example4__sorted-leaf-list"> <sch:param name="start" value="/nc:rpc-reply/nc:data"/> <sch:param name="pref" value="ex4"/> </sch:pattern> </sch:schema> The "sorted-leaf-list" grouping from theoutput schema. However, an implementation SHOULD check that itinput module iscompatiblemapped to an abstract pattern with an @id value of "_example4__sorted-leaf-list" in which theYANG version declared by the'must' statement(currently version 1). 11.61.corresponds to the <sch:assert> element. Theyin-element Statement This statementabstract pattern isnot mapped totheoutput schema, but seeinstantiated by therules for extension handling in Section 9.4. 12. Mapping NETMOD-specific annotationspattern with an @id value of "id2802112" which sets the "start" and "pref" parameters toDSDL Schema Languages This section contains mapping specificationappropriate values. Note that another Schematron element, <sch:report>, was automatically added, checking forindividual NETMOD- specific annotations. In each case,duplicate leaf-list entries. The mapping from theresulthybrid schema to Schematron proceeds in the following steps: 1. First, the active subtree(s) of themappinghybrid schema must beinserted into an appropriate context ofselected depending on the requested targetDSDL schema as described in Section 10. The contextdocument type. This procedure isdetermined by the element definition in the conceptual tree schemaidentical towhichtheannotation is attached. InRELAX NG case, including theresthandling ofthis section, we will denote CONTELEM@nma:config if thenametarget document type is <nc:get- config> reply. 2. Namespaces ofthis context element properly qualifiedall input YANG modules, together withits namespace prefix. Unless otherwise stated, Schematron asserts are descendantsthe namespaces of base NETCONF ("nc" prefix) or notifications ("en" prefix) MUST be declared using the"standard"<sch:ns> element, for example <sch:ns uri="http://example.com/ns/example4" prefix="ex4"/> 3. One patternand therefore active in both validation phases. 12.1. The @nma:config Annotation If thisis created for every input module. In addition, an abstract pattern is created for every named pattern definition containing one or more semantic annotations. 4. A <sch:rule> element is created for each element pattern containing semantic annotations. 5. Every such annotation ispresent withthen mapped to an <sch:assert> or <sch: report> element which is installed as a child of thevalue "false",<sch:rule> element. 11.2.1. Constraints on Mandatory Choice In order to fully represent thefollowing rules MUST be observed for DSDL schemassemantics of<nc:get-config> reply: o When generating RELAX NG,YANG's 'choice' statement with thecontents of"mandatory true;" substatement, theCONTELEM definition MUST be changedRELAX NG grammar has to<rng:notAllowed>. o When generatingbe combined with a special Schematronor DSRL,rule. EXAMPLE. Consider theCONTELEM definition andfollowing module: module example5 { namespace "http://example.com/ns/example5"; prefix ex5; choice foobar { mandatory true; case foo { leaf foo1 { type uint8; } leaf foo2 { type uint8; } } leaf bar { type uint8; } } } In this module, allits descendantsthree leaf nodes in both case branches are optional but because of theconceptual tree schema MUST"mandatory true;" statement, at least one of them must beignored. 12.2. The @nma:default Annotation This annotation is used for generating the DSRL schema as describedpresent inSection 10.4. 12.3.a valid configuration. The@nma:implicit Annotation This annotation'choice' statement from this module isused for generatingmapped to theDSRL schema as described in Section 10.4. 12.4. The <nma:error-app-tag> Annotation This annotation currently has no mapping defined. 12.5. The <nma:error-message> Annotation This annotation is handled within <nma:must>, see Section 12.11. 12.6. The <nma:instance-identifier> Annotation If this annotation element hasfollowing fragment of the@require-instance attribute withRELAX NG schema: <rng:choice> <rng:interleave> <rng:optional> <rng:element name="ex5:foo1"> <rng:data type="unsignedByte"/> </rng:element> </rng:optional> <rng:optional> <rng:element name="ex5:foo2"> <rng:data type="unsignedByte"/> </rng:element> </rng:optional> </rng:interleave> <rng:element name="ex5:bar"> <rng:data type="unsignedByte"/> </rng:element> </rng:choice> In thevalue "false", it is ignored. Otherwise it is mapped tosecond case branch, thefollowing Schematron assert: <sch:assert test="nmf:evaluate(.)"> The"ex5:bar" elementpointed to by "CONTELEM" must exist. </sch:assert> The nmf:evaluate() functionisan XSLT extension function (see Extension Functions in [XSLT])defined as mandatory so thatevaluates an XPath expression at runtime. Such an extension function is provided by some XSLT processors, for example Saxon [3]. 12.7. The @nma:key Annotation Assumethisannotation attribute has the value "k_1 k_2 ... k_n", i.e., specifies n children of CONTELEM as list keys. The annotation is then mapped to the following Schematron report: <sch:report test="CONDITION"> Duplicate key of list "CONTELEM" </sch:report> where CONDITION haselement must be present in a valid configuration if thisform: preceding-sibling::CONTELEM[C_1 and C_2 and ... and C_n] Each sub-expression C_i, for i=1,2,...,n, specifies the condition for violation of uniqueness of key k_i, namely k_i=current()/k_i 12.8. The @nma:leafref Annotation This annotationbranch ismapped toselected. However, thefollowing assert: <sch:assert test="PATH=."> Leafref "CONTELEM" must havetwo elements in thesame valuefirst branch "foo" cannot be both declared as"PATH" </sch:assert> where PATH is the valuemandatory since each of@nma:leafref. The assert isthem alone suffices for adescendantvalid configuration. As a result, the above RELAX NG fragment would successfully validate configurations where none of the"ref-integrity" pattern,three leaf elements are present. Therefore, mandatory choices, whichmeans that it willcan beused only forrecognized in the"full" validation phase. 12.9. The @nma:min-elements Annotation This annotation is mapped tohybrid schema as <rng:choice> elements with thefollowing Schematron assert: <sch:assert test="count(../CONTELEM)>=MIN"> List "CONTELEM" - item count must@nma:mandatory annotation, have to be handled in a special way: For each mandatory choice where at leastMIN </sch:assert> where MIN is the valueone of@nma:min-elements. 12.10. The @nma:max-elements Annotation This annotation is mapped tothefollowingcases contains more than one node, a Schematronassert: <sch:assert test="count(../CONTELEM)<=MAX"> List "CONTELEM" - item count mustrule MUST beat most MAX </sch:assert> where MAX isadded enforcing thevaluepresence of at least one element from any of@nma:min-elements. 12.11. The <nma:must> Annotation This annotation is mapped tothefollowingcases. (RELAX NG schema guarantees that elements from different cases cannot be mixed together, that all mandatory nodes are present etc.). For the example module above, the Schematronassert:rule will be as follows: <sch:rule context="/nc:rpc-reply/nc:data"> <sch:asserttest="EXPRESSION"> MESSAGEtest="ex5:foo1 or ex5:foo2 or ex5:bar"> Node(s) from at least one case of choice "foobar" must exist. </sch:assert>where EXPRESSION</sch:rule> 11.3. Mapping Default Values to DSRL DSRL is thevalue of the mandatory @assert attributeonly component of<nma:must>. If the <nma:error-message> subelement exists, MESSAGEDSDL which issetallowed toits content, otherwise it ischange the information settoof thedefault message "Condition EXPRESSION must be true". 12.12. The <nma:ordered-by> Annotation This annotation currently has no mapping defined. 12.13. The <nma:status> Annotation This annotation currentlyvalidated XML document. While DSRL also hasno mapping defined. 12.14. The @nma:unique Annotation Theother functions, YANG-to-DSDL mappingof this annotation is almost identical asuses it only for@nma:key, see Section 12.7, with two small differences: o The value of @nma:unique is a listspecifying and applying default contents. For XML instance documents based on YANG data models, insertion ofdescendant schema node identifiers rather than simple leaf names. However,default contents may potentially take place for all implicit nodes identified by theXPath expressions specifiedrules in Section12.7 work without any modifications if9.1.2. In DSRL, thedescendant schema node identifiersdefault contents of an element aresubstituted for k_1, k_2, ..., k_n. o The message appearing asspecified using thetext of <sch:report><dsrl:default-content> element, which isdifferent: "Violated uniquenessa child of <dsrl:element- map>. Two sibling elements of <dsrl:default-content> determine the context forlist CONTELEM". 12.15. The @nma:when Annotation This annotation is mapped tothefollowing Schematron assert: <sch:assert test="EXPRESSION"> Node "CONTELEM" isapplication of the default contents, see [DSRL]: o <dsrl:parent> element contains an XSLT pattern specifying the parent element; the default contents are applied onlyvalid when "EXPRESSION" is true. </sch:assert> where EXPRESSION isif thevalue of @nma:when. 13. IANA Considerations This document registers three namespace URIsparent element exists in theIETF XML registry [RFC3688]: URI: urn:ietf:params:xml:ns:netmod:dsdl-annotations:1 URI: urn:ietf:params:xml:ns:netmod:conceptual-tree:1 URI: urn:ietf:params:xml:ns:netmod:xpath-extensions:1 14. Security Considerations This document defines a procedure that maps data models expressed ininstance document. o <dsrl:name> contains theYANG language to a coordinated setXML name ofDSDL schemas. The procedure itself has no security impact ontheInternet. DSDL schemas obtained byelement which, if missing or empty, is inserted together with themapping procedure may be usedcontents of <dsrl:default- content>. The <dsrl:parent> element is optional in a general DSRL schema but, forvalidatingthecontentpurpose ofNETCONF protocol data units or entire datastores and thus provide additional validity checks above those performedthe YANG-to-DSDL mapping, this element MUST be always present, in order to guarantee a proper application of default contents. DSRL mapping only deals with <rng:element> patterns in the hybrid schema that define implicit nodes (see Section 9.1.2). Such element patterns are distinguished byNETCONF server and client implementations supporting YANG data models.having NETMOD-specific annotation attributes @nma:default or @nma:implicit, i.e., either <rng:element name="ELEM" nma:default="DEFVALUE"> ... </rng:element> or <rng:element name="ELEM" nma:implicit="true"> ... </rng:element> Thestrictness offormer case applies to leaf nodes having the 'default' substatement, but also to leaf nodes that obtain their default value from a typedef, if thisvalidationtypedef isdirectly derived fromexpanded according to thesource YANG modulesrules in Section 9.2.2 so that thevalidated XML data adhere to. 15. Acknowledgments@nma:default annotation is attached directly to the leaf's element pattern. Theauthors wishlatter case is used for all implicit containers (see Section 9.1) and for leafs that obtain the default value from a typedef and don't have the @nma:default annotation. In the simplest case, both element patterns are mapped tothankthe followingindividuals who provided helpful suggestions and/or comments on various versionsDSRL element map: <dsrl:element-map> <dsrl:parent>XPARENT</dsrl:parent> <dsrl:name>ELEM</dsrl:name> <dsrl:default-content>DEFCONT</dsrl:default-content> </dsrl:element-map> where XPARENT is the absolute XPath ofthis document: Andy Bierman, Martin Bjorklund, Jirka KosekELEM's parent element in the data tree andPhil Shafer. 16. References 16.1. Normative References [DSDL] ISO/IEC, "Document Schema Definition Languages (DSDL) - Part 1: Overview", ISO/IEC 19757-1, 11 2004. [DSRL] ISO/IEC, "Information Technology - Document Schema Definition Languages (DSDL)DEFCONT is constructed as follows: o If the implicit node ELEM is a leaf and has the @nma:default attribute, DEFCONT is set to the value of this attribute (denoted above as DEFVALUE). o If the implicit node ELEM is a leaf and has the @nma:implicit attribute with the value of "true", the default value has to be determined from the @nma:default attribute of the definition of ELEM's type (perhaps recursively) and used in place of DEFCONT in the above DSRL element map. See also Section 9.2.2. o Otherwise, the implicit node ELEM is a container and DEFCONT is constructed as an XML fragment containing all descendant elements of ELEM that have either @nma:implicit or @nma:default attribute. In addition, when mapping the default case of a choice, it has to be guaranteed that the default contents are not applied if any node from any non-default case is present. This is accomplished by setting <dsrl:parent> in a special way: <dsrl:parent>XPARENT[not (ELEM1|ELEM2|...|ELEMn)]</dsrl:parent> where ELEM1, ELEM2, ... ELEMn are the names of all top-level nodes from all non-default cases. The rest of the element map is exactly as before. EXAMPLE. Consider the following YANG module: module example6 { namespace "http://example.com/ns/example6"; prefix ex6; container outer { leaf leaf1 { type uint8; default 1; } choice one-or-two { default "one"; container one { leaf leaf2 { type uint8; default 2; } } leaf leaf3 { type uint8; default 3; } } } } The DSRL schema generated for the "get-reply" target document type will be: <?xml version="1.0" encoding="utf-8"?> <dsrl:maps xmlns:dsrl="http://purl.oclc.org/dsdl/dsrl" xmlns:ex6="http://example.com/ns/example6" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"> <dsrl:element-map> <dsrl:parent>/nc:rpc-reply/nc:data</dsrl:parent> <dsrl:name>ex6:outer</dsrl:name> <dsrl:default-content> <ex6:leaf1>1</ex6:leaf1> <ex6:one><ex6:leaf2>2</ex6:leaf2></ex6:one> <?xml version="1.0" encoding="utf-8"?> <dsrl:maps xmlns:dsrl="http://purl.oclc.org/dsdl/dsrl" xmlns:ex6="http://example.com/ns/example6" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"> <dsrl:element-map> <dsrl:parent>/nc:rpc-reply/nc:data</dsrl:parent> <dsrl:name>ex6:outer</dsrl:name> <dsrl:default-content> <ex6:leaf1>1</ex6:leaf1> <ex6:one> <ex6:leaf2>2</ex6:leaf2> </ex6:one> </dsrl:default-content> </dsrl:element-map> <dsrl:element-map> <dsrl:parent>/nc:rpc-reply/nc:data/ex6:outer</dsrl:parent> <dsrl:name>ex6:leaf1</dsrl:name> <dsrl:default-content>1</dsrl:default-content> </dsrl:element-map> <dsrl:element-map> <dsrl:parent> /nc:rpc-reply/nc:data/ex6:outer[not(ex6:leaf3)] </dsrl:parent> <dsrl:name>ex6:one</dsrl:name> <dsrl:default-content> <ex6:leaf2>2</ex6:leaf2> </dsrl:default-content> </dsrl:element-map> <dsrl:element-map> <dsrl:parent> /nc:rpc-reply/nc:data/ex6:outer/ex6:one </dsrl:parent> <dsrl:name>ex6:leaf2</dsrl:name> <dsrl:default-content>2</dsrl:default-content> </dsrl:element-map> </dsrl:maps> Note that the default value for "leaf3" defined in the YANG module is ignored because "leaf3" represents a non-default alternative of a choice and as such never becomes an implicit element. 12. Mapping NETMOD-specific Annotations to DSDL Schema Languages This section contains the mapping specification for the individual NETMOD-specific annotations. In each case, the result of the mapping must be inserted into an appropriate context of the target DSDL schema as described in Section 11. The context is determined by the element pattern in the hybrid schema to which the annotation is attached. In the rest of this section, we will denote CONTELEM the name of this context element properly qualified with its namespace prefix. 12.1. The @nma:config Annotation If this annotation is present with the value of "false", the following rules MUST be observed for DSDL schemas of <nc:get-config> reply: o When generating RELAX NG, the contents of the CONTELEM definition MUST be changed to <rng:notAllowed>. o When generating Schematron or DSRL, the CONTELEM definition and all its descendants in the hybrid schema MUST be ignored. 12.2. The @nma:default Annotation This annotation is used for generating the DSRL schema as described in Section 11.3. 12.3. The <nma:error-app-tag> Annotation This annotation currently has no mapping defined. 12.4. The <nma:error-message> Annotation This annotation is handled within <nma:must>, see Section 12.13. 12.5. The @if-feature Annotation The information about available features MAY be supplied as an input parameter to an implementation. In this case, the following changes MUST be performed for all features that are considered unavailable: o When generating RELAX NG, the contents of the CONTELEM definition MUST be changed to <rng:notAllowed>. o When generating Schematron or DSRL, the CONTELEM definition and all its descendants in the hybrid schema MUST be ignored. 12.6. The @nma:implicit Annotation This annotation is used for generating the DSRL schema as described in Section 11.3. 12.7. The <nma:instance-identifier> Annotation If this annotation element has the @require-instance attribute with the value of "false", it is ignored. Otherwise it is mapped to the following Schematron assert: <sch:assert test="nmf:evaluate(.)"> The element pointed to by "CONTELEM" must exist. </sch:assert> The nmf:evaluate() function is an XSLT extension function (see Extension Functions in [XSLT]) that evaluates an XPath expression at run time. Such an extension function is provided by some XSLT processors, for example Saxon [3]. 12.8. The @nma:key Annotation Assume this annotation attribute contains "k_1 k_2 ... k_n", i.e., specifies n children of CONTELEM as list keys. The annotation is then mapped to the following Schematron report: <sch:report test="CONDITION"> Duplicate key of list "CONTELEM" </sch:report> where CONDITION has this form: preceding-sibling::CONTELEM[C_1 and C_2 and ... and C_n] Each sub-expression C_i, for i=1,2,...,n, specifies the condition for violated uniqueness of the key k_i, namely k_i=current()/k_i 12.9. The @nma:leaf-list Annotation This annotation is mapped to the following Schematron rule which detects duplicate entries of a leaf-list: <sch:report test=". = preceding-sibling::PREFIX:sorted-entry"> Duplicate leaf-list entry "<sch:value-of select="."/>". </sch:report> See Section 11.2 for a complete example. 12.10. The @nma:leafref Annotation This annotation is mapped to the following assert: <sch:assert test="PATH=."> Leaf "PATH" does not exist for leafref value "VALUE" </sch:assert> where PATH is the value of @nma:leafref and VALUE is the value of the context element in the instance document for which the referred leaf doesn't exist. 12.11. The @nma:min-elements Annotation This annotation is mapped to the following Schematron assert: <sch:assert test="count(../CONTELEM)>=MIN"> List "CONTELEM" - item count must be at least MIN </sch:assert> where MIN is the value of @nma:min-elements. 12.12. The @nma:max-elements Annotation This annotation is mapped to the following Schematron assert: <sch:assert test="count(../CONTELEM)<=MAX or preceding-sibling::../CONTELEM"> Number of list items must be at most MAX </sch:assert> where MAX is the value of @nma:min-elements. 12.13. The <nma:must> Annotation This annotation is mapped to the following Schematron assert: <sch:assert test="EXPRESSION"> MESSAGE </sch:assert> where EXPRESSION is the value of the mandatory @assert attribute of <nma:must>. If the <nma:error-message> subelement exists, MESSAGE is set to its contents, otherwise it is set to the default message "Condition EXPRESSION must be true". 12.14. The <nma:ordered-by> Annotation This annotation currently has no mapping defined. 12.15. The <nma:status> Annotation This annotation currently has no mapping defined. 12.16. The @nma:unique Annotation The mapping of this annotation is almost identical as for @nma:key, see Section 12.8, with two small differences: o The value of @nma:unique is a list of descendant schema node identifiers rather than simple leaf names. However, the XPath expressions specified in Section 12.8 work without any modifications if the descendant schema node identifiers are substituted for k_1, k_2, ..., k_n. o The message appearing as the text of <sch:report> is different: "Violated uniqueness for list CONTELEM". 12.17. The @nma:when Annotation This annotation is mapped to the following Schematron assert: <sch:assert test="EXPRESSION"> Node "CONTELEM" is only valid when "EXPRESSION" is true. </sch:assert> where EXPRESSION is the value of @nma:when. 13. IANA Considerations This document registers three namespace URIs in the IETF XML registry [RFC3688]: URI: urn:ietf:params:xml:ns:netmod:dsdl-annotations:1 URI: urn:ietf:params:xml:ns:netmod:xpath-extensions:1 14. Security Considerations This document defines a procedure that maps data models expressed in the YANG language to a coordinated set of DSDL schemas. The procedure itself has no security impact on the Internet. DSDL schemas obtained by the mapping procedure may be used for validating the contents of NETCONF messages or entire datastores and thus provide additional validity checks above those performed by NETCONF server and client implementations supporting YANG data models. The strictness of this validation is directly derived from the source YANG modules that the validated XML data adhere to. 15. Acknowledgments The authors wish to thank the following individuals who provided helpful suggestions and/or comments on various versions of this document: Andy Bierman, Martin Bjorklund, Jirka Kosek and Phil Shafer. 16. References 16.1. Normative References [DSDL] ISO/IEC, "Document Schema Definition Languages (DSDL) - Part8: Document Semantics Renaming Language - DSRL",1: Overview", ISO/IEC19757-8:2008(E), 12 2008. [NVDL]19757-1, 11 2004. [DSRL] ISO/IEC, "Information Technology - Document Schema Definition Languages (DSDL) - Part4: Namespace-Based Validation Dispatching8: Document Semantics Renaming Language(NVDL)", ISO/ IEC 19757-4:2006(E), 6 2006.- DSRL", ISO/IEC 19757-8:2008(E), 12 2008. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004. [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, December 2006. [RFC5013] Kunze, J., "The Dublin Core Metadata Element Set", RFC 5013, August 2007. [RNG] ISO/IEC, "Information Technology - Document Schema Definition Languages (DSDL) - Part 2: Regular-Grammar- Based Validation - RELAX NG. Second Edition.", ISO/ IEC 19757-2:2008(E),12 2008. [RNG-CS] ISO/IEC, "Information Technology - Document Schema Definition Languages (DSDL) - Part 2: Regular-Grammar- Based Validation - RELAX NG. AMENDMENT 1: Compact Syntax", ISO/IEC 19757-2:2003/Amd. 1:2006(E), 1 2006. [RNG-DTD] Clark, J., Ed. and M. Murata, Ed., "RELAX NG DTD Compatibility", OASIS Committee Specification 3 December 2001, December 2001. [Schematron] ISO/IEC, "Information Technology - Document Schema Definition Languages (DSDL) - Part 3: Rule-Based Validation - Schematron", ISO/IEC 19757-3:2006(E), 6 2006. [XML] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", World Wide Web Consortium Recommendation REC- xml-20081126, November 2008, <http://www.w3.org/TR/2006/REC-xml-20060816>. [XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) Version 1.0", World Wide Web Consortium Recommendation REC-xpath-19991116, November 1999, <http://www.w3.org/TR/1999/REC-xpath-19991116>. [XSD-D] Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes Second Edition", World Wide Web Consortium Recommendation REC-xmlschema-2-20041028, October 2004, <http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>. [XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World Wide Web Consortium Recommendation REC-xslt-19991116, November 1999. [YANG] Bjorklund, M., Ed., "YANG - A data modeling language for NETCONF", draft-ietf-netmod-yang-11 (work in progress), Febuary 2010. [Ytypes] Schoenwaelder, J., Ed., "Common YANG Data Types", draft-ietf-netmod-yang-types-07 (work in progress), February 2010. 16.2. Informative References [RFC1157] Case, J., Fedor, M., Schoffstall, M., and J. Davin, "Simple Network Management Protocol (SNMP)", STD 15, RFC 1157, May 1990. [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. Schoenwaelder, Ed., "Structure of Management Information Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. [RFC3216] Elliott, C., Harrington, D., Jason, J., Schoenwaelder,12 2008. [RNG-CS] ISO/IEC, "Information Technology - Document Schema Definition Languages (DSDL) - Part 2: Regular-Grammar- Based Validation - RELAX NG. AMENDMENT 1: Compact Syntax", ISO/IEC 19757-2:2003/Amd. 1:2006(E), 1 2006. [RNG-DTD] Clark, J.,Strauss, F.,Ed. andW. Weiss, "SMIng Objectives", RFC 3216,M. Murata, Ed., "RELAX NG DTD Compatibility", OASIS Committee Specification 3 December 2001, December 2001.[RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event Notifications", RFC 5277, July 2008. [Vli04] van der Vlist, E., "RELAX NG", O'Reilly , 2004. [XSD] Thompson, H., Beech, D., Maloney, M., and N. Mendelsohn, "XML[Schematron] ISO/IEC, "Information Technology - Document Schema Definition Languages (DSDL) - Part1: Structures Second Edition",3: Rule-Based Validation - Schematron", ISO/IEC 19757-3:2006(E), 6 2006. [XML] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", World Wide Web Consortium RecommendationREC-xmlschema-1-20041028, October 2004, <http://www.w3.org/TR/2004/REC-xmlschema-1-20041028>. URIs [1] <http://www.thaiopensource.com/relaxng/trang.html> [2] <http://dublincore.org/> [3] <http://www.saxonica.com/> [4] <http://www.yang-central.org/twiki/bin/view/Main/DhcpTutorial> [5] <http://code.google.com/p/pyang/> [6] <http://thaiopensource.com/relaxng/trang.html> Appendix A. Schemas for NETMOD-Specific Annotations This appendix utilizes Namespace-Based Validation Dispatching Language (NVDL, Part 4 of DSDL) [NVDL] to define NETMOD-specific annotations as extensions of the RELAX NG language. The NVDL schema may be used for validating conceptual tree schemas as compound XML documents consisting of RELAX NG sections and embedded sections with NETMOD-specific annotations. The NVDL schema dispatches the validation as follows: 1. RELAX NG sections identified by the namespace URI "http://relaxng.org/ns/structure/1.0" is validated with the standard RELAX NG schema for RELAX NG, see [RNG], Annex A. 2. NETMOD-specific annotation sections identified by the namespace URI "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1" are validated by several context-dependent RELAX NG schemas given below. 3. Other sections such as Dublin Core metadata or <a:documentation> annotation are attached toREC- xml-20081126, November 2008, <http://www.w3.org/TR/2006/REC-xml-20060816>. [XML-INFOSET] Tobin, R. andvalidated together with the parent RELAX NG section. A.1. NVDLJ. Cowan, "XML Information Set (Second Edition)", World Wide Web Consortium Recommendation REC- xml-infoset-20040204, February 2004, <http://www.w3.org/TR/2004/REC-xml-infoset-20040204>. [XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) Version 1.0", World Wide Web Consortium Recommendation REC-xpath-19991116, November 1999, <http://www.w3.org/TR/1999/REC-xpath-19991116>. [XSD-D] Biron, P. and A. Malhotra, "XML Schema<CODE BEGINS> file "nmannot.nvdl" <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE nvdl:rules [<!ENTITY nmannot-uri "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1"> ]> <rules xmlns="http://purl.oclc.org/dsdl/nvdl/ns/structure/1.0" startMode="rng"> <mode name="rng"> <namespace ns="http://relaxng.org/ns/structure/1.0"> <validate schema="http://relaxng.org/relaxng.rng" useMode="other"> <context path="define" useMode="define"/> <context path="oneOrMore/element" useMode="list"/> <context path="element" useMode="element"/> <context path="choice/group|choice/interleave" useMode="group-interleave"/> <context path="choice|ref" useMode="choice-ref"/> <context path="value" useMode="value"/> </validate> </namespace> </mode> <mode name="define"> <namespace ns="&nmannot-uri;" match="attributes"> <validate schema="define.rng"/> </namespace> </mode> <mode name="element"> <namespace ns="&nmannot-uri;" match="elements"> <validate schema="element-el.rng"/> </namespace> <namespace ns="&nmannot-uri;" match="attributes"> <validate schema="element-att.rng"/> </namespace> </mode> <mode name="group-interleave"> <namespace ns="&nmannot-uri;" match="attributes"> <validate schema="group-interleave.rng"/> </namespace> </mode> <mode name="choice-ref"> <namespace ns="&nmannot-uri;" match="attributes"> <validate schema="choice-ref.rng"/> </namespace> </mode> <mode name="list"> <namespace ns="&nmannot-uri;" match="attributes"> <validate schema="list.rng"/> </namespace> </mode> <mode name="value"> <namespace ns="&nmannot-uri;" match="attributes"> <validate schema="value.rng"/> </namespace> </mode> <mode name="other"> <namespace ns="&nmannot-uri;" match="elements attributes"> <reject/> </namespace> <anyNamespace match="elements attributes"> <attach/> </anyNamespace> </mode> </rules> <CODE ENDS> A.2. Annotation Attributes for define Pattern <CODE BEGINS> file "define.rng" <?xml version="1.0" encoding="UTF-8"?> <grammar xmlns="http://relaxng.org/ns/structure/1.0"> <include href="nmannotdefs.rng"/> <start> <group> <ref name="default-attribute"/> <ref name="status-attribute"/> <ref name="units-attribute"/> </group> </start> </grammar> <CODE ENDS> A.3. Annotation Elements for element Pattern <CODE BEGINS> file "element-el.rng" <?xml version="1.0" encoding="UTF-8"?> <grammar xmlns="http://relaxng.org/ns/structure/1.0"> <include href="nmannotdefs.rng"/> <start> <choice> <ref name="must-element"/> <ref name="instance-identifier-element"/> </choice> </start> </grammar> <CODE ENDS> A.4. Annotation Attributes for element Pattern <CODE BEGINS> file "element-att.rng" <?xml version="1.0" encoding="UTF-8"?> <grammar xmlns="http://relaxng.org/ns/structure/1.0"> <include href="nmannotdefs.rng"/> <start> <group> <ref name="config-attribute"/> <ref name="default-attribute"/> <ref name="implicit-attribute"/> <ref name="leafref-attribute"/> <ref name="presence-attribute"/> <ref name="status-attribute"/> <ref name="units-attribute"/> <ref name="when-attribute"/> </group> </start> </grammar> <CODE ENDS> A.5. Annotation attributes for group Pattern <CODE BEGINS> file "group-interleave.rng" <?xml version="1.0" encoding="UTF-8"?> <grammar xmlns="http://relaxng.org/ns/structure/1.0"> <include href="nmannotdefs.rng"/> <start> <group> <ref name="implicit-attribute"/> <ref name="status-attribute"/> <ref name="when-attribute"/> </group> </start> </grammar> <CODE ENDS> A.6. Annotation attributesPart 2: Datatypes Second Edition", World Wide Web Consortium Recommendation REC-xmlschema-2-20041028, October 2004, <http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>. [XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World Wide Web Consortium Recommendation REC-xslt-19991116, November 1999. [YANG] Bjorklund, M., Ed., "YANG - A data modeling language forchoiceNETCONF", draft-ietf-netmod-yang-13 (work in progress), June 2010. [Ytypes] Schoenwaelder, J., Ed., "Common YANG Data Types", draft-ietf-netmod-yang-types-09 (work in progress), April 2010. 16.2. Informative References [RFC1157] Case, J., Fedor, M., Schoffstall, M., and J. Davin, "Simple Network Management Protocol (SNMP)", STD 15, RFC 1157, May 1990. [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. Schoenwaelder, Ed., "Structure of Management Information Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. [RFC3216] Elliott, C., Harrington, D., Jason, J., Schoenwaelder, J., Strauss, F., andref Patterns <CODE BEGINS> file "choice-ref.rng" <?xml version="1.0" encoding="UTF-8"?> <grammar xmlns="http://relaxng.org/ns/structure/1.0"> <include href="nmannotdefs.rng"/> <start> <group> <ref name="status-attribute"/> <ref name="when-attribute"/> </group> </start> </grammar> <CODE ENDS> A.7. Annotation attributes for element Pattern in the List Context <CODE BEGINS> file "list.rng" <?xml version="1.0" encoding="UTF-8"?> <grammar xmlns="http://relaxng.org/ns/structure/1.0"> <include href="nmannotdefs.rng"/> <start> <group> <ref name="key-attribute"/> <ref name="min-elements-attribute"/> <ref name="max-elements-attribute"/> <ref name="ordered-by-attribute"/> <ref name="unique-attribute"/> </group> </start> </grammar> <CODE ENDS> A.8. Annotation attributes for value Pattern <CODE BEGINS> file "value.rng" <?xml version="1.0" encoding="UTF-8"?> <grammar xmlns="http://relaxng.org/ns/structure/1.0"> <include href="nmannotdefs.rng"/> <start> <ref name="status-attribute"/> </start> </grammar> <CODE ENDS> A.9. Named PatternsW. Weiss, "SMIng Objectives", RFC 3216, December 2001. [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event Notifications", RFC 5277, July 2008. [Vli04] van der Vlist, E., "RELAX NG", O'Reilly , 2004. [XSD] Thompson, H., Beech, D., Maloney, M., and N. Mendelsohn, "XML Schema Part 1: Structures Second Edition", World Wide Web Consortium Recommendation REC-xmlschema-1-20041028, October 2004, <http://www.w3.org/TR/2004/REC-xmlschema-1-20041028>. URIs [1] <http://www.thaiopensource.com/relaxng/trang.html> [2] <http://dublincore.org/> [3] <http://www.saxonica.com/> [4] <http://www.yang-central.org/twiki/bin/view/Main/DhcpTutorial> [5] <http://code.google.com/p/pyang/> Appendix A. RELAX NG Schema forAllNETMOD-Specific Annotations This appendix defines the content model for all NETMOD-specific annotations in the form of RELAX NG named pattern definitions. <CODE BEGINS> file"nmannotdefs.rng""nmannot.rng" <?xml version="1.0" encoding="UTF-8"?> <grammar xmlns="http://relaxng.org/ns/structure/1.0" xmlns:nma="urn:ietf:params:xml:ns:netmod:dsdl-annotations:1" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"> <define name="config-attribute"><optional><attribute name="nma:config"> <data type="boolean"/> </attribute></optional></define> <definename="default-attribute"> <optional> <attribute name="nma:default"/> </optional>name="data-element"> <element name="nma:data"> <ref name="__anyxml__"/> </element> </define> <definename="implicit-attribute"> <optional>name="default-attribute"> <attributename="nma:implicit">name="nma:default"> <datatype="boolean"/>type="string"/> </attribute></optional></define> <define name="error-app-tag-element"><optional><element name="nma:error-app-tag"> <text/> </element></optional></define> <define name="error-message-element"><optional><element name="nma:error-message"> <text/> </element></optional></define> <define name="if-feature-attribute"> <attribute name="nma:if-feature"> <list> <data type="QName"/> </list> </attribute> </define> <define name="implicit-attribute"> <attribute name="nma:implicit"> <data type="boolean"/> </attribute> </define> <define name="instance-identifier-element"> <element name="nma:instance-identifier"> <optional> <attribute name="nma:require-instance"> <data type="boolean"/> </attribute> </optional> </element> </define> <define name="key-attribute"><optional><attribute name="nma:key"> <list> <data type="QName"/> </list> </attribute></optional></define> <define name="leaf-list-attribute"> <attribute name="nma:leaf-list"> <data type="boolean"/> </attribute> </define> <define name="leafref-attribute"><optional><attribute name="nma:leafref"> <data type="string"/> </attribute></optional></define> <definename="min-elements-attribute"> <optional>name="mandatory-attribute"> <attributename="nma:min-elements">name="nma:mandatory"> <datatype="nonNegativeInteger"/>type="Name"/> </attribute></optional></define> <define name="max-elements-attribute"><optional><attribute name="nma:max-elements"> <data type="nonNegativeInteger"/> </attribute> </define> <define name="min-elements-attribute"> <attribute name="nma:min-elements"> <data type="nonNegativeInteger"/> </attribute> </define> <define name="module-attribute"> <attribute name="nma:module"> <data type="Name"/> </attribute> </define> <define name="must-element"> <element name="nma:must"> <attribute name="assert"> <data type="string"/> </attribute> <interleave> <optional> <ref name="error-app-tag-element"/> </optional> <optional> <ref name="error-message-element"/> </optional> </interleave> </element> </define> <define name="notifications-element"> <element name="nma:notifications"> <zeroOrMore> <element name="nma:notification"> <ref name="__anyxml__"/> </element> </zeroOrMore> </element> </define> <definename="must-element">name="rpcs-element"> <elementname="nma:must"> <attribute name="assert"> <data type="string"/> </attribute>name="nma:rpcs"> <zeroOrMore> <element name="nma:rpc"> <interleave> <element name="nma:input"> <refname="error-app-tag-element"/>name="__anyxml__"/> </element> <optional> <element name="nma:output"> <refname="error-message-element"/>name="__anyxml__"/> </element> </optional> </interleave> </element> </zeroOrMore> </element> </define> <define name="ordered-by-attribute"><optional><attribute name="nma:ordered-by"> <choice> <value>user</value> <value>system</value> </choice> </attribute></optional> </define> <define name="presence-attribute"> <optional> <attribute name="nma:presence"> <value>true</value> </attribute> </optional></define> <define name="status-attribute"> <optional> <attribute name="nma:status"> <choice> <value>current</value> <value>deprecated</value> <value>obsolete</value> </choice> </attribute> </optional> </define> <define name="unique-attribute"> <optional> <attribute name="nma:unique"> <list> <data type="token"/> </list> </attribute> </optional> </define> <define name="units-attribute"> <optional> <attribute name="nma:units"> <data type="string"/> </attribute> </optional> </define> <define name="when-attribute"> <optional> <attribute name="nma:when"> <data type="string"/> </attribute> </optional> </define> <define name="__anyxml__"> <zeroOrMore> <choice> <attribute> <anyName/> </attribute> <element> <anyName/> <ref name="__anyxml__"/> </element> <text/> </choice> </zeroOrMore> </define> </grammar> <CODE ENDS> Appendix B. Schema-Independent Library In order to avoid copying the common named pattern definitions to every RELAX NG schema generated in the second mapping step, the definitions are collected in a library file - schema-independent library - which is included by the validating schemas under the file name "relaxng-lib.rng" (XML syntax) and "relaxng-lib.rnc" (compact syntax). The included definitions cover patterns for common elements from base NETCONF [RFC4741] and event notifications [RFC5277]. <CODE BEGINS> file "relaxng-lib.rng" <?xml version="1.0" encoding="UTF-8"?> <grammar xmlns="http://relaxng.org/ns/structure/1.0" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:en="urn:ietf:params:xml:ns:netconf:notification:1.0" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"> <define name="message-id-attribute"> <attribute name="message-id"> <data type="string"> <param name="maxLength">4095</param> </data> </attribute> </define> <define name="ok-element"> <element name="nc:ok"> <empty/> </element> </define> <define name="eventTime-element"> <element name="en:eventTime"> <data type="dateTime"/> </element> </define> </grammar> <CODE ENDS> Appendix C. Mapping DHCP Data Model - A Complete Example This appendix demonstrates both steps of the YANG-to-DSDL mapping applied to the "canonical" DHCP tutorial [4] data model. The single input YANG module is shown in Appendix C.1 and the output schemas in the following two subsections. Theconceptual treehybrid schema was obtained by the"rng""dsdl" plugin of the pyang [5] tool and the validating DSDL schemas obtained by XSLT stylesheets that are also part of pyang distribution.RELAX NG schemas are shown in both XML and compact syntax. The latter was obtained from the former by using the Trang tool [6]Due to the limit of 72 characters per line, a few long strings required manual editing, in particular the regular expression patterns for IP addresses etc.in the RELAX NG schemas. In the compact syntax we broke the patterns to appropriate segments and joined them with the concatenation operator "~". In the XML syntax, though, the long patterns had to beThese were replaced by the placeholder string "... regex pattern ...". Also, line breaks were added to several documentation strings and Schematron messages. Other than that, the results of the automatic translations were not changed. C.1. Input YANG Module module dhcp { namespace "http://example.com/ns/dhcp"; prefix dhcp; import ietf-yang-types { prefix yang; } import ietf-inet-types { prefix inet; } organization "yang-central.org"; description "Partial data model for DHCP, based on the config of the ISC DHCP reference implementation."; container dhcp { description "configuration and operational parameters for a DHCP server."; leaf max-lease-time { type uint32; units seconds; default 7200; } leaf default-lease-time { type uint32; units seconds; must '. <= ../max-lease-time' { error-message "The default-lease-time must be less than max-lease-time"; } default 600; } uses subnet-list; container shared-networks { list shared-network { key name; leaf name { type string; } uses subnet-list; } } container status { config false; list leases { key address; leaf address { type inet:ip-address; } leaf starts { type yang:date-and-time; } leaf ends { type yang:date-and-time; } container hardware { leaf type { type enumeration { enum "ethernet"; enum "token-ring"; enum "fddi"; } } leaf address { type yang:phys-address; } } } } } grouping subnet-list { description "A reusable list of subnets"; list subnet { key net; leaf net { type inet:ip-prefix; } container range { presence "enables dynamic address assignment"; leaf dynamic-bootp { type empty; description "Allows BOOTP clients to get addresses in this range"; } leaf low { type inet:ip-address; mandatory true; } leaf high { type inet:ip-address; mandatory true; } } container dhcp-options { description "Options in the DHCP protocol"; leaf-list router { type inet:host; ordered-by user; reference "RFC 2132, sec. 3.8"; } leaf domain-name { type inet:domain-name; reference "RFC 2132, sec. 3.17"; } } leaf max-lease-time { type uint32; units seconds; default 7200; } } } } C.2.Conceptual TreeHybrid SchemaC.2.1. XML Syntax<?xml version="1.0" encoding="UTF-8"?> <grammar xmlns="http://relaxng.org/ns/structure/1.0"xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"xmlns:nma="urn:ietf:params:xml:ns:netmod:dsdl-annotations:1" xmlns:dc="http://purl.org/dc/terms" xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0" xmlns:dhcp="http://example.com/ns/dhcp"xmlns:nma="urn:ietf:params:xml:ns:netmod:dsdl-annotations:1" xmlns:nmt="urn:ietf:params:xml:ns:netmod:conceptual-tree:1"datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"> <dc:creator>Pyang0.9.3, CTS1.0a, DSDL plugin</dc:creator> <dc:date>2010-06-17</dc:date> <start> <grammar nma:module="dhcp" ns="http://example.com/ns/dhcp"> <dc:source>YANG module 'dhcp'</dc:source> <start><element name="nmt:netmod-tree"> <element name="nmt:top"> <interleave><nma:data> <optional> <elementname="dhcp:dhcp" nma:implicit="true">nma:implicit="true" name="dhcp:dhcp"> <interleave> <a:documentation> configuration and operational parameters for a DHCPserverserver. </a:documentation> <optional> <elementname="dhcp:max-lease-time"nma:default="7200" name="dhcp:max-lease-time" nma:units="seconds"> <data type="unsignedInt"/> </element> </optional> <optional> <elementname="dhcp:default-lease-time"nma:default="600" name="dhcp:default-lease-time" nma:units="seconds"> <data type="unsignedInt"/> <nma:must assert=". <= ../dhcp:max-lease-time"> <nma:error-message> The default-lease-time must be less thanmax-lease-time.max-lease-time </nma:error-message> </nma:must> </element> </optional> <ref name="_dhcp__subnet-list"/> <optional> <element name="dhcp:shared-networks"><interleave><zeroOrMore> <elementname="dhcp:shared-network" nma:key="dhcp:name">nma:key="dhcp:name" name="dhcp:shared-network"> <element name="dhcp:name"> <data type="string"/> </element><interleave><ref name="_dhcp__subnet-list"/></interleave></element> </zeroOrMore></interleave></element> </optional> <optional> <element name="dhcp:status" nma:config="false"><interleave><zeroOrMore> <elementname="dhcp:leases" nma:key="dhcp:address"> <element name="dhcp:address"> <ref name="ietf-inet-types__ip-address"/> </element> <interleave> <optional> <element name="dhcp:starts"> <ref name="ietf-yang-types__date-and-time"/> </element> </optional> <optional> <element name="dhcp:ends"> <ref name="ietf-yang-types__date-and-time"/> </element> </optional> <optional> <element name="dhcp:hardware"> <interleave> <optional> <element name="dhcp:type"> <choice> <value>ethernet</value> <value>token-ring</value> <value>fddi</value> </choice> </element> </optional> <optional> <element name="dhcp:address"> <ref name="ietf-yang-types__phys-address"/> </element> </optional> </interleave> </element> </optional> </interleave> </element> </zeroOrMore> </interleave> </element> </optional> </interleave> </element> </optional> </interleave> </element> <element name="nmt:rpc-methods"> <empty/> </element> <element name="nmt:notifications"> <empty/> </element> </element> </start> <define name="_dhcp__subnet-list"> <interleave> <a:documentation>A reusable list of subnets</a:documentation> <zeroOrMore> <element name="dhcp:subnet" nma:key="dhcp:net"> <element name="dhcp:net"> <ref name="ietf-inet-types__ip-prefix"/> </element> <interleave> <optional> <element name="dhcp:range"> <interleave> <optional> <element name="dhcp:dynamic-bootp"> <a:documentation> Allows BOOTP clients to get addresses in this range </a:documentation> <empty/> </element> </optional> <element name="dhcp:low"> <ref name="ietf-inet-types__ip-address"/> </element> <element name="dhcp:high"> <ref name="ietf-inet-types__ip-address"/> </element> </interleave> </element> </optional> <optional> <element name="dhcp:dhcp-options"> <interleave> <a:documentation> Options in the DHCP protocol </a:documentation> <zeroOrMore>nma:key="dhcp:address" name="dhcp:leases"> <elementname="dhcp:router" nma:ordered-by="user"> <a:documentation> See: RFC 2132, sec. 3.8 </a:documentation>name="dhcp:address"> <refname="ietf-inet-types__host"/>name="ietf-inet-types__ip-address"/> </element></zeroOrMore><interleave> <optional> <elementname="dhcp:domain-name"> <a:documentation> See: RFC 2132, sec. 3.17 </a:documentation>name="dhcp:starts"> <refname="ietf-inet-types__domain-name"/>name="ietf-yang-types__date-and-time"/> </element> </optional></interleave><optional> <element name="dhcp:ends"> <ref name="ietf-yang-types__date-and-time"/> </element> </optional> <optional> <elementname="dhcp:max-lease-time" nma:default="7200" nma:units="seconds"> <data type="unsignedInt"/>name="dhcp:hardware"> <interleave> <optional> <element name="dhcp:type"> <choice> <value>ethernet</value> <value>token-ring</value> <value>fddi</value> </choice> </element> </optional> <optional> <element name="dhcp:address"> <ref name="ietf-yang-types__phys-address"/> </element> </optional> </interleave> </element> </optional> </interleave> </element> </zeroOrMore> </element> </optional> </interleave></define> <define name="ietf-inet-types__ip-prefix"> <choice> <ref name="ietf-inet-types__ipv4-prefix"/> <ref name="ietf-inet-types__ipv6-prefix"/> </choice> </define></element> </optional> </nma:data> <nma:rpcs/> <nma:notifications/> </start> </grammar> </start> <definename="ietf-inet-types__ipv4-prefix">name="ietf-yang-types__phys-address"> <data type="string"> <paramname="pattern">... regex pattern ...</param>name="pattern">([0-9a-fA-F]{2}(:[0-9a-fA-F]{2})*)?</param> </data> </define> <definename="ietf-inet-types__ipv6-prefix">name="ietf-inet-types__ipv6-address"> <data type="string"> <param name="pattern">... regex pattern ...</param> <param name="pattern">... regex pattern ...</param> </data> </define> <definename="ietf-inet-types__ip-address">name="ietf-inet-types__ip-prefix"> <choice> <refname="ietf-inet-types__ipv4-address"/>name="ietf-inet-types__ipv4-prefix"/> <refname="ietf-inet-types__ipv6-address"/>name="ietf-inet-types__ipv6-prefix"/> </choice> </define> <definename="ietf-inet-types__ipv4-address"> <data type="string"> <param name="pattern">... regex pattern ...</param> </data> </define> <define name="ietf-inet-types__ipv6-address"> <data type="string"> <param name="pattern">... regex pattern ...</param> <param name="pattern">... regex pattern ...</param> </data> </define> <definename="ietf-inet-types__host"> <choice> <ref name="ietf-inet-types__ip-address"/> <ref name="ietf-inet-types__domain-name"/> </choice> </define> <definename="ietf-inet-types__domain-name"> <data type="string"> <param name="minLength">1</param> <param name="maxLength">253</param> <param name="pattern">... regex pattern ...</param> </data> </define> <definename="ietf-yang-types__date-and-time"> <data type="string"> <param name="pattern">... regex pattern ...</param> </data> </define> <definename="ietf-yang-types__phys-address"> <data type="string"> <param name="pattern"> ([0-9a0-fA-F]{2}(:[0-9a0-fA-F]{2})*)? </param> </data> </define> </grammar> C.2.2. Compact Syntax namespace a = "http://relaxng.org/ns/compatibility/annotations/1.0" namespace dc = "http://purl.org/dc/terms" namespace dhcp = "http://example.com/ns/dhcp" namespace nma = "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1" namespace nmt = "urn:ietf:params:xml:ns:netmod:conceptual-tree:1" dc:creator [ "Pyang 0.9.3, CTS plugin" ] dc:source [ "YANG module 'dhcp'" ] start = element nmt:netmod-tree { element nmt:top { [ nma:implicit = "true" ] element dhcp:dhcp { ## ## configuration and operational parameters for a DHCP server ## ([ nma:default = "7200" nma:units = "seconds" ] element dhcp:max-lease-time { xsd:unsignedInt }? & [ nma:default = "600" nma:units = "seconds" ] element dhcp:default-lease-time { xsd:unsignedInt >> nma:must [ assert = ". <= ../dhcp:max-lease-time" nma:error-message [ "\x{a}" ~ "The default-lease-time must be less than max-lease-time." ~ "\x{a}" ] ] }? & _dhcp__subnet-list & element dhcp:shared-networks { [ nma:key = "dhcp:name" ] element dhcp:shared-network { element dhcp:name { xsd:string }, (_dhcp__subnet-list) }* }? & [ nma:config = "false" ] element dhcp:status { [ nma:key = "dhcp:address" ] element dhcp:leases { element dhcp:address { ietf-inet-types__ip-address }, (element dhcp:starts { ietf-yang-types__date-and-time }? & element dhcp:ends { ietf-yang-types__date-and-time }? & element dhcp:hardware { element dhcp:type { "ethernet" | "token-ring" | "fddi" }? & element dhcp:address { ietf-yang-types__phys-address }? }?) }* }?) }? }, element nmt:rpc-methods { empty }, element nmt:notifications { empty } } _dhcp__subnet-list = ## Aname="_dhcp__subnet-list"> <a:documentation>A reusable list ofsubnets ([ nma:key = "dhcp:net" ] element dhcp:subnet { element dhcp:net { ietf-inet-types__ip-prefix }, (element dhcp:range { ## ##subnets</a:documentation> <zeroOrMore> <element nma:key="net" name="subnet"> <element name="net"> <ref name="ietf-inet-types__ip-prefix"/> </element> <interleave> <optional> <element name="range"> <interleave> <optional> <element name="dynamic-bootp"> <a:documentation> Allows BOOTP clients to get addresses in this range## element dhcp:dynamic-bootp { empty }? & element dhcp:low { ietf-inet-types__ip-address } & element dhcp:high { ietf-inet-types__ip-address } }? & element dhcp:dhcp-options { ## ##</a:documentation> <empty/> </element> </optional> <element name="low"> <ref name="ietf-inet-types__ip-address"/> </element> <element name="high"> <ref name="ietf-inet-types__ip-address"/> </element> </interleave> </element> </optional> <optional> <element name="dhcp-options"> <interleave> <a:documentation> Options in the DHCP protocol## ( ## ##</a:documentation> <zeroOrMore> <element nma:leaf-list="true" name="router" nma:ordered-by="user"> <a:documentation> See: RFC 2132, sec. 3.8## [ nma:ordered-by = "user" ] element dhcp:router { ietf-inet-types__host }* & ## ##</a:documentation> <ref name="ietf-inet-types__host"/> </element> </zeroOrMore> <optional> <element name="domain-name"> <a:documentation> See: RFC 2132, sec. 3.17## element dhcp:domain-name { ietf-inet-types__domain-name }?) }? & [ nma:default = "7200" nma:units = "seconds" ] element dhcp:max-lease-time { xsd:unsignedInt }?) }*) ietf-inet-types__ip-prefix = ietf-inet-types__ipv4-prefix | ietf-inet-types__ipv6-prefix ietf-inet-types__ipv4-prefix = xsd:string { pattern = "... regex pattern ..." } ietf-inet-types__ipv6-prefix = xsd:string { pattern = "... regex pattern ..." pattern = "... regex pattern ..." } ietf-inet-types__ip-address = ietf-inet-types__ipv4-address | ietf-inet-types__ipv6-address ietf-inet-types__ipv4-address = xsd:string { pattern = "...</a:documentation> <ref name="ietf-inet-types__domain-name"/> </element> </optional> </interleave> </element> </optional> <optional> <element nma:default="7200" name="max-lease-time" nma:units="seconds"> <data type="unsignedInt"/> </element> </optional> </interleave> </element> </zeroOrMore> </define> <define name="ietf-inet-types__domain-name"> <data type="string"> <param name="pattern">... regex pattern..." } ietf-inet-types__ipv6-address = xsd:string { pattern = "......</param> <param name="minLength">1</param> <param name="maxLength">253</param> </data> </define> <define name="ietf-inet-types__ipv4-prefix"> <data type="string"> <param name="pattern">... regex pattern..." pattern = "......</param> </data> </define> <define name="ietf-inet-types__ipv4-address"> <data type="string"> <param name="pattern">... regex pattern..." } ietf-inet-types__host = ietf-inet-types__ip-address | ietf-inet-types__domain-name ietf-inet-types__domain-name = xsd:string { minLength = "1" maxLength = "253" pattern = "......</param> </data> </define> <define name="ietf-inet-types__ipv6-prefix"> <data type="string"> <param name="pattern">... regex pattern..." } ietf-yang-types__date-and-time = xsd:string { pattern = "......</param> <param name="pattern">... regex pattern..." } ietf-yang-types__phys-address = xsd:string { pattern = "([0-9a0-fA-F]{2}(:[0-9a0-fA-F]{2})*)?" }...</param> </data> </define> <define name="ietf-inet-types__ip-address"> <choice> <ref name="ietf-inet-types__ipv4-address"/> <ref name="ietf-inet-types__ipv6-address"/> </choice> </define> </grammar> C.3. Final DSDL Schemas This appendix contains DSDL schemas that were obtained from theconceptual treehybrid schema in Appendix C.2 by XSL transformations. These schemas can be directly used for validating a reply to unfiltered<get><nc:get> with the contents corresponding to the DHCP data model. The RELAX NG schema(again shown(in two parts, as explained inboth XML and compact syntax)Section 8.2) also includes theschema independentschema-independent library from Appendix B. C.3.1. Main RELAX NG Schema for<get><nc:get> Reply- XML Syntax<?xml version="1.0" encoding="utf-8"?> <grammar xmlns="http://relaxng.org/ns/structure/1.0"xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0" xmlns:dc="http://purl.org/dc/terms" xmlns:dhcp="http://example.com/ns/dhcp"xmlns:nma="urn:ietf:params:xml:ns:netmod:dsdl-annotations:1"xmlns:nmt="urn:ietf:params:xml:ns:netmod:conceptual-tree:1"xmlns:dhcp="http://example.com/ns/dhcp" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes" ns="urn:ietf:params:xml:ns:netconf:base:1.0"> <include href="relaxng-lib.rng"/> <start> <element name="rpc-reply"> <ref name="message-id-attribute"/> <element name="data"> <interleave> <grammar ns="http://example.com/ns/dhcp"> <include href="dhcp-gdefs.rng"/> <start> <optional> <element name="dhcp:dhcp"> <interleave> <optional> <element name="dhcp:max-lease-time"> <data type="unsignedInt"/> </element> </optional> <optional> <element name="dhcp:default-lease-time"> <data type="unsignedInt"/> </element> </optional> <ref name="_dhcp__subnet-list"/> <optional> <element name="dhcp:shared-networks"><interleave><zeroOrMore> <element name="dhcp:shared-network"> <element name="dhcp:name"> <data type="string"/> </element><interleave><ref name="_dhcp__subnet-list"/></interleave></element> </zeroOrMore></interleave></element> </optional> <optional> <element name="dhcp:status"><interleave><zeroOrMore> <element name="dhcp:leases"> <element name="dhcp:address"> <ref name="ietf-inet-types__ip-address"/> </element> <interleave> <optional> <element name="dhcp:starts"> <ref name="ietf-yang-types__date-and-time"/> </element> </optional> <optional> <element name="dhcp:ends"> <ref name="ietf-yang-types__date-and-time"/> </element> </optional> <optional> <element name="dhcp:hardware"> <interleave> <optional> <element name="dhcp:type"> <choice> <value>ethernet</value> <value>token-ring</value> <value>fddi</value> </choice> </element> </optional> <optional> <element name="dhcp:address"> <ref name="ietf-yang-types__phys-address"/> </element> </optional> </interleave> </element> </optional> </interleave> </element> </zeroOrMore></interleave></element> </optional> </interleave> </element> </optional> </start> </grammar> </interleave> </element> </element> </start> </grammar> C.3.2. RELAX NG Schema - Global Named Pattern Definitions <?xml version="1.0" encoding="utf-8"?> <grammar xmlns="http://relaxng.org/ns/structure/1.0" xmlns:nma="urn:ietf:params:xml:ns:netmod:dsdl-annotations:1" xmlns:dhcp="http://example.com/ns/dhcp" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"> <define name="ietf-yang-types__phys-address"> <data type="string"> <param name="pattern"> ([0-9a-fA-F]{2}(:[0-9a-fA-F]{2})*)? </param> </data> </define> <define name="ietf-inet-types__ipv6-address"> <data type="string"> <param name="pattern">... regex pattern ...</param> </data> </define> <define name="ietf-inet-types__ip-prefix"> <choice> <ref name="ietf-inet-types__ipv4-prefix"/> <ref name="ietf-inet-types__ipv6-prefix"/> </choice> </define> <define name="ietf-inet-types__host"> <choice> <ref name="ietf-inet-types__ip-address"/> <ref name="ietf-inet-types__domain-name"/> </choice> </define> <define name="ietf-yang-types__date-and-time"> <data type="string"> <param name="pattern">... regex pattern ...</param> </data> </define> <define name="_dhcp__subnet-list"><interleave><zeroOrMore> <elementname="dhcp:subnet">name="subnet"> <elementname="dhcp:net">name="net"> <ref name="ietf-inet-types__ip-prefix"/> </element> <interleave> <optional> <elementname="dhcp:range">name="range"> <interleave> <optional> <elementname="dhcp:dynamic-bootp">name="dynamic-bootp"> <empty/> </element> </optional> <elementname="dhcp:low">name="low"> <ref name="ietf-inet-types__ip-address"/> </element> <elementname="dhcp:high">name="high"> <ref name="ietf-inet-types__ip-address"/> </element> </interleave> </element> </optional> <optional> <elementname="dhcp:dhcp-options">name="dhcp-options"> <interleave> <zeroOrMore> <elementname="dhcp:router">name="router"> <ref name="ietf-inet-types__host"/> </element> </zeroOrMore> <optional> <elementname="dhcp:domain-name">name="domain-name"> <ref name="ietf-inet-types__domain-name"/> </element> </optional> </interleave> </element> </optional> <optional> <elementname="dhcp:max-lease-time">name="max-lease-time"> <data type="unsignedInt"/> </element> </optional> </interleave> </element> </zeroOrMore></interleave> </define> <define name="ietf-inet-types__ip-prefix"> <choice> <ref name="ietf-inet-types__ipv4-prefix"/> <ref name="ietf-inet-types__ipv6-prefix"/> </choice> </define> <define name="ietf-inet-types__ipv4-prefix"> <data type="string"> <param name="pattern">... regex pattern ...</param> </data> </define> <define name="ietf-inet-types__ipv6-prefix"> <data type="string"> <param name="pattern">... regex pattern ...</param> <param name="pattern">... regex pattern ...</param> </data> </define> <define name="ietf-inet-types__ip-address"> <choice> <ref name="ietf-inet-types__ipv4-address"/> <ref name="ietf-inet-types__ipv6-address"/> </choice> </define> <define name="ietf-inet-types__ipv4-address"> <data type="string"> <param name="pattern">... regex pattern ...</param> </data></define> <definename="ietf-inet-types__ipv6-address">name="ietf-inet-types__domain-name"> <data type="string"> <param name="pattern">... regex pattern ...</param> <paramname="pattern">... regex pattern ...</param> </data> </define> <define name="ietf-inet-types__host"> <choice> <ref name="ietf-inet-types__ip-address"/> <ref name="ietf-inet-types__domain-name"/> </choice> </define> <define name="ietf-inet-types__domain-name"> <data type="string"> <paramname="minLength">1</param> <param name="maxLength">253</param><param name="pattern">... regex pattern ...</param> </data> </define> <define name="ietf-yang-types__date-and-time"> <data type="string"> <param name="pattern">... regex pattern ...</param></data> </define> <definename="ietf-yang-types__phys-address">name="ietf-inet-types__ipv4-prefix"> <data type="string"> <paramname="pattern"> ([0-9a0-fA-F]{2}(:[0-9a0-fA-F]{2})*)? </param> </data> </define> </grammar> C.3.2. RELAX NG Schema for <get> Reply - Compact Syntax default namespace = "urn:ietf:params:xml:ns:netconf:base:1.0" namespace a = "http://relaxng.org/ns/compatibility/annotations/1.0" namespace dc = "http://purl.org/dc/terms" namespace dhcp = "http://example.com/ns/dhcp" namespace nma = "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1" namespace nmt = "urn:ietf:params:xml:ns:netmod:conceptual-tree:1" include "relaxng-lib.rnc" start = element rpc-reply { message-id-attribute, element data { element dhcp:dhcp { element dhcp:max-lease-time { xsd:unsignedInt }? & element dhcp:default-lease-time { xsd:unsignedInt }? & _dhcp__subnet-list & element dhcp:shared-networks { element dhcp:shared-network { element dhcp:name { xsd:string }, (_dhcp__subnet-list) }* }? & element dhcp:status { element dhcp:leases { element dhcp:address { ietf-inet-types__ip-address }, (element dhcp:starts { ietf-yang-types__date-and-time }? & element dhcp:ends { ietf-yang-types__date-and-time }? & element dhcp:hardware { element dhcp:type { "ethernet" | "token-ring" | "fddi" }? & element dhcp:address { ietf-yang-types__phys-address }? }?) }* }? }? } } _dhcp__subnet-list = element dhcp:subnet { element dhcp:net { ietf-inet-types__ip-prefix }, (element dhcp:range { element dhcp:dynamic-bootp { empty }? & element dhcp:low { ietf-inet-types__ip-address } & element dhcp:high { ietf-inet-types__ip-address } }? & element dhcp:dhcp-options { element dhcp:router { ietf-inet-types__host }* & element dhcp:domain-name { ietf-inet-types__domain-name }? }? & element dhcp:max-lease-time { xsd:unsignedInt }?) }* ietf-inet-types__ip-prefix = ietf-inet-types__ipv4-prefix | ietf-inet-types__ipv6-prefix ietf-inet-types__ipv4-prefix = xsd:string { pattern = "... regex pattern ..." } ietf-inet-types__ipv6-prefix = xsd:string { pattern = "... regex pattern ..." pattern = "... regex pattern ..." } ietf-inet-types__ip-address = ietf-inet-types__ipv4-address | ietf-inet-types__ipv6-address ietf-inet-types__ipv4-address = xsd:string { pattern = "... regex pattern ..." } ietf-inet-types__ipv6-address = xsd:string { pattern = "... regex pattern ..." pattern = "...name="pattern">... regex pattern..." } ietf-inet-types__host = ietf-inet-types__ip-address | ietf-inet-types__domain-name ietf-inet-types__domain-name = xsd:string { minLength = "1" maxLength = "253" pattern = "......</param> </data> </define> <define name="ietf-inet-types__ipv4-address"> <data type="string"> <param name="pattern">... regex pattern..." } ietf-yang-types__date-and-time = xsd:string { pattern = "......</param> </data> </define> <define name="ietf-inet-types__ipv6-prefix"> <data type="string"> <param name="pattern">... regex pattern..." } ietf-yang-types__phys-address = xsd:string {...</param> <param name="pattern">... regex pattern= "\x{a}" ~ " ([0-9a0-fA-F]{2}(:[0-9a0-fA-F]{2})*)?\x{a}" ~ " " } C.4....</param> </data> </define> <define name="ietf-inet-types__ip-address"> <choice> <ref name="ietf-inet-types__ipv4-address"/> <ref name="ietf-inet-types__ipv6-address"/> </choice> </define> </grammar> C.3.3. Schematron Schema for<get><nc:get> Reply <?xml version="1.0" encoding="utf-8"?> <sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron"> <sch:ns uri="http://example.com/ns/dhcp" prefix="dhcp"/> <sch:ns uri="urn:ietf:params:xml:ns:netconf:base:1.0" prefix="nc"/><sch:phase id="full"> <sch:active pattern="standard"/> <sch:active pattern="ref-integrity"/> </sch:phase> <sch:phase id="noref"> <sch:active pattern="standard"/> </sch:phase><sch:patternid="standard">abstract="true" id="_dhcp__subnet-list"> <sch:ruleid="std-id2247270" abstract="true">context="$start/$pref:subnet"> <sch:reporttest="preceding-sibling::dhcp:subnet [dhcp:net=current()/dhcp:net]">test="preceding-sibling::$pref:subnet [$pref:net=current()/$pref:net]"> Duplicate keyof list dhcp:subnet"net" </sch:report> </sch:rule> <sch:rulecontext="/nc:rpc-reply/nc:data/dhcp:dhcp/ dhcp:default-lease-time">context="$start/$pref:subnet/$pref:dhcp-options/$pref:router"> <sch:report test=".=preceding-sibling::router"> Duplicate leaf-list value "<sch:value-of select="."/>" </sch:report> </sch:rule> </sch:pattern> <sch:pattern id="dhcp"> <sch:rule context="/nc:rpc-reply/nc:data/dhcp:dhcp/dhcp:default-lease-time"> <sch:assert test=". <= ../dhcp:max-lease-time"> The default-lease-time must be less thanmax-lease-time.max-lease-time </sch:assert> </sch:rule> <sch:rulecontext="/nc:rpc-reply/nc:data/dhcp:dhcp/dhcp:subnet"> <sch:extends rule="std-id2247270"/> </sch:rule> <sch:rulecontext="/nc:rpc-reply/nc:data/dhcp:dhcp/ dhcp:shared-networks/dhcp:shared-network"> <sch:report test="preceding-sibling::dhcp:shared-network [dhcp:name=current()/dhcp:name]"> Duplicate keyof list dhcp:shared-network"dhcp:name" </sch:report> </sch:rule> <sch:rule context="/nc:rpc-reply/nc:data/dhcp:dhcp/dhcp:shared-networks/dhcp:shared-network/ dhcp:subnet"> <sch:extends rule="std-id2247270"/> </sch:rule> <sch:rule context="/nc:rpc-reply/nc:data/dhcp:dhcp/dhcp:status/dhcp:leases"> <sch:report test="preceding-sibling::dhcp:leases [dhcp:address=current()/dhcp:address]"> Duplicate keyof list dhcp:leases"dhcp:address" </sch:report> </sch:rule> </sch:pattern> <sch:patternid="ref-integrity"/>id="id2768196" is-a="_dhcp__subnet-list"> <sch:param name="start" value="/nc:rpc-reply/nc:data/dhcp:dhcp"/> <sch:param name="pref" value="dhcp"/> </sch:pattern> <sch:pattern id="id2768215" is-a="_dhcp__subnet-list"> <sch:param name="start" value="/nc:rpc-reply/nc:data/dhcp:dhcp/ dhcp:shared-networks/dhcp:shared-network"/> <sch:param name="pref" value="dhcp"/> </sch:pattern> </sch:schema>C.5.C.3.4. DSRL Schema for<get><nc:get> Reply <?xml version="1.0" encoding="utf-8"?> <dsrl:maps xmlns:dsrl="http://purl.oclc.org/dsdl/dsrl" xmlns:dhcp="http://example.com/ns/dhcp" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"> <dsrl:element-map><dsrl:parent>/nc:rpc-reply/nc:data/</dsrl:parent><dsrl:parent>/nc:rpc-reply/nc:data</dsrl:parent> <dsrl:name>dhcp:dhcp</dsrl:name> <dsrl:default-content> <dhcp:max-lease-time>7200</dhcp:max-lease-time> <dhcp:default-lease-time>600</dhcp:default-lease-time> </dsrl:default-content> </dsrl:element-map> <dsrl:element-map> <dsrl:parent>/nc:rpc-reply/nc:data/dhcp:dhcp</dsrl:parent> <dsrl:name>dhcp:max-lease-time</dsrl:name> <dsrl:default-content>7200</dsrl:default-content> </dsrl:element-map> <dsrl:element-map> <dsrl:parent>/nc:rpc-reply/nc:data/dhcp:dhcp</dsrl:parent> <dsrl:name>dhcp:default-lease-time</dsrl:name> <dsrl:default-content>600</dsrl:default-content> </dsrl:element-map> <dsrl:element-map> <dsrl:parent> /nc:rpc-reply/nc:data/dhcp:dhcp/dhcp:subnet </dsrl:parent> <dsrl:name>dhcp:max-lease-time</dsrl:name> <dsrl:default-content>7200</dsrl:default-content> </dsrl:element-map> <dsrl:element-map> <dsrl:parent> /nc:rpc-reply/nc:data/dhcp:dhcp/dhcp:shared-networks/ dhcp:shared-network/dhcp:subnet </dsrl:parent> <dsrl:name>dhcp:max-lease-time</dsrl:name> <dsrl:default-content>7200</dsrl:default-content> </dsrl:element-map> </dsrl:maps> Appendix D. Change Log D.1. Changes Between Versions -05 and -06 o Terminology change: "conceptual tree schema" -> "hybrid schema". o Changed sectioning markers in the hybrid schema into plain NETMOD- specific annotations. Hence the former "nmt" namespace is not used at all. o Added the following NETMOD-specific annotations: @nma:if-feature, @nma:leaf-list, @nma:mandatory, @nma:module, removed @nma: presence. o Changed the structure of RELAX NG schemas by using embedded grammars and declaration of namespaces via @ns. This was necessary for enabling the "chameleon" behavior of global definitions. o Schematron validation phases are not used. o If an XPath expression appears inside a top-level grouping, the local prefix must be represented using the variable $pref. (This is related to the previous item.) o DHCP example: All RNG schemas are only in the XML syntax. Added RNG with global definitions. o Added [XML-INFOSET] to normative references. o Listed the terms that are defined in other documents. o The schema for NETMOD-specific annotation is now given only as RNG named pattern definitions, no more in NVDL. D.2. Changes Between Versions -04 and -05 o Removed NS prefix from document element name of the DOCTYPE declaration in the NVDL schema. D.3. Changes Between Versions -04 and -05 o Leafs that take their default value from a typedef and are not annotated with @nma:default must have @nma:implicit="true". o Changed code markers CODE BEGINS/ENDS to the form agreed by the WG. o Derived types "date-and-time" and "uri" SHOULD be mapped to XSD "dateTime" and "anyURI" types, respectively. o Clarified the notion of implicit nodes under under 'case' in Section 9.1.2. o Moved draft-ietf-netmod-yang-types-06 to normative references. o An extra <rng:group> is no more required for the default case of a choice in the shorthand notation.D.2.D.4. Changes Between Versions -03 and -04 o Implemented ordering rules for list children - keys must go first and appear in the same order as in the input YANG module. o The 'case' statement is now mapped to either <rng:group> (insideRPCs)RPC operations) or <rng:interleave> (otherwise). o A nma:default annotation coming from a datatype which the mapping expands is attached to the <rng:element> pattern where the expansion occurs. Added an example. o Documentation statements ('description', 'reference', 'status') MAY be ignored. o Single-valued numeric or length range parts are mapped to <rng: value> pattern or "length" facet. o Example for "string" datatype was added. o Appendix A now uses NVDL for defining NETMOD-specific annotations. o Added CODE BEGINS/ENDS markers. o Separated normative and informative references. o Added URL for XPath extensions namespace. o Added Section 2 (Terminology and Notation). o Added Section 14 (Security Considerations). o Added Section 15 (Acknowledgments). o Removed compact syntax schema from Appendix B. o Editorial changes: symbolic citation labels.D.3.D.5. Changes Between Versions -02 and -03 o Changed @nma:default-case to @nma:implicit. o Changed nma:leafref annotation from element to attribute. o Added skeleton rule to Section10.2.11.2. o Reworked Section10.4,11.3, added skeleton element maps,corrected the example. o AddedSection 8.5section on 'feature' and 'deviation'. o New Section 9.1 integrating discussion of both optional/mandatory (was in -02) and implicit nodes (new). o Reflected that key argument and schema node identifiers are no more XPath (should be in yang-07). o Element patterns for implicit containers now must have @nma: implicit attribute. o Removed "float32" and "float64" types and added mapping of "decimal64" with example. o Removed mapping of 'require-instance' for "leafref" type. o Updated RELAX NG schema for NETMOD-specific annotations. o Updated the DHCP example.D.4.D.6. Changes Between Versions -01 and -02 o Moved Section 7 "NETCONF Content Validation" after Section 6. o New text about mapping defaults to DSRL, especially in Section 7 and Section10.4.11.3. o Finished the DHCP example by adding the DSRL schema to Appendix C. o New @nma:presence annotation was added - it is needed for proper handling of defaultcontent.contents. o Section10.311.2.1 "Constraints on Mandatory Choice" was added because these constraints require a combination of RELAX NG and Schematron. o Fixed the schema for NETMOD-specific annotations by adding explicit prefix to all defined elements and attributes. Previously, the attributes had no namespace. o Handling of 'feature', 'if-feature' and 'deviation' added. o Handling of nma:instance-identifier via XSLT extension function.D.5.D.7. Changes Between Versions -00 and -01 o Attributes @nma:min-elements and @nma:max-elements are attached to <rng:element> (list entry) and not to <rng:zeroOrMore> or <rng: oneOrMore>. o Keys and all node identifiers in 'key' and 'unique' statements are prefixed. o Fixed the mapping of 'rpc' and 'notification'. o Removed previous sec. 7.5 "RPC Signatures and Notifications" - the same information is now contained in Section11.5010.50 and Section11.37.10.37. o Added initial "_" to mangled names of groupings. o Mandated the use of @xmlns:xxx as the only method for declaring the target namespace. o Added section "Handling of XML Namespaces" to explain the previous item. o Completed DHCP example in Appendix C. o Almost all text about the second mapping step is new. Authors' Addresses Ladislav Lhotka CESNET Email: lhotka@cesnet.cz Rohan Mahy Plantronics Email: rohan@ekabal.com Sharon Chisholm Nortel Email: schishol@nortel.com