RFC 6110

Mapping YANG to Document Schema Definition Languages and Validating NETCONF Content

📅 published February 2011, from ietf

RFC 6110 📜💖 Mapping YANG to Document Schema Definition Languages and Validating NETCONF Content

okay bestie, RFC 6110 is giving data modelling meets XML validation 🎀✨. It's from the IETF, it's a Standards Track document (so it's the real deal, not just an idea), written by L. Lhotka, Ed. from CESNET, and it was published in February 2011 🌸. Its ISSN is 2070-1721. The title block doesn't list any document that it obsoletes or updates, so it doesn't replace or change anything else 🧚.

Abstract ✨

okay so the abstract says this doc lays out the rules for turning YANG data models into DSDL (Document Schema Definition Languages) 💅. DSDL is a set of XML schema languages that's standardized as ISO/IEC 19757, and it's a coordinated family, so they all work together 🦋. The three DSDL languages covered are RELAX NG (Regular Language for XML Next Generation), Schematron, and DSRL (Schematron and Document Schema Renaming Language) 🔥.

The mapping takes one or more YANG modules and spits out a set of DSDL schemas for whichever target document type you pick, like datastore content, Network Configuration Protocol (NETCONF) messages, and so on 💜. The abstract also says the doc talks about how to do schema-based validation on those kinds of documents, which is the part where you actually check that everything is valid 🙈.

Status of This Memo 🌈

so this section is basically the doc's ID card 🪪. It's an Internet Standards Track document, and it's a product of the Internet Engineering Task Force (IETF) 🫶. It represents the consensus of the IETF community, it went through public review, and the Internet Engineering Steering Group (IESG) approved it for publication 👑. If you want more on Internet Standards, check out Section 2 of RFC 5741 ⭐.

For the current status, any errata, or to send feedback, go to http://www.rfc-editor.org/info/rfc6110 💌.

Copyright Notice 💅

the copyright is (c) 2011 IETF Trust and the persons identified as the document authors, and all rights are reserved 🎀. This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info), as they stand on the date this doc was published 🧚. Read those carefully, bestie, because they describe your rights and restrictions for this doc 😭.

One more important bit: any Code Components pulled out of this document must include the Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without any warranty, as the Simplified BSD License describes 🦋.

🎀 part 1 of 18 done, bestie!! more parts are coming, so stay tuned and get ready for the YANG-to-DSDL mapping rules next 🫶💖

Table of Contents ✨

okay bestie, here's the map of the whole doc 🗺️💖 every section number stays exactly the same so the cross-refs still work 🫶

   1. Introduction ....................................................5
   2. Terminology and Notation ........................................6
      2.1. Glossary of New Terms ......................................9
   3. Objectives and Motivation ......................................10
   4. DSDL Schema Languages ..........................................11
      4.1. RELAX NG ..................................................11
      4.2. Schematron ................................................12
      4.3. Document Semantics Renaming Language (DSRL) ...............13
   5. Additional Annotations .........................................14
      5.1. Dublin Core Metadata Elements .............................14
      5.2. RELAX NG DTD Compatibility Annotations ....................14
      5.3. NETMOD-Specific Annotations ...............................15
   6. Overview of the Mapping ........................................16
   7. NETCONF Content Validation .....................................18
   8. Design Considerations ..........................................19
      8.1. Hybrid Schema .............................................19
      8.2. Modularity ................................................22
      8.3. Granularity ...............................................23
      8.4. Handling of XML Namespaces ................................24
   9. Mapping YANG Data Models to the Hybrid Schema ..................25
      9.1. Occurrence Rules for Data Nodes ...........................25
           9.1.1. Optional and Mandatory Nodes .......................26
           9.1.2. Implicit Nodes .....................................27
      9.2. Mapping YANG Groupings and Typedefs .......................28
           9.2.1. YANG Refinements and Augments ......................29
           9.2.2. Type Derivation Chains .............................32
      9.3. Translation of XPath Expressions ..........................35
      9.4. YANG Language Extensions ..................................36
   10. Mapping YANG Statements to the Hybrid Schema ..................37
      10.1. The 'anyxml' Statement ...................................37
      10.2. The 'argument' Statement .................................38
      10.3. The 'augment' Statement ..................................39
      10.4. The 'base' Statement .....................................39
      10.5. The 'belongs-to' Statement ...............................39
      10.6. The 'bit' Statement ......................................39
      10.7. The 'case' Statement .....................................39
      10.8. The 'choice' Statement ...................................39
      10.9. The 'config' Statement ...................................40
      10.10. The 'contact' Statement .................................40
      10.11. The 'container' Statement ...............................40
      10.12. The 'default' Statement .................................40
      10.13. The 'description' Statement .............................42
      10.14. The 'deviation' Statement ...............................42
      10.15. The 'enum' Statement ....................................42
      10.16. The 'error-app-tag' Statement ...........................42
      10.17. The 'error-message' Statement ...........................42
      10.18. The 'extension' Statement ...............................43
      10.19. The 'feature' Statement .................................43
      10.20. The 'grouping' Statement ................................43
      10.21. The 'identity' Statement ................................43
      10.22. The 'if-feature' Statement ..............................45
      10.23. The 'import' Statement ..................................45
      10.24. The 'include' Statement .................................45
      10.25. The 'input' Statement ...................................46
      10.26. The 'key' Statement .....................................46
      10.27. The 'leaf' Statement ....................................46
      10.28. The 'leaf-list' Statement ...............................46
      10.29. The 'length' Statement ..................................47
      10.30. The 'list' Statement ....................................47
      10.31. The 'mandatory' Statement ...............................48
      10.32. The 'max-elements' Statement ............................49
      10.33. The 'min-elements' Statement ............................49
      10.34. The 'module' Statement ..................................49
      10.35. The 'must' Statement ....................................49
      10.36. The 'namespace' Statement ...............................50
      10.37. The 'notification' Statement ............................50
      10.38. The 'ordered-by' Statement ..............................50
      10.39. The 'organization' Statement ............................50
      10.40. The 'output' Statement ..................................51
      10.41. The 'path' Statement ....................................51
      10.42. The 'pattern' Statement .................................51
      10.43. The 'position' Statement ................................51
      10.44. The 'prefix' Statement ..................................51
      10.45. The 'presence' Statement ................................51
      10.46. The 'range' Statement ...................................51
      10.47. The 'reference' Statement ...............................51
      10.48. The 'require-instance' Statement ........................51
      10.49. The 'revision' Statement ................................52
      10.50. The 'rpc' Statement .....................................52
      10.51. The 'status' Statement ..................................52
      10.52. The 'submodule' Statement ...............................52
      10.53. The 'type' Statement ....................................53
           10.53.1. The "empty" Type .................................54
           10.53.2. The "boolean" Type ...............................54
           10.53.3. The "binary" Type ................................54
           10.53.4. The "bits" Type ..................................54
           10.53.5. The "enumeration" and "union" Types ..............54
           10.53.6. The "identityref" Type ...........................54
           10.53.7. The "instance-identifier" Type ...................55
           10.53.8. The "leafref" Type ...............................55
           10.53.9. The Numeric Types ................................55
           10.53.10. The "string" Type ...............................57
           10.53.11. Derived Types ...................................58
      10.54. The 'typedef' Statement .................................59
      10.55. The 'unique' Statement ..................................59
      10.56. The 'units' Statement ...................................60
      10.57. The 'uses' Statement ....................................60
      10.58. The 'value' Statement ...................................60
      10.59. The 'when' Statement ....................................60
      10.60. The 'yang-version' Statement ............................60
      10.61. The 'yin-element' Statement .............................61
   11. Mapping the Hybrid Schema to DSDL .............................61
      11.1. Generating RELAX NG Schemas for Various Document Types ...61
      11.2. Mapping Semantic Constraints to Schematron ...............62
           11.2.1. Constraints on Mandatory Choice ...................65
      11.3. Mapping Default Values to DSRL ...........................67
   12. Mapping NETMOD-Specific Annotations to DSDL Schema Languages ..71
      12.1. The @nma:config Annotation ...............................71
      12.2. The @nma:default Annotation ..............................71
      12.3. The <nma:error-app-tag> Annotation .......................71
      12.4. The <nma:error-message> Annotation .......................71
      12.5. The @if-feature Annotation ...............................71
      12.6. The @nma:implicit Annotation .............................72
      12.7. The <nma:instance-identifier> Annotation .................72
      12.8. The @nma:key Annotation ..................................72
      12.9. The @nma:leaf-list Annotation ............................72
      12.10. The @nma:leafref Annotation .............................73
      12.11. The @nma:min-elements Annotation ........................73
      12.12. The @nma:max-elements Annotation ........................73
      12.13. The <nma:must> Annotation ...............................73
      12.14. The <nma:ordered-by> Annotation .........................74
      12.15. The <nma:status> Annotation .............................74
      12.16. The @nma:unique Annotation ..............................74
      12.17. The @nma:when Annotation ................................74
   13. IANA Considerations ...........................................75
   14. Security Considerations .......................................75
   15. Contributors ..................................................75
   16. Acknowledgments ...............................................76
   17. References ....................................................76
      17.1. Normative References .....................................76
      17.2. Informative References ...................................77
   Appendix A. RELAX NG Schema for NETMOD-Specific Annotations .......79
   Appendix B. Schema-Independent Library ............................84
   Appendix C. Mapping DHCP Data Model - A Complete Example ..........85
      C.1. Input YANG Module .........................................85
      C.2. Hybrid Schema .............................................88
      C.3. Final DSDL Schemas  .......................................93
           C.3.1. Main RELAX NG Schema for <nc:get> Reply ............93
           C.3.2. RELAX NG Schema - Global Named Pattern
                  Definitions ........................................95
           C.3.3. Schematron Schema for <nc:get> Reply ...............98
           C.3.4. DSRL Schema for <nc:get> Reply .....................99

1. Introduction ✨

okay so NETCONF already has a base protocol for config management, [RFC4741], and it's honestly solid 💖 It sets up the protocol bindings and an XML container syntax for config and management operations. What it does NOT do is give you a data modeling language, or any rules for how to model config and state info. 🙈

The IETF Operations Area has a long history of writing data for SNMP MIB modules [RFC1157] using the Structure of Management Information (SMI) language [RFC2578]. ngl, that modeling approach has some well-known problems, but most of SMI's data modeling features are still considered extremely important. The lesson from before: if you model just the valid syntax and skip the semantic relationships, you get significant interoperability problems. 💀

The NETCONF community agreed that a data modeling framework was needed to support ongoing development of IETF and vendor-defined management information modules. So the NETMOD Working Group got chartered to design a modeling language that defines the semantics of operational data, configuration data, event notifications, and operations. The big focus was "human-friendliness", meaning readability and ease of use 🎀 That became the YANG data modeling language [RFC6020], which now serves as the normative description of NETCONF data models. iconic.

Since NETCONF encodes its messages in XML, it makes total sense to express constraints on NETCONF content with standard XML schema languages. The NETMOD WG picked the Document Schema Definition Languages (DSDL), which are being standardized as ISO/ IEC 19757 [DSDL]. DSDL is a whole framework of XML schema languages covering grammar rules, semantic constraints, and other data modeling aspects. The really good part is that they all work together in a coordinated and consistent way 🦋 Some DSDL parts aren't standardized yet and are still a work in progress, but the three that the YANG-to-DSDL mapping relies on are already International Standards and are supported by a bunch of software tools: Regular Language for XML Next Generation (RELAX NG), Schematron, and Document Schema Renaming Language (DSRL) 💅

This document specifies a mapping that translates YANG data models into XML schemas, using a subset of the DSDL schema languages 🧚 The mapping happens in two steps. In the first step, the structure of the data tree, the signatures of remote procedure call (RPC) operations, and notifications get expressed as the so-called "hybrid schema". That's a single RELAX NG schema with annotations that carry extra data model info, like metadata, documentation, semantic constraints, default values, and so on 🌸 The second step then generates a coordinated set of DSDL schemas. Those can validate specific XML documents, like client requests, server responses, or notifications, and they can also take into account things like active capabilities or features. ✨

2. Terminology and Notation 🎀

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 🫶

The following terms are defined in [RFC4741]:

client
datastore
message
operation
server

The following terms are defined in [RFC6020]:

augment
base type
built-in type
configuration data
container
data model
data node
data tree
derived type
device deviation
extension
feature
grouping
instance identifier
leaf-list
list
mandatory node
module
RPC
RPC operation
schema node
schema tree
state data
submodule
top-level data node
uses

The following terms are defined in [XML-INFOSET]:

attribute
document
document element
document type declaration (DTD)
element
information set
namespace

In the text, these typographic conventions are used 💜

YANG statement keywords are delimited by single quotes.
XML element names are delimited by "<" and ">" characters.
Names of XML attributes are prefixed by the "@" character.
Other literal values are delimited by double quotes.

XML element names are always written with explicit namespace prefixes corresponding to the following XML vocabularies:

"a": DTD compatibility annotations [RNG-DTD]
"dc": Dublin Core metadata elements [RFC5013]
"dsrl": Document Semantics Renaming Language [DSRL]
"en": NETCONF event notifications [RFC5277]
"nc": NETCONF protocol [RFC4741]
"nma": NETMOD-specific schema annotations (see Section 5.3)
"nmf": NETMOD-specific XML Path Language (XPath) extension functions (see Section 12.7)
"rng": RELAX NG [RNG]
"sch": ISO Schematron [Schematron]
"xsd": W3C XML Schema [XSD]

Here's the mapping of these prefixes to namespace URIs 🍓

+--------+-----------------------------------------------------+
| Prefix | Namespace URI                                       |
+--------+-----------------------------------------------------+
| a      | http://relaxng.org/ns/compatibility/annotations/1.0 |
|        |                                                     |
| dc     | http://purl.org/dc/terms                            |
|        |                                                     |
| dsrl   | http://purl.oclc.org/dsdl/dsrl                      |
|        |                                                     |
| en     | urn:ietf:params:xml:ns:netconf:notification:1.0     |
|        |                                                     |
| nc     | urn:ietf:params:xml:ns:netconf:base:1.0             |
|        |                                                     |
| nma    | urn:ietf:params:xml:ns:netmod:dsdl-annotations:1    |
|        |                                                     |
| nmf    | urn:ietf:params:xml:ns:netmod:xpath-extensions:1    |
|        |                                                     |
| rng    | http://relaxng.org/ns/structure/1.0                 |
|        |                                                     |
| sch    | http://purl.oclc.org/dsdl/schematron                |
|        |                                                     |
| xsd    | http://www.w3.org/2001/XMLSchema                    |
+--------+-----------------------------------------------------+

          Table 1: Used namespace prefixes and corresponding URIs

2.1. Glossary of New Terms 🌈

ancestor data type: Any data type from which a given data type is (transitively) derived.
ancestor built-in data type: The built-in data type that is at the start of the type derivation chain for a given data type.
hybrid schema: A RELAX NG schema with annotations, which embodies the same information as the source YANG module(s). See Section 8.1 for details.
implicit node: A data node that, if it is not instantiated in a data tree, may be added to the information set of that data tree (configuration, RPC input or output, notification) without changing the semantics of the data tree.

3. Objectives and Motivation 💅

The main goal here is to complement YANG as a data modeling language with the validation capabilities of the DSDL schema languages, namely RELAX NG, Schematron, and DSRL. ✨ This document describes how grammatical, semantic, and data type constraints expressed in YANG correspond to equivalent DSDL patterns and rules. The ultimate goal is to capture all substantial information contained in YANG modules and express it in DSDL schemas. The mapping from YANG to DSDL described here may in principle be invertible, but the inverse mapping from DSDL to YANG is beyond the scope of this document 🙈

XML-based information models and XML-encoded data show up in several different forms across the various phases of YANG data modeling and the NETCONF workflow: configuration datastore contents, RPC requests and replies, and notifications. On top of that, RPC operations are characterized by an inherent diversity, because capabilities and features are selectively available. YANG modules can also define new RPC operations. The mapping should be able to handle this variability and generate schemas that are tailored to a particular situation, which makes them way more effective for validation than generic all-encompassing schemas 🦋

To deal with this variability, we assume the DSDL schemas will be generated on demand, for a particular purpose, from the available collection of YANG modules, and that their lifetime will be relatively short. In other words, we don't expect any collection of DSDL schemas to be created and maintained over a long period in parallel with the YANG modules. 🌸

The generated schemas are mainly meant to be input for existing XML schema validators and other off-the-shelf tools. But developers and users may also read the schemas as a formal representation of the constraints on a particular XML-encoded data object, so our secondary goal is to keep the schemas as readable as possible 🫶 To that end, the complexity of the mapping is split into two steps:

