--- 1/draft-ietf-netmod-dsdl-map-02.txt 2009-07-13 17:12:41.000000000 +0200 +++ 2/draft-ietf-netmod-dsdl-map-03.txt 2009-07-13 17:12:41.000000000 +0200 @@ -1,22 +1,22 @@ NETMOD L. Lhotka Internet-Draft CESNET Intended status: Standards Track R. Mahy -Expires: October 31, 2009 Plantronics +Expires: January 14, 2010 Plantronics S. Chisholm Nortel - April 29, 2009 + July 13, 2009 Mapping YANG to Document Schema Definition Languages and Validating NETCONF Content - draft-ietf-netmod-dsdl-map-02 + draft-ietf-netmod-dsdl-map-03 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,186 +25,194 @@ 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 October 31, 2009. + This Internet-Draft will expire on January 14, 2010. Copyright Notice Copyright (c) 2009 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 describes the mapping rules for translating YANG data - models into XML schemas using Document Schema Definition Languages - (DSDL) and outlines the procedure for validating various types of - NETCONF protocol data units using these schemas. + 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 2. Objectives and Motivation . . . . . . . . . . . . . . . . . . 9 3. DSDL Schema Languages . . . . . . . . . . . . . . . . . . . . 11 3.1. RELAX NG . . . . . . . . . . . . . . . . . . . . . . . . 11 3.2. Schematron . . . . . . . . . . . . . . . . . . . . . . . 12 3.3. Document Semantics Renaming Language (DSRL) . . . . . . 13 4. Additional Annotations . . . . . . . . . . . . . . . . . . . 14 4.1. Dublin Core Metadata Elements . . . . . . . . . . . . . 14 4.2. RELAX NG DTD Compatibility Annotations . . . . . . . . . 14 - 4.3. NETMOD-specific Annotations . . . . . . . . . . . . . . 15 + 4.3. NETMOD-Specific Annotations . . . . . . . . . . . . . . 15 5. Overview of the Mapping . . . . . . . . . . . . . . . . . . . 17 6. NETCONF Content Validation . . . . . . . . . . . . . . . . . 19 7. Design Considerations . . . . . . . . . . . . . . . . . . . . 20 7.1. Conceptual Data Tree . . . . . . . . . . . . . . . . . . 20 7.2. Modularity . . . . . . . . . . . . . . . . . . . . . . . 22 7.3. Granularity . . . . . . . . . . . . . . . . . . . . . . 23 7.4. Handling of XML Namespaces . . . . . . . . . . . . . . . 23 + 7.5. Features and Deviations . . . . . . . . . . . . . . . . 24 8. Mapping YANG Data Models to the Conceptual Tree Schema . . . 25 - 8.1. Optional and Mandatory Content . . . . . . . . . . . . . 25 - 8.2. Mapping YANG Groupings and Typedefs . . . . . . . . . . 26 - 8.2.1. YANG Refinements and Augments . . . . . . . . . . . 28 - 8.2.2. Type derivation chains . . . . . . . . . . . . . . 31 - 8.3. Translation of XPath Expressions . . . . . . . . . . . . 32 - 8.4. YANG Language Extensions . . . . . . . . . . . . . . . . 33 - 9. Mapping Conceptual Tree Schema to DSDL . . . . . . . . . . . 35 - 9.1. Generating RELAX NG Schemas for Various Document Types . 35 - 9.1.1. Reply to or . . . . . . . . . . 36 - 9.1.2. Remote Procedure Calls . . . . . . . . . . . . . . 36 - 9.1.3. Notifications . . . . . . . . . . . . . . . . . . . 37 - 9.2. Mapping Semantic Constraints to Schematron . . . . . . . 38 - 9.2.1. Validation Phases . . . . . . . . . . . . . . . . . 41 - 9.3. Constraints on Mandatory Choice . . . . . . . . . . . . 42 - 9.4. Mapping Default Values to DSRL . . . . . . . . . . . . . 44 - 10. Mapping YANG Statements to Annotated RELAX NG . . . . . . . . 47 - 10.1. The anyxml Statement . . . . . . . . . . . . . . . . . . 47 - 10.2. The argument Statement . . . . . . . . . . . . . . . . . 48 - 10.3. The augment Statement . . . . . . . . . . . . . . . . . 48 - 10.4. The base Statement . . . . . . . . . . . . . . . . . . . 49 - 10.5. The belongs-to Statement . . . . . . . . . . . . . . . . 49 - 10.6. The bit Statement . . . . . . . . . . . . . . . . . . . 49 - 10.7. The case Statement . . . . . . . . . . . . . . . . . . . 49 - 10.8. The choice Statement . . . . . . . . . . . . . . . . . . 49 - 10.9. The config Statement . . . . . . . . . . . . . . . . . . 49 - 10.10. The contact Statement . . . . . . . . . . . . . . . . . 49 - 10.11. The container Statement . . . . . . . . . . . . . . . . 50 - 10.12. The default Statement . . . . . . . . . . . . . . . . . 50 - 10.13. The description Statement . . . . . . . . . . . . . . . 51 - 10.14. The deviation Statement . . . . . . . . . . . . . . . . 51 - 10.15. The enum Statement . . . . . . . . . . . . . . . . . . . 51 - 10.16. The error-app-tag Statement . . . . . . . . . . . . . . 51 - 10.17. The error-message Statement . . . . . . . . . . . . . . 51 - 10.18. The extension Statement . . . . . . . . . . . . . . . . 51 - 10.19. The feature Statement . . . . . . . . . . . . . . . . . 51 - 10.20. The grouping Statement . . . . . . . . . . . . . . . . . 52 - 10.21. The identity Statement . . . . . . . . . . . . . . . . . 52 - 10.22. The if-feature Statement . . . . . . . . . . . . . . . . 52 - 10.23. The import Statement . . . . . . . . . . . . . . . . . . 52 - 10.24. The include Statement . . . . . . . . . . . . . . . . . 53 - 10.25. The input Statement . . . . . . . . . . . . . . . . . . 53 - 10.26. The key Statement . . . . . . . . . . . . . . . . . . . 53 - 10.27. The leaf Statement . . . . . . . . . . . . . . . . . . . 53 - 10.28. The leaf-list Statement . . . . . . . . . . . . . . . . 53 - 10.29. The length Statement . . . . . . . . . . . . . . . . . . 54 - 10.30. The list Statement . . . . . . . . . . . . . . . . . . . 54 - 10.31. The mandatory Statement . . . . . . . . . . . . . . . . 54 - 10.32. The max-elements Statement . . . . . . . . . . . . . . . 54 - 10.33. The min-elements Statement . . . . . . . . . . . . . . . 54 - 10.34. The module Statement . . . . . . . . . . . . . . . . . . 55 - 10.35. The must Statement . . . . . . . . . . . . . . . . . . . 55 - 10.36. The namespace Statement . . . . . . . . . . . . . . . . 55 - 10.37. The notification Statement . . . . . . . . . . . . . . . 56 - 10.38. The ordered-by Statement . . . . . . . . . . . . . . . . 56 - 10.39. The organization Statement . . . . . . . . . . . . . . . 56 - 10.40. The output Statement . . . . . . . . . . . . . . . . . . 56 - 10.41. The path Statement . . . . . . . . . . . . . . . . . . . 56 - 10.42. The pattern Statement . . . . . . . . . . . . . . . . . 56 - 10.43. The position Statement . . . . . . . . . . . . . . . . . 57 - 10.44. The prefix Statement . . . . . . . . . . . . . . . . . . 57 - 10.45. The presence Statement . . . . . . . . . . . . . . . . . 57 - 10.46. The range Statement . . . . . . . . . . . . . . . . . . 57 - 10.47. The reference Statement . . . . . . . . . . . . . . . . 57 - 10.48. The require-instance Statement . . . . . . . . . . . . . 57 - 10.49. The revision Statement . . . . . . . . . . . . . . . . . 57 - 10.50. The rpc Statement . . . . . . . . . . . . . . . . . . . 58 - 10.51. The status Statement . . . . . . . . . . . . . . . . . . 58 - 10.52. The submodule Statement . . . . . . . . . . . . . . . . 58 - 10.53. The type Statement . . . . . . . . . . . . . . . . . . . 58 - 10.53.1. The empty Type . . . . . . . . . . . . . . . . . . 59 - 10.53.2. The boolean and binary Types . . . . . . . . . . . 59 - 10.53.3. The bits Type . . . . . . . . . . . . . . . . . . . 60 - 10.53.4. The enumeration and union Types . . . . . . . . . . 60 - 10.53.5. The identityref Type . . . . . . . . . . . . . . . 60 - 10.53.6. The instance-identifier Type . . . . . . . . . . . 62 - 10.53.7. The leafref Type . . . . . . . . . . . . . . . . . 62 - 10.53.8. The numeric Types . . . . . . . . . . . . . . . . . 62 - 10.53.9. The string Type . . . . . . . . . . . . . . . . . . 63 - 10.53.10. Derived Types . . . . . . . . . . . . . . . . . . . 64 - 10.54. The typedef Statement . . . . . . . . . . . . . . . . . 64 - 10.55. The unique Statement . . . . . . . . . . . . . . . . . . 65 - 10.56. The units Statement . . . . . . . . . . . . . . . . . . 65 - 10.57. The uses Statement . . . . . . . . . . . . . . . . . . . 65 - 10.58. The value Statement . . . . . . . . . . . . . . . . . . 65 - 10.59. The when Statement . . . . . . . . . . . . . . . . . . . 65 - 10.60. The yang-version Statement . . . . . . . . . . . . . . . 65 - 10.61. The yin-element Statement . . . . . . . . . . . . . . . 66 + 8.1. Occurrence Rules for Data Nodes . . . . . . . . . . . . 25 + 8.1.1. Optional and Mandatory Nodes . . . . . . . . . . . 26 + 8.1.2. Implicit Nodes . . . . . . . . . . . . . . . . . . 27 + 8.2. Mapping YANG Groupings and Typedefs . . . . . . . . . . 28 + 8.2.1. YANG Refinements and Augments . . . . . . . . . . . 30 + 8.2.2. Type derivation chains . . . . . . . . . . . . . . 33 + 8.3. Translation of XPath Expressions . . . . . . . . . . . . 34 + 8.4. YANG Language Extensions . . . . . . . . . . . . . . . . 35 + 9. Mapping Conceptual Tree Schema to DSDL . . . . . . . . . . . 37 + 9.1. Generating RELAX NG Schemas for Various Document Types . 37 + 9.1.1. Reply to or . . . . . . . . . . 38 + 9.1.2. Remote Procedure Calls . . . . . . . . . . . . . . 38 + 9.1.3. Notifications . . . . . . . . . . . . . . . . . . . 39 + 9.2. Mapping Semantic Constraints to Schematron . . . . . . . 40 + 9.2.1. Validation Phases . . . . . . . . . . . . . . . . . 43 + 9.3. Constraints on Mandatory Choice . . . . . . . . . . . . 44 + 9.4. Mapping Default Values to DSRL . . . . . . . . . . . . . 46 + 10. Mapping YANG Statements to Conceptual Tree Schema . . . . . . 50 + 10.1. The anyxml Statement . . . . . . . . . . . . . . . . . . 50 + 10.2. The argument Statement . . . . . . . . . . . . . . . . . 51 + 10.3. The augment Statement . . . . . . . . . . . . . . . . . 52 + 10.4. The base Statement . . . . . . . . . . . . . . . . . . . 52 + 10.5. The belongs-to Statement . . . . . . . . . . . . . . . . 52 + 10.6. The bit Statement . . . . . . . . . . . . . . . . . . . 52 + 10.7. The case Statement . . . . . . . . . . . . . . . . . . . 52 + 10.8. The choice Statement . . . . . . . . . . . . . . . . . . 52 + 10.9. The config Statement . . . . . . . . . . . . . . . . . . 53 + 10.10. The contact Statement . . . . . . . . . . . . . . . . . 53 + 10.11. The container Statement . . . . . . . . . . . . . . . . 53 + 10.12. The default Statement . . . . . . . . . . . . . . . . . 53 + 10.13. The description Statement . . . . . . . . . . . . . . . 54 + 10.14. The deviation Statement . . . . . . . . . . . . . . . . 54 + 10.15. The enum Statement . . . . . . . . . . . . . . . . . . . 54 + 10.16. The error-app-tag Statement . . . . . . . . . . . . . . 55 + 10.17. The error-message Statement . . . . . . . . . . . . . . 55 + 10.18. The extension Statement . . . . . . . . . . . . . . . . 55 + 10.19. The feature Statement . . . . . . . . . . . . . . . . . 55 + 10.20. The grouping Statement . . . . . . . . . . . . . . . . . 55 + 10.21. The identity Statement . . . . . . . . . . . . . . . . . 55 + 10.22. The if-feature Statement . . . . . . . . . . . . . . . . 56 + 10.23. The import Statement . . . . . . . . . . . . . . . . . . 56 + 10.24. The include Statement . . . . . . . . . . . . . . . . . 56 + 10.25. The input Statement . . . . . . . . . . . . . . . . . . 56 + 10.26. The key Statement . . . . . . . . . . . . . . . . . . . 56 + 10.27. The leaf Statement . . . . . . . . . . . . . . . . . . . 56 + 10.28. The leaf-list Statement . . . . . . . . . . . . . . . . 57 + 10.29. The length Statement . . . . . . . . . . . . . . . . . . 57 + 10.30. The list Statement . . . . . . . . . . . . . . . . . . . 58 + 10.31. The mandatory Statement . . . . . . . . . . . . . . . . 58 + 10.32. The max-elements Statement . . . . . . . . . . . . . . . 58 + 10.33. The min-elements Statement . . . . . . . . . . . . . . . 58 + 10.34. The module Statement . . . . . . . . . . . . . . . . . . 58 + 10.35. The must Statement . . . . . . . . . . . . . . . . . . . 58 + 10.36. The namespace Statement . . . . . . . . . . . . . . . . 59 + 10.37. The notification Statement . . . . . . . . . . . . . . . 59 + 10.38. The ordered-by Statement . . . . . . . . . . . . . . . . 59 + 10.39. The organization Statement . . . . . . . . . . . . . . . 60 + 10.40. The output Statement . . . . . . . . . . . . . . . . . . 60 + 10.41. The path Statement . . . . . . . . . . . . . . . . . . . 60 + 10.42. The pattern Statement . . . . . . . . . . . . . . . . . 60 + 10.43. The position Statement . . . . . . . . . . . . . . . . . 60 + 10.44. The prefix Statement . . . . . . . . . . . . . . . . . . 60 + 10.45. The presence Statement . . . . . . . . . . . . . . . . . 60 + 10.46. The range Statement . . . . . . . . . . . . . . . . . . 60 + 10.47. The reference Statement . . . . . . . . . . . . . . . . 60 + 10.48. The require-instance Statement . . . . . . . . . . . . . 61 + 10.49. The revision Statement . . . . . . . . . . . . . . . . . 61 + 10.50. The rpc Statement . . . . . . . . . . . . . . . . . . . 61 + 10.51. The status Statement . . . . . . . . . . . . . . . . . . 62 + 10.52. The submodule Statement . . . . . . . . . . . . . . . . 62 + 10.53. The type Statement . . . . . . . . . . . . . . . . . . . 62 + 10.53.1. The empty Type . . . . . . . . . . . . . . . . . . 63 + 10.53.2. The boolean and binary Types . . . . . . . . . . . 63 + 10.53.3. The bits Type . . . . . . . . . . . . . . . . . . . 63 + 10.53.4. The enumeration and union Types . . . . . . . . . . 63 + 10.53.5. The identityref Type . . . . . . . . . . . . . . . 63 + 10.53.6. The instance-identifier Type . . . . . . . . . . . 65 + 10.53.7. The leafref Type . . . . . . . . . . . . . . . . . 65 + 10.53.8. The numeric Types . . . . . . . . . . . . . . . . . 65 + 10.53.9. The string Type . . . . . . . . . . . . . . . . . . 67 + 10.53.10. Derived Types . . . . . . . . . . . . . . . . . . . 67 + 10.54. The typedef Statement . . . . . . . . . . . . . . . . . 68 + 10.55. The unique Statement . . . . . . . . . . . . . . . . . . 68 + 10.56. The units Statement . . . . . . . . . . . . . . . . . . 68 + 10.57. The uses Statement . . . . . . . . . . . . . . . . . . . 69 + 10.58. The value Statement . . . . . . . . . . . . . . . . . . 69 + 10.59. The when Statement . . . . . . . . . . . . . . . . . . . 69 + 10.60. The yang-version Statement . . . . . . . . . . . . . . . 69 + 10.61. The yin-element Statement . . . . . . . . . . . . . . . 69 11. Mapping NETMOD-specific annotations to DSDL Schema - Languages . . . . . . . . . . . . . . . . . . . . . . . . . . 67 - 11.1. The @nma:config Annotation . . . . . . . . . . . . . . . 67 - 11.2. The @nma:default Annotation . . . . . . . . . . . . . . 67 - 11.3. The @nma:default-case Annotation . . . . . . . . . . . . 67 - 11.4. The Annotation . . . . . . . . . . . 67 - 11.5. The Annotation . . . . . . . . . . . 67 - 11.6. The Annotation . . . . . . . . 67 - 11.7. The @nma:key Annotation . . . . . . . . . . . . . . . . 68 - 11.8. The Annotation . . . . . . . . . . . . . . 68 - 11.9. The @nma:min-elements Annotation . . . . . . . . . . . . 69 - 11.10. The @nma:max-elements Annotation . . . . . . . . . . . . 69 - 11.11. The Annotation . . . . . . . . . . . . . . . 69 - 11.12. The Annotation . . . . . . . . . . . . 69 - 11.13. The Annotation . . . . . . . . . . . . . . 69 - 11.14. The @nma:unique Annotation . . . . . . . . . . . . . . . 70 - 11.15. The @nma:when Annotation . . . . . . . . . . . . . . . . 70 - 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 71 - 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 72 - Appendix A. RELAX NG Schema for NETMOD-specific Annotations . . 74 - A.1. XML Syntax . . . . . . . . . . . . . . . . . . . . . . . 74 - A.2. Compact Syntax . . . . . . . . . . . . . . . . . . . . . 77 - Appendix B. Schema-Independent Library . . . . . . . . . . . . . 78 - B.1. XML Syntax . . . . . . . . . . . . . . . . . . . . . . . 78 - B.2. Compact Syntax . . . . . . . . . . . . . . . . . . . . . 79 - Appendix C. Mapping DHCP Data Model - A Complete Example . . . . 80 - C.1. Input YANG Module . . . . . . . . . . . . . . . . . . . 80 - C.2. Conceptual Tree Schema . . . . . . . . . . . . . . . . . 83 - C.2.1. XML Syntax . . . . . . . . . . . . . . . . . . . . 83 - C.2.2. Compact Syntax . . . . . . . . . . . . . . . . . . 87 - C.3. Final DSDL Schemas . . . . . . . . . . . . . . . . . . . 90 - C.3.1. RELAX NG Schema for Reply - XML Syntax . . . 90 - C.3.2. RELAX NG Schema for Reply - Compact Syntax . 94 - C.4. Schematron Schema for Reply . . . . . . . . . . . 97 - C.5. DSRL Schema for Reply . . . . . . . . . . . . . . 98 - Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 99 - D.1. Changes Between Versions -01 and -02 . . . . . . . . . . 99 - D.2. Changes Between Versions -00 and -01 . . . . . . . . . . 99 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 101 + Languages . . . . . . . . . . . . . . . . . . . . . . . . . . 70 + 11.1. The @nma:config Annotation . . . . . . . . . . . . . . . 70 + 11.2. The @nma:default Annotation . . . . . . . . . . . . . . 70 + 11.3. The @nma:implicit Annotation . . . . . . . . . . . . . . 70 + 11.4. The Annotation . . . . . . . . . . . 70 + 11.5. The Annotation . . . . . . . . . . . 70 + 11.6. The Annotation . . . . . . . . 70 + 11.7. The @nma:key Annotation . . . . . . . . . . . . . . . . 71 + 11.8. The @nma:leafref Annotation . . . . . . . . . . . . . . 71 + 11.9. The @nma:min-elements Annotation . . . . . . . . . . . . 71 + 11.10. The @nma:max-elements Annotation . . . . . . . . . . . . 72 + 11.11. The Annotation . . . . . . . . . . . . . . . 72 + 11.12. The Annotation . . . . . . . . . . . . 72 + 11.13. The Annotation . . . . . . . . . . . . . . 72 + 11.14. The @nma:unique Annotation . . . . . . . . . . . . . . . 72 + 11.15. The @nma:when Annotation . . . . . . . . . . . . . . . . 73 + 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 74 + 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 75 + Appendix A. RELAX NG Schema for NETMOD-specific Annotations . . 77 + A.1. XML Syntax . . . . . . . . . . . . . . . . . . . . . . . 77 + A.2. Compact Syntax . . . . . . . . . . . . . . . . . . . . . 80 + Appendix B. Schema-Independent Library . . . . . . . . . . . . . 81 + B.1. XML Syntax . . . . . . . . . . . . . . . . . . . . . . . 81 + B.2. Compact Syntax . . . . . . . . . . . . . . . . . . . . . 82 + Appendix C. Mapping DHCP Data Model - A Complete Example . . . . 83 + C.1. Input YANG Module . . . . . . . . . . . . . . . . . . . 83 + C.2. Conceptual Tree Schema . . . . . . . . . . . . . . . . . 86 + C.2.1. XML Syntax . . . . . . . . . . . . . . . . . . . . 86 + C.2.2. Compact Syntax . . . . . . . . . . . . . . . . . . 91 + C.3. Final DSDL Schemas . . . . . . . . . . . . . . . . . . . 93 + C.3.1. RELAX NG Schema for Reply - XML Syntax . . . 94 + C.3.2. RELAX NG Schema for Reply - Compact Syntax . 98 + C.4. Schematron Schema for Reply . . . . . . . . . . . 100 + C.5. DSRL Schema for Reply . . . . . . . . . . . . . . 102 + Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 103 + D.1. Changes Between Versions -02 and -03 . . . . . . . . . . 103 + D.2. Changes Between Versions -01 and -02 . . . . . . . . . . 103 + D.3. Changes Between Versions -00 and -01 . . . . . . . . . . 104 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 105 1. Introduction The NETCONF Working Group has completed a base protocol used for configuration management [1]. 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 @@ -228,46 +236,46 @@ being standardized as ISO/IEC 19757 [6]. 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 it is true that some DSDL parts have not been standardized yet and are still work in progress, the three parts that the YANG-to-DSDL mapping relies upon - RELAX NG, Schematron and DSRL - already have the status of an ISO/IEC International Standard and are supported in a number of software tools. - This document contains the specification of a mapping that translates + This document contains specification of a mapping that translates YANG data models to XML schemas utilizing a subset of the DSDL schema languages. The mapping procedure is divided into two steps: In the first step, the structure of the data tree, RPC signatures and notifications is expressed as a single RELAX NG grammar with simple annotations representing additional data model information (metadata, documentation, semantic constraints, default values etc.). The second step then generates a coordinated set of DSDL schemas that can validate specific XML documents such as client requests, server responses or notifications, perhaps also taking into account additional context such as active capabilities. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [7]. In the text, we also use the following typographic conventions: o YANG statement keywords are delimited by single quotes. - o Literal values are delimited by double quotes. - o XML element names are delimited by "<" and ">" characters. o Names of XML attributes are prefixed by the "@" character. + o Other literal values are delimited by double quotes. + XML elements names are always written with explicit namespace prefixes corresponding to the following XML vocabularies: "a" DTD compatibility annotations [8] "dc" Dublin Core metadata elements [9] "nc" NETCONF protocol [1] "en" NETCONF event notifications [10] @@ -333,274 +341,279 @@ 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 efficient 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 extended periods of time in parallel to YANG + 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 schema of the so-called "conceptual tree", which contains grammatical constraints for the main data tree as well as RPCs and notifications. In order to record additional constraints that appear in the YANG modules but cannot be expressed in RELAX - NG, the schema is augmented by simple annotations. The resulting - schema should thus be considered a reasonably readable equivalent - of the input YANG modules. + NG, the schema is augmented by simple annotations. The output of + the first step can thus be considered a reasonably readable + equivalent of the input YANG modules. 2. In the second step, the annotated RELAX NG schema from step 1 is - transformed further to a coordinated set of DSDL schemas - containing constraints for a particular data object and a + 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. 3. 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, + notably W3C XML Schema (XSD) [14], the DSDL framework adheres to the + principle of "small languages": Each of the DSDL constituents is a + stand-alone schema languages 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. 3.1. RELAX NG RELAX NG (pronounced "relaxing") is an XML schema language for grammar-based validation and Part 2 of the ISO/IEC DSDL family of standards [12]. Like the W3C XML Schema language [14], it is able to - describe constraints on the structure and contents of XML documents. + describe constraints on the structure and content of XML documents. However, unlike the DTD [15] and XSD schema languages, RELAX NG intentionally avoids any infoset augmentation such as defining default values. In the DSDL architecture, the particular task of defining and applying default values is delegated to another schema language, DSRL (see Section 3.3). As its base datatype library, RELAX NG uses the W3C XML Schema Datatype Library [16], but unlike XSD, other datatype libraries may be used along with it or even replace it if necessary. RELAX NG is very liberal in accepting annotations from other namespaces. With few exceptions, such annotations may be placed - anywhere in the schema and need no encapsulating element such as + anywhere in the schema and need no encapsulating elements such as in XSD. - RELAX NG schema can be represented using two equivalent syntaxes: XML + RELAX NG schemas can be represented n two equivalent syntaxes: XML and compact. The compact syntax is described in Annex C of the RELAX NG specification [17], which was added to the standard in 2006 (Amendment 1). Automatic bidirectional conversions between the two - syntaxes can be accomplished using for example Trang [23]. + syntaxes can be accomplished using several tools, for example + Trang [23]. 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 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 - on readability that results from adding annotations is often much - stronger for the compact syntax than for the XML syntax. + of annotations on readability is often much stronger for the + compact syntax than for the XML syntax. o In a 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. - For these reasons, the mapping specification in this document use + 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". 3.2. Schematron Schematron is Part 3 of DSDL that reached the status of a full ISO/ IEC standard in 2006 [13]. In contrast to the traditional schema languages such as DTD, XSD or RELAX NG, which are based on the concept of a formal grammar, Schematron utilizes a rule-based approach. Its rules may specify arbitrary conditions involving data from different parts of an XML document. Each rule consists of three - essential parts: + essential components: - o Context - an XPath expression that defines the set of locations - where the rule is to be applied, + o context - an XPath expression that defines the set of locations + where the rule is to be applied; - o Assert or report condition - another XPath expression that is + o assert or report condition - another XPath expression that is evaluated relative to the location matched by the context - expression. + expression; - o Human-readable message that is displayed when the assert condition + o human-readable message that is displayed when the assert condition is false or report condition is true. The difference between the assert and report condition is that the former is positive in that it states a condition that a valid document has to satisfy, whereas the latter specifies an error condition. Schematron draws most of its expressive power from XPath [18] and XSLT [19]. 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). The human-readable error messages are another feature that - distinguishes Schematron from other schema languages such as RELAX NG - or XSD. 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. - - ISO Schematron introduced the concept of _abstract patterns_ whose - purpose is similar to functions in programming languages. The - mapping described in this document uses a library of abstract - patterns for specifying generic constraints such as uniqueness of - certain leaf values in list items. + 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. The rules defined by a Schematron schema may be divided into several 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". 3.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 [11]. Unlike RELAX NG and Schematron, it is specifically designed to modify XML information set - of the validated document. The primary application for DSRL is - renaming XML elements and attributes. DSRL can also define default - values for XML attributes and elements so that elements or attributes - with these default values are inserted if they are missing in the - validated documents. The latter feature is used by the YANG-to-DSDL - mapping for representing YANG defaults for leaf nodes. + 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. DSRL elements are qualified with namespace URI "http://purl.oclc.org/dsdl/dsrl". 4. Additional Annotations - In addition to the DSDL schema languages, the mapping uses three sets - of annotations that are added as foreign-namespace elements and - attributes to RELAX NG schemas. Two of the annotation sets - Dublin + 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. While these data model items may not be used for - formal validation, they quite often carry important information. - Therefore, they SHOULD be included in the conceptual tree schema and - MAY also appear in the final validation schemas. + 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 semantic + The third set are NETMOD-specific annotations conveying YANG semantic constraints and other information that cannot be expressed natively 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. 4.1. Dublin Core Metadata Elements Dublin Core [24] is a system of metadata elements that was originally created for describing metadata of World Wide Web resources in order to facilitate their automated lookup. Later it was accepted as a standard for describing metadata of arbitrary resources. This - specification uses the definition found in [9]. + specification uses the definition from [9]. Dublin Core elements are qualified with namespace URI "http://purl.org/dc/terms". 4.2. RELAX NG DTD Compatibility Annotations DTD compatibility annotations are part of the RELAX NG DTD - Compatibility specification [8]. The YANG-to-DSDL mapping uses only - the annotation for representing YANG 'description' - and 'reference' texts. + Compatibility specification [8]. YANG-to-DSDL mapping uses only the + annotation for representing YANG 'description' and + 'reference' texts. Note that there is no intention to make the resulting schemas DTD- compatible, the main reason for using these annotations is technical: they are well supported and adequately interpreted by several RELAX NG tools. DTD compatibility annotations are qualified with namespace URI "http://relaxng.org/ns/compatibility/annotations/1.0". -4.3. NETMOD-specific Annotations +4.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 - mapped to these annotations in a very straightforward way. With one - exception - @nma:default-case - the annotation attributes and - elements always have the same name as the corresponding YANG - statement. + mapped to these annotations in a very straightforward way. In most + cases, the annotation attributes and elements always have the same + name as the corresponding YANG statement. Table 2 lists alphabetically the names of NETMOD-specific annotation - elements (in angle brackets) and attributes (prefixed with "@") along + attributes (prefixed with "@") and elements (in angle brackets) along with a reference to the section where their use is described. Appendix A then contains the RELAX NG schema of this annotation vocabulary. - +---------------------------+---------+------+ + +---------------------------+--------------------+------+ | annotation | section | note | - +---------------------------+---------+------+ + +---------------------------+--------------------+------+ | @nma:config | 10.9 | | | | | | | @nma:default | 10.12 | | | | | | - | @nma:default-case | 10.7 | | + | @nma:implicit | 10.11, 10.7, 10.12 | | | | | | | | 10.16 | 1 | | | | | | | 10.17 | 1 | | | | | | | 10.53.6 | 2 | | | | | | @nma:key | 10.26 | | | | | | - | | 10.53.7 | 2 | + | @nma:leafref | 10.53.7 | | | | | | | @nma:min-elements | 10.28 | | | | | | | @nma:max-elements | 10.28 | | | | | | | | 10.35 | 3 | | | | | | @nma:ordered-by | 10.38 | | | | | | | @nma:presence | 10.45 | | | | | | | @nma:status | 10.51 | | | | | | | @nma:unique | 10.55 | | | | | | | @nma:units | 10.56 | | | | | | | @nma:when | 10.59 | | - +---------------------------+---------+------+ + +---------------------------+--------------------+------+ Table 2: NETMOD-specific annotations Notes: 1. Appears only as subelement of . 2. Has an optional attribute @require-instance. 3. Has a mandatory attribute @assert and two optional subelements @@ -639,79 +652,79 @@ RELAX NG (list key definitions, 'must' statements etc.) and various documentation texts are recorded in the schema as simple annotations belonging to special namespaces. 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 simplest 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, elements etc. + 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 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). The output of the first mapping step is an annotated RELAX NG schema - for the conceptual tree, which represents a virtual XML document - containing, in its different subtrees, the entire datastore, all RPC - requests and replies, and notifications 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, 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 - will typically produce validation schemas. The conceptual tree is - further described in Section 7.1. + for the conceptual tree - a virtual XML document containing, in its + different subtrees, the entire datastore, all RPC requests and + replies, and notifications 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, + 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 7.1. Other information contained in input YANG modules, such as semantic - constraints or default values, are recorded as annotations - XML - elements or attributes 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 4.1). Finally, documentation strings - are mapped to the elements belonging to the DTD - compatibility vocabulary (Section 4.2). + 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 4.1). Finally, documentation + strings are mapped to the elements belonging to the + DTD compatibility vocabulary (Section 4.2). - The output from the second step is is a coordinated set of three DSDL + 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 values. + o DSRL schema containing a specification of default content. 6. 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 corresponding to various NETCONF PDUs. + 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, the default values for leaves have to be applied and their ancestor containers added where necessary. It is important to apply the defaults before the next validation step because @@ -733,83 +746,76 @@ | grammar, | defaults | semantic | datatypes | | constraints | | | +----------+ +--------+ +------------+ | RELAX NG | | DSRL | | Schematron | | schema | | schema | | schema | +----------+ +--------+ +------------+ Figure 2: Outline of the validation procedure - The process of substituting default values is complicated by the - rules for non-presence containers and choices in YANG, which may lead - to insertion of entire subtrees in the NETCONF instance document. - Section 9.4 describes how this procedure is represented in DSRL and - how the DSRL schema is obtained from the conceptual tree schema. - 7. Design Considerations YANG modules could be mapped to DSDL schemas in a number of ways. The mapping procedure described in this document uses several specific design decisions that are discussed in the following subsections. 7.1. Conceptual Data Tree DSDL schemas generated from YANG modules using the procedure described in this document are intended to be used for validating - XML-encoded NETCONF data in various forms (full datastore and several - types of PDUs): every YANG-based model represents the contents of a - full 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. + XML-encoded NETCONF data in various forms: every YANG-based model + 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. - The conceptual data tree for a YANG module defining nodes in the - namespace "http://example.com/ns/example" may be schematically - represented as follows: + 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 ... ... ... ... - + ... ... @@ -828,46 +834,46 @@ 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. 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 configuration repository 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. + 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. 7.2. Modularity Both YANG and RELAX NG offer means for modularity, i.e., for - splitting the contents into separate modules (schemas) and combining - or reusing them in various ways. However, the approaches taken by - YANG and RELAX NG differ. Modularity in RELAX NG is suitable for ad - hoc combinations of a small number of schemas whereas YANG assumes a - large set of modules similar to SNMP MIBs. The following differences - are important: + splitting the contents of a full schema into separate modules and + combining or reusing them in various ways. However, the approaches + taken by YANG and RELAX NG differ. Modularity in RELAX NG is + suitable for ad hoc combinations of a small number of schemas whereas + YANG assumes a large set of modules similar to SNMP MIBs. The + following differences are important: o In YANG, whenever module A imports module B, it gets access to the definitions (groupings and typedefs) appearing at the top level of - module B. However, no part of module B's data tree is imported + module B. However, no part of data tree from module B is imported along with it. In contrast, the pattern in RELAX NG imports both definitions of named patterns and the entire schema tree from the included schema. o The names of imported YANG groupings and typedefs are qualified with the namespace of the imported module. On the other hand, the - data nodes contained inside the imported groupings, when used - within the importing module, become part of the importing + names of data nodes contained inside the imported groupings, when + used within the importing module, become part of the importing namespace. In RELAX NG, the names of patterns are unqualified and so named patterns defined in both the importing and imported module share the same flat namespace. The contents of RELAX NG named patterns may either keep the namespace of the schema where they are defined or inherit the namespace of the importing module, analogically to YANG. However, in order to achieve the latter behavior, the imported module must be prepared in a special way as a library module that cannot be used as a stand-alone schema. So the conclusion is that the modularity mechanisms of YANG and RELAX @@ -913,97 +919,204 @@ of RELAX NG. For this reason, the mapping essentially keeps the granularity of the original YANG data model: definitions of named patterns in the resulting RELAX NG schema usually have direct counterparts in YANG groupings and definitions of derived types. 7.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 the YANG-to-DSDL mapping algorithm allows for multiple - input YANG modules that naturally leads to compound document schemas. + purpose since the 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 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. The design decision for the mapping is to use exclusively the - alternative 1, since 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 all input modules are recorded in the resulting schema - - the prefix for the namespace declared using @ns would be lost. + 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. - Analogically, DSRL schemas may declare the default target namespace - using the @targetNamespace attribute and any number of additional - target namespaces via the standard XML attributes xmlns:xxx. + 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. +7.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. It is + assumed that all features and deviations are specified beforehand and + the corresponding changes in the input YANG modules are already + applied. + 8. Mapping YANG Data Models to the Conceptual Tree Schema This section explains the main principles underlying the first step of the mapping. Its result is an annotated RELAX NG schema of the conceptual tree, which is described in Section 7.1. As a special case, if the input YANG modules contain no data nodes - (this is typical e.g., for datatype library modules), an + (this is typical, e.g., for datatype library modules), an implementation MAY entirely remove the schema of the (empty) 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 10. -8.1. Optional and Mandatory Content +8.1. Occurrence Rules for Data Nodes - In YANG, the decision whether a given data node is mandatory or - optional is driven by the following rules, see Section 3.1 in [5]: + In DSDL schema languages, occurrence constraints for a node are + always localized together with that node. In RELAX NG, for example, + pattern always appears as the parent element of the + pattern defining the node in the schema. Similarly, DSRL specifies + default content separately for every single node, be it a leaf or + non-leaf element. - Leaf and choice nodes are mandatory if they contain the substatement + In contrast, for a YANG container it is often necessary to examine + the entire subtree under that container 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 all transformation procedures in the second mapping step can + simply use this information and need not examine the subtree again. + + The following two occurrence characteristics have to be determined + for every container: + + 1. optional/mandatory - mandatory containers must exist in a valid + instance document while optional ones may be omitted; + + 2. implicit - an implicit container is added to the instance + document in the process of substituting defaults for missing leaf + values. + + Both characteristics apply to containers at the top level of the data + tree, and then also to other containers under the additional + condition that their parent node exists in the instance document. + For example, consider the following YANG fragment: + + container outer { + presence 'Presence of "outer" means something.'; + container c1 { + leaf foo { + type uint8; + default 1; + } + } + container c2 { + leaf-list bar { + type uint8; + min-elements 0; + } + } + container c3 { + leaf baz { + type uint8; mandatory true; + } + } + } - For a choice node this means that at least one node from exactly one - case branch must exist. + Here, container "outer" has the 'presence' substatement, which means + that it is optional and not implicit. If "outer" is not present in a + configuration, its child containers are not present as well. + However, if "outer" does exist, it makes sense to ask which of its + child containers are optional and which are implicit. In this case, + "c1" is optional and implicit, "c2" is optional but not implicit and + "c3" is mandatory (and therefore not implicit). - In addition, leaf nodes are mandatory if they are declared as list + The following subsections give precise rules for determining whether + a container is optional or mandatory and whether it is implicit. In + order to simplify their description, it is useful to define these + occurrence characteristics for other types of nodes - leaf, list, + leaf-list and anyxml. + +8.1.1. Optional and Mandatory Nodes + + The decision whether a given node is mandatory or optional is + governed by the following rules, see Section 3.1 in [5]: + + 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. - Lists or leaf-lists are mandatory if they contain 'min-elements' - substatement with argument value greater than zero. + o List or leaf-list nodes are mandatory if they contain 'min- + elements' substatement with argument value greater than zero. - A slightly more complicated situation arises for YANG containers. - First, containers with the 'presence' substatement are always - optional since their presence or absence carries specific - information. On the other hand, non-presence containers may be - omitted if they are empty. This leads to the following recursive - rule: + 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 container node is optional if its definition contains the - 'presence' substatement or none of its child nodes is mandatory. + A node is optional if it is not mandatory. - In RELAX NG, all elements that are optional must be explicitly - wrapped in the element. The mapping algorithm thus - uses the above rules to determine whether a YANG node is optional and - if so, insert the element in the RELAX NG schema. + In RELAX NG, definitions of nodes that are optional must be + explicitly wrapped in the element. The mapping + algorithm thus uses the above rules to determine whether a YANG node + is optional and if so, inserts 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. + +8.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 [5]. + + 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 (if defined by the 'default' substatement of + 'choice') MUST be also marked in the same way, i.e., by @nma:implicit + set to "true". 8.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 [5]. Moreover, top-level symbols from external modules are @@ -1011,32 +1124,32 @@ 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: - o Names of groupings and typedefs appearing at the _top level_ of - the YANG module hierarchy are prefixed with the module name and - two underscore characters ("__"). + o Names of groupings and typedefs appearing at the top level of the + YANG module hierarchy are prefixed with the module name and two + underscore characters ("__"). o Names of other groupings and typedefs, i.e., those that do not appear at the top level of a YANG module, are prefixed with the module name, double underscore, and then the names of all ancestor data nodes separated by double underscore. o Since the names of groupings and typedefs in YANG have different namespaces, an additional underline character is added to the - front of the mangled names of all groupings. + beginning of the mangled names of all groupings. For example, consider the following YANG module which imports the standard module "inet-types" [20]: module example1 { namespace "http://example.com/ns/example1"; prefix ex1; import "inet-types" { prefix "inet"; } @@ -1069,29 +1182,29 @@ IPv6 addresses are not shown): [aeiouy]* - + - + @@ -1119,27 +1232,27 @@ 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 a subset of XPath 1.0 expressions as - arguments, schema nodes that are arbitrarily deep inside the grouping - content. In contrast, definitions of named patterns in RELAX NG - operate 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 7.3) and very difficult to read. + they can address, using XPath-like expressions as arguments, schema + nodes that are arbitrarily deep inside the grouping content. In + contrast, definitions of named patterns in RELAX NG operate + 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 7.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 virtually replaced by the content of the corresponding grouping, the changes specified in the 'refine' and 'augment' statements are applied and the resulting YANG schema fragment is mapped as if the 'uses'/'grouping' indirection wasn't there. @@ -1174,29 +1287,29 @@ The resulting conceptual tree schema contains three named pattern definitions corresponding to the three groupings, namely - + - + 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: @@ -1209,21 +1322,21 @@ The resulting conceptual tree schema now contains just one named pattern definition - "_example__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: - + 8.2.2. Type derivation chains RELAX NG has no equivalent of the type derivation mechanism in YANG, where a base built-in type may be modified (in multiple steps) by adding new restrictions. Therefore, when mapping YANG derived types with restrictions, the derived types MUST be "unwound" all the way @@ -1270,72 +1383,63 @@ leaf month { type dozen { range 7..max; } } The output RELAX NG schema then won't contain any named pattern definition and leaf "month" will be mapped directly to - + 7 12 8.3. Translation of XPath Expressions - YANG uses full XPath 1.0 syntax [18] for the arguments of 'must' and - 'when' statements and a subset thereof in several other statements. - However, since the name of a data node always belongs to the - namespace of the YANG Module where the data node is defined, 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. + YANG uses full XPath 1.0 syntax [18] 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. If an XPath expression is carried over to a NETMOD-specific - annotation in the first mapping step, it MUST be translated into a - fully conformant XPath 1.0 expression that also reflects the + 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 [5], sections 7.5.3 and 7.19.5. + expressions, see [5], sections 7.5.3 and 7.19.5 in [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". - [Editor's note: We may want to introduce "$root" variable that always - contains the appropriate partial path in conceptual tree. The - translated XPath in the example would then become "$root/dhcp:dhcp/ - dhcp:max-lease-time".] - The key identifiers and "descendant schema node identifiers" (see the - ABNF production for "descendant-schema-nodeid" in Section 12 of [5]) - that appear as items in the arguments of 'key' and 'unique' - statements, respectively, are special XPath expressions and MUST be - translated in the same way, i.e., after the translation each key and - every component of a node identifier must have the namespace prefix - of the local module. + ABNF production for and "descendant-schema-nodeid" in Section 12 of + [5]) are not XPath expressions but SHOULD be translated by adding + local module prefixes as well. 8.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 @@ -1357,48 +1461,47 @@ This extension can then be used in the same or another module, for instance like this: leaf folio { acme:documentation-flag 42; type string; } If this extension is honored by the mapping, it will be mapped to - + Note that the 'extension' statement itself is not mapped in any way. 9. Mapping Conceptual Tree Schema to DSDL As explained in Section 5, 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 reply to or , RPC requests or replies and notification. Other parameters - further describing the context may also be provided, such as the list - of active capabilities, features etc. + 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 or the requested document type. For example, if a + 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 accommodated to the specific encapsulating XML + 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 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. These three tasks are together much simpler than the first mapping step. Presumably, they can be effectively realized using XSL @@ -1418,24 +1521,23 @@ 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 definition are - collected in a library file "relang-lib.rng" which is then included - by the validating RELAX NG schemas. Appendix B has the listing of - this library file. + 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 11.1 for more details. 9.1.1. Reply to or For a reply to or , the mapping must take the part @@ -1465,21 +1567,21 @@ that are really used in the particular output grammar. 9.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 in an RPC request or reply. For "yam:myrpc" request, the + type is an RPC request or reply. For "yam:myrpc" request, the resulting grammar looks as follows: ... patterns defining contents of subtree ... ... "nmt:rpc-method/nmt:input/yam:myrpc" ... @@ -1526,62 +1628,70 @@ "nmt:rpc-notification/yam:mynotif" subtree --> The definition of the named pattern "eventTime-element" is found in the "relaxng-lib.rng" library file. - And again, 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 notification. + Again, 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 notification. 9.2. Mapping Semantic Constraints to Schematron Schematron schemas tend to be much flatter and more uniform compared - to RELAX with exactly four levels of XML hierarchy: , - , and or . + 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 - element. Every rule corresponds to exactly one element definition in - the conceptual tree schema. The mandatory @context attribute of - is set to the absolute path of the corresponding element - in the data tree. + element. Every rule corresponds to exactly one element definition + pattern in the conceptual tree schema: - In the opposite direction, however, not every element definition has - a corresponding rule in the Schematron schema: only those definitions - are taken into account that are annotated with at least one of the - following NETMOD-specific annotations: , - @nma:key, , @nma:min-elements, @nma:max-elements, , @nma:unique and . + + ... + + + 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 . + + 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 discriminating between subsets of rules that belong to different validation phases, see Section 9.2.1. Therefore, the always has exactly two children: one named "standard" contains rules for all annotations except - and , and another named "ref-integrity" containing rules + 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 _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 this abstract pattern in the concrete context. + 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. EXAMPLE. Consider this element definition annotated with : The default-lease-time must be less than max-lease-time @@ -1660,21 +1768,21 @@ 5. All annotations attached to the given element definition are then mapped using the mapping rules specified in Section 11. The resulting or elements are the installed as children of the element. 9.2.1. Validation Phases In certain situations it is useful to validate XML instance documents without enforcing the referential integrity constraints represented - by the and annotations. For + 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_: 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. @@ -1759,148 +1867,163 @@ In the second case branch, the "ex4:bar" element is defined as mandatory so that this element must be present in a valid configuration if this branch is selected. However, the two elements in the first branch "foo" cannot be both declared as mandatory since - each one of them alone suffices for a valid configuration. As a - result, the above RELAX NG fragment would successfully validate - configurations where none of the three leafs elements is present. + each of them alone suffices for a valid configuration. As a result, + the above RELAX NG fragment would successfully validate + configurations where none of the three leaf elements is present. Therefore, mandatory choices, which can be recognized in the conceptual tree schema as elements that do not have as their parent, have to be handled in a special way: For each mandatory choice where at least one of the cases contains more than one node, a rule MUST be present in the "standard" pattern of the Schematron schema enforcing the presence of at least one element from any of the cases. (RELAX NG schema guarantees that elements from different cases cannot be mixed together, that all mandatory nodes are present etc.). - For the example module above, the Schematron rule can be as follows: + For the example module above, the Schematron rule will be as follows: Node(s) from at least one case of choice "foobar" must exist. 9.4. Mapping Default Values to DSRL - DSRL is the only component of DSDL that changes 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 model, insertion of - default content in general includes not only default values for leaf - elements but also containers without presence. The following - definition helps in explaining the steps needed for generating the - DSRL schema. - - For a given conceptual tree schema and XML instance document, we - define _implicit element_ to be an element that is inserted in the - process of substituting the default content, provided that its parent - element exists in the instance document. - - Now, let C be a conceptual tree schema and D a NETCONF instance - document. Denote R the RELAX NG schema for the document type of D, - which is generated form C and assume D is a valid XML document with - respect to R. Let P be an element appearing in D. According to the - YANG rules, an element E, which is defined as an optional child of P - in the data tree, is an implicit element if and only if it is either - - a leaf element whose definition in C has a default value specified - in the @nma:default attribute, or - - a container element that does not have the @nma:presence attribute - set to "true" in C and at least one of its children in the data - tree is an implicit element. - - Element E has to satisfy additional conditions in the following two - special cases in order to be an implicit element, regardless of - whether it is a leaf or container: - - o If E is defined in C inside an alternative of , then - this alternative must be marked as the default one with @nma: - default-case="true" in C. - - o If the definition of E in C carries the @nma:when attribute, then - the condition in the value of @nma:when must be true in the - context of the instance document D. + 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 takes place for all implicit + nodes, see Section 8.1. 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 [11]: + element, which is a child of . Two sibling elements of determine the + context for application of the default content, see [11]: 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. - o contains the XML name of the element which is inserted - together with the content of . + o contains the XML name of the element which, if missing + 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. - The logic of DSRL implies that for every non-leaf element P (implicit - or not) containing at least one implicit element among its children, - the DSRL schema must provide one element map for each implicit child - element E, where the full XPath of P appears in the - element and the name of E in . + DSRL mapping only deals with element patterns defining implicit nodes + (see Section 8.1.2). In the conceptual tree schema, such element + patterns are distinguished by NETMOD-specific annotation attributes + that @nma:default or @nma:implicit, i.e., they are either + + + ... + + + or + + + ... + + + In the simple case, these 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: + + If the element pattern defining ELEM is annotated with @nma: + default, DEFCONT is equal to the value of this attribute denoted + above as DEFVALUE. + + 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. + + A more complicated situation arises when the element pattern defining + an implicit node ELEM is a child of with @nma:implicit + attribute. This corresponds to the default case of a YANG choice + (see Section 10.12) and the DSRL mapping has to make sure that the + default content is applied only if none of the nodes from any non- + default case are 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. EXAMPLE. Consider the following YANG module: module example5 { namespace "http://example.com/ns/example5"; prefix ex5; container outer { leaf leaf1 { type uint8; - default "1"; + default 1; } choice one-or-two { default "one"; container one { leaf leaf2 { type uint8; - default "2"; + default 2; } } leaf leaf3 { type uint8; - default "3"; + default 3; } } } } The DSRL schema generated for the "get-reply" target document type will be: - /nc:rpc-reply/nc:data/ + /nc:rpc-reply/nc:data ex5:outer 1 + 2 - /nc:rpc-reply/nc:data/ + + /nc:rpc-reply/nc:data/ex5:outer[not(ex5:leaf3)] + ex5:one 2 /nc:rpc-reply/nc:data/ex5:outer ex5:leaf1 1 @@ -1915,25 +2038,21 @@ /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. - Since DSRL has no facilities similar to named patterns in RELAX NG, - their definitions used in the conceptual tree schema must be expanded - in all places where they are referenced. - -10. Mapping YANG Statements to Annotated RELAX NG +10. 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 5. 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 algorithm is inherently recursive, which means that after @@ -1962,27 +2081,27 @@ We use the following notation: 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. 10.1. The anyxml Statement - This statement is mapped to element and ARGUMENT - becomes the value of its @name attribute. The content of is + 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 are mapped to additional - children of the RELAX NG element definition. + 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. [21], p. 172): @@ -1990,37 +2109,43 @@ - EXAMPLE: YANG statement + EXAMPLE: YANG statement in a module with namespace prefix "yam" anyxml data { description "Any XML content allowed here."; } - maps to the following fragment: + is mapped to the following fragment: - + Any XML content allowed here + An anyxml node is optional if there is no "mandatory true;" + substatement. The element then MUST be wrapped in + , except when the 'anyxml' statement is a child of the + 'choice' statement and thus forms a shorthand case for that choice + (see Section 8.1.1 for details). + 10.2. The argument Statement This statement is not mapped to the output schema, but see the rules - for extension handling in Section 8.4. + for handling extensions in Section 8.4. 10.3. The augment Statement As a substatement of 'uses', this statement is handled as a part of 'uses' mapping, see Section 10.57. At the top level of a module or submodule, the 'augment' statement is used for augmenting the schema tree of another YANG module. If the latter module is not processed within the same mapping session, the top-level 'augment' statement MUST be ignored. Otherwise, the @@ -2039,111 +2164,123 @@ initiated from the main module, see Section 10.24. 10.6. The bit Statement This statement is handled within the "bits" type, see Section 10.53.3. 10.7. The case Statement This statement is mapped to element. If the argument of - a sibling 'default' statement equals to ARGUMENT, @nma:default-case - attribute with the value of "true" is added to that - element. + a sibling 'default' statement equals to ARGUMENT, @nma:implicit + attribute with the value "true" MUST be added to that + 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 [5]). 10.8. The choice Statement This statement is mapped to element. - Unless 'choice' has the 'mandatory' substatement with the value of + Unless 'choice' has the 'mandatory' substatement with the value "true", the element MUST be wrapped in . - The 'choice' statement with "mandatory true;" requires additional handling, see Section 9.3. + The alternatives in - mapped from either the 'case' + statement or a shorthand case - MUST NOT be defined as optional. + 10.9. The config Statement This statement is mapped to @nma:config attribute and ARGUMENT becomes its value. 10.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 10.34. The original - modules are the authoritative sources of the authorship information. + YANG modules are the authoritative sources of the authorship + information. 10.11. The container Statement - Using the procedure outlined in Section 8.1, the mapping algorithm + Using the rules specified in Section 8.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 - as the value of its @name attribute. + with prepended local namespace prefix as the value of its @name + attribute. + + Finally, using the rules specified in Section 8.1.2, the mapping + algorithm MUST determine whether the container is implicit, and if + so, add the attribute @nma:implicit with the value "true" to the + element. 10.12. The default Statement If this statement is a substatement of 'typedef' or 'leaf', it is mapped to the @nma:default attribute of PARENT and ARGUMENT becomes its value. + The @nma:default attribute MUST NOT be used for nodes that belong to + non-default cases of a choice (see Section 7.9.3 in [5]). + As a substatement of 'choice', the 'default' statement identifies the default case and is handled within the 'case' statement, see Section 10.7. If the default case uses the shorthand notation where the 'case' statement is omitted, an extra element MUST be - inserted with @nma:default-case attribute set to "true". The net - result is then the same as if the 'case' statement wasn't omitted for - the default case. + inserted with @nma:implicit attribute set to "true" and map the + default case node inside this element. The net result is then the + same as if the 'case' statement wasn't omitted for the default case. - EXAMPLE. The following 'choice' statement + 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 - - + + - + 10.13. The description Statement This statement is ignored if it appears at the top level of each input YANG module. The description can be found in the source module that is referred to by Dublin Core element and use ARGUMENT as its content. Otherwise, this statement is mapped to the DTD compatibility element and ARGUMENT becomes its text. In order to get properly formatted in the RELAX NG compact syntax, this element SHOULD be inserted as the first child of PARENT. 10.14. The deviation Statement - All 'deviation' statements found in the input YANG modules MUST be - applied first so that the mapping algorithm operates on a schema tree - with all deviations already incorporated. + This statement is ignored, see Section 7.5. 10.15. The enum Statement This statement is mapped to element and ARGUMENT becomes its text. All substatements except 'status' are ignored because the element cannot contain annotations, see [12], section 6. 10.16. The error-app-tag Statement This statement is ignored unless it is a substatement of 'must'. In @@ -2156,21 +2293,21 @@ the latter case it is mapped to the element. See also Section 10.35. 10.18. The extension Statement This statement is ignored. However, extensions to the YANG language MAY be mapped as described in Section 8.4. 10.19. The feature Statement - This statement is ignored. + This statement is ignored, see Section 7.5. 10.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 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 8.2. @@ -2187,23 +2324,21 @@ 10.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 10.53.5 for more details and an example. 10.22. The if-feature Statement - The information whether a given feature is available or not MUST be - supplied to the mapping procedure, which MUST modify the YANG schema - tree by including or excluding the parts that depend on that feature. + This statement is ignored, see Section 7.5. 10.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 tree of the imported module. If the 'import' statement has the 'revision' substatement, the corresponding revision of the imported module MUST be used. The @@ -2228,78 +2363,82 @@ 10.26. The key Statement This statement is mapped to @nma:key attribute. ARGUMENT is 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. 10.27. The leaf Statement This statement is mapped to the element and ARGUMENT - becomes the value of its @name attribute. + with prepended local namespace prefix becomes the value of its @name + attribute. - The leaf is optional if there is no "mandatory true;" substatement - and if the leaf is not declared among the keys of an enclosing list. - In this case, the element MUST be wrapped in . + A leaf is optional if there is no "mandatory true;" substatement and + if the leaf is not declared among the keys of an enclosing list. The + element then MUST be wrapped in , except + when the 'leaf' statement is a child of the 'choice' statement and + thus forms a shorthand case for that choice (see Section 8.1.1 for + details). 10.28. The leaf-list Statement This statement is mapped to a block enclosed by either or element depending on whether the argument of 'min-elements' substatement is "0" or positive, respectively (it is zero by default). This or element becomes the PARENT. is the added as a child element of PARENT and ARGUMENT - becomes the value of its @name attribute. If the 'leaf-list' - statement has the 'min-elements' substatement and its argument is - greater than one, additional attribute @nma:min-elements is attached - to and the argument of 'min-elements' becomes the value - of this attribute. Similarly, if there is the 'max-elements' - substatement and its argument value is not "unbounded", attribute - @nma:max-elements is attached to this element and the argument of - 'max-elements' becomes the value of this attribute. + with prepended local namespace prefix becomes the value of its @name + attribute. If the 'leaf-list' statement has the 'min-elements' + substatement and its argument is greater than one, additional + attribute @nma:min-elements is attached to and the + argument of 'min-elements' becomes the value of this attribute. + Similarly, if there is the 'max-elements' substatement and its + argument value is not "unbounded", attribute @nma:max-elements is + attached to this element and the argument of 'max-elements' becomes + the value of this attribute. - EXAMPLE. YANG leaf-list + EXAMPLE. YANG leaf-list in a module with namespace prefix "yam" leaf-list foliage { min-elements 3; max-elements 6378; ordered-by user; type string; } is mapped to the following RELAX NG fragment: - 10.29. The length Statement This statement is handled within the "string" type, see Section 10.53.9. 10.30. The list Statement This statement is mapped exactly as the 'leaf-list' statement, see Section 10.28. 10.31. The mandatory Statement This statement may appear as a substatement of 'leaf', 'choice' or 'anyxml' statement. If ARGUMENT is "true", the parent data node is - mapped as mandatory, see Section 8.1. + mapped as mandatory, see Section 8.1.1. 10.32. The max-elements Statement This statement is handled within 'leaf-list' or 'list' statements, see Section 10.28. 10.33. The min-elements Statement This statement is handled within 'leaf-list' or 'list' statements, see Section 10.28. @@ -2404,41 +2543,41 @@ 10.44. The prefix Statement This statement is handled within the sibling 'namespace' statement, see Section 10.36, or within the parent 'import' statement, see Section 10.23. As a substatement of 'belongs-to' (in submodules), the 'prefix' statement is ignored. 10.45. The presence Statement This statement is mapped to the annotation attribute @nma:presence - with the value of "true". In addition, it influences the mapping of + with the value "true". In addition, it influences the mapping of 'container' (Section 10.11): the parent container definition MUST be wrapped in , regardless of its content. See also - Section 8.1. + Section 8.1.1. 10.46. The range Statement This statement is handled within numeric types, see Section 10.53.8. 10.47. The reference Statement This statement is ignored if it appears at the top level of a module or submodule. Otherwise, this statement is mapped to element and its text is set to ARGUMENT prefixed with "See: ". 10.48. The require-instance Statement - This statement is handled within the types "leafref" - (Section 10.53.7) and "instance-identifier" (Section 10.53.6). + This statement is handled within "instance-identifier" type + (Section 10.53.6). 10.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 [5]. This date SHOULD be recorded, together with the name of the YANG module, in the corresponding Dublin Core element (see Section 10.34), for example in this form: @@ -2481,49 +2620,45 @@ This statement is not specifically mapped. Its substatements are mapped as if they appeared directly in the module the submodule belongs to. 10.53. The type Statement Most YANG built-in types have an equivalent in the XSD datatype library [16] as shown in Table 3. - +-----------+---------------+----------------------------------+ + +-----------+---------------+--------------------------------+ | YANG type | XSD type | Meaning | - +-----------+---------------+----------------------------------+ + +-----------+---------------+--------------------------------+ | int8 | byte | 8-bit integer value | | | | | | int16 | short | 16-bit integer value | | | | | | int32 | int | 32-bit integer value | | | | | | int64 | long | 64-bit integer value | | | | | | uint8 | unsignedByte | 8-bit unsigned integer value | | | | | | uint16 | unsignedShort | 16-bit unsigned integer value | | | | | | uint32 | unsignedInt | 32-bit unsigned integer value | | | | | | uint64 | unsignedLong | 64-bit unsigned integer value | | | | | - | float32 | float | 32-bit IEEE floating-point value | - | | | | - | float64 | double | 64-bit IEEE floating-point 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 Details about the mapping of individual YANG built-in types are given in the following subsections. 10.53.1. The empty Type This type is mapped to . @@ -2589,67 +2724,91 @@ base "crypto:crypto-alg"; description "DES crypto algorithm"; } identity des3 { base "crypto:crypto-alg"; description "Triple DES crypto algorithm"; } } - If these two modules are imported to another module, leaf definition + If these two modules are imported to another module with namespace + prefix "yam", leaf definition leaf crypto { type identityref { base "crypto:crypto-alg"; } } is mapped to - + crypto:crypto-alg des:des des:des3 The "crypto" and "des" prefixes will by typically defined via attributes of the element. 10.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 . 10.53.7. The leafref Type - This type is mapped to element with @type attribute set to - the type of the leaf given in the argument of 'path' substatement. - In addition, element MUST be inserted as a child of - PARENT. The argument value of the 'path' substatement is set as the - text of this element. - - The 'require-instance' substatement, if it exists, is mapped to the - @require-instance attribute of . + 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 8.3, is set as the value of this + attribute. 10.53.8. The numeric Types YANG built-in numeric types are "int8", "int16", "int32", "int64", - "uint8", "uint16", "uint32", "uint64", "float32" and "float64". They - are mapped to element with @type attribute set to ARGUMENT + "uint8", "uint16", "uint32", "uint64" and "decimal64". They are + mapped to element with @type attribute set to ARGUMENT mapped according to Table 3. + 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. + + For example, the statement + + type decimal64 { + fraction-digits 2; + } + + is mapped to the following RELAX NG datatype: + + + 19 + 2 + + All numeric types support the 'range' restriction, which is handled in the following way: o If the range expression consists of a single range part, insert the pair of RELAX NG facets ... and ... @@ -2782,22 +2941,22 @@ corresponding grouping must be looked up and its contents is inserted as children of PARENT. See Section 8.2.1 for further details and an example. 10.58. The value Statement This statement is ignored. 10.59. The when Statement - This statement is mapped to @nma:when attribute and ARGUMENT becomes - it value. + This statement is mapped to @nma:when attribute and ARGUMENT, + translated according to Section 8.3, becomes it value. 10.60. The yang-version Statement This statement is not mapped to the output schema. However, an implementation SHOULD check that it is compatible with the YANG version declared by the statement (currently version 1). 10.61. The yin-element Statement This statement is not mapped to the output schema, but see the rules @@ -2825,21 +2984,21 @@ 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. 11.2. The @nma:default Annotation This annotation is used for generating the DSRL schema as described in Section 9.4. -11.3. The @nma:default-case Annotation +11.3. The @nma:implicit Annotation This annotation is used for generating the DSRL schema as described in Section 9.4. 11.4. The Annotation This annotation currently has no mapping defined. 11.5. The Annotation @@ -2871,46 +3030,31 @@ 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 k_i=current()/k_i -11.8. The Annotation - - The mapping of this annotation depends on its @require-instance - attribute. If this attribute is not present or its value is "true", - the referred leaf must exist in the instance document (this is - verified by the RELAX NG schema) and the annotation is - mapped to the following assert: - - - Leafref "CONTELEM" must have the same value as "PATH" - - - where PATH is the content of . +11.8. The @nma:leafref Annotation - If the @require-instance attribute has the value "false", then the - equality in contents of the context element and the referred leaf is - required only if the referred leaf exists. Hence, is - mapped to the following assert: + This annotation is mapped to the following assert: - + Leafref "CONTELEM" must have the same value as "PATH" - In both cases the assert is a descendant of the "ref-integrity" - pattern, which means that it will be used only for the "full" - validation phase. + where PATH is the value of @nma:leafref. The assert is a descendant + of the "ref-integrity" pattern, which means that it will be used only + for the "full" validation phase. 11.9. The @nma:min-elements Annotation This annotation is mapped to the following Schematron assert: List "CONTELEM" - item count must be at least MIN where MIN is the value of @nma:min-elements. @@ -3097,22 +3241,22 @@ - - + + @@ -3137,27 +3281,22 @@ - - - - - - - + + @@ -3225,34 +3364,33 @@ A.2. Compact Syntax namespace nma = "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1" config-attribute = attribute nma:config { xsd:boolean } default-attribute = attribute nma:default { text } - default-case-attribute = attribute nma:default-case { xsd:boolean } + implicit-attribute = attribute nma:implicit { xsd:boolean } error-app-tag-element = element nma:error-app-tag { text }? error-message-element = element nma:error-message { text }? instance-identifier-element = element nma:instance-identifier { attribute nma:require-instance { xsd:boolean }? } key-attribute = attribute nma:key { list { xsd:QName } } leafref-element = - element nma:leafref { - attribute nma:require-instance { xsd:boolean }?, + attribute nma:leafref { xsd:string } min-elements-attribute = attribute nma:min-elements { xsd:integer } max-elements-attribute = attribute nma:max-elements { xsd:integer } must-element = element nma:must { attribute nma:assert { xsd:string }, (err-app-tag-element & err-message-element) } ordered-by-attribute = attribute nma:ordered-by { "user" | "system" } @@ -3365,21 +3503,21 @@ "configuration and operational parameters for a DHCP server."; leaf max-lease-time { type uint32; units seconds; default 7200; } leaf default-lease-time { type uint32; units seconds; - must '. <= ../dhcp:max-lease-time' { + must '. <= ../max-lease-time' { error-message "The default-lease-time must be less than max-lease-time"; } default 600; } uses subnet-list; container shared-networks { list shared-network { @@ -3474,367 +3612,382 @@ - Pyang 0.9.3, RELAX NG plugin + Pyang 0.9.3, CTS plugin YANG module 'dhcp' - + + - configuration and operational parameters for a DHCP server. + configuration and operational parameters for a DHCP server - + - The default-lease-time must be less than max-lease-time + The default-lease-time must be less than max-lease-time. + + + + + - + + - + - + + ethernet token-ring fddi - + + + + + + A reusable list of subnets - + + + Allows BOOTP clients to get addresses in this range - + - + + + Options in the DHCP protocol See: RFC 2132, sec. 3.8 - + See: RFC 2132, sec. 3.17 - + + + + - + - - + + - + ... regex pattern ... - + ... regex pattern ... + ... regex pattern ... - + - - + + - + ... regex pattern ... - + ... regex pattern ... + ... regex pattern ... - + - - + + - + - ... regex pattern ... + 1 + 253 ... regex pattern ... - + ... regex pattern ... - - + + + + ([0-9a0-fA-F]{2}(:[0-9a0-fA-F]{2})*)? + + C.2.2. Compact Syntax namespace a = "http://relaxng.org/ns/compatibility/annotations/1.0" namespace dc = "http://purl.org/dc/terms" namespace dhcp = "http://example.com/ns/dhcp" namespace nma = "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1" namespace nmt = "urn:ietf:params:xml:ns:netmod:conceptual-tree:1" - dc:creator [ "Pyang 0.9.3, RELAX NG plugin" ] + dc:creator [ "Pyang 0.9.3, CTS plugin" ] dc:source [ "YANG module 'dhcp'" ] start = element nmt:netmod-tree { element nmt:top { - - ## configuration and operational parameters for a DHCP server. + [ nma:implicit = "true" ] element dhcp:dhcp { - [ nma:default = "7200" nma:units = "seconds" ] - element dhcp:max-lease-time { xsd:unsignedInt }?, - [ nma:default = "600" nma:units = "seconds" ] + + ## + ## configuration and operational parameters for a DHCP server + ## + ([ nma:default = "7200" nma:units = "seconds" ] + element dhcp:max-lease-time { xsd:unsignedInt }? + & [ nma:default = "600" nma:units = "seconds" ] element dhcp:default-lease-time { xsd:unsignedInt >> nma:must [ assert = ". <= ../dhcp:max-lease-time" nma:error-message [ - "The default-lease-time must be less than max-lease-time" + "\x{a}" ~ + "The default-lease-time must be less than max-lease-time." ~ + "\x{a}" ] ] - }?, - _dhcp__subnet-list, - element dhcp:shared-networks { + }? + & _dhcp__subnet-list + & element dhcp:shared-networks { [ nma:key = "dhcp:name" ] element dhcp:shared-network { element dhcp:name { xsd:string }, - _dhcp__subnet-list + (_dhcp__subnet-list) }* - }?, - [ nma:config = "false" ] + }? + & [ nma:config = "false" ] element dhcp:status { [ nma:key = "dhcp:address" ] element dhcp:leases { - element dhcp:address { inet-types__ip-address }, - element dhcp:starts { yang-types__date-and-time }?, - element dhcp:ends { yang-types__date-and-time }?, - element dhcp:hardware { - element dhcp:type { "ethernet" - | "token-ring" - | "fddi" - }?, - element dhcp:address { yang-types__phys-address }? + element dhcp:address { ietf-inet-types__ip-address }, + (element dhcp:starts { ietf-yang-types__date-and-time }? + & element dhcp:ends { ietf-yang-types__date-and-time }? + & element dhcp:hardware { + element dhcp:type { + "ethernet" | "token-ring" | "fddi" }? - }* + & element dhcp:address { + ietf-yang-types__phys-address }? + }?) + }* + }?) }? }, element nmt:rpc-methods { empty }, element nmt:notifications { empty } } + _dhcp__subnet-list = ## A reusable list of subnets - _dhcp__subnet-list = - [ nma:key = "dhcp:net" ] + ([ nma:key = "dhcp:net" ] element dhcp:subnet { - element dhcp:net { inet-types__ip-prefix }, - element dhcp:range { + element dhcp:net { ietf-inet-types__ip-prefix }, + (element dhcp:range { + ## ## Allows BOOTP clients to get addresses in this range - element dhcp:dynamic-bootp { empty }?, - element dhcp:low { inet-types__ip-address }, - element dhcp:high { inet-types__ip-address } - }?, + ## + element dhcp:dynamic-bootp { empty }? + & element dhcp:low { ietf-inet-types__ip-address } + & element dhcp:high { ietf-inet-types__ip-address } + }? + & element dhcp:dhcp-options { + ## ## Options in the DHCP protocol - element dhcp:dhcp-options { - + ## + ( + ## ## See: RFC 2132, sec. 3.8 + ## [ nma:ordered-by = "user" ] - element dhcp:router { inet-types__host }*, - + element dhcp:router { ietf-inet-types__host }* + & + ## ## See: RFC 2132, sec. 3.17 - element dhcp:domain-name { inet-types__domain-name }? - }?, - [ nma:default = "7200" nma:units = "seconds" ] - element dhcp:max-lease-time { xsd:unsignedInt }? - }* - inet-types__ip-prefix = - inet-types__ipv4-prefix | inet-types__ipv6-prefix - inet-types__ipv4-prefix = - xsd:string { - pattern = - "(([0-1]?[0-9]?[0-9]|2[0-4][0-9]|25[0-5])\.)" ~ - "{3}([0-1]?[0-9]?[0-9]|2[0-4][0-9]|25[0-5])/\p{N}+" - } - inet-types__ipv6-prefix = - xsd:string { - pattern = - "((([0-9a-fA-F]{1,4}:){7})([0-9a-fA-F]{1,4})/" ~ - "\p{N}+)|((([0-9a-fA-F]{1,4}:){6})(([0-9]{1,3}\." ~ - "[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}))/\p{N}+)|" ~ - "((([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*(::)" ~ - "(([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*/\p{N}+)" ~ - "((([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*(::)" ~ - "(([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*(([0-9]" ~ - "{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}))/\p{N}+)" - } - inet-types__ip-address = - inet-types__ipv4-address | inet-types__ipv6-address - inet-types__ipv4-address = + ## + element dhcp:domain-name { ietf-inet-types__domain-name }?) + }? + & [ nma:default = "7200" nma:units = "seconds" ] + element dhcp:max-lease-time { xsd:unsignedInt }?) + }*) + ietf-inet-types__ip-prefix = + ietf-inet-types__ipv4-prefix | ietf-inet-types__ipv6-prefix + ietf-inet-types__ipv4-prefix = + xsd:string { pattern = "... regex pattern ..." } + ietf-inet-types__ipv6-prefix = xsd:string { - pattern = - "(([0-1]?[0-9]?[0-9]|2[0-4][0-9]|25[0-5])\.){3}([0-1]?" ~ - "[0-9]?[0-9]|2[0-4][0-9]|25[0-5])(%[\p{N}\p{L}]+)?" + pattern = "... regex pattern ..." + pattern = "... regex pattern ..." } - inet-types__ipv6-address = + ietf-inet-types__ip-address = + ietf-inet-types__ipv4-address | ietf-inet-types__ipv6-address + ietf-inet-types__ipv4-address = + xsd:string { pattern = "... regex pattern ..." } + ietf-inet-types__ipv6-address = xsd:string { - pattern = - "((([0-9a-fA-F]{1,4}:){7})([0-9a-fA-F]{1,4})(%[\p{N}" ~ - "\p{L}]+)?)|((([0-9a-fA-F]{1,4}:){6})(([0-9]{1,3}\." ~ - "[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}))(%[\p{N}\p{L}]+)?)|" ~ - "((([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*(::)" ~ - "(([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*(%[\p{N}" ~ - "\p{L}]+)?)((([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*" ~ - "(::)(([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*(([0-9]{1,3}" ~ - "\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}))(%[\p{N}\p{L}]+)?)" + pattern = "... regex pattern ..." + pattern = "... regex pattern ..." } - inet-types__host = inet-types__ip-address | inet-types__domain-name - inet-types__domain-name = + ietf-inet-types__host = + ietf-inet-types__ip-address | ietf-inet-types__domain-name + ietf-inet-types__domain-name = xsd:string { - pattern = - "([a-zA-Z][a-zA-Z0-9\-]*[a-zA-Z0-9]\.)*" ~ - "[a-zA-Z][a-zA-Z0-9\-]*[a-zA-Z0-9]" - pattern = - "([r-zA-Z][a-zA-Z0-9\-]*[a-zA-Z0-9]\.)*" ~ - "[a-zA-Z][a-zA-Z0-9\-]*[a-zA-Z0-9]" + minLength = "1" + maxLength = "253" + pattern = "... regex pattern ..." } - yang-types__date-and-time = + ietf-yang-types__date-and-time = + xsd:string { pattern = "... regex pattern ..." } + ietf-yang-types__phys-address = xsd:string { - pattern = - "\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}" ~ - "(\.d*)?(Z|(\+|-)\d{2}:\d{2})" + pattern = "([0-9a0-fA-F]{2}(:[0-9a0-fA-F]{2})*)?" } - yang-types__phys-address = xsd:string C.3. Final DSDL Schemas This appendix contains DSDL schemas that were obtained from the conceptual tree schema in Appendix C.2 by XSL transformations. These schemas can be directly used for validating a reply to unfiltered with the contents corresponding to the DHCP data model. The RELAX NG schema (again shown in both XML and compact syntax) includes the schema independent library from Appendix B. @@ -3844,349 +3997,353 @@ - + - - - + + + + + + + + + - + + - + - + + ethernet token-ring fddi - + + + + + - - + + + - + + + - + - + + + - + - + + + + - + - - + + - + ... regex pattern ... - + ... regex pattern ... + ... regex pattern ... - + - - + + - + ... regex pattern ... - + ... regex pattern ... + ... regex pattern ... - + - - + + - + - ... regex pattern ... + 1 + 253 ... regex pattern ... - + ... regex pattern ... - - + + + + ([0-9a0-fA-F]{2}(:[0-9a0-fA-F]{2})*)? + + C.3.2. RELAX NG Schema for Reply - Compact Syntax default namespace = "urn:ietf:params:xml:ns:netconf:base:1.0" namespace a = "http://relaxng.org/ns/compatibility/annotations/1.0" namespace dc = "http://purl.org/dc/terms" namespace dhcp = "http://example.com/ns/dhcp" namespace nma = "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1" namespace nmt = "urn:ietf:params:xml:ns:netmod:conceptual-tree:1" include "relaxng-lib.rnc" start = element rpc-reply { message-id-attribute, element data { element dhcp:dhcp { - element dhcp:max-lease-time { xsd:unsignedInt }?, - element dhcp:default-lease-time { xsd:unsignedInt }?, - _dhcp__subnet-list, - element dhcp:shared-networks { + element dhcp:max-lease-time { xsd:unsignedInt }? + & element dhcp:default-lease-time { xsd:unsignedInt }? + & _dhcp__subnet-list + & element dhcp:shared-networks { element dhcp:shared-network { element dhcp:name { xsd:string }, - _dhcp__subnet-list + (_dhcp__subnet-list) }* - }?, - element dhcp:status { + }? + & element dhcp:status { element dhcp:leases { - element dhcp:address { inet-types__ip-address }, - element dhcp:starts { yang-types__date-and-time }?, - element dhcp:ends { yang-types__date-and-time }?, - element dhcp:hardware { - element dhcp:type { "ethernet" - | "token-ring" - | "fddi" - }?, - element dhcp:address { yang-types__phys-address }? + element dhcp:address { ietf-inet-types__ip-address }, + (element dhcp:starts { ietf-yang-types__date-and-time }? + & element dhcp:ends { ietf-yang-types__date-and-time }? + & element dhcp:hardware { + element dhcp:type { + "ethernet" | "token-ring" | "fddi" }? + & element dhcp:address { + ietf-yang-types__phys-address + }? + }?) }* }? }? } } _dhcp__subnet-list = element dhcp:subnet { - element dhcp:net { inet-types__ip-prefix }, - element dhcp:range { - element dhcp:dynamic-bootp { empty }?, - element dhcp:low { inet-types__ip-address }, - element dhcp:high { inet-types__ip-address } - }?, - element dhcp:dhcp-options { - element dhcp:router { inet-types__host }*, - element dhcp:domain-name { inet-types__domain-name }? - }?, - element dhcp:max-lease-time { xsd:unsignedInt }? + element dhcp:net { ietf-inet-types__ip-prefix }, + (element dhcp:range { + element dhcp:dynamic-bootp { empty }? + & element dhcp:low { ietf-inet-types__ip-address } + & element dhcp:high { ietf-inet-types__ip-address } + }? + & element dhcp:dhcp-options { + element dhcp:router { ietf-inet-types__host }* + & element dhcp:domain-name { ietf-inet-types__domain-name }? + }? + & element dhcp:max-lease-time { xsd:unsignedInt }?) }* - inet-types__ip-prefix = - inet-types__ipv4-prefix | inet-types__ipv6-prefix - inet-types__ipv4-prefix = - xsd:string { - pattern = - "(([0-1]?[0-9]?[0-9]|2[0-4][0-9]|25[0-5])\.)" ~ - "{3}([0-1]?[0-9]?[0-9]|2[0-4][0-9]|25[0-5])/\p{N}+" - } - inet-types__ipv6-prefix = - xsd:string { - pattern = - "((([0-9a-fA-F]{1,4}:){7})([0-9a-fA-F]{1,4})/" ~ - "\p{N}+)|((([0-9a-fA-F]{1,4}:){6})(([0-9]{1,3}\." ~ - "[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}))/\p{N}+)|" ~ - "((([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*(::)" ~ - "(([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*/\p{N}+)" ~ - "((([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*(::)" ~ - "(([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*(([0-9]" ~ - "{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}))/\p{N}+)" - } - inet-types__ip-address = - inet-types__ipv4-address | inet-types__ipv6-address - inet-types__ipv4-address = + ietf-inet-types__ip-prefix = + ietf-inet-types__ipv4-prefix | ietf-inet-types__ipv6-prefix + ietf-inet-types__ipv4-prefix = + xsd:string { pattern = "... regex pattern ..." } + ietf-inet-types__ipv6-prefix = xsd:string { - pattern = - "(([0-1]?[0-9]?[0-9]|2[0-4][0-9]|25[0-5])\.){3}([0-1]?" ~ - "[0-9]?[0-9]|2[0-4][0-9]|25[0-5])(%[\p{N}\p{L}]+)?" + pattern = "... regex pattern ..." + pattern = "... regex pattern ..." } - inet-types__ipv6-address = + ietf-inet-types__ip-address = + ietf-inet-types__ipv4-address | ietf-inet-types__ipv6-address + ietf-inet-types__ipv4-address = + xsd:string { pattern = "... regex pattern ..." } + ietf-inet-types__ipv6-address = xsd:string { - pattern = - "((([0-9a-fA-F]{1,4}:){7})([0-9a-fA-F]{1,4})(%[\p{N}" ~ - "\p{L}]+)?)|((([0-9a-fA-F]{1,4}:){6})(([0-9]{1,3}\." ~ - "[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}))(%[\p{N}\p{L}]+)?)|" ~ - "((([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*(::)" ~ - "(([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*(%[\p{N}" ~ - "\p{L}]+)?)((([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*" ~ - "(::)(([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*(([0-9]{1,3}" ~ - "\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}))(%[\p{N}\p{L}]+)?)" + pattern = "... regex pattern ..." + pattern = "... regex pattern ..." } - inet-types__host = inet-types__ip-address | inet-types__domain-name - inet-types__domain-name = + ietf-inet-types__host = + ietf-inet-types__ip-address | ietf-inet-types__domain-name + ietf-inet-types__domain-name = xsd:string { - pattern = - "([a-zA-Z][a-zA-Z0-9\-]*[a-zA-Z0-9]\.)*" ~ - "[a-zA-Z][a-zA-Z0-9\-]*[a-zA-Z0-9]" - pattern = - "([r-zA-Z][a-zA-Z0-9\-]*[a-zA-Z0-9]\.)*" ~ - "[a-zA-Z][a-zA-Z0-9\-]*[a-zA-Z0-9]" + minLength = "1" + maxLength = "253" + pattern = "... regex pattern ..." } - yang-types__date-and-time = + ietf-yang-types__date-and-time = + xsd:string { pattern = "... regex pattern ..." } + ietf-yang-types__phys-address = xsd:string { pattern = - "\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}" ~ - "(\.d*)?(Z|(\+|-)\d{2}:\d{2})" + "\x{a}" ~ + " ([0-9a0-fA-F]{2}(:[0-9a0-fA-F]{2})*)?\x{a}" ~ + " " } - yang-types__phys-address = xsd:string C.4. Schematron Schema for Reply - + Duplicate key of list dhcp:subnet - The default-lease-time must be less than max-lease-time + The default-lease-time must be less than max-lease-time. - + Duplicate key of list dhcp:shared-network - + Duplicate key of list dhcp:leases @@ -4228,21 +4385,54 @@ /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 -01 and -02 +D.1. 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 9.2. + + o Reworked Section 9.4, added skeleton element maps,corrected the + example. + + o Added section Section 7.5 on 'feature' and 'deviation'. + + o New Section 8.1 integrating discussion of both optional/mandatory + (was in -02) and implicit nodes (new). + + o Reflected that key argument and schema node identifiers are no + more XPath (should be in yang-07). + + o Element patterns for implicit containers now must have @nma: + implicit attribute. + + o Removed "float32" and "float64" types and added mapping of + "decimal64" with example. + + o Removed mapping of 'require-instance' for "leafref" type. + + o Updated RELAX NG schema for NETMOD-specific annotations. + + o Updated the DHCP example. + + o Many minor corrections and clarifications. + +D.2. Changes Between Versions -01 and -02 o Moved Section 6 "NETCONF Content Validation" after Section 5. o New text about mapping defaults to DSRL, especially in Section 6 and Section 9.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. @@ -4254,21 +4444,21 @@ 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. o Many other minor corrections and improvements. -D.2. Changes Between Versions -00 and -01 +D.3. 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'.