One document matched: draft-ietf-netmod-dsdl-map-04.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-04">
<front>
<title abbrev="Mapping YANG to DSDL">Mapping YANG to Document Schema
Definition Languages and Validating NETCONF Content</title>
<author initials="L." surname="Lhotka" fullname="Ladislav Lhotka">
<organization>CESNET</organization>
<address>
<email>lhotka@cesnet.cz</email>
</address>
</author>
<author initials="R." surname="Mahy" fullname="Rohan Mahy">
<organization>Plantronics</organization>
<address>
<email>rohan@ekabal.com</email>
</address>
</author>
<author initials="S." surname="Chisholm" fullname="Sharon Chisholm">
<organization>Nortel</organization>
<address>
<email>schishol@nortel.com</email>
</address>
</author>
<date day="19" month="October" year="2009"/>
<area>Operations and Management</area>
<workgroup>NETMOD</workgroup>
<abstract>
<t>This draft 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
19757. The following DSDL schema languages are used 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 PDU
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 modeling language or accompanying rules for how to model
configuration and status information (in XML syntax) carried by
NETCONF. The IETF Operations Area has a long tradition of defining
data for SNMP Management Information Bases (MIBs) <xref
target="RFC1157"/> using the 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 rather than 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 address this problem, by defining a new
human-friendly modeling language based on SMIng <xref
target="RFC3216"/> and called YANG <xref target="YANG"/>. </t>
<t>Since NETCONF uses XML for encoding its protocol data units
(PDU), 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 - RELAX NG, Schematron and 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 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, RPC
signatures and notifications is expressed as a single RELAX NG
grammar with simple 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 validate specific XML documents such
as client requests, server responses or notifications, perhaps
also taking into account additional context such as active
capabilities.</t>
</section>
<section anchor="term-not" title="Terminology and Notation">
<t>This document relies on many terms that are defined in the
specifications of the NETCONF protocol <xref target="RFC4741"/>
and YANG data modeling language <xref target="YANG"/>. Also, the
common terminology of XML and DSDL schema languages is used as
defined in the respective standards <xref target="XML"/>, <xref
target="DSDL"/>, <xref target="NVDL"/>, <xref target="RNG"/>,
<xref target="Schematron"/> and <xref target="DSRL"/>.</t>
<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>In the text, we use the following typographic conventions:
<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</t>
<t hangText=""nmt"">Conceptual tree (see <xref
target="conceptualTree"/>)</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>nmt</c><c>urn:ietf:params:xml:ns:netmod:conceptual-tree: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 datytype 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>conceptual data tree: A virtual XML document integrating
all components of a YANG data model, i.e., configuration
datastore, RPC methods (both requests and replies) and
notifications. The conceptual tree is normally not
instantiated, it only serves as a conceptual target for its
schema. See <xref target="conceptualTree"/> for details.</t>
<t>implicit node: A node that, if missing, may be added to the
information set of an XML document (configuration, RPC input
or output, notification) without changing the meaning of that
XML document for the NETCONF server.</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 by validation capabilities of DSDL schema
languages, primarily RELAX NG and Schematron. This document
describes the correspondence between grammatical, semantic and data
type constraints expressed in YANG and equivalent DSDL
constructs. 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 is in principle invertible, the inverse mapping from
DSDL to YANG is not in its scope.</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 methods are
characterized by an inherent diversity resulting from selective
availability of capabilities and features. YANG modules can also
define new RPC methods. 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
schemas can be generated on demand 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 the
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 a single RELAX NG schema of the so-called "conceptual tree",
which contains grammatical constraints for the main data tree as
well as RPCs and notifications. In order to record additional
constraints that appear in the YANG modules but cannot be
expressed in RELAX NG, the schema is augmented by simple
annotations. The output of the first step can thus be considered
a reasonably readable equivalent of the input YANG modules.</t>
<t>In the second step, the annotated RELAX NG 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 an international
standard ISO/IEC 19757. Unlike other approaches to XML document
validation, notably W3C XML Schema (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, Schematron and 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 content 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 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 <eref
target="http://www.thaiopensource.com/relaxng/trang.html">Trang</eref>.
</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 generally require 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 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
for the XML syntax.</t>
<t>In a computer program, it is more difficult to generate
compact syntax than XML syntax. While a number of software
libraries exist that make it easy to create an XML tree in
memory and serialize it, no such aid is available for 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 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 future).</t>
<t>The human-readable error messages are another feature that
distinguishes Schematron from other common schema languages. The
messages may even contain XPath expressions that are evaluated
in the actual context and thus refer to existing XML document
nodes and their content.</t>
<t>The rules defined by a Schematron schema may be divided into
several subsets known as <spanx
style="emph">phases</spanx>. Validations may then be set up to
include only selected phases. In the context of NETCONF data
validation, this is useful for relaxing constraints that may not
always apply. For example, the reference integrity may not be
enforced for a candidate configuration.</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, it is
specifically designed 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 content for XML elements
so that elements or attributes with these default values are
inserted if they are missing (or present and empty) in the
validated documents. The latter feature is used by the
YANG-to-DSDL mapping for representing YANG default values for
leaf nodes.</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. 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 conceptual tree schema and MAY also appear in the final
validation schemas.</t>
<t>The third set are NETMOD-specific annotations conveying YANG
semantic constraints and other information that cannot be
expressed natively in RELAX NG. These annotations are only used in
the first step of the mapping, i.e., in the conceptual tree
schema. In the second mapping step, these annotations are
converted to Schematron and DSRL rules.</t>
<section anchor="dcElements" title="Dublin Core Metadata Elements">
<t><eref target="http://dublincore.org/">Dublin Core</eref> 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 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 interpreted 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" that appear
in various locations in the conceptual tree schema. YANG
statements are mapped to these annotations in a straightforward
way. In most cases, the annotation attributes and elements
always 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 the formal specification of 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:default</c>
<c><xref format="counter" target="default-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: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: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:leafref</c>
<c><xref format="counter" target="leafref-type"/></c>
<c></c>
<c>@nma:min-elements</c>
<c><xref format="counter" target="leaf-list-stmt"/></c>
<c></c>
<c>@nma:max-elements</c>
<c><xref format="counter" target="leaf-list-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:ordered-by</c>
<c><xref format="counter" target="ordered-by-stmt"/></c>
<c></c>
<c>@nma:presence</c>
<c><xref format="counter" target="presence-stmt"/></c>
<c></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 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>
</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
|
+-------------------------------------+
| RELAX NG schema for conceptual tree |
+-------------------------------------+
/ | | \
/ | | \ +-------+
Tg/ Tr| |Tn \ |library|
/ | | \ +-------+
+---------+ +-----+ +-------+ +------+
|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 a single RELAX NG schema for the conceptual tree (see
<xref target="conceptualTree"/>). 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 simple annotations belonging to special
namespaces.</t>
<t>In the second step, the conceptual tree schema is 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 just three
simple possibilities as examples. In the process, appropriate
parts of the conceptual tree schema are extracted and specific
annotations transformed to equivalent, but usually more complex,
Schematron patterns, DSRL element maps etc.</t>
<t>As indicated in <xref target="fig-mapschema"/>, the second
step of the mapping also uses a schema-independent library that
contains common schema objects such as RELAX NG named pattern
definitions.</t>
</list></t>
<t>An implementation of the mapping algorithm accepts 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 roots. 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 module(s) imports
(transitively).</t>
<t>The output of the first mapping step is an annotated RELAX NG
schema for the conceptual tree - a virtual XML document
containing, in its different subtrees, the entire datastore, all
RPC requests and replies, and notifications as defined by the
input YANG modules. By "virtual" we mean that such an XML document
need not correspond to the actual layout of the configuration
database in a NETCONF agent, and will certainly never appear on
the wire as the content of a NETCONF PDU. Hence, the RELAX NG
schema for the conceptual tree is not intended for any direct
validations but rather as a representation of a particular data
model expressed in RELAX NG and the common starting point for
subsequent transformations that may produce practical validation
schemas. The conceptual tree is further described in <xref
target="conceptualTree"/>.</t>
<t>Other information contained in input YANG modules, such as
semantic constraints or default values, are recorded in the
conceptual tree 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 annotations utilizing
Dublin Core elements (<xref target="dcElements"/>). Finally,
documentation strings are mapped to the <a:documentation>
elements belonging to the DTD compatibility vocabulary (<xref
target="dtdCompatibility"/>).</t>
<t>The output from 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 a specification of default
content.</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 content of a datastore or various
NETCONF PDUs.</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 can be immediately
checked for grammatical and data type validity using the RELAX
NG schema.</t>
<t anchor="val-dsrl">Second, default values for leaf nodes have
to be applied and their ancestor containers added where
necessary. It is important to apply the defaults before the next
validation step because YANG specification <xref target="YANG"/>
states that the data tree against which XPath expressions are
evaluated already has all defaults filled-in. Note that this
step modifies the information set of the input XML document.</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 modules could in principle be mapped to 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="conceptualTree" title="Conceptual Data Tree">
<t>DSDL schemas generated from YANG modules using the procedure
described in this document are intended to be used for
validating XML-encoded NETCONF data in various forms: every
YANG-based model represents the contents of a datastore but also
implies an array of schemas for all types of NETCONF PDUs. For a
reasonably strict validation of a given data object, the schemas
have to be quite specific. To begin with, effective validation
of NETCONF PDU content requires separation of client and server
schemas. While the decision about proper structuring of all
PDU-validating schemas is beyond the scope of this document, the
mapping procedure is designed to accommodate any foreseeable
validation needs.</t>
<t>An essential part of the YANG-to-DSDL mapping procedure is
nonetheless common to all validation approaches: the grammar and
datatype specifications for the datastore, RPCs and
notifications expressed by one or more YANG modules have to be
translated to RELAX NG. In order to be able to separate this
common step, we introduce the notion of <spanx
style="emph">conceptual data tree</spanx>: it is a virtual XML
tree that contains full datastore, RPC requests with
corresponding replies and notifications. The schema for the
conceptual tree - a single RELAX NG schema with annotations -
therefore has a quite similar logic as the input YANG module(s),
the only major difference being the RELAX NG schema
language.</t>
<t>For example, the conceptual data tree for a YANG module
defining nodes in the namespace "http://example.com/ns/example"
may be schematically represented as follows:</t>
<figure>
<artwork>
<![CDATA[<nmt:netmod-tree
xmlns:nmt="urn:ietf:params:xml:ns:netmod:conceptual-tree:1"
xmlns:ex="http://example.com/ns/example">
<nmt:top>
... configuration and status data ...
</nmt:top>
<nmt:rpc-methods>
<nmt:rpc-method>
<nmt:input>
<ex:myrpc ...>
...
</myrpc>
</nmt:input>
<nmt:output>
...
</nmt:output>
</nmt:rpc-method>
...
</nmt:rpc-methods>
<nmt:notifications>
<nmt:notification>
<ex:mynotif>
...
</mynotif>
</nmt:notification>
...
</nmt:notifications>
</nmt:netmod>]]></artwork>
</figure>
<t>The namespace URI
"urn:ietf:params:xml:ns:netmod:conceptual-tree:1" identifies a
simple vocabulary consisting of a few elements that encapsulate
and separate the various parts of the conceptual data tree.</t>
<t>The conceptual tree schema is not intended for direct
validation but rather serves as a well-defined starting point
for subsequent transformations that generate validation
schemas. In general, these transformations should be relatively
simple - they will typically extract one or more subtrees from
the conceptual tree schema, modify them as necessary and add
encapsulating elements such as those from the NETCONF RPC
layer.</t>
<t>Additional information contained in the source YANG
module(s), such as semantic constraints and default values, is
represented in the form of interim NETMOD-specific annotations
that are included as foreign-namespace elements or attributes in
the RELAX NG schema for the conceptual tree. In the second phase
of the mapping, these annotations are translated to equivalent
Schematron and DSRL rules.</t>
<t>As a useful side effect, by introducing the conceptual data
tree we are also able to resolve the difficulties arising from
the fact that a single datastore may consist of multiple
parallel data hierarchies defined in one or more YANG modules,
which cannot be mapped to a valid XML document. In the
conceptual data tree, such multiple hierarchies appear under the
single <nmt:top> element.</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 MIBs. 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 imported module must be prepared in a special
way as a library module that cannot be used as a stand-alone
schema.</t>
</list></t>
<t>So the conclusion is that the modularity mechanisms of YANG
and RELAX NG, albeit similar, are not directly
compatible. Therefore, the corresponding design decision for the
mapping algorithm is to collect all information in a single
schema for the conceptual tree, even if it comes from multiple
YANG modules or submodules. In other words, translations of
imported groupings and typedefs are installed in the translation
of importing module - but only if they are really used
there.</t>
<t>NOTE: The 'include' statement that is used in YANG for
including submodules has in fact the same semantics as the
<rng:include> pattern. However, since we don't map the
modular structure for YANG modules, it seems to have little
sense to do it for submodules. Consequently, the contents of
submodules appear directly in the conceptual tree schema,
too.</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 that's 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 extension mechanisms
to those of RELAX NG. For this reason, the mapping essentially
keeps the granularity of the original YANG data model:
definitions of named patterns in the resulting RELAX NG schema
usually have direct counterparts in YANG groupings and
definitions of derived types.</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 YANG-to-DSDL mapping allows for
multiple input YANG modules that 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 cases these attributes are typically attached to the
<rng:grammar> element.</t>
<t>The design decision for the mapping is to use exclusively the
alternative <xref format="counter" target="xmlns-att"/>, since
in this case all YANG modules are represented symmetrically,
which makes further processing of the conceptual tree schema
considerably easier. Moreover, this way the namespace prefixes
declared in the input modules are recorded in the resulting
schema - the prefix for the namespace declared using @ns would
be lost.</t>
<t>DSRL schemas can declare any number of target namespaces via
the standard XML attributes xmlns:xxx.</t>
<t>In contrast, Schematron requires all the target namespaces to
be defined in the <sch:ns> subelements of the root
<sch:schema> element.</t>
</section>
<section anchor="features-deviations"
title="Features and Deviations">
<t>YANG provides statements that allow for marking parts of the
schema as conditional ('feature' and 'if-feature' statements) or
declaring deviations from a data model ('deviation'
statement). These statements are not handled by the YANG-to-DSDL
mapping. Instead, it is assumed that all features and deviations
are specified beforehand and the corresponding changes in the
input YANG modules are already applied.</t>
</section>
</section>
<section
anchor="desc-yang-to-cts"
title="Mapping YANG Data Models to the Conceptual Tree Schema">
<t>This section explains the main principles underlying the first
step of the mapping. Its result is an annotated RELAX NG schema of
the conceptual tree, which is described in <xref
target="conceptualTree"/>.</t>
<t>As a special case, if the input YANG modules contain no data
nodes (this is typical, e.g., for datatype library modules), an
implementation MAY entirely remove the schema of the (empty)
conceptual tree - the <rng:start> element with all its
contents. The output RELAX NG schema will then contain only named
pattern definitions translated from YANG groupings and
typedefs.</t>
<t>Detailed specification of the mapping of individual YANG
statements is contained in <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 RELAX NG, for
example, <rng:optional> pattern appears as the parent
element of the pattern defining the node in the schema, be it a
leaf or container node. Similarly, DSRL specifies default
content 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'. In
contrast, 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 containers and mark
accordingly the corresponding <rng:element> patterns in
the conceptual tree 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 container element
must always be present in a valid configuration. If so, such a
container element is called mandatory, otherwise it is called
optional. This constraint is very closely related to the notion
of mandatory nodes in <eref
target="http://tools.ietf.org/html/draft-ietf-netmod-yang-05#section-3.1">Section
3.1</eref> in <xref target="YANG"/>. The only difference is that
we also consider 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. Such elements are called implicit.</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 for other
types of nodes as well, i.e., leaf, list, leaf-list and anyxml.</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, leaf nodes are mandatory if they are
declared as list keys.</t>
<t>List or leaf-list nodes are mandatory if they contain
'min-elements' substatement with 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 is optional iff it is not mandatory.</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 conceptual tree schema.</t>
<t>However, alternatives in <rng:choice> are never
defined as optional in the conceptual tree schema. Therefore,
'anyxml', 'container', 'leaf', 'list' and 'leaf-list'
statements appearing as children of 'choice' (shorthand cases)
are always mapped to mandatory RELAX NG patterns. If a choice
in YANG is not mandatory, <rng:optional> is used to wrap
the entire <rng:choice> pattern.</t>
</section>
<section anchor="implicit-nodes" title="Implicit Nodes">
<t>The following rules are used to determine whether a given
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 specified
default value (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 is
mandatory and at least one child is implicit.</t>
<t>As an exception to the above two rules, a leaf or
container node appearing inside a case of a choice can be
implicit only if that case is declared as default by using
the 'default' statement, see <eref
target="http://tools.ietf.org/html/draft-ietf-netmod-yang-06#section-7.9.3">Section
7.9.3</eref> in <xref target="YANG"/>.</t>
</list></t>
<t>In the conceptual tree schema, all implicit containers MUST
be marked with @nma:implicit attribute with the value
"true". In addition, the default case in a choice (defined by
the 'default' substatement of 'choice') MUST be also marked in
the same way, i.e., by @nma:implicit set to "true".</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/draft-ietf-netmod-yang-05#section-5.5">
Section 5.5</eref> in <xref target="YANG"/>. Moreover, top-level
symbols from external modules are 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>Since the names of groupings and typedefs in YANG have
different namespaces, an additional underline character is
added to the beginning of the mangled names of all
groupings.</t>
</list>
</t>
<t>EXAMPLE. Consider the following YANG module which imports
the standard module "ietf-inet-types" <xref target="Ytypes"/>:</t>
<figure>
<artwork>
<![CDATA[module example1 {
namespace "http://example.com/ns/example1";
prefix ex1;
import "ietf-inet-types" {
prefix "inet";
}
typedef vowels {
type string {
pattern "[aeiouy]*";
}
}
grouping "grp1" {
leaf "void" {
type "empty";
}
}
container "cont" {
grouping "grp2" {
leaf "address" {
type "inet:ip-address";
}
}
leaf foo {
type vowels;
}
uses "grp1";
uses "grp2";
}
}]]></artwork>
</figure>
<t>The resulting RELAX NG schema will then contain the following
named pattern definitions (long regular expression patterns for
IPv4 and IPv6 addresses are not shown):</t>
<figure>
<artwork>
<![CDATA[<rng:define name="example1__vowels">
<rng:data type="string">
<rng:param name="pattern">[aeiouy]*</param>
</rng:data>
</rng:define>
<rng:define name="_example1__grp1">
<rng:optional>
<rng:element name="ex1:void">
<rng:empty/>
</rng:element>
</rng:optional>
</rng:define>
<rng:define name="_example1__cont__grp2">
<rng:optional>
<rng:element name="ex1:address">
<rng:ref name="ietf-inet-types__ip-address"/>
</rng:element>
</rng:optional>
</rng:define>
<rng:define name="ietf-inet-types__ip-address">
<rng:choice>
<rng:ref name="ietf-inet-types__ipv4-address"/>
<rng:ref name="ietf-inet-types__ipv6-address"/>
</rng:choice>
</rng:define>
<rng:define name="ietf-inet-types__ipv4-address">
<rng:data type="string">
<rng:param name="pattern">... regex pattern ...</param>
</rng:data>
</rng:define>
<rng:define name="ietf-inet-types__ipv6-address">
<rng:data type="string">
<rng:param name="pattern">... regex pattern ...</param>
</rng:data>
</rng:define>]]></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
allows for modifying <spanx style="emph">expansions</spanx> of
groupings. Specifically, YANG provides two statements for this
purpose that may appear as substatements of 'uses':
<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 content.</t>
</list></t>
<t>Both 'refine' and 'augment' statements are quite powerful
in that they can address, using XPath-like expressions as
arguments, schema nodes that are arbitrarily deep inside the
grouping content. In contrast, modifications of named pattern
definitions in RELAX NG are applied exclusively at the topmost
level of the named pattern content. In order to achieve a
modifiability of named patterns comparable to YANG, the 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 content 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
content, 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 conceptual tree schema contains three named
pattern definitions corresponding to the three groupings,
namely</t>
<figure>
<artwork>
<![CDATA[<rng:define name="_example2__leaves">
<rng:ref name="_example2__fr"/>
<rng:ref name="_example2__es"/>
</rng:define>
<rng:define name="_example2__fr">
<rng:optional>
<rng:element name="ex2:feuille">
<rng:data type="string"/>
</rng:element>
</rng:optional>
</rng:define>
<rng:define name="_example2__es">
<rng:optional>
<rng:element name="ex2:hoja">
<rng:data type="string"/>
</rng:element>
</rng:optional>
</rng:define>
]]></artwork>
</figure>
<t>and the configuration data part of the conceptual tree schema
is a single named pattern reference:</t>
<figure>
<artwork>
<![CDATA[<rng:ref name="_example2__leaves"/>]]></artwork>
</figure>
<t>Now assume that the "uses leaves" statement is refined:</t>
<figure>
<artwork>
<![CDATA[uses leaves {
refine "hoja" {
default "alamo";
}
}]]></artwork>
</figure>
<t>The resulting conceptual tree 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
conceptual tree now looks like this:</t>
<figure>
<artwork>
<![CDATA[<rng:ref name="_example2__fr"/>
<rng:optional>
<rng:element name="ex2:hoja" nma:default="alamo">
<rng:data type="string"/>
</rng:element>
</rng:optional>]]></artwork>
</figure>
</section>
<section anchor="chtypes" title="Type derivation chains">
<t>RELAX NG has no equivalent of the type derivation mechanism
in YANG, where a ancestor built-in type may be modified (perhaps
in multiple steps) by adding new restrictions. Therefore, when
mapping YANG derived types with restrictions, the derived
types MUST be "unwound" all the way back to the ancestor built-in
type. At the same time, all restrictions found along the type
derivation chain MUST be combined and their intersection used
as facets restricting the corresponding type in RELAX NG.</t>
<t>When a derived YANG type is used without restrictions - as
a substatement of either 'leaf' or another 'typedef' - the
'type' statement is mapped simply to the <rng:ref>
element, i.e., a named pattern reference. However, if
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 output
schema, restricted with facets that again 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" is 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</param>
<rng:param name="maxInclusive">12</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 won't contain any named
pattern definition and 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</param>
<rng:param name="maxInclusive">12</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, the
@nma:default annotation arising from the expanded type
or ancestor types in the type derivation chain MUST be
attached to the element 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</param>
<rng:param name="maxInclusive">12</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</param>
<rng:param name="maxInclusive">12</param>
</rng:data>
</rng:element>]]></artwork>
</figure>
<t>However, if the definition of leaf "month" itself
contained the 'default' substatement, the default specified
for the "dozen" type will 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. However,
since 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 <spanx
style="emph">default namespace</spanx> in XPath 2.0: node names
needn't carry a namespace prefix inside the module where they
are defined, in which case the module's namespace is
assumed.</t>
<t>If an XPath expression is carried over to a NETMOD-specific
annotation in the conceptual tree schema, it MUST be translated
into a fully conformant XPath 1.0 expression that also reflects
the hierarchy of the conceptual data tree:
<list style="numbers">
<t anchor="item-prefix">Each unprefixed node name MUST be
prepended with the local module's namespace prefix declared by
the 'prefix' statement.</t>
<t anchor="item-root">Absolute XPath expressions, i.e., those
starting with a slash, MUST be prepended with appropriate path
in the conceptual tree, according to the YANG specification of
context for XPath expressions, see <xref target="YANG"/>,
sections <eref
target="http://tools.ietf.org/html/draft-ietf-netmod-yang-05#section-7.5.3">7.5.3</eref>
and <eref
target="http://tools.ietf.org/html/draft-ietf-netmod-yang-05#section-7.19.5">7.19.5</eref>
in <xref target="YANG"/>.</t>
</list></t>
<t>Translation rule <xref format="counter" target="item-root"/>
means for example that absolute XPath expressions appearing in
the main configuration data tree always start with
"nmt:netmod-tree/nmt:top/", those appearing in a notification
always start with
"nmt:netmod-tree/nmt:notifications/nmt:notification/", etc.</t>
<t>EXAMPLE. YANG XPath expression "/dhcp/max-lease-time"
appearing in the main configuration data will be translated to
"nmt:netmod-tree/nmt:top/dhcp:dhcp/dhcp:max-lease-time".</t>
<t>The key identifiers and "descendant schema node identifiers"
(see the ABNF production for and "descendant-schema-nodeid" in
<eref
target="http://tools.ietf.org/html/draft-ietf-netmod-yang-05#section-12">Section 12</eref>
of <xref target="YANG"/>) are not XPath expressions but SHOULD
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 can be used as the native statements, only with
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 every
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.</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="cts-to-dsdl"
title="Mapping Conceptual Tree Schema to DSDL">
<t>As explained in <xref target="mappingOverview"/>, the second step
of the YANG-to-DSDL mapping takes the conceptual tree schema and
transforms it to various DSDL schemas ready for validation. As an
input parameter, this step gets in the simplest case a specification
of the NETCONF XML document type (or combination of multiple types)
that is to be validated. These document type can be, for example,
the content of a datastore, reply to <nc:get> or
<nc:get-config>, other RPC requests or replies and
notifications.</t>
<t>In general, the second mapping step has to accomplish the
following three tasks:
<list style="numbers">
<t>Extract the part(s) of the conceptual tree schema that are
appropriate for the requested document type. For example, if a
<get> reply is to be validated, the subtree under
<nmt:top> must be selected.</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
datastore 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
corresponding schema-language-specific rules.</t>
</list></t>
<t>These three tasks are together much simpler than the first
mapping step. Presumably, they can be effectively realized
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 conceptual tree schema really means only taking
appropriate parts from the conceptual tree schema and assembling
them in a new RELAX NG grammar, perhaps after removing all
unwanted annotations. Depending on the XML document type that is
the target for validation (<get>/<get-config> reply,
RPC or notification) a corresponding top-level part of the grammar
MUST be added as described in the following subsections.</t>
<t>Schemas for multiple alternative target document types can also
be easily generated by enclosing the definitions for requested
type in <rng:choice> element.</t>
<t>In order to avoid copying identical named pattern definitions
to the output RELAX NG file, these schema-independent definitions
SHOULD be collected in a library file which is then included by
the validating RELAX NG schemas. <xref target="app-library"/> has
the listing of this library file.</t>
<t>The minor exception mentioned above is the annotation
@nma:config, which must be observed if the target document type is
<get-config> reply. In this case, each element definition
that has this attribute with the value "false" MUST be removed
from the schema together with its descendants. See <xref
target="nma-config"/> for more details.</t>
<section title="Reply to <get> or <get-config>">
<t>For a reply to <get> or <get-config>, the mapping
must take the part of the conceptual tree schema under the
definition of <nmt:top> and insert it in the following
grammar:</t>
<figure>
<artwork>
<![CDATA[<rng:grammar ... namespaces etc. ...>
<rng:include href="relaxng-lib.rng"/>
<rng:start>
<rng:element name="nc:rpc-reply">
<rng:ref name="message-id-attribute"/>
<rng:element name="nc:data">
... patterns defining contents of "nmt:top" subtree ...
</rng:element>
</rng:element>
</rng:start>
... named pattern definitions ...
</rng:grammar>]]></artwork>
</figure>
<t>The definition for the named pattern "message-id-attribute"
is found in the library file "relaxng-lib.rng" which is included
on the second line (see <xref target="app-library"/>).</t>
<t>Definitions of other named patterns MUST be copied from the
conceptual tree schema without any changes to the resulting
grammar. However, an implementation MAY choose to copy only
those definitions that are really used in the particular
output grammar.</t>
</section>
<section title="Remote Procedure Calls">
<t>For an RPC method named "myrpc" and defined in a YANG
module with prefix "yam", the corresponding schema subtree is
identified by the definition of <nmt:rpc-method> element
whose <nmt:input> subelement has <yam:myrpc> as the
only child.</t>
<t>The mapping must also take into account whether the target
document type is an RPC request or reply. For "yam:myrpc"
request, the resulting grammar looks as follows:</t>
<figure>
<artwork>
<![CDATA[<rng:grammar ... namespaces etc. ...>
<rng:include href="relaxng-lib.rng"/>
<rng:start>
<rng:element name="nc:rpc">
<rng:ref name="message-id-attribute"/>
<rng:element name="yam:myrpc">
... patterns defining contents of subtree ...
... "nmt:rpc-method/nmt:input/yam:myrpc" ...
</rng:element>
</rng:element>
</rng:start>
... named pattern definitions ...
</rng:grammar>]]></artwork>
</figure>
<t>For "myrpc" reply, the output grammar is</t>
<figure>
<artwork>
<![CDATA[<rng:grammar ... namespaces etc. ...>
<rng:include href="relaxng-lib.rng"/>
<rng:start>
<rng:element name="nc:rpc-reply">
<rng:ref name="message-id-attribute"/>
... patterns defining contents of corresponding ...
... "nmt:rpc-method/nmt:output" subtree ...
</rng:element>
</rng:start>
... named pattern definitions ...
</rng:grammar>]]></artwork>
</figure>
<t>In both cases, exact copies of named pattern definitions from
the conceptual tree schema MUST be inserted, but an
implementation MAY choose to include only those used for the
given RPC.</t>
</section>
<section title="Notifications">
<t>For a notification named "mynotif" and defined in a YANG
module with prefix "yam", the corresponding schema subtree is
identified by the definition of <nmt:notification> element
that has the single child <yam:mynotif>.</t>
<t>The resulting grammar looks as follows:</t>
<figure>
<artwork>
<![CDATA[<rng:grammar ... namespaces etc. ...>
<rng:include href="relaxng-lib.rng"/>
<rng:start>
<rng:element name="en:notification">
<rng:ref name="eventTime-element"/>
<rng:element name="yam:mynotif">
<!-- patterns defining contents of
"nmt:rpc-notification/yam:mynotif" subtree -->
</rng:element>
</rng:element>
</rng:start>
<!-- named pattern definitions -->
</rng:grammar>]]></artwork>
</figure>
<t>The definition of the named pattern "eventTime-element" is
found in the "relaxng-lib.rng" library file, see <xref
target="app-library"/>.</t>
<t>Again, exact copies of named pattern definitions from the
conceptual tree schema MUST be inserted, but an implementation
MAY choose to include only those used for the given
notification.</t>
</section>
</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 <spanx
style="emph">rule</spanx> represented by the <sch:rule>
element. Every rule corresponds to exactly one element definition
pattern in the conceptual tree schema:</t>
<figure>
<artwork>
<![CDATA[<sch:rule context="XELEM">
...
</sch:rule>]]></artwork>
</figure>
<t>The value of the mandatory @context attribute of
<sch:rule> is set to the absolute path of the context
element in the data tree. The <sch:rule> element contains
the mappings of one or more of the following NETMOD-specific
annotations, if they are attached to the context element:
<nma:instance-identifier>, @nma:key, @nma:leafref,
@nma:min-elements, @nma:max-elements, <nma:must>,
@nma:unique and <nma:when>.</t>
<t>In the opposite direction, however, not every element
definition pattern in the conceptual tree schema has a
corresponding rule in the Schematron schema: definitions of
elements the carry none of the above annotations are omitted.</t>
<t>Schematron rules may be further grouped into <spanx
style="emph">patterns</spanx> represented by the
<sch:pattern> element. The mapping uses patterns only for
discriminating between subsets of rules that belong to different
validation phases, see <xref
target="validationPhases"/>. Therefore, the <sch:schema>
always has exactly two <sch:pattern> children: one named
"standard" contains rules for all annotations except
<nma:instance-identifier> and @nma:leafref, and
another named "ref-integrity" containing rules for these two
remaining annotations, i.e., referential integrity checks.</t>
<t>Element definitions in the conceptual tree schema that appear
inside a named pattern definition (i.e., have <rng:define>
among its ancestors) are subject to a different treatment. This is
because their path in the data tree is not fixed - the named
pattern may be referred to in multiple different places. The
mapping uses Schematron <spanx style="emph">abstract rules</spanx>
to handle this case: An element definition inside a named pattern
is mapped to an abstract rule and every use of the named pattern
then extends (uses) this abstract rule in the concrete
context.</t>
<t>EXAMPLE. Consider this element pattern annotated with
<nma:must>:</t>
<figure>
<artwork>
<![CDATA[<rng:element name="dhcp:default-lease-time">
<rng: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>
</rng:element>]]></artwork>
</figure>
<t>If this element pattern appears outside any named pattern
and as a child of <dhcp:dhcp> (as it does in the DHCP
schema, see <xref target="app-dhcp-cts"/>), it is mapped to the
following Schematron rule:</t>
<figure>
<artwork>
<![CDATA[<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>]]></artwork>
</figure>
<t>Now assume the element definition is inside a named pattern
definition, say</t>
<figure>
<artwork>
<![CDATA[<rng:define name="_dhcp__default-lease-time">
<rng:element name="dhcp:default-lease-time">
... same content ...
</rng:element>
</rng:define>]]></artwork>
</figure>
<t>In this case it is mapped to an abstract rule, for instance</t>
<figure>
<artwork>
<![CDATA[<sch:rule id="id31415926" abstract="true">
<sch:assert test=". <= ../dhcp:max-lease-time">
The default-lease-time must be less than max-lease-time
</sch:assert>
</sch:rule>]]></artwork>
</figure>
<t>Any use of the named pattern definition via <rng:ref
name="_dhcp__default-lease-time"/> then results in a new rule
extending the abstract one, for example</t>
<figure>
<artwork>
<![CDATA[<sch:rule context="/nc:rpc-reply/nc:data/dhcp:dhcp/
dhcp:default-lease-time">
<sch:extends rule="id31415926"/>
</sch:rule>]]></artwork>
</figure>
<t>Care must be taken that the value of the @context attribute in
general consists of two parts in this case: its beginning is
determined by the location of the <rng:ref> element in the
main schema tree and the rest of the path comes from the relative
position of the annotated element definition inside the named
pattern. The situation becomes even more complex when the mapping
has to deal with chained definitions of named patterns
(<rng:ref> inside <rng:define>). The @context value
then must be recursively glued together from multiple parts.</t>
<t>The mapping from the conceptual tree schema to Schematron
proceeds in the following steps:
<list style="numbers">
<t>First, the active subtree(s) of the conceptual tree schema
must be selected depending on the requested target document
type. This procedure is identical to the RELAX NG case,
including the handling of @nma:config if
the target document type is <get-config> reply.</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/dhcp" prefix="dhcp"/>]]></artwork>
</figure>
</t>
<t>Validation phases are defined (see <xref
target="validationPhases"/>) and their constituting patterns
"standard" and "ref-integrity" created.</t>
<t>For either validation phase, the input conceptual tree schema
is scanned and element definitions with annotations relevant for
the given phase are selected and a <sch:rule> is created
for each of them. The rule is abstract if the element definition
appears inside a named pattern, see above.</t>
<t>All annotations attached to the given element definition are
then mapped using the mapping rules specified in <xref
target="nma-to-dsdl"/>. The resulting <sch:assert> or
<sch:report> elements are the installed as children of the
<sch:rule> element.</t>
</list></t>
<section anchor="validationPhases" title="Validation Phases">
<t>In certain situations it is useful to validate XML instance
documents without enforcing the referential integrity
constraints represented by the @nma:leafref and
<nma:instance-identifier> annotations. For example, a
candidate configuration referring to configuration parameters or
state data of certain hardware will not pass full validation
before the hardware is installed. To handle this, the Schematron
mapping introduces two <spanx style="emph">validation
phases</spanx>:
<list style="symbols">
<t>Validation phase "full", which is the default, checks all
semantic constraints.</t>
<t>Validation phase "noref" is the same as "full" except it
doesn't check referential integrity constraints.</t>
</list>
</t>
<t>A parameter identifying the validation phase to use has to be
passed to the Schematron processor or otherwise both patterns
are used by default. How this is exactly done depends on the
concrete Schematron processor and is outside the scope of this
document.</t>
<t>The validation phases are defined in Schematron by listing
the patterns that are to be applied for each phase. Therefore,
the mapping puts the rules for referential integrity checking to
a special <sch:pattern> with @id attribute set
to "ref-integrity". The rules mapped from the remaining semantic
constraints are put to another <sch:pattern> with @id
attributes set to "standard".</t>
<t>With validation phases, the resulting Schematron schema has
the following overall structure:</t>
<figure>
<artwork>
<![CDATA[<sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron">
<sch:ns uri="..." prefix="..."/>
... more NS declarations ...
<sch:phase id="full">
<sch:active pattern="standard"/>
<sch:active pattern="ref-integrity"/>
</sch:phase>
<sch:phase id="noref">
<sch:active pattern="standard"/>
</sch:phase>
<sch:pattern id="standard">
... all rules except ref. integrity checks ...
</sch:pattern>
<sch:pattern id="ref-integrity">
... rules for ref. integrity checks ...
</sch:pattern>
</sch:schema>]]></artwork>
</figure>
</section>
</section>
<section anchor="mandatory-choice"
title="Constraints on Mandatory Choice">
<t>In order to fully represent the semantics of YANG 'choice'
statement with "mandatory true;" substatement, the RELAX NG
grammar has to be combined with a special Schematron
rule.</t>
<t>EXAMPLE. Consider the following module:</t>
<figure>
<artwork>
<![CDATA[module example4 {
namespace "http://example.com/ns/example4";
prefix ex4;
choice foobar {
mandatory true;
case foo {
leaf foo1 {
type uint8;
}
leaf foo2 {
type uint8;
}
}
leaf bar {
type uint8;
}
}
}]]></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 conceptual tree schema:</t>
<figure>
<artwork>
<![CDATA[<rng:choice>
<rng:interleave>
<rng:optional>
<rng:element name="ex4:foo1">
<rng:data type="unsignedByte"/>
</rng:element>
</rng:optional>
<rng:optional>
<rng:element name="ex4:foo2">
<rng:data type="unsignedByte"/>
</rng:element>
</rng:optional>
</rng:interleave>
<rng:element name="ex4:bar">
<rng:data type="unsignedByte"/>
</rng:element>
</rng:choice>]]></artwork>
</figure>
<t>In the second case branch, the "ex4:bar" element is defined as
mandatory so that this element must be present in a valid
configuration if this branch is selected. However, the two
elements in the first branch "foo" cannot be both declared as
mandatory since each of them alone suffices for a valid
configuration. As a result, the above RELAX NG fragment would
successfully validate configurations where none of the three leaf
elements is present.</t>
<t>Therefore, mandatory choices, which can be recognized in the
conceptual tree schema as <rng:choice> elements that do not
have <optional> as their parent, have to be handled in a
special way: For each mandatory choice where at least one of the
cases contains more than one node, a rule MUST be present in the
"standard" pattern of the Schematron schema enforcing the presence
of at least one element from any of the cases. (RELAX NG schema
guarantees that elements from different cases cannot be mixed
together, that all mandatory nodes are present etc.).</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="ex4:foo1 or ex4:foo2 or ex4:bar">
Node(s) from at least one case of choice "foobar" must exist.
</sch:assert>
</sch:rule>]]></artwork>
</figure>
</section>
<section anchor="mappingDSRL"
title="Mapping Default Values to DSRL">
<t>DSRL is the only component of DSDL that is allowed to change
the information set of the validated XML document. While DSRL has
other functions, the YANG-to-DSDL mapping uses it only for
specifying default content. For XML instance documents based on
YANG data models, insertion of default content may potentially
take place for all implicit nodes, see <xref
target="occurrence-rules"/>.</t>
<t>In DSRL, the default content of an element is specified using
the <dsrl:default-content> element, which is a child of
<dsrl:element-map>. Two sibling elements of
<dsrl:default-content> determine the context for application
of the default content, see <xref target="DSRL"/>:
<list style="symbols">
<t><dsrl:parent> element contains an XSLT pattern
specifying the parent element; the default content is applied
only if the parent element exists in the instance document.</t>
<t><dsrl:name> contains the XML name of the element which,
if missing or empty, is inserted together with the content 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 proper
application of default content.</t>
<t>DSRL mapping only deals with element patterns defining implicit
nodes (see <xref target="implicit-nodes"/>). In the conceptual
tree schema, such element patterns are distinguished by
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>In the simple case, these 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 element pattern defining ELEM is annotated with
@nma:default, DEFCONT is equal to the value of this attribute
(denoted above as DEFVALUE).</t>
<t>Otherwise, if the element pattern defining ELEM is annotated
with @nma:implicit, DEFCONT is an XML fragment containing all
descendant elements of ELEM that have either @nma:implicit or
@nma:default attribute.</t>
</list></t>
<t>Inside the subtree of <rng:choice>, the @nma:default and
@nma:implicit annotations MUST be ignored unless they are
descendants of a <rng:group> or <rng:interleave>
pattern with @nma:implicit attribute set to "true" - this
corresponds to the default case of a YANG choice (see <xref
target="default-stmt"/>).</t>
<t>When mapping such a default case, it has to be guaranteed that
the default content is be applied if any of the nodes from any
non-default case are 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 top-level nodes
from all non-default cases. The rest of the element map is exactly
as above.</t>
<t>EXAMPLE. Consider the following YANG module:</t>
<figure>
<artwork>
<![CDATA[module example5 {
namespace "http://example.com/ns/example5";
prefix ex5;
container outer {
leaf leaf1 {
type uint8;
default 1;
}
choice one-or-two {
default "one";
container one {
leaf leaf2 {
type uint8;
default 2;
}
}
leaf leaf3 {
type uint8;
default 3;
}
}
}
}]]></artwork>
</figure>
<t>The DSRL schema generated for the "get-reply" target document
type will be:</t>
<figure>
<artwork>
<![CDATA[<dsrl:maps xmlns:dsrl="http://purl.oclc.org/dsdl/dsrl"
xmlns:ex5="http://example.com/ns/example5"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<dsrl:element-map>
<dsrl:parent>/nc:rpc-reply/nc:data</dsrl:parent>
<dsrl:name>ex5:outer</dsrl:name>
<dsrl:default-content>
<ex5:leaf1>1</ex5:leaf1>
<ex5:one><ex5:leaf2>2</ex5:leaf2></ex5:one>
</dsrl:default-content>
</dsrl:element-map>
<dsrl:element-map>
<dsrl:parent>
/nc:rpc-reply/nc:data/ex5:outer[not(ex5:leaf3)]
</dsrl:parent>
<dsrl:name>ex5:one</dsrl:name>
<dsrl:default-content>
<ex5:leaf2>2</ex5:leaf2>
</dsrl:default-content>
</dsrl:element-map>
<dsrl:element-map>
<dsrl:parent>/nc:rpc-reply/nc:data/ex5:outer</dsrl:parent>
<dsrl:name>ex5:leaf1</dsrl:name>
<dsrl:default-content>1</dsrl:default-content>
</dsrl:element-map>
<dsrl:element-map>
<dsrl:parent>/nc:rpc-reply/nc:data/ex5:outer</dsrl:parent>
<dsrl:name>ex5:one</dsrl:name>
<dsrl:default-content>
<ex5:leaf2>2</ex5:leaf2>
</dsrl:default-content>
</dsrl:element-map>
<dsrl:element-map>
<dsrl:parent>/nc:rpc-reply/nc:data/ex5:outer/ex5:one</dsrl:parent>
<dsrl:name>ex5:leaf2</dsrl:name>
<dsrl:default-content>2</dsrl:default-content>
</dsrl:element-map>
</dsrl:maps>]]>
</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 can never become an implicit
element.</t>
<t>YANG leaf nodes may also obtain a default value from their
type definition. Consequently, @nma:default attributes may also
be attached to <rng:define> elements. The DSRL mapping
MUST handle all <rng:element> patterns that refer to such
a named pattern definition and don't have their own @nma:default
attribute in the same way as if the @nma:default attributed was
attached to the referring <rng:element>.</t>
<t>Finally, if there is a chain of named pattern definitions
containing multiple @nma:default attributes, only the topmost
@nma:default annotation is taken into account.</t>
</section>
</section>
<section anchor="yang-to-rng"
title="Mapping YANG Statements to Conceptual Tree Schema">
<t>Each subsection in this section is devoted to one YANG
statement and provides the specification how the statement is
mapped to the annotated RELAX NG schema of the conceptual
tree. This is the first step of the mapping procedure, see <xref
target="mappingOverview"/>. 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 <nmt:rpc-methods> subtree (i.e., for RPC
input and output parameters) the order of subelements is fixed
and their definitions in the conceptual tree schema MUST follow
the order specified in the source YANG module.</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
conceptual tree schema MUST be enclosed in the
<rng:interleave> element.</t> <t>Otherwise, all
definitions of subelements in the conceptual tree schema MUST be
enclosed in the <rng:interleave> element.</t>
</list></t>
<t>We use the following notation:
<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 content of <rng:element>
is</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 RELAX NG element
definition.</t>
<t>If the '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 <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 latter 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 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 RPC definition or not. If the argument
of a sibling 'default' statement equals to ARGUMENT,
@nma:implicit attribute with the value "true" MUST be added to
that <rng:group> or <rng:interleave> element. The
@nma:implicit attribute MUST NOT be used for nodes that belong
to non-default cases of a choice (see <eref
target="http://tools.ietf.org/html/draft-ietf-netmod-yang-06#section-7.9.3">Section
7.9.3</eref> in <xref target="YANG"/>).</t>
</section>
<section anchor="choice-stmt" title="The choice Statement">
<t>This statement is mapped to <rng:choice> element.</t>
<t>Unless 'choice' has the 'mandatory' substatement with the
value "true", the <rng:choice> element MUST be wrapped in
<rng:optional>. The 'choice' statement with "mandatory
true;" requires additional handling, see <xref
target="mandatory-choice"/>.</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 is not used by the mapping since the output
RELAX NG schema may result from multiple YANG modules created by
different authors. The 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 "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, an extra <rng:group> or <rng:interleave>
element MUST be inserted with @nma:implicit attribute set to
"true" and the default case node is mapped inside this
element. The net result is then 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 mapped to</t>
<figure>
<artwork>
<![CDATA[<rng:choice>
<rng:interleave nma:implicit="true">
<rng:element name="yam:feuille">
<rng:empty/>
</rng:element>
</rng:interleave>
<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 MAY be ignored. Otherwise, it 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, see <xref
target="features-deviations"/>.</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, see <xref
target="features-deviations"/>.</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 <spanx style="emph">without
refinements and augments</spanx> 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>Whenever a grouping is used with additional refinements
and/or augments, the grouping is expanded so that the
refinements and augments may be applied directly 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 recording all
'grouping' 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="identity-stmt" title="The identity Statement">
<t>This statement is not specifically mapped. However, if the
identity defined by this statement is used as the base for an
"identityref" type in any of the input modules, ARGUMENT will
appear as the text of one of the <rng:value> elements in
the mapping of that "identityref" type. See <xref
target="identityref-type"/> for more details and an example.</t>
</section>
<section anchor="if-feature-stmt" title="The if-feature Statement">
<t>This statement is ignored, see <xref
target="features-deviations"/>.</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 be able to use its top-level groupings and typedefs 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 was a subset of 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 is
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>A leaf is optional if there is no "mandatory true;"
substatement and if the leaf is not declared among the keys of
an enclosing list. The <rng:element> element then MUST be
wrapped in <rng:optional>, except when the 'leaf'
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="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. 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. YANG leaf-list in a module with 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: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"/>.</t>
<t>When mapping the substatements of 'list', the order of
children of the list element MUST be specified so that list keys
always appear in the same order as they are defined in the input
YANG module and before other children, see <xref
target="YANG"/>, <eref
target="http://tools.ietf.org/html/draft-ietf-netmod-yang-07#section-7.8.5">Section
7.8.5</eref>. In particular, if any list key is defined in a
grouping but the list itself is not defined in 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 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
"yam:clef" definition 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>
</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 not specifically mapped except that a
<dc:source> element SHOULD be created as a child of
<rng:grammar> and contain ARGUMENT as a reference to the
input YANG module. See also <xref target="revision-stmt"/>.</t>
<t>With respect to the conceptual tree schema, substatements of
'module' MUST be mapped so that
<list style="symbols">
<t>top level data elements be defined as children of the
<nmt:top> element;</t>
<t>elements mapped from 'rpc' statements be defined as
children of the <nmt:rpc-methods> element;</t>
<t>elements mapped from 'notification' statements be defined
as children of the <nmt: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
get other subelements resulting from mapping 'error-app-tag' and
'error-message' substatements. Other substatements of 'must',
i.e., 'description' and 'reference', are ignored.</t>
<t>EXAMPLE. YANG statement</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 to @xmlns:xxx attribute of the
<rng:grammar> element where "xxx"
is the namespace prefix specified by the sibling 'prefix'
statement. ARGUMENT becomes the value of this attribute.</t>
</section>
<section anchor="notification-stmt"
title="The notification Statement">
<t>This statement is mapped to the following subtree in the
RELAX NG schema ("yam" is the prefix of the local YANG module):</t>
<figure>
<artwork>
<![CDATA[<rng:element name="nmt:notification">
<rng:element name="yam:ARGUMENT">
...
</rng:element>
</rng:element>]]></artwork>
</figure>
<t>Substatements of 'notification' are mapped under
<rng:element name="yam:ARGUMENT">.</t>
<t>The <rng:element name="nmt:rpc-notification"> element is
a child of <rng:element name="nmt:notifications">.</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 not used by the mapping since the output
RELAX NG schema may result from multiple YANG modules authored
by different parties. The schema contains references to all
input modules in the Dublin Core elements <dc:source>, see
<xref target="module-stmt"/>. The original 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 'rpc' statement, see <xref
target="rpc-stmt"/>.</t>
</section>
<section anchor="path-stmt" title="The path Statement">
<t>This statement is handled within "leafref" type, see <xref
target="leafref-type"/>.</t>
</section>
<section anchor="pattern-stmt" title="The pattern Statement">
<t>This statement is handled within "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 is mapped to the annotation attribute
@nma:presence with the value "true". In addition, it
influences the mapping of 'container' (<xref
target="container-stmt"/>): the parent container definition MUST
be wrapped in <rng:optional>, regardless of its
content. 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 MAY be ignored. Otherwise, it 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="YANG"/>. This date SHOULD be recorded,
together with the name of the YANG module, in the corresponding
Dublin Core element <dc:source> (see <xref
target="module-stmt"/>), for example in this form:</t>
<figure>
<artwork>
<![CDATA[<dc:source>YANG module 'foo', revision 2009-01-19</dc:source>]]></artwork>
</figure>
<t>The 'description' substatement of 'revision' is not used.</t>
</section>
<section anchor="rpc-stmt"
title="The rpc Statement">
<t>This statement is mapped to the following subtree in the
RELAX NG schema ("yam" is the prefix of the local YANG module):</t>
<figure>
<artwork>
<![CDATA[<rng:element name="nmt:rpc-method">
<rng:element name="nmt:input">
<rng:element name="yam:ARGUMENT">
<!-- mapped content of 'input' -->
</rng:element>
</rng:element>
<rng:element name="nmt:output">
<!-- mapped content of 'output' -->
</rng:element>
</rng:element>]]></artwork>
</figure>
<t>As indicated by the comments, contents of the 'input'
substatement (if any) are mapped under <rng:element
name="yam:ARGUMENT">. Similarly, contents of the 'output'
substatement are mapped under <rng:element
name="nmt:output">. If there is no 'output' substatement, the
<rng:element name="nmt:output"> MUST NOT be present.</t>
<t>The <rng:element name="nmt:rpc-method"> element is
a child of <rng:element name="nmt:rpc-methods">.</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 types 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="Selected datatypes from 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>boolean</c><c>boolean</c><c>"true" or "false"</c>
<c>binary</c><c>base64Binary</c><c>binary data in base64 encoding</c>
</texttable>
<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="boobi-types" title="The boolean and binary Types">
<t>These two built-in types do not allow any restrictions and
are mapped simply by inserting <rng:data> element whose
@type attribute is set to ARGUMENT mapped according to <xref
target="tab-types"/> above.</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 the corresponding 'bit' statement.</t>
</section>
<section anchor="enuun-type"
title="The enumeration and union Types">
<t>These types are mapped to <rng:choice> element.</t>
</section>
<section anchor="identityref-type"
title="The identityref Type">
<t>This type is mapped to <rng:choice> element with one
or more <rng:value> subelements. Each of the
<rng:value> subelements MUST have the @type attribute and
its value set to "QName". One <rng:value> subelement for
the base identity MUST always be present - it
contains the argument of the 'base' substatement as its text.
In addition, one <rng:value>
substatement MUST be added for each identity declared locally
or in an imported module that is derived from this base
identity.</t>
<t>All namespace prefixes that are used for identities from
imported modules MUST be appropriately defined.</t>
<t>EXAMPLE (taken from <eref
target="http://tools.ietf.org/html/draft-ietf-netmod-yang-05#section-7.16.3">Section 7.16.3</eref>
of <xref target="YANG"/>). Consider the following two 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>If these two modules are imported to another module with
namespace prefix "yam", leaf
definition</t>
<figure>
<artwork>
<![CDATA[leaf crypto {
type identityref {
base "crypto:crypto-alg";
}
}]]></artwork>
</figure>
<t>is mapped to</t>
<figure>
<artwork>
<![CDATA[<rng:element name="yam:crypto">
<rng:choice>
<rng:value type="QName">crypto:crypto-alg</value>
<rng:value type="QName">des:des</value>
<rng:value type="QName">des:des3</value>
</rng:choice>
</rng:element>]]></artwork>
</figure>
<t>The "crypto" and "des" prefixes will by typically defined
via attributes of the <rng:grammar> element.</t>
</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, empty
<nma:instance-identifier> element MUST be inserted as a
child of PARENT.</t>
<t>The 'require-instance' substatement, if it exists, is
mapped to the @require-instance attribute of
<nma:instance-identifier>.</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. 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 mapped according to <xref
target="tab-types"/>.</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 the "totalDigits" facet 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
handled as follows:</t>
<t>If the range expression has just a single range,
then
<list style="symbols">
<t>if the range consists of a single number, the
<rng:value> pattern is inserted and its content set to
this number.</t>
<t>Otherwise the range consists of both lower and upper
bound and the following pair of datatype facets are
inserted:
<figure>
<artwork>
<![CDATA[<rng:param name="minInclusive">...</rng:param>
]]></artwork>
</figure>
and
<figure>
<artwork>
<![CDATA[<rng:param name="maxInclusive">...</rng:param>
]]></artwork>
</figure>
Their contents are the lower and upper bound,
respectively. If the lower bound is "min", the
"minInclusive" facet is omitted and if the upper bound is
"max", the "maxInclusive" facet is omitted.</t>
</list></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 the <rng:data> elements are
wrapped in <rng:choice> element. Each <rng:data>
element contains the <rng:value> pattern or the
"minInclusive" and "maxInclusive" facets for the corresponding
part of the range expression as described in the previous
paragraph. For the "decimal64" type, the "totalDigits" and
"fractionDigits" must be repeated inside each of the
<rng:data> elements.</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:value>42</rng:value>
</rng:data>
<rng:data type="int">
<rng:param name="minInclusive">100</rng:param>
</rng:data>
</rng:choice>]]></artwork>
</figure>
</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 L, the
following datatype facet is inserted:
<figure>
<artwork>
<![CDATA[<rng:param name="length">L</rng:param>]]>.
</artwork>
</figure></t>
<t>Otherwise the length range consists of both lower and
upper bound and the following pair of datatype facets are
inserted:
<figure>
<artwork>
<![CDATA[<rng:param name="minLength">...</rng:param>
]]></artwork>
</figure>
and
<figure>
<artwork>
<![CDATA[<rng:param name="maxLength">...</rng:param>
]]></artwork>
</figure>
Their contents are the lower and upper bound of the length
range, respectively. If the lower bound is "min", the
"minLength" facet is omitted and if the upper bound is
"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 the <rng:data>
elements are wrapped in <rng:choice> element. Each
<rng:data> element contains the "length" or "minLength"
and "maxLength" facets for the corresponding 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 content 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 output schema yet, the
corresponding 'typedef' must be found and its mapping
installed as a subelement of <rng:grammar>, 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 is used. Restrictions appearing at
all stages of the 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 <spanx style="emph">without
restrictions</spanx> 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>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
is 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 and the
value of its @name attribute is set to ARGUMENT mangled
according to <xref target="grouping-typedef"/></t>
<t>If there are any 'refine' or 'augment' substatements, the
corresponding grouping must be looked up and its contents is
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).</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="nma-to-dsdl"
title="Mapping NETMOD-specific annotations to DSDL Schema Languages">
<t>This section contains mapping specification for individual
NETMOD-specific annotations. In each case, the result of the
mapping must be inserted into an appropriate context of the target
DSDL schema as described in <xref target="cts-to-dsdl"/>. The
context is determined by the element definition in the conceptual
tree schema to which the annotation is attached. In the rest of
this section, we will denote CONTELEM the name of this context
element properly qualified with its namespace prefix. Unless
otherwise stated, Schematron asserts are descendants of the
"standard" pattern and therefore active in both validation
phases.</t>
<section anchor="nma-config" title="The @nma:config Annotation">
<t>If this annotation is present with the value "true", the
following rules apply for DSDL schemas of <nc:get-config>
reply. In particular:
<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 conceptual tree
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-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-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-instance-identifier"
title="The <nma:instance-identifier> Annotation">
<t>If this annotation element has the @require-instance
attribute with the value "false", it is ignored. Otherwise it is
mapped to the following Schematron assert:</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 runtime. Such an extension function is
provided by some XSLT processors, for example <eref
target="http://www.saxonica.com/">Saxon</eref>.</t>
</section>
<section anchor="nma-key" title="The @nma:key Annotation">
<t>Assume this annotation has the value "k_1 k_2 ... k_n", i.e.,
specifies n child leaves as keys. The annotation is then mapped
to the following Schematron report:</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 C_i, for i=1,2,...,n, specifies the condition for
violation of uniqueness of key k_i, namely</t>
<figure>
<artwork>
k_i=current()/k_i</artwork>
</figure>
</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=.">
Leafref "CONTELEM" must have the same value as "PATH"
</sch:assert>
]]></artwork>
</figure>
<t>where PATH is the value of @nma:leafref. The assert is a
descendant of the "ref-integrity" pattern, which means that it
will be used only for the "full" validation phase.</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">
List "CONTELEM" - item count 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 content, 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 if "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 registers three namespace URIs in the IETF XML
registry <xref target="RFC3688"/>:</t>
<figure>
<artwork>URI: urn:ietf:params:xml:ns:netmod:dsdl-annotations:1</artwork>
</figure>
<figure>
<artwork>URI: urn:ietf:params:xml:ns:netmod:conceptual-tree:1</artwork>
</figure>
<figure>
<artwork>urn:ietf:params:xml:ns:netmod:xpath-extensions:1</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 content of NETCONF protocol data units or entire
data stores 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="acknowledgements" title="Acknowledgements">
<t>The authors wish to thank the following individuals who
provided helpful suggestions and/or comments on various versions
of this document: Andy Bierman, Martin Bjorklund, Jirka Kosek 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="11" 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="12" year="2008"/>
</front>
<seriesInfo name="ISO/IEC" value="19757-8:2008(E)"/>
</reference>
<reference anchor="NVDL">
<front>
<title>Information Technology - Document Schema Definition
Languages (DSDL) - Part 4: Namespace-Based Validation
Dispatching Language (NVDL)</title>
<author fullname="ISO/IEC">
<organization>ISO/IEC</organization>
</author>
<date day="1" month="6" year="2006"/>
</front>
<seriesInfo name="ISO/IEC" value="19757-4:2006(E)"/>
<format type="ZIP"
target="http://standards.iso.org/ittf/PubliclyAvailableStandards/c040833_ISO_IEC_19757-4_2006(E).zip"/>
</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='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="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="12" 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="1" 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="6" 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 (Fourth 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='François Yergeau'>
<organization />
</author>
<date month='August' day='16' year='2006' />
</front>
<seriesInfo name='World Wide Web Consortium Recommendation'
value='REC-xml-20060816' />
<format type='HTML'
target='http://www.w3.org/TR/2006/REC-xml-20060816' />
</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='YANG'>
<front>
<title>YANG - A data modeling language for NETCONF</title>
<author role="editor" initials='M' surname='Bjorklund'
fullname='Martin Bjorklund'>
<organization />
</author>
<date month='March' day='6' year='2009' />
</front>
<seriesInfo name='Internet-Draft'
value='draft-ietf-netmod-yang-04' />
<format type='HTML'
target='http://tools.ietf.org/html/draft-ietf-netmod-yang-04' />
</reference>
</references>
<references title="Informative References">
<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='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='RFC3216'>
<front>
<title>SMIng Objectives</title>
<author initials='C.' surname='Elliott' fullname='C. Elliott'>
<organization/></author>
<author initials='D.' surname='Harrington' fullname='D. Harrington'>
<organization /></author>
<author initials='J.' surname='Jason' fullname='J. Jason'>
<organization /></author>
<author initials='J.' surname='Schoenwaelder'
fullname='J. Schoenwaelder'>
<organization /></author>
<author initials='F.' surname='Strauss' fullname='F. Strauss'>
<organization /></author>
<author initials='W.' surname='Weiss' fullname='W. Weiss'>
<organization /></author>
<date year='2001' month='December' />
</front>
<seriesInfo name='RFC' value='3216' />
<format type='TXT' octets='58551'
target='http://www.ietf.org/rfc/rfc3216.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="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>
<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='Ytypes'>
<front>
<title>Common YANG Data Types</title>
<author role="editor" initials='J.' surname='Schoenwaelder'
fullname='Juergen Schoenwaelder'>
<organization />
</author>
<date month='May' day='13' year='2009' />
</front>
<seriesInfo name='Internet-Draft'
value='draft-ietf-netmod-yang-types-03' />
<format type='HTML'
target='http://tools.ietf.org/html/draft-ietf-netmod-yang-types-03'/>
</reference>
</references>
<section anchor="nma-schema"
title="Schemas for NETMOD-Specific Annotations">
<t>This appendix utilizes Namespace-Based Validation Dispatching
Language (NVDL, Part 4 of DSDL) <xref target="NVDL"/> to define
NETMOD-specific annotations as extensions of the RELAX NG
language. The NVDL schema may be used for validating conceptual
tree schemas as compound XML documents consisting of RELAX NG
sections and embedded sections with NETMOD-specific
annotations. The NVDL schema dispatches the validation as follows:
<list style="numbers">
<t>RELAX NG sections identified by the namespace URI
"http://relaxng.org/ns/structure/1.0" is validated with the
standard RELAX NG schema for RELAX NG, see <xref target="RNG"/>,
Annex A.</t>
<t>NETMOD-specific annotation sections identified by the
namespace URI "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1"
are validated by several context-dependent RELAX NG schemas
given below.</t>
<t>Other sections such as Dublin Core metadata or
<a:documentation> annotation are attached to and validated
together with the parent RELAX NG section.</t>
</list></t>
<section anchor="nma-nvdl"
title="NVDL Schema">
<figure>
<artwork>
<![CDATA[== CODE BEGINS: file "nmannot.nvdl"
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE nvdl:rules [<!ENTITY nmannot-uri
"urn:ietf:params:xml:ns:netmod:dsdl-annotations:1">
]>
<rules xmlns="http://purl.oclc.org/dsdl/nvdl/ns/structure/1.0"
startMode="rng">
<mode name="rng">
<namespace ns="http://relaxng.org/ns/structure/1.0">
<validate schema="http://relaxng.org/relaxng.rng"
useMode="other">
<context path="define" useMode="define"/>
<context path="oneOrMore/element" useMode="list"/>
<context path="element" useMode="element"/>
<context path="choice/group|choice/interleave"
useMode="group-interleave"/>
<context path="choice|ref" useMode="choice-ref"/>
<context path="value" useMode="value"/>
</validate>
</namespace>
</mode>
<mode name="define">
<namespace ns="&nmannot-uri;" match="attributes">
<validate schema="define.rng"/>
</namespace>
</mode>
<mode name="element">
<namespace ns="&nmannot-uri;" match="elements">
<validate schema="element-el.rng"/>
</namespace>
<namespace ns="&nmannot-uri;" match="attributes">
<validate schema="element-att.rng"/>
</namespace>
</mode>
<mode name="group-interleave">
<namespace ns="&nmannot-uri;" match="attributes">
<validate schema="group-interleave.rng"/>
</namespace>
</mode>
<mode name="choice-ref">
<namespace ns="&nmannot-uri;" match="attributes">
<validate schema="choice-ref.rng"/>
</namespace>
</mode>
<mode name="list">
<namespace ns="&nmannot-uri;" match="attributes">
<validate schema="list.rng"/>
</namespace>
</mode>
<mode name="value">
<namespace ns="&nmannot-uri;" match="attributes">
<validate schema="value.rng"/>
</namespace>
</mode>
<mode name="other">
<namespace ns="&nmannot-uri;" match="elements attributes">
<reject/>
</namespace>
<anyNamespace match="elements attributes">
<attach/>
</anyNamespace>
</mode>
</rules>
== CODE ENDS]]></artwork>
</figure>
</section>
<section anchor="nma-define"
title="Annotation Attributes for define Pattern">
<figure>
<artwork>
<![CDATA[== CODE BEGINS: file "define.rng"
<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="nmannotdefs.rng"/>
<start>
<group>
<ref name="default-attribute"/>
<ref name="status-attribute"/>
<ref name="units-attribute"/>
</group>
</start>
</grammar>
== CODE ENDS]]></artwork>
</figure>
</section>
<section anchor="nma-element-el"
title="Annotation Elements for element Pattern">
<figure>
<artwork>
<![CDATA[== CODE BEGINS: file "element-el.rng"
<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="nmannotdefs.rng"/>
<start>
<choice>
<ref name="must-element"/>
<ref name="instance-identifier-element"/>
</choice>
</start>
</grammar>
== CODE ENDS]]></artwork>
</figure>
</section>
<section anchor="nma-element-att"
title="Annotation Attributes for element Pattern">
<figure>
<artwork>
<![CDATA[== CODE BEGINS: file "element-att.rng"
<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="nmannotdefs.rng"/>
<start>
<group>
<ref name="config-attribute"/>
<ref name="default-attribute"/>
<ref name="implicit-attribute"/>
<ref name="leafref-attribute"/>
<ref name="presence-attribute"/>
<ref name="status-attribute"/>
<ref name="units-attribute"/>
<ref name="when-attribute"/>
</group>
</start>
</grammar>
== CODE ENDS]]></artwork>
</figure>
</section>
<section anchor="nma-group"
title="Annotation attributes for group Pattern">
<figure>
<artwork>
<![CDATA[== CODE BEGINS: file "group-interleave.rng"
<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="nmannotdefs.rng"/>
<start>
<group>
<ref name="implicit-attribute"/>
<ref name="status-attribute"/>
<ref name="when-attribute"/>
</group>
</start>
</grammar>
== CODE ENDS]]></artwork>
</figure>
</section>
<section anchor="nma-choice-ref"
title="Annotation attributes for choice and ref Patterns">
<figure>
<artwork>
<![CDATA[== CODE BEGINS: file "choice-ref.rng"
<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="nmannotdefs.rng"/>
<start>
<group>
<ref name="status-attribute"/>
<ref name="when-attribute"/>
</group>
</start>
</grammar>
== CODE ENDS]]></artwork>
</figure>
</section>
<section anchor="nma-list"
title="Annotation attributes for element Pattern in the
List Context">
<figure>
<artwork>
<![CDATA[== CODE BEGINS: file "list.rng"
<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="nmannotdefs.rng"/>
<start>
<group>
<ref name="key-attribute"/>
<ref name="min-elements-attribute"/>
<ref name="max-elements-attribute"/>
<ref name="ordered-by-attribute"/>
<ref name="unique-attribute"/>
</group>
</start>
</grammar>
== CODE ENDS]]></artwork>
</figure>
</section>
<section anchor="nma-value"
title="Annotation attributes for value Pattern">
<figure>
<artwork>
<![CDATA[== CODE BEGINS: file "value.rng"
<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="nmannotdefs.rng"/>
<start>
<ref name="status-attribute"/>
</start>
</grammar>
== CODE ENDS]]></artwork>
</figure>
</section>
<section anchor="nma-named-patterns"
title="Named Patterns for All NETMOD-Specific Annotations">
<figure>
<artwork>
<![CDATA[== CODE BEGINS: file "nmannotdefs.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">
<optional>
<attribute name="nma:config">
<data type="boolean"/>
</attribute>
</optional>
</define>
<define name="default-attribute">
<optional>
<attribute name="nma:default"/>
</optional>
</define>
<define name="implicit-attribute">
<optional>
<attribute name="nma:implicit">
<data type="boolean"/>
</attribute>
</optional>
</define>
<define name="error-app-tag-element">
<optional>
<element name="nma:error-app-tag">
<text/>
</element>
</optional>
</define>
<define name="error-message-element">
<optional>
<element name="nma:error-message">
<text/>
</element>
</optional>
</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">
<optional>
<attribute name="nma:key">
<list>
<data type="QName"/>
</list>
</attribute>
</optional>
</define>
<define name="leafref-attribute">
<optional>
<attribute name="nma:leafref">
<data type="string"/>
</attribute>
</optional>
</define>
<define name="min-elements-attribute">
<optional>
<attribute name="nma:min-elements">
<data type="nonNegativeInteger"/>
</attribute>
</optional>
</define>
<define name="max-elements-attribute">
<optional>
<attribute name="nma:max-elements">
<data type="nonNegativeInteger"/>
</attribute>
</optional>
</define>
<define name="must-element">
<element name="nma:must">
<attribute name="assert">
<data type="string"/>
</attribute>
<interleave>
<ref name="error-app-tag-element"/>
<ref name="error-message-element"/>
</interleave>
</element>
</define>
<define name="ordered-by-attribute">
<optional>
<attribute name="nma:ordered-by">
<choice>
<value>user</value>
<value>system</value>
</choice>
</attribute>
</optional>
</define>
<define name="presence-attribute">
<optional>
<attribute name="nma:presence">
<value>true</value>
</attribute>
</optional>
</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>
</grammar>
== CODE ENDS]]></artwork>
</figure>
</section>
</section>
<section anchor="app-library" title="Schema-Independent Library">
<t>In order to avoid copying the same named pattern definitions to
the RELAX NG schemas generated in the second mapping step, we
collected these definitions to a library file - schema-independent
library - which is included by the validating schemas under the
file name "relaxng-lib.rng" (XML syntax) and "relaxng-lib.rnc"
(compact syntax). The included definitions cover patterns for
common elements from base NETCONF <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" <eref
target="http://www.yang-central.org/twiki/bin/view/Main/DhcpTutorial">DHCP
tutorial</eref> data model. The input (single) YANG module is
shown in <xref target="app-dhcp-yang"/> and the output schemas in
the following two subsections.</t>
<t>The conceptual tree schema was obtained by the "rng" plugin of
the <eref target="http://code.google.com/p/pyang/">pyang</eref>
tool and the validating DSDL schemas by XSLT stylesheets that are
also part of pyang distribution. RELAX NG schemas are shown in
both XML and compact syntax. The latter was obtained from the
former by using the <eref
target="http://thaiopensource.com/relaxng/trang.html">Trang
tool</eref></t>
<t>Due to the limit of 72 characters per line, few long strings
required manual editing, in particular the regular expression
patterns for IP addresses etc. in the RELAX NG schemas. In the
compact syntax we broke the patterns to appropriate segments and
joined them with the concatenation operator "~". In the XML
syntax, though, the long patterns had to be replaced by the
placeholder string "... regex pattern ...". Also, line breaks were
added to several documentation strings and Schematron
messages. Other than that, the results of the automatic
translations were not changed.</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-cts" title="Conceptual Tree Schema">
<section title="XML Syntax">
<figure>
<artwork>
<![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<grammar
xmlns="http://relaxng.org/ns/structure/1.0"
xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"
xmlns:dc="http://purl.org/dc/terms"
xmlns:dhcp="http://example.com/ns/dhcp"
xmlns:nma="urn:ietf:params:xml:ns:netmod:dsdl-annotations:1"
xmlns:nmt="urn:ietf:params:xml:ns:netmod:conceptual-tree:1"
datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
<dc:creator>Pyang 0.9.3, CTS plugin</dc:creator>
<dc:source>YANG module 'dhcp'</dc:source>
<start>
<element name="nmt:netmod-tree">
<element name="nmt:top">
<interleave>
<optional>
<element name="dhcp:dhcp" nma:implicit="true">
<interleave>
<a:documentation>
configuration and operational parameters for a DHCP server
</a:documentation>
<optional>
<element name="dhcp:max-lease-time"
nma:default="7200" nma:units="seconds">
<data type="unsignedInt"/>
</element>
</optional>
<optional>
<element name="dhcp:default-lease-time"
nma:default="600" 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">
<interleave>
<zeroOrMore>
<element name="dhcp:shared-network"
nma:key="dhcp:name">
<element name="dhcp:name">
<data type="string"/>
</element>
<interleave>
<ref name="_dhcp__subnet-list"/>
</interleave>
</element>
</zeroOrMore>
</interleave>
</element>
</optional>
<optional>
<element name="dhcp:status" nma:config="false">
<interleave>
<zeroOrMore>
<element name="dhcp:leases"
nma:key="dhcp:address">
<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>
</interleave>
</element>
</optional>
</interleave>
</element>
</optional>
</interleave>
</element>
<element name="nmt:rpc-methods">
<empty/>
</element>
<element name="nmt:notifications">
<empty/>
</element>
</element>
</start>
<define name="_dhcp__subnet-list">
<interleave>
<a:documentation>A reusable list of subnets</a:documentation>
<zeroOrMore>
<element name="dhcp:subnet" nma:key="dhcp:net">
<element name="dhcp:net">
<ref name="ietf-inet-types__ip-prefix"/>
</element>
<interleave>
<optional>
<element name="dhcp:range">
<interleave>
<optional>
<element name="dhcp:dynamic-bootp">
<a:documentation>
Allows BOOTP clients to get addresses in this range
</a:documentation>
<empty/>
</element>
</optional>
<element name="dhcp:low">
<ref name="ietf-inet-types__ip-address"/>
</element>
<element name="dhcp:high">
<ref name="ietf-inet-types__ip-address"/>
</element>
</interleave>
</element>
</optional>
<optional>
<element name="dhcp:dhcp-options">
<interleave>
<a:documentation>
Options in the DHCP protocol
</a:documentation>
<zeroOrMore>
<element name="dhcp: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="dhcp: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 name="dhcp:max-lease-time"
nma:default="7200" nma:units="seconds">
<data type="unsignedInt"/>
</element>
</optional>
</interleave>
</element>
</zeroOrMore>
</interleave>
</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__ipv4-prefix">
<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>
<define name="ietf-inet-types__ipv4-address">
<data type="string">
<param name="pattern">... regex pattern ...</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__host">
<choice>
<ref name="ietf-inet-types__ip-address"/>
<ref name="ietf-inet-types__domain-name"/>
</choice>
</define>
<define name="ietf-inet-types__domain-name">
<data type="string">
<param name="minLength">1</param>
<param name="maxLength">253</param>
<param name="pattern">... regex pattern ...</param>
</data>
</define>
<define name="ietf-yang-types__date-and-time">
<data type="string">
<param name="pattern">... regex pattern ...</param>
</data>
</define>
<define name="ietf-yang-types__phys-address">
<data type="string">
<param name="pattern">
([0-9a0-fA-F]{2}(:[0-9a0-fA-F]{2})*)?
</param>
</data>
</define>
</grammar>
]]></artwork>
</figure>
</section>
<section title="Compact Syntax">
<figure>
<artwork>
<![CDATA[namespace a = "http://relaxng.org/ns/compatibility/annotations/1.0"
namespace dc = "http://purl.org/dc/terms"
namespace dhcp = "http://example.com/ns/dhcp"
namespace nma = "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1"
namespace nmt = "urn:ietf:params:xml:ns:netmod:conceptual-tree:1"
dc:creator [ "Pyang 0.9.3, CTS plugin" ]
dc:source [ "YANG module 'dhcp'" ]
start =
element nmt:netmod-tree {
element nmt:top {
[ nma:implicit = "true" ]
element dhcp:dhcp {
##
## configuration and operational parameters for a DHCP server
##
([ nma:default = "7200" nma:units = "seconds" ]
element dhcp:max-lease-time { xsd:unsignedInt }?
& [ nma:default = "600" nma:units = "seconds" ]
element dhcp:default-lease-time {
xsd:unsignedInt
>> nma:must [
assert = ". <= ../dhcp:max-lease-time"
nma:error-message [
"\x{a}" ~
"The default-lease-time must be less than max-lease-time." ~
"\x{a}"
]
]
}?
& _dhcp__subnet-list
& element dhcp:shared-networks {
[ nma:key = "dhcp:name" ]
element dhcp:shared-network {
element dhcp:name { xsd:string },
(_dhcp__subnet-list)
}*
}?
& [ nma:config = "false" ]
element dhcp:status {
[ nma:key = "dhcp:address" ]
element dhcp:leases {
element dhcp:address { ietf-inet-types__ip-address },
(element dhcp:starts { ietf-yang-types__date-and-time }?
& element dhcp:ends { ietf-yang-types__date-and-time }?
& element dhcp:hardware {
element dhcp:type {
"ethernet" | "token-ring" | "fddi"
}?
& element dhcp:address {
ietf-yang-types__phys-address
}?
}?)
}*
}?)
}?
},
element nmt:rpc-methods { empty },
element nmt:notifications { empty }
}
_dhcp__subnet-list =
## A reusable list of subnets
([ nma:key = "dhcp:net" ]
element dhcp:subnet {
element dhcp:net { ietf-inet-types__ip-prefix },
(element dhcp:range {
##
## Allows BOOTP clients to get addresses in this range
##
element dhcp:dynamic-bootp { empty }?
& element dhcp:low { ietf-inet-types__ip-address }
& element dhcp:high { ietf-inet-types__ip-address }
}?
& element dhcp:dhcp-options {
##
## Options in the DHCP protocol
##
(
##
## See: RFC 2132, sec. 3.8
##
[ nma:ordered-by = "user" ]
element dhcp:router { ietf-inet-types__host }*
&
##
## See: RFC 2132, sec. 3.17
##
element dhcp:domain-name { ietf-inet-types__domain-name }?)
}?
& [ nma:default = "7200" nma:units = "seconds" ]
element dhcp:max-lease-time { xsd:unsignedInt }?)
}*)
ietf-inet-types__ip-prefix =
ietf-inet-types__ipv4-prefix | ietf-inet-types__ipv6-prefix
ietf-inet-types__ipv4-prefix =
xsd:string { pattern = "... regex pattern ..." }
ietf-inet-types__ipv6-prefix =
xsd:string {
pattern = "... regex pattern ..."
pattern = "... regex pattern ..."
}
ietf-inet-types__ip-address =
ietf-inet-types__ipv4-address | ietf-inet-types__ipv6-address
ietf-inet-types__ipv4-address =
xsd:string { pattern = "... regex pattern ..." }
ietf-inet-types__ipv6-address =
xsd:string {
pattern = "... regex pattern ..."
pattern = "... regex pattern ..."
}
ietf-inet-types__host =
ietf-inet-types__ip-address | ietf-inet-types__domain-name
ietf-inet-types__domain-name =
xsd:string {
minLength = "1"
maxLength = "253"
pattern = "... regex pattern ..."
}
ietf-yang-types__date-and-time =
xsd:string { pattern = "... regex pattern ..." }
ietf-yang-types__phys-address =
xsd:string {
pattern = "([0-9a0-fA-F]{2}(:[0-9a0-fA-F]{2})*)?"
}
]]></artwork>
</figure>
</section>
</section>
<section anchor="app-dhcp-2" title="Final DSDL Schemas">
<t>This appendix contains DSDL schemas that were obtained from the
conceptual tree schema in <xref target="app-dhcp-cts"/> by XSL
transformations. These schemas can be directly used for validating
a reply to unfiltered <get> with the contents corresponding
to the DHCP data model.</t>
<t>The RELAX NG schema (again shown in both XML and compact
syntax) includes the schema independent library from <xref
target="app-library"/>.</t>
<section title="RELAX NG Schema for <get> Reply - XML Syntax">
<figure>
<artwork>
<![CDATA[<?xml version="1.0" encoding="utf-8"?>
<grammar
xmlns="http://relaxng.org/ns/structure/1.0"
xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"
xmlns:dc="http://purl.org/dc/terms"
xmlns:dhcp="http://example.com/ns/dhcp"
xmlns:nma="urn:ietf:params:xml:ns:netmod:dsdl-annotations:1"
xmlns:nmt="urn:ietf:params:xml:ns:netmod:conceptual-tree:1"
datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"
ns="urn:ietf:params:xml:ns:netconf:base:1.0">
<include href="relaxng-lib.rng"/>
<start>
<element name="rpc-reply">
<ref name="message-id-attribute"/>
<element name="data">
<interleave>
<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">
<interleave>
<zeroOrMore>
<element name="dhcp:shared-network">
<element name="dhcp:name">
<data type="string"/>
</element>
<interleave>
<ref name="_dhcp__subnet-list"/>
</interleave>
</element>
</zeroOrMore>
</interleave>
</element>
</optional>
<optional>
<element name="dhcp:status">
<interleave>
<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>
</interleave>
</element>
</optional>
</interleave>
</element>
</optional>
</interleave>
</element>
</element>
</start>
<define name="_dhcp__subnet-list">
<interleave>
<zeroOrMore>
<element name="dhcp:subnet">
<element name="dhcp:net">
<ref name="ietf-inet-types__ip-prefix"/>
</element>
<interleave>
<optional>
<element name="dhcp:range">
<interleave>
<optional>
<element name="dhcp:dynamic-bootp">
<empty/>
</element>
</optional>
<element name="dhcp:low">
<ref name="ietf-inet-types__ip-address"/>
</element>
<element name="dhcp:high">
<ref name="ietf-inet-types__ip-address"/>
</element>
</interleave>
</element>
</optional>
<optional>
<element name="dhcp:dhcp-options">
<interleave>
<zeroOrMore>
<element name="dhcp:router">
<ref name="ietf-inet-types__host"/>
</element>
</zeroOrMore>
<optional>
<element name="dhcp:domain-name">
<ref name="ietf-inet-types__domain-name"/>
</element>
</optional>
</interleave>
</element>
</optional>
<optional>
<element name="dhcp:max-lease-time">
<data type="unsignedInt"/>
</element>
</optional>
</interleave>
</element>
</zeroOrMore>
</interleave>
</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__ipv4-prefix">
<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>
<define name="ietf-inet-types__ipv4-address">
<data type="string">
<param name="pattern">... regex pattern ...</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__host">
<choice>
<ref name="ietf-inet-types__ip-address"/>
<ref name="ietf-inet-types__domain-name"/>
</choice>
</define>
<define name="ietf-inet-types__domain-name">
<data type="string">
<param name="minLength">1</param>
<param name="maxLength">253</param>
<param name="pattern">... regex pattern ...</param>
</data>
</define>
<define name="ietf-yang-types__date-and-time">
<data type="string">
<param name="pattern">... regex pattern ...</param>
</data>
</define>
<define name="ietf-yang-types__phys-address">
<data type="string">
<param name="pattern">
([0-9a0-fA-F]{2}(:[0-9a0-fA-F]{2})*)?
</param>
</data>
</define>
</grammar>
]]></artwork>
</figure>
</section>
<section
title="RELAX NG Schema for <get> Reply - Compact Syntax">
<figure>
<artwork>
<![CDATA[default namespace = "urn:ietf:params:xml:ns:netconf:base:1.0"
namespace a = "http://relaxng.org/ns/compatibility/annotations/1.0"
namespace dc = "http://purl.org/dc/terms"
namespace dhcp = "http://example.com/ns/dhcp"
namespace nma = "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1"
namespace nmt = "urn:ietf:params:xml:ns:netmod:conceptual-tree:1"
include "relaxng-lib.rnc"
start =
element rpc-reply {
message-id-attribute,
element data {
element dhcp:dhcp {
element dhcp:max-lease-time { xsd:unsignedInt }?
& element dhcp:default-lease-time { xsd:unsignedInt }?
& _dhcp__subnet-list
& element dhcp:shared-networks {
element dhcp:shared-network {
element dhcp:name { xsd:string },
(_dhcp__subnet-list)
}*
}?
& element dhcp:status {
element dhcp:leases {
element dhcp:address { ietf-inet-types__ip-address },
(element dhcp:starts { ietf-yang-types__date-and-time }?
& element dhcp:ends { ietf-yang-types__date-and-time }?
& element dhcp:hardware {
element dhcp:type {
"ethernet" | "token-ring" | "fddi"
}?
& element dhcp:address {
ietf-yang-types__phys-address
}?
}?)
}*
}?
}?
}
}
_dhcp__subnet-list =
element dhcp:subnet {
element dhcp:net { ietf-inet-types__ip-prefix },
(element dhcp:range {
element dhcp:dynamic-bootp { empty }?
& element dhcp:low { ietf-inet-types__ip-address }
& element dhcp:high { ietf-inet-types__ip-address }
}?
& element dhcp:dhcp-options {
element dhcp:router { ietf-inet-types__host }*
& element dhcp:domain-name { ietf-inet-types__domain-name }?
}?
& element dhcp:max-lease-time { xsd:unsignedInt }?)
}*
ietf-inet-types__ip-prefix =
ietf-inet-types__ipv4-prefix | ietf-inet-types__ipv6-prefix
ietf-inet-types__ipv4-prefix =
xsd:string { pattern = "... regex pattern ..." }
ietf-inet-types__ipv6-prefix =
xsd:string {
pattern = "... regex pattern ..."
pattern = "... regex pattern ..."
}
ietf-inet-types__ip-address =
ietf-inet-types__ipv4-address | ietf-inet-types__ipv6-address
ietf-inet-types__ipv4-address =
xsd:string { pattern = "... regex pattern ..." }
ietf-inet-types__ipv6-address =
xsd:string {
pattern = "... regex pattern ..."
pattern = "... regex pattern ..."
}
ietf-inet-types__host =
ietf-inet-types__ip-address | ietf-inet-types__domain-name
ietf-inet-types__domain-name =
xsd:string {
minLength = "1"
maxLength = "253"
pattern = "... regex pattern ..."
}
ietf-yang-types__date-and-time =
xsd:string { pattern = "... regex pattern ..." }
ietf-yang-types__phys-address =
xsd:string {
pattern =
"\x{a}" ~
" ([0-9a0-fA-F]{2}(:[0-9a0-fA-F]{2})*)?\x{a}" ~
" "
}
]]></artwork>
</figure>
</section>
</section>
<section title="Schematron Schema for <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:phase id="full">
<sch:active pattern="standard"/>
<sch:active pattern="ref-integrity"/>
</sch:phase>
<sch:phase id="noref">
<sch:active pattern="standard"/>
</sch:phase>
<sch:pattern id="standard">
<sch:rule id="std-id2247270" abstract="true">
<sch:report test="preceding-sibling::dhcp:subnet
[dhcp:net=current()/dhcp:net]">
Duplicate key of list dhcp:subnet
</sch:report>
</sch:rule>
<sch:rule context="/nc:rpc-reply/nc:data/dhcp:dhcp/
dhcp:default-lease-time">
<sch:assert test=". <= ../dhcp:max-lease-time">
The default-lease-time must be less than max-lease-time.
</sch:assert>
</sch:rule>
<sch:rule context="/nc:rpc-reply/nc:data/dhcp:dhcp/dhcp:subnet">
<sch:extends rule="std-id2247270"/>
</sch:rule>
<sch:rule context="/nc:rpc-reply/nc:data/dhcp:dhcp/
dhcp:shared-networks/dhcp:shared-network">
<sch:report test="preceding-sibling::dhcp:shared-network
[dhcp:name=current()/dhcp:name]">
Duplicate key of list dhcp:shared-network
</sch:report>
</sch:rule>
<sch:rule context="/nc:rpc-reply/nc:data/dhcp:dhcp/
dhcp:shared-networks/dhcp:shared-network/
dhcp:subnet">
<sch:extends rule="std-id2247270"/>
</sch:rule>
<sch:rule context="/nc:rpc-reply/nc:data/dhcp:dhcp/
dhcp:status/dhcp:leases">
<sch:report test="preceding-sibling::dhcp:leases
[dhcp:address=current()/dhcp:address]">
Duplicate key of list dhcp:leases
</sch:report>
</sch:rule>
</sch:pattern>
<sch:pattern id="ref-integrity"/>
</sch:schema>
]]></artwork>
</figure>
</section>
<section title="DSRL Schema for <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 anchor="change-log" title="Change Log">
<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 RPCs) 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="acknowledgements"/> (Acknowledgements).</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 <xref target="features-deviations"/> 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 content.</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-24 03:11:14 |