The first step maps one or more YANG modules to the so-called hybrid schema, which is a single RELAX NG schema that describes grammatical constraints for the main data tree as well as for RPC operations and notifications. Semantic constraints and other information in the input YANG modules get recorded in the hybrid schema as foreign namespace annotations. So the output of the first step can be considered a virtually complete equivalent of the input YANG modules. It can't, however, be directly used for any validation. 🧚
In the second step, the hybrid schema from step 1 is transformed further into a coordinated set of fully conformant DSDL schemas, containing constraints for a particular data object and a specific situation. The DSDL schemas are intended mainly for machine validation using off-the-shelf tools. 💖

4. DSDL Schema Languages 🌸

Document Schema Definition Languages (DSDL) is a framework of schema languages being developed as the International Standard ISO/ IEC 19757 [DSDL]. Unlike other approaches to XML document validation, most notably W3C XML Schema Definition (XSD) [XSD], the DSDL framework follows the principle of "small languages". Each DSDL constituent is a stand-alone schema language with a relatively narrow purpose and focus. Together, though, these schema languages can be used in a coordinated way to accomplish various validation tasks. 👑

The mapping described in this document uses three of the DSDL schema languages: RELAX NG [RNG], Schematron [Schematron], and DSRL [DSRL]. 🔥

4.1. RELAX NG 🎀

okay so RELAX NG (pronounced "relaxing" 🧘‍♀️) is an XML schema language for grammar-based validation, and it's Part 2 of the ISO/IEC DSDL family of standards [RNG] 💅. Like XSD, it can describe constraints on the structure and contents of XML documents. BUT unlike the DTD [XML] and XSD schema languages, RELAX NG intentionally avoids any infoset augmentation, like defining default values 🙈. That's not an oversight, it's a whole design choice! In the DSDL architecture, defining and applying default values is handed off to a different schema language, DSRL (see Section 4.3) 🦋.

As its base data type library, RELAX NG uses the W3C XML Schema Datatypes [XSD-D]. The difference from XSD is that other data type libraries can be used along with it, or even replace it if necessary 🌈.

RELAX NG is super liberal about annotations from other namespaces ✨. With a few exceptions, those annotations can go pretty much anywhere in the schema, and they don't need wrapper elements like <xsd:annotation> the way they do in XSD. no cap, that's so much less drama 💖.

RELAX NG schemas can be written in two equivalent syntaxes: XML and compact 🍓. The compact syntax is described in Annex C of the RELAX NG specification [RNG-CS], which was added to the standard in 2006 (Amendment 1). You can convert between the two automatically with several tools, for example Trang [Trang] 🔥.

Okay so the compact syntax is usually the fan favorite for publishing RELAX NG schemas because it's terse and readable 😭. Validators and other software tools, though, usually work with the XML syntax. The compact syntax has two drawbacks, though, and we need to talk about them bestie 👀:

External annotations make the compact syntax schema considerably less readable. In the XML syntax, annotating elements and attributes are represented in a simple, uniform way (XML elements and attributes from foreign namespaces). The compact syntax, meanwhile, uses as many as four different syntactic constructs: documentation, grammar, initial, and following annotations. So the impact of annotations on readability is often much stronger for the compact syntax than for the XML syntax 💀.
In a computer program, it's harder to generate the compact syntax than the XML syntax. There are a bunch of software libraries that make it easy to create an XML tree in memory and then serialize it, but no such aid exists for the compact syntax 😤.

So for these reasons, the mapping specification in this document uses exclusively the XML syntax 🫶. Where appropriate, though, the schemas resulting from the translation MAY be presented in the equivalent compact syntax ✨.

RELAX NG elements are qualified with the namespace URI http://relaxng.org/ns/structure/1.0. The namespace of the XSD data type library is http://www.w3.org/2001/XMLSchema-datatypes 🌸.

4.2. Schematron 🦋

Schematron is Part 3 of DSDL and reached the status of a full ISO/IEC standard in 2006 [Schematron] 💜. Here's the plot twist: traditional schema languages like DTD, XSD, or RELAX NG are based on the concept of a formal grammar, but Schematron goes rule-based instead 🧚. Its rules can specify arbitrary conditions involving data from different parts of an XML document, and each rule has three essential components:

context - an XPath expression that defines the set of locations where the rule is to be applied;
assert or report condition - another XPath expression that is evaluated relative to the location matched by the context expression;
human-readable message that is displayed when the assert condition is false or report condition is true.

The difference between assert and report is what makes them iconic 👑. An assert condition is positive: it states a condition that a valid document has to satisfy. A report condition, on the other hand, specifies an error condition 🙈.

Schematron gets most of its expressive power from XPath [XPath] and Extensible Stylesheet Language Transformations (XSLT) [XSLT] 💅. ISO Schematron allows dynamic query language binding, so the following XML query languages can be used: STX, XSLT 1.0, XSLT 1.1, EXSLT, XSLT 2.0, XPath 1.0, XPath 2.0, and XQuery 1.0 (this list may be extended in the future) 🌈.

Human-readable error messages are another feature that sets Schematron apart from other common schema languages 💖. The messages can even contain XPath expressions that get evaluated in the actual context, so they can refer to information items in the XML document being validated. Literally so helpful ✨.

Another feature of Schematron that the mapping uses is abstract patterns 🍓. These work essentially as macros, and they may also contain parameters that get supplied when the abstract pattern is used.

Schematron elements are qualified with namespace URI http://purl.oclc.org/dsdl/schematron ⭐.

4.3. Document Semantics Renaming Language (DSRL) 🌸

DSRL (pronounced "disrule") is Part 8 of DSDL and reached the status of a full ISO/IEC standard in 2008 [DSRL] 🔥. Unlike RELAX NG and Schematron, DSRL is allowed to modify the XML information set of the validated document. Main character energy 👑. While DSRL is primarily meant for renaming XML elements and attributes, it can also define default values for XML attributes and default contents for XML elements or subtrees, so the default contents get inserted if they're missing in the validated documents 🧚‍♀️. The YANG-to-DSDL mapping uses that last feature to represent YANG default contents, which consist of leaf nodes with default values and their ancestor non-presence containers 🫶.

DSRL elements are qualified with namespace URI http://purl.oclc.org/dsdl/dsrl 💜.

5. Additional Annotations ✨

Besides the DSDL schema languages, the mapping also uses three sets of annotations 🎀. These get added as foreign-namespace attributes and elements to RELAX NG schemas.

Two of the annotation sets, Dublin Core elements and DTD compatibility annotations, are standard vocabularies for representing metadata and documentation, respectively 🌈. Even though these data model items aren't used for formal validation, they quite often carry important information for data model implementers, so they SHOULD be included in the hybrid schema and MAY also appear in the final validation schemas 🦋.

The third set is NETMOD-specific annotations 💅. They're specifically designed for the hybrid schema and convey semantic constraints and other information that can't be expressed directly in RELAX NG. In the second mapping step, these annotations get converted to Schematron and DSRL rules 🔥.

5.1. Dublin Core Metadata Elements 📚

Dublin Core is a system of metadata elements that was originally created for describing metadata of World Wide Web resources, so they could be looked up automatically 🤓. Later it was accepted as a standard for describing metadata of arbitrary resources. This specification uses the definition from [RFC5013] 🍓.

Dublin Core elements are qualified with namespace URI http://purl.org/dc/terms ✨.

5.2. RELAX NG DTD Compatibility Annotations 🧁

DTD compatibility annotations are part of the RELAX NG DTD Compatibility specification [RNG-DTD] 💖. The YANG-to-DSDL mapping uses only the <a:documentation> annotation to represent YANG 'description' and 'reference' texts 🌸.

Note that there is no intention to make the resulting schemas DTD-compatible 🙅‍♀️. The main reason for using these annotations is technical: they're well supported and adequately formatted by several RELAX NG tools 🫶.

DTD compatibility annotations are qualified with namespace URI http://relaxng.org/ns/compatibility/annotations/1.0 💜.

5.3. NETMOD-Specific Annotations ✨

okay so bestie 🫶 NETMOD-specific annotations are XML elements and attributes that live in the namespace urn:ietf:params:xml:ns:netmod:dsdl-annotations:1, and they can pop up all over the hybrid schema 🦋 YANG statements get mapped to them in a super straightforward way. Most of the time the annotation attribute or element has the same name as the YANG statement it came from, so it's giving familiar vibes 💜

Table 2 is the full lineup 🌸 It lists, alphabetically, every NETMOD-specific annotation attribute (the ones with an @ in front) and element (the ones in angle brackets), plus the section where each one gets used. Appendix A has a RELAX NG schema for this whole annotation vocabulary 📚

      +---------------------------+--------------------+------+
      | annotation                | section            | note |
      +---------------------------+--------------------+------+
      | @nma:config               | 10.9               |      |
      |                           |                    |      |
      | <nma:data>                | 8.1                | 4    |
      |                           |                    |      |
      | @nma:default              | 10.12              |      |
      |                           |                    |      |
      | <nma:error-app-tag>       | 10.16              | 1    |
      |                           |                    |      |
      | <nma:error-message>       | 10.17              | 1    |
      |                           |                    |      |
      | @nma:if-feature           | 10.22              |      |
      |                           |                    |      |
      | @nma:implicit             | 10.11, 10.7, 10.12 |      |
      |                           |                    |      |
      | <nma:input>               | 8.1                | 4    |
      |                           |                    |      |
      | <nma:instance-identifier> | 10.53.7            | 2    |
      |                           |                    |      |
      | @nma:key                  | 10.26              |      |
      |                           |                    |      |
      | @nma:leaf-list            | 10.28              |      |
      |                           |                    |      |
      | @nma:leafref              | 10.53.8            |      |
      |                           |                    |      |
      | @nma:mandatory            | 10.8               |      |
      |                           |                    |      |
      | @nma:max-elements         | 10.28              |      |
      |                           |                    |      |
      | @nma:min-elements         | 10.28              |      |
      |                           |                    |      |
      | @nma:module               | 10.34              |      |
      |                           |                    |      |
      | <nma:must>                | 10.35              | 3    |
      |                           |                    |      |
      | <nma:notification>        | 8.1                | 4    |
      |                           |                    |      |
      | <nma:notifications>       | 8.1                | 4    |
      |                           |                    |      |
      | @nma:ordered-by           | 10.38              |      |
      | <nma:output>              | 8.1                | 4    |
      |                           |                    |      |
      | <nma:rpc>                 | 8.1                | 4    |
      |                           |                    |      |
      | <nma:rpcs>                | 8.1                | 4    |
      |                           |                    |      |
      | @nma:status               | 10.51              |      |
      |                           |                    |      |
      | @nma:unique               | 10.55              |      |
      |                           |                    |      |
      | @nma:units                | 10.56              |      |
      |                           |                    |      |
      | @nma:when                 | 10.59              |      |
      +---------------------------+--------------------+------+

Table 2: NETMOD-specific annotations

Notes:

Appears only as a subelement of <nma:must>.
Has an optional attribute @require-instance.
Has a mandatory attribute @assert and two optional subelements <nma:error-app-tag> and <nma:error-message>.
Marker element in the hybrid schema.

6. Overview of the Mapping 🗺️

this section gives you the big picture of the YANG-to-DSDL mapping, including what goes in and what comes out 💖 Figure 1 shows the overall structure:

                    +----------------+
                    | YANG module(s) |
                    +----------------+
                            |
                            |T
                            |
          +------------------------------------+
          |           hybrid schema            |
          +------------------------------------+
               /       |           |       \
              /        |           |        \
           Tg/       Tr|           |Tn       \
            /          |           |          \
      +---------+   +-----+    +-------+    +------+
      |get reply|   | rpc |    | notif |    | .... |
      +---------+   +-----+    +-------+    +------+

                    Figure 1: Structure of the mapping

The mapping procedure is split into two steps:

Transformation T in the first step maps one or more YANG modules to the hybrid schema (see Section 8.1). Constraints that cannot be expressed directly in RELAX NG (list key definitions, must statements, etc.) and various documentation texts are recorded in the schema as foreign-namespace annotations.
In the second step, the hybrid schema may be transformed in multiple ways to a coordinated set of DSDL schemas that can be used for validating a particular data object in a specific context. Figure 1 shows three simple possibilities as examples. In the process, appropriate parts of the hybrid schema are extracted and specific annotations transformed to equivalent, but usually more complex, Schematron patterns, DSRL element maps, etc.

An implementation of the mapping algorithm MUST accept one or more valid YANG modules as its input. It's really important to be able to process multiple YANG modules together, since multiple modules may be negotiated for a NETCONF session. The contents of the configuration datastore are then the union of the data trees specified by the individual modules, which may also lead to multiple root nodes of the datastore hierarchy 🌈 On top of that, the input modules may be coupled further by the augment statement, where one module augments the data tree of another module.

It's also assumed that the algorithm has access, perhaps on demand, to all YANG modules that the input modules import (directly or transitively) 🧚

Other information in the input YANG modules, like semantic constraints and default values, is recorded in the hybrid schema as annotations. These are XML attributes or elements qualified with the namespace URI urn:ietf:params:xml:ns:netmod:dsdl-annotations:1. Metadata describing the YANG modules is mapped to Dublin Core annotation elements (Section 5.1). Finally, documentation strings are mapped to <a:documentation> elements that belong to the DTD compatibility vocabulary (Section 5.2) 🎀

The output of the second step is a coordinated set of three DSDL schemas for a specific data object and context:

RELAX NG schema describing the grammatical and data type constraints;
Schematron schema expressing other constraints such as uniqueness of list keys or user-specified semantic rules;
DSRL schema containing the specification of default contents.

7. NETCONF Content Validation 💅

this section explains how the schemas generated by the YANG-to-DSDL mapping are supposed to be applied when validating XML instance documents, like the contents of a datastore or various NETCONF messages 🔥

The validation goes through the following steps, which are also illustrated in Figure 2:

The XML instance document is checked for grammatical and data type validity using the RELAX NG schema.
Default values for leaf nodes have to be applied, and their ancestor containers added where necessary. It's important to add the implicit nodes before the next validation step, because the YANG specification [RFC6020] requires that the data tree against which XPath expressions are evaluated already has all defaults filled in. Note that this step modifies the information set of the validated XML document 👑
The semantic constraints are checked using the Schematron schema.

      +----------+                        +----------+
      |          |                        |   XML    |
      |   XML    |                        | document |
      | document |-----------o----------->|   with   |
      |          |           ^            | defaults |
      |          |           |            |          |
      +----------+           |            +----------+
           ^                 | filling in       ^
           | grammar,        | defaults         | semantic
           | data types       |                  | constraints
           |                 |                  |
      +----------+       +--------+       +------------+
      | RELAX NG |       |  DSRL  |       | Schematron |
      |  schema  |       | schema |       |   schema   |
      +----------+       +--------+       +------------+

            Figure 2: Outline of the validation procedure

8. Design Considerations 🧠

YANG data models could, in principle, be mapped to the DSDL schemas in a number of ways 🌸 The mapping procedure described in this document uses several specific design decisions, which are discussed in the following subsections.

8.1. Hybrid Schema ✨

okay so, remember Section 6? The first step of the mapping makes this middle-man document called the hybrid schema 💖 It spells out every constraint for the entire data model, written in RELAX NG syntax with some extra annotations. But you can't validate with it directly, bestie 💀 It isn't even a valid RELAX NG schema, because it's secretly a bunch of schemas squished together and separated by special annotation elements.

Every input YANG module gets exactly one embedded grammar in the hybrid schema 🧚 That separation lets each embedded grammar tuck its named pattern definitions into its own namespace, which matters a lot for mapping YANG groupings (more deets in Section 9.2) 🎀

Beyond grammar and data type stuff, YANG modules carry info RELAX NG just can't express: semantic constraints, default values, metadata, documentation, and so on 📚 In the hybrid schema, these show up as XML attributes and elements in the namespace "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1". The full list is in Section 5.3, and the rules for using them come in the sections after that 🦋

YANG modules don't only define configuration and state data. They also define (multiple) RPC operations [RFC4741] and/or event notifications [RFC5277] 😭 So to fit all three kinds of data model into one schema document, the hybrid schema uses special markers that wrap sub-schemas for configuration and state data, individual RPC operations (both the input and output parts), and individual notifications 💅

