tech-invite   World Map     

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

RFC 6110

 Errata 
Proposed STD
Pages: 100
Top     in Index     Prev     Next
in Group Index     Prev in Group     Next in Group     Group: NETMOD

Mapping YANG to Document Schema Definition Languages and Validating NETCONF Content

Part 1 of 4, p. 1 to 16
None       Next RFC Part

Updated by:    7952


Top       ToC       Page 1 
Internet Engineering Task Force (IETF)                    L. Lhotka, Ed.
Request for Comments: 6110                                        CESNET
Category: Standards Track                                  February 2011
ISSN: 2070-1721


          Mapping YANG to Document Schema Definition Languages
                     and Validating NETCONF Content

Abstract

   This document specifies the mapping rules for translating YANG data
   models into Document Schema Definition Languages (DSDL), a
   coordinated set of XML schema languages standardized as ISO/IEC
   19757.  The following DSDL schema languages are addressed by the
   mapping: Regular Language for XML Next Generation (RELAX NG),
   Schematron, and Schematron and Document Schema Renaming Language
   (DSRL).  The mapping takes one or more YANG modules and produces a
   set of DSDL schemas for a selected target document type -- datastore
   content, Network Configuration Protocol (NETCONF) messages, etc.
   Procedures for schema-based validation of such documents are also
   discussed.

Status of This Memo

   This is an Internet Standards Track document.

   This document is a product of the Internet Engineering Task Force
   (IETF).  It represents the consensus of the IETF community.  It has
   received public review and has been approved for publication by the
   Internet Engineering Steering Group (IESG).  Further information on
   Internet Standards is available in Section 2 of RFC 5741.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be obtained at
   http://www.rfc-editor.org/info/rfc6110.

Page 2 
Copyright Notice

   Copyright (c) 2011 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1. Introduction ....................................................5
   2. Terminology and Notation ........................................6
      2.1. Glossary of New Terms ......................................9
   3. Objectives and Motivation ......................................10
   4. DSDL Schema Languages ..........................................11
      4.1. RELAX NG ..................................................11
      4.2. Schematron ................................................12
      4.3. Document Semantics Renaming Language (DSRL) ...............13
   5. Additional Annotations .........................................14
      5.1. Dublin Core Metadata Elements .............................14
      5.2. RELAX NG DTD Compatibility Annotations ....................14
      5.3. NETMOD-Specific Annotations ...............................15
   6. Overview of the Mapping ........................................16
   7. NETCONF Content Validation .....................................18
   8. Design Considerations ..........................................19
      8.1. Hybrid Schema .............................................19
      8.2. Modularity ................................................22
      8.3. Granularity ...............................................23
      8.4. Handling of XML Namespaces ................................24
   9. Mapping YANG Data Models to the Hybrid Schema ..................25
      9.1. Occurrence Rules for Data Nodes ...........................25
           9.1.1. Optional and Mandatory Nodes .......................26
           9.1.2. Implicit Nodes .....................................27
      9.2. Mapping YANG Groupings and Typedefs .......................28
           9.2.1. YANG Refinements and Augments ......................29
           9.2.2. Type Derivation Chains .............................32
      9.3. Translation of XPath Expressions ..........................35
      9.4. YANG Language Extensions ..................................36
   10. Mapping YANG Statements to the Hybrid Schema ..................37
      10.1. The 'anyxml' Statement ...................................37
      10.2. The 'argument' Statement .................................38

