draft-ietf-netmod-dsdl-map-01.txt   draft-ietf-netmod-dsdl-map-02.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: September 9, 2009 Plantronics Expires: October 31, 2009 Plantronics
S. Chisholm S. Chisholm
Nortel Nortel
March 8, 2009 April 29, 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-01 draft-ietf-netmod-dsdl-map-02
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 September 9, 2009. This Internet-Draft will expire on October 31, 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 in effect on the date of
(http://trustee.ietf.org/license-info) in effect on the date of publication of this document (http://trustee.ietf.org/license-info).
publication of this document. Please review these documents Please review these documents carefully, as they describe your rights
carefully, as they describe your rights and restrictions with respect 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) and outlines the procedure for validating various types of (DSDL) and outlines the procedure for validating various types of
NETCONF protocol data units using these schemas. NETCONF protocol data units using these schemas.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 6 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6
2. Objectives and Motivation . . . . . . . . . . . . . . . . . . 9 2. Objectives and Motivation . . . . . . . . . . . . . . . . . . 9
3. DSDL Schema Languages . . . . . . . . . . . . . . . . . . . . 11 3. DSDL Schema Languages . . . . . . . . . . . . . . . . . . . . 11
3.1. RELAX NG . . . . . . . . . . . . . . . . . . . . . . . . 11 3.1. RELAX NG . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2. Schematron . . . . . . . . . . . . . . . . . . . . . . . 12 3.2. Schematron . . . . . . . . . . . . . . . . . . . . . . . 12
3.3. Document Semantics Renaming Language (DSRL) . . . . . . . 13 3.3. Document Semantics Renaming Language (DSRL) . . . . . . 13
4. Additional Annotations . . . . . . . . . . . . . . . . . . . . 14 4. Additional Annotations . . . . . . . . . . . . . . . . . . . 14
4.1. Dublin Core Metadata Elements . . . . . . . . . . . . . . 14 4.1. Dublin Core Metadata Elements . . . . . . . . . . . . . 14
4.2. RELAX NG DTD Compatibility Annotations . . . . . . . . . 14 4.2. RELAX NG DTD Compatibility Annotations . . . . . . . . . 14
4.3. NETMOD-specific Annotations . . . . . . . . . . . . . . . 15 4.3. NETMOD-specific Annotations . . . . . . . . . . . . . . 15
5. Overview of the Mapping . . . . . . . . . . . . . . . . . . . 17 5. Overview of the Mapping . . . . . . . . . . . . . . . . . . . 17
6. Design Considerations . . . . . . . . . . . . . . . . . . . . 19 6. NETCONF Content Validation . . . . . . . . . . . . . . . . . 19
6.1. Conceptual Data Tree . . . . . . . . . . . . . . . . . . 19 7. Design Considerations . . . . . . . . . . . . . . . . . . . . 20
6.2. Modularity . . . . . . . . . . . . . . . . . . . . . . . 21 7.1. Conceptual Data Tree . . . . . . . . . . . . . . . . . . 20
6.3. Granularity . . . . . . . . . . . . . . . . . . . . . . . 22 7.2. Modularity . . . . . . . . . . . . . . . . . . . . . . . 22
6.4. Handling of XML Namespaces . . . . . . . . . . . . . . . 22 7.3. Granularity . . . . . . . . . . . . . . . . . . . . . . 23
7. Mapping YANG Data Models to the Conceptual Tree Schema . . . . 24 7.4. Handling of XML Namespaces . . . . . . . . . . . . . . . 23
7.1. Optional and Mandatory Content . . . . . . . . . . . . . 24 8. Mapping YANG Data Models to the Conceptual Tree Schema . . . 25
7.2. Mapping YANG Groupings and Typedefs . . . . . . . . . . . 25 8.1. Optional and Mandatory Content . . . . . . . . . . . . . 25
7.2.1. YANG Refinements and Augments . . . . . . . . . . . 27 8.2. Mapping YANG Groupings and Typedefs . . . . . . . . . . 26
7.2.2. Type derivation chains . . . . . . . . . . . . . . . 30 8.2.1. YANG Refinements and Augments . . . . . . . . . . . 28
7.3. Translation of XPath Expressions . . . . . . . . . . . . 31 8.2.2. Type derivation chains . . . . . . . . . . . . . . 31
7.4. YANG Language Extensions . . . . . . . . . . . . . . . . 32 8.3. Translation of XPath Expressions . . . . . . . . . . . . 32
8. Mapping Conceptual Tree Schema to DSDL . . . . . . . . . . . . 34 8.4. YANG Language Extensions . . . . . . . . . . . . . . . . 33
8.1. Generating RELAX NG Schemas for Various Document Types . 34 9. Mapping Conceptual Tree Schema to DSDL . . . . . . . . . . . 35
8.1.1. Reply to <get> or <get-config> . . . . . . . . . . . 35 9.1. Generating RELAX NG Schemas for Various Document Types . 35
8.1.2. Remote Procedure Calls . . . . . . . . . . . . . . . 35 9.1.1. Reply to <get> or <get-config> . . . . . . . . . . 36
8.1.3. Notifications . . . . . . . . . . . . . . . . . . . 36 9.1.2. Remote Procedure Calls . . . . . . . . . . . . . . 36
8.2. Mapping Semantic Constraints to Schematron . . . . . . . 37 9.1.3. Notifications . . . . . . . . . . . . . . . . . . . 37
8.2.1. Validation Phases . . . . . . . . . . . . . . . . . 40 9.2. Mapping Semantic Constraints to Schematron . . . . . . . 38
8.3. Mapping Default Values to DSRL . . . . . . . . . . . . . 41 9.2.1. Validation Phases . . . . . . . . . . . . . . . . . 41
9. NETCONF Content Validation . . . . . . . . . . . . . . . . . . 42 9.3. Constraints on Mandatory Choice . . . . . . . . . . . . 42
10. Mapping YANG Statements to Annotated RELAX NG . . . . . . . . 43 9.4. Mapping Default Values to DSRL . . . . . . . . . . . . . 44
10.1. The anyxml Statement . . . . . . . . . . . . . . . . . . 43 10. Mapping YANG Statements to Annotated RELAX NG . . . . . . . . 47
10.2. The argument Statement . . . . . . . . . . . . . . . . . 44 10.1. The anyxml Statement . . . . . . . . . . . . . . . . . . 47
10.3. The augment Statement . . . . . . . . . . . . . . . . . . 44 10.2. The argument Statement . . . . . . . . . . . . . . . . . 48
10.4. The base Statement . . . . . . . . . . . . . . . . . . . 45 10.3. The augment Statement . . . . . . . . . . . . . . . . . 48
10.5. The belongs-to Statement . . . . . . . . . . . . . . . . 45 10.4. The base Statement . . . . . . . . . . . . . . . . . . . 49
10.6. The bit Statement . . . . . . . . . . . . . . . . . . . . 45 10.5. The belongs-to Statement . . . . . . . . . . . . . . . . 49
10.7. The case Statement . . . . . . . . . . . . . . . . . . . 45 10.6. The bit Statement . . . . . . . . . . . . . . . . . . . 49
10.8. The choice Statement . . . . . . . . . . . . . . . . . . 45 10.7. The case Statement . . . . . . . . . . . . . . . . . . . 49
10.9. The config Statement . . . . . . . . . . . . . . . . . . 45 10.8. The choice Statement . . . . . . . . . . . . . . . . . . 49
10.10. The contact Statement . . . . . . . . . . . . . . . . . . 45 10.9. The config Statement . . . . . . . . . . . . . . . . . . 49
10.11. The container Statement . . . . . . . . . . . . . . . . . 45 10.10. The contact Statement . . . . . . . . . . . . . . . . . 49
10.12. The default Statement . . . . . . . . . . . . . . . . . . 46 10.11. The container Statement . . . . . . . . . . . . . . . . 50
10.13. The description Statement . . . . . . . . . . . . . . . . 46 10.12. The default Statement . . . . . . . . . . . . . . . . . 50
10.14. The enum Statement . . . . . . . . . . . . . . . . . . . 47 10.13. The description Statement . . . . . . . . . . . . . . . 51
10.15. The error-app-tag Statement . . . . . . . . . . . . . . . 47 10.14. The deviation Statement . . . . . . . . . . . . . . . . 51
10.16. The error-message Statement . . . . . . . . . . . . . . . 47 10.15. The enum Statement . . . . . . . . . . . . . . . . . . . 51
10.17. The extension Statement . . . . . . . . . . . . . . . . . 47 10.16. The error-app-tag Statement . . . . . . . . . . . . . . 51
10.18. The grouping Statement . . . . . . . . . . . . . . . . . 47 10.17. The error-message Statement . . . . . . . . . . . . . . 51
10.19. The identity Statement . . . . . . . . . . . . . . . . . 48 10.18. The extension Statement . . . . . . . . . . . . . . . . 51
10.20. The import Statement . . . . . . . . . . . . . . . . . . 48 10.19. The feature Statement . . . . . . . . . . . . . . . . . 51
10.21. The include Statement . . . . . . . . . . . . . . . . . . 48 10.20. The grouping Statement . . . . . . . . . . . . . . . . . 52
10.22. The input Statement . . . . . . . . . . . . . . . . . . . 48 10.21. The identity Statement . . . . . . . . . . . . . . . . . 52
10.23. The key Statement . . . . . . . . . . . . . . . . . . . . 48 10.22. The if-feature Statement . . . . . . . . . . . . . . . . 52
10.24. The leaf Statement . . . . . . . . . . . . . . . . . . . 48 10.23. The import Statement . . . . . . . . . . . . . . . . . . 52
10.25. The leaf-list Statement . . . . . . . . . . . . . . . . . 49 10.24. The include Statement . . . . . . . . . . . . . . . . . 53
10.26. The length Statement . . . . . . . . . . . . . . . . . . 49 10.25. The input Statement . . . . . . . . . . . . . . . . . . 53
10.27. The list Statement . . . . . . . . . . . . . . . . . . . 50 10.26. The key Statement . . . . . . . . . . . . . . . . . . . 53
10.28. The mandatory Statement . . . . . . . . . . . . . . . . . 50 10.27. The leaf Statement . . . . . . . . . . . . . . . . . . . 53
10.29. The max-elements Statement . . . . . . . . . . . . . . . 50 10.28. The leaf-list Statement . . . . . . . . . . . . . . . . 53
10.30. The min-elements Statement . . . . . . . . . . . . . . . 50 10.29. The length Statement . . . . . . . . . . . . . . . . . . 54
10.31. The module Statement . . . . . . . . . . . . . . . . . . 50 10.30. The list Statement . . . . . . . . . . . . . . . . . . . 54
10.32. The must Statement . . . . . . . . . . . . . . . . . . . 50 10.31. The mandatory Statement . . . . . . . . . . . . . . . . 54
10.33. The namespace Statement . . . . . . . . . . . . . . . . . 51 10.32. The max-elements Statement . . . . . . . . . . . . . . . 54
10.34. The notification Statement . . . . . . . . . . . . . . . 51 10.33. The min-elements Statement . . . . . . . . . . . . . . . 54
10.35. The ordered-by Statement . . . . . . . . . . . . . . . . 51 10.34. The module Statement . . . . . . . . . . . . . . . . . . 55
10.36. The organization Statement . . . . . . . . . . . . . . . 52 10.35. The must Statement . . . . . . . . . . . . . . . . . . . 55
10.37. The output Statement . . . . . . . . . . . . . . . . . . 52 10.36. The namespace Statement . . . . . . . . . . . . . . . . 55
10.38. The path Statement . . . . . . . . . . . . . . . . . . . 52 10.37. The notification Statement . . . . . . . . . . . . . . . 56
10.39. The pattern Statement . . . . . . . . . . . . . . . . . . 52 10.38. The ordered-by Statement . . . . . . . . . . . . . . . . 56
10.40. The position Statement . . . . . . . . . . . . . . . . . 52 10.39. The organization Statement . . . . . . . . . . . . . . . 56
10.41. The prefix Statement . . . . . . . . . . . . . . . . . . 52 10.40. The output Statement . . . . . . . . . . . . . . . . . . 56
10.42. The presence Statement . . . . . . . . . . . . . . . . . 52 10.41. The path Statement . . . . . . . . . . . . . . . . . . . 56
10.43. The range Statement . . . . . . . . . . . . . . . . . . . 52 10.42. The pattern Statement . . . . . . . . . . . . . . . . . 56
10.44. The reference Statement . . . . . . . . . . . . . . . . . 52 10.43. The position Statement . . . . . . . . . . . . . . . . . 57
10.45. The require-instance Statement . . . . . . . . . . . . . 53 10.44. The prefix Statement . . . . . . . . . . . . . . . . . . 57
10.46. The revision Statement . . . . . . . . . . . . . . . . . 53 10.45. The presence Statement . . . . . . . . . . . . . . . . . 57
10.47. The rpc Statement . . . . . . . . . . . . . . . . . . . . 53 10.46. The range Statement . . . . . . . . . . . . . . . . . . 57
10.48. The status Statement . . . . . . . . . . . . . . . . . . 53 10.47. The reference Statement . . . . . . . . . . . . . . . . 57
10.49. The submodule Statement . . . . . . . . . . . . . . . . . 54 10.48. The require-instance Statement . . . . . . . . . . . . . 57
10.50. The type Statement . . . . . . . . . . . . . . . . . . . 54 10.49. The revision Statement . . . . . . . . . . . . . . . . . 57
10.50.1. The empty Type . . . . . . . . . . . . . . . . . . . 55 10.50. The rpc Statement . . . . . . . . . . . . . . . . . . . 58
10.50.2. The boolean and binary Types . . . . . . . . . . . . 55 10.51. The status Statement . . . . . . . . . . . . . . . . . . 58
10.50.3. The bits Type . . . . . . . . . . . . . . . . . . . 55 10.52. The submodule Statement . . . . . . . . . . . . . . . . 58
10.50.4. The enumeration and union Types . . . . . . . . . . 55 10.53. The type Statement . . . . . . . . . . . . . . . . . . . 58
10.50.5. The identityref Type . . . . . . . . . . . . . . . . 55 10.53.1. The empty Type . . . . . . . . . . . . . . . . . . 59
10.50.6. The instance-identifier Type . . . . . . . . . . . . 57 10.53.2. The boolean and binary Types . . . . . . . . . . . 59
10.50.7. The leafref Type . . . . . . . . . . . . . . . . . . 57 10.53.3. The bits Type . . . . . . . . . . . . . . . . . . . 60
10.50.8. The numeric Types . . . . . . . . . . . . . . . . . 57 10.53.4. The enumeration and union Types . . . . . . . . . . 60
10.50.9. The string Type . . . . . . . . . . . . . . . . . . 58 10.53.5. The identityref Type . . . . . . . . . . . . . . . 60
10.50.10. Derived Types . . . . . . . . . . . . . . . . . . . 59 10.53.6. The instance-identifier Type . . . . . . . . . . . 62
10.51. The typedef Statement . . . . . . . . . . . . . . . . . . 59 10.53.7. The leafref Type . . . . . . . . . . . . . . . . . 62
10.52. The unique Statement . . . . . . . . . . . . . . . . . . 60 10.53.8. The numeric Types . . . . . . . . . . . . . . . . . 62
10.53. The units Statement . . . . . . . . . . . . . . . . . . . 60 10.53.9. The string Type . . . . . . . . . . . . . . . . . . 63
10.54. The uses Statement . . . . . . . . . . . . . . . . . . . 60 10.53.10. Derived Types . . . . . . . . . . . . . . . . . . . 64
10.55. The value Statement . . . . . . . . . . . . . . . . . . . 60 10.54. The typedef Statement . . . . . . . . . . . . . . . . . 64
10.56. The when Statement . . . . . . . . . . . . . . . . . . . 60 10.55. The unique Statement . . . . . . . . . . . . . . . . . . 65
10.57. The yang-version Statement . . . . . . . . . . . . . . . 60 10.56. The units Statement . . . . . . . . . . . . . . . . . . 65
10.58. The yin-element Statement . . . . . . . . . . . . . . . . 61 10.57. The uses Statement . . . . . . . . . . . . . . . . . . . 65
10.58. The value Statement . . . . . . . . . . . . . . . . . . 65
10.59. The when Statement . . . . . . . . . . . . . . . . . . . 65
10.60. The yang-version Statement . . . . . . . . . . . . . . . 65
10.61. The yin-element Statement . . . . . . . . . . . . . . . 66
11. Mapping NETMOD-specific annotations to DSDL Schema 11. Mapping NETMOD-specific annotations to DSDL Schema
Languages . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Languages . . . . . . . . . . . . . . . . . . . . . . . . . . 67
11.1. The @nma:config Annotation . . . . . . . . . . . . . . . 62 11.1. The @nma:config Annotation . . . . . . . . . . . . . . . 67
11.2. The @nma:default Annotation . . . . . . . . . . . . . . . 62 11.2. The @nma:default Annotation . . . . . . . . . . . . . . 67
11.3. The @nma:default-case Annotation . . . . . . . . . . . . 62 11.3. The @nma:default-case Annotation . . . . . . . . . . . . 67
11.4. The <nma:error-app-tag> Annotation . . . . . . . . . . . 62 11.4. The <nma:error-app-tag> Annotation . . . . . . . . . . . 67
11.5. The <nma:error-message> Annotation . . . . . . . . . . . 62 11.5. The <nma:error-message> Annotation . . . . . . . . . . . 67
11.6. The <nma:instance-identifier> Annotation . . . . . . . . 62 11.6. The <nma:instance-identifier> Annotation . . . . . . . . 67
11.7. The @nma:key Annotation . . . . . . . . . . . . . . . . . 63 11.7. The @nma:key Annotation . . . . . . . . . . . . . . . . 68
11.8. The <nma:leafref> Annotation . . . . . . . . . . . . . . 63 11.8. The <nma:leafref> Annotation . . . . . . . . . . . . . . 68
11.9. The @nma:min-elements Annotation . . . . . . . . . . . . 64 11.9. The @nma:min-elements Annotation . . . . . . . . . . . . 69
11.10. The @nma:max-elements Annotation . . . . . . . . . . . . 64 11.10. The @nma:max-elements Annotation . . . . . . . . . . . . 69
11.11. The <nma:must> Annotation . . . . . . . . . . . . . . . . 64 11.11. The <nma:must> Annotation . . . . . . . . . . . . . . . 69
11.12. The <nma:ordered-by> Annotation . . . . . . . . . . . . . 64 11.12. The <nma:ordered-by> Annotation . . . . . . . . . . . . 69
11.13. The <nma:status> Annotation . . . . . . . . . . . . . . . 64 11.13. The <nma:status> Annotation . . . . . . . . . . . . . . 69
11.14. The @nma:unique Annotation . . . . . . . . . . . . . . . 64 11.14. The @nma:unique Annotation . . . . . . . . . . . . . . . 70
11.15. The @nma:when Annotation . . . . . . . . . . . . . . . . 65 11.15. The @nma:when Annotation . . . . . . . . . . . . . . . . 70
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 66 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 71
13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 67 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 72
Appendix A. RELAX NG Schema for NETMOD-specific Annotations . . . 69 Appendix A. RELAX NG Schema for NETMOD-specific Annotations . . 74
A.1. XML Syntax . . . . . . . . . . . . . . . . . . . . . . . 69 A.1. XML Syntax . . . . . . . . . . . . . . . . . . . . . . . 74
A.2. Compact Syntax . . . . . . . . . . . . . . . . . . . . . 72 A.2. Compact Syntax . . . . . . . . . . . . . . . . . . . . . 77
Appendix B. Schema-Independent Library . . . . . . . . . . . . . 73 Appendix B. Schema-Independent Library . . . . . . . . . . . . . 78
B.1. XML Syntax . . . . . . . . . . . . . . . . . . . . . . . 73 B.1. XML Syntax . . . . . . . . . . . . . . . . . . . . . . . 78
B.2. Compact Syntax . . . . . . . . . . . . . . . . . . . . . 74 B.2. Compact Syntax . . . . . . . . . . . . . . . . . . . . . 79
Appendix C. Mapping DHCP Data Model - A Complete Example . . . . 75 Appendix C. Mapping DHCP Data Model - A Complete Example . . . . 80
C.1. Input YANG Module . . . . . . . . . . . . . . . . . . . . 75 C.1. Input YANG Module . . . . . . . . . . . . . . . . . . . 80
C.2. Conceptual Tree Schema . . . . . . . . . . . . . . . . . 78 C.2. Conceptual Tree Schema . . . . . . . . . . . . . . . . . 83
C.2.1. XML Syntax . . . . . . . . . . . . . . . . . . . . . 78 C.2.1. XML Syntax . . . . . . . . . . . . . . . . . . . . 83
C.2.2. Compact Syntax . . . . . . . . . . . . . . . . . . . 82 C.2.2. Compact Syntax . . . . . . . . . . . . . . . . . . 87
C.3. Final DSDL Schemas . . . . . . . . . . . . . . . . . . . 85 C.3. Final DSDL Schemas . . . . . . . . . . . . . . . . . . . 90
C.3.1. RELAX NG Schema for <get> Reply - XML Syntax . . . . 85 C.3.1. RELAX NG Schema for <get> Reply - XML Syntax . . . 90
C.3.2. RELAX NG Schema for <get> Reply - Compact Syntax . . 89 C.3.2. RELAX NG Schema for <get> Reply - Compact Syntax . 94
C.4. Schematron Schema for <get> Reply . . . . . . . . . . . . 92 C.4. Schematron Schema for <get> Reply . . . . . . . . . . . 97
C.5. DSRL Schema for <get> Reply . . . . . . . . . . . . . . . 93 C.5. DSRL Schema for <get> Reply . . . . . . . . . . . . . . 98
Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 94 Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 99
D.1. Changes Between Versions -00 and -01 . . . . . . . . . . 94 D.1. Changes Between Versions -01 and -02 . . . . . . . . . . 99
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 95 D.2. Changes Between Versions -00 and -01 . . . . . . . . . . 99
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 101
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 7, line 32 skipping to change at page 7, line 32
"a" DTD compatibility annotations [8] "a" DTD compatibility annotations [8]
"dc" Dublin Core metadata elements [9] "dc" Dublin Core metadata elements [9]
"nc" NETCONF protocol [1] "nc" NETCONF protocol [1]
"en" NETCONF event notifications [10] "en" NETCONF event notifications [10]
"nma" NETMOD-specific schema annotations (see Section 4.3) "nma" NETMOD-specific schema annotations (see Section 4.3)
"nmt" Conceptual tree (see Section 6.1) "nmt" Conceptual tree (see Section 7.1)
"dsrl" Document Semantics Renaming Language [11] "dsrl" Document Semantics Renaming Language [11]
"rng" RELAX NG [12] "rng" RELAX NG [12]
"sch" ISO Schematron [13] "sch" ISO Schematron [13]
"xsd" W3C XML Schema [14] "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
skipping to change at page 15, line 11 skipping to change at page 15, line 11
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
mapped to these annotations in a very straightforward way. In mapped to these annotations in a very straightforward way. With one
particular, the annotation attributes and elements always have the exception - @nma:default-case - the annotation attributes and
same name as the corresponding YANG statement. elements always have the same name as the corresponding YANG
statement.
Table 2 lists alphabetically the names of NETMOD-specific annotation Table 2 lists alphabetically the names of NETMOD-specific annotation
elements (in angle brackets) and attributes (prefixed with "@") along elements (in angle brackets) and attributes (prefixed with "@") along
with a reference to the section where their use is described. with a reference to the section where their use is described.
Appendix A then contains the RELAX NG schema of this annotation Appendix A then contains the RELAX NG schema of this annotation
vocabulary. vocabulary.
+---------------------------+---------+------+ +---------------------------+---------+------+
| annotation | section | note | | annotation | section | note |
+---------------------------+---------+------+ +---------------------------+---------+------+
| @nma:config | 10.9 | | | @nma:config | 10.9 | |
| | | | | | | |
| @nma:default | 10.12 | | | @nma:default | 10.12 | |
| | | | | | | |
| @nma:default-case | 10.7 | | | @nma:default-case | 10.7 | |
| | | | | | | |
| <nma:error-app-tag> | 10.15 | 1 | | <nma:error-app-tag> | 10.16 | 1 |
| | | | | | | |
| <nma:error-message> | 10.16 | 1 | | <nma:error-message> | 10.17 | 1 |
| | | | | | | |
| <nma:instance-identifier> | 10.50.6 | 2 | | <nma:instance-identifier> | 10.53.6 | 2 |
| | | | | | | |
| @nma:key | 10.23 | | | @nma:key | 10.26 | |
| | | | | | | |
| <nma:leafref> | 10.50.7 | 2 | | <nma:leafref> | 10.53.7 | 2 |
| | | | | | | |
| @nma:min-elements | 10.25 | | | @nma:min-elements | 10.28 | |
| | | | | | | |
| @nma:max-elements | 10.25 | | | @nma:max-elements | 10.28 | |
| | | | | | | |
| <nma:must> | 10.32 | 3 | | <nma:must> | 10.35 | 3 |
| | | | | | | |
| @nma:ordered-by | 10.35 | | | @nma:ordered-by | 10.38 | |
| | | | | | | |
| @nma:status | 10.48 | | | @nma:presence | 10.45 | |
| | | | | | | |
| @nma:unique | 10.52 | | | @nma:status | 10.51 | |
| | | | | | | |
| @nma:units | 10.53 | | | @nma:unique | 10.55 | |
| | | | | | | |
| @nma:when | 10.56 | | | @nma:units | 10.56 | |
| | | |
| @nma:when | 10.59 | |
+---------------------------+---------+------+ +---------------------------+---------+------+
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>.
2. Has an optional attribute @require-instance. 2. Has an optional attribute @require-instance.
skipping to change at page 17, line 17 skipping to change at page 17, line 17
This section gives an overview of the YANG-to-DSDL mapping, its This section gives an overview of the YANG-to-DSDL mapping, its
inputs and outputs. Figure 1 presents an overall structure of the inputs and outputs. Figure 1 presents an overall structure of the
mapping: mapping:
+----------------+ +----------------+
| YANG module(s) | | YANG module(s) |
+----------------+ +----------------+
| |
|T |T
| |
+---------------------------------+ +-------------------------------------+
| DSDL schema for conceptual tree | | RELAX NG schema for conceptual tree |
+---------------------------------+ +-------------------------------------+
/ | | \ +-------+
/ | | \ |library|
Tg/ Tr| |Tn \ +-------+
/ | | \ / | | \
/ | | \ +-------+
Tg/ Tr| |Tn \ |library|
/ | | \ +-------+
+---------+ +-----+ +-------+ +------+ +---------+ +-----+ +-------+ +------+
|get reply| | rpc | | notif | | .... | |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 7.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 is transformed in 2. In the second step, the conceptual tree schema is transformed 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
skipping to change at page 18, line 28 skipping to change at page 18, line 28
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
modules. By "virtual" we mean that such an XML document need not modules. By "virtual" we mean that such an XML document need not
correspond to the actual layout of the configuration database in a correspond to the actual layout of the configuration database in a
NETCONF agent, and will certainly never appear on the wire as the NETCONF agent, and will certainly never appear on the wire as the
content of a NETCONF PDU. Hence, the RELAX NG schema for the content of a NETCONF PDU. Hence, the RELAX NG schema for the
conceptual tree is not intended for any direct validations but rather conceptual tree is not intended for any direct validations but rather
as a representation of a particular data model expressed in RELAX NG as a representation of a particular data model expressed in RELAX NG
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 7.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> elements 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).
skipping to change at page 19, line 5 skipping to change at page 19, line 5
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.
6. Design Considerations 6. NETCONF Content Validation
This section describes how the schemas generated by the YANG-to-DSDL
mapping are supposed to be applied for validating XML instance
documents corresponding to various NETCONF PDUs.
The validation proceeds in the following steps, which are also
illustrated in Figure 2:
1. The XML instance document can be immediately checked for
grammatical and data type validity using the RELAX NG schema.
2. Second, the default values for leaves have to be applied and
their ancestor containers added where necessary. It is important
to apply the defaults before the next validation step because
YANG specification [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
The process of substituting default values is complicated by the
rules for non-presence containers and choices in YANG, which may lead
to insertion of entire subtrees in the NETCONF instance document.
Section 9.4 describes how this procedure is represented in DSRL and
how the DSRL schema is obtained from the conceptual tree schema.
7. Design Considerations
YANG modules could be mapped to DSDL schemas in a number of ways. 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 7.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. While the decision about proper client and server schemas. While the decision about proper
skipping to change at page 19, line 39 skipping to change at page 20, line 39
datatype specifications for the datastore, RPCs and notifications datatype specifications for the datastore, RPCs and notifications
expressed by one or more YANG modules have to be translated to RELAX expressed by one or more YANG modules have to be translated to RELAX
NG. In order to be able to separate this common step, we introduce NG. In order to be able to separate this common step, we introduce
the notion of _conceptual data tree_: it is a virtual XML tree that the notion of _conceptual data tree_: it is a virtual XML tree that
contains full datastore, RPC requests with corresponding replies and contains full datastore, RPC requests with corresponding replies and
notifications. The schema for the conceptual tree - a single RELAX notifications. The schema for the conceptual tree - a single RELAX
NG schema with annotations - therefore has a quite similar logic as NG schema with annotations - therefore has a quite similar logic as
the input YANG module(s), the only major difference being the RELAX the input YANG module(s), the only major difference being the RELAX
NG schema language. NG schema language.
The conceptual data tree may be schematically represented as follows: The conceptual data tree for a YANG module defining nodes in the
namespace "http://example.com/ns/example" 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"
xmlns:ex="http://example.com/ns/example">
<nmt:top> <nmt:top>
... configuration and status data ... ... configuration and status data ...
</nmt:top> </nmt:top>
<nmt:rpc-methods> <nmt:rpc-methods>
<nmt:rpc-method> <nmt:rpc-method>
<nmt:input> <nmt:input>
<myrpc ...> <ex:myrpc ...>
... ...
</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> <nmt:notification>
<mynotif> <ex:mynotif>
... ...
</mynotif> </mynotif>
</nmt:notification> </nmt:notification>
... ...
</nmt:notifications> </nmt:notifications>
</nmt:netmod> </nmt:netmod>
The namespace URI "urn:ietf:params:xml:ns:netmod:conceptual-tree:1" The namespace URI "urn:ietf:params:xml:ns:netmod:conceptual-tree:1"
identifies a simple vocabulary consisting of a few elements that identifies a simple vocabulary consisting of a few elements that
encapsulate and separate the various parts of the conceptual data encapsulate and separate the various parts of the conceptual data
skipping to change at page 21, line 12 skipping to change at page 22, line 12
the conceptual tree. In the second phase of the mapping, these the conceptual tree. In the second phase of the mapping, these
annotations are 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 arising 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:top> element. multiple hierarchies appear under the single <nmt:top> element.
6.2. Modularity 7.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:
o In YANG, whenever module A imports module B, it gets access to the o In YANG, whenever module A imports module B, it gets access to the
skipping to change at page 22, line 9 skipping to change at page 23, line 9
translation of importing module - but only if they are really used translation of importing module - but only if they are really used
there. there.
NOTE: The 'include' statement that is used in YANG for including NOTE: The 'include' statement that is used in YANG for including
submodules has in fact the same semantics as the <rng:include> submodules has in fact the same semantics as the <rng:include>
pattern. However, since we don't map the modular structure for YANG pattern. However, since we don't map the modular structure for YANG
modules, it seems to have little sense to do it for submodules. modules, it seems to have little sense to do it for submodules.
Consequently, the contents of submodules appear directly in the Consequently, the contents of submodules appear directly in the
conceptual tree schema, too. conceptual tree schema, too.
6.3. Granularity 7.3. Granularity
RELAX NG supports different styles of schema structuring: One RELAX NG supports different styles of schema structuring: One
extreme, often called "Russian Doll", specifies the structure of an extreme, often called "Russian Doll", specifies the structure of an
XML instance document in a single hierarchy. The other extreme, the XML instance document in a single hierarchy. The other extreme, the
flat style, uses a similar approach as the Data Type Definition (DTD) flat style, uses a similar approach as the Data Type Definition (DTD)
schema language - every XML element is introduced inside a new named schema language - every XML element is introduced inside a new named
pattern. In practice, some compromise between the two extremes is pattern. In practice, some compromise between the two extremes is
usually chosen. usually chosen.
YANG supports both styles in principle, too, but in most cases the YANG supports both styles in principle, too, but in most cases the
skipping to change at page 22, line 38 skipping to change at page 23, 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.
6.4. Handling of XML Namespaces 7.4. Handling of XML Namespaces
Most modern XML schema languages including RELAX NG, Schematron and Most modern XML schema languages including RELAX NG, Schematron and
DSRL support schemas for so-called compound XML documents, which DSRL support schemas for so-called compound XML documents, which
contain elements from multiple namespaces. This is useful for our contain elements from multiple namespaces. This is useful for our
purpose since the YANG-to-DSDL mapping algorithm allows for multiple purpose since the YANG-to-DSDL mapping algorithm allows for multiple
input YANG modules that naturally leads to compound document schemas. input YANG modules that naturally leads to compound document schemas.
RELAX NG offers two alternatives for defining the "target" namespaces RELAX NG offers two alternatives for defining the "target" namespaces
in the schema: in the schema:
skipping to change at page 23, line 18 skipping to change at page 24, line 18
In both cases these attributes are typically attached to the <rng: In both cases these attributes are typically attached to the <rng:
grammar> element. grammar> element.
The design decision for the mapping is to use exclusively the The design decision for the mapping is to use exclusively the
alternative 1, since all YANG modules are represented symmetrically, alternative 1, since all YANG modules are represented symmetrically,
which makes further processing of the conceptual tree schema which makes further processing of the conceptual tree schema
considerably easier. Moreover, this way the namespace prefixes considerably easier. Moreover, this way the namespace prefixes
declared in all input modules are recorded in the resulting schema - declared in all input modules are recorded in the resulting schema -
the prefix for the namespace declared using @ns would be lost. the prefix for the namespace declared using @ns would be lost.
In contrast, there is no choice for Schematron and DSRL since both Analogically, DSRL schemas may declare the default target namespace
schema languages require the target namespaces to be defined by using the @targetNamespace attribute and any number of additional
special means. In Schematron, <sch:ns> subelements of the root <sch: target namespaces via the standard XML attributes xmlns:xxx.
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 In contrast, Schematron requires all the target namespaces to be
defined in the <sch:ns> subelements of the root <sch:schema> element.
8. 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. Its result is an annotated RELAX NG schema of the of the mapping. Its result is an annotated RELAX NG schema of the
conceptual tree, which is described in Section 6.1. conceptual tree, which is described in Section 7.1.
As a special case, if the input YANG modules contain no data nodes As a special case, if the input YANG modules contain no data nodes
(this is typical e.g., for datatype library modules), an (this is typical e.g., for datatype library modules), an
implementation MAY entirely remove the schema of the (empty) implementation MAY entirely remove the schema of the (empty)
conceptual tree - the <rng:start> element with all its contents. The conceptual tree - the <rng:start> element with all its contents. The
output RELAX NG schema will then contain only named pattern output RELAX NG schema will then contain only named pattern
definitions translated from YANG groupings and typedefs. definitions translated from YANG groupings and typedefs.
Detailed specification of the mapping of individual YANG statements Detailed specification of the mapping of individual YANG statements
is contained in Section 10. is contained in Section 10.
7.1. Optional and Mandatory Content 8.1. Optional and Mandatory Content
In YANG, the decision whether a given data node is mandatory or In YANG, the decision whether a given data node is mandatory or
optional is driven by the following rules, see [5], Section 3.1: optional is driven by the following rules, see Section 3.1 in [5]:
Leaf and choice nodes are mandatory if they contain the substatement Leaf and choice nodes are mandatory if they contain the substatement
mandatory true; mandatory true;
For a choice node this means that at least one node from exactly one
case branch must exist.
In addition, leaf nodes are mandatory if they are declared as list In addition, leaf nodes are mandatory if they are declared as list
keys. keys.
Lists or leaf-lists are mandatory if 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
skipping to change at page 25, line 5 skipping to change at page 26, line 5
rule: rule:
A container node is optional if its definition contains the A container node is optional if its definition contains the
'presence' substatement or none of its child nodes is mandatory. 'presence' substatement or none of its child nodes is mandatory.
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 8.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
to take into account. to take into account.
First of all, YANG typedefs and groupings may appear at all levels of First of all, YANG typedefs and groupings may appear at all levels of
the module hierarchy and are subject to lexical scoping, see [5], the module hierarchy and are subject to lexical scoping, see Section
Section 5.5. Moreover, top-level symbols from external modules are 5.5 in [5]. Moreover, top-level symbols from external modules are
imported as qualified names represented using the external module imported as qualified names represented using the external module
namespace prefix and the name of the symbol. In contrast, named namespace prefix and the name of the symbol. In contrast, named
patterns in RELAX NG (both local and imported via the <rng:include> patterns in RELAX NG (both local and imported via the <rng:include>
pattern) share the same namespace and within a grammar they are pattern) share the same namespace and within a grammar they are
always global - their definitions may only appear at the top level as always global - their definitions may only appear at the top level as
children of the <rng:grammar> element. Consequently, whenever YANG children of the <rng:grammar> element. Consequently, whenever YANG
groupings and typedefs are mapped to RELAX NG named pattern groupings and typedefs are mapped to RELAX NG named pattern
definitions, their names MUST be disambiguated in order to avoid definitions, their names MUST be disambiguated in order to avoid
naming conflicts. The mapping uses the following procedure for naming conflicts. The mapping uses the following procedure for
mangling the names of groupings and type definitions: mangling the names of groupings and type definitions:
skipping to change at page 26, line 7 skipping to change at page 27, line 7
o Since the names of groupings and typedefs in YANG have different o Since the names of groupings and typedefs in YANG have different
namespaces, an additional underline character is added to the namespaces, an additional underline character is added to the
front of the mangled names of all groupings. 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" [20]: 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]*";
} }
} }
grouping "grp1" { grouping "grp1" {
leaf "void" { leaf "void" {
skipping to change at page 27, line 46 skipping to change at page 28, line 46
<rng:param name="pattern">... regex pattern ...</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">... regex pattern ...</param> <rng:param name="pattern">... regex pattern ...</param>
</rng:data> </rng:data>
</rng:define> </rng:define>
7.2.1. YANG Refinements and Augments 8.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
statements for this purpose that may appear as substatements of statements for this purpose that may appear as substatements of
'uses': 'uses':
o 'refine' statement allows for changing parameters of a schema node o 'refine' statement allows for changing parameters of a schema node
skipping to change at page 28, line 20 skipping to change at page 29, line 20
o 'augment' statement can be used for adding new schema nodes to the o 'augment' statement can be used for adding new schema nodes to the
grouping content. grouping content.
Both 'refine' and 'augment' statements are quite powerful in that Both 'refine' and 'augment' statements are quite powerful in that
they can address, using a subset of XPath 1.0 expressions as they can address, using a subset of XPath 1.0 expressions as
arguments, schema nodes that are arbitrarily deep inside the grouping arguments, schema nodes that are arbitrarily deep inside the grouping
content. In contrast, definitions of named patterns in RELAX NG content. In contrast, definitions of named patterns in RELAX NG
operate exclusively at the topmost level of the named pattern operate exclusively at the topmost level of the named pattern
content. In order to achieve a modifiability of named patterns content. In order to achieve a modifiability of named patterns
comparable to YANG, the RELAX NG schema would have to be extremely comparable to YANG, the RELAX NG schema would have to be extremely
flat (cf. Section 6.3) and very difficult to read. flat (cf. Section 7.3) and very difficult to read.
Since the goal of the mapping described in this document is to Since the goal of the mapping described in this document is to
generate ad hoc DSDL schemas, we decided to avoid these complications generate ad hoc DSDL schemas, we decided to avoid these complications
and instead expand the grouping and refine and/or augment it "in and instead expand the grouping and refine and/or augment it "in
place". In other words, every 'uses' statement which has 'refine' place". In other words, every 'uses' statement which has 'refine'
and/or 'augment' substatements is virtually replaced by the content and/or 'augment' substatements is virtually replaced by the content
of the corresponding grouping, the changes specified in the 'refine' of the corresponding grouping, the changes specified in the 'refine'
and 'augment' statements are applied and the resulting YANG schema and 'augment' statements are applied and the resulting YANG schema
fragment is mapped as if the 'uses'/'grouping' indirection wasn't fragment is mapped as if the 'uses'/'grouping' indirection wasn't
there. there.
skipping to change at page 30, line 26 skipping to change at page 31, line 26
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 8.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
adding new restrictions. Therefore, when mapping YANG derived types adding new restrictions. Therefore, when mapping YANG derived types
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.
skipping to change at page 31, line 46 skipping to change at page 32, line 46
The output RELAX NG schema then won't contain any named pattern The output RELAX NG schema then won't contain any named pattern
definition and leaf "month" will be mapped directly to definition and leaf "month" will be mapped directly to
<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 8.3. Translation of XPath Expressions
YANG uses full XPath 1.0 syntax [18] 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 name of a data node always belongs to the However, since the name of a data node always belongs to the
namespace of the YANG Module where the data node is defined, YANG namespace of the YANG Module where the data node is defined, YANG
adopted a simplification similar to the concept of _default adopted a simplification similar to the concept of _default
namespace_ in XPath 2.0: node names needn't carry a namespace prefix namespace_ in XPath 2.0: node names needn't carry a namespace prefix
inside the module where they are defined, in which case the module's inside the module where they are defined, in which case the module's
namespace is assumed. namespace is assumed.
skipping to change at page 32, line 19 skipping to change at page 33, line 19
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 [18], sections 7.5.3 and 7.19.5. expressions, see [5], sections 7.5.3 and 7.19.5.
Translation rule 2 means for example that absolute XPath expressions Translation rule 2 means for example that absolute XPath expressions
appearing in the main configuration data tree always start with "nmt: appearing in the main configuration data tree always start with "nmt:
netmod-tree/nmt:top/", those appearing in a notification always start netmod-tree/nmt:top/", those appearing in a notification always start
with "nmt:netmod-tree/nmt:notifications/nmt:notification/", etc. with "nmt:netmod-tree/nmt:notifications/nmt:notification/", 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:top/dhcp:dhcp/dhcp:max-lease-time". nmt:top/dhcp:dhcp/dhcp:max-lease-time".
skipping to change at page 32, line 43 skipping to change at page 33, line 43
dhcp:max-lease-time".] dhcp:max-lease-time".]
The key identifiers and "descendant schema node identifiers" (see the The key identifiers and "descendant schema node identifiers" (see the
ABNF production for "descendant-schema-nodeid" in Section 12 of [5]) ABNF production for "descendant-schema-nodeid" in Section 12 of [5])
that appear as items in the arguments of 'key' and 'unique' that appear as items in the arguments of 'key' and 'unique'
statements, respectively, are special XPath expressions and MUST be statements, respectively, are special XPath expressions and MUST be
translated in the same way, i.e., after the translation each key and translated in the same way, i.e., after the translation each key and
every component of a node identifier must have the namespace prefix every component of a node identifier must have the namespace prefix
of the local module. of the local module.
7.4. YANG Language Extensions 8.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 34, line 5 skipping to change at page 35, 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.
8. Mapping Conceptual Tree Schema to DSDL 9. Mapping Conceptual Tree Schema to DSDL
As explained in Section 5, the second step of the YANG-to-DSDL As explained in Section 5, the second step of the YANG-to-DSDL
mapping takes the conceptual tree schema and transforms it to various mapping takes the conceptual tree schema and transforms it to various
DSDL schemas ready for validation. As an input parameter, this step DSDL schemas ready for validation. As an input parameter, this step
gets in the simplest case a specification of the NETCONF XML document gets in the simplest case a specification of the NETCONF XML document
type (or combination of multiple types) that is to be validated. type (or combination of multiple types) that is to be validated.
These document type can be for example reply to <nc:get> or <nc:get- These document type can be for example reply to <nc:get> or <nc:get-
config>, RPC requests or replies and notification. Other parameters config>, RPC requests or replies and notification. Other parameters
further describing the context may also be provided, such as the list further describing the context may also be provided, such as the list
of active capabilities, features etc. of active capabilities, features etc.
skipping to change at page 34, line 43 skipping to change at page 35, line 43
These three tasks are together much simpler than the first mapping These three tasks are together much simpler than the first mapping
step. Presumably, they can be effectively realized using XSL step. Presumably, they can be effectively realized using XSL
transformations [19]. transformations [19].
The following subsections describe the details of the second mapping The following subsections describe the details of the second mapping
step for the individual DSDL schema languages. Section 11 then step for the individual DSDL schema languages. Section 11 then
contains a detailed specification for the mapping of all NETMOD- contains a detailed specification for the mapping of all NETMOD-
specific annotations. specific annotations.
8.1. Generating RELAX NG Schemas for Various Document Types 9.1. Generating RELAX NG Schemas for Various Document Types
With one minor exception, obtaining a validating RELAX NG schema from With one minor exception, obtaining a validating RELAX NG schema from
the conceptual tree schema really means only taking appropriate parts the conceptual tree schema really means only taking appropriate parts
from the conceptual tree schema and assembling them in a new RELAX NG from the conceptual tree schema and assembling them in a new RELAX NG
grammar, perhaps after removing all unwanted annotations. Depending grammar, perhaps after removing all unwanted annotations. Depending
on the XML document type that is the target for validation (<get>/ on the XML document type that is the target for validation (<get>/
<get-config> reply, RPC or notification) a corresponding top-level <get-config> reply, RPC or notification) a corresponding top-level
part of the grammar MUST be added as described in the following part of the grammar MUST be added as described in the following
subsections. subsections.
skipping to change at page 35, line 21 skipping to change at page 36, line 21
collected in a library file "relang-lib.rng" which is then included collected in a library file "relang-lib.rng" which is then included
by the validating RELAX NG schemas. Appendix B has the listing of by the validating RELAX NG schemas. Appendix B has the listing of
this library file. this library file.
The minor exception mentioned above is the annotation @nma:config, The minor exception mentioned above is the annotation @nma:config,
which must be observed if the target document type is <get-config> which must be observed if the target document type is <get-config>
reply. In this case, each element definition that has this attribute reply. In this case, each element definition that has this attribute
with the value "false" MUST be removed from the schema together with with the value "false" MUST be removed from the schema together with
its descendants. See Section 11.1 for more details. its descendants. See Section 11.1 for more details.
8.1.1. Reply to <get> or <get-config> 9.1.1. Reply to <get> or <get-config>
For a reply to <get> or <get-config>, the mapping must take the part 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 of the conceptual tree schema under the definition of <nmt:top> and
insert it in the following grammar: insert it in the following grammar:
<rng:grammar ... namespaces etc. ...> <rng:grammar ... namespaces etc. ...>
<rng:include href="relaxng-lib.rng"/> <rng:include href="relaxng-lib.rng"/>
<rng:start> <rng:start>
<rng:element name="nc:rpc-reply"> <rng:element name="nc:rpc-reply">
<rng:ref name="message-id-attribute"/> <rng:ref name="message-id-attribute"/>
skipping to change at page 35, line 49 skipping to change at page 36, line 49
The definition for the named pattern "message-id-attribute" is found The definition for the named pattern "message-id-attribute" is found
in the library file "relaxng-lib.rng" which is included on the second in the library file "relaxng-lib.rng" which is included on the second
line (see Appendix B). line (see Appendix B).
Definitions of other named patterns MUST be copied from the Definitions of other named patterns MUST be copied from the
conceptual tree schema without any changes to the resulting grammar. conceptual tree schema without any changes to the resulting grammar.
However, an implementation MAY choose to copy only those definitions However, an implementation MAY choose to copy only those definitions
that are really used in the particular output grammar. that are really used in the particular output grammar.
8.1.2. Remote Procedure Calls 9.1.2. Remote Procedure Calls
For an RPC method named "myrpc" and defined in a YANG module with For an RPC method named "myrpc" and defined in a YANG module with
prefix "yam", the corresponding schema subtree is identified by the prefix "yam", the corresponding schema subtree is identified by the
definition of <nmt:rpc-method> element whose <nmt:input> subelement definition of <nmt:rpc-method> element whose <nmt:input> subelement
has <yam:myrpc> as the only child. has <yam:myrpc> as the only child.
The mapping must also take into account whether the target document The mapping must also take into account whether the target document
type in an RPC request or reply. For "yam:myrpc" request, the type in an RPC request or reply. For "yam:myrpc" request, the
resulting grammar looks as follows: resulting grammar looks as follows:
skipping to change at page 36, line 43 skipping to change at page 37, line 43
... "nmt:rpc-method/nmt:output" subtree ... ... "nmt:rpc-method/nmt:output" subtree ...
</rng:element> </rng:element>
</rng:start> </rng:start>
... named pattern definitions ... ... named pattern definitions ...
</rng:grammar> </rng:grammar>
In both cases, exact copies of named pattern definitions from the In both cases, exact copies of named pattern definitions from the
conceptual tree schema MUST be inserted, but an implementation MAY conceptual tree schema MUST be inserted, but an implementation MAY
choose to include only those used for the given RPC. choose to include only those used for the given RPC.
8.1.3. Notifications 9.1.3. Notifications
For a notification named "mynotif" and defined in a YANG module with For a notification named "mynotif" and defined in a YANG module with
prefix "yam", the corresponding schema subtree is identified by the prefix "yam", the corresponding schema subtree is identified by the
definition of <nmt:notification> element that has the single child definition of <nmt:notification> element that has the single child
<yam:mynotif>. <yam:mynotif>.
The resulting grammar looks as follows: The resulting grammar looks as follows:
<rng:grammar ... namespaces etc. ...> <rng:grammar ... namespaces etc. ...>
<rng:include href="relaxng-lib.rng"/> <rng:include href="relaxng-lib.rng"/>
skipping to change at page 37, line 26 skipping to change at page 38, line 26
<!-- named pattern definitions --> <!-- named pattern definitions -->
</rng:grammar> </rng:grammar>
The definition of the named pattern "eventTime-element" is found in The definition of the named pattern "eventTime-element" is found in
the "relaxng-lib.rng" library file. the "relaxng-lib.rng" library file.
And again, exact copies of named pattern definitions from the And again, exact copies of named pattern definitions from the
conceptual tree schema MUST be inserted, but an implementation MAY conceptual tree schema MUST be inserted, but an implementation MAY
choose to include only those used for the given notification. choose to include only those used for the given notification.
8.2. Mapping Semantic Constraints to Schematron 9.2. Mapping Semantic Constraints to Schematron
Schematron schemas tend to be much flatter and more uniform compared Schematron schemas tend to be much flatter and more uniform compared
to RELAX with exactly four levels of XML hierarchy: <sch:schema>, to RELAX with exactly four levels of XML hierarchy: <sch:schema>,
<sch:pattern>, <sch:rule> and <sch:assert> or <sch:report>. <sch:pattern>, <sch:rule> and <sch:assert> or <sch:report>.
In a Schematron schema generated by the second mapping step, the In a Schematron schema generated by the second mapping step, the
basic unit of organization is a _rule_ represented by the <sch:rule> basic unit of organization is a _rule_ represented by the <sch:rule>
element. Every rule corresponds to exactly one element definition in element. Every rule corresponds to exactly one element definition in
the conceptual tree schema. The mandatory @context attribute of the conceptual tree schema. The mandatory @context attribute of
<sch:rule> is set to the absolute path of the corresponding element <sch:rule> is set to the absolute path of the corresponding element
skipping to change at page 37, line 49 skipping to change at page 38, line 49
In the opposite direction, however, not every element definition has In the opposite direction, however, not every element definition has
a corresponding rule in the Schematron schema: only those definitions a corresponding rule in the Schematron schema: only those definitions
are taken into account that are annotated with at least one of the are taken into account that are annotated with at least one of the
following NETMOD-specific annotations: <nma:instance-identifier>, following NETMOD-specific annotations: <nma:instance-identifier>,
@nma:key, <nma:leafref>, @nma:min-elements, @nma:max-elements, <nma: @nma:key, <nma:leafref>, @nma:min-elements, @nma:max-elements, <nma:
must>, @nma:unique and <nma:when>. must>, @nma:unique and <nma:when>.
Schematron rules may be further grouped into _patterns_ represented Schematron rules may be further grouped into _patterns_ represented
by the <sch:pattern> element. The mapping uses patterns only for by the <sch:pattern> element. The mapping uses patterns only for
discriminating between subsets of rules that belong to different discriminating between subsets of rules that belong to different
validation phases, see Section 8.2.1. Therefore, the <sch:schema> validation phases, see Section 9.2.1. Therefore, the <sch:schema>
always has exactly two <sch:pattern> children: one named "standard" always has exactly two <sch:pattern> children: one named "standard"
contains rules for all annotations except <nma:instance-identifier> contains rules for all annotations except <nma:instance-identifier>
and <nma:leafref>, and another named "ref-integrity" containing rules and <nma:leafref>, and another named "ref-integrity" containing rules
for these two remaining annotations, i.e., referential integrity for these two remaining annotations, i.e., referential integrity
checks. checks.
Element definitions in the conceptual tree schema that appear inside Element definitions in the conceptual tree schema that appear inside
a named pattern definition (i.e., have <rng:define> among its a named pattern definition (i.e., have <rng:define> among its
ancestors) are subject to a different treatment. This is because ancestors) are subject to a different treatment. This is because
their path in the data tree is not fixed - the named pattern may be their path in the data tree is not fixed - the named pattern may be
skipping to change at page 39, line 45 skipping to change at page 40, line 45
This procedure is identical to the RELAX NG case, including the This procedure is identical to the RELAX NG case, including the
handling of @nma:config if the target document type is <get- handling of @nma:config if the target document type is <get-
config> reply. config> reply.
2. Namespaces of all input YANG modules, together with the 2. Namespaces of all input YANG modules, together with the
namespaces of base NETCONF ("nc" prefix) or notifications ("en" namespaces of base NETCONF ("nc" prefix) or notifications ("en"
prefix) MUST be declared using the <sch:ns> element, for example prefix) MUST be declared using the <sch:ns> element, for example
<sch:ns uri="http://example.com/ns/dhcp" prefix="dhcp"/> <sch:ns uri="http://example.com/ns/dhcp" prefix="dhcp"/>
3. Validation phases are defined (see Section 8.2.1) and their 3. Validation phases are defined (see Section 9.2.1) and their
constituting patterns "standard" and "ref-integrity" created. constituting patterns "standard" and "ref-integrity" created.
4. For either validation phase, the input conceptual tree schema is 4. For either validation phase, the input conceptual tree schema is
scanned and element definitions with annotations relevant for the scanned and element definitions with annotations relevant for the
given phase are selected and a <sch:rule> is created for each of given phase are selected and a <sch:rule> is created for each of
them. The rule is abstract if the element definition appears them. The rule is abstract if the element definition appears
inside a named pattern, see above. inside a named pattern, see above.
5. All annotations attached to the given element definition are then 5. All annotations attached to the given element definition are then
mapped using the mapping rules specified in Section 11. The mapped using the mapping rules specified in Section 11. The
resulting <sch:assert> or <sch:report> elements are the installed resulting <sch:assert> or <sch:report> elements are the installed
as children of the <sch:rule> element. as children of the <sch:rule> element.
8.2.1. Validation Phases 9.2.1. Validation Phases
In certain situations it is useful to validate XML instance documents In certain situations it is useful to validate XML instance documents
without enforcing the referential integrity constraints represented without enforcing the referential integrity constraints represented
by the <nma:leafref> and <nma:instance-identifier> annotations. For by the <nma:leafref> and <nma:instance-identifier> annotations. For
example, a candidate configuration refering to configuration example, a candidate configuration referring to configuration
parameters or state data of certain hardware will not pass full parameters or state data of certain hardware will not pass full
validation before the hardware is installed. To handle this, the validation before the hardware is installed. To handle this, the
Schematron mapping introduces two _validation phases_: Schematron mapping introduces two _validation phases_:
o Validation phase "full", which is the default, checks all semantic o Validation phase "full", which is the default, checks all semantic
constraints. constraints.
o Validation phase "noref" is the same as "full" except it doesn't o Validation phase "noref" is the same as "full" except it doesn't
check referential integrity constraints. check referential integrity constraints.
skipping to change at page 41, line 23 skipping to change at page 42, line 23
<sch:active pattern="standard"/> <sch:active pattern="standard"/>
</sch:phase> </sch:phase>
<sch:pattern id="standard"> <sch:pattern id="standard">
... all rules except ref. integrity checks ... ... all rules except ref. integrity checks ...
</sch:pattern> </sch:pattern>
<sch:pattern id="ref-integrity"> <sch:pattern id="ref-integrity">
... rules for ref. integrity checks ... ... rules for ref. integrity checks ...
</sch:pattern> </sch:pattern>
</sch:schema> </sch:schema>
8.3. Mapping Default Values to DSRL 9.3. Constraints on Mandatory Choice
TBD In order to fully represent the semantics of YANG 'choice' statement
with "mandatory true;" substatement, the RELAX NG grammar has to be
combined with a special Schematron rule. Consider the following
module:
9. NETCONF Content Validation module example4 {
namespace "http://example.com/ns/example4";
prefix ex4;
choice foobar {
mandatory true;
case foo {
leaf foo1 {
type uint8;
}
leaf foo2 {
type uint8;
}
}
leaf bar {
type uint8;
}
}
}
This section describes the procedures for validating XML instance In this module, all three leaf nodes in both case branches are
documents corresponding to various NETCONF PDUs given the set of DSDL optional but because of the "mandatory true;" statement, at least one
schemas generated for the particular document type. of them must be present in a valid configuration. The 'choice'
statement from this module is mapped to the following fragment of the
conceptual tree schema:
[Editor's note: This section is incomplete. We have to figure out <rng:choice>
what are the NETCONF instances we want to validate, and also the <rng:group>
validation contexts and modes. However, these questions are not <rng:optional>
DSDL-specific and should be addressed by the WG.] <rng:element name="ex4:foo1">
<rng:data type="unsignedByte"/>
</rng:element>
</rng:optional>
<rng:optional>
<rng:element name="ex4:foo2">
<rng:data type="unsignedByte"/>
</rng:element>
</rng:optional>
</rng:group>
<rng:element name="ex4:bar">
<rng:data type="unsignedByte"/>
</rng:element>
</rng:choice>
The validation proceeds in the following steps, see also Figure 2: In the second case branch, the "ex4:bar" element is defined as
mandatory so that this element must be present in a valid
configuration if this branch is selected. However, the two elements
in the first branch "foo" cannot be both declared as mandatory since
each one of them alone suffices for a valid configuration. As a
result, the above RELAX NG fragment would successfully validate
configurations where none of the three leafs elements is present.
1. The XML instance document can be immediately checked for Therefore, mandatory choices, which can be recognized in the
grammatical and data type validity using the RELAX NG schema. conceptual tree schema as <rng:choice> elements that do not have
<optional> as their parent, have to be handled in a special way: For
each mandatory choice where at least one of the cases contains more
than one node, a rule MUST be present in the "standard" pattern of
the Schematron schema enforcing the presence of at least one element
from any of the cases. (RELAX NG schema guarantees that elements
from different cases cannot be mixed together, that all mandatory
nodes are present etc.).
2. Second, the default values for leaves and default cases have to For the example module above, the Schematron rule can be as follows:
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. <sch:rule context="/nc:rpc-reply/nc:data">
<sch:assert test="ex4:foo1 or ex4:foo2 or ex4:bar">
Node(s) from at least one case of choice "foobar" must exist.
</sch:assert>
</sch:rule>
+----------+ +----------+ 9.4. Mapping Default Values to DSRL
| | | 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 DSRL is the only component of DSDL that changes the information set
of the validated XML document. While DSRL has other functions, the
YANG-to-DSDL mapping uses it only for specifying default content.
For XML instance documents based on YANG data model, insertion of
default content in general includes not only default values for leaf
elements but also containers without presence. The following
definition helps in explaining the steps needed for generating the
DSRL schema.
For a given conceptual tree schema and XML instance document, we
define _implicit element_ to be an element that is inserted in the
process of substituting the default content, provided that its parent
element exists in the instance document.
Now, let C be a conceptual tree schema and D a NETCONF instance
document. Denote R the RELAX NG schema for the document type of D,
which is generated form C and assume D is a valid XML document with
respect to R. Let P be an element appearing in D. According to the
YANG rules, an element E, which is defined as an optional child of P
in the data tree, is an implicit element if and only if it is either
a leaf element whose definition in C has a default value specified
in the @nma:default attribute, or
a container element that does not have the @nma:presence attribute
set to "true" in C and at least one of its children in the data
tree is an implicit element.
Element E has to satisfy additional conditions in the following two
special cases in order to be an implicit element, regardless of
whether it is a leaf or container:
o If E is defined in C inside an alternative of <rng:choice>, then
this alternative must be marked as the default one with @nma:
default-case="true" in C.
o If the definition of E in C carries the @nma:when attribute, then
the condition in the value of @nma:when must be true in the
context of the instance document D.
In DSRL, the default content of an element is specified using the
<dsrl:default-content> element, which is a child of <dsrl:element>.
Two sibling elements of <dsrl:default-content> determine the context
for application of the default content, see [11]:
o <dsrl:parent> element contains an XSLT pattern specifying the
parent element; the default content is applied only if the parent
element exists in the instance document.
o <dsrl:name> contains the XML name of the element which is inserted
together with the content of <dsrl:default-content>.
The <dsrl:parent> element is optional in a general DSRL schema but
for the purpose of the YANG-to-DSDL mapping this element MUST be
always present in order to guarantee proper application of default
content.
The logic of DSRL implies that for every non-leaf element P (implicit
or not) containing at least one implicit element among its children,
the DSRL schema must provide one element map for each implicit child
element E, where the full XPath of P appears in the <dsrl:parent>
element and the name of E in <dsrl:name>.
EXAMPLE. Consider the following YANG module:
module example5 {
namespace "http://example.com/ns/example5";
prefix ex5;
container outer {
leaf leaf1 {
type uint8;
default "1";
}
choice one-or-two {
default "one";
container one {
leaf leaf2 {
type uint8;
default "2";
}
}
leaf leaf3 {
type uint8;
default "3";
}
}
}
}
The DSRL schema generated for the "get-reply" target document type
will be:
<dsrl:maps xmlns:dsrl="http://purl.oclc.org/dsdl/dsrl"
xmlns:ex5="http://example.com/ns/example5"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<dsrl:element-map>
<dsrl:parent>/nc:rpc-reply/nc:data/</dsrl:parent>
<dsrl:name>ex5:outer</dsrl:name>
<dsrl:default-content>
<ex5:leaf1>1</ex5:leaf1>
</dsrl:default-content>
</dsrl:element-map>
<dsrl:element-map>
<dsrl:parent>/nc:rpc-reply/nc:data/</dsrl:parent>
<dsrl:name>ex5:one</dsrl:name>
<dsrl:default-content>
<ex5:leaf2>2</ex5:leaf2>
</dsrl:default-content>
</dsrl:element-map>
<dsrl:element-map>
<dsrl:parent>/nc:rpc-reply/nc:data/ex5:outer</dsrl:parent>
<dsrl:name>ex5:leaf1</dsrl:name>
<dsrl:default-content>1</dsrl:default-content>
</dsrl:element-map>
<dsrl:element-map>
<dsrl:parent>/nc:rpc-reply/nc:data/ex5:outer</dsrl:parent>
<dsrl:name>ex5:one</dsrl:name>
<dsrl:default-content>
<ex5:leaf2>2</ex5:leaf2>
</dsrl:default-content>
</dsrl:element-map>
<dsrl:element-map>
<dsrl:parent>/nc:rpc-reply/nc:data/ex5:outer/ex5:one</dsrl:parent>
<dsrl:name>ex5:leaf2</dsrl:name>
<dsrl:default-content>2</dsrl:default-content>
</dsrl:element-map>
</dsrl:maps>
Note that the default value for "leaf3" defined in the YANG module is
ignored, because "leaf3" represents a non-default alternative of a
choice and as such can never become an implicit element.
Since DSRL has no facilities similar to named patterns in RELAX NG,
their definitions used in the conceptual tree schema must be expanded
in all places where they are referenced.
10. Mapping YANG Statements to Annotated RELAX NG 10. Mapping YANG Statements to 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
provides the specification how the statement is mapped to the provides the specification how the statement is mapped to the
annotated RELAX NG schema of the conceptual tree. This is the first annotated RELAX NG schema of the conceptual tree. This is the first
step of the mapping procedure, see Section 5. The subsections are step of the mapping procedure, see Section 5. The subsections are
sorted alphabetically 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.
YANG XML encoding rules translate to the following rules for ordering
multiple subelements:
1. Within the <nmt:rpc-methods> subtree (i.e., for RPC input and
output parameters) the order of subelements is fixed and their
definitions in the conceptual tree schema MUST follow the order
specified in the source YANG module.
2. When mapping the 'list' statement, all keys MUST come before any
other subelements and in the same order as they are declared in
the 'key' statement. The order of the remaining (non-key)
subelements is not specified, so their definitions in the
conceptual tree schema MUST be enclosed in the <rng:interleave>
element.
3. Otherwise, all definitions of subelements in the conceptual tree
schema MUST be enclosed in the <rng:interleave> element.
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.
o The element in the RELAX NG schema that becomes the parent of the o The element in the RELAX NG schema that becomes the parent of the
resulting XML fragment is denoted by PARENT. resulting XML fragment is denoted by PARENT.
10.1. The anyxml Statement 10.1. The anyxml Statement
This statement is mapped to <rng:element> element and ARGUMENT This statement is mapped to <rng:element> element and ARGUMENT
becomes the value of its @name attribute. The content of <rng: becomes the value of its @name attribute. The content of <rng:
skipping to change at page 44, line 36 skipping to change at page 48, line 43
maps to the following fragment: maps to the following fragment:
<rng:element name="data"> <rng:element name="data">
<a:documentation>Any XML content allowed here</a:documentation> <a:documentation>Any XML content allowed here</a:documentation>
<rng:ref name="__anyxml__"/> <rng:ref name="__anyxml__"/>
</rng:element> </rng:element>
10.2. The argument Statement 10.2. The argument 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 8.4.
10.3. The augment Statement 10.3. The augment Statement
As a substatement of 'uses', this statement is handled as a part of As a substatement of 'uses', this statement is handled as a part of
'uses' mapping, see Section 10.54. 'uses' mapping, see Section 10.57.
At the top level of a module or submodule, the 'augment' statement is At the top level of a module or submodule, the 'augment' statement is
used for augmenting the schema tree of another YANG module. If the used for augmenting the schema tree of another YANG module. If the
latter module is not processed within the same mapping session, the latter module is not processed within the same mapping session, the
top-level 'augment' statement MUST be ignored. Otherwise, the top-level 'augment' statement MUST be ignored. Otherwise, the
contents of the statement are added to the foreign module with the contents of the statement are added to the foreign module with the
namespace of the module where the 'augment' statement appears. namespace of the module where the 'augment' statement appears.
10.4. The base Statement 10.4. The base Statement
This statement is ignored as a substatement of 'identity' and handled This statement is ignored as a substatement of 'identity' and handled
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.53.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.24.
10.6. The bit Statement 10.6. The bit Statement
This statement is handled within the "bits" type, see This statement is handled within the "bits" type, see
Section 10.50.3. Section 10.53.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
This statement is mapped to <rng:choice> element. This statement is mapped to <rng:choice> element.
Unless 'choice' has the 'mandatory' substatement with the value of Unless 'choice' has the 'mandatory' substatement with the value of
"true", the <rng:choice> element MUST be wrapped in <rng:optional>. "true", the <rng:choice> element MUST be wrapped in <rng:optional>.
The 'choice' statement with "mandatory true;" requires additional
handling, see Section 9.3.
10.9. The config Statement 10.9. The config Statement
This statement is mapped to @nma:config attribute and ARGUMENT This statement is mapped to @nma:config attribute and ARGUMENT
becomes its value. becomes its value.
10.10. The contact Statement 10.10. The contact 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 created by different schema may result from multiple YANG modules created by different
authors. The schema contains references to all input modules in the authors. 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.34. The original
modules are the authoritative sources of the authorship information. modules are the authoritative sources of the authorship information.
10.11. The container Statement 10.11. The container Statement
Using the procedure outlined in Section 7.1, the mapping algorithm Using the procedure outlined in Section 8.1, the mapping algorithm
MUST determine whether the statement defines an optional container, MUST determine whether the statement defines an optional container,
and if so, insert the <rng:optional> element and make it the new and if so, insert the <rng:optional> element and make it the new
PARENT. PARENT.
The container defined by this statement is then mapped to the <rng: The container defined by this statement is then mapped to the <rng:
element> element, which becomes a child of PARENT and uses ARGUMENT element> element, which becomes a child of PARENT and uses ARGUMENT
as the value of its @name attribute. as the value of its @name attribute.
10.12. The default Statement 10.12. The default Statement
skipping to change at page 47, line 11 skipping to change at page 51, line 18
input YANG module. The description can be found in the source module input YANG module. The description can be found in the source module
that is referred to by Dublin Core element <dc:source> and use that is referred to by Dublin Core element <dc:source> and use
ARGUMENT as its content. ARGUMENT as its content.
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 deviation Statement
All 'deviation' statements found in the input YANG modules MUST be
applied first so that the mapping algorithm operates on a schema tree
with all deviations already incorporated.
10.15. 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 [12], Section 6. <rng:value> element cannot contain annotations, see [12], section 6.
10.15. The error-app-tag Statement 10.16. 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.35.
10.16. The error-message Statement 10.17. 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
the latter case it is mapped to the <nma:error-message> element. See the latter case it is mapped to the <nma:error-message> element. See
also Section 10.32. also Section 10.35.
10.17. The extension Statement 10.18. The extension Statement
This statement is ignored. However, extensions to the YANG language This statement is ignored. However, extensions to the YANG language
MAY be mapped as described in Section 7.4. MAY be mapped as described in Section 8.4.
10.18. The grouping Statement 10.19. The feature Statement
This statement is ignored.
10.20. The grouping Statement
This statement is mapped to a RELAX NG named pattern definition <rng: This statement is mapped to a RELAX NG named pattern definition <rng:
define>, but only if the grouping defined by this statement is used define>, but only if the grouping defined by this statement is used
_without refinements and augments_ in at least one of the input _without refinements and augments_ in at least one of the input
modules. In this case, the named pattern definition becomes a child modules. In this case, the named pattern definition becomes a child
of the <rng:grammar> element and its name is ARGUMENT mangled of the <rng:grammar> element and its name is ARGUMENT mangled
according to the rules specified in Section 7.2. according to the rules specified in Section 8.2.
Whenever a grouping is used with additional refinements and/or Whenever a grouping is used with additional refinements and/or
augments, the grouping is expanded so that the refinements and augments, the grouping is expanded so that the refinements and
augments may be applied directly to the prescribed schema nodes. See augments may be applied directly to the prescribed schema nodes. See
Section 7.2.1 for further details and an example. Section 8.2.1 for further details and an example.
An implementation MAY offer the option of recording all 'grouping' An implementation MAY offer the option of recording all 'grouping'
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.19. The identity Statement 10.21. The identity Statement
This statement is not specifically mapped. However, if the identity This statement is not specifically mapped. However, if the identity
defined by this statement is used as the base for an "identityref" defined by this statement is used as the base for an "identityref"
type in any of the input modules, ARGUMENT will appear as the text of type in any of the input modules, ARGUMENT will appear as the text of
one of the <rng:value> elements in the mapping of that "identityref" one of the <rng:value> elements in the mapping of that "identityref"
type. See Section 10.50.5 for more details and an example. type. See Section 10.53.5 for more details and an example.
10.20. The import Statement 10.22. The if-feature Statement
The information whether a given feature is available or not MUST be
supplied to the mapping procedure, which MUST modify the YANG schema
tree by including or excluding the parts that depend on that feature.
10.23. The import Statement
This statement is not specifically mapped. The module whose name is This statement is not specifically mapped. The module whose name is
in ARGUMENT has to be parsed so that the importing module be able to in ARGUMENT has to be parsed so that the importing module be able to
use its top-level groupings and typedefs and also augment the data use its top-level groupings and typedefs and also augment the data
tree of the imported module. tree of the imported module.
If the 'import' statement has the 'revision' substatement, the If the 'import' statement has the 'revision' substatement, the
corresponding revision of the imported module MUST be used. The corresponding revision of the imported module MUST be used. The
mechanism for finding a given module revision is outside the scope of mechanism for finding a given module revision is outside the scope of
this document. this document.
10.21. The include Statement 10.24. The include Statement
This statement is not specifically mapped. The submodule whose name This statement is not specifically mapped. The submodule whose name
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.25. The input Statement
This statement is handled within 'rpc' statement, see Section 10.47. This statement is handled within 'rpc' statement, see Section 10.50.
10.23. The key Statement 10.26. The key Statement
This statement is mapped to @nma:key attribute. ARGUMENT is MUST be This statement is mapped to @nma:key attribute. ARGUMENT is MUST be
translated so that every key is prefixed with the namespace prefix of translated so that every key is prefixed with the namespace prefix of
the local module. The result of this translation then becomes the the local module. The result of this translation then becomes the
value of the @nma:key attribute. value of the @nma:key attribute.
10.24. The leaf Statement 10.27. 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.28. 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.
<rng:element> is the added as a child element of PARENT and ARGUMENT <rng:element> is the added as a child element of PARENT and ARGUMENT
becomes the value of its @name attribute. If the 'leaf-list' becomes the value of its @name attribute. If the 'leaf-list'
statement has the 'min-elements' substatement and its argument is statement has the 'min-elements' substatement and its argument is
skipping to change at page 49, line 44 skipping to change at page 54, line 24
is mapped to the following RELAX NG fragment: is mapped to the following RELAX NG fragment:
<rng:oneOrMore> <rng:oneOrMore>
<rng:element name="foliage" nma:ordered-by="user" <rng:element name="foliage" nma:ordered-by="user"
nma:min-elements="3" nma:max-elements="6378"> 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.29. The length Statement
This statement is handled within the "string" type, see This statement is handled within the "string" type, see
Section 10.50.9. Section 10.53.9.
10.27. The list Statement 10.30. 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.28.
10.28. The mandatory Statement 10.31. 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
mapped as mandatory, see Section 7.1. mapped as mandatory, see Section 8.1.
10.29. The max-elements Statement 10.32. The max-elements Statement
This statement is handled within 'leaf-list' or 'list' statements, This statement is handled within 'leaf-list' or 'list' statements,
see Section 10.25. see Section 10.28.
10.30. The min-elements Statement 10.33. The min-elements Statement
This statement is handled within 'leaf-list' or 'list' statements, This statement is handled within 'leaf-list' or 'list' statements,
see Section 10.25. see Section 10.28.
10.31. The module Statement 10.34. The module Statement
This statement is not specifically mapped except that a <dc:source> This statement is not specifically mapped except that a <dc:source>
element SHOULD be created as a child of <rng:grammar> and contain element SHOULD be created as a child of <rng:grammar> and contain
ARGUMENT as a reference to the input YANG module. See also ARGUMENT as a reference to the input YANG module. See also
Section 10.46. Section 10.49.
With respect to the conceptual tree schema, substatements of 'module' With respect to the conceptual tree schema, substatements of 'module'
MUST be mapped so that MUST be mapped so that
o top level data elements be defined as children of the <nmt:top> o top level data elements be defined as children of the <nmt:top>
element; element;
o elements mapped from 'rpc' statements be defined as children of o elements mapped from 'rpc' statements be defined as children of
the <nmt:rpc-methods> element; the <nmt:rpc-methods> element;
o elements mapped from 'notification' statements be defined as o elements mapped from 'notification' statements be defined as
children of the <nmt:notifications> element. children of the <nmt:notifications> element.
10.32. The must Statement 10.35. The must Statement
This statement is mapped to the <nma:must> element. It has one This statement is mapped to the <nma:must> element. It has one
mandatory attribute @assert (with no namespace), which contains mandatory attribute @assert (with no namespace), which contains
ARGUMENT transformed into a valid XPath expression (see Section 7.3). ARGUMENT transformed into a valid XPath expression (see Section 8.3).
The <nma:must> element may get other subelements resulting from The <nma:must> element may get other subelements resulting from
mapping 'error-app-tag' and 'error-message' substatements. Other mapping 'error-app-tag' and 'error-message' substatements. Other
substatements of 'must', i.e., 'description' and 'reference', are substatements of 'must', i.e., 'description' and 'reference', are
ignored. ignored.
EXAMPLE. YANG statement EXAMPLE. YANG statement
must 'current() <= ../max-lease-time' { must 'current() <= ../max-lease-time' {
error-message error-message
"The default-lease-time must be less than max-lease-time"; "The default-lease-time must be less than max-lease-time";
} }
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.36. The namespace Statement
This statement is mapped to @xmlns:xxx attribute of the <rng:grammar> This statement is mapped to @xmlns:xxx attribute of the <rng:grammar>
element where "xxx" is the namespace prefix specified by the sibling element where "xxx" is the namespace prefix specified by the sibling
'prefix' statement. ARGUMENT becomes the value of this attribute. 'prefix' statement. ARGUMENT becomes the value of this attribute.
10.34. The notification Statement 10.37. The notification Statement
This statement is mapped to the following subtree in the RELAX NG This statement is mapped to the following subtree in the RELAX NG
schema ("yam" is the prefix of the local YANG module): schema ("yam" is the prefix of the local YANG module):
<rng:element name="nmt:notification"> <rng:element name="nmt:notification">
<rng:element name="yam:ARGUMENT"> <rng:element name="yam:ARGUMENT">
... ...
</rng:element> </rng:element>
</rng:element> </rng:element>
Substatements of 'notification' are mapped under <rng:element Substatements of 'notification' are mapped under <rng:element
name="yam:ARGUMENT">. name="yam:ARGUMENT">.
The <rng:element name="nmt:rpc-notification"> element is a child of The <rng:element name="nmt:rpc-notification"> element is a child of
<rng:element name="nmt:notifications">. <rng:element name="nmt:notifications">.
10.35. The ordered-by Statement 10.38. 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.28 for an
example. example.
10.36. The organization Statement 10.39. 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.34. 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.40. The output Statement
This statement is handled within 'rpc' statement, see Section 10.47. This statement is handled within 'rpc' statement, see Section 10.50.
10.38. The path Statement 10.41. The path Statement
This statement is handled within "leafref" type, see Section 10.50.7. This statement is handled within "leafref" type, see Section 10.53.7.
10.39. The pattern Statement 10.42. The pattern Statement
This statement is handled within "string" type, see Section 10.50.9. This statement is handled within "string" type, see Section 10.53.9.
10.40. The position Statement 10.43. The position Statement
This statement is ignored. This statement is ignored.
10.41. The prefix Statement 10.44. The prefix Statement
This statement is handled within the sibling 'namespace' statement, This statement is handled within the sibling 'namespace' statement,
see Section 10.33, or within the parent 'import' statement, see see Section 10.36, or within the parent 'import' statement, see
Section 10.20. As a substatement of 'belongs-to' (in submodules), Section 10.23. As a substatement of 'belongs-to' (in submodules),
the 'prefix' statement is ignored. the 'prefix' statement is ignored.
10.42. The presence Statement 10.45. The presence Statement
This statement influences the mapping of 'container' (Section 10.11): This statement is mapped to the annotation attribute @nma:presence
it makes the parent container optional, regardless of its content. with the value of "true". In addition, it influences the mapping of
See also Section 7.1. 'container' (Section 10.11): the parent container definition MUST be
wrapped in <rng:optional>, regardless of its content. See also
Section 8.1.
10.43. The range Statement 10.46. The range Statement
This statement is handled within numeric types, see Section 10.50.8. This statement is handled within numeric types, see Section 10.53.8.
10.44. The reference Statement 10.47. 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.48. The require-instance Statement
This statement is handled within the types "leafref" This statement is handled within the types "leafref"
(Section 10.50.7) and "instance-identifier" (Section 10.50.6). (Section 10.53.7) and "instance-identifier" (Section 10.53.6).
10.46. The revision Statement 10.49. 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.34), 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.50. The rpc Statement
This statement is mapped to the following subtree in the RELAX NG This statement is mapped to the following subtree in the RELAX NG
schema ("yam" is the prefix of the local YANG module): schema ("yam" is the prefix of the local YANG module):
<rng:element name="nmt:rpc-method"> <rng:element name="nmt:rpc-method">
<rng:element name="nmt:input"> <rng:element name="nmt:input">
<rng:element name="yam:ARGUMENT"> <rng:element name="yam:ARGUMENT">
<!-- mapped content of 'input' --> <!-- mapped content of 'input' -->
</rng:element> </rng:element>
</rng:element> </rng:element>
skipping to change at page 53, line 49 skipping to change at page 58, line 31
As indicated by the comments, contents of the 'input' substatement As indicated by the comments, contents of the 'input' substatement
(if any) are mapped under <rng:element name="yam:ARGUMENT">. (if any) are mapped under <rng:element name="yam:ARGUMENT">.
Similarly, contents of the 'output' substatement are mapped under Similarly, contents of the 'output' substatement are mapped under
<rng:element name="nmt:output">. If there is no 'output' <rng:element name="nmt:output">. If there is no 'output'
substatement, the <rng:element name="nmt:output"> MUST NOT be substatement, the <rng:element name="nmt:output"> MUST NOT be
present. present.
The <rng:element name="nmt:rpc-method"> element is a child of <rng: The <rng:element name="nmt:rpc-method"> element is a child of <rng:
element name="nmt:rpc-methods">. element name="nmt:rpc-methods">.
10.48. The status Statement 10.51. 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.52. 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.53. 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 [16] 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 |
skipping to change at page 55, line 5 skipping to change at page 59, line 40
| boolean | boolean | "true" or "false" | | boolean | boolean | "true" or "false" |
| | | | | | | |
| binary | base64Binary | binary data in base64 encoding | | binary | base64Binary | binary data in base64 encoding |
+-----------+---------------+----------------------------------+ +-----------+---------------+----------------------------------+
Table 3: Selected datatypes from the W3C XML Schema Type Library Table 3: Selected datatypes from the W3C XML Schema Type Library
Details about the mapping of individual YANG built-in types are given Details about the mapping of individual YANG built-in types are given
in the following subsections. in the following subsections.
10.50.1. The empty Type 10.53.1. The empty Type
This type is mapped to <rng:empty/>. This type is mapped to <rng:empty/>.
10.50.2. The boolean and binary Types 10.53.2. The boolean and binary Types
These two built-in types do not allow any restrictions and are mapped These two built-in types do not allow any restrictions and are mapped
simply by inserting <rng:data> element whose @type attribute is set simply by inserting <rng:data> element whose @type attribute is set
to ARGUMENT mapped according to Table 3. to ARGUMENT mapped according to Table 3.
10.50.3. The bits Type 10.53.3. The bits Type
This type is mapped to <rng:list> and for each 'bit' substatement the This type is mapped to <rng:list> and for each 'bit' substatement the
following XML fragment is inserted as a child of <rng:list>: following XML fragment is inserted as a child of <rng:list>:
<rng:optional> <rng:optional>
<rng:value>bit_name</rng:value> <rng:value>bit_name</rng:value>
</rng:optional> </rng:optional>
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.53.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.53.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 value> subelements. Each of the <rng:value> subelements MUST have
the @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 Section 7.16.3 of [5]). Consider the following
YANG modules: two YANG modules:
module crypto-base { module crypto-base {
namespace "http://example.com/crypto-base"; namespace "http://example.com/crypto-base";
prefix "crypto"; prefix "crypto";
identity crypto-alg { identity crypto-alg {
description description
"Base identity from which all crypto algorithms "Base identity from which all crypto algorithms
are derived."; are derived.";
} }
skipping to change at page 57, line 7 skipping to change at page 62, line 7
<rng:element name="crypto"> <rng:element name="crypto">
<rng:choice> <rng:choice>
<rng:value type="QName">crypto:crypto-alg</value> <rng:value type="QName">crypto:crypto-alg</value>
<rng:value type="QName">des:des</value> <rng:value type="QName">des:des</value>
<rng:value type="QName">des:des3</value> <rng:value type="QName">des:des3</value>
</rng:choice> </rng:choice>
</rng:element> </rng:element>
The "crypto" and "des" prefixes will by typically defined via The "crypto" and "des" prefixes will by typically defined via
attributes of the <rng:grammar> element. attributes of the <rng:grammar> element.
10.50.6. The instance-identifier Type 10.53.6. The instance-identifier Type
This type is mapped to <rng:data> element with @type attribute set to This type is mapped to <rng:data> element with @type attribute set to
"string". In addition, empty <nma:instance-identifier> element MUST "string". In addition, empty <nma:instance-identifier> element MUST
be inserted as a child of PARENT. be inserted as a child of PARENT.
The 'require-instance' substatement, if it exists, is mapped to the The 'require-instance' substatement, if it exists, is mapped to the
@require-instance attribute of <nma:instance-identifier>. @require-instance attribute of <nma:instance-identifier>.
10.50.7. The leafref Type 10.53.7. The leafref Type
This type is mapped to <rng:data> element with @type attribute set to This type is mapped to <rng:data> element with @type attribute set to
the type of the leaf given in the argument of 'path' substatement. the type of the leaf given in the argument of 'path' substatement.
In addition, <nma:leafref> element MUST be inserted as a child of In addition, <nma:leafref> element MUST be inserted as a child of
PARENT. The argument value of the 'path' substatement is set as the PARENT. The argument value of the 'path' substatement is set as the
text of this element. text of this element.
The 'require-instance' substatement, if it exists, is mapped to the The 'require-instance' substatement, if it exists, is mapped to the
@require-instance attribute of <nma:leafref>. @require-instance attribute of <nma:leafref>.
10.50.8. The numeric Types 10.53.8. The numeric Types
YANG built-in numeric types are "int8", "int16", "int32", "int64", YANG built-in numeric types are "int8", "int16", "int32", "int64",
"uint8", "uint16", "uint32", "uint64", "float32" and "float64". They "uint8", "uint16", "uint32", "uint64", "float32" and "float64". They
are mapped to <rng:data> element with @type attribute set to ARGUMENT are mapped to <rng:data> element with @type attribute set to ARGUMENT
mapped according to Table 3. mapped according to Table 3.
All numeric types support the 'range' restriction, which is handled All numeric types support the 'range' restriction, which is handled
in the following way: in the following way:
o If the range expression consists of a single range part, insert o If the range expression consists of a single range part, insert
skipping to change at page 58, line 38 skipping to change at page 63, line 38
<rng:data type="int"> <rng:data type="int">
<rng:param name="minInclusive">42</rng:param> <rng:param name="minInclusive">42</rng:param>
<rng:param name="maxInclusive">42</rng:param> <rng:param name="maxInclusive">42</rng:param>
</rng:data> </rng:data>
<rng:data type="int"> <rng:data type="int">
<rng:param name="minInclusive">100</rng:param> <rng:param name="minInclusive">100</rng:param>
</rng:data> </rng:data>
</rng:choice> </rng:choice>
</rng:define> </rng:define>
10.50.9. The string Type 10.53.9. The string Type
This type is mapped to <rng:data> element with the @type attribute This type is mapped to <rng:data> element with the @type attribute
set to "string". set to "string".
For the 'pattern' restriction, insert <rng:param> element with @name For the 'pattern' restriction, insert <rng:param> element with @name
attribute set to "pattern". The argument of the 'pattern' statement attribute set to "pattern". The argument of the 'pattern' statement
(regular expression) becomes the content of this element. (regular expression) becomes the content of this element.
The 'length' restriction is handled in the same way as the 'range' The 'length' restriction is handled in the same way as the 'range'
restriction for the numeric types, with the additional twist that if restriction for the numeric types, with the additional twist that if
the length expression has multiple parts, the "pattern" facet the length expression has multiple parts, the "pattern" facet
<rng:param name="pattern">...</rng:param> <rng:param name="pattern">...</rng:param>
if there is any, must be repeated inside each copy of the <rng:data> if there is any, must be repeated inside each copy of the <rng:data>
element, i.e., for each length part. element, i.e., for each length part.
10.50.10. Derived Types 10.53.10. Derived Types
If the 'type' statement refers to a derived type, it is mapped in one If the 'type' statement refers to a derived type, it is mapped in one
of the following ways depending on whether it contains any of the following ways depending on whether it contains any
restrictions as its substatements: restrictions as its substatements:
1. Without restrictions, the 'type' statement is mapped simply to 1. Without restrictions, the 'type' statement is mapped simply to
the <rng:ref> element, i.e., a reference to a named pattern. If the <rng:ref> element, i.e., a reference to a named pattern. If
the RELAX NG definition of this named pattern has not been added the RELAX NG definition of this named pattern has not been added
to the output schema yet, the corresponding 'typedef' must be to the output schema yet, the corresponding 'typedef' must be
found and its mapping installed as a subelement of <rng:grammar>, found and its mapping installed as a subelement of <rng:grammar>,
see Section 10.51. Even if a given derived type is used more see Section 10.54. Even if a given derived type is used more
than once in the input YANG modules, the mapping of the than once in the input YANG modules, the mapping of the
corresponding 'typedef' MUST be installed only once. corresponding 'typedef' MUST be installed only once.
2. If any restrictions are present, the base type for the given 2. If any restrictions are present, the base type for the given
derived type must be determined and the mapping of this base type derived type must be determined and the mapping of this base type
is used. Restrictions appearing at all stages of the derivation is used. Restrictions appearing at all stages of the derivation
chain must be taken into account and their conjunction added to chain must be taken into account and their conjunction added to
the <rng:data> element which defines the basic type. the <rng:data> element which defines the basic type.
See Section 7.2.2 for more details and an example. See Section 8.2.2 for more details and an example.
10.51. The typedef Statement 10.54. The typedef Statement
This statement is mapped to a RELAX NG named pattern definition <rng: This statement is mapped to a RELAX NG named pattern definition <rng:
define>, but only if the type defined by this statement is used define>, but only if the type defined by this statement is used
_without restrictions_ in at least one of the input modules. In this _without restrictions_ in at least one of the input modules. In this
case, the named pattern definition becomes a child of the <rng: case, the named pattern definition becomes a child of the <rng:
grammar> element and its name is ARGUMENT mangled according to the grammar> element and its name is ARGUMENT mangled according to the
rules specified in Section 7.2. rules specified in Section 8.2.
Whenever a derived type is used with additional restrictions, the the Whenever a derived type is used with additional restrictions, the the
base type for the derived type is used instead with restrictions base type for the derived type is used instead with restrictions
(facets) that are a combination of all restrictions specified along (facets) that are a combination of all restrictions specified along
the type derivation chain. See Section 10.50.10 for further details the type derivation chain. See Section 10.53.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.55. The unique Statement
This statement is mapped to @nma:unique attribute. ARGUMENT is This statement is mapped to @nma:unique attribute. ARGUMENT is
translated so that every node identifier in each of its components is translated so that every node identifier in each of its components is
prefixed with the namespace prefix of the local module, unless the prefixed with the namespace prefix of the local module, unless the
prefix is already present. The result of this translation then prefix is already present. The result of this translation then
becomes the value of the @nma:unique attribute. becomes the value of the @nma:unique attribute.
For example, assuming that the local module prefix is "ex", For example, assuming that the local module prefix is "ex",
unique "foo ex:bar/baz" unique "foo ex:bar/baz"
is mapped to the following attribute/value pair: is mapped to the following attribute/value pair:
nma:unique="ex:foo ex:bar/ex:baz" nma:unique="ex:foo ex:bar/ex:baz"
10.53. The units Statement 10.56. 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.57. 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
attribute is set to ARGUMENT mangled according to Section 7.2 attribute is set to ARGUMENT mangled according to Section 8.2
If there are any 'refine' or 'augment' substatements, the If there are any 'refine' or 'augment' substatements, the
corresponding grouping must be looked up and its contents is inserted corresponding grouping must be looked up and its contents is inserted
as children of PARENT. See Section 7.2.1 for further details and an as children of PARENT. See Section 8.2.1 for further details and an
example. example.
10.55. The value Statement 10.58. The value Statement
This statement is ignored. This statement is ignored.
10.56. The when Statement 10.59. The when Statement
This statement is mapped to @nma:when attribute and ARGUMENT becomes This statement is mapped to @nma:when attribute and ARGUMENT becomes
it value. it value.
10.57. The yang-version Statement 10.60. The yang-version Statement
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.61. 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 8.4.
11. Mapping NETMOD-specific annotations to DSDL Schema Languages 11. Mapping NETMOD-specific annotations to DSDL Schema Languages
This section contains mapping specification for individual NETMOD- This section contains mapping specification for individual NETMOD-
specific annotations. In each case, the result of the mapping must specific annotations. In each case, the result of the mapping must
be inserted into an appropriate context of the target DSDL schema as be inserted into an appropriate context of the target DSDL schema as
described in Section 8. The context is determined by the element described in Section 9. The context is determined by the element
definition in the conceptual tree schema to which the annotation is definition in the conceptual tree schema to which the annotation is
attached. In the rest of this section, we will denote CONTELEM the attached. In the rest of this section, we will denote CONTELEM the
name of this context element properly qualified with its namespace name of this context element properly qualified with its namespace
prefix. Unless otherwise stated, Schematron asserts are descendants prefix. Unless otherwise stated, Schematron asserts are descendants
of the "standard" pattern and therefore active in both validation of the "standard" pattern and therefore active in both validation
phases. phases.
11.1. The @nma:config Annotation 11.1. The @nma:config Annotation
This annotation MUST be observed when generating any schema for the This annotation MUST be observed when generating any schema for the
reply to <nc:get-config>. In particular: reply to <nc:get-config>. In particular:
o When generating RELAX NG, the contents of the CONTELEM definition o When generating RELAX NG, the contents of the CONTELEM definition
MUST be changed to <rng:notAllowed>. MUST be changed to <rng:notAllowed>.
o When generating Schematron or DSRL, the CONTELEM definition and o When generating Schematron or DSRL, the CONTELEM definition and
all its descendants in the conceptual tree schema MUST be ignored. all its descendants in the conceptual tree schema MUST be ignored.
11.2. The @nma:default Annotation 11.2. The @nma:default Annotation
TBD This annotation is used for generating the DSRL schema as described
in Section 9.4.
11.3. The @nma:default-case Annotation 11.3. The @nma:default-case Annotation
TBD This annotation is used for generating the DSRL schema as described
in Section 9.4.
11.4. The <nma:error-app-tag> Annotation 11.4. The <nma:error-app-tag> Annotation
This annotation currently has no mapping defined. This annotation currently has no mapping defined.
11.5. The <nma:error-message> Annotation 11.5. The <nma:error-message> Annotation
This annotation is handled within <nma:must>, see Section 11.11. This annotation is handled within <nma:must>, see Section 11.11.
11.6. The <nma:instance-identifier> Annotation 11.6. The <nma:instance-identifier> Annotation
This annotation currently has no mapping defined. If this annotation element has the @require-instance attribute with
the value "false", it is ignored. Otherwise it is mapped to the
following Schematron assert:
[Editor's note: The mapping is probably not possible with XPath 1.0 <sch:assert test="nmf:evaluate(.)">
as the query language in Schematron. Shall we use EXSLT or XPath The element pointed to by "CONTELEM" must exist.
2.0?] </sch:assert>
The nmf:evaluate() function is an XSLT extension function (see
Extension Functions in [19]) that evaluates an XPath expression at
runtime. Such an extension function is provided by some XSLT
processors, for example Saxon [25].
11.7. The @nma:key Annotation 11.7. The @nma:key Annotation
Assume this annotation has the value "k_1 k_2 ... k_n", i.e., 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 specifies n child leaves as keys. The annotation is then mapped to
the following Schematron report: the following Schematron report:
<sch:report test="CONDITION"> <sch:report test="CONDITION">
Duplicate key of list "CONTELEM" Duplicate key of list "CONTELEM"
</sch:report> </sch:report>
skipping to change at page 65, line 13 skipping to change at page 70, line 21
identifiers rather than simple leaf names. However, the XPath identifiers rather than simple leaf names. However, the XPath
expressions specified in Section 11.7 work without any expressions specified in Section 11.7 work without any
modifications if the descendant schema node identifiers are modifications if the descendant schema node identifiers are
substituted for k_1, k_2, ..., k_n. substituted for k_1, k_2, ..., k_n.
o The message appearing as the text of <sch:report> is different: o The message appearing as the text of <sch:report> is different:
"Violated uniqueness for list CONTELEM". "Violated uniqueness for list CONTELEM".
11.15. The @nma:when Annotation 11.15. The @nma:when Annotation
<sch:assert test="EXPRESSION or not(..)"> This annotation is mapped to the following Schematron assert:
Node "CONTELEM" requires "EXPRESSION"
<sch:assert test="EXPRESSION">
Node "CONTELEM" is only valid if "EXPRESSION" is true.
</sch:assert> </sch:assert>
where EXPRESSION is the value of @nma:when. 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
[22]: [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
skipping to change at page 68, line 48 skipping to change at page 73, line 48
[21] van der Vlist, E., "RELAX NG", O'Reilly , 2004. [21] van der Vlist, E., "RELAX NG", O'Reilly , 2004.
[22] 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.
[23] <http://www.thaiopensource.com/relaxng/trang.html> [23] <http://www.thaiopensource.com/relaxng/trang.html>
[24] <http://dublincore.org/> [24] <http://dublincore.org/>
[25] <http://www.yang-central.org/twiki/bin/view/Main/DhcpTutorial> [25] <http://www.saxonica.com/>
[26] <http://code.google.com/p/pyang/> [26] <http://www.yang-central.org/twiki/bin/view/Main/DhcpTutorial>
[27] <http://thaiopensource.com/relaxng/trang.html> [27] <http://code.google.com/p/pyang/>
[28] <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
also be done as in the spec for DTD compatibility annotations.] also be done as in the spec for DTD compatibility annotations.]
A.1. XML Syntax A.1. XML Syntax
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0" <grammar xmlns="http://relaxng.org/ns/structure/1.0"
ns="urn:ietf:params:xml:ns:netmod:dsdl-annotations:1" xmlns:nma="urn:ietf:params:xml:ns:netmod:dsdl-annotations:1"
datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"> datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
<define name="config-attribute"> <define name="config-attribute">
<attribute name="config"> <attribute name="nma:config">
<data type="boolean"/> <data type="boolean"/>
</attribute> </attribute>
</define> </define>
<define name="default-attribute"> <define name="default-attribute">
<attribute name="default"/> <attribute name="nma:default"/>
</define> </define>
<define name="default-case-attribute"> <define name="default-case-attribute">
<attribute name="default-case"> <attribute name="nma:default-case">
<data type="boolean"/> <data type="boolean"/>
</attribute> </attribute>
</define> </define>
<define name="error-app-tag-element"> <define name="error-app-tag-element">
<optional> <optional>
<element name="error-app-tag"> <element name="nma:error-app-tag">
<text/> <text/>
</element> </element>
</optional> </optional>
</define> </define>
<define name="error-message-element"> <define name="error-message-element">
<optional> <optional>
<element name="error-message"> <element name="nma:error-message">
<text/> <text/>
</element> </element>
</optional> </optional>
</define> </define>
<define name="instance-identifier-element"> <define name="instance-identifier-element">
<element name="instance-identifier"> <element name="nma:instance-identifier">
<optional> <optional>
<attribute name="require-instance"> <attribute name="nma:require-instance">
<data type="boolean"/> <data type="boolean"/>
</attribute> </attribute>
</optional> </optional>
</element> </element>
</define> </define>
<define name="key-attribute"> <define name="key-attribute">
<attribute name="key"> <attribute name="nma:key">
<list> <list>
<data type="QName"/> <data type="QName"/>
</list> </list>
</attribute> </attribute>
</define> </define>
<define name="leafref-element"> <define name="leafref-element">
<element name="leafref"> <element name="nma:leafref">
<optional> <optional>
<attribute name="require-instance"> <attribute name="nma:require-instance">
<data type="boolean"/> <data type="boolean"/>
</attribute> </attribute>
</optional> </optional>
<data type="string"/> <data type="string"/>
</element> </element>
</define> </define>
<define name="min-elements-attribute"> <define name="min-elements-attribute">
<attribute name="min-elements"> <attribute name="nma:min-elements">
<data type="integer"/> <data type="integer"/>
</attribute> </attribute>
</define> </define>
<define name="max-elements-attribute"> <define name="max-elements-attribute">
<attribute name="max-elements"> <attribute name="nma:max-elements">
<data type="integer"/> <data type="integer"/>
</attribute> </attribute>
</define> </define>
<define name="must-element"> <define name="must-element">
<element name="must"> <element name="nma:must">
<attribute name="assert"> <attribute name="nma:assert">
<data type="string"/> <data type="string"/>
</attribute> </attribute>
<interleave> <interleave>
<ref name="err-app-tag-element"/> <ref name="err-app-tag-element"/>
<ref name="err-message-element"/> <ref name="err-message-element"/>
</interleave> </interleave>
</element> </element>
</define> </define>
<define name="ordered-by-attribute"> <define name="ordered-by-attribute">
<attribute name="ordered-by"> <attribute name="nma:ordered-by">
<choice> <choice>
<value>user</value> <value>user</value>
<value>system</value> <value>system</value>
</choice> </choice>
</attribute> </attribute>
</define> </define>
<define name="presence-attribute">
<attribute name="nma:presence">
<value>true</value>
</attribute>
</define>
<define name="status-attribute"> <define name="status-attribute">
<attribute name="status"> <attribute name="nma:status">
<choice> <choice>
<value>current</value> <value>current</value>
<value>deprecated</value> <value>deprecated</value>
<value>obsolete</value> <value>obsolete</value>
</choice> </choice>
</attribute> </attribute>
</define> </define>
<define name="unique-attribute"> <define name="unique-attribute">
<attribute name="unique"> <attribute name="nma:unique">
<list> <list>
<data type="string"/> <data type="string"/>
</list> </list>
</attribute> </attribute>
</define> </define>
<define name="units-attribute"> <define name="units-attribute">
<attribute name="units"> <attribute name="nma:units">
<data type="string"/> <data type="string"/>
</attribute> </attribute>
</define> </define>
<define name="when-attribute"> <define name="when-attribute">
<attribute name="when"> <attribute name="nma:when">
<data type="string"/> <data type="string"/>
</attribute> </attribute>
</define> </define>
</grammar> </grammar>
A.2. Compact Syntax A.2. Compact Syntax
default namespace = namespace nma = "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1"
"urn:ietf:params:xml:ns:netmod:dsdl-annotations:1"
config-attribute = attribute config { xsd:boolean } config-attribute = attribute nma:config { xsd:boolean }
default-attribute = attribute default { text } default-attribute = attribute nma:default { text }
default-case-attribute = attribute default-case { xsd:boolean } default-case-attribute = attribute nma:default-case { xsd:boolean }
error-app-tag-element = element error-app-tag { text }? error-app-tag-element = element nma:error-app-tag { text }?
error-message-element = element error-message { text }? error-message-element = element nma:error-message { text }?
instance-identifier-element = instance-identifier-element =
element instance-identifier { element nma:instance-identifier {
attribute require-instance { xsd:boolean }? attribute nma:require-instance { xsd:boolean }?
} }
key-attribute = key-attribute =
attribute key { attribute nma:key {
list { xsd:QName } list { xsd:QName }
} }
leafref-element = leafref-element =
element leafref { element nma:leafref {
attribute require-instance { xsd:boolean }?, attribute nma:require-instance { xsd:boolean }?,
xsd:string xsd:string
} }
min-elements-attribute = attribute min-elements { xsd:integer } min-elements-attribute = attribute nma:min-elements { xsd:integer }
max-elements-attribute = attribute max-elements { xsd:integer } max-elements-attribute = attribute nma:max-elements { xsd:integer }
must-element = must-element =
element must { element nma:must {
attribute assert { xsd:string }, attribute nma:assert { xsd:string },
(err-app-tag-element & err-message-element) (err-app-tag-element & err-message-element)
} }
ordered-by-attribute = attribute ordered-by { "user" | "system" } ordered-by-attribute = attribute nma:ordered-by { "user" | "system" }
presence-attribute = attribute nma:presence { "true" }
status-attribute = status-attribute =
attribute status { "current" | "deprecated" | "obsolete" } attribute nma:status { "current" | "deprecated" | "obsolete" }
unique-attribute = unique-attribute =
attribute unique { attribute nma:unique {
list { xsd:string } list { xsd:string }
} }
units-attribute = attribute units { xsd:string } units-attribute = attribute nma:units { xsd:string }
when-attribute = attribute when { xsd:string } when-attribute = attribute nma:when { xsd:string }
Appendix B. Schema-Independent Library Appendix B. Schema-Independent Library
In order to avoid copying the same named pattern definitions to the In order to avoid copying the same named pattern definitions to the
RELAX NG schemas generated in the second mapping step, we collected RELAX NG schemas generated in the second mapping step, we collected
these definitions to a library file - schema-independent library - these definitions to a library file - schema-independent library -
which is included by the validating schemas under the file name which is included by the validating schemas under the file name
"relaxng-lib.rng" (XML syntax) and "relaxng-lib.rnc" (compact "relaxng-lib.rng" (XML syntax) and "relaxng-lib.rnc" (compact
syntax). The included definitions cover patterns for common elements syntax). The included definitions cover patterns for common elements
from base NETCONF [1] and event notifications [10]. from base NETCONF [1] and event notifications [10].
skipping to change at page 75, line 8 skipping to change at page 81, line 8
message-id-attribute = message-id-attribute =
attribute message-id { attribute message-id {
xsd:string { maxLength = "4095" } xsd:string { maxLength = "4095" }
} }
ok-element = element nc:ok { empty } ok-element = element nc:ok { empty }
eventTime-element = element en:eventTime { xsd:dateTime } eventTime-element = element en:eventTime { xsd:dateTime }
Appendix C. Mapping DHCP Data Model - A Complete Example Appendix C. Mapping DHCP Data Model - A Complete Example
This appendix demonstrates both steps of the YANG-to-DSDL mapping This appendix demonstrates both steps of the YANG-to-DSDL mapping
applied to the "canonical" DHCP tutorial [25] data model. The input applied to the "canonical" DHCP tutorial [26] data model. The input
(single) YANG module is shown in Appendix C.1 and the output schemas (single) YANG module is shown in Appendix C.1 and the output schemas
in the following two subsections. in the following two subsections.
The conceptual tree schema was obtained by the "rng" plugin of the The conceptual tree schema was obtained by the "rng" plugin of the
pyang [26] tool and the validating DSDL schemas by XSLT stylesheets pyang [27] tool and the validating DSDL schemas by XSLT stylesheets
that are also part of pyang distribution. RELAX NG schemas are shown that are also part of pyang distribution. RELAX NG schemas are shown
in both XML and compact syntax. The latter was obtained from the in both XML and compact syntax. The latter was obtained from the
former by using the Trang tool [27] former by using the Trang tool [28]
Due to the limit of 72 characters per line, few long strings required Due to the limit of 72 characters per line, few long strings required
manual editing, in particular the regular expression patterns for IP manual editing, in particular the regular expression patterns for IP
addresses etc. in the RELAX NG schemas. In the compact syntax we addresses etc. in the RELAX NG schemas. In the compact syntax we
broke the patterns to appropriate segments and joined them with the broke the patterns to appropriate segments and joined them with the
concatenation operator "~". In the XML syntax, though, the long concatenation operator "~". In the XML syntax, though, the long
patterns had to be replaced by the placeholder string "... regex patterns had to be replaced by the placeholder string "... regex
pattern ...". Also, line breaks were added to several documentation pattern ...". Also, line breaks were added to several documentation
strings and Schematron messages. Other than that, the results of the strings and Schematron messages. Other than that, the results of the
automatic translations were not changed. automatic translations were not changed.
skipping to change at page 93, line 13 skipping to change at page 99, line 13
[dhcp:address=current()/dhcp:address]"> [dhcp:address=current()/dhcp:address]">
Duplicate key of list dhcp:leases Duplicate key of list dhcp:leases
</sch:report> </sch:report>
</sch:rule> </sch:rule>
</sch:pattern> </sch:pattern>
<sch:pattern id="ref-integrity"/> <sch:pattern id="ref-integrity"/>
</sch:schema> </sch:schema>
C.5. DSRL Schema for <get> Reply C.5. DSRL Schema for <get> Reply
TBD <?xml version="1.0" encoding="utf-8"?>
<dsrl:maps xmlns:dsrl="http://purl.oclc.org/dsdl/dsrl"
xmlns:dhcp="http://example.com/ns/dhcp"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<dsrl:element-map>
<dsrl:parent>/nc:rpc-reply/nc:data/</dsrl:parent>
<dsrl:name>dhcp:dhcp</dsrl:name>
<dsrl:default-content>
<dhcp:max-lease-time>7200</dhcp:max-lease-time>
<dhcp:default-lease-time>600</dhcp:default-lease-time>
</dsrl:default-content>
</dsrl:element-map>
<dsrl:element-map>
<dsrl:parent>/nc:rpc-reply/nc:data/dhcp:dhcp</dsrl:parent>
<dsrl:name>dhcp:max-lease-time</dsrl:name>
<dsrl:default-content>7200</dsrl:default-content>
</dsrl:element-map>
<dsrl:element-map>
<dsrl:parent>/nc:rpc-reply/nc:data/dhcp:dhcp</dsrl:parent>
<dsrl:name>dhcp:default-lease-time</dsrl:name>
<dsrl:default-content>600</dsrl:default-content>
</dsrl:element-map>
<dsrl:element-map>
<dsrl:parent>
/nc:rpc-reply/nc:data/dhcp:dhcp/dhcp:subnet
</dsrl:parent>
<dsrl:name>dhcp:max-lease-time</dsrl:name>
<dsrl:default-content>7200</dsrl:default-content>
</dsrl:element-map>
<dsrl:element-map>
<dsrl:parent>
/nc:rpc-reply/nc:data/dhcp:dhcp/dhcp:shared-networks/
dhcp:shared-network/dhcp:subnet
</dsrl:parent>
<dsrl:name>dhcp:max-lease-time</dsrl:name>
<dsrl:default-content>7200</dsrl:default-content>
</dsrl:element-map>
</dsrl:maps>
Appendix D. Change Log Appendix D. Change Log
D.1. Changes Between Versions -00 and -01 D.1. Changes Between Versions -01 and -02
o Moved Section 6 "NETCONF Content Validation" after Section 5.
o New text about mapping defaults to DSRL, especially in Section 6
and Section 9.4.
o Finished the DHCP example by adding the DSRL schema to Appendix C.
o New @nma:presence annotation was added - it is needed for proper
handling of default content.
o Section 9.3 "Constraints on Mandatory Choice" was added because
these constraints require a combination of RELAX NG and
Schematron.
o Fixed the schema for NETMOD-specific annotations by adding
explicit prefix to all defined elements and attributes.
Previously, the attributes had no namespace.
o Handling of 'feature', 'if-feature' and 'deviation' added.
o Handling of nma:instance-identifier via XSLT extension function.
o Many other minor corrections and improvements.
D.2. Changes Between Versions -00 and -01
o Attributes @nma:min-elements and @nma:max-elements are attached to o Attributes @nma:min-elements and @nma:max-elements are attached to
<rng:element> (list entry) and not to <rng:zeroOrMore> or <rng: <rng:element> (list entry) and not to <rng:zeroOrMore> or <rng:
oneOrMore>. oneOrMore>.
o Keys and all node identifiers in 'key' and 'unique' statements are o Keys and all node identifiers in 'key' and 'unique' statements are
prefixed. prefixed.
o Fixed the mapping of 'rpc' and 'notification'. o Fixed the mapping of 'rpc' and 'notification'.
o Removed previous Sec. 7.5 "RPC Signatures and Notifications" - the o Removed previous sec. 7.5 "RPC Signatures and Notifications" - the
same information is now contained in Section 10.47 and same information is now contained in Section 10.50 and
Section 10.34. Section 10.37.
o Added initial "_" to mangled names of groupings. o Added initial "_" to mangled names of groupings.
o Mandated the use of @xmlns:xxx as the only method for declaring o Mandated the use of @xmlns:xxx as the only method for declaring
the target namespace. the target namespace.
o Added section "Handling of XML Namespaces" to explain the previous o Added section "Handling of XML Namespaces" to explain the previous
item. item.
o Completed DHCP example in Appendix C. o Completed DHCP example in Appendix C.
 End of changes. 218 change blocks. 
401 lines changed or deleted 751 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/