Difference: DSDLTechDetails (1 vs. 6)

Revision 62011-02-16 - LadaLhotka

Line: 1 to 1
 
META TOPICPARENT name="DSDLMappingTutorial"

Revision 52011-02-16 - LadaLhotka

Line: 1 to 1
 
META TOPICPARENT name="DSDLMappingTutorial"

Revision 42010-06-02 - LadaLhotka

Line: 1 to 1
 
META TOPICPARENT name="DSDLMappingTutorial"
Changed:
<
<

Technical Details of DSDL Mapping and Validation

Revision 32010-06-01 - LadaLhotka

Line: 1 to 1
 
META TOPICPARENT name="DSDLMappingTutorial"
Added:
>
>
<-- pyang commiters, please edit the TWiki source
     in the pyang repository at Google Code, directory doc/
-->
 

Technical Details of DSDL Mapping and Validation

This page is a supplement to DSDLMappingTutorial and provides

Revision 22010-05-27 - LadaLhotka

Line: 1 to 1
 
META TOPICPARENT name="DSDLMappingTutorial"

Technical Details of DSDL Mapping and Validation

This page is a supplement to DSDLMappingTutorial and provides technical details about the mapping of YANG data models to DSDL schemas and validation of instance documents. This information should

Changed:
<
<
help in implementing the DSDL mapping and validation of instance documents on non-Unix operating system and/or with alternative XML tools.
>
>
help in implementing the DSDL mapping and validation on non-Unix operating systems and/or with alternative XML tools.
  Essentially, we take the same data model as in DSDLMappingTutorial, manually execute every step performed by the yang2dsdl script and
Line: 16 to 15
 
  1. Using the DSDL plugin of pyang, we generate an interim object called hybrid schema.
Changed:
<
<
  1. From the hybrid schema we the generate the DSDL schemas
>
>
  1. From the hybrid schema we generate the DSDL schemas
  (RELAX NG, Schematron and DSRL) using three XSLT stylesheets.
  1. The RELAX NG schema can then be used with any validator to check grammatical constraints and datatypes. We demonstrate this with

Revision 12010-05-27 - LadaLhotka

Line: 1 to 1
Added:
>
>
META TOPICPARENT name="DSDLMappingTutorial"

Technical Details of DSDL Mapping and Validation

This page is a supplement to DSDLMappingTutorial and provides technical details about the mapping of YANG data models to DSDL schemas and validation of instance documents. This information should help in implementing the DSDL mapping and validation of instance documents on non-Unix operating system and/or with alternative XML tools.

Essentially, we take the same data model as in DSDLMappingTutorial, manually execute every step performed by the yang2dsdl script and explain the results. The process may look quite daunting at first, so let's outline the main steps:

  1. Using the DSDL plugin of pyang, we generate an interim object called hybrid schema.
  2. From the hybrid schema we the generate the DSDL schemas (RELAX NG, Schematron and DSRL) using three XSLT stylesheets.
  3. The RELAX NG schema can then be used with any validator to check grammatical constraints and datatypes. We demonstrate this with xmllint.
  4. The DSRL schema is transformed to an XSLT stylesheet, which is then used for adding leaf nodes with default values to the instance document.
  5. Finally, we perform Schematron validation: The Schematron schema is transformed to an XSLT stylesheet which is then applied to the instance document.

All in all, for a given data model and a given target document type, a complete validation of an instance document against the data model eventually involves one RELAX NG schema and two XSLT stylesheets – one for DSRL and another for Schematron. Therefore, such a validation can be performed using ubiquitous XML tools.

Generating the Hybrid Schema

The first step in the translation of a YANG data model to DSDL schemas utilizes the DSDL plugin of pyang:

pyang -f dsdl -o aug-acme-system.dsdl acme-system.yang extra-interface.yang

The result, stored in the file aug-acme-system.dsdl, is the so-called hybrid schema. It is essentially a RELAX NG schema for the entire data model with additional annotations that specify semantic constraints and other information.

RELAX NG, Schematron and DSRL Schemas

The final DSDL schemas are obtained from the hybrid schema via XSL transformations. The necessary XSLT stylesheets are contained in the pyang package. Their location is installation dependent, by default it is the directory /usr/local/share/yang/xslt. Assuming that the installation directory is contained in the environment variable PYANG_XSLT_DIR, we can obtain the three schemas (plus the auxiliary RELAX NG schema with global definitions) as follows:

RELAX NG
$ xsltproc --output aug-acme-system-dstore.rng \
  --stringparam basename aug-acme-system \
  --stringparam target dstore \
  $PYANG_XSLT_DIR/gen-relaxng.xsl aug-acme-system.dsdl

RELAX NG with global definitions
xsltproc --output aug-acme-system-gdefs.rng \
  --stringparam gdefs-only 1 \
  $PYANG_XSLT_DIR/gen-relaxng.xsl aug-acme-system.dsdl

Schematron
xsltproc --output aug-acme-system-dstore.sch \
  --stringparam target dstore \
  $PYANG_XSLT_DIR/gen-schematron.xsl aug-acme-system.dsdl

DSRL
xsltproc --output aug-acme-system-dstore.dsrl \
  --stringparam target dstore \
  $PYANG_XSLT_DIR/gen-dsrl.xsl aug-acme-system.dsdl

Instead of xsltproc, any other XSLT processor may be used provided it supports XSLT 1.0 and EXSLT.

Validating Grammatical Constraints and Datatypes

Having the RELAX NG schema, validation of the instance document is now straightforward:

