--- 1/draft-ietf-netmod-dsdl-map-04.txt 2010-03-02 11:11:12.000000000 +0100 +++ 2/draft-ietf-netmod-dsdl-map-05.txt 2010-03-02 11:11:13.000000000 +0100 @@ -1,22 +1,33 @@ NETMOD L. Lhotka Internet-Draft CESNET Intended status: Standards Track R. Mahy -Expires: April 22, 2010 Plantronics +Expires: September 3, 2010 Plantronics S. Chisholm Nortel - October 19, 2009 + March 2, 2010 Mapping YANG to Document Schema Definition Languages and Validating NETCONF Content - draft-ietf-netmod-dsdl-map-04 + draft-ietf-netmod-dsdl-map-05 + +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 are used 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, NETCONF PDU etc. Procedures for schema- + based validation of such documents are also discussed. Status of this Memo This Internet-Draft is submitted to IETF in 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. Note that other groups may also distribute working documents as Internet- Drafts. @@ -25,43 +36,35 @@ 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 on April 22, 2010. + This Internet-Draft will expire on September 3, 2010. Copyright Notice - - Copyright (c) 2009 IETF Trust and the persons identified as the + 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 in effect on the date of - publication of this document (http://trustee.ietf.org/license-info). - Please review these documents carefully, as they describe your rights - and restrictions with respect to this document. - -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 are used 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, NETCONF PDU etc. Procedures for schema- - based validation of such documents are also discussed. + 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 BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 7 2.1. Glossary of New Terms . . . . . . . . . . . . . . . . . 8 3. Objectives and Motivation . . . . . . . . . . . . . . . . . . 10 4. DSDL Schema Languages . . . . . . . . . . . . . . . . . . . . 12 4.1. RELAX NG . . . . . . . . . . . . . . . . . . . . . . . . 12 4.2. Schematron . . . . . . . . . . . . . . . . . . . . . . . 13 @@ -77,178 +80,178 @@ 8.2. Modularity . . . . . . . . . . . . . . . . . . . . . . . 23 8.3. Granularity . . . . . . . . . . . . . . . . . . . . . . 24 8.4. Handling of XML Namespaces . . . . . . . . . . . . . . . 24 8.5. Features and Deviations . . . . . . . . . . . . . . . . 25 9. Mapping YANG Data Models to the Conceptual Tree Schema . . . 26 9.1. Occurrence Rules for Data Nodes . . . . . . . . . . . . 26 9.1.1. Optional and Mandatory Nodes . . . . . . . . . . . 27 9.1.2. Implicit Nodes . . . . . . . . . . . . . . . . . . 28 9.2. Mapping YANG Groupings and Typedefs . . . . . . . . . . 29 9.2.1. YANG Refinements and Augments . . . . . . . . . . . 31 - 9.2.2. Type derivation chains . . . . . . . . . . . . . . 34 + 9.2.2. Type Derivation Chains . . . . . . . . . . . . . . 34 9.3. Translation of XPath Expressions . . . . . . . . . . . . 37 9.4. YANG Language Extensions . . . . . . . . . . . . . . . . 37 10. Mapping Conceptual Tree Schema to DSDL . . . . . . . . . . . 39 10.1. Generating RELAX NG Schemas for Various Document Types . 39 10.1.1. Reply to or . . . . . . . . . . 40 10.1.2. Remote Procedure Calls . . . . . . . . . . . . . . 40 10.1.3. Notifications . . . . . . . . . . . . . . . . . . . 41 - 10.2. Mapping Semantic Constraints to Schematron . . . . . . . 42 10.2.1. Validation Phases . . . . . . . . . . . . . . . . . 45 10.3. Constraints on Mandatory Choice . . . . . . . . . . . . 46 10.4. Mapping Default Values to DSRL . . . . . . . . . . . . . 48 - 11. Mapping YANG Statements to Conceptual Tree Schema . . . . . . 53 - 11.1. The anyxml Statement . . . . . . . . . . . . . . . . . . 53 - 11.2. The argument Statement . . . . . . . . . . . . . . . . . 54 - 11.3. The augment Statement . . . . . . . . . . . . . . . . . 55 - 11.4. The base Statement . . . . . . . . . . . . . . . . . . . 55 - 11.5. The belongs-to Statement . . . . . . . . . . . . . . . . 55 - 11.6. The bit Statement . . . . . . . . . . . . . . . . . . . 55 - 11.7. The case Statement . . . . . . . . . . . . . . . . . . . 55 - 11.8. The choice Statement . . . . . . . . . . . . . . . . . . 55 - 11.9. The config Statement . . . . . . . . . . . . . . . . . . 56 - 11.10. The contact Statement . . . . . . . . . . . . . . . . . 56 - 11.11. The container Statement . . . . . . . . . . . . . . . . 56 - 11.12. The default Statement . . . . . . . . . . . . . . . . . 56 + 11. Mapping YANG Statements to Conceptual Tree Schema . . . . . . 52 + 11.1. The anyxml Statement . . . . . . . . . . . . . . . . . . 52 + 11.2. The argument Statement . . . . . . . . . . . . . . . . . 53 + 11.3. The augment Statement . . . . . . . . . . . . . . . . . 54 + 11.4. The base Statement . . . . . . . . . . . . . . . . . . . 54 + 11.5. The belongs-to Statement . . . . . . . . . . . . . . . . 54 + 11.6. The bit Statement . . . . . . . . . . . . . . . . . . . 54 + 11.7. The case Statement . . . . . . . . . . . . . . . . . . . 54 + 11.8. The choice Statement . . . . . . . . . . . . . . . . . . 54 + 11.9. The config Statement . . . . . . . . . . . . . . . . . . 55 + 11.10. The contact Statement . . . . . . . . . . . . . . . . . 55 + 11.11. The container Statement . . . . . . . . . . . . . . . . 55 + 11.12. The default Statement . . . . . . . . . . . . . . . . . 55 11.13. The description Statement . . . . . . . . . . . . . . . 57 - 11.14. The deviation Statement . . . . . . . . . . . . . . . . 58 - 11.15. The enum Statement . . . . . . . . . . . . . . . . . . . 58 - 11.16. The error-app-tag Statement . . . . . . . . . . . . . . 58 - 11.17. The error-message Statement . . . . . . . . . . . . . . 58 - 11.18. The extension Statement . . . . . . . . . . . . . . . . 58 - 11.19. The feature Statement . . . . . . . . . . . . . . . . . 58 - 11.20. The grouping Statement . . . . . . . . . . . . . . . . . 58 - 11.21. The identity Statement . . . . . . . . . . . . . . . . . 59 - 11.22. The if-feature Statement . . . . . . . . . . . . . . . . 59 - 11.23. The import Statement . . . . . . . . . . . . . . . . . . 59 - 11.24. The include Statement . . . . . . . . . . . . . . . . . 59 + 11.14. The deviation 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. The identity Statement . . . . . . . . . . . . . . . . . 58 + 11.22. The if-feature Statement . . . . . . . . . . . . . . . . 58 + 11.23. The import Statement . . . . . . . . . . . . . . . . . . 58 + 11.24. The include Statement . . . . . . . . . . . . . . . . . 58 11.25. The input Statement . . . . . . . . . . . . . . . . . . 59 11.26. The key Statement . . . . . . . . . . . . . . . . . . . 59 - 11.27. The leaf Statement . . . . . . . . . . . . . . . . . . . 60 - 11.28. The leaf-list Statement . . . . . . . . . . . . . . . . 60 - 11.29. The length Statement . . . . . . . . . . . . . . . . . . 61 - 11.30. The list Statement . . . . . . . . . . . . . . . . . . . 61 - 11.31. The mandatory Statement . . . . . . . . . . . . . . . . 62 - 11.32. The max-elements Statement . . . . . . . . . . . . . . . 62 + 11.27. The leaf Statement . . . . . . . . . . . . . . . . . . . 59 + 11.28. The leaf-list Statement . . . . . . . . . . . . . . . . 59 + 11.29. The length Statement . . . . . . . . . . . . . . . . . . 60 + 11.30. The list Statement . . . . . . . . . . . . . . . . . . . 60 + 11.31. The mandatory Statement . . . . . . . . . . . . . . . . 61 + 11.32. The max-elements Statement . . . . . . . . . . . . . . . 61 11.33. The min-elements Statement . . . . . . . . . . . . . . . 62 11.34. The module Statement . . . . . . . . . . . . . . . . . . 62 - 11.35. The must Statement . . . . . . . . . . . . . . . . . . . 63 + 11.35. The must Statement . . . . . . . . . . . . . . . . . . . 62 11.36. The namespace Statement . . . . . . . . . . . . . . . . 63 11.37. The notification Statement . . . . . . . . . . . . . . . 63 - 11.38. The ordered-by Statement . . . . . . . . . . . . . . . . 64 - 11.39. The organization Statement . . . . . . . . . . . . . . . 64 - 11.40. The output Statement . . . . . . . . . . . . . . . . . . 64 - 11.41. The path Statement . . . . . . . . . . . . . . . . . . . 64 + 11.38. The ordered-by Statement . . . . . . . . . . . . . . . . 63 + 11.39. The organization Statement . . . . . . . . . . . . . . . 63 + 11.40. The output Statement . . . . . . . . . . . . . . . . . . 63 + 11.41. The path Statement . . . . . . . . . . . . . . . . . . . 63 11.42. The pattern Statement . . . . . . . . . . . . . . . . . 64 11.43. The position Statement . . . . . . . . . . . . . . . . . 64 11.44. The prefix Statement . . . . . . . . . . . . . . . . . . 64 11.45. The presence Statement . . . . . . . . . . . . . . . . . 64 - 11.46. The range Statement . . . . . . . . . . . . . . . . . . 65 - 11.47. The reference Statement . . . . . . . . . . . . . . . . 65 - 11.48. The require-instance Statement . . . . . . . . . . . . . 65 - 11.49. The revision Statement . . . . . . . . . . . . . . . . . 65 + 11.46. The range Statement . . . . . . . . . . . . . . . . . . 64 + 11.47. The reference Statement . . . . . . . . . . . . . . . . 64 + 11.48. The require-instance Statement . . . . . . . . . . . . . 64 + 11.49. The revision Statement . . . . . . . . . . . . . . . . . 64 11.50. The rpc Statement . . . . . . . . . . . . . . . . . . . 65 - 11.51. The status Statement . . . . . . . . . . . . . . . . . . 66 - 11.52. The submodule Statement . . . . . . . . . . . . . . . . 66 - 11.53. The type Statement . . . . . . . . . . . . . . . . . . . 66 - 11.53.1. The empty Type . . . . . . . . . . . . . . . . . . 67 + 11.51. The status Statement . . . . . . . . . . . . . . . . . . 65 + 11.52. The submodule Statement . . . . . . . . . . . . . . . . 65 + 11.53. The type Statement . . . . . . . . . . . . . . . . . . . 65 + 11.53.1. The empty Type . . . . . . . . . . . . . . . . . . 66 11.53.2. The boolean and binary Types . . . . . . . . . . . 67 11.53.3. The bits Type . . . . . . . . . . . . . . . . . . . 67 - 11.53.4. The enumeration and union Types . . . . . . . . . . 68 - 11.53.5. The identityref Type . . . . . . . . . . . . . . . 68 - 11.53.6. The instance-identifier Type . . . . . . . . . . . 70 - 11.53.7. The leafref Type . . . . . . . . . . . . . . . . . 70 - 11.53.8. The numeric Types . . . . . . . . . . . . . . . . . 70 - 11.53.9. The string Type . . . . . . . . . . . . . . . . . . 72 - 11.53.10. Derived Types . . . . . . . . . . . . . . . . . . . 73 - 11.54. The typedef Statement . . . . . . . . . . . . . . . . . 74 - 11.55. The unique Statement . . . . . . . . . . . . . . . . . . 74 - 11.56. The units Statement . . . . . . . . . . . . . . . . . . 74 + 11.53.4. The enumeration and union Types . . . . . . . . . . 67 + 11.53.5. The identityref Type . . . . . . . . . . . . . . . 67 + 11.53.6. The instance-identifier Type . . . . . . . . . . . 69 + 11.53.7. The leafref Type . . . . . . . . . . . . . . . . . 69 + 11.53.8. The numeric Types . . . . . . . . . . . . . . . . . 69 + 11.53.9. The string Type . . . . . . . . . . . . . . . . . . 71 + 11.53.10. Derived Types . . . . . . . . . . . . . . . . . . . 72 + 11.54. The typedef Statement . . . . . . . . . . . . . . . . . 73 + 11.55. The unique Statement . . . . . . . . . . . . . . . . . . 73 + 11.56. The units Statement . . . . . . . . . . . . . . . . . . 73 11.57. The uses Statement . . . . . . . . . . . . . . . . . . . 74 - 11.58. The value Statement . . . . . . . . . . . . . . . . . . 75 - 11.59. The when Statement . . . . . . . . . . . . . . . . . . . 75 - 11.60. The yang-version Statement . . . . . . . . . . . . . . . 75 - 11.61. The yin-element Statement . . . . . . . . . . . . . . . 75 + 11.58. The value Statement . . . . . . . . . . . . . . . . . . 74 + 11.59. The when Statement . . . . . . . . . . . . . . . . . . . 74 + 11.60. The yang-version Statement . . . . . . . . . . . . . . . 74 + 11.61. The yin-element Statement . . . . . . . . . . . . . . . 74 12. Mapping NETMOD-specific annotations to DSDL Schema - Languages . . . . . . . . . . . . . . . . . . . . . . . . . . 76 - 12.1. The @nma:config Annotation . . . . . . . . . . . . . . . 76 - 12.2. The @nma:default Annotation . . . . . . . . . . . . . . 76 - 12.3. The @nma:implicit Annotation . . . . . . . . . . . . . . 76 - 12.4. The Annotation . . . . . . . . . . . 76 - 12.5. The Annotation . . . . . . . . . . . 76 - 12.6. The Annotation . . . . . . . . 76 - 12.7. The @nma:key Annotation . . . . . . . . . . . . . . . . 77 - 12.8. The @nma:leafref Annotation . . . . . . . . . . . . . . 77 - 12.9. The @nma:min-elements Annotation . . . . . . . . . . . . 77 - 12.10. The @nma:max-elements Annotation . . . . . . . . . . . . 78 - 12.11. The Annotation . . . . . . . . . . . . . . . 78 - 12.12. The Annotation . . . . . . . . . . . . 78 - 12.13. The Annotation . . . . . . . . . . . . . . 78 - 12.14. The @nma:unique Annotation . . . . . . . . . . . . . . . 78 - 12.15. The @nma:when Annotation . . . . . . . . . . . . . . . . 79 - 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 80 - 14. Security Considerations . . . . . . . . . . . . . . . . . . . 81 - 15. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 82 - 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 83 - 16.1. Normative References . . . . . . . . . . . . . . . . . . 83 - 16.2. Informative References . . . . . . . . . . . . . . . . . 84 - Appendix A. Schemas for NETMOD-Specific Annotations . . . . . . 87 - A.1. NVDL Schema . . . . . . . . . . . . . . . . . . . . . . 87 - A.2. Annotation Attributes for define Pattern . . . . . . . . 89 - A.3. Annotation Elements for element Pattern . . . . . . . . 89 - A.4. Annotation Attributes for element Pattern . . . . . . . 90 - A.5. Annotation attributes for group Pattern . . . . . . . . 90 - A.6. Annotation attributes for choice and ref Patterns . . . 91 + Languages . . . . . . . . . . . . . . . . . . . . . . . . . . 75 + 12.1. The @nma:config Annotation . . . . . . . . . . . . . . . 75 + 12.2. The @nma:default Annotation . . . . . . . . . . . . . . 75 + 12.3. The @nma:implicit Annotation . . . . . . . . . . . . . . 75 + 12.4. The Annotation . . . . . . . . . . . 75 + 12.5. The Annotation . . . . . . . . . . . 75 + 12.6. The Annotation . . . . . . . . 75 + 12.7. The @nma:key Annotation . . . . . . . . . . . . . . . . 76 + 12.8. The @nma:leafref Annotation . . . . . . . . . . . . . . 76 + 12.9. The @nma:min-elements Annotation . . . . . . . . . . . . 76 + 12.10. The @nma:max-elements Annotation . . . . . . . . . . . . 77 + 12.11. The Annotation . . . . . . . . . . . . . . . 77 + 12.12. The Annotation . . . . . . . . . . . . 77 + 12.13. The Annotation . . . . . . . . . . . . . . 77 + 12.14. The @nma:unique Annotation . . . . . . . . . . . . . . . 77 + 12.15. 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. Schemas for NETMOD-Specific Annotations . . . . . . 86 + A.1. NVDL Schema . . . . . . . . . . . . . . . . . . . . . . 86 + A.2. Annotation Attributes for define Pattern . . . . . . . . 88 + A.3. Annotation Elements for element Pattern . . . . . . . . 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 . . . 90 A.7. Annotation attributes for element Pattern in the List - Context . . . . . . . . . . . . . . . . . . . . . . . . 91 - A.8. Annotation attributes for value Pattern . . . . . . . . 92 - A.9. Named Patterns for All NETMOD-Specific Annotations . . . 92 - Appendix B. Schema-Independent Library . . . . . . . . . . . . . 96 - Appendix C. Mapping DHCP Data Model - A Complete Example . . . . 97 - C.1. Input YANG Module . . . . . . . . . . . . . . . . . . . 97 - C.2. Conceptual Tree Schema . . . . . . . . . . . . . . . . . 100 - C.2.1. XML Syntax . . . . . . . . . . . . . . . . . . . . 100 - C.2.2. Compact Syntax . . . . . . . . . . . . . . . . . . 105 - C.3. Final DSDL Schemas . . . . . . . . . . . . . . . . . . . 107 - C.3.1. RELAX NG Schema for Reply - XML Syntax . . . 108 - C.3.2. RELAX NG Schema for Reply - Compact Syntax . 112 - C.4. Schematron Schema for Reply . . . . . . . . . . . 114 - C.5. DSRL Schema for Reply . . . . . . . . . . . . . . 116 - Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 117 - D.1. Changes Between Versions -03 and -04 . . . . . . . . . . 117 - D.2. Changes Between Versions -02 and -03 . . . . . . . . . . 117 - D.3. Changes Between Versions -01 and -02 . . . . . . . . . . 118 - D.4. Changes Between Versions -00 and -01 . . . . . . . . . . 119 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 120 + Context . . . . . . . . . . . . . . . . . . . . . . . . 90 + A.8. Annotation attributes for value Pattern . . . . . . . . 91 + A.9. Named Patterns for All NETMOD-Specific Annotations . . . 91 + Appendix B. Schema-Independent Library . . . . . . . . . . . . . 95 + Appendix C. Mapping DHCP Data Model - A Complete Example . . . . 96 + C.1. Input YANG Module . . . . . . . . . . . . . . . . . . . 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 Reply - XML Syntax . . . 107 + C.3.2. RELAX NG Schema for Reply - Compact Syntax . 111 + C.4. Schematron Schema for Reply . . . . . . . . . . . 113 + C.5. DSRL Schema for Reply . . . . . . . . . . . . . . 115 + Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 116 + D.1. Changes Between Versions -04 and -05 . . . . . . . . . . 116 + D.2. Changes Between Versions -03 and -04 . . . . . . . . . . 116 + D.3. Changes Between Versions -02 and -03 . . . . . . . . . . 117 + D.4. Changes Between Versions -01 and -02 . . . . . . . . . . 117 + D.5. Changes Between Versions -00 and -01 . . . . . . . . . . 118 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 119 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 modeling language or accompanying rules for how to model configuration and status 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 rather than additional semantic + 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 + 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 its protocol data units (PDU), 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 as ISO/IEC 19757 [DSDL]. The DSDL framework comprises a set of XML schema languages that address grammar rules, semantic constraints and other data modeling aspects but also, and more importantly, do it in a coordinated and consistent way. While @@ -288,40 +291,40 @@ 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] + "a" DTD compatibility annotations [RNG-DTD]; - "dc" Dublin Core metadata elements [RFC5013] + "dc" Dublin Core metadata elements [RFC5013]; - "dsrl" Document Semantics Renaming Language [DSRL] + "dsrl" Document Semantics Renaming Language [DSRL]; - "en" NETCONF event notifications [RFC5277] + "en" NETCONF event notifications [RFC5277]; - "nc" NETCONF protocol [RFC4741] + "nc" NETCONF protocol [RFC4741]; - "nma" NETMOD-specific schema annotations (see Section 5.3) + "nma" NETMOD-specific schema annotations (see Section 5.3); - "nmf" NETMOD-specific XPath extension functions + "nmf" NETMOD-specific XPath extension functions (see Section 12.6); - "nmt" Conceptual tree (see Section 8.1) + "nmt" Conceptual tree (see Section 8.1); - "rng" RELAX NG [RNG] + "rng" RELAX NG [RNG]; - "sch" ISO Schematron [Schematron] - "xsd" W3C XML Schema [XSD] + "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 | @@ -357,52 +360,52 @@ o conceptual data tree: A virtual 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 serves as a conceptual target for its schema. 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 for the NETCONF server. + 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, primarily RELAX NG and Schematron. This document + languages, namely RELAX NG, Schematron and DSRL. This document describes the correspondence between grammatical, semantic and data type constraints expressed in YANG and equivalent DSDL constructs. 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 document is in principle invertible, the inverse mapping from DSDL to YANG is not in its scope. 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, RPC methods are characterized by an inherent diversity resulting from selective availability of capabilities and features. YANG modules can also define new RPC methods. 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 schemas - can be generated on demand 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. + can 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 to the existing 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 a single RELAX NG @@ -417,21 +420,21 @@ 2. In the second step, the annotated RELAX NG 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 as an international standard ISO/ - IEC 19757. Unlike other approaches to XML document validation, + 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 @@ -457,36 +460,36 @@ 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 generally require the XML syntax. However, the + 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 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 for the XML syntax. - o In a computer program, it is more difficult to generate compact - syntax than XML syntax. While a number of software libraries - exist that make it easy to create an XML tree in memory and - serialize it, no such aid is available for compact 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 memory + and serialize it, no such aid is available for compact syntax. For these reasons, the mapping specification in this document uses exclusively the XML syntax. Where appropriate, though, the schemas resulting from the translation may 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". @@ -512,70 +515,71 @@ 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 future). + 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-readable error messages are another feature that distinguishes Schematron from other common schema languages. The messages may even contain XPath expressions that are evaluated in the actual context and thus refer to existing XML document nodes and - their content. + their contents. The rules defined by a Schematron schema may be divided into several - subsets known as _phases_. Validations may then be set up to include + subsets known as phases. Validations may then be set up to include only selected phases. In the context of NETCONF data validation, this is useful for relaxing constraints that may not always apply. For example, the reference integrity may not be enforced for a candidate configuration. 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, it is specifically designed 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 default content for XML elements so that elements or attributes with these default values 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 values for leaf nodes. + 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 the conceptual tree schema and MAY also appear in the final validation schemas. The third set are NETMOD-specific annotations conveying YANG semantic - constraints and other information that cannot be expressed natively + 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 @@ -598,24 +602,24 @@ 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" that appear in - various locations in the conceptual tree schema. YANG statements are + various locations of the conceptual tree schema. YANG statements are mapped to these annotations in a straightforward way. In most cases, - the annotation attributes and elements always have the same name as - the corresponding YANG statement. + 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 contains the formal specification of this annotation vocabulary. +---------------------------+--------------------+------+ | annotation | section | note | +---------------------------+--------------------+------+ @@ -689,102 +693,103 @@ +---------+ +-----+ +-------+ +------+ 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 to a single RELAX NG schema for the conceptual tree (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 simple - annotations belonging to special namespaces. + various documentation texts are recorded in the schema as + foreign-namespace annotations. 2. In the second step, the conceptual tree schema is 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 shows just three simple possibilities as examples. In the process, appropriate parts of the conceptual tree 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 algorithm accepts 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 + An implementation of the mapping algorithm is supposed to 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 multiple roots. 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 module(s) imports (transitively). + to all YANG modules that the input modules import (perhaps + 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 agent, + 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 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. + 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 constraints or default values, are recorded in the conceptual tree 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 to annotations utilizing Dublin Core elements (Section 5.1). Finally, documentation - strings are mapped to the elements belonging to the - DTD compatibility vocabulary (Section 5.2). + strings are mapped to elements belonging to the DTD + compatibility vocabulary (Section 5.2). The output from 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 a specification of default content. + 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 the content of a datastore or various NETCONF PDUs. The validation proceeds in the following steps, which are also illustrated in Figure 2: 1. The XML instance document can be immediately checked for grammatical and data type validity using the RELAX NG schema. 2. Second, default values for leaf nodes have to be applied and their ancestor containers added where necessary. It is important - to apply the defaults before the next validation step because + to add the implicit nodes before the next validation step because YANG specification [YANG] states 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 input XML document. + the validated XML document. 3. The semantic constraints are checked using the Schematron schema. +----------+ +----------+ | | | XML | | XML | | document | | document |-----------o----------->| with | | | ^ | defaults | | | | | | +----------+ | +----------+ @@ -814,30 +819,30 @@ represents the contents of a datastore but also implies an array of schemas for all types of NETCONF PDUs. For a reasonably strict validation of a given data object, the schemas have to be quite specific. To begin with, effective validation of NETCONF PDU content requires separation of client and server schemas. While the decision about proper structuring of all PDU-validating schemas is beyond the scope of this document, the mapping procedure is designed to accommodate any foreseeable validation needs. An essential part of the YANG-to-DSDL mapping procedure is - nonetheless common to all validation approaches: the grammar and - datatype specifications for the datastore, RPCs and notifications - expressed by one or more YANG modules have to be translated to RELAX - NG. In order to be able to separate this common step, we introduce - the notion of _conceptual data tree_: it is a virtual XML tree that - contains full datastore, RPC requests with corresponding replies and - notifications. The schema for the conceptual tree - a single RELAX - NG schema with annotations - therefore has a quite similar logic as - the input YANG module(s), the only major difference being the RELAX - NG schema language. + nonetheless common to all validation needs: the grammar and datatype + specifications for the datastore, RPCs and notifications expressed by + one or more YANG modules have to be translated to RELAX NG. In order + to be able to separate this common step, we introduce the notion of + conceptual data tree: it is a virtual XML tree that contains full + datastore, RPC requests with corresponding replies and notifications. + The schema for the conceptual tree - a single RELAX NG schema with + annotations - therefore has a quite similar logic as the input YANG + module(s), the only major difference being the RELAX NG schema + language. For example, the conceptual data tree for a YANG module defining nodes in the namespace "http://example.com/ns/example" may be schematically represented as follows: ... configuration and status data ... @@ -876,21 +881,22 @@ 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, is represented 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 translated to equivalent Schematron and DSRL rules. + 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 defined in one 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 element. 8.2. Modularity @@ -969,45 +975,45 @@ counterparts in YANG groupings and definitions of derived types. 8.4. Handling of XML Namespaces Most modern XML schema languages including RELAX NG, Schematron and DSRL support schemas for so-called compound XML documents, which contain elements from multiple namespaces. This is useful for our purpose since YANG-to-DSDL mapping allows for multiple input YANG modules that naturally leads to compound document schemas. - RELAX NG offers two alternatives for defining the "target" namespaces + 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 both cases these attributes are typically attached to the element. + In both cases, these attributes are typically attached to the element but may also appear elsewhere. The design decision for the mapping is to use exclusively the alternative 1, since in this case all YANG modules are represented symmetrically, which makes further processing of the conceptual tree schema considerably easier. Moreover, this way the namespace prefixes declared in the input modules are recorded in the resulting schema - the prefix for the namespace declared using @ns would be lost. DSRL schemas can declare any number of target namespaces via the standard XML attributes xmlns:xxx. - In contrast, Schematron requires all the target namespaces to be - defined in the subelements of the root element. + In contrast, Schematron requires all target namespaces to be defined + in the subelements of the root 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. @@ -1024,51 +1030,51 @@ conceptual tree - the element with all its contents. The output RELAX NG schema will then contain only named pattern definitions translated from YANG groupings and typedefs. Detailed specification of the mapping of individual YANG statements is contained in Section 11. 9.1. Occurrence Rules for Data Nodes In DSDL schema languages, occurrence constraints for a node are - always localized together with that node. In RELAX NG, for example, - pattern appears as the parent element of the pattern - defining the node in the schema, be it a leaf or container node. - Similarly, DSRL specifies default content separately for every single - node, be it a leaf or non-leaf element. + always localized together with that node. In a RELAX NG schema, for + example, pattern appears as the parent element of the + pattern defining a leaf or non-leaf element. Similarly, DSRL + specifies default content 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, 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 all containers and mark accordingly the corresponding patterns in the conceptual tree 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 given container element must always be present in a valid configuration. If so, such a container element is called mandatory, otherwise it is called optional. This - constraint is very closely related to the notion of mandatory nodes - in Section 3.1 in [YANG]. The only difference is that we also - consider list keys to be mandatory. + constraint is closely related to the notion of mandatory nodes in + Section 3.1 in [YANG]. The only difference is that we also consider + 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. - Such elements are called implicit. + In this document, such elements are called implicit. 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 { @@ -1094,91 +1100,95 @@ 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 for other types of nodes - as well, i.e., leaf, list, leaf-list and anyxml. + characteristics, it is useful to define them also for other types of + data nodes, i.e., leaf, list, leaf-list and anyxml. 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, leaf nodes are mandatory if they are declared as list keys. o List or leaf-list nodes are mandatory if they contain 'min- elements' substatement with 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 iff it is not 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 element. The mapping MUST use the above rules to determine whether a YANG node is optional and if so, insert the element in the conceptual tree schema. However, alternatives in are never defined as optional in the conceptual tree schema. Therefore, 'anyxml', 'container', 'leaf', 'list' and 'leaf-list' statements appearing as children of - 'choice' (shorthand cases) are always mapped to mandatory RELAX NG - patterns. If a choice in YANG is not mandatory, is - used to wrap the entire pattern. + 'choice' (so-called shorthand cases) are always mapped to mandatory + RELAX NG patterns. If a choice in YANG is not mandatory, is used to wrap the entire 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 a specified default value (either directly or via its datatype). o A container node is implicit if and only if it does not have the 'presence' substatement, none of its children is mandatory and at least one child is implicit. - o As an exception to the above two rules, a leaf or container node - appearing inside a case of a choice can be implicit only if that - case is declared as default by using the 'default' statement, see - Section 7.9.3 in [YANG]. + In the conceptual tree schema, all implicit containers, as well as + leafs that obtain their default value from a typedef and don't have + the @nma:default attribute, MUST be marked with @nma:implicit + attribute having the value "true". - In the conceptual tree schema, all implicit containers MUST be marked - with @nma:implicit attribute with the value "true". In addition, the - default case in a choice (defined by the 'default' substatement of - 'choice') MUST be also marked in the same way, i.e., by @nma:implicit - set to "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 Section 10.4. 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]. Moreover, top-level symbols from external modules are + 5.5 in [YANG]. Second, top-level symbols from external modules are 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 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 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: @@ -1267,41 +1277,43 @@ ... regex pattern ... ... regex pattern ... + 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 YANG allows for modifying - _expansions_ of groupings. Specifically, YANG provides two - statements for this purpose that may appear as substatements of - 'uses': + themselves are modified whereas YANG allows for modifying expansions + of groupings. Specifically, YANG provides two statements for this + purpose that may appear as substatements of 'uses': 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 grouping content. Both 'refine' and 'augment' statements are quite powerful in that - they can address, using XPath-like expressions as arguments, schema - nodes that are arbitrarily deep inside the grouping content. In - contrast, modifications of named pattern definitions in RELAX NG are - applied exclusively at the topmost level of the named pattern + they can address, using XPath-like expressions as their arguments, + schema nodes that are arbitrarily deep inside the grouping content. + In contrast, modifications of named pattern definitions in RELAX NG + are applied exclusively at the topmost level of the named pattern content. In order to achieve a modifiability of named patterns comparable to YANG, the 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 the content of the corresponding grouping, the changes specified in the 'refine' and @@ -1357,62 +1369,57 @@ and the configuration data part of the conceptual tree schema is a single named pattern reference: - Now assume that the "uses leaves" statement is refined: + Now assume that the "uses leaves" statement contains a 'refine' + substatement, for example: uses leaves { refine "hoja" { default "alamo"; } } The resulting conceptual tree 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 the conceptual tree now - looks like this: + refined. The configuration data part of the conceptual tree schema + now looks like this: -9.2.2. Type derivation chains - - RELAX NG has no equivalent of the type derivation mechanism in YANG, - where a ancestor built-in type may be modified (perhaps in multiple - steps) by adding new restrictions. Therefore, when mapping YANG - derived types with restrictions, the derived types MUST be "unwound" - all the way back to the ancestor built-in type. At the same time, - all restrictions found along the type derivation chain MUST be - combined and their intersection used as facets restricting the - corresponding type in RELAX NG. +9.2.2. Type Derivation Chains - When a derived YANG type is used without restrictions - as a - substatement of either 'leaf' or another 'typedef' - the 'type' - statement is mapped simply to the element, i.e., a named - pattern reference. However, if 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 the output schema, restricted with facets that again - correspond to the combination of all restrictions found along the - type derivation chain and also in the 'type' statement. + RELAX NG has no equivalent of the type derivation mechanism in YANG + that allows to modify a built-in type (perhaps in multiple steps) by + adding new restrictions. When a derived YANG type is used without + restrictions - as a substatement of either 'leaf' or another + 'typedef' - the 'type' statement is mapped simply to the + element, i.e., a named pattern reference, and the type definition is + mapped to a RELAX NG named pattern definition. However, if + 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 the output 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; } @@ -1501,70 +1508,70 @@ However, if the definition of leaf "month" itself contained the 'default' substatement, the default specified for the "dozen" type will 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. However, since 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 needn't carry a - namespace prefix inside the module where they are defined, in which - case the module's namespace is assumed. + '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 needn't carry a namespace prefix + inside the module where they are defined and the local module's + namespace is assumed. If an XPath expression is carried over to a NETMOD-specific annotation in the conceptual tree schema, it MUST be translated into a fully conformant XPath 1.0 expression that also reflects the hierarchy of the conceptual data tree: 1. Each unprefixed node name MUST be prepended with the local module's namespace prefix declared by the 'prefix' statement. 2. Absolute XPath expressions, i.e., those starting with a slash, MUST be prepended with appropriate path in the conceptual tree, according to the YANG specification of context for XPath - expressions, see [YANG], sections 7.5.3 and 7.19.5 in [YANG]. + expressions, see [YANG], Sections 7.5.3 and 7.19.5. Translation rule 2 means for example that absolute XPath expressions appearing in the main configuration data tree always start with "nmt: netmod-tree/nmt:top/", those appearing in a notification always start with "nmt:netmod-tree/nmt:notifications/nmt:notification/", etc. EXAMPLE. YANG XPath expression "/dhcp/max-lease-time" appearing in the main configuration data will be translated to "nmt:netmod-tree/ nmt:top/dhcp:dhcp/dhcp:max-lease-time". The key identifiers and "descendant schema node identifiers" (see the ABNF production for and "descendant-schema-nodeid" in Section 12 of [YANG]) are not XPath expressions but SHOULD 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 - can be used as the native statements, only with 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 every place of a RELAX NG - schema. + 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. + 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: @@ -1580,72 +1587,73 @@ Note that the 'extension' statement itself is not mapped in any way. 10. Mapping Conceptual Tree Schema to DSDL As explained in Section 6, the second step of the YANG-to-DSDL mapping takes the conceptual tree schema and transforms it to various - DSDL schemas ready for validation. As an input parameter, this step - gets in the simplest case a specification of the NETCONF XML document - type (or combination of multiple types) that is to be validated. - These document type can be, for example, the content of a datastore, - reply to or , other RPC requests or replies - and notifications. + DSDL schemas prepared for validating instance XML documents. As an + input parameter, this step takes in the simplest case just a + specification of the NETCONF XML document type (or combination of + multiple types) that is to be validated. These document type can be, + for example, the content of a datastore, reply to or , other RPC requests or replies and notifications. In general, the second mapping step has to accomplish the following three tasks: 1. Extract the part(s) of the conceptual tree schema that are appropriate for the requested document type. For example, if a reply is to be validated, the subtree under must be selected. 2. The schema must be adapted to the specific encapsulating XML elements mandated by the RPC layer. These are, for example, and elements in the case of a datastore or and elements in the case of a reply or for a notification. 3. Finally, NETMOD-specific annotations that are relevant for the - schema language of the generated schema must be mapped to - corresponding schema-language-specific rules. + schema language of the generated schema must be mapped to the + corresponding rules. These three tasks are together much simpler than the first mapping - step. Presumably, they can be effectively realized using XSL - transformations [XSLT]. + step and can be effectively implemented using XSL transformations + [XSLT]. The following subsections describe the details of the second mapping step for the individual DSDL schema languages. Section 12 then contains a detailed specification for the mapping of all NETMOD- 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 parts - from the conceptual tree schema and assembling them in a new RELAX NG + of the conceptual tree schema and assembling them in a new RELAX NG grammar, perhaps after removing all unwanted annotations. Depending on the XML document type that is the target for validation (/ 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 element. - In order to avoid copying identical named pattern definitions to the - output RELAX NG file, these schema-independent definitions SHOULD be - collected in a library file which is then included by the validating - RELAX NG schemas. Appendix B has the listing of this library file. + In order to avoid copying common named pattern definitions to every + single output RELAX NG file, these schema-independent definitions + SHOULD be collected in a library file which is then included by the + validating RELAX NG schemas. Appendix B has the listing of this + library file. The minor exception mentioned above is the annotation @nma:config, which must be observed if the target document type is reply. In this case, each element definition that has this attribute with the value "false" MUST be removed from the schema together with its descendants. See Section 12.1 for more details. 10.1.1. Reply to or For a reply to or , the mapping must take the part @@ -1662,58 +1670,58 @@ ... named pattern definitions ... The definition for the named pattern "message-id-attribute" is found in the library file "relaxng-lib.rng" which is included on the second line (see Appendix B). - Definitions of other named patterns MUST be copied from the - conceptual tree schema without any changes to the resulting grammar. - However, an implementation MAY choose to copy only those definitions - that are really used in the particular output grammar. + Definitions of other named patterns MUST be copied literally from the + conceptual tree schema to the resulting grammar. However, an + implementation MAY choose to copy only those definitions that are + really used in the particular output grammar. 10.1.2. Remote Procedure Calls For an RPC method named "myrpc" and defined in a YANG module with prefix "yam", the corresponding schema subtree is identified by the definition of element whose subelement has as the only child. The mapping must also take into account whether the target document type is an RPC request or reply. For "yam:myrpc" request, the resulting grammar looks as follows: - ... patterns defining contents of subtree ... + ... patterns defining contents of the subtree ... ... "nmt:rpc-method/nmt:input/yam:myrpc" ... ... named pattern definitions ... - For "myrpc" reply, the output grammar is + For "yam:myrpc" reply, the output grammar is - ... patterns defining contents of corresponding ... + ... patterns defining contents of the corresponding ... ... "nmt:rpc-method/nmt:output" subtree ... ... named pattern definitions ... In both cases, exact copies of named pattern definitions from the conceptual tree schema MUST be inserted, but an implementation MAY choose to include only those used for the given RPC. @@ -1747,59 +1755,60 @@ tree schema MUST be inserted, but an implementation MAY choose to include only those used for the given notification. 10.2. Mapping Semantic Constraints to Schematron Schematron schemas tend to be much flatter and more uniform compared to RELAX NG. They have exactly four levels of XML hierarchy: , , and or . In a Schematron schema generated by the second mapping step, the - basic unit of organization is a _rule_ represented by the + basic unit of organization is a rule represented by the element. Every rule corresponds to exactly one element definition pattern in the conceptual tree schema: ... - The value of the mandatory @context attribute of is set to - the absolute path of the context element in the data tree. The element contains the mappings of one or more of the following - NETMOD-specific annotations, if they are attached to the context - element: , @nma:key, @nma:leafref, @nma:min- - elements, @nma:max-elements, , @nma:unique and . + The value of the mandatory @context attribute of (denoted + as XELEM) MUST be set to the absolute path of the context element in + the data tree. The element contains the mappings of one + or more of the following NETMOD-specific annotations, if they are + attached to the context element: , @nma:key, + @nma:leafref, @nma:min-elements, @nma:max-elements, , @nma: + unique and . In the opposite direction, however, not every element definition pattern in the conceptual tree schema has a corresponding rule in the Schematron schema: definitions of elements the carry none of the above annotations are omitted. - Schematron rules may be further grouped into _patterns_ represented - by the element. The mapping uses patterns only for + Schematron rules may be further grouped into patterns represented by + the element. The mapping uses patterns only for discriminating between subsets of rules that belong to different validation phases, see Section 10.2.1. Therefore, the always has exactly two children: one named "standard" contains rules for all annotations except and @nma:leafref, and another 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 among its ancestors) are subject to a different treatment. This is because their path in the data tree is not fixed - the named pattern may be - referred to in multiple different places. The mapping uses - Schematron _abstract rules_ to handle this case: An element - definition inside a named pattern is mapped to an abstract rule and - every use of the named pattern then extends (uses) this abstract rule - in the concrete context. + referred to in multiple places. The mapping uses Schematron abstract + rules to handle this case: An element definition inside a named + pattern is mapped to an abstract rule and every use of the named + pattern then extends (uses) this abstract rule in the concrete + context. EXAMPLE. Consider this element pattern annotated with : The default-lease-time must be less than max-lease-time @@ -1865,46 +1874,46 @@ prefix) MUST be declared using the element, for example 3. Validation phases are defined (see Section 10.2.1) and their constituting patterns "standard" and "ref-integrity" created. 4. For either validation phase, the input conceptual tree schema is scanned and element definitions with annotations relevant for the given phase are selected and a is created for each of - them. The rule is abstract if the element definition appears - inside a named pattern, see above. + them. As explained above, the rule is abstract if the element + definition appears inside a named pattern. 5. All annotations attached to the given element definition are then mapped using the mapping rules specified in Section 12. The resulting or elements are the installed as children of the element. 10.2.1. Validation Phases In certain situations it is useful to validate XML instance documents without enforcing the referential integrity constraints represented by the @nma:leafref and 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_: + 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 both patterns are used by + 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 for each phase. Therefore, the mapping puts the rules for referential integrity checking to a special with @id attribute set to "ref-integrity". The rules mapped from the remaining semantic constraints are put to another with @id attributes set to "standard". @@ -2002,25 +2011,25 @@ Node(s) from at least one case of choice "foobar" must exist. 10.4. Mapping Default Values to DSRL DSRL is the only component of DSDL that is allowed to change the - information set of the validated XML document. While DSRL has other - functions, the YANG-to-DSDL mapping uses it only for specifying - default content. For XML instance documents based on YANG data - models, insertion of default content may potentially take place for - all implicit nodes, see Section 9.1. + information set of the validated XML document. While DSRL also has + 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 by the rules in Section 9.1.2. In DSRL, the default content of an element is specified using the element, which is a child of . Two sibling elements of determine the context for application of the default content, see [DSRL]: o element contains an XSLT pattern specifying the parent element; the default content is applied only if the parent element exists in the instance document. @@ -2028,70 +2037,84 @@ or empty, is inserted together with the content of . The element is optional in a general DSRL schema but for the purpose of the YANG-to-DSDL mapping this element MUST be always present in order to guarantee proper application of default content. DSRL mapping only deals with element patterns defining implicit nodes (see Section 9.1.2). In the conceptual tree schema, such element - patterns are distinguished by NETMOD-specific annotation attributes - @nma:default or @nma:implicit, i.e., either + patterns are distinguished by having NETMOD-specific annotation + attributes @nma:default or @nma:implicit, i.e., either ... or ... - In the simple case, these element patterns are mapped to the + The former case applies to leaf nodes having the 'default' + substatement, but also to leaf nodes that obtain their default value + from a typedef, if this typedef is expanded according to the rules in + Section 9.2.2 so that the @nma:default annotation is attached + directly to the leaf's element pattern. + + The latter 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 to the following DSRL element map: XPARENT ELEM DEFCONT where XPARENT is the absolute XPath of ELEM's parent element in the data tree and DEFCONT is constructed as follows: - o If the element pattern defining ELEM is annotated with @nma: - default, DEFCONT is equal to the value of this attribute (denoted + 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 Otherwise, if the element pattern defining ELEM is annotated with - @nma:implicit, DEFCONT is an XML fragment containing all - descendant elements of ELEM that have either @nma:implicit or - @nma:default attribute. + o If the implicit node ELEM is a leaf and has the @nma:implicit + attribute with the value "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. - Inside the subtree of , the @nma:default and @nma: - implicit annotations MUST be ignored unless they are descendants of a - or pattern with @nma:implicit attribute - set to "true" - this corresponds to the default case of a YANG choice - (see Section 11.12). + 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. - When mapping such a default case, it has to be guaranteed that the - default content is be applied if any of the nodes from any non- - default case are present. This is accomplished by setting in a special way: + The , or patterns appearing + directly under MUST NOT have either @nma:default or + @nma:implicit annotation unless they belong to the default 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 + in a special way: XPARENT[not (ELEM1|ELEM2|...|ELEMn)] - where ELEM1, ELEM2, ... ELEMn are the names of top-level nodes from - all non-default cases. The rest of the element map is exactly as - above. + 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 example5 { namespace "http://example.com/ns/example5"; prefix ex5; container outer { leaf leaf1 { type uint8; default 1; @@ -2148,42 +2171,30 @@ /nc:rpc-reply/nc:data/ex5:outer/ex5:one ex5:leaf2 2 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 can never become an implicit element. - - YANG leaf nodes may also obtain a default value from their type - definition. Consequently, @nma:default attributes may also be - attached to elements. The DSRL mapping MUST handle all - patterns that refer to such a named pattern definition - and don't have their own @nma:default attribute in the same way as if - the @nma:default attributed was attached to the referring . - - Finally, if there is a chain of named pattern definitions containing - multiple @nma:default attributes, only the topmost @nma:default - annotation is taken into account. + ignored because "leaf3" represents a non-default alternative of a + 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 how the statement is mapped to the annotated RELAX NG schema of the conceptual tree. This is the first - step of the mapping procedure, see Section 6. The subsections are - sorted alphabetically by the statement keyword. + step of the mapping procedure as explained in Section 6. The + subsections are sorted alphabetically by the statement keyword. Each YANG statement is mapped to an XML fragment, typically a single element or attribute but it may also be a larger structure. The mapping procedure is inherently recursive, which means that after finishing a statement the mapping continues with its substatements, if there are any, and a certain element of the resulting fragment becomes the parent of other fragments resulting from the mapping of substatements. Any changes to this default recursive procedure are explicitly specified. @@ -2198,35 +2209,35 @@ 2. When mapping the 'list' statement, all keys MUST come before any other subelements and in the same order as they are declared in the 'key' statement. The order of the remaining (non-key) subelements is not specified, so their definitions in the conceptual tree schema MUST be enclosed in the element. 3. Otherwise, all definitions of subelements in the conceptual tree schema MUST be enclosed in the element. - We use the following notation: + We use the following conventions: o The argument of the statement being mapped is denoted by ARGUMENT. o The element in the RELAX NG schema that becomes the parent of the resulting XML fragment is denoted by PARENT. 11.1. The anyxml Statement This statement is mapped to element and ARGUMENT with prepended local namespace prefix becomes the value of its @name attribute. The content of is - Substatements of the 'anyxml' statement, if any, may be mapped to + Substatements of the 'anyxml' statement, if any, MAY be mapped to additional children of the RELAX NG element definition. If the 'anyxml' statement occurs in any of the input YANG modules, the following pattern definition MUST be added exactly once to the RELAX NG schema as a child of the element (cf. [Vli04], p. 172): @@ -2294,48 +2305,48 @@ This statement is handled within the "bits" type, see Section 11.53.3. 11.7. The case Statement This statement is mapped to or element, depending on whether the statement belongs to an RPC definition or not. If the argument of a sibling 'default' statement equals to ARGUMENT, @nma:implicit attribute with the value "true" MUST be added to that or element. The @nma:implicit - attribute MUST NOT be used for nodes that belong to non-default cases - of a choice (see Section 7.9.3 in [YANG]). + attribute MUST NOT be used for nodes at the top-level of a non- + default case (see Section 7.9.3 in [YANG]). 11.8. The choice Statement This statement is mapped to element. Unless 'choice' has the 'mandatory' substatement with the value "true", the element MUST be wrapped in . - The 'choice' statement with "mandatory true;" requires additional + The 'choice' statement with "mandatory true;" may require additional handling, see Section 10.3. The alternatives in - mapped from either the 'case' statement or a shorthand case - MUST NOT be defined as optional. 11.9. The config Statement This statement is mapped to @nma:config attribute and ARGUMENT becomes its value. 11.10. The contact Statement - This statement is not used by the mapping since the output RELAX NG - schema may result from multiple YANG modules created by different - authors. The schema contains references to all input modules in the - Dublin Core elements , see Section 11.34. The original - YANG modules are the authoritative sources of the authorship - information. + This statement SHOULD NOT be used by the mapping since the output + RELAX NG schema may result from multiple YANG modules created by + different authors. The schema contains references to all input + modules in the Dublin Core elements , see Section 11.34. + The original YANG modules are the authoritative sources of the + authorship information. 11.11. The container Statement Using the rules specified in Section 9.1.1, the mapping algorithm MUST determine whether the statement defines an optional container, and if so, insert the element and make it the new PARENT. The container defined by this statement is then mapped to the element, which becomes a child of PARENT and uses ARGUMENT @@ -2362,43 +2373,56 @@ 'typedef' mapping. o Otherwise, @nma:default becomes an attribute of the ancestor RELAX NG pattern inside which the expansion takes place. Details and an example are given in Section 9.2.2. Finally, as a substatement of 'choice', the 'default' statement identifies the default case and is handled within the 'case' statement, see Section 11.7. If the default case uses the shorthand - notation where the 'case' statement is omitted, an extra - or element MUST be inserted with @nma:implicit - attribute set to "true" and the default case node is mapped inside - this element. The net result is then the same as if the 'case' - statement wasn't omitted for the default case. + notation where the 'case' statement is omitted, the @nma:implicit + attribute with the value "true" is either attached to the node + representing the default case in the shorthand notation or, + alternatively, an extra element MAY be inserted and the + @nma:implicit attribute attached to it. In the latter case, the net + result is the same as if the 'case' statement wasn't omitted for the + default case. EXAMPLE. The following 'choice' statement in a module with namespace prefix "yam" choice leaves { default feuille; leaf feuille { type empty; } leaf hoja { type empty; } } - is mapped to + is either mapped directly to - + + + + + + + + + or the default case may be wrapped in an extra : + + + - + 11.13. The description Statement This statement MAY be ignored. Otherwise, it is mapped to the DTD compatibility element and ARGUMENT becomes its text. @@ -2435,42 +2459,43 @@ MAY be mapped as described in Section 9.4. 11.19. The feature Statement This statement is ignored, see Section 8.5. 11.20. The grouping Statement This statement is mapped to a RELAX NG named pattern definition , but only if the grouping defined by this statement is used - _without refinements and augments_ in at least one of the input + without refinements and augments in at least one of the input modules. In this case, the named pattern definition becomes a child of the element and its name is ARGUMENT mangled according to the rules specified in Section 9.2. Whenever a grouping is used with additional refinements and/or augments, the grouping is expanded so that the refinements and - augments may be applied directly to the prescribed schema nodes. See + augments may be applied in place to the prescribed schema nodes. See Section 9.2.1 for further details and an example. An implementation MAY offer the option of recording all 'grouping' 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. 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, ARGUMENT will appear as the text of - one of the elements in the mapping of that "identityref" - type. See Section 11.53.5 for more details and an example. + type in any of the input modules, or is derived from this base, + ARGUMENT will appear as the text of one of the elements + in the mapping of that "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 that the importing module be able to use its top-level groupings and typedefs and also augment the data @@ -2491,21 +2516,21 @@ corresponding revision of the submodule MUST be used. The mechanism 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 is MUST be + 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 leaf Statement This statement is mapped to the element and ARGUMENT with prepended local namespace prefix becomes the value of its @name attribute. @@ -2558,28 +2581,28 @@ This statement is handled within the "string" type, see Section 11.53.9. 11.30. The list Statement This statement is mapped exactly as the 'leaf-list' statement, see Section 11.28. When mapping the substatements of 'list', the order of children of - the list element MUST be specified so that list keys always appear in - the same order as they are defined in the input YANG module and - before other children, see [YANG], Section 7.8.5. In particular, if - any list key is defined in a grouping but the list itself is not - defined in the same grouping, and the position 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. + the list element MUST be specified so that list keys, if there are + any, always appear in the same order as they are defined in the input + YANG module and before other children, see [YANG], Section 7.8.5. In + particular, if any list key is defined in a grouping but the list + node itself is not a part of the same grouping, and the position 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 the following YANG fragment of a module with prefix "yam": grouping keygrp { leaf clef { type uint8; } } @@ -2634,28 +2657,28 @@ 11.34. The module Statement This statement is not specifically mapped except that a element SHOULD be created as a child of and contain ARGUMENT as a reference to the input YANG module. See also Section 11.49. With respect to the conceptual tree schema, substatements of 'module' MUST be mapped so that - o top level data elements be defined as children of the + o top level data elements be defined as descendants of the element; - o elements mapped from 'rpc' statements be defined as children of + o elements mapped from 'rpc' statements be defined as descendants of the element; o elements mapped from 'notification' statements be defined as - children of the element. + descendants of the element. 11.35. The must Statement This statement is mapped to the element. It has one mandatory attribute @assert (with no namespace), which contains ARGUMENT transformed into a valid XPath expression (see Section 9.3). The 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. @@ -2698,25 +2722,26 @@ . 11.38. The ordered-by Statement This statement is mapped to @nma:ordered-by attribute and ARGUMENT becomes the value of this attribute. See Section 11.28 for an example. 11.39. The organization Statement - This statement is not used by the mapping since the output RELAX NG - schema may result from multiple YANG modules authored by different - parties. The schema contains references to all input modules in the - Dublin Core elements , see Section 11.34. The original - modules are the authoritative sources of the authorship information. + This statement is not used by the mapping since the output conceptual + tree schema may result from multiple YANG modules authored by + different parties. The schema contains references to all input + modules in the Dublin Core elements , see Section 11.34. + The original modules are the authoritative sources of the authorship + 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 @@ -2759,64 +2784,63 @@ 11.49. The revision Statement The mapping uses only the most recent instance of the 'revision' statement, i.e., one with the latest date in ARGUMENT, which specifies the current revision of the input YANG module [YANG]. This date SHOULD be recorded, together with the name of the YANG module, in the corresponding Dublin Core element (see Section 11.34), for example in this form: - YANG module 'foo', revision 2009-01-19 - - The 'description' substatement of 'revision' is not used. + YANG module 'foo', revision 2010-03-02 + The 'description' substatement of 'revision' is ignored. 11.50. The rpc Statement This statement is mapped to the following subtree in the RELAX NG schema ("yam" is the prefix of the local YANG module): - + ... mapped content of 'input' ... - + ... mapped content of 'output' ... - As indicated by the comments, contents of the 'input' substatement - (if any) are mapped under . - Similarly, contents of the 'output' substatement are mapped under - . If there is no 'output' - substatement, the MUST NOT be - present. + As indicated in the schema fragment, contents of the 'input' + substatement (if any) are mapped under . Similarly, contents of the 'output' substatement are + mapped under . If there is no + 'output' substatement, the MUST NOT + be present. The element is a child of . 11.51. The status Statement This statement MAY be ignored. Otherwise, it is mapped to @nma: status attribute and ARGUMENT becomes its value. 11.52. The submodule Statement This statement is not specifically mapped. Its substatements are mapped as if they appeared directly in the module the submodule belongs to. 11.53. The type Statement - Most YANG built-in types have an equivalent in the XSD datatype + Most YANG built-in datatypes have an equivalent in the XSD datatype library [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 | @@ -2831,21 +2855,31 @@ | | | | | 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: Selected datatypes from the W3C XML Schema Type Library + Table 3: YANG built-in datatypes with equivalents in the W3C XML + Schema Type Library + + Two important datatypes of the XSD 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 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 following subsections. 11.53.1. The empty Type This type is mapped to . 11.53.2. The boolean and binary Types @@ -2928,59 +2961,60 @@ is mapped to crypto:crypto-alg des:des des:des3 - The "crypto" and "des" prefixes will by typically defined via + The "crypto" and "des" prefixes will typically be defined via attributes of the element. 11.53.6. The instance-identifier Type This type is mapped to element with @type attribute set to "string". In addition, empty element MUST be inserted as a child of PARENT. - The 'require-instance' substatement, if it exists, is mapped to the - @require-instance attribute of . + The argument of the 'require-instance' substatement, if it exists, + becomes the value of the @require-instance attribute of . 11.53.7. The leafref Type This type is mapped exactly as the type of the leaf given in the argument of 'path' substatement. In addition, @nma:leafref attribute MUST be added to PARENT. The argument of the 'path' substatement, translated according to Section 9.3, is set as the value of this attribute. 11.53.8. The numeric Types YANG built-in numeric types are "int8", "int16", "int32", "int64", "uint8", "uint16", "uint32", "uint64" and "decimal64". They are mapped to element with @type attribute set to ARGUMENT - mapped according to Table 3. + translated according to Table 3 above. An exception is the "decimal64" type, which is mapped to the "decimal" type of the XSD datatype library. Its precision and number of fractional digits are controlled with the following facets, which MUST always be present: o "totalDigits" facet set to the value of 19. o "fractionDigits" facet set to the argument of the 'fraction- digits' substatement. - The fixed value of the "totalDigits" facet corresponds to the maximum - of 19 decimal digits for 64-bit integers. + The fixed value of "totalDigits" corresponds to the maximum of 19 + decimal digits for 64-bit integers. For example, the statement type decimal64 { fraction-digits 2; } is mapped to the following RELAX NG datatype: @@ -3004,25 +3038,25 @@ and ... Their contents are the lower and upper bound, respectively. If the lower bound is "min", the "minInclusive" facet is omitted and if the upper bound is "max", the "maxInclusive" facet is omitted. If the range expression has multiple parts separated by "|", then the parent element must be repeated once for every range part - and all the elements are wrapped in element. + and all such elements are wrapped in element. Each element contains the pattern or the - "minInclusive" and "maxInclusive" facets for the corresponding part - of the range expression as described in the previous paragraph. For - the "decimal64" type, the "totalDigits" and "fractionDigits" must be + "minInclusive" and "maxInclusive" facets for one part of the range + expression as described in the previous paragraph. For the + "decimal64" type, the "totalDigits" and "fractionDigits" must be repeated inside each of the elements. For example, type int32 { range "-6378..0|42|100..max"; } is mapped to the following RELAX NG fragment: @@ -3063,24 +3097,24 @@ ... Their contents are the lower and upper bound of the length range, respectively. If the lower bound is "min", the "minLength" facet is omitted and if the upper bound is "max", the "maxLength" facet is omitted. If the length expression has of multiple parts separated by "|", then the parent element must be repeated once for every range - part and all the elements are wrapped in + part and all such elements are wrapped in element. Each element contains the "length" or - "minLength" and "maxLength" facets for the corresponding part of the - length expression as described in the previous paragraph. + "minLength" and "maxLength" facets for one part of the length + expression as described in the previous paragraph. Every 'pattern' restriction of the "string" datatype is mapped to the "pattern" facet ... with content equal to the argument of the 'pattern' statement. All such "pattern" facets must be repeated inside each copy of the element, i.e., once for each length range. @@ -3107,39 +3141,40 @@ 11.53.10. Derived Types If the 'type' statement refers to a derived type, it is mapped in one of the following ways depending on whether it contains any restrictions as its substatements: 1. Without restrictions, the 'type' statement is mapped simply to the element, i.e., a reference to a named pattern. If the RELAX NG definition of this named pattern has not been added - to the output schema yet, the corresponding 'typedef' must be - found and its mapping installed as a subelement of , - see Section 11.54. Even if a given derived type is used more - than once in the input YANG modules, the mapping of the + to the output schema yet, the corresponding type definition MUST + be found and its mapping installed as a subelement of , see Section 11.54. Even if a given derived type is + used more than once in the input YANG modules, the mapping of the corresponding 'typedef' MUST be installed only once. 2. If any restrictions are present, the ancestor built-in type for the given derived type must be determined and the mapping of this - base type is used. Restrictions appearing at all stages of the - derivation chain must be taken into account and their conjunction - added to the element which defines the basic type. + base type MUST be used. Restrictions appearing at all stages of + the type derivation chain MUST be taken into account and their + conjunction added to the element which defines the + basic type. See Section 9.2.2 for more details and an example. 11.54. The typedef Statement This statement is mapped to a RELAX NG named pattern definition , but only if the type defined by this statement is used - _without restrictions_ in at least one of the input modules. In this + without restrictions in at least one of the input modules. In this case, the named pattern definition becomes a child of the element and its name is ARGUMENT mangled according to the rules specified in Section 9.2. Whenever a derived type is used with additional restrictions, the ancestor built-in type for the derived type is used instead with restrictions (facets) that are a combination of all restrictions specified along the type derivation chain. See Section 11.53.10 for further details and an example. @@ -3150,39 +3185,46 @@ 11.55. The unique Statement This statement is mapped to @nma:unique attribute. ARGUMENT is translated so that every node identifier in each of its components is prefixed with the namespace prefix of the local module, unless the prefix is already present. The result of this translation then becomes the value of the @nma:unique attribute. For example, assuming that the local module prefix is "ex", + unique "foo ex:bar/baz" is mapped to the following 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. + its value. Implementations MAY ignore this statement. 11.57. The uses Statement If this statement has neither 'refine' nor 'augment' substatements, - it is mapped to element and the value of its @name - attribute is set to ARGUMENT mangled according to Section 9.2 + it is mapped to element, i.e., a reference to a named + pattern, and the value of its @name attribute is set to ARGUMENT + mangled according to Section 9.2. If the RELAX NG definition of the + referenced named pattern has not been added to the output schema yet, + the corresponding grouping MUST be found and its mapping installed as + a subelement of , see Section 11.20. - If there are any 'refine' or 'augment' substatements, the - corresponding grouping must be looked up and its contents is inserted - under PARENT. See Section 9.2.1 for further details and an example. + Otherwise, if the 'uses' statement has any 'refine' or 'augment' + substatements, the corresponding grouping must 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 statement is ignored. 11.59. The when Statement This statement is mapped to @nma:when attribute and ARGUMENT, translated according to Section 9.3, becomes it value. @@ -3205,23 +3247,22 @@ described in Section 10. The context is determined by the element definition in the conceptual tree 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. Unless otherwise stated, Schematron asserts are descendants of the "standard" pattern and therefore active in both validation phases. 12.1. The @nma:config Annotation - If this annotation is present with the value "true", the following - rules apply for DSDL schemas of reply. In - particular: + If this annotation is present with the value "false", the following + rules MUST be observed for DSDL schemas of reply: o When generating RELAX NG, the contents of the CONTELEM definition MUST be changed to . o When generating Schematron or DSRL, the CONTELEM definition and all its descendants in the conceptual tree schema MUST be ignored. 12.2. The @nma:default Annotation This annotation is used for generating the DSRL schema as described @@ -3250,33 +3291,33 @@ The element pointed to by "CONTELEM" must exist. The nmf:evaluate() function is an XSLT extension function (see Extension Functions in [XSLT]) that evaluates 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 - Assume this annotation has the value "k_1 k_2 ... k_n", i.e., - specifies n child leaves as keys. The annotation is then mapped to - the following Schematron report: + Assume this annotation 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: Duplicate key of list "CONTELEM" where CONDITION has this form: preceding-sibling::CONTELEM[C_1 and C_2 and ... and C_n] - Each C_i, for i=1,2,...,n, specifies the condition for violation of - uniqueness of key k_i, namely + 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 annotation is mapped to the following assert: Leafref "CONTELEM" must have the same value as "PATH" @@ -3338,48 +3379,48 @@ substituted for k_1, k_2, ..., k_n. o The message appearing as the text of is different: "Violated uniqueness for list CONTELEM". 12.15. The @nma:when Annotation This annotation is mapped to the following Schematron assert: - Node "CONTELEM" is only valid if "EXPRESSION" is true. + Node "CONTELEM" is only valid when "EXPRESSION" is true. 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:conceptual-tree:1 - urn:ietf:params:xml:ns:netmod:xpath-extensions: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 content of NETCONF protocol data units or entire data - stores and thus provide additional validity checks above those + validating the content of NETCONF protocol data units 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. Acknowledgements +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 @@ -3421,42 +3462,46 @@ [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 (Fourth + F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", World Wide Web Consortium Recommendation REC- - xml-20060816, August 2006, + xml-20081126, November 2008, . [XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) Version 1.0", World Wide Web Consortium Recommendation REC-xpath-19991116, November 1999, . [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, . [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-04 (work in progress), - March 2009. + 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. @@ -3469,24 +3514,20 @@ 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, . - [Ytypes] Schoenwaelder, J., Ed., "Common YANG Data Types", - draft-ietf-netmod-yang-types-03 (work in progress), - May 2009. - URIs [1] [2] [3] [4] @@ -3512,21 +3553,21 @@ 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 annotation are attached to and validated together with the parent RELAX NG section. A.1. NVDL Schema - == CODE BEGINS: file "nmannot.nvdl" + file "nmannot.nvdl" ]> - == CODE ENDS + A.2. Annotation Attributes for define Pattern - == CODE BEGINS: file "define.rng" + file "define.rng" - == CODE ENDS + A.3. Annotation Elements for element Pattern - == CODE BEGINS: file "element-el.rng" + file "element-el.rng" - == CODE ENDS + A.4. Annotation Attributes for element Pattern - == CODE BEGINS: file "element-att.rng" + file "element-att.rng" - == CODE ENDS + A.5. Annotation attributes for group Pattern - == CODE BEGINS: file "group-interleave.rng" + file "group-interleave.rng" - == CODE ENDS + A.6. Annotation attributes for choice and ref Patterns - == CODE BEGINS: file "choice-ref.rng" + file "choice-ref.rng" - == CODE ENDS + A.7. Annotation attributes for element Pattern in the List Context - == CODE BEGINS: file "list.rng" + file "list.rng" - == CODE ENDS + A.8. Annotation attributes for value Pattern - == CODE BEGINS: file "value.rng" + file "value.rng" - == CODE ENDS + A.9. Named Patterns for All NETMOD-Specific Annotations - == CODE BEGINS: file "nmannotdefs.rng" + file "nmannotdefs.rng" @@ -3868,33 +3909,33 @@ - == CODE ENDS + Appendix B. Schema-Independent Library - In order to avoid copying the same named pattern definitions to the - RELAX NG schemas generated in the second mapping step, we collected - these definitions to 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 + 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" + file "relaxng-lib.rng" @@ -3910,28 +3951,28 @@ - == 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 input - (single) YANG module is shown in Appendix C.1 and the output schemas - in the following two subsections. + 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. The conceptual tree schema was obtained by the "rng" plugin of the pyang [5] tool and the validating DSDL schemas 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, 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 @@ -4853,21 +4894,40 @@ /nc:rpc-reply/nc:data/dhcp:dhcp/dhcp:shared-networks/ dhcp:shared-network/dhcp:subnet dhcp:max-lease-time 7200 Appendix D. Change Log -D.1. Changes Between Versions -03 and -04 +D.1. 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 is no more required for the default case of a + choice in the shorthand notation. + +D.2. 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 (inside RPCs) or (otherwise). o A nma:default annotation coming from a datatype which the mapping expands is attached to the pattern where the expansion occurs. Added an example. @@ -4885,27 +4945,27 @@ 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 (Acknowledgements). + o Added Section 15 (Acknowledgments). o Removed compact syntax schema from Appendix B. o Editorial changes: symbolic citation labels. -D.2. Changes Between Versions -02 and -03 +D.3. 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 Section 10.2. o Reworked Section 10.4, added skeleton element maps,corrected the example. @@ -4922,21 +4982,21 @@ 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.3. Changes Between Versions -01 and -02 +D.4. 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 Section 10.4. 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 default content. @@ -4946,21 +5006,21 @@ 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.4. Changes Between Versions -00 and -01 +D.5. Changes Between Versions -00 and -01 o Attributes @nma:min-elements and @nma:max-elements are attached to (list entry) and not to or . o Keys and all node identifiers in 'key' and 'unique' statements are prefixed. o Fixed the mapping of 'rpc' and 'notification'.