The markers are these XML elements in the NETMOD-specific annotations namespace (URI urn:ietf:params:xml:ns:netmod:dsdl-annotations:1):

    +-------------------+---------------------------------------+
    | Element name      | Role                                  |
    +-------------------+---------------------------------------+
    | nma:data          | encloses configuration and state data |
    |                   |                                       |
    | nma:rpcs          | encloses all RPC operations           |
    |                   |                                       |
    | 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   |
    +-------------------+---------------------------------------+

            Table 3: Marker elements in the hybrid schema

For example, picture a data model made of two YANG modules, "example-a" and "example-b", which define nodes in the namespaces "http://example.com/ns/example-a" and "http://example.com/ns/example-b". Module "example-a" defines configuration/state data, RPC methods and notifications, whereas "example-b" defines only configuration/state data. The hybrid schema can then be schematically represented like this 🌸

  <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>
        ...local named pattern definitions of example-a...
      </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>
        ...local named pattern definitions of example-b...
      </grammar>
    </start>
    ...global named pattern definitions...
  </grammar>

A complete hybrid schema for the data model of a DHCP server is given in Appendix C.2 🎀

8.2. Modularity

Both YANG and RELAX NG have ways to do modularity, meaning you can split a full schema into separate modules and then combine or reuse them in different ways 🧩 But they do it differently! Modularity in RELAX NG is best for ad hoc mixing of a small number of schemas, whereas YANG assumes a big set of modules, kinda like SNMP MIB modules. Here are the differences that matter 👑

In YANG, whenever module A imports module B, it gets access to the definitions (groupings and typedefs) at the top level of module B. However, no part of the data tree from module B comes along with the import. In contrast, the <rng:include> pattern in RELAX NG brings in both the named pattern definitions AND the entire schema tree from the included schema 😳
The names of imported YANG groupings and typedefs get qualified with the namespace of the imported module. On the other hand, the names of data nodes inside the imported groupings become part of the importing module's namespace when used there 💅 In RELAX NG, pattern names are unqualified, so named patterns defined in both the importing and the imported module share one flat namespace. The contents of RELAX NG named patterns can either keep the namespace of the schema where they're defined, or inherit the namespace of the importing module, analogically to YANG. But to get that second behavior, the named pattern definitions must be included from an external schema, and that schema has to be prepared in a special way (see [Vli04], Chapter 11) 🥹

To map YANG's modularity to RELAX NG as closely as possible, a validating RELAX NG schema (the result of the second mapping step) has to be split into two files. One of them contains all the global definitions mapped from top-level YANG groupings that appear in ALL input YANG modules... wait, in all input YANG modules, my bad 🙈 This RELAX NG schema MUST NOT define any namespace via the @ns attribute.

The other RELAX NG schema file then defines the actual data trees mapped from the input YANG modules, each enclosed in its own embedded grammar. The embedded grammars where at least one of the global definitions is used MUST include the first schema with the definitions, and also MUST define the local namespace using the @ns attribute. That way, the global definitions can be used inside different embedded grammars, each time accepting a different local namespace ✨

Named pattern definitions mapped from non-top-level YANG groupings MUST be placed inside the embedded grammar that corresponds to the YANG module where the grouping is defined 🧁

In the hybrid schema, we need to tell global and non-global named pattern definitions apart while still keeping the hybrid schema in one file. Here's how that works 🦋

Every global definition MUST be placed as a child of the outer <rng:grammar> element (the document root of the hybrid schema).
Every non-global definition MUST be placed as a child of the corresponding embedded <rng:grammar> element.

YANG also lets you split a module into a bunch of submodules. But submodules have no impact on the scope of identifiers and namespaces, so modularity based on submodules isn't mapped in any way. The contents of submodules get handled as if the submodule text appeared directly in the main module 🫶

8.3. Granularity

RELAX NG supports different styles of schema structuring. At one extreme, often called "Russian Doll", the structure of an XML instance document is specified as one single hierarchy 🪆 At the other extreme is the flat style, which uses a similar approach to the Data Type Definition (DTD) schema language: every XML element corresponds to a named pattern definition. In practice, people usually pick some compromise between the two extremes 🌈

YANG supports both styles in principle too, but in most cases modules are organized closer to the "Russian Doll" style, which gives a better insight into the structure of the configuration data 👀 Groupings are usually only defined for contents that are prepared for reuse in multiple places via the uses statement. RELAX NG schemas, on the other hand, tend to be much flatter, because finer granularity is also needed in RELAX NG for extensibility. It's only possible to replace or modify schema fragments that have been factored out as named patterns. For YANG this isn't an issue, since its augment and refine statements can delve, using path expressions, into arbitrary depths of existing structures 💖

Honestly, it's not feasible to map YANG's powerful extension mechanisms onto the ones available in RELAX NG 😭 So the mapping basically keeps the granularity of the original YANG data model. YANG groupings and definitions of derived types usually have direct counterparts in the definitions of named patterns in the resulting RELAX NG schema 💅

8.4. Handling of XML Namespaces

Okay so bestie, most modern XML schema languages, including RELAX NG, Schematron, and DSRL, can handle compound XML documents 🌈 These are the ones that mix elements from multiple namespaces. This is SO useful for us, because the YANG-to-DSDL mapping lets you feed in multiple YANG modules, which naturally leads to compound document schemas 💖

RELAX NG gives you two ways to define the target namespaces in the schema:

The first possibility is the traditional XML way, via the @xmlns:xxx attribute.
One of the target namespace URIs may be declared using the @ns attribute.

In both the hybrid schema and the validation RELAX NG schemas generated in the second step, the namespaces MUST be declared as follows:

The root <rng:grammar> MUST have @xmlns:xxx attributes declaring 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. 🔥
Each embedded <rng:grammar> element MUST declare the namespace of 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. 💅

This setup is illustrated by the example at the end of Section 8.1. 🦋

DSRL schemas may declare any number of target namespaces via the standard XML attributes xmlns:xxx. 🎀

Schematron, in contrast, requires all used namespaces to be defined in the <sch:ns> subelements of the document element <sch:schema>. Not my favourite, ngl 🙈

9. Mapping YANG Data Models to the Hybrid Schema ✨

This section explains the main principles governing the first step of the mapping. Its result is the hybrid schema that is described in Section 8.1. 🌸

A detailed specification of the mapping of individual YANG statements is contained in Section 10. 📚

9.1. Occurrence Rules for Data Nodes

In DSDL schema languages, occurrence constraints for a node are always localized together with that node. In a RELAX NG schema, for example, the <rng:optional> pattern appears as the parent element of the pattern defining a leaf or non-leaf element. Similarly, DSRL specifies default contents separately for every single node, be it a leaf or non-leaf element. 🧚

For leaf nodes in YANG modules, the occurrence constraints are also easily inferred from the substatements of leaf. On the other hand, for a YANG container, it is often necessary to examine its entire subtree in order to determine the container's occurrence constraints. Ugh, subtrees, so much work 😭

Therefore, one of the goals of the first mapping step is to infer the occurrence constraints for all data nodes and mark, accordingly, the corresponding <rng:element> patterns in the hybrid schema, so that any transformation procedure in the second mapping step can simply use this information and need not examine the subtree again. Main character energy for the mapping step, honestly 👑

First, it has to be decided whether a given data node must always be present in a valid configuration. If so, such a node is called mandatory; otherwise, it is called optional. This constraint is closely related to the notion of mandatory nodes in Section 3.1 in [RFC6020]. The only difference is that this document also considers list keys to be mandatory. 💜

The other occurrence constraint has to do with the semantics of the default statement and the possibility of removing empty non-presence containers. As a result, the information set of a valid configuration may be modified by adding or removing certain leaf or container elements without changing the meaning of the configuration. In this document, such elements are called implicit. In the hybrid schema, they can be identified as RELAX NG patterns having either the @nma:default or the @nma:implicit attribute. ✨

Note that both occurrence constraints apply to containers at the top level of the data tree, and then also to other containers under the additional condition that their parent node exists in the instance document. For example, consider the following YANG fragment:

container outer {
    presence 'Presence of "outer" means something.';
    container c1 {
        leaf foo {
            type uint8;
            default 1;
        }
    }
    container c2 {
        leaf-list bar {
            type uint8;
            min-elements 0;
        }
    }
    container c3 {
        leaf baz {
            type uint8;
            mandatory true;
        }
    }
}

Here, container "outer" has the presence substatement, which means that it is optional and not implicit. If "outer" is not present in a configuration, its child containers are not present as well. However, if "outer" does exist, it makes sense to ask which of its child containers are optional and which are implicit. In this case, "c1" is optional and implicit, "c2" is optional but not implicit, and "c3" is mandatory (and therefore not implicit). 🍓

The following subsections give precise rules for determining whether a container is optional or mandatory and whether it is implicit. In order to simplify the recursive definition of these occurrence characteristics, it is useful to define them also for other types of YANG schema nodes, i.e., leaf, list, leaf-list, anyxml, and choice. 🌈

9.1.1. Optional and Mandatory Nodes

The decision whether a given node is mandatory or optional is governed by the following rules:

Leaf, anyxml, and choice nodes are mandatory if they contain the substatement mandatory true;. For a choice node, this means that at least one node from exactly one case branch must exist.
In addition, a leaf node is mandatory if it is declared as a list key.
A list or leaf-list node is mandatory if it contains the min-elements substatement with an argument value greater than zero.
A container node is mandatory if its definition does not contain the presence substatement and at least one of its child nodes is mandatory.

A node that is not mandatory is said to be optional. 🦋

In RELAX NG, definitions of nodes that are optional must be explicitly wrapped in the <rng:optional> element. The mapping MUST use the above rules to determine whether a YANG node is optional, and if so, insert the <rng:optional> element in the hybrid schema. 🔥

However, alternatives in <rng:choice> MUST NOT be defined as optional in the hybrid schema. If a choice in YANG is not mandatory, <rng:optional> MUST be used to wrap the entire <rng:choice> pattern. Okay the rules are strict here and I respect it 💅

9.1.2. Implicit Nodes

The following rules are used to determine whether a given data node is implicit:

List, leaf-list, and anyxml nodes are never implicit.
A leaf node is implicit if and only if it has a default value, defined either directly or via its data type.
A container node is implicit if and only if it does not have the presence substatement, none of its children are mandatory, and at least one child is implicit.

In the hybrid schema, all implicit containers, as well as leafs that obtain their default value from a typedef and don't have the @nma:default attribute, MUST be marked with @nma:implicit attribute having the value of "true". 🎀

Note that Section 7.9.3 in [RFC6020] specifies other rules that must be taken into account when deciding whether or not a given container or leaf appearing inside a case of a choice is ultimately implicit. Specifically, a leaf or container under a case can be implicit only if the case appears in the argument of the choice's default statement. However, this is not sufficient by itself but also depends on the particular instance XML document, namely on the presence or absence of nodes from other (non-default) cases. The details are explained in Section 11.3. 🧠

9.2. Mapping YANG Groupings and Typedefs

YANG groupings and typedefs are generally mapped to RELAX NG named patterns. There are, however, several caveats that the mapping has to take into account. ⚠️

First of all, YANG typedefs and groupings may appear at all levels of the module hierarchy and are subject to lexical scoping, see Section 5.5 in [RFC6020]. Second, top-level symbols from external modules may be imported as qualified names represented using the external module namespace prefix and the name of the symbol. In contrast, named patterns in RELAX NG (both local and imported via the <rng:include> pattern) share the same namespace and within a grammar they are always global -- their definitions may only appear at the top level as children of the <rng:grammar> element. Consequently, whenever YANG groupings and typedefs are mapped to RELAX NG named pattern definitions, their names MUST be disambiguated in order to avoid naming conflicts. The mapping uses the following procedure for mangling the names of groupings and type definitions: 🌸

Names of groupings and typedefs appearing at the top level of the YANG module hierarchy are prefixed with the module name and two underscore characters (__).
Names of other groupings and typedefs, i.e., those that do not appear at the top level of a YANG module, are prefixed with the module name, double underscore, and then the names of all ancestor data nodes separated by double underscore.
Finally, since the names of groupings and typedefs in YANG have different namespaces, an additional underscore character is added 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 [RFC6020]): 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 that imports the standard module "ietf-inet-types" [RFC6021]:

module example1 {
    namespace "http://example.com/ns/example1";
    prefix ex1;
    typedef vowels {
        type string {
            pattern "[aeiouy]*";
        }
    }
    grouping "grp1" {
        leaf "void" {
            type "empty";
        }
    }
    container "cont" {
        leaf foo {
            type vowels;
        }
        uses "grp1";
    }
}

The hybrid schema generated by the first mapping step will then contain the following two (global) named pattern definitions:

<rng:define name="example1__vowels">
  <rng:data type="string">
    <rng:param name="pattern">[aeiouy]*</rng:param>
  </rng:data>
</rng:define>

<rng:define name="_example1__grp1">
  <rng:optional>
    <rng:element name="void">
      <rng:empty/>
    </rng:element>
  </rng:optional>
</rng:define>

Okay so YANG groupings are basically the same vibe as named pattern definitions in RELAX NG, and both languages let you tweak them later 💅. The difference is that in RELAX NG the definitions themselves get modified 🙃, while YANG gives you two substatements of 'uses' that modify the expansions of groupings instead 🎀:

The 'refine' statement lets you change parameters of a schema node inside the grouping that the parent 'uses' statement points at ✨
The 'augment' statement can add new schema nodes into the grouping contents 🌸

Both 'refine' and 'augment' are super powerful, bestie, because they can target schema nodes that are arbitrarily deep inside the grouping contents, using XPath-like expressions as their arguments 😭. RELAX NG modifications of named pattern definitions only apply at the topmost level of the named pattern contents, so no deep dives there 🙅‍♀️. To get the same modifiability on named patterns that YANG has, your RELAX NG schema would need to be extremely flat (cf. Section 8.3) and honestly very difficult to read 💀.

Since the goal of this mapping is to generate ad hoc DSDL schemas, we decided to skip all that drama and expand the grouping and refine and/or augment it "in place" 🧚. So every 'uses' statement with 'refine' and/or 'augment' substatements gets replaced by the contents of the corresponding grouping, the changes from the 'refine' and 'augment' statements get applied, and the resulting YANG schema fragment is mapped as if the 'uses'/'grouping' indirection wasn't there at all 🫶.

If there are further 'uses' statements inside the grouping contents, they might need expanding too. That's needed if the contained 'uses'/'grouping' pair sits on the "modification path" given in the argument of a 'refine' or 'augment' statement 👑.

EXAMPLE. Consider the following YANG module 🍓:

module example2 {
    namespace "http://example.com/ns/example2";
    prefix ex2;
    grouping leaves {
        uses fr;
        uses es;
    }
    grouping fr {
        leaf feuille {
            type string;
        }
    }
    grouping es {
        leaf hoja {
            type string;
        }
    }
    uses leaves;
}

The resulting hybrid schema contains three global named pattern definitions, one for each of the three groupings, namely:

<rng:define name="_example2__leaves">
  <rng:interleave>
    <rng:ref name="_example2__fr"/>
    <rng:ref name="_example2__es"/>
  </rng:interleave>
</rng:define>

<rng:define name="_example2__fr">
  <rng:optional>
    <rng:element name="feuille">
      <rng:data type="string"/>
    </rng:element>
  </rng:optional>
</rng:define>

<rng:define name="_example2__es">
  <rng:optional>
    <rng:element name="hoja">
      <rng:data type="string"/>
    </rng:element>
  </rng:optional>
</rng:define>

And the configuration data part of the hybrid schema is a single named pattern reference:

<nma:data>
  <rng:ref name="_example2__leaves"/>
</nma:data>

Now assume that the "uses leaves" statement contains a 'refine' substatement, for example:

uses leaves {
    refine "hoja" {
        default "alamo";
    }
}

The resulting hybrid schema now contains just one named pattern definition, "_example2__fr". The other two groupings, "leaves" and "es", have to be expanded because they both lie on the "modification path", i.e., they contain the leaf "hoja" that's being refined 🌈. The configuration data part of the hybrid schema now looks like this:

<nma:data>
  <rng:interleave>
    <rng:ref name="_example2__fr"/>
    <rng:optional>
      <rng:element name="ex2:hoja" nma:default="alamo">
        <rng:data type="string"/>
      </rng:element>
    </rng:optional>
  </rng:interleave>
</nma:data>

9.2.2. Type Derivation Chains

RELAX NG has no equivalent of YANG's type derivation mechanism, which lets you restrict a built-in type (maybe in multiple steps) by adding new constraints 🧩. Whenever a derived YANG type gets used without restrictions, whether as a substatement of 'leaf' or of another 'typedef', the 'type' statement is mapped simply to a named pattern reference <rng:ref>, and the type definition is mapped to a RELAX NG named pattern definition <rng:define> 💖. But if any restrictions are specified as substatements of the 'type' statement, the type definition MUST be expanded at that point, so that only the ancestor built-in type shows up in the hybrid schema, restricted with facets that match the combination of all restrictions found along the type derivation chain and also in the 'type' statement 😤.

