idnits 2.17.1 draft-mahy-canmod-dsdl-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 19. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 3281. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 3292. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 3299. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 3305. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 38 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 1524: '...sing annotation called "status" SHOULD...' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year == Line 1085 has weird spacing: '...element t1-ti...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 8, 2008) is 5761 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: '28' is mentioned on line 2531, but not defined == Missing Reference: '29' is mentioned on line 2533, but not defined == Missing Reference: '30' is mentioned on line 2536, but not defined == Missing Reference: '31' is mentioned on line 2539, but not defined == Missing Reference: '32' is mentioned on line 2541, but not defined == Missing Reference: '33' is mentioned on line 2543, but not defined == Missing Reference: '34' is mentioned on line 2545, but not defined == Missing Reference: '35' is mentioned on line 2547, but not defined -- Looks like a reference, but probably isn't: 'TODO' on line 1814 == Missing Reference: '36' is mentioned on line 2549, but not defined -- Looks like a reference, but probably isn't: '0-5' on line 2790 -- Looks like a reference, but probably isn't: '0-4' on line 2790 -- Looks like a reference, but probably isn't: '0-9' on line 2790 -- Looks like a reference, but probably isn't: '1-9' on line 2199 == Missing Reference: '37' is mentioned on line 2710, but not defined == Missing Reference: '38' is mentioned on line 2724, but not defined == Missing Reference: '39' is mentioned on line 2717, but not defined == Missing Reference: '40' is mentioned on line 2717, but not defined == Missing Reference: '41' is mentioned on line 2717, but not defined == Missing Reference: '42' is mentioned on line 2731, but not defined == Missing Reference: '43' is mentioned on line 2767, but not defined == Missing Reference: '44' is mentioned on line 2837, but not defined == Missing Reference: '45' is mentioned on line 2838, but not defined == Missing Reference: '46' is mentioned on line 2884, but not defined == Missing Reference: '47' is mentioned on line 2893, but not defined == Missing Reference: '01' is mentioned on line 2790, but not defined -- Looks like a reference, but probably isn't: '0-9a-fA-F' on line 2789 -- Looks like a reference, but probably isn't: 'TM' on line 3221 ** Obsolete normative reference: RFC 4741 (ref. '1') (Obsoleted by RFC 6241) == Outdated reference: A later version (-13) exists of draft-ietf-netmod-yang-00 == Outdated reference: A later version (-01) exists of draft-lhotka-yang-dsdl-map-00 Summary: 3 errors (**), 0 flaws (~~), 26 warnings (==), 15 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETMOD WG R. Mahy 3 Internet-Draft Plantronics 4 Intended status: Informational S. Chisholm 5 Expires: January 9, 2009 Nortel 6 L. Lhotka 7 CESNET 8 July 8, 2008 10 Representing Netconf Data Models using Document Schema Definition 11 Languages (DSDL) 12 draft-mahy-canmod-dsdl-02.txt 14 Status of this Memo 16 By submitting this Internet-Draft, each author represents that any 17 applicable patent or other IPR claims of which he or she is aware 18 have been or will be disclosed, and any of which he or she becomes 19 aware will be disclosed, in accordance with Section 6 of BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF), its areas, and its working groups. Note that 23 other groups may also distribute working documents as Internet- 24 Drafts. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 The list of current Internet-Drafts can be accessed at 32 http://www.ietf.org/ietf/1id-abstracts.txt. 34 The list of Internet-Draft Shadow Directories can be accessed at 35 http://www.ietf.org/shadow.html. 37 This Internet-Draft will expire on January 9, 2009. 39 Copyright Notice 41 Copyright (C) The IETF Trust (2008). 43 Abstract 45 This document describes a concrete approach for representing Netconf 46 and other IETF data models using the RelaxNG schema language and the 47 Schematron validation language, which are both part of ISO's Document 48 Schema Definition Languages (DSDL) standard. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 53 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 54 3. RelaxNG . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 55 4. Processing annotations for additional validation . . . . . . . 8 56 4.1. The 'unique' annotation . . . . . . . . . . . . . . . . . 8 57 4.2. The 'key' annotation . . . . . . . . . . . . . . . . . . . 9 58 4.3. The 'keyref' annotation . . . . . . . . . . . . . . . . . 11 59 4.4. The 'mustUse' annotation . . . . . . . . . . . . . . . . . 13 60 4.5. The 'infoType' annotation . . . . . . . . . . . . . . . . 13 61 4.6. Additional validation rules . . . . . . . . . . . . . . . 14 62 5. Validating instance data automatically with Schematron . . . . 15 63 5.1. Schematron patterns for data model validation . . . . . . 16 64 5.2. Phases of validation . . . . . . . . . . . . . . . . . . . 18 65 6. Validating the data model itself . . . . . . . . . . . . . . . 19 66 7. Documentation annotations . . . . . . . . . . . . . . . . . . 19 67 7.1. Creator information . . . . . . . . . . . . . . . . . . . 19 68 7.2. Descriptions, defaults, and units . . . . . . . . . . . . 20 69 7.3. Semantic Hints . . . . . . . . . . . . . . . . . . . . . . 21 70 8. Extensibility Model . . . . . . . . . . . . . . . . . . . . . 22 71 8.1. Pattern scoping using modules . . . . . . . . . . . . . . 22 72 8.2. Extending existing modules (forward compatibility) . . . . 23 73 8.3. Backwards Compatibility . . . . . . . . . . . . . . . . . 24 74 8.4. Default Values . . . . . . . . . . . . . . . . . . . . . . 25 75 9. Netconf Specifics . . . . . . . . . . . . . . . . . . . . . . 26 76 9.1. Get and Get-config operations . . . . . . . . . . . . . . 26 77 9.2. Edit-config operations . . . . . . . . . . . . . . . . . . 26 78 9.3. Netconf notifications . . . . . . . . . . . . . . . . . . 27 79 9.4. New netconf actions . . . . . . . . . . . . . . . . . . . 29 80 9.5. Netconf specific error messages . . . . . . . . . . . . . 29 81 9.6. Scope of an XML document . . . . . . . . . . . . . . . . . 31 82 10. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 32 83 10.1. Cardinality . . . . . . . . . . . . . . . . . . . . . . . 33 84 10.2. Operations on managed objects . . . . . . . . . . . . . . 33 85 10.3. Element and Attribute Status . . . . . . . . . . . . . . . 34 86 10.4. Additional Conformance Information . . . . . . . . . . . . 35 87 10.5. Schema Level Conformance - Server-side . . . . . . . . . . 35 88 10.6. Schema Level Conformance - Client-side . . . . . . . . . . 35 89 11. Grading against the requirements . . . . . . . . . . . . . . . 35 90 11.1. Met requirements . . . . . . . . . . . . . . . . . . . . . 36 91 11.2. Met applicable subset . . . . . . . . . . . . . . . . . . 42 92 11.3. Not Met . . . . . . . . . . . . . . . . . . . . . . . . . 43 93 12. Full Examples . . . . . . . . . . . . . . . . . . . . . . . . 44 94 13. Example Standalone Schematron . . . . . . . . . . . . . . . . 49 95 14. "DML" Annotations Schema . . . . . . . . . . . . . . . . . . . 51 96 15. Yang Mapping . . . . . . . . . . . . . . . . . . . . . . . . . 53 97 15.1. Literal Mappings . . . . . . . . . . . . . . . . . . . . . 54 98 15.2. Non-literal Mappings . . . . . . . . . . . . . . . . . . . 54 99 15.3. Information intentionally not Mapped . . . . . . . . . . . 55 100 16. Security Considerations . . . . . . . . . . . . . . . . . . . 55 101 17. IANA Consideration . . . . . . . . . . . . . . . . . . . . . . 55 102 18. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 55 103 Appendix A. XSLT Transform from processing annotation to 104 Schematron . . . . . . . . . . . . . . . . . . . . . 56 105 Appendix B. Data type library . . . . . . . . . . . . . . . . . . 56 106 B.1. About Domain-Specific Pattern Libraries . . . . . . . . . 58 107 B.1.1. Internet Data Types . . . . . . . . . . . . . . . . . 59 108 B.1.2. IEEE Data Types . . . . . . . . . . . . . . . . . . . 63 109 Appendix C. DHCP schema in Relax XML format . . . . . . . . . . . 63 110 19. References . . . . . . . . . . . . . . . . . . . . . . . . . . 68 111 19.1. Normative References . . . . . . . . . . . . . . . . . . . 68 112 19.2. Informational References . . . . . . . . . . . . . . . . . 69 113 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 71 114 Intellectual Property and Copyright Statements . . . . . . . . . . 72 116 1. Introduction 118 The NETCONF Working Group has completed a base protocol [1] used for 119 configuration management. This base specification defines protocol 120 bindings and an XML [6] container syntax for configuration and 121 management operations, but does not include a modeling language or 122 accompanying rules for how to model configuration and status 123 information (in XML syntax) carried by Netconf. The IETF Operations 124 area has a long tradition of defining data for SNMP [16] Management 125 Information Bases (MIBs) using the SMI [17] to model its data. While 126 this specific modeling approach has a number of well-understood 127 problems, most of the data modeling features provided by SMI are 128 still considered extremely important. Simply modeling the valid 129 syntax rather than additional semantic relationships has caused 130 significant interoperability problems in the past. 132 The Netconf community concluded that a data modeling framework is 133 needed to support ongoing development of IETF and vendor-defined 134 management information modules. The NETMOD Working Group was 135 chartered to address this problem, by defining a "human-friendly" 136 modeling language called YANG [5], a "tool-friendly" modeling 137 language, and a mapping from YANG to the tool-friendly language. 138 This document describes a "tool-friendly" language suitable for 139 Netconf, but flexible enough to be suitable for other uses. 141 The approach to data modeling described here uses the two most mature 142 parts of the ISO Document Schema Definition Languages (DSDL) [28] 143 multi-part standard: Relax NG and Schematron (see also Part 1 of DSDL 144 - the overview [19] and an overview presentation on DSDL [29]). The 145 proposal then goes on to define additional processing and 146 documentation annotation schema. Relax NG [10] is a mature, 147 traditional schema language for validating the structure of an XML 148 document. Schematron [9] is a rule-based schema validation language 149 which uses XPath [11] expressions to validate content and relational 150 constraints. In addition, this document defines and reuses various 151 annotation schema which can provide additional metadata about 152 specific elements in the data model such as textual descriptions, 153 default values, relational integrity key definitions, and whether 154 data is configuration or status data. 156 This combination was created to specifically address a set of 157 Netconf-specific modeling requirements, and in addition should be 158 useful as a general purpose data modeling solution useful for other 159 IETF working groups. The authors believe that reusing schema work 160 being developed and used by other standards bodies provides 161 substantial long-term benefits to the IETF management community, so 162 this proposal attempts to reuse as much existing work as possible. 164 2. Overview 166 This document describes a concrete data modeling environment which 167 meets the Netconf data modeling design team requirements but is 168 otherwise very general purpose in nature. The proposal is quite 169 modular and draws from a number of existing standards and well- 170 understood schemas. Relevant requirements will be mentioned in each 171 major section, but a table of requirements is included in Section 11. 172 In order to make it easier to visualize this approach and its mapping 173 from YANG, we produced a non-trivial data model description to 174 generate an instance document compatible with the DHCP configuration 175 example document in Appendix C of the requirements document. The 176 full example data model document is shown in Section 12. 178 This document starts in Section 3 by describing the use of RelaxNG to 179 model XML syntax, element and attribute names, containment 180 relationships, cardinality, data types, and simple range and pattern 181 restrictions. RelaxNG can use its own basic type definitions or 182 reuse the W3C XML Schema Datatypes [7] definitions. It is also 183 straightforward to reference one or more external libraries of data 184 types, such as the IP and IEEE networking type libraries defined in 185 Appendix B. 187 While using an existing schema language is a good start toward the 188 data modeling requirements, a data modeling solution also needs 189 additional semantics conveyed. Section 4 describes "processing 190 annotations" which describe validation rules for instance documents 191 based on the data model. These annotations are incorporated inline 192 with the RelaxNG schema. Most of these validation rules can be 193 validated either in source code generated by a human or in a machine 194 readable way. The machine readable rules make extensive use of XPath 195 [11] expressions. [TODO: illustration here] If desired, an XSLT [12] 196 (Extensible Stylesheet Language: Transformations) document described 197 in Appendix A can convert the machine readable rules in a specific 198 data model document into a Schematron validation document for that 199 data model. This conversion is done only once each time the data 200 model is modified. 202 Section 5 describes how a Schematron document is used to validate an 203 instance document, and describes a set of three different levels or 204 phases of validation that this proposal supports. Section 6 205 describes how Schematron can validate a very different set of rules 206 on data model documents to make sure that they comply with specific 207 conventions. This document defines a set of Schematron rules in 208 Appendix B, which are compatible with content restrictions imposed by 209 Netconf. 211 Section 7 describes how to attach document metadata (ex: title, 212 author, dates), per element descriptions, semantic hints about 213 elements, default values, units, and conformance status (active, 214 deprecated, obsolete) to the data model as documentation annotations. 215 Most of the document metadata is described using the Dublin Core [2] 216 metadata schemas. Default values are described using the DTD 217 (Document Type Definition) compatibility annotations [30]. The 218 definition for units is copied from the units definitions used by the 219 Geographic Markup Language GML [21]. The rest of these annotations 220 are defined in a RelaxNG annotation schema in Section 14. 222 Section 8 describes the extensibility and versioning model envisioned 223 by this proposal. It also describes the interaction between default 224 values and extensibility in this proposal. 226 Finally, Section 9 describes how to use the data model to support 227 Netconf-specific requirements. In particular, this section describes 228 how to model Netconf notifications [4] of a nearly full DHCP scope 229 and an IP address conflict, a Netconf-specific error response, and 230 the definition of a new action to revoke a lease. 232 3. RelaxNG 234 RelaxNG is an XML schema language developed by OASIS [31] and then 235 adopted by ISO as Part 2 of DSDL. It is now a full ISO standard. 236 RelaxNG has a reputation that it is easy to read and easy to learn. 237 RelaxNG has a solid theoretical basis, and is the canonical schema 238 format for several major W3C standards (XHTML [22], SVG [23], XML 239 signature [24], RDF [25]). RelaxNG includes strong support for XML 240 namespaces [8], treats attributes and elements similarly, and can 241 define schemas which support (or do not support) unordered content. 242 It can use integral types or an external data type library such as 243 W3C XML Schema Datatypes. 245 Unlike W3C XML Schema [26] (referred to later as XSD or WXS), RelaxNG 246 only describes the structure and contents of XML documents. RelaxNG 247 intentionally does not try to modify the information set of an XML 248 document. For example, it does not address default values (supported 249 in XML Data Type Definitions) or key and keyref types (supported in 250 W3C XML Schema). Since RelaxNG supports arbitrary annotations, other 251 languages can add semantics to a RelaxNG schema. Indeed, the RelaxNG 252 DTD compatibility schema includes annotations for default values. 253 The rest of DSDL also follows this modular philosophy. Part 6 of 254 DSDL (work not started) is reserved for path-based integrity 255 constraints (analogous to XSD keys and keyrefs). 257 RelaxNG has both an XML representation and a Compact representation. 258 They can be converted automatically using open source tools such as 259 Trang [32]. Trang can also convert either form of RelaxNG to XSD 260 format automatically with some minor restrictions (RelaxNG can 261 represent some schema which XSD cannot). This document will use the 262 Compact form for brevity and readability throughout. 264 In RelaxNG Compact syntax, the symbols '?' (one or zero), '+' (one or 265 more), and '*' (zero or more) have their familiar meaning. The 266 symbol ',' indicates the next pattern follows in order, the symbol 267 '&' indicates that the next element can come before or after the 268 current pattern, and the '|' symbol indicates a choice among 269 patterns. Below is an example of a RelaxNG Compact schema snippet, 270 simplified from the schema for the full example in this proposal. 272 start = element-dhcp 274 element-dhcp = element dhcp { 275 element subnet { 276 element network { ipv4-address-content }, 277 element prefix-length { 278 xsd:short { minInclusive = "0" maxInclusive = "32" } 279 } 280 element-range?, 281 element leases { 282 element-lease* 283 }?, 284 }* 285 } 287 element-range = element range { 288 element low { ipv4-address-content }, 289 element high { ipv4-address-content } 290 } 292 element-lease = element lease { 293 attribute ip-address { ipv4-address-content }, 294 element starts { xsd:dateTime }, 295 element ends { xsd:dateTime }, 296 element mac-address { mac-address-content } 297 } 299 A full tutorial on RelaxNG [33] is beyond the scope of this document. 300 This proposal will try to introduce unfamiliar concepts as they 301 appear, but in some cases, the reader may wish to consult an outside 302 reference or tutorial. More information on RelaxNG is available in 303 relaxng book [18] and at the following web sites: 304 305 306 308 4. Processing annotations for additional validation 310 RelaxNG readily accepts annotations in other namespaces. For 311 example, one of the RelaxNG DTD compatibility annotations is used to 312 specify descriptive text about the element (shown as an initial 313 annotation); another compatibilty annotation specifies default values 314 (shown as a following annotation): 316 namespace compat = "http://relaxng.org/ns/compatibility/annotations/1.0" 318 element ice-cream { 319 [ 320 compat:documentation ["Defines two flavors or ice cream"] 321 ] 322 ("vanilla" | "chocolate") >> compat:defaultValue ["chocolate"] 323 } 325 or in Relax NG XML format: 327 328 329 Defines two flavors of ice cream 330 331 332 vanilla 333 chocolate 334 335 chocolate 336 338 There are a variety of reasons to add annotations, but this section 339 of the proposal focuses on annotations which can be used to define 340 further processing on an instance document, especially validation. 341 Processing annotations could be implemented automatically by a 342 machine or by a human reading descriptive text in the data model who 343 implements source code. This document defines a new schema for both 344 processing annotations and documentation annotations. This section 345 begins by explaining the semantics of each of the processing 346 annotations defined here. In our examples, this annotation schema 347 will use the namespace prefix 'dml'. 349 4.1. The 'unique' annotation 351 The 'unique' annotation element specifies an expression (usually an 352 element) that needs to be unique within a list. The annotation can 353 follows any element definition which has a cardinality greater than 354 one ('+' or '*'). The content of the unique element is an XPath [11] 355 expression which is evaluated relative to the element it follows (and 356 its immediate parent). For example, in the following example, the 357 'port' element has to be unique within all other service elements 358 under the servers element: 360 element-servers = element servers { 361 element service { 362 element name { xsd:string }, 363 element port { xsd:unsignedShort } 364 >> dml:unique ["port"] 365 }+ 366 } 367 # '//servers/service' must have only one 'port' with a specific value. 369 In terms of XPath expressions, this means that in the context 370 '//servers/service/port', the XPath expression 'count( //servers/ 371 service[port=current()] ) = 1' needs to be true. (Does the number of 372 service elements with a port element equal to the value of the 373 current port element equal 1?). Expressing this rule as a series of 374 XPath expressions makes the rule more precise, but it also enables a 375 conversion of this constraint to a Schematron validation rule as 376 discussed in Section 5. In the following snippet of instance 377 document, the second http service is not allowed since its port 378 number conflicts with another service. 380 381 382 ssh 383 2222 384 385 386 http 387 80 388 389 390 http 391 2222 392 393 395 This syntax is also capable of specifying that the combination of one 396 or more fields is required to be unique. 398 4.2. The 'key' annotation 400 In many cases, something is unique in a list because it is actually a 401 key used in cross-element relationships. The 'key' annotation 402 specifies that an expression can be used as a unique lookup key among 403 the elements of a list (an element with cardinality greater than 404 one). In addition, this key can be used in another element which is 405 a key reference (keyref) to provide referential integrity between 406 these related elements. As with the 'unique' element, the content of 407 the 'key' element is an XPath expression which is evaluated relative 408 to the element it follows (and its immediate parent). 410 As shown in the next example, the key can be a compound key (formed 411 from more than one element or attribute), and it can reference 412 descendants of arbitrary depth to form the key. The key to the 413 subnet element in the instance document is "192.168.24.0/24". 415 Keys are critical for any data that will be configured or for any 416 data that will be referenced via a keyref statement. Therefore key 417 definitions are mandatory for all lists except as described below. 418 For convenience, some lists have an implicit key: 419 o list elements which have an 'id' (key) attribute with the type 420 xsd:ID; 421 o list elements which have only an 'xml:lang' (key) attribute and 422 only contain character data (no subelements); 423 o list elements which have no character data and a single mandatory 424 (key) attribute; and 425 o list elements which contain only character data (no subelements) 426 and which have no attributes (the character data is the key). 428 element-dhcp = element dhcp { 429 element subnet { 430 element prefix { 431 element network { ipv4-address-content }, 432 element prefix-length { 433 xsd:short { minInclusive = "0" maxInclusive = "32" } 434 } 435 }, 436 element-range 437 >> dml:key ["concat(prefix/network, '/', prefix/prefix-length)"] 438 }+ 439 } 441 442 443 444 192.168.24.0 445 24 446 447 448 192.168.24.20 449 192.168.24.250 450 451 453 455 Note that several module validation rules can be defined for 456 convenience. For example: If an XML element with a maximum 457 cardinality greater than one (for brevity a 'list element') has an 458 'id' attribute with type 'ID', the validation rules could use the 459 'id' attribute as the list key. If a list element consists only 460 of a single text value and no attributes, the validation rules 461 could use the text value as the key unless a different key 462 definition is explicitly provided. Likewise, if a list element 463 consists of an empty value and has only one attribute, the 464 attribute could be used as the key unless a different key 465 definition is explicitly provided. 467 4.3. The 'keyref' annotation 469 The contents of the 'keyref' annotation contains an XPath expression 470 which points to the element under which a 'key' annotation was 471 defined. In the example in the previous section, the key element 472 annotates the 'subnet' element. Therefore a keyref annotation 473 referring to a specific subnet element will use the XPath expression 474 '//dhcp:subnet'. Note that keyrefs could often refer to elements in 475 a different namespace. For example, in the example that follows, the 476 dhcp:interfaces-filter element consists of a list of tokens which 477 refer to keys defined under the //int:interface schema definition. 479 element-subnet = element subnet { 480 element network { ipv4-address-content }, 481 element prefix-length { 482 xsd:short { minInclusive = "0" maxInclusive = "32" } 483 }, 484 element interface-filter { 485 element interface { 486 xsd:token 487 >> dml:keyref ["//int:interface"] 488 }+ 489 } 490 } 491 element-interfaces = element int:interfaces { 492 element int:interface { 493 element int:ifIndex { xsd:token }, 494 element int:ifType { xsd:token } 495 >> dml:key ["int:ifIndex"] 496 }+ 497 } 499 503 504 505 10.1.1.0 506 24 508 509 lo0 510 en2 511 512 513 514 515 lo0 516 en1 517 en2 518 519 521 Be aware that in some cases, a list may consist of elements which 522 have both a key and keyref (a list of keyrefs). 524 4.4. The 'mustUse' annotation 526 An element in the data model tagged with the 'mustUse' annotation 527 indicates that the tagged element needs to appear in the instance 528 document whenever its parent appears. Items with a defaultValue 529 annotation cannot also have a mustUse annotation. 531 In many schemas, there is a facility for using fragments or 532 patches of XML documents. (Netconf uses these fragments 533 extensively in edit-config operations for example). In order to 534 accommodate these fragments, the cardinality of an otherwise 535 "required" element may allow the element to be optional in an XML 536 fragment. The mustUse annotation provides a way to express what 537 is actually required in this situation. 539 See also the client-side conformance discussion in Section 10. 541 4.5. The 'infoType' annotation 543 The 'infoType' annotation indicates the category of data that applies 544 to the annotated element and all its children until another 545 'infoType' annotation. The content of the 'infoType' element is an 546 enumeration. The 'config' type is the default value. It indicates 547 that the covered data is configuration and that it is at least 548 theoretically possible to include this data in read, write, create, 549 and delete operations. Likewise 'non-config' information can be 550 read, but cannot be included in write, create, and delete operations. 551 (Note: 'non-config' was split into 'status' and 'statistics' 552 information in a previous definition of this language.) 554 The example below indicates that the 'leases' element and all its 555 sub-elements are status information and not suitable for creating, 556 writing, or deleting. 558 element-leases = element leases { 559 element lease { 560 attribute ip-address { ipv4-address-content }, 561 element starts { xsd:dateTime }, 562 element ends { xsd:dateTime }, 563 element mac-address { mac-address-content } 564 }* 565 >> dml:infoType ["non-config"] 566 } 568 In addition, this annotation element has optional minAccess and 569 maxAccess attributes which can override the default list of relevant 570 operations. These attributes are discussed in more detail in 571 Section 10. 573 Finally, the infoType can be extended for Netconf or other protocol- 574 specific extensions. It is used to describe which elements are part 575 of a notification or Netconf RPC action, for example as used in 576 Section 9.3 and Section 9.4 respectively. 578 4.6. Additional validation rules 580 In our DHCP example, the validation statement that "subnets can't 581 overlap" is easy to say in English, but hard to write formally. In 582 addition, some validation tests may be difficult or impossible to 583 evaluate without local state information. The 'manual-validation- 584 rule' annotation provides a natural language explanation of a 585 validation constraint that can only be evaluated by a human. When 586 validation rules (as in Section 5) are automatically generated, a 587 warning will be generated for each manual-validation-rule. 589 element-subnet = element subnet { 590 element network { ipv4-address-content }, 591 element prefix-length { 592 xsd:short { minInclusive = "0" maxInclusive = "32" } 593 } 594 >> dml:manual-validation-rule [xml:lang="en" 595 "Subnets may not overlap"] 596 >> dml:manual-validation-rule [xml:lang="fr" 597 "Les sous-reseaux ne peuvent pas se superposer"] 598 } 600 In addition, the data model can also define additional rules formally 601 by embedding specific Schematron rules. Schematron is a rule-based 602 validation language for XML documents. Schematron patterns define a 603 series of rules using XPath expressions which evaluate to a boolean 604 value. These rules contain human language text which could be used 605 to implement manual validation. The text node of the Schematron 606 assert statement should provide text suitable for a human to write an 607 equivalent validity check. 609 element-dhcp = element dhcp { 610 [ 611 sch:ns [ prefix="dhcp" uri="http://example.org/ns/dhcp" ] 612 sch:pattern [ 613 sch:rule [ 614 context = "//dhcp:dhcp" 615 sch:assert [ 616 test = "dhcp:default-lease-time <= dhcp:max-lease-time" 617 "Default lease time cannot be larger than maximum lease time" 618 ] 619 ] 620 ] 621 ] 622 element default-lease-time { xsd:unsignedInt }?, 623 element max-lease-time { xsd:unsignedInt }?, 624 ... 625 } 627 The preceding example consists of a single rule. In the context of 628 the 'dhcp' element, the value of the 'default-lease-time' element 629 needs to be less than or equal to the value of the 'max-lease-time' 630 element. 632 Both the 'dml:manual-validation-rule' and Schematron 'assert' 633 elements can contain an attribute to convey Netconf-specific error 634 messages. For more information, see Section 9.5. 636 Once these embedded Schematron rules are written, one vendor could 637 enforce these rules in code, while another could validate against the 638 embedded Schematron rules. A vendor can also use the provided XSLT 639 transformation in Appendix A to create a standalone Schematron file 640 from the data model. 642 5. Validating instance data automatically with Schematron 644 ISO Schematron is a rule-based validation language based on XPath 645 expressions. It is Part 3 of the DSDL standard. XPath is an 646 expression language for defining parts of an XML document; it uses 647 path expressions to navigate in XML documents and access XML nodes 648 (elements, attributes, text, namespaces, processing-intructions, 649 comments, and the root/document node. It also includes a library of 650 functions. The XSLT and XLink specifications also rely on XPath 651 expressions and built-in functions. 653 XPath uses path expressions to select nodes or node-sets in an XML 654 document. These path expressions look very much like the expressions 655 you see when you work with a traditional computer file system. While 656 a complete tutorial on Schematron [34] or tutorial on XPath [35] is 657 beyond the scope of this document, we will walk through a simple 658 example to highlight the most important concepts. This example is 659 functionally the same as the example of Schematron embedded in 660 RelaxNG Compact in the last section. More Schematron resources are 661 available here: 662 663 664 666 5.1. Schematron patterns for data model validation 668 Below is a simple Schematron rule. 670 671 672 673 674 676 Default lease time cannot be larger than maximum lease time 677 678 679 680 682 The Schematron validator evaluates the context of each rule, then 683 evaluates each assert or report clause within the rule. Lets look at 684 a more complicated example that is used for insuring that a key is 685 unique within a list context. 687 688 690 The value ifIndex must be unique among all interfaces. 691 692 694 For every ifIndex element, the 'assert' tests if the number of 695 interfaces which have an ifIndex matching the current one (being 696 evaluated) is one. This XPath expression is rather long. Since we 697 will use this idiom repeatedly, we can define a Schematron abstract 698 pattern to express this more succinctly: 700 701 702 703 The key "" needs to be unique 704 within the list at: . 705 706 707 709 710 711 712 713 715 Likewise, we can write Schematron abstract patterns for validating 716 keyref relationships as well. 718 719 720 721 The contents of "" 722 must be a '' with the key 723 "" in this context: 724 . 725 726 727 729 730 731 732 734 735 736 738 Even the Schematron abstract patterns shown above contain paths that 739 a computer could derive automatically. The XSLT stylesheet described 740 in Appendix A could read the data model processing annotations to 741 automatically generate Schematron patterns that use these abstract 742 patterns. The XSLT stylesheet is just calculating the context XPaths 743 by examining the document structure in the RelaxNG schema. Once 744 generated, these rules can be used to test the validity of instance 745 documents. These Schematron tests can provide different levels of 746 validity checking. 748 5.2. Phases of validation 750 Conceptually, an implementation can validate its instance data in 751 different logical phases, adding more tests with each phase. We use 752 three levels or phases for validating an instance document. There is 753 a level of validation which is appropriate even for loose XML 754 document fragments which still maintain their hierarchy (the fragment 755 phase), there is a level of validation appropriate for a cohesive XML 756 document but which may not be able to validate relational integrity 757 checks against some operational state (the standard phase), and there 758 is validation which includes all relational integrity checks (the 759 full validation phase). For example, in Netconf an edit-config 760 operation can cause the replacement a small fragment of XML. A 761 candidate configuration may be waiting for application but can't 762 check the readiness of a piece of hardware that the configuration 763 refers to. 765 From the NETCONF perspective, these three phrases can considered to 766 have the following scope and triggers: 767 1. the fragment phase: This can be run against individual NETCONF 768 operations; should be automatically triggered 769 2. the standard phase: This can be run against the candidate 770 configuration, but won't always pass; should be manually 771 triggered 772 3. the full validation phase: This can be run against a running 773 configuration; should be automatically triggered 775 During the Fragment phase validation: 776 o Verify that the content is appropriate to the operation (by 777 passing a variable to Schematron with the type of operation). See 778 Section 9.2 and Section 9.4 for Netconf specific examples of this 779 additional validation. 781 During Standard phase validation (all rules except for keyref 782 checking): 783 o Verify that mustUse items are present 784 o Check the uniqueness for unique and key annotations 785 o Print a warning if any manual validation rules are present 787 During Full phase validation: add keyref checks. 789 All embedded Schematron will run in the standard phase unless the a 790 'dml:phase' attribute is included with the name of a different phase 791 ('fragment' or 'full'). 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 809 6. Validating the data model itself 811 In addition to validating the instance data, it is necessary to 812 validate the data model document whenever the data model itself is 813 modified. In addition to syntax checks, the content of several of 814 the annotations can be validated. Finally, certain bindings or 815 usages will need to enforce constraints individual data model. 817 For example, Netconf needs the following restrictions: 819 o Elements with cardinality greater than one (lists), which can have 820 more than one child element need to have a key defined. 821 o Mixed content (non-whitespace text nodes interleaved with 822 elements) is not allowed. 823 o All schema modules need to have a top-level version number 824 attribute. 826 Of course, a Schematron file could be written to check these 827 constraints. In the Netconf case, this is unlikely to be needed if 828 data models are usually converted from YANG. 830 7. Documentation annotations 832 This section describes annotations which do not have an effect on 833 validation. 835 7.1. Creator information 837 Metadata about the data model document (ex: title, author, dates) is 838 expressed using a combination of Dublin Core metadata terms, and the 839 DML schema defined in this document. This proposal recommends that 840 all data models include a Dublin Core title, creator, description, 841 and created (creation date) element. Data model authors can include 842 any additional Dublin Core metadata which is relevant. In addition, 843 the DML annotation schema adds an 'organization' annotation and a 844 'contact' annotation. Organization is a human readable string that 845 indicates the organization responsible for the data model. It 846 includes an optional language attribute. Contact is a URI that can 847 be used to reach the author or maintainer of the data model. Using a 848 mailto: URI is recommended. Finally, the version of the data model 849 is expressed in a 'dataModelVersion' annotation. 851 >> dc:title [ "Example schema for DHCP server" ] 852 >> dml:dataModelVersion ["1.0"] 853 >> dc:type ["Dataset"] 854 >> dc:creator [ "Rohan Mahy" ] 855 >> dml:organization [ "as an individual" ] 856 >> dml:contact [ "mailto:rohan@example.org" ] 857 >> dc:created [ "2008-02-13" ] 859 7.2. Descriptions, defaults, and units 861 Default values and semantic descriptions for individual schema items 862 use the RelaxNG DTD compatibility annotations. 864 element default-lease-time { 865 xsd:unsignedInt 866 >> compat:defaultValue ["3600"] >> dml:units ["s"] 867 >> compat:documentation [ xml:lang="en" 868 "The default duration of a DHCP lease in seconds" ] 869 }? 871 Typically default values only apply to a specific version of a data 872 model. Default values which persist for all versions of a module are 873 identified with a special attribute as described in Section 8.4. 875 The 'units' annotation expresses the unit of measure for an element 876 with a numeric value. The syntax for this annotation is copied from 877 the GML (Geographic Markup Language) specification [21]. 879 NOTE: It is recommended that the symbol be an identifier for a 880 unit of measure as specified in the Unified Code of Units of 881 Measure (UCUM) [13] (http://aurora.regenstrief.org/UCUM). This 882 provides a set of symbols and a grammar for constructing 883 identifiers for units of measure that are unique, and may be 884 easily entered with a keyboard supporting the limited character 885 set known as 7-bit ASCII. ISO 2955 formerly provided a 886 specification with this scope, but was withdrawn in 2001. UCUM 887 largely follows ISO 2955 with modifications to remove ambiguities 888 and other problems. 889 URL for GML specs is: http://www.opengeospatial.org/standards/gml 891 The compat:documentation annotation can also be used to provide 892 general descriptions of elements, similar to the DESCRIPTION tag in 893 SNMP MIBs. 895 7.3. Semantic Hints 897 Some schemas include container elements which have a semantic meaning 898 (for example, to enable a specific service) when they are present 899 even if they are empty. The 'existence' annotation provides a 900 semantic hint to a processor that such an element cannot be omitted 901 just because it is empty. (This document does not condone or condemn 902 this practice.) 904 # snippet of data model 905 element-range = element range { 906 element low { ipv4-address-content }?, 907 element high { ipv4-address-content }? 908 >> dml:existence [] 909 >> compat:documentation 910 ["The presence of a range element turns on dynamic addressing " ~ 911 "for the subnet. If low and high elements are missing, the " ~ 912 "DHCP server serves dynamic addresses for the whole range " ~ 913 "except for any router addresses on that subnet."] 914 } 916 917 918 919 10.254.240.0 920 22 921 923 924 926 The 'list-order' annotation conveys whether the order of a list is 927 semantically meaningful as another semantic hint. The value 'any- 928 order' means that order is not meaningful, while the value 'user- 929 order' means that the order of the elements in the list are 930 semantically meaningful. The default semantic in the absence of this 931 annotation is that order is not semantically meaningful. 933 element-router-list-option = element router-list { 934 element router { ipv4-address-content }+ 935 >> dml:order ["user-order"] 936 } 938 The 'status' annotation is used to convey conformance status (active, 939 deprecated, obsolete) of a particular element. See Section 10 for 940 more detailed semantics of this annotation. 942 The data model can also include a 'mustUnderstand' annotation. This 943 annotation contains a space-separated list of namespace prefixes that 944 the consumer of the document must be able to understand to continue 945 processing the document. This attribute can also be included in 946 instance documents as described in Section 8. 948 8. Extensibility Model 950 8.1. Pattern scoping using modules 952 This proposal expects large amounts of configuration will be split 953 into modules. A module represents a cohesive set of data about a 954 particular aspect of a device which is generally separable from other 955 aspects of the device. For example, configuration of a DHCP server 956 vs. a web server, or configuration of router interfaces vs. access 957 lists. 959 Each module needs to have its own namespace and a module version 960 number. Each module has a Relax NG start pattern indicating the top- 961 level element for that module. If this module is used as a 962 standalone document, the start pattern indicates the root element of 963 the XML document. 965 If (quite likely) a device supports several modules, a configuration 966 file can be constructed by including all the relevant modules as 967 external references. The entire grammar from the external reference 968 is included starting from the external start pattern. The patterns 969 in the external grammar are locally scoped so that a pattern in one 970 module does not conflict with another pattern of the same name in 971 another module. In the example below, the DHCP module and the 972 interfaces module both have an "element-interface" pattern, but this 973 does not cause a conflict since these patterns are in different 974 scopes. 976 # config-root.rnc 977 default namespace = "http://example.org/ns/root" 978 start = element-config 979 element-config = element config { 980 external "interfaces.rnc" ? & 981 external "dhcp.rnc" ? 983 } 985 The example above allows (and correctly validates) instance documents 986 with the following hierarchy: 988 993 994 995 996 997 998 999 1001 8.2. Extending existing modules (forward compatibility) 1003 The authors envision that data model modules for Netconf and other 1004 IETF protocols will have a small set of standardized modules and 1005 potentially a much larger collection of vendor-defined modules. 1006 Often standardized modules are partially open to allow vendors to 1007 extend a data model without modifying the original core module 1008 definition. Assume that the example DHCP module is a standardized 1009 module and that a vendor wants to add two new extensions to this 1010 module. 1012 Rather than reference the standardized module directly in 'config- 1013 root.rnc', the vendor creates a new module shim which includes the 1014 core module and then either adds new definitions or includes 1015 additional definitions. The shim can mix inline definitions with 1016 included definitions. 1018 # dhcp+extensions.rnc 1019 include "dhcp.rnc" # base module 1021 include "dhcp-tz.rnc" # timezone option extension 1022 include "dhcp-wins.rnc" # WINS server option extension 1023 The included files redefine an existing pattern in the base module by 1024 combining the new content with the base content. Relax NG supports 1025 combination through interleave (with the "&=" operator) and 1026 combination through choice (with the "|=" operator). The example 1027 here uses combination with interleave since the base module also used 1028 interleave within the contents of 'element-dhcp-option'. 1030 # dhcp-tz.rnc 1031 namespace tz = "http://example.org/ns/dhcp/timezone" 1032 element-dhcp-option &= element tz:timezone { token }? 1034 # dhcp-wins.rnc 1035 namespace wins = "http://example.org/ns/dhcp/wins-option" 1036 element-dhcp-option &= element wins:wins-server { token }* 1038 8.3. Backwards Compatibility 1040 All data models defined using this proposal are expected to have at 1041 least one namespace URI per module and a top level dml: 1042 dataModelVersion attribute which provides the current version number 1043 for that module. The extensibility model suggested here has future 1044 extensibility implications motivated strongly by the importance of 1045 backwards compatibility. 1047 Elements and attributes are never removed from the schema for a 1048 particular namespace. However, content can be deprecated in any 1049 version change. Content which was deprecated in a previous version 1050 of the same schema can be made obsolete when updating the schema to 1051 the next "major version number". Module maintainers can indicate the 1052 status of module elements using the dml:status annotation. 1054 In some cases the "no deletion" policy will cause content to migrate 1055 to a new element name if the structure of the old element name was 1056 poorly implemented. If the model developer truly wants to reuse an 1057 element or attribute name which was made obsolete, the schema can 1058 migrate to a new namespace. 1060 It is not acceptable to add new mandatory content (content with 1061 either a dml:mustUse annotation or content with a cardinality of at 1062 least one) without breaking backwards compatibility. While this can 1063 be a bit limiting when trying to add critical new features, adding 1064 default values (see next section) to new optional content can get 1065 around many of the limitations. 1067 These limitation are not a result of using Relax NG, but rather 1068 based on operational experience with SNMP, CLI and other 1069 management interfaces. The goal is to provide stability to 1070 NETCONF clients (operator scripts and management applications) and 1071 other usages of this proposal using content defined using these 1072 rules. 1074 8.4. Default Values 1076 There are a set of default values which are very stable over time and 1077 across implementations. Typically these are related to a default or 1078 constant in a protocol. For example, the example below shows a timer 1079 default defined in the SIP protocol [27]. This example adds an 1080 attribute to the defaultValue annotation which indicates that this 1081 particular default is a module-level default and will never change 1082 for this element in this namespace: 1084 element-sip-timers = element sip-timers { 1085 element t1-timer { 1086 xsd:positiveInteger 1087 >> compat:defaultValue [ dml:moduleDefault="true" 1088 "500" ] >> dml:units ["ms"] 1089 } 1090 ... 1091 } 1093 These module defaults will be the same for all implementations of the 1094 schema across different products and different versions. 1095 Implementations themselves tend to have a set of default values which 1096 differ from this module-level default. This second type, an 1097 implementation default, differs between implementations and between 1098 versions as appropriate. In fact, different implementations may have 1099 different sets of elements for which they have defined default 1100 values. 1102 Implementation defaults are an important feature to be able to 1103 maintain backwards compatibility. It allows for new elements to be 1104 added to a schema in a way that clients not familiar with the new 1105 elements can continue to send older configuration commands and still 1106 successfully change the configuration in a deterministic and 1107 predictable fashion. Given the static nature of module-level 1108 defaults, they will rarely be used, so implementation defaults fill 1109 this gap. 1111 The proposal provides the ability for model developers to specify 1112 default values when applicable. Whether these values are retrieved 1113 as a result of various operations (ex: a 'get' or 'get-config' 1114 operation in Netconf) is a protocol-specific behaviour and is not 1115 prescribed by the solution. This provides the flexibility for the 1116 protocol to support both an operation which returns elements who 1117 currently have the default value and an operation which does not. It 1118 also leaves it to the protocol to decide whether or not to present 1119 elements who have been explicitly set to the same value as the 1120 default. 1122 When a compat:defaultValue annotation appears without the dml: 1123 moduleDefault attribute, the defaultValue is an implementation (per- 1124 version) default. 1126 9. Netconf Specifics 1128 While many of the features described above are motivated by Netconf, 1129 they all could be applicable or relevant to other data modeling 1130 applications. The mechanisms described below are specific to 1131 Netconf. 1133 9.1. Get and Get-config operations 1135 The get operation retrieves all data of any infoType. The get-config 1136 operation only retreives data with an infoType of 'config'. Assuming 1137 the "op" variable is set to the type of Netconf operation (ex: get, 1138 get-config, edit-config, notify), the snippet of Schematron below can 1139 validate that nonconfig data is never present in a get-config or 1140 edit-config operation. 1142 1143 1144 1145 The element "" is operational data which is not allowed 1146 in a "" Netconf request. 1147 1148 1149 1151 1152 1153 1154 1156 9.2. Edit-config operations 1158 The edit-config operation can be performed on content whose 1159 minAccess/maxAccess allows creation, modification or deletion and 1160 which a particular implementation has provided supported for these 1161 operations. 1163 Creatable content are elements whose maxAccess clause allows creation 1164 and that exist in an implementation that supports creation of that 1165 element. Writable content are elements whose maxAccess clause allows 1166 writing and that exist in an implementation that supports editing of 1167 that element. Deletable content are elements whose maxAccess clause 1168 allows deleting and that exist in an implementation that supports 1169 deleting of that element. Readable content are elements whose 1170 maxAccess clause allows reading and that exist in an implementation 1171 that supports reading of that element. 1173 During an edit-config operation using merge, if an element or 1174 attribute is creatable and this object does not exist, it is created. 1175 If it is not creatable, the an error is reported. During a replace, 1176 If the element or attribute is writeable and exists, then all child 1177 nodes not present in the XML that are deletable are deleted, and 1178 child nodes present in the XML but not present in the datastore which 1179 are creatable are created. During a create, the element or attribute 1180 is created if it does not exist, if it is creatable. During a 1181 delete, if the element or attribute is deletable the element is 1182 deleted if it exists. An attempt to create, modify or delete 1183 elements or child elements when these operations are not supported 1184 will result in an error. 1186 The copy-config operations replaces one configuration with another. 1187 The access writes of the individual managed resources and data 1188 elements involved in the configuration are not taken into account in 1189 this case. The delete-config operation deletes an entire 1190 configuration datastore. Likewise, the access writes of the 1191 individual managed resources and data elements involved in the 1192 configuration are not taken into account. 1194 Read-only data should not itself be included in an edit-config 1195 operation, but may be included when an operation is performed on a 1196 containing element with sufficient privileges. These elements get 1197 created when their containing element is created and deleted when 1198 their containing element is deleted. 1200 9.3. Netconf notifications 1202 Below is the definition of two Netconf notifications. The first 1203 definition consists of completely new content. The second definition 1204 contains new content and reuses a pattern from DHCP configuration 1205 portion of the data model. 1207 namespace rng = "http://relaxng.org/ns/structure/1.0" 1208 namespace xsd = "http://www/w3/org/2001/XMLSchema-datatypes" 1209 namespace xml = "http://www.w3.org/XML/1998/namespace" 1210 namespace sch = "http://www.ascc.net/xml/schematron" 1211 namespace dc = "http://purl.org/dc/terms" 1212 namespace dml = "http://example.org/ns/dml" 1213 namespace compat ="http://relaxng.org/ns/compatibility/annotations/1.0" 1214 namespace notif = "urn:ietf:params:xml:ns:netconf:notification:rng:1.0" 1215 namespace ns1 = "notif" 1216 default namespace = "http://www.example.com/dhcp" 1218 compat:documentation [ 1219 "This schema demonstrates defining two Netconf notifications." ~ 1220 "The contents of the first notification is defined using" ~ 1221 "entirely new content. The second notification reuses content" ~ 1222 "defined for use in Netconf get operations." 1223 ] 1224 include "notifications.rnc" inherit = ns1 1226 notificationContent |= 1227 [ 1228 compat:documentation [ 1229 "This notification is sent out when an IP address" ~ 1230 "conflict is detected. The DHCP client discovers" ~ 1231 "its assigned address is already in use." 1232 ] 1233 ] 1234 element dhcpAddressConflictNotification { 1235 element ip-address { ipv4-address-content }, 1236 element rogue-mac-address { 1237 mac-address-content 1238 >> compat:documentation ["The conflicting MAC address"] 1239 }, 1240 element leased-mac-address { 1241 mac-address-content 1242 >> compat:documentation ["The MAC address of the DHCP client"] 1243 } 1244 >> dml:infoType ["notify"] 1245 } 1247 notificationContent |= 1248 [ 1249 compat:documentation [ 1250 "This notification is sent out when the dynamic" ~ 1251 "IP address range for a subnet is nearly full." 1252 ] 1253 ] 1254 element dhcpScopeNearlyFullNotification { 1255 ( 1256 element addresses-used { xsd:integer }, 1257 element addresses-avail { xsd:integer }, 1258 element-subnet 1259 )+ 1260 >> dml:infoType ["notify"] 1261 } 1263 start |= notificationType 1265 9.4. New netconf actions 1267 Below is an example specification of a new Netconf action. The 1268 Netconf-specific infoType attribute 'action' defines the name of the 1269 new action. 1271 namespace rng = "http://relaxng.org/ns/structure/1.0" 1272 namespace xsd = "http://www/w3/org/2001/XMLSchema-datatypes" 1273 namespace xml = "http://www.w3.org/XML/1998/namespace" 1274 namespace sch = "http://www.ascc.net/xml/schematron" 1275 namespace dc = "http://purl.org/dc/terms" 1276 namespace dml = "http://example.org/ns/dml" 1277 namespace compat ="http://relaxng.org/ns/compatibility/annotations/1.0" 1278 namespace netconf = "urn:ietf:params:xml:ns:netconf:base:1.0" 1279 namespace ns1 = "netconf" 1280 default namespace = "http://www.example.com/dhcp" 1282 compat:documentation [ 1283 "This schema defines the dhcp revoke lease rpc action" 1284 ] 1285 include "netconf.rnc" inherit = ns1 1287 revokeLeaseType = element revoke-lease { 1288 element address { ipv4-address-content }+ 1289 >> dml:infoType ["rpc-request" action="revoke-lease" ] 1290 } 1292 rpcType |= revokeLeaseType 1293 start |= rpcType 1295 Some members of the Netconf WG have suggested that new Netconf 1296 actions should be able to define arbitrary success responses 1297 instead of just the tag currently defined in the Netconf 1298 base protocol. If the WG decides to adopt this change, it would 1299 be desirable to match the "signature" of these responses to the 1300 appropriate action by tagging each response with a new infoType of 1301 rpc-response and including the action attribute used in the 1302 corresponding request. 1304 9.5. Netconf specific error messages 1306 Custom Netconf error messages are available as error annotation 1307 attributes for Schematron. Schematron allows attributes from other 1308 namespaces in all its elements. The 'dml:netconf-error-app-tag' 1309 attribute can be used to provide a error-app-tag value specific to 1310 the data model. In addition, the error text can be localized in 1311 Schematron using the 'diagnostics' element. 1313 1314 1315 1318 The contents of "" 1319 must be a '' with the key 1320 "" in this context: 1321 . 1322 1323 1324 1326 1327 1328 The contents of "" 1329 must be a 'keyref' with the key 1330 "" in this context: 1331 . 1332 1333 1334 Les contenus de "" 1335 droite etre un 'keyref' avec le cle 1336 "" dans cette contexte: 1337 . 1338 1339 1341 1342 1343 1345 1346 1347 1349 This would generate the following RPC error during an edit-config 1350 with full validation enabled: 1352 1353 1354 application 1355 invalid-value 1356 error 1357 keyref-failure 1358 //dhcp:subnet[@key="192.168.16.0/24] 1359 /dhcp:interface-filter[interface='en4'] 1360 1361 The contents of "//dhcp:interface-filter" must be a 'keyref' 1362 with the key "//int:ifIndex" in this context: int:interface. 1363 1364 1365 Les contenus de "//dhcp:interface-filter" droite etre un 'keyref' 1366 avec le cle "//int:ifIndex" dans cette contexte: int:interface 1367 1368 1369 1371 9.6. Scope of an XML document 1373 All types of XML schemas validate based on the contents of a 1374 "document". In the context of Netconf, what is considered a single 1375 XML document for validation purposes is an important issue which is 1376 directly related to the use of XML validation tools that can parse 1377 Netconf data models. Three possibilities are worth considering: 1378 o Each Netconf message is a document. Any XML inside the Netconf 1379 message (both the "envelope" and the configuration or other 1380 operational data) needs to be valid according to some combination 1381 of schema. 1382 o An entire device configuration is an XML document. In this case, 1383 the schema included in a Netconf operation (especially in an edit- 1384 config or get-config operation) is logically validated separately 1385 from the Netconf "envelope". There can be mulitple documents 1386 accessible to Netconf. For example, a device can support multiple 1387 candidate configurations and a running configuration, each of 1388 which is handled as a separate XML document. This option allows 1389 individual configuration files on a disk to be validated. 1390 o Each module is an XML document. This option is similar to the 1391 second option, except that a naming convention for specific 1392 instance files is needed for referential integrity validation to 1393 succeed. Breaking a configuration file into smaller logical 1394 chunks allows automatic validation to proceed more quickly and 1395 consume less memory. It also insures that validation checks are 1396 only run for configuration modules which have changed since the 1397 last validation, or which refer to modules which have changed. 1398 Another benefit of this approach is that it becomes much easier to 1399 insure that non-random id attributes are unique within the scope 1400 of a document. 1402 One of the implications of this choice is that the starting element 1403 of an XML document needs to be specified, either in the schema 1404 language (as supported in Relax NG) or externally in text and to 1405 validators. This is an aspect of Netconf's usage of XML which is 1406 underspecified and somewhat sloppy. The full DHCP configuration 1407 example in Section 12 assumes option 2 and so it defines a root 1408 config element (which would be required for option 2). However, each 1409 module include a top level element which could become the root 1410 element of its own document. 1412 To implement option 3, the non-abstract Schematron rule described in 1413 Section 5 for keyref validation would need to be modified slightly to 1414 include the correct document name. Specifically, the key-context 1415 would become something like: "document('interfaces.xml')// 1416 int:interfaces/int:interface" 1418 This proposal also used option 1 in order to demonstrate 1419 notifications and actions which extend the Netconf protocol itself. 1420 These example could be reworked to also include the relevant 1421 configuration as an external reference to avoid naming conflicts. 1423 Finally, part 4 of DSDL is the Namespace-based Validation Dispatching 1424 Language (NVDL) could be useful for managing modules defined using 1425 different schema languages. An NVDL script controls the dispatching 1426 of elements or attributes in a given XML document to different 1427 validators, depending on the namespaces of the elements or 1428 attributes. An NVDL script also specifies which schemas are used by 1429 these validators. These schemas can be written in any schema 1430 language. 1432 10. Conformance 1434 When defining NETCONF content, it is also necessary to define 1435 machine-readable conformance for that content. The conformance 1436 method described provides a means of providing information about 1437 individual elements which is then used to calculate the schema 1438 conformance. There is no separate definition of schema conformance. 1439 Previous solutions with separate conformance sections were found to 1440 have issues, particularly in keeping them up to date as the schema 1441 evolved. They also were not always used outside of standards 1442 activities where people did not either fully understand them or see 1443 the value in them. 1445 Conformance specifies not only whether to object must be supported, 1446 but also the level of access, read versus write for example that is 1447 minimally required. 1449 10.1. Cardinality 1451 When defining attributes and elements in the XML syntax, the 1452 'optional', 'oneOrMore' or 'zeroOrMore' tags are used to specify the 1453 cardinality of the element. In the compact syntax, "?" means 1454 optional, "+" means one or more, "*" means zero or more. When no 1455 cardinality indicator is present, this is interpreted to mean exactly 1456 once. 1458 10.2. Operations on managed objects 1460 Operations that can be performed on managed objects fall into one of 1461 the following equivalence classes: "create", "delete", "read", 1462 "write", and "execute". A value of "create" means it is possible to 1463 create new instances of this element. A value of "delete" means it 1464 is possible to destroy instances of this element. A value of "read" 1465 means that it is possible to view values of this element. A value of 1466 "write" means it is possible to modify an instance of this element. 1467 A value of "execute" means that there is a side effect execution such 1468 as rebooting that is permissible as a result of the command. 1470 The kind of access which is allowed for a particular element depends 1471 on its infoType. The minimum access needed for an implementation for 1472 a specific kind of infoType is that element's 'minAccess'. The 1473 maximum access allowed is that element's 'maxAccess'. Normally these 1474 values do not need to be modified. There is a default access class 1475 for each infoType. 1477 +---------------+-----------+--------------------------+ 1478 | Data Category | minAccess | maxAccess | 1479 +---------------+-----------+--------------------------+ 1480 | config | read | read,write,create,delete | 1481 | non-config | read | read | 1482 | action | execute | execute | 1483 | notify | read | read | 1484 +---------------+-----------+--------------------------+ 1486 Default access classes for infoTypes 1488 However, if a specific piece of data needs a different class it can 1489 be modified using the infoType annotation's minAccess and maxAccess 1490 attributes. For example, perhaps a 'controller' element can only be 1491 created automatically as a side-effect of some other action. The 1492 example below documents this by explicitly setting the maxAccess 1493 attribute: 1495 element-controller = element controller { 1496 # a bunch of sub-elements of controller 1497 # ... 1498 >> dml:infoType [ maxAccess="read write delete" "config"] 1499 >> compat:documentation ["Can't create a controller"] 1500 } 1502 To describe how this applies specifically to Netconf: a value of 1503 "create" means it is possible to create new instances of this element 1504 using commands like the NETCONF 'edit-config' or copy- config' 1505 commands. A value of "delete" means it is possible to destroy 1506 instances of this element using commands like the NETCONF 'edit- 1507 config', 'copy-config' or 'delete-config' operations. A value of 1508 "read" means that it is possible to view values of this element using 1509 commands like the 'get-config', 'get' or 'notification' operations. 1510 A value of "write" means it is possible to modify an instance of this 1511 element using commands like the NETCONF 'edit-config' or 'copy- 1512 config' commands. A value of "execute" means that there is a side 1513 effect execution such as rebooting that is permissible as a result of 1514 the command. For example, commands like the NETCONF 'edit-config' or 1515 a 'copy-config' command or the ability to execute a commands like the 1516 'lock', 'unlock' or 'kill-session' command. 1518 10.3. Element and Attribute Status 1520 As a schema evolves, certain elements and attributes may no longer be 1521 relevant. Simply deleting these from the schema may be acceptable 1522 for elements that did not see implementation, but others will require 1523 a strategy to allow implementers to migrate away from the old 1524 elements. An optional processing annotation called "status" SHOULD 1525 be used to provide the status of the element. When not present, it 1526 will assume a value of "current". The other value of this object are 1527 "deprecated" and "obsolete". A value of "deprecated" indicates that 1528 implementations should consider migrating away from this object and 1529 that its implementation is no longer required to be considered 1530 conformant. A value of "obsolete" means the object should not be 1531 implemented. Deprecated and obsolete content is never removed from 1532 the document and its element name can never be re-used. 1534 In XML syntax 1535 current 1537 In compact syntax 1538 >> dml:status [ "current" ] 1540 10.4. Additional Conformance Information 1542 Additional information about conformance should be specified using a 1543 documentation tag. 1545 Examples of additional conformance information that may be useful to 1546 provide includes how implementations can specify specific exceptions 1547 to required conformance, dependencies between elements (in order to 1548 do A, you need to first do B) and conditional conformance (if BGP, 1549 then ...). 1551 10.5. Schema Level Conformance - Server-side 1553 In order to claim compliance to a schema, all elements and attributes 1554 need to conform to their given cardinality definitions and all 1555 elements and attributes with a status of "current" and with a 1556 cardinality greater than or equal to one need to be supported. In 1557 addition, all of the operations listed by the minAccess attribute 1558 need to be supported. 1560 10.6. Schema Level Conformance - Client-side 1562 Client-side conformance is a method of indicating whether presence of 1563 an object is required in order to be a valid configuration. A new 1564 processing annotation is added called mustUse to support this. When 1565 present, this object is required in a valid configuration and when 1566 not present, it is optional in a valid configuration. Note that 1567 optional objects may have default values to enable them to have 1568 values in the configuration without being explicitly set by the 1569 client. 1571 In XML syntax 1572 1574 In compact syntax 1575 >> dml:mustUse [] 1577 11. Grading against the requirements 1579 A design team collected, clarified and categorized requirements [14] 1580 for a data modeling language from a broad group of IETF participants. 1581 Many of these requirements have broad agreement within the design 1582 team. This document describes how this approach addresses all the 1583 broadly agreed requirements and the vast majority of the additional 1584 requirements. The following outlines how these requirements (version 1585 -03) are met by this solution or when applicably, why it was felt 1586 requirements should not be met. 1588 11.1. Met requirements 1590 The following requirements are all met by this proposal. 1592 o 3.1.1 Notification Definition 1593 o 3.1.2 Notification Get 1594 This proposal can be used to define notifications reusing or 1595 separately defining content in any proportion. Two example 1596 notiications are shown in Section 9.3. 1598 o 3.1.3 Locking 1599 This solution does not preclude the fine-grain locking mechanism 1600 proposed in the partial locking draft. That approach primarily is 1601 built using XPath and it is well- understood how to use XPath with 1602 Relax NG-based solutions. 1604 o 3.1.4 All Base Operations 1605 Operations using get, get-config, and edit-config are described in 1606 Section 9.2 and Section 9.1. 1608 o 3.1.5 Define new NETCONF Operations 1609 o 3.1.6 Separation of Operations and Payload 1610 The proposal allows definition of new Netconf actions. An example is 1611 in Section 9.4. The dml:infoType annotation provides a clear 1612 distinction between actions and incorporated data. 1614 o 3.1.7 Error Annotation 1615 Netconf-specific error messages can be defined using 'dml:netconf- 1616 error-app-tag' error annotation attributes added to embedded 1617 Schematron rules as described in Section 9.5. 1619 o 3.1.8 No Mixed Content 1620 The Schematron rules run against each data model (described in 1621 Section 6) prevent introducing mixed content. 1623 o 3.2.1 Human Readable 1624 o 3.2.2 Machine Readable 1625 o 3.2.3 Textual Representation (72 column ASCII) 1626 o 3.2.7 Diff Friendly 1627 These are inherent features of Relax NG Compact. 1629 o 3.2.4 Document Information 1630 The proposal uses DublinCore elements and the dml:organization and 1631 dml:email elements, as described in Section 7. 1633 o 3.2.5 Change control 1634 o 3.2.6 Dependency risk reduction 1635 Relax NG and Schematron (and the rest of DSDL) are ISO standards. 1636 DublinCore is a publication of the [openmetadata alliance?] We can 1637 reference specific versions of these references. The DML annotations 1638 described in this proposal would have IETF change control. 1640 o 3.2.8.1. Descriptions using Local Languages 1641 o 3.2.8.2. UTF-8 Encoding 1642 o 3.2.8.3. Localization Support 1643 o 3.2.8.4. Error String Localization 1644 The proposal uses UTF-8 encoding and allows arbitrary text 1645 annotations in any language. Localization of a data model is a user- 1646 interface issue. An additional annotation (not defined here) could 1647 be added to provide localized names for elements for automatically 1648 generated web forms for example. Error string localization is shown 1649 in Section 9.5. 1651 o 3.2.8.5. Tag Names and Strings in Local Languages 1652 While XML elements can be named with non-ASCII characters in Relax 1653 NG, this practice is discouraged by the IETF. If desirable, a 1654 warning or error could be incorporated into the data model Schematron 1655 rules described in Section 6 if non-ASCII characters are present in 1656 element and attribute names. Alternatively, DSDL Part 8 - The 1657 Document Schema Renaming Language (DSRL) could be used to transalte 1658 between localized and canonical tag names. 1660 o 3.3.1 Modularity 1661 o 3.3.2 Reusable Definitions 1662 o 3.3.3 Modular extension 1663 Relax NG allows schema to be defined in separate files, and to both 1664 reuse and extend parts of schema (patterns) defined in separate 1665 files. The full example in Section 12 shows how the DHCP module is 1666 extended with the timezone option in dhcp-tz.rnc and the WINS server 1667 option in dhcp-wins.rnc without modifying the original dhcp.rnc 1668 schema or its annotations. A dhcp+extensions.rnc file needed a 1669 single line added to include the new extension. Multiple extensions 1670 to the same portion of the schema are allowed. To add a new module, 1671 a single line is added to the top-level "config-root.rnc" file. 1672 Pattern names do not need to be unique among multiple modules. More 1673 extensibility issues are discussed in Section 8. 1675 o 3.4.1 Default values on the wire 1676 Default values are mentioned in Section 7. Default values are 1677 specific to a specific version of the data model. Data with a 1678 default value can be excluded from an instance document if the 1679 carrying protocol provides some way to discriminate between 1680 configuration with and without default values. When used with 1681 Netconf, the edit config will exclude default values unless defaults 1682 are explicitly requested in a get or get-config request. 1684 o 3.4.2.1 Ordered Lists 1685 o 3.4.2.2 Order within containers 1686 o 3.4.2.3 Interleaving 1687 Relax NG supports both ordered and unordered collections of non-like 1688 elements through the "," (sequence) and "&" (interleave) operators. 1689 While interleaved collections proxide more flexibility, sequenced 1690 content is supported for backwards compatibility, etc. The dml:list- 1691 order annotation can be used as a semantic hint so that Netconf 1692 agents know if the order of a list is semantically meaningful. 1694 o 3.4.3.1 Validate instance data 1695 o 3.4.3.2 Tools to validate instance data 1696 Instance data is valid if it validates against both Relax NG (with 1697 emebbeded Schematron and the machine-generated Schematron schemas for 1698 uniqueness and referential integrity. Validators for these schema 1699 exist. 1701 o 3.4.4 Instance Canonicalization 1702 To canonicalize an instance of a data model created using this 1703 proposal, follow the rules defined in [3] and then for element or 1704 attribute values which are of type token or list, replace any 1705 sequence of whitespce characters with a single space (0x20) character 1706 and remove any leading or trailing whitespace. 1708 o 3.4.5 Character set encoding 1709 o 3.4.6 Model instance localization 1710 Relax NG handles UTF-8 data correctly. While element and attribute 1711 names are allowed to consist of non-ASCII data, this usage is 1712 strongly discouraged. Wherever character content occurs, the data 1713 model can include multiple versions of this content with xml:lang 1714 attributes to allow for localization. 1716 o 3.5.1 Human readable semantics 1717 o 3.5.2 Basic types 1718 o 3.5.3 Handling opaque data 1719 The Relax NG Compact syntax has a human readable syntax. The manual 1720 and schematron validation rules are also human readable. Relax NG 1721 includes a set of basic data types and allows the use of external 1722 datatype libraries, including the XML Schema data type library. An 1723 appendix also includes a reusable library of content types commonly 1724 used in network management. 1726 o 3.5.4.1 Define Keys 1727 o 3.5.4.2 Deep Keys 1728 The proposal describes a mechanism for defining keys in Section 4.2. 1729 These can be compound and/or arbitrarily deep keys. 1731 o 3.5.5.1 Simple Relationships 1732 The key and keyref annotations (described in Section 4.2 and 1733 Section 4.3) define a formal 1:1 or 1:n relationship between objects 1734 in different hierarchies. These relationships can be formally 1735 validated. 1737 o 3.5.5.3 Retrieve Relationships instance 1738 The value of the element that the keyref processing annotation was 1739 attached to will provide the relationship instance information in the 1740 NETCONF content. 1742 For example, the keyref definition for the interface element 1744 element interface-filter { 1745 element interface { 1746 xsd:token 1747 >> dml:keyref ["//int:interface"] 1748 }+ 1749 } 1751 Has an instance of 1753 1754 lo0 1755 en2 1756 1758 which is the instance of the particular interface involved in this 1759 reference. 1761 o 3.5.6. Hierarchical Data 1762 The proposal supports hierarchical data of arbitrary depth. 1764 o 3.5.7.1. Referential Integrity 1765 The proposal supports validation of complex relationships. 1766 Furthermore, as discussed in Section 5, the proposal supports three 1767 "phases" of validation according to context. 1769 o 3.5.8 Characterize Data 1770 Data is characterized as configuration, non-configuration, 1771 notification, and action using the dml:infoType annotation discussed 1772 in Section 4.5. 1774 o 3.5.9.1. Default Values 1775 Static default values are defined using the Relax NG DTD 1776 compatibility 'defaultValue' annotation. 1778 o 3.5.10.1. Formal Description of Constraints 1779 o 3.5.10.2. Multi-element Constraints 1780 o 3.5.10.3. Non-Key Uniqueness 1781 This proposal supports contraints using human-readable and/or inline 1782 Schematron as described in Section 4.6. Range and pattern 1783 constraints are part of the XML Schema Datatypes library and reused 1784 by Relax NG. A shortcut for constraining uniqueness is described in 1785 Section 4.1. 1787 o 3.5.11 Units 1788 A unit annotation is defined and described in Section 7. 1790 o 3.5.12 Define actions 1791 This is a duplicate of requirement 3.1.5. 1793 o 3.6.1.1. Language Versioning 1794 o 3.6.1.2. User Extensions 1795 o 3.6.1.3. Mandatory Extensions 1796 The data modeling annotations (DML for convenience) defined in this 1797 proposal are extensible. The version of these annotations is 1798 documented in a dmlVersion attribute of the dml element. Users can 1799 add additional DML element and attribute annotations as needed. 1800 These are ignored if not understood unless they contain a namespace 1801 name which is in the dml:mustUnderstand list of namespace prefixes. 1803 o 3.6.2.1. Model Version Identification 1804 Each data model module needs to have a dml:version annotation on its 1805 top-level (root) element. 1807 o 3.6.2.2. Interaction with defaults 1808 In this proposal, defaults are only valid for a specfic version of a 1809 data model. If the client does not have the current version of the 1810 data model it cannot make any assumptions about default values in 1811 use. 1813 o 3.6.2.3. Conformance Interference 1814 [TODO]. 1816 o 3.6.2.4. Obsolete Portions of a Model 1817 The dml:status annotation is used to mark portions of a schema 1818 deprecated or obsolete. 1820 o 3.6.3.1. Schema Version of Instance 1821 Each data model module is encouraged to include a dmlVersion 1822 attribute on its root element with the version of the data model 1823 generated. The schematron validator for data models described in 1824 Section 6 can generate a warning or error if a data model does not 1825 include such an attribute. 1827 o 3.6.3.2. Interaction with default Values 1828 Use of defaults is discussed extensively in Section 8.4. 1830 o 3.6.3.3. Backwards Compatibility 1831 o 3.6.3.4. Forwards Compatibility 1832 These issues are discussed in detail in Section 8. 1834 o 3.6.3.5. Must-Understand Model Extensions 1835 Clients which do not support a namespace indentified in the namespace 1836 prefix list in a dml:mustUnderstand element or attribute need to 1837 generate an error. This element or attribute can be added either 1838 under the top-level element of a module, the top-level configuration 1839 element, or as an attribute to the appropriate Netconf RPC element. 1841 o 3.7.1. Conformance to the Modeling Language 1842 An implementation conforms to this proposal if: 1843 1. it automatically validates instance documents using a conformant 1844 Relax NG validator; 1845 2. it automatically validates instance documents using any inline 1846 Schematron validation rules for the appropriate phase using a 1847 conformant Schematron validator; and 1848 3. it verifies 'unique', 'key', 'keyref'. 'mustUse' and 'infoType' 1849 constraints on instance documents as described in Section 4. 1850 Any other implementation which validates equivalently is also 1851 conformant. 1853 o 3.7.2.2. Server Conformance to Schema 1854 o 3.7.2.3. Client Conformance To Schema 1855 o 3.7.2.4. Versioned Conformance 1856 These issues are discussed in detail in Section 10. 1858 o 3.8.1. Standard Technology 1859 This proposal maximizes reuse of standard technology in the form of 1860 ISO DSDL Part 2 (Relax NG), ISO DSDL Part 3 (Schematron), the Relax 1861 NG DTD compatibility annotations, and the DublinCore metadata 1862 annotations. 1864 o 3.8.2. Translate Models to Other Forms 1865 The syntax portion of the model definition proposed by this document 1866 already uses Relax NG. This format can be converted to XSD (W3C XML 1867 Schema) automatically using existing tools (e.g. Trang) with a few 1868 simple limitations related to inherent limitations in XSD. For 1869 example, XSD does not support the interleave pattern, so interleaved 1870 element would not be allowed or would need to be converted to choice 1871 blocks which are compatible with XSD substitution groups. 1873 The conversion is very slightly lossy. The start pattern in Relax NG 1874 defines the root XML element. This information is lost in 1875 translation as there is no applicable concept in XSD. Other than 1876 that, no information is lost. 1878 o 3.8.3. Minimize SMI Translation Pain 1879 SNMP was primarily used for operational data while NETCONF will be 1880 used for both configuration and operational data. We therefore 1881 believe it is more important to define a useful set of datatypes 1882 which are a good fit for NETCONF rather then translating straight 1883 from SMI. The emphasis is on being able to exploit data type 1884 definitions from the XML world, such as W3C XML Schema Datatypes 1885 definitions and the relax NG native datatype library. That having 1886 been said, it is possible to define a data type library with a 1887 comparable set of definitions to provide parity to the ones used in 1888 SMI. A hopefully suitable data type library is defined in 1889 Appendix B. 1891 o 3.8.4. Generate Models from Other Forms 1892 The standard XML representation for UML is the XML Metadata 1893 Interchange (XMI) format. It is possible to generate Relax NG and 1894 the annotations described here using an XSLT transformation 1895 stylesheet from XMI when the UML uses a compatible subset of concepts 1896 (e.g. no many-to-many relationships). Converting between UML and 1897 Relax NG is discussed in the van der Vlist Relax NG book in Chapter 1898 14, Section 3 [36]. 1900 o 3.8.5. Isolate Models from Protocol 1901 This proposal has a clear separation of generic data modeling 1902 features and a very rich Netconf binding. 1904 o 3.8.6. Library Support 1905 Relax NG is supported in dozens of commercial and open source XML 1906 editors, validators, and XML libraries. Schematron is implemented in 1907 a handful of commercial and open source products. Use of schematron 1908 for validation is not strictly necessary, since validation rules are 1909 also presented in human-readable text. Any implementation which 1910 validates correctly is acceptable. Since DSDL is an ISO standard and 1911 the W3C is incorporating parts of DSDL in its newer specification, it 1912 is likely that implementation of these specification will increase. 1914 11.2. Met applicable subset 1916 o 3.8.7. RFC 3139 Considerations 1917 The scope of the NETCONF data model work is 'Device-Local 1918 Configuration'. Many of the requirements identified in this RFC are 1919 met by the NETCONF protocol, independent of the features of the data 1920 modeling language choice. The solution does specifically meet the 1921 requirement for data-specific errors identified in requirement 10 as 1922 well as provide for the extensibility of configuration data that 1923 requirement 14 is looking for. 1925 o 3.8.8. RFC 3216 Considerations 1926 Some of the requirements developed and captured during the 1927 development of SMIng are relevant to this discussion. Others are 1928 applicable to very specific protocol nuances of either SNMP or 1929 COPS-PR or specific use cases for these technologies that are likely 1930 not relevant to NETCONF. The requirements which are the most 1931 relevant to this discussion are reflected in the list above. 1933 11.3. Not Met 1935 o 3.5.5.2. Many-to-Many Relationships 1936 The authors did not see a compelling need for many-to-many 1937 relationships as a native feature of the data modeling solution. In 1938 most cases, this could be emulated as follows. Consider a many-to- 1939 many relationship between ports and interfaces. Each port can 1940 contain a list of keyrefs to interfaces. Likewise, each interface 1941 can contain a list of keyrefs to ports. 1943 o 3.5.7.2. Extended Referential Integrity 1944 In order to evaluate if this solution support referential integrity 1945 checks against pre-configured resources, we need to make some 1946 assumptions on how pre-configuration is modelled. If pre-configured 1947 resources are part of the configuration with special status 1948 information to indicate that the underlying hardware or software is 1949 currently not installed, then the same validation rules used for 1950 present resources applies. For example, the validity of referenced 1951 resources in keyref definitions can be verified. Additional 1952 referential checks could be added that are aware of whether equipment 1953 is pre-configured or present and respond appropriately. 1955 Validating against unreachable resources and validating against 1956 operational data runs into issues that have more to do with network 1957 element limitations then with the choice of specification language. 1958 The current operational state on the network element is related to 1959 the current configuration, which is likely different then the 1960 operational state that will result once the configuration is applied. 1961 While some network elements are able to support determining the new 1962 operational state prior to the configuration being committed, this 1963 feature may be beyond the ability of most NETCONF-managed network 1964 elements to provide. While Schematron can in theory support checks 1965 of this nature, we feel this is an advanced feature and not one we 1966 should be focusing on at present. 1968 o 3.5.9.2 Dynamic Defaults 1969 Dynamic default values are very complex. They introduce brittleness 1970 in the system. The additional bandwidth of sending configuration 1971 information which has a dynamic default is minor and presents an 1972 opportunity for significant simplification. Therefore this proposal 1973 does not address dynamic defaults. If desirable, they could be added 1974 as a separate extension (possibly introduced with the mustUnderstand 1975 annotation). Any such extension would probably use XPath expressions 1976 to formally describe the dynamic relationships. 1978 o 3.7.2.1. Conditional Conformance 1979 This proposal does not support conditional conformance. Conditional 1980 conformance in the past introduced a considerable amount of 1981 complexity with very little gain and occasionally major 1982 interoperability problems. As such, this proposal does not support 1983 conditional conformance. Conformance is implemented at the 1984 granularty of an XML namespace. 1986 12. Full Examples 1988 The example files below are Relax NG Compact schema files with the 1989 annotations described in this document. The next section contains an 1990 example of a standalone generated Schematron file which corresponds 1991 to this Relax NG syntax. 1993 In order to fit within 72 characters in width, the pattern 1994 restriction on 'ip-address-content' had to be split across two lines. 1995 This is indicated by the '~' operator in the example. This operator 1996 in Relax NG Compact is equivalent to concatening the two lines into a 1997 single quoted string literal. 1999 # config-root.rnc 2000 namespace rng = "http://relaxng.org/ns/structure/1.0" 2001 namespace dc = "http://purl.org/dc/terms" 2002 namespace dml = "http://example.org/ns/dml" 2003 namespace compat ="http://relaxng.org/ns/compatibility/annotations/1.0" 2004 namespace cfg = "http://example.org/ns/cfg" 2006 start = element-config 2007 element-config = element cfg:config { config-contents } 2008 config-contents = empty 2010 config-contents &= external "interfaces.rnc" ? 2011 config-contents &= external "dhcp.rnc" ? 2013 # interfaces.rnc 2014 namespace rng = "http://relaxng.org/ns/structure/1.0" 2015 namespace xsd = "http://www/w3/org/2001/XMLSchema-datatypes" 2016 namespace xml = "http://www.w3.org/XML/1998/namespace" 2017 namespace sch = "http://www.ascc.net/xml/schematron" 2018 namespace dc = "http://purl.org/dc/terms" 2019 namespace dml = "http://example.org/ns/dml" 2020 namespace compat ="http://relaxng.org/ns/compatibility/annotations/1.0" 2021 namespace int = "http://example.org/ns/int" 2022 default namespace = "http://example.org/ns/int" 2024 start = element-interfaces 2026 element-interfaces = element interfaces { 2027 element-interface+ 2028 >> dc:title [ "Example Interfaces schema fragment" ] 2029 } 2031 element-interface = element interface { 2032 element ifIndex { xsd:token }, 2033 element ifType { xsd:token } 2034 >> dml:key [ "ifIndex"] 2035 >> dml:version ["1.0"] 2036 } 2038 # dhcp+extensions.rnc 2039 namespace rng = "http://relaxng.org/ns/structure/1.0" 2040 datatypes xsd = "http://www.w3.org/2001/XMLSchema-datatypes" 2042 include "dhcp.rnc" # base module 2044 include "dhcp-tz.rnc" # timezone option extension 2045 include "dhcp-wins.rnc" # WINS server option extension 2047 # dhcp.rnc 2048 namespace rng = "http://relaxng.org/ns/structure/1.0" 2049 namespace xsd = "http://www/w3/org/2001/XMLSchema-datatypes" 2050 namespace xml = "http://www.w3.org/XML/1998/namespace" 2051 namespace sch = "http://www.ascc.net/xml/schematron" 2052 namespace dc = "http://purl.org/dc/terms" 2053 namespace dml = "http://example.org/ns/dml" 2054 namespace dhcp = "http://example.org/ns/dhcp" 2055 namespace int = "http://example.org/ns/int" 2056 namespace nt = "http://example.org/ns/net-types" 2057 namespace compat ="http://relaxng.org/ns/compatibility/annotations/1.0" 2058 default namespace = "http://example.org/ns/dhcp" 2060 include "network-types.rnc" 2062 start = element-dhcp 2063 element-dhcp = element dhcp { 2064 global-timer-elements, 2065 element-subnet*, 2066 element-shared-network* 2067 >> dc:title [ "Example schema for DHCP server" ] 2068 >> dml:version ["1.0"] 2069 >> dc:type ["Dataset"] 2070 >> dc:creator [ "Rohan Mahy" ] 2071 >> dml:organization [ "as an individual" ] 2072 >> dml:contact [ "mailto:rohan@ekabal.com" ] 2073 >> dc:created [ "2008-02-13" ] 2074 } 2076 global-timer-elements = ( 2077 [ 2078 sch:ns [ prefix="dhcp" uri="http://example.org/ns/dhcp" ] 2079 sch:pattern [ 2080 sch:rule [ 2081 context = "//dhcp:dhcp" 2082 sch:assert [ 2083 test = "dhcp:default-lease-time <= dhcp:max-lease-time" 2084 "Default lease time cannot be larger than maximum lease time" 2085 ] 2086 ] 2087 ] 2088 ] 2089 element default-lease-time { 2090 xsd:unsignedInt 2091 >> compat:defaultValue ["3600"] >> dml:units ["s"] 2092 }?, 2093 element max-lease-time { xsd:unsignedInt 2094 >> dml:units ["s"] }? 2095 ) 2097 element-shared-network = element shared-network { 2098 attribute name { token }, 2099 element-subnet* 2100 } 2102 element-subnet = element subnet { 2103 element-network, 2104 element-prefix-length, 2105 element-range?, 2106 element-dhcp-options?, 2107 element max-lease-time { 2108 xsd:unsignedInt 2109 >> dml:units ["s"] 2110 >> dml:status ["deprecated"] 2112 }?, 2113 element leases { 2114 element-lease* 2115 >> dml:infoType ["non-config"] 2116 }?, 2117 element-interface-filter? 2118 >> dml:key ["concat(network, '/', prefix-length)"] 2119 >> dml:manual-validation-rule [ 2120 "Verify that none of the subnets overlap with other subnets." ] 2121 } 2123 element-network = element network { 2124 ipv4-address-content 2125 } 2126 element-prefix-length = element prefix-length { 2127 xsd:short { minInclusive = "0" maxInclusive = "32" } 2128 } 2130 element-range = element range { 2131 element low { ipv4-address-content }?, 2132 element high { ipv4-address-content }? 2133 >> dml:existence [] 2134 >> dml:manual-validation-rule [ 2135 "Verify the range is within the subnet." ] 2136 } 2138 element-dhcp-options = element dhcp-options { 2139 element-router-list-option? & 2140 element-domain-list-option? & 2141 element-custom-option* 2142 } 2144 element-lease = element lease { 2145 attribute ip-address { ipv4-address-content }, 2146 element starts { xsd:dateTime }, 2147 element ends { xsd:dateTime }, 2148 element mac-address { mac-address-content } 2149 >> dml:key ["@ip-address"] 2150 } 2152 element-router-list-option = element router-list { 2153 element router { ipv4-address-content }+ 2154 >> dml:order ["user-order"] 2155 } 2156 element-domain-list-option = element domain-list { 2157 element domain { token }+ 2158 } 2159 element-custom-option = element custom { 2160 attribute option { xsd:unsignedByte }, 2161 ( 2162 element ip-address { ipv4-address-content } 2163 | element string { string } 2164 ) 2165 >> dml:key ["@option"] 2166 } 2168 element-interface-filter = element interface-filter { 2169 element-interface+ 2170 } 2172 element-interface = element interface { 2173 token >> dml:keyref ["//int:interface"] 2174 } 2176 # dhcp-tz.rnc 2177 namespace rng = "http://relaxng.org/ns/structure/1.0" 2178 datatypes xsd = "http://www.w3.org/2001/XMLSchema-datatypes" 2179 namespace tz = "http://example.org/ns/dhcp/timezone" 2180 element-dhcp-option &= element tz:timezone { token }? 2182 # dhcp-wins.rnc 2183 namespace rng = "http://relaxng.org/ns/structure/1.0" 2184 datatypes xsd = "http://www.w3.org/2001/XMLSchema-datatypes" 2185 namespace wins = "http://example.org/ns/dhcp/wins-option" 2186 element-dhcp-option &= element wins:wins-server { token }* 2188 #network-types.rnc 2189 namespace rng = "http://relaxng.org/ns/structure/1.0" 2190 namespace xsd = "http://www/w3/org/2001/XMLSchema-datatypes" 2191 namespace xml = "http://www.w3.org/XML/1998/namespace" 2192 namespace sch = "http://www.ascc.net/xml/schematron" 2193 namespace dc = "http://purl.org/dc/terms" 2194 namespace dml = "http://example.org/ns/dml" 2195 namespace compat ="http://relaxng.org/ns/compatibility/annotations/1.0" 2197 ipv4-address-content = xsd:token { pattern = 2198 "((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}" ~ 2199 "(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])" 2200 } 2201 mac-address-content = xsd:token { pattern = 2202 "(([0-9a-fA-F]{2}):?){5}[0-9a-fA-F]{2}" } 2204 13. Example Standalone Schematron 2206 The example Schematron file will validate the DHCP configuration 2207 example below. It demonstrates the concept of phases and uses 2208 abstract patterns for key and keyref validation, and for proper 2209 Netconf operation containment. 2211 2213 2214 2216 2217 2218 2220 Default lease time cannot be larger than maximum lease time 2221 2222 2223 2225 2226 2227 2228 The element "" is operational data which is not allowed 2229 in a "" Netconf request. 2230 2231 2232 2234 2235 2236 2238 2239 2240 2241 The key "" needs to be unique 2242 within the list at: . 2243 2244 2245 2247 2248 2249 2250 2251 2252 2253 2255 2257 2258 2259 2260 2262 2263 2265 2267 2269 2270 2271 2272 The contents of "" 2273 must be a '' with the key 2274 "" in this context: 2275 . 2276 2277 2278 2280 2281 2283 2284 2285 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2304 14. "DML" Annotations Schema 2306 Below is the complete Relax NG Compact formal syntax for the 2307 annotations schema. 2309 # dml.rnc 2310 namespace rng = "http://relaxng.org/ns/structure/1.0" 2311 datatypes xsd = "http://www.w3.org/2001/XMLSchema-datatypes" 2312 namespace xml = "http://www.w3.org/XML/1998/namespace" 2313 namespace compat ="http://relaxng.org/ns/compatibility/annotations/1.0" 2314 default namespace = "http://example.org/ns/dml" 2316 start = element-dml 2318 element-dml = element dml { 2319 dmlVersionAttribute? & 2320 dml-contents 2321 } 2323 dmlVersionAttribute = attribute dmlVersion { "1.0" } 2325 dml-contents = ( 2326 dataModelVersion & 2327 organization* & 2328 contact-info* & 2329 list-order* & 2330 data-category* & 2331 mustUse-flag* & 2332 container-existence* & 2333 manual-validation* & 2334 units* & 2335 conformStatus* & 2336 mustUnderstand* 2337 ) 2339 # Each data model needs a version string 2340 dataModelVersion = element version { xsd:string } 2342 # Information about the data model author(s). 2343 # Seems like this should be in Dublin Core 2344 organization = element organization { string-with-lang } 2345 contact-info = element contact { xsd:anyURI } 2347 # Processing annotations 2348 unique = element unique { xsd:anyURI } 2349 key = element key { xsd:anyURI } 2350 keyref = element keyref { xsd:anyURI } 2352 data-category = element infoType { 2353 attribute minAccess { list { access-strings }}?, 2354 attribute maxAccess { list { access-strings }}?, 2355 attribute action { xsd:string }, 2356 ("config" | "non-config" | "rpc-request" | "notify") 2357 >> compat:defaultValue ["config"] 2358 } 2359 access-strings = ( "read" | "write" | "create" | "delete" | "execute" ) 2361 mustUse-flag = element mustUse { xsd:boolean 2362 >> compat:defaultValue ["false"] 2363 } 2365 manual-validation = element manual-validation-rule { string-with-lang } 2367 # Semantic hints 2368 list-order = element order { 2369 ("any-order" | "user-order") 2370 >> compat:defaultValue ["any-order"] 2371 } 2373 container-existence = element existence { empty } 2375 units = element units { 2376 xsd:string { pattern="[^: \n\r\t]+" } 2377 # allow familiar units, but no whitespace or absolute URIs here 2378 | 2379 xsd:anyURI { pattern="([a-zA-Z][a-zA-Z0-9\-\+\.]*:|\.\./|\./|#).*" } 2380 # allow absolute URIs, plus relative URIs with ./ or ../ 2381 # prohibit relative URIs that could look like a unit, ex: m/s 2382 } 2383 # Definition copied from definition of gml:Uomidentifier from 2384 # Section 8.2.3.6 of Geography Markup Language (GML) v3.2.1 2386 string-with-lang = ( 2387 attribute xml:lang { xsd:language }, 2388 xsd:string 2389 ) 2391 conformStatus = element status { 2392 "active" | "deprecated" | "obsolete" 2393 >> compat:defaultValue ["active"] 2394 } 2396 # the mustUnderstand element contains space separated list of namespace 2397 # tokens that need to be supported to correctly process the data model 2398 mustUnderstand = element mustUnderstand { list { xsd:NCName } } 2400 dml-netconf-error-app-tag = 2401 attribute netconf-error-app-tag { xsd:string } 2403 dml-phase-attribute = attribute phase { "fragment" | "std" | "full" } 2405 dml-moduleDefault = attribute moduleDefault { 2406 xsd:boolean >> compat:defaultValue ["false"] 2407 } 2409 15. Yang Mapping 2411 The Yang specification defines an human-friendly definition of 2412 NETCONF content to complements the tool-friendly definition defined 2413 in this document. A mapping from Yang to the tool-friendly 2414 definition contained within this document is done in a predictable 2415 and reproducible manner. The approach taken is to use native Relax 2416 NG and Schematron mechanisms as much as possible. In some cases, the 2417 original flexibility available in the DSDL solutions may need to be 2418 restricted. Features introduced in this draft, ie are not natively a 2419 part of the DSDL family of specifications, are closely aligned to the 2420 equivalent feature defined in yang. Additional work in progress on 2421 YANG to DSDL mapping is available in a separate mapping draft [15]. 2423 [Editor's Note: This alignment is a work in progress. Some noted 2424 areas of misalignment that need to be discussed and solutions agreed 2425 to are 2426 As discussed in Section 9.6, what is the scope of the XML document 2427 being validated and how does this map to Schematron phases? 2428 Yang does not use Dublin Core to specify contact information. 2429 Yang does not use GML for unit specification 2430 Yang embeds the version number of a schema in its URI rather then 2431 having it as a separate field. 2432 How do manual validation rules map into Yang? 2433 How does mustUse and the concept of client-side conformance fit? 2434 How to support ordered lists of elements (not instance data) in 2435 Yang? 2436 ] 2438 15.1. Literal Mappings 2440 While additional detail will be provided to ensure fully 2441 interoperable mappings are possible, the following features are 2442 similar if not identitical between yang and NETCONF DSDL so a very 2443 straightforward mappings is possible. 2444 o basic datatypes 2445 o key 2446 o keyref 2447 o unique 2448 o status 2449 o organization 2450 o order 2451 o defaults 2452 o data-model specific error message definition 2453 o description clauses (mapped to documentation annotation) 2454 o comments map to native Relax NG comments 2455 o 'description' construct will be mapped to the documentation 2456 annotation.. 2457 o namespace and prefix will map to native Relax NG namespace 2458 definitions 2459 o import and include will map to native Relax NG namespace 2460 definitions. 2461 o choice 2462 o xmlany will map to Relax NG's native 'any'. 2464 15.2. Non-literal Mappings 2466 This section outlines mapping details that, while not difficult, 2467 require more changes then the formatting changes typical in the items 2468 listed above. First the extensibility model of Relax NG tends to 2469 encourage very flat schemas. When converting from YANG to RelaxNG 2470 automatically, it is acceptable to primarily define RelaxNG patterns 2471 for explicitly defined YANG groupings, top-level module definitions, 2472 notifications, and RPC signatures. The rest of the schema under this 2473 level could be defined as a "Russian doll" (i.e. nested) Relax NG 2474 schema. Presumably, if converting from YANG to Relax NG, the 2475 extensibility of the data model would be managed using YANG 2476 extensibility mechanisms and the effective (merged) data model 2477 converted to DSDL. 2479 Yang indicates whether data is configuration or not by the presence 2480 or absence of the 'config' attribute. In NETCONF DSDL, this is done 2481 via the infoType annotation and the values of config and non-config. 2483 Containers will leverage the 'existence' annotation. 2485 The information defined in a yang module statement will be mapped 2486 into a series of Dublin Core and NETCONF DSDL-specific tags such as 2487 contact and organization. 2489 For disussion on mapping from containers to Relax NG, see [15] 2491 The submodule concept will map into native Relax NG schema 2492 definitions. Both modules and submodules are Relax NG schema 2493 definitions. 2495 The typedef concept maps to native Relax NG patterns. 2497 The min-element and max-element yang annotations will map to native 2498 Relax NG cardinality indicators. Note that the meaning of absent 2499 annotations between the two approaches does not align so this will 2500 need to be addressed during the mapping. 2502 15.3. Information intentionally not Mapped 2504 One field that should never be mapped is that one which indicates 2505 which version of yang and what version of the solution defined in 2506 this document is being used. The Yang version of content should 2507 specify its correct language version as should the NETCONF DSDL 2508 definition. 2510 The following constructs serve the yang extensibility model but are 2511 not required in the mapping to NETCONF DSDL: uses, mandatory, augment 2512 and must 2514 16. Security Considerations 2516 TBD 2518 17. IANA Consideration 2520 A future version of this specification will need to register 2521 appropriate namespaces with IANA. 2523 18. Contributors 2525 Randy Presuhn contributed to the development of this proposal and 2526 provided useful advice on the extensibility model. Thanks to Alan 2527 Hawrylyshen for an early read. 2529 URIs 2531 [28] 2533 [29] 2536 [30] 2539 [31] 2541 [32] 2543 [33] 2545 [34] 2547 [35] 2549 [36] 2551 [37] 2553 [38] 2555 [39] 2557 [40] 2559 [41] 2561 [42] 2563 [43] 2565 [44] 2567 [45] 2569 [46] 2571 [47] 2573 Appendix A. XSLT Transform from processing annotation to Schematron 2575 Write up notes on how the XSLT works. Generating rules for 2576 uniqueness and key verification. Walk upward until an element 2577 element (add to front of path) or ref element (recurse) is 2578 encountered. Include namespace prefixes. Continue once more for the 2579 parent element. Generating rules for key verification. Generating 2580 rules for keyref validation. Deleting elements or attributes which 2581 are marked obsolete. 2583 TODO 2585 Appendix B. Data type library 2587 Part 5 of the DSDL Framework defines a very flexible and powerful 2588 syntax for creating named sets of user-defined datatypes. While this 2589 might be the ultimate way for defining new datatypes, this syntax, 2590 known as Datatype Library Language (DTLL) [20], is still work in 2591 progress and the number of implementations is quite small. 2593 As an interim solution, the datatypes necessary for NETCONF data 2594 modelling purposes can be provided in two different forms: 2595 1. Generic simple datatypes - various types of numbers, strings, 2596 booleans, dates etc. - are available in all RELAX NG 2597 implementations via the W3C XML Schema Datatypes library [7]. 2598 2. Domain-specific datatypes such as IP addresses, DNS domain names 2599 and MAC addresses can be prepared as libraries of patterns 2600 expressed in RELAX NG. 2602 RELAX NG has built-in support for the W3C XML Schema Datatypes 2603 library [7]. In the compact syntax, the namespace of this library 2604 ("http://www.w3.org/2001/XMLSchema-datatypes") is declared implicitly 2605 with prefix "xsd". In the XML syntax, the URI of this (or any other) 2606 datatype library must be explicitly declared using the 2607 "datatypeLibrary" attribute. 2609 Usage of datatypes from the XML Schema Library in RELAX NG is 2610 straightforward. For example, an element containing autonomous 2611 system number can be defined as follows: 2613 element asn { xsd:unsignedShort } 2615 Likewise, it is easy to impose additional restrictions by means of so 2616 called facets, for example ranges of permissible values: 2618 element hello-multiplier { 2619 xsd:unsignedByte { minInclusive = "3" maxInclusive = "20" } 2620 } 2622 The most important datatypes provided by the XML Schema Library are 2623 summarized in Table 2. 2625 +---------------+---------------------------------------------------+ 2626 | Type | Meaning | 2627 +---------------+---------------------------------------------------+ 2628 | byte | 8-bit integer value | 2629 | short | 16-bit integer value | 2630 | int | 32-bit integer value | 2631 | long | 64-bit integer value | 2632 | unsignedByte | 8-bit unsigned integer value | 2633 | unsignedShort | 16-bit unsigned integer value | 2634 | unsignedInt | 32-bit unsigned integer value | 2635 | unsignedLong | 64-bit unsigned integer value | 2636 | float | 32-bit IEEE floating-point value | 2637 | double | 64-bit IEEE floating-point value | 2638 | string | character string without whitespace normalization | 2639 | token | character string with whitespace normalization | 2640 | boolean | boolean type with values "true" or "false" | 2641 | base64Binary | binary data in base64 encoding | 2642 | anyURI | uniform resource identifier | 2643 | dateTime | date and time value according to ISO 8601 | 2644 +---------------+---------------------------------------------------+ 2646 Table 2: Selected datatypes from the W3C XML Schema Type Library 2648 B.1. About Domain-Specific Pattern Libraries 2650 This section contains two library modules with reusable RELAX NG 2651 patterns: 2652 inet-types - common Internet-related datatypes such as IP 2653 addresses and prefixes, port numbers and DNS domain names 2654 ieee-types - common datatypes defined in IEEE 802 standards: MAC 2655 address, bridge identifier and VLAN identifier. 2657 The patterns defined in these modules can be used, unmodified or with 2658 modifications, in RELAX NG schemas. This is accomplished by 2659 including one or more modules in the schema, for example 2661 include "inet-types.rnc" 2663 In the compact syntax, the way the included pattern definitions are 2664 used is almost identical to the previous case of simple datatype 2665 libraries; the only difference is the absence of a namespace prefix. 2666 In the following example, the "ip-address" pattern is defined in the 2667 "inet-types" module: 2669 element source-address { ip-address } 2671 The patterns in the "inet-types" and "ieee-types" modules are 2672 designed for maximum flexibility. They can be extended or modified 2673 using standard RELAX NG mechanisms. As an example, consider the 2674 definition of "port-number" pattern that does not allow a zero value. 2675 If a data modeller had an application where the zero value is 2676 meaningful, she could reuse the definition in the following way: 2678 port-number |= "0" 2680 This construct is called "combination by choice" in RELAX NG and is 2681 equivalent to the following definition: 2683 port-number = xsd:unsignedShort { minInclusive = "1" } | "0" 2685 Extension of patterns defined in an external module is possible 2686 through "combination by interleave". For example, if we wanted to 2687 add scope identifier to IP prefixes, we could redefine the "ip- 2688 prefix" pattern as follows: 2690 ip-prefix &= element scope { xsd:token } 2692 This is equivalent to the following definition: 2694 ip-prefix = ((attribute version { "ipv4" }?, ipv4-prefix) 2695 | (attribute version { "ipv6" }?, ipv6-prefix)) 2696 & element scope { xsd:token } 2698 Finally, the third possibility for modifying predefined patterns is 2699 to replace selected pattern definitions entirely with our own 2700 versions. 2702 B.1.1. Internet Data Types 2704 # inet-types.rnc 2705 default namespace = "urn:ietf:params:xml:ns:relax-ng:inet-types" 2707 B.1.1.1. ip-version 2709 This pattern defines possible values for IP protocol version. See 2710 RFC 791 [37] and RFC 2460 [38]. 2712 ip-version = "unknown" | "ipv4" | "ipv6" 2714 B.1.1.2. dscp 2716 This pattern represents Differentiated Services Code Point. See RFC 2717 3289 [39], RFC 2474 [40] and RFC 2780 [41]. 2719 dscp = xsd:unsignedByte { maxInclusive = "63" } 2721 B.1.1.3. flow-label 2723 This pattern represents the flow label - 20-bit value that is used 2724 for discriminating traffic flows. See RFC 2460 [38]. 2726 flow-label = xsd:unsignedInt { maxInclusive = "1048576" } 2728 B.1.1.4. port-number 2730 This pattern represents the port number that is used by transport 2731 layer protocols such as TCP or UDP. See RFC 4001 [42]. 2733 port-number = xsd:unsignedShort { minInclusive = "1" } 2735 B.1.1.5. ip-address 2737 This pattern represents IP address (either IPv4 or IPv6). The 2738 version may be indicated in the "version" attribute, otherwise it is 2739 determined from the textual format. 2741 ip-address = 2742 (attribute version { "ipv4" }?, 2743 ipv4-address) 2744 | (attribute version { "ipv6" }?, 2745 ipv6-address) 2747 B.1.1.6. ipv4-address 2749 This pattern represents IPv4 address in the usual dotted quad 2750 notation. 2752 The pattern is referenced by: 2753 o ip-address (Appendix B.1.1.5) 2754 o ipv4-prefix (Appendix B.1.1.9) 2755 o host (Appendix B.1.1.12) 2757 ipv4-address = 2758 xsd:token { 2759 pattern = 2760 "((25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])\.){3}" ~ 2761 "(25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])" 2762 } 2764 B.1.1.7. ipv6-address 2766 This pattern represents IPv6 address in one of the three textual 2767 formats defined in RFC 4291 [43], section 2.2 (full, shortened and 2768 mixed). 2770 The pattern is referenced by: 2771 o ip-address (Appendix B.1.1.5) 2772 o ipv6-prefix (Appendix B.1.1.10) 2773 o host (Appendix B.1.1.12) 2775 ipv6-address = 2776 xsd:token { 2777 pattern = "([0-9a-fA-F]{0,4}:){0,7}[0-9a-fA-F]{0,4}" 2778 pattern = 2779 "(([0-9a-fA-F]+:){7}[0-9a-fA-F]+)|" ~ 2780 "(([0-9a-fA-F]+:)*[0-9a-fA-F]+)?::(([0-9a-fA-F]+:)*[0-9a-fA-F]+)?" 2781 } 2782 | 2783 xsd:token { 2784 pattern = 2785 "([0-9a-fA-F]{0,4}:){0,6}((25[0-5]|2[0-4][0-9]|" ~ 2786 "[01]?[0-9]?[0-9]).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])" 2787 pattern = 2788 "(([0-9a-fA-F]+:){6}|(([0-9a-fA-F]+:)*[0-9a-fA-F]+)?::" ~ 2789 "([0-9a-fA-F]+:)*)((25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9]).)" ~ 2790 "{3}(25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])" 2791 } 2793 B.1.1.8. ip-prefix 2795 This pattern represents IP prefix (either IPv4 or IPv6). The version 2796 may be indicated in the "version" attribute, otherwise it is 2797 determined from the textual format. 2799 ip-prefix = 2800 (attribute version { "ipv4" }?, 2801 ipv4-prefix) 2802 | 2803 (attribute version { "ipv6" }?, 2804 ipv6-prefix) 2806 B.1.1.9. ipv4-prefix 2808 This pattern represents IPv4 prefix. Prefix length is specified by 2809 the "length" subelement. 2811 The pattern is referenced by: 2812 o ip-prefix (Appendix B.1.1.8) 2814 ipv4-prefix = 2815 element address { ipv4-address } 2816 & element length { 2817 xsd:unsignedByte { maxInclusive = "32" } 2819 } 2821 B.1.1.10. ipv6-prefix 2823 This pattern represents IPv6 prefix. Prefix length is specified by 2824 the "length" subelement. 2826 The pattern is referenced by: 2827 o ip-prefix (Appendix B.1.1.8) 2829 ipv6-prefix = 2830 element address { ipv6-address } 2831 & element length { 2832 xsd:unsignedByte { maxInclusive = "128" } 2833 } 2835 B.1.1.11. domain-name 2837 This pattern represents DNS domain name, see RFC 1034 [44] and RFC 2838 1123 [45]. 2840 The pattern is referenced by: 2841 o host (Appendix B.1.1.12) 2843 domain-name = 2844 xsd:token { 2845 maxLength = "255" 2846 pattern = 2847 "([A-Za-z0-9]([\-A-Za-z0-9]{0,61}[A-Za-z0-9])?.)*" ~ 2848 "[A-Za-z0-9]([\-A-Za-z0-9]{0,61}[A-Za-z0-9])?.?" 2849 } 2851 B.1.1.12. host 2853 This pattern represents either an IP address (IPv4 or IPv6) or a host 2854 name. The type of the contents may be indicated by the "content- 2855 type" attribute, otherwise it is determined from textual format. 2857 host = 2858 ( attribute content-type { "ipv4" }?, 2859 ipv4-address) 2860 | 2861 ( attribute content-type { "ipv6" }?, 2862 ipv6-address) 2863 | 2864 ( attribute content-type { "dns" }?, 2865 domain-name) 2867 B.1.2. IEEE Data Types 2869 # ieee-types.rnc 2870 default namespace = "urn:ietf:params:xml:ns:relax-ng:ieee-types" 2872 B.1.2.1. mac-address 2874 This pattern represents an IEEE 802 MAC address in the canonical 2875 format. 2877 mac-address = xsd:token { 2878 pattern = "([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}" 2879 } 2881 B.1.2.2. bridgeid 2883 This pattern represents an identifier of a MAC bridge. See IEEE 2884 802.1D-2004 [46], Section 9.2.5. 2886 bridgeid = xsd:token { 2887 pattern = "[0-9a-fA-F]{4}:([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}" 2888 } 2890 B.1.2.3. vlanid 2892 This pattern represents a 12-bit VLAN identifier that is used as a 2893 VLAN tag in IEEE 802.1Q frames. See IEEE 802.1Q-2005 [47]. 2895 vlanid = xsd:unsignedShort { 2896 minInclusive = "1" 2897 maxInclusive = "4094" 2898 } 2900 Appendix C. DHCP schema in Relax XML format 2902 For those who prefer the XML syntax of Relax NG, the "dhcp.rnc" file 2903 was converted to "dhcp.rng" using Trang. Some additional whitespace 2904 was added to improve readability and to make the document fit in 72 2905 characters. 2907 2908 2909 2923 2925 2926 2927 2929 2930 2931 2932 2933 2934 2935 2936 2937 2938 Example schema for DHCP server 2939 1.0 2940 Dataset 2941 Rohan Mahy 2942 as an individual 2943 mailto:rohan@ekabal.com 2944 2008-02-13 2945 2946 2948 2949 2950 2951 2952 2953 2955 Default lease time cannot be larger than maximum lease time 2956 2957 2958 2959 2960 3600 2961 s 2962 2963 2964 2965 2966 2967 s 2968 2969 2970 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 s 2997 deprecated 2998 2999 3000 3001 3002 3003 3004 3005 non-config 3006 3007 3008 3009 3010 3011 concat(network, '/', prefix-length) 3012 3013 Verify that none of the subnets overlap with other subnets. 3014 3015 3016 3018 3019 3020 3021 3022 3024 3025 3026 3027 0 3028 32 3029 3030 3031 3033 3034 3035 3036 3037 3038 3039 3040 3041 3042 3043 3044 3045 3046 3047 Verify the range is within the subnet. 3048 3049 3050 3052 3053 3054 3055 3056 3058 3059 3060 3061 3062 3063 3064 3065 3066 3067 3069 3070 3071 3072 3073 3074 3075 3076 3077 3078 3079 3080 3081 3082 3083 @ip-address 3084 3085 3087 3088 3089 3090 3091 3092 3093 3094 user-order 3095 3096 3098 3099 3100 3101 3102 3103 3104 3105 3107 3109 3110 3111 3112 3113 3114 3115 3116 3117 3118 3119 3120 3121 3122 @option 3123 3124 3126 3127 3128 3129 3130 3131 3132 3134 3135 3136 3137 //int:interface 3138 3139 3140 3142 19. References 3144 19.1. Normative References 3146 [1] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 3147 December 2006. 3149 [2] Kunze, J. and T. Baker, "The Dublin Core Metadata Element Set", 3150 RFC 5013, August 2007. 3152 [3] Boyer, J., "Canonical XML Version 1.0", RFC 3076, March 2001. 3154 [4] Chisholm, S. and H. Trevino, "NETCONF Event Notifications", 3155 draft-ietf-netconf-notification-14 (work in progress), 3156 June 2008. 3158 [5] Bjorklund, M., "YANG - A data modeling language for NETCONF", 3159 draft-ietf-netmod-yang-00 (work in progress), May 2008. 3161 [6] Maler, E., Paoli, J., Bray, T., Sperberg-McQueen, C., and F. 3162 Yergeau, "Extensible Markup Language (XML) 1.0 (Fourth 3163 Edition)", World Wide Web Consortium Recommendation REC-xml- 3164 20060816, August 2006, 3165 . 3167 [7] Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes Second 3168 Edition", World Wide Web Consortium Recommendation REC- 3169 xmlschema-2-20041028, October 2004, 3170 . 3172 [8] Bray, T., Tobin, R., Layman, A., and D. Hollander, "Namespaces 3173 in XML 1.0 (Second Edition)", World Wide Web Consortium 3174 Recommendation REC-xml-names-20060816, August 2006, 3175 . 3177 [9] ISO, "Document Schema Definition Languages (DSDL) -- Part 3: 3178 Rule-based validation -- Schematron", June 2006. 3180 [10] ISO, "Document Schema Definition Languages (DSDL): Part 2: 3181 Regular Grammer-based Validation - Relax NG", Decemeber 2002. 3183 [11] Clark, J. and S. DeRose, "XML Path Language (XPath) 2.0", 3184 January 2007, . 3186 [12] Clark, J., "XSL Transformations (XSLT)", November 1999. 3188 [13] Schadow, G. and C. McDonald, "The Unified Code for Units of 3189 Measure", November 2005. 3191 19.2. Informational References 3193 [14] Presuhn, R., "The Requirements Draft", draft-presuhn-rcdml-03 3194 (work in progress), February 2008. 3196 [15] Lhotka, L., "Mapping of YANG to DSDL", 3197 draft-lhotka-yang-dsdl-map-00 (work in progress), July 2008. 3199 [16] Case, J., Fedor, M., Schoffstall, M., and J. Davin, "Simple 3200 Network Management Protocol (SNMP)", STD 15, RFC 1157, 3201 May 1990. 3203 [17] McCloghrie, K., Ed., Perkins, D., Ed., and J. Schoenwaelder, 3204 Ed., "Structure of Management Information Version 2 (SMIv2)", 3205 STD 58, RFC 2578, April 1999. 3207 [18] van der Vlist, E., "Relax NG", 2004. 3209 [19] ISO/IEC, "Document Schema Definition Languages (DSDL) - Part 1: 3210 Overview", ISO/IEC 19757-1, 11 2004. 3212 [20] ISO/IEC, "Document Schema Definition Languages (DSDL) - Part 5: 3213 Datatypes - Datatype Library Language (DTLL)", ISO/IEC 19757-5, 3214 2006. 3216 [21] Cox, S., Daisey, P., Lake, R., Portele, P., and A. Whiteside, 3217 "OpenGIS Geography Markup Language (GML Implementation 3218 Specification", February 2007. 3220 [22] McCarron, S., Schnitzenbaumer, S., Dooley, S., Wugofski, T., 3221 Boumphrey, F., and M. Altheim, "XHTML[TM] Modularization 1.1", 3222 World Wide Web Consortium LastCall WD-xhtml-modularization- 3223 20060705, July 2006, 3224 . 3226 [23] Jackson, D., Ferraiolo, J., and J. Fujisawa, "Scalable Vector 3227 Graphics (SVG) 1.1 Specification", W3C CR CR-SVG11-20020430, 3228 April 2002. 3230 [24] Reagle, J., Solo, D., and D. Eastlake, "XML-Signature Syntax 3231 and Processing", World Wide Web Consortium Recommendation REC- 3232 xmldsig-core-20020212, February 2002, 3233 . 3235 [25] Klyne, G. and J. Carroll, "Resource Description Framework 3236 (RDF): Concepts and Abstract Syntax", World Wide Web Consortium 3237 Recommendation REC-rdf-concepts-20040210, February 2004, 3238 . 3240 [26] Thompson, H., Beech, D., Maloney, M., and N. Mendelsohn, "XML 3241 Schema Part 1: Structures Second Edition", World Wide Web 3242 Consortium Recommendation REC-xmlschema-1-20041028, 3243 October 2004, 3244 . 3246 [27] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., 3247 Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP: 3248 Session Initiation Protocol", RFC 3261, June 2002. 3250 Authors' Addresses 3252 Rohan Mahy 3253 Plantronics 3255 Email: rohan@ekabal.com 3257 Sharon Chisholm 3258 Nortel 3260 Email: schishol@nortel.com 3262 Ladislav Lhotka 3263 CESNET 3265 Email: lhotka@cesnet.cz 3267 Full Copyright Statement 3269 Copyright (C) The IETF Trust (2008). 3271 This document is subject to the rights, licenses and restrictions 3272 contained in BCP 78, and except as set forth therein, the authors 3273 retain all their rights. 3275 This document and the information contained herein are provided on an 3276 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 3277 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 3278 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 3279 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 3280 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 3281 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3283 Intellectual Property 3285 The IETF takes no position regarding the validity or scope of any 3286 Intellectual Property Rights or other rights that might be claimed to 3287 pertain to the implementation or use of the technology described in 3288 this document or the extent to which any license under such rights 3289 might or might not be available; nor does it represent that it has 3290 made any independent effort to identify any such rights. Information 3291 on the procedures with respect to rights in RFC documents can be 3292 found in BCP 78 and BCP 79. 3294 Copies of IPR disclosures made to the IETF Secretariat and any 3295 assurances of licenses to be made available, or the result of an 3296 attempt made to obtain a general license or permission for the use of 3297 such proprietary rights by implementers or users of this 3298 specification can be obtained from the IETF on-line IPR repository at 3299 http://www.ietf.org/ipr. 3301 The IETF invites any interested party to bring to its attention any 3302 copyrights, patents or patent applications, or other proprietary 3303 rights that may cover technology that may be required to implement 3304 this standard. Please address the information to the IETF at 3305 ietf-ipr@ietf.org. 3307 Acknowledgment 3309 Funding for the RFC Editor function is provided by the IETF 3310 Administrative Support Activity (IASA).