Top      ToC       Page 3 
      10.3. The 'augment' Statement ..................................39
      10.4. The 'base' Statement .....................................39
      10.5. The 'belongs-to' Statement ...............................39
      10.6. The 'bit' Statement ......................................39
      10.7. The 'case' Statement .....................................39
      10.8. The 'choice' Statement ...................................39
      10.9. The 'config' Statement ...................................40
      10.10. The 'contact' Statement .................................40
      10.11. The 'container' Statement ...............................40
      10.12. The 'default' Statement .................................40
      10.13. The 'description' Statement .............................42
      10.14. The 'deviation' Statement ...............................42
      10.15. The 'enum' Statement ....................................42
      10.16. The 'error-app-tag' Statement ...........................42
      10.17. The 'error-message' Statement ...........................42
      10.18. The 'extension' Statement ...............................43
      10.19. The 'feature' Statement .................................43
      10.20. The 'grouping' Statement ................................43
      10.21. The 'identity' Statement ................................43
      10.22. The 'if-feature' Statement ..............................45
      10.23. The 'import' Statement ..................................45
      10.24. The 'include' Statement .................................45
      10.25. The 'input' Statement ...................................46
      10.26. The 'key' Statement .....................................46
      10.27. The 'leaf' Statement ....................................46
      10.28. The 'leaf-list' Statement ...............................46
      10.29. The 'length' Statement ..................................47
      10.30. The 'list' Statement ....................................47
      10.31. The 'mandatory' Statement ...............................48
      10.32. The 'max-elements' Statement ............................49
      10.33. The 'min-elements' Statement ............................49
      10.34. The 'module' Statement ..................................49
      10.35. The 'must' Statement ....................................49
      10.36. The 'namespace' Statement ...............................50
      10.37. The 'notification' Statement ............................50
      10.38. The 'ordered-by' Statement ..............................50
      10.39. The 'organization' Statement ............................50
      10.40. The 'output' Statement ..................................51
      10.41. The 'path' Statement ....................................51
      10.42. The 'pattern' Statement .................................51
      10.43. The 'position' Statement ................................51
      10.44. The 'prefix' Statement ..................................51
      10.45. The 'presence' Statement ................................51
      10.46. The 'range' Statement ...................................51
      10.47. The 'reference' Statement ...............................51
      10.48. The 'require-instance' Statement ........................51
      10.49. The 'revision' Statement ................................52
      10.50. The 'rpc' Statement .....................................52

Top      ToC       Page 4 
      10.51. The 'status' Statement ..................................52
      10.52. The 'submodule' Statement ...............................52
      10.53. The 'type' Statement ....................................53
           10.53.1. The "empty" Type .................................54
           10.53.2. The "boolean" Type ...............................54
           10.53.3. The "binary" Type ................................54
           10.53.4. The "bits" Type ..................................54
           10.53.5. The "enumeration" and "union" Types ..............54
           10.53.6. The "identityref" Type ...........................54
           10.53.7. The "instance-identifier" Type ...................55
           10.53.8. The "leafref" Type ...............................55
           10.53.9. The Numeric Types ................................55
           10.53.10. The "string" Type ...............................57
           10.53.11. Derived Types ...................................58
      10.54. The 'typedef' Statement .................................59
      10.55. The 'unique' Statement ..................................59
      10.56. The 'units' Statement ...................................60
      10.57. The 'uses' Statement ....................................60
      10.58. The 'value' Statement ...................................60
      10.59. The 'when' Statement ....................................60
      10.60. The 'yang-version' Statement ............................60
      10.61. The 'yin-element' Statement .............................61
   11. Mapping the Hybrid Schema to DSDL .............................61
      11.1. Generating RELAX NG Schemas for Various Document Types ...61
      11.2. Mapping Semantic Constraints to Schematron ...............62
           11.2.1. Constraints on Mandatory Choice ...................65
      11.3. Mapping Default Values to DSRL ...........................67
   12. Mapping NETMOD-Specific Annotations to DSDL Schema Languages ..71
      12.1. The @nma:config Annotation ...............................71
      12.2. The @nma:default Annotation ..............................71
      12.3. The <nma:error-app-tag> Annotation .......................71
      12.4. The <nma:error-message> Annotation .......................71
      12.5. The @if-feature Annotation ...............................71
      12.6. The @nma:implicit Annotation .............................72
      12.7. The <nma:instance-identifier> Annotation .................72
      12.8. The @nma:key Annotation ..................................72
      12.9. The @nma:leaf-list Annotation ............................72
      12.10. The @nma:leafref Annotation .............................73
      12.11. The @nma:min-elements Annotation ........................73
      12.12. The @nma:max-elements Annotation ........................73
      12.13. The <nma:must> Annotation ...............................73
      12.14. The <nma:ordered-by> Annotation .........................74
      12.15. The <nma:status> Annotation .............................74
      12.16. The @nma:unique Annotation ..............................74
      12.17. The @nma:when Annotation ................................74
   13. IANA Considerations ...........................................75
   14. Security Considerations .......................................75
   15. Contributors ..................................................75