EXAMPLE. Consider this YANG module:

module example3 {
    namespace "http://example.com/ns/example3";
    prefix ex3;
    typedef dozen {
        type uint8 {
            range 1..12;
        }
    }
    leaf month {
        type dozen;
    }
}

The 'type' statement in "leaf month" has no restrictions, so it's mapped simply to the reference <rng:ref name="example3__dozen"/>, and the corresponding named pattern is defined as follows:

<rng:define name="example3__dozen">
  <rng:data type="unsignedByte">
    <rng:param name="minInclusive">1</rng:param>
    <rng:param name="maxInclusive">12</rng:param>
  </rng:data>
</rng:define>

Now let's say the definition of leaf "month" changes to:

leaf month {
    type dozen {
        range 7..max;
    }
}

The output RELAX NG schema then won't contain any named pattern definition, and the leaf "month" gets mapped directly to:

<rng:element name="ex3:month">
  <rng:data type="unsignedByte">
    <rng:param name="minInclusive">7</rng:param>
    <rng:param name="maxInclusive">12</rng:param>
  </rng:data>
</rng:element>

The mapping of type derivation chains can get a bit more complicated because of the 'default' statement in type definitions 🍬. In the simple case, when a type definition containing the 'default' statement is used without restrictions, the 'default' statement is mapped to the @nma:default attribute attached to the <rng:define> element.

But if that type definition has to be expanded due to restrictions, the @nma:default attribute coming from the expanded type or from ancestor types in the type derivation chain MUST be attached to the pattern where the expansion occurs 🫣. If there are multiple 'default' statements in consecutive steps of the type derivation, only the 'default' statement closest to the expanded type is used.

EXAMPLE. Here's a variation of the last example:

module example3bis {
    namespace "http://example.com/ns/example3bis";
    prefix ex3bis;
    typedef dozen {
        type uint8 {
            range 1..12;
        }
        default 7;
    }
    leaf month {
        type dozen;
    }
}

The 'typedef' statement in this module is mapped to the following named pattern definition:

<rng:define name="example3bis__dozen" @nma:default="7">
  <rng:data type="unsignedByte">
    <rng:param name="minInclusive">1</rng:param>
    <rng:param name="maxInclusive">12</rng:param>
  </rng:data>
</rng:define>

If the "dozen" type gets restricted when used in the leaf "month" definition, as in the previous example, then the "dozen" type has to be expanded and @nma:default becomes an attribute of the <ex3bis:month> element definition:

<rng:element name="ex3bis:month" @nma:default="7">
  <rng:data type="unsignedByte">
    <rng:param name="minInclusive">7</rng:param>
    <rng:param name="maxInclusive">12</rng:param>
  </rng:data>
</rng:element>

However, if the definition of the leaf "month" itself contained the 'default' substatement, then the default specified for the "dozen" type would be ignored 🙈.

9.3. Translation of XPath Expressions

YANG uses full XPath 1.0 syntax [XPath] for the arguments of 'must', 'when', and 'path' statements 🔍. The names of data nodes defined in a YANG module always belong to that module's namespace, so YANG went with a simplification similar to the default namespace concept in XPath 2.0: node names in XPath expressions don't need a namespace prefix inside the module where they're defined, and the local module's namespace is assumed 💅.

So, all XPath expressions MUST be translated into a fully conformant XPath 1.0 expression: every unprefixed node name MUST be prepended with the local module's namespace prefix, as declared by the 'prefix' statement ✨.

XPath expressions appearing inside top-level groupings need special attention, because all unprefixed node names in them must adopt the namespace of each module where the grouping is used (cf. Section 8.2) 🌸. To pull that off, the local prefix MUST be represented using the variable "$pref" in the hybrid schema. A Schematron schema that runs into such an XPath expression then supplies an appropriate value for this variable, through a parameter to an abstract pattern that the YANG grouping is mapped to (see Section 11.2) 🧚.

For example, the XPath expression "/dhcp/max-lease-time" appearing in a YANG module with the "dhcp" prefix will be translated to:

"$pref:dhcp/$pref:max-lease-time", if the expression is inside a top-level grouping;
"dhcp:dhcp/dhcp:max-lease-time", otherwise.

YANG also uses other XPath-like expressions, namely key identifiers and "descendant schema node identifiers" (see the ABNF production for and "descendant-schema-nodeid" in Section 12 of [RFC6020]) 🔑. These expressions MUST be translated by adding local module prefixes as well 💜.

9.4. YANG Language Extensions

YANG lets you extend its own language right in-line by adding new statements with keywords from special namespaces 🎀. Extensions first have to be declared using the 'extension' statement, and then they can be used like standard YANG statements, from which they're distinguished by a namespace prefix qualifying the extension keyword. RELAX NG has a similar extension mechanism, since XML elements and attributes with names from foreign namespaces can be inserted at almost any place in a RELAX NG schema 🌈.

YANG language extensions may or may not mean anything in the context of DSDL schemas 🤷‍♀️. Therefore, an implementation MAY ignore any or all of the extensions. However, an extension that is not ignored MUST be mapped to XML element(s) and/or attribute(s) that exactly match the YIN form of the extension, see Section 11.1 in [RFC6020] 🦋.

EXAMPLE. Consider the following extension defined by the "acme" module:

extension documentation-flag {
    argument number;
}

This extension can then be used in the same or another module, for instance like this:

leaf folio {
    acme:documentation-flag 42;
    type string;
}

If this extension is honored by the mapping, it will be mapped to:

<rng:element name="acme:folio">
   <acme:documentation-flag number="42"/>
   <rng:data type="string"/>
</rng:element>

Note that the 'extension' statement itself is not mapped in any way 💀.

10. Mapping YANG Statements to the Hybrid Schema ✨

Okay so this section is basically a dictionary for YANG statements 📖💖 Every subsection covers one statement and explains how it becomes part of the hybrid schema. They're sorted alphabetically by keyword, so you can find your fave fast 🧚

Each YANG statement turns into an XML fragment. That's usually one element or attribute, but it can be a bigger chunk too 🎀 The whole thing is recursive: once a statement is mapped, we move on to its substatements (if it has any), and one piece of the fragment you just made becomes the parent of whatever comes out of those substatements. If something breaks this default flow, the spec calls it out explicitly, so no sneaky surprises 👀

YANG's XML encoding rules come down to three ordering vibes for multiple subelements:

Inside the <nma:rpcs> subtree (so the input and output parameters of an RPC operation), the order is fixed. The definitions in the hybrid schema MUST follow the order from the source YANG module.
When mapping the 'list' statement, all keys MUST come before any other subelements, and they MUST be in the same order they're declared in the 'key' statement. The non-key subelements don't have a set order, so their definitions in the hybrid schema MUST be enclosed in the <rng:interleave> element.
Otherwise, the order is arbitrary, which means every subelement definition in the hybrid schema MUST be enclosed in the <rng:interleave> element.

A couple of conventions show up all over this section:

ARGUMENT is the argument of the statement being mapped. 💅
PARENT is the element in the RELAX NG schema that becomes the parent of the resulting XML fragment. 🦋

10.1. The 'anyxml' Statement

This statement maps to the <rng:element> element. ARGUMENT, with the local namespace prefix stuck on the front, becomes the value of its @name attribute. The contents of <rng:element> are:

<rng:ref name="__anyxml__"/>

Substatements of the 'anyxml' statement, if there are any, MAY be mapped to extra children of the <rng:element> element. 🌸

If at least one 'anyxml' statement shows up in any of the input YANG modules, the following pattern definition MUST be added exactly once to the RELAX NG schema, as a child of the root <rng:grammar> element (cf. [Vli04], p. 172):

<rng:define name="__anyxml__">
  <rng:zeroOrMore>
    <rng:choice>
      <rng:attribute>
        <rng:anyName/>
      </rng:attribute>
      <rng:element>
        <rng:anyName/>
        <rng:ref name="__anyxml__"/>
      </rng:element>
      <rng:text/>
    </rng:choice>
  </rng:zeroOrMore>
</rng:define>

EXAMPLE: here's a YANG statement in a module with namespace prefix "yam":

anyxml data {
    description "Any XML content allowed here.";
}

It gets mapped to this fragment:

<rng:element name="yam:data">
    <a:documentation>Any XML content allowed here</a:documentation>
    <rng:ref name="__anyxml__"/>
</rng:element>

An anyxml node is optional if there's no "mandatory true;" substatement. In that case, the <rng:element> element MUST be wrapped in <rng:optional>. The exception is when the 'anyxml' statement is a child of the 'choice' statement, where it forms a shorthand case for that choice (see Section 9.1.1 for details). ✨

10.2. The 'argument' Statement

This statement isn't mapped to the output schema. Check out the rules for handling extensions in Section 9.4 though 🧐

10.3. The 'augment' Statement

When 'augment' is a substatement of 'uses', it's handled as part of the 'uses' mapping. See Section 10.57.

At the top level of a module or submodule, the 'augment' statement is used to augment the schema tree of another YANG module. If the augmented module isn't processed in the same mapping session, the top-level 'augment' statement MUST be ignored. 🙈 Otherwise, the contents of the statement get added to the foreign module, using the namespace of the module where the 'augment' statement appears.

10.4. The 'base' Statement

This statement is ignored when it's a substatement of 'identity'. When it shows up as a substatement of the 'identityref' type, it's handled within that type. See Section 10.53.6.

10.5. The 'belongs-to' Statement

This statement isn't used at all, because submodules are always processed starting from the main module. See Section 10.24. 🍓

10.6. The 'bit' Statement

This statement is handled within the "bits" type. See Section 10.53.4. 💜

10.7. The 'case' Statement

This statement maps to the <rng:group> or <rng:interleave> element. Which one depends on whether or not the statement is part of an RPC operation definition. If a sibling 'default' statement has an argument equal to ARGUMENT, the @nma:implicit attribute with the value "true" MUST be added to that <rng:group> or <rng:interleave> element. 🔥 The @nma:implicit attribute MUST NOT be used for nodes at the top level of a non-default case (see Section 7.9.3 in [RFC6020]).

10.8. The 'choice' Statement

This statement maps to the <rng:choice> element.

If 'choice' has a 'mandatory' substatement with the value "true", the attribute @nma:mandatory MUST be added to the <rng:choice> element, with ARGUMENT as its value. This case might need extra handling, see Section 11.2.1. Otherwise, if "mandatory true;" isn't present, the <rng:choice> element MUST be wrapped in <rng:optional>. 👑

The alternatives inside <rng:choice> (mapped from either a 'case' statement or a shorthand case) MUST NOT be defined as optional.

10.9. The 'config' Statement

This statement maps to the @nma:config attribute, and ARGUMENT becomes its value. ⭐

10.10. The 'contact' Statement

This statement SHOULD NOT be used by the mapping. The reason is that the hybrid schema can be mapped from multiple YANG modules written by different authors. The hybrid schema holds references to all input modules in the Dublin Core elements <dc:source>, see Section 10.34. The original YANG modules are the authoritative sources for authorship info 🫶

10.11. The 'container' Statement

Using the rules in Section 9.1.1, the mapping algorithm MUST determine whether the statement defines an optional container. If it does, insert the <rng:optional> element and make it the new PARENT. 🌈

The container defined by this statement then maps to the <rng:element> element. That element becomes a child of PARENT, and ARGUMENT (with the local namespace prefix) is used as the value of its @name attribute.

Finally, using the rules in Section 9.1.2, the mapping algorithm MUST determine whether the container is implicit. If it is, add the attribute @nma:implicit with the value "true" to the <rng:element> element. 🧚

10.12. The 'default' Statement

If this statement is a substatement of 'leaf', it maps to the @nma:default attribute of PARENT, and ARGUMENT becomes its value. 🎀

As a substatement of 'typedef', the 'default' statement also maps to the @nma:default attribute, with ARGUMENT as its value. Where that attribute lands depends on whether the type definition has to be expanded when it's used:

If the type definition is not expanded, @nma:default becomes an attribute of the <rng:define> pattern that comes out of the parent 'typedef' mapping.
Otherwise, @nma:default becomes an attribute of the ancestor RELAX NG pattern where the expansion happens.

Details and an example are in Section 9.2.2. 💖

Last one: as a substatement of 'choice', the 'default' statement identifies the default case, and it gets handled inside the 'case' statement (see Section 10.7). If the default case uses the shorthand notation (no 'case' statement), the @nma:implicit attribute with the value "true" either goes on the node representing that default case in the shorthand, or an extra <rng:group> element MAY be inserted and the attribute attached to that instead. Either way, the end result is the same as if the 'case' statement hadn't been omitted for the default case. 🦋

EXAMPLE. Here's a 'choice' statement in a module with namespace prefix "yam":

choice leaves {
    default feuille;
    leaf feuille { type empty; }
    leaf hoja { type empty; }
}

It can be mapped directly to:

<rng:choice>
  <rng:element name="yam:feuille" nma:implicit="true">
    <rng:empty/>
  </rng:element>
  <rng:element name="yam:hoja">
    <rng:empty/>
  </rng:element/>
</rng:choice>

Or the default case can be wrapped in an extra <rng:group>:

<rng:choice>
  <rng:group nma:implicit="true">
    <rng:element name="yam:feuille">
      <rng:empty/>
    </rng:element>
  </rng:group>
  <rng:element name="yam:hoja">
    <rng:empty/>
  </rng:element/>
</rng:choice>

10.13. The 'description' Statement

This statement maps to the DTD compatibility element <a:documentation>, and ARGUMENT becomes its text.

To get formatted properly in the RELAX NG compact syntax, this element SHOULD be inserted as the first child of PARENT. 📝

10.14. The 'deviation' Statement

This statement is ignored. It's assumed that all deviations are known beforehand, and their changes have already been applied to the input YANG modules. 🙌

10.15. The 'enum' Statement

This statement maps to the <rng:value> element, and ARGUMENT becomes its text. Every substatement except 'status' is ignored, because the <rng:value> element can't contain annotation elements (see [RNG], Section 6). 💅

10.16. The 'error-app-tag' Statement

This statement is ignored unless it's a substatement of 'must'. When it is, it maps to the <nma:error-app-tag> element. See also Section 10.35. 🚨

10.17. The 'error-message' Statement

This statement is ignored unless it's a substatement of 'must'. When it is, it maps to the <nma:error-message> element. See also Section 10.35. 💬

10.18. The 'extension' Statement

This statement is ignored. However, extensions to the YANG language MAY be mapped as described in Section 9.4. 🧩

10.19. The 'feature' Statement

This statement is ignored. 🌸

10.20. The 'grouping' Statement 🧩

This statement is mapped to a RELAX NG named pattern definition <rng:define>, but only if the grouping defined by this statement is used without refinements and augments in at least one of the input modules. 💅 In that case, the named pattern definition becomes a child of the <rng:grammar> element, and its name is ARGUMENT mangled according to the rules in Section 9.2.

As explained in Section 8.2, a named pattern definition MUST be placed:

as a child of the root <rng:grammar> element if the corresponding grouping is defined at the top level of an input YANG module;
otherwise as a child of the embedded <rng:grammar> element corresponding to the module in which the grouping is defined.

Whenever a grouping is used with refinements and/or augments, it gets expanded so the refinements and augments can 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 mapping all 'grouping' statements as named pattern definitions in the output RELAX NG schema, even if they aren't referenced. ✨ This is useful for mapping YANG "library" modules, which usually contain only 'typedef' and/or 'grouping' statements.

10.21. The 'identity' Statement 🆔

This statement is mapped to the following named pattern definition, which gets 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 the named pattern corresponding to an
   identity that is derived from the current identity.  Exactly one
   <rng:ref> element MUST be present for every such identity.

Okay, the bit that matters most: exactly one <rng:ref> element MUST be present for every identity derived from the current one. 🎯

EXAMPLE ([RFC6020], Section 7.16.3). 🌸 Let's say we have these identities defined across two 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";
  }
}

The identities get mapped to these 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 the arguments of all sibling 'if-feature' statements (with added prefixes, if missing), MUST be collected in a space-separated list. 📝 That list becomes the value of the @nma:if-feature attribute, and this attribute is attached to PARENT.

10.23. The 'import' Statement 📦

This statement isn't specifically mapped. ✨ The module whose name is in ARGUMENT has to be parsed, so the importing module can use its top-level groupings, typedefs and identities, and also augment the data tree of the imported module.

