Network Working Group B. Linowski Internet-Draft M. Storch Intended status: Standards Track M. Lahdensivu Expires: September 12, 2008 M. Ersue (ed.) Nokia Siemens Networks March 11, 2008 Kalua - A Data Modeling Language for NETCONF draft-ersue-netconf-kalua-dml-01 Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on September 12, 2008. Linowski, et al. Expires September 12, 2008 [Page 1] Internet-Draft Kalua DML March 2008 Abstract This document specifies a Data Modeling Language (Kalua DML), which is designed to be used as a specification language for the payload of the IETF NETCONF protocol [RFC4741] as well as to specify other management related data models. The Kalua DML aims to fit the requirements specified in draft-linowski-netconf-dml-requirements [Linowski] and supports most of the requirements in RCDML [RCDML]. Comments can be sent to ngo@ietf.org. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 2. Conventions used in this document . . . . . . . . . . . . . . 8 3. Documentation conventions . . . . . . . . . . . . . . . . . . 9 3.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 9 3.2. Model element descriptions . . . . . . . . . . . . . . . 10 3.3. Constraints . . . . . . . . . . . . . . . . . . . . . . . 11 4. Language Introduction . . . . . . . . . . . . . . . . . . . . 12 4.1. Language Design Fundamentals . . . . . . . . . . . . . . 12 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 13 4.2.1. Network resource configuration modeling . . . . . . . 13 4.2.2. Network Modeling and Network Management Support . . . 18 4.2.3. Notifications . . . . . . . . . . . . . . . . . . . . 24 4.2.4. Simplicity and Ease of Use . . . . . . . . . . . . . 27 4.2.5. Straightforward and Lossless Mapping . . . . . . . . 28 4.2.6. Kalua as Metamodel . . . . . . . . . . . . . . . . . 28 4.2.7. Release Management . . . . . . . . . . . . . . . . . 29 4.3. Use of XML and XML Schema . . . . . . . . . . . . . . . . 30 5. Kalua Elements . . . . . . . . . . . . . . . . . . . . . . . 32 5.1. Common Kalua Elements . . . . . . . . . . . . . . . . . . 32 5.1.1. name . . . . . . . . . . . . . . . . . . . . . . . . 32 5.1.2. presentation . . . . . . . . . . . . . . . . . . . . 33 5.1.3. description . . . . . . . . . . . . . . . . . . . . . 33 5.1.4. References to KALUA elements . . . . . . . . . . . . 33 5.1.5. Types . . . . . . . . . . . . . . . . . . . . . . . . 34 5.2. module . . . . . . . . . . . . . . . . . . . . . . . . . 36 5.2.1. Element Attributes . . . . . . . . . . . . . . . . . 36 5.2.2. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 37 5.2.3. Sub-Elements . . . . . . . . . . . . . . . . . . . . 38 5.2.4. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 38 5.2.5. Element Examples . . . . . . . . . . . . . . . . . . 39 5.3. import . . . . . . . . . . . . . . . . . . . . . . . . . 39 5.3.1. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 40 5.3.2. Sub-Elements . . . . . . . . . . . . . . . . . . . . 40 5.3.3. Constraints . . . . . . . . . . . . . . . . . . . . . 40 Linowski, et al. Expires September 12, 2008 [Page 2] Internet-Draft Kalua DML March 2008 5.3.4. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 41 5.3.5. Element Examples . . . . . . . . . . . . . . . . . . 41 5.4. attribute . . . . . . . . . . . . . . . . . . . . . . . . 41 5.4.1. Attributes . . . . . . . . . . . . . . . . . . . . . 42 5.4.2. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 42 5.4.3. Sub-Elements . . . . . . . . . . . . . . . . . . . . 44 5.4.4. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 44 5.4.5. Element Examples . . . . . . . . . . . . . . . . . . 45 5.4.6. NETCONF Payload Examples . . . . . . . . . . . . . . 46 5.5. attribute-group . . . . . . . . . . . . . . . . . . . . . 46 5.5.1. Attributes . . . . . . . . . . . . . . . . . . . . . 47 5.5.2. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 47 5.5.3. Sub-Elements . . . . . . . . . . . . . . . . . . . . 47 5.5.4. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 48 5.5.5. Element Examples . . . . . . . . . . . . . . . . . . 48 5.5.6. NETCONF Payload Examples . . . . . . . . . . . . . . 48 5.6. structure . . . . . . . . . . . . . . . . . . . . . . . . 49 5.6.1. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 49 5.6.2. Sub-Elements . . . . . . . . . . . . . . . . . . . . 50 5.6.3. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 50 5.6.4. Element Examples . . . . . . . . . . . . . . . . . . 50 5.6.5. NETCONF Payload Examples . . . . . . . . . . . . . . 51 5.7. sequence . . . . . . . . . . . . . . . . . . . . . . . . 51 5.7.1. Attributes . . . . . . . . . . . . . . . . . . . . . 52 5.7.2. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 52 5.7.3. Sub-Elements . . . . . . . . . . . . . . . . . . . . 53 5.7.4. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 53 5.7.5. Element Examples . . . . . . . . . . . . . . . . . . 54 5.7.6. NETCONF Payload Examples . . . . . . . . . . . . . . 54 5.8. simple-type . . . . . . . . . . . . . . . . . . . . . . . 55 5.8.1. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 56 5.8.2. Sub-Elements . . . . . . . . . . . . . . . . . . . . 56 5.8.3. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 56 5.9. enum . . . . . . . . . . . . . . . . . . . . . . . . . . 57 5.9.1. Sub-Elements . . . . . . . . . . . . . . . . . . . . 57 5.9.2. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 58 5.9.3. Element Examples . . . . . . . . . . . . . . . . . . 58 5.9.4. NETCONF Payload Examples . . . . . . . . . . . . . . 58 5.10. enum-literal . . . . . . . . . . . . . . . . . . . . . . 58 5.10.1. Attributes . . . . . . . . . . . . . . . . . . . . . 59 5.10.2. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 60 5.10.3. Sub-Elements . . . . . . . . . . . . . . . . . . . . 60 5.10.4. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 60 5.10.5. Element Examples . . . . . . . . . . . . . . . . . . 60 5.10.6. NETCONF Payload Examples . . . . . . . . . . . . . . 61 5.11. union . . . . . . . . . . . . . . . . . . . . . . . . . . 61 5.11.1. Sub-Elements . . . . . . . . . . . . . . . . . . . . 62 5.11.2. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 62 Linowski, et al. Expires September 12, 2008 [Page 3] Internet-Draft Kalua DML March 2008 5.11.3. Element Examples . . . . . . . . . . . . . . . . . . 62 5.11.4. NETCONF Payload Examples . . . . . . . . . . . . . . 63 5.12. restriction . . . . . . . . . . . . . . . . . . . . . . . 63 5.12.1. Sub-Elements . . . . . . . . . . . . . . . . . . . . 64 5.12.2. Restriction Facet-Elements . . . . . . . . . . . . . 64 5.12.3. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 65 5.12.4. Element Examples . . . . . . . . . . . . . . . . . . 66 5.13. typedef . . . . . . . . . . . . . . . . . . . . . . . . . 66 5.13.1. Attributes . . . . . . . . . . . . . . . . . . . . . 66 5.13.2. Sub-Elements . . . . . . . . . . . . . . . . . . . . 67 5.13.3. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 67 5.13.4. Element Examples . . . . . . . . . . . . . . . . . . 67 5.13.5. NETCONF Payload Examples . . . . . . . . . . . . . . 68 5.14. use . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 5.14.1. Attributes . . . . . . . . . . . . . . . . . . . . . 69 5.14.2. Sub-Elements . . . . . . . . . . . . . . . . . . . . 69 5.14.3. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 69 5.14.4. Element Examples . . . . . . . . . . . . . . . . . . 69 5.14.5. NETCONF Payload Examples . . . . . . . . . . . . . . 70 5.15. key . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 5.15.1. Attributes . . . . . . . . . . . . . . . . . . . . . 71 5.15.2. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 72 5.15.3. Sub-Elements . . . . . . . . . . . . . . . . . . . . 72 5.15.4. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 72 5.15.5. Element Examples . . . . . . . . . . . . . . . . . . 73 5.15.6. NETCONF Payload Examples . . . . . . . . . . . . . . 73 5.16. constraint . . . . . . . . . . . . . . . . . . . . . . . 74 5.16.1. Attributes . . . . . . . . . . . . . . . . . . . . . 74 5.16.2. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 74 5.16.3. Sub-Elements . . . . . . . . . . . . . . . . . . . . 74 5.16.4. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 75 5.16.5. Element Examples . . . . . . . . . . . . . . . . . . 75 5.17. class . . . . . . . . . . . . . . . . . . . . . . . . . . 75 5.17.1. Attributes . . . . . . . . . . . . . . . . . . . . . 77 5.17.2. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 77 5.17.3. Sub-Elements . . . . . . . . . . . . . . . . . . . . 78 5.17.4. Constraints . . . . . . . . . . . . . . . . . . . . . 78 5.17.5. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 78 5.17.6. Element Examples . . . . . . . . . . . . . . . . . . 79 5.17.7. NETCONF Payload Examples . . . . . . . . . . . . . . 80 5.18. relationship . . . . . . . . . . . . . . . . . . . . . . 81 5.18.1. Attributes . . . . . . . . . . . . . . . . . . . . . 82 5.18.2. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 83 5.18.3. Sub-Elements . . . . . . . . . . . . . . . . . . . . 83 5.18.4. Source and Target Leaf Sub-Elements . . . . . . . . . 84 5.18.5. Constraints . . . . . . . . . . . . . . . . . . . . . 84 5.18.6. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 86 5.18.7. Element Examples . . . . . . . . . . . . . . . . . . 87 Linowski, et al. Expires September 12, 2008 [Page 4] Internet-Draft Kalua DML March 2008 5.18.8. NETCONF Payload Examples . . . . . . . . . . . . . . 91 5.19. annotation . . . . . . . . . . . . . . . . . . . . . . . 93 5.19.1. Element Attributes . . . . . . . . . . . . . . . . . 93 5.19.2. Sub-Elements . . . . . . . . . . . . . . . . . . . . 94 5.19.3. Constraints . . . . . . . . . . . . . . . . . . . . . 94 5.19.4. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 94 5.19.5. Element Examples . . . . . . . . . . . . . . . . . . 94 5.20. annotation-property . . . . . . . . . . . . . . . . . . . 94 5.20.1. Element Attributes . . . . . . . . . . . . . . . . . 95 5.20.2. Constraints . . . . . . . . . . . . . . . . . . . . . 95 5.20.3. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 95 5.20.4. Element Examples . . . . . . . . . . . . . . . . . . 95 5.21. annotation-type . . . . . . . . . . . . . . . . . . . . . 96 5.21.1. Element Attributes . . . . . . . . . . . . . . . . . 96 5.21.2. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 96 5.21.3. Sub-Elements . . . . . . . . . . . . . . . . . . . . 96 5.21.4. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 97 5.21.5. Element Examples . . . . . . . . . . . . . . . . . . 97 5.22. annotable-type . . . . . . . . . . . . . . . . . . . . . 97 5.22.1. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 98 5.22.2. Element Examples . . . . . . . . . . . . . . . . . . 98 5.23. annotation-property-type . . . . . . . . . . . . . . . . 98 5.23.1. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 99 5.23.2. Sub-Elements . . . . . . . . . . . . . . . . . . . . 99 5.23.3. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 99 5.23.4. Element Examples . . . . . . . . . . . . . . . . . . 100 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 101 7. Security Considerations . . . . . . . . . . . . . . . . . . . 102 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 103 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 104 9.1. Normative References . . . . . . . . . . . . . . . . . . 104 9.2. Informative References . . . . . . . . . . . . . . . . . 104 Appendix A. Kalua XML Schema . . . . . . . . . . . . . . . . . . 105 Appendix B. Module Example: RFC1213-MIB . . . . . . . . . . . . 117 Appendix C. Netconf Payload Example . . . . . . . . . . . . . . 133 Appendix D. NETCONF Notification Example . . . . . . . . . . . . 135 Appendix E. DHCP example from RCDML Requirements Document . . . 136 Appendix F. DHCP augmentation example from RCDML Requirements Document . . . . . . . . . . . . . . . . . . . . . . 141 Appendix G. Example for Partial Lock RPC for NETCONF . . . . . . 142 Appendix H. Support of RCDML Requirements in Kalua . . . . . . . 144 Appendix I. Support of Use Cases for SMI and MIB Modules . . . . 150 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 152 Intellectual Property and Copyright Statements . . . . . . . . . 153 Linowski, et al. Expires September 12, 2008 [Page 5] Internet-Draft Kalua DML March 2008 1. Introduction This document specifies a Data Modeling Language (Kalua DML), which is designed to be used as a specification language for the payload of the IETF NETCONF protocol [RFC4741] as well as to specify other configuration management (CM) related data models. The Kalua DML aims to fit the requirements specified in draft-linowski-netconf-dml- requirements [Linowski] and supports most of the requirements in RCDML [RCDML]. XML-based data exchange and management has become increasingly important because of its flexibility, readability, and ease of use. XML supports hierarchical data structures and is supported by a large number of management applications. The NETCONF Working Group has completed the standardization of the XML-based configuration management protocol and its notification mechanism supporting asynchronous notifications. However, a standardized way of configuration data modeling for Netconf is missing. There is a need to define a standard content layer based on a data-modeling framework for the development of standard and vendor defined data model modules. The necessary Data Modeling Language should address the requirements of the Netconf protocols fully. However, the optimal case would be if the DML can be used also for management fragments other than the Configuration Management. We need to take into consideration the increasing need for extensibility and the opportunity of providing one data modeling language solution for different IETF problems also other than O&M issues e.g. application servers. The aim for a new DML solution at the IETF should be to support extensibility, broader applicability to different kind of management issues and harmonization of data models for manifold management applications. Having this in mind the definition of a common O&M meta-model seems to be sensible where diverse management fragments, such as configuration management, can derive or inherit commonly used data modeling structures and do not define these themselves if already available. For the achievement of such flexibility, we propose an object-oriented approach where attribute groups and meta class definitions can be inherited to avoid data redundancy and to enable data model design flexibility. In the following chapters the KALUA Data Modeling Language fitting to the requirements defined in draft-linowski-netconf-dml-requirements [Linowski] is specified. The specification defines the model elements of the KALUA language. Linowski, et al. Expires September 12, 2008 [Page 6] Internet-Draft Kalua DML March 2008 KALUA language defines how one can model basic concepts which apply to a specific management fragment, such as fragment identifiers, annotations, content trees, and common principles that apply to fragments of the metamodel (such as identifiers of model objects and references between the objects). KALUA language is designed to model the operation and maintenance interface, that is, the crossing point where the network equipment and management system meet. Kalua defines how one can model configuration management concepts and can use and combine the features of Kalua to create expressive and concise data models. Kalua language provides built-in abstract and concrete object classes, attributes, attribute groups and data types that the data models may use by inheritance. This approach harmonizes concepts, which are widely used in operations and maintenance data models. Linowski, et al. Expires September 12, 2008 [Page 7] Internet-Draft Kalua DML March 2008 2. 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 [RFC2119]. Linowski, et al. Expires September 12, 2008 [Page 8] Internet-Draft Kalua DML March 2008 3. Documentation conventions 3.1. Terminology o abstract class: abstract class is a class, which cannot be instantiated. That is, an object instance cannot be created with an abstract class as its class. However, abstract classes as a super-class of a class does not prevent the non-abstract class to be instantiated. o annotation: Additional metadata that refines semantics of a model element. A typed annotation consists of properties, which have a type and a value. o attribute: A named data element that can hold a value (structural feature). o attribute group: Group of attributes supposed to be used only to define the contents of classes (or structures). o attribute container: A model element that contains attributes. Abstraction of attribute groups, structures and classes. o base type: The type from which a refined type was derived, which may be a built-in type or another derived type. o built-in type: A data type defined in the Kalua, such as 'unsignedInt' or string. o class: A language construct used to describe the structural features of instances with an own identity and life-cycle. o data model: A mapping of the contents of an information model into a form that is specific to a particular type of data store or repository. A "data model" is the rendering of an information model according to a specific set of mechanisms for representing, organizing, storing and handling data. o enumeration: Data type with an enumerated set of values. o identifier: Used to identify a model element (class, attribute, etc.) in the containing namespace in a unique way. o information model: An abstraction and representation of the entities in a managed environment, their properties, attributes and operations, and the way that they relate to each other. It is independent of any specific repository, software usage, protocol, or platform. Linowski, et al. Expires September 12, 2008 [Page 9] Internet-Draft Kalua DML March 2008 o list: Sequence of elements of the same type. o managed object: An abstract representation of network resources that are managed. A managed object may represent a physical entity, a network service, or an abstraction of a resource that exists independently of its use. o management fragment: category of management tasks. For example configuration management, performance management, and fault management are management fragments. o model element: A building block of the Kalua language. o module: A set of related definitions o object: Instance of a class o relationship: Definition of an association between instances of two classes. o struct: Set of attributes without own identity o super class or superclass: A class from which the derived class is directly derived. 3.2. Model element descriptions Each model element is described in its own section, with the model element name as a title. Attributes of a model element are described in an attributes section. Model elements, which are contained in a model element, are listed in a sub-elements section. XML elements, which are not model elements, are described in a leaf sub-elements section. In the sub-elements section, a minimum and maximum number of occurrences per containing model element are defined for each sub- element. If maximum number of occurrences is 'unbounded', there is no upper limit on how many times the sub-element may be repeated. The status of the elements has been stated as M(andatory or O(ptional). The model element sections give a definition example of that model element type in Kalua language, the relevant part of the Kalua XML schema, and if applicable, an example of the Netconf payload model by using the model element definition. Linowski, et al. Expires September 12, 2008 [Page 10] Internet-Draft Kalua DML March 2008 3.3. Constraints In case of complex restrictions on sets of acceptable values for features of a Kalua element, the constraints are listed in a separate constraints section. Linowski, et al. Expires September 12, 2008 [Page 11] Internet-Draft Kalua DML March 2008 4. Language Introduction 4.1. Language Design Fundamentals Kalua is an XML-based language for configuration data modeling and network respectively system information modeling. Using XML as a technological foundation for Kalua was chosen since: o NETCONF is an XML passed protocol in which protocol elements as well as payload is encoded in XML. So using XML also as a basis for the language that is supposed to define the structure of NETCONF avoids technological fragmentation. o XML is well known in the IT industry. Using it as a basis for a language decreases the barrier for adoption on the syntax level. People can mainly focus on understating the language concepts and their semantics instead of learning an entirely new syntax that requires new tools for validation and processing. o XML and the specification language for XML documents (XML schema) have almost ubiquitous support in all kinds of IT systems. So creating, validating and processing of language documents should only require low to modest effort. Kalua combines concepts of data modeling (such as structures, sequences, attribute groups etc.) with concepts from object-oriented domain modeling (classes, relationships and class inheritance). This was done because of several reasons: o Network management in particular but also system management in general is often done in a hierarchical manner. That means some kind of manager, a network management system, a mediator but also network elements with management functions have to deal with plain configuration data as well as with some form of data represented by more or less generic models. Being able to express both types of data in Kalua helps to keep the integration and mediation effort low when integrating different systems, operating at different levels in the abstraction hierarchy. Even if other modeling languages like UML (at the highest levels) or SMI (at the lower levels) are used in different layers, being able to represent core concepts of such languages in Kalua helps to avoid "semantic gaps" that require cumbersome and costly "bridges" (in form of mediators, model transformers, etc.) o Enhanced expressiveness: It is very useful to be able to specify plain data structures and links as well as concepts with a more refined semantics like classes and relationships (associations). Linowski, et al. Expires September 12, 2008 [Page 12] Internet-Draft Kalua DML March 2008 Being able to choose the most appropriate modeling construct ensures correctness, maintainability, and reusability. o Flexibility: Managed systems with individual elements are in a continuous change, i.e. new types of network elements are introduced, new versions of such elements are created, and additional ways of connecting (relating) elements need to be represented. The challenge here is to integrate new parts into the picture without having to alter the models for existing parts. Object oriented modeling provides mechanisms to address this challenge. Abstract classes allow defining and relating generic concepts. For example, this facilitates implementing generic management functionality that can be applied to instances of all concrete classes which specialize particular abstract classes. Inheritance allows to add new enhanced or otherwise refined without touching the base class. Relationship refinement allows detailing how newly created resources (represented by classes) participate in already defined relationships. o TM Forum NGOSS SID (Shared Information/Data) model, which is the basis of OSS/J API data models, and the DMTF CIM (Common Information Model) are examples of data models in the network management domain that make use of object- oriented concepts. 4.2. Language Overview This section introduces the core concepts of Kalua, puts them in perspective to common problems in configuration and network modeling, and illustrates their use and interrelations with examples. 4.2.1. Network resource configuration modeling As a language that is supposed to specify the structure of the payload of the Netconf protocol, Kalua has various language features for specifying the data structures representing configuration elements and state description elements of systems. 4.2.1.1. Property modeling As a DML for configuration management, it must be possible to describe the properties of manageable resources that are subject of configuration. In addition, it must be possible to specify properties that represent the actual state of such a manageable resource. Such properties are modeled in Kalua in form of attributes. Linowski, et al. Expires September 12, 2008 [Page 13] Internet-Draft Kalua DML March 2008 kalua:long ... An attribute is simply a property of some manageable entity, which has a name and a type, among some other features that control how the attribute can be used. Attributes can have primitive types (int, boolean, string, etc.), refined simple types, as well as complex types (structures, sequences, etc.). 4.2.1.2. Primitive Types and Refinement of Primitive Types Manageable resources typically have many attributes of primitive type, for example numeric parameters, string type parameters, boolean flags or configuration items with an enumerable set of values. Kalua therefore supports all non-XML specific and not date-related primitives and build-in types defined in [XML schema 1.1 Part 2: Datatypes]. In effect that means that all signed integer types (short, int, long etc.), all unsigned integer types ("unsignedInt", "unsignedLong" etc.), "float" and "double" as well as other basic primitives like "string" and "boolean" are supported. Predefined types are used by referring to them in type elements. kalua:int Also "dateTime" and "duration" are supported in order to express points in time or periods of time. Other XML schema data types that deal with time related values are not part of Kalua in order to avoid that systems interpreting Kalua defined contents have to cope with many types that only provide little additional value (XML schema 1.1 Part 2: Datatypes defines 11 different time related types). In addition, the XML centric types like "NCName" or "QName" are left out from Kalua as their use would require detailed XML knowledge and their value outside XML centric applications is questionable. Since many network resource parameters accept only a subset of the range of values that can be hold by a primitive type instance, it is quite essential that such restrictions can be exactly yet easily expressed. For example, for an attribute that specifies an angle in degrees, it should be possible to limit the range of acceptable values to start from 0.0 inclusive and end at 360.0 exclusive. In Kalua, restricting the set of values that can be applied to an attribute is done by refining an existing primitive type with constraints. Linowski, et al. Expires September 12, 2008 [Page 14] Internet-Draft Kalua DML March 2008 kalua:double ... 4.2.1.3. Complex Datatype Modeling Apart from creating new types by refining primitive types, Kalua also supports the construction of complex types, namely structures, sequences, and enumerations. Many network element parameters accept only a few distinct value representing different configuration options. Also, the state of resources is often described with a few distinct literals. The operational state as defined in ITU-T X.721 is a typical example. In order to be able to define attributes that accept only a value from a fixed set of alternatives, Kalua supports enumerations. ... Many network elements have some kind of data that is organized in lists, arrays or tables, simply because some basic set of data has to present in multiple instances in order to describe configuration or state data properly and completely. Kalua support this kind of data structures in form of sequences. Depending on the properties of the sequence, it can represent arrays (sequences with a fixed length), list (sequences with a variable length) or even bags (sequences in which the actual position of an element has no meaning). kalua:boolean ... Linowski, et al. Expires September 12, 2008 [Page 15] Internet-Draft Kalua DML March 2008 In order to represent the configuration or state data of network resources accurately, it is often needed to group various attributes with probably different types into an own organization unit. Kalua allows defining structures in order to address this need. kalua:string kalua:unsignedShort ... Apart from consolidating attributes into a bigger unit, structures are also useful to structure the namespace for properties of a manageable resource. The full potential of sequences and structures is only unleashed when they are combined. Many network elements and other kinds of configurable systems have some kind of data tables. In Kalua, a table can be modeled as a sequence of structures. The member attributes of the structure define the columns, the properties of the sequence define the extend of the table. kalua:string ... kalua:unsignedShort ... ... ... It is allowed to nest complex type definitions in an arbitrary fashion. Therefor it is possible to define structures that contain sequence-type attributes, sequences of sequences, etc. Linowski, et al. Expires September 12, 2008 [Page 16] Internet-Draft Kalua DML March 2008 4.2.1.4. Named Data Types In the examples above, the structures, sequences and enumerations were not given a name. In case a complex datatype is defined inside an attribute, a name is not needed as the name of the attribute is used to address the element of the datatype. In case a complex datatype is defined inside a sequence, an index-number is used. Often complex types can be reused in various different places of the configuration of a configurable system (network element). For example, many IP-based network elements must deal with several IP- addresses as part of their configuration. It is useful to create a structure, which combines the attributes, e.g. describing an IP- address, and to give it a name enabling the usage wherever needed. Kalua introduces the typedef element for this purpose. A type definition (typedef) simply gives a datatype a name. The name specified as part of the typedef is applied to the datatype defined inside the type definition element. kalua:string ... kalua:unsignedShort ... ... ... Such a user-defined data type can now be in each context where a type is expected. For example, such a type can be used inside attribute definitions and sequence definitions. ipAddress ... Type definitions can only appear in the scope of a module (they are top-level elements). Linowski, et al. Expires September 12, 2008 [Page 17] Internet-Draft Kalua DML March 2008 4.2.2. Network Modeling and Network Management Support Manageable network elements do not exist in isolation. Almost any kind of manageable network resource is in some form related to other network resources. This web of network elements connected via all kinds of relationships - the network topology - is one of the cornerstones of effective network management. It has even significant impact on the management of individual network elements as many of their configuration elements realize or depend on the topology and typically a large portion of their state data can only be interpreted with respect to its place in the network topology. o A network resource is contained in another resource. Containment means that a manageable resource is physically contained in another one, for example a card that is plugged into a rack. However, containment could also mean that a resource is only conceptually enclosed in another resource. This is often synonymous with being dependent in terms of manageability on the containing resource. o A network element is connected to another network element. For example, data transmission channels like PCM links can be seen as connections. o Network resources are in some form related to conceptual entities like maintenance regions or locations. o Network resources use functionality of another resource. Being able to model network resources as well as conceptual resources and the relationships between them is quite essential for many management tasks. Kalua therefore supports two concepts form object oriented domain modeling, namely classes and relationships. 4.2.2.1. Classes The main purpose of classes is to represent configurable entities that share the following characteristics: o they have an own identity, o they have an own, independent life cycle, and o they are often treated as being a more abstract entity. o Instances are often related to instances of other classes in some form. Linowski, et al. Expires September 12, 2008 [Page 18] Internet-Draft Kalua DML March 2008 In Kalua, classes are containers of attributes. That makes them similar to structures. But in contrast to structures: o Classes can have a superclass. A class inherits all attributes (and involvement in relationships) from its superclass. The same applies for the superclass of the superclass and further ancestor classes. o Instances of classes can be used wherever instances of the superclass can be used (Liskov substitution principle). So an is-a relationship is established between the derived class and its superclass. o Classes can be abstract. That is useful to define concepts that serve as a blueprint for concrete derived classes. In addition, relationships can be defined that involve an abstract with a concrete class or even with another abstract class. o Classes must have a key in case they are asscoiated to other classes by reference relationships. As instances of such classes have to have an own identity, it must be possible to address class instances uniquely by a key value. That is also needed in order to realize relationships between classes respectively between instances of related classes. Classes are a vehicle to model "first-class network resources type" like types of network resources with an own O&M interface as well as independent conceptual entities like regions, sites, policies, plans etc. 4.2.2.2. Relationships Kalua also supports the concept of relationships. A relationship associates instances of two classes, which can be two distinct classes or the same class. The two endpoints of the relationship are called source and target. The naming of the endpoints should lead to a consistent usage of relationship definitions. This does not mean that a relationship can only be navigated from source to target. An important aspect of relationships in Kalua are that they are defined outside the classes they connect. That has several advantages: o It is not necessary to anticipate and define all kinds of relationship that might be needed in the future. Instead, relationship can be added "on top" of the classes they connect later when really needed. That also prevents having to deal with relationships that were once introduced because it was assumed Linowski, et al. Expires September 12, 2008 [Page 19] Internet-Draft Kalua DML March 2008 they would be needed but actually are not used. o Relationships and classes can be separated into different modules. Therefore, it is possible to define classes and their inner structure (by using and defining all kinds of data types) in one module and put relationships and supplementary definitions for network modeling in another module. While a network element agent only deals with the first module, a higher-level management system can use the second module, which includes the first. o They are very much decoupled. In case the definition of a relationship would be owned by one of its endpoints (or the definition would be even shared between both endpoints), introducing a new relationship would require that the modules that contain the classes to be related have to be changed. That might not be a big technical problem, but is often more an organizational issue. ... ... Manager ... ManagedObject ... .... Kalua also supports relationship refinement. I.e. it is possible to define relatively high- level (abstract) relationships, which are refined by relationships that connect more concrete classes. .... A typical use case for this feature is the proper modeling of Linowski, et al. Expires September 12, 2008 [Page 20] Internet-Draft Kalua DML March 2008 containment relationships, especially such that define the management hierarchy of network resources. The parent-child relationship is then defined at the root of the class hierarchy for managed objects (managed object contains an arbitrary number of other managed objects). In order to properly define the relationship semantics as well as to enhance flexibility and expressiveness, three kinds of relationships are supported in Kalua: o Reference relationships. They simply associate two classes. o Containment relationships. This kind of relationship defines a strict existence dependency between the contained object (target end) and the containing end (source end). It means that if the container object is deleted all contained objects are deleted as well. o Calculated relationships. Here, it is defined which instances of the source and target end class (and their subclasses) are actually related by a relationship expression. In effect, the contents of the relationship are actually defined by the state of the instances at the source and target end. Such relationships have to be evaluated "online" whenever they are queried. Two important aspects of relationships as defined in Kalua deserve some explicit discussion. When specifying the containment of class instances in Kalua, this has to be done by defining containment relationships between them. While this requires some effort for explicit specification of the containment relationships, it has several advantages: o Especially, it is possible to specify more than one containment relationship that has the same contained class at the target end. I.e. a class (respectively their instances) can be contained in multiple different classes. o It is possible to specify in a common way that a previously defined class can be contained in a new class, so that the definition of containment is not constrained by any other organizational aspect. o The multiplicity of instances of the contained class (target end) can be exactly specified. Kalua supports the specification of prescriptive reference relationships and containment relationships. In addition, it allows Linowski, et al. Expires September 12, 2008 [Page 21] Internet-Draft Kalua DML March 2008 the specification of descriptive calculated relationships. It is important to support both types of relationships as they address different use cases: o In many cases references to resources in the same or other network elements are realized with attributes that contain some kind of implicit key value or a part of a composite key. For example, in order to describe an "is-connected-to" relationship associating two network elements that are physically connected via PCM links, the reference to the other end of the association could be represented by a numerical id of the PCM link terminated in the network element plus the index of the timeslot in that PCM link. The PCM id as well as the timeslot index is then represented as two numerical attributes. This kind of association is best represented with a calculated relationship with an expression that compares tuples of instances of the class at the target end and instances of the class at the source end by checking if they have the same PCM link id and timeslot index stored in two particular attributes. Realizing such a descriptive relationship with a reference relationship typically leads to the problem of keeping track with the configuration changes. o Now if such network elements should be associated to a maintenance region, a conceptual entity that groups resources based on their geographical or even logical location in a network, using a descriptive approach does not work, respectively is rather inappropriate. Many network elements do not have configuration elements that can be used to store a key of a maintenance region, even putting this information directly into a resource in the network is not a good idea in the first place. This kind of association is best realized in a prescriptive way by defining a reference relationship. It is then left to the system that in managing relationships specified in Kalua where and how the actual relationship information is stored. The key specification feature, which is part of Kalua, just describes which attributes of a resource could be used for storing relationships. 4.2.2.3. Information Modeling with Classes and Relationships The example below illustrates some of the essential aspects of classes and relationships. First, network elements and locations are modeled as abstract classes because network elements and sites Linowski, et al. Expires September 12, 2008 [Page 22] Internet-Draft Kalua DML March 2008 obviously have an independent life cycle. A network element comes into existence terms of management at the latest when it is deployed into the network and switched on. A location comes into existence when somebody creates it in some kind of management system. Network element as well as location is abstract concepts. By itself they do not contain enough information to be usable for most (but not necessarily all) concrete management operations. However, defining them allows the establishment of a relationship between them, which provides already some value. For example, it is possible to tell if two network elements are placed at the same location and get the description of the location of a network element. As instances of "ManagedObject" are related to the instance of "Location", they can be also related to instances of "Site" as a specific type of location. It is even possible to define another class that derives from "Location", e.g. one that uses geographical coordinates to describe a location, and uses instances of that class to represent the location for any type of network elements. kalua:long" ... kalua:string" ... locationId ManagedObject kalua:string ... ... ManagedObject ... Linowski, et al. Expires September 12, 2008 [Page 23] Internet-Draft Kalua DML March 2008 Location ... .... Location kalua:string ... kalua:string ... kalua:string ... kalua:string ... 4.2.3. Notifications Same data model applies to change notifications, get (get-config, get) and edit-config operations of Netconf. In the context of Netconf protocol, operation attribute of a data element within the notification indicates whether the data has been merged, created, replaced, or deleted. The semantics of updating the data with notification from server to the client are the same as changing data with an edit-config from client to server. Default behavior is to merge. Several changes can be combined in the same notification, and changed changes done with one edit-config may be sent as several notifications. The following example demonstrates how the same Kalua model is used in get-config and edit-config requests and in a change notification. The following is the definition of the module used in the example: Linowski, et al. Expires September 12, 2008 [Page 24] Internet-Draft Kalua DML March 2008 http://www.example.com/profile pr/ 1.0 kalua:string string name First, the client requested get-config shows the initial state of the configuration: profile-1 auto profile-2 manual Linowski, et al. Expires September 12, 2008 [Page 25] Internet-Draft Kalua DML March 2008 Then, another Netconf client requests edit-config from the same server to change the running configuration: profile-1 manual Then, a change event notification is sent to all clients which have subscribed the notifications for this part of the data: profile-1 auto The client can also see the change in the get-config result. The data parts of the data which are not included in the change notification have not been changed. Linowski, et al. Expires September 12, 2008 [Page 26] Internet-Draft Kalua DML March 2008 profile-1 auto profile-2 manual 4.2.4. Simplicity and Ease of Use While being complete in terms of expressive power, the DML should be as simple as possible. The main reason for that is ease of use and understandability. Simplicity in the context of a modeling language means: o As few language elements as possible. The more elements a language has, the more time it takes to learn them. o No complicated rules that restrict how and in which way language elements can be used. Having the freedom to use language elements wherever they make sense allows concentrating on the modeling problem at hand. Kalua is an XML based language, because: o The XML syntax is well known and the structure of basic syntax elements like elements, attributes is quite simple. As long as the overall structure of the DML language documents remains at a Linowski, et al. Expires September 12, 2008 [Page 27] Internet-Draft Kalua DML March 2008 decent level and the verbosity is minimized, the usage of XML syntax is acceptable. o There are also a huge amount of tools available that allow editing, validating, and processing XML. That compensates the existing annoyances of XML as a language. o Finally, usability needs to be seen from the point of view of an engineer that is supposed to implement software that is reading, writing, or transforming DML documents. In case of an XML-based language, one can use existing, well-known software components with standardized or at least widely accepted interfaces. 4.2.5. Straightforward and Lossless Mapping 4.2.5.1. Mapping to XML Schema As Kalua is an XML-based language, which describes structural aspects of network resources, it is possible to translate a Kalua model (document) into an XML schema. That allows to use off the shelf XML parsers to read Kalua model files, check their well- formedness and validate their contents. 4.2.5.2. Mapping to UML2 As Kalua supports with classes, relationship (associations), and inheritance some of the core object oriented design concepts, translating Kalua models to UML2 models is done smoothly. Here the integration of object oriented concepts and their distinction from data modeling concepts pays back as it does not need to "guess" (by using some formalized heuristics) by what UML2 metamodel element a Kalua element is correctly represented. 4.2.5.3. Mapping from UML2 Also for mapping in the other direction, from UML2 to Kalua, the integration of object- oriented concepts makes things easier. The mapping from models specified with UML (version 2 as well as previous 1.x releases) is important as many standard models in the telecommunication domain like TMF SID, CIM and 3GPP are specified in UML. 4.2.6. Kalua as Metamodel Models can also be seen as instances of a metamodel. This point of view is especially important because the metamodel prescribes to a large extend how models are represented in object oriented terms as the predominant paradigm in programming languages today. Linowski, et al. Expires September 12, 2008 [Page 28] Internet-Draft Kalua DML March 2008 The language features of Kalua are designed so that they can be easily mapped to metamodel classes and mix-in-classes (that can be also represented as interfaces). That should foster a structurally common representation of Kalua model elements in programming environments. 4.2.7. Release Management Managed resources change over time, new features are introduced, existing features are removed. Thus their models must also change to accurately reflect these changes. At the same time, existing data, created with the old model, must be usable together with the new data. Applications developed against old model should be usable after upgrade. For example, views created in a management system should not become unusable whenever there is a change in the managed resources. They should be usable as long as the change is not affecting the parts of the model that they rely on. For example, adding an attribute to a class does not affect an application reading the data, and adding an optional attribute to a class does not affect the application writing the data. Kalua allows any number of releases of a module. Each module release may add or remove module elements compared to other releases. Model elements with the same name appearing in different releases of the same module are considered to represent the same type of managable resources. Multiple releases frequently occur when building systems that are both in a manager and agent role. E.g. a management system manages several agents via the NETCONF protocol, and exposes its own configuration data to an upper level management system via the NETCONF protocol, including the configuration data from the managed agents. Each agent defines its configuraton data as a Kalua module. The management system imports each of these modules into one composite Kalua module. This composite module defines the configuration data the management system exposes towards any upper level management system via the NETCONF protocol. In the upper scenario, the need for multiple releases occurs when there are Kalua modules of different releases but same type among the modules of the agents. Hierarchies of NETCONF interfaces may appear in the following system architectures: o A controller device providing a NETCONF interface manages several subdevices via NETCONF. Linowski, et al. Expires September 12, 2008 [Page 29] Internet-Draft Kalua DML March 2008 o An element management system providing a NETCONF interface manages several devices via NETCONF. o A regional management system providing a NETCONF interface manages several element management systems via NETCONF. o A global management system manages several regional management systems via NETCONF. Example Controller http://www.example.controller.com/ controller 2.1 Example http://www.subdevice.com/ subdevice1.0 1.0 http://www.subdevice.com/ subdevice2.0 2.0 4.3. Use of XML and XML Schema Kalua is an XML-based language. The Kalua syntax and basic part of its semantics are specified in an XML schema - the Kalua schema (see Appendix A.). The syntax of Kalua was designed along the following guidelines: o Primary language concepts that can contain other language concepts are realized as XML elements. o Properties of primary language elements that potentially have long text values are represented as leaf XML elements with simple type contents. o Only the name of definitions and properties that always have short values are realized as XML attributes. Linowski, et al. Expires September 12, 2008 [Page 30] Internet-Draft Kalua DML March 2008 o Mixed content is prohibited. Linowski, et al. Expires September 12, 2008 [Page 31] Internet-Draft Kalua DML March 2008 5. Kalua Elements KALUA specification introduces a set of language elements. Many of the concepts defined in KALUA contain a set of common attributes or features defined in the sub- chapters below. Each concept definition specifies which of these attributes, if any, are applicable to the concept and whether the attribute is mandatory or not in this context. 5.1. Common Kalua Elements The elements in this section are commonly used by Kalua language elements that define model elements. The value for each of the elements is provided as element body text. 5.1.1. name Type: string [a-zA-Z][_A-Za-z0-9]{0,29} Description: "name" is a unique and permanent identifier of the KALUA element within a single module. "name" cannot be changed during the lifetime of the element (that is, across releases of a module); if the identifier changes, the element is considered to be new and the old element is considered to be deleted. Thus, the old data corresponding to this object is no longer accessible through the adaptation. The case of characters does not play a role in the uniqueness criteria. This means 'BTS' and 'bts' are overlapping identifiers. However, references to the "name" use the same case as in the definition of the element (see Section 5.1.4.). "name" is used to refer to the KALUA element in KALUA files, database schemata, data files, other metadata/configuration files, APIs, and everywhere where references to elements need to be interpreted by applications. However, "presentation" (described below) should be used in user interfaces to identify the elements. In context of adaptation development for each NE type, the uniqueness criteria of identifiers needs to be defined so that uniqueness constraints described in this specification and KALUA fragment specifications are met. Elements of different type may have the same "name". Specific model element types may have additional constraints for Linowski, et al. Expires September 12, 2008 [Page 32] Internet-Draft Kalua DML March 2008 uniqueness of the "name" for a specific concept, defined separately for each model element type. 5.1.2. presentation Type: string, maximum length 100 Description: A short name visible to the end-user in application user interfaces. "presentation" is not used to refer to a KALUA element in data or metadata. Only end-user documentation should refer to the elements using "presentation". "presentation" can be changed without breaking the compatibility of existing data or other parts of metadata. "presentation" included in the model files is just a default. Default presentation could be overridden by language specific "presentation". If "presentation" is omitted it defaults to the value of name. "presentation" does not need to be unique within an adaptation or across adaptations. However, as "presentation" normally serves as an identifier of the element for the user, you should avoid overlapping values where two elements may be used in the same context (for example, in AttributeDef sub-elements of one ClassDef). 5.1.3. description Type: string, maximum length 2000 Description: "description" is a longer text, which helps end users to understand the purpose and other details of the element. It can span multiple lines, and can contain any characters. Applications displaying the "description" are also capable of deriving and displaying such information directly from metadata. 5.1.4. References to KALUA elements KALUA language specifies references from model elements to other model elements. For each reference, a target model element type, for example attribute-group, is defined. While the semantics of a reference depend on model element type, and are definied for each model element type separately, KALUA uses a common syntax for the references to the model elements. The reference consists of a namespace prefix, a colon, and a model element name, that is, ns- Linowski, et al. Expires September 12, 2008 [Page 33] Internet-Draft Kalua DML March 2008 prefix:name. Each reference has one target model element. The module where the model element is defined is considered target module of the reference. If the target module is the module containing the reference, the ns- prefix part of the reference must equal to the ns-prefix element of the module. If the target module is another module, there must exist an import element, within the module containing the reference or some modules imported by the module containing the reference, where value of the ns-prefix element equals to the ns-prefix part of the reference and ns-uri element equals to the ns-uri element of the target module. The name part of a reference must be equal to the value of the name attribute of the target model element. 5.1.5. Types KALUA supports a subset of the primitive types respectively build-in types defined in 'XML Schema 1.1 Part 2: Datatypes'. Most of the numeric types are supported, the types for specifying a point in time and a duration, string and boolean as well as a selection of name types. The table below lists all primitive types supported by Kalua. Their value range, support for special values (like NaN, INF, -0), and lexical mapping is supported as defined in 'XML Schema Part 2: Datatypes' [XSD-TYPES]. In addition: o a value for type dateTime can also be specified in seconds from Epoch 00:00:00 on January 1, 1970, encoded as non-negative, decimal integer. o A value for type duration can also be specified in seconds, encoded as non-negative, decimal integer. In effect, values matching the regular expression '\+?[1-9][0-9]*' has to be interpreted as seconds from Epoch (dateTime) respectively duration in seconds (duration). Linowski, et al. Expires September 12, 2008 [Page 34] Internet-Draft Kalua DML March 2008 +---------------+---------------------------------------------------+ | Identifier | Description | +---------------+---------------------------------------------------+ | string | String of characters. In case no length or | | | max-length restriction is specified, it is not | | | guaranteed that strings longer than 250 | | | characters can be stored in attributes that use a | | | the string type or a type that is based on string | | | without any length restriction.. | | | | | boolean | Boolean value | | | | | byte | Signed 8 bit integer. | | | | | short | Signed 16 bit integer | | | | | int | Signed 32 bit integer | | | | | long | Signed 64 bit integer | | | | | unsignedByte | Unsigned byte | | | | | float | IEEE 754 compliant, 32 bit floating point value | | | | | double | IEEE 754 compliant, 64 bit floating point value | | | | | unsignedShort | Unsigned 16 bit integer | | | | | unsignedInt | Unsigned 32 bit integer | | | | | unsignedLong | Unsigned 64 bit integer | | | | | dateTime | Date and time value | | | | | duration | A duration of time | | | | | decimal | Fixed point decimal with p decimal digits before | | | the decimal point and s digits behind the decimal | | | point. p is the precision and s the scale. The | | | default precision is 10 and the default scale is | | | 6. Specify precision and scale with a precision | | | constraint. | | | | | integer | Signed integer up to p decimal digits, where p is | | | the precision. The default precision is 10.. | +---------------+---------------------------------------------------+ Linowski, et al. Expires September 12, 2008 [Page 35] Internet-Draft Kalua DML March 2008 5.2. module "module" is the root element of the Kalua definitions. Each Kalua document must contain exactly one "module" element. All other definitions of the model are contained in a module element. "module" is a logical grouping of definitions. However, the split of definitions to separate modules also implies the following semantics: o "module" implies the version of the definitions o "module" implies the namespace of the definitions o applicability of annotation types are limited to those "modules" which define or import them o references to model elements can occur only to definitions in the "module" itself, or any directly or indirectly imported module 5.2.1. Element Attributes +-----------+------------+--------------------------------------+---+ | Attribute | Type | Description | S | | | [Default] | | | +-----------+------------+--------------------------------------+---+ | name | xsd:string | Unique identifier of the module | M | | | | within systems using this module. | | | | | To select globally unique | | | | | identifiers, identifiers should | | | | | begin with an inverse domain name of | | | | | the entity defining the module. | | +-----------+------------+--------------------------------------+---+ Linowski, et al. Expires September 12, 2008 [Page 36] Internet-Draft Kalua DML March 2008 5.2.2. Leaf Sub-Elements +--------------+-------------------+----------------------------+---+ | Sub-Element | Type [Default] | Description | S | +--------------+-------------------+----------------------------+---+ | presentation | xsd:string | See Section 5.1.2 | O | | | | | | | description | xsd:string | See Section 5.1.3 | O | | | | | | | ns-uri | xsd:string | Defines the target | M | | | | namespace of the all | | | | | definitions in this | | | | | module. In Kalua, this | | | | | uniquely identifies the | | | | | module. | | | | | | | | ns-prefix | xsd:string | Defines the prefix used to | M | | | | attach the namespace to | | | | | the model element names. | | | | | | | | release | xsd:string | Indicates the release | M | | | maximum length | version of this specific | | | | 20. [a-zA-Z0-9]+ | definition of the module. | | | | (\.[a-zA-Z0-9]+)* | | | | | | | | | organization | xsd:string | Name of the organization | M | | | maximum length | responsible for the | | | | 100 | module. | | +--------------+-------------------+----------------------------+---+ Linowski, et al. Expires September 12, 2008 [Page 37] Internet-Draft Kalua DML March 2008 5.2.3. Sub-Elements +-----------------+-----------+-----------+-------------------------+ | Sub-Element | MinOccurs | MaxOccurs | Description | +-----------------+-----------+-----------+-------------------------+ | annotation | 0 | unbounded | See Section 5.19 | | | | | | | import | 0 | unbounded | See Section 5.3 | | | | | | | typedef | 0 | unbounded | See Section 5.13 | | | | | | | attribute-group | 0 | unbounded | See Section 5.5 | | | | | | | class | 0 | unbounded | See Section 5.17 | | | | | | | relationship | 0 | unbounded | See Section 5.18 | | | | | | | annotation-type | 0 | unbounded | See Section 5.21 | +-----------------+-----------+-----------+-------------------------+ 5.2.4. XSD 5.2.5. Element Examples Example Ethernet Interface http://www.example.com/ example 2.1 Example 5.3. import "import" element makes all definitions from another module available in the module containing the "import" element. All definitions imported to that other module from any other modules are imported as well. Linowski, et al. Expires September 12, 2008 [Page 39] Internet-Draft Kalua DML March 2008 5.3.1. Leaf Sub-Elements +-------------+-------------------+-----------------------------+---+ | Sub-Element | Type [Default] | Description | S | +-------------+-------------------+-----------------------------+---+ | ns-uri | xsd:string | Selects the imported | M | | | | module. | | | | | | | | ns-prefix | xsd:string | Defines the namespace | M | | | | prefix used in the module | | | | | containing the import | | | | | element to attach the | | | | | namespace to the model | | | | | element names. When | | | | | writing a module, ns-prefix | | | | | of the imported module | | | | | should be used as the ns- | | | | | prefix of the import | | | | | element, unless there is a | | | | | conflicting ns-prefix | | | | | already in use in the | | | | | module. | | | | | | | | release | xsd:string | Selects from which release | M | | | maximum length | of the module the | | | | 20. [a-zA-Z0-9]+ | definitions are imported. | | | | (\.[a-zA-Z0-9]+)* | | | | | | | | | description | xsd:string | See Section 5.1.3 | O | +-------------+-------------------+-----------------------------+---+ 5.3.2. Sub-Elements +-------------+-----------+-----------+-----------------------------+ | Sub-Element | MinOccurs | MaxOccurs | Description | +-------------+-----------+-----------+-----------------------------+ | annotation | 0 | unbounded | See Section 5.19 | +-------------+-----------+-----------+-----------------------------+ 5.3.3. Constraints Model element references are only allowed to model elements in modules, which are directly or indirectly imported by the module in which the reference is given. A module must not directly or indirectly import definitions from several releases of a module. Linowski, et al. Expires September 12, 2008 [Page 40] Internet-Draft Kalua DML March 2008 A module must not directly or indirectly import itself. That is, circular imports between modules are not allowed. All namespace prefixes, including the prefix of the module itself, must be unique within the module. 5.3.4. XSD 5.3.5. Element Examples http://www.example.com/ example 2.1 5.4. attribute An "attribute" represents structural features of some kind of manageable resource. As such, "attributes" can be part of an attribute group, a class, or a structure. An "attribute" can be addressed via its name. Each "attribute" name must be unique with respect to all "attributes" defined in the containing element (class, structure or attribute group) and the "attributes" inherited from superclasses and incorporated "attribute" groups. The most important property of an "attribute" is its type. "Attributes" can have a primitive type (for example, string, long, or boolean) as well as a constructed data type, that is, a sequence type, structure type or an enumeration. It is possible to refer to named types (see Section 5.13.) via the type element as well as to define the type inline by using sequence, structure or primitive elements inside the attribute element. Linowski, et al. Expires September 12, 2008 [Page 41] Internet-Draft Kalua DML March 2008 5.4.1. Attributes +-----------+----------------+---------------------------+----------+ | Attribute | Type [Default] | Description | Use | +-----------+----------------+---------------------------+----------+ | name | name-string | The name of the | required | | | (see | attribute. | | | | Section 5.1.1) | | | +-----------+----------------+---------------------------+----------+ 5.4.2. Leaf Sub-Elements +--------------+------------+-----+-----+---------------------------+ | Sub-Element | Type | min | max | Description | | | [Default] | oc. | oc. | | +--------------+------------+-----+-----+---------------------------+ | presentation | xsd:string | 0 | 1 | The presentation name | | | | | | used for the attribute. | | | | | | This name should be used | | | | | | in GUI's when presenting | | | | | | the attribute to human | | | | | | end users. | | | | | | | | description | xsd:string | 0 | 1 | The description of the | | | | | | attribute | | | | | | | | mandatory | none | 0 | 1 | If present must be | | | | | | provided during creation | | | | | | of the owning entity. | | | | | | Otherwise providing a | | | | | | value is optional | | | | | | | | optional | none | 0 | 1 | If present, a value might | | | | | | be provided during | | | | | | creation of the owning | | | | | | object. This is the | | | | | | default behavior. | | | | | | | | read-only | none | 0 | 1 | if present, the attribute | | | | | | is read only. It neither | | | | | | possible to provide a | | | | | | value during creation of | | | | | | the owning object | | | | | | creation nor to change | | | | | | the value afterwards. | | | | | | | Linowski, et al. Expires September 12, 2008 [Page 42] Internet-Draft Kalua DML March 2008 | read-write | none | 0 | 1 | If present, the attribute | | | | | | can be read and written. | | | | | | This is the default | | | | | | behavior. | | | | | | | | unchangeable | none | 0 | 1 | If present, the attribute | | | | | | might be or must be | | | | | | assigned a value during | | | | | | creation of the owning | | | | | | object (depending on the | | | | | | presence of "mandatory" | | | | | | or "optional"), but | | | | | | cannot be changed | | | | | | afterwards. | | | | | | | | default | xsd:string | 0 | 1 | Specifies the default | | ValueLiteral | | | | value for the attribute. | | | | | | Default values can only | | | | | | be specified for | | | | | | primitive types. If the | | | | | | type is not 'string', a | | | | | | valid value literal must | | | | | | be used. | | | | | | | | unit | xsd:string | 0 | 1 | Specifies the unit in | | | | | | which the value for this | | | | | | attribute is measured. | | | | | | In case a unit is | | | | | | specified for the | | | | | | attribute type, this is | | | | | | overwritten by this unit. | +--------------+------------+-----+-----+---------------------------+ Only one of the elements "read-write", "read-only" or "unchangeable" might be present in an attribute element. Only "mandatory" or "optional" might be present (but not both). In case "read-only" is present, neither "mandatory" nor "optional" could be present. Linowski, et al. Expires September 12, 2008 [Page 43] Internet-Draft Kalua DML March 2008 5.4.3. Sub-Elements +-------------+--------+-----------+--------------------------------+ | Sub-Element | min | max | Description | | | occurs | occurs | | +-------------+--------+-----------+--------------------------------+ | annotation | 0 | unbounded | See Section 5.19 | | | | | | | constraint | 0 | unbounded | Constraints applied in the | | | | | context of the attribute. | | | | | | | type | 0 | 1 | The named type of the | | | | | attribute. | | | | | | | primitive | 0 | 1 | The inline defined primitive | | | | | type of this attribute | | | | | | | structure | 0 | 1 | The inline defined structure | | | | | type of this attribute. | | | | | | | sequence | 0 | 1 | The inline defined sequence | | | | | type of this attribute. | +-------------+--------+-----------+--------------------------------+ 5.4.4. XSD Linowski, et al. Expires September 12, 2008 [Page 44] Internet-Draft Kalua DML March 2008 5.4.5. Element Examples Linowski, et al. Expires September 12, 2008 [Page 45] Internet-Draft Kalua DML March 2008 Frequency kalua:int 1800 Bearer channel frequency. kalua:float kalua:float 5.4.6. NETCONF Payload Examples 1900 120.87 97.334 5.5. attribute-group "attribute groups" are a means to bundle a set of attributes that are typically used together. For example, an "attribute group" for describing an IP address would bundle a string-typed attribute for the hostname and a short-typed attribute for the port. The main purpose of "attribute groups" is to be incorporated (used) by model elements that can contain attributes, so classes, structures and other attribute groups. Using an "attribute group" means that all the attributes that belong to the attribute group are imported into the using element. Attributes incorporated from an attribute group are otherwise treated as if they were directly inside incorporating element. No 'is-a' relationship is established between the "attribute group" and a using class or structure. As the "attribute group" concept is Linowski, et al. Expires September 12, 2008 [Page 46] Internet-Draft Kalua DML March 2008 only addressing organizational purposes, "attribute groups" cannot be instantiated. 5.5.1. Attributes +---------+----------------+-----------------------------+----------+ | Feature | Type | Description | Use | +---------+----------------+-----------------------------+----------+ | name | name-string | The name of the attribute | required | | | (see | group. It must be unique | | | | Section 5.1.1) | within the containing | | | | | module. | | +---------+----------------+-----------------------------+----------+ 5.5.2. Leaf Sub-Elements +--------------+------------+-----+-----+---------------------------+ | Sub-Element | Type | min | max | Description | | | | oc. | oc. | | +--------------+------------+-----+-----+---------------------------+ | presentation | xsd:string | 0 | 1 | The presentation name | | | | | | used for the attribute | | | | | | group. | | | | | | | | description | xsd:string | 0 | 1 | The description of the | | | | | | attribute group. | +--------------+------------+-----+-----+---------------------------+ 5.5.3. Sub-Elements +-------------+--------+-----------+--------------------------------+ | Sub-Element | min | max | Description | | | occurs | occurs | | +-------------+--------+-----------+--------------------------------+ | constraint | 0 | unbounded | Constraints that apply in the | | | | | context of this attribute | | | | | group. | | | | | | | attribute | 0 | unbounded | The attributes belonging to | | | | | this attribute group. | | | | | | | use | 0 | unbounded | The attribute groups used by | | | | | this attribute group | | | | | | | key | 0 | unbounded | Key definitions | +-------------+--------+-----------+--------------------------------+ Linowski, et al. Expires September 12, 2008 [Page 47] Internet-Draft Kalua DML March 2008 5.5.4. XSD 5.5.5. Element Examples IP Address IP address attributes kalua:string kalua:unsignedShort 5.5.6. NETCONF Payload Examples . . www.example.com 30100 . . Linowski, et al. Expires September 12, 2008 [Page 48] Internet-Draft Kalua DML March 2008 5.6. structure "structures" define cohesive sets of named properties of potentially varying type. In Kalua, "structure" elements define ordered sets of attribute elements. Each member attribute must have a name that is unique with respect to the other attributes contained in the "structure" or incorporated from used attribute groups. A "structure" itself has no name. A "structure" can be either a sub- element of an attribute definition, sequence definition or a sub- element of a type definition. In case a structure is defined inside an attribute or sequence, the structure can be addressed only by the name of the owning attribute respectively the element index in the sequence. In case a structure is part of a type definition, the type name is applied to the structure. Such structure types can be reused (referred to) in all contexts where a data type is expected. Since structures are attribute containers, structures can use or incorporate attribute groups. All attributes defined in used attribute groups become members of the "structure" and can be treated as any other attribute directly defined in the structure. Also keys can be defined for structures. In case the scope is global, the key attributes uniquely identify each "structure" instance within all instances of this "structure" definition. Keys with local scope identify "structure" instances only within the context of the containing object. Such keys are primarily used for structures that are used as elements of sequences. This allows to also addressing them via a key value. 5.6.1. Leaf Sub-Elements +-------------+----------------+-----+-----+------------------------+ | Sub-Element | Type | min | max | Description | | | | oc. | oc. | | +-------------+----------------+-----+-----+------------------------+ | description | name-string | 0 | 1 | The description of the | | | (see | | | structure type. | | | Section 5.1.1) | | | | +-------------+----------------+-----+-----+------------------------+ Linowski, et al. Expires September 12, 2008 [Page 49] Internet-Draft Kalua DML March 2008 5.6.2. Sub-Elements +-------------+--------+-----------+--------------------------------+ | Sub-Element | min | max | Description | | | occurs | occurs | | +-------------+--------+-----------+--------------------------------+ | annotation | 0 | unbounded | Annotations attached to the | | | | | structure. | | | | | | | constraint | 0 | unbounded | Constraints that apply in the | | | | | context of this attribute | | | | | group. | | | | | | | attribute | 0 | unbounded | The attributes belonging to | | | | | this attribute group. | | | | | | | use | 0..n | unbounded | The attribute groups used by | | | | | this attribute group | | | | | | | key | 0..n | unbounded | Key definitions | +-------------+--------+-----------+--------------------------------+ 5.6.3. XSD 5.6.4. Element Examples (x,y) kalua::double kalua:double Linowski, et al. Expires September 12, 2008 [Page 50] Internet-Draft Kalua DML March 2008 5.6.5. NETCONF Payload Examples . . . 441.2 172.5 . . 5.7. sequence A "sequence" is a data structure that contains several objects of the same type that can be addressed by their position in the "sequence". Sequences are therefore an ordered collection. Each "sequence" has a base type that determines the type of its elements. Constraints have a minimum length and a maximum length. By setting the maximum length to unbounded, it is possible to define sequences with arbitrary length. Sequences are also constrainable elements. Constraints defined within a "sequence" are applied in the context of the "sequence" object, they are not implicitly applied to each member. However, since the member type can be defined inline, it is no problem to refine an exiting data type with additional constraints. Sequence types have no name. A "sequence" can be either a sub- element of an attribute definition, another "sequence" definition, or a sub-element of a type definition. In case a "sequence" is defined inside an attribute or "sequence", the "sequence" type cannot be reused in another context. Instances can be addressed by the name of the owning attribute respectively the element index in the "sequence". In case a "sequence" is part of a type definition, the type name is applied to the "sequence". Such "sequence" types can be reused (referred to) in all contexts where a data type is expected. When representing sequence contents as XML elements, two cases have to be distinguished: o In case the elementName attribute of the sequence element is specified, the contents of each element of the sequence is wrapped into an XML element with the given name. Making the "boundaries" of a sequence element value explicit in the serialized form is Linowski, et al. Expires September 12, 2008 [Page 51] Internet-Draft Kalua DML March 2008 sometimes needed in order to make sure that the original structure of the contents can be reconstructed from the serialized form. For example, a serialized form of a sequence of sequence of unbounded maximum length that does not demarcate the start and beginning of the elements of the inner sequence does not allow reconstructing the original input. o In case elementName is not defined, each element is serialized as if it was directly contained in the owning element (typically an attribute). In effect, the sequence is "flattened". 5.7.1. Attributes +-------------+-----------------+------------------------+----------+ | Attribute | Type [default] | Description | Use | +-------------+-----------------+------------------------+----------+ | minLength | xsd:unsignedInt | The minimum sequence | optional | | | [0] | length | | | | | | | | maxLength | xsd:unsignedInt | The maximum sequence | optional | | | [unbounded] | length | | | | | | | | elementName | name-string | The name used for | optional | | | (see | elements in the | | | | Section 5.1.1) | sequence data | | | | | representation. | | | | | | | | ordered | xsd:boolean | Tells if the sequence | optional | | | [false] | represents an ordered | | | | | collection or rather a | | | | | bag of elements. In | | | | | the second case, the | | | | | ordering of the | | | | | elements is arbitrary | | | | | and therefore has no | | | | | meaning. | | +-------------+-----------------+------------------------+----------+ 5.7.2. Leaf Sub-Elements +-------------+------------+-----+-----+----------------------------+ | Sub-Element | Type | min | max | Description | | | | oc. | oc. | | +-------------+------------+-----+-----+----------------------------+ | description | xsd:string | 0 | 1 | The description of the | | | | | | sequence type. | +-------------+------------+-----+-----+----------------------------+ Linowski, et al. Expires September 12, 2008 [Page 52] Internet-Draft Kalua DML March 2008 5.7.3. Sub-Elements +-------------+--------+-----------+--------------------------------+ | Sub-Element | min | max | Description | | | occurs | occurs | | +-------------+--------+-----------+--------------------------------+ | annotation | 0 | unbounded | Annotations attached to the | | | | | attribute group. | | | | | | | constraint | 0 | unbounded | Constraints that apply in the | | | | | context of this attribute | | | | | group. | | | | | | | type | 1 | 1 | The element type | +-------------+--------+-----------+--------------------------------+ 5.7.4. XSD Linowski, et al. Expires September 12, 2008 [Page 53] Internet-Draft Kalua DML March 2008 5.7.5. Element Examples . . . (x,y) kalua::double kalua:double . . kalua:int kalua:string 5.7.6. NETCONF Payload Examples Linowski, et al. Expires September 12, 2008 [Page 54] Internet-Draft Kalua DML March 2008 . . . 441.2 172.5 441.2 198.3 343.8 198.3 . . . 2 3 8 15 . . . r6687120-01 r6687124-07 r6687201-03 5.8. simple-type "simple-type" elements are used to define new types that have simple values. However, like definitions of complex types (structures, sequences), they can be described and annotated. The unit in which a value of this simple type is measured can be stated and constraints can be specified for them. The set of legal values for the "simple-type" is defined by enumeration named values (enumeration element), by restricting existing simple types (restriction), by combining simple types (union) or by referring to an existing named "simple-type" (type). Linowski, et al. Expires September 12, 2008 [Page 55] Internet-Draft Kalua DML March 2008 5.8.1. Leaf Sub-Elements +-------------+------------+-----+-----+----------------------------+ | Sub-Element | Type | min | max | Description | | | | oc. | oc. | | +-------------+------------+-----+-----+----------------------------+ | unit | xsd:string | 0 | 1 | The unit in which values | | | | | | of simple types is | | | | | | measured. | +-------------+------------+-----+-----+----------------------------+ 5.8.2. Sub-Elements +-------------+--------+-----------+--------------------------------+ | Sub-Element | min | max | Description | | | occurs | occurs | | +-------------+--------+-----------+--------------------------------+ | annotation | 0 | unbounded | Annotations attached to the | | | | | attribute group. | | | | | | | constraint | 0 | unbounded | Constraints that apply in the | | | | | context of this attribute | | | | | group. | | | | | | | type | 0 | 1 | Reference to an existing | | | | | simple type. Allowing to | | | | | refer to a complex datatype | | | | | (structure, sequence) is not | | | | | allowed in the scope of a | | | | | simple type. | | | | | | | enum | 0 | 1 | Enumeration of simple type | | | | | values. | | | | | | | union | 0 | 1 | Union of simple types. | | | | | | | restriction | 0 | 1 | Restriction of another simple | | | | | type. | +-------------+--------+-----------+--------------------------------+ Exactly one of the type, enum, union, or restriction elements must be present in a "simple- type". 5.8.3. XSD Linowski, et al. Expires September 12, 2008 [Page 56] Internet-Draft Kalua DML March 2008 5.9. enum Enum elements define enumeration types, so types that are characterized by a fixed of named values. Each legal enumeration value is specified by an enum-literal element. As a simple-type, enumerations do not have an own description, annotations or constraints, the ones defined inside the owning simple-type element apply implicitly to the enumeration type. 5.9.1. Sub-Elements +--------------+--------+-----------+-------------------------------+ | Sub-Element | min | max | Description | | | occurs | occurs | | +--------------+--------+-----------+-------------------------------+ | enum-literal | 0 | unbounded | The enumeration values. | +--------------+--------+-----------+-------------------------------+ Linowski, et al. Expires September 12, 2008 [Page 57] Internet-Draft Kalua DML March 2008 5.9.2. XSD 5.9.3. Element Examples . . . AdministrativeState . . 5.9.4. NETCONF Payload Examples locked 5.10. enum-literal An "enum-literal" defines one of the values that can be assigned to an enumeration that is defined by the containing enum element Each "enum literal" must have a different name. Linowski, et al. Expires September 12, 2008 [Page 58] Internet-Draft Kalua DML March 2008 In addition to the name and presentation that can be specified for the literal, also a value may be provided. This value is used to represent the enum value in the implementing system. This could be useful in case a simple network element represents enumeration values as numbers. However, "enum literal" values should not be used when an enumeration type is defined that is standardized or otherwise implementation agnostic. E.g., the administrative state as defined in X.731 defines the values "unknown", "locked" , "shuttingDown" and "unlocked", so these terms are best used as literal names. However, is does not mandate any particular storage representation, so none should be given in the definition of the according "enum literals". The presence of the value attribute also controls the enum value representation: o In case the value attribute is not used, the name of the "enum literal" is used to represent the enum value o In case the value attribute was assigned a value, that value is used to represent the literal. The value attribute must be used consistently. Either all "enum- literal" elements have a value attribute or none. 5.10.1. Attributes +---------+------------+---------------------------------+----------+ | Feature | Type | Description | Use | +---------+------------+---------------------------------+----------+ | name | xsd:string | The name of the attribute. It | required | | | | must be unique within the set | | | | | of attributes which is the | | | | | union of the attributes defined | | | | | in the same attribute container | | | | | (class, structure, | | | | | attribute-group), the | | | | | attributes inherited from | | | | | superclasses (class) and the | | | | | set of attributes incorporated | | | | | from attribute groups (class, | | | | | structure, attribute-group). | | | | | | | | value | xsd:string | The string representation of | optional | | | | the storage value of the enum | | | | | literal | | +---------+------------+---------------------------------+----------+ Linowski, et al. Expires September 12, 2008 [Page 59] Internet-Draft Kalua DML March 2008 5.10.2. Leaf Sub-Elements +--------------+------------+-----+-----+---------------------------+ | Sub-Element | Type | min | max | Description | | | | oc. | oc. | | +--------------+------------+-----+-----+---------------------------+ | presentation | xsd:string | 0 | 1 | The presentation name | | | | | | used for the attribute | | | | | | group. | | | | | | | | description | xsd:string | 0 | 1 | The description of the | | | | | | attribute group. | +--------------+------------+-----+-----+---------------------------+ 5.10.3. Sub-Elements +-------------+--------+-----------+--------------------------------+ | Sub-Element | min | max | Description | | | occurs | occurs | | +-------------+--------+-----------+--------------------------------+ | annotation | 0 | unbounded | Annotations attached to the | | | | | attribute group. | +-------------+--------+-----------+--------------------------------+ 5.10.4. XSD 5.10.5. Element Examples Linowski, et al. Expires September 12, 2008 [Page 60] Internet-Draft Kalua DML March 2008 Not started Running Suspended Stopped . . 5.10.6. NETCONF Payload Examples . . 1 . . . 8 5.11. union A "union" combines two or more simple types. The set of legal values of this type is the "union" of all sets of legal values of each included simple type. As a simple type, "unions" do not have an own description, annotations or constraints, the ones defined inside the owning simple-type element apply implicitly to the enumeration type. Linowski, et al. Expires September 12, 2008 [Page 61] Internet-Draft Kalua DML March 2008 5.11.1. Sub-Elements +-------------+--------+-----------+--------------------------------+ | Sub-Element | min | max | Description | | | occurs | occurs | | +-------------+--------+-----------+--------------------------------+ | type | 0 | unbounded | A named simple type that is | | | | | part of the union type. | | | | | | | enumeration | 0 | unbounded | An enumeration that is part of | | | | | the union type. | | | | | | | restriction | 0 | unbounded | A restricted simple type that | | | | | is part of the union type. | | | | | | | union | 0 | unbounded | A subordinate union type that | | | | | is part of this union type. | +-------------+--------+-----------+--------------------------------+ 5.11.2. XSD 5.11.3. Element Examples Linowski, et al. Expires September 12, 2008 [Page 62] Internet-Draft Kalua DML March 2008 kalua:int . . . . 5.11.4. NETCONF Payload Examples 110 . . 230 . : 0 5.12. restriction A "restriction" element specifies a restricted simple type. That is done by applying restriction facets to the contained or referred base simple type. It is possible to apply multiple restriction facets. A legal value for the restricted type must comply with all "restrictions", including the "restrictions" already applied to the base type. The restriction facets supported by Kalua are a subset of the restriction facets as defined in 'XML Schema 1.1 Part 2: Datatypes'. Linowski, et al. Expires September 12, 2008 [Page 63] Internet-Draft Kalua DML March 2008 5.12.1. Sub-Elements +-------------+--------+--------+-----------------------------------+ | Sub-Element | min | max | Description | | | occurs | occurs | | +-------------+--------+--------+-----------------------------------+ | type | 0 | 1 | The restricted named base type | | | | | | | enumeration | 0 | 1 | The restricted enumeration base | | | | | type | | | | | | | restriction | 0 | 1 | The further restricted base type. | | | | | | | union | 0 | 1 | The restricted union type. | +-------------+--------+--------+-----------------------------------+ 5.12.2. Restriction Facet-Elements +----------------+--------+-----------+-----------------------------+ | Sub-Element | min | max | Description | | | occurs | occurs | | +----------------+--------+-----------+-----------------------------+ | minInclusive | 0 | unbounded | Inclusive lower bound for a | | | | | numerical base type. | | | | | | | minExclusive | 0 | unbounded | Exclusive lower bound for a | | | | | numerical base type | | | | | | | maxInclusive | 0 | unbounded | Inclusive upper bound for a | | | | | numerical base type. | | | | | | | maxExclusive | 0 | unbounded | Exclusive upper bound for a | | | | | numerical base type | | | | | | | totalDigits | 0 | unbounded | The total digits of a | | | | | decimal base type | | | | | | | fractionDigits | 0 | unbounded | The fraction digits of a | | | | | decimal base type | | | | | | | length | 0 | unbounded | The length of a string base | | | | | type | | | | | | | minLength | 0 | unbounded | The minimum length of a | | | | | string base type | | | | | | | maxLength | 0 | unbounded | The maximum length of a | | | | | string base type | Linowski, et al. Expires September 12, 2008 [Page 64] Internet-Draft Kalua DML March 2008 | pattern | 0 | unbounded | A regular expression that | | | | | must be matched. Applies | | | | | to string base type | +----------------+--------+-----------+-----------------------------+ 5.12.3. XSD Linowski, et al. Expires September 12, 2008 [Page 65] Internet-Draft Kalua DML March 2008 5.12.4. Element Examples kalua:int . . . . 5.13. typedef The "typedef" element is used to give otherwise anonymous datatypes a name which can be used to refer to this type wherever a datatype is required. This is done by using the type name as body value of the type element. 5.13.1. Attributes +---------+-------------+--------------------------------+----------+ | Feature | Type | Description | Use | +---------+-------------+--------------------------------+----------+ | name | name-string | The name of the type. It must | required | | | | be unique within the | | | | | containing module. | | +---------+-------------+--------------------------------+----------+ Linowski, et al. Expires September 12, 2008 [Page 66] Internet-Draft Kalua DML March 2008 5.13.2. Sub-Elements +-------------+--------+--------+-----------------------------------+ | Sub-Element | min | max | Description | | | occurs | occurs | | +-------------+--------+--------+-----------------------------------+ | structure | 0 | 1 | The structure type to give a | | | | | name. | | | | | | | sequence | 0 | 1 | The sequence type to give a name. | | | | | | | simple-type | 0 | 1 | A simple-type that is given a | | | | | name. | | | | | | | type | 0 | 1 | Provides an alias for the | | | | | referred named type. | +-------------+--------+--------+-----------------------------------+ Exactly one of the structure, sequence, simple-type or type elements must be specified as child of the typedef element. 5.13.3. XSD 5.13.4. Element Examples Linowski, et al. Expires September 12, 2008 [Page 67] Internet-Draft Kalua DML March 2008 kalua:double ... kalua:double ... 5.13.5. NETCONF Payload Examples . . 0.73001 0.239 . . 5.14. use "use" elements specify what attribute groups are used in the owning attribute container. All attributes of the used (incorporated) attribute group become part of the containing element. Using an attribute from an attribute group is equivalent with defining an attribute directly as part of the container. Therefore, it is not allowed that attributes incorporated from an attribute group have the same name as an attribute that is already part of the container namespace. Since attribute groups are only organizing facilities, no "is-a relationship" is established between the used attribute group and the using container (class, structure). Note that also attribute groups themselves can use other attribute groups. "use" elements are processed in the order as they are defined in Linowski, et al. Expires September 12, 2008 [Page 68] Internet-Draft Kalua DML March 2008 their attribute container. 5.14.1. Attributes +-----------------+-------------+------------------------+----------+ | Feature | Type | Description | Use | +-----------------+-------------+------------------------+----------+ | attribute-group | name-string | The reference of the | required | | | | used attribute group. | | +-----------------+-------------+------------------------+----------+ 5.14.2. Sub-Elements +-------------+--------+-----------+--------------------------------+ | Sub-Element | min | max | Description | | | occurs | occurs | | +-------------+--------+-----------+--------------------------------+ | description | 0 | 1 | The description of the use | | | | | element. | | | | | | | annotation | 0 | unbounded | Annotations attached to the | | | | | use element. | +-------------+--------+-----------+--------------------------------+ 5.14.3. XSD 5.14.4. Element Examples Linowski, et al. Expires September 12, 2008 [Page 69] Internet-Draft Kalua DML March 2008 IP Address < description > IP address attributes kalua:string kalua:unsignedShort . . 5.14.5. NETCONF Payload Examples . . . www.example.com 30100 12 . . 5.15. key "key" elements specify which attributes belonging to an attribute container (class, structure, attribute group) form a "key". A "key" is a set of one or more distinct member attributes. Member attributes could be all attributes that cannot be left unset. Attributes directly defined in the scope of a class or group can be combined with attributes inherited from superclasses or incorporated from attribute groups. An attribute could be part of multiple keys. One important aspect of a "key" is its scope: Linowski, et al. Expires September 12, 2008 [Page 70] Internet-Draft Kalua DML March 2008 o global: indicates a globally unique key o local: indicates that the key only identified instances in the scope of their containing (scoping) object "Keys" can have slightly different semantics depending in which context they are defined respectively used. In effect, the context of use also determines which scopes can be used: o A "key" that is part of a class uniquely identifies the instances of that class any meaningful context of use. For example, a "key" of a network element class must identify its instances (NE's) in the whole network. A "key" for a mobile equipment class must uniquely identify the equipment among all other mobile equipments (so an attribute capable of holding the 15 digit IMEI might do the job). o In contrast to that, "keys" that are part of structures may only uniquely identify the structure instance inside its containing object. In this case the scope of the key is 'local'. It is also possible that a "key" uniquely identifies the structure instance among all other instances. In this case, the scope of the "key" is 'global'. o In case a "key" is defined in an attribute group, its exact semantics is undefined. A concrete semantics is applied by using the attribute group in a class or structure. The member attributes of a "key" are enumerated by the member elements contained in the "key" element. 5.15.1. Attributes +-----------+-----------------+--------------------------+----------+ | Attribute | Type | Description | Use | +-----------+-----------------+--------------------------+----------+ | scope | xsd:enumeration | The reference of the | required | | | | used attribute group. | | +-----------+-----------------+--------------------------+----------+ Linowski, et al. Expires September 12, 2008 [Page 71] Internet-Draft Kalua DML March 2008 5.15.2. Leaf Sub-Elements +-------------+-------------+-----+-----------+---------------------+ | Sub-Element | Type | min | max oc. | Description | | | | oc. | | | +-------------+-------------+-----+-----------+---------------------+ | description | xsd:string | 0 | 1 | The description of | | | | | | the key. | | | | | | | | member | name-string | 0 | unbounded | The names of the | | | | | | member attributes. | +-------------+-------------+-----+-----------+---------------------+ 5.15.3. Sub-Elements +-------------+--------+-----------+--------------------------------+ | Sub-Element | min | max | Description | | | occurs | occurs | | +-------------+--------+-----------+--------------------------------+ | annotation | 0 | unbounded | Annotations attached to the | | | | | use element. | | | | | | | member | 1 | unbounded | The members of the key | +-------------+--------+-----------+--------------------------------+ 5.15.4. XSD Linowski, et al. Expires September 12, 2008 [Page 72] Internet-Draft Kalua DML March 2008 5.15.5. Element Examples Mobile Equipment ... kalua:string kalua:string . . imei vendor serialNr 5.15.6. NETCONF Payload Examples . . SpaceMobil 23-2308263673 800282737266302 . . Linowski, et al. Expires September 12, 2008 [Page 73] Internet-Draft Kalua DML March 2008 5.16. constraint "constraint" elements can be used to formulate constraints that are applied in the scope of the containing element. For example, "constraints" defined as child elements of an attribute element constrain the set of values that can be assigned to that attribute. "Constraints" defined as sub- elements of attribute containers (structures, attribute groups, classes) can express restrictions that values of one attribute can have to other attributes in that container. "Constraints" defined as part of relationships allows narrowing the set of instances that can actually be associated by that relationship. "Constraints" defined in classes could even navigate via relationship ends to other object in order to express constraints between instances of different classes. The "constraint" expression is specified as body value of the expression element. Therefore, exactly one expression element must be present. 5.16.1. Attributes +---------+-------------+--------------------------------+----------+ | Feature | Type | Description | Use | +---------+-------------+--------------------------------+----------+ | name | name-string | The name of the constraint. | required | +---------+-------------+--------------------------------+----------+ 5.16.2. Leaf Sub-Elements +-------------+------------+-----+-----+----------------------------+ | Sub-Element | Type | min | max | Description | | | | oc. | oc. | | +-------------+------------+-----+-----+----------------------------+ | description | xsd:string | 0 | 1 | The description of | | | | | | constraint | | | | | | | | expression | xsd:string | 0 | 1 | The constraint expression. | +-------------+------------+-----+-----+----------------------------+ 5.16.3. Sub-Elements Linowski, et al. Expires September 12, 2008 [Page 74] Internet-Draft Kalua DML March 2008 +-------------+--------+-----------+--------------------------------+ | Sub-Element | min | max | Description | | | occurs | occurs | | +-------------+--------+-----------+--------------------------------+ | annotation | 0 | unbounded | Annotations attached to the | | | | | attribute group. | +-------------+--------+-----------+--------------------------------+ 5.16.4. XSD 5.16.5. Element Examples @voltage * @ampere <= @maxPower 5.17. class "Classes" are used to describe objects that have an own identity and a potentially independent life cycle. "Classes" can represent concrete manageable resources in the network such as specific types of network elements or abstract concepts (e.g. managed objects or network resources). A "class" can have one superclass at the maximum. From the superclass a "class" does not only inherit all attributes and relationships, but also an implicit 'is-a' relationship is established between the "class" and its super class. This means that wherever the super class is used or referred to, also the derived "class" can be used. Kalua supports only single inheritance. This is to avoid the huge complexity caused by inheriting from multiple base classes. Linowski, et al. Expires September 12, 2008 [Page 75] Internet-Draft Kalua DML March 2008 For reusing sets of attribute definitions that describe a certain aspect of an object, a "class" can use 0..n attribute groups (see Section 5.5). This means that all attributes of a used attribute group become members of the using "class". This does NOT mean that an 'is-a' relationship is established between the "class" and its base attribute groups. Instance of classes must be uniquely identifiable in case they are associated by reference relationships, so some kind of key needs to be available. Such a key is obtained in the following way: o If a key with global scope is defined in the "class" directly, inherited from a super class, or incorporated from an attribute group, this key is used. o In case a class is contained in another class and a key with local scope is defined, the global scope key for the actual class is composed from the key of the owing class and the own local scope key. o In case the class not contained in any another class and has a local key, this is used, as it is assumed that a NETCONF agent is able to uniquely identify the instance in its given context. In order to describe how class instances can be accessed, class definitions can contain a max-access element. Its body text value can have one of the following values: o not-accessible: The class is used only for internal purposes. Instances cannot be accessed in any way. o accessible-for-notify: Only notifications are generated when instances are created, modified or deleted. o read-only: It is only possible to read the actual state of instances of this class. o read-write: Instances of this class can be read and written, but not created. o read-create: It is possible to create, write, and read instances. In case instances of a class are readable, notifications might also be send when they are created, changed or deleted. Linowski, et al. Expires September 12, 2008 [Page 76] Internet-Draft Kalua DML March 2008 5.17.1. Attributes +---------+-------------+--------------------------------+----------+ | Feature | Type | Description | use | +---------+-------------+--------------------------------+----------+ | name | name-string | The name of the class. | required | +---------+-------------+--------------------------------+----------+ 5.17.2. Leaf Sub-Elements +--------------+-----------------+-----+-----+----------------------+ | Sub-Element | Type | min | max | Description | | | | oc. | oc. | | +--------------+-----------------+-----+-----+----------------------+ | description | xsd:string | 0 | 1 | The description of | | | | | | the class | | | | | | | | presentation | xsd:string | 0 | 1 | The presentation | | | | | | name used for the | | | | | | class respectively | | | | | | instances of the | | | | | | class. | | | | | | | | abstract | xsd:boolean | 0 | 1 | If present, the | | | | | | class is abstract. | | | | | | | | superclass | name-string | 0 | 1 | The name of the | | | | | | superclass. | | | | | | | | max-access | xsd:enumeration | | | Specifies how class | | | | | | instances can be | | | | | | accessed. | +--------------+-----------------+-----+-----+----------------------+ Linowski, et al. Expires September 12, 2008 [Page 77] Internet-Draft Kalua DML March 2008 5.17.3. Sub-Elements +-------------+--------+-----------+--------------------------------+ | Sub-Element | min | max | Description | | | occurs | occurs | | +-------------+--------+-----------+--------------------------------+ | annotation | 0 | unbounded | Annotations attached to the | | | | | class. | | | | | | | constraint | 0 | unbounded | Constraints that apply in the | | | | | context of this class. | | | | | | | attribute | 0 | unbounded | The attributes directly | | | | | declared in the class. | | | | | | | use | 0 | unbounded | The attribute groups used by | | | | | the class. | | | | | | | key | 0 | unbounded | Key definitions | +-------------+--------+-----------+--------------------------------+ 5.17.4. Constraints A class must not be its own super class - neither directly nor indirectly. This implies a cycle in the inheritance graph and does not have well-defined semantics. If a class is abstract and inherits from a superclass, this superclass must be abstract as well. A class must not inherit from an attribute group that is already inherited by one of its ancestor classes (that is, its super class or the super class of the super class, and so on). 5.17.5. XSD Linowski, et al. Expires September 12, 2008 [Page 78] Internet-Draft Kalua DML March 2008 5.17.6. Element Examples Linowski, et al. Expires September 12, 2008 [Page 79] Internet-Draft Kalua DML March 2008 A site at which some network resources are located kalua:string kalua:string kalua:string kalua:unsigedInt kalua:string kalua:string kalua:string name 5.17.7. NETCONF Payload Examples Linowski, et al. Expires September 12, 2008 [Page 80] Internet-Draft Kalua DML March 2008 . . RANC Alphabet street 123 Megalopolis 65432 23o48'7'' 56o23'45'' 125m . . 5.18. relationship "relationship" elements specify associations between two classes or an attribute group and a class. With "relationships", it is possible to describe the way instances of particular classes relate to each other. This covers the simple 'is-used-by' or 'is-managed-by' "relationship" as well as containment "relationships," such as the well-known parent-child "relationship" between managed objects. Three different types of relationships are distinguished: o reference: Simple bi-directional references between instances of two classes. For example, a 'managed-by' "relationship" indicates that the instance at the source end is managed by the instance at the target end. o containment: A containment "relationship" in which the instance at the source end contains all instances at the target end. This also means that if the containing object is deleted, all contained objects are also deleted. o calculated: Dynamically calculated "relationships". Instances of the classes at the source and target end are related if they are in the result set produced by the evaluation of a "relationship" expression at runtime. With this type of "relationship" you can define that two objects are related if they have the same parent in the containment tree and a particular attribute has the same value in both instances. A "relationship" can also refine an existing "relationship". This feature is usually used to narrow down the usage of a generic Linowski, et al. Expires September 12, 2008 [Page 81] Internet-Draft Kalua DML March 2008 "relationship" inherited by the source and target end class. For example, an abstract class 'Resource' has a relationship 'managedResources' that refers to all resources managed by a particular resource. If two concrete classes, 'ProtectionGroup' and 'ProtectionUnit', inherit from 'Resource', you can refine the generic relationship 'managedResources' by creating a "relationship" definition 'managedUnits' between 'ProtectionGroup' and 'ProtectionUnit' that has 'managedResource' as its base relationship. This would mean that a protection group could only manage protection units and no other types of resources. There are two main reasons to specify abstract relationships that are refined by concrete relationships: o The generic "relationship" can be used to navigate between object instances without needing to know what type of refined relationships exist for each concrete class. In the example above, this means that an application that only deals with resources can find out the managed units of a protection group instance by following the 'managedResources' relationship. o The system that has to store and restore class instances can take advantage of the fact that a "relationship" refines another one by reusing storage space. In the example above this means that if 'ProtectionGroup' and 'ProtectionUnit' instances are stored in a relational database, the foreign key columns that are used to address the managing resource can be reused for addressing the controlling protection group. 5.18.1. Attributes +-----------+------------+-------------------------------+----------+ | Attribute | Type | Description | Use | +-----------+------------+-------------------------------+----------+ | name | xsd:string | The name of the relationship | required | +-----------+------------+-------------------------------+----------+ Linowski, et al. Expires September 12, 2008 [Page 82] Internet-Draft Kalua DML March 2008 5.18.2. Leaf Sub-Elements +--------------+-----------------+-----+-----+----------------------+ | Sub-Element | Type | min | max | Description | | | | oc. | oc. | | +--------------+-----------------+-----+-----+----------------------+ | description | xsd:string | 0 | 1 | The description of | | | | | | the relationship. | | | | | | | | kind | xsd:enumeration | 1 | 1 | The kind of | | | | | | relationship | | | | | | (reference, | | | | | | containment, | | | | | | calculated) | | | | | | | | readonly | xsd:boolean | 0 | 1 | Tells if | | | | | | relationship can be | | | | | | modifier, which is | | | | | | the default, or only | | | | | | read. | | | | | | | | base | name-string | 0 | 1 | The name of the base | | Relationship | | | | relationship | +--------------+-----------------+-----+-----+----------------------+ 5.18.3. Sub-Elements +-------------+--------+-----------+--------------------------------+ | Sub-Element | min | max | Description | | | occurs | occurs | | +-------------+--------+-----------+--------------------------------+ | annotation | 0 | unbounded | Annotations attached to the | | | | | relationship | | | | | | | constraint | 0 | unbounded | Constraints that apply in the | | | | | context of this attribute | | | | | group. | | | | | | | source | 1 | 1 | The specification of the | | | | | source-end of the | | | | | relationship. | | | | | | | target | 1 | 1 | The specification of the | | | | | target-end of the relationship | +-------------+--------+-----------+--------------------------------+ Linowski, et al. Expires September 12, 2008 [Page 83] Internet-Draft Kalua DML March 2008 5.18.4. Source and Target Leaf Sub-Elements The table below describes the simple typed XML elements that have to appear in source and target elements of a relationship element. +-------------+----------------+-----+-----+------------------------+ | Sub-Element | Type | min | max | Description | | | | oc. | oc. | | +-------------+----------------+-----+-----+------------------------+ | class | name-string | 1 | 1 | The class at one of | | | | | | the ends of the | | | | | | relationship. | | | | | | | | role | name-string | 1 | 1 | The role name of a | | | | | | relationship-end-class | | | | | | | | minCardinal | xsd:unsignedLo | 1 | 1 | The minimum number of | | ity | ng | | | objects that are | | | | | | addressed at the | | | | | | source or target end | | | | | | of this relationship. | | | | | | Typical values for the | | | | | | minimum cardinality | | | | | | are 0 (the target | | | | | | endpoint can remain | | | | | | undefined) or 1 (the | | | | | | target endpoint must | | | | | | be defined). | | | | | | | | maxCardinal | xsd:unsignedLo | 1 | 1 | The maximum number of | | ity | ng | | | objects that are | | | | | | addressed at the | | | | | | source or target end | | | | | | of this relationship. | | | | | | The value "unbounded" | | | | | | can be used to denoted | | | | | | an unlimited number of | | | | | | objects at the given | | | | | | relationship end. | +-------------+----------------+-----+-----+------------------------+ 5.18.5. Constraints Several constraints must be fulfilled by an relationship: o A valid source end multiplicity requires that either the maximum cardinality is unbounded or the minimum cardinality is not greater than the maximum cardinality. Linowski, et al. Expires September 12, 2008 [Page 84] Internet-Draft Kalua DML March 2008 o The source end multiplicity specification must allow that at least one object can be addressed at the source end, so source-end max cardinality must be greater than zero. o A valid target end multiplicity requires that either the maximum cardinality is unbounded or the minimum cardinality is not greater than the maximum cardinality. o The target end multiplicity specification must allow that at least one object can be addressed at the source end, so target-end max cardinality must be greater than zero. o An object can only be contained in another object at the same point in time. So in case of an containment relationship, it implies that the source-end max cardinality is one. When refining relationships, several constraints have to be considered: o If the relationship refines a base relationship, the source end class must be equal or derived from the base relationship source end class. o If the relationship refines a base relationship, the target end class must be equal or derived from the base relationship target end class. o If the relationship refines a base relationship, the relationship type must be the same as for the base relationship. o If the relationship refines a base relationship, the target minimum cardinality must be equal or greater than the target minimum cardinality at the base relationship. o If the relationship refines a base relationship, the target maximum cardinality must be equal or smaller than the target maximum cardinality at the base relationship. o If the relationship refines a base relationship, the source minimum cardinality must be equal or greater than the source minimum cardinality at the base relationship. o If the relationship refines a base relationship, the source maximum cardinality must be equal or smaller than the source maximum cardinality at the base relationship. Linowski, et al. Expires September 12, 2008 [Page 85] Internet-Draft Kalua DML March 2008 5.18.6. XSD Linowski, et al. Expires September 12, 2008 [Page 86] Internet-Draft Kalua DML March 2008 5.18.7. Element Examples $source/ipAdEntIfIndex=$target/ifIndex ipAddrEntry ipAddress 0 1 ifEntry interface 1 1 Linowski, et al. Expires September 12, 2008 [Page 87] Internet-Draft Kalua DML March 2008 kalua:string kalua:string kalua:string objectId commonName RootEntity kalua:string Linowski, et al. Expires September 12, 2008 [Page 88] Internet-Draft Kalua DML March 2008 Entity ManagementMethod ManagementMethod ManagedEnity Resource kalua:dateTime kalua:string Linowski, et al. Expires September 12, 2008 [Page 89] Internet-Draft Kalua DML March 2008 kalua:string kalua:string Resource Linowski, et al. Expires September 12, 2008 [Page 90] Internet-Draft Kalua DML March 2008 kalua:boolean PhysicalResource physicalResource 0 unbounded LogicalResource logicalResource 0 unbounded 5.18.8. NETCONF Payload Examples . . . NW-Card-11783 C12 . . N-737362183-34 . . TP-83838 Linowski, et al. Expires September 12, 2008 [Page 91] Internet-Draft Kalua DML March 2008 TP-83845 . . TP-83838 IP-TP-3 . . true . . NW-Card-11783 . . TP-83845 IP-TP-10 . . false . . NW-Card-11783 Linowski, et al. Expires September 12, 2008 [Page 92] Internet-Draft Kalua DML March 2008 5.19. annotation Kalua supports an "annotation" mechanism to allow extensions to the model language, "annotation" is a set of additional properties associated with a model element. There can be several "annotations" associated with the same model element. "Annotations" are 'typed', that is, each "annotation" must instantiate a particular annotation type also defined in the module or in a directly or indirectly imported module. The annotation type specifies which entries can be or must be present in an "annotation". The annotation type also implies semantics of the annotation data; however, semantics are not modeled and are conveyed in the description within the annotation-type definition only. An annotation type is defined with an annotation-type element. Reader of the module must not treat unrecognized annotation types as errors. A model element is annotated by adding an annotation sub-element to the element definition. This element contains any number of annotation-property elements, which are pairs made up of a name and a value. The order of annotation-property elements has no semantic value. The name and values in the annotation-property elements must match a corresponding element specification contained in the annotation- property elements of the referred annotation-type element. 5.19.1. Element Attributes +-----------+------------+--------------------------------------+---+ | Attribute | Type | Description | S | | | [Default] | | | +-----------+------------+--------------------------------------+---+ | name | xsd:string | Defines type of the annotation. | M | +-----------+------------+--------------------------------------+---+ Linowski, et al. Expires September 12, 2008 [Page 93] Internet-Draft Kalua DML March 2008 5.19.2. Sub-Elements +-------------+-----------+-----------+-----------------------------+ | Sub-Element | MinOccurs | MaxOccurs | Description | +-------------+-----------+-----------+-----------------------------+ | e: | 0 | unbounded | Defines values for the | | annotation- | | | properties of the | | property | | | annotation. | +-------------+-----------+-----------+-----------------------------+ 5.19.3. Constraints The annotation-type element, which is available in the module and which has the same value for attribute name as the annotation element has, must be applicable to the model element type which contains the "annotation". 5.19.4. XSD 5.19.5. Element Examples objectStorage true true 5.20. annotation-property "annotation-property" element defines value of a property within an annotation. Semantics of the "annotation-property" values depend on the annotation-type element referred to by the annotation element containing the "annotation-property". Linowski, et al. Expires September 12, 2008 [Page 94] Internet-Draft Kalua DML March 2008 5.20.1. Element Attributes +-----------+------------+--------------------------------------+---+ | Attribute | Type | Description | S | | | [Default] | | | +-----------+------------+--------------------------------------+---+ | name | xsd:string | A name of the annotation property. | M | | | | The name must match with id | | | | | attribute of one of the Annotation | | | | | Entry Type elements within | | | | | Annotation Type element to which the | | | | | containing Annotation refers to. | | +-----------+------------+--------------------------------------+---+ Table 1: Annotation-property element attributes 5.20.2. Constraints No two "annotation-property" elements within one annotation element may have the same value for attribute name. For each "annotation-property" element, there must be an annotation- property-type element in the referred annotation-type element. Content of the "annotation-property" element must match with the pattern of the corresponding annotation-property-type element. All annotation properties which are defined for the annotation-type of the annotation must be present in the annotation, or must be defined as optional in the annotation- type. 5.20.3. XSD 5.20.4. Element Examples true Linowski, et al. Expires September 12, 2008 [Page 95] Internet-Draft Kalua DML March 2008 5.21. annotation-type A module can define "annotation types" for use in that module, or other modules that import the module. "annotation-types" define the structure of additional information that can be added to the Kalua model elements. Each "annotation-type" applies to a selected subset of model elements. 5.21.1. Element Attributes +-----------+-------------+-------------------------------------+---+ | Attribute | Type | Description | S | | | [Default] | | | +-----------+-------------+-------------------------------------+---+ | Name | xsd:string | Identifies the annotation type. | M | | | | | | | multiple | xsd:boolean | If true, multiple instances of the | O | | | [true] | annotation type can be attached to | | | | | a model element. If false, only | | | | | one instance with this annotation | | | | | type can be attached to a model | | | | | element. | | +-----------+-------------+-------------------------------------+---+ 5.21.2. Leaf Sub-Elements +--------------+------------+-----------------------------------+---+ | Sub-Element | Type | Description | S | | | [Default] | | | +--------------+------------+-----------------------------------+---+ | presentation | xsd:string | See Section 5.1.2 | O | | | | | | | description | xsd:string | See Section 5.1.3 | O | +--------------+------------+-----------------------------------+---+ 5.21.3. Sub-Elements +----------------+-----------+-----------+--------------------------+ | Sub-Element | MinOccurs | MaxOccurs | Description | +----------------+-----------+-----------+--------------------------+ | annotable-type | 1 | unbounded | Defines to which Kalua | | | | | element types | | | | | annotations with this | | | | | type can be added. | | | | | | | annotation | 0 | unbounded | See Section 5.19 | | | | | | Linowski, et al. Expires September 12, 2008 [Page 96] Internet-Draft Kalua DML March 2008 | annotation- | 0 | unbounded | Defines which properties | | property | | | must or may be present | | | | | in annotations of this | | | | | type. | +----------------+-----------+-----------+--------------------------+ 5.21.4. XSD 5.21.5. Element Examples class true|false true|false 5.22. annotable-type "annotable-type" defines that an annotation, of the type, which contains this element, can be attached to the model elements of the given type. The content of this element is the name of the model element type. Linowski, et al. Expires September 12, 2008 [Page 97] Internet-Draft Kalua DML March 2008 5.22.1. XSD 5.22.2. Element Examples class 5.23. annotation-property-type "annotation-property-type" defines a property within the annotation- type element. It defines the allowed values for the property and whether property is optional. Linowski, et al. Expires September 12, 2008 [Page 98] Internet-Draft Kalua DML March 2008 5.23.1. Leaf Sub-Elements +--------------+------------+-----------------------------------+---+ | Sub-Element | Type | Description | S | | | [Default] | | | +--------------+------------+-----------------------------------+---+ | presentation | xsd:string | See Section 5.1.2 | O | | | | | | | description | xsd:string | See Section 5.1.3 | O | | | | | | | optional | none | Defines whether a property is | O | | | | optional or mandatory in the | | | | | annotation element. If the | | | | | element is present, the property | | | | | is optional. If the element is | | | | | not present, the property is | | | | | mandatory. | | | | | | | | pattern | xsd:string | Language of the allowed values | O | | | [.*] | for the property. The language | | | | | is defined using a regular | | | | | expression, according to regular | | | | | expression syntax and semantics | | | | | specified in the 'XML Schema Part | | | | | 2: Datatypes Second Edition' | | | | | [XSD-TYPES]. | | +--------------+------------+-----------------------------------+---+ 5.23.2. Sub-Elements +-------------+-----------+-----------+-----------------------------+ | Sub-Element | MinOccurs | MaxOccurs | Description | +-------------+-----------+-----------+-----------------------------+ | annotation | 0 | unbounded | See Section 5.19 | +-------------+-----------+-----------+-----------------------------+ 5.23.3. XSD Linowski, et al. Expires September 12, 2008 [Page 99] Internet-Draft Kalua DML March 2008 5.23.4. Element Examples true|false true|false Linowski, et al. Expires September 12, 2008 [Page 100] Internet-Draft Kalua DML March 2008 6. IANA Considerations A registry for standard Kalua modules needs to be set up. Each entry shall contain the unique module name, the unique XML namespace from the Kalua URI Scheme and some reference to the module's documentation. The URIs for the Kalua XML namespace will be registered in the IETF XML registry RFC 3688 [RFC3688]. Linowski, et al. Expires September 12, 2008 [Page 101] Internet-Draft Kalua DML March 2008 7. Security Considerations Kalua DML itself has no security impact on the Internet. Security issues might be related to the usage of data, which is modeled with Kalua. These issues need to be discussed in documents describing the data models and related interfaces. Linowski, et al. Expires September 12, 2008 [Page 102] Internet-Draft Kalua DML March 2008 8. Acknowledgements We would like to thank to David Kessens and Leo Hippelainen for their contributions and review. Linowski, et al. Expires September 12, 2008 [Page 103] Internet-Draft Kalua DML March 2008 9. References 9.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004. [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, December 2006. [XSD-TYPES] Biron, P V. and A. Malhotra, "XML Schema Part 2: Datatypes Second Edition, W3C REC REC-xmlschema-2-20041028", October 2004, . 9.2. Informative References [RFC3139] Sanchez, L., McCloghrie, K., and J. Saperia, "Requirements for Configuration Management of IP-based Networks", RFC 3139, June 2001. [RFC3216] Elliott, C., Harrington, D., Jason, J., Schoenwaelder, J., Strauss, F., and W. Weiss, "SMIng Objectives", RFC 3216, December 2001. [Linowski] Linowski, B., "NETCONF Data Modeling Language Requirements", February 2008, . [RCDML] Presuhn, R., "Requirements for a Configuration Data Modeling Language", February 2008, . [I-D.bjorklund-netconf-yang] Bjorklund, M., "YANG - A data modeling language for NETCONF", draft-bjorklund-netconf-yang-02 (work in progress), February 2008. Linowski, et al. Expires September 12, 2008 [Page 104] Internet-Draft Kalua DML March 2008 Appendix A. Kalua XML Schema Linowski, et al. Expires September 12, 2008 [Page 105] Internet-Draft Kalua DML March 2008 Keys on classes can be globally unique or locally unique (i.e unique within the scope of their containing element). Keys on structures are always locally unique. Keys on attribute-groups are merged to the set of keys of the element using them. If a class uses the attribute-group, the key can be globally unique. Linowski, et al. Expires September 12, 2008 [Page 106] Internet-Draft Kalua DML March 2008 Linowski, et al. Expires September 12, 2008 [Page 108] Internet-Draft Kalua DML March 2008 Linowski, et al. Expires September 12, 2008 [Page 109] Internet-Draft Kalua DML March 2008 If present it means that this class cannot be instantiated. Do we really want a restriction to single inheritance? Linowski, et al. Expires September 12, 2008 [Page 110] Internet-Draft Kalua DML March 2008 Linowski, et al. Expires September 12, 2008 [Page 111] Internet-Draft Kalua DML March 2008 Linowski, et al. Expires September 12, 2008 [Page 114] Internet-Draft Kalua DML March 2008 Linowski, et al. Expires September 12, 2008 [Page 116] Internet-Draft Kalua DML March 2008 Appendix B. Module Example: RFC1213-MIB The example below shows how the contents of the MIB RFC1213-MIB is represented in Kalua. RFC1213-MIB Extracted from rfc1213.txt iso.org.dod.internet.mgmt.mib-2.rfc1213 rfc1213 1 RFC iso.org.dod.internet.mgmt.mib-2.rfc1155-smi rfc1155-smi 1 Structure of Management Information iso.org.dod.internet.mgmt.mib-2.rfc1212 rfc1212 1 Object type definition macros This data type is used to model textual information taken from the NVT ASCII character set. By convention, objects with this syntax are declared as having SIZE (0..255) kalua:string This data type is used to model media addresses. For many types of media, this will be in a binary representation. For example, an ethernet address would be represented as a string of 6 octets. kalua:string Linowski, et al. Expires September 12, 2008 [Page 117] Internet-Draft Kalua DML March 2008 System group Implementation of the System group is mandatory for all systems. If an agent is not configured to have a value for any of these variables, a string of length 0 is returned. A textual description of the entity. This value should include the full name and version identification of the system's hardware type, software operating-system, and networking software. It is mandatory that this only contain printable ASCII characters. DisplayString The vendor's authoritative identification of the network management subsystem contained in the entity. This value is allocated within the SMI enterprises subtree (1.3.6.1.4.1) and provides an easy and unambiguous means for determining `what kind of box' is being managed. For example, if vendor `Flintstones, Inc.' was assigned the subtree 1.3.6.1.4.1.4242, it could assign the identifier 1.3.6.1.4.1.4242.1.1 to its `Fred Router'. kalua:string Linowski, et al. Expires September 12, 2008 [Page 118] Internet-Draft Kalua DML March 2008 The time (in hundredths of a second) since the network management portion of the system was last re-initialized. rfc1155-smi:TimeTicks The textual identification of the contact person for this managed node, together with information on how to contact this person. DisplayString An administratively-assigned name for this managed node. By convention, this is the node's fully-qualified domain name. DisplayString The physical location of this node (e.g., 'telephone closet, 3rd floor'). DisplayString Linowski, et al. Expires September 12, 2008 [Page 119] Internet-Draft Kalua DML March 2008 A value which indicates the set of services that this entity primarily offers. The value is a sum. This sum initially takes the value zero, Then, for each layer, L, in the range 1 through 7, that this node performs transactions for, 2 raised to (L - 1) is added to the sum. For example, a node which performs primarily routing functions would have a value of 4 (2^(3-1)). In contrast, a node which is a host offering application services would have a value of 72 (2^(4-1) + 2^(7-1)). Note that in the context of the Internet suite of protocols, values should be calculated accordingly: layer 1 physical (e.g., repeaters) layer 2 datalink/subnetwork (e.g., bridges) layer 3 internet (e.g., IP gateways) layer 4 end-to-end (e.g., IP hosts) layer 7 applications (e.g., mail relays) For systems including OSI protocols, layers 5 and 6 may also be counted." kalua:integer sysName The number of network interfaces (regardless of their current state) present on this system. Linowski, et al. Expires September 12, 2008 [Page 120] Internet-Draft Kalua DML March 2008 kalua:integer A list of interface entries. The number of entries is given by the value of ifNumber. interfaces parent 1 1 ifEntry children 0 unbounded An interface entry containing objects at the subnetwork layer and below for a particular interface. A unique value for each interface. Its value ranges between 1 and the value of ifNumber. The value for each interface must remain constant at least from one re-initialization of the entity's network management system to the next re- initialization. kalua:integer A textual string containing information about the Linowski, et al. Expires September 12, 2008 [Page 121] Internet-Draft Kalua DML March 2008 interface. This string should include the name of the manufacturer, the product name and the version of the hardware interface. DisplayString The type of interface, distinguished according to the physical/link protocol(s) immediately 'below' the network layer in the protocol stack. ddn-x25 rfc877-x25 ethernet-csmacd iso88023-csmacd iso88024-tokenBus iso88025-tokenRing iso88026-man frame-relay The size of the largest datagram which can be sent/received on the interface, specified in octets. For interfaces that are used for transmitting network datagrams, this is the size of the largest network datagram that can be sent on the interface. kalua:integer octets An estimate of the interface's current bandwidth in bits per second. For interfaces which do not vary in bandwidth or for those where no accurate estimation can be made, this object should contain the nominal bandwidth. rfc1155-smi:Gauge bit/sec The interface's address at the protocol layer immediately `below' the network layer in the protocol stack. For interfaces which do not have Linowski, et al. Expires September 12, 2008 [Page 123] Internet-Draft Kalua DML March 2008 such an address (e.g., a serial line), this object should contain an octet string of zero length. PhysAddress The desired state of the interface. The testing(3) state indicates that no operational packets can be passed. The current operational state of the interface. The testing(3) state indicates that no operational packets can be passed. A reference to MIB definitions specific to the particular media being used to realize the interface. For example, if the interface is realized by an ethernet, then the value of this Linowski, et al. Expires September 12, 2008 [Page 124] Internet-Draft Kalua DML March 2008 object refers to a document defining objects specific to ethernet. If this information is not present, its value should be set to the OBJECT IDENTIFIER { 0 0 }, which is a syntatically valid object identifier, and any conformant implementation of ASN.1 and BER must be able to generate and recognize this value. kalua:string ifIndex the Address Translation group Implementation of the Address Translation group is mandatory for all systems. Note however that this group is deprecated by MIB-II. That is, it is being included solely for compatibility with MIB-I nodes, and will most likely be excluded from MIB-III nodes. From MIB-II and onwards, each network protocol group contains its own address translation tables. The Address Translation group contains one table which is the union across all interfaces of the translation tables for converting a NetworkAddress (e.g., an IP address) into a subnetwork-specific address. For lack of a better term, this document refers to such a subnetwork-specific address as a `physical' address. Examples of such translation tables are: for broadcast media where ARP is in use, the translation table is equivalent to the ARP cache; or, on an X.25 network where non-algorithmic translation to X.121 addresses is required, the translation table contains the NetworkAddress to X.121 address equivalences. The Address Translation tables contain the NetworkAddress to `physical' address equivalences. Some interfaces do not use translation tables for determining address equivalences (e.g., DDN-X.25 has an algorithmic method); if all interfaces are Linowski, et al. Expires September 12, 2008 [Page 125] Internet-Draft Kalua DML March 2008 of this type, then the Address Translation table is empty, i.e., has zero entries. at parent 1 1 atEntry children 0 unbounded Each entry contains one NetworkAddress to 'physical' address equivalence. The interface on which this entry's equivalence is effective. The interface identified by a particular value of this index is the same interface as identified by the same value of ifIndex. kalua:int The media-dependent `physical' address. Setting this object to a null string (one of zero length) has the effect of invaliding the corresponding entry in the atTable object. That is, it effectively dissasociates the interface identified with said entry from the mapping Linowski, et al. Expires September 12, 2008 [Page 126] Internet-Draft Kalua DML March 2008 identified with said entry. It is an implementation-specific matter as to whether the agent removes an invalidated entry from the table. Accordingly, management stations must be prepared to receive tabular information from agents that corresponds to entries not currently in use. Proper interpretation of such entries requires examination of the relevant atPhysAddress object. PhysAddress The NetworkAddress (e.g., the IP address) corresponding to the media-dependent `physical' address. NetworkAddress atIfIndex atNetAddress $source/atIfIndex= $target/ifIndex atEntry atEntry 0 1 ifEntry ifEntry 1 Linowski, et al. Expires September 12, 2008 [Page 127] Internet-Draft Kalua DML March 2008 1 The indication of whether this entity is acting as an IP gateway in respect to the forwarding of datagrams received by, but not addressed to, this entity. IP gateways forward datagrams. IP hosts do not (except those source-routed via the host). Note that for some managed nodes, this object may take on only a subset of the values possible. Accordingly, it is appropriate for an agent to return a 'badValue' response if a management station attempts to change this object to an inappropriate value. acting as a gateway not-forwarding NOT acting as a gateway The table of addressing information relevant to this entity's IP addresses. ip parent Linowski, et al. Expires September 12, 2008 [Page 128] Internet-Draft Kalua DML March 2008 1 1 ipAddrEntry children 0 unbounded The IP address to which this entry's addressing information pertains. rfc1155-smi:IpAddress The index value which uniquely identifies the interface to which this entry is applicable. The interface identified by a particular value of this index is the same interface as identified by the same value of ifIndex. kalua:integer ipAdEntAddr $source/ipAdEntIfIndex= $target/ifIndex ipAddrEntry ipAddress 0 1 Linowski, et al. Expires September 12, 2008 [Page 129] Internet-Draft Kalua DML March 2008 ifEntry interface 1 1 annotation-property-type annotation-type attribute attribute-group class constraint enum enum-literal import key member module relationship sequence structure typedef use A linkDown trap signifies that the SNMP entity, acting in an agent role, has detected that the ifOperStatus object for one of its communication links is about to enter the down state from some other state (but not from the notPresent state). This other state is indicated by the included value of ifOperStatus. accessible-for-notify Linowski, et al. Expires September 12, 2008 [Page 130] Internet-Draft Kalua DML March 2008 kalua:int kalua:int The desired state of the interface. The testing(3) state indicates that no operational packets can be passed. When a managed system initializes, all interfaces start with ifAdminStatus in the down(2) state. As a result of either explicit management action or per configuration information retained by the managed system, ifAdminStatus is then changed to either the up(1) or testing(3) states (or remains in the down(2) state). kalua:int The current operational state of the interface. The testing(3) state indicates that no operational packets can be passed. If ifAdminStatus is down(2) then ifOperStatus should be down(2). If ifAdminStatus is changed to up(1) then ifOperStatus should change to up(1) if the interface is ready to transmit and receive network traffic; it should change to dormant(5) if the interface is waiting for external actions (such as a serial line waiting for an incoming connection); it should remain in the down(2) state if and only if there is a fault that prevents it from going to the up(1) state; it should remain in the notPresent(6) Linowski, et al. Expires September 12, 2008 [Page 131] Internet-Draft Kalua DML March 2008 state if the interface has missing (typically, hardware) components. Linowski, et al. Expires September 12, 2008 [Page 132] Internet-Draft Kalua DML March 2008 Appendix C. Netconf Payload Example The XML example below shows a Netconf payload that is in line with the Kalua module shown in the previous sections: IP Router 8.0.1.2.3.5.63.22.3.4 646467347 Bob's phone: (352) 465 3746 available 24/7 Bob's router Bob's garage 6 1 1 Flintstone Inc Ethernet A562 10 1500 10000000 0:12:3f:7d:b5:8b 1 1 1 0:23:be:8e:00:6a 192.168.2.1 1 Linowski, et al. Expires September 12, 2008 [Page 133] Internet-Draft Kalua DML March 2008 1 10.34.120.3 1 10.22.255.255 Linowski, et al. Expires September 12, 2008 [Page 134] Internet-Draft Kalua DML March 2008 Appendix D. NETCONF Notification Example The XML example below shows a NETCONF notification for the Kalua module rfc1213-mib.xml: 2007-07-08T00:01:00Z 1 1 1 2 1 Linowski, et al. Expires September 12, 2008 [Page 135] Internet-Draft Kalua DML March 2008 Appendix E. DHCP example from RCDML Requirements Document The following XML example demonstrates the Kalua variant of the DHCP example in RCDML Requirements Document [RCDML]. DHCP DHCP example, as in draft-presuhn-rcdml-03#appendix-C http://example.org/ns/dhcp dhcp 1 Nokia Siemens Networks urn:ietf:params:xml:ns:netmod:base ndl http://example.com/ns/int int interfaces default-lease-time kalua:int max-lease-time kalua:int dhcp parent subnet children Linowski, et al. Expires September 12, 2008 [Page 136] Internet-Draft Kalua DML March 2008 ndl:ipAddress prefix-length kalua:int rangeType max-lease-time kalua:int ip-address ndl:ipAddress kalua:dateTime kalua:dateTime mac-address ndl:nsapAddress ip_address kalua:string network Linowski, et al. Expires September 12, 2008 [Page 137] Internet-Draft Kalua DML March 2008 prefix_length dynamic-bootp kalua:boolean true ndl:ipAddress ndl:ipAddress dhcp dhcp dhcp_options dhcp_options dhcp-options router-list ndl:ipAddress domain-list ndl:ipAddress Linowski, et al. Expires September 12, 2008 [Page 138] Internet-Draft Kalua DML March 2008 kalua:int ip-address ndl:ipAddress kalua:string $source/interface_filter/interface=$target/ifName subnet filtering_subnet unbounded int:interface filtered_interface unbounded kalua:string name shared_network parent Linowski, et al. Expires September 12, 2008 [Page 139] Internet-Draft Kalua DML March 2008 subnet children Linowski, et al. Expires September 12, 2008 [Page 140] Internet-Draft Kalua DML March 2008 Appendix F. DHCP augmentation example from RCDML Requirements Document The XML example below shows the Kalua variant of the DHCP augmentation example in RCDML Requirements Document [RCDML]. DHCP_augment DHCP augmentation example, as in http://tools.ietf.org/html/draft-presuhn-rcdml-03#appendix-C http://example.org/ns/cal cal 1 Nokia Siemens Networks http://example.org/ns/dhcp dhcp Inheritance would imply substitution of the element name as well, which is not the case here. An additional augmentation mechanism would be needed to truly support this case. dhcp:dhcp_options kalua:string Linowski, et al. Expires September 12, 2008 [Page 141] Internet-Draft Kalua DML March 2008 Appendix G. Example for Partial Lock RPC for NETCONF The XML example below shows a Kalua example for Partial Lock RPC for NETCONF. NETCONF partial lock NETCONF partial lock operations urn:ietf:params:xml:ns:netconf:partial-lock:1.0 ncpl 1 IETF urn:ietf:params:xml:ns:netconf:base:1.0 nc kalua:unsignedInt This operation defines the element for partial-lock RPC operation. Positive response to this operation is the "lock-id" element. nc:config_name kalua:string sadasd Linowski, et al. Expires September 12, 2008 [Page 142] Internet-Draft Kalua DML March 2008 This operation defines the element for partial-unlock RPC operation. The standard positive response (rpc-reply with <nc:ok/>) is sent if the operation succeeds. sadasd Linowski, et al. Expires September 12, 2008 [Page 143] Internet-Draft Kalua DML March 2008 Appendix H. Support of RCDML Requirements in Kalua Following table shows the support of RCDML Requirements in Kalua. +--------------------------------------+-----------+----------------+ | RCDML Requirements | Kalua | Comments | | | support | | +--------------------------------------+-----------+----------------+ | 1. Consequences of NETCONF | | | | | | | | 1.1. Notification Definition | Yes | | | (Agreed) | | | | | | | | 1.2. Notification Get (NOT Agreed) | Yes (*) | Reuse of | | | | config | | | | definitions | | | | possible, not | | | | mandatory | | | | | | 1.3. Locking (Agreed) | Yes | | | | | | | 1.4. All Base Operations (Agreed) | Yes | | | | | | | 1.5. Define new NETCONF Operations | Yes (wo) | | | (Agreed) | | | | | | | | 1.6. Separation of Operations and | Yes | | | Payload (Agreed) | | | | | | | | 1.7. Error Annotation (Agreed) | Yes (wo) | In parallel to | | | | Req. # 1.5 | | | | | | 1.8. No Mixed Content (Agreed) | Yes | | | | | | | 2. Model Representation | | | | Requirements | | | | | | | | 2.1. Human Readable (Agreed) | Yes | | | | | | | 2.2. Machine Readable (Agreed) | Yes | | | | | | | 2.3. Textual Representation | Yes | | | (Agreed) | | | | | | | | 2.4. Document Information (Agreed) | Yes | | | | | | | 2.5. Ownership and Change Control | Yes | | | (Agreed) | | | Linowski, et al. Expires September 12, 2008 [Page 144] Internet-Draft Kalua DML March 2008 | 2.6. Dependency Risk Reduction | Yes | | | (Agreed) | | | | | | | | 2.7. Diff-Friendly (Agreed) | Yes | | | | | | | 2.8. Internationalization and | Yes | | | Localization | | | | | | | | 2.8.1. Descriptions using Local | Yes | | | Languages (Agreed) | | | | | | | | 2.8.2. UTF-8 Encoding (Agreed) | Yes | | | | | | | 2.8.3. Localization Support | Yes | | | (Agreed) | | | | | | | | 2.8.4. Error String Localization | Yes | | | (Agreed) | | | | | | | | 2.8.5. Tag Names and Strings in | No | | | Local Languages (NOT agreed) | | | | | | | | 3. Reusability Requirements | | | | | | | | 3.1. Modularity (Agreed) | Yes | | | | | | | 3.2. Reusable Definitions (Agreed) | Yes | | | | | | | 3.3. Modular extension (Agreed) | Yes | | | | | | | 4. Instance Data Requirements | | | | | | | | 4.1. Default Values on the Wire | Yes (wo) | | | (Agreed) | | | | | | | | 4.2. Ordering | | | | | | | | 4.2.1. Ordered Lists (Agreed) | Yes | | | | | | | 4.2.2. Order within Containers (NOT | No | Not for | | Agreed) | | containment | | | | relationships. | | | | | | 4.2.3. Interleaving (NOT Agreed) | Yes (*) | Order of | | | | contained | | | | elements is | | | | not defined | | | | | Linowski, et al. Expires September 12, 2008 [Page 145] Internet-Draft Kalua DML March 2008 | 4.3. Validation | | | | | | | | 4.3.1. Validate Instance Data | Yes | No explicit | | (Agreed) | | definition of | | | | valid and | | | | well-formed | | | | | | 4.3.2. Tools to Validate Instance | No | | | Data (NOT Agreed) | | | | | | | | 4.4. Instance Canonicalization | Yes (wo) | | | (Agreed) | | | | | | | | 4.5. Character Set and Encoding | Yes | | | (Agreed) | | | | | | | | 4.6. Model Instance Localization | Yes (*) | | | (NOT Agreed) | | | | | | | | 5. Semantic Richness Requirements | | | | | | | | 5.1. Human-Readable Semantics | Yes | | | (Agreed) | | | | | | | | 5.2. Basic Types (Agreed) | Yes | | | | | | | 5.3. Handling Opaque Data (Agreed) | Yes (wo) | kalua:any type | | | | can be added | | | | easilly | | | | | | 5.4. Keys | | | | | | | | 5.4.1. Define Keys (Agreed) | Yes | | | | | | | 5.4.2. Deep Keys (NOT Agreed) | Yes | | | | | | | 5.5. Relationships | | | | | | | | 5.5.1. Simple Relationships | Yes | | | (Agreed) | | | | | | | | 5.5.2. Many-to-Many Relationships | Yes (*) | | | (NOT Agreed) | | | | | | | | 5.5.3. Retrieve Relationships | Yes (*) | | | instance (NOT Agreed) | | | | | | | Linowski, et al. Expires September 12, 2008 [Page 146] Internet-Draft Kalua DML March 2008 | 5.5.4. Retrieve Relationships - | Yes (*) | | | qualified (NOT Agreed) | | | | | | | | 5.6. Hierarchical Data | Yes | | | | | | | 5.7. Referential Integrity | | | | | | | | 5.7.1. Referential Integrity (NOT | Yes (wo) | Calculated | | Agreed) | (*) | relationships | | | | do not imply | | | | referential | | | | integrity. | | | | Reference | | | | relationships | | | | only cover the | | | | key attributes | | | | | | 5.7.2. Extended Referential | No | Not really | | Integrity (NOT Agreed) | | clear what | | | | this is ... | | | | | | 5.7.3. Referential Integrity | Yes (*) | | | Robustness (NOT Agreed) | | | | | | | | 5.8. Characterize Data (Agreed) | Yes | | | | | | | 5.9. Defaults | | | | | | | | 5.9.1. Default Values (NOT Agreed) | Yes (*) | | | | | | | 5.9.2. Dynamic Defaults (NOT | No | | | Agreed) | | | | | | | | 5.10. Formal Constraints | | | | | | | | 5.10.1. Formal Description of | Yes | | | Constraints (Agreed) | | | | | | | | 5.10.2. Multi-element Constraints | No | | | (NOT Agreed) | | | | | | | | 5.10.3. Non-Key Uniqueness (Agreed) | Yes | | | | | | | 5.11. Units (Agreed) | Yes | | | | | | | 5.12. Define Actions (NOT Agreed) | No | | | | | | | 6. Extensibility Requirements | | | Linowski, et al. Expires September 12, 2008 [Page 147] Internet-Draft Kalua DML March 2008 | 6.1. Language Extensibility | Yes | | | | | | | 6.1.1. Language Versioning (Agreed) | Yes | | | | | | | 6.1.2. User Extensions (NOT Agreed) | Yes (*) | | | | | | | 6.1.3. Mandatory Extensions (NOT | No | | | Agreed) | | | | | | | | 6.2. Model Extensibility | | | | | | | | 6.2.1. Model Version Identification | Yes | | | (Agreed) | | | | | | | | 6.2.2. Interaction with defaults | No | | | (NOT Agreed) | | | | | | | | 6.2.3. Conformance Interference | Yes (wo) | | | (NOT Agreed) | (*) | | | | | | | 6.2.4. Obsolete Portions of a Model | Yes | Solution | | (Agreed) | | assumes that | | | | the manager | | | | will select | | | | the correct | | | | version of a | | | | module | | | | (matching the | | | | agent) | | | | | | 6.3. Instance Data Extensibility | | | | | | | | 6.3.1. Schema Version of Instance | Yes (wo) | | | (NOT Agreed) | (*) | | | | | | | 6.3.2. Interaction with default | No | | | Values (NOT Agreed) | | | | | | | | 6.3.3. Backwards Compatibility | Partially | Additional | | (Agreed) | | inheritance | | | | may lead to | | | | element names | | | | not understood | | | | by old | | | | clients. | | | | | Linowski, et al. Expires September 12, 2008 [Page 148] Internet-Draft Kalua DML March 2008 | 6.3.4. Forwards Compatibility (NOT | No | Unclear about | | Agreed) | | implications | | | | of this | | | | requirement | | | | | | 7. Talking About Conformance | | | | | | | | 7.1. Conformance to the Modeling | Yes (*) | | | Language (NOT Agreed) | | | | | | | | 7.2. Conformance to a Model | Yes | | | (Agreed) | | | | | | | | 8. Techno-Political Constraints | | | | | | | | 8.1. Standard Technology (NOT | Yes (*) | | | Agreed) | | | | | | | | 8.2. Translate Models to Other | Yes | | | Forms (Agreed) | | | | | | | | 8.3. Minimize SMI Translation Pain | No | | | (NOT Agreed) | | | | | | | | 8.4. Generate Models from Other | Yes (*) | | | Forms (NOT Agreed) | | | | | | | | 8.5. Isolate Models from Protocol | Yes (*) | | | (NOT Agreed) | | | | | | | | 8.6. Library Support (NOT Agreed) | Yes (*) | | | | | | | 8.7. RFC 3139 Considerations | Yes | | | | | | | 8.8. RFC 3216 Considerations | Yes | | +--------------------------------------+-----------+----------------+ Table 2: Support of RCDML Requirements in Kalua (wo): work ongoing (*): Not agreed RCDML requirement supported by Kalua Linowski, et al. Expires September 12, 2008 [Page 149] Internet-Draft Kalua DML March 2008 Appendix I. Support of Use Cases for SMI and MIB Modules Following table shows the support of Use cases for SMI and MIB modules in Kalua. +----+--------------------------------------------------+-----------+ | # | Use cases for SMI and MIB modules | Supported | | | | by Kalua | +----+--------------------------------------------------+-----------+ | 1 | Agreement on a set of standard knobs (or | Yes | | | proprietary knobs in a proprietary MIB module). | | | | These knobs can be defined in a clear and | | | | unambiguous manner including the restrictions | | | | that apply to the knobs, such as range, | | | | character set, what gets counted in a counter, | | | | and so on. Ideally, Netconf knobs would support | | | | all the types of management object properties | | | | already supported by MIB modules, unless it can | | | | be shown that such properties do not apply to | | | | configuration. | | | | | | | 2 | clear specification in the schema of what | Yes (*) | | | MUST/SHOULD/MAY/MUST NOT/SHOULD NOT be supported | | | | to claim compliance to the standard, to support | | | | vendor-neutral interoperability | | | | | | | 3 | modular documents that can be formally validated | Yes | | | using tools such as smilint | | | | | | | 4 | enough information for implementers to | Yes | | | implement, with internal engineering choices | | | | being implementer-dependent, but with | | | | vendor-neutral formats on-the-wire | | | | | | | 5 | enough human-readable description/qualities that | Yes | | | operators can read the raw schema to understand | | | | the meaning of a managed object | | | | | | | 6 | enough machine-readability that applications can | Yes | | | effectively parse (and compare/contrast/utilize) | | | | the information across multiple vendor | | | | implementations, and across multiple vendor | | | | implementation releases. | | | | | | Linowski, et al. Expires September 12, 2008 [Page 150] Internet-Draft Kalua DML March 2008 | 7 | the document can be used by network management | Yes | | | applications to programmatically create | | | | corresponding databases of information (i.e. an | | | | NMS can IMPORT a MIB module to create | | | | corresponding record formats in a database) | | | | | | | 8 | each managed object is clearly | Yes | | | instance-addressable such that a sender can | | | | label the object instance being sent in a | | | | message | | | | | | | 9 | the receiver of a message can clearly identify | Yes | | | the instance of any object contained in a | | | | message, and can validate the data types and | | | | values (such as range, character set, etc.) of | | | | objects being passed in a message | | | | | | | 10 | a protocol-dependent message MAY contain a very | Yes | | | small subset of the managed objects defined in a | | | | schema (e.g., one object from a schema) and | | | | still meet the previous requirements | | | | | | | 11 | a protocol-dependent message MAY contain a | Yes | | | mixture of managed objects defined in different | | | | modules/schemas, and still meet the previous | | | | requirements | | +----+--------------------------------------------------+-----------+ Table 3: Support of Use cases for SMI and MIB modules in Kalua (*): Kalua does not define optional elements. Linowski, et al. Expires September 12, 2008 [Page 151] Internet-Draft Kalua DML March 2008 Authors' Addresses Bernd Linowski Nokia Siemens Networks Heltorfer Strasse 1 40472 Duesseldorf Germany Email: bernd.linowski@nsn.com Martin Storch Nokia Siemens Networks Heltorfer Strasse 1 40472 Duesseldorf Germany Email: martin.storch@nsn.com Mikko Lahdensivu Nokia Siemens Networks Hatanpaeaen valtatie 30 33100 Tampere Finland Email: mikko.lahdensivu@nsn.com Mehmet Ersue Nokia Siemens Networks St.-Martin-Strasse 76 81541 Munich Germany Email: mehmet.ersue@nsn.com Linowski, et al. Expires September 12, 2008 [Page 152] Internet-Draft Kalua DML March 2008 Full Copyright Statement Copyright (C) The IETF Trust (2008). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Intellectual Property The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Linowski, et al. Expires September 12, 2008 [Page 153]