Top      ToC       Page 5 
   16. Acknowledgments ...............................................76
   17. References ....................................................76
      17.1. Normative References .....................................76
      17.2. Informative References ...................................77
   Appendix A. RELAX NG Schema for NETMOD-Specific Annotations .......79
   Appendix B. Schema-Independent Library ............................84
   Appendix C. Mapping DHCP Data Model - A Complete Example ..........85
      C.1. Input YANG Module .........................................85
      C.2. Hybrid Schema .............................................88
      C.3. Final DSDL Schemas  .......................................93
           C.3.1. Main RELAX NG Schema for <nc:get> Reply ............93
           C.3.2. RELAX NG Schema - Global Named Pattern
                  Definitions ........................................95
           C.3.3. Schematron Schema for <nc:get> Reply ...............98
           C.3.4. DSRL Schema for <nc:get> Reply .....................99

1.  Introduction

   The NETCONF Working Group has completed a base protocol used for
   configuration management [RFC4741].  This base specification defines
   protocol bindings and an XML container syntax for configuration and
   management operations, but does not include a data modeling language
   or accompanying rules for how to model configuration and state
   information carried by NETCONF.  The IETF Operations Area has a long
   tradition of defining data for Simple Network Management Protocol
   (SNMP) Management Information Bases (MIB) modules [RFC1157] using the
   Structure of Management Information (SMI) language [RFC2578] 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 without the 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.  The NETMOD Working Group was
   chartered to design a modeling language defining the semantics of
   operational data, configuration data, event notifications, and
   operations, with focus on "human-friendliness", i.e., readability and
   ease of use.  The result is the YANG data modeling language
   [RFC6020], which now serves for the normative description of NETCONF
   data models.

   Since NETCONF uses XML for encoding its messages, it is natural to
   express the constraints on NETCONF content using standard XML schema
   languages.  For this purpose, the NETMOD WG selected the Document
   Schema Definition Languages (DSDL) that is being standardized as
   ISO/IEC 19757 [DSDL].  The DSDL framework comprises a set of XML

Top      ToC       Page 6 
   schema languages that address grammar rules, semantic constraints,
   and other data modeling aspects, but also, and more importantly, do
   it in a coordinated and consistent way.  While it is true that some
   DSDL parts have not been standardized yet and are still work in
   progress, the three parts that the YANG-to-DSDL mapping relies upon
   -- Regular Language for XML Next Generation (RELAX NG), Schematron
   and Document Schema Renaming Language (DSRL) -- already have the
   status of an ISO/ IEC International Standard and are supported in a
   number of software tools.

   This document contains a specification of a mapping that translates
   YANG data models to XML schemas utilizing a subset of the DSDL schema
   languages.  The mapping procedure is divided into two steps: In the
   first step, the structure of the data tree, signatures of remote
   procedure call (RPC) operations, and notifications are expressed as
   the so-called "hybrid schema" -- a single RELAX NG schema with
   annotations representing additional data model information (metadata,
   documentation, semantic constraints, default values, etc.).  The
   second step then generates a coordinated set of DSDL schemas that can
   be used for validating specific XML documents such as client
   requests, server responses or notifications, perhaps also taking into
   account additional context such as active capabilities or features.

2.  Terminology and Notation

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].

   The following terms are defined in [RFC4741]:

   o  client

   o  datastore

   o  message

   o  operation

   o  server

   The following terms are defined in [RFC6020]:

   o  augment

   o  base type

   o  built-in type

Top      ToC       Page 7 
   o  configuration data

   o  container

   o  data model

   o  data node

   o  data tree

   o  derived type

   o  device deviation

   o  extension

   o  feature

   o  grouping

   o  instance identifier

   o  leaf-list

   o  list

   o  mandatory node

   o  module

   o  RPC

   o  RPC operation

   o  schema node

   o  schema tree

   o  state data

   o  submodule

   o  top-level data node

   o  uses

