draft-ietf-netmod-dsdl-map-00.txt   draft-ietf-netmod-dsdl-map-01.txt 
NETMOD L. Lhotka NETMOD L. Lhotka
Internet-Draft CESNET Internet-Draft CESNET
Intended status: Standards Track R. Mahy Intended status: Standards Track R. Mahy
Expires: August 15, 2009 Plantronics Expires: September 9, 2009 Plantronics
S. Chisholm S. Chisholm
Nortel Nortel
February 11, 2009 March 8, 2009
Mapping YANG to Document Schema Definition Languages and Validating Mapping YANG to Document Schema Definition Languages and Validating
NETCONF Content NETCONF Content
draft-ietf-netmod-dsdl-map-00 draft-ietf-netmod-dsdl-map-01
Status of this Memo Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet- other groups may also distribute working documents as Internet-
Drafts. Drafts.
skipping to change at page 1, line 36 skipping to change at page 1, line 36
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on August 15, 2009. This Internet-Draft will expire on September 9, 2009.
Copyright Notice Copyright Notice
Copyright (c) 2009 IETF Trust and the persons identified as the Copyright (c) 2009 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. to this document.
Abstract Abstract
This draft describes the mapping rules for translating YANG data This draft describes the mapping rules for translating YANG data
models into XML schemas using Document Schema Definition Languages models into XML schemas using Document Schema Definition Languages
(DSDL). (DSDL) and outlines the procedure for validating various types of
NETCONF protocol data units using these schemas.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 6
2. Objectives and Motivation . . . . . . . . . . . . . . . . . . 8 2. Objectives and Motivation . . . . . . . . . . . . . . . . . . 9
3. DSDL Schema Languages . . . . . . . . . . . . . . . . . . . . 10 3. DSDL Schema Languages . . . . . . . . . . . . . . . . . . . . 11
3.1. RELAX NG . . . . . . . . . . . . . . . . . . . . . . . . 10 3.1. RELAX NG . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2. Schematron . . . . . . . . . . . . . . . . . . . . . . . 11 3.2. Schematron . . . . . . . . . . . . . . . . . . . . . . . 12
3.3. Document Schema Renaming Language (DSRL) . . . . . . . . 12 3.3. Document Semantics Renaming Language (DSRL) . . . . . . . 13
4. Additional Annotations . . . . . . . . . . . . . . . . . . . . 13 4. Additional Annotations . . . . . . . . . . . . . . . . . . . . 14
4.1. Dublin Core Metadata Elements . . . . . . . . . . . . . . 13 4.1. Dublin Core Metadata Elements . . . . . . . . . . . . . . 14
4.2. RELAX NG DTD Compatibility Annotations . . . . . . . . . 13 4.2. RELAX NG DTD Compatibility Annotations . . . . . . . . . 14
4.3. NETMOD-specific Annotations . . . . . . . . . . . . . . . 14 4.3. NETMOD-specific Annotations . . . . . . . . . . . . . . . 15
5. Overview of the Mapping . . . . . . . . . . . . . . . . . . . 16 5. Overview of the Mapping . . . . . . . . . . . . . . . . . . . 17
6. Design Considerations . . . . . . . . . . . . . . . . . . . . 19 6. Design Considerations . . . . . . . . . . . . . . . . . . . . 19
6.1. Conceptual Data Tree . . . . . . . . . . . . . . . . . . 19 6.1. Conceptual Data Tree . . . . . . . . . . . . . . . . . . 19
6.2. Modularity . . . . . . . . . . . . . . . . . . . . . . . 21 6.2. Modularity . . . . . . . . . . . . . . . . . . . . . . . 21
6.3. Granularity . . . . . . . . . . . . . . . . . . . . . . . 22 6.3. Granularity . . . . . . . . . . . . . . . . . . . . . . . 22
7. Mapping Data Model Structure to the Conceptual Tree Schema . . 23 6.4. Handling of XML Namespaces . . . . . . . . . . . . . . . 22
7.1. Optional and Mandatory Content . . . . . . . . . . . . . 23 7. Mapping YANG Data Models to the Conceptual Tree Schema . . . . 24
7.2. Mapping YANG Groupings and Typedefs . . . . . . . . . . . 23 7.1. Optional and Mandatory Content . . . . . . . . . . . . . 24
7.2.1. YANG Refinements and Augments . . . . . . . . . . . 26 7.2. Mapping YANG Groupings and Typedefs . . . . . . . . . . . 25
7.2.2. Type derivation chains . . . . . . . . . . . . . . . 29 7.2.1. YANG Refinements and Augments . . . . . . . . . . . 27
7.3. Translation of XPath Expressions . . . . . . . . . . . . 30 7.2.2. Type derivation chains . . . . . . . . . . . . . . . 30
7.4. YANG Language Extensions . . . . . . . . . . . . . . . . 31 7.3. Translation of XPath Expressions . . . . . . . . . . . . 31
7.5. RPC Signatures and Notifications . . . . . . . . . . . . 32 7.4. YANG Language Extensions . . . . . . . . . . . . . . . . 32
8. Mapping Conceptual Tree Schema to DSDL . . . . . . . . . . . . 33 8. Mapping Conceptual Tree Schema to DSDL . . . . . . . . . . . . 34
8.1. Mapping Semantic Constraints to Schematron . . . . . . . 33 8.1. Generating RELAX NG Schemas for Various Document Types . 34
8.1.1. Library of Schema-independent Schematron Patterns . 33 8.1.1. Reply to <get> or <get-config> . . . . . . . . . . . 35
8.2. Mapping Default Values to DSRL . . . . . . . . . . . . . 33 8.1.2. Remote Procedure Calls . . . . . . . . . . . . . . . 35
9. NETCONF Content Validation . . . . . . . . . . . . . . . . . . 34 8.1.3. Notifications . . . . . . . . . . . . . . . . . . . 36
9.1. Validation Phases . . . . . . . . . . . . . . . . . . . . 34 8.2. Mapping Semantic Constraints to Schematron . . . . . . . 37
10. Mapping YANG Statements to Annotated RELAX NG . . . . . . . . 36 8.2.1. Validation Phases . . . . . . . . . . . . . . . . . 40
10.1. The anyxml Statement . . . . . . . . . . . . . . . . . . 36 8.3. Mapping Default Values to DSRL . . . . . . . . . . . . . 41
10.2. The argument Statement . . . . . . . . . . . . . . . . . 37 9. NETCONF Content Validation . . . . . . . . . . . . . . . . . . 42
10.3. The augment Statement . . . . . . . . . . . . . . . . . . 37 10. Mapping YANG Statements to Annotated RELAX NG . . . . . . . . 43
10.4. The base Statement . . . . . . . . . . . . . . . . . . . 38 10.1. The anyxml Statement . . . . . . . . . . . . . . . . . . 43
10.5. The belongs-to Statement . . . . . . . . . . . . . . . . 38 10.2. The argument Statement . . . . . . . . . . . . . . . . . 44
10.6. The bit Statement . . . . . . . . . . . . . . . . . . . . 38 10.3. The augment Statement . . . . . . . . . . . . . . . . . . 44
10.7. The case Statement . . . . . . . . . . . . . . . . . . . 38 10.4. The base Statement . . . . . . . . . . . . . . . . . . . 45
10.8. The choice Statement . . . . . . . . . . . . . . . . . . 38 10.5. The belongs-to Statement . . . . . . . . . . . . . . . . 45
10.9. The config Statement . . . . . . . . . . . . . . . . . . 38 10.6. The bit Statement . . . . . . . . . . . . . . . . . . . . 45
10.10. The contact Statement . . . . . . . . . . . . . . . . . . 38 10.7. The case Statement . . . . . . . . . . . . . . . . . . . 45
10.11. The container Statement . . . . . . . . . . . . . . . . . 38 10.8. The choice Statement . . . . . . . . . . . . . . . . . . 45
10.12. The default Statement . . . . . . . . . . . . . . . . . . 39 10.9. The config Statement . . . . . . . . . . . . . . . . . . 45
10.13. The description Statement . . . . . . . . . . . . . . . . 39 10.10. The contact Statement . . . . . . . . . . . . . . . . . . 45
10.14. The enum Statement . . . . . . . . . . . . . . . . . . . 40 10.11. The container Statement . . . . . . . . . . . . . . . . . 45
10.15. The error-app-tag Statement . . . . . . . . . . . . . . . 40 10.12. The default Statement . . . . . . . . . . . . . . . . . . 46
10.16. The error-message Statement . . . . . . . . . . . . . . . 40 10.13. The description Statement . . . . . . . . . . . . . . . . 46
10.17. The extension Statement . . . . . . . . . . . . . . . . . 40 10.14. The enum Statement . . . . . . . . . . . . . . . . . . . 47
10.18. The grouping Statement . . . . . . . . . . . . . . . . . 40 10.15. The error-app-tag Statement . . . . . . . . . . . . . . . 47
10.19. The identity Statement . . . . . . . . . . . . . . . . . 41 10.16. The error-message Statement . . . . . . . . . . . . . . . 47
10.20. The import Statement . . . . . . . . . . . . . . . . . . 41 10.17. The extension Statement . . . . . . . . . . . . . . . . . 47
10.21. The include Statement . . . . . . . . . . . . . . . . . . 41 10.18. The grouping Statement . . . . . . . . . . . . . . . . . 47
10.22. The input Statement . . . . . . . . . . . . . . . . . . . 41 10.19. The identity Statement . . . . . . . . . . . . . . . . . 48
10.23. The key Statement . . . . . . . . . . . . . . . . . . . . 41 10.20. The import Statement . . . . . . . . . . . . . . . . . . 48
10.24. The leaf Statement . . . . . . . . . . . . . . . . . . . 41 10.21. The include Statement . . . . . . . . . . . . . . . . . . 48
10.25. The leaf-list Statement . . . . . . . . . . . . . . . . . 42 10.22. The input Statement . . . . . . . . . . . . . . . . . . . 48
10.26. The length Statement . . . . . . . . . . . . . . . . . . 42 10.23. The key Statement . . . . . . . . . . . . . . . . . . . . 48
10.27. The list Statement . . . . . . . . . . . . . . . . . . . 42 10.24. The leaf Statement . . . . . . . . . . . . . . . . . . . 48
10.28. The mandatory Statement . . . . . . . . . . . . . . . . . 43 10.25. The leaf-list Statement . . . . . . . . . . . . . . . . . 49
10.29. The max-elements Statement . . . . . . . . . . . . . . . 43 10.26. The length Statement . . . . . . . . . . . . . . . . . . 49
10.30. The min-elements Statement . . . . . . . . . . . . . . . 43 10.27. The list Statement . . . . . . . . . . . . . . . . . . . 50
10.31. The module Statement . . . . . . . . . . . . . . . . . . 43 10.28. The mandatory Statement . . . . . . . . . . . . . . . . . 50
10.32. The must Statement . . . . . . . . . . . . . . . . . . . 43 10.29. The max-elements Statement . . . . . . . . . . . . . . . 50
10.33. The namespace Statement . . . . . . . . . . . . . . . . . 44 10.30. The min-elements Statement . . . . . . . . . . . . . . . 50
10.34. The notification Statement . . . . . . . . . . . . . . . 45 10.31. The module Statement . . . . . . . . . . . . . . . . . . 50
10.35. The ordered-by Statement . . . . . . . . . . . . . . . . 45 10.32. The must Statement . . . . . . . . . . . . . . . . . . . 50
10.36. The organization Statement . . . . . . . . . . . . . . . 45 10.33. The namespace Statement . . . . . . . . . . . . . . . . . 51
10.37. The output Statement . . . . . . . . . . . . . . . . . . 46 10.34. The notification Statement . . . . . . . . . . . . . . . 51
10.38. The path Statement . . . . . . . . . . . . . . . . . . . 46 10.35. The ordered-by Statement . . . . . . . . . . . . . . . . 51
10.39. The pattern Statement . . . . . . . . . . . . . . . . . . 46 10.36. The organization Statement . . . . . . . . . . . . . . . 52
10.40. The position Statement . . . . . . . . . . . . . . . . . 46 10.37. The output Statement . . . . . . . . . . . . . . . . . . 52
10.41. The prefix Statement . . . . . . . . . . . . . . . . . . 46 10.38. The path Statement . . . . . . . . . . . . . . . . . . . 52
10.42. The presence Statement . . . . . . . . . . . . . . . . . 46 10.39. The pattern Statement . . . . . . . . . . . . . . . . . . 52
10.43. The range Statement . . . . . . . . . . . . . . . . . . . 46 10.40. The position Statement . . . . . . . . . . . . . . . . . 52
10.44. The reference Statement . . . . . . . . . . . . . . . . . 46 10.41. The prefix Statement . . . . . . . . . . . . . . . . . . 52
10.45. The require-instance Statement . . . . . . . . . . . . . 46 10.42. The presence Statement . . . . . . . . . . . . . . . . . 52
10.46. The revision Statement . . . . . . . . . . . . . . . . . 47 10.43. The range Statement . . . . . . . . . . . . . . . . . . . 52
10.47. The rpc Statement . . . . . . . . . . . . . . . . . . . . 47 10.44. The reference Statement . . . . . . . . . . . . . . . . . 52
10.48. The status Statement . . . . . . . . . . . . . . . . . . 47 10.45. The require-instance Statement . . . . . . . . . . . . . 53
10.49. The submodule Statement . . . . . . . . . . . . . . . . . 47 10.46. The revision Statement . . . . . . . . . . . . . . . . . 53
10.50. The type Statement . . . . . . . . . . . . . . . . . . . 47 10.47. The rpc Statement . . . . . . . . . . . . . . . . . . . . 53
10.50.1. The empty Type . . . . . . . . . . . . . . . . . . . 48 10.48. The status Statement . . . . . . . . . . . . . . . . . . 53
10.50.2. The boolean and binary Types . . . . . . . . . . . . 48 10.49. The submodule Statement . . . . . . . . . . . . . . . . . 54
10.50.3. The bits Type . . . . . . . . . . . . . . . . . . . 49 10.50. The type Statement . . . . . . . . . . . . . . . . . . . 54
10.50.4. The enumeration and union Types . . . . . . . . . . 49 10.50.1. The empty Type . . . . . . . . . . . . . . . . . . . 55
10.50.5. The identityref Type . . . . . . . . . . . . . . . . 49 10.50.2. The boolean and binary Types . . . . . . . . . . . . 55
10.50.6. The instance-identifier Type . . . . . . . . . . . . 51 10.50.3. The bits Type . . . . . . . . . . . . . . . . . . . 55
10.50.7. The leafref Type . . . . . . . . . . . . . . . . . . 51 10.50.4. The enumeration and union Types . . . . . . . . . . 55
10.50.8. The numeric Types . . . . . . . . . . . . . . . . . 51 10.50.5. The identityref Type . . . . . . . . . . . . . . . . 55
10.50.9. The string Type . . . . . . . . . . . . . . . . . . 52 10.50.6. The instance-identifier Type . . . . . . . . . . . . 57
10.50.10. Derived Types . . . . . . . . . . . . . . . . . . . 53 10.50.7. The leafref Type . . . . . . . . . . . . . . . . . . 57
10.51. The typedef Statement . . . . . . . . . . . . . . . . . . 53 10.50.8. The numeric Types . . . . . . . . . . . . . . . . . 57
10.52. The unique Statement . . . . . . . . . . . . . . . . . . 54 10.50.9. The string Type . . . . . . . . . . . . . . . . . . 58
10.53. The units Statement . . . . . . . . . . . . . . . . . . . 54 10.50.10. Derived Types . . . . . . . . . . . . . . . . . . . 59
10.54. The uses Statement . . . . . . . . . . . . . . . . . . . 54 10.51. The typedef Statement . . . . . . . . . . . . . . . . . . 59
10.55. The value Statement . . . . . . . . . . . . . . . . . . . 54 10.52. The unique Statement . . . . . . . . . . . . . . . . . . 60
10.56. The when Statement . . . . . . . . . . . . . . . . . . . 54 10.53. The units Statement . . . . . . . . . . . . . . . . . . . 60
10.57. The yang-version Statement . . . . . . . . . . . . . . . 54 10.54. The uses Statement . . . . . . . . . . . . . . . . . . . 60
10.58. The yin-element Statement . . . . . . . . . . . . . . . . 54 10.55. The value Statement . . . . . . . . . . . . . . . . . . . 60
11. Mapping NETMOD-specific annotations to Schematron and DSRL . . 55 10.56. The when Statement . . . . . . . . . . . . . . . . . . . 60
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 56 10.57. The yang-version Statement . . . . . . . . . . . . . . . 60
13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 57 10.58. The yin-element Statement . . . . . . . . . . . . . . . . 61
Appendix A. RELAX NG Schema for NETMOD-specific Annotations . . . 59 11. Mapping NETMOD-specific annotations to DSDL Schema
A.1. XML Syntax . . . . . . . . . . . . . . . . . . . . . . . 59 Languages . . . . . . . . . . . . . . . . . . . . . . . . . . 62
A.2. Compact Syntax . . . . . . . . . . . . . . . . . . . . . 62 11.1. The @nma:config Annotation . . . . . . . . . . . . . . . 62
Appendix B. Schematron Library . . . . . . . . . . . . . . . . . 63 11.2. The @nma:default Annotation . . . . . . . . . . . . . . . 62
Appendix C. Translation of the DHCP Data Model . . . . . . . . . 64 11.3. The @nma:default-case Annotation . . . . . . . . . . . . 62
C.1. XML Syntax . . . . . . . . . . . . . . . . . . . . . . . 64 11.4. The <nma:error-app-tag> Annotation . . . . . . . . . . . 62
C.2. Compact Syntax . . . . . . . . . . . . . . . . . . . . . 68 11.5. The <nma:error-message> Annotation . . . . . . . . . . . 62
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 72 11.6. The <nma:instance-identifier> Annotation . . . . . . . . 62
11.7. The @nma:key Annotation . . . . . . . . . . . . . . . . . 63
11.8. The <nma:leafref> Annotation . . . . . . . . . . . . . . 63
11.9. The @nma:min-elements Annotation . . . . . . . . . . . . 64
11.10. The @nma:max-elements Annotation . . . . . . . . . . . . 64
11.11. The <nma:must> Annotation . . . . . . . . . . . . . . . . 64
11.12. The <nma:ordered-by> Annotation . . . . . . . . . . . . . 64
11.13. The <nma:status> Annotation . . . . . . . . . . . . . . . 64
11.14. The @nma:unique Annotation . . . . . . . . . . . . . . . 64
11.15. The @nma:when Annotation . . . . . . . . . . . . . . . . 65
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 66
13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Appendix A. RELAX NG Schema for NETMOD-specific Annotations . . . 69
A.1. XML Syntax . . . . . . . . . . . . . . . . . . . . . . . 69
A.2. Compact Syntax . . . . . . . . . . . . . . . . . . . . . 72
Appendix B. Schema-Independent Library . . . . . . . . . . . . . 73
B.1. XML Syntax . . . . . . . . . . . . . . . . . . . . . . . 73
B.2. Compact Syntax . . . . . . . . . . . . . . . . . . . . . 74
Appendix C. Mapping DHCP Data Model - A Complete Example . . . . 75
C.1. Input YANG Module . . . . . . . . . . . . . . . . . . . . 75
C.2. Conceptual Tree Schema . . . . . . . . . . . . . . . . . 78
C.2.1. XML Syntax . . . . . . . . . . . . . . . . . . . . . 78
C.2.2. Compact Syntax . . . . . . . . . . . . . . . . . . . 82
C.3. Final DSDL Schemas . . . . . . . . . . . . . . . . . . . 85
C.3.1. RELAX NG Schema for <get> Reply - XML Syntax . . . . 85
C.3.2. RELAX NG Schema for <get> Reply - Compact Syntax . . 89
C.4. Schematron Schema for <get> Reply . . . . . . . . . . . . 92
C.5. DSRL Schema for <get> Reply . . . . . . . . . . . . . . . 93
Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 94
D.1. Changes Between Versions -00 and -01 . . . . . . . . . . 94
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 95
1. Introduction 1. Introduction
The NETCONF Working Group has completed a base protocol used for The NETCONF Working Group has completed a base protocol used for
configuration management [1]. This base specification defines configuration management [1]. This base specification defines
protocol bindings and an XML container syntax for configuration and protocol bindings and an XML container syntax for configuration and
management operations, but does not include a modeling language or management operations, but does not include a modeling language or
accompanying rules for how to model configuration and status accompanying rules for how to model configuration and status
information (in XML syntax) carried by NETCONF. The IETF Operations information (in XML syntax) carried by NETCONF. The IETF Operations
Area has a long tradition of defining data for SNMP Management Area has a long tradition of defining data for SNMP Management
skipping to change at page 6, line 22 skipping to change at page 7, line 22
o Literal values are delimited by double quotes. o Literal values are delimited by double quotes.
o XML element names are delimited by "<" and ">" characters. o XML element names are delimited by "<" and ">" characters.
o Names of XML attributes are prefixed by the "@" character. o Names of XML attributes are prefixed by the "@" character.
XML elements names are always written with explicit namespace XML elements names are always written with explicit namespace
prefixes corresponding to the following XML vocabularies: prefixes corresponding to the following XML vocabularies:
a DTD compatibility annotations [8] "a" DTD compatibility annotations [8]
dc Dublin Core metadata elements "dc" Dublin Core metadata elements [9]
nc NETCONF protocol [1] "nc" NETCONF protocol [1]
nma NETMOD-specific schema annotations "en" NETCONF event notifications [10]
nmt Conceptual tree "nma" NETMOD-specific schema annotations (see Section 4.3)
dsrl Document Schema Renaming Language[9] "nmt" Conceptual tree (see Section 6.1)
rng RELAX NG[10] "dsrl" Document Semantics Renaming Language [11]
sch ISO Schematron[11] "rng" RELAX NG [12]
xsd W3C XML Schema[12] "sch" ISO Schematron [13]
"xsd" W3C XML Schema [14]
The following table shows the mapping of these prefixes to namespace The following table shows the mapping of these prefixes to namespace
URIs. URIs.
+--------+-----------------------------------------------------+ +--------+-----------------------------------------------------+
| Prefix | Namespace URI | | Prefix | Namespace URI |
+--------+-----------------------------------------------------+ +--------+-----------------------------------------------------+
| a | http://relaxng.org/ns/compatibility/annotations/1.0 | | a | http://relaxng.org/ns/compatibility/annotations/1.0 |
| | | | | |
| dc | http://purl.org/dc/terms | | dc | http://purl.org/dc/terms |
| | | | | |
| nc | urn:ietf:params:xml:ns:netconf:base:1.0 | | nc | urn:ietf:params:xml:ns:netconf:base:1.0 |
| | | | | |
| en | urn:ietf:params:xml:ns:netconf:notification:1.0 |
| | |
| nma | urn:ietf:params:xml:ns:netmod:dsdl-annotations:1 | | nma | urn:ietf:params:xml:ns:netmod:dsdl-annotations:1 |
| | | | | |
| nmt | urn:ietf:params:xml:ns:netmod:conceptual-tree:1 | | nmt | urn:ietf:params:xml:ns:netmod:conceptual-tree:1 |
| | | | | |
| dsrl | http://purl.oclc.org/dsdl/dsrl | | dsrl | http://purl.oclc.org/dsdl/dsrl |
| | | | | |
| rng | http://relaxng.org/ns/structure/1.0 | | rng | http://relaxng.org/ns/structure/1.0 |
| | | | | |
| sch | http://purl.oclc.org/dsdl/schematron | | sch | http://purl.oclc.org/dsdl/schematron |
| | | | | |
skipping to change at page 10, line 14 skipping to change at page 11, line 14
3. DSDL Schema Languages 3. DSDL Schema Languages
The mapping described in this document uses three of the DSDL schema The mapping described in this document uses three of the DSDL schema
languages, namely RELAX NG, Schematron and DSRL. languages, namely RELAX NG, Schematron and DSRL.
3.1. RELAX NG 3.1. RELAX NG
RELAX NG (pronounced "relaxing") is an XML schema language for RELAX NG (pronounced "relaxing") is an XML schema language for
grammar-based validation and Part 2 of the ISO/IEC DSDL family of grammar-based validation and Part 2 of the ISO/IEC DSDL family of
standards [10]. Like the W3C XML Schema language [12], it is able to 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 contents of XML documents.
However, unlike the DTD [13] and XSD schema languages, RELAX NG However, unlike the DTD [15] and XSD schema languages, RELAX NG
intentionally avoids any infoset augmentation such as defining intentionally avoids any infoset augmentation such as defining
default values. In the DSDL architecture, the particular task of default values. In the DSDL architecture, the particular task of
defining and applying default values is delegated to another schema defining and applying default values is delegated to another schema
language, DSRL (see Section 3.3). language, DSRL (see Section 3.3).
As its base datatype library, RELAX NG uses the W3C XML Schema As its base datatype library, RELAX NG uses the W3C XML Schema
Datatype Library [14], but unlike XSD, other datatype libraries may Datatype Library [16], but unlike XSD, other datatype libraries may
be used along with it or even replace it if necessary. be used along with it or even replace it if necessary.
RELAX NG is very liberal in accepting annotations from other RELAX NG is very liberal in accepting annotations from other
namespaces. With few exceptions, such annotations may be placed 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 element such as
<xsd:annotation> in XSD. <xsd:annotation> in XSD.
RELAX NG schema can be represented using two equivalent syntaxes: XML RELAX NG schema can be represented using two equivalent syntaxes: XML
and compact. The compact syntax is described in Annex C of the RELAX and compact. The compact syntax is described in Annex C of the RELAX
NG specification [15], which was added to the standard in 2006 NG specification [17], which was added to the standard in 2006
(Amendment 1). Automatic bidirectional conversions between the two (Amendment 1). Automatic bidirectional conversions between the two
syntaxes can be accomplished using for example Trang [22]. syntaxes can be accomplished using for example Trang [23].
For its terseness and readability, the compact syntax is often the For its terseness and readability, the compact syntax is often the
preferred form for publishing RELAX NG schemas whereas validators and preferred form for publishing RELAX NG schemas whereas validators and
other software tools generally require the XML syntax. However, the other software tools generally require the XML syntax. However, the
compact syntax has two drawbacks: compact syntax has two drawbacks:
o External annotations make the compact syntax schema considerably o External annotations make the compact syntax schema considerably
less readable. While in the XML syntax the annotating elements less readable. While in the XML syntax the annotating elements
and attributes are represented in a simple and uniform way (XML and attributes are represented in a simple and uniform way (XML
elements and attributes from foreign namespaces), the compact elements and attributes from foreign namespaces), the compact
syntax uses four different syntactic constructs: documentation, syntax uses four different syntactic constructs: documentation,
grammar, initial and following annotations. Therefore, the impact grammar, initial and following annotations. Therefore, the impact
on readability that results from adding annotations is often much on readability that results from adding annotations is often much
stronger for the compact syntax than for the XML syntax. stronger for the compact syntax than for the XML syntax.
o It is more difficult to programmatically generate compact syntax o In a program, it is more difficult to generate compact syntax than
than XML syntax. While a number of software libraries exist that XML syntax. While a number of software libraries exist that make
make it easy to create an XML tree in memory and serialize it, no it easy to create an XML tree in memory and serialize it, no such
such aid is available for compact syntax. 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 use
exclusively the XML syntax. Where appropriate, though, the schemas exclusively the XML syntax. Where appropriate, though, the schemas
resulting from the translation may be presented in the equivalent resulting from the translation may be presented in the equivalent
compact syntax. compact syntax.
RELAX NG elements are qualified with the namespace URI RELAX NG elements are qualified with the namespace URI
"http://relaxng.org/ns/structure/1.0". The namespace of the W3C "http://relaxng.org/ns/structure/1.0". The namespace of the W3C
Schema Datatype Library is Schema Datatype Library is
"http://www.w3.org/2001/XMLSchema-datatypes". "http://www.w3.org/2001/XMLSchema-datatypes".
3.2. Schematron 3.2. Schematron
Schematron is Part 3 of DSDL that reached the status of a full ISO/ Schematron is Part 3 of DSDL that reached the status of a full ISO/
IEC standard in 2006 [11]. In contrast to the traditional schema IEC standard in 2006 [13]. In contrast to the traditional schema
languages such as DTD, XSD or RELAX NG, which are based on the languages such as DTD, XSD or RELAX NG, which are based on the
concept of a formal grammar, Schematron utilizes a rule-based concept of a formal grammar, Schematron utilizes a rule-based
approach. Its rules may specify arbitrary conditions involving data approach. Its rules may specify arbitrary conditions involving data
from different parts of an XML document. Each rule consists of three from different parts of an XML document. Each rule consists of three
essential parts: essential parts:
o Context - an XPath expression that defines the set of locations o Context - an XPath expression that defines the set of locations
where the rule is to be applied, 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 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. is false or report condition is true.
The difference between the assert and report condition is that the The difference between the assert and report condition is that the
former is positive in that it states a condition that a valid former is positive in that it states a condition that a valid
document has to satisfy, whereas the latter specifies an error document has to satisfy, whereas the latter specifies an error
condition. The mapping described in this document uses exclusively condition.
the positive (assert) form.
Schematron draws most of its expressive power from XPath [16] and Schematron draws most of its expressive power from XPath [18] and
XSLT [17]. ISO Schematron allows for dynamic query language binding XSLT [19]. ISO Schematron allows for dynamic query language binding
so that the following XML query languages can be used: STX, XSLT 1.0, 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 XSLT 1.1, EXSLT, XSLT 2.0, XPath 1.0, XPath 2.0 and XQuery 1.0 (this
list may be extended in future). list may be extended in future).
The human-readable error messages are another feature that The human-readable error messages are another feature that
distinguishes Schematron from other schema languages such as RELAX NG distinguishes Schematron from other schema languages such as RELAX NG
or XSD. The messages may even contain XPath expressions that are or XSD. The messages may even contain XPath expressions that are
evaluated in the actual context and thus refer to existing XML evaluated in the actual context and thus refer to existing XML
document nodes and their content. document nodes and their content.
skipping to change at page 12, line 23 skipping to change at page 13, line 22
The rules defined by a Schematron schema may be divided into several The rules defined by a Schematron schema may be divided into several
subsets known as _phases_. Validations may then be set up to include subsets known as _phases_. Validations may then be set up to include
only selected phases. In the context of NETCONF data validation, only selected phases. In the context of NETCONF data validation,
this is useful for relaxing constraints that may not always apply. this is useful for relaxing constraints that may not always apply.
For example, the reference integrity may not be enforced for a For example, the reference integrity may not be enforced for a
candidate configuration. candidate configuration.
Schematron elements are qualified with namespace URI Schematron elements are qualified with namespace URI
"http://purl.oclc.org/dsdl/schematron". "http://purl.oclc.org/dsdl/schematron".
3.3. Document Schema Renaming Language (DSRL) 3.3. Document Semantics Renaming Language (DSRL)
DSRL (pronounced "disrule") is Part 8 of DSDL that reached the status DSRL (pronounced "disrule") is Part 8 of DSDL that reached the status
of a full ISO/IEC standard in 2008 [9]. Unlike RELAX NG and of a full ISO/IEC standard in 2008 [11]. Unlike RELAX NG and
Schematron, it is specifically designed to modify XML information set Schematron, it is specifically designed to modify XML information set
of the validated document. The primary application for DSRL is of the validated document. The primary application for DSRL is
renaming XML elements and attributes. DSRL can also define default renaming XML elements and attributes. DSRL can also define default
values for XML attributes and elements so that elements or attributes values for XML attributes and elements so that elements or attributes
with these default values are inserted if they are missing in the with these default values are inserted if they are missing in the
validated documents. The latter feature is used by the YANG-to-DSDL validated documents. The latter feature is used by the YANG-to-DSDL
mapping for representing YANG defaults for leaf nodes. mapping for representing YANG defaults for leaf nodes.
DSRL elements are qualified with namespace URI DSRL elements are qualified with namespace URI
"http://purl.oclc.org/dsdl/dsrl". "http://purl.oclc.org/dsdl/dsrl".
skipping to change at page 13, line 26 skipping to change at page 14, line 26
The third set are NETMOD-specific annotations conveying semantic The third set are NETMOD-specific annotations conveying semantic
constraints and other information that cannot be expressed natively constraints and other information that cannot be expressed natively
in RELAX NG. These annotations are only used in the first step of 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 the mapping, i.e., in the conceptual tree schema. In the second
mapping step, these annotations are converted to Schematron and DSRL mapping step, these annotations are converted to Schematron and DSRL
rules. rules.
4.1. Dublin Core Metadata Elements 4.1. Dublin Core Metadata Elements
Dublin Core [23] is a system of metadata elements that was originally Dublin Core [24] is a system of metadata elements that was originally
created for describing metadata of World Wide Web resources in order created for describing metadata of World Wide Web resources in order
to facilitate their automated lookup. Later it was accepted as a to facilitate their automated lookup. Later it was accepted as a
standard for describing metadata of arbitrary resources. This standard for describing metadata of arbitrary resources. This
specification uses the definition found in [18]. specification uses the definition found in [9].
Dublin Core elements are qualified with namespace URI Dublin Core elements are qualified with namespace URI
"http://purl.org/dc/terms". "http://purl.org/dc/terms".
4.2. RELAX NG DTD Compatibility Annotations 4.2. RELAX NG DTD Compatibility Annotations
DTD compatibility annotations are part of the RELAX NG DTD DTD compatibility annotations are part of the RELAX NG DTD
Compatibility specification [8]. The YANG-to-DSDL mapping uses only Compatibility specification [8]. The YANG-to-DSDL mapping uses only
the <a:documentation> annotation for representing YANG 'description' the <a:documentation> annotation for representing YANG 'description'
and 'reference' texts. and 'reference' texts.
Note that there is no intention to make the resulting schemas DTD- Note that there is no intention to make the resulting schemas DTD-
compatible, the main reason for using these annotations is technical: compatible, the main reason for using these annotations is technical:
it is well supported and adequately interpreted by several RELAX NG they are well supported and adequately interpreted by several RELAX
tools. NG tools.
DTD compatibility annotations are qualified with namespace URI DTD compatibility annotations are qualified with namespace URI
"http://relaxng.org/ns/compatibility/annotations/1.0". "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 NETMOD-specific annotations are XML elements and attributes qualified
with the namespace URI with the namespace URI
"urn:ietf:params:xml:ns:netmod:dsdl-annotations:1" that appear in "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1" that appear in
various locations in the conceptual tree schema. YANG statements are various locations in the conceptual tree schema. YANG statements are
skipping to change at page 15, line 34 skipping to change at page 16, line 34
| @nma:min-elements | 10.25 | | | @nma:min-elements | 10.25 | |
| | | | | | | |
| @nma:max-elements | 10.25 | | | @nma:max-elements | 10.25 | |
| | | | | | | |
| <nma:must> | 10.32 | 3 | | <nma:must> | 10.32 | 3 |
| | | | | | | |
| @nma:ordered-by | 10.35 | | | @nma:ordered-by | 10.35 | |
| | | | | | | |
| @nma:status | 10.48 | | | @nma:status | 10.48 | |
| | | | | | | |
| @nma:unique | 10.48 | | | @nma:unique | 10.52 | |
| | | | | | | |
| @nma:units | 10.48 | | | @nma:units | 10.53 | |
| | | | | | | |
| @nma:when | 10.56 | | | @nma:when | 10.56 | |
+---------------------------+---------+------+ +---------------------------+---------+------+
Table 2: NETMOD-specific annotations Table 2: NETMOD-specific annotations
Notes: Notes:
1. Appears only as subelement of <nma:must>. 1. Appears only as subelement of <nma:must>.
skipping to change at page 16, line 22 skipping to change at page 17, line 22
| YANG module(s) | | YANG module(s) |
+----------------+ +----------------+
| |
|T |T
| |
+---------------------------------+ +---------------------------------+
| DSDL schema for conceptual tree | | DSDL schema for conceptual tree |
+---------------------------------+ +---------------------------------+
/ | | \ +-------+ / | | \ +-------+
/ | | \ |library| / | | \ |library|
Td/ Ts| |Tc \ +-------+ Tg/ Tr| |Tn \ +-------+
/ | | \ / | | \
+---------+ +------+ +------+ +------+ +---------+ +-----+ +-------+ +------+
|datastore| |server| |client| | .... | |get reply| | rpc | | notif | | .... |
+---------+ +------+ +------+ +------+ +---------+ +-----+ +-------+ +------+
Figure 1: Structure of the mapping Figure 1: Structure of the mapping
The mapping procedure is divided into two steps: The mapping procedure is divided into two steps:
1. Transformation T in the first step maps one or more YANG modules 1. Transformation T in the first step maps one or more YANG modules
to a single RELAX NG schema for the conceptual tree (see to a single RELAX NG schema for the conceptual tree (see
Section 6.1). Constraints that cannot be expressed directly in Section 6.1). Constraints that cannot be expressed directly in
RELAX NG (list key definitions, 'must' statements etc.) and RELAX NG (list key definitions, 'must' statements etc.) and
various documentation texts are recorded in the schema as simple various documentation texts are recorded in the schema as simple
annotations belonging to special namespaces. annotations belonging to special namespaces.
2. In the second step, the conceptual tree schema may be transformed 2. In the second step, the conceptual tree schema is transformed in
in multiple ways to a coordinated set of DSDL schemas that can be multiple ways to a coordinated set of DSDL schemas that can be
used for validating a particular data object in a specific used for validating a particular data object in a specific
context. Figure 1 shows just three simplest possibilities as context. Figure 1 shows just three simplest possibilities as
examples. In the process, appropriate parts of the conceptual examples. In the process, appropriate parts of the conceptual
tree schema are extracted and specific annotations transformed to tree schema are extracted and specific annotations transformed to
equivalent, but usually more complex, Schematron patterns, <dsrl: equivalent, but usually more complex, Schematron patterns, <dsrl:
default-content> elements etc. default-content> elements etc.
3. As indicated in Figure 1, the second step of the mapping also 3. As indicated in Figure 1, the second step of the mapping also
uses a schema-independent library that contains mainly Schematron uses a schema-independent library that contains common schema
abstract patterns corresponding to common YANG concepts such as objects such as RELAX NG named pattern definitions.
the uniqueness constraint for list keys.
An implementation of the mapping algorithm accepts one or more valid An implementation of the mapping algorithm accepts one or more valid
YANG modules as its input. It is important to be able to process YANG modules as its input. It is important to be able to process
multiple YANG modules together since multiple modules may be multiple YANG modules together since multiple modules may be
negotiated for a NETCONF session and the contents of the negotiated for a NETCONF session and the contents of the
configuration datastore is then obtained as the union of data trees configuration datastore is then obtained as the union of data trees
specified by the individual modules, perhaps with multiple root specified by the individual modules, which may also lead to multiple
nodes. In addition, the input modules may be further coupled by the roots. In addition, the input modules may be further coupled by the
'augment' statement in which one module augments the data tree of 'augment' statement in which one module augments the data tree of
another module. another module.
It is also assumed that the algorithm has access, perhaps on demand, It is also assumed that the algorithm has access, perhaps on demand,
to all YANG modules that the module(s) imports (transitively). to all YANG modules that the module(s) imports (transitively).
The output of the first mapping step is an annotated RELAX NG schema The output of the first mapping step is an annotated RELAX NG schema
for the conceptual tree, which represents a virtual XML document for the conceptual tree, which represents a virtual XML document
containing, in its different subtrees, the entire datastore, all RPC containing, in its different subtrees, the entire datastore, all RPC
requests and replies, and notifications defined by the input YANG requests and replies, and notifications defined by the input YANG
skipping to change at page 17, line 38 skipping to change at page 18, line 36
and the common starting point for subsequent transformations that and the common starting point for subsequent transformations that
will typically produce validation schemas. The conceptual tree is will typically produce validation schemas. The conceptual tree is
further described in Section 6.1. further described in Section 6.1.
Other information contained in input YANG modules, such as semantic Other information contained in input YANG modules, such as semantic
constraints or default values, are recorded as annotations - XML constraints or default values, are recorded as annotations - XML
elements or attributes qualified with namespace URI elements or attributes qualified with namespace URI
"urn:ietf:params:xml:ns:netmod:dsdl-annotations:1". Metadata "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1". Metadata
describing the YANG modules are mapped to annotations utilizing describing the YANG modules are mapped to annotations utilizing
Dublin Core elements (Section 4.1). Finally, documentation strings Dublin Core elements (Section 4.1). Finally, documentation strings
are mapped to the <a:documentation> element belonging to the DTD are mapped to the <a:documentation> elements belonging to the DTD
compatibility vocabulary (Section 4.2). 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 is a coordinated set of three DSDL
schemas corresponding to a specific data object and context: schemas corresponding to a specific data object and context:
o RELAX NG schema describing the grammatical and datatype o RELAX NG schema describing the grammatical and datatype
constraints; constraints;
o Schematron schema expressing other constraints such as uniqueness o Schematron schema expressing other constraints such as uniqueness
of list keys or user-specified semantic rules; 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 values.
An implementation SHOULD allow for selecting a subset of schema
languages and annotation types to be used for output. For example, a
user might want to select pure RELAX NG without any annotations.
6. Design Considerations 6. Design Considerations
YANG modules could be mapped to DSDL schemas in a number of ways. YANG modules could be mapped to DSDL schemas in a number of ways.
The mapping procedure described in this document uses several The mapping procedure described in this document uses several
specific design decisions that are discussed in the following specific design decisions that are discussed in the following
subsections. subsections.
6.1. Conceptual Data Tree 6.1. Conceptual Data Tree
DSDL schemas generated from YANG modules using the procedure DSDL schemas generated from YANG modules using the procedure
described in this document are intended to be used for validating described in this document are intended to be used for validating
XML-encoded NETCONF data in various forms (full datastore and several XML-encoded NETCONF data in various forms (full datastore and several
types of PDUs): every YANG-based model represents the contents of a 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 full datastore but also implies an array of schemas for all types of
NETCONF PDUs. For a reasonably strict validation of a given data NETCONF PDUs. For a reasonably strict validation of a given data
object, the schemas have to be quite specific. To begin with, object, the schemas have to be quite specific. To begin with,
effective validation of NETCONF PDU content requires separation of effective validation of NETCONF PDU content requires separation of
client and server schemas. However, the decision about proper client and server schemas. While the decision about proper
structuring of all PDU-validating schemas is beyond the scope of this structuring of all PDU-validating schemas is beyond the scope of this
document. However, the mapping procedure described in this document document, the mapping procedure is designed to accommodate any
is designed to accommodate any foreseeable validation needs. foreseeable validation needs.
An essential part of the YANG-to-DSDL mapping procedure is An essential part of the YANG-to-DSDL mapping procedure is
nonetheless common to all validation approaches: the schemas for the nonetheless common to all validation approaches: the grammar and
datastore, RPCs and notifications expressed by one or more YANG datatype specifications for the datastore, RPCs and notifications
modules have to be translated to RELAX NG. In order to be able to expressed by one or more YANG modules have to be translated to RELAX
separate this common step, we introduce the notion of _conceptual NG. In order to be able to separate this common step, we introduce
data tree_: it is a virtual XML tree that contains full datastore, the notion of _conceptual data tree_: it is a virtual XML tree that
RPC requests with corresponding replies and notifications. The contains full datastore, RPC requests with corresponding replies and
schema for the conceptual tree - a single RELAX NG schema with notifications. The schema for the conceptual tree - a single RELAX
annotations - therefore has a quite similar logic as the input YANG NG schema with annotations - therefore has a quite similar logic as
module(s), the only major difference being the RELAX NG schema the input YANG module(s), the only major difference being the RELAX
language. NG schema language.
The conceptual data tree may be schematically represented as follows: The conceptual data tree may be schematically represented as follows:
<nmt:netmod-tree <nmt:netmod-tree
xmlns:nmt="urn:ietf:params:xml:ns:netmod:conceptual-tree:1"> xmlns:nmt="urn:ietf:params:xml:ns:netmod:conceptual-tree:1">
<nmt:main> <nmt:top>
... configuration and status data ... ... configuration and status data ...
</nmt:main> </nmt:top>
<nmt:rpc-methods> <nmt:rpc-methods>
<nmt:rpc-method name="..."> <nmt:rpc-method>
<nmt:input> <nmt:input>
<myrpc ...>
... ...
</myrpc>
</nmt:input> </nmt:input>
<nmt:output> <nmt:output>
... ...
</nmt:output> </nmt:output>
</nmt:rpc-method> </nmt:rpc-method>
... ...
</nmt:rpcs> </nmt:rpcs>
<nmt:notifications> <nmt:notifications>
<nmt:notification name="..."> <nmt:notification>
<mynotif>
... ...
</mynotif>
</nmt:notification> </nmt:notification>
... ...
</nmt:notifications> </nmt:notifications>
</nmt:netmod> </nmt:netmod>
The namespace URI "urn:ietf:params:xml:ns:netmod:tree:1" identifies a The namespace URI "urn:ietf:params:xml:ns:netmod:conceptual-tree:1"
simple vocabulary consisting of a few elements that encapsulate and identifies a simple vocabulary consisting of a few elements that
separate the various parts of the conceptual data tree. encapsulate and separate the various parts of the conceptual data
tree.
The conceptual tree schema is not intended for direct validation but The conceptual tree schema is not intended for direct validation but
rather serves as a well-defined starting point for subsequent rather serves as a well-defined starting point for subsequent
transformations that generate various validation schemas. Such transformations that generate various validation schemas. Such
transformations should be relatively simple, they will typically transformations should be relatively simple, they will typically
extract one or several subtrees from the conceptual tree schema, extract one or several subtrees from the conceptual tree schema,
modify them as necessary and add encapsulating elements such as those modify them as necessary and add encapsulating elements such as those
from the NETCONF RPC layer. from the NETCONF RPC layer.
Additional information contained in the source YANG module(s), such Additional information contained in the source YANG module(s), such
as semantic constraints and default values, is represented in the as semantic constraints and default values, is represented in the
form of _interim annotations_ that are included as foreign-namespace form of interim NETMOD-specific annotations that are included as
elements or attributes in the RELAX NG schema for the conceptual foreign-namespace elements or attributes in the RELAX NG schema for
tree. In the second phase of the mapping, the interim annotations the conceptual tree. In the second phase of the mapping, these
are extracted and translated to equivalent Schematron and DSRL rules. annotations are translated to equivalent Schematron and DSRL rules.
As a useful side effect, by introducing the conceptual data tree we As a useful side effect, by introducing the conceptual data tree we
are also able to resolve the difficulties stemming from the fact that are also able to resolve the difficulties arising from the fact that
a single configuration repository may consist of multiple parallel a single configuration repository may consist of multiple parallel
data hierarchies defined in one or more YANG modules, which cannot be data hierarchies defined in one or more YANG modules, which cannot be
mapped to a valid XML document. In the conceptual data tree, such mapped to a valid XML document. In the conceptual data tree, such
multiple hierarchies appear under the single <nmt:main> element. multiple hierarchies appear under the single <nmt:top> element.
6.2. Modularity 6.2. Modularity
Both YANG and RELAX NG offer means for modularity, i.e., for Both YANG and RELAX NG offer means for modularity, i.e., for
splitting the contents into separate modules (schemas) and combining splitting the contents into separate modules (schemas) and combining
or reusing them in various ways. However, the approaches taken by or reusing them in various ways. However, the approaches taken by
YANG and RELAX NG differ. Modularity in RELAX NG is suitable for ad 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 hoc combinations of a small number of schemas whereas YANG assumes a
large set of modules similar to SNMP MIBs. The following differences large set of modules similar to SNMP MIBs. The following differences
are important: are important:
skipping to change at page 23, line 5 skipping to change at page 22, line 38
YANG this is not an issue since its 'augment' and 'refine' statements YANG this is not an issue since its 'augment' and 'refine' statements
can delve, by using path expressions, into arbitrary depths of can delve, by using path expressions, into arbitrary depths of
existing structures. existing structures.
In general, it not feasible to map YANG extension mechanisms to those In general, it not feasible to map YANG extension mechanisms to those
of RELAX NG. For this reason, the mapping essentially keeps the of RELAX NG. For this reason, the mapping essentially keeps the
granularity of the original YANG data model: definitions of named granularity of the original YANG data model: definitions of named
patterns in the resulting RELAX NG schema usually have direct patterns in the resulting RELAX NG schema usually have direct
counterparts in YANG groupings and definitions of derived types. counterparts in YANG groupings and definitions of derived types.
7. Mapping Data Model Structure to the Conceptual Tree Schema 6.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.
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 <rng:
grammar> 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.
In contrast, there is no choice for Schematron and DSRL since both
schema languages require the target namespaces to be defined by
special means. In Schematron, <sch:ns> subelements of the root <sch:
schema> element serve this purpose, whereas in DSRL it is the
@targetNamespace attribute of the root <dsrl:maps> element.
7. Mapping YANG Data Models to the Conceptual Tree Schema
This section explains the main principles underlying the first step This section explains the main principles underlying the first step
of the mapping. Details about mapping individual YANG statements are of the mapping. Its result is an annotated RELAX NG schema of the
contained in Section 10. conceptual tree, which is described in Section 6.1.
As a special case, if the input YANG modules contain no data nodes
(this is typical e.g., for datatype library modules), an
implementation MAY entirely remove the schema of the (empty)
conceptual tree - the <rng:start> element with all its contents. The
output RELAX NG schema will then contain only named pattern
definitions translated from YANG groupings and typedefs.
Detailed specification of the mapping of individual YANG statements
is contained in Section 10.
7.1. Optional and Mandatory Content 7.1. Optional and Mandatory Content
In YANG, all leaf nodes are optional unless they contain substatement In YANG, the decision whether a given data node is mandatory or
optional is driven by the following rules, see [5], Section 3.1:
Leaf and choice nodes are mandatory if they contain the substatement
mandatory true; mandatory true;
or unless they are declared as list keys. In addition, leaf nodes are mandatory if they are declared as list
keys.
Lists or leaf-lists are optional unless they contain 'min-elements' Lists or leaf-lists are mandatory if they contain 'min-elements'
substatement with argument value greater than zero. substatement with argument value greater than zero.
A slightly more complicated situation arises for YANG containers. A slightly more complicated situation arises for YANG containers.
First, containers with the 'presence' substatement are always First, containers with the 'presence' substatement are always
optional since their presence or absence carries specific optional since their presence or absence carries specific
information. On the other hand, non-presence containers may be information. On the other hand, non-presence containers may be
omitted if they are empty. For the purposes of the YANG-to-DSDL omitted if they are empty. This leads to the following recursive
mapping, we declare a non-presence container as optional if and only rule:
if the following two conditions hold:
1. none of its descendant leaf nodes is mandatory or, if such a leaf
exists, it is enclosed in an intervening container with presence;
2. none of its descendant list or leaf-list nodes has 'min-elements' A container node is optional if its definition contains the
substatement with argument value greater than zero or, if such a 'presence' substatement or none of its child nodes is mandatory.
list or leaf-list exists, it is enclosed in an intervening
container with presence.
In RELAX NG, all elements that are optional must be explicitly In RELAX NG, all elements that are optional must be explicitly
wrapped in the <rng:optional> element. The mapping algorithm thus wrapped in the <rng:optional> element. The mapping algorithm thus
uses the above rules to determine whether a YANG node is optional and uses the above rules to determine whether a YANG node is optional and
if so, insert the <rng:optional> element in the RELAX NG schema. if so, insert the <rng:optional> element in the RELAX NG schema.
7.2. Mapping YANG Groupings and Typedefs 7.2. Mapping YANG Groupings and Typedefs
YANG groupings and typedefs are generally mapped to RELAX NG named YANG groupings and typedefs are generally mapped to RELAX NG named
patterns. There are, however, several caveats that the mapping has patterns. There are, however, several caveats that the mapping has
skipping to change at page 24, line 23 skipping to change at page 25, line 34
o Names of groupings and typedefs appearing at the _top level_ of o Names of groupings and typedefs appearing at the _top level_ of
the YANG module hierarchy are prefixed with the module name and the YANG module hierarchy are prefixed with the module name and
two underscore characters ("__"). two underscore characters ("__").
o Names of other groupings and typedefs, i.e., those that do not 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 appear at the top level of a YANG module, are prefixed with the
module name, double underscore, and then the names of all ancestor module name, double underscore, and then the names of all ancestor
data nodes separated by double underscore. 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.
For example, consider the following YANG module which imports the For example, consider the following YANG module which imports the
standard module "inet-types" [19]: standard module "inet-types" [20]:
module example1 { module example1 {
namespace "http://example.com/ns/example1"; namespace "http://example.com/ns/example1";
prefix "ex1"; prefix "ex1";
import "inet-types" { import "inet-types" {
prefix "inet"; prefix "inet";
} }
typedef vowels { typedef vowels {
type string { type string {
pattern "[aeiouy]*"; pattern "[aeiouy]*";
skipping to change at page 26, line 11 skipping to change at page 27, line 11
The resulting RELAX NG schema will then contain the following named The resulting RELAX NG schema will then contain the following named
pattern definitions (long regular expression patterns for IPv4 and pattern definitions (long regular expression patterns for IPv4 and
IPv6 addresses are not shown): IPv6 addresses are not shown):
<rng:define name="example1__vowels"> <rng:define name="example1__vowels">
<rng:data type="string"> <rng:data type="string">
<rng:param name="pattern">[aeiouy]*</param> <rng:param name="pattern">[aeiouy]*</param>
</rng:data> </rng:data>
</rng:define> </rng:define>
<rng:define name="example1__grp1"> <rng:define name="_example1__grp1">
<rng:optional> <rng:optional>
<rng:element name="t:void"> <rng:element name="t:void">
<rng:empty/> <rng:empty/>
</rng:element> </rng:element>
</rng:optional> </rng:optional>
</rng:define> </rng:define>
<rng:define name="example1__cont__grp2"> <rng:define name="_example1__cont__grp2">
<rng:optional> <rng:optional>
<rng:element name="t:address"> <rng:element name="t:address">
<rng:ref name="inet-types__ip-address"/> <rng:ref name="inet-types__ip-address"/>
</rng:element> </rng:element>
</rng:optional> </rng:optional>
</rng:define> </rng:define>
<rng:define name="inet-types__ip-address"> <rng:define name="inet-types__ip-address">
<rng:choice> <rng:choice>
<rng:ref name="inet-types__ipv4-address"/> <rng:ref name="inet-types__ipv4-address"/>
<rng:ref name="inet-types__ipv6-address"/> <rng:ref name="inet-types__ipv6-address"/>
</rng:choice> </rng:choice>
</rng:define> </rng:define>
<rng:define name="inet-types__ipv4-address"> <rng:define name="inet-types__ipv4-address">
<rng:data type="string"> <rng:data type="string">
<rng:param name="pattern">... removed ...</param> <rng:param name="pattern">... regex pattern ...</param>
</rng:data> </rng:data>
</rng:define> </rng:define>
<rng:define name="inet-types__ipv6-address"> <rng:define name="inet-types__ipv6-address">
<rng:data type="string"> <rng:data type="string">
<rng:param name="pattern">... removed ...</param> <rng:param name="pattern">... regex pattern ...</param>
</rng:data> </rng:data>
</rng:define> </rng:define>
7.2.1. YANG Refinements and Augments 7.2.1. YANG Refinements and Augments
YANG groupings represent a similar concept as named pattern YANG groupings represent a similar concept as named pattern
definitions in RELAX NG and both languages also offer mechanisms for definitions in RELAX NG and both languages also offer mechanisms for
their subsequent modification. However, in RELAX NG the definitions their subsequent modification. However, in RELAX NG the definitions
themselves are modified whereas YANG allows for modifying themselves are modified whereas YANG allows for modifying
_expansions_ of groupings. Specifically, YANG provides two _expansions_ of groupings. Specifically, YANG provides two
skipping to change at page 28, line 28 skipping to change at page 29, line 28
leaf hoja { leaf hoja {
type string; type string;
} }
} }
uses leaves; uses leaves;
} }
The resulting conceptual tree schema contains three named pattern The resulting conceptual tree schema contains three named pattern
definitions corresponding to the three groupings, namely definitions corresponding to the three groupings, namely
<rng:define name="example2__leaves"> <rng:define name="_example2__leaves">
<rng:ref name="example2__fr"/> <rng:ref name="_example2__fr"/>
<rng:ref name="example2__es"/> <rng:ref name="_example2__es"/>
</rng:define> </rng:define>
<rng:define name="example2__fr"> <rng:define name="_example2__fr">
<rng:optional> <rng:optional>
<rng:element name="feuille"> <rng:element name="feuille">
<rng:data type="string"/> <rng:data type="string"/>
</rng:element> </rng:element>
</rng:optional> </rng:optional>
</rng:define> </rng:define>
<rng:define name="example2__es"> <rng:define name="_example2__es">
<rng:optional> <rng:optional>
<rng:element name="hoja"> <rng:element name="hoja">
<rng:data type="string"/> <rng:data type="string"/>
</rng:element> </rng:element>
</rng:optional> </rng:optional>
</rng:define> </rng:define>
and the configuration data part of the conceptual tree schema will be and the configuration data part of the conceptual tree schema is a
a single named pattern reference: single named pattern reference:
<rng:ref name="example2__leaves"/>
Now assume that the "leave" expansion is refined: <rng:ref name="_example2__leaves"/>
Now assume that the "uses leaves" statement is refined:
uses leaves { uses leaves {
refine "hoja" { refine "hoja" {
default "alamo"; default "alamo";
} }
} }
The resulting conceptual tree schema now contains just one named The resulting conceptual tree schema now contains just one named
pattern definition - "example__fr". The other two groupings "leaves" pattern definition - "_example__fr". The other two groupings
and "es" have to be expanded because they both lie on the "leaves" and "es" have to be expanded because they both lie on the
"modification path", i.e., contain the leaf "hoja" that is being "modification path", i.e., contain the leaf "hoja" that is being
refined. The configuration data part of the conceptual tree now refined. The configuration data part of the conceptual tree now
looks like this: looks like this:
<rng:ref name="example2__fr"/> <rng:ref name="_example2__fr"/>
<rng:optional> <rng:optional>
<rng:element name="hoja" nma:default="alamo"> <rng:element name="hoja" nma:default="alamo">
<rng:data type="string"/> <rng:data type="string"/>
</rng:element> </rng:element>
</rng:optional> </rng:optional>
7.2.2. Type derivation chains 7.2.2. Type derivation chains
RELAX NG has no equivalent of the type derivation mechanism in YANG, 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 where a base built-in type may be modified (in multiple steps) by
skipping to change at page 29, line 44 skipping to change at page 30, line 41
with restrictions, the derived types MUST be "unwound" all the way with restrictions, the derived types MUST be "unwound" all the way
back to the base built-in type. At the same time, all restrictions back to the base built-in type. At the same time, all restrictions
found along the type derivation chain MUST be combined and their found along the type derivation chain MUST be combined and their
intersection used as facets restricting the corresponding type in intersection used as facets restricting the corresponding type in
RELAX NG. RELAX NG.
When a derived YANG type is used without restrictions, the 'type' When a derived YANG type is used without restrictions, the 'type'
statement is mapped simply to the <rng:ref> element, i.e., a named statement is mapped simply to the <rng:ref> element, i.e., a named
pattern reference. However, if restrictions are specified as pattern reference. However, if restrictions are specified as
substatements of the 'type' statement, the type MUST be expanded at substatements of the 'type' statement, the type MUST be expanded at
that point so that only the built-in type appears in the output that point so that only the base built-in type appears in the output
schema, restricted with facets that again correspond to the schema, restricted with facets that again correspond to the
combination of all restrictions found along the type derivation chain combination of all restrictions found along the type derivation chain
and also in the 'type' statement. and also in the 'type' statement.
EXAMPLE. Consider this YANG module: EXAMPLE. Consider this YANG module:
module example3 { module example3 {
namespace "http://example.com/ns/example3"; namespace "http://example.com/ns/example3";
prefix ex3; prefix ex3;
typedef dozen { typedef dozen {
skipping to change at page 30, line 48 skipping to change at page 31, line 48
<rng:element name="month"> <rng:element name="month">
<rng:data type="unsignedByte"> <rng:data type="unsignedByte">
<rng:param name="minInclusive">7</param> <rng:param name="minInclusive">7</param>
<rng:param name="maxInclusive">12</param> <rng:param name="maxInclusive">12</param>
</rng:data> </rng:data>
</rng:element> </rng:element>
7.3. Translation of XPath Expressions 7.3. Translation of XPath Expressions
YANG uses full XPath 1.0 syntax [16] for the arguments of 'must' and YANG uses full XPath 1.0 syntax [18] for the arguments of 'must' and
'when' statements and a subset thereof in several other statements. 'when' statements and a subset thereof in several other statements.
However, since the names of data nodes defined by YANG modules are However, since the name of a data node always belongs to the
always namespace qualified, YANG adopted a simplification similar to namespace of the YANG Module where the data node is defined, YANG
the concept of _default namespace_ in XPath 2.0: node names needn't adopted a simplification similar to the concept of _default
carry a namespace prefix inside the module where they are defined, in namespace_ in XPath 2.0: node names needn't carry a namespace prefix
which case the module's namespace is assumed. 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 If an XPath expression is carried over to a NETMOD-specific
annotation in the first mapping step, it MUST be translated into a annotation in the first mapping step, it MUST be translated into a
fully conformant XPath 1.0 expression that also reflects the fully conformant XPath 1.0 expression that also reflects the
hierarchy of the conceptual data tree: hierarchy of the conceptual data tree:
1. Each unprefixed node name MUST be prepended with the local 1. Each unprefixed node name MUST be prepended with the local
module's namespace prefix declared by the 'prefix' statement. module's namespace prefix declared by the 'prefix' statement.
2. Absolute XPath expressions, i.e., those starting with a slash, 2. Absolute XPath expressions, i.e., those starting with a slash,
MUST be prepended with appropriate path in the conceptual tree, MUST be prepended with appropriate path in the conceptual tree,
according to the YANG specification of context for XPath according to the YANG specification of context for XPath
expressions, see [16], sections 7.5.3 and 7.19.5. expressions, see [18], sections 7.5.3 and 7.19.5.
Translation rule 2 means that absolute XPath expressions appearing in Translation rule 2 means for example that absolute XPath expressions
the main configuration data tree always start with "nmt:netmod-tree/ appearing in the main configuration data tree always start with "nmt:
nmt:main/", those appearing in "my-notif" notification always start netmod-tree/nmt:top/", those appearing in a notification always start
with "nmt:netmod-tree/nmt:notifications/ with "nmt:netmod-tree/nmt:notifications/nmt:notification/", etc.
nmt:notification[@name='my-notif']/", etc.
EXAMPLE. YANG XPath expression "/dhcp/max-lease-time" appearing in EXAMPLE. YANG XPath expression "/dhcp/max-lease-time" appearing in
the main configuration data will be translated to "nmt:netmod-tree/ the main configuration data will be translated to "nmt:netmod-tree/
nmt:main/dhcp:dhcp/dhcp:max-lease-time". nmt:top/dhcp:dhcp/dhcp:max-lease-time".
[Editor's note: We may want to introduce "$root" variable that always [Editor's note: We may want to introduce "$root" variable that always
contains the appropriate partial path in conceptual tree. The contains the appropriate partial path in conceptual tree. The
translated XPath in the example would then become "$root/dhcp:dhcp/ translated XPath in the example would then become "$root/dhcp:dhcp/
dhcp:max-lease-time".] 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.
7.4. YANG Language Extensions 7.4. YANG Language Extensions
YANG allows for extending its own language in-line by adding new YANG allows for extending its own language in-line by adding new
statements with keywords from special namespaces. Such extensions statements with keywords from special namespaces. Such extensions
first have to be declared using the 'extension' statement and then first have to be declared using the 'extension' statement and then
can be used as the native statements, only with a namespace prefix can be used as the native statements, only with a namespace prefix
qualifying the extension keyword. RELAX NG has a similar extension qualifying the extension keyword. RELAX NG has a similar extension
mechanism - XML elements and attributes with names from foreign mechanism - XML elements and attributes with names from foreign
namespaces may be inserted at almost every place of a RELAX NG namespaces may be inserted at almost every place of a RELAX NG
schema. schema.
skipping to change at page 32, line 29 skipping to change at page 34, line 5
If this extension is honored by the mapping, it will be mapped to If this extension is honored by the mapping, it will be mapped to
<rng:element name="folio"> <rng:element name="folio">
<acme:documentation-flag number="42"/> <acme:documentation-flag number="42"/>
<rng:data type="string"/> <rng:data type="string"/>
</rng:element> </rng:element>
Note that the 'extension' statement itself is not mapped in any way. Note that the 'extension' statement itself is not mapped in any way.
7.5. RPC Signatures and Notifications 8. Mapping Conceptual Tree Schema to DSDL
In the conceptual tree schema, YANG definitions of RPC methods are As explained in Section 5, the second step of the YANG-to-DSDL
mapped to the subtree under "/nmt:netmod-tree/nmt:rpc-methods". Each mapping takes the conceptual tree schema and transforms it to various
RPC method corresponds to one subelement of <nmt:rpc-methods>, namely DSDL schemas ready for validation. As an input parameter, this step
<nmt:rpc-method name="..."> where the value of the @name attribute is gets in the simplest case a specification of the NETCONF XML document
set to the name of the method. In turn, the <nmt:rpc-method> element type (or combination of multiple types) that is to be validated.
has two subelements, <nmt:input> and <nmt:output> (both are optional) These document type can be for example reply to <nc:get> or <nc:get-
that contain input and input parameters of the given RPC method, config>, RPC requests or replies and notification. Other parameters
respectively. further describing the context may also be provided, such as the list
of active capabilities, features etc.
Analogically, the content of each notification is mapped inside the In general, the second mapping step has to accomplish the following
element <nmt:notification name="...">, which is a subelement of three tasks:
"/nmt:netmod-tree/nmt:notifications".
8. Mapping Conceptual Tree Schema to DSDL 1. Extract the part(s) of the conceptual tree schema that are
appropriate or the requested document type. For example, if a
<get> reply is to be validated, the subtree under <nmt:top> must
be selected.
[Editor's note: This section is not finished yet. We need to write a 2. The schema must be accommodated to the specific encapsulating XML
mapping specification for each of the NETMOD-specific annotations.] elements mandated by the RPC layer. These are, for example, <nc:
rpc> and <nc:data> elements in the case of a datastore or <en:
notification> for a notification.
8.1. Mapping Semantic Constraints to Schematron 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.
TBD These three tasks are together much simpler than the first mapping
step. Presumably, they can be effectively realized using XSL
transformations [19].
8.1.1. Library of Schema-independent Schematron Patterns The following subsections describe the details of the second mapping
step for the individual DSDL schema languages. Section 11 then
contains a detailed specification for the mapping of all NETMOD-
specific annotations.
This section outlines the schema-independent library of Schematron 8.1. Generating RELAX NG Schemas for Various Document Types
patterns.
TBD With one minor exception, obtaining a validating RELAX NG schema from
the conceptual tree schema really means only taking appropriate parts
from the conceptual tree schema and assembling them in a new RELAX NG
grammar, perhaps after removing all unwanted annotations. Depending
on the XML document type that is the target for validation (<get>/
<get-config> reply, RPC or notification) a corresponding top-level
part of the grammar MUST be added as described in the following
subsections.
8.2. Mapping Default Values to DSRL Schemas for multiple alternative target document types can also be
easily generated by enclosing the definitions for requested type in
<rng:choice> element.
TBD 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.
9. NETCONF Content Validation The minor exception mentioned above is the annotation @nma:config,
which must be observed if the target document type is <get-config>
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.
[Editor's note: This section is not finished yet. We have to figure 8.1.1. Reply to <get> or <get-config>
out what are the NETCONF objects we want to validate, and also the
validation contexts and modes. The concept of validation phases
outlined below is just one part of the problem. However, these
questions are not DSDL-specific and should be addressed by the WG.
One issue is DSDL-specific though: we have to find a way for
validating compound documents using both NETCONF and NETMOD schemas.
NVDL is a good candidate.]
9.1. Validation Phases For a reply to <get> or <get-config>, the mapping must take the part
of the conceptual tree schema under the definition of <nmt:top> and
insert it in the following grammar:
Validation of a configuration datastore or NETCONF PDUs may occur in <rng:grammar ... namespaces etc. ...>
different logical phases, adding more tests with each phase. We use <rng:include href="relaxng-lib.rng"/>
three levels or phases for validating an instance document. There is <rng:start>
a level of validation which is appropriate even for loose XML <rng:element name="nc:rpc-reply">
document fragments which still maintain their hierarchy (_fragment <rng:ref name="message-id-attribute"/>
phase_), another level of validation is appropriate for a cohesive <rng:element name="nc:data">
XML document which may however not be able to validate relational ... patterns defining contents of "nmt:top" subtree ...
integrity checks against some operational state (_standard phase_), </rng:element>
and finally there is validation which cover everything including all </rng:element>
relational integrity checks (_full validation phase_). For example, </rng:start>
in NETCONF an edit-config operation can cause the replacement a small ... named pattern definitions ...
fragment of XML. A candidate configuration may be waiting for </rng:grammar>
application but can't check the readiness of a piece of hardware that
the configuration refers to.
From the NETCONF perspective, these three phases can be considered to The definition for the named pattern "message-id-attribute" is found
have the following scope: in the library file "relaxng-lib.rng" which is included on the second
line (see Appendix B).
1. the fragment phase: This can be run against individual NETCONF Definitions of other named patterns MUST be copied from the
operations. conceptual tree schema without any changes to the resulting grammar.
However, an implementation MAY choose to copy only those definitions
that are really used in the particular output grammar.
2. the standard phase: This can be run against the candidate 8.1.2. Remote Procedure Calls
configuration, but won't always pass.
3. the full validation phase: This can be run against a running For an RPC method named "myrpc" and defined in a YANG module with
configuration. prefix "yam", the corresponding schema subtree is identified by the
definition of <nmt:rpc-method> element whose <nmt:input> subelement
has <yam:myrpc> as the only child.
During the Fragment phase validation it is verified that the content The mapping must also take into account whether the target document
is well-formed and appropriate to the operation. type in an RPC request or reply. For "yam:myrpc" request, the
resulting grammar looks as follows:
During Standard phase validation (all rules except for leafref <rng:grammar ... namespaces etc. ...>
checking): <rng:include href="relaxng-lib.rng"/>
<rng:start>
<rng:element name="nc:rpc">
<rng:ref name="message-id-attribute"/>
<rng:element name="yam:myrpc">
... patterns defining contents of subtree ...
... "nmt:rpc-method/nmt:input/yam:myrpc" ...
</rng:element>
</rng:element>
</rng:start>
... named pattern definitions ...
</rng:grammar>
o Verify that mandatory nodes are present. For "myrpc" reply, the output grammar is
o Check the uniqueness for unique and key annotations. <rng:grammar ... namespaces etc. ...>
<rng:include href="relaxng-lib.rng"/>
<rng:start>
<rng:element name="nc:rpc-reply">
<rng:ref name="message-id-attribute"/>
... patterns defining contents of corresponding ...
... "nmt:rpc-method/nmt:output" subtree ...
</rng:element>
</rng:start>
... named pattern definitions ...
</rng:grammar>
o Print a warning if any manual validation rules are present. In both cases, exact copies of named pattern definitions from the
conceptual tree schema MUST be inserted, but an implementation MAY
choose to include only those used for the given RPC.
During Full phase validation: add leafref checks. 8.1.3. Notifications
The mechanism how the phase specification is passed to the Schematron For a notification named "mynotif" and defined in a YANG module with
validator is outside the scope of this document. For example, it can prefix "yam", the corresponding schema subtree is identified by the
be accomplished via command line parameters. definition of <nmt:notification> element that has the single child
<yam:mynotif>.
<sch:phase id="fragment"> The resulting grammar looks as follows:
<sch:active pattern="lease-time"/>
<sch:active pattern="nonconfig"/> <rng:grammar ... namespaces etc. ...>
</sch:phase> <rng:include href="relaxng-lib.rng"/>
<sch:phase id="std"> <rng:start>
<sch:active pattern="lease-time"/> <rng:element name="en:notification">
<sch:active pattern="nonconfig"/> <rng:ref name="eventTime-element"/>
<sch:active pattern="key"/> <rng:element name="yam:myrpc">
</sch:phase> <!-- patterns defining contents of
"nmt:rpc-notification/yam:mynotif" subtree -->
</rng:element>
</rng:element>
</rng:start>
<!-- named pattern definitions -->
</rng:grammar>
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.
8.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: <sch:schema>,
<sch:pattern>, <sch:rule> and <sch:assert> or <sch:report>.
In a Schematron schema generated by the second mapping step, the
basic unit of organization is a _rule_ represented by the <sch:rule>
element. Every rule corresponds to exactly one element definition in
the conceptual tree schema. The mandatory @context attribute of
<sch:rule> is set to the absolute path of the corresponding element
in the data tree.
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:instance-identifier>,
@nma:key, <nma:leafref>, @nma:min-elements, @nma:max-elements, <nma:
must>, @nma:unique and <nma:when>.
Schematron rules may be further grouped into _patterns_ represented
by the <sch:pattern> element. The mapping uses patterns only for
discriminating between subsets of rules that belong to different
validation phases, see Section 8.2.1. Therefore, the <sch:schema>
always has exactly two <sch:pattern> children: one named "standard"
contains rules for all annotations except <nma:instance-identifier>
and <nma:leafref>, 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 <rng:define> 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.
EXAMPLE. Consider this element definition annotated with <nma:must>:
<rng:element name="dhcp:default-lease-time">
<rng:data type="unsignedInt"/>
<nma:must assert=". &lt;= ../dhcp:max-lease-time">
<nma:error-message>
The default-lease-time must be less than max-lease-time
</nma:error-message>
</nma:must>
</rng:element>
If this element definition appears outside any named pattern and as a
child of <dhcp:dhcp> (as it does in the DHCP schema, see
Appendix C.2), it is mapped to the following Schematron rule:
<sch:rule context="/nc:rpc-reply/nc:data/dhcp:dhcp/
dhcp:default-lease-time">
<sch:assert test=". &lt;= ../dhcp:max-lease-time">
The default-lease-time must be less than max-lease-time
</sch:assert>
</sch:rule>
Now assume the element definition is inside a named pattern
definition, say
<rng:define name="_dhcp__default-lease-time">
<rng:element name="dhcp:default-lease-time">
... same content ...
</rng:element>
</rng:define>
In this case it is mapped to an abstract rule:
<sch:rule id="id31415926" abstract="true">
<sch:assert test=". &lt;= ../dhcp:max-lease-time">
The default-lease-time must be less than max-lease-time
</sch:assert>
</sch:rule>
Any use of the named pattern definition via <rng:ref
name="_dhcp__default-lease-time"/> then results in a new rule
extending the abstract one, for example
<sch:rule context="/nc:rpc-reply/nc:data/dhcp:dhcp/
dhcp:default-lease-time">
<sch:extends rule="id31415926"/>
</sch:rule>
Care must be taken that the value of the @context attribute in
general consists of two parts in this case: its beginning is
determined by the location of the <rng:ref> element in the main
schema tree and the rest of the path comes from the relative position
of the annotated element definition inside the named pattern. The
situation becomes even more complex when the mapping has to deal with
chained definitions of named patterns (<rng:ref> inside <rng:
define>). The @context value then must be recursively glued together
from multiple parts.
The mapping from the conceptual tree schema to Schematron proceeds in
the following steps:
1. First, the active subtree(s) of the conceptual tree schema must
be selected depending on the requested target document type.
This procedure is identical to the RELAX NG case, including the
handling of @nma:config if the target document type is <get-
config> reply.
2. Namespaces of all input YANG modules, together with the
namespaces of base NETCONF ("nc" prefix) or notifications ("en"
prefix) MUST be declared using the <sch:ns> element, for example
<sch:ns uri="http://example.com/ns/dhcp" prefix="dhcp"/>
3. Validation phases are defined (see Section 8.2.1) and their
constituting patterns "standard" and "ref-integrity" created.
4. For either validation phase, the input conceptual tree schema is
scanned and element definitions with annotations relevant for the
given phase are selected and a <sch:rule> is created for each of
them. The rule is abstract if the element definition appears
inside a named pattern, see above.
5. All annotations attached to the given element definition are then
mapped using the mapping rules specified in Section 11. The
resulting <sch:assert> or <sch:report> elements are the installed
as children of the <sch:rule> element.
8.2.1. Validation Phases
In certain situations it is useful to validate XML instance documents
without enforcing the referential integrity constraints represented
by the <nma:leafref> and <nma:instance-identifier> annotations. For
example, a candidate configuration refering to configuration
parameters or state data of certain hardware will not pass full
validation before the hardware is installed. To handle this, the
Schematron mapping introduces two _validation phases_:
o Validation phase "full", which is the default, checks all semantic
constraints.
o Validation phase "noref" is the same as "full" except it doesn't
check referential integrity constraints.
A parameter identifying the validation phase to use has to be passed
to the Schematron processor or otherwise both patterns are used by
default. How this is exactly done depends on the concrete Schematron
processor and is outside the scope of this document.
The validation phases are defined in Schematron by listing the
patterns that are to be applied for each phase. Therefore, the
mapping puts the rules for referential integrity checking to a
special <sch:pattern> with @id attribute set to "ref-integrity". The
rules mapped from the remaining semantic constraints are put to
another <sch:pattern> with @id attributes set to "standard".
With validation phases, the resulting Schematron schema has the
following overall structure:
<sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron">
<sch:ns uri="..." prefix="..."/>
... more NS declarations ...
<sch:phase id="full"> <sch:phase id="full">
<sch:active pattern="lease-time"/> <sch:active pattern="standard"/>
<sch:active pattern="nonconfig"/> <sch:active pattern="ref-integrity"/>
<sch:active pattern="key"/>
<sch:active pattern="keyref"/>
</sch:phase> </sch:phase>
<sch:phase id="noref">
<sch:active pattern="standard"/>
</sch:phase>
<sch:pattern id="standard">
... all rules except ref. integrity checks ...
</sch:pattern>
<sch:pattern id="ref-integrity">
... rules for ref. integrity checks ...
</sch:pattern>
</sch:schema>
8.3. Mapping Default Values to DSRL
TBD
9. NETCONF Content Validation
This section describes the procedures for validating XML instance
documents corresponding to various NETCONF PDUs given the set of DSDL
schemas generated for the particular document type.
[Editor's note: This section is incomplete. We have to figure out
what are the NETCONF instances we want to validate, and also the
validation contexts and modes. However, these questions are not
DSDL-specific and should be addressed by the WG.]
The validation proceeds in the following steps, see also 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 and default cases have to
be applied. It is important to apply the defaults before the
next validation step because [5] states that the data tree
against which XPath expressions are evaluated already has all
defaults filled-in. Note that this step modifies the information
set of the input XML document.
3. The semantic constraints are checked using the Schematron schema.
+----------+ +----------+
| | | XML |
| XML | | document |
| document |-----------o----------->| with |
| | ^ | defaults |
| | | | |
+----------+ | +----------+
^ | filling-in ^
| grammar, | defaults | semantic
| datatypes | | constraints
| | |
+----------+ +--------+ +------------+
| RELAX NG | | DSRL | | Schematron |
| schema | | schema | | schema |
+----------+ +--------+ +------------+
Figure 2: Outline of the validation procedure
10. Mapping YANG Statements to Annotated RELAX NG 10. Mapping YANG Statements to Annotated RELAX NG
Each subsection in this section is devoted to one YANG statement and Each subsection in this section is devoted to one YANG statement and
describes how the statement is mapped to the annotated RELAX NG provides the specification how the statement is mapped to the
schema of the conceptual tree. This is the first step of the mapping annotated RELAX NG schema of the conceptual tree. This is the first
procedure, see Section 5. The subsections are sorted alphabetically step of the mapping procedure, see Section 5. The subsections are
by the statement keyword. sorted alphabetically by the statement keyword.
Each YANG statement is mapped to an XML fragment, typically a single Each YANG statement is mapped to an XML fragment, typically a single
element or attribute but it may also be a larger structure. The element or attribute but it may also be a larger structure. The
mapping algorithm is inherently recursive, which means that after mapping algorithm is inherently recursive, which means that after
finishing a statement the mapping continues with its substatements, finishing a statement the mapping continues with its substatements,
if there are any, and a certain element of the resulting fragment if there are any, and a certain element of the resulting fragment
becomes the parent of other fragments resulting from the mapping of becomes the parent of other fragments resulting from the mapping of
substatements. We use the following notation: substatements. We use the following notation:
o The argument of the statement being mapped is denoted by ARGUMENT. o The argument of the statement being mapped is denoted by ARGUMENT.
skipping to change at page 36, line 39 skipping to change at page 43, line 39
becomes the value of its @name attribute. The content of <rng: becomes the value of its @name attribute. The content of <rng:
element> is element> is
<rng:ref name="__anyxml__"/> <rng:ref name="__anyxml__"/>
Substatements of the 'anyxml' statement are mapped to additional Substatements of the 'anyxml' statement are mapped to additional
children of the RELAX NG element definition. children of the RELAX NG element definition.
If the 'anyxml' statement occurs in any of the input YANG modules, If the 'anyxml' statement occurs in any of the input YANG modules,
the following pattern definition MUST be added exactly once to the the following pattern definition MUST be added exactly once to the
RELAX NG schema as a child of the <rng:grammar> element (cf. [20], p. RELAX NG schema as a child of the <rng:grammar> element (cf. [21], p.
172): 172):
<rng:define name="__anyxml__"> <rng:define name="__anyxml__">
<rng:zeroOrMore> <rng:zeroOrMore>
<rng:choice> <rng:choice>
<rng:attribute> <rng:attribute>
<rng:anyName/> <rng:anyName/>
</rng:attribute> </rng:attribute>
<rng:element> <rng:element>
<rng:anyName/> <rng:anyName/>
skipping to change at page 38, line 18 skipping to change at page 45, line 18
within the 'identityref' type if it appears as a substatement of that within the 'identityref' type if it appears as a substatement of that
type definition, see Section 10.50.5. type definition, see Section 10.50.5.
10.5. The belongs-to Statement 10.5. The belongs-to Statement
This statement is not used since processing of submodules is always This statement is not used since processing of submodules is always
initiated from the main module, see Section 10.21. initiated from the main module, see Section 10.21.
10.6. The bit Statement 10.6. The bit Statement
Handled within the "bits" type, see Section 10.50.3. This statement is handled within the "bits" type, see
Section 10.50.3.
10.7. The case Statement 10.7. The case Statement
This statement is mapped to <rng:group> element. If the argument of This statement is mapped to <rng:group> element. If the argument of
a sibling 'default' statement equals to ARGUMENT, @nma:default-case a sibling 'default' statement equals to ARGUMENT, @nma:default-case
attribute with the value of "true" is added to that <rng:group> attribute with the value of "true" is added to that <rng:group>
element. element.
10.8. The choice Statement 10.8. The choice Statement
skipping to change at page 40, line 12 skipping to change at page 47, line 15
Otherwise, this statement is mapped to the DTD compatibility element Otherwise, this statement is mapped to the DTD compatibility element
<a:documentation> and ARGUMENT becomes its text. <a:documentation> and ARGUMENT becomes its text.
In order to get properly formatted in the RELAX NG compact syntax, In order to get properly formatted in the RELAX NG compact syntax,
this element SHOULD be inserted as the first child of PARENT. this element SHOULD be inserted as the first child of PARENT.
10.14. The enum Statement 10.14. The enum Statement
This statement is mapped to <rng:value> element and ARGUMENT becomes This statement is mapped to <rng:value> element and ARGUMENT becomes
its text. All substatements except 'status' are ignored because the its text. All substatements except 'status' are ignored because the
<rng:value> element cannot contain annotations, see [10], Section 6. <rng:value> element cannot contain annotations, see [12], Section 6.
10.15. The error-app-tag Statement 10.15. The error-app-tag Statement
This statement is ignored unless it is a substatement of 'must'. In This statement is ignored unless it is a substatement of 'must'. In
the latter case it is mapped to the <nma:error-app-tag> element. See the latter case it is mapped to the <nma:error-app-tag> element. See
also Section 10.32. also Section 10.32.
10.16. The error-message Statement 10.16. The error-message Statement
This statement is ignored unless it is a substatement of 'must'. In This statement is ignored unless it is a substatement of 'must'. In
skipping to change at page 41, line 38 skipping to change at page 48, line 38
is in ARGUMENT has to be parsed and its contents mapped exactly as if is in ARGUMENT has to be parsed and its contents mapped exactly as if
the submodule text was a subset of the main module text. the submodule text was a subset of the main module text.
If the 'include' statement has the 'revision' substatement, the If the 'include' statement has the 'revision' substatement, the
corresponding revision of the submodule MUST be used. The mechanism corresponding revision of the submodule MUST be used. The mechanism
for finding a given submodule revision is outside the scope of this for finding a given submodule revision is outside the scope of this
document. document.
10.22. The input Statement 10.22. The input Statement
This statement is mapped to <rng:element> and its @name attribute is This statement is handled within 'rpc' statement, see Section 10.47.
set to "nmt:input".
10.23. The key Statement 10.23. The key Statement
This statement is mapped to @nma:key attribute and ARGUMENT becomes This statement is mapped to @nma:key attribute. ARGUMENT is MUST be
the value of this attribute. 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.24. The leaf Statement 10.24. The leaf Statement
This statement is mapped to the <rng:element> element and ARGUMENT This statement is mapped to the <rng:element> element and ARGUMENT
becomes the value of its @name attribute. becomes the value of its @name attribute.
The leaf is optional if there is no "mandatory true;" substatement 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. and if the leaf is not declared among the keys of an enclosing list.
In this case, the <rng:element> element MUST be wrapped in <rng: In this case, the <rng:element> element MUST be wrapped in <rng:
optional>. optional>.
10.25. The leaf-list Statement 10.25. The leaf-list Statement
This statement is mapped to a block enclosed by either <rng: This statement is mapped to a block enclosed by either <rng:
zeroOrMore> or <rng:oneOrMore> element depending on whether the zeroOrMore> or <rng:oneOrMore> element depending on whether the
argument of 'min-elements' substatement is "0" or positive, argument of 'min-elements' substatement is "0" or positive,
respectively (it is zero by default). This <rng:zeroOrMore> or <rng: respectively (it is zero by default). This <rng:zeroOrMore> or <rng:
oneOrMore> element becomes the PARENT. oneOrMore> element becomes the PARENT.
skipping to change at page 42, line 16 skipping to change at page 49, line 16
optional>. optional>.
10.25. The leaf-list Statement 10.25. The leaf-list Statement
This statement is mapped to a block enclosed by either <rng: This statement is mapped to a block enclosed by either <rng:
zeroOrMore> or <rng:oneOrMore> element depending on whether the zeroOrMore> or <rng:oneOrMore> element depending on whether the
argument of 'min-elements' substatement is "0" or positive, argument of 'min-elements' substatement is "0" or positive,
respectively (it is zero by default). This <rng:zeroOrMore> or <rng: respectively (it is zero by default). This <rng:zeroOrMore> or <rng:
oneOrMore> element becomes the PARENT. oneOrMore> element becomes the PARENT.
Further, if the argument of 'min-elements' is greater than one, <rng:element> is the added as a child element of PARENT and ARGUMENT
attribute @nma:min-elements is attached to PARENT and the argument of becomes the value of its @name attribute. If the 'leaf-list'
'min-elements' becomes the value of this attribute. statement has the 'min-elements' substatement and its argument is
greater than one, additional attribute @nma:min-elements is attached
If there is the 'max-elements' substatement, attribute @nma:max- to <rng:element> and the argument of 'min-elements' becomes the value
elements is attached to PARENT and the argument of 'max-elements' of this attribute. Similarly, if there is the 'max-elements'
becomes the value of this attribute. substatement and its argument value is not "unbounded", attribute
@nma:max-elements is attached to this element and the argument of
Then <rng:element> is added as a child element of PARENT and ARGUMENT 'max-elements' becomes the value of this attribute.
becomes the value of its @name attribute.
EXAMPLE. YANG leaf-list EXAMPLE. YANG leaf-list
leaf-list foliage { leaf-list foliage {
min-elements 3; min-elements 3;
max-elements 6378; max-elements 6378;
ordered-by user; ordered-by user;
type string; type string;
} }
is mapped to the following RELAX NG fragment: is mapped to the following RELAX NG fragment:
<rng:oneOrMore nma:max-elements="6378" <rng:oneOrMore>
nma:min-elements="3"> <rng:element name="foliage" nma:ordered-by="user"
<rng:element name="foliage" nma:ordered-by="user"> nma:min-elements="3" nma:max-elements="6378">
<rng:data type="string"/> <rng:data type="string"/>
</rng:element> </rng:element>
</rng:oneOrMore> </rng:oneOrMore>
10.26. The length Statement 10.26. The length Statement
Handled within the "string" type, see Section 10.50.9. This statement is handled within the "string" type, see
Section 10.50.9.
10.27. The list Statement 10.27. The list Statement
This statement is mapped exactly as the 'leaf-list' statement, see This statement is mapped exactly as the 'leaf-list' statement, see
Section 10.25. Section 10.25.
10.28. The mandatory Statement 10.28. The mandatory Statement
This statement may appear as a substatement of 'leaf', 'choice' or This statement may appear as a substatement of 'leaf', 'choice' or
'anyxml' statement. If ARGUMENT is "true", the parent data node is 'anyxml' statement. If ARGUMENT is "true", the parent data node is
skipping to change at page 44, line 19 skipping to change at page 51, line 23
is mapped to is mapped to
<nma:must assert="current()&lt;=../dhcp:max-lease-time"> <nma:must assert="current()&lt;=../dhcp:max-lease-time">
<nma:error-message> <nma:error-message>
The default-lease-time must be less than max-lease-time The default-lease-time must be less than max-lease-time
</nma:error-message> </nma:error-message>
</nma:must> </nma:must>
10.33. The namespace Statement 10.33. The namespace Statement
ARGUMENT of this statement - namespace URI of the input module - is This statement is mapped to @xmlns:xxx attribute of the <rng:grammar>
mapped to an XML attribute of the <rng:grammar> element (the root of element where "xxx" is the namespace prefix specified by the sibling
the RELAX NG schema) in the following way: 'prefix' statement. ARGUMENT becomes the value of this attribute.
1. For one of the input modules, its namespace URI MAY become the
value of the @ns attribute.
2. For the remaining input modules, the namespace URI becomes the
value of the @xmlns:xxx attribute where "xxx" is a unique prefix,
which SHOULD be set to the argument of the 'prefix' statement in
the same module (see Section 10.41).
In case 2, names of all data nodes appearing as values of the @name
attribute of the <rng:element> elements in the RELAX NG schema MUST
use the given prefix whereas in case 1 the values have no prefix.
Namespace URI of all input modules MAY be mapped using the method in
2. The advantage of this approach is that the recommended prefixes
are recorded in the output RELAX NG schema for all input modules.
EXAMPLE: Assume we have the following two YANG modules as input:
module foo-module {
namespace "http://example.com/ns/foo";
prefix foo;
...
}
and
module bar-module {
namespace "http://example.com/ns/bar";
prefix bar;
...
}
The <rng:grammar> element in the output schema may then be either
<rng:grammar xmlns="http://relaxng.org/ns/structure/1.0" 10.34. The notification Statement
xmlns:foo="http://example.com/ns/foo"
xmlns:bar="http://example.com/ns/bar"
...
>
...
</rng:grammar>
or This statement is mapped to the following subtree in the RELAX NG
schema ("yam" is the prefix of the local YANG module):
<rng:grammar xmlns="http://relaxng.org/ns/structure/1.0" <rng:element name="nmt:notification">
ns="http://example.com/ns/foo" <rng:element name="yam:ARGUMENT">
xmlns:bar="http://example.com/ns/bar"
...
>
... ...
</rng:grammar> </rng:element>
</rng:element>
The third possibility is analogical to the previous one, only with
the roles of "foo" and "bar" exchanged.
10.34. The notification Statement Substatements of 'notification' are mapped under <rng:element
name="yam:ARGUMENT">.
This element is mapped to <rng:element> and its @name attribute is The <rng:element name="nmt:rpc-notification"> element is a child of
set to "nmt:notification" element. This element is defined as a <rng:element name="nmt:notifications">.
child of the <nmt:notifications> element in the conceptual tree.
10.35. The ordered-by Statement 10.35. The ordered-by Statement
This statement is mapped to @nma:ordered-by attribute and ARGUMENT This statement is mapped to @nma:ordered-by attribute and ARGUMENT
becomes the value of this attribute. See Section 10.25 for an becomes the value of this attribute. See Section 10.25 for an
example. example.
10.36. The organization Statement 10.36. The organization Statement
This statement is not used by the mapping since the output RELAX NG This statement is not used by the mapping since the output RELAX NG
schema may result from multiple YANG modules authored by different schema may result from multiple YANG modules authored by different
parties. The schema contains references to all input modules in the parties. The schema contains references to all input modules in the
Dublin Core elements <dc:source>, see Section 10.31. The original Dublin Core elements <dc:source>, see Section 10.31. The original
modules are the authoritative sources of the authorship information. modules are the authoritative sources of the authorship information.
10.37. The output Statement 10.37. The output Statement
This statement is mapped to <rng:element> and its @name attribute is This statement is handled within 'rpc' statement, see Section 10.47.
set to "nmt:output".
10.38. The path Statement 10.38. The path Statement
Handled within "leafref" type, see Section 10.50.7. This statement is handled within "leafref" type, see Section 10.50.7.
10.39. The pattern Statement 10.39. The pattern Statement
Handled within "string" type, see Section 10.50.9. This statement is handled within "string" type, see Section 10.50.9.
10.40. The position Statement 10.40. The position Statement
This statement is ignored. This statement is ignored.
10.41. The prefix Statement 10.41. The prefix Statement
ARGUMENT of this statement - the recommended namespace prefix for the This statement is handled within the sibling 'namespace' statement,
input module - MAY be mapped to a namespace prefix declared using the see Section 10.33, or within the parent 'import' statement, see
@xmlns:xxx attribute of the <rng:grammar> element in the output Section 10.20. As a substatement of 'belongs-to' (in submodules),
schema, where "xxx" is replaced by ARGUMENT. For multiple input the 'prefix' statement is ignored.
modules, the mapping of prefixes depends on how their namespace URIs
are used, see Section 10.33.
10.42. The presence Statement 10.42. The presence Statement
This statement influences the mapping of 'container' (Section 10.11): This statement influences the mapping of 'container' (Section 10.11):
it makes the parent container optional, regardless of its content. it makes the parent container optional, regardless of its content.
See also Section 7.1. See also Section 7.1.
10.43. The range Statement 10.43. The range Statement
Handled within numeric types, see Section 10.50.8. This statement is handled within numeric types, see Section 10.50.8.
10.44. The reference Statement 10.44. The reference Statement
This statement is ignored if it appears at the top level of a module This statement is ignored if it appears at the top level of a module
or submodule. or submodule.
Otherwise, this statement is mapped to <a:documentation> element and Otherwise, this statement is mapped to <a:documentation> element and
its text is set to ARGUMENT prefixed with "See: ". its text is set to ARGUMENT prefixed with "See: ".
10.45. The require-instance Statement 10.45. The require-instance Statement
Handled within the types "leafref" (Section 10.50.7) and "instance- This statement is handled within the types "leafref"
identifier" (Section 10.50.6). (Section 10.50.7) and "instance-identifier" (Section 10.50.6).
10.46. The revision Statement 10.46. The revision Statement
The mapping uses only the most recent instance of the 'revision' The mapping uses only the most recent instance of the 'revision'
statement, i.e., one with the latest date in ARGUMENT, which statement, i.e., one with the latest date in ARGUMENT, which
specifies the current revision of the input YANG module [5]. This specifies the current revision of the input YANG module [5]. This
date SHOULD be recorded, together with the name of the YANG module, date SHOULD be recorded, together with the name of the YANG module,
in the corresponding Dublin Core element <dc:source> (see in the corresponding Dublin Core element <dc:source> (see
Section 10.31), for example in this form: Section 10.31), for example in this form:
<dc:source>YANG module 'foo', revision 2009-01-19</dc:source> <dc:source>YANG module 'foo', revision 2009-01-19</dc:source>
The 'description' substatement of 'revision' is not used. The 'description' substatement of 'revision' is not used.
10.47. The rpc Statement 10.47. The rpc Statement
This element is mapped to <rng:element> and its @name attribute is This statement is mapped to the following subtree in the RELAX NG
set to "nmt:rpc-method" element. This element is defined as a child schema ("yam" is the prefix of the local YANG module):
of the <nmt:rpc-methods> element in the conceptual tree.
<rng:element name="nmt:rpc-method">
<rng:element name="nmt:input">
<rng:element name="yam:ARGUMENT">
<!-- mapped content of 'input' -->
</rng:element>
</rng:element>
<rng:element name="nmt:output">
<!-- mapped content of 'output' -->
</rng:element>
</rng:element>
As indicated by the comments, contents of the 'input' substatement
(if any) are mapped under <rng:element name="yam:ARGUMENT">.
Similarly, contents of the 'output' substatement are mapped under
<rng:element name="nmt:output">. If there is no 'output'
substatement, the <rng:element name="nmt:output"> MUST NOT be
present.
The <rng:element name="nmt:rpc-method"> element is a child of <rng:
element name="nmt:rpc-methods">.
10.48. The status Statement 10.48. The status Statement
This statement is mapped to @nma:status attribute and ARGUMENT This statement is mapped to @nma:status attribute and ARGUMENT
becomes its value. becomes its value.
10.49. The submodule Statement 10.49. The submodule Statement
This statement is not specifically mapped. Its substatements are This statement is not specifically mapped. Its substatements are
mapped as if they appeared directly in the module the submodule mapped as if they appeared directly in the module the submodule
belongs to. belongs to.
10.50. The type Statement 10.50. The type Statement
Most YANG built-in types have an equivalent in the XSD datatype Most YANG built-in types have an equivalent in the XSD datatype
library [14] as shown in Table 3. library [16] as shown in Table 3.
+-----------+---------------+----------------------------------+ +-----------+---------------+----------------------------------+
| YANG type | XSD type | Meaning | | YANG type | XSD type | Meaning |
+-----------+---------------+----------------------------------+ +-----------+---------------+----------------------------------+
| int8 | byte | 8-bit integer value | | int8 | byte | 8-bit integer value |
| | | | | | | |
| int16 | short | 16-bit integer value | | int16 | short | 16-bit integer value |
| | | | | | | |
| int32 | int | 32-bit integer value | | int32 | int | 32-bit integer value |
| | | | | | | |
skipping to change at page 49, line 24 skipping to change at page 55, line 34
where bit_name is the name of the bit as found in the argument of the where bit_name is the name of the bit as found in the argument of the
corresponding 'bit' statement. corresponding 'bit' statement.
10.50.4. The enumeration and union Types 10.50.4. The enumeration and union Types
These types are mapped to <rng:choice> element. These types are mapped to <rng:choice> element.
10.50.5. The identityref Type 10.50.5. The identityref Type
This type is mapped to <rng:choice> element with one or more <rng: This type is mapped to <rng:choice> element with one or more <rng:
value> subelements. Each of the <rng:value> subelements MUST have a value> subelements. Each of the <rng:value> subelements MUST have
@type attribute and its value set to "QName". One <rng:value> the @type attribute and its value set to "QName". One <rng:value>
subelement with argument of the 'base' substatement as its text MUST subelement with argument of the 'base' substatement as its text MUST
always be present. In addition, one <rng:value> substatement MUST be always be present. In addition, one <rng:value> substatement MUST be
added for each identity declared locally or in an imported module added for each identity declared locally or in an imported module
that has the argument of the 'base' substatement as its base that has the argument of the 'base' substatement as its base
identity. identity.
All namespace prefixes that are used for identities from imported All namespace prefixes that are used for identities from imported
modules MUST be appropriately defined. modules MUST be appropriately defined.
EXAMPLE (taken from [5], Section 7.6.13). Consider the following two EXAMPLE (taken from [5], Section 7.6.13). Consider the following two
skipping to change at page 54, line 7 skipping to change at page 60, line 7
the type derivation chain. See Section 10.50.10 for further details the type derivation chain. See Section 10.50.10 for further details
and an example. and an example.
An implementation MAY offer the option of recording all 'typedef' An implementation MAY offer the option of recording all 'typedef'
statements as named patterns in the output RELAX NG schema even if statements as named patterns in the output RELAX NG schema even if
they are not referenced. This is useful for mapping YANG "library" they are not referenced. This is useful for mapping YANG "library"
modules containing only 'typedef' and/or 'grouping' statements. modules containing only 'typedef' and/or 'grouping' statements.
10.52. The unique Statement 10.52. The unique Statement
This statement is mapped to @nma:unique attribute and ARGUMENT This statement is mapped to @nma:unique attribute. ARGUMENT is
becomes its value. translated so that every node identifier in each of its components is
prefixed with the namespace prefix of the local module, unless the
prefix is already present. The result of this translation then
becomes the value of the @nma:unique attribute.
For example, assuming that the local module prefix is "ex",
unique "foo ex:bar/baz"
is mapped to the following attribute/value pair:
nma:unique="ex:foo ex:bar/ex:baz"
10.53. The units Statement 10.53. The units Statement
This statement is mapped to @nma:units attribute and ARGUMENT becomes This statement is mapped to @nma:units attribute and ARGUMENT becomes
its value. its value.
10.54. The uses Statement 10.54. The uses Statement
If this statement has neither 'refine' nor 'augment' substatements, If this statement has neither 'refine' nor 'augment' substatements,
it is mapped to <rng:ref> element and the value of its @name it is mapped to <rng:ref> element and the value of its @name
skipping to change at page 55, line 5 skipping to change at page 62, line 5
This statement is not mapped to the output schema. However, an This statement is not mapped to the output schema. However, an
implementation SHOULD check that it is compatible with the YANG implementation SHOULD check that it is compatible with the YANG
version declared by the statement (currently version 1). version declared by the statement (currently version 1).
10.58. The yin-element Statement 10.58. The yin-element Statement
This statement is not mapped to the output schema, but see the rules This statement is not mapped to the output schema, but see the rules
for extension handling in Section 7.4. for extension handling in Section 7.4.
11. Mapping NETMOD-specific annotations to Schematron and DSRL 11. Mapping NETMOD-specific annotations to DSDL Schema Languages
This section contains mapping specification for individual NETMOD-
specific annotations. In each case, the result of the mapping must
be inserted into an appropriate context of the target DSDL schema as
described in Section 8. The context is determined by the element
definition in the conceptual tree schema to which the annotation is
attached. In the rest of this section, we will denote CONTELEM the
name of this context element properly qualified with its namespace
prefix. Unless otherwise stated, Schematron asserts are descendants
of the "standard" pattern and therefore active in both validation
phases.
11.1. The @nma:config Annotation
This annotation MUST be observed when generating any schema for the
reply to <nc:get-config>. In particular:
o When generating RELAX NG, the contents of the CONTELEM definition
MUST be changed to <rng:notAllowed>.
o When generating Schematron or DSRL, the CONTELEM definition and
all its descendants in the conceptual tree schema MUST be ignored.
11.2. The @nma:default Annotation
TBD
11.3. The @nma:default-case Annotation
TBD TBD
11.4. The <nma:error-app-tag> Annotation
This annotation currently has no mapping defined.
11.5. The <nma:error-message> Annotation
This annotation is handled within <nma:must>, see Section 11.11.
11.6. The <nma:instance-identifier> Annotation
This annotation currently has no mapping defined.
[Editor's note: The mapping is probably not possible with XPath 1.0
as the query language in Schematron. Shall we use EXSLT or XPath
2.0?]
11.7. The @nma:key Annotation
Assume this annotation has the value "k_1 k_2 ... k_n", i.e.,
specifies n child leaves as keys. The annotation is then mapped to
the following Schematron report:
<sch:report test="CONDITION">
Duplicate key of list "CONTELEM"
</sch:report>
where CONDITION has this form:
preceding-sibling::CONTELEM[C_1 and C_2 and ... and C_n]
Each 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 <nma:leafref> 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 <nma:leafref> annotation is
mapped to the following assert:
<sch:assert test="PATH=..">
Leafref "CONTELEM" must have the same value as "PATH"
</sch:assert>
where PATH is the content of <nma:leafref>.
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, <nma:leafref> is
mapped to the following assert:
<sch:assert test="not(PATH) or PATH=..">
Leafref "CONTELEM" must have the same value as "PATH"
</sch:assert>
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.
11.9. The @nma:min-elements Annotation
This annotation is mapped to the following Schematron assert:
<sch:assert test="count(../CONTELEM)&gt;=MIN">
List "CONTELEM" - item count must be at least MIN
</sch:assert>
where MIN is the value of @nma:min-elements.
11.10. The @nma:max-elements Annotation
This annotation is mapped to the following Schematron assert:
<sch:assert test="count(../CONTELEM)&lt;=MAX">
List "CONTELEM" - item count must be at most MAX
</sch:assert>
where MAX is the value of @nma:min-elements.
11.11. The <nma:must> Annotation
This annotation is mapped to the following Schematron assert:
<sch:assert test="EXPRESSION">
MESSAGE
</sch:assert>
where EXPRESSION is the value of the mandatory @assert attribute of
<nma:must>. If the <nma:error-message> subelement exists, MESSAGE is
set to its content, otherwise it is set to the default message
"Condition EXPRESSION must be true".
11.12. The <nma:ordered-by> Annotation
This annotation currently has no mapping defined.
11.13. The <nma:status> Annotation
This annotation currently has no mapping defined.
11.14. The @nma:unique Annotation
The mapping of this annotation is almost identical as for @nma:key,
see Section 11.7, with two small differences:
o The value of @nma:unique is a list of descendant schema node
identifiers rather than simple leaf names. However, the XPath
expressions specified in Section 11.7 work without any
modifications if the descendant schema node identifiers are
substituted for k_1, k_2, ..., k_n.
o The message appearing as the text of <sch:report> is different:
"Violated uniqueness for list CONTELEM".
11.15. The @nma:when Annotation
<sch:assert test="EXPRESSION or not(..)">
Node "CONTELEM" requires "EXPRESSION"
</sch:assert>
where EXPRESSION is the value of @nma:when.
12. IANA Considerations 12. IANA Considerations
This document registers two namespace URIs in the IETF XML registry This document registers two namespace URIs in the IETF XML registry
[21]: [22]:
URI: urn:ietf:params:xml:ns:netmod:dsdl-annotations:1 URI: urn:ietf:params:xml:ns:netmod:dsdl-annotations:1
URI: urn:ietf:params:xml:ns:netmod:conceptual-tree:1 URI: urn:ietf:params:xml:ns:netmod:conceptual-tree:1
13. References 13. References
[1] Enns, R., "NETCONF Configuration Protocol", RFC 4741, [1] Enns, R., "NETCONF Configuration Protocol", RFC 4741,
December 2006. December 2006.
[2] Case, J., Fedor, M., Schoffstall, M., and J. Davin, "Simple [2] Case, J., Fedor, M., Schoffstall, M., and J. Davin, "Simple
Network Management Protocol (SNMP)", STD 15, RFC 1157, Network Management Protocol (SNMP)", STD 15, RFC 1157,
May 1990. May 1990.
skipping to change at page 57, line 23 skipping to change at page 67, line 23
[3] McCloghrie, K., Ed., Perkins, D., Ed., and J. Schoenwaelder, [3] McCloghrie, K., Ed., Perkins, D., Ed., and J. Schoenwaelder,
Ed., "Structure of Management Information Version 2 (SMIv2)", Ed., "Structure of Management Information Version 2 (SMIv2)",
STD 58, RFC 2578, April 1999. STD 58, RFC 2578, April 1999.
[4] Elliott, C., Harrington, D., Jason, J., Schoenwaelder, J., [4] Elliott, C., Harrington, D., Jason, J., Schoenwaelder, J.,
Strauss, F., and W. Weiss, "SMIng Objectives", RFC 3216, Strauss, F., and W. Weiss, "SMIng Objectives", RFC 3216,
December 2001. December 2001.
[5] Bjorklund, M., Ed., "YANG - A data modeling language for [5] Bjorklund, M., Ed., "YANG - A data modeling language for
NETCONF", draft-ietf-netmod-yang-03 (work in progress), NETCONF", draft-ietf-netmod-yang-04 (work in progress),
January 2009. March 2009.
[6] ISO/IEC, "Document Schema Definition Languages (DSDL) - Part 1: [6] ISO/IEC, "Document Schema Definition Languages (DSDL) - Part 1:
Overview", ISO/IEC 19757-1, 11 2004. Overview", ISO/IEC 19757-1, 11 2004.
[7] Bradner, S., "Key words for use in RFCs to Indicate Requirement [7] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997. Levels", BCP 14, RFC 2119, March 1997.
[8] Clark, J., Ed. and M. Murata, Ed., "RELAX NG DTD [8] Clark, J., Ed. and M. Murata, Ed., "RELAX NG DTD
Compatibility", OASIS Committee Specification 3 December 2001, Compatibility", OASIS Committee Specification 3 December 2001,
December 2001. December 2001.
[9] ISO/IEC, "Information Technology - Document Schema Definition [9] Kunze, J., "The Dublin Core Metadata Element Set", RFC 5013,
August 2007.
[10] Chisholm, S. and H. Trevino, "NETCONF Event Notifications",
RFC 5277, July 2008.
[11] ISO/IEC, "Information Technology - Document Schema Definition
Languages (DSDL) - Part 8: Document Semantics Renaming Language Languages (DSDL) - Part 8: Document Semantics Renaming Language
- DSRL", ISO/IEC 19757-8:2008(E), 12 2008. - DSRL", ISO/IEC 19757-8:2008(E), 12 2008.
[10] ISO/IEC, "Information Technology - Document Schema Definition [12] ISO/IEC, "Information Technology - Document Schema Definition
Languages (DSDL) - Part 2: Regular-Grammar-Based Validation - Languages (DSDL) - Part 2: Regular-Grammar-Based Validation -
RELAX NG. Second Edition.", ISO/IEC 19757-2:2008(E), 12 2008. RELAX NG. Second Edition.", ISO/IEC 19757-2:2008(E), 12 2008.
[11] ISO/IEC, "Information Technology - Document Schema Definition [13] ISO/IEC, "Information Technology - Document Schema Definition
Languages (DSDL) - Part 3: Rule-Based Validation - Schematron", Languages (DSDL) - Part 3: Rule-Based Validation - Schematron",
ISO/IEC 19757-3:2006(E), 6 2006. ISO/IEC 19757-3:2006(E), 6 2006.
[12] Thompson, H., Beech, D., Maloney, M., and N. Mendelsohn, "XML [14] Thompson, H., Beech, D., Maloney, M., and N. Mendelsohn, "XML
Schema Part 1: Structures Second Edition", World Wide Web Schema Part 1: Structures Second Edition", World Wide Web
Consortium Recommendation REC-xmlschema-1-20041028, Consortium Recommendation REC-xmlschema-1-20041028,
October 2004, October 2004,
<http://www.w3.org/TR/2004/REC-xmlschema-1-20041028>. <http://www.w3.org/TR/2004/REC-xmlschema-1-20041028>.
[13] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and F. [15] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and F.
Yergeau, "Extensible Markup Language (XML) 1.0 (Fourth Yergeau, "Extensible Markup Language (XML) 1.0 (Fourth
Edition)", World Wide Web Consortium Recommendation REC-xml- Edition)", World Wide Web Consortium Recommendation REC-xml-
20060816, August 2006, 20060816, August 2006,
<http://www.w3.org/TR/2006/REC-xml-20060816>. <http://www.w3.org/TR/2006/REC-xml-20060816>.
[14] Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes Second [16] Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes Second
Edition", World Wide Web Consortium Recommendation REC- Edition", World Wide Web Consortium Recommendation REC-
xmlschema-2-20041028, October 2004, xmlschema-2-20041028, October 2004,
<http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>. <http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.
[15] ISO/IEC, "Information Technology - Document Schema Definition [17] ISO/IEC, "Information Technology - Document Schema Definition
Languages (DSDL) - Part 2: Regular-Grammar-Based Validation - Languages (DSDL) - Part 2: Regular-Grammar-Based Validation -
RELAX NG. AMENDMENT 1: Compact Syntax", ISO/IEC 19757-2:2003/ RELAX NG. AMENDMENT 1: Compact Syntax", ISO/IEC 19757-2:2003/
Amd. 1:2006(E), 1 2006. Amd. 1:2006(E), 1 2006.
[16] Clark, J. and S. DeRose, "XML Path Language (XPath) Version [18] Clark, J. and S. DeRose, "XML Path Language (XPath) Version
1.0", World Wide Web Consortium Recommendation REC-xpath- 1.0", World Wide Web Consortium Recommendation REC-xpath-
19991116, November 1999, 19991116, November 1999,
<http://www.w3.org/TR/1999/REC-xpath-19991116>. <http://www.w3.org/TR/1999/REC-xpath-19991116>.
[17] Clark, J., "XSL Transformations (XSLT) Version 1.0", World Wide [19] Clark, J., "XSL Transformations (XSLT) Version 1.0", World Wide
Web Consortium Recommendation REC-xslt-19991116, November 1999. Web Consortium Recommendation REC-xslt-19991116, November 1999.
[18] Kunze, J., "The Dublin Core Metadata Element Set", RFC 5013, [20] Schoenwaelder, J., Ed., "Common YANG Data Types",
August 2007.
[19] Schoenwaelder, J., Ed., "Common YANG Data Types",
draft-ietf-netmod-yang-types-01 (work in progress), draft-ietf-netmod-yang-types-01 (work in progress),
November 2008. November 2008.
[20] van der Vlist, E., "RELAX NG", O'Reilly , 2004. [21] van der Vlist, E., "RELAX NG", O'Reilly , 2004.
[21] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, [22] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004. January 2004.
[22] <http://www.thaiopensource.com/relaxng/trang.html> [23] <http://www.thaiopensource.com/relaxng/trang.html>
[23] <http://dublincore.org/> [24] <http://dublincore.org/>
[24] <http://www.yang-central.org/twiki/bin/view/Main/DhcpTutorial> [25] <http://www.yang-central.org/twiki/bin/view/Main/DhcpTutorial>
[25] <http://thaiopensource.com/relaxng/trang.html> [26] <http://code.google.com/p/pyang/>
[27] <http://thaiopensource.com/relaxng/trang.html>
Appendix A. RELAX NG Schema for NETMOD-specific Annotations Appendix A. RELAX NG Schema for NETMOD-specific Annotations
This appendix contains the RELAX NG schema for the NETMOD-specific This appendix contains the RELAX NG schema for the NETMOD-specific
annotations in both XML and compact syntax. annotations in both XML and compact syntax.
[Editor's note: It is currently only a set of named pattern [Editor's note: It is currently only a set of named pattern
definitions as templates for the annotation elements and attributes. definitions as templates for the annotation elements and attributes.
We should find a way how to connect this to the schema for RELAX NG, We should find a way how to connect this to the schema for RELAX NG,
which these annotations extend. One option may be NVDL or it can which these annotations extend. One option may be NVDL or it can
skipping to change at page 63, line 5 skipping to change at page 73, line 5
ordered-by-attribute = attribute ordered-by { "user" | "system" } ordered-by-attribute = attribute ordered-by { "user" | "system" }
status-attribute = status-attribute =
attribute status { "current" | "deprecated" | "obsolete" } attribute status { "current" | "deprecated" | "obsolete" }
unique-attribute = unique-attribute =
attribute unique { attribute unique {
list { xsd:string } list { xsd:string }
} }
units-attribute = attribute units { xsd:string } units-attribute = attribute units { xsd:string }
when-attribute = attribute when { xsd:string } when-attribute = attribute when { xsd:string }
Appendix B. Schematron Library Appendix B. Schema-Independent Library
This appendix contains the schema-independent library of Schematron In order to avoid copying the same named pattern definitions to the
abstract patterns. RELAX NG schemas generated in the second mapping step, we collected
these definitions to a library file - schema-independent library -
which is included by the validating schemas under the file name
"relaxng-lib.rng" (XML syntax) and "relaxng-lib.rnc" (compact
syntax). The included definitions cover patterns for common elements
from base NETCONF [1] and event notifications [10].
[Editor's note: It is incomplete.] B.1. XML Syntax
<!-- Uniqueness of list keys --> <?xml version="1.0" encoding="UTF-8"?>
<sch:pattern abstract="true" id="key">
<sch:rule context="$context">
<sch:assert test="count($context[$key=current()/$key])=1">
The key "<value-of select="$key"/>" needs to be unique
within the list at: <value-of select="$context"/>.
</sch:assert>
</sch:rule>
</sch:pattern>
<!-- Check of listref target --> <!-- Library of RELAX NG pattern definitions -->
<sch:pattern abstract="true" id="keyref">
<sch:rule context="$keyref-context">
<sch:assert test="$key-context[$key=current()]">
The contents of "<value-of select="$keyref-context"/>"
must be a '</name>' with the key
"<value-of select="$key"/>" in this context:
<value-of select="$key-context"/>.
</sch:assert>
</sch:rule>
</sch:pattern>
Appendix C. Translation of the DHCP Data Model <grammar xmlns="http://relaxng.org/ns/structure/1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:en="urn:ietf:params:xml:ns:netconf:notification:1.0"
datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
This appendix demonstrates output of the YANG->DSDL mapping algorithm <define name="message-id-attribute">
applied to the "canonical" DHCP tutorial [24] data model. <attribute name="message-id">
<data type="string">
<param name="maxLength">4095</param>
</data>
</attribute>
</define>
Appendix C.1 shows the result of the mapping algorithm in the RELAX <define name="ok-element">
NG XML syntax and Appendix C.2 the same in the compact syntax, which <element name="nc:ok">
was obtained using the Trang tool [25]. <empty/>
</element>
</define>
The long regular expressions for IP addresses etc. that would exceed <define name="eventTime-element">
the limit of 72 characters per line were trimmed. Other than that, <element name="en:eventTime">
the results of the automatic translations were not changed. <data type="dateTime"/>
</element>
</define>
</grammar>
C.1. XML Syntax B.2. Compact Syntax
# Library of RELAX NG pattern definitions
namespace en = "urn:ietf:params:xml:ns:netconf:notification:1.0"
namespace nc = "urn:ietf:params:xml:ns:netconf:base:1.0"
message-id-attribute =
attribute message-id {
xsd:string { maxLength = "4095" }
}
ok-element = element nc:ok { empty }
eventTime-element = element en:eventTime { xsd:dateTime }
Appendix C. Mapping DHCP Data Model - A Complete Example
This appendix demonstrates both steps of the YANG-to-DSDL mapping
applied to the "canonical" DHCP tutorial [25] data model. The input
(single) YANG module is shown in Appendix C.1 and the output schemas
in the following two subsections.
The conceptual tree schema was obtained by the "rng" plugin of the
pyang [26] tool and the validating DSDL schemas by XSLT stylesheets
that are also part of pyang distribution. RELAX NG schemas are shown
in both XML and compact syntax. The latter was obtained from the
former by using the Trang tool [27]
Due to the limit of 72 characters per line, few long strings required
manual editing, in particular the regular expression patterns for IP
addresses etc. in the RELAX NG schemas. In the compact syntax we
broke the patterns to appropriate segments and joined them with the
concatenation operator "~". In the XML syntax, though, the long
patterns had to be replaced by the placeholder string "... regex
pattern ...". Also, line breaks were added to several documentation
strings and Schematron messages. Other than that, the results of the
automatic translations were not changed.
C.1. Input YANG Module
module dhcp {
namespace "http://example.com/ns/dhcp";
prefix dhcp;
import yang-types { prefix yang; }
import inet-types { prefix inet; }
organization
"yang-central.org";
description
"Partial data model for DHCP, based on the config of
the ISC DHCP reference implementation.";
container dhcp {
description
"configuration and operational parameters for a DHCP server.";
leaf max-lease-time {
type uint32;
units seconds;
default 7200;
}
leaf default-lease-time {
type uint32;
units seconds;
must '. <= ../dhcp:max-lease-time' {
error-message
"The default-lease-time must be less than max-lease-time";
}
default 600;
}
uses subnet-list;
container shared-networks {
list shared-network {
key name;
leaf name {
type string;
}
uses subnet-list;
}
}
container status {
config false;
list leases {
key address;
leaf address {
type inet:ip-address;
}
leaf starts {
type yang:date-and-time;
}
leaf ends {
type yang:date-and-time;
}
container hardware {
leaf type {
type enumeration {
enum "ethernet";
enum "token-ring";
enum "fddi";
}
}
leaf address {
type yang:phys-address;
}
}
}
}
}
grouping subnet-list {
description "A reusable list of subnets";
list subnet {
key net;
leaf net {
type inet:ip-prefix;
}
container range {
presence "enables dynamic address assignment";
leaf dynamic-bootp {
type empty;
description
"Allows BOOTP clients to get addresses in this range";
}
leaf low {
type inet:ip-address;
mandatory true;
}
leaf high {
type inet:ip-address;
mandatory true;
}
}
container dhcp-options {
description "Options in the DHCP protocol";
leaf-list router {
type inet:host;
ordered-by user;
reference "RFC 2132, sec. 3.8";
}
leaf domain-name {
type inet:domain-name;
reference "RFC 2132, sec. 3.17";
}
}
leaf max-lease-time {
type uint32;
units seconds;
default 7200;
}
}
}
}
C.2. Conceptual Tree Schema
C.2.1. XML Syntax
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<grammar <grammar
xmlns="http://relaxng.org/ns/structure/1.0" xmlns="http://relaxng.org/ns/structure/1.0"
xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0" xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"
xmlns:dc="http://purl.org/dc/terms" xmlns:dc="http://purl.org/dc/terms"
xmlns:dhcp="http://example.com/ns/dhcp" xmlns:dhcp="http://example.com/ns/dhcp"
xmlns:nma="urn:ietf:params:xml:ns:netmod:rng-annot:1" xmlns:nma="urn:ietf:params:xml:ns:netmod:dsdl-annotations:1"
xmlns:nmt="urn:ietf:params:xml:ns:netmod:tree:1" xmlns:nmt="urn:ietf:params:xml:ns:netmod:conceptual-tree:1"
datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"> datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
<dc:creator>Pyang 0.9.3, RELAX NG plugin</dc:creator> <dc:creator>Pyang 0.9.3, RELAX NG plugin</dc:creator>
<dc:source>YANG module 'dhcp'</dc:source> <dc:source>YANG module 'dhcp'</dc:source>
<start> <start>
<element name="nmt:netmod-tree"> <element name="nmt:netmod-tree">
<element name="nmt:top"> <element name="nmt:top">
<interleave> <interleave>
<optional> <optional>
<element name="dhcp:dhcp"> <element name="dhcp:dhcp">
<a:documentation>configuration and operational <a:documentation>
parameters for a DHCP server.</a:documentation> configuration and operational parameters for a DHCP server.
</a:documentation>
<optional> <optional>
<element name="dhcp:max-lease-time" <element name="dhcp:max-lease-time"
nma:default="7200" nma:default="7200" nma:units="seconds">
nma:units="seconds">
<data type="unsignedInt"/> <data type="unsignedInt"/>
</element> </element>
</optional> </optional>
<optional> <optional>
<element name="dhcp:default-lease-time" <element name="dhcp:default-lease-time"
nma:default="600" nma:default="600" nma:units="seconds">
nma:units="seconds">
<data type="unsignedInt"/> <data type="unsignedInt"/>
<nma:must <nma:must
assert="current() &lt;= ../max-lease-time"> assert=". &lt;= ../dhcp:max-lease-time">
<nma:error-message>The default-lease-time must be <nma:error-message>
less than max-lease-time</nma:error-message> The default-lease-time must be less than max-lease-time
</nma:error-message>
</nma:must> </nma:must>
</element> </element>
</optional> </optional>
<ref name="dhcp__subnet-list"/> <ref name="_dhcp__subnet-list"/>
<optional> <optional>
<element name="dhcp:shared-networks"> <element name="dhcp:shared-networks">
<zeroOrMore> <zeroOrMore>
<element name="dhcp:shared-network" <element name="dhcp:shared-network"
nma:key="name"> nma:key="dhcp:name">
<element name="dhcp:name"> <element name="dhcp:name">
<data type="string"/> <data type="string"/>
</element> </element>
<ref name="dhcp__subnet-list"/> <ref name="_dhcp__subnet-list"/>
</element> </element>
</zeroOrMore> </zeroOrMore>
</element> </element>
</optional> </optional>
<optional> <optional>
<element name="dhcp:status" <element name="dhcp:status" nma:config="false">
nma:config="false">
<zeroOrMore> <zeroOrMore>
<element name="dhcp:leases" <element name="dhcp:leases"
nma:key="address"> nma:key="dhcp:address">
<element name="dhcp:address"> <element name="dhcp:address">
<ref name="inet-types__ip-address"/> <ref name="inet-types__ip-address"/>
</element> </element>
<optional> <optional>
<element name="dhcp:starts"> <element name="dhcp:starts">
<ref name="yang-types__date-and-time"/> <ref name="yang-types__date-and-time"/>
</element> </element>
</optional> </optional>
<optional> <optional>
<element name="dhcp:ends"> <element name="dhcp:ends">
skipping to change at page 66, line 28 skipping to change at page 80, line 19
</interleave> </interleave>
</element> </element>
<element name="nmt:rpc-methods"> <element name="nmt:rpc-methods">
<empty/> <empty/>
</element> </element>
<element name="nmt:notifications"> <element name="nmt:notifications">
<empty/> <empty/>
</element> </element>
</element> </element>
</start> </start>
<define name="dhcp__subnet-list"> <define name="_dhcp__subnet-list">
<a:documentation>A reusable list of subnets</a:documentation> <a:documentation>A reusable list of subnets</a:documentation>
<zeroOrMore> <zeroOrMore>
<element name="dhcp:subnet" nma:key="net"> <element name="dhcp:subnet" nma:key="dhcp:net">
<element name="dhcp:net"> <element name="dhcp:net">
<ref name="inet-types__ip-prefix"/> <ref name="inet-types__ip-prefix"/>
</element> </element>
<optional> <optional>
<element name="dhcp:range"> <element name="dhcp:range">
<optional> <optional>
<element name="dhcp:dynamic-bootp"> <element name="dhcp:dynamic-bootp">
<a:documentation>Allows BOOTP clients to get addresses <a:documentation>
in this range</a:documentation> Allows BOOTP clients to get addresses in this range
</a:documentation>
<empty/> <empty/>
</element> </element>
</optional> </optional>
<element name="dhcp:low"> <element name="dhcp:low">
<ref name="inet-types__ip-address"/> <ref name="inet-types__ip-address"/>
</element> </element>
<element name="dhcp:high"> <element name="dhcp:high">
<ref name="inet-types__ip-address"/> <ref name="inet-types__ip-address"/>
</element> </element>
</element> </element>
</optional> </optional>
<optional> <optional>
<element name="dhcp:dhcp-options"> <element name="dhcp:dhcp-options">
<a:documentation>Options in the DHCP <a:documentation>
protocol</a:documentation> Options in the DHCP protocol
</a:documentation>
<zeroOrMore> <zeroOrMore>
<element name="dhcp:router" <element name="dhcp:router" nma:ordered-by="user">
nma:ordered-by="user"> <a:documentation>
See: RFC 2132, sec. 3.8
</a:documentation>
<ref name="inet-types__host"/> <ref name="inet-types__host"/>
<a:documentation>See: RFC 2132,
sec. 3.8</a:documentation>
</element> </element>
</zeroOrMore> </zeroOrMore>
<optional> <optional>
<element name="dhcp:domain-name"> <element name="dhcp:domain-name">
<a:documentation>
See: RFC 2132, sec. 3.17
</a:documentation>
<ref name="inet-types__domain-name"/> <ref name="inet-types__domain-name"/>
<a:documentation>See: RFC 2132,
sec. 3.17</a:documentation>
</element> </element>
</optional> </optional>
</element> </element>
</optional> </optional>
<optional> <optional>
<element name="dhcp:max-lease-time" <element name="dhcp:max-lease-time"
nma:default="7200" nma:default="7200" nma:units="seconds">
nma:units="seconds">
<data type="unsignedInt"/> <data type="unsignedInt"/>
</element> </element>
</optional> </optional>
</element> </element>
</zeroOrMore> </zeroOrMore>
</define> </define>
<define name="inet-types__ip-prefix"> <define name="inet-types__ip-prefix">
<choice> <choice>
<ref name="inet-types__ipv4-prefix"/> <ref name="inet-types__ipv4-prefix"/>
<ref name="inet-types__ipv6-prefix"/> <ref name="inet-types__ipv6-prefix"/>
</choice> </choice>
</define> </define>
<define name="inet-types__ipv4-prefix"> <define name="inet-types__ipv4-prefix">
<data type="string"> <data type="string">
<param name="pattern">... removed ...</param> <param name="pattern">... regex pattern ...</param>
</data> </data>
</define> </define>
<define name="inet-types__ipv6-prefix"> <define name="inet-types__ipv6-prefix">
<data type="string"> <data type="string">
<param name="pattern">... removed ...</param> <param name="pattern">... regex pattern ...</param>
</data> </data>
</define> </define>
<define name="inet-types__ip-address"> <define name="inet-types__ip-address">
<choice> <choice>
<ref name="inet-types__ipv4-address"/> <ref name="inet-types__ipv4-address"/>
<ref name="inet-types__ipv6-address"/> <ref name="inet-types__ipv6-address"/>
</choice> </choice>
</define> </define>
<define name="inet-types__ipv4-address"> <define name="inet-types__ipv4-address">
<data type="string"> <data type="string">
<param name="pattern">... removed ...</param> <param name="pattern">... regex pattern ...</param>
</data> </data>
</define> </define>
<define name="inet-types__ipv6-address"> <define name="inet-types__ipv6-address">
<data type="string"> <data type="string">
<param name="pattern">... removed ...</param> <param name="pattern">... regex pattern ...</param>
</data> </data>
</define> </define>
<define name="inet-types__host"> <define name="inet-types__host">
<choice> <choice>
<ref name="inet-types__ip-address"/> <ref name="inet-types__ip-address"/>
<ref name="inet-types__domain-name"/> <ref name="inet-types__domain-name"/>
</choice> </choice>
</define> </define>
<define name="inet-types__domain-name"> <define name="inet-types__domain-name">
<data type="string"> <data type="string">
<param name="pattern">... removed ...</param> <param name="pattern">... regex pattern ...</param>
<param name="pattern">... regex pattern ...</param>
</data> </data>
</define> </define>
<define name="yang-types__date-and-time"> <define name="yang-types__date-and-time">
<data type="string"> <data type="string">
<param name="pattern">... removed ...</param> <param name="pattern">... regex pattern ...</param>
</data> </data>
</define> </define>
<define name="yang-types__phys-address"> <define name="yang-types__phys-address">
<data type="string"> <data type="string"/>
<param name="pattern">... removed ...</param>
</data>
</define> </define>
</grammar> </grammar>
C.2. Compact Syntax C.2.2. Compact Syntax
namespace a = "http://relaxng.org/ns/compatibility/annotations/1.0" namespace a = "http://relaxng.org/ns/compatibility/annotations/1.0"
namespace dc = "http://purl.org/dc/terms" namespace dc = "http://purl.org/dc/terms"
namespace dhcp = "http://example.com/ns/dhcp" namespace dhcp = "http://example.com/ns/dhcp"
namespace nma = "urn:ietf:params:xml:ns:netmod:rng-annot:1" namespace nma = "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1"
namespace nmt = "urn:ietf:params:xml:ns:netmod:tree: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, RELAX NG plugin" ]
dc:source [ "YANG module 'dhcp'" ] dc:source [ "YANG module 'dhcp'" ]
start = start =
element nmt:netmod-tree { element nmt:netmod-tree {
element nmt:top { element nmt:top {
## configuration and operational parameters for a DHCP server. ## configuration and operational parameters for a DHCP server.
element dhcp:dhcp { element dhcp:dhcp {
[ nma:default = "7200" nma:units = "seconds" ] [ nma:default = "7200" nma:units = "seconds" ]
element dhcp:max-lease-time { xsd:unsignedInt }?, element dhcp:max-lease-time { xsd:unsignedInt }?,
[ nma:default = "600" nma:units = "seconds" ] [ nma:default = "600" nma:units = "seconds" ]
element dhcp:default-lease-time { element dhcp:default-lease-time {
skipping to change at page 69, line 17 skipping to change at page 83, line 8
element nmt:top { element nmt:top {
## configuration and operational parameters for a DHCP server. ## configuration and operational parameters for a DHCP server.
element dhcp:dhcp { element dhcp:dhcp {
[ nma:default = "7200" nma:units = "seconds" ] [ nma:default = "7200" nma:units = "seconds" ]
element dhcp:max-lease-time { xsd:unsignedInt }?, element dhcp:max-lease-time { xsd:unsignedInt }?,
[ nma:default = "600" nma:units = "seconds" ] [ nma:default = "600" nma:units = "seconds" ]
element dhcp:default-lease-time { element dhcp:default-lease-time {
xsd:unsignedInt xsd:unsignedInt
>> nma:must [ >> nma:must [
assert = "current() <= ../max-lease-time" assert = ". <= ../dhcp:max-lease-time"
nma:error-message [ nma:error-message [
"The default-lease-time must be less "The default-lease-time must be less than max-lease-time"
than max-lease-time"
] ]
] ]
}?, }?,
dhcp__subnet-list, _dhcp__subnet-list,
element dhcp:shared-networks { element dhcp:shared-networks {
[ nma:key = "name" ] [ nma:key = "dhcp:name" ]
element dhcp:shared-network { element dhcp:shared-network {
element dhcp:name { xsd:string }, element dhcp:name { xsd:string },
dhcp__subnet-list _dhcp__subnet-list
}* }*
}?, }?,
[ nma:config = "false" ] [ nma:config = "false" ]
element dhcp:status { element dhcp:status {
[ nma:key = "address" ] [ nma:key = "dhcp:address" ]
element dhcp:leases { element dhcp:leases {
element dhcp:address { inet-types__ip-address }, element dhcp:address { inet-types__ip-address },
element dhcp:starts { yang-types__date-and-time }?, element dhcp:starts { yang-types__date-and-time }?,
element dhcp:ends { yang-types__date-and-time }?, element dhcp:ends { yang-types__date-and-time }?,
element dhcp:hardware { element dhcp:hardware {
element dhcp:type { "ethernet" | "token-ring" | "fddi" }?, element dhcp:type { "ethernet"
| "token-ring"
| "fddi"
}?,
element dhcp:address { yang-types__phys-address }? element dhcp:address { yang-types__phys-address }?
}? }?
}* }*
}? }?
}? }?
}, },
element nmt:rpc-methods { empty }, element nmt:rpc-methods { empty },
element nmt:notifications { empty } element nmt:notifications { empty }
} }
## A reusable list of subnets ## A reusable list of subnets
dhcp__subnet-list = _dhcp__subnet-list =
[ nma:key = "net" ] [ nma:key = "dhcp:net" ]
element dhcp:subnet { element dhcp:subnet {
element dhcp:net { inet-types__ip-prefix }, element dhcp:net { inet-types__ip-prefix },
element dhcp:range { element dhcp:range {
## Allows BOOTP clients to get addresses in this range ## Allows BOOTP clients to get addresses in this range
element dhcp:dynamic-bootp { empty }?, element dhcp:dynamic-bootp { empty }?,
element dhcp:low { inet-types__ip-address }, element dhcp:low { inet-types__ip-address },
element dhcp:high { inet-types__ip-address } element dhcp:high { inet-types__ip-address }
}?, }?,
## Options in the DHCP protocol ## Options in the DHCP protocol
element dhcp:dhcp-options { element dhcp:dhcp-options {
## See: RFC 2132, sec. 3.8
[ nma:ordered-by = "user" ] [ nma:ordered-by = "user" ]
element dhcp:router { element dhcp:router { inet-types__host }*,
inet-types__host
>> a:documentation [ "See: RFC 2132, sec. 3.8" ] ## See: RFC 2132, sec. 3.17
}*, element dhcp:domain-name { inet-types__domain-name }?
element dhcp:domain-name {
inet-types__domain-name
>> a:documentation [ "See: RFC 2132, sec. 3.17" ]
}?
}?, }?,
[ nma:default = "7200" nma:units = "seconds" ] [ nma:default = "7200" nma:units = "seconds" ]
element dhcp:max-lease-time { xsd:unsignedInt }? element dhcp:max-lease-time { xsd:unsignedInt }?
}* }*
inet-types__ip-prefix = inet-types__ip-prefix =
inet-types__ipv4-prefix | inet-types__ipv6-prefix inet-types__ipv4-prefix | inet-types__ipv6-prefix
inet-types__ipv4-prefix = inet-types__ipv4-prefix =
xsd:string { xsd:string {
pattern = "... removed ..." 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 = inet-types__ipv6-prefix =
xsd:string { xsd:string {
pattern = "... removed ..." 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__ip-address =
inet-types__ipv4-address | inet-types__ipv6-address inet-types__ipv4-address | inet-types__ipv6-address
inet-types__ipv4-address = inet-types__ipv4-address =
xsd:string { xsd:string {
pattern = "... removed ..." 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}]+)?"
} }
inet-types__ipv6-address = inet-types__ipv6-address =
xsd:string { xsd:string {
pattern = "... removed ..." 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}]+)?)"
} }
inet-types__host = inet-types__ip-address | inet-types__domain-name inet-types__host = inet-types__ip-address | inet-types__domain-name
inet-types__domain-name = inet-types__domain-name =
xsd:string { xsd:string {
pattern = "... removed ..." 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]"
} }
yang-types__date-and-time = yang-types__date-and-time =
xsd:string { xsd:string {
pattern = "... removed ..." pattern =
"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}" ~
"(\.d*)?(Z|(\+|-)\d{2}:\d{2})"
} }
yang-types__phys-address = 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
<get> 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.
C.3.1. RELAX NG Schema for <get> Reply - XML Syntax
<?xml version="1.0" encoding="utf-8"?>
<grammar
xmlns="http://relaxng.org/ns/structure/1.0"
xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"
xmlns:dc="http://purl.org/dc/terms"
xmlns:dhcp="http://example.com/ns/dhcp"
xmlns:nma="urn:ietf:params:xml:ns:netmod:dsdl-annotations:1"
xmlns:nmt="urn:ietf:params:xml:ns:netmod:conceptual-tree:1"
datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"
ns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rng:include xmlns:rng="http://relaxng.org/ns/structure/1.0"
href="./relaxng-lib.rng"/>
<start>
<rng:element xmlns:rng="http://relaxng.org/ns/structure/1.0"
name="rpc-reply">
<rng:ref name="message-id-attribute"/>
<rng:element name="data">
<interleave>
<optional>
<element name="dhcp:dhcp">
<optional>
<element name="dhcp:max-lease-time">
<data type="unsignedInt"/>
</element>
</optional>
<optional>
<element name="dhcp:default-lease-time">
<data type="unsignedInt"/>
</element>
</optional>
<ref name="_dhcp__subnet-list"/>
<optional>
<element name="dhcp:shared-networks">
<zeroOrMore>
<element name="dhcp:shared-network">
<element name="dhcp:name">
<data type="string"/>
</element>
<ref name="_dhcp__subnet-list"/>
</element>
</zeroOrMore>
</element>
</optional>
<optional>
<element name="dhcp:status">
<zeroOrMore>
<element name="dhcp:leases">
<element name="dhcp:address">
<ref name="inet-types__ip-address"/>
</element>
<optional>
<element name="dhcp:starts">
<ref name="yang-types__date-and-time"/>
</element>
</optional>
<optional>
<element name="dhcp:ends">
<ref name="yang-types__date-and-time"/>
</element>
</optional>
<optional>
<element name="dhcp:hardware">
<optional>
<element name="dhcp:type">
<choice>
<value>ethernet</value>
<value>token-ring</value>
<value>fddi</value>
</choice>
</element>
</optional>
<optional>
<element name="dhcp:address">
<ref name="yang-types__phys-address"/>
</element>
</optional>
</element>
</optional>
</element>
</zeroOrMore>
</element>
</optional>
</element>
</optional>
</interleave>
</rng:element>
</rng:element>
</start>
<define name="_dhcp__subnet-list">
<zeroOrMore>
<element name="dhcp:subnet">
<element name="dhcp:net">
<ref name="inet-types__ip-prefix"/>
</element>
<optional>
<element name="dhcp:range">
<optional>
<element name="dhcp:dynamic-bootp">
<empty/>
</element>
</optional>
<element name="dhcp:low">
<ref name="inet-types__ip-address"/>
</element>
<element name="dhcp:high">
<ref name="inet-types__ip-address"/>
</element>
</element>
</optional>
<optional>
<element name="dhcp:dhcp-options">
<zeroOrMore>
<element name="dhcp:router">
<ref name="inet-types__host"/>
</element>
</zeroOrMore>
<optional>
<element name="dhcp:domain-name">
<ref name="inet-types__domain-name"/>
</element>
</optional>
</element>
</optional>
<optional>
<element name="dhcp:max-lease-time">
<data type="unsignedInt"/>
</element>
</optional>
</element>
</zeroOrMore>
</define>
<define name="inet-types__ip-prefix">
<choice>
<ref name="inet-types__ipv4-prefix"/>
<ref name="inet-types__ipv6-prefix"/>
</choice>
</define>
<define name="inet-types__ipv4-prefix">
<data type="string">
<param name="pattern">... regex pattern ...</param>
</data>
</define>
<define name="inet-types__ipv6-prefix">
<data type="string">
<param name="pattern">... regex pattern ...</param>
</data>
</define>
<define name="inet-types__ip-address">
<choice>
<ref name="inet-types__ipv4-address"/>
<ref name="inet-types__ipv6-address"/>
</choice>
</define>
<define name="inet-types__ipv4-address">
<data type="string">
<param name="pattern">... regex pattern ...</param>
</data>
</define>
<define name="inet-types__ipv6-address">
<data type="string">
<param name="pattern">... regex pattern ...</param>
</data>
</define>
<define name="inet-types__host">
<choice>
<ref name="inet-types__ip-address"/>
<ref name="inet-types__domain-name"/>
</choice>
</define>
<define name="inet-types__domain-name">
<data type="string">
<param name="pattern">... regex pattern ...</param>
<param name="pattern">... regex pattern ...</param>
</data>
</define>
<define name="yang-types__date-and-time">
<data type="string">
<param name="pattern">... regex pattern ...</param>
</data>
</define>
<define name="yang-types__phys-address">
<data type="string"/>
</define>
</grammar>
C.3.2. RELAX NG Schema for <get> Reply - Compact Syntax
default namespace = "urn:ietf:params:xml:ns:netconf:base:1.0"
namespace a = "http://relaxng.org/ns/compatibility/annotations/1.0"
namespace dc = "http://purl.org/dc/terms"
namespace dhcp = "http://example.com/ns/dhcp"
namespace nma = "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1"
namespace nmt = "urn:ietf:params:xml:ns:netmod:conceptual-tree:1"
include "relaxng-lib.rnc"
start =
element rpc-reply {
message-id-attribute,
element data {
element dhcp:dhcp {
element dhcp:max-lease-time { xsd:unsignedInt }?,
element dhcp:default-lease-time { xsd:unsignedInt }?,
_dhcp__subnet-list,
element dhcp:shared-networks {
element dhcp:shared-network {
element dhcp:name { xsd:string },
_dhcp__subnet-list
}*
}?,
element dhcp:status {
element dhcp:leases {
element dhcp:address { 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 }?
}?
}*
}?
}?
}
}
_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 }?
}*
inet-types__ip-prefix =
inet-types__ipv4-prefix | inet-types__ipv6-prefix
inet-types__ipv4-prefix =
xsd:string { xsd:string {
pattern = "([0-9a0-fA-F]{2}(:[0-9a0-fA-F]{2})*)?" 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 =
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}]+)?"
}
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}]+)?)"
}
inet-types__host = inet-types__ip-address | inet-types__domain-name
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]"
}
yang-types__date-and-time =
xsd:string {
pattern =
"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}" ~
"(\.d*)?(Z|(\+|-)\d{2}:\d{2})"
}
yang-types__phys-address = xsd:string
C.4. Schematron Schema for <get> Reply
<?xml version="1.0" encoding="utf-8"?>
<sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron">
<sch:ns uri="http://example.com/ns/dhcp" prefix="dhcp"/>
<sch:ns uri="urn:ietf:params:xml:ns:netconf:base:1.0"
prefix="nc"/>
<sch:phase id="full">
<sch:active pattern="standard"/>
<sch:active pattern="ref-integrity"/>
</sch:phase>
<sch:phase id="noref">
<sch:active pattern="standard"/>
</sch:phase>
<sch:pattern id="standard">
<sch:rule id="std-id2246197" abstract="true">
<sch:report test="preceding-sibling::dhcp:subnet
[dhcp:net=current()/dhcp:net]">
Duplicate key of list dhcp:subnet
</sch:report>
</sch:rule>
<sch:rule context="/nc:rpc-reply/nc:data/dhcp:dhcp/
dhcp:default-lease-time">
<sch:assert test=". &lt;= ../dhcp:max-lease-time">
The default-lease-time must be less than max-lease-time
</sch:assert>
</sch:rule>
<sch:rule context="/nc:rpc-reply/nc:data/dhcp:dhcp/dhcp:subnet">
<sch:extends rule="std-id2246197"/>
</sch:rule>
<sch:rule context="/nc:rpc-reply/nc:data/dhcp:dhcp/
dhcp:shared-networks/dhcp:shared-network">
<sch:report test="preceding-sibling::dhcp:shared-network
[dhcp:name=current()/dhcp:name]">
Duplicate key of list dhcp:shared-network
</sch:report>
</sch:rule>
<sch:rule context="/nc:rpc-reply/nc:data/dhcp:dhcp/
dhcp:shared-networks/dhcp:shared-network/
dhcp:subnet">
<sch:extends rule="std-id2246197"/>
</sch:rule>
<sch:rule context="/nc:rpc-reply/nc:data/dhcp:dhcp/
dhcp:status/dhcp:leases">
<sch:report test="preceding-sibling::dhcp:leases
[dhcp:address=current()/dhcp:address]">
Duplicate key of list dhcp:leases
</sch:report>
</sch:rule>
</sch:pattern>
<sch:pattern id="ref-integrity"/>
</sch:schema>
C.5. DSRL Schema for <get> Reply
TBD
Appendix D. Change Log
D.1. Changes Between Versions -00 and -01
o Attributes @nma:min-elements and @nma:max-elements are attached to
<rng:element> (list entry) and not to <rng:zeroOrMore> or <rng:
oneOrMore>.
o Keys and all node identifiers in 'key' and 'unique' statements are
prefixed.
o Fixed the mapping of 'rpc' and 'notification'.
o Removed previous Sec. 7.5 "RPC Signatures and Notifications" - the
same information is now contained in Section 10.47 and
Section 10.34.
o Added initial "_" to mangled names of groupings.
o Mandated the use of @xmlns:xxx as the only method for declaring
the target namespace.
o Added section "Handling of XML Namespaces" to explain the previous
item.
o Completed DHCP example in Appendix C.
o Almost all text about the second mapping step is new.
Authors' Addresses Authors' Addresses
Ladislav Lhotka Ladislav Lhotka
CESNET CESNET
Email: lhotka@cesnet.cz Email: lhotka@cesnet.cz
Rohan Mahy Rohan Mahy
Plantronics Plantronics
 End of changes. 218 change blocks. 
543 lines changed or deleted 1627 lines changed or added

This html diff was produced by rfcdiff 1.35. The latest version is available from http://tools.ietf.org/tools/rfcdiff/