Modular RELAX NG Schema of
NETCONF RPC and Protocol OperationsCESNETZikova 4Praha 6160 00CZlhotka@cesnet.cz
Operations and Management
NETCONFNETCONFRELAX NGXML schemaThis memo presents a schema for NETCONF RPC and protocol
operations expressed in RELAX NG (compact syntax). The schema is
modular and cleanly separates the server and client part of the
NETCONF vocabulary and also the schema extensions provided by
optional capabilities. The modular structure improves readability
but also enables selecting certain modules and assembling them into
a grammar that can be used for validation of NETCONF protocol data
units.Specification of the NETCONF protocol
contains in its Appendix B a formal definition of the vocabulary
of RPC and protocol operations expressed using the W3C XML Schema
language (, -
henceforth referred to as "XSD").However, the NETCONF protocol vocabulary actually consists of
two distinct parts - one for the NETCONF client and the other for
the NETCONF server - that can never appear together in the same
NETCONF PDU. The overlap of these two parts is small and even if
the same element, such as <hello>, is allowed in both, the
content model of each version may differ. Moreover, the PDU
contents in every particular case depend on the capabilities
supported by the server and negotiated in the <hello>
messages. The all-encompassing approach of the NETCONF XSD schema
cannot take these differences into account and the grammar is thus
in many places too liberal. As a result, the XSD schema can hardly
be used for serious validation of NETCONF PDUs.This report introduces a new modular schema for the same
NETCONF protocol vocabulary expressed in RELAX NG , a simple but powerful schema language that became
Part 2 of the international standard ISO/IEC 19757 . RELAX NG has two official syntaxes, XML and
compact, the latter, being designed primarily for human readers
without special training, is considerably more suitable for
inclusion in standardization documents such as RFCs than XML-based
syntaxes.The goal of this work is twofold:
Demonstrate that RELAX NG is a sound alternative to XSD for
the given purpose in that it is able to express the same (or
even more detailed) grammar and data-typing rules as the
existing NETCONF XSD schema and do it in a way that is
considerably more human-readable.Use the extensibility framework of RELAX NG for dividing the
schema into smaller modules according to the logic of the
NETCONF protocol. Such a decomposition will not only further aid
readability and make the parts of the schema easier to maintain,
but also allow for using the modules directly for NETCONF PDU
validation.The report is organized as follows: In the we summarize the problems of the NETCONF XSD
schema, describes the structure and main
design features of the modular RELAX NG schema, shows how to use the modules for effective
validation of NETCONF PDUs in specific contexts and finally concludes the reports. contains full listing of the RELAX NG
modules in the compact syntax.The NETCONF XSD schema in Appendix B of can serve well as a set of formalized
guidelines for implementers of the NETCONF protocol, especially
the RPC layer. However, this schema is much less useful for the
second major purpose of XML schemas, namely for validating
documents, in our case NETCONF PDUs. The reason for this
deficiency is that many of the constraints in the schema are
rather lax or even logically inconsistent. The latter problem is
manifested, for example, in the <session-id> parameter of
the <hello> element: the schema declares it as optional
(minOccurs="0") but, in fact, this content model is appropriate
neither for server's nor for client's version of <hello> -
it is mandatory in the former but not allowed at all in the
latter.Similarly, the borderline case of a <rpc-reply> to an
invalid <rpc> lacking the "message-id" parameter led the
schema designers to declaring this parameter as optional. As an
unfortunate result, any <rpc-reply> with "message-id"
missing will be found valid.Strict validation of NETCONF PDUs in a particular context must
also take into account the set of capabilities supported by the
concrete server. The XSD schema is not designed to allow such
specialization.Finally, Appendix A of defines the
standard NETCONF errors and specifies constraints on their
contents. For example, some combinations or "error-tag" and
"error-type" parameters are not permitted, some errors have
prescribed content of "error-info" while others cannot have this
parameter, and all these standard errors have severity
"error". Again, the XSD schema doesn't take these constraints into
account and allows all possible combinations of error
parameters.Modular RELAX NG schema is designed for much stricter
validation of NETCONF PDUs than the XSD schema. This is achieved by
utilizing auxiliary information that is typically available, such
as the originator of the PDU - server or client - and list of
capabilities supported by the server.The RELAX NG schema is divided into 11 modules, each of them
stored in a separate file:
nc-base-commonnc-base-clientnc-base-servernc-writable-running-clientnc-candidate-clientnc-confirmed-commit-clientnc-rollback-on-error-clientnc-validate-clientnc-startup-clientnc-url-clientnc-xpath-clientThe file names are composed of the module name and the
appropriate extension - either ".rng" or ".rnc", depending on
whether the file contains RELAX NG in the XML or compact syntax.The main division line in the schema goes between the client
and server part. Hence, modules "nc-base-client" and
"nc-base-server" contain the client and server vocabulary,
respectively. However, this is only the bare-bones NETCONF,
without any optional capabilities. Few parameters and RELAX NG
patterns are common to both the client and server schemas and
these are contained in the "nc-base-common" module.Further, extensions to the schema provided by optional
capabilities are defined in separate modules. In general, there
would be two modules per capability - one with the server and the
other with the client extensions. However, all the standard
extensions defined in only affect the
client vocabulary, so the server module is not
needed. Nevertheless, other capabilities may extend or change the
server vocabulary, too, for example by introducing new error
types.The schema modules are designed for maximum
extensibility. Therefore, their RELAX NG patterns mainly use the
"content-oriented" style that allows new content to be easily
added without redefining entire patterns. Due to this design, the
capability modules can be generally very short and easy to
understand. However, taking the content-oriented design to the
extreme would make the schemas unwieldy, so we use it only in
places where extensions are likely.Two of the RELAX NG modules - "nc-base-client" and
"nc-base-server" - are full-fledged grammars that can be readily
used for validating NETCONF PDUs generated by the client and
server, respectively. So the following PDU (taken from ) will successfully validate against the
"nc-base-client" schema:However, if we replace the <running/> element in the
"source" parameter with <startup/>, the validation fails
since the optional capabilities such as :startup are not supported
by the "nc-base-client" schema. We can allow <startup/> as
the value of the "source" parameter simply by using the following
schema:In the same way, we can include any combination of capabilities
as long as they are not mutually exclusive.For the server PDUs the procedure is analogical but generally
simpler since none of the standard capabilities defined in affects the server schema, so the
"nc-base-server" schema is sufficient for validating server
PDUs.The set of RELAX NG schemas presented in this report provide a
modular grammar that can be used as a formal definition and
documentation of the NETCONF vocabulary, but also for validating
NETCONF PDUs. As a validation vehicle, though, these schemas are
considerably stricter than the W3C XML Schema from . This is mainly due to the fact that each of
the RELAX NG schema modules deals with a certain specific part of
the vocabulary - client or server side of a NETCONF channel, or
individual capabilities. The modules can be assembled in many
different ways into validation schemas that may be used for
effective NETCONF PDU validation.The fact that the modular RELAX NG schema is stricter and more
validation-oriented than its XSD counterpart doesn't mean that it
is less readable. On the contrary, separating the server and
client vocabularies and factoring out the optional capabilities
resulted in base server and client schemas that are simple and
easy to comprehend. Likewise, most capability schemas are almost
trivial but still show quite precisely where and how each
capability extends the vocabulary.The simplicity and limited scope of the schema modules also
enables their inclusion in larger validation frameworks such as
DSDL and/or combination with a NETCONF
concrete data model expressed in RELAX NG or a different data
modelling language.As a matter of fact, most improvements described in this report
could, and probably should, be applied to the NETCONF XSD schema
in , too. The only notable exception is
the compact syntax, which is special to RELAX NG.NETCONF Configuration ProtocolJuniper NetworksXML Schema Part 1: Structures, Second EditionUniversity of EdinburghOracle CorporationCommerce OneLotus Development CorporationXML Schema Part 2: Datatypes, Second EditionKaiser PermanenteMicrosoftDocument Schema Definition Languages (DSDL) - Part 1:
OverviewISO/IECDocument Schema Definition Languages (DSDL) - Part 2:
Regular Grammar-Based Validation - RELAX NGISO/IECThis appendix contains listings of the RELAX NG modules in the
compact syntax. The modules cover the NETCONF client and server
vocabularies including all optional capabilities described in RFC
4741 .This module defines several parameters patterns that are
referenced in both the client and server schemas.This module specifies the NETCONF client vocabulary without
any optional capabilities.This module specifies the NETCONF server vocabulary without
any optional capabilities.This module specifies the extensions to the client schema
provided by the :writable-running capability. The server
schema is unchanged. See RFC 4741 ,
Sec. 8.2.This module specifies the extensions to the client schema
provided by the :candidate capability. The server schema is
unchanged. See RFC 4741 , Sec. 8.3.This module specifies the extensions to the client schema
provided by the :confirmed-commit capability. The server
schema is unchanged. See RFC 4741 ,
Sec. 8.4.This module specifies the extensions to the client schema
provided by the :rollback-on-error capability. The server
schema is unchanged. See RFC 4741 ,
Sec. 8.5.This module specifies the extensions to the client schema
provided by the :validate capability. The server schema is
unchanged. See RFC 4741 , Sec. 8.6.This module specifies the extensions to the client schema
provided by the :startup capability. The server schema is
unchanged. See RFC 4741 , Sec. 8.7.This module specifies the extensions to the client schema
provided by the :url capability. The server schema is
unchanged. See RFC 4741 , Sec. 8.8.This module specifies the extensions to the client schema
provided by the :xpath capability. The server schema is
unchanged. See RFC 4741 , Sec. 8.9.