Top      ToC       Page 8 
   The following terms are defined in [XML-INFOSET]:

   o  attribute

   o  document

   o  document element

   o  document type declaration (DTD)

   o  element

   o  information set

   o  namespace

   In the text, the following typographic conventions are used:

   o  YANG statement keywords are delimited by single quotes.

   o  XML element names are delimited by "<" and ">" characters.

   o  Names of XML attributes are prefixed by the "@" character.

   o  Other literal values are delimited by double quotes.

   XML element names are always written with explicit namespace prefixes
   corresponding to the following XML vocabularies:

   "a"  DTD compatibility annotations [RNG-DTD];

   "dc"  Dublin Core metadata elements [RFC5013];

   "dsrl"  Document Semantics Renaming Language [DSRL];

   "en"  NETCONF event notifications [RFC5277];

   "nc"  NETCONF protocol [RFC4741];

   "nma"  NETMOD-specific schema annotations (see Section 5.3);

   "nmf"  NETMOD-specific XML Path Language (XPath) extension functions
      (see Section 12.7);

   "rng"  RELAX NG [RNG];

   "sch"  ISO Schematron [Schematron];

Top      ToC       Page 9 
   "xsd"  W3C XML Schema [XSD].

   The following table shows the mapping of these prefixes to namespace
   URIs.

     +--------+-----------------------------------------------------+
     | Prefix | Namespace URI                                       |
     +--------+-----------------------------------------------------+
     | a      | http://relaxng.org/ns/compatibility/annotations/1.0 |
     |        |                                                     |
     | dc     | http://purl.org/dc/terms                            |
     |        |                                                     |
     | dsrl   | http://purl.oclc.org/dsdl/dsrl                      |
     |        |                                                     |
     | en     | urn:ietf:params:xml:ns:netconf:notification:1.0     |
     |        |                                                     |
     | nc     | urn:ietf:params:xml:ns:netconf:base:1.0             |
     |        |                                                     |
     | nma    | urn:ietf:params:xml:ns:netmod:dsdl-annotations:1    |
     |        |                                                     |
     | nmf    | urn:ietf:params:xml:ns:netmod:xpath-extensions:1    |
     |        |                                                     |
     | rng    | http://relaxng.org/ns/structure/1.0                 |
     |        |                                                     |
     | sch    | http://purl.oclc.org/dsdl/schematron                |
     |        |                                                     |
     | xsd    | http://www.w3.org/2001/XMLSchema                    |
     +--------+-----------------------------------------------------+

          Table 1: Used namespace prefixes and corresponding URIs

2.1.  Glossary of New Terms

   o  ancestor data type: Any data type from which a given data type is
      (transitively) derived.

   o  ancestor built-in data type: The built-in data type that is at the
      start of the type derivation chain for a given data type.

   o  hybrid schema: A RELAX NG schema with annotations, which embodies
      the same information as the source YANG module(s).  See
      Section 8.1 for details.

   o  implicit node: A data node that, if it is not instantiated in a
      data tree, may be added to the information set of that data tree
      (configuration, RPC input or output, notification) without
      changing the semantics of the data tree.

Top      ToC       Page 10 
3.  Objectives and Motivation

   The main objective of this work is to complement YANG as a data
   modeling language with validation capabilities of DSDL schema
   languages, namely RELAX NG, Schematron, and DSRL.  This document
   describes the correspondence between grammatical, semantic, and data
   type constraints expressed in YANG and equivalent DSDL patterns and
   rules.  The ultimate goal is to be able to capture all substantial
   information contained in YANG modules and express it in DSDL schemas.
   While the mapping from YANG to DSDL described in this document may in
   principle be invertible, the inverse mapping from DSDL to YANG is
   beyond the scope of this document.

   XML-based information models and XML-encoded data appear in several
   different forms in various phases of YANG data modeling and NETCONF
   workflow -- configuration datastore contents, RPC requests and
   replies, and notifications.  Moreover, RPC operations are
   characterized by an inherent diversity resulting from selective
   availability of capabilities and features.  YANG modules can also
   define new RPC operations.  The mapping should be able to accommodate
   this variability and generate schemas that are specifically tailored
   to a particular situation and thus considerably more effective for
   validation than generic all-encompassing schemas.

   In order to cope with this variability, we assume that the DSDL
   schemas will be generated on demand for a particular purpose from the
   available collection of YANG modules and their lifetime will be
   relatively short.  In other words, we don't envision that any
   collection of DSDL schemas will be created and maintained over an
   extended period of time in parallel to YANG modules.

   The generated schemas are primarily intended as input to existing XML
   schema validators and other off-the-shelf tools.  However, the
   schemas may also be perused by developers and users as a formal
   representation of constraints on a particular XML-encoded data
   object.  Consequently, our secondary goal is to keep the schemas as
   readable as possible.  To this end, the complexity of the mapping is
   distributed into two steps:

   1.  The first step maps one or more YANG modules to the so-called
       hybrid schema, which is a single RELAX NG schema that describes
       grammatical constraints for the main data tree as well as for RPC
       operations and notifications.  Semantic constraints and other
       information appearing in the input YANG modules is recorded in
       the hybrid schema in the form of foreign namespace annotations.
       The output of the first step can thus be considered a virtually
       complete equivalent of the input YANG modules.  It cannot,
       however, be directly used for any validation.

Top      ToC       Page 11 
   2.  In the second step, the hybrid schema from step 1 is transformed
       further to a coordinated set of fully conformant DSDL schemas
       containing constraints for a particular data object and a
       specific situation.  The DSDL schemas are intended mainly for
       machine validation using off-the-shelf tools.

4.  DSDL Schema Languages

   Document Schema Definition Languages (DSDL) is a framework of schema
   languages that is being developed as the International Standard ISO/
   IEC 19757 [DSDL].  Unlike other approaches to XML document
   validation, most notably W3C XML Schema Definition (XSD) [XSD], the
   DSDL framework adheres to the principle of "small languages": each of
   the DSDL constituents is a stand-alone schema language with a
   relatively narrow purpose and focus.  Together, these schema
   languages may be used in a coordinated way to accomplish various
   validation tasks.

   The mapping described in this document uses three of the DSDL schema
   languages, namely RELAX NG [RNG], Schematron [Schematron], and DSRL
   [DSRL].

4.1.  RELAX NG

   RELAX NG (pronounced "relaxing") is an XML schema language for
   grammar-based validation and Part 2 of the ISO/IEC DSDL family of
   standards [RNG].  Like XSD, it is able to describe constraints on the
   structure and contents of XML documents.  However, unlike the DTD
   [XML] and XSD schema languages, RELAX NG intentionally avoids any
   infoset augmentation such as defining default values.  In the DSDL
   architecture, the particular task of defining and applying default
   values is delegated to another schema language, DSRL (see
   Section 4.3).

   As its base data type library, RELAX NG uses the W3C XML Schema
   Datatypes [XSD-D]; but unlike XSD, other data type libraries may be
   used along with it or even replace it if necessary.

   RELAX NG is very liberal in accepting annotations from other
   namespaces.  With a few exceptions, such annotations may be placed
   anywhere in the schema and need no encapsulating elements such as
   <xsd:annotation> in XSD.

Top      ToC       Page 12 
   RELAX NG schemas can be represented in two equivalent syntaxes: XML
   and compact.  The compact syntax is described in Annex C of the RELAX
   NG specification [RNG-CS], which was added to the standard in 2006
   (Amendment 1).  Automatic bidirectional conversions between the two
   syntaxes can be accomplished using several tools, for example, Trang
   [Trang].

   For its terseness and readability, the compact syntax is often the
   preferred form for publishing RELAX NG schemas, whereas validators
   and other software tools usually work with the XML syntax.  However,
   the compact syntax has two drawbacks:

   o  External annotations make the compact syntax schema considerably
      less readable.  While in the XML syntax the annotating elements
      and attributes are represented in a simple and uniform way (XML
      elements and attributes from foreign namespaces), the compact
      syntax uses as many as four different syntactic constructs:
      documentation, grammar, initial, and following annotations.
      Therefore, the impact of annotations on readability is often much
      stronger for the compact syntax than it is for the XML syntax.

   o  In a computer program, it is more difficult to generate the
      compact syntax than the XML syntax.  While a number of software
      libraries exist that make it easy to create an XML tree in the
      memory and then serialize it, no such aid is available for the
      compact syntax.

   For these reasons, the mapping specification in this document uses
   exclusively the XML syntax.  Where appropriate, though, the schemas
   resulting from the translation MAY be presented in the equivalent
   compact syntax.

   RELAX NG elements are qualified with the namespace URI
   "http://relaxng.org/ns/structure/1.0".  The namespace of the XSD data
   type library is "http://www.w3.org/2001/XMLSchema-datatypes".

