NETCONF WG R. Mahy
Internet-Draft Plantronics
Intended status: Informational S. Chisholm
Expires: August 21, 2008 Nortel Networks
February 18, 2008
Defining Netconf Data Models using Document Schema Definition Languages
(DSDL)
draft-mahy-canmod-dsdl-00.txt
Status of this Memo
By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on August 21, 2008.
Copyright Notice
Copyright (C) The IETF Trust (2008).
Abstract
This document describes a concrete proposal for creating Netconf and
other IETF data models using the RelaxNG schema language and the
Schematron validation language, which are both part of ISO's Document
Schema Definition Languages (DSDL) standard.
Mahy & Chisholm Expires August 21, 2008 [Page 1]
Internet-Draft CANMOD using DSDL February 2008
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. RelaxNG . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
4. Processing annotations for additional validation . . . . . . . 7
4.1. The 'unique' annotation . . . . . . . . . . . . . . . . . 7
4.2. The 'key' annotation . . . . . . . . . . . . . . . . . . . 8
4.3. The 'keyref' annotation . . . . . . . . . . . . . . . . . 9
4.4. The 'mustUse' annotation . . . . . . . . . . . . . . . . . 11
4.5. The 'info-type' annotation . . . . . . . . . . . . . . . . 11
4.6. Additional validation rules . . . . . . . . . . . . . . . 12
5. Validating instance data automatically with Schematron . . . . 13
6. Validating the data model itself . . . . . . . . . . . . . . . 15
7. Documentation annotations . . . . . . . . . . . . . . . . . . 16
8. Extensibility Model . . . . . . . . . . . . . . . . . . . . . 17
9. Netconf Specifics . . . . . . . . . . . . . . . . . . . . . . 18
9.1. Edit-config operations . . . . . . . . . . . . . . . . . . 19
9.2. Get and Get-config operations . . . . . . . . . . . . . . 19
9.3. Netconf notifications . . . . . . . . . . . . . . . . . . 20
9.4. New netconf actions . . . . . . . . . . . . . . . . . . . 21
9.5. Netconf specific error messages . . . . . . . . . . . . . 21
10. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 23
10.1. Cardinality . . . . . . . . . . . . . . . . . . . . . . . 23
10.2. Operations on managed objects . . . . . . . . . . . . . . 24
10.3. Element and Attribute Status . . . . . . . . . . . . . . . 24
10.4. Additional Conformance Information . . . . . . . . . . . . 25
10.5. Schema Level Conformance - Server-side . . . . . . . . . . 25
10.6. Schema Level Conformance - Client-side . . . . . . . . . . 25
11. Grading against the requirements . . . . . . . . . . . . . . . 26
12. Full Examples . . . . . . . . . . . . . . . . . . . . . . . . 33
13. "DML" Annotations Schema . . . . . . . . . . . . . . . . . . . 37
14. Security Considerations . . . . . . . . . . . . . . . . . . . 39
15. IANA Consideration . . . . . . . . . . . . . . . . . . . . . . 39
16. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 39
Appendix A. XSLT Transform from processing annotation to
Schematron . . . . . . . . . . . . . . . . . . . . . 39
Appendix B. Schematron for validating data model documents . . . 40
17. References . . . . . . . . . . . . . . . . . . . . . . . . . . 40
17.1. Normative References . . . . . . . . . . . . . . . . . . . 40
17.2. Informational References . . . . . . . . . . . . . . . . . 41
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 42
Intellectual Property and Copyright Statements . . . . . . . . . . 43
Mahy & Chisholm Expires August 21, 2008 [Page 2]
Internet-Draft CANMOD using DSDL February 2008
1. Introduction
The NETCONF Working Group has completed a base protocol [1] used for
configuration management. This base specification defines protocol
bindings and an XML [4] container syntax for configuration and
management operations, but does not include a modeling language or
accompanying rules for how to model configuration and status
information (in XML syntax) carried by Netconf. The IETF Operations
area has a long tradition of defining data for SNMP [13] Management
Information Bases (MIBs) using the SMI [14] to model its data. While
this specific modeling approach has a number of well-understood
problems, most of the data modeling features provided by SMI are
still considered extremely important. Simply modeling the valid
syntax rather than additional semantic relationships has caused
significant interoperability problems in the past. The Netconf
community concluded that a data modeling framework is needed to
support ongoing development of IETF and vendor-defined management
information modules.
A design team collected, clarified and categorized requirements [12]
for a data modeling language from a broad group of IETF participants.
Many of these requirements have broad agreement within the design
team. This document describes an approach that addresses all the
broadly agreed requirements and a substantial number of the
additional requirements.
The approach to data modeling described here uses the two most mature
parts of the ISO Document Schema Definition Languages (DSDL) [22]
multi-part standard: Relax NG and Schematron, plus additional
processing and documentation annotation schema. Relax NG [8] is a
mature, traditional schema language for validating the structure of
an XML document. Schematron [7] is a rule-based schema validation
language which uses XPath [9] expressions to validate content and
relational constraints. In addition, this document defines and
reuses various annotation schema which can provide additional
metadata about specific elements in the data model such as textual
descriptions, default values, relational integrity key definitions,
and whether data is configuration or status data.
This combination was created to specifically address a set of
Netconf-specific modeling requirements, and in addition should be
useful as a general purpose data modeling solution useful for other
IETF working groups. The authors believe that reusing schema work
being developed and used by other standards bodies provides
substantial long-term benefits to the IETF management community, so
this proposal attempts to reuse as much as possible.
Mahy & Chisholm Expires August 21, 2008 [Page 3]
Internet-Draft CANMOD using DSDL February 2008
2. Overview
This document proposes a concrete data modeling environment which
meets the Netconf data modeling design team requirements but is
otherwise very general purpose in nature. The proposal is quite
modular and draws from a number of existing standards and well-
understood schemas. Relevant requirements will be mentioned in each
major section, but a table of requirements is included in Section 11.
In order to make it easier to compare various proposed solutions to
provide a framework to define NETCONF content, each proposal produced
a non-trivial data model description to generate an instance document
compatible with the DHCP configuration example document in Appendix C
of the requirements document. The full example data model document
is shown in Section 12.
This document starts in Section 3 by describing the use of RelaxNG to
model XML syntax, element and attribute names, containment
relationships, cardinality, data types, and simple range and pattern
restrictions. RelaxNG can use its own basic type definitions or
reuse the W3C XML Schema Datatypes [5] definitions. It is also
straightforward to reference one or more external libraries of data
types. This proposal includes definitions of IPv4 addresses and MAC
addresses.
While using an existing schema language is a good start toward the
data modeling requirements, a data modeling solution also needs
additional semantics conveyed. Section 4 describes "processing
annotations" which describe validation rules for instance documents
based on the data model. These annotations are incorporated inline
with the RelaxNG schema. Most of these validation rules can be
validated either in source code generated by a human or in a machine
readable way. [Sharon: this last bit needs explaining] The machine
readable rules make extensive use of XPath [9] expressions. An XSLT
[10] (Extensible Stylesheet Language: Transformations) document
described in Appendix A can convert the machine readable rules in a
specific data model document into a Schematron validation document
for that data model. This conversion is done only once each time the
data model is modified.
Section 5 describes how a Schematron document is used to validate an
instance document, and describes a set of three different levels or
phases of validation that this proposal supports. Section 6
describes how Schematron can validate a very different set of rules
on data model documents to make sure that they comply with specific
conventions. This document defines a set of Schematron rules in
Appendix B, which are compatible with content restrictions imposed by
Netconf.
Mahy & Chisholm Expires August 21, 2008 [Page 4]
Internet-Draft CANMOD using DSDL February 2008
Section 7 describes how to attach document metadata (ex: title,
author, dates), per element descriptions, semantic hints about
elements, default values, units, and conformance status (active,
deprecated, obsolete) to the data model as documentation annotations.
Most of the document metadata is described using the Dublin Core [2]
metadata schemas. Default values are described using the DTD
(Document Type Definition) compatibility annotations [23]. The
definition for units is copied from the units definitions used by the
Geographic Markup Language GML [16]. The rest of these annotations
are defined in a RelaxNG annotation schema in Section 13.
Section 8 describes the extensibility and versioning model envisioned
by this proposal. It also describes the interaction between default
values and extensibility in this proposal.
Finally, Section 9 describes how to use the data model to support
Netconf-specific requirements. In particular, this section describes
how to model Netconf notification [Sharon: do we mean notification
here?]of a nearly full DHCP scope and an IP address conflict, a
Netconf-specific error response, and the definition of a new action
to revoke a lease.
3. RelaxNG
RelaxNG is an XML schema language developed by OASIS [24] and then
adopted by ISO as Part 2 of DSDL. It is now a full ISO standard.
RelaxNG has a reputation that it is easy to read and easy to learn.
RelaxNG has a solid theoretical basis, and is the canonical schema
format for several major W3C standards (XHTML [17], SVG [18], XML
signature [19], RDF [20]). RelaxNG includes strong support for XML
namespaces [6], treats attributes and elements similarly, and can
define schemas which support (or do not support) unordered content.
It can use integral types or an external data type library such as
W3C XML Schema Datatypes.
Unlike W3C XML Schema [21] (referred to later as XSD or WXS), RelaxNG
only describes the structure and contents of XML documents. RelaxNG
intentionally does not try to modify the information set of an XML
document. For example, it does not address default values (supported
XML DTDs) or key and keyref types (supported in W3C XML Schema).
Since RelaxNG supports arbitrary annotations, other languages can add
semantics to a RelaxNG schema. Indeed, the RelaxNG DTD compatibility
schema includes annotations for default values. The rest of DSDL
also follows this modular philosophy. Part 6 of DSDL (work not
started) is reserved for path-based integrity constraints (analogous
to XSD keys and keyrefs).
Mahy & Chisholm Expires August 21, 2008 [Page 5]
Internet-Draft CANMOD using DSDL February 2008
RelaxNG has both an XML representation and a Compact representation.
They can be converted automatically using open source tools such as
Trang [25]. Trang can also convert either form of RelaxNG to XSD
format automatically with some minor restrictions (RelaxNG can
represent some schema which XSD cannot). This document will use the
Compact form for brevity and readability throughout.
In RelaxNG Compact syntax, the symbols '?' (one or zero), '+' (one or
more), and '*' (zero or more) have their familiar meaning. The
symbol ',' indicates the next pattern follows in order, the symbol
'&' indicates that the next element can come before or after the
current pattern, and the '|' symbol indicates a choice among
patterns. Below is an example of a RelaxNG Compact schema snippet,
simplified from the schema for the full example in this proposal.
start = element-dhcp
element-dhcp = element dhcp {
element subnet {
element network { ipv4-address-content },
element prefix-length {
xsd:short { minInclusive = "0" maxInclusive = "32" }
}
element-range?,
element leases {
element-lease*
}?,
}*
}
element-range = element range {
element low { ipv4-address-content },
element high { ipv4-address-content }
}
element-lease = element lease {
attribute ip-address { ipv4-address-content },
element starts { xsd:dateTime },
element ends { xsd:dateTime },
element mac-address { mac-address-content }
}
A full tutorial on RelaxNG is beyond the scope of this document.
This proposal will try to introduce unfamiliar concepts as they
appear, but in some cases, the reader may wish to consult an outside
reference or tutorial. More information on RelaxNG is available in
relaxng book [15] and at the following web sites:
Mahy & Chisholm Expires August 21, 2008 [Page 6]
Internet-Draft CANMOD using DSDL February 2008
4. Processing annotations for additional validation
RelaxNG readily accepts annotations in other namespaces. For
example, one of the RelaxNG DTD compatibility annotations is used to
specify default values:
namespace compat = "http://relaxng.org/ns/compatibility/annotations/1.0"
element ice-cream {
("vanilla" | "chocolate") >> compat:defaultValue ["chocolate"]
}
There are a variety of reasons to add annotations, but this section
of the proposal focuses on annotations which can be used to define
further processing on an instance document, especially validation.
Processing annotations could be implemented automatically by a
machine or by a human reading descriptive text in the data model who
implements source code. This document defines a new schema for both
processing annotations and documentation annotations. This section
begins by explaining the semantics of each of the processing
annotations defined here. In our examples, this annotation schema
will use the namespace prefix 'dml'.
4.1. The 'unique' annotation
The 'unique' annotation element specifies an expression (usually an
element) that needs to be unique within a list. The annotation can
follows any element definition which has a cardinality greater than
one ('+' or '*'). The content of the unique element is an XPath [9]
expression which is evaluated relative to the element it follows (and
its immediate parent). For example, in the following example, the
'port' element has to be unique within all other service elements
under the servers element:
element-servers = element servers {
element service {
element name { xsd:string },
element port { xsd:unsignedShort }
}+ >> dml:unique ["port"]
}
# '//servers/service' must have only one 'port' with a specific value.
In terms of XPath expressions, this means that in the context
'//servers/service/port', the XPath expression 'count( //servers/
service[port=current()] ) = 1' needs to be true. (Does the number of
Mahy & Chisholm Expires August 21, 2008 [Page 7]
Internet-Draft CANMOD using DSDL February 2008
service elements with a port element equal to the value of the
current port element equal 1?). Expressing this rule as a series of
XPath expressions makes the rule more precise, but it also enables a
conversion of this constraint to a Schematron validation rule as
discussed in Section 5. In the following snippet of instance
document, the second http service is not allowed since its port
number conflicts with another service.
ssh
2222
http
80
http
2222
This syntax is also capable of specifying that the combination of one
or more fields is required to be unique.
4.2. The 'key' annotation
In many cases, something is unique in a list because it is actually a
key used in cross-element relationships. The 'key' annotation
specifies that an expression can be used as a unique lookup key among
the elements of a list (an element with cardinality greater than
one). In addition, this key can be used in another element which is
a key reference (keyref) to provide referential integrity between
these related elements. As with the 'unique' element, the content of
the 'key' element is an XPath expression which is evaluated relative
to the element it follows (and its immediate parent).
As shown in the next example, the key can be a compound key (formed
from more than one element or attribute), and it can reference
descendants of arbitrary depth to form the key. The key to the
subnet element in the instance document is "192.168.24.0/24".
Key are critical for any data that will be configured or for any data
that will get referenced via a keyref statement. Therefore key
definitions are mandatory for all lists.
Mahy & Chisholm Expires August 21, 2008 [Page 8]
Internet-Draft CANMOD using DSDL February 2008
element-dhcp = element dhcp {
element subnet {
element prefix {
element network { ipv4-address-content },
element prefix-length {
xsd:short { minInclusive = "0" maxInclusive = "32" }
}
},
element-range
}+ >> dml:key ["concat(prefix/network, '/', prefix/prefix-length)"]
}
192.168.24.0
24
192.168.24.20
192.168.24.250
The validation rule for keys are as follows: If an XML element with
cardinality greater than one (for brevity a 'list element') has an
'id' attribute with type 'ID', the validation rules defined here will
use the 'id' attribute as the list key. If a list element consists
only of a single text value, the validation rules defined here will
use the text value as the key unless a different key definition is
explicitly provided. Likewise, if a list element consists of an
empty value and has only one attribute, the attribute will be used as
the key unless a different key definition is explicitly provided.
[EDITOR'S NOTE: It would be really nice to use a key attribute or
an id attribute in most lists. Perhaps adding a separate 'keydef'
annotation that you put on the actual key attribute would be
nice.]
4.3. The 'keyref' annotation
The contents of the 'keyref' annotation contains an XPath expression
which points to the element under which a 'key' annotation was
defined. In the example in the previous section, the key element
annotates the 'subnet' element. Therefore a keyref annotation
referring to a specific subnet element will use the XPath expression
'//dhcp:subnet'. Note that keyrefs could often refer to elements in
Mahy & Chisholm Expires August 21, 2008 [Page 9]
Internet-Draft CANMOD using DSDL February 2008
a different namespace. For example, in the example that follows, the
dhcp:interfaces-filter element consists of a list of tokens which
refer to keys defined under the //int:interface schema definition.
element-subnet = element subnet {
element network { ipv4-address-content },
element prefix-length {
xsd:short { minInclusive = "0" maxInclusive = "32" }
},
element interface-filter {
element interface { xsd:token }+
>> dml:keyref ["//int:interface"]
}
}
element-interfaces = element int:interfaces {
element int:interface {
element int:ifIndex { xsd:token },
element int:ifType { xsd:token }
}+ >> dml:key ["int:ifIndex"]
}
10.1.1.0
24
lo0
en2
lo0
en1
en2
Be aware that in some cases, a list may consist of elements which
have both a key and keyref (a list of keyrefs).
Mahy & Chisholm Expires August 21, 2008 [Page 10]
Internet-Draft CANMOD using DSDL February 2008
4.4. The 'mustUse' annotation
An element in the data model tagged with the 'mustUse' annotation
indicates that the tagged element needs to appear in the instance
document whenever its parent appears. Items with a defaultValue
annotation cannot also have a mustUse annotation.
In many schemas, there is a facility for using fragments or
patches of XML documents. (Netconf uses these fragments
extensively in edit-config operations for example). In order to
accommodate these fragments, the cardinality of an otherwise
"required" element may allow the element to be optional in an XML
fragment. The mustUse annotation provides a way to express what
is actually required in this situation.
See also the client-side discussed in Section 10.
4.5. The 'info-type' annotation
The 'info-type' annotation indicates the category of data that
applies to the annotated element and all its children until another
'info-type' annotation. The content of the 'info-type' element is an
enumeration. The 'config' type is the default value. It indicates
that the covered data is configuration and that it is at least
theoretically possible to include this data in read, write, create,
and delete operations. Likewise 'status' and 'statistics'
information can be read, but cannot be included in write, create, and
delete operations.
The example below indicates that the 'leases' element and all its
sub-elements are status information and not suitable for creating,
writing, or deleting.
element-leases = element leases {
element lease {
attribute ip-address { ipv4-address-content },
element starts { xsd:dateTime },
element ends { xsd:dateTime },
element mac-address { mac-address-content }
}*
} >> dml:info-type ["status"]
In addition, this annotation element has optional minAccess and
maxAccess attributes which can override the default list of relevant
operations. These attributes are discussed in more detail in
Section 10.
Mahy & Chisholm Expires August 21, 2008 [Page 11]
Internet-Draft CANMOD using DSDL February 2008
4.6. Additional validation rules
In our DHCP example, the validation statement that "subnets can't
overlap" is easy to say in English, but hard to write formally. In
addition, some validation tests may be difficult or impossible to
evaluate without local state information. The 'manual-validation-
rule' annotation provides a natural language explanation of a
validation constraint that can only be evaluated by a human. When
validation rules (as in Section 5) are automatically generated, a
warning will be generated for each manual-validation-rule.
element-subnet = element subnet {
element network { ipv4-address-content },
element prefix-length {
xsd:short { minInclusive = "0" maxInclusive = "32" }
}
}
>> dml:manual-validation-rule [xml:lang="en" "Subnets may not overlap"]
>> dml:manual-validation-rule [xml:lang="fr"
"On ne peu pas numere les networks l'un sur l'autre"]
In addition, the data model can also define additional rules formally
by embedding specific Schematron rules. Schematron is a rule-based
validation language for XML documents. Schematron patterns define a
series of rules using XPath expressions which evaluate to a boolean
value. These rules contain human language text which could be used
to implement manual validation. The text node of the Schematron
assert statement should provide text suitable for a human to write an
equivalent validity check.
element-dhcp = element dhcp {
[
sch:pattern [
sch:rule [
context = "//dhcp:dhcp"
sch:assert [
test = "dhcp:default-lease-time <= dhcp:max-lease-time"
"Default lease time cannot be larger than maximum lease time"
]
]
]
]
element default-lease-time { xsd:unsignedInt }?,
element max-lease-time { xsd:unsignedInt }?,
...
}
The preceding example consists of a single rule. In the context of
Mahy & Chisholm Expires August 21, 2008 [Page 12]
Internet-Draft CANMOD using DSDL February 2008
the 'dhcp' element, the value of the 'default-lease-time' element
needs to be less than or equal to the value of the 'max-lease-time'
element.
Once these embedded Schematron rules are written, one vendor could
enforce these rules in code, while another could use the provided
XSLT transformation in Appendix A to create a Schematron file from
the data model.
5. Validating instance data automatically with Schematron
ISO Schematron is a rule-based validation language based on XPath
expressions. It is Part 3 of the DSDL standard. [Add a very short
explanation of XPath expressions] While a complete tutorial on
Schematron or XPath is beyond the scope of this document, we will
walk through a simple example to highlight the most important
concepts. This example is functionally the same as the example of
Schematron embedded in RelaxNG Compact in the last section.
Default lease time cannot be larger than maximum lease time
The Schematron validator evaluates the context of each rule, then
evaluates each assert or report clause within the rule. Lets look at
a more complicated example that is used for insuring that a key is
unique within a list context.
The value ifIndex must be unique among all interfaces.
For every ifIndex element, the 'assert' tests if the number of
interfaces which have an ifIndex matching the current one (being
evaluated). This XPath expression is rather long. Since we will use
this idiom repeatedly, we can define a Schematron abstract pattern to
Mahy & Chisholm Expires August 21, 2008 [Page 13]
Internet-Draft CANMOD using DSDL February 2008
express this more succinctly.
The key "$key" needs to be unique within the list at: $context
Likewise, we can write Schematron abstract patterns for validating
keyref relationships as well.
The contents of "$keyref-context" must be a
with the key "$key" in this context: $key-context.
The provided XSLT stylesheet reads the data model processing
annotations to automatically generate Schematron patterns that use
these abstract patterns. The XSLT stylesheet is just calculating the
context XPaths by examining the document structure in the RelaxNG
schema. Once generated, these rules can be used to test the validity
of instance documents. These Schematron tests can provide different
levels of validity checking.
Conceptually, an implementation can validate its instance data in
different logical phases, adding more tests with each phase. We use
three levels or phases for validating an instance document. There is
a level of validation which is appropriate even for loose XML
document fragments which still maintain their hierarchy (the fragment
phase), there is a level of validation appropriate for a cohesive XML
Mahy & Chisholm Expires August 21, 2008 [Page 14]
Internet-Draft CANMOD using DSDL February 2008
document but which may not be able to validate relational integrity
checks against some operational state (the standard phase), and there
is validation which includes all relational integrity checks (the
full validation phase). For example, in Netconf an edit-config
operation can cause the replacement a small fragment of XML. A
candidate configuration may be waiting for application but can't
check the readiness of a piece of hardware that the configuration
refers to.
[EDITORS NOTE: move to netconf specific section. Sharon: We can,
just so long as readers can connect the dots to NETCONF themselves.
Otherwise we risk comments about being too general.] From the
NETCONF perspective, these three phrases can considered to have the
following scope and triggers:
1. the fragment phase: This can be run against individual NETCONF
operations; should be automatically triggered
2. the standard phase: This can be run against the candidate
configuration, but won't always pass; should be manually
triggered
3. the full validation phase: This can be run against a running
configuration; should be automatically triggered
During the Fragment phase validation:
o Verify that the content is appropriate to the operation (by
passing a variable to Schematron with the type of operation)
During Standard phase validation (all rules except for keyref
checking):
o Verify that mustUse items are present
o Check the uniqueness for unique and key annotations
o Print a warning if any manual validation rules are present
During Full phase validation: add keyref checks.
All embedded Schematron will run in the standard phase unless the a
'dml:phase' attribute is included with the name of a different phase
('fragment' or 'full').
6. Validating the data model itself
In addition to validating the instance data, it is necessary to
validate the data model document whenever the data model itself is
modified. In addition to syntax checks, the content of several of
the annotations can be validated. Finally, certain bindings or
usages will need to enforce constraints individual data model.
For example, netconf needs the following restrictions.
Mahy & Chisholm Expires August 21, 2008 [Page 15]
Internet-Draft CANMOD using DSDL February 2008
o Elements with cardinality greater than one (lists), which can have
more than one child element need to have a key defined.
o Mixed content (non-whitespace text nodes interleaved with
elements) is not allowed.
o All schema modules need to have a top-level version number
attribute.
The Schematron file in Appendix B will check these constraints.
7. Documentation annotations
This section describes annotations which do not have have an effect
on validation.
Metadata about the data model document (ex: title, author, dates) is
expressed using a combination of Dublin Core metadata terms, and the
DML schema defined in this document. This proposal recommends that
all data models include a Dublin Core title, creator, description,
and created (creation date) element. Data model authors can include
any additional Dublin Core metadata which is relevant. In addition,
the DML annotation schema adds an 'organization' annotation and a
'contact' annotation. Organization is a human readable string that
indicates the organization responsible for the data model. It
includes an optional language attribute. Contact is a URI that can
be used to reach the author or maintainer of the data model. Using a
mailto: URI is recommended. Finally, the version of the data model
is expressed in a 'dataModelVersion' annotation.
>> dc:title [ "Example schema for DHCP server" ]
>> dml:dataModelVersion ["1.0"]
>> dc:type ["Dataset"]
>> dc:creator [ "Rohan Mahy" ]
>> dml:organization [ "as an individual" ]
>> dml:contact [ "mailto:rohan@example.org" ]
>> dc:created [ "2008-02-13" ]
Default values and semantic descriptions for individual schema items
use the RelaxNG DTD compatibility annotations.
element default-lease-time { xsd:unsignedInt }?
>> compat:defaultValue ["3600"] >> dml:units ["s"]
>> compat:documentation [ xml:lang="en"
"The default duration of a DHCP lease in seconds" ]
The 'units' annotation expresses the unit of measure for an element
with a numeric value. The syntax for this annotation is copied from
the GML (Geographic Markup Language) specification.
Mahy & Chisholm Expires August 21, 2008 [Page 16]
Internet-Draft CANMOD using DSDL February 2008
NOTE: It is recommended that the symbol be an identifier for a
unit of measure as specified in the Unified Code of Units of
Measure (UCUM) [11] (http://aurora.regenstrief.org/UCUM). This
provides a set of symbols and a grammar for constructing
identifiers for units of measure that are unique, and may be
easily entered with a keyboard supporting the limited character
set known as 7-bit ASCII. ISO 2955 formerly provided a
specification with this scope, but was withdrawn in 2001. UCUM
largely follows ISO 2955 with modifications to remove ambiguities
and other problems.
URL for GML specs is: http://www.opengeospatial.org/standards/gml
The compat:documentation annotation can also be used provide general
descriptions of elements, similar to the DESCRIPTION tag in SNMP
MIBs.
Some schemas include container elements which have a semantic meaning
(for example, to enable a specific service) when they are present
even if they are empty. The 'existence' annotation provides a
semantic hint to a processor that such an element cannot be omitted
just because it is empty. This document does not condone or condemn
this practice.
The 'list-order' annotation conveys whether the order of a list is
semantically meaningful as another semantic hint. The value 'any-
order' means that order is not meaningful, while the value 'user-
order' means that the order of the elements in the list are
semantically meaningful. The default semantic in the absence of this
annotation is that order is not semantically meaningful.
The 'status' annotation is used to convey conformance status (active,
deprecated, obsolete) of a particular element. See Section 10 for
more detailed semantics of this annotation.
[EDITOR NOTE: Do we want to include a mustUnderstand annotation?
Sharon: if we add it, it can only be used sparingly, so is of limited
value.]
8. Extensibility Model
All data models defined using this proposal are expected to have a
namespace URI and a top level dml:dataModelVersion attribute which
provides the current version number for that namespace. The
extensibility model is based strongly on backwards compatibility with
the following rules:
Mahy & Chisholm Expires August 21, 2008 [Page 17]
Internet-Draft CANMOD using DSDL February 2008
Elements and attributes are never removed from the schema for a
particular namespace. Content can be deprecated in any version
change. Content which was deprecated in a previous version of the
same schema can be made obsolete when updating the schema to the
next "major version number". If the model developer truly wants
to reuse an element or attribute name which was made obsolete, the
schema can migrate to a new namespace.
It is not possible to add new mandatory content (content with
either a dml:mustUse annotation or content with a cardinality of
at least one) without breaking backwards compatibility. While
this can be a bit limiting when trying to add critical new
features, adding default values to new optional content can get
around many of the limitations.
These limitation are not a result of using Relax NG, but rather based
on operational experience with SNMP, CLI and other management
interfaces. The goal is to provide stability to the NETCONF clients
(operator scripts and management applications) using the NETCONF
content.
The RelaxNG example schema is an extensible closed schema. It was
defined using a relatively flat structure. RelaxNG allows pattern
definitions to be combined (extended) either via interleave or via
adding an additional choice. Many of these definitions need to
include original schema files. In order to allow multiple extensions
to the same schema, an approach like the one used in the full example
can be taken:
start = element-config
element-config = element cfg:config { root-config-contents }
root-config-contents = empty
include "network-types.rnc"
include "interfaces.rnc"
include "dhcp.rnc"
9. Netconf Specifics
While many of the features described above are motivated by Netconf,
they all could be applicable or relevant to other data modeling
applications. The mechanisms described below are specific to
Netconf.
Mahy & Chisholm Expires August 21, 2008 [Page 18]
Internet-Draft CANMOD using DSDL February 2008
9.1. Edit-config operations
[Editor's Note: I would like to thank the Yang draft for serving as
the template for some content in this section.]
The edit-config operation can be performed on content whose
minAccess/maxAccess allows creation, modification and deletion
and which a particular implementation has provided supported for
these operations.
If an element or attribute is creatable (both allowed by the
minAccess/maxAccess clause and supported by the particular
implementation) and this object does not exist, it is created during
a 'merge'. If it is not creatable, the an error is reported.
If the element or attribute is writeable (both allowed by the
minAccess/maxAccess clause and supported by the particular
implementation) and exists, then with a "replace" , all child nodes
not present in the XML that are deletable are deleted, and child
nodes present in the XML but not present in the datastore which
are creatable are created. An attempt to create, modify or delete
elements or child elements when these operations are not supported
will result in an error.
If the operation is "create" the element or attribute is created
if it does not exist, if it creatable, otherwise an error is
reported.
If the element or attribute is deletable (both allowed by the
minAccess/maxAccess clause and supported by the particular
implementation), and the operation is "delete" the node is deleted
if it exists. Otherwise an error is reported
Read-only data should not itself be included in an edit-config
operation, but may be included when an operation is performed on
a containing element with sufficient privileges. These elements get
created when their containing element is created and deleted when
their containing element is deleted.
9.2. Get and Get-config operations
The get operation retrieves all data of any infoType. The
get-config operation only retreives data with an infoType of
'config'.
Mahy & Chisholm Expires August 21, 2008 [Page 19]
Internet-Draft CANMOD using DSDL February 2008
9.3. Netconf notifications
Below
namespace rng = "http://relaxng.org/ns/structure/1.0"
namespace xsd = "http://www/w3/org/2001/XMLSchema-datatypes"
namespace xml = "http://www.w3.org/XML/1998/namespace"
namespace sch = "http://www.ascc.net/xml/schematron"
namespace dc = "http://purl.org/dc/terms"
namespace dml = "http://example.org/ns/dml"
namespace compat ="http://relaxng.org/ns/compatibility/annotations/1.0"
namespace notif = "urn:ietf:params:xml:ns:netconf:notification:rng:1.0"
namespace ns1 = "notif"
default namespace = "http://www.example.com/dhcp"
compat:documentation [
"This schema demonstrates defining two Netconf notifications." ~
"The contents of the first notification is defined using" ~
"entirely new content. The second notification reuses content" ~
"defined for use in Netconf get operations."
]
include "notifications.rnc" inherit = ns1
notificationContent |=
[
compat:documentation [
"This notification is sent out when an IP address" ~
"conflict is detected. The DHCP client discovers" ~
"its assigned address is already in use."
]
]
element dhcpAddressConflictNotification {
element ip-address { ipv4-address-content },
element rogue-mac-address { mac-address-content }
>> compat:documentation ["The conflicting MAC address"],
element leased-mac-address { mac-address-content }
>> compat:documentation ["The MAC address of the DHCP client"]
}
>> dml:info-type ["notify"]
notificationContent |=
[
compat:documentation [
"This notification is sent out when the dynamic" ~
"IP address range for a subnet is nearly full."
]
]
element dhcpScopeNearlyFullNotification {
Mahy & Chisholm Expires August 21, 2008 [Page 20]
Internet-Draft CANMOD using DSDL February 2008
(
element addresses-used { xsd:integer },
element addresses-avail { xsd:integer },
element-subnet
)+
}
>> dml:info-type ["notify"]
start |= notificationType
9.4. New netconf actions
Below is an example specification of a new Netconf action.
namespace rng = "http://relaxng.org/ns/structure/1.0"
namespace xsd = "http://www/w3/org/2001/XMLSchema-datatypes"
namespace xml = "http://www.w3.org/XML/1998/namespace"
namespace sch = "http://www.ascc.net/xml/schematron"
namespace dc = "http://purl.org/dc/terms"
namespace dml = "http://example.org/ns/dml"
namespace compat ="http://relaxng.org/ns/compatibility/annotations/1.0"
namespace netconf = "urn:ietf:params:xml:ns:netconf:base:1.0"
namespace ns1 = "netconf"
default namespace = "http://www.example.com/dhcp"
compat:documentation [
"This schema defines the dhcp revoke lease rpc action"
]
include "netconf.rnc" inherit = ns1
revokeLeaseType = element revoke-lease {
element address { ipv4-address-content }+
} >> dml:info-type ["action"]
rpcType |= revokeLeaseType
start |= rpcType
9.5. Netconf specific error messages
Custom Netconf error messages are available as error annotation
attributes for Schematron. Schematron allows attributes from other
namespaces in all its elements. The 'dml:netconf-error-app-tag'
attribute can be used to provide a error-app-tag value specific to
the data model. In addition, the error text can be localized in
Schematron using the 'diagnostics' element.
Mahy & Chisholm Expires August 21, 2008 [Page 21]
Internet-Draft CANMOD using DSDL February 2008
The contents of "$keyref-context" must be a
with the key "$key" in this context: $key-context.
The contents of "$keyref-context" must be a 'keyref'
with the key "$key" in this context: $key-context.
Les contenus de $keyref-context droite etre un 'keyref'
avec le cle "$key" dans cette contexte: $key-context
This would generate the following RPC error during an edit-config
with full validation enabled:
Mahy & Chisholm Expires August 21, 2008 [Page 22]
Internet-Draft CANMOD using DSDL February 2008
application
invalid-value
error
keyref-failure
//dhcp:subnet[@key="192.168.16.0/24]
/dhcp:interface-filter[interface='en4']
The contents of "//dhcp:interface-filter" must be a 'keyref'
with the key "//int:ifIndex" in this context: int:interface.
Les contenus de "//dhcp:interface-filter" droite etre un 'keyref'
avec le cle "//int:ifIndex" dans cette contexte: int:interface
10. Conformance
When defining NETCONF content, it is also necessary to define
machine-readable conformance for that content. The conformance
method described provides a means of providing information about
individual elements which is then used to calculate the schema
conformance. There is no separate definition of schema conformance.
Previous solutions with separate conformance sections were found to
have issues, particularly in keeping them up to date as the schema
evolved. They also were not always used outside of standards
activities where people did not either fully understand them or see
the value in them.
Conformance specifies not only whether to object must be supported,
but also the level of access, read versus write for example that is
minimally required.
10.1. Cardinality
When defining attributes and elements in the XML syntax, the
'optional', 'oneOrMore' or 'zeroOrMore' tags are used to specify the
cardinality of the element. In the compact syntax, "?" means
optional, "+" means one or more, "*" means zero or more. When no
cardinality indicator is present, this is interpreted to mean exactly
once.
Mahy & Chisholm Expires August 21, 2008 [Page 23]
Internet-Draft CANMOD using DSDL February 2008
10.2. Operations on managed objects
Operations that can be performed on managed objects fall into one of
the following equivalence classes: "Create", "Delete", "Read",
"Write", and "Execute". A value of "create" means it is possible to
create new instances of this element using commands like the NETCONF
'edit-config' or copy- config' commands. A value of "delete" means
it is possible to destroy instances of this element using commands
like the NETCONF 'edit-config', 'copy-config' or 'delete-config'
operations. A value of "read" means that it is possible to view
values of this element using commands like the 'get-config', 'get' or
'notification' operations. A value of "write" means it is possible
to modify an instance of this element using commands like the NETCONF
'edit-config' or 'copy- config' commands. A value of "execute" means
that there is a side effect execution such as rebooting that is
permissible as a result of the command. For example, commands like
the NETCONF 'edit-config' or a 'copy-config' command or the ability
to execute a commands like the 'lock', 'unlock'> or 'kill-session'
command. This document introduces new process annotations of
"minAccess" and "maxAccess", which contain a non-empty list of
values. The "minAccess" element defines the set of operations that
must be supported in order to claim compliance to this schema. The
"maxAccess" element contains the full set of operations that make
operational sense for this object. If not present, it assumes the
same value as the minAccess tag. For example, a status object might
have a "minAccess" of read but a "maxAccess" of read and write to
indicate that it must be possible to perform a get operation the
status, but implementations could also allow configuration operations
on it as well. In the case of a statistic, both the "minAccess" and
"maxAccess" might have values of read.
In XML syntax, an example would be
In compact syntax, an example would be
>> dml:minAccess [ dml:read[] ]
>> dml:maxAccess [ dml:read[] dml:write[] ]
10.3. Element and Attribute Status
As a schema evolves, certain elements and attributes may no longer be
relevant. Simply deleting these from the schema may be acceptable
for elements that did not see implementation, but others will require
a strategy to allow implementers to migrate away from the old
elements. An optional processing annotation called "status" SHOULD
be used to provide the status of the element. When not present, it
will assume a value of "current". The other value of this object are
Mahy & Chisholm Expires August 21, 2008 [Page 24]
Internet-Draft CANMOD using DSDL February 2008
"deprecated" and "obsolete". A value of "deprecated" indicates that
implementations should consider migrating away from this object and
that its implementation is no longer required to be considered
conformant. A value of "obsolete" means the object should not be
implemented. Deprecated and obsolete content is never removed from
the document and its element name can never be re-used.
In XML syntax
current
In compact syntax
>> dml:status [ "current" ]
10.4. Additional Conformance Information
Additional information about conformance should be specified using a
documentation tag.
Examples of additional conformance information that may be useful to
provide includes how implementations can specify specific exceptions
to required conformance, dependencies between elements (in order to
do A, you need to first do B) and conditional conformance (if BGP,
then ...).
10.5. Schema Level Conformance - Server-side
In order to claim compliance to a schema, all elements and attributes
need to conform to their given cardinality definitions and all
elements and attributes with a status of "current" and with a
cardinality greater than or equal to one need to be supported. In
addition, all of the operations listed by the minAccess attribute
need to be supported.
10.6. Schema Level Conformance - Client-side
Client-side conformance is a method of indicating whether presence of
an object is required in order to be a valid configuration. A new
processing annotation is added called mustUse to support this. When
present, this object is required in a valid configuration and when
not present, it is optional in a valid configuration. Note that
optional objects may have default values to enable them to have
values in the configuration without being explicitly set by the
client.
In XML syntax
In compact syntax
Mahy & Chisholm Expires August 21, 2008 [Page 25]
Internet-Draft CANMOD using DSDL February 2008
>> dml:mustUse []
11. Grading against the requirements
The following outlines how the RCDML requirements [12] (version -03)
are met by this solution or when applicably, why it was felt
requirements should not be met.
3.1. Consequences of NETCONF
3.1.1. Notification Definition (Agreed)
Met/Not Met: Met
Section: Section 9
Comments:
3.1.2. Notification Get (NOT Agreed)
Met/Not Met: Met
Section: Section 9
Comments:
3.1.3. Locking (Agreed)
Met/Not Met: Met
Section:
Comments:
3.1.4. All Base Operations (Agreed)
Met/Not Met: Met
Section: Section 9
Comments:
3.1.5. Define new NETCONF Operations (Agreed)
Met/Not Met: Met
Section: Section 9
Comments:
3.1.6. Separation of Operations and Payload (Agreed)
Met/Not Met: Met
Section:
Comments:
3.1.7. Error Annotation (Agreed)
Met/Not Met: Met
Section: Section 9
Comments:
3.1.8. No Mixed Content (Agreed)
Met/Not Met: Met
Section:
Comments:
3.2. Model Representation Requirements
3.2.1. Human Readable (Agreed)
Met/Not Met: Met
Mahy & Chisholm Expires August 21, 2008 [Page 26]
Internet-Draft CANMOD using DSDL February 2008
Section:
Comments:
3.2.2. Machine Readable (Agreed)
Met/Not Met: Met
Section:
Comments:
3.2.3. Textual Representation (Agreed)
Met/Not Met: Met
Section:
Comments:
3.2.4. Document Information (Agreed)
Met/Not Met: Met
Section: Section 7
Comments:
3.2.5. Ownership and Change Control (Agreed)
Met/Not Met: Met
Section:
Comments:
3.2.6. Dependency Risk Reduction (Agreed)
Met/Not Met: Met
Section:
Comments:
3.2.7. Diff-Friendly (Agreed)
Met/Not Met: Met
Section:
Comments:
3.2.8. Internationalization and Localization
3.2.8.1. Descriptions using Local Languages (Agreed)
Met/Not Met: Met
Section:
Comments:
3.2.8.2. UTF-8 Encoding (Agreed)
Met/Not Met: Met
Section:
Comments:
3.2.8.3. Localization Support (Agreed)
Met/Not Met: Met
Section:
Comments:
3.2.8.4. Error String Localization (Agreed)
Met/Not Met: Met
Section:
Comments:
3.2.8.5. Tag Names and Strings in Local Languages (NOT
agreed)
Mahy & Chisholm Expires August 21, 2008 [Page 27]
Internet-Draft CANMOD using DSDL February 2008
Met/Not Met: Met
Section:
Comments:
Met/Not Met:
Section:
Comments:
3.3. Reusability Requirements
3.3.1. Modularity (Agreed)
Met/Not Met: Met
Section:
Comments:
3.3.2. Reusable Definitions (Agreed)
Met/Not Met: Met
Section:
Comments:
3.3.3. Modular extension (Agreed)
Met/Not Met: Met
Section: Section 8
Comments:
3.4. Instance Data Requirements
3.4.1. Default Values on the Wire (Agreed)
Met/Not Met: Met
Section: Section 7
Comments:
3.4.2. Ordering
3.4.2.1. Ordered Lists (Agreed)
Met/Not Met: Met
Section:
Comments:
3.4.2.2. Order within Containers (NOT Agreed)
Met/Not Met: Met
Section:
Comments:
3.4.2.3. Interleaving (NOT Agreed)
Met/Not Met: Met
Section:
Comments:
3.4.3. Validation
3.4.3.1. Validate Instance Data (Agreed)
Met/Not Met: Met
Section:
Comments:
3.4.3.2. Tools to Validate Instance Data (NOT Agreed)
Met/Not Met: Met
Mahy & Chisholm Expires August 21, 2008 [Page 28]
Internet-Draft CANMOD using DSDL February 2008
Section:
Comments:
3.4.4. Instance Canonicalization (Agreed)
Met/Not Met: Met
Section:
Comments:
3.4.5. Character Set and Encoding (Agreed)
Met/Not Met: Met
Section:
Comments:
3.4.6. Model Instance Localization (NOT Agreed)
Met/Not Met: Met
Section:
Comments:
3.5. Semantic Richness Requirements
3.5.1. Human-Readable Semantics (Agreed)
Met/Not Met: Met
Section:
Comments:
3.5.2. Basic Types (Agreed)
Met/Not Met: Met
Section:
Comments:
3.5.3. Handling Opaque Data (Agreed)
Met/Not Met: Met
Section:
Comments:
3.5.4. Keys
3.5.4.1. Define Keys (Agreed)
Met/Not Met: Met
Section:
3.5.4.2. Deep Keys (NOT Agreed)
Met/Not Met: Met
Section:
3.5.5. Relationships
3.5.5.1. Simple Relationships (Agreed)
Met/Not Met: Met
Section:
3.5.5.2. Many-to-Many Relationships (NOT Agreed)
Met/Not Met: Not Met
Section:
3.5.5.3. Retrieve Relationships instance (NOT Agreed)
Met/Not Met: ?
Section:
Mahy & Chisholm Expires August 21, 2008 [Page 29]
Internet-Draft CANMOD using DSDL February 2008
3.5.6. Hierarchical Data
Met/Not Met: Met
Section:
Comments:
3.5.7. Referential Integrity
3.5.7.1. Referential Integrity (NOT Agreed)
Met/Not Met: Met
Section:
Comments:
3.5.7.2. Extended Referential Integrity (NOT Agreed)
Met/Not Met: Met
Section:
Comments:
3.5.8. Characterize Data (Agreed)
Met/Not Met: Met
Section:
Comments:
3.5.9. Defaults
3.5.9.1. Default Values (NOT Agreed)
Met/Not Met: Met
Section: Section 7
Comments:
3.5.10. Formal Constraints
3.5.10.1. Formal Description of Constraints (Agreed)
Met/Not Met: Met
Section:
Comments:
3.5.10.2. Multi-element Constraints (NOT Agreed)
Met/Not Met: Met
Section:
Comments:
3.5.10.3. Non-Key Uniqueness (Agreed)
Met/Not Met: Met
Section:
Comments:
3.5.11. Units (Agreed)
Met/Not Met: Met
Section:
Comments:
3.5.12. Define Actions (NOT Agreed)
Met/Not Met: Met
Section:
Comments:
3.6. Extensibility Requirements
Mahy & Chisholm Expires August 21, 2008 [Page 30]
Internet-Draft CANMOD using DSDL February 2008
3.6.1. Language Extensibility
3.6.1.1. Language Versioning (Agreed)
Met/Not Met: Met
Section:
Comments:
3.6.1.2. User Extensions (NOT Agreed)
Met/Not Met: Met
Section:
Comments:
3.6.1.3. Mandatory Extensions (NOT Agreed)
Met/Not Met: Met
Section:
Comments:
3.6.2. Model Extensibility
3.6.2.1. Model Version Identification (Agreed)
Met/Not Met: Met
Section:
Comments:
3.6.2.2. Interaction with defaults (NOT Agreed)
Met/Not Met: Met
Section:
Comments:
3.6.2.3. Conformance Interference (NOT Agreed)
Met/Not Met: Met
Section:
Comments:
3.6.2.4. Obsolete Portions of a Model (Agreed)
Met/Not Met: Met
Section:
Comments:
3.6.3. Instance Data Extensibility
3.6.3.1. Schema Version of Instance (NOT Agreed)
Met/Not Met: Met
Section:
Comments:
3.6.3.2. Interaction with default Values (NOT Agreed)
Met/Not Met: Met
Section:
Comments:
3.6.3.3. Backwards Compatibility (Agreed)
Met/Not Met: Met
Section:
Comments:
3.6.3.4. Forwards Compatibility (NOT Agreed)
Mahy & Chisholm Expires August 21, 2008 [Page 31]
Internet-Draft CANMOD using DSDL February 2008
Met/Not Met: Met
Section:
Comments:
3.6.3.5. Must-Understand Model Extensions (NOT Agreed)
Met/Not Met: Met
Section:
Comments:
3.7. Talking About Conformance
3.7.1. Conformance to the Modeling Language (NOT Agreed)
Met/Not Met: Met
Section:
Comments:
3.7.2. Conformance to a Model (Agreed)
3.7.2.1. Conditional Conformance (NOT Agreed)
Met/Not Met: Met
Section:
Comments:
3.7.2.2. Server Conformance to Schema (Agreed)
Met/Not Met: Met
Section:
Comments:
3.7.2.3. Client Conformance To Schema (NOT Agreed)
Met/Not Met: Met
Section:
Comments:
3.7.2.4. Versioned Conformance (NOT Agreed)
Met/Not Met: Met
Section:
Comments:
3.8. Techno-Political Constraints
3.8.1. Standard Technology (NOT Agreed)
Met/Not Met: Met
Section:
Comments:
3.8.2. Translate Models to Other Forms (Agreed)
Met/Not Met: Met
Section:
Comments:
3.8.3. Minimize SMI Translation Pain (NOT Agreed)
Met/Not Met: Met?
Section:
Comments:
3.8.4. Generate Models from Other Forms (NOT Agreed)
Met/Not Met:
Mahy & Chisholm Expires August 21, 2008 [Page 32]
Internet-Draft CANMOD using DSDL February 2008
Section:
Comments:
3.8.5. Isolate Models from Protocol (NOT Agreed)
Met/Not Met: Met
Section:
Comments:
3.8.6. Library Support (NOT Agreed)
Met/Not Met: Met
Section:
Comments:
3.8.7. RFC 3139 Considerations
Met/Not Met: ?
Section:
Comments:
3.8.8. RFC 3216 Considerations
Met/Not Met: ?
Section:
Comments:
12. Full Examples
The example below
In order to fit within 72 characters in width, the pattern
restriction on 'ip-address-content' had to be split across two lines.
This is indicated by the '~' operator in the example. This operator
is equivalent to concatening the two lines into a single quoted
string literal.
# config-root.rnc
namespace rng = "http://relaxng.org/ns/structure/1.0"
namespace xsd = "http://www/w3/org/2001/XMLSchema-datatypes"
namespace xml = "http://www.w3.org/XML/1998/namespace"
namespace sch = "http://www.ascc.net/xml/schematron"
namespace dc = "http://purl.org/dc/terms"
namespace dml = "http://example.org/ns/dml"
namespace compat ="http://relaxng.org/ns/compatibility/annotations/1.0"
namespace cfg = "http://example.org/ns/cfg"
start = element-config
element-config = element cfg:config { root-config-contents }
root-config-contents = empty
include "network-types.rnc"
include "interfaces.rnc"
include "dhcp.rnc"
Mahy & Chisholm Expires August 21, 2008 [Page 33]
Internet-Draft CANMOD using DSDL February 2008
# interfaces.rnc
namespace rng = "http://relaxng.org/ns/structure/1.0"
namespace xsd = "http://www/w3/org/2001/XMLSchema-datatypes"
namespace xml = "http://www.w3.org/XML/1998/namespace"
namespace sch = "http://www.ascc.net/xml/schematron"
namespace dc = "http://purl.org/dc/terms"
namespace dml = "http://example.org/ns/dml"
namespace compat ="http://relaxng.org/ns/compatibility/annotations/1.0"
namespace int = "http://example.org/ns/int"
default namespace = "http://example.org/ns/int"
root-config-contents &= element-interfaces
element-interfaces = element interfaces {
element interface {
element ifIndex { xsd:token },
element ifType { xsd:token }
}+ >> dml:key [ "ifIndex"]
}
>> dc:title [ "Example Interfaces schema fragment" ]
# dhcp.rnc
namespace rng = "http://relaxng.org/ns/structure/1.0"
namespace xsd = "http://www/w3/org/2001/XMLSchema-datatypes"
namespace xml = "http://www.w3.org/XML/1998/namespace"
namespace sch = "http://www.ascc.net/xml/schematron"
namespace dc = "http://purl.org/dc/terms"
namespace dml = "http://example.org/ns/dml"
namespace dhcp = "http://example.org/ns/dhcp"
namespace tz = "http://example.org/ns/dhcp/timezone"
namespace int = "http://example.org/ns/int"
namespace compat ="http://relaxng.org/ns/compatibility/annotations/1.0"
default namespace = "http://example.org/ns/dhcp"
root-config-contents &= element-dhcp
element-dhcp = element dhcp {
global-timer-elements,
subnet-elements,
element-shared-network* >> dml:key ["@name"]
}
>> dc:title [ "Example schema for DHCP server" ]
>> dml:dataModelVersion ["1.0"]
>> dc:type ["Dataset"]
>> dc:creator [ "Rohan Mahy" ]
>> dml:organization [ "as an individual" ]
>> dml:contact [ "mailto:rohan@example.org" ]
Mahy & Chisholm Expires August 21, 2008 [Page 34]
Internet-Draft CANMOD using DSDL February 2008
>> dc:created [ "2008-02-13" ]
global-timer-elements = (
[
sch:pattern [
sch:rule [
context = "//dhcp:dhcp"
sch:assert [
test = "dhcp:default-lease-time <= dhcp:max-lease-time"
"Default lease time cannot be larger than maximum lease time"
]
]
]
]
element default-lease-time { xsd:unsignedInt }?
>> compat:defaultValue ["3600"] >> dml:units ["s"],
element max-lease-time { xsd:unsignedInt }?
>> dml:units ["s"]
)
element-shared-network = element shared-network {
attribute name { token },
subnet-elements
}
subnet-elements = element-subnet*
>> dml:key ["concat(network, '/', prefix-length)"]
>> dml:manual-validation-rule [
"Verify that none of the subnets overlap with other subnets." ]
element-subnet = element subnet {
element-network,
element-prefix-length,
element-range?
>> dml:existence []
>> dml:manual-validation-rule [
"Verify the range is within the subnet."
],
element-dhcp-options?,
element max-lease-time { xsd:unsignedInt }?
>> dml:units ["s"] >> dml:status ["deprecated"],
element leases {
element-lease* >> sch:key ["@ip-address"]
}? >> dml:info-type ["status"],
element-interface-filter?
}
Mahy & Chisholm Expires August 21, 2008 [Page 35]
Internet-Draft CANMOD using DSDL February 2008
element-network = element network {
ipv4-address-content
}
element-prefix-length = element prefix-length {
xsd:short { minInclusive = "0" maxInclusive = "32" }
}
element-range = element range {
element low { ipv4-address-content }?,
element high { ipv4-address-content }?
}
element-dhcp-options = element dhcp-options {
element-router-list-option? &
element-domain-list-option? &
element-custom-option* >> dml:key ["@option"]
}
element-dhcp-option &= element tz:timezone { token }?
# this is an example of simple inline extensibility
element-lease = element lease {
attribute ip-address { ipv4-address-content },
element starts { xsd:dateTime },
element ends { xsd:dateTime },
element mac-address { mac-address-content }
}
element-router-list-option = element router-list {
element router { ipv4-address-content }+
>> dml:order ["user-order"]
}
element-domain-list-option = element domain-list {
element domain { token }+
}
element-custom-option = element custom {
attribute option { xsd:unsignedByte },
(
element ip-address { ipv4-address-content }
| element string { string }
)
}
element-interface-filter = element interface-filter {
element interface { token }+ >> dml:keyref ["//int:interface"]
}
Mahy & Chisholm Expires August 21, 2008 [Page 36]
Internet-Draft CANMOD using DSDL February 2008
#network-types.rnc
namespace rng = "http://relaxng.org/ns/structure/1.0"
namespace xsd = "http://www/w3/org/2001/XMLSchema-datatypes"
namespace xml = "http://www.w3.org/XML/1998/namespace"
namespace sch = "http://www.ascc.net/xml/schematron"
namespace dc = "http://purl.org/dc/terms"
namespace dml = "http://example.org/ns/dml"
namespace compat ="http://relaxng.org/ns/compatibility/annotations/1.0"
ipv4-address-content = xsd:token { pattern =
"((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}" ~
"(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])"
}
mac-address-content = xsd:token { pattern =
"(([0-9a-fA-F]{2}):?){5}[0-9a-fA-F]{2}" }
13. "DML" Annotations Schema
here:
namespace rng = "http://relaxng.org/ns/structure/1.0"
datatypes xsd = "http://www.w3.org/2001/XMLSchema-datatypes"
namespace xml = "http://www.w3.org/XML/1998/namespace"
namespace compat = "http://relaxng.org/ns/compatibility/annotations/1.0"
default namespace = "http://example.org/ns/dml"
#start = element-dml
element-dml = element dml {
attribute dmlVersion { "1.0" }? &
dml-contents
}
dml-contents = (
dataModelVersion &
organization* &
contact-info* &
list-order* &
data-category* &
mustUse-flag* &
container-existence* &
manual-validation* &
units* &
mustUnderstand*
)
Mahy & Chisholm Expires August 21, 2008 [Page 37]
Internet-Draft CANMOD using DSDL February 2008
# Each data model needs a version string
dataModelVersion = element dataModelVersion { xsd:string }
# Information about the data model author(s).
# Seems like this should be in Dublin Core
organization = element organization { string-with-lang }
contact-info = element contact { xsd:anyURI }
# Processing annotations
unique = element unique { xsd:anyURI }
key = element key { xsd:anyURI }
keyref = element keyref { xsd:anyURI }
data-category = element info-type {
attribute minAccess { xsd:string }?,
attribute maxAccess { xsd:string }?,
("config" | "status" | "statistics" | "action" | "notify")
} >> compat:defaultValue ["config"]
mustUse-flag = element mustUse { xsd:boolean }
>> compat:defaultValue ["false"]
manual-validation = element manual-validation-rule { string-with-lang }
# Semantic hints
list-order = element order { "any-order" | "user-order" }
>> compat:defaultValue ["any-order"]
container-existence = element existence { empty }
units = element units {
xsd:string { pattern="[^: \n\r\t]+" }
# allow familiar units, but no whitespace or absolute URIs here
|
xsd:anyURI { pattern="([a-zA-Z][a-zA-Z0-9\-\+\.]*:|\.\./|\./|#).*" }
# allow absolute URIs, plus relative URIs with ./ or ../
# prohibit relative URIs that could look like a unit, ex: m/s
}
# Definition copied from definition of gml:Uomidentifier from
# Section 8.2.3.6 of Geography Markup Language (GML) v3.2.1
string-with-lang = (
attribute xml:lang { xsd:language },
xsd:string
)
# the mustUnderstand element contains a namespace token
# that needs to be supported to correctly process the data model
Mahy & Chisholm Expires August 21, 2008 [Page 38]
Internet-Draft CANMOD using DSDL February 2008
mustUnderstand = element mustUnderstand { xsd:NCName }
14. Security Considerations
TBD
15. IANA Consideration
This document merely evaluates a possible technical approach. It
requires no action by IANA. A specification that uses this approach
would need to register a namespace with IANA.
16. Contributors
Ladislav Lhotka and Randy Presuhn contributed to the development of
this proposal. Sharon was responsible for text on Conformance,
Defaults, and Netconf notifications. She was invaluable for those
"why does Netconf do it that way" questions. Randy provided useful
advice on the extensibility model. Some of the constructs in the
RelaxNG schema were adapted from similar constructs in Ladislav's
FlowMon schema.
Thanks to Alan Hawrylyshen for an early read.
URIs
[22]
[23]
[24]
[25]
Appendix A. XSLT Transform from processing annotation to Schematron
Here it is:
This space intentionally left blank.
Notes on how the XSLT works. Generating rules for uniqueness
Generating rules for key verification Generating rules Deleting
elements or attributes which are marked obsolete
Mahy & Chisholm Expires August 21, 2008 [Page 39]
Internet-Draft CANMOD using DSDL February 2008
Appendix B. Schematron for validating data model documents
Here it is:
17. References
17.1. Normative References
[1] Enns, R., "NETCONF Configuration Protocol", RFC 4741,
December 2006.
[2] Kunze, J. and T. Baker, "The Dublin Core Metadata Element Set",
RFC 5013, August 2007.
[3] Chisholm, S. and H. Trevino, "NETCONF Event Notifications",
draft-ietf-netconf-notification-11 (work in progress),
November 2007.
[4] Maler, E., Paoli, J., Yergeau, F., Sperberg-McQueen, C., and T.
Bray, "Extensible Markup Language (XML) 1.0 (Fourth Edition)",
World Wide Web Consortium Recommendation REC-xml-20060816,
August 2006, .
[5] Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes Second
Edition", World Wide Web Consortium Recommendation REC-
xmlschema-2-20041028, October 2004,
.
[6] Layman, A., Hollander, D., Tobin, R., and T. Bray, "Namespaces
in XML 1.0 (Second Edition)", World Wide Web Consortium
Recommendation REC-xml-names-20060816, August 2006,
.
[7] ISO, "Document Schema Definition Languages (DSDL) -- Part 3:
Rule-based validation -- Schematron", June 2006.
[8] ISO, "Document Schema Definition Languages (DSDL): Part 2:
Regular Grammer-based Validation - Relax NG", Decemeber 2002.
[9] Clark, J. and S. DeRose, "XML Path Language (XPath) 2.0",
January 2007, .
[10] Clark, J., "XSL Transformations (XSLT)", November 1999.
[11] Schadow, G. and C. McDonald, "The Unified Code for Units of
Mahy & Chisholm Expires August 21, 2008 [Page 40]
Internet-Draft CANMOD using DSDL February 2008
Measure", November 2005.
17.2. Informational References
[12] Presuhn, R., "Requirements for a Configuration Data Modeling
Language", draft-presuhn-rcdml-03 (work in progress),
February 2008.
[13] Case, J., Fedor, M., Schoffstall, M., and J. Davin, "Simple
Network Management Protocol (SNMP)", STD 15, RFC 1157,
May 1990.
[14] McCloghrie, K., Ed., Perkins, D., Ed., and J. Schoenwaelder,
Ed., "Structure of Management Information Version 2 (SMIv2)",
STD 58, RFC 2578, April 1999.
[15] Van der Vlist, E., "Relax NG", 2004.
[16] Cox, S., Daisey, P., Lake, R., Portele, P., and A. Whiteside,
"OpenGIS Geography Markup Language (GML Implementation
Specification", February 2007.
[17] Schnitzenbaumer, S., Boumphrey, F., Wugofski, T., Altheim, M.,
McCarron, S., and S. Dooley, "XHTML Modularization 1.1", World
Wide Web Consortium LastCall WD-xhtml-modularization-20060705,
July 2006,
.
[18] Jackson, D., Ferraiolo, J., and J. Fujisawa, "Scalable Vector
Graphics (SVG) 1.1 Specification", W3C CR CR-SVG11-20020430,
April 2002.
[19] Solo, D., Reagle, J., and D. Eastlake, "XML-Signature Syntax
and Processing", World Wide Web Consortium Recommendation REC-
xmldsig-core-20020212, February 2002,
.
[20] Klyne, G. and J. Carroll, "Resource Description Framework
(RDF): Concepts and Abstract Syntax", World Wide Web Consortium
Recommendation REC-rdf-concepts-20040210, February 2004,
.
[21] Maloney, M., Thompson, H., Mendelsohn, N., and D. Beech, "XML
Schema Part 1: Structures Second Edition", World Wide Web
Consortium Recommendation REC-xmlschema-1-20041028,
October 2004,
.
Mahy & Chisholm Expires August 21, 2008 [Page 41]
Internet-Draft CANMOD using DSDL February 2008
Authors' Addresses
Rohan Mahy
Plantronics
Email: rohan@ekabal.com
Sharon Chisholm
Nortel Networks
Email: schishol@nortel.com
Mahy & Chisholm Expires August 21, 2008 [Page 42]
Internet-Draft CANMOD using DSDL February 2008
Full Copyright Statement
Copyright (C) The IETF Trust (2008).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Acknowledgment
Funding for the RFC Editor function is provided by the IETF
Administrative Support Activity (IASA).
Mahy & Chisholm Expires August 21, 2008 [Page 43]