6. Overview of the Mapping
This section gives an overview of the YANG-to-DSDL mapping, its
inputs and outputs. Figure 1 presents an overall structure of the
mapping:
+----------------+
| YANG module(s) |
+----------------+
|
|T
|
+------------------------------------+
| hybrid schema |
+------------------------------------+
/ | | \
/ | | \
Tg/ Tr| |Tn \
/ | | \
+---------+ +-----+ +-------+ +------+
|get reply| | rpc | | notif | | .... |
+---------+ +-----+ +-------+ +------+
Figure 1: Structure of the mapping
The mapping procedure is divided into two steps:
1. Transformation T in the first step maps one or more YANG modules
to the hybrid schema (see Section 8.1). Constraints that cannot
be expressed directly in RELAX NG (list key definitions, 'must'
statements, etc.) and various documentation texts are recorded in
the schema as foreign-namespace annotations.
2. In the second step, the hybrid schema may be transformed in
multiple ways to a coordinated set of DSDL schemas that can be
used for validating a particular data object in a specific
context. Figure 1 shows three simple possibilities as examples.
In the process, appropriate parts of the hybrid schema are
extracted and specific annotations transformed to equivalent, but
usually more complex, Schematron patterns, DSRL element maps,
etc.
An implementation of the mapping algorithm MUST accept one or more
valid YANG modules as its input. It is important to be able to
process multiple YANG modules together since multiple modules may be
negotiated for a NETCONF session and the contents of the
configuration datastore is then obtained as the union of data trees
specified by the individual modules, which may also lead to multiple
root nodes of the datastore hierarchy. In addition, the input
modules may be further coupled by the 'augment' statement in which
one module augments the data tree of another module.
It is also assumed that the algorithm has access, perhaps on demand,
to all YANG modules that the input modules import (directly or
transitively).
Other information contained in input YANG modules, such as semantic
constraints and default values, is recorded in the hybrid schema as
annotations -- XML attributes or elements qualified with the
namespace URI "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1".
Metadata describing the YANG modules are mapped to Dublin Core
annotations elements (Section 5.1). Finally, documentation strings
are mapped to <a:documentation> elements belonging to the DTD
compatibility vocabulary (Section 5.2).
The output of the second step is a coordinated set of three DSDL
schemas corresponding to a specific data object and context:
o RELAX NG schema describing the grammatical and data type
constraints;
o Schematron schema expressing other constraints such as uniqueness
of list keys or user-specified semantic rules;
o DSRL schema containing the specification of default contents.
7. NETCONF Content Validation
This section describes how the schemas generated by the YANG-to-DSDL
mapping are supposed to be applied for validating XML instance
documents such as the contents of a datastore or various NETCONF
messages.
The validation proceeds in the following steps, which are also
illustrated in Figure 2:
1. The XML instance document is checked for grammatical and data
type validity using the RELAX NG schema.
2. Default values for leaf nodes have to be applied and their
ancestor containers added where necessary. It is important to
add the implicit nodes before the next validation step because
YANG specification [RFC6020] requires that the data tree against
which XPath expressions are evaluated already has all defaults
filled-in. Note that this step modifies the information set of
the validated XML document.
3. The semantic constraints are checked using the Schematron schema.
+----------+ +----------+
| | | XML |
| XML | | document |
| document |-----------o----------->| with |
| | ^ | defaults |
| | | | |
+----------+ | +----------+
^ | filling in ^
| grammar, | defaults | semantic
| data types | | constraints
| | |
+----------+ +--------+ +------------+
| RELAX NG | | DSRL | | Schematron |
| schema | | schema | | schema |
+----------+ +--------+ +------------+
Figure 2: Outline of the validation procedure8. Design Considerations
YANG data models could, in principle, be mapped to the DSDL schemas
in a number of ways. The mapping procedure described in this
document uses several specific design decisions that are discussed in
the following subsections.
8.1. Hybrid Schema
As was explained in Section 6, the first step of the mapping produces
an intermediate document -- the hybrid schema, which specifies all
constraints for the entire data model using the RELAX NG syntax and
additional annotations. In cannot be directly used for validation --
as a matter of fact, it is not even a valid RELAX NG schema because
it contains multiple schemas demarcated by special annotation
elements.
Every input YANG module corresponds to exactly one embedded grammar
in the hybrid schema. This separation of input YANG modules allows
each embedded grammar to include named pattern definitions into its
own namespace, which is important for mapping YANG groupings (see
Section 9.2 for additional details).
In addition to grammatical and data type constraints, YANG modules
provide other important information that cannot be expressed in a
RELAX NG schema: semantic constraints, default values, metadata,
documentation, and so on. Such information items are represented in
the hybrid schema as XML attributes and elements belonging to the
namespace with the following URI:
"urn:ietf:params:xml:ns:netmod:dsdl-annotations:1". A complete list
of these annotations is given in Section 5.3, detailed rules about
their use are then contained in the following sections.
YANG modules define data models not only for configuration and state
data but also for (multiple) RPC operations [RFC4741] and/or event
notifications [RFC5277]. In order to be able to capture all three
types of data models in one schema document, the hybrid schema uses
special markers that enclose sub-schemas for configuration and state
data, individual RPC operations (both input and output part) and
individual notifications.
The markers are the following XML elements in the namespace of
NETMOD-specific annotations (URI
urn:ietf:params:xml:ns:netmod:dsdl-annotations:1):
+-------------------+---------------------------------------+
| Element name | Role |
+-------------------+---------------------------------------+
| nma:data | encloses configuration and state data |
| | |
| nma:rpcs | encloses all RPC operations |
| | |
| nma:rpc | encloses an individual RPC operation |
| | |
| nma:input | encloses an RPC request |
| | |
| nma:output | encloses an RPC reply |
| | |
| nma:notifications | encloses all notifications |
| | |
| nma:notification | encloses an individual notification |
+-------------------+---------------------------------------+
Table 3: Marker elements in the hybrid schema
For example, consider a data model formed by two YANG modules
"example-a" and "example-b" that define nodes in the namespaces
"http://example.com/ns/example-a" and
"http://example.com/ns/example-b". Module "example-a" defines
configuration/state data, RPC methods and notifications, whereas
"example-b" defines only configuration/state data. The hybrid schema
can then be schematically represented as follows:
...global named pattern definitions...
</grammar>
A complete hybrid schema for the data model of a DHCP server is given
in Appendix C.2.
8.2. Modularity
Both YANG and RELAX NG offer means for modularity, i.e., for
splitting the contents of a full schema into separate modules and
combining or reusing them in various ways. However, the approaches
taken by YANG and RELAX NG differ. Modularity in RELAX NG is
suitable for ad hoc combinations of a small number of schemas whereas
YANG assumes a large set of modules similar to SNMP MIB modules. The
following differences are important:
o 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.
o The names of imported YANG groupings and typedefs are qualified
with the namespace of the imported module. On the other hand, the
names of data nodes contained inside the imported groupings, when
used within the importing module, become part of the importing
module's namespace. In RELAX NG, the names of patterns are
unqualified and so named patterns defined in both the importing
and imported module share the same flat namespace. The contents
of RELAX NG named patterns may either keep the namespace of the
schema where they are defined or inherit the namespace of the
importing module, analogically to YANG. However, in order to
achieve the latter behavior, the definitions of named patterns
must be included from an external schema, which has to be prepared
in a special way (see [Vli04], Chapter 11).
In order to map, as much as possible, the modularity of YANG to RELAX
NG, a validating RELAX NG schema (the result of the second mapping
step) has to be split into two files, one of them containing all
global definitions that are mapped from top-level YANG groupings
appearing in all input YANG module. This RELAX NG schema MUST NOT
define any namespace via the @ns attribute.
The other RELAX NG schema file then defines actual data trees mapped
from input YANG modules, each of them enclosed in an own embedded
grammar. Those embedded grammars, in which at least one of the
global definitions is used, MUST include the first schema with
definitions and also MUST define the local namespace using the @ns
attribute. This way, the global definitions can be used inside
different embedded grammar, each time accepting a different local
namespace.
Named pattern definitions that are mapped from non-top-level YANG
groupings MUST be placed inside the embedded grammar corresponding to
the YANG module where the grouping is defined.
In the hybrid schema, we need to distinguish the global and non-
global named pattern definitions while still keeping the hybrid
schema in one file. This is accomplished in the following way:
o Every global definition MUST be placed as a child of the outer
<rng:grammar> element (the document root of the hybrid schema).
o Every non-global definitions MUST be placed as a child of the
corresponding embedded <rng:grammar> element.
YANG also allows for splitting a module into a number of submodules.
However, as submodules have no impact on the scope of identifiers and
namespaces, the modularity based on submodules is not mapped in any
way. The contents of submodules is therefore handled as if the
submodule text appeared directly in the main module.
8.3. Granularity
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.
YANG supports both styles in principle, too, but in most cases the
modules are organized in a way closer to the "Russian Doll" style,
which provides a better insight into the structure of the
configuration data. Groupings are usually defined only for contents
that are prepared for reuse in multiple places via the 'uses'
statement. In contrast, RELAX NG schemas tend to be much flatter,
because finer granularity is also needed in RELAX NG for
extensibility of the schemas -- it is only possible to replace or
modify schema fragments that are factored out as named patterns. For
YANG, this is not an issue since its 'augment' and 'refine'
statements can delve, by using path expressions, into arbitrary
depths of existing structures.
In general, it is not feasible to map YANG's powerful extension
mechanisms to those available in RELAX NG. For this reason, the
mapping essentially keeps the granularity of the original YANG data
model: YANG groupings and definitions of derived types usually have
direct counterparts in definitions of named patterns in the resulting
RELAX NG schema.
8.4. Handling of XML Namespaces
Most modern XML schema languages, including RELAX NG, Schematron, and
DSRL, support schemas for so-called compound XML documents that
contain elements from multiple namespaces. This is useful for our
purpose since the YANG-to-DSDL mapping allows for multiple input YANG
modules, which naturally leads to compound document schemas.
RELAX NG offers two alternatives for defining the target namespaces
in the schema:
1. First possibility is the traditional XML way via the @xmlns:xxx
attribute.
2. One of the target namespace URIs may be declared using the @ns
attribute.
In both the hybrid schema and validation RELAX NG schemas generated
in the second step, the namespaces MUST be declared as follows:
1. The root <rng:grammar> MUST have @xmlns:xxx attributes declaring
prefixes of all namespaces that are used in the data model. The
prefixes SHOULD be identical to those defined in the 'prefix'
statements. An implementation of the mapping MUST resolve all
collisions in the prefixes defined by different input modules, if
there are any.
2. Each embedded <rng:grammar> element MUST declare the namespace of
the corresponding module using the @ns attribute. This way, the
names of nodes defined by global named patterns are able to adopt
the local namespace of each embedded grammar, as explained in
Section 8.2.
This setup is illustrated by the example at the end of Section 8.1.
DSRL schemas may declare any number of target namespaces via the
standard XML attributes xmlns:xxx.
In contrast, Schematron requires all used namespaces to be defined in
the <sch:ns> subelements of the document element <sch:schema>.
9. Mapping YANG Data Models to the Hybrid Schema
This section explains the main principles governing the first step of
the mapping. Its result is the hybrid schema that is described in
Section 8.1.
A detailed specification of the mapping of individual YANG statements
is contained in Section 10.
9.1. Occurrence Rules for Data Nodes
In DSDL schema languages, occurrence constraints for a node are
always localized together with that node. In a RELAX NG schema, for
example, the <rng:optional> pattern appears as the parent element of
the pattern defining a leaf or non-leaf element. Similarly, DSRL
specifies default contents separately for every single node, be it a
leaf or non-leaf element.
For leaf nodes in YANG modules, the occurrence constraints are also
easily inferred from the substatements of 'leaf'. On the other hand,
for a YANG container, it is often necessary to examine its entire
subtree in order to determine the container's occurrence constraints.
Therefore, one of the goals of the first mapping step is to infer the
occurrence constraints for all data nodes and mark, accordingly, the
corresponding <rng:element> patterns in the hybrid schema so that any
transformation procedure in the second mapping step can simply use
this information and need not examine the subtree again.
First, it has to be decided whether a given data node must always be
present in a valid configuration. If so, such a node is called
mandatory, otherwise it is called optional. This constraint is
closely related to the notion of mandatory nodes in Section 3.1 in
[RFC6020]. The only difference is that this document also considers
list keys to be mandatory.
The other occurrence constraint has to do with the semantics of the
'default' statement and the possibility of removing empty non-
presence containers. As a result, the information set of a valid
configuration may be modified by adding or removing certain leaf or
container elements without changing the meaning of the configuration.
In this document, such elements are called implicit. In the hybrid
schema, they can be identified as RELAX NG patterns having either the
@nma:default or the @nma:implicit attribute.
Note that both occurrence constraints apply to containers at the top
level of the data tree, and then also to other containers under the
additional condition that their parent node exists in the instance
document. For example, consider the following YANG fragment:
container outer {
presence 'Presence of "outer" means something.';
container c1 {
leaf foo {
type uint8;
default 1;
}
}
container c2 {
leaf-list bar {
type uint8;
min-elements 0;
}
}
container c3 {
leaf baz {
type uint8;
mandatory true;
}
}
}
Here, container "outer" has the 'presence' substatement, which means
that it is optional and not implicit. If "outer" is not present in a
configuration, its child containers are not present as well.
However, if "outer" does exist, it makes sense to ask which of its
child containers are optional and which are implicit. In this case,
"c1" is optional and implicit, "c2" is optional but not implicit, and
"c3" is mandatory (and therefore not implicit).
The following subsections give precise rules for determining whether
a container is optional or mandatory and whether it is implicit. In
order to simplify the recursive definition of these occurrence
characteristics, it is useful to define them also for other types of
YANG schema nodes, i.e., leaf, list, leaf-list, anyxml, and choice.
9.1.1. Optional and Mandatory Nodes
The decision whether a given node is mandatory or optional is
governed by the following rules:
o 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.
o In addition, a leaf node is mandatory if it is declared as a list
key.
o A list or leaf-list node is mandatory if it contains the 'min-
elements' substatement with an argument value greater than zero.
o A container node is mandatory if its definition does not contain
the 'presence' substatement and at least one of its child nodes is
mandatory.
A node that is not mandatory is said to be optional.
In RELAX NG, definitions of nodes that are optional must be
explicitly wrapped in the <rng:optional> element. The mapping MUST
use the above rules to determine whether a YANG node is optional, and
if so, insert the <rng:optional> element in the hybrid schema.
However, alternatives in <rng:choice> MUST NOT be defined as optional
in the hybrid schema. If a choice in YANG is not mandatory, <rng:
optional> MUST be used to wrap the entire <rng:choice> pattern.
9.1.2. Implicit Nodes
The following rules are used to determine whether a given data node
is implicit:
o List, leaf-list, and anyxml nodes are never implicit.
o A leaf node is implicit if and only if it has a default value,
defined either directly or via its data type.
o A container node is implicit if and only if it does not have the
'presence' substatement, none of its children are mandatory, and
at least one child is implicit.
In the hybrid schema, all implicit containers, as well as leafs that
obtain their default value from a typedef and don't have the @nma:
default attribute, MUST be marked with @nma:implicit attribute having
the value of "true".
Note that Section 7.9.3 in [RFC6020] specifies other rules that must
be taken into account when deciding whether or not a given container
or leaf appearing inside a case of a choice is ultimately implicit.
Specifically, a leaf or container under a case can be implicit only
if the case appears in the argument of the choice's 'default'
statement. However, this is not sufficient by itself but also
depends on the particular instance XML document, namely on the
presence or absence of nodes from other (non-default) cases. The
details are explained in Section 11.3.
9.2. Mapping YANG Groupings and Typedefs
YANG groupings and typedefs are generally mapped to RELAX NG named
patterns. There are, however, several caveats that the mapping has
to take into account.
First of all, YANG typedefs and groupings may appear at all levels of
the module hierarchy and are subject to lexical scoping, see Section
5.5 in [RFC6020]. Second, top-level symbols from external modules
may be imported as qualified names represented using the external
module namespace prefix and the name of the symbol. In contrast,
named patterns in RELAX NG (both local and imported via the <rng:
include> pattern) share the same namespace and within a grammar they
are always global -- their definitions may only appear at the top
level as children of the <rng:grammar> element. Consequently,
whenever YANG groupings and typedefs are mapped to RELAX NG named
pattern definitions, their names MUST be disambiguated in order to
avoid naming conflicts. The mapping uses the following procedure for
mangling the names of groupings and type definitions:
o 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 ("__").
o Names of other groupings and typedefs, i.e., those that do not
appear at the top level of a YANG module, are prefixed with the
module name, double underscore, and then the names of all ancestor
data nodes separated by double underscore.
o Finally, since the names of groupings and typedefs in YANG have
different namespaces, an additional underscore character is added
to the beginning of the mangled names of all groupings.
An additional complication is caused by the YANG rules for subelement
ordering (see, e.g., Section 7.5.7 in [RFC6020]): in RPC input and
output parameters, subelements must follow the order specified in the
data model; otherwise, the order is arbitrary. Consequently, if a
grouping is used both in RPC input/output parameters and elsewhere,
it MUST be mapped to two different named pattern definitions -- one
with fixed order and the other with arbitrary order. To distinguish
them, the "__rpc" suffix MUST be appended to the version with fixed
order.
EXAMPLE. Consider the following YANG module that imports the
standard module "ietf-inet-types" [RFC6021]:
module example1 {
namespace "http://example.com/ns/example1";
prefix ex1;
typedef vowels {
type string {
pattern "[aeiouy]*";
}
}
grouping "grp1" {
leaf "void" {
type "empty";
}
}
container "cont" {
leaf foo {
type vowels;
}
uses "grp1";
}
}
The hybrid schema generated by the first mapping step will then
contain the following two (global) named pattern definitions:
<rng:define name="example1__vowels">
<rng:data type="string">
<rng:param name="pattern">[aeiouy]*</rng:param>
</rng:data>
</rng:define>
<rng:define name="_example1__grp1">
<rng:optional>
<rng:element name="void">
<rng:empty/>
</rng:element>
</rng:optional>
</rng:define>
9.2.1. YANG Refinements and Augments
YANG groupings represent a similar concept as named pattern
definitions in RELAX NG, and both languages also offer mechanisms for
their subsequent modification. However, in RELAX NG, the definitions
themselves are modified, whereas YANG provides two substatements of
'uses', which modify expansions of groupings:
o The 'refine' statement allows for changing parameters of a schema
node inside the grouping referenced by the parent 'uses'
statement;
o The 'augment' statement can be used for adding new schema nodes to
the grouping contents.
Both 'refine' and 'augment' statements are quite powerful in that
they can address, using XPath-like expressions as their arguments,
schema nodes that are arbitrarily deep inside the grouping contents.
In contrast, modifications of named pattern definitions in RELAX NG
are applied exclusively at the topmost level of the named pattern
contents. In order to achieve a modifiability of named patterns
comparable to YANG, a RELAX NG schema would have to be extremely flat
(cf. Section 8.3) and very difficult to read.
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 that has 'refine'
and/or 'augment' substatements is replaced by the contents of the
corresponding grouping, the changes specified in the 'refine' and
'augment' statements are applied, and the resulting YANG schema
fragment is mapped as if the 'uses'/'grouping' indirection wasn't
there.
If there are further 'uses' statements inside the grouping contents,
they may require expansion, too: it is necessary if the contained
'uses'/'grouping' pair lies on the "modification path" specified in
the argument of a 'refine' or 'augment' statement.
and the configuration data part of the hybrid schema is a single
named pattern reference:
<nma:data>
<rng:ref name="_example2__leaves"/>
</nma:data>
Now assume that the "uses leaves" statement contains a 'refine'
substatement, for example:
uses leaves {
refine "hoja" {
default "alamo";
}
}
The resulting hybrid schema now contains just one named pattern
definition - "_example2__fr". The other two groupings "leaves" and
"es" have to be expanded because they both lie on the "modification
path", i.e., contain the leaf "hoja" that is being refined. The
configuration data part of the hybrid schema now looks like this:
<nma:data>
<rng:interleave>
<rng:ref name="_example2__fr"/>
<rng:optional>
<rng:element name="ex2:hoja" nma:default="alamo">
<rng:data type="string"/>
</rng:element>
</rng:optional>
</rng:interleave>
</nma:data>
9.2.2. Type Derivation Chains
RELAX NG has no equivalent of the type derivation mechanism in YANG
that allows one to restrict a built-in type (perhaps in multiple
steps) by adding new constraints. Whenever a derived YANG type is
used without restrictions -- as a substatement of either 'leaf' or
another 'typedef' -- then the 'type' statement is mapped simply to a
named pattern reference <rng:ref>, and the type definition is mapped
to a RELAX NG named pattern definition <rng:define>. However, if any
restrictions are specified as substatements of the 'type' statement,
the type definition MUST be expanded at that point so that only the
ancestor built-in type appears in the hybrid schema, restricted with
facets that correspond to the combination of all restrictions found
along the type derivation chain and also in the 'type' statement.
EXAMPLE. Consider this YANG module:
module example3 {
namespace "http://example.com/ns/example3";
prefix ex3;
typedef dozen {
type uint8 {
range 1..12;
}
}
leaf month {
type dozen;
}
}
The 'type' statement in "leaf month" has no restrictions and is
therefore mapped simply to the reference <rng:ref
name="example3__dozen"/> and the corresponding named pattern is
defined as follows:
<rng:define name="example3__dozen">
<rng:data type="unsignedByte">
<rng:param name="minInclusive">1</rng:param>
<rng:param name="maxInclusive">12</rng:param>
</rng:data>
</rng:define>
Assume now that the definition of leaf "month" is changed to:
leaf month {
type dozen {
range 7..max;
}
}
The output RELAX NG schema then will not contain any named pattern
definition and the leaf "month" will be mapped directly to:
<rng:element name="ex3:month">
<rng:data type="unsignedByte">
<rng:param name="minInclusive">7</rng:param>
<rng:param name="maxInclusive">12</rng:param>
</rng:data>
</rng:element>
The mapping of type derivation chains 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.
However, if that type definition has to be expanded due to
restrictions, the @nma:default attribute arising from the expanded
type or ancestor types in the type derivation chain MUST be attached
to the pattern where the expansion occurs. If there are multiple
'default' statements in consecutive steps of the type derivation,
only the 'default' statement that is closest to the expanded type is
used.
EXAMPLE. Consider this variation of the last example:
module example3bis {
namespace "http://example.com/ns/example3bis";
prefix ex3bis;
typedef dozen {
type uint8 {
range 1..12;
}
default 7;
}
leaf month {
type dozen;
}
}
The 'typedef' statement in this module is mapped to the following
named pattern definition:
<rng:define name="example3bis__dozen" @nma:default="7">
<rng:data type="unsignedByte">
<rng:param name="minInclusive">1</rng:param>
<rng:param name="maxInclusive">12</rng:param>
</rng:data>
</rng:define>
If the "dozen" type 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:
<rng:element name="ex3bis:month" @nma:default="7">
<rng:data type="unsignedByte">
<rng:param name="minInclusive">7</rng:param>
<rng:param name="maxInclusive">12</rng:param>
</rng:data>
</rng:element>
However, if the definition of the leaf "month" itself contained the
'default' substatement, the default specified for the "dozen" type
would be ignored.
9.3. Translation of XPath Expressions
YANG uses full XPath 1.0 syntax [XPath] for the arguments of 'must',
'when', and 'path' statements. As the names of data nodes defined in
a YANG module always belong to the namespace of that YANG module,
YANG adopted a simplification similar to the concept of default
namespace in XPath 2.0: node names in XPath expressions needn't carry
a namespace prefix inside the module where they are defined and the
local module's namespace is assumed.
Consequently, all XPath expressions MUST be translated into a fully
conformant XPath 1.0 expression: every unprefixed node name MUST be
prepended with the local module's namespace prefix as declared by the
'prefix' statement.
XPath expressions appearing inside top-level groupings require
special attention because all unprefixed node names contained in them
must adopt the namespace of each module where the grouping is used
(cf. Section 8.2). In order to achieve this, the local prefix MUST
be represented using the variable "$pref" in the hybrid schema. A
Schematron schema which encounters such an XPath expression then
supplies an appropriate value for this variable via a parameter to an
abstract pattern to which the YANG grouping is mapped (see
Section 11.2).
For example, XPath expression "/dhcp/max-lease-time" appearing in a
YANG module with the "dhcp" prefix will be translated to:
o "$pref:dhcp/$pref:max-lease-time", if the expression is inside a
top-level grouping;
o "dhcp:dhcp/dhcp:max-lease-time", otherwise.
YANG also uses other XPath-like expressions, namely key identifiers
and "descendant schema node identifiers" (see the ABNF production for
and "descendant-schema-nodeid" in Section 12 of [RFC6020]). These
expressions MUST be translated by adding local module prefixes as
well.
9.4. YANG Language Extensions
YANG allows for extending its own language in-line by adding new
statements with keywords from special namespaces. Such extensions
first have to be declared using the 'extension' statement, and then
they can be used as the standard YANG statements, from which they are
distinguished by a namespace prefix qualifying the extension keyword.
RELAX NG has a similar extension mechanism -- XML elements and
attributes with names from foreign namespaces may be inserted at
almost any place of a RELAX NG schema.
YANG language extensions may or may not have a meaning in the context
of DSDL schemas. Therefore, an implementation MAY ignore any or all
of the extensions. However, an extension that is not ignored MUST be
mapped to XML element(s) and/or attribute(s) that exactly match the
YIN form of the extension, see Section 11.1 in [RFC6020].
EXAMPLE. Consider the following extension defined by the "acme"
module:
extension documentation-flag {
argument number;
}
This extension can then be used in the same or another module, for
instance like this:
leaf folio {
acme:documentation-flag 42;
type string;
}
If this extension is honored by the mapping, it will be mapped to:
<rng:element name="acme:folio">
<acme:documentation-flag number="42"/>
<rng:data type="string"/>
</rng:element>
Note that the 'extension' statement itself is not mapped in any way.
