tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Gloss.     Arch.     IMS     UICC    |    Misc.    |    search     info

RFC 6110

 
 
 

Mapping YANG to Document Schema Definition Languages and Validating NETCONF Content

Part 2 of 4, p. 16 to 36
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 16 
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:

Top      Up      ToC       Page 17 
                    +----------------+
                    | 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.

Top      Up      ToC       Page 18 
   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.

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

               Figure 2: Outline of the validation procedure

8.  Design Considerations

   YANG data models could, in principle, be mapped to the DSDL schemas
   in a number of ways.  The mapping procedure described in this
   document uses several specific design decisions 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

Top      Up      ToC       Page 20 
   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:

Top      Up      ToC       Page 21 
  <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>

Top      Up      ToC       Page 22 
    ...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

Top      Up      ToC       Page 23 
   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.

Top      Up      ToC       Page 24 
   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>.

Top      Up      ToC       Page 25 
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.

Top      Up      ToC       Page 26 
   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:

Top      Up      ToC       Page 27 
   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

Top      Up      ToC       Page 28 
   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.

Top      Up      ToC       Page 29 
   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:

Top      Up      ToC       Page 30 
   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.

Top      Up      ToC       Page 31 
   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>

Top      Up      ToC       Page 32 
   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.

Top      Up      ToC       Page 33 
   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'

Top      Up      ToC       Page 34 
   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:

Top      Up      ToC       Page 35 
   <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.

Top      Up      ToC       Page 36 
   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 RFC Part