$ xmllint --noout --relaxng aug-acme-system-dstore.rng aug-acme-system-dstore.xml

As we saw in DSDLMappingTutorial, the validation error messages provided by xmllint are rather cryptic, so it might be a good idea to replace xmllint with another RELAX NG validator, for example Jing.

Adding Leaf Nodes with Default Values

Before we can check the instance datastore for semantic validity, all missing leaf nodes have to be added with their default values where possible, if such a default value is defined in the data model. Our example has one such leaf node: eid:enabled. Note that without adding this leaf with the default value of false, the instance document doesn't satisfy the 'must' constraint in the extra-interface-data module.

It is the DSRL schema that defines rules for adding default values along with their ancestor containers. The task is carried out in two steps. First, the DSRL schema is transformed to an XSLT stylesheet:

$ xsltproc --output aug-acme-system-dstore-dsrl.xsl \
  $PYANG_XSLT_DIR/dsrl2xslt.xsl aug-acme-system-dstore.dsrl

The generated stylesheet, aug-acme-system-dstore-dsrl.xsl, can now be applied to the instance document (actually, to any grammatically valid document of the same type), which leads to a new instance document, aug-acme-system-dstore-wdef.xml:

$ xsltproc --output aug-acme-system-dstore-wdef.xml \
  aug-acme-system-dstore-dsrl.xsl aug-acme-system-dstore.xml
$ xmllint --format aug-acme-system-dstore-wdef.xml 
<?xml version="1.0" encoding="utf-8"?>
<system xmlns="http://acme.example.com/system" xmlns:eid="http://foo.example.com/extra-if-data">
  <host-name>katz</host-name>
  <domain-search>acme.example.com foo.example.com</domain-search>
  <interface>
    <name>eth0</name>
    <type>Ethernet</type>
    <mtu>1500</mtu>
    <eid:enabled>true</eid:enabled>
    <eid:ipv4-address>192.0.2.1</eid:ipv4-address>
    <eid:subnet-mask-length>24</eid:subnet-mask-length>
  </interface>
  <interface>
    <name>eth1</name>
    <mtu>1500</mtu>
    <type>Ethernet</type>
    <eid:enabled>false</eid:enabled>
  </interface>
</system>

We can see that the element <eid:enabled> with the default value of false has indeed been added.

Validating Semantic Constraints

The last step is the Schematron validation. We use the skeleton implementation of Schematron by Rick Jelliffe for this purpose. Thanks to its license, this implementation could be included in the pyang distribution.

The workflow is similar to the DSRL case above. The Schematron schema is first transformed (in two steps, but this is only a technical detail) into an XSLT stylesheet, aug-acme-system-dstore-sch.xsl:

$ xsltproc $PYANG_XSLT_DIR/iso_abstract_expand.xsl aug-acme-system-dstore.sch | \
  xsltproc --output aug-acme-system-dstore-sch.xsl \
  $PYANG_XSLT_DIR/iso_svrl_for_xslt1.xsl -

The stylesheet is applied to the instance document with added defaults in this way:

$ xsltproc --output aug-acme-system-dstore.svrl \
  aug-acme-system-dstore-sch.xsl aug-acme-system-dstore-wdef.xml
The output file, aug-acme-system-dstore.svrl, introduces yet another XML format – Schematron Validation Report Language (SVRL). In order to get a human-readable report, the yang2dsdl script utilizes a simple XSLT stylesheet to extract error messages from SVRL (there are none as the document is valid in our case):
$ xsltproc $PYANG_XSLT_DIR/svrl2text.xsl aug-acme-system-dstore.svrl
No errors found.

Note, however, that SVRL reports in general contain more detailed diagnostic information that can help precisely localize each error.

META FILEATTACHMENT attachment="aug-acme-system.dsdl" attr="h" comment="hybrid schema" date="1274963944" name="aug-acme-system.dsdl" path="aug-acme-system.dsdl" size="4309" stream="aug-acme-system.dsdl" user="Main.LadaLhotka" version="1"
META FILEATTACHMENT attachment="aug-acme-system-dstore-dsrl.xsl" attr="h" comment="XSLT generated from DSRL" date="1274963988" name="aug-acme-system-dstore-dsrl.xsl" path="aug-acme-system-dstore-dsrl.xsl" size="722" stream="aug-acme-system-dstore-dsrl.xsl" user="Main.LadaLhotka" version="1"
META FILEATTACHMENT attachment="aug-acme-system-dstore-sch.xsl" attr="h" comment="XSLT generated from Schematron" date="1274964012" name="aug-acme-system-dstore-sch.xsl" path="aug-acme-system-dstore-sch.xsl" size="11217" stream="aug-acme-system-dstore-sch.xsl" user="Main.LadaLhotka" version="1"
META FILEATTACHMENT attachment="aug-acme-system-dstore-wdef.xml" attr="h" comment="Instance datastore with defaults" date="1274964044" name="aug-acme-system-dstore-wdef.xml" path="aug-acme-system-dstore-wdef.xml" size="617" stream="aug-acme-system-dstore-wdef.xml" user="Main.LadaLhotka" version="1"
META FILEATTACHMENT attachment="aug-acme-system-dstore.svrl" attr="h" comment="SVRL report" date="1274964074" name="aug-acme-system-dstore.svrl" path="aug-acme-system-dstore.svrl" size="1132" stream="aug-acme-system-dstore.svrl" user="Main.LadaLhotka" version="1"
 
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback