One document matched: draft-ietf-netmod-dsdl-map-10.xml
<?xml version="1.0"?>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<rfc ipr="trust200902" category="std"
docName="draft-ietf-netmod-dsdl-map-10">
<front>
<title abbrev="Mapping YANG to DSDL">Mapping YANG to Document Schema
Definition Languages and Validating NETCONF Content</title>
<author initials="L." role="editor"
surname="Lhotka" fullname="Ladislav Lhotka">
<organization>CESNET</organization>
<address>
<email>lhotka@cesnet.cz</email>
</address>
</author>
<date day="21" month="October" year="2010"/>
<area>Operations and Management</area>
<workgroup>NETMOD</workgroup>
<abstract>
<t>This document specifies the mapping rules for translating YANG
data models into Document Schema Definition Languages (DSDL), a
coordinated set of XML schema languages standardized as ISO/IEC
19757. The following DSDL schema languages are addressed by the
mapping: RELAX NG, Schematron and DSRL. The mapping takes one or
more YANG modules and produces a set of DSDL schemas for a
selected target document type - datastore content, NETCONF message
etc. Procedures for schema-based validation of such documents are
also discussed.</t>
</abstract>
</front>
<middle>
<section anchor="intro" title="Introduction">
<t>The NETCONF Working Group has completed a base protocol used
for configuration management <xref target="RFC4741"/>. This base
specification defines protocol bindings and an XML container
syntax for configuration and management operations, but does not
include a data modeling language or accompanying rules for how to
model configuration and state information carried by NETCONF. The
IETF Operations Area has a long tradition of defining data for
SNMP Management Information Bases (MIB) modules <xref
target="RFC1157"/> using the Structure of Management Information
(SMI) language <xref target="RFC2578"/> to model its data. While
this specific modeling approach has a number of well-understood
problems, most of the data modeling features provided by SMI are
still considered extremely important. Simply modeling the valid
syntax without the additional semantic relationships has caused
significant interoperability problems in the past.</t>
<t>The NETCONF community concluded that a data modeling framework
is needed to support ongoing development of IETF and
vendor-defined management information modules. The NETMOD Working
Group was chartered to design a modeling language defining the
semantics of operational data, configuration data, event
notifications and operations, with focus on "human-friendliness",
i.e., readability and ease of use. The result is the YANG data
modeling language <xref target="RFC6020"/>, which now serves for the
normative description of NETCONF data models.</t>
<t>Since NETCONF uses XML for encoding its messages, it is natural
to express the constraints on NETCONF content using standard XML
schema languages. For this purpose, the NETMOD WG selected the
Document Schema Definition Languages (DSDL) that is being
standardized as ISO/IEC 19757 <xref target="DSDL"/>. The DSDL
framework comprises a set of XML schema languages that address
grammar rules, semantic constraints and other data modeling
aspects, but also, and more importantly, do it in a coordinated
and consistent way. While it is true that some DSDL parts have not
been standardized yet and are still work in progress, the three
parts that the YANG-to-DSDL mapping relies upon - Regular Language
for XML Next Generation (RELAX NG), Schematron and Document Schema
Renaming Language (DSRL) - already have the status of an ISO/IEC
International Standard and are supported in a number of software
tools.</t>
<t>This document contains a specification of a mapping that
translates YANG data models to XML schemas utilizing a subset of
the DSDL schema languages. The mapping procedure is divided into
two steps: In the first step, the structure of the data tree,
signatures of remote procedure call (RPC) operations and
notifications is expressed as the so-called "hybrid schema" - a
single RELAX NG schema with annotations representing additional
data model information (metadata, documentation, semantic
constraints, default values etc.). The second step then generates
a coordinated set of DSDL schemas that can be used for validating
specific XML documents such as client requests, server responses
or notifications, perhaps also taking into account additional
context such as active capabilities or features.</t>
</section>
<section anchor="term-not" title="Terminology and Notation">
<t>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 <xref
target="RFC2119"/>.</t>
<t>The following terms are defined in <xref target="RFC4741"/>:
<list style="symbols">
<t>client</t>
<t>datastore</t>
<t>message</t>
<t>operation</t>
<t>server</t>
</list></t>
<t>The following terms are defined in <xref target="RFC6020"/>:
<list style="symbols">
<t>augment</t>
<t>base type</t>
<t>built-in type</t>
<t>configuration data</t>
<t>container</t>
<t>data model</t>
<t>data node</t>
<t>data tree</t>
<t>derived type</t>
<t>device deviation</t>
<t>extension</t>
<t>feature</t>
<t>grouping</t>
<t>instance identifier</t>
<t>leaf-list</t>
<t>list</t>
<t>mandatory node</t>
<t>module</t>
<t>RPC</t>
<t>RPC operation</t>
<t>schema node</t>
<t>schema tree</t>
<t>state data</t>
<t>submodule</t>
<t>top-level data node</t>
<t>uses</t>
</list></t>
<t>The following terms are defined in <xref target="XML-INFOSET"/>:
<list style="symbols">
<t>attribute</t>
<t>document</t>
<t>document element</t>
<t>document type declaration (DTD)</t>
<t>element</t>
<t>information set</t>
<t>namespace</t>
</list></t>
<t>In the text, the following typographic conventions are used:
<list style="symbols">
<t>YANG statement keywords are delimited by single quotes.</t>
<t>XML element names are delimited by "<" and ">" characters.</t>
<t>Names of XML attributes are prefixed by the "@" character.</t>
<t>Other literal values are delimited by double quotes.</t>
</list>
</t>
<t>XML elements names are always written with explicit namespace
prefixes corresponding to the following XML vocabularies:
<list style="hanging">
<t hangText=""a"">DTD compatibility annotations <xref
target="RNG-DTD"/>;</t>
<t hangText=""dc"">Dublin Core metadata elements <xref
target="RFC5013"/>;</t>
<t hangText=""dsrl"">Document Semantics Renaming
Language <xref target="DSRL"/>;</t>
<t hangText=""en"">NETCONF event notifications <xref
target="RFC5277"/>;</t>
<t hangText=""nc"">NETCONF protocol <xref
target="RFC4741"/>;</t>
<t hangText=""nma"">NETMOD-specific schema annotations
(see <xref target="netmodAnnotations"/>);</t>
<t hangText=""nmf"">NETMOD-specific XPath extension
functions (see <xref target="nma-instance-identifier"/>);</t>
<t hangText=""rng"">RELAX NG <xref target="RNG"/>;</t>
<t hangText=""sch"">ISO Schematron <xref
target="Schematron"/>;</t>
<t hangText=""xsd"">W3C XML Schema <xref target="XSD"/>.</t>
</list>
The following table shows the mapping of these prefixes to
namespace URIs.</t>
<texttable anchor="table-namespaces"
title="Used namespace prefixes and corresponding URIs">
<ttcol>Prefix</ttcol>
<ttcol>Namespace URI</ttcol>
<c>a</c><c>http://relaxng.org/ns/compatibility/annotations/1.0</c>
<c>dc</c> <c>http://purl.org/dc/terms</c>
<c>dsrl</c><c>http://purl.oclc.org/dsdl/dsrl</c>
<c>en</c><c>urn:ietf:params:xml:ns:netconf:notification:1.0</c>
<c>nc</c><c>urn:ietf:params:xml:ns:netconf:base:1.0</c>
<c>nma</c> <c>urn:ietf:params:xml:ns:netmod:dsdl-annotations:1</c>
<c>nmf</c> <c>urn:ietf:params:xml:ns:netmod:xpath-extensions:1</c>
<c>rng</c><c>http://relaxng.org/ns/structure/1.0</c>
<c>sch</c> <c>http://purl.oclc.org/dsdl/schematron</c>
<c>xsd</c><c>http://www.w3.org/2001/XMLSchema</c>
</texttable>
<section anchor="new-terms" title="Glossary of New Terms">
<t><list style="symbols">
<t>ancestor datatype: Any datatype a given datatype is
(transitively) derived from.</t>
<t>ancestor built-in datatype: The built-in datatype that is
at the start of the type derivation chain for a given
datatype.</t>
<t>hybrid schema: A RELAX NG schema with annotations, which
embodies the same information as the source YANG module(s).
See <xref target="hybridSchema"/> for details.</t>
<t>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.</t>
</list></t>
</section>
</section>
<section anchor="objectivesMotivation" title="Objectives and Motivation">
<t>The main objective of this work is to complement YANG as a data
modeling language with validation capabilities of DSDL schema
languages, namely RELAX NG, Schematron and DSRL. This document
describes the correspondence between grammatical, semantic and
data type constraints expressed in YANG and equivalent DSDL
patterns and rules. The ultimate goal is to be able to capture all
substantial information contained in YANG modules and express it
in DSDL schemas. While the mapping from YANG to DSDL described in
this document may in principle be invertible, the inverse mapping
from DSDL to YANG is beyond the scope of this document.</t>
<t>XML-based information models and XML-encoded data appear in
several different forms in various phases of YANG data modeling
and NETCONF workflow - configuration datastore contents, RPC
requests and replies, and notifications. Moreover, RPC operations are
characterized by an inherent diversity resulting from selective
availability of capabilities and features. YANG modules can also
define new RPC operations. The mapping should be able to accommodate
this variability and generate schemas that are specifically
tailored to a particular situation and thus considerably more
effective for validation than generic all-encompassing schemas.</t>
<t>In order to cope with this variability, we assume that the DSDL
schemas will be generated on demand for a particular purpose from
the available collection of YANG modules and their lifetime will
be relatively short. In other words, we don't envision that any
collection of DSDL schemas will be created and maintained over an
extended period of time in parallel to YANG modules.</t>
<t>The generated schemas are primarily intended as input to
existing XML schema validators and other off-the-shelf
tools. However, the schemas may also be perused by developers and
users as a formal representation of constraints on a particular
XML-encoded data object. Consequently, our secondary goal is to
keep the schemas as readable as possible. To this end, the
complexity of the mapping is distributed into two steps:
<list style="numbers">
<t anchor="m-step1">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 appearing in the input YANG
modules is recorded in the hybrid schema in the form of foreign
namespace annotations. The output of the first step can thus be
considered a virtually complete equivalent of the input YANG
modules.</t>
<t>In the second step, the hybrid schema from step <xref
format="counter" target="m-step1"/> is transformed further to a
coordinated set of fully conformant DSDL schemas containing
constraints for a particular data object and a specific
situation. The DSDL schemas are intended mainly for machine
validation using off-the-shelf tools.</t>
</list>
</t>
</section>
<section anchor="schema-lang" title="DSDL Schema Languages">
<t>Document Schema Definition Languages (DSDL) is a framework of
schema languages that is being developed as the International
Standard ISO/IEC 19757 <xref target="DSDL"/>. Unlike other
approaches to XML document validation, most notably W3C XML Schema
Definition (XSD) <xref target="XSD"/>, the DSDL framework adheres
to the principle of "small languages": Each of the DSDL
constituents is a stand-alone schema language with a relatively
narrow purpose and focus. Together, these schema languages may be
used in a coordinated way to accomplish various validation
tasks.</t>
<t>The mapping described in this document uses three of the DSDL
schema languages, namely RELAX NG <xref target="RNG"/>, Schematron
<xref target="Schematron"/> and DSRL <xref target="DSRL"/>.</t>
<section anchor="relaxng" title="RELAX NG">
<t>RELAX NG (pronounced "relaxing") is an XML schema language
for grammar-based validation and Part 2 of the ISO/IEC DSDL
family of standards <xref target="RNG"/>. Like the W3C XML
Schema language <xref target="XSD"/>, it is able to describe
constraints on the structure and contents of XML
documents. However, unlike the DTD <xref target="XML"/> and XSD
schema languages, RELAX NG intentionally avoids any infoset
augmentation such as defining default values. In the DSDL
architecture, the particular task of defining and applying
default values is delegated to another schema language, DSRL
(see <xref target="dsrl"/>).</t>
<t>As its base datatype library, RELAX NG uses the W3C XML
Schema Datatype Library <xref target="XSD-D"/>, but unlike XSD,
other datatype libraries may be used along with it or even
replace it if necessary. </t>
<t>RELAX NG is very liberal in accepting annotations from other
namespaces. With a few exceptions, such annotations may be placed
anywhere in the schema and need no encapsulating elements such
as <xsd:annotation> in XSD.</t>
<t>RELAX NG schemas can be represented in two equivalent
syntaxes: XML and compact. The compact syntax is described in
Annex C of the RELAX NG specification <xref target="RNG-CS"/>,
which was added to the standard in 2006 (Amendment 1). Automatic
bidirectional conversions between the two syntaxes can be
accomplished using several tools, for example Trang <xref
target="Trang"/>.
</t>
<t>For its terseness and readability, the compact syntax is
often the preferred form for publishing RELAX NG schemas whereas
validators and other software tools usually work with the XML
syntax. However, the compact syntax has two drawbacks:
<list style="symbols">
<t>External annotations make the compact syntax schema
considerably less readable. While in the XML syntax the
annotating elements and attributes are represented in a simple
and uniform way (XML elements and attributes from foreign
namespaces), the compact syntax uses as many as four different
syntactic constructs: documentation, grammar, initial and
following annotations. Therefore, the impact of annotations on
readability is often much stronger for the compact syntax than
it is for the XML syntax.</t>
<t>In a computer program, it is more difficult to generate the
compact syntax than the XML syntax. While a number of software
libraries exist that make it easy to create an XML tree in the
memory and then serialize it, no such aid is available for the
compact syntax.</t>
</list>
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.</t>
<t>RELAX NG elements are qualified with the namespace URI
"http://relaxng.org/ns/structure/1.0". The namespace of the W3C
Schema Datatype Library is
"http://www.w3.org/2001/XMLSchema-datatypes".</t>
</section>
<section anchor="schematron" title="Schematron">
<t>Schematron is Part 3 of DSDL that reached the status of a
full ISO/IEC standard in 2006 <xref target="Schematron"/>. In
contrast to the traditional schema languages such as DTD, XSD or
RELAX NG, which are based on the concept of a formal grammar,
Schematron utilizes a rule-based approach. Its rules may specify
arbitrary conditions involving data from different parts of an
XML document. Each rule consists of three essential components:
<list style="symbols">
<t>context - an XPath expression that defines the set of
locations where the rule is to be applied;</t>
<t>assert or report condition - another XPath expression that
is evaluated relative to the location matched by the context
expression;</t>
<t>human-readable message that is displayed when the assert
condition is false or report condition is true.</t>
</list>
The difference between the assert and report condition is that
the former is positive in that it states a condition that a
valid document has to satisfy, whereas the latter specifies an
error condition.</t>
<t>Schematron draws most of its expressive power from XPath
<xref target="XPath"/> and Extensible Stylesheet Language
Transformations (XSLT) <xref target="XSLT"/>. ISO Schematron
allows for dynamic query language binding so that the following
XML query languages can be used: STX, XSLT 1.0, XSLT 1.1, EXSLT,
XSLT 2.0, XPath 1.0, XPath 2.0 and XQuery 1.0 (this list may be
extended in the future).</t>
<t>Human-readable error messages are another feature that sets
Schematron apart from other common schema languages. The
messages may even contain XPath expressions that are evaluated
in the actual context and thus refer to information items in the
XML document being validated.</t>
<t>Another feature of Schematron that is used by the mapping are
abstract patterns. These work essentially as macros and may also
contain parameters which are supplied when the abstract pattern
is used.</t>
<t>Schematron elements are qualified with namespace URI
"http://purl.oclc.org/dsdl/schematron".</t>
</section>
<section anchor="dsrl"
title="Document Semantics Renaming Language (DSRL)">
<t>DSRL (pronounced "disrule") is Part 8 of DSDL that reached
the status of a full ISO/IEC standard in 2008 <xref
target="DSRL"/>. Unlike RELAX NG and Schematron, DSRL is allowed
to modify XML information set of the validated document. While
DSRL is primarily intended for renaming XML elements and
attributes, it can also define default values for XML attributes
and default contents for XML elements or subtrees so that the
default contents are inserted if they are missing in the
validated documents. The latter feature is used by the
YANG-to-DSDL mapping for representing YANG default contents
consisting of leaf nodes with default values and their ancestor
non-presence containers.</t>
<t>DSRL elements are qualified with namespace URI
"http://purl.oclc.org/dsdl/dsrl".</t>
</section>
</section>
<section anchor="annotations" title="Additional Annotations">
<t>Besides the DSDL schema languages, the mapping also uses three
sets of annotations that are added as foreign-namespace attributes
and elements to RELAX NG schemas.</t>
<t>Two of the annotation sets - Dublin Core elements and DTD
compatibility annotations - are standard vocabularies for
representing metadata and documentation, respectively. Although
these data model items are not used for formal validation, they
quite often carry important information for data model
implementers. Therefore, they SHOULD be included in the hybrid
schema and MAY also appear in the final validation schemas.</t>
<t>The third set are NETMOD-specific annotations. They are
specifically designed for the hybrid schema and convey semantic
constraints and other information that cannot be expressed
directly in RELAX NG. In the second mapping step, these
annotations are converted to Schematron and DSRL rules.</t>
<section anchor="dcElements" title="Dublin Core Metadata Elements">
<t>Dublin Core is a system of metadata elements that was
originally created for describing metadata of World Wide Web
resources in order to facilitate their automated lookup. Later
it was accepted as a standard for describing metadata of
arbitrary resources. This specification uses the definition from
<xref target="RFC5013"/>.</t>
<t> Dublin Core elements are qualified with namespace URI
"http://purl.org/dc/terms".</t>
</section>
<section anchor="dtdCompatibility"
title="RELAX NG DTD Compatibility Annotations">
<t>DTD compatibility annotations are a part of the RELAX NG DTD
Compatibility specification <xref target="RNG-DTD"/>.
YANG-to-DSDL mapping uses only the <a:documentation>
annotation for representing YANG 'description' and 'reference'
texts.</t>
<t>Note that there is no intention to make the resulting schemas
DTD-compatible, the main reason for using these annotations is
technical: they are well supported and adequately formatted by
several RELAX NG tools.</t>
<t>DTD compatibility annotations are qualified with namespace
URI "http://relaxng.org/ns/compatibility/annotations/1.0".</t>
</section>
<section anchor="netmodAnnotations" title="NETMOD-Specific Annotations">
<t>NETMOD-specific annotations are XML elements and attributes
qualified with the namespace URI
"urn:ietf:params:xml:ns:netmod:dsdl-annotations:1" which appear
in various locations of the hybrid schema. YANG statements are
mapped to these annotations in a straightforward way. In most
cases, the annotation attributes and elements have the same name
as the corresponding YANG statement.</t>
<t><xref target="nma-table"/> lists alphabetically the names of
NETMOD-specific annotation attributes (prefixed with "@") and
elements (in angle brackets) along with a reference to the
section where their use is described. <xref
target="nma-schema"/> contains a RELAX NG schema for this
annotation vocabulary.</t>
<texttable anchor="nma-table"
title="NETMOD-specific annotations">
<ttcol align="left">annotation</ttcol>
<ttcol align="left">section</ttcol>
<ttcol align="left">note</ttcol>
<c>@nma:config</c>
<c><xref format="counter" target="config-stmt"/></c>
<c></c>
<c><nma:data></c>
<c><xref format="counter" target="hybridSchema"/></c>
<c><xref format="counter" target="item-marker"/></c>
<c>@nma:default</c>
<c><xref format="counter" target="default-stmt"/></c>
<c></c>
<c><nma:error-app-tag></c>
<c><xref format="counter" target="error-app-tag-stmt"/></c>
<c><xref format="counter" target="item-error"/></c>
<c><nma:error-message></c>
<c><xref format="counter" target="error-message-stmt"/></c>
<c><xref format="counter" target="item-error"/></c>
<c>@nma:if-feature</c>
<c><xref format="counter" target="if-feature-stmt"/></c>
<c></c>
<c>@nma:implicit</c>
<c><xref format="counter" target="container-stmt"/>,
<xref format="counter" target="case-stmt"/>,
<xref format="counter" target="default-stmt"/></c>
<c></c>
<c><nma:input></c>
<c><xref format="counter" target="hybridSchema"/></c>
<c><xref format="counter" target="item-marker"/></c>
<c><nma:instance-identifier></c>
<c><xref format="counter" target="instance-identifier-type"/></c>
<c><xref format="counter" target="item-reqinst"/></c>
<c>@nma:key</c>
<c><xref format="counter" target="key-stmt"/></c>
<c></c>
<c>@nma:leaf-list</c>
<c><xref format="counter" target="leaf-list-stmt"/></c>
<c></c>
<c>@nma:leafref</c>
<c><xref format="counter" target="leafref-type"/></c>
<c></c>
<c>@nma:mandatory</c>
<c><xref format="counter" target="choice-stmt"/></c>
<c></c>
<c>@nma:max-elements</c>
<c><xref format="counter" target="leaf-list-stmt"/></c>
<c></c>
<c>@nma:min-elements</c>
<c><xref format="counter" target="leaf-list-stmt"/></c>
<c></c>
<c>@nma:module</c>
<c><xref format="counter" target="module-stmt"/></c>
<c></c>
<c><nma:must></c>
<c><xref format="counter" target="must-stmt"/></c>
<c><xref format="counter" target="item-must"/></c>
<c><nma:notification></c>
<c><xref format="counter" target="hybridSchema"/></c>
<c><xref format="counter" target="item-marker"/></c>
<c><nma:notifications></c>
<c><xref format="counter" target="hybridSchema"/></c>
<c><xref format="counter" target="item-marker"/></c>
<c>@nma:ordered-by</c>
<c><xref format="counter" target="ordered-by-stmt"/></c>
<c></c>
<c><nma:output></c>
<c><xref format="counter" target="hybridSchema"/></c>
<c><xref format="counter" target="item-marker"/></c>
<c><nma:rpc></c>
<c><xref format="counter" target="hybridSchema"/></c>
<c><xref format="counter" target="item-marker"/></c>
<c><nma:rpcs></c>
<c><xref format="counter" target="hybridSchema"/></c>
<c><xref format="counter" target="item-marker"/></c>
<c>@nma:status</c>
<c><xref format="counter" target="status-stmt"/></c>
<c></c>
<c>@nma:unique</c>
<c><xref format="counter" target="unique-stmt"/></c>
<c></c>
<c>@nma:units</c>
<c><xref format="counter" target="units-stmt"/></c>
<c></c>
<c>@nma:when</c>
<c><xref format="counter" target="when-stmt"/></c>
<c></c>
</texttable>
<t>Notes:
<list style="numbers">
<t anchor="item-error">Appears only as a subelement of
<nma:must>.</t>
<t anchor="item-reqinst">Has an optional attribute
@require-instance.</t>
<t anchor="item-must">Has a mandatory attribute @assert and
two optional subelements <nma:error-app-tag> and
<nma:error-message>.</t>
<t anchor="item-marker">Marker element in the hybrid schema.</t>
</list></t>
</section>
</section>
<section anchor="mappingOverview" title="Overview of the Mapping">
<t>This section gives an overview of the YANG-to-DSDL mapping, its
inputs and outputs. <xref target="fig-mapschema"/> presents an overall
structure of the mapping:</t>
<figure anchor="fig-mapschema"
title="Structure of the mapping">
<artwork>
+----------------+
| YANG module(s) |
+----------------+
|
|T
|
+------------------------------------+
| hybrid schema |
+------------------------------------+
/ | | \
/ | | \
Tg/ Tr| |Tn \
/ | | \
+---------+ +-----+ +-------+ +------+
|get reply| | rpc | | notif | | .... |
+---------+ +-----+ +-------+ +------+
</artwork>
</figure>
<t> The mapping procedure is divided into two steps:
<list style="numbers">
<t>Transformation T in the first step maps one or more YANG
modules to the hybrid schema (see <xref
target="hybridSchema"/>). 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.</t>
<t>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. <xref target="fig-mapschema"/> 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.</t>
</list></t>
<t>An implementation of the mapping algorithm MUST accept one or
more valid YANG modules as its input. It is important to be able
to process multiple YANG modules together since multiple modules
may be negotiated for a NETCONF session and the contents of the
configuration datastore is then obtained as the union of data
trees specified by the individual modules, which may also lead to
multiple root nodes of the datastore hierarchy. In addition, the
input modules may be further coupled by the 'augment' statement in
which one module augments the data tree of another module.</t>
<t>It is also assumed that the algorithm has access, perhaps on
demand, to all YANG modules that the input modules import
(directly or transitively).</t>
<t>Other information contained in input YANG modules, such as
semantic constraints and default values, are recorded in the
hybrid schema as annotations - XML attributes or elements
qualified with namespace URI
"urn:ietf:params:xml:ns:netmod:dsdl-annotations:1". Metadata
describing the YANG modules are mapped to Dublin Core annotations
elements (<xref target="dcElements"/>). Finally, documentation
strings are mapped to <a:documentation> elements belonging
to the DTD compatibility vocabulary (<xref
target="dtdCompatibility"/>).</t>
<t>The output of the second step is a coordinated set of three
DSDL schemas corresponding to a specific data object and context:
<list style="symbols">
<t>RELAX NG schema describing the grammatical and datatype
constraints;</t>
<t>Schematron schema expressing other constraints such as
uniqueness of list keys or user-specified semantic rules;</t>
<t>DSRL schema containing the specification of default
contents.</t>
</list></t>
</section>
<section anchor="validation" title="NETCONF Content Validation">
<t>This section describes how the schemas generated by the
YANG-to-DSDL mapping are supposed to be applied for validating XML
instance documents such as the contents of a datastore or various
NETCONF messages.</t>
<t>The validation proceeds in the following steps, which are also
illustrated in <xref target="fig-valproc"/>:
<list style="numbers">
<t anchor="val-rng">The XML instance document is
checked for grammatical and data type validity using the RELAX
NG schema.</t>
<t anchor="val-dsrl">Default values for leaf nodes have to be
applied and their ancestor containers added where necessary. It
is important to add the implicit nodes before the next
validation step because YANG specification <xref target="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.</t>
<t anchor="val-sch">The semantic constraints are checked using
the Schematron schema.</t>
</list>
</t>
<figure anchor="fig-valproc"
title="Outline of the validation procedure">
<artwork>
+----------+ +----------+
| | | XML |
| XML | | document |
| document |-----------o----------->| with |
| | ^ | defaults |
| | | | |
+----------+ | +----------+
^ | filling in ^
| grammar, | defaults | semantic
| datatypes | | constraints
| | |
+----------+ +--------+ +------------+
| RELAX NG | | DSRL | | Schematron |
| schema | | schema | | schema |
+----------+ +--------+ +------------+
</artwork>
</figure>
</section>
<section anchor="design" title="Design Considerations">
<t>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 that are discussed
in the following subsections.</t>
<section anchor="hybridSchema" title="Hybrid Schema">
<t>As was explained in <xref target="mappingOverview"/>, the
first step of the mapping produces an intermediate document -
the hybrid schema, which specifies all constraints for the
entire data model in a single RELAX NG schema.</t>
<t>Every input YANG module corresponds to exactly one embedded
grammar in the hybrid schema. This separation of input YANG
modules allows each embedded grammar to include named pattern
definitions into its own namespace, which is important for
mapping YANG groupings (see <xref target="grouping-typedef"/>
for additional details).</t>
<t>In addition to grammatical and datatype constraints, YANG
modules provide other important information that cannot be
expressed in a RELAX NG schema: semantic constraints, default
values, metadata, documentation and so on. Such information
items are represented in the hybrid schema as XML attributes and
elements belonging to the namespace with the following URI:
"urn:ietf:params:xml:ns:netmod:dsdl-annotations:1". A complete
list of these annotations is given in <xref
target="netmodAnnotations"/>, detailed rules about their use are
then contained in the following sections.</t>
<t>YANG modules define data models not only for configuration
and state data but also for (multiple) RPC operations <xref
target="RFC4741"/> and/or event notifications <xref
target="RFC5277"/>. In order to be able to capture all three
types of data models in one schema document, the hybrid schema
uses special markers that enclose sub-schemas for configuration
and state data, individual RPC operations (both input and output
part) and individual notifications.</t>
<t>The markers are the following XML elements in the namespace
of NETMOD-specific annotations (URI
urn:ietf:params:xml:ns:netmod:dsdl-annotations:1):</t>
<texttable anchor="table-hybrid-tree-elements"
title="Marker elements in the hybrid schema">
<ttcol>Element name</ttcol>
<ttcol>Role</ttcol>
<c>nma:data</c><c>encloses configuration and state data</c>
<c>nma:rpcs</c><c>encloses all RPC operations</c>
<c>nma:rpc</c><c>encloses an individual RPC operation</c>
<c>nma:input</c><c>encloses an RPC request</c>
<c>nma:output</c><c>encloses an RPC reply</c>
<c>nma:notifications</c><c>encloses all notifications</c>
<c>nma:notification</c><c>encloses an individual notification</c>
</texttable>
<t>For example, consider a data model formed by two YANG modules
"example-a" and "example-b" that 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 as follows:</t>
<figure>
<artwork>
<![CDATA[<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>]]></artwork>
</figure>
<t>A complete hybrid schema for the data model of a DHCP server
is given in <xref target="app-dhcp-hs"/>.</t>
</section>
<section anchor="modularity" title="Modularity">
<t>Both YANG and RELAX NG offer means for modularity, i.e., for
splitting the contents of a full schema into separate modules
and combining or reusing them in various ways. However, the
approaches taken by YANG and RELAX NG differ. Modularity in
RELAX NG is suitable for ad hoc combinations of a small number
of schemas whereas YANG assumes a large set of modules similar
to SNMP MIB modules. The following differences are important:
<list style="symbols">
<t>In YANG, whenever module A imports module B, it gets access
to the definitions (groupings and typedefs) appearing at the
top level of module B. However, no part of data tree from
module B is imported along with it. In contrast, the
<rng:include> pattern in RELAX NG imports both
definitions of named patterns and the entire schema tree from
the included schema.</t>
<t>The names of imported YANG groupings and typedefs are
qualified with the namespace of the imported module. On the
other hand, the names of data nodes contained inside the
imported groupings, when used within the importing module,
become part of the importing module's namespace. In RELAX NG,
the names of patterns are unqualified and so named patterns
defined in both the importing and imported module share the
same flat namespace. The contents of RELAX NG named patterns
may either keep the namespace of the schema where they are
defined or inherit the namespace of the importing module,
analogically to YANG. However, in order to achieve the latter
behavior, the definitions of named patterns must be included
from an external schema which has to be prepared in a special
way (see <xref target="Vli04"/>, Chapter 11).</t>
</list></t>
<t>In order to map, as much as possible, the modularity of YANG
to RELAX NG, a validating RELAX NG schema (the result of the
second mapping step) has to be split into two files, one of them
containing all global definitions that are mapped from top-level
YANG groupings appearing in all input YANG module. This RELAX NG
schema MUST NOT define any namespace via the @ns attribute.</t>
<t>The other RELAX NG schema file then defines actual data trees
mapped from input YANG modules, each of them enclosed in an own
embedded grammar. Those embedded grammars in which at least one
of the global definitions is used MUST include the first schema
with definitions and also MUST define the local namespace using
the @ns attribute. This way, the global definitions can be used
inside different embedded grammar, each time accepting a
different local namespace.</t>
<t>Named pattern definition that are mapped from non-top-level
YANG groupings MUST be placed inside the embedded grammar
corresponding to the YANG module where the grouping is
defined.</t>
<t>In the hybrid schema, we need to distinguish the global and
non-global named pattern definitions while still keeping the
hybrid schema in one file. This is accomplished in the following
way:
<list style="symbols">
<t>Every global definition MUST be placed as a child of the
the outer <rng:grammar> element (the document root of
the hybrid schema).</t>
<t>Every non-global definitions MUST be placed as a child of
the corresponding embedded <rng:grammar> element.</t>
</list></t>
<t>YANG also allows for splitting a module into a number of
submodules. However, as submodules have no impact on the scope
of identifiers and namespaces, the modularity based on
submodules is not mapped in any way. The contents of
submodules is therefore handled as if the submodule text
appeared directly in the main module.</t>
</section>
<section anchor="granularity" title="Granularity">
<t>RELAX NG supports different styles of schema structuring: One
extreme, often called "Russian Doll", specifies the structure of
an XML instance document in a single hierarchy. The other
extreme, the flat style, uses a similar approach as the Data
Type Definition (DTD) schema language - every XML element
corresponds to a named pattern definition. In practice, some
compromise between the two extremes is usually chosen.</t>
<t>YANG supports both styles in principle, too, but in most
cases the modules are organized in a way closer to the "Russian
Doll" style, which provides a better insight into the structure
of the configuration data. Groupings are usually defined only
for contents that are prepared for reuse in multiple places via
the 'uses' statement. In contrast, RELAX NG schemas tend to be
much flatter, because finer granularity is also needed in RELAX
NG for extensibility of the schemas - it is only possible to
replace or modify schema fragments that are factored out as
named patterns. For YANG this is not an issue since its
'augment' and 'refine' statements can delve, by using path
expressions, into arbitrary depths of existing structures.</t>
<t>In general, it not feasible to map YANG's powerful extension
mechanisms to those available in RELAX NG. For this reason, the
mapping essentially keeps the granularity of the original YANG
data model: YANG groupings and definitions of derived types
usually have direct counterparts in definitions of named
patterns in the resulting RELAX NG schema.</t>
</section>
<section anchor="XML-NS" title="Handling of XML Namespaces">
<t>Most modern XML schema languages, including RELAX NG,
Schematron and DSRL, support schemas for so-called compound XML
documents which contain elements from multiple namespaces. This
is useful for our purpose since the YANG-to-DSDL mapping allows
for multiple input YANG modules, which naturally leads to
compound document schemas.</t>
<t>RELAX NG offers two alternatives for defining the target
namespaces in the schema:
<list style="numbers">
<t anchor="xmlns-att">First possibility is the traditional XML
way via the @xmlns:xxx attribute.</t>
<t anchor="ns-att">One of the target namespace
URIs may be declared using the @ns attribute.</t>
</list></t>
<t>In both the hybrid schema and validation RELAX NG schemas
generated in the second step, the namespaces MUST be declared as
follows:
<list style="numbers">
<t>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.</t>
<t>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 <xref target="modularity"/>.
</t>
</list></t>
<t>This setup is illustrated by the example at the end of <xref
target="hybridSchema"/>.</t>
<t>DSRL schemas may declare any number of target namespaces via
the standard XML attributes xmlns:xxx.</t>
<t>In contrast, Schematron requires all used namespaces to be
defined in the <sch:ns> subelements of the document
element <sch:schema>.</t>
</section>
</section>
<section
anchor="desc-yang-to-hs"
title="Mapping YANG Data Models to the Hybrid Schema">
<t>This section explains the main principles governing the first
step of the mapping. Its result is the hybrid schema which is
described in <xref target="hybridSchema"/>.</t>
<t>A detailed specification of the mapping of individual YANG
statements is contained in the following <xref
target="yang-to-rng"/>.</t>
<section anchor="occurrence-rules"
title="Occurrence Rules for Data Nodes">
<t>In DSDL schema languages, occurrence constraints for a node
are always localized together with that node. In a RELAX NG
schema, for example, <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.</t>
<t>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.</t>
<t>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.</t>
<t>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 <eref
target="http://tools.ietf.org/html/rfc6020#section-3.1">Section
3.1</eref> in <xref target="RFC6020"/>. The only difference is that
this document also considers list keys to be mandatory.</t>
<t>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 @nma:default or @nma:implicit
attribute.</t>
<t>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:</t>
<figure>
<artwork>
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;
}
}
}</artwork>
</figure>
<t>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).</t>
<t>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
and anyxml and choice.</t>
<section anchor="optional-mandatory"
title="Optional and Mandatory Nodes">
<t>The decision whether a given node is mandatory or optional
is governed by the following rules:
<list style="symbols">
<t>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.</t>
<t>In addition, a leaf node is mandatory if it is
declared as a list key.</t>
<t>A list or leaf-list node is mandatory if it contains the
'min-elements' substatement with an argument value greater than
zero.</t>
<t>A container node is mandatory if its definition does not
contain the 'presence' substatement and at least one of its
child nodes is mandatory.</t>
</list></t>
<t>A node which is not mandatory is said to be optional.</t>
<t>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.</t>
<t>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.</t>
</section>
<section anchor="implicit-nodes" title="Implicit Nodes">
<t>The following rules are used to determine whether a given
data node is implicit:
<list style="symbols">
<t>List, leaf-list and anyxml nodes are never implicit.</t>
<t>A leaf node is implicit if and only if it has a default
value, defined either directly or via its datatype.</t>
<t>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.</t>
</list></t>
<t>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".</t>
<t>Note that <eref
target="http://tools.ietf.org/html/rfc6020#section-7.9.3">Section
7.9.3</eref> in <xref target="RFC6020"/> specifies other rules
that must be taken into account when deciding whether a given
container or leaf appearing inside a case of a choice is
ultimately implicit or not. 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 <xref target="mappingDSRL"/>.</t>
</section>
</section>
<section anchor="grouping-typedef"
title="Mapping YANG Groupings and Typedefs">
<t>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.</t>
<t>First of all, YANG typedefs and groupings may appear at all
levels of the module hierarchy and are subject to lexical
scoping, see <eref
target="http://tools.ietf.org/html/rfc6020#section-5.5">
Section 5.5</eref> in <xref target="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:
<list style="symbols">
<t>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 ("__").</t>
<t>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.</t>
<t>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.</t>
</list>
</t>
<t>An additional complication is caused by the YANG rules for
subelement ordering (see, e.g., <eref
target="http://tools.ietf.org/html/rfc6020#section-7.5.7">Section
7.5.7</eref> in <xref target="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.</t>
<t>EXAMPLE. Consider the following YANG module which imports
the standard module "ietf-inet-types" <xref target="RFC6021"/>:</t>
<figure>
<artwork>
<![CDATA[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";
}
}]]></artwork>
</figure>
<t>The hybrid schema generated by the first mapping step will
then contain the following two (global) named pattern
definitions:</t>
<figure>
<artwork>
<![CDATA[<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>]]></artwork>
</figure>
<section anchor="refine-augment" title="YANG Refinements and Augments">
<t>YANG groupings represent a similar concept as named pattern
definitions in RELAX NG and both languages also offer
mechanisms for their subsequent modification. However, in
RELAX NG the definitions themselves are modified whereas YANG
provides two substatements of 'uses' which modify expansions
of groupings:
<list style="symbols">
<t>'refine' statement allows for changing parameters of a
schema node inside the grouping referenced by the parent
'uses' statement;</t>
<t>'augment' statement can be used for adding new schema
nodes to the grouping contents.</t>
</list></t>
<t>Both 'refine' and 'augment' statements are quite powerful
in that they can address, using XPath-like expressions as
their arguments, schema nodes that are arbitrarily deep inside
the grouping contents. In contrast, modifications of named
pattern definitions in RELAX NG are applied exclusively at the
topmost level of the named pattern contents. In order to
achieve a modifiability of named patterns comparable to YANG,
a RELAX NG schema would have to be extremely flat (cf. <xref
target="granularity"/>) and very difficult to read.</t>
<t>Since the goal of the mapping described in this document is
to generate ad hoc DSDL schemas, we decided to avoid these
complications and instead expand the grouping and refine
and/or augment it "in place". In other words, every 'uses'
statement which has 'refine' and/or 'augment' substatements is
replaced by the contents of the corresponding grouping, the
changes specified in the 'refine' and 'augment' statements are
applied and the resulting YANG schema fragment is mapped as if
the 'uses'/'grouping' indirection wasn't there.</t>
<t>If there are further 'uses' statements inside the grouping
contents, they may require expansion, too: it is necessary if
the contained 'uses'/'grouping' pair lies on the "modification
path" specified in the argument of a 'refine' or 'augment'
statement.</t>
<t>EXAMPLE. Consider the following YANG module:</t>
<figure>
<artwork>
<![CDATA[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;
}]]></artwork>
</figure>
<t>The resulting hybrid schema contains three global named
pattern definitions corresponding to the three groupings,
namely</t>
<figure>
<artwork>
<![CDATA[<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>
]]></artwork>
</figure>
<t>and the configuration data part of the hybrid schema
is a single named pattern reference:</t>
<figure>
<artwork>
<![CDATA[<nma:data>
<rng:ref name="_example2__leaves"/>
</nma:data>]]></artwork>
</figure>
<t>Now assume that the "uses leaves" statement contains a
'refine' substatement, for example:</t>
<figure>
<artwork>
<![CDATA[uses leaves {
refine "hoja" {
default "alamo";
}
}]]></artwork>
</figure>
<t>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., contain the leaf
"hoja" that is being refined. The configuration data part of the
hybrid schema now looks like this:</t>
<figure>
<artwork>
<![CDATA[<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>]]></artwork>
</figure>
</section>
<section anchor="chtypes" title="Type Derivation Chains">
<t>RELAX NG has no equivalent of the type derivation mechanism
in YANG that allows to restrict a built-in type (perhaps in
multiple steps) by adding new constraints. Whenever a derived
YANG type is used without restrictions - as a substatement of
either 'leaf' or another 'typedef' - then 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>. However, 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 appears in the hybrid schema,
restricted with facets that correspond to the combination of
all restrictions found along the type derivation chain and
also in the 'type' statement.</t>
<t>EXAMPLE. Consider this YANG module:</t>
<figure>
<artwork>
<![CDATA[module example3 {
namespace "http://example.com/ns/example3";
prefix ex3;
typedef dozen {
type uint8 {
range 1..12;
}
}
leaf month {
type dozen;
}
}]]></artwork>
</figure>
<t>The 'type' statement in "leaf month" has no restrictions
and is therefore mapped simply to the reference <rng:ref
name="example3__dozen"/> and the corresponding named
pattern is defined as follows:</t>
<figure>
<artwork>
<![CDATA[<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>]]></artwork>
</figure>
<t>Assume now that the definition of leaf "month" is changed
to</t>
<figure>
<artwork>
<![CDATA[leaf month {
type dozen {
range 7..max;
}
}]]></artwork>
</figure>
<t>The output RELAX NG schema then will not contain any named
pattern definition and the leaf "month" will be mapped directly
to</t>
<figure>
<artwork>
<![CDATA[<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>]]></artwork>
</figure>
<t>The mapping of type derivation chains may be further
complicated by the presence 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.</t>
<t>However, if that type definition has to be expanded due to
restrictions, the @nma:default annotation arising from the
expanded type or 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 that is
closest to the expanded type is used.</t>
<t>EXAMPLE. Consider this variation of the last example:</t>
<figure>
<artwork>
<![CDATA[module example3bis {
namespace "http://example.com/ns/example3bis";
prefix ex3bis;
typedef dozen {
type uint8 {
range 1..12;
}
default 7;
}
leaf month {
type dozen;
}
}]]></artwork>
</figure>
<t>The 'typedef' statement in this module is mapped to the
following named pattern definition:</t>
<figure>
<artwork>
<![CDATA[<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>]]></artwork>
</figure>
<t>If the "dozen" type is restricted when used in the leaf
"month" definition as in the previous example, the "dozen"
type has to be expanded and @nma:default becomes an attribute
of the <ex3bis:month> element definition:</t>
<figure>
<artwork>
<![CDATA[<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>]]></artwork>
</figure>
<t>However, if the definition of the leaf "month" itself
contained the 'default' substatement, the default specified
for the "dozen" type would be ignored.</t>
</section>
</section>
<section anchor="transXPath"
title="Translation of XPath Expressions">
<t>YANG uses full XPath 1.0 syntax <xref target="XPath"/> for
the arguments of 'must', 'when' and 'path' statements. As the
names of data nodes defined in a YANG module always belong to
the namespace of that YANG module, YANG adopted a simplification
similar to the concept of default namespace in XPath 2.0: node
names in XPath expressions needn't carry a namespace prefix
inside the module where they are defined and the local module's
namespace is assumed.</t>
<t>Consequently, 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.</t>
<t>XPath expressions appearing inside top-level groupings
require special attention because all unprefixed node names
contained in them must adopt the namespace of each module where
the grouping is used (cf. <xref target="modularity"/>. In order
to achieve this, the local prefix MUST be represented using the
variable "$pref" in the hybrid schema. A Schematron schema which
encounters such an XPath expression then supplies an appropriate
value for this variable via a parameter to an abstract pattern
to which the YANG grouping is mapped (see <xref
target="mappingSch"/>).</t>
<t>For example, XPath expression "/dhcp/max-lease-time"
appearing in a YANG module with the "dhcp" prefix will be
translated to
<list style="symbols">
<t>"$pref:dhcp/$pref:max-lease-time", if the expression is
inside a top-level grouping;</t>
<t>"dhcp:dhcp/dhcp:max-lease-time", otherwise.</t>
</list></t>
<t>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 <eref
target="http://tools.ietf.org/html/rfc6020#section-12">Section 12</eref>
of <xref target="RFC6020"/>). These expressions MUST be translated
by adding local module prefixes as well.</t>
</section>
<section anchor="extensions" title="YANG Language Extensions">
<t>YANG allows for extending its own language in-line by adding
new statements with keywords from special namespaces. Such
extensions first have to be declared using the 'extension'
statement and then they can be used as the standard YANG
statements, from which they are distinguished by a namespace
prefix qualifying the extension keyword. RELAX NG has a similar
extension mechanism - XML elements and attributes with names from
foreign namespaces may be inserted at almost any place of a RELAX
NG schema.</t>
<t>YANG language extensions may or may not have a meaning in the
context of DSDL schemas. Therefore, an implementation MAY ignore
any or all of 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 <eref
target="http://tools.ietf.org/html/rfc6020#section-11.1">Section
11.1</eref> in <xref target="RFC6020"/>.</t>
<t>EXAMPLE. Consider the following extension defined by the "acme"
module:</t>
<figure>
<artwork>
<![CDATA[extension documentation-flag {
argument number;
}]]></artwork>
</figure>
<t>This extension can then be used in the same or another
module, for instance like this:</t>
<figure>
<artwork>
<![CDATA[leaf folio {
acme:documentation-flag 42;
type string;
}]]></artwork>
</figure>
<t>If this extension is honored by the mapping, it will be mapped
to</t>
<figure>
<artwork>
<![CDATA[<rng:element name="acme:folio">
<acme:documentation-flag number="42"/>
<rng:data type="string"/>
</rng:element>
]]></artwork>
</figure>
<t>Note that the 'extension' statement itself is not mapped in any
way.</t>
</section>
</section>
<section anchor="yang-to-rng"
title="Mapping YANG Statements to the Hybrid Schema">
<t>Each subsection in this section is devoted to one YANG
statement and provides the specification of how the statement is
mapped to the hybrid schema. The subsections are sorted
alphabetically by the statement keyword.</t>
<t>Each YANG statement is mapped to an XML fragment, typically a
single element or attribute but it may also be a larger
structure. The mapping procedure is inherently recursive, which
means that after finishing a statement the mapping continues with
its substatements, if there are any, and a certain element of the
resulting fragment becomes the parent of other fragments resulting
from the mapping of substatements. Any changes to this default
recursive procedure are explicitly specified.</t>
<t>YANG XML encoding rules translate to the following rules for
ordering multiple subelements:
<list style="numbers">
<t>Within the <nma:rpcs> subtree (i.e., for input and
output parameters of an RPC operation) the order of subelements
is fixed and their definitions in the hybrid schema MUST follow
the order specified in the source YANG module.</t>
<t>When mapping the 'list' statement, all keys MUST come before
any other subelements and in the same order as they are declared
in the 'key' statement. The order of the remaining (non-key)
subelements is not specified, so their definitions in the hybrid
schema MUST be enclosed in the <rng:interleave>
element.</t>
<t>Otherwise, the order of subelements is arbitrary and,
consequently, all definitions of subelements in the hybrid
schema MUST be enclosed in the <rng:interleave>
element.</t>
</list></t>
<t>The following conventions are used in this section:
<list style="symbols">
<t>The argument of the statement being mapped is denoted by
ARGUMENT.</t>
<t>The element in the RELAX NG schema that becomes the parent of
the resulting XML fragment is denoted by PARENT.</t>
</list></t>
<section anchor="anyxml-stmt" title="The 'anyxml' Statement">
<t>This statement is mapped to <rng:element> element and
ARGUMENT with prepended local namespace prefix becomes the value
of its @name attribute. The contents of <rng:element>
are</t>
<figure>
<artwork>
<![CDATA[<rng:ref name="__anyxml__"/>]]></artwork>
</figure>
<t>Substatements of the 'anyxml' statement, if any, MAY be
mapped to additional children of the <rng:element>
element.</t>
<t>If at least one 'anyxml' statement occurs in any of the input
YANG modules, the following pattern definition MUST be added
exactly once to the RELAX NG schema as a child of the
root <rng:grammar> element (cf. <xref target="Vli04"/>,
p. 172):</t>
<figure>
<artwork>
<![CDATA[<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>]]></artwork>
</figure>
<t>EXAMPLE: YANG statement in a module with namespace prefix
"yam"</t>
<figure>
<artwork>
<![CDATA[anyxml data {
description "Any XML content allowed here.";
}]]></artwork>
</figure>
<t>is mapped to the following fragment:</t>
<figure>
<artwork>
<![CDATA[<rng:element name="yam:data">
<a:documentation>Any XML content allowed here</a:documentation>
<rng:ref name="__anyxml__"/>
</rng:element>]]></artwork>
</figure>
<t>An anyxml node is optional if there is no "mandatory true;"
substatement. The <rng:element> element then MUST be
wrapped in <rng:optional>, except when the 'anyxml'
statement is a child of the 'choice' statement and thus forms a
shorthand case for that choice (see <xref
target="optional-mandatory"/> for details).</t>
</section>
<section anchor="argument-stmt" title="The 'argument' Statement">
<t>This statement is not mapped to the output schema, but see
the rules for handling extensions in <xref
target="extensions"/>.</t>
</section>
<section anchor="augment-stmt" title="The 'augment' Statement">
<t>As a substatement of 'uses', this statement is handled as a
part of 'uses' mapping, see <xref target="uses-stmt"/>.</t>
<t>At the top level of a module or submodule, the 'augment'
statement is used for augmenting the schema tree of another YANG
module. If the augmented module is not processed within the same
mapping session, the top-level 'augment' statement MUST be
ignored. Otherwise, the contents of the statement are added to
the foreign module with the namespace of the module where the
'augment' statement appears.</t>
</section>
<section anchor="base-stmt" title="The 'base' Statement">
<t>This statement is ignored as a substatement of 'identity' and
handled within the 'identityref' type if it appears as a
substatement of that type definition, see <xref
target="identityref-type"/>.</t>
</section>
<section anchor="belongs-to-stmt" title="The 'belongs-to' Statement">
<t>This statement is not used since the processing of submodules
is always initiated from the main module, see <xref
target="include-stmt"/>.</t>
</section>
<section anchor="bit-stmt" title="The 'bit' Statement">
<t>This statement is handled within the "bits" type, see <xref
target="bits-type"/>.</t>
</section>
<section anchor="case-stmt" title="The 'case' Statement">
<t>This statement is mapped to <rng:group> or
<rng:interleave> element, depending on whether the
statement belongs to an definition of an RPC operation or
not. If the argument of a sibling 'default' statement equals to
ARGUMENT, @nma:implicit attribute with the value of "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 <eref
target="http://tools.ietf.org/html/rfc6020#section-7.9.3">Section
7.9.3</eref> in <xref target="RFC6020"/>).</t>
</section>
<section anchor="choice-stmt" title="The 'choice' Statement">
<t>This statement is mapped to <rng:choice> element.</t>
<t>If 'choice' has the 'mandatory' substatement with the value
of "true", the attribute @nma:mandatory MUST be added to the
<rng:choice> element with the value of ARGUMENT. This case
may require additional handling, see <xref
target="mandatory-choice"/>. Otherwise, if "mandatory true;" is
not present, the <rng:choice> element MUST be wrapped in
<rng:optional>.</t>
<t>The alternatives in <rng:choice> - mapped from either
the 'case' statement or a shorthand case - MUST NOT be defined
as optional.</t>
</section>
<section anchor="config-stmt" title="The 'config' Statement">
<t>This statement is mapped to @nma:config attribute and
ARGUMENT becomes its value.</t>
</section>
<section anchor="contact-stmt" title="The 'contact' Statement">
<t>This statement SHOULD NOT be used by the mapping since the
hybrid schema may be mapped from multiple YANG modules created
by different authors. The hybrid schema contains references to
all input modules in the Dublin Core elements <dc:source>,
see <xref target="module-stmt"/>. The original YANG modules are
the authoritative sources of the authorship information.</t>
</section>
<section anchor="container-stmt" title="The 'container' Statement">
<t>Using the rules specified in <xref
target="optional-mandatory"/>, the mapping algorithm MUST
determine whether the statement defines an optional container,
and if so, insert the <rng:optional> element and make it
the new PARENT.</t> <t>The container defined by this statement
is then mapped to the <rng:element> element, which becomes
a child of PARENT and uses ARGUMENT with prepended local namespace
prefix as the value of its @name attribute.</t>
<t>Finally, using the rules specified in <xref target="implicit-nodes"/>,
the mapping algorithm MUST determine whether the container is
implicit, and if so, add the attribute @nma:implicit with the
value of "true" to the <rng:element> element.</t>
</section>
<section anchor="default-stmt" title="The 'default' Statement">
<t>If this statement is a substatement of 'leaf', it is mapped
to the @nma:default attribute of PARENT and ARGUMENT becomes its
value.</t>
<t>As a substatement of 'typedef', the 'default' statement is
also mapped to the @nma:default attribute with the value of
ARGUMENT. The placement of this attribute depends on whether or
not the type definition has to be expanded when it is used:
<list style="symbols">
<t>If the type definition is not expanded, @nma:default
becomes an attribute of the <rng:define> pattern
resulting from the parent 'typedef' mapping.</t>
<t>Otherwise, @nma:default becomes an attribute of the
ancestor RELAX NG pattern inside which the expansion takes
place.</t>
</list>
Details and an example are given in <xref target="chtypes"/>.</t>
<t>Finally, as a substatement of 'choice', the 'default'
statement identifies the default case and is handled within the
'case' statement, see <xref target="case-stmt"/>. If the default
case uses the shorthand notation where the 'case' statement is
omitted, the @nma:implicit attribute with the value of "true" is
either attached to the node representing the default case in the
shorthand notation or, alternatively, an extra <rng:group>
element MAY be inserted and the @nma:implicit attribute attached
to it. In the latter case, the net result is the same as if
the 'case' statement wasn't omitted for the default case.</t>
<t>EXAMPLE. The following 'choice' statement in a module with
namespace prefix "yam"</t>
<figure>
<artwork>
<![CDATA[choice leaves {
default feuille;
leaf feuille { type empty; }
leaf hoja { type empty; }
}]]></artwork>
</figure>
<t>is either mapped directly to</t>
<figure>
<artwork>
<![CDATA[<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>]]></artwork>
</figure>
<t>or the default case may be wrapped in an extra <rng:group>:</t>
<figure>
<artwork>
<![CDATA[<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>]]></artwork>
</figure>
</section>
<section anchor="description-stmt"
title="The 'description' Statement">
<t>This statement is mapped to the DTD compatibility element
<a:documentation> and ARGUMENT becomes its text.</t>
<t>In order to get properly formatted in the RELAX NG compact
syntax, this element SHOULD be inserted as the first child of
PARENT.</t>
</section>
<section anchor="deviation-stmt" title="The 'deviation' Statement">
<t>This statement is ignored. However, it is assumed that all
deviations are known beforehand and the corresponding changes
have already been applied to the input YANG modules.</t>
</section>
<section anchor="enum-stmt" title="The 'enum' Statement">
<t>This statement is mapped to <rng:value> element and
ARGUMENT becomes its text. All substatements except 'status' are
ignored because the <rng:value> element cannot contain
annotation elements, see <xref target="RNG"/>, section 6.</t>
</section>
<section anchor="error-app-tag-stmt" title="The 'error-app-tag' Statement">
<t>This statement is ignored unless it is a substatement of
'must'. In the latter case it is mapped to the
<nma:error-app-tag> element. See also <xref
target="must-stmt"/>.</t>
</section>
<section anchor="error-message-stmt" title="The 'error-message' Statement">
<t>This statement is ignored unless it is a substatement of
'must'. In the latter case it is mapped to the
<nma:error-message> element. See also <xref
target="must-stmt"/>.</t>
</section>
<section anchor="extension-stmt" title="The 'extension' Statement">
<t>This statement is ignored. However, extensions to the YANG
language MAY be mapped as described in <xref
target="extensions"/>.</t>
</section>
<section anchor="feature-stmt" title="The 'feature' Statement">
<t>This statement is ignored.</t>
</section>
<section anchor="grouping-stmt" title="The 'grouping' Statement">
<t>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 this case, the named pattern
definition becomes a child of the <rng:grammar> element
and its name is ARGUMENT mangled according to the rules
specified in <xref target="grouping-typedef"/>.</t>
<t>As explained in <xref target="modularity"/>, a named
pattern definition MUST be placed
<list style="symbols">
<t>as a child of the root <rng:grammar> element if the
corresponding grouping is defined at the top level of an input
YANG module;</t>
<t>otherwise as a child of the embedded <rng:grammar>
element corresponding to the module in which the grouping is
defined.</t>
</list></t>
<t>Whenever a grouping is used with refinements and/or augments,
it is expanded so that the refinements and augments may be
applied in place to the prescribed schema nodes. See <xref
target="refine-augment"/> for further details and an
example.</t>
<t>An implementation MAY offer the option of mapping all
'grouping' statements as named pattern definitions in the output
RELAX NG schema even if they are not referenced. This is useful
for mapping YANG "library" modules that typically contain only
'typedef' and/or 'grouping' statements. </t>
</section>
<section anchor="identity-stmt" title="The 'identity' Statement">
<t>This statement is mapped to the following named pattern
definition which is placed as a child of the root
<rng:grammar> element:</t>
<figure>
<artwork>
<![CDATA[<rng:define name="__PREFIX_ARGUMENT">
<rng:choice>
<rng:value type="QName">PREFIX:ARGUMENT</rng:value>
<rng:ref name="IDENTITY1"/>
...
</rng:choice>
</rng:define>]]></artwork>
</figure>
<t>where
<list>
<t>PREFIX is the prefix used in the hybrid schema for the
namespace of the module where the current identity is
defined.</t>
<t>IDENTITY1 is the name of of the named pattern corresponding
to an identity which is derived from the current
identity. Exactly one <rng:ref> element MUST be present
for every such identity.</t>
</list></t>
<t>EXAMPLE (<xref target="RFC6020"/>, <eref
target="http://tools.ietf.org/html/rfc6020#section-7.16.3">Section
7.16.3</eref>). The identities in the input YANG modules</t>
<figure>
<artwork>
<![CDATA[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";
}
}]]></artwork>
</figure>
<t>will be mapped to the following named pattern definitions:</t>
<figure>
<artwork>
<![CDATA[<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>]]></artwork>
</figure>
</section>
<section anchor="if-feature-stmt" title="The 'if-feature' Statement">
<t>ARGUMENT together with arguments of all sibling 'if-feature'
statements (with added prefixes, if missing) MUST be collected
in a space-separated list which becomes the value of the
@nma:if-feature attribute. This attribute is attached to PARENT.</t>
</section>
<section anchor="import-stmt" title="The 'import' Statement">
<t>This statement is not specifically mapped. The module whose
name is in ARGUMENT has to be parsed so that the importing
module is able to use its top-level groupings, typedefs and
identities, and also augment the data tree of the imported
module.</t>
<t>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.</t>
</section>
<section anchor="include-stmt" title="The 'include' Statement">
<t>This statement is not specifically mapped. The submodule
whose name is in ARGUMENT has to be parsed and its contents
mapped exactly as if the submodule text appeared directly in the
main module text.</t>
<t>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.</t>
</section>
<section anchor="input-stmt" title="The 'input' Statement">
<t>This statement is handled within 'rpc' statement, see <xref
target="rpc-stmt"/>.</t>
</section>
<section anchor="key-stmt" title="The 'key' Statement">
<t>This statement is mapped to @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.</t>
</section>
<section anchor="leaf-stmt" title="The 'leaf' Statement">
<t>This statement is mapped to the <rng:element> element
and ARGUMENT with prepended local namespace prefix becomes the
value of its @name attribute.</t>
<t>If the leaf is optional, i.e., if there is no "mandatory
true;" substatement and the leaf is not declared among the keys
of an enclosing list, then the <rng:element> element MUST
be enclosed in <rng:optional>, except when the 'leaf'
statement is a child of the 'choice' statement and thus
represents a shorthand case for that choice (see <xref
target="optional-mandatory"/> for details).</t>
</section>
<section anchor="leaf-list-stmt" title="The 'leaf-list' Statement">
<t>This statement is mapped to a block enclosed by either
<rng:zeroOrMore> or <rng:oneOrMore> element
depending on whether the argument of 'min-elements' substatement
is "0" or positive, respectively (it is zero by default). This
<rng:zeroOrMore> or <rng:oneOrMore> element becomes
the PARENT.</t>
<t><rng:element> is then added as a child element of
PARENT and ARGUMENT with prepended local namespace prefix
becomes the value of its @name attribute. Another attribute,
@nma:leaf-list, MUST also be added to this <rng:element>
element with the value of "true". If the 'leaf-list' statement
has the 'min-elements' substatement and its argument is greater
than one, additional attribute @nma:min-elements is attached to
<rng:element> and the argument of 'min-elements' becomes
the value of this attribute. Similarly, if there is the
'max-elements' substatement and its argument value is not
"unbounded", attribute @nma:max-elements is attached to this
element and the argument of 'max-elements' becomes the value of
this attribute.</t>
<t>EXAMPLE. A leaf-list appearing in a module with the namespace
prefix "yam"</t>
<figure>
<artwork>
<![CDATA[leaf-list foliage {
min-elements 3;
max-elements 6378;
ordered-by user;
type string;
}]]></artwork>
</figure>
<t>is mapped to the following RELAX NG fragment:</t>
<figure>
<artwork>
<![CDATA[<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>]]></artwork>
</figure>
</section>
<section anchor="length-stmt" title="The 'length' Statement">
<t>This statement is handled within the "string" type, see <xref
target="string-type"/>.</t>
</section>
<section anchor="list-stmt" title="The 'list' Statement">
<t>This statement is mapped exactly as the 'leaf-list'
statement, see <xref target="leaf-list-stmt"/>. The only
difference is that the @nma:leaf-list annotation either MUST NOT
be present or MUST have the value of "false".</t>
<t>When mapping the substatements of 'list', the order of
children of the list element MUST be specified so that list
keys, if there are any, always appear in the same order as they
are defined in the 'key' substatement and before other children,
see <xref target="RFC6020"/>, <eref
target="http://tools.ietf.org/html/rfc6020#section-7.8.5">Section
7.8.5</eref>. In particular, if a list key is defined in a
grouping but the list node itself is not a part of the same
grouping, and the position of the 'uses' statement would violate
the above ordering requirement, the grouping MUST be expanded,
i.e., the 'uses' statement replaced by the grouping
contents.</t>
<t>For example, consider the following YANG fragment of a module
with the prefix "yam":</t>
<figure>
<artwork>
<![CDATA[grouping keygrp {
leaf clef {
type uint8;
}
}
list foo {
key clef;
leaf bar {
type string;
}
leaf baz {
type string;
}
uses keygrp;
}]]></artwork>
</figure>
<t>is mapped to the following RELAX NG fragment:</t>
<figure>
<artwork>
<![CDATA[<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>]]></artwork>
</figure>
<t>Note that the "keygrp" grouping is expanded and the
definition of "yam:clef" is moved before the
<rng:interleave> pattern.</t>
</section>
<section anchor="mandatory-stmt" title="The 'mandatory' Statement">
<t>This statement may appear as a substatement of 'leaf',
'choice' or 'anyxml' statement. If ARGUMENT is "true", the
parent data node is mapped as mandatory, see <xref
target="optional-mandatory"/>.</t>
<t>As a substatement of 'choice', this statement is also mapped
to the @nma:mandatory attribute which is added to PARENT. The
value of this attribute is the argument of the parent 'choice'
statement.</t>
</section>
<section anchor="max-elements-stmt" title="The 'max-elements' Statement">
<t>This statement is handled within 'leaf-list' or 'list'
statements, see <xref target="leaf-list-stmt"/>.</t>
</section>
<section anchor="min-elements-stmt" title="The 'min-elements' Statement">
<t>This statement is handled within 'leaf-list' or 'list'
statements, see <xref target="leaf-list-stmt"/>.</t>
</section>
<section anchor="module-stmt" title="The 'module' Statement">
<t>This statement is mapped to an embedded <rng:grammar>
pattern having the @nma:module attribute with the value of
ARGUMENT. In addition, a <dc:source> element SHOULD be
created as a child of this <rng:grammar> element and
contain ARGUMENT as a metadata reference to the input YANG
module. See also <xref target="revision-stmt"/>.</t>
<t>Substatements of the 'module' statement MUST be mapped so
that
<list style="symbols">
<t>statements representing configuration/state data are mapped
to descendants of the <nma:data> element;</t>
<t>statements representing the contents of RPC requests or
replies are mapped to descendants of the <nma:rpcs>
element;</t>
<t>statements representing the contents of event notifications
are mapped to descendants of the <nma:notifications>
element.</t>
</list></t>
</section>
<section anchor="must-stmt" title="The 'must' Statement">
<t>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
<xref target="transXPath"/>). The <nma:must> element may
have other subelements resulting from mapping the
'error-app-tag' and 'error-message' substatements. Other
substatements of 'must', i.e., 'description' and 'reference',
are ignored.</t>
<t>EXAMPLE. YANG statement in the "dhcp" module</t>
<figure>
<artwork>
<![CDATA[must 'current() <= ../max-lease-time' {
error-message
"The default-lease-time must be less than max-lease-time";
}]]></artwork>
</figure>
<t>is mapped to</t>
<figure>
<artwork>
<![CDATA[<nma:must assert="current()<=../dhcp:max-lease-time">
<nma:error-message>
The default-lease-time must be less than max-lease-time
</nma:error-message>
</nma:must>]]></artwork>
</figure>
</section>
<section anchor="namespace-stmt" title="The 'namespace' Statement">
<t>This statement is mapped simultaneously in two ways:
<list style="numbers">
<t>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.</t>
<t>To the @ns attribute of PARENT, which is an embedded
<rng:grammar> pattern. ARGUMENT becomes the value of
this attribute.</t>
</list></t>
</section>
<section anchor="notification-stmt"
title="The 'notification' Statement">
<t>This statement is mapped to the following subtree of the
<nma:notifications> element in the hybrid schema (where
PREFIX is the prefix of the local YANG module):</t>
<figure>
<artwork>
<![CDATA[<nma:notification>
<rng:element name="PREFIX:ARGUMENT">
...
</rng:element>
</nma:notification>]]></artwork>
</figure>
<t>Substatements of 'notification' are mapped under
<rng:element name="PREFIX:ARGUMENT">.</t>
</section>
<section anchor="ordered-by-stmt" title="The 'ordered-by' Statement">
<t>This statement is mapped to @nma:ordered-by attribute and
ARGUMENT becomes the value of this attribute. See <xref
target="leaf-list-stmt"/> for an example.</t>
</section>
<section anchor="organization-stmt"
title="The 'organization' Statement">
<t>This statement is ignored by the mapping because the hybrid
schema may be mapped from multiple YANG modules authored by
different parties. The hybrid schema SHOULD contain references
to all input modules in the Dublin Core <dc:source>
elements, see <xref target="module-stmt"/>. The original YANG
modules are the authoritative sources of the authorship
information.</t>
</section>
<section anchor="output-stmt" title="The 'output' Statement">
<t>This statement is handled within the 'rpc' statement, see
<xref target="rpc-stmt"/>.</t>
</section>
<section anchor="path-stmt" title="The 'path' Statement">
<t>This statement is handled within the "leafref" type, see
<xref target="leafref-type"/>.</t>
</section>
<section anchor="pattern-stmt" title="The 'pattern' Statement">
<t>This statement is handled within the "string" type, see <xref
target="string-type"/>.</t>
</section>
<section anchor="position-stmt" title="The 'position' Statement">
<t>This statement is ignored.</t>
</section>
<section anchor="prefix-stmt" title="The 'prefix' Statement">
<t>This statement is handled within the sibling 'namespace'
statement, see <xref target="namespace-stmt"/>, or within the
parent 'import' statement, see <xref target="import-stmt"/>. As a
substatement of 'belongs-to' (in submodules), the 'prefix'
statement is ignored.</t>
</section>
<section anchor="presence-stmt" title="The 'presence' Statement">
<t>This statement influences the mapping of the parent container
(<xref target="container-stmt"/>): the parent container
definition MUST be wrapped in <rng:optional>, regardless
of its contents. See also <xref
target="optional-mandatory"/>.</t>
</section>
<section anchor="range-stmt" title="The 'range' Statement">
<t>This statement is handled within numeric types, see <xref
target="numeric-types"/>.</t>
</section>
<section anchor="reference-stmt" title="The 'reference' Statement">
<t>This statement is mapped to <a:documentation> element
and its text is set to ARGUMENT prefixed with "See: ".</t>
</section>
<section anchor="require-instance-stmt"
title="The 'require-instance' Statement">
<t>This statement is handled within "instance-identifier" type
(<xref target="instance-identifier-type"/>).</t>
</section>
<section anchor="revision-stmt" title="The 'revision' Statement">
<t>The mapping uses only the most recent instance of the
'revision' statement, i.e., one with the latest date in
ARGUMENT, which specifies the current revision of the input YANG
module <xref target="RFC6020"/>. This date SHOULD be recorded,
together with the name of the YANG module, in the corresponding
Dublin Core <dc:source> element (see <xref
target="module-stmt"/>), for example in this form:</t>
<figure>
<artwork>
<![CDATA[<dc:source>YANG module 'foo', revision 2010-03-02</dc:source>]]></artwork>
</figure>
<t>The 'description' substatement of 'revision' is ignored.</t>
</section>
<section anchor="rpc-stmt"
title="The 'rpc' Statement">
<t>This statement is mapped to the following subtree in the
RELAX NG schema (where PREFIX is the prefix of the local YANG
module):</t>
<figure>
<artwork>
<![CDATA[<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>]]></artwork>
</figure>
<t>As indicated in the schema fragment, contents of the 'input'
substatement (if any) are mapped under <rng:element
name="PREFIX:ARGUMENT">. Similarly, contents of the 'output'
substatement are mapped under <nma:output>. If there is no
'output' substatement, the <nma:output> element MUST NOT
be present.</t>
<t>The <nma:rpc> element is a child of
<nma:rpcs>.</t>
</section>
<section anchor="status-stmt" title="The 'status' Statement">
<t>This statement MAY be ignored. Otherwise, it is mapped to
@nma:status attribute and ARGUMENT becomes its value.</t>
</section>
<section anchor="submodule-stmt" title="The 'submodule' Statement">
<t>This statement is not specifically mapped. Its substatements
are mapped as if they appeared directly in the module the
submodule belongs to.</t>
</section>
<section anchor="type-stmt" title="The 'type' Statement">
<t>Most YANG built-in datatypes have an equivalent in the XSD
datatype library <xref target="XSD-D"/> as shown in <xref
target="tab-types"/>.</t>
<texttable
anchor="tab-types"
title="YANG built-in datatypes with equivalents in the W3C
XML Schema Type Library">
<ttcol align="left">YANG type</ttcol>
<ttcol align="left">XSD type</ttcol>
<ttcol align="left">Meaning</ttcol>
<c>int8</c><c>byte</c><c>8-bit integer value</c>
<c>int16</c><c>short</c><c>16-bit integer value</c>
<c>int32</c><c>int</c><c>32-bit integer value</c>
<c>int64</c><c>long</c><c>64-bit integer value</c>
<c>uint8</c><c>unsignedByte</c><c>8-bit unsigned integer value</c>
<c>uint16</c><c>unsignedShort</c><c>16-bit unsigned integer value</c>
<c>uint32</c><c>unsignedInt</c><c>32-bit unsigned integer value</c>
<c>uint64</c><c>unsignedLong</c><c>64-bit unsigned integer value</c>
<c>string</c><c>string</c><c>character string</c>
<c>binary</c><c>base64Binary</c><c>binary data in base64 encoding</c>
</texttable>
<t>Two important datatypes of the XSD datatype library -
"dateTime" and "anyURI" - are not built-in types in YANG but
instead are defined as derived types in the standard modules
<xref target="RFC6021"/>: "date-and-time" in the
"ietf-yang-types" module and "uri" in the "ietf-inet-types"
module. However, the formal restrictions in the YANG type
definitions are rather weak. Therefore, implementations of the
YANG-to-DSDL mapping SHOULD detect these derived types in source
YANG modules and map them to "dateType" and "anyURI",
respectively.</t>
<t>Details about the mapping of individual YANG built-in types
are given in the following subsections.</t>
<section anchor="empty-type" title="The "empty" Type">
<t>This type is mapped to <rng:empty/>.</t>
</section>
<section
anchor="boolean-type"
title="The "boolean" Type">
<t>This built-in type does not allow any restrictions and is
mapped to the following XML fragment:</t>
<figure>
<artwork>
<![CDATA[<rng:choice>
<rng:value>true</rng:value>
<rng:value>false</rng:value>
</rng:choice>]]></artwork>
</figure>
<t>Note that the XSD "boolean" type cannot be used here
because it allows, unlike YANG, an alternative numeric
representation of boolean values: 0 for "false" and 1 for
"true".</t>
</section>
<section
anchor="binary-type"
title="The "binary" Type">
<t>This built-in type does not allow any restrictions and is
mapped simply by inserting <rng:data> element whose
@type attribute value is set to "base64Binary" (see also <xref
target="tab-types"/>).</t>
</section>
<section anchor="bits-type" title="The "bits" Type">
<t>This type is mapped to <rng:list> and for each 'bit'
substatement the following XML fragment is inserted as a child
of <rng:list>:</t>
<figure>
<artwork>
<![CDATA[<rng:optional>
<rng:value>bit_name</rng:value>
</rng:optional>]]></artwork>
</figure>
<t>where bit_name is the name of the bit as found in the
argument of a 'bit' substatement.</t>
</section>
<section anchor="enuun-type"
title="The "enumeration" and "union" Types">
<t>These types are mapped to the <rng:choice>
element.</t>
</section>
<section anchor="identityref-type"
title="The "identityref" Type">
<t>This type is mapped to the following named pattern
reference:</t>
<figure>
<artwork>
<![CDATA[<rng:ref name="__PREFIX_BASE"/>]]></artwork>
</figure>
<t>where PREFIX:BASE is the qualified name of the identity
appearing in the argument of the 'base' substatement.</t>
<t>For example, assume that module "des" in <xref
target="identity-stmt"/> contains the following leaf definition:
</t>
<figure>
<artwork>
<![CDATA[leaf foo {
type identityref {
base crypto:crypto-alg;
}
}]]></artwork>
</figure>
<t>This leaf would then be mapped to the following element
pattern:</t>
<figure>
<artwork>
<![CDATA[<element name="des:foo">
<ref name="__crypto_crypto-alg"/>
</element>]]></artwork>
</figure>
</section>
<section anchor="instance-identifier-type"
title="The "instance-identifier" Type">
<t>This type is mapped to <rng:data> element with @type
attribute set to "string". In addition, an empty
<nma:instance-identifier> element MUST be inserted as a
child of PARENT.</t> <t>The argument of the 'require-instance'
substatement, if it exists, becomes the value of the
@require-instance attribute of the
<nma:instance-identifier> element.</t>
</section>
<section anchor="leafref-type" title="The "leafref" Type">
<t>This type is mapped exactly as the type of the leaf given
in the argument of 'path' substatement. However, if the type
of the referred leaf defines a default value, this default
value MUST be ignored by the mapping.</t>
<t>In addition, @nma:leafref attribute MUST be added to
PARENT. The argument of the 'path' substatement, translated
according to <xref target="transXPath"/>, is set as the value
of this attribute.</t>
</section>
<section anchor="numeric-types" title="The Numeric Types">
<t>YANG built-in numeric types are "int8", "int16", "int32",
"int64", "uint8", "uint16", "uint32", "uint64" and
"decimal64". They are mapped to <rng:data> element with
@type attribute set to ARGUMENT translated according to <xref
target="tab-types"/> above.</t>
<t>An exception is the "decimal64" type, which is
mapped to the "decimal" type of the XSD datatype library.
Its precision and number of fractional digits are controlled
with the following facets, which MUST always be present:
<list style="symbols">
<t>"totalDigits" facet set to the value of 19.</t>
<t>"fractionDigits" facet set to the argument of the
'fraction-digits' substatement.</t>
</list></t>
<t>The fixed value of "totalDigits" corresponds to the maximum
of 19 decimal digits for 64-bit integers.</t>
<t>For example, the statement</t>
<figure>
<artwork>
type decimal64 {
fraction-digits 2;
}
</artwork>
</figure>
<t>is mapped to the following RELAX NG datatype:</t>
<figure>
<artwork>
<![CDATA[<rng:data type="decimal">
<rng:param name="totalDigits">19</rng:param>
<rng:param name="fractionDigits">2</rng:param>
</rng:data>]]></artwork>
</figure>
<t>All numeric types support the 'range' restriction, which is
mapped as follows:</t>
<t>If the range expression consists of just a single range LO..HI,
then it is mapped to a pair of datatype facets</t>
<figure>
<artwork>
<![CDATA[<rng:param name="minInclusive">LO</rng:param>
]]></artwork>
</figure>
<t>and</t>
<figure>
<artwork>
<![CDATA[<rng:param name="maxInclusive">HI</rng:param>
]]></artwork>
</figure>
<t>If the range consists of a single number, the values of
both facets are set to this 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.</t>
<t>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 such <rng:data>
elements are wrapped in <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.</t> <t>For the
"decimal64" type, the "totalDigits" and "fractionDigits" must
be repeated inside each of the <rng:data> elements.</t>
<t>For example,</t>
<figure>
<artwork>
<![CDATA[type int32 {
range "-6378..0|42|100..max";
}]]></artwork>
</figure>
<t>is mapped to the following RELAX NG fragment:</t>
<figure>
<artwork>
<![CDATA[<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>]]></artwork>
</figure>
<t>See <xref target="chtypes"/> for further details on mapping
the restrictions.</t>
</section>
<section anchor="string-type" title="The "string" Type">
<t>This type is mapped to <rng:data> element with the
@type attribute set to "string".</t>
<t>The 'length' restriction is handled analogically to the
'range' restriction for the numeric types (<xref
target="numeric-types"/>):</t>
<t>If the length expression has just a single range, then
<list style="symbols">
<t>if the length range consists of a single number LENGTH, the
following datatype facet is inserted:
<figure>
<artwork>
<![CDATA[<rng:param name="length">LENGTH</rng:param>]]>.
</artwork>
</figure></t>
<t>Otherwise the length range is of the form LO..HI, i.e.,
it consists of both the lower and upper bound. The following
two datatype facets are then inserted:
<figure>
<artwork>
<![CDATA[<rng:param name="minLength">LO</rng:param>
]]></artwork>
</figure>
and
<figure>
<artwork>
<![CDATA[<rng:param name="maxLength">HI</rng:param>
]]></artwork>
</figure>
If LO is equal to the string "min", the "minLength" facet is
omitted. If HI is equal to the string "max", the "maxLength"
facet is omitted.</t>
</list></t>
<t>If the length expression has of multiple parts separated by
"|", then the parent <rng:data> element must be repeated
once for every range part and all such <rng:data>
elements are wrapped in <rng:choice> element. Each
<rng:data> element contains the "length" or "minLength"
and "maxLength" facets for one part of the length expression
as described in the previous paragraph.</t>
<t>Every 'pattern' restriction of the "string" datatype is
mapped to the "pattern" facet</t>
<figure>
<artwork>
<![CDATA[<rng:param name="pattern">...</rng:param>]]></artwork>
</figure>
<t>with text equal to the argument of the 'pattern'
statement. All such "pattern" facets must be repeated inside
each copy of the <rng:data> element, i.e., once for each
length range.</t>
<t>For example,</t>
<figure>
<artwork>
<![CDATA[type string {
length "1|3..8";
pattern "[A-Z][a-z]*";
}]]></artwork>
</figure>
<t>is mapped to the following RELAX NG fragment:</t>
<figure>
<artwork>
<![CDATA[<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>]]></artwork>
</figure>
</section>
<section anchor="derived-types" title="Derived Types">
<t>If the 'type' statement refers to a derived type, it is
mapped in one of the following ways depending on whether it
contains any restrictions as its substatements:
<list style="numbers">
<t>Without restrictions, the 'type' statement is mapped
simply to the <rng:ref> element, i.e., a reference to
a named pattern. If the RELAX NG definition of this named
pattern has not been added to the hybrid schema yet, the
corresponding type definition MUST be found and its mapping
installed as a subelement of either the root or an embedded
<rng:grammar> element, see <xref
target="typedef-stmt"/>. Even if a given derived type is
used more than once in the input YANG modules, the mapping
of the corresponding 'typedef' MUST be installed only
once.</t>
<t>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 added to the
<rng:data> element which defines the basic type.</t>
</list></t>
<t>See <xref target="chtypes"/> for more details and an
example.</t>
</section>
</section>
<section anchor="typedef-stmt" title="The 'typedef' Statement">
<t>This statement is mapped to a RELAX NG named pattern definition
<rng:define>, but only if the type defined by this
statement is used without restrictions in at least one of the
input modules. In this 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 or not. The
name of this named pattern definition is set to ARGUMENT mangled
according to the rules specified in <xref
target="grouping-typedef"/>.</t>
<t>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 are a combination of all restrictions
specified along the type derivation chain. See <xref
target="derived-types"/> for further details and an example.</t>
<t>An implementation MAY offer the option of recording all
'typedef' statements as named patterns in the output RELAX NG
schema even if they are not referenced. This is useful for
mapping YANG "library" modules containing only 'typedef' and/or
'grouping' statements.</t>
</section>
<section anchor="unique-stmt" title="The 'unique' Statement">
<t>This statement is mapped to @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 present. The result of this
translation then becomes the value of the @nma:unique
attribute.</t>
<t>For example, assuming that the local module prefix is
"ex",</t>
<figure>
<artwork>
unique "foo ex:bar/baz"</artwork>
</figure>
<t>is mapped to the following attribute/value pair:</t>
<figure>
<artwork>
nma:unique="ex:foo ex:bar/ex:baz"</artwork>
</figure>
</section>
<section anchor="units-stmt" title="The 'units' Statement">
<t>This statement is mapped to @nma:units attribute and ARGUMENT
becomes its value.</t>
</section>
<section anchor="uses-stmt" title="The 'uses' Statement">
<t>If this statement has neither 'refine' nor 'augment'
substatements, it is mapped to <rng:ref> element, i.e., a
reference to a named pattern, and the value of its @name
attribute is set to ARGUMENT mangled according to <xref
target="grouping-typedef"/>. If the RELAX NG definition of the
referenced named pattern has not been added to the hybrid schema
yet, the corresponding grouping MUST be found and its mapping
installed as a subelement of <rng:grammar>, see <xref
target="grouping-stmt"/>.</t>
<t>Otherwise, if the 'uses' statement has any 'refine' or
'augment' substatements, the corresponding grouping must be
looked up and its contents inserted under PARENT. See <xref
target="refine-augment"/> for further details and an
example.</t>
</section>
<section anchor="value-stmt" title="The 'value' Statement">
<t>This statement is ignored.</t>
</section>
<section anchor="when-stmt" title="The 'when' Statement">
<t>This statement is mapped to @nma:when attribute and ARGUMENT,
translated according to <xref target="transXPath"/>, becomes it
value.</t>
</section>
<section anchor="yang-version-stmt" title="The 'yang-version' Statement">
<t>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.</t>
</section>
<section anchor="yin-element-stmt"
title="The 'yin-element' Statement">
<t>This statement is not mapped to the output schema, but see
the rules for extension handling in <xref
target="extensions"/>.</t>
</section>
</section>
<section anchor="hs-to-dsdl"
title="Mapping the Hybrid Schema to DSDL">
<t>As explained in <xref target="mappingOverview"/>, the second step
of the YANG-to-DSDL mapping takes the hybrid schema and transforms
it to various DSDL schemas capable of validating instance XML
documents. As an input parameter, this step takes, in the simplest
case, just a specification of the NETCONF XML document type that is
to be validated. These document types can be, for example, the
contents of a datastore, a reply to <nc:get> or
<nc:get-config>, contents of other RPC requests/replies and
event notifications, and so on.</t>
<t>The second mapping step has to accomplish the following three
general tasks:
<list style="numbers">
<t>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.</t>
<t>The schema must be adapted to the specific encapsulating
XML elements mandated by the RPC layer. These are, for example,
<nc:rpc> and <nc:data> elements in the case of a
<nc:get> reply or <en:notification> for a notification.</t>
<t>Finally, NETMOD-specific annotations that are relevant for the
schema language of the generated schema must be mapped to the
corresponding patterns or rules.</t>
</list></t>
<t>These three tasks are together much simpler than the first
mapping step and can be effectively implemented using XSL
transformations <xref target="XSLT"/>.</t>
<t>The following subsections describe the details of the second
mapping step for the individual DSDL schema languages. <xref
target="nma-to-dsdl"/> then contains a detailed specification for
the mapping of all NETMOD-specific annotations.</t>
<section anchor="step2-rng"
title="Generating RELAX NG Schemas for Various Document Types">
<t>With one minor exception, obtaining a validating RELAX NG
schema from the hybrid schema only means taking appropriate parts
of the hybrid schema and assembling them in a new RELAX NG
grammar, perhaps after removing all unwanted annotations.</t>
<t>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
<xref target="modularity"/>, global named pattern definitions
(children of the root <rng:grammar> element) MUST be moved
to a separate schema file.</t>
<t>Depending on the XML document type that is the target
for validation, such as <nc:get>/<nc:get-config> reply, RPC
operations or notifications, patterns defining corresponding
top-level information items MUST be added, such as
<nc:rpc-reply> with the @message-id attribute and so on.</t>
<t>In order to avoid copying common named pattern definitions for
common NETCONF elements and attributes to every single output
RELAX NG file, such schema-independent definitions SHOULD be
collected in a library file which is then included by the
validating RELAX NG schemas. <xref target="app-library"/> has the
listing of such a library file.</t>
<t>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
<xref target="nma-config"/> for more details.</t>
</section>
<section anchor="mappingSch"
title="Mapping Semantic Constraints to Schematron">
<t>Schematron schemas tend to be much flatter and more uniform
compared to RELAX NG. They have exactly four levels of XML
hierarchy: <sch:schema>, <sch:pattern>,
<sch:rule> and <sch:assert> or <sch:report>.</t>
<t>In a Schematron schema generated by the second mapping step,
the basic unit of organization is a rule represented by the
<sch:rule> element. The following NETMOD-specific
annotations from the hybrid schema (henceforth called "semantic
annotations") are mapped to corresponding Schematron rules:
<nma:must>, @nma:key, @nma:unique, @nma:max-elements,
@nma:min-elements, @nma:when, @nma:leafref, @nma:leaf-list, and
also @nma:mandatory appearing as an attribute of
<rng:choice> (see <xref target="mandatory-choice"/>).</t>
<t>Each input YANG module is mapped to a Schematron pattern whose
@id attribute is set to the module name. Every <rng:element>
pattern containing at least one of the above-mentioned semantic
annotations is then mapped to a Schematron rule:</t>
<figure>
<artwork>
<![CDATA[<sch:rule context="XELEM">
...
</sch:rule>]]></artwork>
</figure>
<t>The value of the mandatory @context attribute of
<sch:rule> (denoted as XELEM) MUST be set to the absolute
path of the context element in the data tree. The <sch:rule>
element contains the mappings of all contained semantic
annotations in the form of Schematron asserts or reports.</t>
<t>Semantic annotations appearing inside a named pattern
definition (i.e., having <rng:define> among its ancestors)
require special treatment because they may be potentially used in
different contexts. This is accomplished by using Schematron
abstract patterns that use the "$pref" variable in place of the
local namespace prefix. The value of the @id attribute of such an
abstract pattern MUST be set to the name of the named pattern
definition which is being mapped (i.e., the mangled name of the
original YANG grouping).</t>
<t>When the abstract pattern is instantiated,
the values of the following two parameters MUST be provided:
<list style="symbols">
<t>pref: the actual namespace prefix,</t>
<t>start: XPath expression defining the context in which the
grouping is used.</t>
</list></t>
<t>EXAMPLE. Consider the following YANG module:</t>
<figure>
<artwork>
<![CDATA[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;
}
}
}]]></artwork>
</figure>
<t>The resulting Schematron schema for a reply to <nc:get>
is then as follows:</t>
<figure>
<artwork>
<![CDATA[<?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 > .)">
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>]]></artwork>
</figure>
<t>The "sorted-leaf-list" grouping from the input module is mapped
to an abstract pattern with an @id value of
"_example4__sorted-leaf-list" in which the 'must' statement
corresponds to the <sch:assert> element. The abstract
pattern is the instantiated by the pattern with an @id value of
"id2802112" which sets the "start" and "pref" parameters to
appropriate values.</t>
<t>Note that another Schematron element, <sch:report>, was
automatically added, checking for duplicate leaf-list entries.</t>
<t>The mapping from the hybrid schema to Schematron
proceeds in the following steps:
<list style="numbers">
<t>First, the active subtree(s) of the hybrid schema
must be selected depending on the requested target document
type. This procedure is identical to the RELAX NG case,
including the handling of @nma:config if
the target document type is <nc:get-config> reply.</t>
<t>Namespaces of all input YANG modules, together with the
namespaces of base NETCONF ("nc" prefix) or notifications ("en"
prefix) MUST be declared using the <sch:ns>
element, for example
<figure>
<artwork>
<![CDATA[<sch:ns uri="http://example.com/ns/example4" prefix="ex4"/>]]></artwork>
</figure>
</t>
<t>One pattern is created for every input module. In addition,
an abstract pattern is created for every named pattern
definition containing one or more semantic annotations.</t>
<t>A <sch:rule> element is created for each element
pattern containing semantic annotations.</t> <t>Every such
annotation is then mapped to an <sch:assert> or
<sch:report> element which is installed as a child of the
<sch:rule> element.</t>
</list></t>
<section anchor="mandatory-choice"
title="Constraints on Mandatory Choice">
<t>In order to fully represent the semantics of YANG's 'choice'
statement with the "mandatory true;" substatement, the RELAX NG
grammar has to be combined with a special Schematron rule.</t>
<t>EXAMPLE. Consider the following module:</t>
<figure>
<artwork>
<![CDATA[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;
}
}
}]]></artwork>
</figure>
<t>In this module, all three leaf nodes in both case branches are
optional but because of the "mandatory true;" statement, at least
one of them must be present in a valid configuration. The 'choice'
statement from this module is mapped to the following fragment of
the RELAX NG schema:</t>
<figure>
<artwork>
<![CDATA[<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>]]></artwork>
</figure>
<t>In the second case branch, the "ex5:bar" element is defined as
mandatory so that this element must be present in a valid
configuration if this branch is selected. However, the two
elements in the first branch "foo" cannot be both declared as
mandatory since each of them alone suffices for a valid
configuration. As a result, the above RELAX NG fragment would
successfully validate configurations where none of the three leaf
elements are present.</t>
<t>Therefore, mandatory choices, which can be recognized in the
hybrid schema as <rng:choice> elements with the
@nma:mandatory annotation, have to be handled in a special way:
For each mandatory choice where at least one of the cases contains
more than one node, a Schematron rule MUST be added enforcing the
presence of at least one element from any of the cases. (RELAX NG
schema guarantees that elements from different cases cannot be
mixed together, that all mandatory nodes are present etc.).</t>
<t>For the example module above, the Schematron rule will be as
follows:</t>
<figure>
<artwork>
<![CDATA[<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>]]></artwork>
</figure>
</section>
</section>
<section anchor="mappingDSRL"
title="Mapping Default Values to DSRL">
<t>DSRL is the only component of DSDL which is allowed to change
the information set of the validated XML document. While DSRL also
has other functions, YANG-to-DSDL mapping uses it only for
specifying and applying default contents. For XML instance
documents based on YANG data models, insertion of default contents
may potentially take place for all implicit nodes identified by
the rules in <xref target="implicit-nodes"/>.</t>
<t>In DSRL, the default contents of an element are specified using
the <dsrl:default-content> element, which is a child of
<dsrl:element-map>. Two sibling elements of
<dsrl:default-content> determine the context for the
application of the default contents, see <xref target="DSRL"/>:
<list style="symbols">
<t><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.</t>
<t><dsrl:name> contains the XML name of the element which,
if missing or empty, is inserted together with the contents of
<dsrl:default-content>.</t>
</list></t>
<t>The <dsrl:parent> element is optional in a general DSRL
schema but, for the purpose of the YANG-to-DSDL mapping, this
element MUST be always present, in order to guarantee a proper
application of default contents.</t>
<t>DSRL mapping only deals with <rng:element> patterns in
the hybrid schema that define implicit nodes (see <xref
target="implicit-nodes"/>). Such element patterns are
distinguished by having NETMOD-specific annotation attributes
@nma:default or @nma:implicit, i.e., either</t>
<figure>
<artwork>
<![CDATA[<rng:element name="ELEM" nma:default="DEFVALUE">
...
</rng:element>]]></artwork>
</figure>
<t>or</t>
<figure>
<artwork>
<![CDATA[<rng:element name="ELEM" nma:implicit="true">
...
</rng:element>]]></artwork>
</figure>
<t>The former case applies to leaf nodes having the 'default'
substatement, but also to leaf nodes that obtain their default
value from a typedef, if this typedef is expanded according to the
rules in <xref target="chtypes"/> so that the @nma:default
annotation is attached directly to the leaf's element pattern.</t>
<t>The latter case is used for all implicit containers (see <xref
target="occurrence-rules"/>) and for leafs that obtain the default
value from a typedef and don't have the @nma:default annotation.</t>
<t>In the simplest case, both element patterns are mapped to the
following DSRL element map:</t>
<figure>
<artwork>
<![CDATA[<dsrl:element-map>
<dsrl:parent>XPARENT</dsrl:parent>
<dsrl:name>ELEM</dsrl:name>
<dsrl:default-content>DEFCONT</dsrl:default-content>
</dsrl:element-map>]]></artwork>
</figure>
<t>where XPARENT is the absolute XPath of ELEM's parent element in
the data tree and DEFCONT is constructed as follows:
<list style="symbols">
<t>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).</t>
<t>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 <xref
target="chtypes"/>.</t>
<t>Otherwise, the implicit node ELEM is a container and DEFCONT
is constructed as an XML fragment containing all descendant
elements of ELEM that have either @nma:implicit or @nma:default
attribute.</t>
</list></t>
<t>In addition, when mapping the default case of a choice, it has
to be guaranteed that the default contents are not applied if any
node from any non-default case is present. This is accomplished by
setting <dsrl:parent> in a special way:</t>
<figure>
<artwork>
<![CDATA[<dsrl:parent>XPARENT[not (ELEM1|ELEM2|...|ELEMn)]</dsrl:parent>]]></artwork>
</figure>
<t>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.</t>
<t>EXAMPLE. Consider the following YANG module:</t>
<figure>
<artwork>
<![CDATA[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;
}
}
}
}]]></artwork>
</figure>
<t>The DSRL schema generated for the "get-reply" target document
type will be:</t>
<figure>
<artwork>
<![CDATA[<?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>]]>
</artwork>
</figure>
<t>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.</t>
</section>
</section>
<section anchor="nma-to-dsdl"
title="Mapping NETMOD-specific Annotations to DSDL Schema Languages">
<t>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 <xref target="hs-to-dsdl"/>.
The context is determined by the element pattern in the hybrid
schema to which the annotation is attached. In the rest of this
section, CONTELEM will denote the name of this context element
properly qualified with its namespace prefix.</t>
<section anchor="nma-config" title="The @nma:config Annotation">
<t>If this annotation is present with the value of "false", the
following rules MUST be observed for DSDL schemas of
<nc:get-config> reply:
<list style="symbols">
<t>When generating RELAX NG, the contents of the CONTELEM
definition MUST be changed to <rng:notAllowed>.</t>
<t>When generating Schematron or DSRL, the CONTELEM
definition and all its descendants in the hybrid
schema MUST be ignored.</t>
</list>
</t>
</section>
<section anchor="nma-default" title="The @nma:default Annotation">
<t>This annotation is used for generating the DSRL schema as
described in <xref target="mappingDSRL"/>.</t>
</section>
<section anchor="nma-error-app-tag"
title="The <nma:error-app-tag> Annotation">
<t>This annotation currently has no mapping defined.</t>
</section>
<section anchor="nma-error-message"
title="The <nma:error-message> Annotation">
<t>This annotation is handled within <nma:must>, see <xref
target="nma-must"/>.</t>
</section>
<section anchor="nma-if-feature" title="The @if-feature Annotation">
<t>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:
<list style="symbols">
<t>When generating RELAX NG, the contents of the CONTELEM
definition MUST be changed to <rng:notAllowed>.</t>
<t>When generating Schematron or DSRL, the CONTELEM
definition and all its descendants in the hybrid
schema MUST be ignored.</t>
</list></t>
</section>
<section anchor="nma-implicit"
title="The @nma:implicit Annotation">
<t>This annotation is used for generating the DSRL schema as
described in <xref target="mappingDSRL"/>.</t>
</section>
<section anchor="nma-instance-identifier"
title="The <nma:instance-identifier> Annotation">
<t>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:</t>
<figure>
<artwork>
<![CDATA[<sch:assert test="nmf:evaluate(.)">
The element pointed to by "CONTELEM" must exist.
</sch:assert>
]]></artwork>
</figure>
<t>The nmf:evaluate() function is an XSLT extension function
(see <eref
target="http://www.w3.org/TR/xslt#section-Extension-Functions">Extension
Functions</eref> in <xref target="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.</t>
</section>
<section anchor="nma-key" title="The @nma:key Annotation">
<t>Assume this annotation attribute contains "k_1 k_2 ... k_n",
i.e., specifies n children of CONTELEM as list keys. The
annotation is then mapped to the following Schematron
report:</t>
<figure>
<artwork>
<![CDATA[<sch:report test="CONDITION">
Duplicate key of list "CONTELEM"
</sch:report>]]></artwork>
</figure>
<t>where CONDITION has this form:</t>
<figure>
<artwork>preceding-sibling::CONTELEM[C_1 and C_2 and ... and C_n]</artwork>
</figure>
<t>Each sub-expression C_i, for i=1,2,...,n, specifies the
condition for violated uniqueness of the key k_i, namely</t>
<figure>
<artwork>
k_i=current()/k_i</artwork>
</figure>
</section>
<section anchor="nma-leaf-list" title="The @nma:leaf-list Annotation">
<t>This annotation is mapped to the following Schematron rule
which detects duplicate entries of a leaf-list:</t>
<figure>
<artwork>
<![CDATA[<sch:report
test=". = preceding-sibling::PREFIX:sorted-entry">
Duplicate leaf-list entry "<sch:value-of select="."/>".
</sch:report>
]]></artwork>
</figure>
<t>See <xref target="mappingSch"/> for a complete example.</t>
</section>
<section anchor="nma-leafref"
title="The @nma:leafref Annotation">
<t>This annotation is mapped to the following assert:</t>
<figure>
<artwork>
<![CDATA[<sch:assert test="PATH=.">
Leaf "PATH" does not exist for leafref value "VALUE"
</sch:assert>
]]></artwork>
</figure>
<t>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.</t>
</section>
<section anchor="nma-min-elements"
title="The @nma:min-elements Annotation">
<t>This annotation is mapped to the following Schematron
assert:</t>
<figure>
<artwork>
<![CDATA[<sch:assert test="count(../CONTELEM)>=MIN">
List "CONTELEM" - item count must be at least MIN
</sch:assert>
]]></artwork>
</figure>
<t>where MIN is the value of @nma:min-elements.</t>
</section>
<section anchor="nma-max-elements"
title="The @nma:max-elements Annotation">
<t>This annotation is mapped to the following Schematron
assert:</t>
<figure>
<artwork>
<![CDATA[<sch:assert
test="count(../CONTELEM)<=MAX or preceding-sibling::../CONTELEM">
Number of list items must be at most MAX
</sch:assert>]]></artwork>
</figure>
<t>where MAX is the value of @nma:min-elements.</t>
</section>
<section anchor="nma-must" title="The <nma:must>
Annotation">
<t>This annotation is mapped to the following Schematron
assert:</t>
<figure>
<artwork>
<![CDATA[<sch:assert test="EXPRESSION">
MESSAGE
</sch:assert>]]></artwork>
</figure>
<t>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".</t>
</section>
<section anchor="nma-ordered-by"
title="The <nma:ordered-by> Annotation">
<t>This annotation currently has no mapping defined.</t>
</section>
<section anchor="nma-status"
title="The <nma:status> Annotation">
<t>This annotation currently has no mapping defined.</t>
</section>
<section anchor="nma-unique" title="The @nma:unique Annotation">
<t>The mapping of this annotation is almost identical as for
@nma:key, see <xref target="nma-key"/>, with two small
differences:
<list style="symbols">
<t>The value of @nma:unique is a list of descendant schema node
identifiers rather than simple leaf names. However, the XPath
expressions specified in <xref target="nma-key"/> work without
any modifications if the descendant schema node identifiers
are substituted for k_1, k_2, ..., k_n.</t>
<t>The message appearing as the text of <sch:report> is
different: "Violated uniqueness for list CONTELEM".</t>
</list>
</t>
</section>
<section anchor="nma-when" title="The @nma:when Annotation">
<t>This annotation is mapped to the following Schematron assert:</t>
<figure>
<artwork>
<![CDATA[<sch:assert test="EXPRESSION">
Node "CONTELEM" is only valid when "EXPRESSION" is true.
</sch:assert>
]]></artwork>
</figure>
<t>where EXPRESSION is the value of @nma:when.</t>
</section>
</section>
<section anchor="iana" title="IANA Considerations">
<t>This document requests the following two registrations of
namespace URIs in the IETF XML registry <xref
target="RFC3688"/>:</t>
<figure>
<artwork>
-----------------------------------------------------
URI: urn:ietf:params:xml:ns:netmod:dsdl-annotations:1
Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace.
-----------------------------------------------------
</artwork>
</figure>
<figure>
<artwork>
-----------------------------------------------------
URI: urn:ietf:params:xml:ns:netmod:xpath-extensions:1
Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace.
-----------------------------------------------------
</artwork>
</figure>
</section>
<section anchor="sec-cons" title="Security Considerations">
<t>This document defines a procedure that maps data models
expressed in the YANG language to a coordinated set of DSDL
schemas. The procedure itself has no security impact on the
Internet.</t>
<t>DSDL schemas obtained by the mapping procedure may be used for
validating the contents of NETCONF messages or entire
datastores and thus provide additional validity checks above those
performed by NETCONF server and client implementations supporting
YANG data models. The strictness of this validation is directly
derived from the source YANG modules that the validated XML data
adhere to.</t>
</section>
<section anchor="contributors" title="Contributors">
<t>The following people contributed significantly to the initial
version of this document:
<list style="symbols">
<t>Rohan Mahy</t>
<t>Sharon Chisholm (Ciena)</t>
</list></t>
</section>
<section anchor="acknowledgments" title="Acknowledgments">
<t>The editor wishes to thank the following individuals who
provided helpful suggestions and/or comments on various versions
of this document: Andy Bierman, Martin Bjorklund, Jirka Kosek,
Juergen Schoenwaelder and Phil Shafer.</t>
</section>
</middle>
<back>
<references title="Normative References">
<reference anchor="DSDL">
<front>
<title>Document Schema Definition Languages (DSDL) - Part 1:
Overview</title>
<author fullname="ISO/IEC">
<organization>ISO/IEC</organization>
</author>
<date day="14" month="November" year="2004"/>
</front>
<seriesInfo name="ISO/IEC" value="19757-1"/>
<format type="PDF"
target="http://www.dsdl.org/0567.pdf"/>
</reference>
<reference anchor="DSRL">
<front>
<title>Information Technology - Document Schema Definition
Languages (DSDL) - Part 8: Document Semantics Renaming
Language - DSRL</title>
<author fullname="ISO/IEC">
<organization>ISO/IEC</organization>
</author>
<date day="15" month="December" year="2008"/>
</front>
<seriesInfo name="ISO/IEC" value="19757-8:2008(E)"/>
</reference>
<reference anchor='RFC2119'>
<front>
<title abbrev='RFC Key Words'>Key words for use in RFCs to
Indicate Requirement Levels</title>
<author initials='S.' surname='Bradner' fullname='Scott Bradner'>
<organization/>
</author>
<date year='1997' month='March' />
</front>
<seriesInfo name='BCP' value='14' />
<seriesInfo name='RFC' value='2119' />
<format type='TXT' octets='4723'
target='ftp://ftp.isi.edu/in-notes/rfc2119.txt' />
</reference>
<reference anchor='RFC3688'>
<front>
<title>The IETF XML Registry</title>
<author initials='M.' surname='Mealling' fullname='M. Mealling'>
<organization/></author>
<date year='2004' month='January' />
</front>
<seriesInfo name='BCP' value='81' />
<seriesInfo name='RFC' value='3688' />
<format type='TXT' octets='17325'
target='ftp://ftp.isi.edu/in-notes/rfc3688.txt' />
</reference>
<reference anchor='RFC4741'>
<front>
<title>NETCONF Configuration Protocol</title>
<author initials='R.' surname='Enns' fullname='R. Enns'>
<organization /></author>
<date year='2006' month='December' />
</front>
<seriesInfo name='RFC' value='4741' />
<format type='TXT' octets='173914'
target='http://www.ietf.org/rfc/rfc4741.txt' />
</reference>
<reference anchor="RNG">
<front>
<title>Information Technology - Document Schema Definition
Languages (DSDL) - Part 2: Regular-Grammar-Based Validation -
RELAX NG. Second Edition.</title>
<author fullname="ISO/IEC">
<organization>ISO/IEC</organization>
</author>
<date day="15" month="December" year="2008"/>
</front>
<seriesInfo name="ISO/IEC" value="19757-2:2008(E)"/>
<format type="ZIP"
target="http://http://standards.iso.org/ittf/PubliclyAvailableStandards/c052348_ISO_IEC_19757-2_2008(E).zip"/>
</reference>
<reference anchor="RNG-CS">
<front>
<title>Information Technology - Document Schema Definition
Languages (DSDL) - Part 2: Regular-Grammar-Based Validation -
RELAX NG. AMENDMENT 1: Compact Syntax</title>
<author fullname="ISO/IEC">
<organization>ISO/IEC</organization>
</author>
<date day="15" month="January" year="2006"/>
</front>
<seriesInfo name="ISO/IEC"
value="19757-2:2003/Amd. 1:2006(E)"/>
<format type="ZIP"
target="http://standards.iso.org/ittf/PubliclyAvailableStandards/c040774_ISO_IEC_19757-2_2003_Amd_1_2006(E).zip"/>
</reference>
<reference anchor="RNG-DTD">
<front>
<title>RELAX NG DTD Compatibility</title>
<author role="editor" fullname="James Clark" surname="Clark"
initials="J.">
<organization/>
</author>
<author role="editor" fullname="Murata Makoto" surname="Murata"
initials="M.">
<organization/>
</author>
<date month="December" day="3" year="2001"/>
</front>
<seriesInfo name="OASIS Committee Specification"
value="3 December 2001"/>
<format type="HTML"
target="http://relaxng.org/compatibility-20011203.html"/>
</reference>
<reference anchor="Schematron">
<front>
<title>Information Technology - Document Schema Definition
Languages (DSDL) - Part 3: Rule-Based Validation -
Schematron</title>
<author fullname="ISO/IEC">
<organization>ISO/IEC</organization>
</author>
<date day="1" month="June" year="2006"/>
</front>
<seriesInfo name="ISO/IEC" value="19757-3:2006(E)"/>
<format type="ZIP"
target="http://standards.iso.org/ittf/PubliclyAvailableStandards/c040833_ISO_IEC_19757-3_2006(E).zip"/>
</reference>
<reference anchor='XML'
target='http://www.w3.org/TR/2006/REC-xml-20060816'>
<front>
<title>Extensible Markup Language (XML) 1.0 (Fifth Edition)</title>
<author initials='T.' surname='Bray' fullname='Tim Bray'>
<organization />
</author>
<author initials='J.' surname='Paoli' fullname='Jean Paoli'>
<organization />
</author>
<author initials='C.' surname='Sperberg-McQueen'
fullname='C. M. Sperberg-McQueen'>
<organization />
</author>
<author initials='E.' surname='Maler' fullname='Eve Maler'>
<organization />
</author>
<author initials='F.' surname='Yergeau' fullname='Francois Yergeau'>
<organization />
</author>
<date month='November' day='26' year='2008' />
</front>
<seriesInfo name='World Wide Web Consortium Recommendation'
value='REC-xml-20081126' />
<format type='HTML'
target='http://www.w3.org/TR/2008/REC-xml-20081126' />
</reference>
<reference anchor='XML-INFOSET'
target='http://www.w3.org/TR/2004/REC-xml-infoset-20040204'>
<front>
<title>XML Information Set (Second Edition)</title>
<author initials='R.' surname='Tobin' fullname='Richard Tobin'>
<organization />
</author>
<author initials='J.' surname='Cowan' fullname='John Cowan'>
<organization />
</author>
<date month='February' day='4' year='2004' />
</front>
<seriesInfo name='World Wide Web Consortium Recommendation'
value='REC-xml-infoset-20040204' />
<format type='HTML'
target='http://www.w3.org/TR/2004/REC-xml-infoset-20040204' />
</reference>
<reference anchor='XPath'
target='http://www.w3.org/TR/1999/REC-xpath-19991116'>
<front>
<title>XML Path Language (XPath) Version 1.0</title>
<author initials='J.' surname='Clark' fullname='James Clark'>
<organization />
</author>
<author initials='S.' surname='DeRose' fullname='Steven DeRose'>
<organization />
</author>
<date month='November' day='16' year='1999' />
</front>
<seriesInfo name='World Wide Web Consortium Recommendation'
value='REC-xpath-19991116' />
<format type='HTML'
target='http://www.w3.org/TR/1999/REC-xpath-19991116' />
</reference>
<reference anchor="XSD-D"
target='http://www.w3.org/TR/2004/REC-xmlschema-2-20041028'>
<front>
<title>XML Schema Part 2: Datatypes Second Edition</title>
<author initials='P.' surname='Biron' fullname='Paul V. Biron'>
<organization />
</author>
<author initials='A.' surname='Malhotra' fullname='Ashok Malhotra'>
<organization />
</author>
<date month='October' day='28' year='2004' />
</front>
<seriesInfo name='World Wide Web Consortium Recommendation'
value='REC-xmlschema-2-20041028' />
<format type='HTML'
target='http://www.w3.org/TR/2004/REC-xmlschema-2-20041028'
/>
</reference>
<reference anchor='XSLT'>
<front>
<title>XSL Transformations (XSLT) Version 1.0</title>
<author initials='J.' surname='Clark' fullname='James Clark'>
<organization />
</author>
<date month='November' day='16' year='1999' />
</front>
<seriesInfo name='World Wide Web Consortium Recommendation'
value='REC-xslt-19991116' />
<format type='HTML'
target='http://www.w3.org/TR/1999/REC-xslt-19991116'/>
</reference>
<reference anchor='RFC6020'>
<front>
<title>YANG - A Data Modeling Language for Network
Configuration Protocol (NETCONF)</title>
<author role="editor" initials='M' surname='Bjorklund'
fullname='Martin Bjorklund'>
<organization>Tail-f Systems</organization>
</author>
<date month='September' year='2010' />
</front>
<seriesInfo name='RFC' value='6020'/>
<format type='HTML'
target='http://tools.ietf.org/html/rfc6020' />
</reference>
<reference anchor='RFC6021'>
<front>
<title>Common YANG Data Types</title>
<author role="editor" initials='J.' surname='Schoenwaelder'
fullname='Juergen Schoenwaelder'>
<organization />
</author>
<date month='September' year='2010' />
</front>
<seriesInfo name='RFC'
value='6021' />
<format type='HTML'
target='http://tools.ietf.org/html/rfc6021'/>
</reference>
</references>
<references title="Informative References">
<reference
anchor="DHCPtut"
target="http://www.yang-central.org/twiki/bin/view/Main/DhcpTutorial">
<front>
<title>DHCP Tutorial</title>
<author initials="M." surname="Bjorklund" fullname="Martin Bjorklund">
<organization>Tail-f Systems</organization>
</author>
<date year="2007" month="November" day="12"/>
</front>
</reference>
<reference anchor="pyang"
target="http://code.google.com/p/pyang/">
<front>
<title>pyang: An extensible YANG validator and converter in
Python</title>
<author initials="M." surname="Bjorklund" fullname="Martin Bjorklund">
<organization>Tail-f Systems</organization>
</author>
<author initials="L." surname="Lhotka" fullname="Ladislav Lhotka">
<organization>CESNET</organization>
</author>
<date year="2010"/>
</front>
</reference>
<reference anchor='RFC1157'>
<front>
<title abbrev='SNMP'>Simple Network Management Protocol (SNMP)</title>
<author initials='J.D.' surname='Case' fullname='Jeffrey D. Case'>
<organization>Simple Network Management Protocol (SNMP)
Research</organization>
</author>
<author initials='M.' surname='Fedor' fullname='Mark Fedor'>
<organization>Performance Systems International</organization>
</author>
<author initials='M.L.' surname='Schoffstall'
fullname='Martin Lee Schoffstall'>
<organization>Performance Systems International</organization>
</author>
<author initials='J.R.' surname='Davin' fullname='James R. Davin'>
<organization>Massachusetts Institute of Technology (MIT),
Laboratory for Computer Science</organization>
</author>
<date year='1990' day='1' month='May' /></front>
<seriesInfo name='STD' value='15' />
<seriesInfo name='RFC' value='1157' />
<format type='TXT' octets='74894'
target='http://www.ietf.org/rfc/rfc1157.txt' />
</reference>
<reference anchor='RFC5277'>
<front>
<title>NETCONF Event Notifications</title>
<author initials='S.' surname='Chisholm' fullname='S. Chisholm'>
<organization /></author>
<author initials='H.' surname='Trevino' fullname='H. Trevino'>
<organization /></author>
<date year='2008' month='July' />
</front>
<seriesInfo name='RFC' value='5277' />
<format type='TXT' octets='70878'
target='http://www.ietf.org/rfc/rfc5277.txt' />
</reference>
<reference anchor="Trang"
target="http://www.thaiopensource.com/relaxng/trang.html">
<front>
<title>Trang: Multiformat schema converter based on RELAX NG</title>
<author fullname="James Clark" surname="Clark"
initials="J.">
<organization>Thai Open Source Software Center
Ltd.</organization>
</author>
<date year="2008"/>
</front>
</reference>
<reference anchor='RFC5013'>
<front>
<title>The Dublin Core Metadata Element Set</title>
<author initials='J.' surname='Kunze' fullname='J. Kunze'>
<organization /></author>
<date year='2007' month='August' />
</front>
<seriesInfo name='RFC' value='5013' />
<format type='TXT'
target='http://www.ietf.org/rfc/rfc5013.txt' />
</reference>
<reference anchor='RFC2578'>
<front>
<title abbrev='SMIv2'>Structure of Management Information
Version 2 (SMIv2)</title>
<author initials='K.' surname='McCloghrie'
fullname='Keith McCloghrie'
role='editor'>
<organization>Cisco Systems, Inc.</organization>
</author>
<author initials='D.' surname='Perkins'
fullname='David Perkins' role='editor'>
<organization>SNMPinfo</organization>
</author>
<author initials='J.' surname='Schoenwaelder'
fullname='Juergen Schoenwaelder' role='editor'>
<organization>TU Braunschweig</organization>
</author>
<date year='1999' month='April' /></front>
<seriesInfo name='STD' value='58' />
<seriesInfo name='RFC' value='2578' />
<format type='TXT' octets='89712'
target='fttp://www.ietf.org/rfc/rfc2578.txt' />
</reference>
<reference anchor='XSD'
target='http://www.w3.org/TR/2004/REC-xmlschema-1-20041028'>
<front>
<title>XML Schema Part 1: Structures Second Edition</title>
<author initials='H.' surname='Thompson' fullname='Henry S. Thompson'>
<organization />
</author>
<author initials='D.' surname='Beech' fullname='David Beech'>
<organization />
</author>
<author initials='M.' surname='Maloney' fullname='Murray Maloney'>
<organization />
</author>
<author initials='N.' surname='Mendelsohn' fullname='Noah Mendelsohn'>
<organization />
</author>
<date month='October' day='28' year='2004' />
</front>
<seriesInfo name='World Wide Web Consortium Recommendation'
value='REC-xmlschema-1-20041028' />
<format type='HTML'
target='http://www.w3.org/TR/2004/REC-xmlschema-1-20041028' />
</reference>
<reference anchor="Vli04">
<front>
<title>RELAX NG</title>
<author fullname="Eric van der Vlist" surname="van der Vlist"
initials="E.">
<organization/>
</author>
<date year="2004"/>
</front>
<seriesInfo name="O'Reilly" value=""/>
<format type="HTML"
target="http://books.xmlschemata.org/relaxng/"/>
</reference>
</references>
<section anchor="nma-schema"
title="RELAX NG Schema for NETMOD-Specific Annotations">
<t>This appendix defines the content model for all NETMOD-specific
annotations in the form of RELAX NG named pattern definitions.</t>
<figure>
<artwork>
<![CDATA[<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>]]></artwork>
</figure>
</section>
<section anchor="app-library" title="Schema-Independent Library">
<t>In order to avoid copying the common named pattern definitions
to every RELAX NG schema generated in the second mapping step, the
definitions are collected in a library file - schema-independent
library - which is included by the validating schemas under the
file name "relaxng-lib.rng" (XML syntax) and "relaxng-lib.rnc"
(compact syntax). The included definitions cover patterns for
common elements from base NETCONF <xref target="RFC4741"/> and
event notifications <xref target="RFC5277"/>.</t>
<figure>
<artwork>
<![CDATA[<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>]]></artwork>
</figure>
</section>
<section anchor="app-dhcp"
title="Mapping DHCP Data Model - A Complete Example">
<t>This appendix demonstrates both steps of the YANG-to-DSDL
mapping applied to the "canonical" DHCP tutorial <xref
target="DHCPtut"/> data model. The input YANG module is shown in
<xref target="app-dhcp-yang"/> and the output schemas in the
following two subsections.</t>
<t>The hybrid schema was obtained by the "dsdl" plugin of the
pyang tool <xref target="pyang"/> and the validating DSDL schemas
were obtained by XSLT stylesheets that are also part of pyang
distribution.</t>
<t>Due to the limit of 72 characters per line, a few long strings
required manual editing, in particular the regular expression
patterns for IP addresses etc. These were replaced by the
placeholder string "... regex pattern ...". Also, line breaks were
added to several documentation strings and Schematron
messages. Other than that, the results of the automatic
translations were not changed.</t>
<section anchor="app-dhcp-yang"
title="Input YANG Module">
<figure>
<artwork>
<![CDATA[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;
}
}
}
}]]></artwork>
</figure>
</section>
<section anchor="app-dhcp-hs" title="Hybrid Schema">
<figure>
<artwork>
<![CDATA[<?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=". <= ../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>]]></artwork>
</figure>
</section>
<section anchor="app-dhcp-2" title="Final DSDL Schemas">
<t>This appendix contains DSDL schemas that were obtained from
the hybrid schema in <xref target="app-dhcp-hs"/> by XSL
transformations. These schemas can be directly used for
validating a reply to unfiltered <nc:get> with the contents
corresponding to the DHCP data model.</t>
<t>The RELAX NG schema (in two parts, as explained in <xref
target="modularity"/>) also includes the schema-independent
library from <xref target="app-library"/>.</t>
<section
title="Main RELAX NG Schema for <nc:get> Reply">
<figure>
<artwork>
<![CDATA[<?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>]]></artwork>
</figure>
</section>
<section title="RELAX NG Schema - Global Named Pattern Definitions">
<figure>
<artwork>
<![CDATA[<?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>]]></artwork>
</figure>
</section>
<section title="Schematron Schema for <nc:get> Reply">
<figure>
<artwork>
<![CDATA[<?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=". <= ../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>]]></artwork>
</figure>
</section>
<section title="DSRL Schema for <nc:get> Reply">
<figure>
<artwork>
<![CDATA[<?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>
]]>
</artwork>
</figure>
</section>
</section>
</section>
<section anchor="change-log" title="Change Log">
<t>RFC Editor: remove this section upon publication as an RFC.</t>
<section title="Changes Between Versions -07 and -08">
<t><list style="symbols">
<t>Edits based on Gen-ART review.</t>
<t>Added formal templates in <xref target="iana"/>.</t>
<t>Created the "Contributors" section and moved the former
co-authors there.</t>
<t>Indicated the location of both global and local named
pattern definitions in the example hybrid schema in <xref
target="hybridSchema"/>.</t>
<t>Added reference to EXSLT "evaluate" function.</t>
</list></t>
</section>
<section title="Changes Between Versions -06 and -07">
<t><list style="symbols">
<t>Mapping of 'description', 'reference' and 'units' to the
hybrid schema is now mandatory.</t>
<t>Improvements and fixes of the text based on the AD review</t>
</list></t>
</section>
<section title="Changes Between Versions -05 and -06">
<t><list style="symbols">
<t>Terminology change: "conceptual tree schema" -> "hybrid
schema".</t>
<t>Changed sectioning markers in the hybrid schema into plain
NETMOD-specific annotations. Hence the former "nmt" namespace
is not used at all.</t>
<t>Added the following NETMOD-specific annotations:
@nma:if-feature, @nma:leaf-list, @nma:mandatory,
@nma:module, removed @nma:presence.</t>
<t>Changed the structure of RELAX NG schemas by using embedded
grammars and declaration of namespaces via @ns. This was
necessary for enabling the "chameleon" behavior of global
definitions.</t>
<t>Schematron validation phases are not used.</t>
<t>If an XPath expression appears inside a top-level grouping,
the local prefix must be represented using the variable
$pref. (This is related to the previous item.)</t>
<t>DHCP example: All RNG schemas are only in the XML
syntax. Added RNG with global definitions.</t>
<t>Added <xref target="XML-INFOSET"/> to normative references.</t>
<t>Listed the terms that are defined in other documents.</t>
<t>The schema for NETMOD-specific annotation is now given only
as RNG named pattern definitions, no more in NVDL.</t>
</list></t>
</section>
<section title="Changes Between Versions -04 and -05">
<t><list style="symbols">
<t>Leafs that take their default value from a typedef and are
not annotated with @nma:default must have
@nma:implicit="true".</t>
<t>Changed code markers CODE BEGINS/ENDS to the form agreed by
the WG.</t>
<t>Derived types "date-and-time" and "uri" SHOULD be mapped to
XSD "dateTime" and "anyURI" types, respectively.</t>
<t>Clarified the notion of implicit nodes under under 'case'
in <xref target="implicit-nodes"/>.</t>
<t>Moved draft-ietf-netmod-yang-types-06 to normative
references.</t>
<t>An extra <rng:group> is no more required for the
default case of a choice in the shorthand notation.</t>
</list></t>
</section>
<section title="Changes Between Versions -03 and -04">
<t><list style="symbols">
<t>Implemented ordering rules for list children - keys must go
first and appear in the same order as in the input YANG
module.</t>
<t>The 'case' statement is now mapped to either
<rng:group> (inside RPC operations) or <rng:interleave>
(otherwise).</t>
<t>A nma:default annotation coming from a datatype which the mapping
expands is attached to the <rng:element> pattern where
the expansion occurs. Added an example.</t>
<t>Documentation statements ('description', 'reference',
'status') MAY be ignored.</t>
<t>Single-valued numeric or length range parts are mapped to
<rng:value> pattern or "length" facet.</t>
<t>Example for "string" datatype was added.</t>
<t><xref target="nma-schema"/> now uses NVDL for defining
NETMOD-specific annotations.</t>
<t>Added CODE BEGINS/ENDS markers.</t>
<t>Separated normative and informative references.</t>
<t>Added URL for XPath extensions namespace.</t>
<t>Added <xref target="term-not"/> (Terminology and Notation).</t>
<t>Added <xref target="sec-cons"/> (Security
Considerations).</t>
<t>Added <xref target="acknowledgments"/> (Acknowledgments).</t>
<t>Removed compact syntax schema from <xref
target="app-library"/>.</t>
<t>Editorial changes: symbolic citation labels.</t>
</list></t>
</section>
<section title="Changes Between Versions -02 and -03">
<t><list style="symbols">
<t>Changed @nma:default-case to @nma:implicit.</t>
<t>Changed nma:leafref annotation from element to attribute.</t>
<t>Added skeleton rule to <xref target="mappingSch"/>.</t>
<t>Reworked <xref target="mappingDSRL"/>, added skeleton
element maps,corrected the example.</t>
<t>Added section on 'feature' and 'deviation'.</t>
<t>New <xref target="occurrence-rules"/> integrating discussion
of both optional/mandatory (was in -02) and implicit nodes
(new).</t>
<t>Reflected that key argument and schema node identifiers are
no more XPath (should be in yang-07).</t>
<t>Element patterns for implicit containers now must have
@nma:implicit attribute.</t>
<t>Removed "float32" and "float64" types and added mapping of
"decimal64" with example.</t>
<t>Removed mapping of 'require-instance' for "leafref" type.</t>
<t>Updated RELAX NG schema for NETMOD-specific annotations.</t>
<t>Updated the DHCP example.</t>
</list></t>
</section>
<section title="Changes Between Versions -01 and -02">
<t><list style="symbols">
<t>Moved <xref target="validation"/> "NETCONF Content
Validation" after <xref target="mappingOverview"/>.</t>
<t>New text about mapping defaults to DSRL, especially in
<xref target="validation"/> and <xref
target="mappingDSRL"/>.</t>
<t>Finished the DHCP example by adding the DSRL schema to
<xref target="app-dhcp"/>.</t>
<t>New @nma:presence annotation was added - it is needed for
proper handling of default contents.</t>
<t><xref target="mandatory-choice"/> "Constraints on Mandatory
Choice" was added because these constraints require a
combination of RELAX NG and Schematron.</t>
<t>Fixed the schema for NETMOD-specific annotations by adding
explicit prefix to all defined elements and
attributes. Previously, the attributes had no namespace.</t>
<t>Handling of 'feature', 'if-feature' and 'deviation'
added.</t>
<t>Handling of nma:instance-identifier via XSLT extension
function.</t>
</list></t>
</section>
<section title="Changes Between Versions -00 and -01">
<t><list style="symbols">
<t>Attributes @nma:min-elements and @nma:max-elements are
attached to <rng:element> (list entry) and not to
<rng:zeroOrMore> or <rng:oneOrMore>.</t>
<t>Keys and all node identifiers in 'key' and 'unique'
statements are prefixed.</t>
<t>Fixed the mapping of 'rpc' and 'notification'.</t>
<t>Removed previous sec. 7.5 "RPC Signatures and
Notifications" - the same information is now contained in
<xref target="rpc-stmt"/> and <xref
target="notification-stmt"/>.</t>
<t>Added initial "_" to mangled names of groupings.</t>
<t>Mandated the use of @xmlns:xxx as the only method for
declaring the target namespace.</t>
<t>Added section "Handling of XML Namespaces" to explain the
previous item.</t>
<t>Completed DHCP example in <xref target="app-dhcp"/>.</t>
<t>Almost all text about the second mapping step is new.</t>
</list></t>
</section>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 14:21:25 |