If the 'import' statement has the 'revision' substatement, the corresponding revision of the imported module MUST be used. 🔍 The mechanism for finding a given module revision is outside the scope of this document.

10.24. The 'include' Statement 🧷

This statement isn't specifically mapped either. The submodule whose name is in ARGUMENT has to be parsed, and its contents get mapped exactly as if the submodule text appeared directly in the main module text. 🫶

If the 'include' statement has the 'revision' substatement, the corresponding revision of the submodule MUST be used. The mechanism for finding a given submodule revision is outside the scope of this document.

10.25. The 'input' Statement 📥

This statement is handled within the 'rpc' statement, see Section 10.50.

10.26. The 'key' Statement 🔑

This statement is mapped to the @nma:key attribute. 💖 ARGUMENT MUST be translated so that every key is prefixed with the namespace prefix of the local module. The result of this translation then becomes the value of the @nma:key attribute.

10.27. The 'leaf' Statement 🍃

This statement is mapped to the <rng:element> element, and ARGUMENT, with the local namespace prefix prepended, becomes the value of its @name attribute.

If the leaf is optional (meaning there's no mandatory true; substatement and the leaf isn't declared among the keys of an enclosing list), then the <rng:element> element MUST be enclosed in <rng:optional>. 🙈 The exception is when the 'leaf' statement is a child of the 'choice' statement and therefore represents a shorthand case for that choice (see Section 9.1.1 for details).

10.28. The 'leaf-list' Statement 🌿

This statement is mapped to a block enclosed by either the <rng:zeroOrMore> or the <rng:oneOrMore> element. Which one depends on whether the argument of the 'min-elements' substatement is "0" or positive, respectively (it's zero by default). 🧮 This <rng:zeroOrMore> or <rng:oneOrMore> element becomes the PARENT.

<rng:element> is then added as a child element of PARENT, and ARGUMENT with the local namespace prefix prepended becomes the value of its @name attribute. 🌸 Another attribute, @nma:leaf-list, MUST also be added to this <rng:element> element, with the value "true". If the 'leaf-list' statement has the 'min-elements' substatement and its argument is greater than one, an additional attribute @nma:min-elements is attached to <rng:element>, and the argument of 'min-elements' becomes the value of this attribute. Similarly, if there's a 'max-elements' substatement whose argument value isn't "unbounded", the attribute @nma:max-elements is attached to this element, and the argument of 'max-elements' becomes the value of this attribute.

EXAMPLE. 🌈 Let's look at this 'leaf-list' appearing in a module with the namespace prefix "yam":

leaf-list foliage {
    min-elements 3;
    max-elements 6378;
    ordered-by user;
    type string;
}

It gets mapped to this RELAX NG fragment:

<rng:oneOrMore>
  <rng:element name="yam:foliage" nma:leaf-list="true"
               nma:ordered-by="user"
               nma:min-elements="3" nma:max-elements="6378">
    <rng:data type="string"/>
  </rng:element>
</rng:oneOrMore>

10.29. The 'length' Statement 📏

This statement is handled within the "string" type, see Section 10.53.10.

10.30. The 'list' Statement 📋

This statement is mapped exactly as the 'leaf-list' statement, see Section 10.28. ✨ The only difference is that the @nma:leaf-list annotation either MUST NOT be present, or MUST have the value "false".

When mapping the substatements of 'list', the order of the list element's children MUST be specified so that list keys (if there are any) always appear in the same order as they're defined in the 'key' substatement, and before other children. 👑 See [RFC6020], Section 7.8.5. In particular, if a list key is defined in a grouping but the list node itself isn't part of the same grouping, and the position of the 'uses' statement would break the ordering requirement above, the grouping MUST be expanded. That means the 'uses' statement gets replaced by the grouping contents.

For example, here's a YANG fragment from a module with the prefix "yam":

grouping keygrp {
  leaf clef {
    type uint8;
  }
}
list foo {
  key clef;
  leaf bar {
    type string;
  }
  leaf baz {
    type string;
  }
  uses keygrp;
}

It gets mapped to this RELAX NG fragment:

<rng:zeroOrMore>
  <rng:element name="yam:foo" nma:key="yam:clef">
    <rng:element name="yam:clef">
      <rng:data type="unsignedByte"/>
    </rng:element>
    <rng:interleave>
      <rng:element name="yam:bar">
        <rng:data type="string"/>
      </rng:element>
      <rng:element name="yam:baz">
        <rng:data type="string"/>
      </rng:element>
    </rng:interleave>
  </rng:element>
</rng:zeroOrMore>

Note that the "keygrp" grouping is expanded, and the definition of "yam:clef" is moved before the <rng:interleave> pattern. 🫧

10.31. The 'mandatory' Statement ⚠️

This statement may appear as a substatement of 'leaf', 'choice', or 'anyxml' statements. If ARGUMENT is "true", the parent data node is mapped as mandatory, see Section 9.1.1.

As a substatement of 'choice', this statement is also mapped to the @nma:mandatory attribute, which gets 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, see Section 10.28.

10.33. The 'min-elements' Statement 🔻

This statement is handled within 'leaf-list' or 'list' statements, see Section 10.28.

10.34. The 'module' Statement 🏠

This statement is mapped to an embedded <rng:grammar> pattern that has 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 it contains ARGUMENT as a metadata reference to the input YANG module. See also Section 10.49.

Substatements of the 'module' statement MUST be mapped so that:

statements representing configuration/state data are mapped to descendants of the <nma:data> element;
statements representing the contents of RPC requests or replies are mapped to descendants of the <nma:rpcs> element;
statements representing the contents of event notifications are mapped to descendants of the <nma:notifications> element.

10.35. The 'must' Statement 🚦

This statement is mapped to the <nma:must> element. It has one mandatory attribute, @assert (with no namespace), which contains ARGUMENT transformed into a valid XPath expression (see Section 9.3). ✨ The <nma:must> element may have other subelements resulting from mapping the 'error-app-tag' and 'error-message' substatements. The other substatements of 'must' (that is, 'description' and 'reference') get ignored.

EXAMPLE. 🦋 Here's a YANG statement from the "dhcp" module:

must 'current() <= ../max-lease-time' {
    error-message
        "The default-lease-time must be less than max-lease-time";
}

and it gets mapped to:

<nma:must assert="current()&lt;=../dhcp:max-lease-time">
  <nma:error-message>
    The default-lease-time must be less than max-lease-time
  </nma:error-message>
</nma:must>

10.36. The 'namespace' Statement 🌐

This statement gets mapped in two ways at the same time:

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;
to the @ns attribute of PARENT, which is an embedded <rng:grammar> pattern. ARGUMENT becomes the value of this attribute.

10.37. The 'notification' Statement

okay so this one gets mapped to a subtree under 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>
</nma:notification>

the substatements of 'notification' get mapped under <rng:element name="PREFIX:ARGUMENT"> 🎀

10.38. The 'ordered-by' Statement

this one maps to the @nma:ordered-by attribute, and ARGUMENT becomes its value 🦋 see Section 10.28 for an example, it's giving clarity ✨

10.39. The 'organization' Statement

this statement gets ignored by the mapping 🙈 bc the hybrid schema might be mapped from multiple YANG modules written by different parties. the hybrid schema SHOULD contain references to all input modules in the Dublin Core <dc:source> elements, see Section 10.34.

the original YANG modules are the authoritative sources of the authorship info, so go to them for the credit 🫶

10.40. The 'output' Statement

this one is handled within the 'rpc' statement, see Section 10.50 🧚

10.41. The 'path' Statement

handled within the "leafref" type, see Section 10.53.8 🌸

10.42. The 'pattern' Statement

handled within the "string" type, see Section 10.53.10 💅

10.43. The 'position' Statement

this one is ignored, no cap 🫠

10.44. The 'prefix' Statement

this is handled within the sibling 'namespace' statement, see Section 10.36, or within the parent 'import' statement, see Section 10.23. as a substatement of 'belongs-to' (in submodules), the 'prefix' statement is ignored 🍓

10.45. The 'presence' Statement

this one influences the mapping of the parent container (Section 10.11) 👑 the parent container definition MUST be wrapped in <rng:optional>, regardless of its contents. see also Section 9.1.1 ✨

10.46. The 'range' Statement

handled within numeric types, see Section 10.53.9 🌈

10.47. The 'reference' Statement

this one is mapped to a <a:documentation> element, and its text is set to ARGUMENT prefixed with "See: " 💖

10.48. The 'require-instance' Statement

handled within the "instance-identifier" type (Section 10.53.7) 🎀

10.49. The 'revision' Statement

the mapping only uses the most recent instance of the 'revision' statement 🦋 that's the one with the latest date in ARGUMENT, which specifies the current revision of the input YANG module [RFC6020]. this date SHOULD be recorded, together with the name of the YANG module, in the matching Dublin Core <dc:source> element (see Section 10.34), like this:

<dc:source>YANG module 'foo', revision 2010-03-02</dc:source>

the 'description' substatement of 'revision' gets ignored 💅

10.50. The 'rpc' Statement

this one is mapped to the following subtree in the RELAX NG schema, where PREFIX is the prefix of the local YANG module 🧚

<nma:rpc>
  <nma:input>
    <rng:element name="PREFIX:ARGUMENT">
      ... mapped contents of 'input' ...
    </rng:element>
  </nma:input>
  <nma:output">
    ... mapped contents of 'output' ...
  </nma:output>
</nma:rpc>

so as the fragment shows, the contents of the 'input' substatement (if there are any) get mapped under <rng:element name="PREFIX: ARGUMENT">. same vibe for 'output': its contents get mapped under <nma:output> 🌸 if there's no 'output' substatement, the <nma:output> element MUST NOT be present, periodt 💀

the <nma:rpc> element is a child of <nma:rpcs> ✨

10.51. The 'status' Statement

this one MAY be ignored 🫶 otherwise, it gets mapped to the @nma:status attribute, and ARGUMENT becomes its value 🌈

10.52. The 'submodule' Statement

this isn't specifically mapped 🦋 its substatements are mapped as if they showed up directly in the module that the submodule belongs to 👑

10.53. The 'type' Statement

most YANG built-in data types have an equivalent in the XSD data type library [XSD-D], as shown in Table 4 🍓 it's giving organized:

+-----------+---------------+--------------------------------+
| YANG type | XSD type      | Meaning                        |
+-----------+---------------+--------------------------------+
| int8      | byte          | 8-bit integer value            |
|           |               |                                |
| int16     | short         | 16-bit integer value           |
|           |               |                                |
| int32     | int           | 32-bit integer value           |
|           |               |                                |
| int64     | long          | 64-bit integer value           |
|           |               |                                |
| uint8     | unsignedByte  | 8-bit unsigned integer value   |
|           |               |                                |
| uint16    | unsignedShort | 16-bit unsigned integer value  |
|           |               |                                |
| uint32    | unsignedInt   | 32-bit unsigned integer value  |
|           |               |                                |
| uint64    | unsignedLong  | 64-bit unsigned integer value  |
|           |               |                                |
| string    | string        | character string               |
|           |               |                                |
| binary    | base64Binary  | binary data in base64 encoding |
+-----------+---------------+--------------------------------+

   Table 4: YANG built-in data types with equivalents in the W3C XML
                          Schema Type Library

two important data types from the XSD data type library, "dateTime" and "anyURI", aren't built-in types in YANG 😭 instead they're defined as derived types in the standard modules [RFC6021]: "date-and-time" in the "ietf-yang-types" module and "uri" in the "ietf-inet-types" module. the formal restrictions in the YANG type definitions are rather weak, though 🥺 so implementations of the YANG-to-DSDL mapping SHOULD detect these derived types in source YANG modules and map them to "dateType" and "anyURI", respectively 🔥

the details about mapping each individual YANG built-in type are in the following subsections ✨

10.53.1. The "empty" Type

this type is mapped to <rng:empty/> 🎀

10.53.2. The "boolean" Type

this built-in type doesn't allow any restrictions, and it gets mapped to the following XML fragment:

<rng:choice>
  <rng:value>true</rng:value>
  <rng:value>false</rng:value>
</rng:choice>

note that the XSD "boolean" type can't be used here 🙅 because, unlike YANG, it allows an alternative numeric representation of boolean values: 0 for "false" and 1 for "true" 🤓

10.53.3. The "binary" Type

this built-in type doesn't allow any restrictions either 🫧 it's mapped simply by inserting an <rng:data> element whose @type attribute value is set to "base64Binary" (see also Table 4) 💜

10.53.4. The "bits" Type

this type is mapped to the <rng:list>, and for each 'bit' substatement, the following XML fragment gets inserted as a child of <rng:list>:

<rng:optional>
  <rng:value>bit_name</rng:value>
</rng:optional>

where bit_name is the name of the bit, as found in the argument of a 'bit' substatement 🍓

10.53.5. The "enumeration" and "union" Types

these types are mapped to the <rng:choice> element 🌈

10.53.6. The "identityref" Type

this type is mapped to the following named pattern reference:

<rng:ref name="__PREFIX_BASE"/>

where PREFIX:BASE is the qualified name of the identity appearing in the argument of the 'base' substatement 🧚

for example, say module "des" in Section 10.21 has this leaf definition:

leaf foo {
  type identityref {
    base crypto:crypto-alg;
  }
}

this leaf would then be mapped to the following element pattern:

<element name="des:foo">
  <ref name="__crypto_crypto-alg"/>
</element>

10.53.7. The "instance-identifier" Type

this type is mapped to a <rng:data> element with the @type attribute set to "string" 💖 on top of that, an empty <nma:instance-identifier> element MUST be inserted as a child of PARENT 🫶

the argument of the 'require-instance' substatement, if it exists, becomes the value of the @require-instance attribute of the <nma:instance-identifier> element 🎀

10.53.8. The "leafref" Type

this type is mapped exactly as the type of the leaf given in the argument of the 'path' substatement 🦋 however, if the type of the referred leaf defines a default value, this default value MUST be ignored by the mapping 🙈

also, the @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.9. The Numeric Types

the YANG built-in numeric types are "int8", "int16", "int32", "int64", "uint8", "uint16", "uint32", "uint64", and "decimal64" 🌸 they're mapped to the <rng:data> element with the @type attribute set to ARGUMENT, translated according to Table 4 above 💅

the exception is the "decimal64" type, which is mapped to the "decimal" type of the XSD data type library. its precision and number of fractional digits are controlled with the following facets, which MUST always be present:

o "totalDigits" facet set to the value of 19.

o "fractionDigits" facet set to the argument of the 'fraction-digits' substatement.

the fixed value of "totalDigits" corresponds to the maximum of 19 decimal digits for 64-bit integers 🧮

for example, this statement:

type decimal64 {
    fraction-digits 2;
}

is mapped to the following RELAX NG data type:

<rng:data type="decimal">
  <rng:param name="totalDigits">19</rng:param>
  <rng:param name="fractionDigits">2</rng:param>
</rng:data>

all numeric types support the 'range' restriction, and it gets mapped like this 🌈

if the range expression consists of just a single range LO..HI, then it's mapped to a pair of data type facets:

<rng:param name="minInclusive">LO</rng:param>

and

<rng:param name="maxInclusive">HI</rng:param>

if the range consists of a single number, the values of both facets are set to that value. if LO is equal to the string "min", the "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 parent <rng:data> element must be repeated once for every range part, and all of those <rng:data> elements get wrapped in a <rng:choice> element 🎀 each <rng:data> element contains the "minInclusive" and "maxInclusive" facets for one part of the range expression, as described in the previous paragraph 🦋

for the "decimal64" type, the "totalDigits" and "fractionDigits" must be repeated inside each of the <rng:data> elements 🍓

for example:

type int32 {
    range "-6378..0|42|100..max";
}

is mapped to the following RELAX NG fragment:

<rng:choice>
  <rng:data type="int">
    <rng:param name="minInclusive">-6378</rng:param>
    <rng:param name="maxInclusive">0</rng:param>
  </rng:data>
  <rng:data type="int">
    <rng:param name="minInclusive">42</rng:param>
    <rng:param name="maxInclusive">42</rng:param>
  </rng:data>
  <rng:data type="int">
    <rng:param name="minInclusive">100</rng:param>
  </rng:data>
</rng:choice>

see Section 9.2.2 for further details on mapping the restrictions 🧚

10.53.10. The "string" Type ✨

This type gets mapped to the <rng:data> element with the @type attribute set to "string" 🎀.

The length restriction works pretty much the same way as the range restriction for the numeric types (Section 10.53.9) 💅.

If the length expression has just a single range:

and if the length range consists of a single number LENGTH, the following data type facet gets inserted:

<rng:param name="length">LENGTH</rng:param>.

if the length range is of the form LO..HI, meaning it has both a lower and an upper bound, then these two data type facets get inserted:

<rng:param name="minLength">LO</rng:param>

and

<rng:param name="maxLength">HI</rng:param>

If LO is equal to the string "min", the "minLength" facet gets left out 🙈. If HI is equal to the string "max", the "maxLength" facet gets left out too.

If the length expression has multiple parts separated by "|", then the parent <rng:data> element must be repeated once for every range part, and all of those <rng:data> elements get wrapped in a <rng:choice> element 🌈. Each <rng:data> element holds the "length" or "minLength" and "maxLength" facets for one part of the length expression, the same way as in the paragraph above.

Every 'pattern' restriction of the "string" data type gets mapped to the "pattern" facet:

<rng:param name="pattern">...</rng:param>

with its text equal to the argument of the 'pattern' statement. All of these "pattern" facets must be repeated inside each copy of the <rng:data> element, so once for each length range. Bestie, don't skip this part 😭.

For example,

type string {
    length "1|3..8";
    pattern "[A-Z][a-z]*";
}

gets mapped to the following RELAX NG fragment:

<rng:choice>
  <rng:data type="string">
    <rng:param name="length">1</rng:param>
    <rng:param name="pattern">[A-Z][a-z]*</rng:param>
  </rng:data>
  <rng:data type="string">
    <rng:param name="minLength">3</rng:param>
    <rng:param name="maxLength">8</rng:param>
    <rng:param name="pattern">[A-Z][a-z]*</rng:param>
  </rng:data>
</rng:choice>

10.53.11. Derived Types 🦋

If the 'type' statement refers to a derived type, it gets mapped in one of the following ways, depending on whether it has any restrictions as substatements:

Without restrictions, the 'type' statement gets mapped simply to the <rng:ref> element, which is a reference to a named pattern. If the RELAX NG definition of this named pattern hasn't been added to the hybrid schema yet, the corresponding type definition MUST be found, and its mapping must be installed as a subelement of either the root or an embedded <rng:grammar> element (see Section 10.54). Even if a given derived type gets used more than once in the input YANG modules, the mapping of the corresponding 'typedef' MUST be installed only once 🔥.
If any restrictions are present, the ancestor built-in type for the given derived type must be determined, and the mapping of this base type MUST be used. Restrictions appearing at all stages of the type derivation chain MUST be taken into account, and their conjunction gets added to the <rng:data> element that defines the basic type 👑.

See Section 9.2.2 for more details and an example.

10.54. The 'typedef' Statement 🧚

This statement gets mapped to a RELAX NG named pattern definition <rng:define>, but only if the type it defines is used without restrictions in at least one of the input modules. In that case, the named pattern definition becomes a child of either the root or an embedded <rng:grammar> element, depending on whether the 'typedef' statement appears at the top level of a YANG module. The name of this named pattern definition is set to ARGUMENT, mangled according to the rules in Section 9.2.

Whenever a derived type is used with additional restrictions, the ancestor built-in type for the derived type is used instead, with restrictions (facets) that combine all the restrictions specified along the type derivation chain. See Section 10.53.11 for further details and an example 🍓.

An implementation MAY offer the option of recording all 'typedef' statements as named patterns in the output RELAX NG schema, even if they aren't referenced. This is useful for mapping YANG "library" modules that contain only 'typedef' and/or 'grouping' statements 💜.

10.55. The 'unique' Statement 🌸

This statement gets mapped to the @nma:unique attribute. ARGUMENT MUST be translated so that every node identifier in each of its components is prefixed with the namespace prefix of the local module, unless the prefix is already there. The result of this translation then becomes the value of the @nma:unique attribute.

For example, assuming the local module prefix is "ex",

unique "foo ex:bar/baz"

gets mapped to the following attribute/value pair:

nma:unique="ex:foo ex:bar/ex:baz"

10.56. The 'units' Statement 🎀

This statement gets mapped to the @nma:units attribute, and ARGUMENT becomes its value.

10.57. The 'uses' Statement 💅

If this statement has neither 'refine' nor 'augment' substatements, it gets mapped to the <rng:ref> element, which is a reference to a named pattern. The value of its @name attribute is set to ARGUMENT, mangled according to Section 9.2. If the RELAX NG definition of the referenced named pattern hasn't been added to the hybrid schema yet, the corresponding grouping MUST be found, and its mapping gets installed as a subelement of <rng:grammar> (see Section 10.20) ✨.

Otherwise, if the 'uses' statement has any 'refine' or 'augment' substatements, the corresponding grouping must be looked up, and its contents get inserted under PARENT. See Section 9.2.1 for further details and an example.

10.58. The 'value' Statement 🙈

This statement is ignored.

10.59. The 'when' Statement 🦋

This statement gets mapped to the @nma:when attribute. ARGUMENT, translated according to Section 9.3, becomes its value.

10.60. The 'yang-version' Statement 🔥

This statement is not mapped to the output schema. However, an implementation SHOULD check that it is compatible with the YANG version declared by the statement (currently version 1). In the case of a mismatch, the implementation SHOULD report an error and terminate 💀.

10.61. The 'yin-element' Statement 🌈

This statement is not mapped to the output schema, but see the rules for extension handling in Section 9.4.

11. Mapping the Hybrid Schema to DSDL 🧚‍♀️

As explained in Section 6, the second step of the YANG-to-DSDL mapping takes the hybrid schema and transforms it into various DSDL schemas that can validate instance XML documents. In the simplest case, this step takes just one input parameter: a specification of the NETCONF XML document type to be validated. These document types can be, for example, the contents of a datastore, a reply to <nc:get> or <nc:get-config>, the contents of other RPC requests and replies, event notifications, and so on 💖.

The second mapping step has to accomplish three general tasks:

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.
Adapt the schema to the specific encapsulating XML elements mandated by the RPC layer. For example, these are <nc:rpc> and <nc:data> elements in the case of a <nc:get> reply, or <en:notification> for a notification.
Map the NETMOD-specific annotations that are relevant for the schema language of the generated schema to the corresponding patterns or rules.

These three tasks are together much simpler than the first mapping step, and they can be implemented effectively 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 mapping all NETMOD-specific annotations 🍓.

11.1. Generating RELAX NG Schemas for Various Document Types 🌸

With one minor exception, getting a validating RELAX NG schema from the hybrid schema just means taking the appropriate parts of the hybrid schema and assembling them in a new RELAX NG grammar, perhaps after removing all the 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 a <nc:get> or <nc:get-config> reply, RPC operations, or notifications, patterns defining the corresponding top-level information items MUST be added, such as <nc:rpc-reply> with the @message-id attribute and so on 🎀.

To avoid copying common named pattern definitions for common NETCONF elements and attributes into every single output RELAX NG file, such schema-independent definitions SHOULD be collected in a library file that the validating RELAX NG schemas then include. 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 ✨

okay so Schematron schemas are lowkey so much flatter and more uniform than RELAX NG 🥰 they only have exactly four levels of XML hierarchy: <sch:schema>, <sch:pattern>, <sch:rule>, and <sch:assert> or <sch:report>. no nesting drama at all 🎀

in a Schematron schema made by the second mapping step, the main unit of organization is a rule, shown as the <sch:rule> element. these NETMOD-specific annotations from the hybrid schema (we'll call them "semantic annotations" 💜) get turned into 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 when it shows up as an attribute of <rng:choice> (see Section 11.2.1) 🦋

each input YANG module becomes a Schematron pattern whose @id attribute is set to the module name. then every <rng:element> pattern that has at least one of those semantic annotations becomes a Schematron rule:

<sch:rule context="XELEM">
  ...
</sch:rule>

the @context attribute of <sch:rule> is mandatory, and it's shown as XELEM. it MUST be set to the absolute path of the context element in the data tree 🫶 the <sch:rule> element holds all the mapped semantic annotations as Schematron asserts or reports ✨

now here's the tricky bit 🙈 semantic annotations sitting inside a named pattern definition (so, anything with <rng:define> among its ancestors) need special treatment, because they might get reused in different contexts. the fix is Schematron abstract patterns that use the "$pref" variable in place of the local namespace prefix. the @id attribute of that abstract pattern MUST be set to the name of the named pattern definition being mapped, which is basically the mangled name of the original YANG grouping 💅

when the abstract pattern gets instantiated, the values of these two parameters MUST be provided:

pref: the actual namespace prefix,
start: an XPath expression defining the context in which the grouping is used.

EXAMPLE. let's look at this 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> looks like this 🌸

<?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>

so the "sorted-leaf-list" grouping gets mapped to an abstract pattern with the @id value "_example4__sorted-leaf-list", and its must statement becomes the <sch:assert> element 🎯 then the abstract pattern is instantiated by the pattern with the @id value "id2573371", which sets the "start" and "pref" parameters to the right values ✨

also, sneaky bonus: another Schematron element, <sch:report>, got added automatically to check for duplicate leaf-list entries 👀

the mapping from the hybrid schema to Schematron goes through these steps 💖

first, you select the active subtree(s) of the hybrid schema based on the requested target document type. this is identical to the RELAX NG case, including how @nma:config gets handled when the target document type is a <nc:get-config> reply.
namespaces of all input YANG modules, plus the namespaces of base NETCONF (the "nc" prefix) or notifications (the "en" prefix), MUST be declared using the <sch:ns> element. for example:

<sch:ns uri="http://example.com/ns/example4" prefix="ex4"/>

one pattern gets created for every input module. on top of that, an abstract pattern gets created for every named pattern definition that contains one or more semantic annotations.
a <sch:rule> element gets created for each element pattern that contains semantic annotations.
every one of those annotations then gets 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 what YANG's choice statement means with the "mandatory true;" substatement, the RELAX NG grammar has to be paired with a special Schematron rule 🧚

EXAMPLE. consider this 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;
        }
    }
}