4.2.  Schematron

   Schematron is Part 3 of DSDL that reached the status of a full ISO/
   IEC standard in 2006 [Schematron].  In contrast to the traditional
   schema languages such as DTD, XSD, or RELAX NG, which are based on
   the concept of a formal grammar, Schematron utilizes a rule-based
   approach.  Its rules may specify arbitrary conditions involving data
   from different parts of an XML document.  Each rule consists of three
   essential components:

   o  context - an XPath expression that defines the set of locations
      where the rule is to be applied;

Top      ToC       Page 13 
   o  assert or report condition - another XPath expression that is
      evaluated relative to the location matched by the context
      expression;

   o  human-readable message that is displayed when the assert condition
      is false or report condition is true.

   The difference between the assert and report condition is that the
   former is positive in that it states a condition that a valid
   document has to satisfy, whereas the latter specifies an error
   condition.

   Schematron draws most of its expressive power from XPath [XPath] and
   Extensible Stylesheet Language Transformations (XSLT) [XSLT].  ISO
   Schematron allows for dynamic query language binding so that the
   following XML query languages can be used: STX, XSLT 1.0, XSLT 1.1,
   EXSLT, XSLT 2.0, XPath 1.0, XPath 2.0, and XQuery 1.0 (this list may
   be extended in the future).

   Human-readable error messages are another feature that sets
   Schematron apart from other common schema languages.  The messages
   may even contain XPath expressions that are evaluated in the actual
   context and thus refer to information items in the XML document being
   validated.

   Another feature of Schematron that is used by the mapping are
   abstract patterns.  These work essentially as macros and may also
   contain parameters which are supplied when the abstract pattern is
   used.

   Schematron elements are qualified with namespace URI
   "http://purl.oclc.org/dsdl/schematron".

4.3.  Document Semantics Renaming Language (DSRL)

   DSRL (pronounced "disrule") is Part 8 of DSDL that reached the status
   of a full ISO/IEC standard in 2008 [DSRL].  Unlike RELAX NG and
   Schematron, DSRL is allowed to modify XML information set of the
   validated document.  While DSRL is primarily intended for renaming
   XML elements and attributes, it can also define default values for
   XML attributes and default contents for XML elements or subtrees so
   that the default contents are inserted if they are missing in the
   validated documents.  The latter feature is used by the YANG-to-DSDL
   mapping for representing YANG default contents consisting of leaf
   nodes with default values and their ancestor non-presence containers.

   DSRL elements are qualified with namespace URI
   "http://purl.oclc.org/dsdl/dsrl".

Top      ToC       Page 14 
5.  Additional Annotations

   Besides the DSDL schema languages, the mapping also uses three sets
   of annotations that are added as foreign-namespace attributes and
   elements to RELAX NG schemas.

   Two of the annotation sets -- Dublin Core elements and DTD
   compatibility annotations -- are standard vocabularies for
   representing metadata and documentation, respectively.  Although
   these data model items are not used for formal validation, they quite
   often carry important information for data model implementers.
   Therefore, they SHOULD be included in the hybrid schema and MAY also
   appear in the final validation schemas.

   The third set are NETMOD-specific annotations.  They are specifically
   designed for the hybrid schema and convey semantic constraints and
   other information that cannot be expressed directly in RELAX NG.  In
   the second mapping step, these annotations are converted to
   Schematron and DSRL rules.

5.1.  Dublin Core Metadata Elements

   Dublin Core is a system of metadata elements that was originally
   created for describing metadata of World Wide Web resources in order
   to facilitate their automated lookup.  Later it was accepted as a
   standard for describing metadata of arbitrary resources.  This
   specification uses the definition from [RFC5013].

   Dublin Core elements are qualified with namespace URI
   "http://purl.org/dc/terms".

