Sharon Chisholm Internet Draft Nortel Networks Document: draft-chisholm-netconf-model-00.txt Expires: January 2005 July 2004 Framework for Netconf Data Models Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026 [i]. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Abstract This memo defines a framework for defining content for Netconf. Conventions used in this document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC-2119 [ii]. Table of Contents 1. Introduction...................................................2 2. Considerations for Interoperability............................3 2.1 Data Modeling Language.....................................3 2.2 Conformance................................................3 Chisholm (Editor) Expires - January 2005 [Page 1]
Framework for Netconf Data Models July 2004 2.2.1 Requirements3 2.2.2 Fine Grain Conformance 4 2.3 Versioning.................................................4 2.4 Backwards Compatibility....................................5 2.5 Object Granularity & Access control........................5 3. Considerations for Extensibility...............................5 3.1 Data Types.................................................5 3.2 Elements and Attributes....................................5 3.2.1 Consider Attributes as Metadata 6 3.2.2 Consider the Lack of Extensibility of Attributes6 3.3 Other Extensibility Considerations.........................6 4. Considerations for Parse-ability...............................6 4.1 Well-formed XML............................................7 4.2 No DTDs....................................................7 4.3 Avoid Mixed Content........................................7 4.4 Use an Explicit Namespace on Attributes....................7 4.5 Use Container Elements for Lists...........................7 5. Considerations for Usability...................................8 5.1 Naming.....................................................8 5.1.1 Proper Tag Names 8 5.2 Considerations for Usability...............................9 5.3 Error Handling.............................................9 5.3.1 Design Considerations9 5.4 Schema Documentation.......................................9 6. Other Topics...................................................9 7. Relationship to Netconf Protocol..............................10 8. Security Considerations.......................................10 9. Acknowledgements..............................................10 10. Authors' Address.............................................10 11. References...................................................10 11.1 Normative................................................10 11.2 Informative References...................................11 12. Full Copyright Statement.....................................11 1. Introduction NETCONF [NETCONF-PROTO] can be conceptually partitioned into four layers: Layer Example +-------------+ +-----------------------------+ | Content | | Configuration data | +-------------+ +-----------------------------+ | | +-------------+ +-----------------------------+ | Operations | | <get-config>, <edit-config> | Chisholm (Editor) Expires - January 2005 [Page 2]
Framework for Netconf Data Models July 2004 +-------------+ +-----------------------------+ | | +-------------+ +-----------------------------+ | RPC | | <rpc>, <rpc-reply> | +-------------+ +-----------------------------+ | | +-------------+ +-----------------------------+ | Application | | BEEP, SSH, SSL, console | | Protocol | | | +-------------+ +-----------------------------+ This document provides an introduction to the Netconf Data Model. This work provides a framework for Netconf content. This framework is intended to provide guidance for the creation of Netconf content for the purposes of enabling interoperability, extensibility, parse- ability and usability. [Editor's Note: This document incorporates section 7 of the 'NETCONF Configuration Protocol' specification [NETCONF-PROTO]. This section, entitled 'XML Usage Guidelines for NETCONF' also contains restrictions on the Netconf content. Whether it has been incorporated in the most appropriate way within this memo is for further study.] 2. Considerations for Interoperability This section describes some restrictions on Netconf content that will increase interoperability between implementations and between different versions of a given implementation. 2.1 Data Modeling Language XML Schema should be used to define the XML-formatted data that will be transported via Netconf. 2.2 Conformance 2.2.1 Requirements The following are the requirements that have been identified for the conformance and compliance aspects of Netconf data models. 1. Conformance Needs to be machine-readable 2. Both a high level of abstraction and lower one - specific groups of objects as well as individuals. 3. It would also be good to be able to note specific exceptions to conformance. Chisholm (Editor) Expires - January 2005 [Page 3]
Framework for Netconf Data Models July 2004 4. Dependencies between conformance should also be discoverable - in order to do A, you need to first do B, for example. It was noted that currently adding values to enumerations has an impact on conformance. 5. It will be necessary to be able to specify the minimum and maximum access to objects, compared to whether it can be read, written or created. [Editor's note: this list provides on-par conformance/compliance with SNMP MIBs as well as identifies requirements to fill holes within that paradigm. It might be worth determining which of these will be a requirement moving forward. In particular, do we really want to define minimum and maximum read/write/create to the elements within the data model, elsewhere or not at all?] 2.2.2 Fine Grain Conformance When defining elements, the minOccurs and maxOccurs tags must be used to specify whether that object is required to have a compliant schema. When defining an attribute, the use tag must be used to define whether the attribute is required. 2.3 Versioning The current version of a schema needs to be complete, not a delta from the previous version. The XML Schema version attribute will be used to signify version For example: <?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" version="3.1"> <xs:element name="Foo"> </xs:element> </xs:schema> The XML Schema version attribute will be used to signify version. This allows applications to be aware of XML Schema versions, and changes to XML Schema version, without forcing instance documents to change to a new schema if the new schema is backwards compatible. Instance documents should indicate their compatible version range with an attribute on the root element which contains a list of compatible versions. This implies that applications which consume instance documents must perform processing to confirm XML Schema compliance Chisholm (Editor) Expires - January 2005 [Page 4]
Framework for Netconf Data Models July 2004 When the context or behavior of an element is modified between versions a new schema should be created rather than updating the version of an existing XML Schema. Alternatively, a new element could be created in the existing schema, but using a different name. 2.4 Backwards Compatibility Backwards compatibility requirements come in two forms. The first is bits on the wire compatibility of managed entities and manager implementations that are based on different revisions of an XML Schema. The other is compilation compatibility with XML Schema modules that import definitions from the revised XML Schema module. What sorts of changes in type are permissible? What sorts of changes to the minOccurs, maxOccurs are acceptable? What about minLength maxLength? 2.5 Object Granularity & Access control This area is for further study 3. Considerations for Extensibility 3.1 Data Types XML Schema has 44 built in data types [XML-SCHEMA-2]. Where additional data types are defined, there should be one per XSD. Reusable data types should be declared as complex type, rather than element. It has been suggested that SMIv2 really had too many derived data types. People couldn't really tell them apart and getting the most correct data type was occasionally a non-value add portion of the MIB review process. Care should be taken not to define too many data types. [Editor's note: how can this be turned into a guideline?] 3.2 Elements and Attributes The choice of elements and attributes has been widely discussed, but no absolute guidelines exist. When designing encoding rules for NETCONF content, the following guidelines should be used: Chisholm (Editor) Expires - January 2005 [Page 5]
Framework for Netconf Data Models July 2004 3.2.1 Consider Attributes as Metadata Attributes should contain metadata about the element, not true data. By extension, vital information should not be encoded in attributes. [Editor's Note: which bits of meta data are we actually interested in?] 3.2.2 Consider the Lack of Extensibility of Attributes Attributes are unordered, can appear only once, and can have no children. Data scenarios which must leave room for future expansion (in future specifications or future software releases) should avoid attributes. [Editor's note: this may need to be explained a bit better.] 3.3 Other Extensibility Considerations All data which is intended to allow extension in derived schemas should be defined as (simple or complex) types, not elements. Any data required in an element form should be a reference to a simpleType or complexType declaration. To maintain easy compatibility with old versions of a schema, the ANY element should be used to allow future evolution without impact to applications. In any element or complexType declaration, always add unbounded support for ANY. This allows for unforeseen extension of the schema without effecting the operation of existing applications. 4. Considerations for Parse-ability Netconf content can affect the efficiency and robustness of parsing routines in two ways. The first has to whether any content within the Netconf content could be confused with any aspect of the operations, RPC or application protocol layer. If this is possible, then more careful routines need to be written. In particular, it might be difficult to separate out an implementation into separate methods to parse these different layers if it is necessary to parse the Netconf content and match open and close brackets rather than just looking for an appropriate close tag. Another aspect where the Content will affect performance of the parsing routines is on the assumptions that the parsing routine can make. The following section outlines some restrictions on the Netconf content that will positively impact the performance of parsing routines with minimum impact on the usability of the solution. Chisholm (Editor) Expires - January 2005 [Page 6]
Framework for Netconf Data Models July 2004 4.1 Well-formed XML All XML used within a Netconf solution needs to be well formed [XML] and conform to an XML Schema specification that conforms to the guidelines in this document. 4.2 No DTDs Document type declarations (DTDs) are not permitted to appear in NETCONF content 4.3 Avoid Mixed Content Mixed content is defined as elements that can contain both data and other elements. Elements in NETCONF can contain either data or additional elements only. This greatly simplifies the complexity of parsing XML, especially in the area of significant whitespace. Whitespace inside data elements is significant. Whitespace outside data elements is not. <valid> <element>data</element> <more>data</more> </valid> <not-valid> <element>data<more>data</more>maybe some</element> </not-valid> 4.4 Use an Explicit Namespace on Attributes All attributes should be prefixed so that they belong to a specific namespace. This encourages meaningful definitions that are free of collisions. <valid xmlns="http://valid/" xmlns:v="http://valid/" v:foo="cool"></valid> <not-valid xmlns="http://not-valid/" foo="not-cool"></not-valid> 4.5 Use Container Elements for Lists A distinct container should be used when encoding lists with multiple instances, use a distinct container element, preferably the plural form of the instance element. In this example, the element 'grommet' is contained within the Chisholm (Editor) Expires - January 2005 [Page 7]
Framework for Netconf Data Models July 2004 'grommets' element. <valid> <grommets> <grommet>....</grommet> <grommet>....</grommet> <grommet>....</grommet> </grommets> </valid> Use of container elements allows simpler manipulation of lists and list members. [Editor's Note: Would we want this one to be normative or informative? Are there benefits to never allowing this to be done another way? Would we ever want to?] 5. Considerations for Usability 5.1 Naming [Editor's Note: The implications of putting the rules for constructing the object identifiers within both the protocol and the data model have been discussed. It will be important to look ahead when designing the schema. We need to ensure we don't put any dependencies on data types within the naming hierarchy, for example.] 5.1.1Proper Tag Names When choosing element names, consider the following guidelines: o Prefer ASCII (7-bit). o Prefer lowercase. o Prefer dashes to underscores. o Prefer full words. Note that "config" is considered a full word. These are guidelines only and should be considered secondary to the need for consistency with existing vocabularies. For example, when encoding MIB variables names in NETCONF, use the existing names (ifAddr) instead of shifting to these guidelines (if-address). These Chisholm (Editor) Expires - January 2005 [Page 8]
Framework for Netconf Data Models July 2004 guidelines are valuable when no common vocabulary exists, because they help to avoid the scenario in which a dozen developers choose a dozen names that differ in ways that lead to frustrating inconsistencies, such as ifaddr, if-addr, if-address, interface- address, intf-addr, iaddr, and iface-addr. 5.2 Considerations for Usability 5.3 Error Handling It was agreed that error codes should be structured to consist of both a generic protocol level error code and data model specific error codes. If implementations don't understand the data model specific error codes, they still have the generic one to go by, but the data model specific error codes can provide information about the specific problem that has happened. 5.3.1Design Considerations 1. Granularity of specifying error messages - is it on a per schema, per element, multiple per element basis? 2. What mechanism should be used? Annotation, reserved named element tags, attributes? 3. How closely tied are these to the known set of operations that can be performed on the data? How is this determined? 5.4 Schema Documentation. The 'documentation' tag must be used to provide all addition information to implementers and users of a schema that can not be modeled within the schema itself. This includes further restrictions and additional complexities as well as any information that will be helpful in understanding the element. Note that other means of documenting, including the <!-- --> construct are not as easily associated within specific elements not necessarily understood by all tools. 6. Other Topics The items within this section may not necessarily belong within this specification, so may get moved elsewhere at a later date. It should be possible to discover a box and find out both is major software release numbers as well as the list of data models and their versions that are supported. Chisholm (Editor) Expires - January 2005 [Page 9]
Framework for Netconf Data Models July 2004 7. Relationship to Netconf Protocol The Netconf architecture supports a clear separation between content and protocol. This is an important architectural separation that should be maintained. That having been said, there are major advantages to ensuring that the content of Netconf is well behaved and predictable. Whether a Netconf implementation can be said to be compliant without also being compliant to the guidelines within memo is an area of further study. 8. Security Considerations To be determined once specific aspects of this solution are better understood. In particular, the access control framework and the choice of transport will have a major impact on the security of the solution. 9. Acknowledgements This document is a result of discussions at IETF 59 in Seoul Korea attended by the following people: Sharon Chisholm, David Harrington, Ray Atarashi, Yoshifumi Atarashi, Bert Wijnen, Dan Romascanu, Andy Bierman, Randy Presuhn, Chris Lonvick, Eliot Lear, Avri Doria 10. Authors' Address Sharon Chisholm Nortel Networks PO Box 3511, Station C Ottawa, Ontario, K1Y 4H7 Canada Email: schishol@nortelnetworks.com 11. References 11.1 Normative [NETCONF-PROTO] Enns, R., "NETCONF Configuration Protocol", draft-ietf-netconf-prot-03 (work in progress), June 2004. [XML] Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler, Chisholm (Editor) Expires - January 2005 [Page 10]
Framework for Netconf Data Models July 2004 "Extensible Markup Language (XML) 1.0 (Second Edition)", W3C REC REC-xml-20001006, October 2000. [XML-Schema-2] Biron, P., Malhotra A., "XML Schema Part 2: DataTypes", W3C REC REC-XMLSCHEMA-2-20010502, May 2001 11.2 Informative References 12. Full Copyright Statement Copyright (C) The Internet Society (2004). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. i Bradner, S., "The Internet Standards Process -- Revision 3", BCP 9, RFC 2026, October 1996. ii Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997 Chisholm (Editor) Expires - January 2005 [Page 11]