here's the thing 😭 all three leaf nodes in both case branches are optional, but because of the "mandatory true;" statement, at least one of them has to be present in a valid configuration. the choice statement from this module gets mapped to this 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 it has to be present in a valid configuration if that branch is the one selected 🌈 but the two elements in the first branch ("foo") can't both be declared mandatory, since each one of them alone is enough for a valid configuration. so the RELAX NG fragment above would happily validate configurations where none of the three leaf elements are there at all 🙈

so mandatory choices (recognizable in the hybrid schema as <rng:choice> elements carrying the @nma:mandatory annotation) need a special treatment. for each mandatory choice where at least one of the cases contains more than one node, a Schematron rule MUST be added that enforces the presence of at least one element from any of the cases. (RELAX NG schema already guarantees that elements from different cases can't get mixed together, that all mandatory nodes are present, etc.)

for the example module above, the Schematron rule looks like this 🎀

<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 ✨

okay bestie, DSRL is literally the ONLY part of DSDL that's allowed to change the information set of the validated XML document 💅👑 It does other stuff too, but YANG-to-DSDL mapping only uses it for specifying and applying default contents 🎀 For XML instance documents based on YANG data models, default contents may potentially get inserted for all the implicit nodes identified by the rules in Section 9.1.2 🫶

In DSRL, the default contents of an element are specified with the <dsrl:default-content> element, which is a child of <dsrl:element-map> 🌸 Two sibling elements of <dsrl:default-content> set the context for applying the default contents, see [DSRL]:

the <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;
the <dsrl:name> contains the XML name of the element that, 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, so default contents get applied properly 🔥

DSRL mapping only deals with <rng:element> patterns in the hybrid schema that define implicit nodes (see Section 9.1.2) 🦋 Those element patterns are distinguished by having the NETMOD-specific annotation attributes @nma:default or @nma:implicit, meaning either:

<rng:element name="ELEM" nma:default="DEFVALUE">
  ...
</rng:element>

<rng:element name="ELEM" nma:implicit="true">
  ...
</rng:element>

The first case applies to leaf nodes that have the 'default' substatement, but also to leaf nodes that get their default value from a typedef, if that typedef is expanded according to the rules in Section 9.2.2 so the @nma:default annotation is attached directly to the leaf's element pattern 🧚

The second case is used for all implicit containers (see Section 9.1) and for leafs that get the default value from a typedef and don't have the @nma:default annotation 💜

In the simplest case, both element patterns get mapped to this 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 built like this:

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).
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.
Otherwise, the implicit node ELEM is a container, and DEFCONT is built as an XML fragment containing all descendant elements of ELEM that have either the @nma:implicit or the @nma:default attribute.

Also, 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 handled 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>
    </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 that the annotation is attached to. In the rest of this section, CONTELEM will denote the name of this context element, properly qualified with its namespace prefix 🦋

12.1. The @nma:config Annotation

If this annotation is present with the value of "false", the following rules MUST be observed for DSDL schemas of <nc:get-config> reply:

When generating RELAX NG, the contents of the CONTELEM definition MUST be changed to <rng:notAllowed>.
When generating Schematron or DSRL, the CONTELEM definition and all its descendants in the hybrid schema MUST be ignored.

12.2. The @nma:default Annotation

This annotation is used for generating the DSRL schema as described in Section 11.3 🌈

12.3. The <nma:error-app-tag> Annotation

This annotation currently has no mapping defined 🫠

12.4. The <nma:error-message> Annotation

This annotation is handled within <nma:must>, see Section 12.13 💜

12.5. The @if-feature Annotation

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:

When generating RELAX NG, the contents of the CONTELEM definition MUST be changed to <rng:notAllowed>.
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 the value of "false", it is ignored. Otherwise, it is mapped to the following Schematron assert:

<sch:assert test="nmf:evaluate(.)">
  The element pointed to by "CONTELEM" must exist.
</sch:assert>

The nmf:evaluate() function is an XSLT extension function (see Extension Functions in [XSLT]) that evaluates an XPath expression at run time. Such an extension function is available in Extended XSLT (EXSLT), or provided as a proprietary extension by some XSLT processors, for example Saxon 🔥

12.8. The @nma:key Annotation

Assume this annotation attribute contains "k_1 k_2 ... k_n", i.e., it specifies n children of CONTELEM as list keys. The annotation is then mapped to the following Schematron report:

<sch:report test="CONDITION">
  Duplicate key of list "CONTELEM"
</sch:report>

where CONDITION has this form:

preceding-sibling::CONTELEM[C_1 and C_2 and ... and C_n]

Each sub-expression C_i, for i=1,2,...,n, specifies the condition for violated uniqueness of the key k_i, namely:

k_i=current()/k_i

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:

<sch:assert test="PATH=.">
  Leaf "PATH" does not exist for leafref value "VALUE"
</sch:assert>

where PATH is the value of @nma:leafref, and VALUE is the value of the context element in the instance document for which the referred leaf doesn't exist 🧚

12.11. The @nma:min-elements Annotation

This annotation is mapped to the following Schematron assert:

<sch:assert test="count(../CONTELEM)&gt;=MIN">
  List "CONTELEM" - item count must be at least MIN
</sch:assert>

where MIN is the value of @nma:min-elements 🍓

12.12. The @nma:max-elements Annotation

This annotation is mapped to the following Schematron assert:

<sch:assert
    test="count(../CONTELEM)&lt;=MAX or preceding-sibling::../CONTELEM">
  Number of list items must be at most MAX
</sch:assert>

where MAX is the value of @nma:min-elements 💅

12.13. The <nma:must> Annotation

This annotation is mapped to the following Schematron assert:

<sch:assert test="EXPRESSION">
  MESSAGE
</sch:assert>

where EXPRESSION is the value of the mandatory @assert attribute of <nma:must>. If the <nma:error-message> subelement exists, MESSAGE is set to its contents; otherwise, it is set to the default message "Condition EXPRESSION must be true" 🫶

12.14. The <nma:ordered-by> Annotation

This annotation currently has no mapping defined 🌸

12.15. The <nma:status> Annotation

This annotation currently has no mapping defined 🌸

12.16. The @nma:unique Annotation

The mapping of this annotation is almost identical to the one for @nma:key, see Section 12.8, with two small differences 👑

The value of @nma:unique is a list of descendant schema node identifiers rather than simple leaf names. However, the XPath expressions specified in Section 12.8 work without any modifications if the descendant schema node identifiers are substituted for k_1, k_2, ..., k_n.
The message appearing as the text of <sch:report> is different: "Violated uniqueness for list CONTELEM".

12.17. The @nma:when Annotation

This annotation is mapped to the following Schematron assert:

<sch:assert test="EXPRESSION">
  Node "CONTELEM" is only valid when "EXPRESSION" is true.
