|
META TOPICPARENT |
name="YangTools" |
|
META TOPICPARENT |
name="YangTools" |
|
META TOPICPARENT |
name="YangTools" |
|
META TOPICPARENT |
name="YangTools" |
| |
< < |
DSDL Mapping Tutorial |
|
META TOPICPARENT |
name="YangTools" |
| |
> > | <-- pyang commiters, please edit the TWiki source
in the pyang repository at Google Code, directory doc/
--> | | DSDL Mapping Tutorial
Introduction | | distribution, and then experiment with validating configuration
datastore contents. | |
< < | NOTE: The software tools presented in this tutorial produce compact
XML data with no intervening whitespace. The corresponding files that
are attached to this wiki page and referred to in the text are their
pretty-printed versions obtained by using | > > | The software tools presented in this tutorial produce
compact XML data with no intervening whitespace. The corresponding
files that are attached to this wiki page and referred to in the text
are their pretty-printed versions obtained by using | | xmllint.
The Data Model |
|
META TOPICPARENT |
name="YangTools" |
DSDL Mapping Tutorial | | Feel free to make any other modifications in the instance document and
re-run the validation to see what happens. | |
< < | Developers and technically inclined readers may found further | > > | Developers and technically inclined readers may find further | | technical details about the DSDL mapping and instance validation in
DSDLTechDetails. |
|
META TOPICPARENT |
name="YangTools" |
DSDL Mapping Tutorial | | RELAX NG,
Schematron and DSRL. The
resulting schemas may be used with off-the-shelf XML tools for | |
< < | validating NETCONF datastores and PDUs and other related purposes. | > > | validating NETCONF datastores and messages and other related purposes. | |
The mapping procedure is described in
draft-ietf-netmod-dsdl-map. | | the following module (see also
extra-interface-data.yang): | |
< < |
module extra-interface-data {
namespace "http://foo.example.com/extra-if-data";
prefix eid;
import acme-system {
prefix acme; | > > | module extra-interface-data {
namespace "http://foo.example.com/extra-if-data";
prefix eid;
import acme-system {
prefix acme;
| | } | |
< < | import ietf-inet-types {
prefix inet; | > > | import ietf-inet-types {
prefix inet; | | } | |
< < | augment "/acme:system/acme:interface" {
leaf enabled {
type boolean;
default "false";
must ".='false' or ../ipv4-address and ../subnet-mask-length" {
error-message "IP address and mask must be configured " +
"for enabled interfaces."; | > > | augment "/acme:system/acme:interface" {
leaf enabled {
type boolean;
default "false";
must ".='false' or ../ipv4-address and ../subnet-mask-length" {
error-message "IP address and mask must be configured " +
"for enabled interfaces."; | | }
} | |
< < | leaf ipv4-address {
type inet:ipv4-address; | > > | leaf ipv4-address {
type inet:ipv4-address; | | } | |
< < | leaf subnet-mask-length {
type uint8 {
range "0..32"; | > > | leaf subnet-mask-length {
type uint8 {
range "0..32"; | | }
}
}
} | |
< < | | > > | | |
Our data model now defines a compound document containing nodes in
the namespaces of both the contributing modules, acme-system and |
|
META TOPICPARENT |
name="YangTools" |
DSDL Mapping Tutorial | | NOTE: The software tools presented in this tutorial produce compact
XML data with no intervening whitespace. The corresponding files that
are attached to this wiki page and referred to in the text are their | |
< < | pretty-printed obtained by using | > > | pretty-printed versions obtained by using | | xmllint.
The Data Model | | Next, change the value of <eid:subnet-mask-length> back to 24 but
also introduce two new errors in the second <interface> entry: | |
< < |
- Change the value of
<name> from eth1 to eth0 . As a result, both list entries have the same key.
| > > |
- Change the value of
<name> from eth1 to eth0 . Both list entries now have the same key.
| |
- Add a new element:
<eid:enabled>true</eid:enabled> This violates the constraint stated by the 'must' statement in the extra-interface-data module.
| |
< < | In this case, nXML mode won't complain since the instance document
remains gramatically valid and all datatype constraints are satisfied
as well. The errors we deal with here are semantical. So let's try
the validation with yang2dsdl again: | > > | In this case, RELAX NG validators won't complain since the instance
document remains grammatically valid and all datatype constraints are
satisfied as well. The errors we deal with here are semantic. So
let's try the validation with yang2dsdl again: | |
$ yang2dsdl -s -b aug-acme-system -v aug-acme-system-dstore.xml | |
The error messages are now very clear, Schematron rocks! | |
< < | Feel free to make any other modifications in the instance documents
and re-run the validation to see what happens. | > > | Feel free to make any other modifications in the instance document and
re-run the validation to see what happens. | |
Developers and technically inclined readers may found further
technical details about the DSDL mapping and instance validation in | |
META FILEATTACHMENT |
attachment="acme-system.yang" attr="h" comment="YANG module acme-system" date="1274880028" name="acme-system.yang" path="acme-system.yang" size="901" stream="acme-system.yang" user="Main.LadaLhotka" version="1" |
META FILEATTACHMENT |
attachment="extra-interface-data.yang" attr="h" comment="Module augmenting acme-system" date="1274881291" name="extra-interface-data.yang" path="extra-interface-data.yang" size="643" stream="extra-interface-data.yang" user="Main.LadaLhotka" version="1" |
| |
< < |
META FILEATTACHMENT |
attachment="yang2dsdl.1.html" attr="h" comment="Manual page for yang2dsdl" date="1274881737" name="yang2dsdl.1.html" path="yang2dsdl.1.html" size="13548" stream="yang2dsdl.1.html" user="Main.LadaLhotka" version="1" |
| > > |
META FILEATTACHMENT |
attachment="yang2dsdl.1.html" attr="h" comment="Manual page for yang2dsdl" date="1274964618" name="yang2dsdl.1.html" path="yang2dsdl.1.html" size="13550" stream="yang2dsdl.1.html" user="Main.LadaLhotka" version="2" |
| |
META FILEATTACHMENT |
attachment="aug-acme-system-dstore.rng" attr="h" comment="RELAX NG schema" date="1274899811" name="aug-acme-system-dstore.rng" path="aug-acme-system-dstore.rng" size="2591" stream="aug-acme-system-dstore.rng" user="Main.LadaLhotka" version="1" |
META FILEATTACHMENT |
attachment="aug-acme-system-dstore.sch" attr="h" comment="Schematron schema" date="1274899853" name="aug-acme-system-dstore.sch" path="aug-acme-system-dstore.sch" size="988" stream="aug-acme-system-dstore.sch" user="Main.LadaLhotka" version="1" |
META FILEATTACHMENT |
attachment="aug-acme-system-dstore.dsrl" attr="h" comment="DSRL schema" date="1274899885" name="aug-acme-system-dstore.dsrl" path="aug-acme-system-dstore.dsrl" size="405" stream="aug-acme-system-dstore.dsrl" user="Main.LadaLhotka" version="1" |
META FILEATTACHMENT |
attachment="aug-acme-system-gdefs.rng" attr="h" comment="RELAX NG global defs" date="1274899913" name="aug-acme-system-gdefs.rng" path="aug-acme-system-gdefs.rng" size="403" stream="aug-acme-system-gdefs.rng" user="Main.LadaLhotka" version="1" |
META FILEATTACHMENT |
attachment="aug-acme-system-dstore.xml" attr="h" comment="Instance datastore" date="1274901881" name="aug-acme-system-dstore.xml" path="aug-acme-system-dstore.xml" size="580" stream="aug-acme-system-dstore.xml" user="Main.LadaLhotka" version="1" |
| |
< < |
META FILEATTACHMENT |
attachment="aug-acme-system.dsdl" attr="h" comment="hybrid schema" date="1274942508" 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="1274948359" 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-wdef.xml" attr="h" comment="Instance datastore with defaults" date="1274949157" 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-sch.xsl" attr="h" comment="XSLT generated from Schematron" date="1274950373" 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.svrl" attr="h" comment="SVRL report" date="1274951990" 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" |
|
|
META TOPICPARENT |
name="YangTools" |
DSDL Mapping Tutorial | | distribution, and then experiment with validating configuration
datastore contents. | |
< < | Finally, we dissect the yang2dsdl script and discuss other
possible setups and applications of the DSDL mapping procedure. | | NOTE: The software tools presented in this tutorial produce compact
XML data with no intervening whitespace. The corresponding files that
are attached to this wiki page and referred to in the text are their | | Feel free to make any other modifications in the instance documents
and re-run the validation to see what happens. | |
< < | Looking under the Hood
The yang2dsdl script may also serve as a model for implementing the
DSDL mapping and validating instance documents, perhaps on a non-Unix
operating system and using alternative XML tools. In this section we
describe the individual steps of the process and perform them manually
on our example data model.
The first step always involves 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 an interim product 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.
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
| > > | Developers and technically inclined readers may found further
technical details about the DSDL mapping and instance validation in
DSDLTechDetails. | |
META FILEATTACHMENT |
attachment="acme-system.yang" attr="h" comment="YANG module acme-system" date="1274880028" name="acme-system.yang" path="acme-system.yang" size="901" stream="acme-system.yang" user="Main.LadaLhotka" version="1" |
META FILEATTACHMENT |
attachment="extra-interface-data.yang" attr="h" comment="Module augmenting acme-system" date="1274881291" name="extra-interface-data.yang" path="extra-interface-data.yang" size="643" stream="extra-interface-data.yang" user="Main.LadaLhotka" version="1" |
| |
META FILEATTACHMENT |
attachment="aug-acme-system-gdefs.rng" attr="h" comment="RELAX NG global defs" date="1274899913" name="aug-acme-system-gdefs.rng" path="aug-acme-system-gdefs.rng" size="403" stream="aug-acme-system-gdefs.rng" user="Main.LadaLhotka" version="1" |
META FILEATTACHMENT |
attachment="aug-acme-system-dstore.xml" attr="h" comment="Instance datastore" date="1274901881" name="aug-acme-system-dstore.xml" path="aug-acme-system-dstore.xml" size="580" stream="aug-acme-system-dstore.xml" user="Main.LadaLhotka" version="1" |
META FILEATTACHMENT |
attachment="aug-acme-system.dsdl" attr="h" comment="hybrid schema" date="1274942508" 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="1274948359" 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-wdef.xml" attr="h" comment="Instance datastore with defaults" date="1274949157" 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-sch.xsl" attr="h" comment="XSLT generated from Schematron" date="1274950373" 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.svrl" attr="h" comment="SVRL report" date="1274951990" 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" |
|
|
META TOPICPARENT |
name="YangTools" |
DSDL Mapping Tutorial | | draft-ietf-netmod-dsdl-map.
This tutorial works with a very simple data model consisting of two | |
< < | YANG modules. We will first show how to perform the DSDL mapping | > > | YANG modules. We first show how to perform the DSDL mapping | | procedure with the yang2dsdl script that is a part of pyang
distribution, and then experiment with validating configuration
datastore contents. | |
< < | Finally, we will dissect the yang2dsdl script and discuss other | > > | Finally, we dissect the yang2dsdl script and discuss other | | possible setups and applications of the DSDL mapping procedure. | |
> > | NOTE: The software tools presented in this tutorial produce compact
XML data with no intervening whitespace. The corresponding files that
are attached to this wiki page and referred to in the text are their
pretty-printed obtained by using
xmllint. | | The Data Model
As an example, we use the YANG module acme-system shown at the | |
The error message is not particularly informative – it is a direct | |
< < | output of the RELAX NG validator built in the
xmllint tool – but at least the
conclusion in the last line is correct. | > > | output of the RELAX NG validator built in the xmllint tool – but at
least the conclusion in the last line is correct. | |
Next, change the value of <eid:subnet-mask-length> back to 24 but
also introduce two new errors in the second <interface> entry: | |
Looking under the Hood | |
< < | TBD. | > > | The yang2dsdl script may also serve as a model for implementing the
DSDL mapping and validating instance documents, perhaps on a non-Unix
operating system and using alternative XML tools. In this section we
describe the individual steps of the process and perform them manually
on our example data model.
The first step always involves 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 an interim product 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.
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
| |
META FILEATTACHMENT |
attachment="acme-system.yang" attr="h" comment="YANG module acme-system" date="1274880028" name="acme-system.yang" path="acme-system.yang" size="901" stream="acme-system.yang" user="Main.LadaLhotka" version="1" |
META FILEATTACHMENT |
attachment="extra-interface-data.yang" attr="h" comment="Module augmenting acme-system" date="1274881291" name="extra-interface-data.yang" path="extra-interface-data.yang" size="643" stream="extra-interface-data.yang" user="Main.LadaLhotka" version="1" |
| |
META FILEATTACHMENT |
attachment="aug-acme-system-dstore.dsrl" attr="h" comment="DSRL schema" date="1274899885" name="aug-acme-system-dstore.dsrl" path="aug-acme-system-dstore.dsrl" size="405" stream="aug-acme-system-dstore.dsrl" user="Main.LadaLhotka" version="1" |
META FILEATTACHMENT |
attachment="aug-acme-system-gdefs.rng" attr="h" comment="RELAX NG global defs" date="1274899913" name="aug-acme-system-gdefs.rng" path="aug-acme-system-gdefs.rng" size="403" stream="aug-acme-system-gdefs.rng" user="Main.LadaLhotka" version="1" |
META FILEATTACHMENT |
attachment="aug-acme-system-dstore.xml" attr="h" comment="Instance datastore" date="1274901881" name="aug-acme-system-dstore.xml" path="aug-acme-system-dstore.xml" size="580" stream="aug-acme-system-dstore.xml" user="Main.LadaLhotka" version="1" |
| |
> > |
META FILEATTACHMENT |
attachment="aug-acme-system.dsdl" attr="h" comment="hybrid schema" date="1274942508" name="aug-acme-system.dsdl" path="aug-acme-system.dsdl" size="4309" stream="aug-acme-system.dsdl" user="Main.LadaLhotka" version="1" |
|
|
META TOPICPARENT |
name="YangTools" |
DSDL Mapping Tutorial
Introduction | |
< < | One of the functions implemented in [[http://code.google.com/p/pyang]
[pyang]] is the mapping of | > > | One of the functions implemented in
pyang is the mapping of | | YANG data | |
< < | models to DSDL schemas – RELAX NG, Schematron and DSRL. The | > > | models to DSDL schemas –
RELAX NG,
Schematron and DSRL. The | | resulting schemas may be used with off-the-shelf XML tools for
validating NETCONF datastores and PDUs and other related purposes. | | YANG modules. We will first show how to perform the DSDL mapping
procedure with the yang2dsdl script that is a part of pyang
distribution, and then experiment with validating configuration | |
< < | datastore contents and a NETCONF protocol data unit (PDU). | > > | datastore contents. | |
Finally, we will dissect the yang2dsdl script and discuss other
possible setups and applications of the DSDL mapping procedure. | | }
| |
< < | Our data model now defines a compound document which contains nodes
in the namespaces of both contributing modules, acme-system and | > > | Our data model now defines a compound document containing nodes in
the namespaces of both the contributing modules, acme-system and | | extra-interface-data.
Generating the Schemas | |
- dstore
- raw datastore content;
- get-reply
- a complete NETCONF message containing a reply to
| |
< < | operation; | > > | <get> operation; | |
- getconf-reply
- a complete NETCONF message containing a reply to
| |
< < | <get-config> operation; | > > | <get-config> operation; | |
- rpc
- An RPC request defined in the input YANG module(s);
- rpc-reply
- An RPC reply defined in the input YANG module(s);
- notif
- An event notification defined in the input YANG module(s).
| |
< < | Only the first three targets make sense in our case as our YANG | > > | Only the first three targets make sense in our case as the YANG | | modules define neither RPC operations nor event
notifications. Moreover, there are no operational state data or | |
< < | statistics in our modules, so the replies to and
<get-config> are bound to be identical. | > > | statistics in our modules, so the replies to <get> and
<get-config> are bound to be identical. | | | |
< < | Another technical detail to consider are the file names in which the
output schemas will be stored. | > > | Another detail to consider are the file names in which the output
schemas will be stored. The names have the following general form: | | | |
< < | All right, let's begin with the "dstore" target. We needn't use the
-t option here as "dstore" is the default: | > > |
BASE-TARGET.EXT
The first part, BASE, can be chosen by the user while the other two
cannot. TARGET is always set to the selected target (see above) and
EXT is a file extension specific for each DSDL schema language – rng
is used for RELAX NG, sch for Schematron and dsrl for DSRL.
If the BASE part isn't provided by the user, the script constructs a
default one, which is a concatenation of the names of all input YANG
modules connected with the underscore character _ . The result in
our example – acme-system_extra-interface-data – would lead to
rather long file names. We therefore decide to specify a shorter BASE
part explicitly, say aug-acme-system .
All right, let's generate the DSDL schemas for the "dstore" target. We
needn't use the -t option here as "dstore" is the default: | |
$ yang2dsdl -b aug-acme-system acme-system.yang extra-interface-data.yang | | Done.
| |
> > | As indicated by the program output, the resulting DSDL schemas were
written to three files:
But wait, the script also created a fourth file, namely
aug-acme-system-gdefs.rng. This
is actually a part of the RELAX NG schema containing all global
definitions (mapped from YANG top-level groupings and typedefs). For
technical reasons, these definitions have to be included from an
external file. | | An Instance Configuration Datastore | |
> > | In order to be able to see the generated DSDL schemas in action, we
need to create an XML document containing, in our case, a "raw"
configuration datastore. If we have an appropriate schema-aware
editor, we can provide it with the RELAX NG schema (or Schematron as
well). An excellent choice is
GNU Emacs with James Clark's
nXML mode.
The following is a valid datastore content (see also
aug-acme-system-dstore.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>
</interface>
</system>
Emacs with nXML mode is also a user-friendly RELAX NG
validator. For example, we can try to change the value of the
<eid:subnet-mask-length> element to 42 , which violates a datatype
constraint – this value must be in the range between 0 and 32. As a
result, the wrong value is underlined in Emacs and the status line
indicates that the edited XML document is invalid. | | Validation | |
> > | We can use the yang2dsdl script for validating the above
datastore content (the -s flag instructs the script to use the
existing DSDL schemas, without it the schemas would be regenerated):
$ yang2dsdl -s -b aug-acme-system -v aug-acme-system-dstore.xml
== Using pre-generated schemas
== Validating grammar and datatypes ...
aug-acme-system-dstore.xml validates
== Adding default values... done.
== Validating semantic constraints ...
No errors found.
Sure enough, no errors were detected in the instance document. Now,
let's change the value of the <eid:subnet-mask-length> element to
42 again and re-run the same command:
$ yang2dsdl -s -b aug-acme-system -v aug-acme-system-dstore.xml
== Using pre-generated schemas
== Validating grammar and datatypes ...
Relax-NG validity error : Extra element subnet-mask-length in interleave
aug-acme-system-dstore.xml:12: element subnet-mask-length: Relax-NG validity error : Element interface failed to validate content
Relax-NG validity error : Extra element interface in interleave
aug-acme-system-dstore.xml:6: element interface: Relax-NG validity error : Element system failed to validate content
aug-acme-system-dstore.xml fails to validate
The error message is not particularly informative – it is a direct
output of the RELAX NG validator built in the
xmllint tool – but at least the
conclusion in the last line is correct.
Next, change the value of <eid:subnet-mask-length> back to 24 but
also introduce two new errors in the second <interface> entry:
- Change the value of
<name> from eth1 to eth0 . As a result, both list entries have the same key.
- Add a new element:
<eid:enabled>true</eid:enabled> This violates the constraint stated by the 'must' statement in the extra-interface-data module.
In this case, nXML mode won't complain since the instance document
remains gramatically valid and all datatype constraints are satisfied
as well. The errors we deal with here are semantical. So let's try
the validation with yang2dsdl again:
$ yang2dsdl -s -b aug-acme-system -v aug-acme-system-dstore.xml
== Using pre-generated schemas
== Validating grammar and datatypes ...
aug-acme-system-dstore.xml validates
== Adding default values... done.
== Validating semantic constraints ...
--- Validity error at "/acme:system/acme:interface":
Duplicate key "acme:name"
--- Failed assert at "/acme:system/acme:interface/eid:enabled":
IP address and mask must be configured for enabled interfaces.
The error messages are now very clear, Schematron rocks!
Feel free to make any other modifications in the instance documents
and re-run the validation to see what happens. | | Looking under the Hood | |
> > | TBD. | |
META FILEATTACHMENT |
attachment="acme-system.yang" attr="h" comment="YANG module acme-system" date="1274880028" name="acme-system.yang" path="acme-system.yang" size="901" stream="acme-system.yang" user="Main.LadaLhotka" version="1" |
META FILEATTACHMENT |
attachment="extra-interface-data.yang" attr="h" comment="Module augmenting acme-system" date="1274881291" name="extra-interface-data.yang" path="extra-interface-data.yang" size="643" stream="extra-interface-data.yang" user="Main.LadaLhotka" version="1" |
META FILEATTACHMENT |
attachment="yang2dsdl.1.html" attr="h" comment="Manual page for yang2dsdl" date="1274881737" name="yang2dsdl.1.html" path="yang2dsdl.1.html" size="13548" stream="yang2dsdl.1.html" user="Main.LadaLhotka" version="1" |
| |
> > |
META FILEATTACHMENT |
attachment="aug-acme-system-dstore.rng" attr="h" comment="RELAX NG schema" date="1274899811" name="aug-acme-system-dstore.rng" path="aug-acme-system-dstore.rng" size="2591" stream="aug-acme-system-dstore.rng" user="Main.LadaLhotka" version="1" |
META FILEATTACHMENT |
attachment="aug-acme-system-dstore.sch" attr="h" comment="Schematron schema" date="1274899853" name="aug-acme-system-dstore.sch" path="aug-acme-system-dstore.sch" size="988" stream="aug-acme-system-dstore.sch" user="Main.LadaLhotka" version="1" |
META FILEATTACHMENT |
attachment="aug-acme-system-dstore.dsrl" attr="h" comment="DSRL schema" date="1274899885" name="aug-acme-system-dstore.dsrl" path="aug-acme-system-dstore.dsrl" size="405" stream="aug-acme-system-dstore.dsrl" user="Main.LadaLhotka" version="1" |
META FILEATTACHMENT |
attachment="aug-acme-system-gdefs.rng" attr="h" comment="RELAX NG global defs" date="1274899913" name="aug-acme-system-gdefs.rng" path="aug-acme-system-gdefs.rng" size="403" stream="aug-acme-system-gdefs.rng" user="Main.LadaLhotka" version="1" |
META FILEATTACHMENT |
attachment="aug-acme-system-dstore.xml" attr="h" comment="Instance datastore" date="1274901881" name="aug-acme-system-dstore.xml" path="aug-acme-system-dstore.xml" size="580" stream="aug-acme-system-dstore.xml" user="Main.LadaLhotka" version="1" |
|
|
> > |
META TOPICPARENT |
name="YangTools" |
DSDL Mapping Tutorial
Introduction
One of the functions implemented in [[http://code.google.com/p/pyang]
[pyang]] is the mapping of
YANG data
models to DSDL schemas – RELAX NG, Schematron and DSRL. The
resulting schemas may be used with off-the-shelf XML tools for
validating NETCONF datastores and PDUs and other related purposes.
The mapping procedure is described in
draft-ietf-netmod-dsdl-map.
This tutorial works with a very simple data model consisting of two
YANG modules. We will first show how to perform the DSDL mapping
procedure with the yang2dsdl script that is a part of pyang
distribution, and then experiment with validating configuration
datastore contents and a NETCONF protocol data unit (PDU).
Finally, we will dissect the yang2dsdl script and discuss other
possible setups and applications of the DSDL mapping procedure.
The Data Model
As an example, we use the YANG module acme-system shown at the
bottom of WebHome (see also
acme-system.yang). To make things
slightly more interesting, we augment this module by adding three new
nodes to the entries of the "interface" list. This is accomplished by
the following module (see also
extra-interface-data.yang):
module extra-interface-data {
namespace "http://foo.example.com/extra-if-data";
prefix eid;
import acme-system {
prefix acme;
}
import ietf-inet-types {
prefix inet;
}
augment "/acme:system/acme:interface" {
leaf enabled {
type boolean;
default "false";
must ".='false' or ../ipv4-address and ../subnet-mask-length" {
error-message "IP address and mask must be configured " +
"for enabled interfaces.";
}
}
leaf ipv4-address {
type inet:ipv4-address;
}
leaf subnet-mask-length {
type uint8 {
range "0..32";
}
}
}
}
Our data model now defines a compound document which contains nodes
in the namespaces of both contributing modules, acme-system and
extra-interface-data.
Generating the Schemas
The DSDL schemas can be generated quite easily (at least on Linux and
Unix systems) from the two YANG modules by using the yang2dsdl shell
script which is provided with the pyang distribution. The details
about its usage can be found in the
manual page or by running
yang2dsdl -h .
But before we start, we need to decide which target document type the
generated schemas are to address. Currently, yang2dsdl supports the
following targets that are selected via the -t command line option:
- dstore
- raw datastore content;
- get-reply
- a complete NETCONF message containing a reply to
operation;
- getconf-reply
- a complete NETCONF message containing a reply to
<get-config> operation;
- rpc
- An RPC request defined in the input YANG module(s);
- rpc-reply
- An RPC reply defined in the input YANG module(s);
- notif
- An event notification defined in the input YANG module(s).
Only the first three targets make sense in our case as our YANG
modules define neither RPC operations nor event
notifications. Moreover, there are no operational state data or
statistics in our modules, so the replies to and
<get-config> are bound to be identical.
Another technical detail to consider are the file names in which the
output schemas will be stored.
All right, let's begin with the "dstore" target. We needn't use the
-t option here as "dstore" is the default:
$ yang2dsdl -b aug-acme-system acme-system.yang extra-interface-data.yang
== Generating RELAX NG schema './aug-acme-system-dstore.rng'
Done.
== Generating Schematron schema './aug-acme-system-dstore.sch'
Done.
== Generating DSRL schema './aug-acme-system-dstore.dsrl'
Done.
An Instance Configuration Datastore
Validation
Looking under the Hood
META FILEATTACHMENT |
attachment="acme-system.yang" attr="h" comment="YANG module acme-system" date="1274880028" name="acme-system.yang" path="acme-system.yang" size="901" stream="acme-system.yang" user="Main.LadaLhotka" version="1" |
META FILEATTACHMENT |
attachment="extra-interface-data.yang" attr="h" comment="Module augmenting acme-system" date="1274881291" name="extra-interface-data.yang" path="extra-interface-data.yang" size="643" stream="extra-interface-data.yang" user="Main.LadaLhotka" version="1" |
META FILEATTACHMENT |
attachment="yang2dsdl.1.html" attr="h" comment="Manual page for yang2dsdl" date="1274881737" name="yang2dsdl.1.html" path="yang2dsdl.1.html" size="13548" stream="yang2dsdl.1.html" user="Main.LadaLhotka" version="1" |
|
 Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors. Ideas, requests, problems regarding TWiki? Send feedback
|
|
|