5.2.  RELAX NG DTD Compatibility Annotations

   DTD compatibility annotations are a part of the RELAX NG DTD
   Compatibility specification [RNG-DTD].  YANG-to-DSDL mapping uses
   only the <a:documentation> annotation for representing YANG
   'description' and 'reference' texts.

   Note that there is no intention to make the resulting schemas DTD-
   compatible, the main reason for using these annotations is technical:
   they are well supported and adequately formatted by several RELAX NG
   tools.

   DTD compatibility annotations are qualified with namespace URI
   "http://relaxng.org/ns/compatibility/annotations/1.0".

Top      ToC       Page 15 
5.3.  NETMOD-Specific Annotations

   NETMOD-specific annotations are XML elements and attributes that are
   qualified with the namespace URI
   "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1" and that appear in
   various locations of the hybrid schema.  YANG statements are mapped
   to these annotations in a straightforward way.  In most cases, the
   annotation attributes and elements have the same name as the
   corresponding YANG statement.

   Table 2 lists, alphabetically, the names of NETMOD-specific
   annotation attributes (prefixed with "@") and elements (in angle
   brackets) along with a reference to the section where their use is
   described.  Appendix A contains a RELAX NG schema for this annotation
   vocabulary.

         +---------------------------+--------------------+------+
         | annotation                | section            | note |
         +---------------------------+--------------------+------+
         | @nma:config               | 10.9               |      |
         |                           |                    |      |
         | <nma:data>                | 8.1                | 4    |
         |                           |                    |      |
         | @nma:default              | 10.12              |      |
         |                           |                    |      |
         | <nma:error-app-tag>       | 10.16              | 1    |
         |                           |                    |      |
         | <nma:error-message>       | 10.17              | 1    |
         |                           |                    |      |
         | @nma:if-feature           | 10.22              |      |
         |                           |                    |      |
         | @nma:implicit             | 10.11, 10.7, 10.12 |      |
         |                           |                    |      |
         | <nma:input>               | 8.1                | 4    |
         |                           |                    |      |
         | <nma:instance-identifier> | 10.53.7            | 2    |
         |                           |                    |      |
         | @nma:key                  | 10.26              |      |
         |                           |                    |      |
         | @nma:leaf-list            | 10.28              |      |
         |                           |                    |      |
         | @nma:leafref              | 10.53.8            |      |
         |                           |                    |      |
         | @nma:mandatory            | 10.8               |      |
         |                           |                    |      |
         | @nma:max-elements         | 10.28              |      |
         |                           |                    |      |
         | @nma:min-elements         | 10.28              |      |

Top      ToC       Page 16 
         |                           |                    |      |
         | @nma:module               | 10.34              |      |
         |                           |                    |      |
         | <nma:must>                | 10.35              | 3    |
         |                           |                    |      |
         | <nma:notification>        | 8.1                | 4    |
         |                           |                    |      |
         | <nma:notifications>       | 8.1                | 4    |
         |                           |                    |      |
         | @nma:ordered-by           | 10.38              |      |
         | <nma:output>              | 8.1                | 4    |
         |                           |                    |      |
         | <nma:rpc>                 | 8.1                | 4    |
         |                           |                    |      |
         | <nma:rpcs>                | 8.1                | 4    |
         |                           |                    |      |
         | @nma:status               | 10.51              |      |
         |                           |                    |      |
         | @nma:unique               | 10.55              |      |
         |                           |                    |      |
         | @nma:units                | 10.56              |      |
         |                           |                    |      |
         | @nma:when                 | 10.59              |      |
         +---------------------------+--------------------+------+

                   Table 2: NETMOD-specific annotations

   Notes:

   1.  Appears only as a subelement of <nma:must>.

   2.  Has an optional attribute @require-instance.

   3.  Has a mandatory attribute @assert and two optional subelements
       <nma:error-app-tag> and <nma:error-message>.

   4.  Marker element in the hybrid schema.



(page 16 continued on part 2)

Next RFC Part