draft-ietf-netmod-dsdl-map-05.txt   draft-ietf-netmod-dsdl-map-06.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 3, 2010 Plantronics Expires: December 21, 2010 Plantronics
S. Chisholm S. Chisholm
Nortel Nortel
March 2, 2010 June 19, 2010
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-05 draft-ietf-netmod-dsdl-map-06
Abstract Abstract
This draft specifies the mapping rules for translating YANG data This draft specifies the mapping rules for translating YANG data
models into Document Schema Definition Languages (DSDL), a models into Document Schema Definition Languages (DSDL), a
coordinated set of XML schema languages standardized as ISO 19757. coordinated set of XML schema languages standardized as ISO 19757.
The following DSDL schema languages are used by the mapping: RELAX The following DSDL schema languages are addressed by the mapping:
NG, Schematron and DSRL. The mapping takes one or more YANG modules RELAX NG, Schematron and DSRL. The mapping takes one or more YANG
and produces a set of DSDL schemas for a selected target document modules and produces a set of DSDL schemas for a selected target
type - datastore content, NETCONF PDU etc. Procedures for schema- document type - datastore content, NETCONF message etc. Procedures
based validation of such documents are also discussed. for schema-based validation of such documents are also discussed.
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 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). Note that other groups may also distribute
other groups may also distribute working documents as Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
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 This Internet-Draft will expire on December 21, 2010.
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on September 3, 2010.
Copyright Notice Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the Copyright (c) 2010 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
skipping to change at page 2, line 15 skipping to change at page 2, line 10
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6
2. Terminology and Notation . . . . . . . . . . . . . . . . . . 7 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 7
2.1. Glossary of New Terms . . . . . . . . . . . . . . . . . 8 2.1. Glossary of New Terms . . . . . . . . . . . . . . . . . 10
3. Objectives and Motivation . . . . . . . . . . . . . . . . . . 10 3. Objectives and Motivation . . . . . . . . . . . . . . . . . . 11
4. DSDL Schema Languages . . . . . . . . . . . . . . . . . . . . 12 4. DSDL Schema Languages . . . . . . . . . . . . . . . . . . . . 13
4.1. RELAX NG . . . . . . . . . . . . . . . . . . . . . . . . 12 4.1. RELAX NG . . . . . . . . . . . . . . . . . . . . . . . . 13
4.2. Schematron . . . . . . . . . . . . . . . . . . . . . . . 13 4.2. Schematron . . . . . . . . . . . . . . . . . . . . . . . 14
4.3. Document Semantics Renaming Language (DSRL) . . . . . . 14 4.3. Document Semantics Renaming Language (DSRL) . . . . . . 15
5. Additional Annotations . . . . . . . . . . . . . . . . . . . 15 5. Additional Annotations . . . . . . . . . . . . . . . . . . . 16
5.1. Dublin Core Metadata Elements . . . . . . . . . . . . . 15 5.1. Dublin Core Metadata Elements . . . . . . . . . . . . . 16
5.2. RELAX NG DTD Compatibility Annotations . . . . . . . . . 15 5.2. RELAX NG DTD Compatibility Annotations . . . . . . . . . 16
5.3. NETMOD-Specific Annotations . . . . . . . . . . . . . . 16 5.3. NETMOD-Specific Annotations . . . . . . . . . . . . . . 17
6. Overview of the Mapping . . . . . . . . . . . . . . . . . . . 18 6. Overview of the Mapping . . . . . . . . . . . . . . . . . . . 19
7. NETCONF Content Validation . . . . . . . . . . . . . . . . . 20 7. NETCONF Content Validation . . . . . . . . . . . . . . . . . 21
8. Design Considerations . . . . . . . . . . . . . . . . . . . . 21 8. Design Considerations . . . . . . . . . . . . . . . . . . . . 22
8.1. Conceptual Data Tree . . . . . . . . . . . . . . . . . . 21 8.1. Hybrid Schema . . . . . . . . . . . . . . . . . . . . . 22
8.2. Modularity . . . . . . . . . . . . . . . . . . . . . . . 23 8.2. Modularity . . . . . . . . . . . . . . . . . . . . . . . 25
8.3. Granularity . . . . . . . . . . . . . . . . . . . . . . 24 8.3. Granularity . . . . . . . . . . . . . . . . . . . . . . 26
8.4. Handling of XML Namespaces . . . . . . . . . . . . . . . 24 8.4. Handling of XML Namespaces . . . . . . . . . . . . . . . 27
8.5. Features and Deviations . . . . . . . . . . . . . . . . 25 9. Mapping YANG Data Models to the Hybrid Schema . . . . . . . . 28
9. Mapping YANG Data Models to the Conceptual Tree Schema . . . 26 9.1. Occurrence Rules for Data Nodes . . . . . . . . . . . . 28
9.1. Occurrence Rules for Data Nodes . . . . . . . . . . . . 26 9.1.1. Optional and Mandatory Nodes . . . . . . . . . . . 29
9.1.1. Optional and Mandatory Nodes . . . . . . . . . . . 27 9.1.2. Implicit Nodes . . . . . . . . . . . . . . . . . . 30
9.1.2. Implicit Nodes . . . . . . . . . . . . . . . . . . 28 9.2. Mapping YANG Groupings and Typedefs . . . . . . . . . . 31
9.2. Mapping YANG Groupings and Typedefs . . . . . . . . . . 29 9.2.1. YANG Refinements and Augments . . . . . . . . . . . 32
9.2.1. YANG Refinements and Augments . . . . . . . . . . . 31 9.2.2. Type Derivation Chains . . . . . . . . . . . . . . 35
9.2.2. Type Derivation Chains . . . . . . . . . . . . . . 34
9.3. Translation of XPath Expressions . . . . . . . . . . . . 37 9.3. Translation of XPath Expressions . . . . . . . . . . . . 37
9.4. YANG Language Extensions . . . . . . . . . . . . . . . . 37 9.4. YANG Language Extensions . . . . . . . . . . . . . . . . 38
10. Mapping Conceptual Tree Schema to DSDL . . . . . . . . . . . 39 10. Mapping YANG Statements to the Hybrid Schema . . . . . . . . 40
10.1. Generating RELAX NG Schemas for Various Document Types . 39 10.1. The anyxml Statement . . . . . . . . . . . . . . . . . . 40
10.1.1. Reply to <get> or <get-config> . . . . . . . . . . 40 10.2. The argument Statement . . . . . . . . . . . . . . . . . 41
10.1.2. Remote Procedure Calls . . . . . . . . . . . . . . 40 10.3. The augment Statement . . . . . . . . . . . . . . . . . 42
10.1.3. Notifications . . . . . . . . . . . . . . . . . . . 41 10.4. The base Statement . . . . . . . . . . . . . . . . . . . 42
10.2. Mapping Semantic Constraints to Schematron . . . . . . . 42 10.5. The belongs-to Statement . . . . . . . . . . . . . . . . 42
10.2.1. Validation Phases . . . . . . . . . . . . . . . . . 45 10.6. The bit Statement . . . . . . . . . . . . . . . . . . . 42
10.3. Constraints on Mandatory Choice . . . . . . . . . . . . 46 10.7. The case Statement . . . . . . . . . . . . . . . . . . . 42
10.4. Mapping Default Values to DSRL . . . . . . . . . . . . . 48 10.8. The choice Statement . . . . . . . . . . . . . . . . . . 42
11. Mapping YANG Statements to Conceptual Tree Schema . . . . . . 52 10.9. The config Statement . . . . . . . . . . . . . . . . . . 43
11.1. The anyxml Statement . . . . . . . . . . . . . . . . . . 52 10.10. The contact Statement . . . . . . . . . . . . . . . . . 43
11.2. The argument Statement . . . . . . . . . . . . . . . . . 53 10.11. The container Statement . . . . . . . . . . . . . . . . 43
11.3. The augment Statement . . . . . . . . . . . . . . . . . 54 10.12. The default Statement . . . . . . . . . . . . . . . . . 43
11.4. The base Statement . . . . . . . . . . . . . . . . . . . 54 10.13. The description Statement . . . . . . . . . . . . . . . 45
11.5. The belongs-to Statement . . . . . . . . . . . . . . . . 54 10.14. The deviation Statement . . . . . . . . . . . . . . . . 45
11.6. The bit Statement . . . . . . . . . . . . . . . . . . . 54 10.15. The enum Statement . . . . . . . . . . . . . . . . . . . 45
11.7. The case Statement . . . . . . . . . . . . . . . . . . . 54 10.16. The error-app-tag Statement . . . . . . . . . . . . . . 45
11.8. The choice Statement . . . . . . . . . . . . . . . . . . 54 10.17. The error-message Statement . . . . . . . . . . . . . . 45
11.9. The config Statement . . . . . . . . . . . . . . . . . . 55 10.18. The extension Statement . . . . . . . . . . . . . . . . 45
11.10. The contact Statement . . . . . . . . . . . . . . . . . 55 10.19. The feature Statement . . . . . . . . . . . . . . . . . 45
11.11. The container Statement . . . . . . . . . . . . . . . . 55 10.20. The grouping Statement . . . . . . . . . . . . . . . . . 45
11.12. The default Statement . . . . . . . . . . . . . . . . . 55 10.21. The identity Statement . . . . . . . . . . . . . . . . . 46
11.13. The description Statement . . . . . . . . . . . . . . . 57 10.22. The if-feature Statement . . . . . . . . . . . . . . . . 47
11.14. The deviation Statement . . . . . . . . . . . . . . . . 57 10.23. The import Statement . . . . . . . . . . . . . . . . . . 48
11.15. The enum Statement . . . . . . . . . . . . . . . . . . . 57 10.24. The include Statement . . . . . . . . . . . . . . . . . 48
11.16. The error-app-tag Statement . . . . . . . . . . . . . . 57 10.25. The input Statement . . . . . . . . . . . . . . . . . . 48
11.17. The error-message Statement . . . . . . . . . . . . . . 57 10.26. The key Statement . . . . . . . . . . . . . . . . . . . 48
11.18. The extension Statement . . . . . . . . . . . . . . . . 57 10.27. The leaf Statement . . . . . . . . . . . . . . . . . . . 48
11.19. The feature Statement . . . . . . . . . . . . . . . . . 57 10.28. The leaf-list Statement . . . . . . . . . . . . . . . . 49
11.20. The grouping Statement . . . . . . . . . . . . . . . . . 57 10.29. The length Statement . . . . . . . . . . . . . . . . . . 49
11.21. The identity Statement . . . . . . . . . . . . . . . . . 58 10.30. The list Statement . . . . . . . . . . . . . . . . . . . 50
11.22. The if-feature Statement . . . . . . . . . . . . . . . . 58 10.31. The mandatory Statement . . . . . . . . . . . . . . . . 51
11.23. The import Statement . . . . . . . . . . . . . . . . . . 58 10.32. The max-elements Statement . . . . . . . . . . . . . . . 51
11.24. The include Statement . . . . . . . . . . . . . . . . . 58 10.33. The min-elements Statement . . . . . . . . . . . . . . . 51
11.25. The input Statement . . . . . . . . . . . . . . . . . . 59 10.34. The module Statement . . . . . . . . . . . . . . . . . . 51
11.26. The key Statement . . . . . . . . . . . . . . . . . . . 59 10.35. The must Statement . . . . . . . . . . . . . . . . . . . 52
11.27. The leaf Statement . . . . . . . . . . . . . . . . . . . 59 10.36. The namespace Statement . . . . . . . . . . . . . . . . 52
11.28. The leaf-list Statement . . . . . . . . . . . . . . . . 59 10.37. The notification Statement . . . . . . . . . . . . . . . 53
11.29. The length Statement . . . . . . . . . . . . . . . . . . 60 10.38. The ordered-by Statement . . . . . . . . . . . . . . . . 53
11.30. The list Statement . . . . . . . . . . . . . . . . . . . 60 10.39. The organization Statement . . . . . . . . . . . . . . . 53
11.31. The mandatory Statement . . . . . . . . . . . . . . . . 61 10.40. The output Statement . . . . . . . . . . . . . . . . . . 53
11.32. The max-elements Statement . . . . . . . . . . . . . . . 61 10.41. The path Statement . . . . . . . . . . . . . . . . . . . 53
11.33. The min-elements Statement . . . . . . . . . . . . . . . 62 10.42. The pattern Statement . . . . . . . . . . . . . . . . . 53
11.34. The module Statement . . . . . . . . . . . . . . . . . . 62 10.43. The position Statement . . . . . . . . . . . . . . . . . 54
11.35. The must Statement . . . . . . . . . . . . . . . . . . . 62 10.44. The prefix Statement . . . . . . . . . . . . . . . . . . 54
11.36. The namespace Statement . . . . . . . . . . . . . . . . 63 10.45. The presence Statement . . . . . . . . . . . . . . . . . 54
11.37. The notification Statement . . . . . . . . . . . . . . . 63 10.46. The range Statement . . . . . . . . . . . . . . . . . . 54
11.38. The ordered-by Statement . . . . . . . . . . . . . . . . 63 10.47. The reference Statement . . . . . . . . . . . . . . . . 54
11.39. The organization Statement . . . . . . . . . . . . . . . 63 10.48. The require-instance Statement . . . . . . . . . . . . . 54
11.40. The output Statement . . . . . . . . . . . . . . . . . . 63 10.49. The revision Statement . . . . . . . . . . . . . . . . . 54
11.41. The path Statement . . . . . . . . . . . . . . . . . . . 63 10.50. The rpc Statement . . . . . . . . . . . . . . . . . . . 55
11.42. The pattern Statement . . . . . . . . . . . . . . . . . 64 10.51. The status Statement . . . . . . . . . . . . . . . . . . 55
11.43. The position Statement . . . . . . . . . . . . . . . . . 64 10.52. The submodule Statement . . . . . . . . . . . . . . . . 55
11.44. The prefix Statement . . . . . . . . . . . . . . . . . . 64 10.53. The type Statement . . . . . . . . . . . . . . . . . . . 55
11.45. The presence Statement . . . . . . . . . . . . . . . . . 64 10.53.1. The empty Type . . . . . . . . . . . . . . . . . . 56
11.46. The range Statement . . . . . . . . . . . . . . . . . . 64 10.53.2. The boolean and binary Types . . . . . . . . . . . 57
11.47. The reference Statement . . . . . . . . . . . . . . . . 64 10.53.3. The bits Type . . . . . . . . . . . . . . . . . . . 57
11.48. The require-instance Statement . . . . . . . . . . . . . 64 10.53.4. The enumeration and union Types . . . . . . . . . . 57
11.49. The revision Statement . . . . . . . . . . . . . . . . . 64 10.53.5. The identityref Type . . . . . . . . . . . . . . . 57
11.50. The rpc Statement . . . . . . . . . . . . . . . . . . . 65 10.53.6. The instance-identifier Type . . . . . . . . . . . 58
11.51. The status Statement . . . . . . . . . . . . . . . . . . 65 10.53.7. The leafref Type . . . . . . . . . . . . . . . . . 58
11.52. The submodule Statement . . . . . . . . . . . . . . . . 65 10.53.8. The numeric Types . . . . . . . . . . . . . . . . . 58
11.53. The type Statement . . . . . . . . . . . . . . . . . . . 65 10.53.9. The string Type . . . . . . . . . . . . . . . . . . 60
11.53.1. The empty Type . . . . . . . . . . . . . . . . . . 66 10.53.10. Derived Types . . . . . . . . . . . . . . . . . . . 61
11.53.2. The boolean and binary Types . . . . . . . . . . . 67 10.54. The typedef Statement . . . . . . . . . . . . . . . . . 62
11.53.3. The bits Type . . . . . . . . . . . . . . . . . . . 67 10.55. The unique Statement . . . . . . . . . . . . . . . . . . 62
11.53.4. The enumeration and union Types . . . . . . . . . . 67 10.56. The units Statement . . . . . . . . . . . . . . . . . . 63
11.53.5. The identityref Type . . . . . . . . . . . . . . . 67 10.57. The uses Statement . . . . . . . . . . . . . . . . . . . 63
11.53.6. The instance-identifier Type . . . . . . . . . . . 69 10.58. The value Statement . . . . . . . . . . . . . . . . . . 63
11.53.7. The leafref Type . . . . . . . . . . . . . . . . . 69 10.59. The when Statement . . . . . . . . . . . . . . . . . . . 63
11.53.8. The numeric Types . . . . . . . . . . . . . . . . . 69 10.60. The yang-version Statement . . . . . . . . . . . . . . . 63
11.53.9. The string Type . . . . . . . . . . . . . . . . . . 71 10.61. The yin-element Statement . . . . . . . . . . . . . . . 63
11.53.10. Derived Types . . . . . . . . . . . . . . . . . . . 72 11. Mapping the Hybrid Schema to DSDL . . . . . . . . . . . . . . 64
11.54. The typedef Statement . . . . . . . . . . . . . . . . . 73 11.1. Generating RELAX NG Schemas for Various Document Types . 64
11.55. The unique Statement . . . . . . . . . . . . . . . . . . 73 11.2. Mapping Semantic Constraints to Schematron . . . . . . . 65
11.56. The units Statement . . . . . . . . . . . . . . . . . . 73 11.2.1. Constraints on Mandatory Choice . . . . . . . . . . 68
11.57. The uses Statement . . . . . . . . . . . . . . . . . . . 74 11.3. Mapping Default Values to DSRL . . . . . . . . . . . . . 69
11.58. The value Statement . . . . . . . . . . . . . . . . . . 74 12. Mapping NETMOD-specific Annotations to DSDL Schema
11.59. The when Statement . . . . . . . . . . . . . . . . . . . 74
11.60. The yang-version Statement . . . . . . . . . . . . . . . 74
11.61. The yin-element Statement . . . . . . . . . . . . . . . 74
12. Mapping NETMOD-specific annotations to DSDL Schema
Languages . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Languages . . . . . . . . . . . . . . . . . . . . . . . . . . 75
12.1. The @nma:config Annotation . . . . . . . . . . . . . . . 75 12.1. The @nma:config Annotation . . . . . . . . . . . . . . . 75
12.2. The @nma:default Annotation . . . . . . . . . . . . . . 75 12.2. The @nma:default Annotation . . . . . . . . . . . . . . 75
12.3. The @nma:implicit Annotation . . . . . . . . . . . . . . 75 12.3. The <nma:error-app-tag> Annotation . . . . . . . . . . . 75
12.4. The <nma:error-app-tag> Annotation . . . . . . . . . . . 75 12.4. The <nma:error-message> Annotation . . . . . . . . . . . 75
12.5. The <nma:error-message> Annotation . . . . . . . . . . . 75 12.5. The @if-feature Annotation . . . . . . . . . . . . . . . 75
12.6. The <nma:instance-identifier> Annotation . . . . . . . . 75 12.6. The @nma:implicit Annotation . . . . . . . . . . . . . . 76
12.7. The @nma:key Annotation . . . . . . . . . . . . . . . . 76 12.7. The <nma:instance-identifier> Annotation . . . . . . . . 76
12.8. The @nma:leafref Annotation . . . . . . . . . . . . . . 76 12.8. The @nma:key Annotation . . . . . . . . . . . . . . . . 76
12.9. The @nma:min-elements Annotation . . . . . . . . . . . . 76 12.9. The @nma:leaf-list Annotation . . . . . . . . . . . . . 76
12.10. The @nma:max-elements Annotation . . . . . . . . . . . . 77 12.10. The @nma:leafref Annotation . . . . . . . . . . . . . . 77
12.11. The <nma:must> Annotation . . . . . . . . . . . . . . . 77 12.11. The @nma:min-elements Annotation . . . . . . . . . . . . 77
12.12. The <nma:ordered-by> Annotation . . . . . . . . . . . . 77 12.12. The @nma:max-elements Annotation . . . . . . . . . . . . 77
12.13. The <nma:status> Annotation . . . . . . . . . . . . . . 77 12.13. The <nma:must> Annotation . . . . . . . . . . . . . . . 77
12.14. The @nma:unique Annotation . . . . . . . . . . . . . . . 77 12.14. The <nma:ordered-by> Annotation . . . . . . . . . . . . 78
12.15. The @nma:when Annotation . . . . . . . . . . . . . . . . 78 12.15. The <nma:status> Annotation . . . . . . . . . . . . . . 78
12.16. The @nma:unique Annotation . . . . . . . . . . . . . . . 78
12.17. The @nma:when Annotation . . . . . . . . . . . . . . . . 78
13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 79 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 79
14. Security Considerations . . . . . . . . . . . . . . . . . . . 80 14. Security Considerations . . . . . . . . . . . . . . . . . . . 80
15. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 81 15. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 81
16. References . . . . . . . . . . . . . . . . . . . . . . . . . 82 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 82
16.1. Normative References . . . . . . . . . . . . . . . . . . 82 16.1. Normative References . . . . . . . . . . . . . . . . . . 82
16.2. Informative References . . . . . . . . . . . . . . . . . 83 16.2. Informative References . . . . . . . . . . . . . . . . . 83
Appendix A. Schemas for NETMOD-Specific Annotations . . . . . . 86 Appendix A. RELAX NG Schema for NETMOD-Specific Annotations . . 86
A.1. NVDL Schema . . . . . . . . . . . . . . . . . . . . . . 86 Appendix B. Schema-Independent Library . . . . . . . . . . . . . 91
A.2. Annotation Attributes for define Pattern . . . . . . . . 88 Appendix C. Mapping DHCP Data Model - A Complete Example . . . . 92
A.3. Annotation Elements for element Pattern . . . . . . . . 88 C.1. Input YANG Module . . . . . . . . . . . . . . . . . . . 92
A.4. Annotation Attributes for element Pattern . . . . . . . 89 C.2. Hybrid Schema . . . . . . . . . . . . . . . . . . . . . 94
A.5. Annotation attributes for group Pattern . . . . . . . . 89 C.3. Final DSDL Schemas . . . . . . . . . . . . . . . . . . . 99
A.6. Annotation attributes for choice and ref Patterns . . . 90 C.3.1. Main RELAX NG Schema for <nc:get> Reply . . . . . . 100
A.7. Annotation attributes for element Pattern in the List C.3.2. RELAX NG Schema - Global Named Pattern
Context . . . . . . . . . . . . . . . . . . . . . . . . 90 Definitions . . . . . . . . . . . . . . . . . . . . 102
A.8. Annotation attributes for value Pattern . . . . . . . . 91 C.3.3. Schematron Schema for <nc:get> Reply . . . . . . . 104
A.9. Named Patterns for All NETMOD-Specific Annotations . . . 91 C.3.4. DSRL Schema for <nc:get> Reply . . . . . . . . . . 106
Appendix B. Schema-Independent Library . . . . . . . . . . . . . 95 Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 107
Appendix C. Mapping DHCP Data Model - A Complete Example . . . . 96 D.1. Changes Between Versions -05 and -06 . . . . . . . . . . 107
C.1. Input YANG Module . . . . . . . . . . . . . . . . . . . 96 D.2. Changes Between Versions -04 and -05 . . . . . . . . . . 107
C.2. Conceptual Tree Schema . . . . . . . . . . . . . . . . . 99 D.3. Changes Between Versions -04 and -05 . . . . . . . . . . 107
C.2.1. XML Syntax . . . . . . . . . . . . . . . . . . . . 99 D.4. Changes Between Versions -03 and -04 . . . . . . . . . . 108
C.2.2. Compact Syntax . . . . . . . . . . . . . . . . . . 104 D.5. Changes Between Versions -02 and -03 . . . . . . . . . . 109
C.3. Final DSDL Schemas . . . . . . . . . . . . . . . . . . . 106 D.6. Changes Between Versions -01 and -02 . . . . . . . . . . 109
C.3.1. RELAX NG Schema for <get> Reply - XML Syntax . . . 107 D.7. Changes Between Versions -00 and -01 . . . . . . . . . . 110
C.3.2. RELAX NG Schema for <get> Reply - Compact Syntax . 111 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 111
C.4. Schematron Schema for <get> Reply . . . . . . . . . . . 113
C.5. DSRL Schema for <get> Reply . . . . . . . . . . . . . . 115
Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 116
D.1. Changes Between Versions -04 and -05 . . . . . . . . . . 116
D.2. Changes Between Versions -03 and -04 . . . . . . . . . . 116
D.3. Changes Between Versions -02 and -03 . . . . . . . . . . 117
D.4. Changes Between Versions -01 and -02 . . . . . . . . . . 117
D.5. Changes Between Versions -00 and -01 . . . . . . . . . . 118
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 119
1. Introduction 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 [RFC4741]. This base specification defines configuration management [RFC4741]. 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 data modeling language
accompanying rules for how to model configuration and status or accompanying rules for how to model configuration and state
information (in XML syntax) carried by NETCONF. The IETF Operations information carried by NETCONF. The IETF Operations Area has a long
Area has a long tradition of defining data for SNMP Management tradition of defining data for SNMP Management Information Bases
Information Bases (MIBs) [RFC1157] using the SMI language [RFC2578] (MIBs) [RFC1157] using the SMI language [RFC2578] to model its data.
to model its data. While this specific modeling approach has a While this specific modeling approach has a number of well-understood
number of well-understood problems, most of the data modeling problems, most of the data modeling features provided by SMI are
features provided by SMI are still considered extremely important. still considered extremely important. Simply modeling the valid
Simply modeling the valid syntax without the additional semantic syntax without the additional semantic relationships has caused
relationships has caused significant interoperability problems in the significant interoperability problems in the past.
past.
The NETCONF community concluded that a data modeling framework is The NETCONF community concluded that a data modeling framework is
needed to support ongoing development of IETF and vendor-defined needed to support ongoing development of IETF and vendor-defined
management information modules. The NETMOD Working Group was management information modules. The NETMOD Working Group was
chartered to address this problem by defining a new human-friendly chartered to address this problem by defining a new human-friendly
modeling language based on SMIng [RFC3216] and called YANG [YANG]. modeling language based on SMIng [RFC3216] and called YANG [YANG].
Since NETCONF uses XML for encoding its protocol data units (PDU), it Since NETCONF uses XML for encoding its messages, it is natural to
is natural to express the constraints on NETCONF content using express the constraints on NETCONF content using standard XML schema
standard XML schema languages. For this purpose, the NETMOD WG languages. For this purpose, the NETMOD WG selected the Document
selected the Document Schema Definition Languages (DSDL) that is Schema Definition Languages (DSDL) that is being standardized as ISO/
being standardized as ISO/IEC 19757 [DSDL]. The DSDL framework IEC 19757 [DSDL]. The DSDL framework comprises a set of XML schema
comprises a set of XML schema languages that address grammar rules, languages that address grammar rules, semantic constraints and other
semantic constraints and other data modeling aspects but also, and data modeling aspects, but also, and more importantly, do it in a
more importantly, do it in a coordinated and consistent way. While coordinated and consistent way. While it is true that some DSDL
it is true that some DSDL parts have not been standardized yet and parts have not been standardized yet and are still work in progress,
are still work in progress, the three parts that the YANG-to-DSDL the three parts that the YANG-to-DSDL mapping relies upon - RELAX NG,
mapping relies upon - RELAX NG, Schematron and DSRL - already have Schematron and DSRL - already have the status of an ISO/IEC
the status of an ISO/IEC International Standard and are supported in International Standard and are supported in a number of software
a number of software tools. tools.
This document contains specification of a mapping that translates This document contains a specification of a mapping that translates
YANG data models to XML schemas utilizing a subset of the DSDL schema YANG data models to XML schemas utilizing a subset of the DSDL schema
languages. The mapping procedure is divided into two steps: In the languages. The mapping procedure is divided into two steps: In the
first step, the structure of the data tree, RPC signatures and first step, the structure of the data tree, signatures of RPC
notifications is expressed as a single RELAX NG grammar with simple operations and notifications is expressed as the so-called "hybrid
annotations representing additional data model information (metadata, schema" - a single RELAX NG schema with annotations representing
documentation, semantic constraints, default values etc.). The additional data model information (metadata, documentation, semantic
second step then generates a coordinated set of DSDL schemas that can constraints, default values etc.). The second step then generates a
validate specific XML documents such as client requests, server coordinated set of DSDL schemas that can be used for validating
responses or notifications, perhaps also taking into account specific XML documents such as client requests, server responses or
additional context such as active capabilities. notifications, perhaps also taking into account additional context
such as active capabilities or features.
2. Terminology and Notation 2. Terminology and Notation
This document relies on many terms that are defined in the
specifications of the NETCONF protocol [RFC4741] and YANG data
modeling language [YANG]. Also, the common terminology of XML and
DSDL schema languages is used as defined in the respective standards
[XML], [DSDL], [NVDL], [RNG], [Schematron] and [DSRL].
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
In the text, we use the following typographic conventions: The following terms are defined in [RFC4741]:
o client
o datastore
o message
o operation
o server
The following terms are defined in [YANG]:
o augment
o base type
o built-in type
o configuration data
o container
o data model
o data node
o data tree
o derived type
o device deviation
o extension
o feature
o grouping
o instance identifier
o leaf-list
o list
o mandatory node
o module
o RPC
o RPC operation
o schema node
o schema tree
o state data
o submodule
o top-level data node
o uses
The following terms are defined in [XML-INFOSET]:
o attribute
o document
o document element
o document type declaration (DTD)
o element
o information set
o namespace
In the text, the following typographic conventions are used:
o YANG statement keywords are delimited by single quotes. o YANG statement keywords are delimited by single quotes.
o XML element names are delimited by "<" and ">" characters. o XML element names are delimited by "<" and ">" characters.
o Names of XML attributes are prefixed by the "@" character. o Names of XML attributes are prefixed by the "@" character.
o Other literal values are delimited by double quotes. o Other literal values are delimited by double quotes.
XML elements names are always written with explicit namespace XML elements names are always written with explicit namespace
skipping to change at page 7, line 42 skipping to change at page 9, line 22
"dc" Dublin Core metadata elements [RFC5013]; "dc" Dublin Core metadata elements [RFC5013];
"dsrl" Document Semantics Renaming Language [DSRL]; "dsrl" Document Semantics Renaming Language [DSRL];
"en" NETCONF event notifications [RFC5277]; "en" NETCONF event notifications [RFC5277];
"nc" NETCONF protocol [RFC4741]; "nc" NETCONF protocol [RFC4741];
"nma" NETMOD-specific schema annotations (see Section 5.3); "nma" NETMOD-specific schema annotations (see Section 5.3);
"nmf" NETMOD-specific XPath extension functions (see Section 12.6); "nmf" NETMOD-specific XPath extension functions (see Section 12.7);
"nmt" Conceptual tree (see Section 8.1);
"rng" RELAX NG [RNG]; "rng" RELAX NG [RNG];
"sch" ISO Schematron [Schematron]; "sch" ISO Schematron [Schematron];
"xsd" W3C XML Schema [XSD]. "xsd" W3C XML Schema [XSD].
The following table shows the mapping of these prefixes to namespace The following table shows the mapping of these prefixes to namespace
URIs. URIs.
+--------+-----------------------------------------------------+ +--------+-----------------------------------------------------+
| Prefix | Namespace URI | | Prefix | Namespace URI |
+--------+-----------------------------------------------------+ +--------+-----------------------------------------------------+
| a | http://relaxng.org/ns/compatibility/annotations/1.0 | | a | http://relaxng.org/ns/compatibility/annotations/1.0 |
| | | | | |
skipping to change at page 8, line 26 skipping to change at page 10, line 22
| dsrl | http://purl.oclc.org/dsdl/dsrl | | dsrl | http://purl.oclc.org/dsdl/dsrl |
| | | | | |
| en | urn:ietf:params:xml:ns:netconf:notification:1.0 | | en | urn:ietf:params:xml:ns:netconf:notification:1.0 |
| | | | | |
| nc | urn:ietf:params:xml:ns:netconf:base:1.0 | | nc | urn:ietf:params:xml:ns:netconf:base:1.0 |
| | | | | |
| nma | urn:ietf:params:xml:ns:netmod:dsdl-annotations:1 | | nma | urn:ietf:params:xml:ns:netmod:dsdl-annotations:1 |
| | | | | |
| nmf | urn:ietf:params:xml:ns:netmod:xpath-extensions:1 | | nmf | urn:ietf:params:xml:ns:netmod:xpath-extensions:1 |
| | | | | |
| nmt | urn:ietf:params:xml:ns:netmod:conceptual-tree:1 |
| | |
| rng | http://relaxng.org/ns/structure/1.0 | | rng | http://relaxng.org/ns/structure/1.0 |
| | | | | |
| sch | http://purl.oclc.org/dsdl/schematron | | sch | http://purl.oclc.org/dsdl/schematron |
| | | | | |
| xsd | http://www.w3.org/2001/XMLSchema | | xsd | http://www.w3.org/2001/XMLSchema |
+--------+-----------------------------------------------------+ +--------+-----------------------------------------------------+
Table 1: Used namespace prefixes and corresponding URIs Table 1: Used namespace prefixes and corresponding URIs
2.1. Glossary of New Terms 2.1. Glossary of New Terms
o ancestor datatype: Any datytype a given datatype is (transitively) o ancestor datatype: Any datatype a given datatype is (transitively)
derived from. derived from.
o ancestor built-in datatype: The built-in datatype that is at the o ancestor built-in datatype: The built-in datatype that is at the
start of the type derivation chain for a given datatype. start of the type derivation chain for a given datatype.
o conceptual data tree: A virtual XML document integrating all o hybrid schema: A RELAX NG schema with annotations, which embodies
components of a YANG data model, i.e., configuration datastore, the same information as the source YANG module(s). See
RPC methods (both requests and replies) and notifications. The Section 8.1 for details.
conceptual tree is normally not instantiated, it only serves as a
conceptual target for its schema. See Section 8.1 for details.
o implicit node: A node that, if missing, may be added to the o implicit node: A node that, if missing, may be added to the
information set of an XML document (configuration, RPC input or information set of an XML document (configuration, RPC input or
output, notification) without changing the meaning of that XML output, notification) without changing the meaning of that XML
document. document.
3. Objectives and Motivation 3. Objectives and Motivation
The main objective of this work is to complement YANG as a data The main objective of this work is to complement YANG as a data
modeling language by validation capabilities of DSDL schema modeling language by validation capabilities of DSDL schema
languages, namely RELAX NG, Schematron and DSRL. This document languages, namely RELAX NG, Schematron and DSRL. This document
describes the correspondence between grammatical, semantic and data describes the correspondence between grammatical, semantic and data
type constraints expressed in YANG and equivalent DSDL constructs. type constraints expressed in YANG and equivalent DSDL patterns and
The ultimate goal is to be able to capture all substantial rules. The ultimate goal is to be able to capture all substantial
information contained in YANG modules and express it in DSDL schemas. information contained in YANG modules and express it in DSDL schemas.
While the mapping from YANG to DSDL described in this document is in While the mapping from YANG to DSDL described in this document may in
principle invertible, the inverse mapping from DSDL to YANG is not in principle be invertible, the inverse mapping from DSDL to YANG beyond
its scope. the scope of this document.
XML-based information models and XML-encoded data appear in several XML-based information models and XML-encoded data appear in several
different forms in various phases of YANG data modeling and NETCONF different forms in various phases of YANG data modeling and NETCONF
workflow - configuration datastore contents, RPC requests and workflow - configuration datastore contents, RPC requests and
replies, and notifications. Moreover, RPC methods are characterized replies, and notifications. Moreover, RPC operations are
by an inherent diversity resulting from selective availability of characterized by an inherent diversity resulting from selective
capabilities and features. YANG modules can also define new RPC availability of capabilities and features. YANG modules can also
methods. The mapping should be able to accommodate this variability define new RPC operations. The mapping should be able to accommodate
and generate schemas that are specifically tailored to a particular this variability and generate schemas that are specifically tailored
situation and thus considerably more effective for validation than to a particular situation and thus considerably more effective for
generic all-encompassing schemas. validation than generic all-encompassing schemas.
In order to cope with this variability, we assume that the schemas In order to cope with this variability, we assume that the DSDL
can be generated on demand for a particular purpose from the schemas will be generated on demand for a particular purpose from the
available collection of YANG modules and their lifetime will be available collection of YANG modules and their lifetime will be
relatively short. In other words, we don't envision that any relatively short. In other words, we don't envision that any
collection of DSDL schemas will be created and maintained over an collection of DSDL schemas will be created and maintained over an
extended period of time in parallel to YANG modules. extended period of time in parallel to YANG modules.
The generated schemas are primarily intended as input to the existing The generated schemas are primarily intended as input to existing XML
XML schema validators and other off-the-shelf tools. However, the schema validators and other off-the-shelf tools. However, the
schemas may also be perused by developers and users as a formal schemas may also be perused by developers and users as a formal
representation of constraints on a particular XML-encoded data representation of constraints on a particular XML-encoded data
object. Consequently, our secondary goal is to keep the schemas as object. Consequently, our secondary goal is to keep the schemas as
readable as possible. To this end, the complexity of the mapping is readable as possible. To this end, the complexity of the mapping is
distributed into two steps: distributed into two steps:
1. The first step maps one or more YANG modules to a single RELAX NG 1. The first step maps one or more YANG modules to the so-called
schema of the so-called "conceptual tree", which contains hybrid schema, which is a single RELAX NG schema that describes
grammatical constraints for the main data tree as well as RPCs grammatical constraints for the main data tree as well as for RPC
and notifications. In order to record additional constraints operations and notifications. Semantic constraints and other
that appear in the YANG modules but cannot be expressed in RELAX information appearing in the input YANG modules is recorded in
NG, the schema is augmented by simple annotations. The output of the hybrid schema in the form of foreign namespace annotations.
the first step can thus be considered a reasonably readable The output of the first step can thus be considered a virtually
equivalent of the input YANG modules. complete equivalent of the input YANG modules.
2. In the second step, the annotated RELAX NG schema from step 1 is 2. In the second step, the hybrid schema from step 1 is transformed
transformed further to a coordinated set of fully conformant DSDL further to a coordinated set of fully conformant DSDL schemas
schemas containing constraints for a particular data object and a containing constraints for a particular data object and a
specific situation. The DSDL schemas are intended mainly for specific situation. The DSDL schemas are intended mainly for
machine validation using off-the-shelf tools. machine validation using off-the-shelf tools.
4. DSDL Schema Languages 4. DSDL Schema Languages
Document Schema Definition Languages (DSDL) is a framework of schema Document Schema Definition Languages (DSDL) is a framework of schema
languages that is being developed as an international standard ISO/ languages that is being developed as the International Standard ISO/
IEC 19757. Unlike other approaches to XML document validation, most IEC 19757. Unlike other approaches to XML document validation, most
notably W3C XML Schema (XSD) [XSD], the DSDL framework adheres to the notably W3C XML Schema (XSD) [XSD], the DSDL framework adheres to the
principle of "small languages": Each of the DSDL constituents is a principle of "small languages": Each of the DSDL constituents is a
stand-alone schema language with a relatively narrow purpose and stand-alone schema language with a relatively narrow purpose and
focus. Together, these schema languages may be used in a coordinated focus. Together, these schema languages may be used in a coordinated
way to accomplish various validation tasks. way to accomplish various validation tasks.
The mapping described in this document uses three of the DSDL schema The mapping described in this document uses three of the DSDL schema
languages, namely RELAX NG, Schematron and DSRL. languages, namely RELAX NG, Schematron and DSRL.
4.1. RELAX NG 4.1. RELAX NG
RELAX NG (pronounced "relaxing") is an XML schema language for RELAX NG (pronounced "relaxing") is an XML schema language for
grammar-based validation and Part 2 of the ISO/IEC DSDL family of grammar-based validation and Part 2 of the ISO/IEC DSDL family of
standards [RNG]. Like the W3C XML Schema language [XSD], it is able standards [RNG]. Like the W3C XML Schema language [XSD], it is able
to describe constraints on the structure and content of XML to describe constraints on the structure and contents of XML
documents. However, unlike the DTD [XML] and XSD schema languages, documents. However, unlike the DTD [XML] and XSD schema languages,
RELAX NG intentionally avoids any infoset augmentation such as RELAX NG intentionally avoids any infoset augmentation such as
defining default values. In the DSDL architecture, the particular defining default values. In the DSDL architecture, the particular
task of defining and applying default values is delegated to another task of defining and applying default values is delegated to another
schema language, DSRL (see Section 4.3). schema language, DSRL (see Section 4.3).
As its base datatype library, RELAX NG uses the W3C XML Schema As its base datatype library, RELAX NG uses the W3C XML Schema
Datatype Library [XSD-D], but unlike XSD, other datatype libraries Datatype Library [XSD-D], but unlike XSD, other datatype libraries
may be used along with it or even replace it if necessary. may be used along with it or even replace it if necessary.
RELAX NG is very liberal in accepting annotations from other RELAX NG is very liberal in accepting annotations from other
namespaces. With few exceptions, such annotations may be placed namespaces. With a few exceptions, such annotations may be placed
anywhere in the schema and need no encapsulating elements such as anywhere in the schema and need no encapsulating elements such as
<xsd:annotation> in XSD. <xsd:annotation> in XSD.
RELAX NG schemas can be represented in two equivalent syntaxes: XML RELAX NG schemas can be represented in two equivalent syntaxes: XML
and compact. The compact syntax is described in Annex C of the RELAX and compact. The compact syntax is described in Annex C of the RELAX
NG specification [RNG-CS], which was added to the standard in 2006 NG specification [RNG-CS], which was added to the standard in 2006
(Amendment 1). Automatic bidirectional conversions between the two (Amendment 1). Automatic bidirectional conversions between the two
syntaxes can be accomplished using several tools, for example syntaxes can be accomplished using several tools, for example
Trang [1]. Trang [1].
For its terseness and readability, the compact syntax is often the For its terseness and readability, the compact syntax is often the
preferred form for publishing RELAX NG schemas whereas validators and preferred form for publishing RELAX NG schemas whereas validators and
other software tools usually work with the XML syntax. However, the other software tools usually work with the XML syntax. However, the
compact syntax has two drawbacks: compact syntax has two drawbacks:
o External annotations make the compact syntax schema considerably o External annotations make the compact syntax schema considerably
less readable. While in the XML syntax the annotating elements less readable. While in the XML syntax the annotating elements
and attributes are represented in a simple and uniform way (XML and attributes are represented in a simple and uniform way (XML
elements and attributes from foreign namespaces), the compact elements and attributes from foreign namespaces), the compact
syntax uses four different syntactic constructs: documentation, syntax uses as many as four different syntactic constructs:
grammar, initial and following annotations. Therefore, the impact documentation, grammar, initial and following annotations.
of annotations on readability is often much stronger for the Therefore, the impact of annotations on readability is often much
compact syntax than for the XML syntax. stronger for the compact syntax than it is for the XML syntax.
o In a computer program, it is more difficult to generate the o In a computer program, it is more difficult to generate the
compact syntax than the XML syntax. While a number of software compact syntax than the XML syntax. While a number of software
libraries exist that make it easy to create an XML tree in memory libraries exist that make it easy to create an XML tree in the
and serialize it, no such aid is available for compact syntax. memory and then serialize it, no such aid is available for the
compact syntax.
For these reasons, the mapping specification in this document uses For these reasons, the mapping specification in this document uses
exclusively the XML syntax. Where appropriate, though, the schemas exclusively the XML syntax. Where appropriate, though, the schemas
resulting from the translation may be presented in the equivalent resulting from the translation MAY be presented in the equivalent
compact syntax. compact syntax.
RELAX NG elements are qualified with the namespace URI RELAX NG elements are qualified with the namespace URI
"http://relaxng.org/ns/structure/1.0". The namespace of the W3C "http://relaxng.org/ns/structure/1.0". The namespace of the W3C
Schema Datatype Library is Schema Datatype Library is
"http://www.w3.org/2001/XMLSchema-datatypes". "http://www.w3.org/2001/XMLSchema-datatypes".
4.2. Schematron 4.2. Schematron
Schematron is Part 3 of DSDL that reached the status of a full ISO/ Schematron is Part 3 of DSDL that reached the status of a full ISO/
skipping to change at page 14, line 11 skipping to change at page 15, line 12
former is positive in that it states a condition that a valid former is positive in that it states a condition that a valid
document has to satisfy, whereas the latter specifies an error document has to satisfy, whereas the latter specifies an error
condition. condition.
Schematron draws most of its expressive power from XPath [XPath] and Schematron draws most of its expressive power from XPath [XPath] and
XSLT [XSLT]. ISO Schematron allows for dynamic query language XSLT [XSLT]. ISO Schematron allows for dynamic query language
binding so that the following XML query languages can be used: STX, binding so that the following XML query languages can be used: STX,
XSLT 1.0, XSLT 1.1, EXSLT, XSLT 2.0, XPath 1.0, XPath 2.0 and XSLT 1.0, XSLT 1.1, EXSLT, XSLT 2.0, XPath 1.0, XPath 2.0 and
XQuery 1.0 (this list may be extended in the future). XQuery 1.0 (this list may be extended in the future).
The human-readable error messages are another feature that Human-readable error messages are another feature that sets
distinguishes Schematron from other common schema languages. The Schematron apart from other common schema languages. The messages
messages may even contain XPath expressions that are evaluated in the may even contain XPath expressions that are evaluated in the actual
actual context and thus refer to existing XML document nodes and context and thus refer to information items in the XML document being
their contents. validated.
The rules defined by a Schematron schema may be divided into several Another feature of Schematron that is used by the mapping are
subsets known as phases. Validations may then be set up to include abstract patterns. These work essentially as macros and may also
only selected phases. In the context of NETCONF data validation, contain parameters which are supplied when the abstract pattern is
this is useful for relaxing constraints that may not always apply. used.
For example, the reference integrity may not be enforced for a
candidate configuration.
Schematron elements are qualified with namespace URI Schematron elements are qualified with namespace URI
"http://purl.oclc.org/dsdl/schematron". "http://purl.oclc.org/dsdl/schematron".
4.3. Document Semantics Renaming Language (DSRL) 4.3. Document Semantics Renaming Language (DSRL)
DSRL (pronounced "disrule") is Part 8 of DSDL that reached the status DSRL (pronounced "disrule") is Part 8 of DSDL that reached the status
of a full ISO/IEC standard in 2008 [DSRL]. Unlike RELAX NG and of a full ISO/IEC standard in 2008 [DSRL]. Unlike RELAX NG and
Schematron, it is specifically designed to modify XML information set Schematron, DSRL is allowed to modify XML information set of the
of the validated document. While DSRL is primarily intended for validated document. While DSRL is primarily intended for renaming
renaming XML elements and attributes, it can also define default XML elements and attributes, it can also define default values for
values for XML attributes and default content for XML elements so XML attributes and default contents for XML elements or subtrees so
that elements or attributes with these default values are inserted if that the default contents are inserted if they are missing in the
they are missing (or present and empty) in the validated documents. validated documents. The latter feature is used by the YANG-to-DSDL
The latter feature is used by the YANG-to-DSDL mapping for mapping for representing YANG default contents consisting of leaf
representing YANG default contents consisting of leaf nodes with nodes with default values and their ancestor non-presence containers.
default values and their ancestor non-presence containers.
DSRL elements are qualified with namespace URI DSRL elements are qualified with namespace URI
"http://purl.oclc.org/dsdl/dsrl". "http://purl.oclc.org/dsdl/dsrl".
5. Additional Annotations 5. Additional Annotations
Besides the DSDL schema languages, the mapping also uses three sets Besides the DSDL schema languages, the mapping also uses three sets
of annotations that are added as foreign-namespace attributes and of annotations that are added as foreign-namespace attributes and
elements to RELAX NG schemas. Two of the annotation sets - Dublin elements to RELAX NG schemas.
Core elements and DTD compatibility annotations - are standard
vocabularies for representing metadata and documentation,
respectively. Although these data model items are not used for
formal validation, they quite often carry important information for
data model implementers. Therefore, they SHOULD be included in the
conceptual tree schema and MAY also appear in the final validation
schemas.
The third set are NETMOD-specific annotations conveying YANG semantic Two of the annotation sets - Dublin Core elements and DTD
constraints and other information that cannot be expressed directly compatibility annotations - are standard vocabularies for
in RELAX NG. These annotations are only used in the first step of representing metadata and documentation, respectively. Although
the mapping, i.e., in the conceptual tree schema. In the second these data model items are not used for formal validation, they quite
mapping step, these annotations are converted to Schematron and DSRL often carry important information for data model implementers.
rules. Therefore, they SHOULD be included in the hybrid schema and MAY also
appear in the final validation schemas.
The third set are NETMOD-specific annotations. They are specifically
designed for the hybrid schema and convey semantic constraints and
other information that cannot be expressed directly in RELAX NG. In
the second mapping step, these annotations are converted to
Schematron and DSRL rules.
5.1. Dublin Core Metadata Elements 5.1. Dublin Core Metadata Elements
Dublin Core [2] is a system of metadata elements that was originally Dublin Core [2] is a system of metadata elements that was originally
created for describing metadata of World Wide Web resources in order created for describing metadata of World Wide Web resources in order
to facilitate their automated lookup. Later it was accepted as a to facilitate their automated lookup. Later it was accepted as a
standard for describing metadata of arbitrary resources. This standard for describing metadata of arbitrary resources. This
specification uses the definition from [RFC5013]. specification uses the definition from [RFC5013].
Dublin Core elements are qualified with namespace URI Dublin Core elements are qualified with namespace URI
"http://purl.org/dc/terms". "http://purl.org/dc/terms".
5.2. RELAX NG DTD Compatibility Annotations 5.2. RELAX NG DTD Compatibility Annotations
DTD compatibility annotations are part of the RELAX NG DTD DTD compatibility annotations are a part of the RELAX NG DTD
Compatibility specification [RNG-DTD]. YANG-to-DSDL mapping uses Compatibility specification [RNG-DTD]. YANG-to-DSDL mapping uses
only the <a:documentation> annotation for representing YANG only the <a:documentation> annotation for representing YANG
'description' and 'reference' texts. 'description' and 'reference' texts.
Note that there is no intention to make the resulting schemas DTD- Note that there is no intention to make the resulting schemas DTD-
compatible, the main reason for using these annotations is technical: compatible, the main reason for using these annotations is technical:
they are well supported and adequately interpreted by several RELAX they are well supported and adequately formatted by several RELAX NG
NG tools. tools.
DTD compatibility annotations are qualified with namespace URI DTD compatibility annotations are qualified with namespace URI
"http://relaxng.org/ns/compatibility/annotations/1.0". "http://relaxng.org/ns/compatibility/annotations/1.0".
5.3. NETMOD-Specific Annotations 5.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" which appear in
various locations of the conceptual tree schema. YANG statements are various locations of the hybrid schema. YANG statements are mapped
mapped to these annotations in a straightforward way. In most cases, to these annotations in a straightforward way. In most cases, the
the annotation attributes and elements have the same name as the annotation attributes and elements have the same name as the
corresponding YANG statement. corresponding YANG statement.
Table 2 lists alphabetically the names of NETMOD-specific annotation Table 2 lists alphabetically the names of NETMOD-specific annotation
attributes (prefixed with "@") and elements (in angle brackets) along attributes (prefixed with "@") and elements (in angle brackets) 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 contains the formal specification of this annotation Appendix A contains a RELAX NG schema for this annotation vocabulary.
vocabulary.
+---------------------------+--------------------+------+ +---------------------------+--------------------+------+
| annotation | section | note | | annotation | section | note |
+---------------------------+--------------------+------+ +---------------------------+--------------------+------+
| @nma:config | 11.9 | | | @nma:config | 10.9 | |
| | | | | | | |
| @nma:default | 11.12 | | | <nma:data> | Section 8.1 | 4 |
| | | | | | | |
| @nma:implicit | 11.11, 11.7, 11.12 | | | @nma:default | 10.12 | |
| | | | | | | |
| <nma:error-app-tag> | 11.16 | 1 | | <nma:error-app-tag> | 10.16 | 1 |
| | | | | | | |
| <nma:error-message> | 11.17 | 1 | | <nma:error-message> | 10.17 | 1 |
| | | | | | | |
| <nma:instance-identifier> | 11.53.6 | 2 | | @nma:if-feature | 10.22 | |
| | | | | | | |
| @nma:key | 11.26 | | | @nma:implicit | 10.11, 10.7, 10.12 | |
| | | | | | | |
| @nma:leafref | 11.53.7 | | | <nma:input> | Section 8.1 | 4 |
| | | | | | | |
| @nma:min-elements | 11.28 | | | <nma:instance-identifier> | 10.53.6 | 2 |
| | | | | | | |
| @nma:max-elements | 11.28 | | | @nma:key | 10.26 | |
| | | | | | | |
| <nma:must> | 11.35 | 3 | | @nma:leaf-list | 10.28 | |
| | | | | | | |
| @nma:ordered-by | 11.38 | | | @nma:leafref | 10.53.7 | |
| | | | | | | |
| @nma:presence | 11.45 | | | @nma:mandatory | 10.8 | |
| | | | | | | |
| @nma:status | 11.51 | | | @nma:max-elements | 10.28 | |
| | | | | | | |
| @nma:unique | 11.55 | | | @nma:min-elements | 10.28 | |
| | | | | | | |
| @nma:units | 11.56 | | | @nma:module | 10.34 | |
| | | | | | | |
| @nma:when | 11.59 | | | <nma:must> | 10.35 | 3 |
| | | |
| <nma:notification> | Section 8.1 | 4 |
| | | |
| <nma:notifications> | Section 8.1 | 4 |
| | | |
| @nma:ordered-by | 10.38 | |
| | | |
| <nma:output> | Section 8.1 | 4 |
| | | |
| <nma:rpc> | Section 8.1 | 4 |
| | | |
| <nma:rpcs> | Section 8.1 | 4 |
| | | |
| @nma:status | 10.51 | |
| | | |
| @nma:unique | 10.55 | |
| | | |
| @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 a subelement of <nma:must>.
2. Has an optional attribute @require-instance. 2. Has an optional attribute @require-instance.
3. Has a mandatory attribute @assert and two optional subelements 3. Has a mandatory attribute @assert and two optional subelements
<nma:error-app-tag> and <nma:error-message>. <nma:error-app-tag> and <nma:error-message>.
4. Marker element in the hybrid schema.
6. Overview of the Mapping 6. Overview of the Mapping
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
| |
+-------------------------------------+ +------------------------------------+
| RELAX NG schema for conceptual tree | | hybrid schema |
+-------------------------------------+ +------------------------------------+
/ | | \ / | | \
/ | | \ +-------+ / | | \
Tg/ Tr| |Tn \ |library| Tg/ Tr| |Tn \
/ | | \ +-------+ / | | \
+---------+ +-----+ +-------+ +------+ +---------+ +-----+ +-------+ +------+
|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 the hybrid schema (see Section 8.1). Constraints that cannot
Section 8.1). Constraints that cannot be expressed directly in be expressed directly in RELAX NG (list key definitions, 'must'
RELAX NG (list key definitions, 'must' statements etc.) and statements etc.) and various documentation texts are recorded in
various documentation texts are recorded in the schema as the schema as foreign-namespace annotations.
foreign-namespace annotations.
2. In the second step, the conceptual tree schema is transformed in 2. In the second step, the hybrid schema may be 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 simple possibilities as context. Figure 1 shows three simple possibilities as examples.
examples. In the process, appropriate parts of the conceptual In the process, appropriate parts of the hybrid schema are
tree schema are extracted and specific annotations transformed to extracted and specific annotations transformed to equivalent, but
equivalent, but usually more complex, Schematron patterns, DSRL usually more complex, Schematron patterns, DSRL element maps etc.
element maps etc.
3. As indicated in Figure 1, the second step of the mapping also
uses a schema-independent library that contains common schema
objects such as RELAX NG named pattern definitions.
An implementation of the mapping algorithm is supposed to accept one An implementation of the mapping algorithm MUST accept one or more
or more valid YANG modules as its input. It is important to be able valid YANG modules as its input. It is important to be able to
to process multiple YANG modules together since multiple modules may process multiple YANG modules together since multiple modules may be
be negotiated for a NETCONF session and the contents of the negotiated for a NETCONF session and the contents of the
configuration datastore is then obtained as the union of data trees configuration datastore is then obtained as the union of data trees
specified by the individual modules, which may also lead to multiple specified by the individual modules, which may also lead to multiple
roots. In addition, the input modules may be further coupled by the root nodes of the datastore hierarchy. In addition, the input
'augment' statement in which one module augments the data tree of modules may be further coupled by the 'augment' statement in which
another module. one module augments the data tree of another module.
It is also assumed that the algorithm has access, perhaps on demand, It is also assumed that the algorithm has access, perhaps on demand,
to all YANG modules that the input modules import (perhaps to all YANG modules that the input modules import (directly or
transitively). transitively).
The output of the first mapping step is an annotated RELAX NG schema
for the conceptual tree - a virtual XML document containing, in its
different subtrees, the entire datastore, all RPC requests and
replies, and notifications as defined by the input YANG modules. By
"virtual" we mean that such an XML document need not correspond to
the actual layout of the configuration database in a NETCONF server,
and will certainly never appear on the wire as the content of a
NETCONF PDU. Hence, the RELAX NG schema for the conceptual tree is
not intended for any direct validations but rather as a
representation of a particular data model expressed in annotated
RELAX NG and the common starting point for subsequent transformations
that may produce practical validation schemas. The conceptual tree
is further described in Section 8.1.
Other information contained in input YANG modules, such as semantic Other information contained in input YANG modules, such as semantic
constraints or default values, are recorded in the conceptual tree constraints and default values, are recorded in the hybrid schema as
schema as annotations - XML attributes or elements qualified with annotations - XML attributes or elements qualified with namespace URI
namespace URI "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1". "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1". Metadata
Metadata describing the YANG modules are mapped to annotations describing the YANG modules are mapped to Dublin Core annotations
utilizing Dublin Core elements (Section 5.1). Finally, documentation elements (Section 5.1). Finally, documentation strings are mapped to
strings are mapped to <a:documentation> elements belonging to the DTD <a:documentation> elements belonging to the DTD compatibility
compatibility vocabulary (Section 5.2). vocabulary (Section 5.2).
The output from the second step is a coordinated set of three DSDL The output of the second step is a coordinated set of three DSDL
schemas corresponding to a specific data object and context: schemas corresponding to a specific data object and context:
o RELAX NG schema describing the grammatical and datatype o RELAX NG schema describing the grammatical and datatype
constraints; constraints;
o Schematron schema expressing other constraints such as uniqueness o Schematron schema expressing other constraints such as uniqueness
of list keys or user-specified semantic rules; of list keys or user-specified semantic rules;
o DSRL schema containing the specification of default contents. o DSRL schema containing the specification of default contents.
7. NETCONF Content Validation 7. NETCONF Content Validation
This section describes how the schemas generated by the YANG-to-DSDL This section describes how the schemas generated by the YANG-to-DSDL
mapping are supposed to be applied for validating XML instance mapping are supposed to be applied for validating XML instance
documents such as the content of a datastore or various NETCONF PDUs. documents such as the contents of a datastore or various NETCONF
messages.
The validation proceeds in the following steps, which are also The validation proceeds in the following steps, which are also
illustrated in Figure 2: illustrated in Figure 2:
1. The XML instance document can be immediately checked for 1. The XML instance document is checked for grammatical and data
grammatical and data type validity using the RELAX NG schema. type validity using the RELAX NG schema.
2. Second, default values for leaf nodes have to be applied and 2. Default values for leaf nodes have to be applied and their
their ancestor containers added where necessary. It is important ancestor containers added where necessary. It is important to
to add the implicit nodes before the next validation step because add the implicit nodes before the next validation step because
YANG specification [YANG] states that the data tree against which YANG specification [YANG] requires that the data tree against
XPath expressions are evaluated already has all defaults which XPath expressions are evaluated already has all defaults
filled-in. Note that this step modifies the information set of filled-in. Note that this step modifies the information set of
the validated XML document. the validated XML document.
3. The semantic constraints are checked using the Schematron schema. 3. The semantic constraints are checked using the Schematron schema.
+----------+ +----------+ +----------+ +----------+
| | | XML | | | | XML |
| XML | | document | | XML | | document |
| document |-----------o----------->| with | | document |-----------o----------->| with |
| | ^ | defaults | | | ^ | defaults |
| | | | | | | | | |
+----------+ | +----------+ +----------+ | +----------+
^ | filling-in ^ ^ | filling in ^
| grammar, | defaults | semantic | grammar, | defaults | semantic
| datatypes | | constraints | datatypes | | constraints
| | | | | |
+----------+ +--------+ +------------+ +----------+ +--------+ +------------+
| RELAX NG | | DSRL | | Schematron | | RELAX NG | | DSRL | | Schematron |
| schema | | schema | | schema | | schema | | schema | | schema |
+----------+ +--------+ +------------+ +----------+ +--------+ +------------+
Figure 2: Outline of the validation procedure Figure 2: Outline of the validation procedure
8. Design Considerations 8. Design Considerations
YANG modules could in principle be mapped to DSDL schemas in a number YANG data models could in principle be mapped to the DSDL schemas in
of ways. The mapping procedure described in this document uses a number of ways. The mapping procedure described in this document
several specific design decisions that are discussed in the following uses several specific design decisions that are discussed in the
subsections. following subsections.
8.1. Conceptual Data Tree 8.1. Hybrid Schema
DSDL schemas generated from YANG modules using the procedure As was explained in Section 6, the first step of the mapping produces
described in this document are intended to be used for validating an intermediate document - the hybrid schema, which specifies all
XML-encoded NETCONF data in various forms: every YANG-based model constraints for the entire data model in a single RELAX NG schema.
represents the contents of a datastore but also implies an array of
schemas for all types of NETCONF PDUs. For a reasonably strict
validation of a given data object, the schemas have to be quite
specific. To begin with, effective validation of NETCONF PDU content
requires separation of client and server schemas. While the decision
about proper structuring of all PDU-validating schemas is beyond the
scope of this document, the mapping procedure is designed to
accommodate any foreseeable validation needs.
An essential part of the YANG-to-DSDL mapping procedure is Every input YANG module corresponds to exactly one embedded grammar
nonetheless common to all validation needs: the grammar and datatype in the hybrid schema. This separation of input YANG modules allows
specifications for the datastore, RPCs and notifications expressed by each embedded grammar to include named pattern definitions into its
one or more YANG modules have to be translated to RELAX NG. In order own namespace, which is important for mapping YANG groupings (see
to be able to separate this common step, we introduce the notion of Section 9.2 for additional details).
conceptual data tree: it is a virtual XML tree that contains full
datastore, RPC requests with corresponding replies and notifications.
The schema for the conceptual tree - a single RELAX NG schema with
annotations - therefore has a quite similar logic as the input YANG
module(s), the only major difference being the RELAX NG schema
language.
For example, the conceptual data tree for a YANG module defining In addition to grammatical and datatype constraints, YANG modules
nodes in the namespace "http://example.com/ns/example" may be provide other important information that cannot be expressed in a
schematically represented as follows: RELAX NG schema: semantic constraints, default values, metadata,
documentation and so on. Such information items are represented in
the hybrid schema as XML attributes and elements belonging to the
namespace with the following URI:
"urn:ietf:params:xml:ns:netmod:dsdl-annotations:1". A complete list
of these annotations is given in Section 5.3, detailed rules about
their use are then contained in the following sections.
<nmt:netmod-tree YANG modules define data models not only for configuration and state
xmlns:nmt="urn:ietf:params:xml:ns:netmod:conceptual-tree:1" data but also for (multiple) RPC operations [RFC4741] and/or event
xmlns:ex="http://example.com/ns/example"> notifications [RFC5277]. In order to be able to capture all three
<nmt:top> types of data models in one schema document, the hybrid schema uses
... configuration and status data ... special markers that enclose sub-schemas for configuration and state
</nmt:top> data, individual RPC operations (both input and output part) and
<nmt:rpc-methods> individual notifications.
<nmt:rpc-method>
<nmt:input>
<ex:myrpc ...>
...
</myrpc>
</nmt:input>
<nmt:output>
...
</nmt:output>
</nmt:rpc-method>
...
</nmt:rpc-methods>
<nmt:notifications>
<nmt:notification>
<ex:mynotif>
...
</mynotif>
</nmt:notification>
...
</nmt:notifications>
</nmt:netmod>
The namespace URI "urn:ietf:params:xml:ns:netmod:conceptual-tree:1" The markers are the following XML elements in the namespace of
identifies a simple vocabulary consisting of a few elements that NETMOD-specific annotations (URI
encapsulate and separate the various parts of the conceptual data urn:ietf:params:xml:ns:netmod:dsdl-annotations:1):
tree.
The conceptual tree schema is not intended for direct validation but +-------------------+---------------------------------------+
rather serves as a well-defined starting point for subsequent | Element name | Role |
transformations that generate validation schemas. In general, these +-------------------+---------------------------------------+
transformations should be relatively simple - they will typically | nma:data | encloses configuration and state data |
extract one or more subtrees from the conceptual tree schema, modify | | |
them as necessary and add encapsulating elements such as those from | nma:rpcs | encloses all RPC operations |
the NETCONF RPC layer. | | |
| nma:rpc | encloses an individual RPC operation |
| | |
| nma:input | encloses an RPC request |
| | |
| nma:output | encloses an RPC reply |
| | |
| nma:notifications | encloses all notifications |
| | |
| nma:notification | encloses an individual notification |
+-------------------+---------------------------------------+
Additional information contained in the source YANG module(s), such Table 3: Marker elements in the hybrid schema
as semantic constraints and default values, is represented in the
form of interim NETMOD-specific annotations that are included as
foreign-namespace elements or attributes in the RELAX NG schema for
the conceptual tree. In the second phase of the mapping, these
annotations are typically translated to equivalent Schematron and
DSRL rules.
As a useful side effect, by introducing the conceptual data tree we For example, consider a data model formed by two YANG modules
are also able to resolve the difficulties arising from the fact that "example-a" and "example-b" that define nodes in the namespaces
a single datastore may consist of multiple parallel data hierarchies "http://example.com/ns/example-a" and
defined in one or more YANG modules, which cannot be mapped to a "http://example.com/ns/example-b". Module "example-a" defines
valid XML document. In the conceptual data tree, such multiple configuration/state data, RPC methods and notifications, whereas
hierarchies appear under the single <nmt:top> element. "example-b" defines only configuration/state data. The hybrid schema
can then be schematically represented as follows:
<grammar xmlns="http://relaxng.org/ns/structure/1.0"
xmlns:nma="urn:ietf:params:xml:ns:netmod:dsdl-annotations:1"
xmlns:exa="http://example.com/ns/example-a"
xmlns:exb="http://example.com/ns/example-b"
datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
<start>
<grammar nma:module="example-a"
ns="http://example.com/ns/example-a">
<start>
<nma:data>
...configuration and state data defined in "example-a"...
</nma:data>
<nma:rpcs>
<nma:rpc>
<nma:input>
<element name="exa:myrpc">
...
</element>
</nma:input>
<nma:output>
...
</nma:output>
</nma:rpc>
...
</nma:rpcs>
<nma:notifications>
<nma:notification>
<element name="exa:mynotif">
...
</element>
</nma:notification>
...
</nma:notifications>
</start>
</grammar>
<grammar nma:module="example-b"
ns="http://example.com/ns/example-a">
<start>
<nma:data>
...configuration and state data defined in "example-b"...
</nma:data>
<nma:rpcs/>
<nma:notifications/>
</start>
</grammar>
</start>
</grammar>
A complete hybrid schema for the data model of a DHCP server is given
in Appendix C.2.
8.2. Modularity 8.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 of a full schema into separate modules and splitting the contents of a full schema into separate modules and
combining or reusing them in various ways. However, the approaches combining or reusing them in various ways. However, the approaches
taken by YANG and RELAX NG differ. Modularity in RELAX NG is taken by YANG and RELAX NG differ. Modularity in RELAX NG is
suitable for ad hoc combinations of a small number of schemas whereas suitable for ad hoc combinations of a small number of schemas whereas
YANG assumes a large set of modules similar to SNMP MIBs. The YANG assumes a large set of modules similar to SNMP MIBs. The
following differences are important: following differences are important:
skipping to change at page 23, line 40 skipping to change at page 25, line 34
o The names of imported YANG groupings and typedefs are qualified o The names of imported YANG groupings and typedefs are qualified
with the namespace of the imported module. On the other hand, the with the namespace of the imported module. On the other hand, the
names of data nodes contained inside the imported groupings, when names of data nodes contained inside the imported groupings, when
used within the importing module, become part of the importing used within the importing module, become part of the importing
module's namespace. In RELAX NG, the names of patterns are module's namespace. In RELAX NG, the names of patterns are
unqualified and so named patterns defined in both the importing unqualified and so named patterns defined in both the importing
and imported module share the same flat namespace. The contents and imported module share the same flat namespace. The contents
of RELAX NG named patterns may either keep the namespace of the of RELAX NG named patterns may either keep the namespace of the
schema where they are defined or inherit the namespace of the schema where they are defined or inherit the namespace of the
importing module, analogically to YANG. However, in order to importing module, analogically to YANG. However, in order to
achieve the latter behavior, the imported module must be prepared achieve the latter behavior, the definitions of named patterns
in a special way as a library module that cannot be used as a must be included from an external schema which has to be prepared
stand-alone schema. in a special way (see [Vli04], Chapter 11).
So the conclusion is that the modularity mechanisms of YANG and RELAX In order to map, as much as possible, the modularity of YANG to RELAX
NG, albeit similar, are not directly compatible. Therefore, the NG, a validating RELAX NG schema (the result of the second mapping
corresponding design decision for the mapping algorithm is to collect step) has to be split into two files, one of them containing all
all information in a single schema for the conceptual tree, even if global definitions that are mapped from top-level YANG groupings
it comes from multiple YANG modules or submodules. In other words, appearing in all input YANG module. This RELAX NG schema MUST NOT
translations of imported groupings and typedefs are installed in the define any namespace via the @ns attribute.
translation of importing module - but only if they are really used
there.
NOTE: The 'include' statement that is used in YANG for including The other RELAX NG schema file then defines actual data trees mapped
submodules has in fact the same semantics as the <rng:include> from input YANG modules, each of them enclosed in an own embedded
pattern. However, since we don't map the modular structure for YANG grammar. Those embedded grammars in which at least one of the global
modules, it seems to have little sense to do it for submodules. definitions is used MUST include the first schema with definitions
Consequently, the contents of submodules appear directly in the and also MUST define the local namespace using the @ns attribute.
conceptual tree schema, too. This way, the global definitions can be used inside different
embedded grammar, each time accepting a different local namespace.
Named pattern definition that are mapped from non-top-level YANG
groupings MUST be placed inside the embedded grammar corresponding to
the YANG module where the grouping is defined.
In the hybrid schema, we need to distinguish the global and non-
global named pattern definitions while still keeping the hybrid
schema in one file. This is accomplished in the following way:
o Every global definition MUST be placed as a child of the the outer
<rng:grammar> element (the document root of the hybrid schema).
o Every non-global definitions MUST be placed as a child of the
corresponding embedded <rng:grammar> element.
YANG also allows for splitting a module into a number of submodules.
However, as submodules have no impact on the scope of identifiers and
namespaces, the modularity based on submodules is not mapped in any
way. The contents of submodules is therefore handled as if the
submodule text appeared directly in the main module.
8.3. Granularity 8.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 corresponds to a named pattern schema language - every XML element corresponds to a named pattern
definition. In practice, some compromise between the two extremes is definition. 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
modules are organized in a way that's closer to the "Russian Doll" modules are organized in a way closer to the "Russian Doll" style,
style, which provides a better insight into the structure of the which provides a better insight into the structure of the
configuration data. Groupings are usually defined only for contents configuration data. Groupings are usually defined only for contents
that are prepared for reuse in multiple places via the 'uses' that are prepared for reuse in multiple places via the 'uses'
statement. In contrast, RELAX NG schemas tend to be much flatter, statement. In contrast, RELAX NG schemas tend to be much flatter,
because finer granularity is also needed in RELAX NG for because finer granularity is also needed in RELAX NG for
extensibility of the schemas - it is only possible to replace or extensibility of the schemas - it is only possible to replace or
modify schema fragments that are factored out as named patterns. For modify schema fragments that are factored out as named patterns. For
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's powerful extension
of RELAX NG. For this reason, the mapping essentially keeps the mechanisms to those available in RELAX NG. For this reason, the
granularity of the original YANG data model: definitions of named mapping essentially keeps the granularity of the original YANG data
patterns in the resulting RELAX NG schema usually have direct model: YANG groupings and definitions of derived types usually have
counterparts in YANG groupings and definitions of derived types. direct counterparts in definitions of named patterns in the resulting
RELAX NG schema.
8.4. Handling of XML Namespaces 8.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 YANG-to-DSDL mapping allows for multiple input YANG purpose since the YANG-to-DSDL mapping allows for multiple input YANG
modules that naturally leads to compound document schemas. modules, which 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:
1. First possibility is the traditional XML way via the @xmlns:xxx 1. First possibility is the traditional XML way via the @xmlns:xxx
attribute. attribute.
2. One of the target namespace URIs may be declared using the @ns 2. One of the target namespace URIs may be declared using the @ns
attribute. attribute.
In both cases, these attributes are typically attached to the <rng: In both the hybrid schema and validation RELAX NG schemas generated
grammar> element but may also appear elsewhere. in the second step, the namespaces MUST be declared as follows:
The design decision for the mapping is to use exclusively the
alternative 1, since in this case all YANG modules are represented
symmetrically, which makes further processing of the conceptual tree
schema considerably easier. Moreover, this way the namespace
prefixes declared in the input modules are recorded in the resulting
schema - the prefix for the namespace declared using @ns would be
lost.
DSRL schemas can declare any number of target namespaces via the 1. The root <rng:grammar> MUST have @xmlns:xxx attributes declaring
standard XML attributes xmlns:xxx. prefixes of all namespaces that are used in the data model. The
prefixes SHOULD be identical to those defined in the 'prefix'
statements. An implementation of the mapping MUST resolve all
collisions in the prefixes defined by different input modules, if
there are any.
In contrast, Schematron requires all target namespaces to be defined 2. Each embedded <rng:grammar> element must declare the namespace of
in the <sch:ns> subelements of the root <sch:schema> element. the corresponding module using the @ns attribute. This way, the
names of nodes defined by global named patterns are able to adopt
the local namespace of each embedded grammar, as explained in
Section 8.2.
8.5. Features and Deviations This setup is illustrated by the example at the end of Section 8.1.
YANG provides statements that allow for marking parts of the schema DSRL schemas may declare any number of target namespaces via the
as conditional ('feature' and 'if-feature' statements) or declaring standard XML attributes xmlns:xxx.
deviations from a data model ('deviation' statement). These
statements are not handled by the YANG-to-DSDL mapping. Instead, it
is assumed that all features and deviations are specified beforehand
and the corresponding changes in the input YANG modules are already
applied.
9. Mapping YANG Data Models to the Conceptual Tree Schema In contrast, Schematron requires all used namespaces to be defined in
the <sch:ns> subelements of the document element <sch:schema>.
This section explains the main principles underlying the first step 9. Mapping YANG Data Models to the Hybrid Schema
of the mapping. Its result is an annotated RELAX NG schema of the
conceptual tree, which is described in Section 8.1.
As a special case, if the input YANG modules contain no data nodes This section explains the main principles governing the first step of
(this is typical, e.g., for datatype library modules), an the mapping. Its result is the hybrid schema which is described in
implementation MAY entirely remove the schema of the (empty) Section 8.1.
conceptual tree - the <rng:start> element with all its contents. The
output RELAX NG schema will then contain only named pattern
definitions translated from YANG groupings and typedefs.
Detailed specification of the mapping of individual YANG statements A detailed specification of the mapping of individual YANG statements
is contained in Section 11. is contained in the following Section 10.
9.1. Occurrence Rules for Data Nodes 9.1. Occurrence Rules for Data Nodes
In DSDL schema languages, occurrence constraints for a node are In DSDL schema languages, occurrence constraints for a node are
always localized together with that node. In a RELAX NG schema, for always localized together with that node. In a RELAX NG schema, for
example, <rng:optional> pattern appears as the parent element of the example, <rng:optional> pattern appears as the parent element of the
pattern defining a leaf or non-leaf element. Similarly, DSRL pattern defining a leaf or non-leaf element. Similarly, DSRL
specifies default content separately for every single node, be it a specifies default contents separately for every single node, be it a
leaf or non-leaf element. leaf or non-leaf element.
For leaf nodes in YANG modules, the occurrence constraints are also For leaf nodes in YANG modules, the occurrence constraints are also
easily inferred from the substatements of 'leaf'. In contrast, for a easily inferred from the substatements of 'leaf'. On the other hand,
YANG container it is often necessary to examine its entire subtree in for a YANG container it is often necessary to examine its entire
order to determine the container's occurrence constraints. subtree in order to determine the container's occurrence constraints.
Therefore, one of the goals of the first mapping step is to infer the Therefore, one of the goals of the first mapping step is to infer the
occurrence constraints for all containers and mark accordingly the occurrence constraints for all data nodes and mark accordingly the
corresponding <rng:element> patterns in the conceptual tree schema so corresponding <rng:element> patterns in the hybrid schema so that any
that any transformation procedure in the second mapping step can transformation procedure in the second mapping step can simply use
simply use this information and need not examine the subtree again. this information and need not examine the subtree again.
First, it has to be decided whether a given container element must First, it has to be decided whether a given data node must always be
always be present in a valid configuration. If so, such a container present in a valid configuration. If so, such a node is called
element is called mandatory, otherwise it is called optional. This mandatory, otherwise it is called optional. This constraint is
constraint is closely related to the notion of mandatory nodes in closely related to the notion of mandatory nodes in Section 3.1 in
Section 3.1 in [YANG]. The only difference is that we also consider [YANG]. The only difference is that this document also considers
list keys to be mandatory. list keys to be mandatory.
The other occurrence constraint has to do with the semantics of the The other occurrence constraint has to do with the semantics of the
'default' statement and the possibility of removing empty non- 'default' statement and the possibility of removing empty non-
presence containers. As a result, the information set of a valid presence containers. As a result, the information set of a valid
configuration may be modified by adding or removing certain leaf or configuration may be modified by adding or removing certain leaf or
container elements without changing the meaning of the configuration. container elements without changing the meaning of the configuration.
In this document, such elements are called implicit. In the hybrid
In this document, such elements are called implicit. schema, they can be identified as RELAX NG patterns having either
@nma:default or @nma:implicit attribute.
Note that both occurrence constraints apply to containers at the top Note that both occurrence constraints apply to containers at the top
level of the data tree, and then also to other containers under the level of the data tree, and then also to other containers under the
additional condition that their parent node exists in the instance additional condition that their parent node exists in the instance
document. For example, consider the following YANG fragment: document. For example, consider the following YANG fragment:
container outer { container outer {
presence 'Presence of "outer" means something.'; presence 'Presence of "outer" means something.';
container c1 { container c1 {
leaf foo { leaf foo {
skipping to change at page 27, line 46 skipping to change at page 29, line 40
configuration, its child containers are not present as well. configuration, its child containers are not present as well.
However, if "outer" does exist, it makes sense to ask which of its However, if "outer" does exist, it makes sense to ask which of its
child containers are optional and which are implicit. In this case, child containers are optional and which are implicit. In this case,
"c1" is optional and implicit, "c2" is optional but not implicit and "c1" is optional and implicit, "c2" is optional but not implicit and
"c3" is mandatory (and therefore not implicit). "c3" is mandatory (and therefore not implicit).
The following subsections give precise rules for determining whether The following subsections give precise rules for determining whether
a container is optional or mandatory and whether it is implicit. In a container is optional or mandatory and whether it is implicit. In
order to simplify the recursive definition of these occurrence order to simplify the recursive definition of these occurrence
characteristics, it is useful to define them also for other types of characteristics, it is useful to define them also for other types of
data nodes, i.e., leaf, list, leaf-list and anyxml. YANG schema nodes, i.e., leaf, list, leaf-list and anyxml and choice.
9.1.1. Optional and Mandatory Nodes 9.1.1. Optional and Mandatory Nodes
The decision whether a given node is mandatory or optional is The decision whether a given node is mandatory or optional is
governed by the following rules: governed by the following rules:
o Leaf, anyxml and choice nodes are mandatory if they contain the o Leaf, anyxml and choice nodes are mandatory if they contain the
substatement "mandatory true;". For a choice node this means that substatement "mandatory true;". For a choice node this means that
at least one node from exactly one case branch must exist. at least one node from exactly one case branch must exist.
o In addition, leaf nodes are mandatory if they are declared as list o In addition, a leaf node is mandatory if it is declared as a list
keys. key.
o List or leaf-list nodes are mandatory if they contain 'min- o A list or leaf-list node is mandatory if it contains the 'min-
elements' substatement with argument value greater than zero. elements' substatement with an argument value greater than zero.
o A container node is mandatory if its definition does not contain o A container node is mandatory if its definition does not contain
the 'presence' substatement and at least one of its child nodes is the 'presence' substatement and at least one of its child nodes is
mandatory. mandatory.
A node is optional if and only if it is not mandatory. A node is optional if and only if it is not mandatory.
In RELAX NG, definitions of nodes that are optional must be In RELAX NG, definitions of nodes that are optional must be
explicitly wrapped in the <rng:optional> element. The mapping MUST explicitly wrapped in the <rng:optional> element. The mapping MUST
use the above rules to determine whether a YANG node is optional and use the above rules to determine whether a YANG node is optional and
if so, insert the <rng:optional> element in the conceptual tree if so, insert the <rng:optional> element in the hybrid schema.
schema.
However, alternatives in <rng:choice> are never defined as optional However, alternatives in <rng:choice> MUST NOT be defined as optional
in the conceptual tree schema. Therefore, 'anyxml', 'container', in the hybrid schema. If a choice in YANG is not mandatory, <rng:
'leaf', 'list' and 'leaf-list' statements appearing as children of optional> MUST be used to wrap the entire <rng:choice> pattern.
'choice' (so-called shorthand cases) are always mapped to mandatory
RELAX NG patterns. If a choice in YANG is not mandatory, <rng:
optional> is used to wrap the entire <rng:choice> pattern.
9.1.2. Implicit Nodes 9.1.2. Implicit Nodes
The following rules are used to determine whether a given node is The following rules are used to determine whether a given node is
implicit: implicit:
o List, leaf-list and anyxml nodes are never implicit. o List, leaf-list and anyxml nodes are never implicit.
o A leaf node is implicit if and only if it has a specified default o A leaf node is implicit if and only if it has a default value,
value (either directly or via its datatype). defined either directly or via its datatype.
o A container node is implicit if and only if it does not have the o A container node is implicit if and only if it does not have the
'presence' substatement, none of its children is mandatory and at 'presence' substatement, none of its children are mandatory and at
least one child is implicit. least one child is implicit.
In the conceptual tree schema, all implicit containers, as well as In the hybrid schema, all implicit containers, as well as leafs that
leafs that obtain their default value from a typedef and don't have obtain their default value from a typedef and don't have the @nma:
the @nma:default attribute, MUST be marked with @nma:implicit default attribute, MUST be marked with @nma:implicit attribute having
attribute having the value "true". the value of "true".
Note that Section 7.9.3 in [YANG] specifies other rules that must be Note that Section 7.9.3 in [YANG] specifies other rules that must be
taken into account when deciding whether a given container or leaf taken into account when deciding whether a given container or leaf
appearing inside a case of a choice is ultimately implicit or not. appearing inside a case of a choice is ultimately implicit or not.
Specifically, a leaf or container under a case can be implicit only Specifically, a leaf or container under a case can be implicit only
if the case appears in the argument of the choice's 'default' if the case appears in the argument of the choice's 'default'
statement. However, this is not sufficient by itself but also statement. However, this is not sufficient by itself but also
depends on the particular instance XML document, namely on the depends on the particular instance XML document, namely on the
presence or absence of nodes from other (non-default) cases. The presence or absence of nodes from other (non-default) cases. The
details are explained in Section 10.4. details are explained in Section 11.3.
9.2. Mapping YANG Groupings and Typedefs 9.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 Section the module hierarchy and are subject to lexical scoping, see Section
5.5 in [YANG]. Second, top-level symbols from external modules are 5.5 in [YANG]. Second, top-level symbols from external modules may
imported as qualified names represented using the external module be 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:
o Names of groupings and typedefs appearing at the top level of the o Names of groupings and typedefs appearing at the top level of the
YANG module hierarchy are prefixed with the module name and two YANG module hierarchy are prefixed with the module name and two
underscore characters ("__"). underscore characters ("__").
o Names of other groupings and typedefs, i.e., those that do not o Names of other groupings and typedefs, i.e., those that do not
appear at the top level of a YANG module, are prefixed with the appear at the top level of a YANG module, are prefixed with the
module name, double underscore, and then the names of all ancestor module name, double underscore, and then the names of all ancestor
data nodes separated by double underscore. data nodes separated by double underscore.
o Since the names of groupings and typedefs in YANG have different o Finally, since the names of groupings and typedefs in YANG have
namespaces, an additional underline character is added to the different namespaces, an additional underscore character is added
beginning of the mangled names of all groupings. to the beginning of the mangled names of all groupings.
An additional complication is caused by the YANG rules for subelement
ordering (see, e.g., Section 7.5.7 in [YANG]): In RPC input and
output parameters, subelements must follow the order specified in the
data model, otherwise the order is arbitrary. Consequently, if a
grouping is used both in RPC input/output parameters and elsewhere,
it MUST be mapped to two different named pattern definitions - one
with fixed order and the other with arbitrary order. To distinguish
them, the "__rpc" suffix MUST be appended to the version with fixed
order.
EXAMPLE. Consider the following YANG module which imports the EXAMPLE. Consider the following YANG module which imports the
standard module "ietf-inet-types" [Ytypes]: standard module "ietf-inet-types" [Ytypes]:
module example1 { module example1 {
namespace "http://example.com/ns/example1"; namespace "http://example.com/ns/example1";
prefix ex1; prefix ex1;
import "ietf-inet-types" {
prefix "inet";
}
typedef vowels { typedef vowels {
type string { type string {
pattern "[aeiouy]*"; pattern "[aeiouy]*";
} }
} }
grouping "grp1" { grouping "grp1" {
leaf "void" { leaf "void" {
type "empty"; type "empty";
} }
} }
container "cont" { container "cont" {
grouping "grp2" {
leaf "address" {
type "inet:ip-address";
}
}
leaf foo { leaf foo {
type vowels; type vowels;
} }
uses "grp1"; uses "grp1";
uses "grp2";
} }
} }
The resulting RELAX NG schema will then contain the following named The hybrid schema generated by the first mapping step will then
pattern definitions (long regular expression patterns for IPv4 and contain the following two (global) named pattern definitions:
IPv6 addresses are not shown):
<rng:define name="example1__vowels"> <rng:define name="example1__vowels">
<rng:data type="string"> <rng:data type="string">
<rng:param name="pattern">[aeiouy]*</param> <rng:param name="pattern">[aeiouy]*</rng:param>
</rng:data> </rng:data>
</rng:define> </rng:define>
<rng:define name="_example1__grp1"> <rng:define name="_example1__grp1">
<rng:optional> <rng:optional>
<rng:element name="ex1:void"> <rng:element name="void">
<rng:empty/> <rng:empty/>
</rng:element> </rng:element>
</rng:optional> </rng:optional>
</rng:define> </rng:define>
<rng:define name="_example1__cont__grp2">
<rng:optional>
<rng:element name="ex1:address">
<rng:ref name="ietf-inet-types__ip-address"/>
</rng:element>
</rng:optional>
</rng:define>
<rng:define name="ietf-inet-types__ip-address">
<rng:choice>
<rng:ref name="ietf-inet-types__ipv4-address"/>
<rng:ref name="ietf-inet-types__ipv6-address"/>
</rng:choice>
</rng:define>
<rng:define name="ietf-inet-types__ipv4-address">
<rng:data type="string">
<rng:param name="pattern">... regex pattern ...</param>
</rng:data>
</rng:define>
<rng:define name="ietf-inet-types__ipv6-address">
<rng:data type="string">
<rng:param name="pattern">... regex pattern ...</param>
</rng:data>
</rng:define>
Note that type definitions from the "ietf-inet-types" module are
mapped directly to the conceptual tree schema.
9.2.1. YANG Refinements and Augments 9.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 expansions themselves are modified whereas YANG provides two substatements of
of groupings. Specifically, YANG provides two statements for this 'uses' which modify expansions of groupings:
purpose that may appear as substatements of 'uses':
o 'refine' statement allows for changing parameters of a schema node o 'refine' statement allows for changing parameters of a schema node
inside the grouping referenced by the parent 'uses' statement; inside the grouping referenced by the parent 'uses' statement;
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 contents.
Both 'refine' and 'augment' statements are quite powerful in that Both 'refine' and 'augment' statements are quite powerful in that
they can address, using XPath-like expressions as their arguments, they can address, using XPath-like expressions as their arguments,
schema nodes that are arbitrarily deep inside the grouping content. schema nodes that are arbitrarily deep inside the grouping contents.
In contrast, modifications of named pattern definitions in RELAX NG In contrast, modifications of named pattern definitions in RELAX NG
are applied exclusively at the topmost level of the named pattern are applied exclusively at the topmost level of the named pattern
content. In order to achieve a modifiability of named patterns contents. In order to achieve a modifiability of named patterns
comparable to YANG, the RELAX NG schema would have to be extremely comparable to YANG, a RELAX NG schema would have to be extremely flat
flat (cf. Section 8.3) and very difficult to read. (cf. Section 8.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 replaced by the content of the and/or 'augment' substatements is replaced by the contents of the
corresponding grouping, the changes specified in the 'refine' and corresponding grouping, the changes specified in the 'refine' and
'augment' statements are applied and the resulting YANG schema '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.
If there are further 'uses' statements inside the grouping content, If there are further 'uses' statements inside the grouping contents,
they may require expansion, too: it is necessary if the contained they may require expansion, too: it is necessary if the contained
'uses'/'grouping' pair lies on the "modification path" specified in 'uses'/'grouping' pair lies on the "modification path" specified in
the argument of a 'refine' or 'augment' statement. the argument of a 'refine' or 'augment' statement.
EXAMPLE. Consider the following YANG module: EXAMPLE. Consider the following YANG module:
module example2 { module example2 {
namespace "http://example.com/ns/example2"; namespace "http://example.com/ns/example2";
prefix ex2; prefix ex2;
grouping leaves { grouping leaves {
skipping to change at page 33, line 24 skipping to change at page 34, line 4
type string; type string;
} }
} }
grouping es { grouping es {
leaf hoja { leaf hoja {
type string; type string;
} }
} }
uses leaves; uses leaves;
} }
The resulting hybrid schema contains three global named pattern
The resulting conceptual tree schema contains three named pattern
definitions corresponding to the three groupings, namely definitions corresponding to the three groupings, namely
<rng:define name="_example2__leaves"> <rng:define name="_example2__leaves">
<rng:ref name="_example2__fr"/> <rng:interleave>
<rng:ref name="_example2__es"/> <rng:ref name="_example2__fr"/>
<rng:ref name="_example2__es"/>
</rng:interleave>
</rng:define> </rng:define>
<rng:define name="_example2__fr"> <rng:define name="_example2__fr">
<rng:optional> <rng:optional>
<rng:element name="ex2:feuille"> <rng:element name="feuille">
<rng:data type="string"/> <rng:data type="string"/>
</rng:element> </rng:element>
</rng:optional> </rng:optional>
</rng:define> </rng:define>
<rng:define name="_example2__es"> <rng:define name="_example2__es">
<rng:optional> <rng:optional>
<rng:element name="ex2:hoja"> <rng:element name="hoja">
<rng:data type="string"/> <rng:data type="string"/>
</rng:element> </rng:element>
</rng:optional> </rng:optional>
</rng:define> </rng:define>
and the configuration data part of the conceptual tree schema is a and the configuration data part of the hybrid schema is a single
single named pattern reference: named pattern reference:
<nma:data>
<rng:ref name="_example2__leaves"/>
</nma:data>
<rng:ref name="_example2__leaves"/>
Now assume that the "uses leaves" statement contains a 'refine' Now assume that the "uses leaves" statement contains a 'refine'
substatement, for example: substatement, for example:
uses leaves { uses leaves {
refine "hoja" { refine "hoja" {
default "alamo"; default "alamo";
} }
} }
The resulting conceptual tree schema now contains just one named The resulting hybrid schema now contains just one named pattern
pattern definition - "_example2__fr". The other two groupings definition - "_example2__fr". The other two groupings "leaves" and
"leaves" and "es" have to be expanded because they both lie on the "es" have to be expanded because they both lie on the "modification
"modification path", i.e., contain the leaf "hoja" that is being path", i.e., contain the leaf "hoja" that is being refined. The
refined. The configuration data part of the conceptual tree schema configuration data part of the hybrid schema now looks like this:
now looks like this:
<rng:ref name="_example2__fr"/> <nma:data>
<rng:optional> <rng:interleave>
<rng:element name="ex2:hoja" nma:default="alamo"> <rng:ref name="_example2__fr"/>
<rng:data type="string"/> <rng:optional>
</rng:element> <rng:element name="ex2:hoja" nma:default="alamo">
</rng:optional> <rng:data type="string"/>
</rng:element>
</rng:optional>
</rng:interleave>
</nma:data>
9.2.2. Type Derivation Chains 9.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
that allows to modify a built-in type (perhaps in multiple steps) by that allows to restrict a built-in type (perhaps in multiple steps)
adding new restrictions. When a derived YANG type is used without by adding new constraints. Whenever a derived YANG type is used
restrictions - as a substatement of either 'leaf' or another without restrictions - as a substatement of either 'leaf' or another
'typedef' - the 'type' statement is mapped simply to the <rng:ref> 'typedef' - then the 'type' statement is mapped simply to a named
element, i.e., a named pattern reference, and the type definition is pattern reference <rng:ref>, and the type definition is mapped to a
mapped to a RELAX NG named pattern definition. However, if RELAX NG named pattern definition <rng:define>. However, if any
restrictions are specified as substatements of the 'type' statement, restrictions are specified as substatements of the 'type' statement,
the type definition MUST be expanded at that point so that only the the type definition MUST be expanded at that point so that only the
ancestor built-in type appears in the output schema, restricted with ancestor built-in type appears in the hybrid schema, restricted with
facets that correspond to the combination of all restrictions found facets that correspond to the combination of all restrictions found
along the type derivation chain and also in the 'type' statement. along the type derivation chain and also in the 'type' statement.
EXAMPLE. Consider this YANG module: EXAMPLE. Consider this YANG module:
module example3 { module example3 {
namespace "http://example.com/ns/example3"; namespace "http://example.com/ns/example3";
prefix ex3; prefix ex3;
typedef dozen { typedef dozen {
type uint8 { type uint8 {
range 1..12; range 1..12;
} }
} }
leaf month { leaf month {
type dozen; type dozen;
} }
}
The 'type' statement in "leaf month" is mapped simply to the The 'type' statement in "leaf month" has no restrictions and is
reference <rng:ref name="example3__dozen"/> and the corresponding therefore mapped simply to the reference <rng:ref
named pattern is defined as follows: name="example3__dozen"/> and the corresponding named pattern is
defined as follows:
<rng:define name="example3__dozen"> <rng:define name="example3__dozen">
<rng:data type="unsignedByte"> <rng:data type="unsignedByte">
<rng:param name="minInclusive">1</param> <rng:param name="minInclusive">1</rng:param>
<rng:param name="maxInclusive">12</param> <rng:param name="maxInclusive">12</rng:param>
</rng:data> </rng:data>
</rng:define> </rng:define>
Assume now that the definition of leaf "month" is changed to Assume now that the definition of leaf "month" is changed to
leaf month { leaf month {
type dozen { type dozen {
range 7..max; range 7..max;
} }
} }
The output RELAX NG schema then won't contain any named pattern The output RELAX NG schema then will not contain any named pattern
definition and leaf "month" will be mapped directly to definition and the leaf "month" will be mapped directly to
<rng:element name="ex3:month"> <rng:element name="ex3:month">
<rng:data type="unsignedByte"> <rng:data type="unsignedByte">
<rng:param name="minInclusive">7</param> <rng:param name="minInclusive">7</rng:param>
<rng:param name="maxInclusive">12</param> <rng:param name="maxInclusive">12</rng:param>
</rng:data> </rng:data>
</rng:element> </rng:element>
The mapping of type derivation chains may be further complicated by The mapping of type derivation chains may be further complicated by
the presence of the 'default' statement in type definitions. In the the presence of the 'default' statement in type definitions. In the
simple case, when a type definition containing the 'default' simple case, when a type definition containing the 'default'
statement is used without restrictions, the 'default' statement is statement is used without restrictions, the 'default' statement is
mapped to the @nma:default attribute attached to the <rng:define> mapped to the @nma:default attribute attached to the <rng:define>
element. element.
However, if that type definition has to be expanded, the @nma:default However, if that type definition has to be expanded due to
annotation arising from the expanded type or ancestor types in the restrictions, the @nma:default annotation arising from the expanded
type derivation chain MUST be attached to the element where the type or ancestor types in the type derivation chain MUST be attached
expansion occurs. If there are multiple 'default' statements in to the pattern where the expansion occurs. If there are multiple
consecutive steps of the type derivation, only the 'default' 'default' statements in consecutive steps of the type derivation,
statement that is closest to the expanded type is used. only the 'default' statement that is closest to the expanded type is
used.
EXAMPLE. Consider this variation of the last example: EXAMPLE. Consider this variation of the last example:
module example3bis { module example3bis {
namespace "http://example.com/ns/example3bis"; namespace "http://example.com/ns/example3bis";
prefix ex3bis; prefix ex3bis;
typedef dozen { typedef dozen {
type uint8 { type uint8 {
range 1..12; range 1..12;
} }
default 7; default 7;
} }
leaf month { leaf month {
type dozen; type dozen;
} }
}
The 'typedef' statement in this module is mapped to the following The 'typedef' statement in this module is mapped to the following
named pattern definition: named pattern definition:
<rng:define name="example3bis__dozen" @nma:default="7"> <rng:define name="example3bis__dozen" @nma:default="7">
<rng:data type="unsignedByte"> <rng:data type="unsignedByte">
<rng:param name="minInclusive">1</param> <rng:param name="minInclusive">1</rng:param>
<rng:param name="maxInclusive">12</param> <rng:param name="maxInclusive">12</rng:param>
</rng:data> </rng:data>
</rng:define> </rng:define>
If the "dozen" type is restricted when used in the leaf "month" If the "dozen" type is restricted when used in the leaf "month"
definition as in the previous example, the "dozen" type has to be definition as in the previous example, the "dozen" type has to be
expanded and @nma:default becomes an attribute of the <ex3bis:month> expanded and @nma:default becomes an attribute of the <ex3bis:month>
element definition: element definition:
<rng:element name="ex3bis:month" @nma:default="7"> <rng:element name="ex3bis:month" @nma:default="7">
<rng:data type="unsignedByte"> <rng:data type="unsignedByte">
<rng:param name="minInclusive">7</param> <rng:param name="minInclusive">7</rng:param>
<rng:param name="maxInclusive">12</param> <rng:param name="maxInclusive">12</rng:param>
</rng:data> </rng:data>
</rng:element> </rng:element>
However, if the definition of leaf "month" itself contained the However, if the definition of the leaf "month" itself contained the
'default' substatement, the default specified for the "dozen" type 'default' substatement, the default specified for the "dozen" type
will be ignored. would be ignored.
9.3. Translation of XPath Expressions 9.3. Translation of XPath Expressions
YANG uses full XPath 1.0 syntax [XPath] for the arguments of 'must', YANG uses full XPath 1.0 syntax [XPath] for the arguments of 'must',
'when' and 'path' statements. As the names of data nodes defined in 'when' and 'path' statements. As the names of data nodes defined in
a YANG module always belong to the namespace of that YANG module, a YANG module always belong to the namespace of that YANG module,
YANG adopted a simplification similar to the concept of default YANG 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 in XPath expressions needn't carry
inside the module where they are defined and the local module's a namespace prefix inside the module where they are defined and the
namespace is assumed. local module's namespace is assumed.
If an XPath expression is carried over to a NETMOD-specific Consequently, all XPath expressions MUST be translated into a fully
annotation in the conceptual tree schema, it MUST be translated into conformant XPath 1.0 expression: Every unprefixed node name MUST be
a fully conformant XPath 1.0 expression that also reflects the prepended with the local module's namespace prefix as declared by the
hierarchy of the conceptual data tree: 'prefix' statement.
1. Each unprefixed node name MUST be prepended with the local XPath expressions appearing inside top-level groupings require
module's namespace prefix declared by the 'prefix' statement. special attention because all unprefixed node names contained in them
must adopt the namespace of each module where the grouping is used
(cf. Section 8.2. In order to achieve this, the local prefix MUST be
represented using the variable "$pref" in the hybrid schema. A
Schematron schema which encounters such an XPath expression then
supplies an appropriate value for this variable via a parameter to an
abstract pattern to which the YANG grouping is mapped (see
Section 11.2).
2. Absolute XPath expressions, i.e., those starting with a slash, For example, XPath expression "/dhcp/max-lease-time" appearing in a
MUST be prepended with appropriate path in the conceptual tree, YANG module with the "dhcp" prefix will be translated to
according to the YANG specification of context for XPath
expressions, see [YANG], Sections 7.5.3 and 7.19.5.
Translation rule 2 means for example that absolute XPath expressions o "$pref:dhcp/$pref:max-lease-time", if the expression is inside a
appearing in the main configuration data tree always start with "nmt: top-level grouping;
netmod-tree/nmt:top/", those appearing in a notification always start
with "nmt:netmod-tree/nmt:notifications/nmt:notification/", etc.
EXAMPLE. YANG XPath expression "/dhcp/max-lease-time" appearing in o "dhcp:dhcp/dhcp:max-lease-time", otherwise.
the main configuration data will be translated to "nmt:netmod-tree/
nmt:top/dhcp:dhcp/dhcp:max-lease-time".
The key identifiers and "descendant schema node identifiers" (see the YANG also uses other XPath-like expressions, namely key identifiers
ABNF production for and "descendant-schema-nodeid" in Section 12 of and "descendant schema node identifiers" (see the ABNF production for
[YANG]) are not XPath expressions but SHOULD be translated by adding and "descendant-schema-nodeid" in Section 12 of [YANG]). These
local module prefixes as well. expressions MUST be translated by adding local module prefixes as
well.
9.4. YANG Language Extensions 9.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 standard YANG statements, from which they are they can be used as the standard YANG statements, from which they are
distinguished by a namespace prefix qualifying the extension keyword. distinguished by a namespace prefix qualifying the extension keyword.
RELAX NG has a similar extension mechanism - XML elements and RELAX NG has a similar extension mechanism - XML elements and
attributes with names from foreign namespaces may be inserted at attributes with names from foreign namespaces may be inserted at
almost any place of a RELAX NG schema. almost any place of a RELAX NG schema.
YANG language extensions may or may not have a meaning in the context YANG language extensions may or may not have a meaning in the context
of DSDL schemas. Therefore, an implementation MAY ignore any or all of DSDL schemas. Therefore, an implementation MAY ignore any or all
of the extensions. However, an extension that is not ignored MUST be of the extensions. However, an extension that is not ignored MUST be
mapped to XML element(s) and/or attribute(s) that exactly match the mapped to XML element(s) and/or attribute(s) that exactly match the
YIN form of the extension, see Section 11.1 in [YANG]. YIN form of the extension, see Section 11.1 in [YANG].
skipping to change at page 39, line 5 skipping to change at page 40, 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="acme:folio"> <rng:element name="acme: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.
10. Mapping Conceptual Tree Schema to DSDL 10. Mapping YANG Statements to the Hybrid Schema
As explained in Section 6, the second step of the YANG-to-DSDL
mapping takes the conceptual tree schema and transforms it to various
DSDL schemas prepared for validating instance XML documents. As an
input parameter, this step takes in the simplest case just a
specification of the NETCONF XML document type (or combination of
multiple types) that is to be validated. These document type can be,
for example, the content of a datastore, reply to <nc:get> or <nc:
get-config>, other RPC requests or replies and notifications.
In general, the second mapping step has to accomplish the following
three tasks:
1. Extract the part(s) of the conceptual tree schema that are
appropriate for the requested document type. For example, if a
<get> reply is to be validated, the subtree under <nmt:top> must
be selected.
2. The schema must be adapted to the specific encapsulating XML
elements mandated by the RPC layer. These are, for example, <nc:
rpc> and <nc:data> elements in the case of a <get> reply or <en:
notification> for a notification.
3. Finally, NETMOD-specific annotations that are relevant for the
schema language of the generated schema must be mapped to the
corresponding rules.
These three tasks are together much simpler than the first mapping
step and can be effectively implemented using XSL transformations
[XSLT].
The following subsections describe the details of the second mapping
step for the individual DSDL schema languages. Section 12 then
contains a detailed specification for the mapping of all NETMOD-
specific annotations.
10.1. Generating RELAX NG Schemas for Various Document Types
With one minor exception, obtaining a validating RELAX NG schema from
the conceptual tree schema really means only taking appropriate parts
of the conceptual tree schema and assembling them in a new RELAX NG
grammar, perhaps after removing all unwanted annotations. Depending
on the XML document type that is the target for validation (<get>/
<get-config> reply, RPC or notification) a corresponding top-level
part of the grammar MUST be added as described in the following
subsections.
Schemas for multiple alternative target document types can also be
easily generated by enclosing the definitions for requested type in
<rng:choice> element.
In order to avoid copying common named pattern definitions to every
single output RELAX NG file, these schema-independent definitions
SHOULD be collected in a library file which is then included by the
validating RELAX NG schemas. Appendix B has the listing of this
library file.
The minor exception mentioned above is the annotation @nma:config,
which must be observed if the target document type is <get-config>
reply. In this case, each element definition that has this attribute
with the value "false" MUST be removed from the schema together with
its descendants. See Section 12.1 for more details.
10.1.1. Reply to <get> or <get-config>
For a reply to <get> or <get-config>, the mapping must take the part
of the conceptual tree schema under the definition of <nmt:top> and
insert it in the following grammar:
<rng:grammar ... namespaces etc. ...>
<rng:include href="relaxng-lib.rng"/>
<rng:start>
<rng:element name="nc:rpc-reply">
<rng:ref name="message-id-attribute"/>
<rng:element name="nc:data">
... patterns defining contents of "nmt:top" subtree ...
</rng:element>
</rng:element>
</rng:start>
... named pattern definitions ...
</rng:grammar>
The definition for the named pattern "message-id-attribute" is found
in the library file "relaxng-lib.rng" which is included on the second
line (see Appendix B).
Definitions of other named patterns MUST be copied literally from the
conceptual tree schema to the resulting grammar. However, an
implementation MAY choose to copy only those definitions that are
really used in the particular output grammar.
10.1.2. Remote Procedure Calls
For an RPC method named "myrpc" and defined in a YANG module with
prefix "yam", the corresponding schema subtree is identified by the
definition of <nmt:rpc-method> element whose <nmt:input> subelement
has <yam:myrpc> as the only child.
The mapping must also take into account whether the target document
type is an RPC request or reply. For "yam:myrpc" request, the
resulting grammar looks as follows:
<rng:grammar ... namespaces etc. ...>
<rng:include href="relaxng-lib.rng"/>
<rng:start>
<rng:element name="nc:rpc">
<rng:ref name="message-id-attribute"/>
<rng:element name="yam:myrpc">
... patterns defining contents of the subtree ...
... "nmt:rpc-method/nmt:input/yam:myrpc" ...
</rng:element>
</rng:element>
</rng:start>
... named pattern definitions ...
</rng:grammar>
For "yam:myrpc" reply, the output grammar is
<rng:grammar ... namespaces etc. ...>
<rng:include href="relaxng-lib.rng"/>
<rng:start>
<rng:element name="nc:rpc-reply">
<rng:ref name="message-id-attribute"/>
... patterns defining contents of the corresponding ...
... "nmt:rpc-method/nmt:output" subtree ...
</rng:element>
</rng:start>
... named pattern definitions ...
</rng:grammar>
In both cases, exact copies of named pattern definitions from the
conceptual tree schema MUST be inserted, but an implementation MAY
choose to include only those used for the given RPC.
10.1.3. Notifications
For a notification named "mynotif" and defined in a YANG module with
prefix "yam", the corresponding schema subtree is identified by the
definition of <nmt:notification> element that has the single child
<yam:mynotif>.
The resulting grammar looks as follows:
<rng:grammar ... namespaces etc. ...>
<rng:include href="relaxng-lib.rng"/>
<rng:start>
<rng:element name="en:notification">
<rng:ref name="eventTime-element"/>
<rng:element name="yam:mynotif">
<!-- patterns defining contents of
"nmt:rpc-notification/yam:mynotif" subtree -->
</rng:element>
</rng:element>
</rng:start>
<!-- named pattern definitions -->
</rng:grammar>
The definition of the named pattern "eventTime-element" is found in
the "relaxng-lib.rng" library file, see Appendix B.
Again, exact copies of named pattern definitions from the conceptual
tree schema MUST be inserted, but an implementation MAY choose to
include only those used for the given notification.
10.2. Mapping Semantic Constraints to Schematron
Schematron schemas tend to be much flatter and more uniform compared
to RELAX NG. They have exactly four levels of XML hierarchy: <sch:
schema>, <sch:pattern>, <sch:rule> and <sch:assert> or <sch:report>.
In a Schematron schema generated by the second mapping step, the
basic unit of organization is a rule represented by the <sch:rule>
element. Every rule corresponds to exactly one element definition
pattern in the conceptual tree schema:
<sch:rule context="XELEM">
...
</sch:rule>
The value of the mandatory @context attribute of <sch:rule> (denoted
as XELEM) MUST be set to the absolute path of the context element in
the data tree. The <sch:rule> element contains the mappings of one
or more of the following NETMOD-specific annotations, if they are
attached to the context element: <nma:instance-identifier>, @nma:key,
@nma:leafref, @nma:min-elements, @nma:max-elements, <nma:must>, @nma:
unique and <nma:when>.
In the opposite direction, however, not every element definition
pattern in the conceptual tree schema has a corresponding rule in the
Schematron schema: definitions of elements the carry none of the
above annotations are omitted.
Schematron rules may be further grouped into patterns represented by
the <sch:pattern> element. The mapping uses patterns only for
discriminating between subsets of rules that belong to different
validation phases, see Section 10.2.1. Therefore, the <sch:schema>
always has exactly two <sch:pattern> children: one named "standard"
contains rules for all annotations except <nma:instance-identifier>
and @nma:leafref, and another named "ref-integrity" containing rules
for these two remaining annotations, i.e., referential integrity
checks.
Element definitions in the conceptual tree schema that appear inside
a named pattern definition (i.e., have <rng:define> among its
ancestors) are subject to a different treatment. This is because
their path in the data tree is not fixed - the named pattern may be
referred to in multiple places. The mapping uses Schematron abstract
rules to handle this case: An element definition inside a named
pattern is mapped to an abstract rule and every use of the named
pattern then extends (uses) this abstract rule in the concrete
context.
EXAMPLE. Consider this element pattern annotated with <nma:must>:
<rng:element name="dhcp:default-lease-time">
<rng:data type="unsignedInt"/>
<nma:must assert=". &lt;= ../dhcp:max-lease-time">
<nma:error-message>
The default-lease-time must be less than max-lease-time
</nma:error-message>
</nma:must>
</rng:element>
If this element pattern appears outside any named pattern and as a
child of <dhcp:dhcp> (as it does in the DHCP schema, see
Appendix C.2), it is mapped to the following Schematron rule:
<sch:rule context="/nc:rpc-reply/nc:data/dhcp:dhcp/
dhcp:default-lease-time">
<sch:assert test=". &lt;= ../dhcp:max-lease-time">
The default-lease-time must be less than max-lease-time
</sch:assert>
</sch:rule>
Now assume the element definition is inside a named pattern
definition, say
<rng:define name="_dhcp__default-lease-time">
<rng:element name="dhcp:default-lease-time">
... same content ...
</rng:element>
</rng:define>
In this case it is mapped to an abstract rule, for instance
<sch:rule id="id31415926" abstract="true">
<sch:assert test=". &lt;= ../dhcp:max-lease-time">
The default-lease-time must be less than max-lease-time
</sch:assert>
</sch:rule>
Any use of the named pattern definition via <rng:ref
name="_dhcp__default-lease-time"/> then results in a new rule
extending the abstract one, for example
<sch:rule context="/nc:rpc-reply/nc:data/dhcp:dhcp/
dhcp:default-lease-time">
<sch:extends rule="id31415926"/>
</sch:rule>
Care must be taken that the value of the @context attribute in
general consists of two parts in this case: its beginning is
determined by the location of the <rng:ref> element in the main
schema tree and the rest of the path comes from the relative position
of the annotated element definition inside the named pattern. The
situation becomes even more complex when the mapping has to deal with
chained definitions of named patterns (<rng:ref> inside <rng:
define>). The @context value then must be recursively glued together
from multiple parts.
The mapping from the conceptual tree schema to Schematron proceeds in
the following steps:
1. First, the active subtree(s) of the conceptual tree schema must
be selected depending on the requested target document type.
This procedure is identical to the RELAX NG case, including the
handling of @nma:config if the target document type is <get-
config> reply.
2. Namespaces of all input YANG modules, together with the
namespaces of base NETCONF ("nc" prefix) or notifications ("en"
prefix) MUST be declared using the <sch:ns> element, for example
<sch:ns uri="http://example.com/ns/dhcp" prefix="dhcp"/>
3. Validation phases are defined (see Section 10.2.1) and their
constituting patterns "standard" and "ref-integrity" created.
4. For either validation phase, the input conceptual tree schema is
scanned and element definitions with annotations relevant for the
given phase are selected and a <sch:rule> is created for each of
them. As explained above, the rule is abstract if the element
definition appears inside a named pattern.
5. All annotations attached to the given element definition are then
mapped using the mapping rules specified in Section 12. The
resulting <sch:assert> or <sch:report> elements are the installed
as children of the <sch:rule> element.
10.2.1. Validation Phases
In certain situations it is useful to validate XML instance documents
without enforcing the referential integrity constraints represented
by the @nma:leafref and <nma:instance-identifier> annotations. For
example, a candidate configuration referring to configuration
parameters or state data of certain hardware will not pass full
validation before the hardware is installed. To handle this, the
Schematron mapping introduces two validation phases:
o Validation phase "full", which is the default, checks all semantic
constraints.
o Validation phase "noref" is the same as "full" except it doesn't
check referential integrity constraints.
A parameter identifying the validation phase to use has to be passed
to the Schematron processor or otherwise "full" phase is assumed by
default. How this is exactly done depends on the concrete Schematron
processor and is outside the scope of this document.
The validation phases are defined in Schematron by listing the
patterns that are to be applied for each phase. Therefore, the
mapping puts the rules for referential integrity checking to a
special <sch:pattern> with @id attribute set to "ref-integrity". The
rules mapped from the remaining semantic constraints are put to
another <sch:pattern> with @id attributes set to "standard".
With validation phases, the resulting Schematron schema has the
following overall structure:
<sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron">
<sch:ns uri="..." prefix="..."/>
... more NS declarations ...
<sch:phase id="full">
<sch:active pattern="standard"/>
<sch:active pattern="ref-integrity"/>
</sch:phase>
<sch:phase id="noref">
<sch:active pattern="standard"/>
</sch:phase>
<sch:pattern id="standard">
... all rules except ref. integrity checks ...
</sch:pattern>
<sch:pattern id="ref-integrity">
... rules for ref. integrity checks ...
</sch:pattern>
</sch:schema>
10.3. Constraints on Mandatory Choice
In order to fully represent the semantics of YANG 'choice' statement
with "mandatory true;" substatement, the RELAX NG grammar has to be
combined with a special Schematron rule.
EXAMPLE. Consider the following module:
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;
}
}
}
In this module, all three leaf nodes in both case branches are
optional but because of the "mandatory true;" statement, at least one
of them must be present in a valid configuration. The 'choice'
statement from this module is mapped to the following fragment of the
conceptual tree schema:
<rng:choice>
<rng:interleave>
<rng:optional>
<rng:element name="ex4:foo1">
<rng:data type="unsignedByte"/>
</rng:element>
</rng:optional>
<rng:optional>
<rng:element name="ex4:foo2">
<rng:data type="unsignedByte"/>
</rng:element>
</rng:optional>
</rng:interleave>
<rng:element name="ex4:bar">
<rng:data type="unsignedByte"/>
</rng:element>
</rng:choice>
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 of them alone suffices for a valid configuration. As a result,
the above RELAX NG fragment would successfully validate
configurations where none of the three leaf elements is present.
Therefore, mandatory choices, which can be recognized in the
conceptual tree schema as <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.).
For the example module above, the Schematron rule will be as follows:
<sch:rule context="/nc:rpc-reply/nc:data">
<sch:assert test="ex4:foo1 or ex4:foo2 or ex4:bar">
Node(s) from at least one case of choice "foobar" must exist.
</sch:assert>
</sch:rule>
10.4. Mapping Default Values to DSRL
DSRL is the only component of DSDL that is allowed to change the
information set of the validated XML document. While DSRL also has
other functions, YANG-to-DSDL mapping uses it only for specifying and
applying default content. For XML instance documents based on YANG
data models, insertion of default content may potentially take place
for all implicit nodes defined by the rules in Section 9.1.2.
In DSRL, the default content of an element is specified using the
<dsrl:default-content> element, which is a child of <dsrl:element-
map>. Two sibling elements of <dsrl:default-content> determine the
context for application of the default content, see [DSRL]:
o <dsrl:parent> element contains an 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, if missing
or empty, 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.
DSRL mapping only deals with element patterns defining implicit nodes
(see Section 9.1.2). In the conceptual tree schema, such element
patterns are distinguished by having NETMOD-specific annotation
attributes @nma:default or @nma:implicit, i.e., either
<rng:element name="ELEM" nma:default="DEFVALUE">
...
</rng:element>
or
<rng:element name="ELEM" nma:implicit="true">
...
</rng:element>
The former case applies to leaf nodes having the 'default'
substatement, but also to leaf nodes that obtain their default value
from a typedef, if this typedef is expanded according to the rules in
Section 9.2.2 so that the @nma:default annotation is attached
directly to the leaf's element pattern.
The latter case is used for all implicit containers (see Section 9.1)
and for leafs that obtain the default value from a typedef and don't
have the @nma:default annotation.
In the simplest case, both element patterns are mapped to the
following DSRL element map:
<dsrl:element-map>
<dsrl:parent>XPARENT</dsrl:parent>
<dsrl:name>ELEM</dsrl:name>
<dsrl:default-content>DEFCONT</dsrl:default-content>
</dsrl:element-map>
where XPARENT is the absolute XPath of ELEM's parent element in the
data tree and DEFCONT is constructed as follows:
o If the implicit node ELEM is a leaf and has the @nma:default
attribute, DEFCONT is set to the value of this attribute (denoted
above as DEFVALUE).
o If the implicit node ELEM is a leaf and has the @nma:implicit
attribute with the value "true", the default value has to be
determined from the @nma:default attribute of the definition of
ELEM's type (perhaps recursively) and used in place of DEFCONT in
the above DSRL element map. See also Section 9.2.2.
o Otherwise, the implicit node ELEM is a container and DEFCONT is
constructed as an XML fragment containing all descendant elements
of ELEM that have either @nma:implicit or @nma:default attribute.
The <rng:element>, <rng:group> or <rng:interleave>patterns appearing
directly under <rng:choice> MUST NOT have either @nma:default or
@nma:implicit annotation unless they belong to the default case of a
YANG choice (see Section 11.12).
In addition, when mapping the default case of a choice, it has to be
guaranteed that the default content is not applied if any node from
any non-default case is present. This is accomplished by setting
<dsrl:parent> in a special way:
<dsrl:parent>XPARENT[not (ELEM1|ELEM2|...|ELEMn)]</dsrl:parent>
where ELEM1, ELEM2, ... ELEMn are the names of all top-level nodes
from all non-default cases. The rest of the element map is exactly
as before.
EXAMPLE. Consider the following YANG module:
module 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>
<ex5:one><ex5:leaf2>2</ex5:leaf2></ex5:one>
</dsrl:default-content>
</dsrl:element-map>
<dsrl:element-map>
<dsrl:parent>
/nc:rpc-reply/nc:data/ex5:outer[not(ex5:leaf3)]
</dsrl:parent>
<dsrl:name>ex5:one</dsrl:name>
<dsrl:default-content>
<ex5:leaf2>2</ex5:leaf2>
</dsrl:default-content>
</dsrl:element-map>
<dsrl:element-map>
<dsrl:parent>/nc:rpc-reply/nc:data/ex5:outer</dsrl:parent>
<dsrl:name>ex5:leaf1</dsrl:name>
<dsrl:default-content>1</dsrl:default-content>
</dsrl:element-map>
<dsrl:element-map>
<dsrl:parent>/nc:rpc-reply/nc:data/ex5:outer</dsrl:parent>
<dsrl:name>ex5:one</dsrl:name>
<dsrl:default-content>
<ex5:leaf2>2</ex5:leaf2>
</dsrl:default-content>
</dsrl:element-map>
<dsrl:element-map>
<dsrl:parent>/nc:rpc-reply/nc:data/ex5:outer/ex5:one</dsrl:parent>
<dsrl:name>ex5:leaf2</dsrl:name>
<dsrl:default-content>2</dsrl:default-content>
</dsrl:element-map>
</dsrl:maps>
Note that the default value for "leaf3" defined in the YANG module is
ignored because "leaf3" represents a non-default alternative of a
choice and as such never becomes an implicit element.
11. Mapping YANG Statements to Conceptual Tree Schema
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 of how the statement is mapped to the
annotated RELAX NG schema of the conceptual tree. This is the first hybrid schema. The subsections are sorted alphabetically by the
step of the mapping procedure as explained in Section 6. The statement keyword.
subsections are 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 procedure is inherently recursive, which means that after mapping procedure 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. Any changes to this default recursive procedure are substatements. Any changes to this default recursive procedure are
explicitly specified. explicitly specified.
YANG XML encoding rules translate to the following rules for ordering YANG XML encoding rules translate to the following rules for ordering
multiple subelements: multiple subelements:
1. Within the <nmt:rpc-methods> subtree (i.e., for RPC input and 1. Within the <nma:rpcs> subtree (i.e., for input and output
output parameters) the order of subelements is fixed and their parameters of an RPC operation) the order of subelements is fixed
definitions in the conceptual tree schema MUST follow the order and their definitions in the hybrid schema MUST follow the order
specified in the source YANG module. specified in the source YANG module.
2. When mapping the 'list' statement, all keys MUST come before any 2. When mapping the 'list' statement, all keys MUST come before any
other subelements and in the same order as they are declared in other subelements and in the same order as they are declared in
the 'key' statement. The order of the remaining (non-key) the 'key' statement. The order of the remaining (non-key)
subelements is not specified, so their definitions in the subelements is not specified, so their definitions in the hybrid
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. schema MUST be enclosed in the <rng:interleave> element.
We use the following conventions: 3. Otherwise, the order of subelements is arbitrary and,
consequently, all definitions of subelements in the hybrid schema
MUST be enclosed in the <rng:interleave> element.
The following conventions are used in this section:
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.
11.1. The anyxml Statement 10.1. The anyxml Statement
This statement is mapped to <rng:element> element and ARGUMENT with This statement is mapped to <rng:element> element and ARGUMENT with
prepended local namespace prefix becomes the value of its @name prepended local namespace prefix becomes the value of its @name
attribute. The content of <rng:element> is attribute. The contents of <rng:element> are
<rng:ref name="__anyxml__"/>
<rng:ref name="__anyxml__"/>
Substatements of the 'anyxml' statement, if any, MAY be mapped to Substatements of the 'anyxml' statement, if any, MAY be mapped to
additional children of the RELAX NG element definition. additional children of the <rng:element> element.
If the 'anyxml' statement occurs in any of the input YANG modules, If at least one 'anyxml' statement occurs in any of the input YANG
the following pattern definition MUST be added exactly once to the modules, the following pattern definition MUST be added exactly once
RELAX NG schema as a child of the <rng:grammar> element (cf. [Vli04], to the RELAX NG schema as a child of the root <rng:grammar> element
p. 172): (cf. [Vli04], p. 172):
<rng:define name="__anyxml__"> <rng:define name="__anyxml__">
<rng:zeroOrMore> <rng:zeroOrMore>
<rng:choice> <rng:choice>
<rng:attribute> <rng:attribute>
<rng:anyName/> <rng:anyName/>
</rng:attribute> </rng:attribute>
<rng:element> <rng:element>
<rng:anyName/> <rng:anyName/>
<rng:ref name="__anyxml__"/> <rng:ref name="__anyxml__"/>
skipping to change at page 53, line 48 skipping to change at page 41, line 46
<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>
An anyxml node is optional if there is no "mandatory true;" An anyxml node is optional if there is no "mandatory true;"
substatement. The <rng:element> element then MUST be wrapped in substatement. The <rng:element> element then MUST be wrapped in
<rng:optional>, except when the 'anyxml' statement is a child of the <rng:optional>, except when the 'anyxml' statement is a child of the
'choice' statement and thus forms a shorthand case for that choice 'choice' statement and thus forms a shorthand case for that choice
(see Section 9.1.1 for details). (see Section 9.1.1 for details).
11.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 handling extensions in Section 9.4. for handling extensions in Section 9.4.
11.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 11.57. '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 augmented module is not processed within the same mapping session,
top-level 'augment' statement MUST be ignored. Otherwise, the 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.
11.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 11.53.5. type definition, see Section 10.53.5.
11.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 the processing of submodules is
initiated from the main module, see Section 11.24. always initiated from the main module, see Section 10.24.
11.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 11.53.3. Section 10.53.3.
11.7. The case Statement 10.7. The case Statement
This statement is mapped to <rng:group> or <rng:interleave> element, This statement is mapped to <rng:group> or <rng:interleave> element,
depending on whether the statement belongs to an RPC definition or depending on whether the statement belongs to an definition of an RPC
not. If the argument of a sibling 'default' statement equals to operation or not. If the argument of a sibling 'default' statement
ARGUMENT, @nma:implicit attribute with the value "true" MUST be added equals to ARGUMENT, @nma:implicit attribute with the value of "true"
to that <rng:group> or <rng:interleave> element. The @nma:implicit MUST be added to that <rng:group> or <rng:interleave> element. The
attribute MUST NOT be used for nodes at the top-level of a non- @nma:implicit attribute MUST NOT be used for nodes at the top-level
default case (see Section 7.9.3 in [YANG]). of a non-default case (see Section 7.9.3 in [YANG]).
11.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 If 'choice' has the 'mandatory' substatement with the value of
"true", the <rng:choice> element MUST be wrapped in <rng:optional>. "true", the attribute @nma:mandatory MUST be added to the <rng:
The 'choice' statement with "mandatory true;" may require additional choice> element with the value of ARGUMENT. This case may require
handling, see Section 10.3. additional handling, see Section 11.2.1. Otherwise, if "mandatory
true;" is not present, the <rng:choice> element MUST be wrapped in
<rng:optional>.
The alternatives in <rng:choice> - mapped from either the 'case' The alternatives in <rng:choice> - mapped from either the 'case'
statement or a shorthand case - MUST NOT be defined as optional. statement or a shorthand case - MUST NOT be defined as optional.
11.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.
11.10. The contact Statement 10.10. The contact Statement
This statement SHOULD NOT be used by the mapping since the output This statement SHOULD NOT be used by the mapping since the hybrid
RELAX NG schema may result from multiple YANG modules created by schema may be mapped from multiple YANG modules created by different
different authors. The schema contains references to all input authors. The hybrid schema contains references to all input modules
modules in the Dublin Core elements <dc:source>, see Section 11.34. in the Dublin Core elements <dc:source>, see Section 10.34. The
The original YANG modules are the authoritative sources of the original YANG modules are the authoritative sources of the authorship
authorship information. information.
11.11. The container Statement 10.11. The container Statement
Using the rules specified in Section 9.1.1, the mapping algorithm Using the rules specified in Section 9.1.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
with prepended local namespace prefix as the value of its @name with prepended local namespace prefix as the value of its @name
attribute. attribute.
Finally, using the rules specified in Section 9.1.2, the mapping Finally, using the rules specified in Section 9.1.2, the mapping
algorithm MUST determine whether the container is implicit, and if algorithm MUST determine whether the container is implicit, and if
so, add the attribute @nma:implicit with the value "true" to the so, add the attribute @nma:implicit with the value of "true" to the
<rng:element> element. <rng:element> element.
11.12. The default Statement 10.12. The default Statement
If this statement is a substatement of 'leaf', it is mapped to the If this statement is a substatement of 'leaf', it is mapped to the
@nma:default attribute of PARENT and ARGUMENT becomes its value. @nma:default attribute of PARENT and ARGUMENT becomes its value.
As a substatement of 'typedef', the 'default' statement is also As a substatement of 'typedef', the 'default' statement is also
mapped to the @nma:default attribute with the value of ARGUMENT. The mapped to the @nma:default attribute with the value of ARGUMENT. The
placement of this attribute depends on whether or not the type placement of this attribute depends on whether or not the type
definition has to be expanded when it is used: definition has to be expanded when it is used:
o If the type definition is not expanded, @nma:default becomes an o If the type definition is not expanded, @nma:default becomes an
attribute of the <rng:define> pattern resulting from the parent attribute of the <rng:define> pattern resulting from the parent
'typedef' mapping. 'typedef' mapping.
o Otherwise, @nma:default becomes an attribute of the ancestor RELAX o Otherwise, @nma:default becomes an attribute of the ancestor RELAX
NG pattern inside which the expansion takes place. NG pattern inside which the expansion takes place.
Details and an example are given in Section 9.2.2. Details and an example are given in Section 9.2.2.
Finally, as a substatement of 'choice', the 'default' statement Finally, as a substatement of 'choice', the 'default' statement
identifies the default case and is handled within the 'case' identifies the default case and is handled within the 'case'
statement, see Section 11.7. If the default case uses the shorthand statement, see Section 10.7. If the default case uses the shorthand
notation where the 'case' statement is omitted, the @nma:implicit notation where the 'case' statement is omitted, the @nma:implicit
attribute with the value "true" is either attached to the node attribute with the value of "true" is either attached to the node
representing the default case in the shorthand notation or, representing the default case in the shorthand notation or,
alternatively, an extra <rng:group> element MAY be inserted and the alternatively, an extra <rng:group> element MAY be inserted and the
@nma:implicit attribute attached to it. In the latter case, the net @nma:implicit attribute attached to it. In the latter case, the net
result is the same as if the 'case' statement wasn't omitted for the result is the same as if the 'case' statement wasn't omitted for the
default case. default case.
EXAMPLE. The following 'choice' statement in a module with namespace EXAMPLE. The following 'choice' statement in a module with namespace
prefix "yam" prefix "yam"
choice leaves { choice leaves {
skipping to change at page 57, line 5 skipping to change at page 45, line 5
<rng:group nma:implicit="true"> <rng:group nma:implicit="true">
<rng:element name="yam:feuille"> <rng:element name="yam:feuille">
<rng:empty/> <rng:empty/>
</rng:element> </rng:element>
</rng:group> </rng:group>
<rng:element name="yam:hoja"> <rng:element name="yam:hoja">
<rng:empty/> <rng:empty/>
</rng:element/> </rng:element/>
</rng:choice> </rng:choice>
11.13. The description Statement 10.13. The description Statement
This statement MAY be ignored. Otherwise, it is mapped to the DTD This statement MAY be ignored. Otherwise, it is mapped to the DTD
compatibility element <a:documentation> and ARGUMENT becomes its compatibility element <a:documentation> and ARGUMENT becomes its
text. 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.
11.14. The deviation Statement 10.14. The deviation Statement
This statement is ignored, see Section 8.5. This statement is ignored. However, it is assumed that all
deviations are known beforehand and the corresponding changes have
already been applied to the input YANG modules.
11.15. The enum Statement 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 annotation elements, see [RNG], <rng:value> element cannot contain annotation elements, see [RNG],
section 6. section 6.
11.16. 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 11.35. also Section 10.35.
11.17. 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 11.35. also Section 10.35.
11.18. 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 9.4. MAY be mapped as described in Section 9.4.
11.19. The feature Statement 10.19. The feature Statement
This statement is ignored, see Section 8.5. This statement is ignored.
11.20. The grouping Statement 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 9.2. according to the rules specified in Section 9.2.
Whenever a grouping is used with additional refinements and/or As explained in Section 8.2, a named pattern definition MUST be
augments, the grouping is expanded so that the refinements and placed
augments may be applied in place to the prescribed schema nodes. See
Section 9.2.1 for further details and an example.
An implementation MAY offer the option of recording all 'grouping' o as a child of the root <rng:grammar> element if the corresponding
statements as named patterns in the output RELAX NG schema even if grouping is defined at the top level of an input YANG module;
they are not referenced. This is useful for mapping YANG "library"
modules containing only 'typedef' and/or 'grouping' statements.
11.21. The identity Statement o otherwise as a child of the embedded <rng:grammar> element
corresponding to the module in which the grouping is defined.
This statement is not specifically mapped. However, if the identity Whenever a grouping is used with refinements and/or augments, it is
defined by this statement is used as the base for an "identityref" expanded so that the refinements and augments may be applied in place
type in any of the input modules, or is derived from this base, to the prescribed schema nodes. See Section 9.2.1 for further
ARGUMENT will appear as the text of one of the <rng:value> elements details and an example.
in the mapping of that "identityref" type. See Section 11.53.5 for
more details and an example.
11.22. The if-feature Statement An implementation MAY offer the option of mapping all 'grouping'
statements as named pattern definitions in the output RELAX NG schema
even if they are not referenced. This is useful for mapping YANG
"library" modules that typically contain only 'typedef' and/or
'grouping' statements.
This statement is ignored, see Section 8.5. 10.21. The identity Statement
11.23. The import Statement This statement is mapped to the following named pattern definition
which is placed as a child of the root <rng:grammar> element:
<rng:define name="__PREFIX_ARGUMENT">
<rng:choice>
<rng:value type="QName">PREFIX:ARGUMENT</rng:value>
<rng:ref name="IDENTITY1"/>
...
</rng:choice>
</rng:define>
where
PREFIX is the prefix used in the hybrid schema for the namespace
of the module where the current identity is defined.
IDENTITY1 is the name of of the named pattern corresponding to an
identity which is derived from the current identity. Exactly one
<rng:ref> element MUST be present for every such identity.
EXAMPLE ([YANG], Section 7.16.3). The identities in the input YANG
modules
module crypto-base {
namespace "http://example.com/crypto-base";
prefix "crypto";
identity crypto-alg {
description
"Base identity from which all crypto algorithms
are derived.";
}
}
module des {
namespace "http://example.com/des";
prefix "des";
import "crypto-base" {
prefix "crypto";
}
identity des {
base "crypto:crypto-alg";
description "DES crypto algorithm";
}
identity des3 {
base "crypto:crypto-alg";
description "Triple DES crypto algorithm";
}
}
will be mapped to the following named pattern definitions:
<define name="__crypto_crypto-alg">
<choice>
<value type="QName">crypto:crypto-alg</value>
<ref name="__des_des"/>
<ref name="__des_des3"/>
</choice>
</define>
<define name="__des_des">
<value type="QName">des:des</value>
</define>
<define name="__des_des3">
<value type="QName">des:des3</value>
</define>
10.22. The if-feature Statement
ARGUMENT together with arguments of all sibling 'if-feature'
statements (with added prefixes, if missing) MUST be collected in a
space-separated list which becomes the value of the @nma:if-feature
attribute. This attribute is attached to PARENT.
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 is able to
use its top-level groupings and typedefs and also augment the data use its top-level groupings, typedefs and identities, and also
tree of the imported module. augment the data 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.
11.24. 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 appeared directly in 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.
11.25. The input Statement 10.25. The input Statement
This statement is handled within 'rpc' statement, see Section 11.50. This statement is handled within 'rpc' statement, see Section 10.50.
11.26. The key Statement 10.26. The key Statement
This statement is mapped to @nma:key attribute. ARGUMENT MUST be This statement is mapped to @nma:key attribute. ARGUMENT MUST be
translated so that every key is prefixed with the namespace prefix of 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.
11.27. 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
with prepended local namespace prefix becomes the value of its @name with prepended local namespace prefix becomes the value of its @name
attribute. attribute.
A leaf is optional if there is no "mandatory true;" substatement and If the leaf is optional, i.e., if there is no "mandatory true;"
if the leaf is not declared among the keys of an enclosing list. The substatement and the leaf is not declared among the keys of an
<rng:element> element then MUST be wrapped in <rng:optional>, except enclosing list, then the <rng:element> element MUST be enclosed in
when the 'leaf' statement is a child of the 'choice' statement and <rng:optional>, except when the 'leaf' statement is a child of the
thus forms a shorthand case for that choice (see Section 9.1.1 for 'choice' statement and thus represents a shorthand case for that
details). choice (see Section 9.1.1 for details).
11.28. 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 then added as a child element of PARENT and ARGUMENT <rng:element> is then added as a child element of PARENT and ARGUMENT
with prepended local namespace prefix becomes the value of its @name with prepended local namespace prefix becomes the value of its @name
attribute. If the 'leaf-list' statement has the 'min-elements' attribute. Another attribute, @nma:leaf-list, MUST also be added to
substatement and its argument is greater than one, additional this <rng:element> element with the value of "true". If the 'leaf-
attribute @nma:min-elements is attached to <rng:element> and the list' statement has the 'min-elements' substatement and its argument
argument of 'min-elements' becomes the value of this attribute. is greater than one, additional attribute @nma:min-elements is
Similarly, if there is the 'max-elements' substatement and its attached to <rng:element> and the argument of 'min-elements' becomes
argument value is not "unbounded", attribute @nma:max-elements is the value of this attribute. Similarly, if there is the 'max-
attached to this element and the argument of 'max-elements' becomes elements' substatement and its argument value is not "unbounded",
the value of this attribute. attribute @nma:max-elements is attached to this element and the
argument of 'max-elements' becomes the value of this attribute.
EXAMPLE. A leaf-list appearing in a module with the namespace prefix
"yam"
EXAMPLE. YANG leaf-list in a module with namespace prefix "yam"
leaf-list foliage { leaf-list foliage {
min-elements 3; min-elements 3;
max-elements 6378; max-elements 6378;
ordered-by user; ordered-by user;
type string; type string;
} }
is mapped to the following RELAX NG fragment: is mapped to the following RELAX NG fragment:
<rng:oneOrMore> <rng:oneOrMore>
<rng:element name="yam:foliage" nma:ordered-by="user" <rng:element name="yam:foliage" nma:leaf-list="true"
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>
11.29. 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 11.53.9. Section 10.53.9.
11.30. 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 11.28. Section 10.28. The only difference is that the @nma:leaf-list
annotation either MUST NOT be present or MUST have the value of
"false".
When mapping the substatements of 'list', the order of children of When mapping the substatements of 'list', the order of children of
the list element MUST be specified so that list keys, if there are the list element MUST be specified so that list keys, if there are
any, always appear in the same order as they are defined in the input any, always appear in the same order as they are defined in the 'key'
YANG module and before other children, see [YANG], Section 7.8.5. In substatement and before other children, see [YANG], Section 7.8.5.
particular, if any list key is defined in a grouping but the list In particular, if a list key is defined in a grouping but the list
node itself is not a part of the same grouping, and the position of node itself is not a part of the same grouping, and the position of
the 'uses' statement would violate the above ordering requirement, the 'uses' statement would violate the above ordering requirement,
the grouping MUST be expanded, i.e., the 'uses' statement replaced by the grouping MUST be expanded, i.e., the 'uses' statement replaced by
the grouping contents. the grouping contents.
For example, consider the following YANG fragment of a module with For example, consider the following YANG fragment of a module with
prefix "yam": the prefix "yam":
grouping keygrp { grouping keygrp {
leaf clef { leaf clef {
type uint8; type uint8;
} }
} }
list foo { list foo {
key clef; key clef;
leaf bar { leaf bar {
type string; type string;
} }
leaf baz { leaf baz {
type string; type string;
} }
uses keygrp; uses keygrp;
} }
is mapped to the following RELAX NG fragment: is mapped to the following RELAX NG fragment:
<rng:zeroOrMore> <rng:zeroOrMore>
<rng:element name="yam:foo" nma:key="yam:clef"> <rng:element name="yam:foo" nma:key="yam:clef">
<rng:element name="yam:clef"> <rng:element name="yam:clef">
<rng:data type="unsignedByte"/> <rng:data type="unsignedByte"/>
</rng:element> </rng:element>
<rng:interleave> <rng:interleave>
<rng:element name="yam:bar"> <rng:element name="yam:bar">
<rng:data type="string"/> <rng:data type="string"/>
</rng:element> </rng:element>
<rng:element name="yam:baz"> <rng:element name="yam:baz">
<rng:data type="string"/> <rng:data type="string"/>
</rng:element> </rng:element>
</rng:interleave> </rng:interleave>
</rng:element> </rng:element>
</rng:zeroOrMore> </rng:zeroOrMore>
Note that the "keygrp" grouping is expanded and the "yam:clef" Note that the "keygrp" grouping is expanded and the definition of
definition moved before the <rng:interleave> pattern. "yam:clef" is moved before the <rng:interleave> pattern.
11.31. 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 9.1.1. mapped as mandatory, see Section 9.1.1.
11.32. The max-elements Statement As a substatement of 'choice', this statement is also mapped to the
@nma:mandatory attribute which is added to PARENT. The value of this
attribute is the argument of the parent 'choice' 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 11.28. see Section 10.28.
11.33. 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 11.28. see Section 10.28.
11.34. The module Statement
This statement is not specifically mapped except that a <dc:source> 10.34. The module Statement
element SHOULD be created as a child of <rng:grammar> and contain
ARGUMENT as a reference to the input YANG module. See also
Section 11.49.
With respect to the conceptual tree schema, substatements of 'module' This statement is mapped to an embedded <rng:grammar> pattern having
MUST be mapped so that the @nma:module attribute with the value of ARGUMENT. In addition, a
<dc:source> element SHOULD be created as a child of this <rng:
grammar> element and contain ARGUMENT as a metadata reference to the
input YANG module. See also Section 10.49.
o top level data elements be defined as descendants of the <nmt:top> Substatements of the 'module' statement MUST be mapped so that
element; o statements representing configuration/state data are mapped to
descendants of the <nma:data> element;
o elements mapped from 'rpc' statements be defined as descendants of o statements representing the contents of RPC requests or replies
the <nmt:rpc-methods> element; are mapped to descendants of the <nma:rpcs> element;
o elements mapped from 'notification' statements be defined as o statements representing the contents of event notifications are
descendants of the <nmt:notifications> element. mapped to descendants of the <nma:notifications> element.
11.35. 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 9.3). ARGUMENT transformed into a valid XPath expression (see Section 9.3).
The <nma:must> element may get other subelements resulting from The <nma:must> element may have other subelements resulting from
mapping 'error-app-tag' and 'error-message' substatements. Other mapping the '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 in the "dhcp" module
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>
11.36. The namespace Statement 10.36. The namespace Statement
This statement is mapped to @xmlns:xxx attribute of the <rng:grammar> This statement is mapped in two ways:
element where "xxx" is the namespace prefix specified by the sibling
'prefix' statement. ARGUMENT becomes the value of this attribute.
11.37. The notification Statement 1. To the @xmlns:PREFIX attribute of the root <rng:grammar> element
where PREFIX is the namespace prefix specified by the sibling
'prefix' statement. ARGUMENT becomes the value of this
attribute.
This statement is mapped to the following subtree in the RELAX NG 2. To the @ns attribute of PARENT, which is an embedded <rng:
schema ("yam" is the prefix of the local YANG module): grammar> pattern. ARGUMENT becomes the value of this attribute.
<rng:element name="nmt:notification"> 10.37. The notification Statement
<rng:element name="yam:ARGUMENT">
This statement is mapped to the following subtree of the <nma:
notifications> element in the hybrid schema (where PREFIX is the
prefix of the local YANG module):
<nma:notification>
<rng:element name="PREFIX:ARGUMENT">
... ...
</rng:element> </rng:element>
</rng:element> </nma:notification>
Substatements of 'notification' are mapped under <rng:element Substatements of 'notification' are mapped under <rng:element
name="yam:ARGUMENT">. name="PREFIX:ARGUMENT">.
The <rng:element name="nmt:rpc-notification"> element is a child of
<rng:element name="nmt:notifications">.
11.38. 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 11.28 for an becomes the value of this attribute. See Section 10.28 for an
example. example.
11.39. The organization Statement 10.39. The organization Statement
This statement is not used by the mapping since the output conceptual This statement is ignored by the mapping because the hybrid schema
tree schema may result from multiple YANG modules authored by may be mapped from multiple YANG modules authored by different
different parties. The schema contains references to all input parties. The hybrid schema SHOULD contain references to all input
modules in the Dublin Core elements <dc:source>, see Section 11.34. modules in the Dublin Core <dc:source> elements, see Section 10.34.
The original modules are the authoritative sources of the authorship The original YANG modules are the authoritative sources of the
information. authorship information.
11.40. The output Statement 10.40. The output Statement
This statement is handled within 'rpc' statement, see Section 11.50. This statement is handled within the 'rpc' statement, see
Section 10.50.
11.41. The path Statement 10.41. The path Statement
This statement is handled within "leafref" type, see Section 11.53.7. This statement is handled within the "leafref" type, see
Section 10.53.7.
11.42. The pattern Statement 10.42. The pattern Statement
This statement is handled within "string" type, see Section 11.53.9. This statement is handled within the "string" type, see
Section 10.53.9.
11.43. The position Statement 10.43. The position Statement
This statement is ignored. This statement is ignored.
11.44. 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 11.36, or within the parent 'import' statement, see see Section 10.36, or within the parent 'import' statement, see
Section 11.23. 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.
11.45. The presence Statement 10.45. The presence Statement
This statement is mapped to the annotation attribute @nma:presence This statement influences the mapping of the parent container
with the value "true". In addition, it influences the mapping of (Section 10.11): the parent container definition MUST be wrapped in
'container' (Section 11.11): the parent container definition MUST be <rng:optional>, regardless of its contents. See also Section 9.1.1.
wrapped in <rng:optional>, regardless of its content. See also
Section 9.1.1.
11.46. The range Statement 10.46. The range Statement
This statement is handled within numeric types, see Section 11.53.8. This statement is handled within numeric types, see Section 10.53.8.
11.47. The reference Statement 10.47. The reference Statement
This statement MAY be ignored. Otherwise, it is mapped to This statement MAY be ignored. Otherwise, it is mapped to
<a:documentation> element and its text is set to ARGUMENT prefixed <a:documentation> element and its text is set to ARGUMENT prefixed
with "See: ". with "See: ".
11.48. The require-instance Statement 10.48. The require-instance Statement
This statement is handled within "instance-identifier" type This statement is handled within "instance-identifier" type
(Section 11.53.6). (Section 10.53.6).
11.49. 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 [YANG]. This specifies the current revision of the input YANG module [YANG]. 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 <dc:source> element (see
Section 11.34), for example in this form: Section 10.34), for example in this form:
<dc:source>YANG module 'foo', revision 2010-03-02</dc:source> <dc:source>YANG module 'foo', revision 2010-03-02</dc:source>
The 'description' substatement of 'revision' is ignored. The 'description' substatement of 'revision' is ignored.
11.50. 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 (where PREFIX is the prefix of the local YANG module):
<rng:element name="nmt:rpc-method"> <nma:rpc>
<rng:element name="nmt:input"> <nma:input>
<rng:element name="yam:ARGUMENT"> <rng:element name="PREFIX:ARGUMENT">
... mapped content of 'input' ... ... mapped contents of 'input' ...
</rng:element> </rng:element>
</rng:element> </nma:input>
<rng:element name="nmt:output"> <nma:output">
... mapped content of 'output' ... ... mapped contents of 'output' ...
</rng:element> </nma:output>
</rng:element> </nma:rpc>
As indicated in the schema fragment, contents of the 'input' As indicated in the schema fragment, contents of the 'input'
substatement (if any) are mapped under <rng:element name="yam: substatement (if any) are mapped under <rng:element name="PREFIX:
ARGUMENT">. Similarly, contents of the 'output' substatement are ARGUMENT">. Similarly, contents of the 'output' substatement are
mapped under <rng:element name="nmt:output">. If there is no mapped under <nma:output>. If there is no 'output' substatement, the
'output' substatement, the <rng:element name="nmt:output"> MUST NOT <nma:output> element MUST NOT be present.
be present.
The <rng:element name="nmt:rpc-method"> element is a child of <rng: The <nma:rpc> element is a child of <nma:rpcs>.
element name="nmt:rpc-methods">.
11.51. The status Statement 10.51. The status Statement
This statement MAY be ignored. Otherwise, it is mapped to @nma: This statement MAY be ignored. Otherwise, it is mapped to @nma:
status attribute and ARGUMENT becomes its value. status attribute and ARGUMENT becomes its value.
11.52. 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.
11.53. The type Statement 10.53. The type Statement
Most YANG built-in datatypes have an equivalent in the XSD datatype Most YANG built-in datatypes have an equivalent in the XSD datatype
library [XSD-D] as shown in Table 3. library [XSD-D] as shown in Table 4.
+-----------+---------------+--------------------------------+ +-----------+---------------+--------------------------------+
| YANG type | XSD type | Meaning | | YANG type | XSD type | Meaning |
+-----------+---------------+--------------------------------+ +-----------+---------------+--------------------------------+
| int8 | byte | 8-bit integer value | | int8 | byte | 8-bit integer value |
| | | | | | | |
| int16 | short | 16-bit integer value | | int16 | short | 16-bit integer value |
| | | | | | | |
| int32 | int | 32-bit integer value | | int32 | int | 32-bit integer value |
| | | | | | | |
skipping to change at page 66, line 31 skipping to change at page 56, line 31
| | | | | | | |
| uint64 | unsignedLong | 64-bit unsigned integer value | | uint64 | unsignedLong | 64-bit unsigned integer value |
| | | | | | | |
| string | string | character string | | string | string | character string |
| | | | | | | |
| 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: YANG built-in datatypes with equivalents in the W3C XML Table 4: YANG built-in datatypes with equivalents in the W3C XML
Schema Type Library Schema Type Library
Two important datatypes of the XSD datatype library - "dateTime" and Two important datatypes of the XSD datatype library - "dateTime" and
"anyURI" - are not built-in in YANG but defined as derived types in "anyURI" - are not built-in types in YANG but instead are defined as
the standard modules [Ytypes]: "date-and-time" in the "ietf-yang- derived types in the standard modules [Ytypes]: "date-and-time" in
types" module and "uri" in the "ietf-inet-types" module. However, the "ietf-yang-types" module and "uri" in the "ietf-inet-types"
the formal restrictions in the YANG type definitions are rather weak. module. However, the formal restrictions in the YANG type
Therefore, implementations of the YANG-to-DSDL mapping SHOULD detect definitions are rather weak. Therefore, implementations of the YANG-
these derived types in source YANG modules and map them to "dateType" to-DSDL mapping SHOULD detect these derived types in source YANG
and "anyURI", respectively. modules and map them to "dateType" and "anyURI", respectively.
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.
11.53.1. The empty Type 10.53.1. The empty Type
This type is mapped to <rng:empty/>. This type is mapped to <rng:empty/>.
11.53.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 above. to ARGUMENT mapped according to Table 4 above.
11.53.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 a
corresponding 'bit' statement. 'bit' substatement.
11.53.4. The enumeration and union Types
These types are mapped to <rng:choice> element.
11.53.5. The identityref Type
This type is mapped to <rng:choice> element with one or more <rng:
value> subelements. Each of the <rng:value> subelements MUST have
the @type attribute and its value set to "QName". One <rng:value>
subelement for the base identity MUST always be present - it contains
the argument of the 'base' substatement as its text. In addition,
one <rng:value> substatement MUST be added for each identity declared
locally or in an imported module that is derived from this base
identity.
All namespace prefixes that are used for identities from imported
modules MUST be appropriately defined.
EXAMPLE (taken from Section 7.16.3 of [YANG]). Consider the
following two YANG modules:
module crypto-base { 10.53.4. The enumeration and union Types
namespace "http://example.com/crypto-base";
prefix "crypto";
identity crypto-alg { These types are mapped to the <rng:choice> element.
description
"Base identity from which all crypto algorithms
are derived.";
}
}
module des { 10.53.5. The identityref Type
namespace "http://example.com/des";
prefix "des";
import "crypto-base" { This type is mapped to the following named pattern reference:
prefix "crypto";
}
identity des { <rng:ref name="__PREFIX_BASE"/>
base "crypto:crypto-alg";
description "DES crypto algorithm";
}
identity des3 { where PREFIX:BASE is the qualified name of the identity appearing in
base "crypto:crypto-alg"; the argument of the 'base' substatement.
description "Triple DES crypto algorithm";
}
}
If these two modules are imported to another module with namespace For example, assume that module "des" in Section 10.21 contains the
prefix "yam", leaf definition following leaf definition:
leaf crypto { leaf foo {
type identityref { type identityref {
base "crypto:crypto-alg"; base crypto:crypto-alg;
} }
} }
is mapped to This leaf would then be mapped to the following element pattern:
<rng:element name="yam:crypto"> <element name="des:foo">
<rng:choice> <ref name="__crypto_crypto-alg"/>
<rng:value type="QName">crypto:crypto-alg</value> </element>
<rng:value type="QName">des:des</value>
<rng:value type="QName">des:des3</value>
</rng:choice>
</rng:element>
The "crypto" and "des" prefixes will typically be defined via
attributes of the <rng:grammar> element.
11.53.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, an empty <nma:instance-identifier> element
be inserted as a child of PARENT. MUST be inserted as a child of PARENT.
The argument of the 'require-instance' substatement, if it exists, The argument of the 'require-instance' substatement, if it exists,
becomes the value of the @require-instance attribute of <nma: becomes the value of the @require-instance attribute of the <nma:
instance-identifier>. instance-identifier> element.
11.53.7. The leafref Type 10.53.7. The leafref Type
This type is mapped exactly as the type of the leaf given in the This type is mapped exactly as the type of the leaf given in the
argument of 'path' substatement. In addition, @nma:leafref attribute argument of 'path' substatement. However, if the type of the
MUST be added to PARENT. The argument of the 'path' substatement, referred leaf defines a default value, this default value MUST be
translated according to Section 9.3, is set as the value of this ignored by the mapping.
attribute.
11.53.8. The numeric Types In addition, @nma:leafref attribute MUST be added to PARENT. The
argument of the 'path' substatement, translated according to
Section 9.3, is set as the value of this attribute.
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" and "decimal64". They are "uint8", "uint16", "uint32", "uint64" and "decimal64". They are
mapped to <rng:data> element with @type attribute set to ARGUMENT mapped to <rng:data> element with @type attribute set to ARGUMENT
translated according to Table 3 above. translated according to Table 4 above.
An exception is the "decimal64" type, which is mapped to the An exception is the "decimal64" type, which is mapped to the
"decimal" type of the XSD datatype library. Its precision and number "decimal" type of the XSD datatype library. Its precision and number
of fractional digits are controlled with the following facets, which of fractional digits are controlled with the following facets, which
MUST always be present: MUST always be present:
o "totalDigits" facet set to the value of 19. o "totalDigits" facet set to the value of 19.
o "fractionDigits" facet set to the argument of the 'fraction- o "fractionDigits" facet set to the argument of the 'fraction-
digits' substatement. digits' substatement.
skipping to change at page 70, line 10 skipping to change at page 59, line 10
fraction-digits 2; fraction-digits 2;
} }
is mapped to the following RELAX NG datatype: is mapped to the following RELAX NG datatype:
<rng:data type="decimal"> <rng:data type="decimal">
<rng:param name="totalDigits">19</rng:param> <rng:param name="totalDigits">19</rng:param>
<rng:param name="fractionDigits">2</rng:param> <rng:param name="fractionDigits">2</rng:param>
</rng:data> </rng:data>
All numeric types support the 'range' restriction, which is handled All numeric types support the 'range' restriction, which is mapped as
as follows: follows:
If the range expression has just a single range, then
o if the range consists of a single number, the <rng:value> pattern
is inserted and its content set to this number.
o Otherwise the range consists of both lower and upper bound and the If the range expression consists of just a single range LO..HI, then
following pair of datatype facets are inserted: it is mapped to a pair of datatype facets
<rng:param name="minInclusive">...</rng:param> <rng:param name="minInclusive">LO</rng:param>
and and
<rng:param name="maxInclusive">...</rng:param> <rng:param name="maxInclusive">HI</rng:param>
Their contents are the lower and upper bound, respectively. If If the range consists of a single number, the values of both facets
the lower bound is "min", the "minInclusive" facet is omitted and are set to this value. If LO is equal to the string "min", the
if the upper bound is "max", the "maxInclusive" facet is omitted. "minInclusive" facet is omitted. If HI is equal to the string "max",
the "maxInclusive" facet is omitted.
If the range expression has multiple parts separated by "|", then the If the range expression has multiple parts separated by "|", then the
parent <rng:data> element must be repeated once for every range part parent <rng:data> element must be repeated once for every range part
and all such <rng:data> elements are wrapped in <rng:choice> element. and all such <rng:data> elements are wrapped in <rng:choice> element.
Each <rng:data> element contains the <rng:value> pattern or the Each <rng:data> element contains the "minInclusive" and
"minInclusive" and "maxInclusive" facets for one part of the range "maxInclusive" facets for one part of the range expression as
expression as described in the previous paragraph. For the described in the previous paragraph.
"decimal64" type, the "totalDigits" and "fractionDigits" must be
repeated inside each of the <rng:data> elements. For the "decimal64" type, the "totalDigits" and "fractionDigits" must
be repeated inside each of the <rng:data> elements.
For example, For example,
type int32 { type int32 {
range "-6378..0|42|100..max"; range "-6378..0|42|100..max";
} }
is mapped to the following RELAX NG fragment: is mapped to the following RELAX NG fragment:
<rng:choice> <rng:choice>
<rng:data type="int"> <rng:data type="int">
<rng:param name="minInclusive">-6378</rng:param> <rng:param name="minInclusive">-6378</rng:param>
<rng:param name="maxInclusive">0</rng:param> <rng:param name="maxInclusive">0</rng:param>
</rng:data> </rng:data>
<rng:data type="int"> <rng:data type="int">
<rng:value>42</rng:value> <rng:param name="minInclusive">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>
11.53.9. The string Type See Section 9.2.2 for further details on mapping the restrictions.
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".
The 'length' restriction is handled analogically to the 'range' The 'length' restriction is handled analogically to the 'range'
restriction for the numeric types (Section 11.53.8): restriction for the numeric types (Section 10.53.8):
If the length expression has just a single range, then If the length expression has just a single range, then
o if the length range consists of a single number L, the following o if the length range consists of a single number LENGTH, the
datatype facet is inserted: following datatype facet is inserted:
<rng:param name="length">L</rng:param>. <rng:param name="length">LENGTH</rng:param>.
o Otherwise the length range consists of both lower and upper bound o Otherwise the length range is of the form LO..HI, i.e., it
and the following pair of datatype facets are inserted: consists of both the lower and upper bound. The following two
datatype facets are then inserted:
<rng:param name="minLength">...</rng:param> <rng:param name="minLength">LO</rng:param>
and and
<rng:param name="maxLength">...</rng:param> <rng:param name="maxLength">HI</rng:param>
Their contents are the lower and upper bound of the length range, If LO is equal to the string "min", the "minLength" facet is
respectively. If the lower bound is "min", the "minLength" facet omitted. If HI is equal to the string "max", the "maxLength"
is omitted and if the upper bound is "max", the "maxLength" facet facet is omitted.
is omitted.
If the length expression has of multiple parts separated by "|", then If the length expression has of multiple parts separated by "|", then
the parent <rng:data> element must be repeated once for every range the parent <rng:data> element must be repeated once for every range
part and all such <rng:data> elements are wrapped in <rng:choice> part and all such <rng:data> elements are wrapped in <rng:choice>
element. Each <rng:data> element contains the "length" or element. Each <rng:data> element contains the "length" or
"minLength" and "maxLength" facets for one part of the length "minLength" and "maxLength" facets for one part of the length
expression as described in the previous paragraph. expression as described in the previous paragraph.
Every 'pattern' restriction of the "string" datatype is mapped to the Every 'pattern' restriction of the "string" datatype is mapped to the
"pattern" facet "pattern" facet
<rng:param name="pattern">...</rng:param> <rng:param name="pattern">...</rng:param>
with content equal to the argument of the 'pattern' statement. All with text equal to the argument of the 'pattern' statement. All such
such "pattern" facets must be repeated inside each copy of the <rng: "pattern" facets must be repeated inside each copy of the <rng:data>
data> element, i.e., once for each length range. element, i.e., once for each length range.
For example, For example,
type string { type string {
length "1|3..8"; length "1|3..8";
pattern "[A-Z][a-z]*"; pattern "[A-Z][a-z]*";
} }
is mapped to the following RELAX NG fragment: is mapped to the following RELAX NG fragment:
skipping to change at page 72, line 35 skipping to change at page 61, line 38
<rng:param name="length">1</rng:param> <rng:param name="length">1</rng:param>
<rng:param name="pattern">[A-Z][a-z]*</rng:param> <rng:param name="pattern">[A-Z][a-z]*</rng:param>
</rng:data> </rng:data>
<rng:data type="string"> <rng:data type="string">
<rng:param name="minLength">3</rng:param> <rng:param name="minLength">3</rng:param>
<rng:param name="maxLength">8</rng:param> <rng:param name="maxLength">8</rng:param>
<rng:param name="pattern">[A-Z][a-z]*</rng:param> <rng:param name="pattern">[A-Z][a-z]*</rng:param>
</rng:data> </rng:data>
</rng:choice> </rng:choice>
11.53.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 type definition MUST to the hybrid schema yet, the corresponding type definition MUST
be found and its mapping installed as a subelement of <rng: be found and its mapping installed as a subelement of either the
grammar>, see Section 11.54. Even if a given derived type is root or an embedded <rng:grammar> element, see Section 10.54.
used more than once in the input YANG modules, the mapping of the Even if a given derived type is used more than once in the input
corresponding 'typedef' MUST be installed only once. YANG modules, the mapping of the corresponding 'typedef' MUST be
installed only once.
2. If any restrictions are present, the ancestor built-in type for 2. If any restrictions are present, the ancestor built-in type for
the given derived type must be determined and the mapping of this the given derived type must be determined and the mapping of this
base type MUST be used. Restrictions appearing at all stages of base type MUST be used. Restrictions appearing at all stages of
the type derivation chain MUST be taken into account and their the type derivation chain MUST be taken into account and their
conjunction added to the <rng:data> element which defines the conjunction added to the <rng:data> element which defines the
basic type. basic type.
See Section 9.2.2 for more details and an example. See Section 9.2.2 for more details and an example.
11.54. 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 either the root
grammar> element and its name is ARGUMENT mangled according to the or an embedded <rng:grammar> element, depending on whether the
rules specified in Section 9.2. 'typedef' statement appears at the top level of a YANG module or not.
The name of this named pattern definition is set to ARGUMENT mangled
according to the rules specified in Section 9.2.
Whenever a derived type is used with additional restrictions, the Whenever a derived type is used with additional restrictions, the
ancestor built-in type for the derived type is used instead with ancestor built-in type for the derived type is used instead with
restrictions (facets) that are a combination of all restrictions restrictions (facets) that are a combination of all restrictions
specified along the type derivation chain. See Section 11.53.10 for specified along the type derivation chain. See Section 10.53.10 for
further details and an example. further details 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.
11.55. 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 MUST be
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"
11.56. 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. Implementations MAY ignore this statement. its value. Implementations MAY ignore this statement.
11.57. 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, i.e., a reference to a named it is mapped to <rng:ref> element, i.e., a reference to a named
pattern, and the value of its @name attribute is set to ARGUMENT pattern, and the value of its @name attribute is set to ARGUMENT
mangled according to Section 9.2. If the RELAX NG definition of the mangled according to Section 9.2. If the RELAX NG definition of the
referenced named pattern has not been added to the output schema yet, referenced named pattern has not been added to the hybrid schema yet,
the corresponding grouping MUST be found and its mapping installed as the corresponding grouping MUST be found and its mapping installed as
a subelement of <rng:grammar>, see Section 11.20. a subelement of <rng:grammar>, see Section 10.20.
Otherwise, if the 'uses' statement has any 'refine' or 'augment' Otherwise, if the 'uses' statement has any 'refine' or 'augment'
substatements, the corresponding grouping must be looked up and its substatements, the corresponding grouping must be looked up and its
contents is inserted under PARENT. See Section 9.2.1 for further contents inserted under PARENT. See Section 9.2.1 for further
details and an example. details and an example.
11.58. The value Statement 10.58. The value Statement
This statement is ignored. This statement is ignored.
11.59. The when Statement 10.59. The when Statement
This statement is mapped to @nma:when attribute and ARGUMENT, This statement is mapped to @nma:when attribute and ARGUMENT,
translated according to Section 9.3, becomes it value. translated according to Section 9.3, becomes it value.
11.60. 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).
11.61. 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 9.4. for extension handling in Section 9.4.
12. Mapping NETMOD-specific annotations to DSDL Schema Languages 11. Mapping the Hybrid Schema to DSDL
This section contains mapping specification for individual NETMOD- As explained in Section 6, the second step of the YANG-to-DSDL
specific annotations. In each case, the result of the mapping must mapping takes the hybrid schema and transforms it to various DSDL
be inserted into an appropriate context of the target DSDL schema as schemas capable of validating instance XML documents. As an input
described in Section 10. The context is determined by the element parameter, this step takes, in the simplest case, just a
definition in the conceptual tree schema to which the annotation is specification of the NETCONF XML document type that is to be
validated. These document types can be, for example, the contents of
a datastore, a reply to <nc:get> or <nc:get-config>, contents of
other RPC requests/replies and event notifications, and so on.
In general, the second mapping step has to accomplish the following
three tasks:
1. Extract the parts of the hybrid schema that are appropriate for
the requested document type. For example, if a <nc:get> reply is
to be validated, the subtree under <nma:data> has to be selected.
2. The schema must be adapted to the specific encapsulating XML
elements mandated by the RPC layer. These are, for example, <nc:
rpc> and <nc:data> elements in the case of a <nc:get> reply or
<en:notification> for a notification.
3. Finally, NETMOD-specific annotations that are relevant for the
schema language of the generated schema must be mapped to the
corresponding patterns or rules.
These three tasks are together much simpler than the first mapping
step and can be effectively implemented using XSL transformations
[XSLT].
The following subsections describe the details of the second mapping
step for the individual DSDL schema languages. Section 12 then
contains a detailed specification for the mapping of all NETMOD-
specific annotations.
11.1. Generating RELAX NG Schemas for Various Document Types
With one minor exception, obtaining a validating RELAX NG schema from
the hybrid schema only means taking appropriate parts of the hybrid
schema and assembling them in a new RELAX NG grammar, perhaps after
removing all unwanted annotations.
The structure of the resulting RELAX NG schema is similar to that of
the hybrid schema: The root grammar contains embedded grammars, one
for each input YANG module. However, as explained in Section 8.2,
global named pattern definitions (children of the root <rng:grammar>
element) MUST be moved to a separate schema file.
Depending on the XML document type that is the target for validation,
such as <nc:get>/<nc:get-config> reply, RPC operations or
notifications, patterns defining corresponding top-level information
items MUST be added, such as <nc:rpc-reply> with the @message-id
attribute and so on.
In order to avoid copying common named pattern definitions for common
NETCONF elements and attributes to every single output RELAX NG file,
such schema-independent definitions SHOULD be collected in a library
file which is then included by the validating RELAX NG schemas.
Appendix B has the listing of such a library file.
The minor exception mentioned above is the annotation @nma:config,
which must be observed if the target document type is a reply to <nc:
get-config>. In this case, each element definition that has this
attribute with the value of "false" MUST be removed from the schema
together with its descendants. See Section 12.1 for more details.
11.2. Mapping Semantic Constraints to Schematron
Schematron schemas tend to be much flatter and more uniform compared
to RELAX NG. They have exactly four levels of XML hierarchy: <sch:
schema>, <sch:pattern>, <sch:rule> and <sch:assert> or <sch:report>.
In a Schematron schema generated by the second mapping step, the
basic unit of organization is a rule represented by the <sch:rule>
element. The following NETMOD-specific annotations from the hybrid
schema (henceforth called "semantic annotations") are mapped to
corresponding Schematron rules: <nma:must>, @nma:key, @nma:unique,
@nma:max-elements, @nma:min-elements, @nma:when, @nma:leafref, @nma:
leaf-list, and also @nma:mandatory appearing as an attribute of <rng:
choice> (see Section 11.2.1).
Each input YANG module is mapped to a Schematron pattern whose @id
attribute is set to the module name. Every <rng:element> pattern
containing at least one of the above-mentioned semantic annotations
is then mapped to a Schematron rule:
<sch:rule context="XELEM">
...
</sch:rule>
The value of the mandatory @context attribute of <sch:rule> (denoted
as XELEM) MUST be set to the absolute path of the context element in
the data tree. The <sch:rule> element contains the mappings of all
contained semantic annotations in the form of Schematron asserts or
reports.
Semantic annotations appearing inside a named pattern definition
(i.e., having <rng:define> among its ancestors) require special
treatment because they may be potentially used in different contexts.
This is accomplished by using Schematron abstract patterns that use
the "$pref" variable in place of the local namespace prefix. The
value of the @id attribute of such an abstract pattern MUST be set to
the name of the named pattern definition which is being mapped (i.e.,
the mangled name of the original YANG grouping).
When the abstract pattern is instantiated, the values of the
following two parameters MUST be provided:
o pref: the actual namespace prefix,
o start: XPath expression defining the context in which the grouping
is used.
EXAMPLE. Consider the following YANG module:
module example4 {
namespace "http://example.com/ns/example4";
prefix ex4;
uses sorted-leaf-list;
grouping sorted-leaf-list {
leaf-list sorted-entry {
must "not(preceding-sibling::sorted-entry > .)" {
error-message "Entries must appear in ascending order.";
}
type uint8;
}
}
}
The resulting Schematron schema for a reply to <nc:get> is then as
follows:
<?xml version="1.0" encoding="utf-8"?>
<sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron">
<sch:ns uri="http://example.com/ns/example4" prefix="ex4"/>
<sch:ns uri="urn:ietf:params:xml:ns:netconf:base:1.0"
prefix="nc"/>
<sch:pattern abstract="true"
id="_example4__sorted-leaf-list">
<sch:rule context="$start/$pref:sorted-entry">
<sch:report
test=". = preceding-sibling::$pref:sorted-entry">
Duplicate leaf-list entry "<sch:value-of select="."/>".
</sch:report>
<sch:assert
test="not(preceding-sibling::$pref:sorted-entry &gt; .)">
Entries must appear in ascending order.
</sch:assert>
</sch:rule>
</sch:pattern>
<sch:pattern id="example4"/>
<sch:pattern id="id2573371" is-a="_example4__sorted-leaf-list">
<sch:param name="start" value="/nc:rpc-reply/nc:data"/>
<sch:param name="pref" value="ex4"/>
</sch:pattern>
</sch:schema>
The "sorted-leaf-list" grouping from the input module is mapped to an
abstract pattern with an @id value of "_example4__sorted-leaf-list"
in which the 'must' statement corresponds to the <sch:assert>
element. The abstract pattern is the instantiated by the pattern
with an @id value of "id2802112" which sets the "start" and "pref"
parameters to appropriate values.
Note that another Schematron element, <sch:report>, was automatically
added, checking for duplicate leaf-list entries.
The mapping from the hybrid schema to Schematron proceeds in the
following steps:
1. First, the active subtree(s) of the hybrid schema must be
selected depending on the requested target document type. This
procedure is identical to the RELAX NG case, including the
handling of @nma:config if the target document type is <nc:get-
config> reply.
2. Namespaces of all input YANG modules, together with the
namespaces of base NETCONF ("nc" prefix) or notifications ("en"
prefix) MUST be declared using the <sch:ns> element, for example
<sch:ns uri="http://example.com/ns/example4" prefix="ex4"/>
3. One pattern is created for every input module. In addition, an
abstract pattern is created for every named pattern definition
containing one or more semantic annotations.
4. A <sch:rule> element is created for each element pattern
containing semantic annotations.
5. Every such annotation is then mapped to an <sch:assert> or <sch:
report> element which is installed as a child of the <sch:rule>
element.
11.2.1. Constraints on Mandatory Choice
In order to fully represent the semantics of YANG's 'choice'
statement with the "mandatory true;" substatement, the RELAX NG
grammar has to be combined with a special Schematron rule.
EXAMPLE. Consider the following module:
module example5 {
namespace "http://example.com/ns/example5";
prefix ex5;
choice foobar {
mandatory true;
case foo {
leaf foo1 {
type uint8;
}
leaf foo2 {
type uint8;
}
}
leaf bar {
type uint8;
}
}
}
In this module, all three leaf nodes in both case branches are
optional but because of the "mandatory true;" statement, at least one
of them must be present in a valid configuration. The 'choice'
statement from this module is mapped to the following fragment of the
RELAX NG schema:
<rng:choice>
<rng:interleave>
<rng:optional>
<rng:element name="ex5:foo1">
<rng:data type="unsignedByte"/>
</rng:element>
</rng:optional>
<rng:optional>
<rng:element name="ex5:foo2">
<rng:data type="unsignedByte"/>
</rng:element>
</rng:optional>
</rng:interleave>
<rng:element name="ex5:bar">
<rng:data type="unsignedByte"/>
</rng:element>
</rng:choice>
In the second case branch, the "ex5: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 of them alone suffices for a valid configuration. As a result,
the above RELAX NG fragment would successfully validate
configurations where none of the three leaf elements are present.
Therefore, mandatory choices, which can be recognized in the hybrid
schema as <rng:choice> elements with the @nma:mandatory annotation,
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 Schematron
rule MUST be added enforcing the presence of at least one element
from any of the cases. (RELAX NG schema guarantees that elements
from different cases cannot be mixed together, that all mandatory
nodes are present etc.).
For the example module above, the Schematron rule will be as follows:
<sch:rule context="/nc:rpc-reply/nc:data">
<sch:assert test="ex5:foo1 or ex5:foo2 or ex5:bar">
Node(s) from at least one case of choice "foobar" must exist.
</sch:assert>
</sch:rule>
11.3. Mapping Default Values to DSRL
DSRL is the only component of DSDL which is allowed to change the
information set of the validated XML document. While DSRL also has
other functions, YANG-to-DSDL mapping uses it only for specifying and
applying default contents. For XML instance documents based on YANG
data models, insertion of default contents may potentially take place
for all implicit nodes identified by the rules in Section 9.1.2.
In DSRL, the default contents of an element are specified using the
<dsrl:default-content> element, which is a child of <dsrl:element-
map>. Two sibling elements of <dsrl:default-content> determine the
context for the application of the default contents, see [DSRL]:
o <dsrl:parent> element contains an XSLT pattern specifying the
parent element; the default contents are applied only if the
parent element exists in the instance document.
o <dsrl:name> contains the XML name of the element which, if missing
or empty, is inserted together with the contents 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 a proper application of default
contents.
DSRL mapping only deals with <rng:element> patterns in the hybrid
schema that define implicit nodes (see Section 9.1.2). Such element
patterns are distinguished by having NETMOD-specific annotation
attributes @nma:default or @nma:implicit, i.e., either
<rng:element name="ELEM" nma:default="DEFVALUE">
...
</rng:element>
or
<rng:element name="ELEM" nma:implicit="true">
...
</rng:element>
The former case applies to leaf nodes having the 'default'
substatement, but also to leaf nodes that obtain their default value
from a typedef, if this typedef is expanded according to the rules in
Section 9.2.2 so that the @nma:default annotation is attached
directly to the leaf's element pattern.
The latter case is used for all implicit containers (see Section 9.1)
and for leafs that obtain the default value from a typedef and don't
have the @nma:default annotation.
In the simplest case, both element patterns are mapped to the
following DSRL element map:
<dsrl:element-map>
<dsrl:parent>XPARENT</dsrl:parent>
<dsrl:name>ELEM</dsrl:name>
<dsrl:default-content>DEFCONT</dsrl:default-content>
</dsrl:element-map>
where XPARENT is the absolute XPath of ELEM's parent element in the
data tree and DEFCONT is constructed as follows:
o If the implicit node ELEM is a leaf and has the @nma:default
attribute, DEFCONT is set to the value of this attribute (denoted
above as DEFVALUE).
o If the implicit node ELEM is a leaf and has the @nma:implicit
attribute with the value of "true", the default value has to be
determined from the @nma:default attribute of the definition of
ELEM's type (perhaps recursively) and used in place of DEFCONT in
the above DSRL element map. See also Section 9.2.2.
o Otherwise, the implicit node ELEM is a container and DEFCONT is
constructed as an XML fragment containing all descendant elements
of ELEM that have either @nma:implicit or @nma:default attribute.
In addition, when mapping the default case of a choice, it has to be
guaranteed that the default contents are not applied if any node from
any non-default case is present. This is accomplished by setting
<dsrl:parent> in a special way:
<dsrl:parent>XPARENT[not (ELEM1|ELEM2|...|ELEMn)]</dsrl:parent>
where ELEM1, ELEM2, ... ELEMn are the names of all top-level nodes
from all non-default cases. The rest of the element map is exactly
as before.
EXAMPLE. Consider the following YANG module:
module example6 {
namespace "http://example.com/ns/example6";
prefix ex6;
container outer {
leaf leaf1 {
type uint8;
default 1;
}
choice one-or-two {
default "one";
container one {
leaf leaf2 {
type uint8;
default 2;
}
}
leaf leaf3 {
type uint8;
default 3;
}
}
}
}
The DSRL schema generated for the "get-reply" target document type
will be:
<?xml version="1.0" encoding="utf-8"?>
<dsrl:maps xmlns:dsrl="http://purl.oclc.org/dsdl/dsrl"
xmlns:ex6="http://example.com/ns/example6"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<dsrl:element-map>
<dsrl:parent>/nc:rpc-reply/nc:data</dsrl:parent>
<dsrl:name>ex6:outer</dsrl:name>
<dsrl:default-content>
<ex6:leaf1>1</ex6:leaf1>
<ex6:one><ex6:leaf2>2</ex6:leaf2></ex6:one>
<?xml version="1.0" encoding="utf-8"?>
<dsrl:maps xmlns:dsrl="http://purl.oclc.org/dsdl/dsrl"
xmlns:ex6="http://example.com/ns/example6"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<dsrl:element-map>
<dsrl:parent>/nc:rpc-reply/nc:data</dsrl:parent>
<dsrl:name>ex6:outer</dsrl:name>
<dsrl:default-content>
<ex6:leaf1>1</ex6:leaf1>
<ex6:one>
<ex6:leaf2>2</ex6:leaf2>
</ex6:one>
</dsrl:default-content>
</dsrl:element-map>
<dsrl:element-map>
<dsrl:parent>/nc:rpc-reply/nc:data/ex6:outer</dsrl:parent>
<dsrl:name>ex6:leaf1</dsrl:name>
<dsrl:default-content>1</dsrl:default-content>
</dsrl:element-map>
<dsrl:element-map>
<dsrl:parent>
/nc:rpc-reply/nc:data/ex6:outer[not(ex6:leaf3)]
</dsrl:parent>
<dsrl:name>ex6:one</dsrl:name>
<dsrl:default-content>
<ex6:leaf2>2</ex6:leaf2>
</dsrl:default-content>
</dsrl:element-map>
<dsrl:element-map>
<dsrl:parent>
/nc:rpc-reply/nc:data/ex6:outer/ex6:one
</dsrl:parent>
<dsrl:name>ex6:leaf2</dsrl:name>
<dsrl:default-content>2</dsrl:default-content>
</dsrl:element-map>
</dsrl:maps>
Note that the default value for "leaf3" defined in the YANG module is
ignored because "leaf3" represents a non-default alternative of a
choice and as such never becomes an implicit element.
12. Mapping NETMOD-specific Annotations to DSDL Schema Languages
This section contains the mapping specification for the individual
NETMOD-specific annotations. In each case, the result of the mapping
must be inserted into an appropriate context of the target DSDL
schema as described in Section 11. The context is determined by the
element pattern in the hybrid schema to which the annotation is
attached. In the rest of this section, we will denote CONTELEM the 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.
of the "standard" pattern and therefore active in both validation
phases.
12.1. The @nma:config Annotation 12.1. The @nma:config Annotation
If this annotation is present with the value "false", the following If this annotation is present with the value of "false", the
rules MUST be observed for DSDL schemas of <nc:get-config> reply: following rules MUST be observed for DSDL schemas of <nc:get-config>
reply:
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 hybrid schema MUST be ignored.
12.2. The @nma:default Annotation 12.2. The @nma:default Annotation
This annotation is used for generating the DSRL schema as described This annotation is used for generating the DSRL schema as described
in Section 10.4. in Section 11.3.
12.3. The @nma:implicit Annotation 12.3. The <nma:error-app-tag> Annotation
This annotation is used for generating the DSRL schema as described This annotation currently has no mapping defined.
in Section 10.4.
12.4. The <nma:error-app-tag> Annotation 12.4. The <nma:error-message> Annotation
This annotation currently has no mapping defined. This annotation is handled within <nma:must>, see Section 12.13.
12.5. The <nma:error-message> Annotation 12.5. The @if-feature Annotation
This annotation is handled within <nma:must>, see Section 12.11. The information about available features MAY be supplied as an input
parameter to an implementation. In this case, the following changes
MUST be performed for all features that are considered unavailable:
12.6. The <nma:instance-identifier> Annotation o When generating RELAX NG, the contents of the CONTELEM definition
MUST be changed to <rng:notAllowed>.
o When generating Schematron or DSRL, the CONTELEM definition and
all its descendants in the hybrid schema MUST be ignored.
12.6. The @nma:implicit Annotation
This annotation is used for generating the DSRL schema as described
in Section 11.3.
12.7. The <nma:instance-identifier> Annotation
If this annotation element has the @require-instance attribute with If this annotation element has the @require-instance attribute with
the value "false", it is ignored. Otherwise it is mapped to the the value of "false", it is ignored. Otherwise it is mapped to the
following Schematron assert: following Schematron assert:
<sch:assert test="nmf:evaluate(.)"> <sch:assert test="nmf:evaluate(.)">
The element pointed to by "CONTELEM" must exist. The element pointed to by "CONTELEM" must exist.
</sch:assert> </sch:assert>
The nmf:evaluate() function is an XSLT extension function (see The nmf:evaluate() function is an XSLT extension function (see
Extension Functions in [XSLT]) that evaluates an XPath expression at Extension Functions in [XSLT]) that evaluates an XPath expression at
runtime. Such an extension function is provided by some XSLT run time. Such an extension function is provided by some XSLT
processors, for example Saxon [3]. processors, for example Saxon [3].
12.7. The @nma:key Annotation 12.8. The @nma:key Annotation
Assume this annotation attribute has the value "k_1 k_2 ... k_n", Assume this annotation attribute contains "k_1 k_2 ... k_n", i.e.,
i.e., specifies n children of CONTELEM as list keys. The annotation specifies n children of CONTELEM as list keys. The annotation is
is then mapped to the following Schematron report: then mapped to 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>
where CONDITION has this form: where CONDITION has this form:
preceding-sibling::CONTELEM[C_1 and C_2 and ... and C_n] preceding-sibling::CONTELEM[C_1 and C_2 and ... and C_n]
Each sub-expression C_i, for i=1,2,...,n, specifies the condition for Each sub-expression C_i, for i=1,2,...,n, specifies the condition for
violation of uniqueness of key k_i, namely violated uniqueness of the key k_i, namely
k_i=current()/k_i k_i=current()/k_i
12.8. The @nma:leafref Annotation 12.9. The @nma:leaf-list Annotation
This annotation is mapped to the following Schematron rule which
detects duplicate entries of a leaf-list:
<sch:report
test=". = preceding-sibling::PREFIX:sorted-entry">
Duplicate leaf-list entry "<sch:value-of select="."/>".
</sch:report>
See Section 11.2 for a complete example.
12.10. The @nma:leafref Annotation
This annotation is mapped to the following assert: This annotation is mapped to the following assert:
<sch:assert test="PATH=."> <sch:assert test="PATH=.">
Leafref "CONTELEM" must have the same value as "PATH" Leaf "PATH" does not exist for leafref value "VALUE"
</sch:assert> </sch:assert>
where PATH is the value of @nma:leafref. The assert is a descendant where PATH is the value of @nma:leafref and VALUE is the value of the
of the "ref-integrity" pattern, which means that it will be used only context element in the instance document for which the referred leaf
for the "full" validation phase. doesn't exist.
12.9. The @nma:min-elements Annotation 12.11. The @nma:min-elements Annotation
This annotation is mapped to the following Schematron assert: This annotation is mapped to the following Schematron assert:
<sch:assert test="count(../CONTELEM)&gt;=MIN"> <sch:assert test="count(../CONTELEM)&gt;=MIN">
List "CONTELEM" - item count must be at least MIN List "CONTELEM" - item count must be at least MIN
</sch:assert> </sch:assert>
where MIN is the value of @nma:min-elements. where MIN is the value of @nma:min-elements.
12.10. The @nma:max-elements Annotation 12.12. The @nma:max-elements Annotation
This annotation is mapped to the following Schematron assert: This annotation is mapped to the following Schematron assert:
<sch:assert test="count(../CONTELEM)&lt;=MAX"> <sch:assert
List "CONTELEM" - item count must be at most MAX test="count(../CONTELEM)&lt;=MAX or preceding-sibling::../CONTELEM">
</sch:assert> Number of list items must be at most MAX
</sch:assert>
where MAX is the value of @nma:min-elements. where MAX is the value of @nma:min-elements.
12.11. The <nma:must> Annotation 12.13. The <nma:must> Annotation
This annotation is mapped to the following Schematron assert: This annotation is mapped to the following Schematron assert:
<sch:assert test="EXPRESSION"> <sch:assert test="EXPRESSION">
MESSAGE MESSAGE
</sch:assert> </sch:assert>
where EXPRESSION is the value of the mandatory @assert attribute of where EXPRESSION is the value of the mandatory @assert attribute of
<nma:must>. If the <nma:error-message> subelement exists, MESSAGE is <nma:must>. If the <nma:error-message> subelement exists, MESSAGE is
set to its content, otherwise it is set to the default message set to its contents, otherwise it is set to the default message
"Condition EXPRESSION must be true". "Condition EXPRESSION must be true".
12.12. The <nma:ordered-by> Annotation 12.14. The <nma:ordered-by> Annotation
This annotation currently has no mapping defined. This annotation currently has no mapping defined.
12.13. The <nma:status> Annotation 12.15. The <nma:status> Annotation
This annotation currently has no mapping defined. This annotation currently has no mapping defined.
12.14. The @nma:unique Annotation 12.16. The @nma:unique Annotation
The mapping of this annotation is almost identical as for @nma:key, The mapping of this annotation is almost identical as for @nma:key,
see Section 12.7, with two small differences: see Section 12.8, with two small differences:
o The value of @nma:unique is a list of descendant schema node o The value of @nma:unique is a list of descendant schema node
identifiers rather than simple leaf names. However, the XPath identifiers rather than simple leaf names. However, the XPath
expressions specified in Section 12.7 work without any expressions specified in Section 12.8 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".
12.15. The @nma:when Annotation 12.17. The @nma:when Annotation
This annotation is mapped to the following Schematron assert: This annotation is mapped to the following Schematron assert:
<sch:assert test="EXPRESSION"> <sch:assert test="EXPRESSION">
Node "CONTELEM" is only valid when "EXPRESSION" is true. Node "CONTELEM" is only valid when "EXPRESSION" is true.
</sch:assert> </sch:assert>
where EXPRESSION is the value of @nma:when. where EXPRESSION is the value of @nma:when.
13. IANA Considerations 13. IANA Considerations
This document registers three namespace URIs in the IETF XML registry This document registers three namespace URIs in the IETF XML registry
[RFC3688]: [RFC3688]:
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:xpath-extensions:1 URI: urn:ietf:params:xml:ns:netmod:xpath-extensions:1
14. Security Considerations 14. Security Considerations
This document defines a procedure that maps data models expressed in This document defines a procedure that maps data models expressed in
the YANG language to a coordinated set of DSDL schemas. The the YANG language to a coordinated set of DSDL schemas. The
procedure itself has no security impact on the Internet. procedure itself has no security impact on the Internet.
DSDL schemas obtained by the mapping procedure may be used for DSDL schemas obtained by the mapping procedure may be used for
validating the content of NETCONF protocol data units or entire validating the contents of NETCONF messages or entire datastores and
datastores and thus provide additional validity checks above those thus provide additional validity checks above those performed by
performed by NETCONF server and client implementations supporting NETCONF server and client implementations supporting YANG data
YANG data models. The strictness of this validation is directly models. The strictness of this validation is directly derived from
derived from the source YANG modules that the validated XML data the source YANG modules that the validated XML data adhere to.
adhere to.
15. Acknowledgments 15. Acknowledgments
The authors wish to thank the following individuals who provided The authors wish to thank the following individuals who provided
helpful suggestions and/or comments on various versions of this helpful suggestions and/or comments on various versions of this
document: Andy Bierman, Martin Bjorklund, Jirka Kosek and Phil document: Andy Bierman, Martin Bjorklund, Jirka Kosek and Phil
Shafer. Shafer.
16. References 16. References
16.1. Normative References 16.1. Normative References
[DSDL] ISO/IEC, "Document Schema Definition Languages (DSDL) - [DSDL] ISO/IEC, "Document Schema Definition Languages (DSDL) -
Part 1: Overview", ISO/IEC 19757-1, 11 2004. Part 1: Overview", ISO/IEC 19757-1, 11 2004.
[DSRL] ISO/IEC, "Information Technology - Document Schema [DSRL] ISO/IEC, "Information Technology - Document Schema
Definition Languages (DSDL) - Part 8: Document Semantics Definition Languages (DSDL) - Part 8: Document Semantics
Renaming Language - DSRL", ISO/IEC 19757-8:2008(E), Renaming Language - DSRL", ISO/IEC 19757-8:2008(E),
12 2008. 12 2008.
[NVDL] ISO/IEC, "Information Technology - Document Schema
Definition Languages (DSDL) - Part 4: Namespace-Based
Validation Dispatching Language (NVDL)", ISO/
IEC 19757-4:2006(E), 6 2006.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004. January 2004.
[RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741,
December 2006. December 2006.
[RFC5013] Kunze, J., "The Dublin Core Metadata Element Set", [RFC5013] Kunze, J., "The Dublin Core Metadata Element Set",
skipping to change at page 83, line 11 skipping to change at page 83, line 5
ISO/IEC, "Information Technology - Document Schema ISO/IEC, "Information Technology - Document Schema
Definition Languages (DSDL) - Part 3: Rule-Based Definition Languages (DSDL) - Part 3: Rule-Based
Validation - Schematron", ISO/IEC 19757-3:2006(E), 6 2006. Validation - Schematron", ISO/IEC 19757-3:2006(E), 6 2006.
[XML] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and [XML] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and
F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth
Edition)", World Wide Web Consortium Recommendation REC- Edition)", World Wide Web Consortium Recommendation REC-
xml-20081126, November 2008, xml-20081126, November 2008,
<http://www.w3.org/TR/2006/REC-xml-20060816>. <http://www.w3.org/TR/2006/REC-xml-20060816>.
[XML-INFOSET]
Tobin, R. and J. Cowan, "XML Information Set (Second
Edition)", World Wide Web Consortium Recommendation REC-
xml-infoset-20040204, February 2004,
<http://www.w3.org/TR/2004/REC-xml-infoset-20040204>.
[XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) [XPath] Clark, J. and S. DeRose, "XML Path Language (XPath)
Version 1.0", World Wide Web Consortium Version 1.0", World Wide Web Consortium
Recommendation REC-xpath-19991116, November 1999, Recommendation REC-xpath-19991116, November 1999,
<http://www.w3.org/TR/1999/REC-xpath-19991116>. <http://www.w3.org/TR/1999/REC-xpath-19991116>.
[XSD-D] Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes [XSD-D] Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes
Second Edition", World Wide Web Consortium Second Edition", World Wide Web Consortium
Recommendation REC-xmlschema-2-20041028, October 2004, Recommendation REC-xmlschema-2-20041028, October 2004,
<http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>. <http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.
[XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World [XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World
Wide Web Consortium Recommendation REC-xslt-19991116, Wide Web Consortium Recommendation REC-xslt-19991116,
November 1999. November 1999.
[YANG] Bjorklund, M., Ed., "YANG - A data modeling language for [YANG] Bjorklund, M., Ed., "YANG - A data modeling language for
NETCONF", draft-ietf-netmod-yang-11 (work in progress), NETCONF", draft-ietf-netmod-yang-13 (work in progress),
Febuary 2010. June 2010.
[Ytypes] Schoenwaelder, J., Ed., "Common YANG Data Types", [Ytypes] Schoenwaelder, J., Ed., "Common YANG Data Types",
draft-ietf-netmod-yang-types-07 (work in progress), draft-ietf-netmod-yang-types-09 (work in progress),
February 2010. April 2010.
16.2. Informative References 16.2. Informative References
[RFC1157] Case, J., Fedor, M., Schoffstall, M., and J. Davin, [RFC1157] Case, J., Fedor, M., Schoffstall, M., and J. Davin,
"Simple Network Management Protocol (SNMP)", STD 15, "Simple Network Management Protocol (SNMP)", STD 15,
RFC 1157, May 1990. RFC 1157, May 1990.
[RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J.
Schoenwaelder, Ed., "Structure of Management Information Schoenwaelder, Ed., "Structure of Management Information
Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. Version 2 (SMIv2)", STD 58, RFC 2578, April 1999.
skipping to change at page 85, line 17 skipping to change at page 86, line 5
[1] <http://www.thaiopensource.com/relaxng/trang.html> [1] <http://www.thaiopensource.com/relaxng/trang.html>
[2] <http://dublincore.org/> [2] <http://dublincore.org/>
[3] <http://www.saxonica.com/> [3] <http://www.saxonica.com/>
[4] <http://www.yang-central.org/twiki/bin/view/Main/DhcpTutorial> [4] <http://www.yang-central.org/twiki/bin/view/Main/DhcpTutorial>
[5] <http://code.google.com/p/pyang/> [5] <http://code.google.com/p/pyang/>
[6] <http://thaiopensource.com/relaxng/trang.html> Appendix A. RELAX NG Schema for NETMOD-Specific Annotations
Appendix A. Schemas for NETMOD-Specific Annotations
This appendix utilizes Namespace-Based Validation Dispatching
Language (NVDL, Part 4 of DSDL) [NVDL] to define NETMOD-specific
annotations as extensions of the RELAX NG language. The NVDL schema
may be used for validating conceptual tree schemas as compound XML
documents consisting of RELAX NG sections and embedded sections with
NETMOD-specific annotations. The NVDL schema dispatches the
validation as follows:
1. RELAX NG sections identified by the namespace URI
"http://relaxng.org/ns/structure/1.0" is validated with the
standard RELAX NG schema for RELAX NG, see [RNG], Annex A.
2. NETMOD-specific annotation sections identified by the namespace
URI "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1" are
validated by several context-dependent RELAX NG schemas given
below.
3. Other sections such as Dublin Core metadata or <a:documentation>
annotation are attached to and validated together with the parent
RELAX NG section.
A.1. NVDL Schema
<CODE BEGINS> file "nmannot.nvdl"
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE nvdl:rules [<!ENTITY nmannot-uri
"urn:ietf:params:xml:ns:netmod:dsdl-annotations:1">
]>
<rules xmlns="http://purl.oclc.org/dsdl/nvdl/ns/structure/1.0"
startMode="rng">
<mode name="rng">
<namespace ns="http://relaxng.org/ns/structure/1.0">
<validate schema="http://relaxng.org/relaxng.rng"
useMode="other">
<context path="define" useMode="define"/>
<context path="oneOrMore/element" useMode="list"/>
<context path="element" useMode="element"/>
<context path="choice/group|choice/interleave"
useMode="group-interleave"/>
<context path="choice|ref" useMode="choice-ref"/>
<context path="value" useMode="value"/>
</validate>
</namespace>
</mode>
<mode name="define">
<namespace ns="&nmannot-uri;" match="attributes">
<validate schema="define.rng"/>
</namespace>
</mode>
<mode name="element">
<namespace ns="&nmannot-uri;" match="elements">
<validate schema="element-el.rng"/>
</namespace>
<namespace ns="&nmannot-uri;" match="attributes">
<validate schema="element-att.rng"/>
</namespace>