</sch:assert>

where EXPRESSION is the value of @nma:when ✨

13. IANA Considerations ✨

okay so IANA gets two new namespace URIs in the IETF XML registry [RFC3688] 🗂️💖 both registrations are listed below, and the registrant contact is The IESG 👑

-----------------------------------------------------
URI: urn:ietf:params:xml:ns:netmod:dsdl-annotations:1

Registrant Contact: The IESG.

XML: N/A, the requested URI is an XML namespace.
-----------------------------------------------------

-----------------------------------------------------
URI: urn:ietf:params:xml:ns:netmod:xpath-extensions:1

Registrant Contact: The IESG.

XML: N/A, the requested URI is an XML namespace.
-----------------------------------------------------

14. Security Considerations 🔐

bestie, this one is serious 😭 The procedure in this document maps YANG data models to a coordinated set of DSDL schemas, and the procedure itself has no security impact on the Internet 🫶

the schemas that come out of the mapping may be used to validate NETCONF messages or entire datastores 💅 that means they add validity checks on top of the ones that NETCONF server and client implementations that support YANG data models already do ✨ how strict that validation is comes straight from the source YANG modules that the validated XML data adheres to 🎀

Heads up: the strictness you get from these schemas is only as strict as the YANG modules they came from. Don't assume extra protection that the source modules don't provide 🙈

15. Contributors 🧚

the following people contributed significantly to the initial version of this document 💜

Rohan Mahy
Sharon Chisholm (Ciena)

16. Acknowledgments 🌸

the editor wants to thank the following people, who gave helpful suggestions and/or comments on various versions of this document 🫶 Andy Bierman, Martin Bjorklund, Jirka Kosek, Juergen Schoenwaelder, and Phil Shafer 🌈

17. References 📚

17.1. Normative References

[DSDL]         ISO/IEC, "Document Schema Definition Languages (DSDL)
               - Part 1: Overview", ISO/IEC 19757-1, November 2004.

[DSRL]         ISO/IEC, "Information Technology - Document Schema
               Definition Languages (DSDL) - Part 8: Document
               Semantics Renaming Language - DSRL", ISO/
               IEC 19757-8:2008(E), December 2008.

[RFC2119]      Bradner, S., "Key words for use in RFCs to Indicate
               Requirement Levels", BCP 14, RFC 2119, March 1997.

[RFC3688]      Mealling, M., "The IETF XML Registry", BCP 81,
               RFC 3688, January 2004.

[RFC4741]      Enns, R., "NETCONF Configuration Protocol", RFC 4741,
               December 2006.

[RFC6020]      Bjorklund, M., Ed., "YANG - A Data Modeling Language
               for Network Configuration Protocol (NETCONF)",
               RFC 6020, October 2010.

[RFC6021]      Schoenwaelder, J., Ed., "Common YANG Data Types",
               RFC 6021, October 2010.

[RNG]          ISO/IEC, "Information Technology - Document Schema
               Definition Languages (DSDL) - Part 2: Regular-Grammar-
               Based Validation - RELAX NG. Second Edition.", ISO/
               IEC 19757-2:2008(E), December 2008.

[RNG-CS]       ISO/IEC, "Information Technology - Document Schema
               Definition Languages (DSDL) - Part 2: Regular-Grammar-
               Based Validation - RELAX NG. AMENDMENT 1: Compact
               Syntax", ISO/IEC 19757-2:2003/Amd. 1:2006(E),
               January 2006.

[RNG-DTD]      Clark, J., Ed. and M. Murata, Ed., "RELAX NG DTD
               Compatibility", OASIS Committee Specification, 3
               December 2001.

[Schematron]   ISO/IEC, "Information Technology - Document Schema
               Definition Languages (DSDL) - Part 3: Rule-Based
               Validation - Schematron", ISO/IEC 19757-3:2006(E),
               June 2006.

[XML]          Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E.,
               and F. Yergeau, "Extensible Markup Language (XML) 1.0
               (Fifth Edition)", World Wide Web Consortium
               Recommendation REC-xml-20081126, November 2008,
               <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)
               Version 1.0", World Wide Web Consortium
               Recommendation REC-xpath-19991116, November 1999,
               <http://www.w3.org/TR/1999/REC-xpath-19991116>.

[XSD-D]        Biron, P. and A. Malhotra, "XML Schema Part 2:
               Datatypes Second Edition", World Wide Web Consortium
               Recommendation REC-xmlschema-2-20041028, October 2004,
               <http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.

[XSLT]         Clark, J., "XSL Transformations (XSLT) Version 1.0",
               World Wide Web Consortium Recommendation REC-xslt-
               19991116, November 1999.

17.2. Informative References

[DHCPtut]      Bjorklund, M., "DHCP Tutorial", November 2007, <http:/
               /www.yang-central.org/twiki/bin/view/Main/
               DhcpTutorial>.

[RFC1157]      Case, J., Fedor, M., Schoffstall, M., and J. Davin,
               "Simple Network Management Protocol (SNMP)", RFC 1157,
               May 1990.

[RFC2578]      McCloghrie, K., Ed., Perkins, D., Ed., and J.
               Schoenwaelder, Ed., "Structure of Management
               Information Version 2 (SMIv2)", STD 58, RFC 2578,
               April 1999.

[RFC5013]      Kunze, J., "The Dublin Core Metadata Element Set",
               RFC 5013, August 2007.

[RFC5277]      Chisholm, S. and H. Trevino, "NETCONF Event
               Notifications", RFC 5277, July 2008.

[Trang]        Clark, J., "Trang: Multiformat schema converter based
               on RELAX NG", 2008,
               <http://www.thaiopensource.com/relaxng/trang.html>.

[Vli04]        van der Vlist, E., "RELAX NG", O'Reilly, 2004.

[XSD]          Thompson, H., Beech, D., Maloney, M., and N.
               Mendelsohn, "XML Schema Part 1: Structures Second
               Edition", World Wide Web Consortium
               Recommendation REC-xmlschema-1-20041028, October 2004,
               <http://www.w3.org/TR/2004/REC-xmlschema-1-20041028>.

[pyang]        Bjorklund, M. and L. Lhotka, "pyang: An extensible
               YANG validator and converter in Python", 2010,
               <http://code.google.com/p/pyang/>.

Appendix A. RELAX NG Schema for NETMOD-Specific Annotations 🎀

this appendix defines the content model for all NETMOD-specific annotations, written as RELAX NG named pattern definitions 💅 here's the whole file ✨

<CODE BEGINS> file "nmannot.rng"

<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0"
         xmlns:nma="urn:ietf:params:xml:ns:netmod:dsdl-annotations:1"
         datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">

<define name="config-attribute">
  <attribute name="nma:config">
    <data type="boolean"/>
  </attribute>
</define>

<define name="data-element">
  <element name="nma:data">
    <ref name="__anyxml__"/>
  </element>
</define>

<define name="default-attribute">
  <attribute name="nma:default">
    <data type="string"/>
  </attribute>
</define>

<define name="error-app-tag-element">
  <element name="nma:error-app-tag">
    <text/>
  </element>
</define>

<define name="error-message-element">
  <element name="nma:error-message">
    <text/>
  </element>
</define>
<define name="if-feature-attribute">
  <attribute name="nma:if-feature">
    <list>
      <data type="QName"/>
    </list>
  </attribute>
</define>

<define name="implicit-attribute">
  <attribute name="nma:implicit">
    <data type="boolean"/>
  </attribute>
</define>

<define name="instance-identifier-element">
  <element name="nma:instance-identifier">
    <optional>
      <attribute name="nma:require-instance">
        <data type="boolean"/>
      </attribute>
    </optional>
  </element>
</define>

<define name="key-attribute">
  <attribute name="nma:key">
    <list>
      <data type="QName"/>
    </list>
  </attribute>
</define>

<define name="leaf-list-attribute">
  <attribute name="nma:leaf-list">
    <data type="boolean"/>
  </attribute>
</define>

<define name="leafref-attribute">
  <attribute name="nma:leafref">
    <data type="string"/>
  </attribute>
</define>
<define name="mandatory-attribute">
  <attribute name="nma:mandatory">
    <data type="Name"/>
  </attribute>
</define>

<define name="max-elements-attribute">
  <attribute name="nma:max-elements">
    <data type="nonNegativeInteger"/>
  </attribute>
</define>

<define name="min-elements-attribute">
  <attribute name="nma:min-elements">
    <data type="nonNegativeInteger"/>
  </attribute>
</define>

<define name="module-attribute">
  <attribute name="nma:module">
    <data type="Name"/>
  </attribute>
</define>

<define name="must-element">
  <element name="nma:must">
    <attribute name="assert">
      <data type="string"/>
    </attribute>
    <interleave>
      <optional>
        <ref name="error-app-tag-element"/>
      </optional>
      <optional>
        <ref name="error-message-element"/>
      </optional>
    </interleave>
  </element>
</define>
<define name="notifications-element">
  <element name="nma:notifications">
    <zeroOrMore>
      <element name="nma:notification">
        <ref name="__anyxml__"/>
      </element>
    </zeroOrMore>
  </element>
</define>

<define name="rpcs-element">
  <element name="nma:rpcs">
    <zeroOrMore>
      <element name="nma:rpc">
        <interleave>
          <element name="nma:input">
            <ref name="__anyxml__"/>
          </element>
          <optional>
            <element name="nma:output">
              <ref name="__anyxml__"/>
            </element>
          </optional>
        </interleave>
      </element>
    </zeroOrMore>
  </element>
</define>

<define name="ordered-by-attribute">
  <attribute name="nma:ordered-by">
    <choice>
      <value>user</value>
      <value>system</value>
    </choice>
  </attribute>
</define>
<define name="status-attribute">
  <optional>
    <attribute name="nma:status">
      <choice>
        <value>current</value>
        <value>deprecated</value>
        <value>obsolete</value>
      </choice>
    </attribute>
  </optional>
</define>

<define name="unique-attribute">
  <optional>
    <attribute name="nma:unique">
      <list>
        <data type="token"/>
      </list>
    </attribute>
  </optional>
</define>

<define name="units-attribute">
  <optional>
    <attribute name="nma:units">
      <data type="string"/>
    </attribute>
  </optional>
</define>

<define name="when-attribute">
  <optional>
    <attribute name="nma:when">
      <data type="string"/>
    </attribute>
  </optional>
</define>
<define name="__anyxml__">
  <zeroOrMore>
    <choice>
      <attribute>
        <anyName/>
      </attribute>
      <element>
        <anyName/>
        <ref name="__anyxml__"/>
      </element>
      <text/>
    </choice>
  </zeroOrMore>
</define>

</grammar>

<CODE ENDS>

Appendix B. Schema-Independent Library 📚✨

Okay so, to stop every RELAX NG schema from the second mapping step copy-pasting the same common named patterns 🙄, all the shared definitions live in one library file, the schema-independent library 💅. The validating schemas pull it in under the file names "relaxng-lib.rng" (XML syntax) and "relaxng-lib.rnc" (compact syntax). It covers patterns for common elements from base NETCONF [RFC4741] and event notifications [RFC5277] 💖

<CODE BEGINS> file "relaxng-lib.rng"

<?xml version="1.0" encoding="UTF-8"?>

<grammar xmlns="http://relaxng.org/ns/structure/1.0"
         xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
         xmlns:en="urn:ietf:params:xml:ns:netconf:notification:1.0"
         datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">

  <define name="message-id-attribute">
    <attribute name="message-id">
      <data type="string">
        <param name="maxLength">4095</param>
      </data>
    </attribute>
  </define>
  <define name="ok-element">
    <element name="nc:ok">
      <empty/>
    </element>
  </define>

  <define name="eventTime-element">
    <element name="en:eventTime">
      <data type="dateTime"/>
    </element>
  </define>
</grammar>

<CODE ENDS>

Appendix C. Mapping DHCP Data Model - A Complete Example 🧚

Bestie, this appendix runs both steps of the YANG-to-DSDL mapping on the "canonical" DHCP tutorial [DHCPtut] data model 🎀 The input YANG module is in Appendix C.1, and the output schemas are in the next two subsections 🌸

The hybrid schema came out of the "dsdl" plugin of the pyang tool [pyang] 🦋 and the validating DSDL schemas were made with XSLT stylesheets that also ship with the pyang distribution ✨

Heads up: lines are capped at 72 characters 📏 so a few long strings got manual editing, especially the regular expression patterns for IP addresses, etc. Those got swapped for the placeholder string "... regex pattern ...". Line breaks were also added to some documentation strings and Schematron messages 🙈

Other than that, the results of the automatic translations were not changed 💅

C.1. Input YANG Module

module dhcp {
  namespace "http://example.com/ns/dhcp";
  prefix dhcp;

  import ietf-yang-types { prefix yang; }
  import ietf-inet-types { prefix inet; }
  organization
    "yang-central.org";
  description
    "Partial data model for DHCP, based on the config of
     the ISC DHCP reference implementation.";

  container dhcp {
    description
      "configuration and operational parameters for a DHCP server.";

    leaf max-lease-time {
      type uint32;
      units seconds;
      default 7200;
    }

    leaf default-lease-time {
      type uint32;
      units seconds;
      must '. <= ../max-lease-time' {
        error-message
          "The default-lease-time must be less than max-lease-time";
      }
      default 600;
    }

    uses subnet-list;

    container shared-networks {
      list shared-network {
        key name;

        leaf name {
          type string;
        }
        uses subnet-list;
      }
    }

    container status {
      config false;
      list leases {
        key address;
        leaf address {
          type inet:ip-address;
        }
        leaf starts {
          type yang:date-and-time;
        }
        leaf ends {
          type yang:date-and-time;
        }
        container hardware {
          leaf type {
            type enumeration {
              enum "ethernet";
              enum "token-ring";
              enum "fddi";
            }
          }
          leaf address {
            type yang:phys-address;
          }
        }
      }
    }
  }

  grouping subnet-list {
    description "A reusable list of subnets";
    list subnet {
      key net;
      leaf net {
        type inet:ip-prefix;
      }
      container range {
        presence "enables dynamic address assignment";
        leaf dynamic-bootp {
          type empty;
          description
            "Allows BOOTP clients to get addresses in this range";
        }
        leaf low {
          type inet:ip-address;
          mandatory true;
        }
        leaf high {
          type inet:ip-address;
          mandatory true;
        }
      }

      container dhcp-options {
        description "Options in the DHCP protocol";
        leaf-list router {
          type inet:host;
          ordered-by user;
          reference "RFC 2132, sec. 3.8";
        }
        leaf domain-name {
          type inet:domain-name;
          reference "RFC 2132, sec. 3.17";
        }
      }

      leaf max-lease-time {
        type uint32;
        units seconds;
        default 7200;
      }
    }
  }
}

C.2. Hybrid Schema 💖

Okay bestie, this is the hybrid schema, and it's giving "everything in one place" energy 🎀 It's a single RELAX NG grammar that holds the DHCP module's structure together with the NETMOD annotations ✨

