RFC 6110
Mapping YANG to Document Schema Definition Languages and Validating NETCONF Content
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:
<grammar xmlns="http://relaxng.org/ns/structure/1.0"
xmlns:nma="urn:ietf:params:xml:ns:netmod:dsdl-annotations:1"
xmlns:exa="http://example.com/ns/example-a"
xmlns:exb="http://example.com/ns/example-b"
datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
<start>
<grammar nma:module="example-a"
ns="http://example.com/ns/example-a">
<start>
<nma:data>
...configuration and state data defined in "example-a"...
</nma:data>
<nma:rpcs>
<nma:rpc>
<nma:input>
<element name="exa:myrpc">
...
</element>
</nma:input>
<nma:output>
...
</nma:output>
</nma:rpc>
...
</nma:rpcs>
<nma:notifications>
<nma:notification>
<element name="exa:mynotif">
...
</element>
</nma:notification>
...
</nma:notifications>
</start>
...local named pattern definitions of example-a...
</grammar>
<grammar nma:module="example-b"
ns="http://example.com/ns/example-a">
<start>
<nma:data>
...configuration and state data defined in "example-b"...
</nma:data>
<nma:rpcs/>
<nma:notifications/>
</start>
...local named pattern definitions of example-b...
</grammar>
</start>
...global named pattern definitions...
</grammar>
A complete hybrid schema for the data model of a DHCP server is given
in Appendix C.2.
8.2. Modularity
Both YANG and RELAX NG 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.
EXAMPLE. Consider the following YANG module:
module example2 {
namespace "http://example.com/ns/example2";
prefix ex2;
grouping leaves {
uses fr;
uses es;
}
grouping fr {
leaf feuille {
type string;
}
}
grouping es {
leaf hoja {
type string;
}
}
uses leaves;
}
The resulting hybrid schema contains three global named pattern
definitions corresponding to the three groupings, namely:
<rng:define name="_example2__leaves">
<rng:interleave>
<rng:ref name="_example2__fr"/>
<rng:ref name="_example2__es"/>
</rng:interleave>
</rng:define>
<rng:define name="_example2__fr">
<rng:optional>
<rng:element name="feuille">
<rng:data type="string"/>
</rng:element>
</rng:optional>
</rng:define>
<rng:define name="_example2__es">
<rng:optional>
<rng:element name="hoja">
<rng:data type="string"/>
</rng:element>
</rng:optional>
</rng:define>
and the configuration data part of the hybrid schema is a single
named pattern reference:
<nma:data>
<rng:ref name="_example2__leaves"/>
</nma:data>
Now assume that the "uses leaves" statement contains a 'refine'
substatement, for example:
uses leaves {
refine "hoja" {
default "alamo";
}
}
The resulting hybrid schema now contains just one named pattern
definition - "_example2__fr". The other two groupings "leaves" and
"es" have to be expanded because they both lie on the "modification
path", i.e., 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.
(next page on part 3)
