NETMOD L. Lhotka Internet-Draft CESNET Intended status: Informational July 6, 2008 Expires: January 7, 2009 Mapping of YANG to DSDL draft-lhotka-yang-dsdl-map-00 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 January 7, 2009. Lhotka Expires January 7, 2009 [Page 1] Internet-Draft YANG-DSDL Mapping July 2008 Abstract This draft describes the algorithm and rules for mapping data models expressed in the YANG language to Document Schema Definition Languages (DSDL) with additional annotations. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Overview of the Mapping Algorithm . . . . . . . . . . . . . . 6 2.1. Optional Content . . . . . . . . . . . . . . . . . . . . . 7 3. Schema Languages . . . . . . . . . . . . . . . . . . . . . . . 8 4. Design Considerations . . . . . . . . . . . . . . . . . . . . 11 4.1. Modularity . . . . . . . . . . . . . . . . . . . . . . . . 11 4.2. Granularity . . . . . . . . . . . . . . . . . . . . . . . 11 4.3. Mangled Names of RELAX NG Named Patterns . . . . . . . . . 12 5. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 14 5.1. No Root or Multiple Root Nodes . . . . . . . . . . . . . . 14 5.2. The extension Statement . . . . . . . . . . . . . . . . . 14 5.3. The rpc and notification statements . . . . . . . . . . . 15 5.4. The augment Statement . . . . . . . . . . . . . . . . . . 15 6. Mapping Rules for YANG Statements . . . . . . . . . . . . . . 18 6.1. The anyxml Statement . . . . . . . . . . . . . . . . . . . 19 6.2. The argument Statement . . . . . . . . . . . . . . . . . . 19 6.3. The augment Statement . . . . . . . . . . . . . . . . . . 20 6.4. The belongs-to Statement . . . . . . . . . . . . . . . . . 20 6.5. The bit Statement . . . . . . . . . . . . . . . . . . . . 20 6.6. The case Statement . . . . . . . . . . . . . . . . . . . . 20 6.7. The choice Statement . . . . . . . . . . . . . . . . . . . 20 6.8. The config Statement . . . . . . . . . . . . . . . . . . . 20 6.9. The contact Statement . . . . . . . . . . . . . . . . . . 20 6.10. The container Statement . . . . . . . . . . . . . . . . . 20 6.11. The default Statement . . . . . . . . . . . . . . . . . . 20 6.12. The description Statement . . . . . . . . . . . . . . . . 21 6.13. The enum Statement . . . . . . . . . . . . . . . . . . . . 21 6.14. The error-app-tag Statement . . . . . . . . . . . . . . . 21 6.15. The error-message Statement . . . . . . . . . . . . . . . 21 6.16. The extension Statement . . . . . . . . . . . . . . . . . 21 6.17. The grouping Statement . . . . . . . . . . . . . . . . . . 21 6.18. The import Statement . . . . . . . . . . . . . . . . . . . 21 6.19. The include Statement . . . . . . . . . . . . . . . . . . 21 6.20. The input Statement . . . . . . . . . . . . . . . . . . . 22 6.21. The key Statement . . . . . . . . . . . . . . . . . . . . 22 6.22. The leaf Statement . . . . . . . . . . . . . . . . . . . . 22 6.23. The leaf-list Statement . . . . . . . . . . . . . . . . . 22 6.24. The length Statement . . . . . . . . . . . . . . . . . . . 22 6.25. The list Statement . . . . . . . . . . . . . . . . . . . . 22 Lhotka Expires January 7, 2009 [Page 2] Internet-Draft YANG-DSDL Mapping July 2008 6.26. The mandatory Statement . . . . . . . . . . . . . . . . . 23 6.27. The max-elements Statement . . . . . . . . . . . . . . . . 23 6.28. The min-elements Statement . . . . . . . . . . . . . . . . 23 6.29. The module Statement . . . . . . . . . . . . . . . . . . . 23 6.30. The must Statement . . . . . . . . . . . . . . . . . . . . 23 6.31. The namespace Statement . . . . . . . . . . . . . . . . . 23 6.32. The notification Statement . . . . . . . . . . . . . . . . 23 6.33. The ordered-by Statement . . . . . . . . . . . . . . . . . 23 6.34. The organization Statement . . . . . . . . . . . . . . . . 23 6.35. The output Statement . . . . . . . . . . . . . . . . . . . 23 6.36. The path Statement . . . . . . . . . . . . . . . . . . . . 24 6.37. The pattern Statement . . . . . . . . . . . . . . . . . . 24 6.38. The position Statement . . . . . . . . . . . . . . . . . . 24 6.39. The prefix Statement . . . . . . . . . . . . . . . . . . . 24 6.40. The presence Statement . . . . . . . . . . . . . . . . . . 24 6.41. The range Statement . . . . . . . . . . . . . . . . . . . 24 6.42. The reference Statement . . . . . . . . . . . . . . . . . 24 6.43. The revision Statement . . . . . . . . . . . . . . . . . . 24 6.44. The rpc Statement . . . . . . . . . . . . . . . . . . . . 24 6.45. The status Statement . . . . . . . . . . . . . . . . . . . 25 6.46. The submodule Statement . . . . . . . . . . . . . . . . . 25 6.47. The type Statement . . . . . . . . . . . . . . . . . . . . 25 6.47.1. The empty Type . . . . . . . . . . . . . . . . . . . 26 6.47.2. The boolean and binary Types . . . . . . . . . . . . 26 6.47.3. The instance identifier Type . . . . . . . . . . . . 27 6.47.4. The bits Type . . . . . . . . . . . . . . . . . . . . 27 6.47.5. The enumeration and union Types . . . . . . . . . . . 27 6.47.6. The keyref type . . . . . . . . . . . . . . . . . . . 27 6.47.7. The numeric Types . . . . . . . . . . . . . . . . . . 27 6.47.8. The string Type . . . . . . . . . . . . . . . . . . . 28 6.48. The typedef Statement . . . . . . . . . . . . . . . . . . 29 6.49. The unique Statement . . . . . . . . . . . . . . . . . . . 29 6.50. The units Statement . . . . . . . . . . . . . . . . . . . 29 6.51. The uses Statement . . . . . . . . . . . . . . . . . . . . 29 6.52. The value Statement . . . . . . . . . . . . . . . . . . . 30 6.53. The when Statement . . . . . . . . . . . . . . . . . . . . 30 6.54. The yang-version Statement . . . . . . . . . . . . . . . . 30 6.55. The yin-element Statement . . . . . . . . . . . . . . . . 30 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Appendix A. Translation of the DHCP Data Model . . . . . . . . . 32 A.1. XML Syntax . . . . . . . . . . . . . . . . . . . . . . . . 32 A.2. Compact Syntax . . . . . . . . . . . . . . . . . . . . . . 36 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 39 Intellectual Property and Copyright Statements . . . . . . . . . . 40 Lhotka Expires January 7, 2009 [Page 3] Internet-Draft YANG-DSDL Mapping July 2008 1. Introduction The NETMOD working group complements the results of the NETCONF WG by addressing the data modeling issues. The major item in the NETMOD charter is a new data modeling language called YANG [YANG]. This language, being based on SMIng [RFC3216], builds on the experience of previous network management systems, most notably SNMP. However, since NETCONF chose eXtensible Markup Language [XML] as the method for encoding both configuration data and their envelope (RPC layer), this work can and should also benefit from the body of knowledge, standards and software tools that have been established in the XML world. To this end, YANG also provides an alternative syntax called YIN that is able to represent the same information using XML. Despite the syntactic differences, the information models of YANG and YIN are virtually identical and conversion between YANG and YIN is straightforward in both directions. However, having data models expressed in an XML syntax is not by itself sufficient for leveraging the existing XML know-how and tools. It is also necessary to convey the meaning of YANG models and present it in a way that the existing XML tools can understand. As a matter of fact, YANG/YIN can be viewed as yet another XML schema language. While there are several aspects that make YANG models specific to the NETCONF realm, for the most part the grammatical and semantic constraints that the models express can be equivalently represented in the general-purpose XML schema languages such as W3C XML Schema, RELAX NG, Schematron and others. Therefore, one of the chartered items of the NETMOD WG is to define a mapping from YANG to the Document Schema Definition Languages (DSDL) that is being standardized as ISO/IEC 19757 [DSDL]. The DSDL framework comprises a set of XML schema languages that address grammar rules, semantic constraints and other data modeling aspect but also, and more importantly, can 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 two crucial parts that the YANG -> DSDL mapping relies upon - RELAX NG and Schematron - already have the status of ISO/IEC Final Draft International Standard and are supported in a number of software tools. This memo describes the algorithm for translating YANG data models to a schema (or multiple schemas) utilizing a subset of the DSDL schema languages together with a limited number of other annotations. The aim is to map as much structural, datatyping and semantic information as possible from YANG to DSDL with annotations so that the resulting schema(s) can be used with standard XML tools for a relatively comprehensive validation of the contents of configuration datastores. Lhotka Expires January 7, 2009 [Page 4] Internet-Draft YANG-DSDL Mapping July 2008 The most important schema language in the DSDL framework is RELAX NG [RNG]. The specification of the mapping algorithm given below assumes that output of RELAX NG uses the XML syntax. However, RELAX NG compact syntax [RNG-CS] is often the preferred form for perusal by human readers. A secondary goal therefore is to guarantee a reasonable level of readability of the resulting RELAX NG in the compact syntax as well, even if multiple embedded annotation types are used. In the text, we use the following typographic conventions: o YANG statement keywords are delimited by single quotes. o Literal values are delimited by double quotes. o XML element names are delimited by "<" and ">" characters. o Names of XML attributes are prefixed by the "@" character. Lhotka Expires January 7, 2009 [Page 5] Internet-Draft YANG-DSDL Mapping July 2008 2. Overview of the Mapping Algorithm The mapping algorithm assumes input in the form of a tree data structure representing a valid YANG module, henceforth denoted as the "YANG tree". Each node in the YANG tree is a data structure that corresponds to a single YANG statement. The node records the essential parameters of the statement (keyword, argument string) and keeps a pointer to the parent statement and a list of substatements. It is also assumed that the algorithm has access, perhaps on demand, to the parsed form of all YANG modules that the module imports (transitively). The algorithm recursively traverses the YANG tree in preorder and constructs one or more XML trees for each of the DSDL schema languages that the algorithm generates (see Section 3). In parallel, it keeps a pointer to the current position in each of the schema trees where new XML fragments corresponding to YANG statements get attached. The resulting schema(s) may be internally represented in the form of a Document Object Model (DOM) or any other framework for creating and manipulating moderately sized XML trees. An implementation of the mapping algorithm MUST provide the resulting schema(s) in at least one of the following forms: 1. A set of separate schemas, typically in different disk files, one for each DSDL schema language. Non-DSDL annotations MUST be attached to the RELAX NG schema. 2. A single RELAX NG schema with elements and attributes of the remaining DSDL schema languages and other annotations. The first form is essentially what the DSDL standard [DSDL] expects and can be readily used with existing tools. The advantage of the second form is a more concise representation and better comprehensibility. Note that non-DSDL annotations are always embedded in the RELAX NG schema. An implementation SHOULD also allow the user to select a subset of schema languages and annotation types that are used for output. For example, a user might want to select pure RELAX NG without any annotations and still obtain a schema that is reasonably usable for validation. Lhotka Expires January 7, 2009 [Page 6] Internet-Draft YANG-DSDL Mapping July 2008 2.1. Optional Content In YANG, all leaf nodes are optional unless they contain substatement mandatory true; or unless they are declared as list keys. Lists or leaf-lists are optional unless they contain 'min-elements' substatement with argument value greater than zero. YANG specification allows non-presence containers to be be omitted if they are empty. Containers with the 'presence' substatement are always optional since their presence or absence carries specific information. Putting it all together, we get the following recursive rule for containers: A container is optional if and only if at least one of the following conditions holds: 1. it is a container with presence; 2. none of its descendant leaf nodes is mandatory or, if such a leaf exists, it is enclosed in an intervening container with presence; 3. none of its descendant list or leaf-list nodes has 'min-elements' substatement with argument value greater than zero or, if such a list or leaf-list exists, it is enclosed in an intervening container with presence. In RELAX NG, all elements that are optional must be explicitly wrapped in the element. Therefore, the mapping algorithm MUST be able to determine whether a YANG node is optional and if so, insert the element in the RELAX NG schema. Lhotka Expires January 7, 2009 [Page 7] Internet-Draft YANG-DSDL Mapping July 2008 3. Schema Languages The mapping algorithm uses the following schema languages and annotation types: o _RELAX NG_ (DSDL Part 2 [RNG]) is used for representing grammatical constraints, simple datatypes (via the W3C XML Schema Datatype Library [XSD-D]), complex datatypes, restrictions of datatypes, and YANG groupings. RELAX NG namespace is "http://relaxng.org/ns/structure/1.0". o _Schematron_ (DSDL Part 3 [Schtrn]) is used for specifying additional semantic constraints that are either inherent to YANG (e.g., uniqueness of list keys) or specified by the data model author (e.g., using the 'must' statement). Schematron namespace is "http://purl.oclc.org/dsdl/schematron". o _Document Schema Renaming Language_ (DSRL; DSDL Part 8 [DSRL]) is used only for specifying default values for YANG leaf nodes and typedefs (cf. 'default' statement). DSRL namespace is "http://purl.oclc.org/dsdl/dsrl". o _Dublin Core metadata terms_ [DCMT] are used for general data model metadata such as authorship information, revision date or model description. The namespace for Dublin Core metadata terms is "http://purl.org/dc/terms". o _RELAX NG DTD compatibility annotations_ [RNG-DTD] are used for 'description' and 'reference' strings, except at the top level of a module where Dublin Core metadata terms are used for this purpose. The namespace for DTD compatibility annotations is "http://relaxng.org/ns/compatibility/annotations/1.0". o _NETMOD-specific annotations_ is a small collection of other annotations that convey additional semantics expressed by YANG model. They are always modeled as XML attributes attached to the RELAX NG elements that they qualify. The namespace for NETMOD- specific annotations is "urn:ietf:params:xml:ns:netmod:dsdl-attrib:1". If the YANG module contains no schema tree - for example, if it contains only definitions of grouping and typedefs - then the resulting RELAX NG schema SHOULD NOT have a element. If an implementation generates multiple DSDL schemas (output alternative 1 in Section 2), then all such schemas MUST be valid according to the current DSDL standards. However, if the output form is a single annotated RELAX NG schema (output alternative 2 in Lhotka Expires January 7, 2009 [Page 8] Internet-Draft YANG-DSDL Mapping July 2008 Section 2), certain parts of the annotating DSDL schema rules MAY be omitted, provided that the corresponding information can be unambiguously inferred, typically from the location of the annotating elements within the RELAX NG tree. For example, consider the following YANG snippet: module dhcp { ... container dhcp { ... leaf max-lease-time { ... }; leaf default-lease-time { ... must '$this <= ../max-lease-time' { error-message "default-lease-time must be less than max-lease-time"; } default 600; } ... } ... } If multiple schemas are generated, in this case RELAX NG, Schematron and DSRL, the 'must' statement shall be mapped to the following Schematron fragment: default-lease-time must be less than max-lease-time Similarly, the 'default' statement results in the following DSRL fragment: /dhcp default-lease-time 600 In both the Schematron and DSRL fragments, the context for the rules is explicitly specified by means of an XPath expression. If we Lhotka Expires January 7, 2009 [Page 9] Internet-Draft YANG-DSDL Mapping July 2008 insert these rules as annotations into the RELAX NG schema, the context is implicitly defined by the location of the rules with the RELAX NG schema. Therefore, the resulting RELAX NG schema fragment can be only ... The default-lease-time must be less than max-lease-time 600 Lhotka Expires January 7, 2009 [Page 10] Internet-Draft YANG-DSDL Mapping July 2008 4. Design Considerations This section describes the general principles and conventions used by the mapping algorithm. 4.1. Modularity Both YANG and RELAX NG offer means for modularity, i.e., splitting the contents into separate modules (schemas) and combining or reusing them in various ways. However, the approaches taken by YANG and RELAX NG differ. Modularity in RELAX NG is intended more for ad hoc combinations of a small number of schemas whereas YANG assumes a large set of modules similar to SNMP MIBs. In particular, RELAX NG uses a single flat namespace for all named patterns, be they local or imported, while every YANG module has its unique namespace and symbols imported by other modules remain in the namespace of their original module. Consequently, multiple YANG groupings and typedefs defined in different modules can have the same (local) identifier but still be used together in another module, but in RELAX NG this would mean a name conflict. Therefore, the design decision for the mapping algorithm was to collect all contents in a single DSDL module even if in YANG it is distributed in several modules. Translations of foreign groupings and typedefs are installed in the importing module with appropriately mangled names - but only if they are really used by the importing module. On the other hand, YANG submodules share the same namespace with the modules they belong to, so their modular structure can be retained in RELAX NG by using the element. 4.2. Granularity RELAX NG supports different styles of structuring the schema: One extreme, often called "Russian Doll", specifies the structure of an XML instance document in a single schema. The other extreme, the flat style, is similar to the original Data Type Definition (DTD) schema language - every XML element is introduced inside a new named pattern. In practice, some compromise between the two extremes is usually chosen. YANG in principle supports both styles, too, but in most cases the modules are organized in a way that's closer to the "Russian Doll" style, which provides a better insight into the structure of the configuration data. Groupings are usually defined only for subtrees that are prepared for reuse via the 'uses' statement. In contrast, RELAX NG schemas tend to be much flatter, because finer granularity Lhotka Expires January 7, 2009 [Page 11] Internet-Draft YANG-DSDL Mapping July 2008 is in RELAX NG also needed for extensibility of the schemas - it is only possible to replace or modify schema fragments that are factored out as named patterns. For YANG this is not an issue since its 'augment' statement can delve, by using path expressions, into arbitrary depths of existing structures. We argue in Section 5.4 that is is in general not feasible to map YANG extension mechanisms to those of RELAX NG. For this reason, the mapping keeps the granularity of the original YANG data model: definitions of named patterns in the resulting RELAX NG schema have direct counterparts in YANG groupings and definitions of complex types. 4.3. Mangled Names of RELAX NG Named Patterns YANG typedefs and groupings may appear in all levels of the module hierarchy and are subject to lexical scoping. Moreover, top-level symbols from external modules are imported as qualified names consisting of the external module namespace and the name of the symbol. In contrast, named patterns in RELAX NG (both local and imported) share the same namespace and their definitions may only appear at the top level of the RELAX NG schema as children of the element. Consequently, whenever YANG groupings and typedefs are translated into RELAX NG named pattern definitions, their MUST be disambiguated in order to avoid naming conflicts. The following name mangling procedure is suggested: o Mangled names of local groupings and typedefs start with a double underline character and names of all ancestor nodes in the YANG data tree are recorded in the mangled name, separated by double underlines. o Mangled names of imported groupings and typedefs starts with the name of the modules where they are defined followed by double underline followed by the local name of the grouping or typedef. For example, YANG content Lhotka Expires January 7, 2009 [Page 12] Internet-Draft YANG-DSDL Mapping July 2008 import "inet-types" { prefix "inet"; } grouping "grp1" { leaf "void" { type "empty"; } } container "cont" { grouping "grp2" { leaf "address" { type "inet:ip-address"; } } uses "grp1"; uses "grp2"; } would result in the following definitions of RELAX NG named patterns: ... Lhotka Expires January 7, 2009 [Page 13] Internet-Draft YANG-DSDL Mapping July 2008 5. Open Issues This section collects open issues that need further discussion within the NETMOD WG. 5.1. No Root or Multiple Root Nodes Well-formed XML documents must have exactly one root element (cf. [XML], Section 2.1). In contrast, YANG data models may also allow multiple root nodes or no root at all. Consequently, it is impossible to translate such data models to a valid RELAX NG schema. For multiple roots, the YANG specification [YANG] recommends in Section 5.1.1 to use an extra conceptual root node such as or . While it is possible to include such a conceptual node in the RELAX NG schema, it would likely become an annoyance for data models with a single root. Therefore, a general solution to the problem of multiple roots should be devised. Section 3 specifies that the resulting RELAX NG schema should not have a element if the original YANG model contains no explicit data tree. Strictly speaking, this leads to an invalid RELAX NG schema (cf. [RNG], Section 7.19) and some RELAX NG parsers indeed do complain about it. However, it is a common practice to prepare such "startless" RELAX NG schemas with definitions of reusable named patterns, see e.g., [Vli04], Chapter 10. It is thus probably no reason for concerns - it has to be understood that such schemas are not supposed to be used as stand-alone. However, a YANG data model may also allow empty instance documents if all nodes are optional, as discussed in Section 2.1. This leads to an invalid RELAX NG schema with the following element: ... The problems of no root or multiple root nodes can be solved by changing YANG specification in the sense that all instances of data models must be enclosed in a fixed and mandatory container, for example "netmod-data". 5.2. The extension Statement The 'extension' statement can be used for declaring new statements for the YANG language itself. Their keywords are qualified names Lhotka Expires January 7, 2009 [Page 14] Internet-Draft YANG-DSDL Mapping July 2008 carrying the namespace name of the module that defines them. It is not difficult to insert such extensions into the resulting RELAX NG schema because RELAX NG allows elements and attributes from different namespaces to be freely intermixed with its own elements and attributes. A straightforward option for translating such extensions is to generate the YIN representation of the extension (utilizing the 'argument' substatement of the 'extension' statement) and attach this XML subtree at the corresponding position in the RELAX NG schema tree. It is not clear though whether it is sensible to blindly copy such extensions without knowing their semantics. For example, if the extension utilizes paths referring to the YANG model tree, this paths may become incorrect when used as XPaths in the RELAX NG tree. 5.3. The rpc and notification statements In YANG, the 'rpc' statement declares the signature of a NETCONF RPC operation - method names, input and output parameters. With this information, one can create a pair of schemas for validating protocol data units with NETCONF and messages, but these schemas would be different from the data model for the entire configuration datastore that the rest of the YANG module is about. It is therefore not very clear whether and how to use the 'rpc' statement in the mapping algorithm. A completely analogical situation is with the 'notification' statement that defines a NETCONF notification. 5.4. The augment Statement For the translation to DSDL schemas, the most difficult YANG concept turns out to be the 'augment' statement. This is partly because it in fact serves several different purposes: At the top level of the YANG module hierarchy, the 'augment' statement may be used to add new nodes to a foreign schema that is defined in another module, which is imported in the module where the 'augment' statement appears (see the examples in Section 7.5.14 of [YANG]). In the context of the augmenting module, this 'augment' has no effect since the 'import' statement does not actually import any part of the foreign schema tree, just the top-level groupings and typedefs. Consequently, the algorithm that maps a single YANG module to DSDL should probably ignore it. Probably the most common use of the 'augment' statement is for applying a grouping with additional content that is added at a specified location inside the grouping, for example Lhotka Expires January 7, 2009 [Page 15] Internet-Draft YANG-DSDL Mapping July 2008 grouping "def-coll" { container collector { leaf address { ... } leaf port { ... } } } ... container export { uses "def-coll"; augment collector { leaf protocol { ... } } } An minor difficulty here is that the relation between the 'augment' statement and the corresponding 'uses' is only implicit. If there are multiple 'uses' statements, one first has to figure out which of them the 'augment' applies to, i.e., by inspecting all the groupings and finding the one that has "collector" as its top node. In RELAX NG, a similar effect can be achieved by combining pattern definitions, schematically ...original content... ... ...added content... However, there are three notable differences: o It is the original definition that is extended. This means that every reference to the "def-coll" pattern will use the augmented content. o The two definitions can only by combined at their top level. Therefore, the second pattern definition actually cannot add new content inside "collector". In order to be able to do that, the original content of "collector" must be put into a special named pattern (cf. Section 4.2). o The contents of the two definitions are "interleaved", which means that the original and added content may appear in any order and can even be intermixed. In contrast, the semantics of 'augment' in YANG dictates that the added content be placed after the original one. Lhotka Expires January 7, 2009 [Page 16] Internet-Draft YANG-DSDL Mapping July 2008 As a result, the only way for translating 'uses' with 'augment' to RELAX NG seems to be to copy the grouping content to the place where it is used and augment it there. Finally, another practical motivation for using 'augment' may be its 'when' substatement, which allows for conditional content, for example augment "." { when "ifType='wireless'" { ...added content... } } In DSDL schema languages, there is no direct way for specifying conditional content, but it could be simulated by adding Schematron rules that report an error if any part of the conditional content is present and the when condition is not satisfied. In author's opinion, the problems of the 'augment' statement mentioned above can be mitigated by making the following changes to YANG: o Reconsider the use of 'augment' for modifications of an external schema. It would be better to bind the modifications explicitly to the schema that is to be augmented. o Allow 'augment' to appear only as a substatement of 'uses', along with refinements. This way, the relation between the 'augment' and 'uses' statements will be made explicit. o Make the 'when' statement a general mechanism for including conditional content, even outside 'augment'. Lhotka Expires January 7, 2009 [Page 17] Internet-Draft YANG-DSDL Mapping July 2008 6. Mapping Rules for YANG Statements This section describes in each of its subsections the mapping procedure for one YANG statement, as it is currently implemented in the YANG->DSDL translator plug-in for the _pyang_ tool. It is a work in progress and the implementation is open for discussion and changes. In accord with the description of the mapping algorithm in Section 2, we assume the following context: o The data structure (or object) representing the YANG statement being mapped is stored in the "stmt" variable. In particular, "stmt.arg" is the argument of this statement. o A pointer to the RELAX NG element that will become parent of the new XML fragment representing the translation of the current YANG statement is also available. Schematically, the context in the RELAX NG tree looks like this: ... next new schema stuff comes here ... o When we say here that a new element is inserted, it means that it becomes a child of . When we say that is inserted and becomes the new parent element, the situation changes as follows: ... next new schema stuff comes here ... Throughout this section, we use qualified names for all XML elements. The mapping of prefixes to namespace URIs is shown in Table 1. Lhotka Expires January 7, 2009 [Page 18] Internet-Draft YANG-DSDL Mapping July 2008 +--------+-----------------------------------------------------+ | 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 | | | | | nm | urn:ietf:params:xml:ns:netmod:dsdl-attrib:1 | | | | | sch | http://purl.oclc.org/dsdl/schematron | +--------+-----------------------------------------------------+ Table 1 In order to avoid unnecessary complications, this section describes the mapping algorithm for single-file output, i.e., alternative 2 in Section 2. 6.1. The anyxml Statement At the first occurrence of this statement, the following pattern definition is added to the RELAX NG schema (cf. [Vli04], p. 172): Reference to this pattern is then inserted for all 'anyxml' statements. 6.2. The argument Statement Not implemented, see Section 5.2. Lhotka Expires January 7, 2009 [Page 19] Internet-Draft YANG-DSDL Mapping July 2008 6.3. The augment Statement Not implemented, see Section 5.4. 6.4. The belongs-to Statement Insert Dublin Core metadata term . 6.5. The bit Statement Handled within the "bits" type, see Section 6.47.4. 6.6. The case Statement Insert element and handle all substatements. 6.7. The choice Statement Insert element and handle all substatements. 6.8. The config Statement Attach attribute @nm:config to the parent element and use stmt.arg as its value. 6.9. The contact Statement Insert Dublin Core metadata term and use stmt.arg as its content. 6.10. The container Statement Using the procedure outlined in Section 2.1, determine whether the container is optional, and if so, insert the element and make it the new parent element. Then insert element at the current position and use stmt.arg as the value of its @name attribute. Then handle all substatements. 6.11. The default Statement Insert element with stmt.arg as its content. Lhotka Expires January 7, 2009 [Page 20] Internet-Draft YANG-DSDL Mapping July 2008 6.12. The description Statement If the statement is at the module top level, insert Dublin Core metadata term and use stmt.arg as its content. Otherwise, insert DTD compatibility element . In order to get properly formatted in the RELAX NG compact syntax, this element must be inserted as the first child of the parent element. 6.13. The enum Statement Insert element and use stmt.arg as its content. Then handle the 'status' substatement. Other substatements ('value', 'description' and 'reference') are ignored because the element cannot contain foreign elements, see [RNG], Section 6. 6.14. The error-app-tag Statement Not implemented. 6.15. The error-message Statement Handled only within the 'must' statement, see Section 6.30. Ignored in other contexts. 6.16. The extension Statement Not implemented, see Section 5.2. 6.17. The grouping Statement Insert element and set the value of its @name attribute to stmt.arg with prepended full path, i.e., names of all ancestor nodes in the YANG schema tree separated by double underlines - see Section 4.3. Then handle all substatements. 6.18. The import Statement Ignored, as it is assumed that all imported modules are processed by the YANG parser and made available to the mapping algorithm. 6.19. The include Statement Insert and set the value of its @href attribute to stmt.arg concatenated with the file extension ".rng". Lhotka Expires January 7, 2009 [Page 21] Internet-Draft YANG-DSDL Mapping July 2008 6.20. The input Statement Not implemented, see Section 5.3. 6.21. The key Statement Attach attribute @nm:key to the parent element and use stmt.arg as its value. 6.22. The leaf Statement Unless there is the "mandatory true;" substatement or unless an enclosing list declares this leaf among its keys, insert element and make it the new parent element. Then insert element and use stmt.arg as the value of its @name attribute. Then handle all substatements. 6.23. The leaf-list Statement If there is a 'min-elements' substatement with argument value greater than zero, insert and make it the new parent element. Otherwise insert and make it the new parent element. Then insert and use stmt.arg as its value. If there is a 'min-elements' substatement with argument value greater than zero, attach attribute @nm:min-elements to the element and use the argument of the 'min-elements' statement as its value. If there is a 'max-elements' substatement, attach attribute @nm:max- elements to the element and use the argument of the 'max-elements' statement as its value. If there is an 'ordered-by' substatement, attach attribute @nm:ordered-by to the element and use the argument of the 'ordered-by' statement as its value. Then handle all remaining substatements. 6.24. The length Statement Handled within the "string" type, see Section 6.47.8. 6.25. The list Statement Handled exactly as the 'leaf-list' statement, see Section 6.23. Lhotka Expires January 7, 2009 [Page 22] Internet-Draft YANG-DSDL Mapping July 2008 6.26. The mandatory Statement Handled within the 'leaf' statement, see Section 6.22. 6.27. The max-elements Statement Handled within 'leaf-list' or 'list' statements, see Section 6.23. 6.28. The min-elements Statement Handled within 'leaf-list' or 'list' statements, see Section 6.23. 6.29. The module Statement This statement is not specifically handled. The mapping algorithm starts with its substatements. 6.30. The must Statement Insert element. The value of its @test attribute is set to stmt.arg in which all occurrences of the string "$this" are replaced by "." (single dot). If there is an 'error-message' substatement, its argument value is used as the content of , otherwise the element is empty. 6.31. The namespace Statement Attach @ns attribute to the element (the root of the RELAX NG schema) and use stmt.arg as its value. 6.32. The notification Statement Not implemented, see Section 5.3. 6.33. The ordered-by Statement Handled within 'leaf-list' and 'list' statements, see Section 6.23. 6.34. The organization Statement Insert Dublin Core metadata term and use stmt.arg as its content. 6.35. The output Statement Not implemented, see Section 5.3. Lhotka Expires January 7, 2009 [Page 23] Internet-Draft YANG-DSDL Mapping July 2008 6.36. The path Statement Handled within "keyref" type, see Section 6.47.6. 6.37. The pattern Statement Handled within "string" type, see Section 6.47.8. 6.38. The position Statement Not implemented. 6.39. The prefix Statement Not implemented. In RELAX NG, the elements of the target namespace are unprefixed. 6.40. The presence Statement Handled within 'container' statement, see Section 6.10 and also Section 2.1. 6.41. The range Statement Handled within numeric types, see Section 6.47.7. 6.42. The reference Statement If this statement is at module top level, insert Dublin Core metadata term and use stmt.arg as its content. Otherwise insert and use stmt.arg as its content. Within parent element children, insert it as the last of elements (i.e., after translations of 'description' statements), but before any other subelements. 6.43. The revision Statement Insert Dublin Core metadata term and use stmt.arg as its content. 6.44. The rpc Statement Not implemented, see Section 5.3. Lhotka Expires January 7, 2009 [Page 24] Internet-Draft YANG-DSDL Mapping July 2008 6.45. The status Statement Attach attribute @nm:status to the parent element and use stmt.arg as its value. 6.46. The submodule Statement This statement is not specifically handled. The mapping algorithm starts with its substatements. 6.47. The type Statement References to derived types are handled in the same way as references to groupings via the 'uses' statement (Section 6.51): element is inserted with a properly mangled name and definitions of derived types are copied from external modules as necessary. Most YANG built-in types have an equivalent in the XSD datatype library [XSD-D] as shown in Table 2. Lhotka Expires January 7, 2009 [Page 25] Internet-Draft YANG-DSDL Mapping July 2008 +-----------+---------------+----------------------------------+ | YANG type | XSD type | Meaning | +-----------+---------------+----------------------------------+ | int8 | byte | 8-bit integer value | | | | | | int16 | short | 16-bit integer value | | | | | | int32 | int | 32-bit integer value | | | | | | int64 | long | 64-bit integer value | | | | | | uint8 | unsignedByte | 8-bit unsigned integer value | | | | | | uint16 | unsignedShort | 16-bit unsigned integer value | | | | | | uint32 | unsignedInt | 32-bit unsigned integer value | | | | | | uint64 | unsignedLong | 64-bit unsigned integer value | | | | | | float32 | float | 32-bit IEEE floating-point value | | | | | | float64 | double | 64-bit IEEE floating-point value | | | | | | string | string | character string | | | | | | boolean | boolean | "true" or "false" | | | | | | binary | base64Binary | binary data in base64 encoding | +-----------+---------------+----------------------------------+ Table 2: Selected datatypes from the W3C XML Schema Type Library Details about the mapping of individual YANG built-in types are given in the following subsections. 6.47.1. The empty Type Insert empty element. 6.47.2. The boolean and binary Types These two built-in types do not allow any restrictions and are mapped simply by inserting element whose @type attribute is set to stmt.arg mapped according to Table 2. Lhotka Expires January 7, 2009 [Page 26] Internet-Draft YANG-DSDL Mapping July 2008 6.47.3. The instance identifier Type This YANG built-in type has no equivalent in the XSD datatype library and is mapped to the RELAX NG "string" type: 6.47.4. The bits Type Insert element and insert under it for each 'bit' substatement the following XML fragment: bit_name where bit_name is the name of the bit as found in the argument of the corresponding 'bit' statement. 6.47.5. The enumeration and union Types Insert and handle all substatements. 6.47.6. The keyref type As there is no suitable counterpart for the YANG built-in "keyref" type in the XSD datatype library, this type is mapped to "string" by inserting element with @type attribute set to "string". In addition, element is inserted as child of which checks that a 'list' entry with the corresponding value of the key exists. 6.47.7. The numeric Types YANG built-in numeric types are "int8", "int16", "int32", "int64", "uint8", "uint16", "uint32", "uint64", "float32" and "float64". They are handled by inserting element with @type attribute set to stmt.arg mapped according to Table 2. All numeric types support the 'range' restriction, which is handled in the following way: o If the range expression consists of a single range part, insert the pair of RELAX NG facets ... and Lhotka Expires January 7, 2009 [Page 27] Internet-Draft YANG-DSDL Mapping July 2008 ... Their contents are the lower and upper bound of the range part, respectively. If the range part consists of a single number, both "minInclusive" and "maxInclusive" facets use this value as their content. If the lower bound is "min", the "minInclusive" facet is omitted and if the upper bound is "max", the "maxInclusive" facet is omitted. o If the range expression has multiple parts separated by "|", then repeat the element once for every range part and wrap them all in element. Inside each element, the corresponding range part is handled as described in the previous item. For example, the 'typedef' statement typedef rt { type int32 { range "-6378..0|42|100..max"; } } translates to the following RELAX NG fragment: -6378 0 42 42 100 6.47.8. The string Type This type is mapped by inserting the element with the @type attribute set to "string". For the 'pattern' restriction, insert element with @name attribute set to "pattern". The argument of the 'pattern' statement (regular expression) becomes the content of this element. Lhotka Expires January 7, 2009 [Page 28] Internet-Draft YANG-DSDL Mapping July 2008 The 'length' restriction is handled in the same way as the 'range' restriction for the numeric types, with the additional twist that if the length expression has multiple parts, the "pattern" facet ... if there is any, must be repeated inside each copy of the element, i.e., for each length part. 6.48. The typedef Statement Handled exactly as the 'grouping' statement, see Section 6.17. 6.49. The unique Statement Insert element. Its test checks that no two list items (sibling elements) have the same combination of values of leafs listed in stmt.arg. The content of the element, i.e., the error message, is formed by a concatenation of "Not unique: " and stmt.arg. 6.50. The units Statement Attach attribute @nm:units to the parent element and use stmt.arg as its value. 6.51. The uses Statement 1. Check whether the grouping that the statement refers to is defined in the same module that is being translated. If it is so, go to step 4. 2. [the grouping is defined in another module] If the same grouping has been already used in the module that is being translated, go to step 4. 3. [first use of an external grouping] Copy the grouping definition from the external module and install its translation according to Section 6.17 with a properly mangled name (see Section 4.3). 4. Insert element and set its @name attribute to stmt.arg after performing the name mangling procedure described in Section 4.3, taking into account whether the grouping is local or external. Handling of substatements, and in particular the refinement statements, is not implemented yet. Lhotka Expires January 7, 2009 [Page 29] Internet-Draft YANG-DSDL Mapping July 2008 6.52. The value Statement Not implemented. 6.53. The when Statement Not implemented, see Section 5.4. 6.54. The yang-version Statement Not implemented. Its stmt.arg may be checked by the mapping algorithm in order to make sure that the module is compatible. 6.55. The yin-element Statement Not implemented, see Section 5.2. Lhotka Expires January 7, 2009 [Page 30] Internet-Draft YANG-DSDL Mapping July 2008 7. References [XML] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fourth Edition)", World Wide Web Consortium Recommendation REC- xml-20060816, August 2006, . [XSD-D] Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes Second Edition", World Wide Web Consortium Recommendation REC-xmlschema-2-20041028, October 2004, . [YANG] Bjorklund, M., Ed., "YANG - A data modeling language for NETCONF", draft-ietf-netmod-yang-00 (work in progress), May 2008. [RNG-CS] Clark, J., Ed., "RELAX NG Compact Syntax", OASIS Committee Specification 21 November 2002, November 2002. [RNG-DTD] Clark, J., Ed. and M. Murata, Ed., "RELAX NG DTD Compatibility", OASIS Committee Specification 3 December 2001, December 2001. [DCMT] DCMI, "DCMI Metadata Terms", January 2008. [RFC3216] Elliott, C., Harrington, D., Jason, J., Schoenwaelder, J., Strauss, F., and W. Weiss, "SMIng Objectives", RFC 3216, December 2001. [DSDL] ISO/IEC, "Document Schema Definition Languages (DSDL) - Part 1: Overview", ISO/IEC 19757-1, 11 2004. [RNG] ISO/IEC, "Document Schema Definition Languages (DSDL) - Part 2: Regular-Grammar-Based Validation - RELAX NG", ISO/ IEC 19757-2, 2002. [Schtrn] ISO/IEC, "Document Schema Definition Languages (DSDL) - Part 3: Rule-Based Validation - Schematron", ISO/ IEC 19757-3, 2004. [DSRL] ISO/IEC, "Document Schema Definition Languages (DSDL) - Part 8: Document Schema Renaming Language - DSRL", ISO/ IEC 19757-8, 2006. [Vli04] van der Vlist, E., "RELAX NG", O'Reilly , 2004. [1] Lhotka Expires January 7, 2009 [Page 31] Internet-Draft YANG-DSDL Mapping July 2008 [2] Lhotka Expires January 7, 2009 [Page 32] Internet-Draft YANG-DSDL Mapping July 2008 Appendix A. Translation of the DHCP Data Model This appendix demonstrates output of the YANG->DSDL mapping algorithm applied to the "canonical" DHCP tutorial [1] data model. It is presented as a single-file annotated RELAX NG schema (output alternative 1 in Section 2). Appendix A.1 shows the result of the mapping algorithm in the RELAX NG XML syntax and Appendix A.2 the same in the compact syntax, which was obtained using the Trang tool [2]. The long regular expressions for IP addresses etc. would exceed the limit of 72 characters per line, so they were replaced by a dummy text. Other than that, the results of the automatic translations were not changed. A.1. XML Syntax yang-central.org Partial data model for DHCP, based on the config of the ISC DHCP reference implementation. YANG module 'dhcp' (automatic translation) configuration and operational parameters for a DHCP server. 7200 The default-lease-time must be less than max-lease-time Lhotka Expires January 7, 2009 [Page 33] Internet-Draft YANG-DSDL Mapping July 2008 600 ethernet token-ring fddi Lhotka Expires January 7, 2009 [Page 34] Internet-Draft YANG-DSDL Mapping July 2008 ... IPv4 address regexp ... ... IPv6 address regexp ... ... date-and-time regexp ... A reusable list of subnets Allows BOOTP clients to get addresses in this range Lhotka Expires January 7, 2009 [Page 35] Internet-Draft YANG-DSDL Mapping July 2008 Options in the DHCP protocol See: RFC 2132, sec. 3.8 See: RFC 2132, sec. 3.17 7200 Lhotka Expires January 7, 2009 [Page 36] Internet-Draft YANG-DSDL Mapping July 2008 ... IPv4 prefix regexp ... ... IPv6 prefix regexp ... ([\p{L}\p{N}]+\.)*[\p{L}\p{N}] A.2. Compact Syntax default namespace = "http://example.com/ns/dhcp" namespace a = "http://relaxng.org/ns/compatibility/annotations/1.0" namespace dc = "http://purl.org/dc/terms" namespace dsrl = "http://purl.oclc.org/dsdl/dsrl" namespace nm = "urn:ietf:params:xml:ns:netmod:dsdl-attrib:1" namespace sch = "http://purl.oclc.org/dsdl/schematron" dc:creator [ "yang-central.org" ] dc:description [ "Partial data model for DHCP, based on the config of\x{a}" ~ "the ISC DHCP reference implementation." ] dc:source [ "YANG module 'dhcp' (automatic translation)" ] start = ## configuration and operational parameters for a DHCP server. element dhcp { [ nm:units = "seconds" ] element max-lease-time { xsd:unsignedInt >> dsrl:default-content [ "7200" ] }?, [ nm:units = "seconds" ] element default-lease-time { Lhotka Expires January 7, 2009 [Page 37] Internet-Draft YANG-DSDL Mapping July 2008 xsd:unsignedInt >> sch:assert [ test = ". <= ../max-lease-time" "The default-lease-time must be less than max-lease-time" ] >> dsrl:default-content [ "600" ] }?, __subnet-list, element shared-networks { [ nm:key = "name" ] element shared-network { element name { xsd:string }, __subnet-list }* }?, [ nm:config = "false" ] element status { [ nm:key = "address" ] element leases { element address { inet-types__ip-address }, element starts { yang-types__date-and-time }?, element ends { yang-types__date-and-time }?, element hardware { element type { "ethernet" | "token-ring" | "fddi" }?, element address { yang-types__phys-address }? }? }* }? }? inet-types__ip-address = inet-types__ipv4-address | inet-types__ipv6-address inet-types__ipv4-address = xsd:string { pattern = "... IPv4 address regexp ..." } inet-types__ipv6-address = xsd:string { pattern = "... IPv6 address regexp ..." } yang-types__date-and-time = xsd:string { pattern = "... date-and-time regexp ..." } yang-types__phys-address = xsd:string Lhotka Expires January 7, 2009 [Page 38] Internet-Draft YANG-DSDL Mapping July 2008 ## A reusable list of subnets __subnet-list = [ nm:key = "net" ] element subnet { element net { inet-types__ip-prefix }, element range { ## Allows BOOTP clients to get addresses in this range element dynamic-bootp { empty }?, element low { inet-types__ip-address }, element high { inet-types__ip-address } }, ## Options in the DHCP protocol element dhcp-options { [ nm:ordered-by = "user" ] ( ## See: RFC 2132, sec. 3.8 element router { inet-types__host }*), ## See: RFC 2132, sec. 3.17 element domain-name { inet-types__domain-name }? }?, [ nm:units = "seconds" ] element max-lease-time { xsd:unsignedInt >> dsrl:default-content [ "7200" ] }? }* inet-types__ip-prefix = inet-types__ipv4-prefix | inet-types__ipv6-prefix inet-types__ipv4-prefix = xsd:string { pattern = "... IPv4 prefix regexp ..." } inet-types__ipv6-prefix = xsd:string { pattern = "... IPv6 prefix regexp ..." } inet-types__host = inet-types__ip-address | inet-types__domain-name inet-types__domain-name = xsd:string { pattern = "([\p{L}\p{N}]+\.)*[\p{L}\p{N}]" } Lhotka Expires January 7, 2009 [Page 39] Internet-Draft YANG-DSDL Mapping July 2008 Author's Address Ladislav Lhotka CESNET Email: lhotka@cesnet.cz Lhotka Expires January 7, 2009 [Page 40] Internet-Draft YANG-DSDL Mapping July 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. Lhotka Expires January 7, 2009 [Page 41]