<?xml version="1.0" encoding="UTF-8"?>
<grammar
    xmlns="http://relaxng.org/ns/structure/1.0"
    xmlns:nma="urn:ietf:params:xml:ns:netmod:dsdl-annotations:1"
    xmlns:dc="http://purl.org/dc/terms"
    xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"
    xmlns:dhcp="http://example.com/ns/dhcp"
    datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
 <dc:creator>Pyang 1.0a, DSDL plugin</dc:creator>
 <dc:date>2010-06-17</dc:date>
 <start>
  <grammar nma:module="dhcp" ns="http://example.com/ns/dhcp">
   <dc:source>YANG module 'dhcp'</dc:source>
   <start>

    <nma:data>
     <optional>
      <element nma:implicit="true" name="dhcp:dhcp">
       <interleave>
        <a:documentation>
         configuration and operational parameters for a DHCP server.
        </a:documentation>
        <optional>
         <element nma:default="7200"
                  name="dhcp:max-lease-time"
                  nma:units="seconds">
          <data type="unsignedInt"/>
         </element>
        </optional>
        <optional>
         <element nma:default="600"
                  name="dhcp:default-lease-time"
                  nma:units="seconds">
          <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>
         </element>
        </optional>
        <ref name="_dhcp__subnet-list"/>
        <optional>
         <element name="dhcp:shared-networks">
          <zeroOrMore>
           <element nma:key="dhcp:name"
                    name="dhcp:shared-network">
            <element name="dhcp:name">
             <data type="string"/>
            </element>
            <ref name="_dhcp__subnet-list"/>
           </element>
          </zeroOrMore>
         </element>
        </optional>
        <optional>
         <element name="dhcp:status" nma:config="false">
          <zeroOrMore>
           <element nma:key="dhcp:address"
                    name="dhcp:leases">
            <element name="dhcp:address">
             <ref name="ietf-inet-types__ip-address"/>
            </element>
            <interleave>
             <optional>
              <element name="dhcp:starts">
               <ref name="ietf-yang-types__date-and-time"/>
              </element>
             </optional>
             <optional>
              <element name="dhcp:ends">
               <ref name="ietf-yang-types__date-and-time"/>
              </element>
             </optional>
             <optional>
              <element name="dhcp:hardware">
               <interleave>
                <optional>
                 <element name="dhcp:type">
                  <choice>
                   <value>ethernet</value>
                   <value>token-ring</value>
                   <value>fddi</value>
                  </choice>
                 </element>
                </optional>
                <optional>
                 <element name="dhcp:address">
                  <ref name="ietf-yang-types__phys-address"/>
                 </element>
                </optional>
               </interleave>
              </element>
             </optional>
            </interleave>
           </element>
          </zeroOrMore>
         </element>
        </optional>
       </interleave>
      </element>
     </optional>
    </nma:data>
    <nma:rpcs/>
    <nma:notifications/>
   </start>
  </grammar>
 </start>
 <define name="ietf-yang-types__phys-address">
  <data type="string">
   <param name="pattern">([0-9a-fA-F]{2}(:[0-9a-fA-F]{2})*)?</param>

  </data>
 </define>
 <define name="ietf-inet-types__ipv6-address">
  <data type="string">
   <param name="pattern">... regex pattern ...</param>
   <param name="pattern">... regex pattern ...</param>
  </data>
 </define>
 <define name="ietf-inet-types__ip-prefix">
  <choice>
   <ref name="ietf-inet-types__ipv4-prefix"/>
   <ref name="ietf-inet-types__ipv6-prefix"/>
  </choice>
 </define>
 <define name="ietf-inet-types__host">
  <choice>
   <ref name="ietf-inet-types__ip-address"/>
   <ref name="ietf-inet-types__domain-name"/>
  </choice>
 </define>
 <define name="ietf-yang-types__date-and-time">
  <data type="string">
   <param name="pattern">... regex pattern ...</param>
  </data>
 </define>
 <define name="_dhcp__subnet-list">
  <a:documentation>A reusable list of subnets</a:documentation>
  <zeroOrMore>
   <element nma:key="net" name="subnet">
    <element name="net">
     <ref name="ietf-inet-types__ip-prefix"/>
    </element>
    <interleave>
     <optional>
      <element name="range">
       <interleave>
        <optional>
         <element name="dynamic-bootp">
          <a:documentation>
           Allows BOOTP clients to get addresses in this range
          </a:documentation>
          <empty/>
         </element>
        </optional>
        <element name="low">
         <ref name="ietf-inet-types__ip-address"/>
        </element>
        <element name="high">

         <ref name="ietf-inet-types__ip-address"/>
        </element>
       </interleave>
      </element>
     </optional>
     <optional>
      <element name="dhcp-options">
       <interleave>
        <a:documentation>
         Options in the DHCP protocol
        </a:documentation>
        <zeroOrMore>
         <element nma:leaf-list="true" name="router"
                  nma:ordered-by="user">
          <a:documentation>
           See: RFC 2132, sec. 3.8
          </a:documentation>
          <ref name="ietf-inet-types__host"/>
         </element>
        </zeroOrMore>
        <optional>
         <element name="domain-name">
          <a:documentation>
           See: RFC 2132, sec. 3.17
          </a:documentation>
          <ref name="ietf-inet-types__domain-name"/>
         </element>
        </optional>
       </interleave>
      </element>
     </optional>
     <optional>
      <element nma:default="7200" name="max-lease-time"
               nma:units="seconds">
       <data type="unsignedInt"/>
      </element>
     </optional>
    </interleave>
   </element>
  </zeroOrMore>
 </define>
 <define name="ietf-inet-types__domain-name">
  <data type="string">
   <param name="pattern">... regex pattern ...</param>
   <param name="minLength">1</param>
   <param name="maxLength">253</param>
  </data>
 </define>
 <define name="ietf-inet-types__ipv4-prefix">
  <data type="string">
   <param name="pattern">... regex pattern ...</param>
  </data>
 </define>
 <define name="ietf-inet-types__ipv4-address">
  <data type="string">
   <param name="pattern">... regex pattern ...</param>
  </data>
 </define>
 <define name="ietf-inet-types__ipv6-prefix">
  <data type="string">
   <param name="pattern">... regex pattern ...</param>
   <param name="pattern">... regex pattern ...</param>
  </data>
 </define>
 <define name="ietf-inet-types__ip-address">
  <choice>
   <ref name="ietf-inet-types__ipv4-address"/>
   <ref name="ietf-inet-types__ipv6-address"/>
  </choice>
 </define>
</grammar>

C.3. Final DSDL Schemas 🧚

Okay so this part is where the hybrid schema gets glow-up'd 💅 These DSDL schemas came out of the hybrid schema in Appendix C.2 through XSL transformations, and they're literally ready to go for checking a reply to an unfiltered <nc:get> that holds the DHCP data model 🔥

The RELAX NG schema (in two parts, as explained in Section 8.2) also pulls in the schema-independent library from Appendix B 🫶

C.3.1. Main RELAX NG Schema for `<nc:get>` Reply ✨

<?xml version="1.0" encoding="utf-8"?>
<grammar
    xmlns="http://relaxng.org/ns/structure/1.0"
    xmlns:nma="urn:ietf:params:xml:ns:netmod:dsdl-annotations:1"
    xmlns:dhcp="http://example.com/ns/dhcp"
    datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"
    ns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <include href="relaxng-lib.rng"/>
 <start>
  <element name="rpc-reply">
   <ref name="message-id-attribute"/>
   <element name="data">

    <interleave>
     <grammar ns="http://example.com/ns/dhcp">
      <include href="dhcp-gdefs.rng"/>
      <start>
       <optional>
        <element name="dhcp:dhcp">
         <interleave>
          <optional>
           <element name="dhcp:max-lease-time">
            <data type="unsignedInt"/>
           </element>
          </optional>
          <optional>
           <element name="dhcp:default-lease-time">
            <data type="unsignedInt"/>
           </element>
          </optional>
          <ref name="_dhcp__subnet-list"/>
          <optional>
           <element name="dhcp:shared-networks">
            <zeroOrMore>
             <element name="dhcp:shared-network">
              <element name="dhcp:name">
               <data type="string"/>
              </element>
              <ref name="_dhcp__subnet-list"/>
             </element>
            </zeroOrMore>
           </element>
          </optional>
          <optional>
           <element name="dhcp:status">
            <zeroOrMore>
             <element name="dhcp:leases">
              <element name="dhcp:address">
               <ref name="ietf-inet-types__ip-address"/>
              </element>
              <interleave>
               <optional>
                <element name="dhcp:starts">
                 <ref name="ietf-yang-types__date-and-time"/>
                </element>
               </optional>
               <optional>
                <element name="dhcp:ends">
                 <ref name="ietf-yang-types__date-and-time"/>
                </element>
               </optional>
               <optional>
                <element name="dhcp:hardware">
                 <interleave>
                  <optional>
                   <element name="dhcp:type">
                    <choice>
                     <value>ethernet</value>
                     <value>token-ring</value>
                     <value>fddi</value>
                    </choice>
                   </element>
                  </optional>
                  <optional>
                   <element name="dhcp:address">
                    <ref name="ietf-yang-types__phys-address"/>
                   </element>
                  </optional>
                 </interleave>
                </element>
               </optional>
              </interleave>
             </element>
            </zeroOrMore>
           </element>
          </optional>
         </interleave>
        </element>
       </optional>
      </start>
     </grammar>
    </interleave>
   </element>
  </element>
 </start>
</grammar>

C.3.2. RELAX NG Schema - Global Named Pattern Definitions ✨

okay so this is the big list of named patterns that the RELAX NG schema reuses 💅 Each define is a little reusable building block, like a cookie cutter for the types and structures that show up all over the DHCP data 🍪

<?xml version="1.0" encoding="utf-8"?>
<grammar
    xmlns="http://relaxng.org/ns/structure/1.0"
    xmlns:nma="urn:ietf:params:xml:ns:netmod:dsdl-annotations:1"
    xmlns:dhcp="http://example.com/ns/dhcp"
    datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
 <define name="ietf-yang-types__phys-address">
  <data type="string">
   <param name="pattern">
    ([0-9a-fA-F]{2}(:[0-9a-fA-F]{2})*)?

   </param>
  </data>
 </define>
 <define name="ietf-inet-types__ipv6-address">
  <data type="string">
   <param name="pattern">... regex pattern ...</param>
  </data>
 </define>
 <define name="ietf-inet-types__ip-prefix">
  <choice>
   <ref name="ietf-inet-types__ipv4-prefix"/>
   <ref name="ietf-inet-types__ipv6-prefix"/>
  </choice>
 </define>
 <define name="ietf-inet-types__host">
  <choice>
   <ref name="ietf-inet-types__ip-address"/>
   <ref name="ietf-inet-types__domain-name"/>
  </choice>
 </define>
 <define name="ietf-yang-types__date-and-time">
  <data type="string">
   <param name="pattern">... regex pattern ...</param>
  </data>
 </define>
 <define name="_dhcp__subnet-list">
  <zeroOrMore>
   <element name="subnet">
    <element name="net">
     <ref name="ietf-inet-types__ip-prefix"/>
    </element>
    <interleave>
     <optional>
      <element name="range">
       <interleave>
        <optional>
         <element name="dynamic-bootp">
          <empty/>
         </element>
        </optional>
        <element name="low">
         <ref name="ietf-inet-types__ip-address"/>
        </element>
        <element name="high">
         <ref name="ietf-inet-types__ip-address"/>
        </element>
       </interleave>
      </element>

     </optional>
     <optional>
      <element name="dhcp-options">
       <interleave>
        <zeroOrMore>
         <element name="router">
          <ref name="ietf-inet-types__host"/>
         </element>
        </zeroOrMore>
        <optional>
         <element name="domain-name">
          <ref name="ietf-inet-types__domain-name"/>
         </element>
        </optional>
       </interleave>
      </element>
     </optional>
     <optional>
      <element name="max-lease-time">
       <data type="unsignedInt"/>
      </element>
     </optional>
    </interleave>
   </element>
  </zeroOrMore>
 </define>
 <define name="ietf-inet-types__domain-name">
  <data type="string">
   <param name="pattern">... regex pattern ...</param>
   <param name="minLength">1</param>
   <param name="maxLength">253</param>
  </data>
 </define>
 <define name="ietf-inet-types__ipv4-prefix">
  <data type="string">
   <param name="pattern">... regex pattern ...</param>
  </data>
 </define>
 <define name="ietf-inet-types__ipv4-address">
  <data type="string">
   <param name="pattern">... regex pattern ...</param>
  </data>
 </define>
 <define name="ietf-inet-types__ipv6-prefix">
  <data type="string">
   <param name="pattern">... regex pattern ...</param>
   <param name="pattern">... regex pattern ...</param>
  </data>

 </define>
 <define name="ietf-inet-types__ip-address">
  <choice>
   <ref name="ietf-inet-types__ipv4-address"/>
   <ref name="ietf-inet-types__ipv6-address"/>
  </choice>
 </define>
</grammar>

C.3.3. Schematron Schema for <nc:get> Reply 🎀

this one is the Schematron rules, which are the extra checks that sit on top of the RELAX NG stuff 🦋 it looks at duplicate keys and makes sure the lease times make sense together 🙈

<?xml version="1.0" encoding="utf-8"?>
<sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron">
 <sch:ns uri="http://example.com/ns/dhcp" prefix="dhcp"/>
 <sch:ns uri="urn:ietf:params:xml:ns:netconf:base:1.0" prefix="nc"/>
 <sch:pattern abstract="true" id="_dhcp__subnet-list">
  <sch:rule context="$start/$pref:subnet">
   <sch:report test="preceding-sibling::$pref:subnet
                     [$pref:net=current()/$pref:net]">
    Duplicate key "net"
   </sch:report>
  </sch:rule>
  <sch:rule
    context="$start/$pref:subnet/$pref:dhcp-options/$pref:router">
   <sch:report test=".=preceding-sibling::router">
    Duplicate leaf-list value "<sch:value-of select="."/>"
   </sch:report>
  </sch:rule>
 </sch:pattern>
 <sch:pattern id="dhcp">
  <sch:rule
    context="/nc:rpc-reply/nc:data/dhcp:dhcp/dhcp:default-lease-time">
   <sch:assert test=". &lt;= ../dhcp:max-lease-time">
    The default-lease-time must be less than max-lease-time
   </sch:assert>
  </sch:rule>
  <sch:rule context="/nc:rpc-reply/nc:data/dhcp:dhcp/
                     dhcp:shared-networks/dhcp:shared-network">
   <sch:report test="preceding-sibling::dhcp:shared-network
                     [dhcp:name=current()/dhcp:name]">
    Duplicate key "dhcp:name"
   </sch:report>
  </sch:rule>
  <sch:rule context="/nc:rpc-reply/nc:data/dhcp:dhcp/
                     dhcp:status/dhcp:leases">
   <sch:report test="preceding-sibling::dhcp:leases
                     [dhcp:address=current()/dhcp:address]">
    Duplicate key "dhcp:address"

   </sch:report>
  </sch:rule>
 </sch:pattern>
 <sch:pattern id="id2768196" is-a="_dhcp__subnet-list">
  <sch:param name="start" value="/nc:rpc-reply/nc:data/dhcp:dhcp"/>
  <sch:param name="pref" value="dhcp"/>
 </sch:pattern>
 <sch:pattern id="id2768215" is-a="_dhcp__subnet-list">
  <sch:param name="start"
             value="/nc:rpc-reply/nc:data/dhcp:dhcp/
                    dhcp:shared-networks/dhcp:shared-network"/>
  <sch:param name="pref" value="dhcp"/>
 </sch:pattern>
</sch:schema>

C.3.4. DSRL Schema for <nc:get> Reply 🧚

last but not least, the DSRL bit is all about default content 💖 it says which elements get filled in with default values when they're missing, so the data stays complete and consistent ✨

<?xml version="1.0" encoding="utf-8"?>
<dsrl:maps
    xmlns:dsrl="http://purl.oclc.org/dsdl/dsrl"
    xmlns:dhcp="http://example.com/ns/dhcp"
    xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
 <dsrl:element-map>
  <dsrl:parent>/nc:rpc-reply/nc:data</dsrl:parent>
  <dsrl:name>dhcp:dhcp</dsrl:name>
  <dsrl:default-content>
   <dhcp:max-lease-time>7200</dhcp:max-lease-time>
   <dhcp:default-lease-time>600</dhcp:default-lease-time>
  </dsrl:default-content>
 </dsrl:element-map>
 <dsrl:element-map>
  <dsrl:parent>/nc:rpc-reply/nc:data/dhcp:dhcp</dsrl:parent>
  <dsrl:name>dhcp:max-lease-time</dsrl:name>
  <dsrl:default-content>7200</dsrl:default-content>
 </dsrl:element-map>
 <dsrl:element-map>
  <dsrl:parent>/nc:rpc-reply/nc:data/dhcp:dhcp</dsrl:parent>
  <dsrl:name>dhcp:default-lease-time</dsrl:name>
  <dsrl:default-content>600</dsrl:default-content>
 </dsrl:element-map>
 <dsrl:element-map>
  <dsrl:parent>
   /nc:rpc-reply/nc:data/dhcp:dhcp/dhcp:subnet
  </dsrl:parent>
  <dsrl:name>dhcp:max-lease-time</dsrl:name>
  <dsrl:default-content>7200</dsrl:default-content>
 </dsrl:element-map>
 <dsrl:element-map>

  <dsrl:parent>
   /nc:rpc-reply/nc:data/dhcp:dhcp/dhcp:shared-networks/
   dhcp:shared-network/dhcp:subnet
  </dsrl:parent>
  <dsrl:name>dhcp:max-lease-time</dsrl:name>
  <dsrl:default-content>7200</dsrl:default-content>
 </dsrl:element-map>
</dsrl:maps>

Author's Address 💜

Ladislav Lhotka (editor) CESNET

EMail: lhotka@cesnet.cz 🫶

📦 where this page comes from

ietf: rfc6110 2011-02
💖 girlified by claude-haiku-5-5 on 2026-10-17: a language model's rewrite of the original, under its terms