idnits 2.17.1 draft-ersue-netconf-kalua-dml-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 17. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 6366. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 6377. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 6384. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 6390. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 3 instances of too long lines in the document, the longest one being 2 characters in excess of 72. ** The abstract seems to contain references ([RCDML], [RFC4741], [Linowski]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (March 11, 2008) is 5890 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'Default' is mentioned on line 4142, but not defined -- Looks like a reference, but probably isn't: '0' on line 2156 == Unused Reference: 'RFC3139' is defined on line 4242, but no explicit reference was found in the text == Unused Reference: 'RFC3216' is defined on line 4246, but no explicit reference was found in the text == Unused Reference: 'I-D.bjorklund-netconf-yang' is defined on line 4259, but no explicit reference was found in the text ** Obsolete normative reference: RFC 4741 (Obsoleted by RFC 6241) -- Possible downref: Non-RFC (?) normative reference: ref. 'XSD-TYPES' Summary: 4 errors (**), 0 flaws (~~), 5 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Linowski 3 Internet-Draft M. Storch 4 Intended status: Standards Track M. Lahdensivu 5 Expires: September 12, 2008 M. Ersue (ed.) 6 Nokia Siemens Networks 7 March 11, 2008 9 Kalua - A Data Modeling Language for NETCONF 10 draft-ersue-netconf-kalua-dml-01 12 Status of this Memo 14 By submitting this Internet-Draft, each author represents that any 15 applicable patent or other IPR claims of which he or she is aware 16 have been or will be disclosed, and any of which he or she becomes 17 aware will be disclosed, in accordance with Section 6 of BCP 79. 19 Internet-Drafts are working documents of the Internet Engineering 20 Task Force (IETF), its areas, and its working groups. Note that 21 other groups may also distribute working documents as Internet- 22 Drafts. 24 Internet-Drafts are draft documents valid for a maximum of six months 25 and may be updated, replaced, or obsoleted by other documents at any 26 time. It is inappropriate to use Internet-Drafts as reference 27 material or to cite them other than as "work in progress." 29 The list of current Internet-Drafts can be accessed at 30 http://www.ietf.org/ietf/1id-abstracts.txt. 32 The list of Internet-Draft Shadow Directories can be accessed at 33 http://www.ietf.org/shadow.html. 35 This Internet-Draft will expire on September 12, 2008. 37 Abstract 39 This document specifies a Data Modeling Language (Kalua DML), which 40 is designed to be used as a specification language for the payload of 41 the IETF NETCONF protocol [RFC4741] as well as to specify other 42 management related data models. The Kalua DML aims to fit the 43 requirements specified in draft-linowski-netconf-dml-requirements 44 [Linowski] and supports most of the requirements in RCDML [RCDML]. 46 Comments can be sent to ngo@ietf.org. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 51 2. Conventions used in this document . . . . . . . . . . . . . . 8 52 3. Documentation conventions . . . . . . . . . . . . . . . . . . 9 53 3.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 9 54 3.2. Model element descriptions . . . . . . . . . . . . . . . 10 55 3.3. Constraints . . . . . . . . . . . . . . . . . . . . . . . 11 56 4. Language Introduction . . . . . . . . . . . . . . . . . . . . 12 57 4.1. Language Design Fundamentals . . . . . . . . . . . . . . 12 58 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 13 59 4.2.1. Network resource configuration modeling . . . . . . . 13 60 4.2.2. Network Modeling and Network Management Support . . . 18 61 4.2.3. Notifications . . . . . . . . . . . . . . . . . . . . 24 62 4.2.4. Simplicity and Ease of Use . . . . . . . . . . . . . 27 63 4.2.5. Straightforward and Lossless Mapping . . . . . . . . 28 64 4.2.6. Kalua as Metamodel . . . . . . . . . . . . . . . . . 28 65 4.2.7. Release Management . . . . . . . . . . . . . . . . . 29 66 4.3. Use of XML and XML Schema . . . . . . . . . . . . . . . . 30 67 5. Kalua Elements . . . . . . . . . . . . . . . . . . . . . . . 32 68 5.1. Common Kalua Elements . . . . . . . . . . . . . . . . . . 32 69 5.1.1. name . . . . . . . . . . . . . . . . . . . . . . . . 32 70 5.1.2. presentation . . . . . . . . . . . . . . . . . . . . 33 71 5.1.3. description . . . . . . . . . . . . . . . . . . . . . 33 72 5.1.4. References to KALUA elements . . . . . . . . . . . . 33 73 5.1.5. Types . . . . . . . . . . . . . . . . . . . . . . . . 34 74 5.2. module . . . . . . . . . . . . . . . . . . . . . . . . . 36 75 5.2.1. Element Attributes . . . . . . . . . . . . . . . . . 36 76 5.2.2. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 37 77 5.2.3. Sub-Elements . . . . . . . . . . . . . . . . . . . . 38 78 5.2.4. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 38 79 5.2.5. Element Examples . . . . . . . . . . . . . . . . . . 39 80 5.3. import . . . . . . . . . . . . . . . . . . . . . . . . . 39 81 5.3.1. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 40 82 5.3.2. Sub-Elements . . . . . . . . . . . . . . . . . . . . 40 83 5.3.3. Constraints . . . . . . . . . . . . . . . . . . . . . 40 84 5.3.4. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 41 85 5.3.5. Element Examples . . . . . . . . . . . . . . . . . . 41 86 5.4. attribute . . . . . . . . . . . . . . . . . . . . . . . . 41 87 5.4.1. Attributes . . . . . . . . . . . . . . . . . . . . . 42 88 5.4.2. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 42 89 5.4.3. Sub-Elements . . . . . . . . . . . . . . . . . . . . 44 90 5.4.4. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 44 91 5.4.5. Element Examples . . . . . . . . . . . . . . . . . . 45 92 5.4.6. NETCONF Payload Examples . . . . . . . . . . . . . . 46 93 5.5. attribute-group . . . . . . . . . . . . . . . . . . . . . 46 94 5.5.1. Attributes . . . . . . . . . . . . . . . . . . . . . 47 95 5.5.2. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 47 96 5.5.3. Sub-Elements . . . . . . . . . . . . . . . . . . . . 47 97 5.5.4. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 48 98 5.5.5. Element Examples . . . . . . . . . . . . . . . . . . 48 99 5.5.6. NETCONF Payload Examples . . . . . . . . . . . . . . 48 100 5.6. structure . . . . . . . . . . . . . . . . . . . . . . . . 49 101 5.6.1. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 49 102 5.6.2. Sub-Elements . . . . . . . . . . . . . . . . . . . . 50 103 5.6.3. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 50 104 5.6.4. Element Examples . . . . . . . . . . . . . . . . . . 50 105 5.6.5. NETCONF Payload Examples . . . . . . . . . . . . . . 51 106 5.7. sequence . . . . . . . . . . . . . . . . . . . . . . . . 51 107 5.7.1. Attributes . . . . . . . . . . . . . . . . . . . . . 52 108 5.7.2. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 52 109 5.7.3. Sub-Elements . . . . . . . . . . . . . . . . . . . . 53 110 5.7.4. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 53 111 5.7.5. Element Examples . . . . . . . . . . . . . . . . . . 54 112 5.7.6. NETCONF Payload Examples . . . . . . . . . . . . . . 54 113 5.8. simple-type . . . . . . . . . . . . . . . . . . . . . . . 55 114 5.8.1. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 56 115 5.8.2. Sub-Elements . . . . . . . . . . . . . . . . . . . . 56 116 5.8.3. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 56 117 5.9. enum . . . . . . . . . . . . . . . . . . . . . . . . . . 57 118 5.9.1. Sub-Elements . . . . . . . . . . . . . . . . . . . . 57 119 5.9.2. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 58 120 5.9.3. Element Examples . . . . . . . . . . . . . . . . . . 58 121 5.9.4. NETCONF Payload Examples . . . . . . . . . . . . . . 58 122 5.10. enum-literal . . . . . . . . . . . . . . . . . . . . . . 58 123 5.10.1. Attributes . . . . . . . . . . . . . . . . . . . . . 59 124 5.10.2. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 60 125 5.10.3. Sub-Elements . . . . . . . . . . . . . . . . . . . . 60 126 5.10.4. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 60 127 5.10.5. Element Examples . . . . . . . . . . . . . . . . . . 60 128 5.10.6. NETCONF Payload Examples . . . . . . . . . . . . . . 61 129 5.11. union . . . . . . . . . . . . . . . . . . . . . . . . . . 61 130 5.11.1. Sub-Elements . . . . . . . . . . . . . . . . . . . . 62 131 5.11.2. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 62 132 5.11.3. Element Examples . . . . . . . . . . . . . . . . . . 62 133 5.11.4. NETCONF Payload Examples . . . . . . . . . . . . . . 63 134 5.12. restriction . . . . . . . . . . . . . . . . . . . . . . . 63 135 5.12.1. Sub-Elements . . . . . . . . . . . . . . . . . . . . 64 136 5.12.2. Restriction Facet-Elements . . . . . . . . . . . . . 64 137 5.12.3. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 65 138 5.12.4. Element Examples . . . . . . . . . . . . . . . . . . 66 139 5.13. typedef . . . . . . . . . . . . . . . . . . . . . . . . . 66 140 5.13.1. Attributes . . . . . . . . . . . . . . . . . . . . . 66 141 5.13.2. Sub-Elements . . . . . . . . . . . . . . . . . . . . 67 142 5.13.3. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 67 143 5.13.4. Element Examples . . . . . . . . . . . . . . . . . . 67 144 5.13.5. NETCONF Payload Examples . . . . . . . . . . . . . . 68 145 5.14. use . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 146 5.14.1. Attributes . . . . . . . . . . . . . . . . . . . . . 69 147 5.14.2. Sub-Elements . . . . . . . . . . . . . . . . . . . . 69 148 5.14.3. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 69 149 5.14.4. Element Examples . . . . . . . . . . . . . . . . . . 69 150 5.14.5. NETCONF Payload Examples . . . . . . . . . . . . . . 70 151 5.15. key . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 152 5.15.1. Attributes . . . . . . . . . . . . . . . . . . . . . 71 153 5.15.2. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 72 154 5.15.3. Sub-Elements . . . . . . . . . . . . . . . . . . . . 72 155 5.15.4. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 72 156 5.15.5. Element Examples . . . . . . . . . . . . . . . . . . 73 157 5.15.6. NETCONF Payload Examples . . . . . . . . . . . . . . 73 158 5.16. constraint . . . . . . . . . . . . . . . . . . . . . . . 74 159 5.16.1. Attributes . . . . . . . . . . . . . . . . . . . . . 74 160 5.16.2. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 74 161 5.16.3. Sub-Elements . . . . . . . . . . . . . . . . . . . . 74 162 5.16.4. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 75 163 5.16.5. Element Examples . . . . . . . . . . . . . . . . . . 75 164 5.17. class . . . . . . . . . . . . . . . . . . . . . . . . . . 75 165 5.17.1. Attributes . . . . . . . . . . . . . . . . . . . . . 77 166 5.17.2. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 77 167 5.17.3. Sub-Elements . . . . . . . . . . . . . . . . . . . . 78 168 5.17.4. Constraints . . . . . . . . . . . . . . . . . . . . . 78 169 5.17.5. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 78 170 5.17.6. Element Examples . . . . . . . . . . . . . . . . . . 79 171 5.17.7. NETCONF Payload Examples . . . . . . . . . . . . . . 80 172 5.18. relationship . . . . . . . . . . . . . . . . . . . . . . 81 173 5.18.1. Attributes . . . . . . . . . . . . . . . . . . . . . 82 174 5.18.2. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 83 175 5.18.3. Sub-Elements . . . . . . . . . . . . . . . . . . . . 83 176 5.18.4. Source and Target Leaf Sub-Elements . . . . . . . . . 84 177 5.18.5. Constraints . . . . . . . . . . . . . . . . . . . . . 84 178 5.18.6. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 86 179 5.18.7. Element Examples . . . . . . . . . . . . . . . . . . 87 180 5.18.8. NETCONF Payload Examples . . . . . . . . . . . . . . 91 181 5.19. annotation . . . . . . . . . . . . . . . . . . . . . . . 93 182 5.19.1. Element Attributes . . . . . . . . . . . . . . . . . 93 183 5.19.2. Sub-Elements . . . . . . . . . . . . . . . . . . . . 94 184 5.19.3. Constraints . . . . . . . . . . . . . . . . . . . . . 94 185 5.19.4. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 94 186 5.19.5. Element Examples . . . . . . . . . . . . . . . . . . 94 187 5.20. annotation-property . . . . . . . . . . . . . . . . . . . 94 188 5.20.1. Element Attributes . . . . . . . . . . . . . . . . . 95 189 5.20.2. Constraints . . . . . . . . . . . . . . . . . . . . . 95 190 5.20.3. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 95 191 5.20.4. Element Examples . . . . . . . . . . . . . . . . . . 95 192 5.21. annotation-type . . . . . . . . . . . . . . . . . . . . . 96 193 5.21.1. Element Attributes . . . . . . . . . . . . . . . . . 96 194 5.21.2. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 96 195 5.21.3. Sub-Elements . . . . . . . . . . . . . . . . . . . . 96 196 5.21.4. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 97 197 5.21.5. Element Examples . . . . . . . . . . . . . . . . . . 97 198 5.22. annotable-type . . . . . . . . . . . . . . . . . . . . . 97 199 5.22.1. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 98 200 5.22.2. Element Examples . . . . . . . . . . . . . . . . . . 98 201 5.23. annotation-property-type . . . . . . . . . . . . . . . . 98 202 5.23.1. Leaf Sub-Elements . . . . . . . . . . . . . . . . . . 99 203 5.23.2. Sub-Elements . . . . . . . . . . . . . . . . . . . . 99 204 5.23.3. XSD . . . . . . . . . . . . . . . . . . . . . . . . . 99 205 5.23.4. Element Examples . . . . . . . . . . . . . . . . . . 100 206 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 101 207 7. Security Considerations . . . . . . . . . . . . . . . . . . . 102 208 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 103 209 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 104 210 9.1. Normative References . . . . . . . . . . . . . . . . . . 104 211 9.2. Informative References . . . . . . . . . . . . . . . . . 104 212 Appendix A. Kalua XML Schema . . . . . . . . . . . . . . . . . . 105 213 Appendix B. Module Example: RFC1213-MIB . . . . . . . . . . . . 117 214 Appendix C. Netconf Payload Example . . . . . . . . . . . . . . 133 215 Appendix D. NETCONF Notification Example . . . . . . . . . . . . 135 216 Appendix E. DHCP example from RCDML Requirements Document . . . 136 217 Appendix F. DHCP augmentation example from RCDML Requirements 218 Document . . . . . . . . . . . . . . . . . . . . . . 141 219 Appendix G. Example for Partial Lock RPC for NETCONF . . . . . . 142 220 Appendix H. Support of RCDML Requirements in Kalua . . . . . . . 144 221 Appendix I. Support of Use Cases for SMI and MIB Modules . . . . 150 222 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 152 223 Intellectual Property and Copyright Statements . . . . . . . . . 153 225 1. Introduction 227 This document specifies a Data Modeling Language (Kalua DML), which 228 is designed to be used as a specification language for the payload of 229 the IETF NETCONF protocol [RFC4741] as well as to specify other 230 configuration management (CM) related data models. The Kalua DML 231 aims to fit the requirements specified in draft-linowski-netconf-dml- 232 requirements [Linowski] and supports most of the requirements in 233 RCDML [RCDML]. 235 XML-based data exchange and management has become increasingly 236 important because of its flexibility, readability, and ease of use. 237 XML supports hierarchical data structures and is supported by a large 238 number of management applications. The NETCONF Working Group has 239 completed the standardization of the XML-based configuration 240 management protocol and its notification mechanism supporting 241 asynchronous notifications. 243 However, a standardized way of configuration data modeling for 244 Netconf is missing. There is a need to define a standard content 245 layer based on a data-modeling framework for the development of 246 standard and vendor defined data model modules. 248 The necessary Data Modeling Language should address the requirements 249 of the Netconf protocols fully. However, the optimal case would be 250 if the DML can be used also for management fragments other than the 251 Configuration Management. We need to take into consideration the 252 increasing need for extensibility and the opportunity of providing 253 one data modeling language solution for different IETF problems also 254 other than O&M issues e.g. application servers. The aim for a new 255 DML solution at the IETF should be to support extensibility, broader 256 applicability to different kind of management issues and 257 harmonization of data models for manifold management applications. 259 Having this in mind the definition of a common O&M meta-model seems 260 to be sensible where diverse management fragments, such as 261 configuration management, can derive or inherit commonly used data 262 modeling structures and do not define these themselves if already 263 available. For the achievement of such flexibility, we propose an 264 object-oriented approach where attribute groups and meta class 265 definitions can be inherited to avoid data redundancy and to enable 266 data model design flexibility. 268 In the following chapters the KALUA Data Modeling Language fitting to 269 the requirements defined in draft-linowski-netconf-dml-requirements 270 [Linowski] is specified. The specification defines the model 271 elements of the KALUA language. 273 KALUA language defines how one can model basic concepts which apply 274 to a specific management fragment, such as fragment identifiers, 275 annotations, content trees, and common principles that apply to 276 fragments of the metamodel (such as identifiers of model objects and 277 references between the objects). 279 KALUA language is designed to model the operation and maintenance 280 interface, that is, the crossing point where the network equipment 281 and management system meet. Kalua defines how one can model 282 configuration management concepts and can use and combine the 283 features of Kalua to create expressive and concise data models. 285 Kalua language provides built-in abstract and concrete object 286 classes, attributes, attribute groups and data types that the data 287 models may use by inheritance. This approach harmonizes concepts, 288 which are widely used in operations and maintenance data models. 290 2. Conventions used in this document 292 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 293 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 294 document are to be interpreted as described in RFC 2119 [RFC2119]. 296 3. Documentation conventions 298 3.1. Terminology 300 o abstract class: abstract class is a class, which cannot be 301 instantiated. That is, an object instance cannot be created with 302 an abstract class as its class. However, abstract classes as a 303 super-class of a class does not prevent the non-abstract class to 304 be instantiated. 306 o annotation: Additional metadata that refines semantics of a model 307 element. A typed annotation consists of properties, which have a 308 type and a value. 310 o attribute: A named data element that can hold a value (structural 311 feature). 313 o attribute group: Group of attributes supposed to be used only to 314 define the contents of classes (or structures). 316 o attribute container: A model element that contains attributes. 317 Abstraction of attribute groups, structures and classes. 319 o base type: The type from which a refined type was derived, which 320 may be a built-in type or another derived type. 322 o built-in type: A data type defined in the Kalua, such as 323 'unsignedInt' or string. 325 o class: A language construct used to describe the structural 326 features of instances with an own identity and life-cycle. 328 o data model: A mapping of the contents of an information model into 329 a form that is specific to a particular type of data store or 330 repository. A "data model" is the rendering of an information 331 model according to a specific set of mechanisms for representing, 332 organizing, storing and handling data. 334 o enumeration: Data type with an enumerated set of values. 336 o identifier: Used to identify a model element (class, attribute, 337 etc.) in the containing namespace in a unique way. 339 o information model: An abstraction and representation of the 340 entities in a managed environment, their properties, attributes 341 and operations, and the way that they relate to each other. It is 342 independent of any specific repository, software usage, protocol, 343 or platform. 345 o list: Sequence of elements of the same type. 347 o managed object: An abstract representation of network resources 348 that are managed. A managed object may represent a physical 349 entity, a network service, or an abstraction of a resource that 350 exists independently of its use. 352 o management fragment: category of management tasks. For example 353 configuration management, performance management, and fault 354 management are management fragments. 356 o model element: A building block of the Kalua language. 358 o module: A set of related definitions 360 o object: Instance of a class 362 o relationship: Definition of an association between instances of 363 two classes. 365 o struct: Set of attributes without own identity 367 o super class or superclass: A class from which the derived class is 368 directly derived. 370 3.2. Model element descriptions 372 Each model element is described in its own section, with the model 373 element name as a title. Attributes of a model element are described 374 in an attributes section. Model elements, which are contained in a 375 model element, are listed in a sub-elements section. XML elements, 376 which are not model elements, are described in a leaf sub-elements 377 section. 379 In the sub-elements section, a minimum and maximum number of 380 occurrences per containing model element are defined for each sub- 381 element. If maximum number of occurrences is 'unbounded', there is 382 no upper limit on how many times the sub-element may be repeated. 383 The status of the elements has been stated as M(andatory or 384 O(ptional). 386 The model element sections give a definition example of that model 387 element type in Kalua language, the relevant part of the Kalua XML 388 schema, and if applicable, an example of the Netconf payload model by 389 using the model element definition. 391 3.3. Constraints 393 In case of complex restrictions on sets of acceptable values for 394 features of a Kalua element, the constraints are listed in a separate 395 constraints section. 397 4. Language Introduction 399 4.1. Language Design Fundamentals 401 Kalua is an XML-based language for configuration data modeling and 402 network respectively system information modeling. 404 Using XML as a technological foundation for Kalua was chosen since: 406 o NETCONF is an XML passed protocol in which protocol elements as 407 well as payload is encoded in XML. So using XML also as a basis 408 for the language that is supposed to define the structure of 409 NETCONF avoids technological fragmentation. 411 o XML is well known in the IT industry. Using it as a basis for a 412 language decreases the barrier for adoption on the syntax level. 413 People can mainly focus on understating the language concepts and 414 their semantics instead of learning an entirely new syntax that 415 requires new tools for validation and processing. 417 o XML and the specification language for XML documents (XML schema) 418 have almost ubiquitous support in all kinds of IT systems. So 419 creating, validating and processing of language documents should 420 only require low to modest effort. 422 Kalua combines concepts of data modeling (such as structures, 423 sequences, attribute groups etc.) with concepts from object-oriented 424 domain modeling (classes, relationships and class inheritance). This 425 was done because of several reasons: 427 o Network management in particular but also system management in 428 general is often done in a hierarchical manner. That means some 429 kind of manager, a network management system, a mediator but also 430 network elements with management functions have to deal with plain 431 configuration data as well as with some form of data represented 432 by more or less generic models. Being able to express both types 433 of data in Kalua helps to keep the integration and mediation 434 effort low when integrating different systems, operating at 435 different levels in the abstraction hierarchy. Even if other 436 modeling languages like UML (at the highest levels) or SMI (at the 437 lower levels) are used in different layers, being able to 438 represent core concepts of such languages in Kalua helps to avoid 439 "semantic gaps" that require cumbersome and costly "bridges" (in 440 form of mediators, model transformers, etc.) 442 o Enhanced expressiveness: It is very useful to be able to specify 443 plain data structures and links as well as concepts with a more 444 refined semantics like classes and relationships (associations). 446 Being able to choose the most appropriate modeling construct 447 ensures correctness, maintainability, and reusability. 449 o Flexibility: Managed systems with individual elements are in a 450 continuous change, i.e. new types of network elements are 451 introduced, new versions of such elements are created, and 452 additional ways of connecting (relating) elements need to be 453 represented. The challenge here is to integrate new parts into 454 the picture without having to alter the models for existing parts. 455 Object oriented modeling provides mechanisms to address this 456 challenge. Abstract classes allow defining and relating generic 457 concepts. For example, this facilitates implementing generic 458 management functionality that can be applied to instances of all 459 concrete classes which specialize particular abstract classes. 460 Inheritance allows to add new enhanced or otherwise refined 461 without touching the base class. Relationship refinement allows 462 detailing how newly created resources (represented by classes) 463 participate in already defined relationships. 465 o TM Forum NGOSS SID (Shared Information/Data) model, which is the 466 basis of OSS/J API data models, and the DMTF CIM (Common 467 Information Model) are examples of data models in the network 468 management domain that make use of object- oriented concepts. 470 4.2. Language Overview 472 This section introduces the core concepts of Kalua, puts them in 473 perspective to common problems in configuration and network modeling, 474 and illustrates their use and interrelations with examples. 476 4.2.1. Network resource configuration modeling 478 As a language that is supposed to specify the structure of the 479 payload of the Netconf protocol, Kalua has various language features 480 for specifying the data structures representing configuration 481 elements and state description elements of systems. 483 4.2.1.1. Property modeling 485 As a DML for configuration management, it must be possible to 486 describe the properties of manageable resources that are subject of 487 configuration. In addition, it must be possible to specify 488 properties that represent the actual state of such a manageable 489 resource. Such properties are modeled in Kalua in form of 490 attributes. 492 493 kalua:long 494 ... 495 497 An attribute is simply a property of some manageable entity, which 498 has a name and a type, among some other features that control how the 499 attribute can be used. Attributes can have primitive types (int, 500 boolean, string, etc.), refined simple types, as well as complex 501 types (structures, sequences, etc.). 503 4.2.1.2. Primitive Types and Refinement of Primitive Types 505 Manageable resources typically have many attributes of primitive 506 type, for example numeric parameters, string type parameters, boolean 507 flags or configuration items with an enumerable set of values. 509 Kalua therefore supports all non-XML specific and not date-related 510 primitives and build-in types defined in [XML schema 1.1 Part 2: 511 Datatypes]. In effect that means that all signed integer types 512 (short, int, long etc.), all unsigned integer types ("unsignedInt", 513 "unsignedLong" etc.), "float" and "double" as well as other basic 514 primitives like "string" and "boolean" are supported. Predefined 515 types are used by referring to them in type elements. 517 kalua:int 519 Also "dateTime" and "duration" are supported in order to express 520 points in time or periods of time. Other XML schema data types that 521 deal with time related values are not part of Kalua in order to avoid 522 that systems interpreting Kalua defined contents have to cope with 523 many types that only provide little additional value (XML schema 1.1 524 Part 2: Datatypes defines 11 different time related types). In 525 addition, the XML centric types like "NCName" or "QName" are left out 526 from Kalua as their use would require detailed XML knowledge and 527 their value outside XML centric applications is questionable. 529 Since many network resource parameters accept only a subset of the 530 range of values that can be hold by a primitive type instance, it is 531 quite essential that such restrictions can be exactly yet easily 532 expressed. 534 For example, for an attribute that specifies an angle in degrees, it 535 should be possible to limit the range of acceptable values to start 536 from 0.0 inclusive and end at 360.0 exclusive. In Kalua, restricting 537 the set of values that can be applied to an attribute is done by 538 refining an existing primitive type with constraints. 540 541 542 543 kalua:double 544 545 546 547 548 ... 549 551 4.2.1.3. Complex Datatype Modeling 553 Apart from creating new types by refining primitive types, Kalua also 554 supports the construction of complex types, namely structures, 555 sequences, and enumerations. 557 Many network element parameters accept only a few distinct value 558 representing different configuration options. Also, the state of 559 resources is often described with a few distinct literals. The 560 operational state as defined in ITU-T X.721 is a typical example. In 561 order to be able to define attributes that accept only a value from a 562 fixed set of alternatives, Kalua supports enumerations. 564 565 566 567 568 569 570 571 ... 572 574 Many network elements have some kind of data that is organized in 575 lists, arrays or tables, simply because some basic set of data has to 576 present in multiple instances in order to describe configuration or 577 state data properly and completely. 579 Kalua support this kind of data structures in form of sequences. 580 Depending on the properties of the sequence, it can represent arrays 581 (sequences with a fixed length), list (sequences with a variable 582 length) or even bags (sequences in which the actual position of an 583 element has no meaning). 585 586 kalua:boolean 587 ... 589 591 In order to represent the configuration or state data of network 592 resources accurately, it is often needed to group various attributes 593 with probably different types into an own organization unit. Kalua 594 allows defining structures in order to address this need. 596 597 598 kalua:string 599 600 601 kalua:unsignedShort 602 603 ... 604 606 Apart from consolidating attributes into a bigger unit, structures 607 are also useful to structure the namespace for properties of a 608 manageable resource. 610 The full potential of sequences and structures is only unleashed when 611 they are combined. Many network elements and other kinds of 612 configurable systems have some kind of data tables. In Kalua, a 613 table can be modeled as a sequence of structures. The member 614 attributes of the structure define the columns, the properties of the 615 sequence define the extend of the table. 617 618 619 620 kalua:string 621 ... 622 623 624 kalua:unsignedShort 625 ... 626 627 ... 628 629 ... 630 632 It is allowed to nest complex type definitions in an arbitrary 633 fashion. Therefor it is possible to define structures that contain 634 sequence-type attributes, sequences of sequences, etc. 636 4.2.1.4. Named Data Types 638 In the examples above, the structures, sequences and enumerations 639 were not given a name. In case a complex datatype is defined inside 640 an attribute, a name is not needed as the name of the attribute is 641 used to address the element of the datatype. In case a complex 642 datatype is defined inside a sequence, an index-number is used. 644 Often complex types can be reused in various different places of the 645 configuration of a configurable system (network element). For 646 example, many IP-based network elements must deal with several IP- 647 addresses as part of their configuration. It is useful to create a 648 structure, which combines the attributes, e.g. describing an IP- 649 address, and to give it a name enabling the usage wherever needed. 650 Kalua introduces the typedef element for this purpose. 652 A type definition (typedef) simply gives a datatype a name. The name 653 specified as part of the typedef is applied to the datatype defined 654 inside the type definition element. 656 657 658 659 kalua:string 660 ... 661 662 663 kalua:unsignedShort 664 ... 665 666 ... 667 668 ... 669 671 Such a user-defined data type can now be in each context where a type 672 is expected. For example, such a type can be used inside attribute 673 definitions and sequence definitions. 675 676 ipAddress 677 ... 678 680 Type definitions can only appear in the scope of a module (they are 681 top-level elements). 683 4.2.2. Network Modeling and Network Management Support 685 Manageable network elements do not exist in isolation. Almost any 686 kind of manageable network resource is in some form related to other 687 network resources. This web of network elements connected via all 688 kinds of relationships - the network topology - is one of the 689 cornerstones of effective network management. It has even 690 significant impact on the management of individual network elements 691 as many of their configuration elements realize or depend on the 692 topology and typically a large portion of their state data can only 693 be interpreted with respect to its place in the network topology. 695 o A network resource is contained in another resource. Containment 696 means that a manageable resource is physically contained in 697 another one, for example a card that is plugged into a rack. 698 However, containment could also mean that a resource is only 699 conceptually enclosed in another resource. This is often 700 synonymous with being dependent in terms of manageability on the 701 containing resource. 703 o A network element is connected to another network element. For 704 example, data transmission channels like PCM links can be seen as 705 connections. 707 o Network resources are in some form related to conceptual entities 708 like maintenance regions or locations. 710 o Network resources use functionality of another resource. 712 Being able to model network resources as well as conceptual resources 713 and the relationships between them is quite essential for many 714 management tasks. Kalua therefore supports two concepts form object 715 oriented domain modeling, namely classes and relationships. 717 4.2.2.1. Classes 719 The main purpose of classes is to represent configurable entities 720 that share the following characteristics: 722 o they have an own identity, 724 o they have an own, independent life cycle, and 726 o they are often treated as being a more abstract entity. 728 o Instances are often related to instances of other classes in some 729 form. 731 In Kalua, classes are containers of attributes. That makes them 732 similar to structures. But in contrast to structures: 734 o Classes can have a superclass. A class inherits all attributes 735 (and involvement in relationships) from its superclass. The same 736 applies for the superclass of the superclass and further ancestor 737 classes. 739 o Instances of classes can be used wherever instances of the 740 superclass can be used (Liskov substitution principle). So an 741 is-a relationship is established between the derived class and its 742 superclass. 744 o Classes can be abstract. That is useful to define concepts that 745 serve as a blueprint for concrete derived classes. In addition, 746 relationships can be defined that involve an abstract with a 747 concrete class or even with another abstract class. 749 o Classes must have a key in case they are asscoiated to other 750 classes by reference relationships. As instances of such classes 751 have to have an own identity, it must be possible to address class 752 instances uniquely by a key value. That is also needed in order 753 to realize relationships between classes respectively between 754 instances of related classes. 756 Classes are a vehicle to model "first-class network resources type" 757 like types of network resources with an own O&M interface as well as 758 independent conceptual entities like regions, sites, policies, plans 759 etc. 761 4.2.2.2. Relationships 763 Kalua also supports the concept of relationships. A relationship 764 associates instances of two classes, which can be two distinct 765 classes or the same class. The two endpoints of the relationship are 766 called source and target. The naming of the endpoints should lead to 767 a consistent usage of relationship definitions. This does not mean 768 that a relationship can only be navigated from source to target. 770 An important aspect of relationships in Kalua are that they are 771 defined outside the classes they connect. That has several 772 advantages: 774 o It is not necessary to anticipate and define all kinds of 775 relationship that might be needed in the future. Instead, 776 relationship can be added "on top" of the classes they connect 777 later when really needed. That also prevents having to deal with 778 relationships that were once introduced because it was assumed 779 they would be needed but actually are not used. 781 o Relationships and classes can be separated into different modules. 782 Therefore, it is possible to define classes and their inner 783 structure (by using and defining all kinds of data types) in one 784 module and put relationships and supplementary definitions for 785 network modeling in another module. While a network element agent 786 only deals with the first module, a higher-level management system 787 can use the second module, which includes the first. 789 o They are very much decoupled. In case the definition of a 790 relationship would be owned by one of its endpoints (or the 791 definition would be even shared between both endpoints), 792 introducing a new relationship would require that the modules that 793 contain the classes to be related have to be changed. That might 794 not be a big technical problem, but is often more an 795 organizational issue. 797 798 ... 799 800 801 ... 802 803 804 805 Manager 806 ... 807 808 809 ManagedObject 810 ... 811 812 .... 813 815 Kalua also supports relationship refinement. I.e. it is possible to 816 define relatively high- level (abstract) relationships, which are 817 refined by relationships that connect more concrete classes. 819 820 821 .... 822 824 A typical use case for this feature is the proper modeling of 825 containment relationships, especially such that define the management 826 hierarchy of network resources. The parent-child relationship is 827 then defined at the root of the class hierarchy for managed objects 828 (managed object contains an arbitrary number of other managed 829 objects). 831 In order to properly define the relationship semantics as well as to 832 enhance flexibility and expressiveness, three kinds of relationships 833 are supported in Kalua: 835 o Reference relationships. They simply associate two classes. 837 o Containment relationships. This kind of relationship defines a 838 strict existence dependency between the contained object (target 839 end) and the containing end (source end). It means that if the 840 container object is deleted all contained objects are deleted as 841 well. 843 o Calculated relationships. Here, it is defined which instances of 844 the source and target end class (and their subclasses) are 845 actually related by a relationship expression. In effect, the 846 contents of the relationship are actually defined by the state of 847 the instances at the source and target end. Such relationships 848 have to be evaluated "online" whenever they are queried. 850 Two important aspects of relationships as defined in Kalua deserve 851 some explicit discussion. 853 When specifying the containment of class instances in Kalua, this has 854 to be done by defining containment relationships between them. While 855 this requires some effort for explicit specification of the 856 containment relationships, it has several advantages: 858 o Especially, it is possible to specify more than one containment 859 relationship that has the same contained class at the target end. 860 I.e. a class (respectively their instances) can be contained in 861 multiple different classes. 863 o It is possible to specify in a common way that a previously 864 defined class can be contained in a new class, so that the 865 definition of containment is not constrained by any other 866 organizational aspect. 868 o The multiplicity of instances of the contained class (target end) 869 can be exactly specified. 871 Kalua supports the specification of prescriptive reference 872 relationships and containment relationships. In addition, it allows 873 the specification of descriptive calculated relationships. It is 874 important to support both types of relationships as they address 875 different use cases: 877 o In many cases references to resources in the same or other network 878 elements are realized with attributes that contain some kind of 879 implicit key value or a part of a composite key. 881 For example, in order to describe an "is-connected-to" 882 relationship associating two network elements that are physically 883 connected via PCM links, the reference to the other end of the 884 association could be represented by a numerical id of the PCM link 885 terminated in the network element plus the index of the timeslot 886 in that PCM link. The PCM id as well as the timeslot index is 887 then represented as two numerical attributes. 889 This kind of association is best represented with a calculated 890 relationship with an expression that compares tuples of instances 891 of the class at the target end and instances of the class at the 892 source end by checking if they have the same PCM link id and 893 timeslot index stored in two particular attributes. 895 Realizing such a descriptive relationship with a reference 896 relationship typically leads to the problem of keeping track with 897 the configuration changes. 899 o Now if such network elements should be associated to a maintenance 900 region, a conceptual entity that groups resources based on their 901 geographical or even logical location in a network, using a 902 descriptive approach does not work, respectively is rather 903 inappropriate. 905 Many network elements do not have configuration elements that can 906 be used to store a key of a maintenance region, even putting this 907 information directly into a resource in the network is not a good 908 idea in the first place. This kind of association is best 909 realized in a prescriptive way by defining a reference 910 relationship. It is then left to the system that in managing 911 relationships specified in Kalua where and how the actual 912 relationship information is stored. The key specification 913 feature, which is part of Kalua, just describes which attributes 914 of a resource could be used for storing relationships. 916 4.2.2.3. Information Modeling with Classes and Relationships 918 The example below illustrates some of the essential aspects of 919 classes and relationships. First, network elements and locations are 920 modeled as abstract classes because network elements and sites 921 obviously have an independent life cycle. A network element comes 922 into existence terms of management at the latest when it is deployed 923 into the network and switched on. A location comes into existence 924 when somebody creates it in some kind of management system. 926 Network element as well as location is abstract concepts. By itself 927 they do not contain enough information to be usable for most (but not 928 necessarily all) concrete management operations. However, defining 929 them allows the establishment of a relationship between them, which 930 provides already some value. For example, it is possible to tell if 931 two network elements are placed at the same location and get the 932 description of the location of a network element. 934 As instances of "ManagedObject" are related to the instance of 935 "Location", they can be also related to instances of "Site" as a 936 specific type of location. It is even possible to define another 937 class that derives from "Location", e.g. one that uses geographical 938 coordinates to describe a location, and uses instances of that class 939 to represent the location for any type of network elements. 941 942 943 944 kalua:long" 945 ... 946 947 948 kalua:string" 949 ... 950 951 952 locationId 953 954 956 957 ManagedObject 958 959 kalua:string 960 ... 961 962 964 965 ... 966 ManagedObject 967 ... 968 970 971 Location 972 ... 973 974 .... 975 977 978 Location 979 980 kalua:string 981 ... 982 983 984 kalua:string 985 ... 986 987 988 kalua:string 989 ... 990 991 992 kalua:string 993 ... 994 995 997 4.2.3. Notifications 999 Same data model applies to change notifications, get (get-config, 1000 get) and edit-config operations of Netconf. 1002 In the context of Netconf protocol, operation attribute of a data 1003 element within the notification indicates whether the data has been 1004 merged, created, replaced, or deleted. The semantics of updating the 1005 data with notification from server to the client are the same as 1006 changing data with an edit-config from client to server. Default 1007 behavior is to merge. 1009 Several changes can be combined in the same notification, and changed 1010 changes done with one edit-config may be sent as several 1011 notifications. 1013 The following example demonstrates how the same Kalua model is used 1014 in get-config and edit-config requests and in a change notification. 1016 The following is the definition of the module used in the example: 1018 http://www.example.com/profile 1021 pr/ 1022 1.0 1024 1025 1026 kalua:string 1027 1028 1029 string 1030 1031 1032 name 1033 1034 1036 1038 First, the client requested get-config shows the initial state of the 1039 configuration: 1041 1043 1044 1045 1046 1047 1048 1050 1052 1053 1054 1055 profile-1 1056 auto 1057 1058 1059 profile-2 1060 manual 1061 1062 1063 1064 1065 Then, another Netconf client requests edit-config from the same 1066 server to change the running configuration: 1068 1070 1071 1072 1073 1074 1075 1076 1077 profile-1 1078 manual 1079 1080 1081 1082 1083 1085 1087 1088 1090 Then, a change event notification is sent to all clients which have 1091 subscribed the notifications for this part of the data: 1093 1096 1097 1098 1099 profile-1 1100 auto 1101 1102 1103 1104 1106 The client can also see the change in the get-config result. The 1107 data parts of the data which are not included in the change 1108 notification have not been changed. 1110 1112 1113 1114 1115 1116 1117 1119 1121 1122 1123 1124 profile-1 1125 auto 1126 1127 1128 profile-2 1129 manual 1130 1131 1132 1133 1135 4.2.4. Simplicity and Ease of Use 1137 While being complete in terms of expressive power, the DML should be 1138 as simple as possible. The main reason for that is ease of use and 1139 understandability. 1141 Simplicity in the context of a modeling language means: 1143 o As few language elements as possible. The more elements a 1144 language has, the more time it takes to learn them. 1146 o No complicated rules that restrict how and in which way language 1147 elements can be used. Having the freedom to use language elements 1148 wherever they make sense allows concentrating on the modeling 1149 problem at hand. 1151 Kalua is an XML based language, because: 1153 o The XML syntax is well known and the structure of basic syntax 1154 elements like elements, attributes is quite simple. As long as 1155 the overall structure of the DML language documents remains at a 1156 decent level and the verbosity is minimized, the usage of XML 1157 syntax is acceptable. 1159 o There are also a huge amount of tools available that allow 1160 editing, validating, and processing XML. That compensates the 1161 existing annoyances of XML as a language. 1163 o Finally, usability needs to be seen from the point of view of an 1164 engineer that is supposed to implement software that is reading, 1165 writing, or transforming DML documents. In case of an XML-based 1166 language, one can use existing, well-known software components 1167 with standardized or at least widely accepted interfaces. 1169 4.2.5. Straightforward and Lossless Mapping 1171 4.2.5.1. Mapping to XML Schema 1173 As Kalua is an XML-based language, which describes structural aspects 1174 of network resources, it is possible to translate a Kalua model 1175 (document) into an XML schema. That allows to use off the shelf XML 1176 parsers to read Kalua model files, check their well- formedness and 1177 validate their contents. 1179 4.2.5.2. Mapping to UML2 1181 As Kalua supports with classes, relationship (associations), and 1182 inheritance some of the core object oriented design concepts, 1183 translating Kalua models to UML2 models is done smoothly. Here the 1184 integration of object oriented concepts and their distinction from 1185 data modeling concepts pays back as it does not need to "guess" (by 1186 using some formalized heuristics) by what UML2 metamodel element a 1187 Kalua element is correctly represented. 1189 4.2.5.3. Mapping from UML2 1191 Also for mapping in the other direction, from UML2 to Kalua, the 1192 integration of object- oriented concepts makes things easier. The 1193 mapping from models specified with UML (version 2 as well as previous 1194 1.x releases) is important as many standard models in the 1195 telecommunication domain like TMF SID, CIM and 3GPP are specified in 1196 UML. 1198 4.2.6. Kalua as Metamodel 1200 Models can also be seen as instances of a metamodel. This point of 1201 view is especially important because the metamodel prescribes to a 1202 large extend how models are represented in object oriented terms as 1203 the predominant paradigm in programming languages today. 1205 The language features of Kalua are designed so that they can be 1206 easily mapped to metamodel classes and mix-in-classes (that can be 1207 also represented as interfaces). That should foster a structurally 1208 common representation of Kalua model elements in programming 1209 environments. 1211 4.2.7. Release Management 1213 Managed resources change over time, new features are introduced, 1214 existing features are removed. Thus their models must also change to 1215 accurately reflect these changes. At the same time, existing data, 1216 created with the old model, must be usable together with the new 1217 data. Applications developed against old model should be usable 1218 after upgrade. For example, views created in a management system 1219 should not become unusable whenever there is a change in the managed 1220 resources. They should be usable as long as the change is not 1221 affecting the parts of the model that they rely on. For example, 1222 adding an attribute to a class does not affect an application reading 1223 the data, and adding an optional attribute to a class does not affect 1224 the application writing the data. 1226 Kalua allows any number of releases of a module. Each module release 1227 may add or remove module elements compared to other releases. Model 1228 elements with the same name appearing in different releases of the 1229 same module are considered to represent the same type of managable 1230 resources. 1232 Multiple releases frequently occur when building systems that are 1233 both in a manager and agent role. E.g. a management system manages 1234 several agents via the NETCONF protocol, and exposes its own 1235 configuration data to an upper level management system via the 1236 NETCONF protocol, including the configuration data from the managed 1237 agents. Each agent defines its configuraton data as a Kalua module. 1238 The management system imports each of these modules into one 1239 composite Kalua module. This composite module defines the 1240 configuration data the management system exposes towards any upper 1241 level management system via the NETCONF protocol. 1243 In the upper scenario, the need for multiple releases occurs when 1244 there are Kalua modules of different releases but same type among the 1245 modules of the agents. 1247 Hierarchies of NETCONF interfaces may appear in the following system 1248 architectures: 1250 o A controller device providing a NETCONF interface manages several 1251 subdevices via NETCONF. 1253 o An element management system providing a NETCONF interface manages 1254 several devices via NETCONF. 1256 o A regional management system providing a NETCONF interface manages 1257 several element management systems via NETCONF. 1259 o A global management system manages several regional management 1260 systems via NETCONF. 1262 1263 Example Controller 1264 http://www.example.controller.com/ 1265 controller 1266 2.1 1267 Example 1268 1269 1270 http://www.subdevice.com/ 1271 subdevice1.0 1272 1.0 1273 1274 1275 http://www.subdevice.com/ 1276 subdevice2.0 1277 2.0 1278 1280 4.3. Use of XML and XML Schema 1282 Kalua is an XML-based language. The Kalua syntax and basic part of 1283 its semantics are specified in an XML schema - the Kalua schema (see 1284 Appendix A.). 1286 The syntax of Kalua was designed along the following guidelines: 1288 o Primary language concepts that can contain other language concepts 1289 are realized as XML elements. 1291 o Properties of primary language elements that potentially have long 1292 text values are represented as leaf XML elements with simple type 1293 contents. 1295 o Only the name of definitions and properties that always have short 1296 values are realized as XML attributes. 1298 o Mixed content is prohibited. 1300 5. Kalua Elements 1302 KALUA specification introduces a set of language elements. Many of 1303 the concepts defined in KALUA contain a set of common attributes or 1304 features defined in the sub- chapters below. Each concept definition 1305 specifies which of these attributes, if any, are applicable to the 1306 concept and whether the attribute is mandatory or not in this 1307 context. 1309 5.1. Common Kalua Elements 1311 The elements in this section are commonly used by Kalua language 1312 elements that define model elements. The value for each of the 1313 elements is provided as element body text. 1315 5.1.1. name 1317 Type: string [a-zA-Z][_A-Za-z0-9]{0,29} 1319 Description: 1321 "name" is a unique and permanent identifier of the KALUA element 1322 within a single module. "name" cannot be changed during the lifetime 1323 of the element (that is, across releases of a module); if the 1324 identifier changes, the element is considered to be new and the old 1325 element is considered to be deleted. Thus, the old data 1326 corresponding to this object is no longer accessible through the 1327 adaptation. 1329 The case of characters does not play a role in the uniqueness 1330 criteria. This means 'BTS' and 'bts' are overlapping identifiers. 1331 However, references to the "name" use the same case as in the 1332 definition of the element (see Section 5.1.4.). 1334 "name" is used to refer to the KALUA element in KALUA files, database 1335 schemata, data files, other metadata/configuration files, APIs, and 1336 everywhere where references to elements need to be interpreted by 1337 applications. However, "presentation" (described below) should be 1338 used in user interfaces to identify the elements. 1340 In context of adaptation development for each NE type, the uniqueness 1341 criteria of identifiers needs to be defined so that uniqueness 1342 constraints described in this specification and KALUA fragment 1343 specifications are met. 1345 Elements of different type may have the same "name". 1347 Specific model element types may have additional constraints for 1348 uniqueness of the "name" for a specific concept, defined separately 1349 for each model element type. 1351 5.1.2. presentation 1353 Type: string, maximum length 100 1355 Description: 1357 A short name visible to the end-user in application user interfaces. 1358 "presentation" is not used to refer to a KALUA element in data or 1359 metadata. Only end-user documentation should refer to the elements 1360 using "presentation". "presentation" can be changed without breaking 1361 the compatibility of existing data or other parts of metadata. 1363 "presentation" included in the model files is just a default. 1364 Default presentation could be overridden by language specific 1365 "presentation". If "presentation" is omitted it defaults to the 1366 value of name. 1368 "presentation" does not need to be unique within an adaptation or 1369 across adaptations. However, as "presentation" normally serves as an 1370 identifier of the element for the user, you should avoid overlapping 1371 values where two elements may be used in the same context (for 1372 example, in AttributeDef sub-elements of one ClassDef). 1374 5.1.3. description 1376 Type: string, maximum length 2000 1378 Description: 1380 "description" is a longer text, which helps end users to understand 1381 the purpose and other details of the element. It can span multiple 1382 lines, and can contain any characters. 1384 Applications displaying the "description" are also capable of 1385 deriving and displaying such information directly from metadata. 1387 5.1.4. References to KALUA elements 1389 KALUA language specifies references from model elements to other 1390 model elements. For each reference, a target model element type, for 1391 example attribute-group, is defined. While the semantics of a 1392 reference depend on model element type, and are definied for each 1393 model element type separately, KALUA uses a common syntax for the 1394 references to the model elements. The reference consists of a 1395 namespace prefix, a colon, and a model element name, that is, ns- 1396 prefix:name. 1398 Each reference has one target model element. The module where the 1399 model element is defined is considered target module of the 1400 reference. 1402 If the target module is the module containing the reference, the ns- 1403 prefix part of the reference must equal to the ns-prefix element of 1404 the module. 1406 If the target module is another module, there must exist an import 1407 element, within the module containing the reference or some modules 1408 imported by the module containing the reference, where value of the 1409 ns-prefix element equals to the ns-prefix part of the reference and 1410 ns-uri element equals to the ns-uri element of the target module. 1412 The name part of a reference must be equal to the value of the name 1413 attribute of the target model element. 1415 5.1.5. Types 1417 KALUA supports a subset of the primitive types respectively build-in 1418 types defined in 'XML Schema 1.1 Part 2: Datatypes'. Most of the 1419 numeric types are supported, the types for specifying a point in time 1420 and a duration, string and boolean as well as a selection of name 1421 types. 1423 The table below lists all primitive types supported by Kalua. Their 1424 value range, support for special values (like NaN, INF, -0), and 1425 lexical mapping is supported as defined in 'XML Schema Part 2: 1426 Datatypes' [XSD-TYPES]. 1428 In addition: 1430 o a value for type dateTime can also be specified in seconds from 1431 Epoch 00:00:00 on January 1, 1970, encoded as non-negative, 1432 decimal integer. 1434 o A value for type duration can also be specified in seconds, 1435 encoded as non-negative, decimal integer. 1437 In effect, values matching the regular expression '\+?[1-9][0-9]*' 1438 has to be interpreted as seconds from Epoch (dateTime) respectively 1439 duration in seconds (duration). 1441 +---------------+---------------------------------------------------+ 1442 | Identifier | Description | 1443 +---------------+---------------------------------------------------+ 1444 | string | String of characters. In case no length or | 1445 | | max-length restriction is specified, it is not | 1446 | | guaranteed that strings longer than 250 | 1447 | | characters can be stored in attributes that use a | 1448 | | the string type or a type that is based on string | 1449 | | without any length restriction.. | 1450 | | | 1451 | boolean | Boolean value | 1452 | | | 1453 | byte | Signed 8 bit integer. | 1454 | | | 1455 | short | Signed 16 bit integer | 1456 | | | 1457 | int | Signed 32 bit integer | 1458 | | | 1459 | long | Signed 64 bit integer | 1460 | | | 1461 | unsignedByte | Unsigned byte | 1462 | | | 1463 | float | IEEE 754 compliant, 32 bit floating point value | 1464 | | | 1465 | double | IEEE 754 compliant, 64 bit floating point value | 1466 | | | 1467 | unsignedShort | Unsigned 16 bit integer | 1468 | | | 1469 | unsignedInt | Unsigned 32 bit integer | 1470 | | | 1471 | unsignedLong | Unsigned 64 bit integer | 1472 | | | 1473 | dateTime | Date and time value | 1474 | | | 1475 | duration | A duration of time | 1476 | | | 1477 | decimal | Fixed point decimal with p decimal digits before | 1478 | | the decimal point and s digits behind the decimal | 1479 | | point. p is the precision and s the scale. The | 1480 | | default precision is 10 and the default scale is | 1481 | | 6. Specify precision and scale with a precision | 1482 | | constraint. | 1483 | | | 1484 | integer | Signed integer up to p decimal digits, where p is | 1485 | | the precision. The default precision is 10.. | 1486 +---------------+---------------------------------------------------+ 1488 5.2. module 1490 "module" is the root element of the Kalua definitions. Each Kalua 1491 document must contain exactly one "module" element. All other 1492 definitions of the model are contained in a module element. 1494 "module" is a logical grouping of definitions. However, the split of 1495 definitions to separate modules also implies the following semantics: 1497 o "module" implies the version of the definitions 1499 o "module" implies the namespace of the definitions 1501 o applicability of annotation types are limited to those "modules" 1502 which define or import them 1504 o references to model elements can occur only to definitions in the 1505 "module" itself, or any directly or indirectly imported module 1507 5.2.1. Element Attributes 1509 +-----------+------------+--------------------------------------+---+ 1510 | Attribute | Type | Description | S | 1511 | | [Default] | | | 1512 +-----------+------------+--------------------------------------+---+ 1513 | name | xsd:string | Unique identifier of the module | M | 1514 | | | within systems using this module. | | 1515 | | | To select globally unique | | 1516 | | | identifiers, identifiers should | | 1517 | | | begin with an inverse domain name of | | 1518 | | | the entity defining the module. | | 1519 +-----------+------------+--------------------------------------+---+ 1521 5.2.2. Leaf Sub-Elements 1523 +--------------+-------------------+----------------------------+---+ 1524 | Sub-Element | Type [Default] | Description | S | 1525 +--------------+-------------------+----------------------------+---+ 1526 | presentation | xsd:string | See Section 5.1.2 | O | 1527 | | | | | 1528 | description | xsd:string | See Section 5.1.3 | O | 1529 | | | | | 1530 | ns-uri | xsd:string | Defines the target | M | 1531 | | | namespace of the all | | 1532 | | | definitions in this | | 1533 | | | module. In Kalua, this | | 1534 | | | uniquely identifies the | | 1535 | | | module. | | 1536 | | | | | 1537 | ns-prefix | xsd:string | Defines the prefix used to | M | 1538 | | | attach the namespace to | | 1539 | | | the model element names. | | 1540 | | | | | 1541 | release | xsd:string | Indicates the release | M | 1542 | | maximum length | version of this specific | | 1543 | | 20. [a-zA-Z0-9]+ | definition of the module. | | 1544 | | (\.[a-zA-Z0-9]+)* | | | 1545 | | | | | 1546 | organization | xsd:string | Name of the organization | M | 1547 | | maximum length | responsible for the | | 1548 | | 100 | module. | | 1549 +--------------+-------------------+----------------------------+---+ 1551 5.2.3. Sub-Elements 1553 +-----------------+-----------+-----------+-------------------------+ 1554 | Sub-Element | MinOccurs | MaxOccurs | Description | 1555 +-----------------+-----------+-----------+-------------------------+ 1556 | annotation | 0 | unbounded | See Section 5.19 | 1557 | | | | | 1558 | import | 0 | unbounded | See Section 5.3 | 1559 | | | | | 1560 | typedef | 0 | unbounded | See Section 5.13 | 1561 | | | | | 1562 | attribute-group | 0 | unbounded | See Section 5.5 | 1563 | | | | | 1564 | class | 0 | unbounded | See Section 5.17 | 1565 | | | | | 1566 | relationship | 0 | unbounded | See Section 5.18 | 1567 | | | | | 1568 | annotation-type | 0 | unbounded | See Section 5.21 | 1569 +-----------------+-----------+-----------+-------------------------+ 1571 5.2.4. XSD 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1589 1590 1592 1597 1602 1606 1611 1616 1617 1618 1619 1621 1622 1624 5.2.5. Element Examples 1626 1627 Example Ethernet Interface 1628 http://www.example.com/ 1629 example 1630 2.1 1631 Example 1632 1634 5.3. import 1636 "import" element makes all definitions from another module available 1637 in the module containing the "import" element. All definitions 1638 imported to that other module from any other modules are imported as 1639 well. 1641 5.3.1. Leaf Sub-Elements 1643 +-------------+-------------------+-----------------------------+---+ 1644 | Sub-Element | Type [Default] | Description | S | 1645 +-------------+-------------------+-----------------------------+---+ 1646 | ns-uri | xsd:string | Selects the imported | M | 1647 | | | module. | | 1648 | | | | | 1649 | ns-prefix | xsd:string | Defines the namespace | M | 1650 | | | prefix used in the module | | 1651 | | | containing the import | | 1652 | | | element to attach the | | 1653 | | | namespace to the model | | 1654 | | | element names. When | | 1655 | | | writing a module, ns-prefix | | 1656 | | | of the imported module | | 1657 | | | should be used as the ns- | | 1658 | | | prefix of the import | | 1659 | | | element, unless there is a | | 1660 | | | conflicting ns-prefix | | 1661 | | | already in use in the | | 1662 | | | module. | | 1663 | | | | | 1664 | release | xsd:string | Selects from which release | M | 1665 | | maximum length | of the module the | | 1666 | | 20. [a-zA-Z0-9]+ | definitions are imported. | | 1667 | | (\.[a-zA-Z0-9]+)* | | | 1668 | | | | | 1669 | description | xsd:string | See Section 5.1.3 | O | 1670 +-------------+-------------------+-----------------------------+---+ 1672 5.3.2. Sub-Elements 1674 +-------------+-----------+-----------+-----------------------------+ 1675 | Sub-Element | MinOccurs | MaxOccurs | Description | 1676 +-------------+-----------+-----------+-----------------------------+ 1677 | annotation | 0 | unbounded | See Section 5.19 | 1678 +-------------+-----------+-----------+-----------------------------+ 1680 5.3.3. Constraints 1682 Model element references are only allowed to model elements in 1683 modules, which are directly or indirectly imported by the module in 1684 which the reference is given. 1686 A module must not directly or indirectly import definitions from 1687 several releases of a module. 1689 A module must not directly or indirectly import itself. That is, 1690 circular imports between modules are not allowed. 1692 All namespace prefixes, including the prefix of the module itself, 1693 must be unique within the module. 1695 5.3.4. XSD 1697 1698 1699 1700 1701 1702 1704 5.3.5. Element Examples 1706 1707 http://www.example.com/ 1708 example 1709 2.1 1710 1712 5.4. attribute 1714 An "attribute" represents structural features of some kind of 1715 manageable resource. As such, "attributes" can be part of an 1716 attribute group, a class, or a structure. 1718 An "attribute" can be addressed via its name. Each "attribute" name 1719 must be unique with respect to all "attributes" defined in the 1720 containing element (class, structure or attribute group) and the 1721 "attributes" inherited from superclasses and incorporated "attribute" 1722 groups. 1724 The most important property of an "attribute" is its type. 1725 "Attributes" can have a primitive type (for example, string, long, or 1726 boolean) as well as a constructed data type, that is, a sequence 1727 type, structure type or an enumeration. It is possible to refer to 1728 named types (see Section 5.13.) via the type element as well as to 1729 define the type inline by using sequence, structure or primitive 1730 elements inside the attribute element. 1732 5.4.1. Attributes 1734 +-----------+----------------+---------------------------+----------+ 1735 | Attribute | Type [Default] | Description | Use | 1736 +-----------+----------------+---------------------------+----------+ 1737 | name | name-string | The name of the | required | 1738 | | (see | attribute. | | 1739 | | Section 5.1.1) | | | 1740 +-----------+----------------+---------------------------+----------+ 1742 5.4.2. Leaf Sub-Elements 1744 +--------------+------------+-----+-----+---------------------------+ 1745 | Sub-Element | Type | min | max | Description | 1746 | | [Default] | oc. | oc. | | 1747 +--------------+------------+-----+-----+---------------------------+ 1748 | presentation | xsd:string | 0 | 1 | The presentation name | 1749 | | | | | used for the attribute. | 1750 | | | | | This name should be used | 1751 | | | | | in GUI's when presenting | 1752 | | | | | the attribute to human | 1753 | | | | | end users. | 1754 | | | | | | 1755 | description | xsd:string | 0 | 1 | The description of the | 1756 | | | | | attribute | 1757 | | | | | | 1758 | mandatory | none | 0 | 1 | If present must be | 1759 | | | | | provided during creation | 1760 | | | | | of the owning entity. | 1761 | | | | | Otherwise providing a | 1762 | | | | | value is optional | 1763 | | | | | | 1764 | optional | none | 0 | 1 | If present, a value might | 1765 | | | | | be provided during | 1766 | | | | | creation of the owning | 1767 | | | | | object. This is the | 1768 | | | | | default behavior. | 1769 | | | | | | 1770 | read-only | none | 0 | 1 | if present, the attribute | 1771 | | | | | is read only. It neither | 1772 | | | | | possible to provide a | 1773 | | | | | value during creation of | 1774 | | | | | the owning object | 1775 | | | | | creation nor to change | 1776 | | | | | the value afterwards. | 1777 | | | | | | 1778 | read-write | none | 0 | 1 | If present, the attribute | 1779 | | | | | can be read and written. | 1780 | | | | | This is the default | 1781 | | | | | behavior. | 1782 | | | | | | 1783 | unchangeable | none | 0 | 1 | If present, the attribute | 1784 | | | | | might be or must be | 1785 | | | | | assigned a value during | 1786 | | | | | creation of the owning | 1787 | | | | | object (depending on the | 1788 | | | | | presence of "mandatory" | 1789 | | | | | or "optional"), but | 1790 | | | | | cannot be changed | 1791 | | | | | afterwards. | 1792 | | | | | | 1793 | default | xsd:string | 0 | 1 | Specifies the default | 1794 | ValueLiteral | | | | value for the attribute. | 1795 | | | | | Default values can only | 1796 | | | | | be specified for | 1797 | | | | | primitive types. If the | 1798 | | | | | type is not 'string', a | 1799 | | | | | valid value literal must | 1800 | | | | | be used. | 1801 | | | | | | 1802 | unit | xsd:string | 0 | 1 | Specifies the unit in | 1803 | | | | | which the value for this | 1804 | | | | | attribute is measured. | 1805 | | | | | In case a unit is | 1806 | | | | | specified for the | 1807 | | | | | attribute type, this is | 1808 | | | | | overwritten by this unit. | 1809 +--------------+------------+-----+-----+---------------------------+ 1811 Only one of the elements "read-write", "read-only" or "unchangeable" 1812 might be present in an attribute element. Only "mandatory" or 1813 "optional" might be present (but not both). In case "read-only" is 1814 present, neither "mandatory" nor "optional" could be present. 1816 5.4.3. Sub-Elements 1818 +-------------+--------+-----------+--------------------------------+ 1819 | Sub-Element | min | max | Description | 1820 | | occurs | occurs | | 1821 +-------------+--------+-----------+--------------------------------+ 1822 | annotation | 0 | unbounded | See Section 5.19 | 1823 | | | | | 1824 | constraint | 0 | unbounded | Constraints applied in the | 1825 | | | | context of the attribute. | 1826 | | | | | 1827 | type | 0 | 1 | The named type of the | 1828 | | | | attribute. | 1829 | | | | | 1830 | primitive | 0 | 1 | The inline defined primitive | 1831 | | | | type of this attribute | 1832 | | | | | 1833 | structure | 0 | 1 | The inline defined structure | 1834 | | | | type of this attribute. | 1835 | | | | | 1836 | sequence | 0 | 1 | The inline defined sequence | 1837 | | | | type of this attribute. | 1838 +-------------+--------+-----------+--------------------------------+ 1840 5.4.4. XSD 1841 1844 1845 1846 1847 1848 1849 1851 1852 1853 1854 1855 1857 1858 1859 1860 1862 1864 1865 1866 1867 1869 5.4.5. Element Examples 1870 1871 Frequency 1872 kalua:int 1873 1800 1874 1875 Bearer channel frequency. 1876 1877 1879 1880 1881 1882 kalua:float 1883 1884 1885 kalua:float 1886 1887 1890 5.4.6. NETCONF Payload Examples 1892 1900 1894 1895 120.87 1896 97.334 1897 1899 5.5. attribute-group 1901 "attribute groups" are a means to bundle a set of attributes that are 1902 typically used together. For example, an "attribute group" for 1903 describing an IP address would bundle a string-typed attribute for 1904 the hostname and a short-typed attribute for the port. The main 1905 purpose of "attribute groups" is to be incorporated (used) by model 1906 elements that can contain attributes, so classes, structures and 1907 other attribute groups. Using an "attribute group" means that all 1908 the attributes that belong to the attribute group are imported into 1909 the using element. Attributes incorporated from an attribute group 1910 are otherwise treated as if they were directly inside incorporating 1911 element. 1913 No 'is-a' relationship is established between the "attribute group" 1914 and a using class or structure. As the "attribute group" concept is 1915 only addressing organizational purposes, "attribute groups" cannot be 1916 instantiated. 1918 5.5.1. Attributes 1920 +---------+----------------+-----------------------------+----------+ 1921 | Feature | Type | Description | Use | 1922 +---------+----------------+-----------------------------+----------+ 1923 | name | name-string | The name of the attribute | required | 1924 | | (see | group. It must be unique | | 1925 | | Section 5.1.1) | within the containing | | 1926 | | | module. | | 1927 +---------+----------------+-----------------------------+----------+ 1929 5.5.2. Leaf Sub-Elements 1931 +--------------+------------+-----+-----+---------------------------+ 1932 | Sub-Element | Type | min | max | Description | 1933 | | | oc. | oc. | | 1934 +--------------+------------+-----+-----+---------------------------+ 1935 | presentation | xsd:string | 0 | 1 | The presentation name | 1936 | | | | | used for the attribute | 1937 | | | | | group. | 1938 | | | | | | 1939 | description | xsd:string | 0 | 1 | The description of the | 1940 | | | | | attribute group. | 1941 +--------------+------------+-----+-----+---------------------------+ 1943 5.5.3. Sub-Elements 1945 +-------------+--------+-----------+--------------------------------+ 1946 | Sub-Element | min | max | Description | 1947 | | occurs | occurs | | 1948 +-------------+--------+-----------+--------------------------------+ 1949 | constraint | 0 | unbounded | Constraints that apply in the | 1950 | | | | context of this attribute | 1951 | | | | group. | 1952 | | | | | 1953 | attribute | 0 | unbounded | The attributes belonging to | 1954 | | | | this attribute group. | 1955 | | | | | 1956 | use | 0 | unbounded | The attribute groups used by | 1957 | | | | this attribute group | 1958 | | | | | 1959 | key | 0 | unbounded | Key definitions | 1960 +-------------+--------+-----------+--------------------------------+ 1962 5.5.4. XSD 1964 1968 1969 1970 1971 1972 1973 1974 1975 1977 5.5.5. Element Examples 1979 1980 IP Address 1982 IP address attributes 1983 1984 1985 kalua:string 1986 1987 1988 kalua:unsignedShort 1989 1990 1992 5.5.6. NETCONF Payload Examples 1994 . 1995 . 1996 www.example.com 1997 30100 1998 . 1999 . 2001 5.6. structure 2003 "structures" define cohesive sets of named properties of potentially 2004 varying type. In Kalua, "structure" elements define ordered sets of 2005 attribute elements. Each member attribute must have a name that is 2006 unique with respect to the other attributes contained in the 2007 "structure" or incorporated from used attribute groups. 2009 A "structure" itself has no name. A "structure" can be either a sub- 2010 element of an attribute definition, sequence definition or a sub- 2011 element of a type definition. In case a structure is defined inside 2012 an attribute or sequence, the structure can be addressed only by the 2013 name of the owning attribute respectively the element index in the 2014 sequence. 2016 In case a structure is part of a type definition, the type name is 2017 applied to the structure. Such structure types can be reused 2018 (referred to) in all contexts where a data type is expected. 2020 Since structures are attribute containers, structures can use or 2021 incorporate attribute groups. All attributes defined in used 2022 attribute groups become members of the "structure" and can be treated 2023 as any other attribute directly defined in the structure. 2025 Also keys can be defined for structures. In case the scope is 2026 global, the key attributes uniquely identify each "structure" 2027 instance within all instances of this "structure" definition. Keys 2028 with local scope identify "structure" instances only within the 2029 context of the containing object. Such keys are primarily used for 2030 structures that are used as elements of sequences. This allows to 2031 also addressing them via a key value. 2033 5.6.1. Leaf Sub-Elements 2035 +-------------+----------------+-----+-----+------------------------+ 2036 | Sub-Element | Type | min | max | Description | 2037 | | | oc. | oc. | | 2038 +-------------+----------------+-----+-----+------------------------+ 2039 | description | name-string | 0 | 1 | The description of the | 2040 | | (see | | | structure type. | 2041 | | Section 5.1.1) | | | | 2042 +-------------+----------------+-----+-----+------------------------+ 2044 5.6.2. Sub-Elements 2046 +-------------+--------+-----------+--------------------------------+ 2047 | Sub-Element | min | max | Description | 2048 | | occurs | occurs | | 2049 +-------------+--------+-----------+--------------------------------+ 2050 | annotation | 0 | unbounded | Annotations attached to the | 2051 | | | | structure. | 2052 | | | | | 2053 | constraint | 0 | unbounded | Constraints that apply in the | 2054 | | | | context of this attribute | 2055 | | | | group. | 2056 | | | | | 2057 | attribute | 0 | unbounded | The attributes belonging to | 2058 | | | | this attribute group. | 2059 | | | | | 2060 | use | 0..n | unbounded | The attribute groups used by | 2061 | | | | this attribute group | 2062 | | | | | 2063 | key | 0..n | unbounded | Key definitions | 2064 +-------------+--------+-----------+--------------------------------+ 2066 5.6.3. XSD 2068 2069 2070 2071 2072 2073 2075 2076 2077 2079 5.6.4. Element Examples 2081 2082 (x,y) 2083 2084 kalua::double 2085 2086 2087 kalua:double 2088 2089 2091 5.6.5. NETCONF Payload Examples 2093 . 2094 . 2095 . 2096 2097 441.2 2098 172.5 2099 2100 . 2101 . 2103 5.7. sequence 2105 A "sequence" is a data structure that contains several objects of the 2106 same type that can be addressed by their position in the "sequence". 2107 Sequences are therefore an ordered collection. 2109 Each "sequence" has a base type that determines the type of its 2110 elements. Constraints have a minimum length and a maximum length. 2111 By setting the maximum length to unbounded, it is possible to define 2112 sequences with arbitrary length. 2114 Sequences are also constrainable elements. Constraints defined 2115 within a "sequence" are applied in the context of the "sequence" 2116 object, they are not implicitly applied to each member. However, 2117 since the member type can be defined inline, it is no problem to 2118 refine an exiting data type with additional constraints. 2120 Sequence types have no name. A "sequence" can be either a sub- 2121 element of an attribute definition, another "sequence" definition, or 2122 a sub-element of a type definition. In case a "sequence" is defined 2123 inside an attribute or "sequence", the "sequence" type cannot be 2124 reused in another context. Instances can be addressed by the name of 2125 the owning attribute respectively the element index in the 2126 "sequence". 2128 In case a "sequence" is part of a type definition, the type name is 2129 applied to the "sequence". Such "sequence" types can be reused 2130 (referred to) in all contexts where a data type is expected. 2132 When representing sequence contents as XML elements, two cases have 2133 to be distinguished: 2135 o In case the elementName attribute of the sequence element is 2136 specified, the contents of each element of the sequence is wrapped 2137 into an XML element with the given name. Making the "boundaries" 2138 of a sequence element value explicit in the serialized form is 2139 sometimes needed in order to make sure that the original structure 2140 of the contents can be reconstructed from the serialized form. 2141 For example, a serialized form of a sequence of sequence of 2142 unbounded maximum length that does not demarcate the start and 2143 beginning of the elements of the inner sequence does not allow 2144 reconstructing the original input. 2146 o In case elementName is not defined, each element is serialized as 2147 if it was directly contained in the owning element (typically an 2148 attribute). In effect, the sequence is "flattened". 2150 5.7.1. Attributes 2152 +-------------+-----------------+------------------------+----------+ 2153 | Attribute | Type [default] | Description | Use | 2154 +-------------+-----------------+------------------------+----------+ 2155 | minLength | xsd:unsignedInt | The minimum sequence | optional | 2156 | | [0] | length | | 2157 | | | | | 2158 | maxLength | xsd:unsignedInt | The maximum sequence | optional | 2159 | | [unbounded] | length | | 2160 | | | | | 2161 | elementName | name-string | The name used for | optional | 2162 | | (see | elements in the | | 2163 | | Section 5.1.1) | sequence data | | 2164 | | | representation. | | 2165 | | | | | 2166 | ordered | xsd:boolean | Tells if the sequence | optional | 2167 | | [false] | represents an ordered | | 2168 | | | collection or rather a | | 2169 | | | bag of elements. In | | 2170 | | | the second case, the | | 2171 | | | ordering of the | | 2172 | | | elements is arbitrary | | 2173 | | | and therefore has no | | 2174 | | | meaning. | | 2175 +-------------+-----------------+------------------------+----------+ 2177 5.7.2. Leaf Sub-Elements 2179 +-------------+------------+-----+-----+----------------------------+ 2180 | Sub-Element | Type | min | max | Description | 2181 | | | oc. | oc. | | 2182 +-------------+------------+-----+-----+----------------------------+ 2183 | description | xsd:string | 0 | 1 | The description of the | 2184 | | | | | sequence type. | 2185 +-------------+------------+-----+-----+----------------------------+ 2187 5.7.3. Sub-Elements 2189 +-------------+--------+-----------+--------------------------------+ 2190 | Sub-Element | min | max | Description | 2191 | | occurs | occurs | | 2192 +-------------+--------+-----------+--------------------------------+ 2193 | annotation | 0 | unbounded | Annotations attached to the | 2194 | | | | attribute group. | 2195 | | | | | 2196 | constraint | 0 | unbounded | Constraints that apply in the | 2197 | | | | context of this attribute | 2198 | | | | group. | 2199 | | | | | 2200 | type | 1 | 1 | The element type | 2201 +-------------+--------+-----------+--------------------------------+ 2203 5.7.4. XSD 2205 2206 2207 2208 2209 2210 2211 2212 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2227 2228 2229 2231 5.7.5. Element Examples 2233 2235 2237 . 2238 . 2239 . 2240 2241 2242 2243 (x,y) 2244 2245 kalua::double 2246 2247 2248 kalua:double 2249 2250 2251 2252 . 2253 . 2254 2256 2257 2258 kalua:int 2259 2260 2262 2263 2264 kalua:string 2265 2266 2268 5.7.6. NETCONF Payload Examples 2269 . 2270 . 2271 . 2272 2273 2274 441.2 2275 172.5 2276 2277 2278 441.2 2279 198.3 2280 2281 2282 343.8 2283 198.3 2284 2285 2286 . 2287 . 2288 . 2289 2290 2 2291 3 2292 8 2293 15 2294 2295 . 2296 . 2297 . 2298 r6687120-01 2299 r6687124-07 2300 r6687201-03 2302 5.8. simple-type 2304 "simple-type" elements are used to define new types that have simple 2305 values. However, like definitions of complex types (structures, 2306 sequences), they can be described and annotated. The unit in which a 2307 value of this simple type is measured can be stated and constraints 2308 can be specified for them. 2310 The set of legal values for the "simple-type" is defined by 2311 enumeration named values (enumeration element), by restricting 2312 existing simple types (restriction), by combining simple types 2313 (union) or by referring to an existing named "simple-type" (type). 2315 5.8.1. Leaf Sub-Elements 2317 +-------------+------------+-----+-----+----------------------------+ 2318 | Sub-Element | Type | min | max | Description | 2319 | | | oc. | oc. | | 2320 +-------------+------------+-----+-----+----------------------------+ 2321 | unit | xsd:string | 0 | 1 | The unit in which values | 2322 | | | | | of simple types is | 2323 | | | | | measured. | 2324 +-------------+------------+-----+-----+----------------------------+ 2326 5.8.2. Sub-Elements 2328 +-------------+--------+-----------+--------------------------------+ 2329 | Sub-Element | min | max | Description | 2330 | | occurs | occurs | | 2331 +-------------+--------+-----------+--------------------------------+ 2332 | annotation | 0 | unbounded | Annotations attached to the | 2333 | | | | attribute group. | 2334 | | | | | 2335 | constraint | 0 | unbounded | Constraints that apply in the | 2336 | | | | context of this attribute | 2337 | | | | group. | 2338 | | | | | 2339 | type | 0 | 1 | Reference to an existing | 2340 | | | | simple type. Allowing to | 2341 | | | | refer to a complex datatype | 2342 | | | | (structure, sequence) is not | 2343 | | | | allowed in the scope of a | 2344 | | | | simple type. | 2345 | | | | | 2346 | enum | 0 | 1 | Enumeration of simple type | 2347 | | | | values. | 2348 | | | | | 2349 | union | 0 | 1 | Union of simple types. | 2350 | | | | | 2351 | restriction | 0 | 1 | Restriction of another simple | 2352 | | | | type. | 2353 +-------------+--------+-----------+--------------------------------+ 2355 Exactly one of the type, enum, union, or restriction elements must be 2356 present in a "simple- type". 2358 5.8.3. XSD 2359 2360 2361 2362 2363 2364 2366 2368 2369 2370 2372 2373 2374 2375 2377 2378 2379 2380 2381 2382 2384 5.9. enum 2386 Enum elements define enumeration types, so types that are 2387 characterized by a fixed of named values. Each legal enumeration 2388 value is specified by an enum-literal element. 2390 As a simple-type, enumerations do not have an own description, 2391 annotations or constraints, the ones defined inside the owning 2392 simple-type element apply implicitly to the enumeration type. 2394 5.9.1. Sub-Elements 2396 +--------------+--------+-----------+-------------------------------+ 2397 | Sub-Element | min | max | Description | 2398 | | occurs | occurs | | 2399 +--------------+--------+-----------+-------------------------------+ 2400 | enum-literal | 0 | unbounded | The enumeration values. | 2401 +--------------+--------+-----------+-------------------------------+ 2403 5.9.2. XSD 2405 2406 2407 2410 2411 2413 5.9.3. Element Examples 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 . 2426 . 2427 . 2428 2429 AdministrativeState 2430 . 2431 . 2432 2434 5.9.4. NETCONF Payload Examples 2436 locked 2438 5.10. enum-literal 2440 An "enum-literal" defines one of the values that can be assigned to 2441 an enumeration that is defined by the containing enum element Each 2442 "enum literal" must have a different name. 2444 In addition to the name and presentation that can be specified for 2445 the literal, also a value may be provided. This value is used to 2446 represent the enum value in the implementing system. 2448 This could be useful in case a simple network element represents 2449 enumeration values as numbers. However, "enum literal" values should 2450 not be used when an enumeration type is defined that is standardized 2451 or otherwise implementation agnostic. E.g., the administrative state 2452 as defined in X.731 defines the values "unknown", "locked" , 2453 "shuttingDown" and "unlocked", so these terms are best used as 2454 literal names. However, is does not mandate any particular storage 2455 representation, so none should be given in the definition of the 2456 according "enum literals". 2458 The presence of the value attribute also controls the enum value 2459 representation: 2461 o In case the value attribute is not used, the name of the "enum 2462 literal" is used to represent the enum value 2464 o In case the value attribute was assigned a value, that value is 2465 used to represent the literal. 2467 The value attribute must be used consistently. Either all "enum- 2468 literal" elements have a value attribute or none. 2470 5.10.1. Attributes 2472 +---------+------------+---------------------------------+----------+ 2473 | Feature | Type | Description | Use | 2474 +---------+------------+---------------------------------+----------+ 2475 | name | xsd:string | The name of the attribute. It | required | 2476 | | | must be unique within the set | | 2477 | | | of attributes which is the | | 2478 | | | union of the attributes defined | | 2479 | | | in the same attribute container | | 2480 | | | (class, structure, | | 2481 | | | attribute-group), the | | 2482 | | | attributes inherited from | | 2483 | | | superclasses (class) and the | | 2484 | | | set of attributes incorporated | | 2485 | | | from attribute groups (class, | | 2486 | | | structure, attribute-group). | | 2487 | | | | | 2488 | value | xsd:string | The string representation of | optional | 2489 | | | the storage value of the enum | | 2490 | | | literal | | 2491 +---------+------------+---------------------------------+----------+ 2493 5.10.2. Leaf Sub-Elements 2495 +--------------+------------+-----+-----+---------------------------+ 2496 | Sub-Element | Type | min | max | Description | 2497 | | | oc. | oc. | | 2498 +--------------+------------+-----+-----+---------------------------+ 2499 | presentation | xsd:string | 0 | 1 | The presentation name | 2500 | | | | | used for the attribute | 2501 | | | | | group. | 2502 | | | | | | 2503 | description | xsd:string | 0 | 1 | The description of the | 2504 | | | | | attribute group. | 2505 +--------------+------------+-----+-----+---------------------------+ 2507 5.10.3. Sub-Elements 2509 +-------------+--------+-----------+--------------------------------+ 2510 | Sub-Element | min | max | Description | 2511 | | occurs | occurs | | 2512 +-------------+--------+-----------+--------------------------------+ 2513 | annotation | 0 | unbounded | Annotations attached to the | 2514 | | | | attribute group. | 2515 +-------------+--------+-----------+--------------------------------+ 2517 5.10.4. XSD 2519 2522 2523 2524 2525 2526 2527 2528 2530 5.10.5. Element Examples 2531 2532 2533 2534 2535 Not started 2536 2537 2538 Running 2539 2540 2541 Suspended 2542 2543 2544 Stopped 2545 2546 2547 2548 . 2549 . 2550 2552 5.10.6. NETCONF Payload Examples 2554 . 2555 . 2556 1 2557 . 2558 . 2559 . 2560 8 2562 5.11. union 2564 A "union" combines two or more simple types. The set of legal values 2565 of this type is the "union" of all sets of legal values of each 2566 included simple type. 2568 As a simple type, "unions" do not have an own description, 2569 annotations or constraints, the ones defined inside the owning 2570 simple-type element apply implicitly to the enumeration type. 2572 5.11.1. Sub-Elements 2574 +-------------+--------+-----------+--------------------------------+ 2575 | Sub-Element | min | max | Description | 2576 | | occurs | occurs | | 2577 +-------------+--------+-----------+--------------------------------+ 2578 | type | 0 | unbounded | A named simple type that is | 2579 | | | | part of the union type. | 2580 | | | | | 2581 | enumeration | 0 | unbounded | An enumeration that is part of | 2582 | | | | the union type. | 2583 | | | | | 2584 | restriction | 0 | unbounded | A restricted simple type that | 2585 | | | | is part of the union type. | 2586 | | | | | 2587 | union | 0 | unbounded | A subordinate union type that | 2588 | | | | is part of this union type. | 2589 +-------------+--------+-----------+--------------------------------+ 2591 5.11.2. XSD 2593 2594 2595 2598 2599 2601 5.11.3. Element Examples 2602 2603 2604 2605 2606 kalua:int 2607 2608 2609 2610 2611 2612 2613 2614 2615 . 2616 . 2617 2618 . 2619 . 2621 5.11.4. NETCONF Payload Examples 2623 110 2624 . 2625 . 2626 230 2627 . 2628 : 2629 0 2631 5.12. restriction 2633 A "restriction" element specifies a restricted simple type. That is 2634 done by applying restriction facets to the contained or referred base 2635 simple type. 2637 It is possible to apply multiple restriction facets. A legal value 2638 for the restricted type must comply with all "restrictions", 2639 including the "restrictions" already applied to the base type. 2641 The restriction facets supported by Kalua are a subset of the 2642 restriction facets as defined in 'XML Schema 1.1 Part 2: Datatypes'. 2644 5.12.1. Sub-Elements 2646 +-------------+--------+--------+-----------------------------------+ 2647 | Sub-Element | min | max | Description | 2648 | | occurs | occurs | | 2649 +-------------+--------+--------+-----------------------------------+ 2650 | type | 0 | 1 | The restricted named base type | 2651 | | | | | 2652 | enumeration | 0 | 1 | The restricted enumeration base | 2653 | | | | type | 2654 | | | | | 2655 | restriction | 0 | 1 | The further restricted base type. | 2656 | | | | | 2657 | union | 0 | 1 | The restricted union type. | 2658 +-------------+--------+--------+-----------------------------------+ 2660 5.12.2. Restriction Facet-Elements 2662 +----------------+--------+-----------+-----------------------------+ 2663 | Sub-Element | min | max | Description | 2664 | | occurs | occurs | | 2665 +----------------+--------+-----------+-----------------------------+ 2666 | minInclusive | 0 | unbounded | Inclusive lower bound for a | 2667 | | | | numerical base type. | 2668 | | | | | 2669 | minExclusive | 0 | unbounded | Exclusive lower bound for a | 2670 | | | | numerical base type | 2671 | | | | | 2672 | maxInclusive | 0 | unbounded | Inclusive upper bound for a | 2673 | | | | numerical base type. | 2674 | | | | | 2675 | maxExclusive | 0 | unbounded | Exclusive upper bound for a | 2676 | | | | numerical base type | 2677 | | | | | 2678 | totalDigits | 0 | unbounded | The total digits of a | 2679 | | | | decimal base type | 2680 | | | | | 2681 | fractionDigits | 0 | unbounded | The fraction digits of a | 2682 | | | | decimal base type | 2683 | | | | | 2684 | length | 0 | unbounded | The length of a string base | 2685 | | | | type | 2686 | | | | | 2687 | minLength | 0 | unbounded | The minimum length of a | 2688 | | | | string base type | 2689 | | | | | 2690 | maxLength | 0 | unbounded | The maximum length of a | 2691 | | | | string base type | 2692 | pattern | 0 | unbounded | A regular expression that | 2693 | | | | must be matched. Applies | 2694 | | | | to string base type | 2695 +----------------+--------+-----------+-----------------------------+ 2697 5.12.3. XSD 2699 2701 2702 2703 2704 2706 2707 2709 2710 2711 2713 2715 2717 2719 2720 2721 2722 2723 2726 2727 2728 2729 2730 2732 2733 2735 2737 2738 2740 2742 5.12.4. Element Examples 2744 2745 2746 2747 2748 kalua:int 2749 2750 2751 2752 2753 2754 2755 2756 2757 . 2758 . 2759 2760 . 2761 . 2763 5.13. typedef 2765 The "typedef" element is used to give otherwise anonymous datatypes a 2766 name which can be used to refer to this type wherever a datatype is 2767 required. This is done by using the type name as body value of the 2768 type element. 2770 5.13.1. Attributes 2772 +---------+-------------+--------------------------------+----------+ 2773 | Feature | Type | Description | Use | 2774 +---------+-------------+--------------------------------+----------+ 2775 | name | name-string | The name of the type. It must | required | 2776 | | | be unique within the | | 2777 | | | containing module. | | 2778 +---------+-------------+--------------------------------+----------+ 2780 5.13.2. Sub-Elements 2782 +-------------+--------+--------+-----------------------------------+ 2783 | Sub-Element | min | max | Description | 2784 | | occurs | occurs | | 2785 +-------------+--------+--------+-----------------------------------+ 2786 | structure | 0 | 1 | The structure type to give a | 2787 | | | | name. | 2788 | | | | | 2789 | sequence | 0 | 1 | The sequence type to give a name. | 2790 | | | | | 2791 | simple-type | 0 | 1 | A simple-type that is given a | 2792 | | | | name. | 2793 | | | | | 2794 | type | 0 | 1 | Provides an alias for the | 2795 | | | | referred named type. | 2796 +-------------+--------+--------+-----------------------------------+ 2798 Exactly one of the structure, sequence, simple-type or type elements 2799 must be specified as child of the typedef element. 2801 5.13.3. XSD 2803 2807 2808 2809 2810 2811 2812 2813 2815 5.13.4. Element Examples 2816 2817 2818 2819 kalua:double 2820 ... 2821 2822 2823 kalua:double 2824 ... 2825 2826 2827 2829 5.13.5. NETCONF Payload Examples 2831 . 2832 . 2833 2834 0.73001 2835 0.239 2836 2837 . 2838 . 2840 5.14. use 2842 "use" elements specify what attribute groups are used in the owning 2843 attribute container. 2845 All attributes of the used (incorporated) attribute group become part 2846 of the containing element. Using an attribute from an attribute 2847 group is equivalent with defining an attribute directly as part of 2848 the container. 2850 Therefore, it is not allowed that attributes incorporated from an 2851 attribute group have the same name as an attribute that is already 2852 part of the container namespace. 2854 Since attribute groups are only organizing facilities, no "is-a 2855 relationship" is established between the used attribute group and the 2856 using container (class, structure). 2858 Note that also attribute groups themselves can use other attribute 2859 groups. 2861 "use" elements are processed in the order as they are defined in 2862 their attribute container. 2864 5.14.1. Attributes 2866 +-----------------+-------------+------------------------+----------+ 2867 | Feature | Type | Description | Use | 2868 +-----------------+-------------+------------------------+----------+ 2869 | attribute-group | name-string | The reference of the | required | 2870 | | | used attribute group. | | 2871 +-----------------+-------------+------------------------+----------+ 2873 5.14.2. Sub-Elements 2875 +-------------+--------+-----------+--------------------------------+ 2876 | Sub-Element | min | max | Description | 2877 | | occurs | occurs | | 2878 +-------------+--------+-----------+--------------------------------+ 2879 | description | 0 | 1 | The description of the use | 2880 | | | | element. | 2881 | | | | | 2882 | annotation | 0 | unbounded | Annotations attached to the | 2883 | | | | use element. | 2884 +-------------+--------+-----------+--------------------------------+ 2886 5.14.3. XSD 2888 2889 2890 2891 2892 2893 2895 2896 2898 5.14.4. Element Examples 2899 2900 IP Address 2901 < description > 2902 IP address attributes 2903 2904 2905 kalua:string 2906 2907 2908 kalua:unsignedShort 2909 2910 2912 2913 2914 . 2915 2916 . 2917 2919 5.14.5. NETCONF Payload Examples 2921 . 2922 2923 . 2924 . 2925 www.example.com 2926 30100 2927 12 2928 . 2929 . 2930 2932 5.15. key 2934 "key" elements specify which attributes belonging to an attribute 2935 container (class, structure, attribute group) form a "key". A "key" 2936 is a set of one or more distinct member attributes. Member 2937 attributes could be all attributes that cannot be left unset. 2938 Attributes directly defined in the scope of a class or group can be 2939 combined with attributes inherited from superclasses or incorporated 2940 from attribute groups. An attribute could be part of multiple keys. 2942 One important aspect of a "key" is its scope: 2944 o global: indicates a globally unique key 2946 o local: indicates that the key only identified instances in the 2947 scope of their containing (scoping) object 2949 "Keys" can have slightly different semantics depending in which 2950 context they are defined respectively used. In effect, the context 2951 of use also determines which scopes can be used: 2953 o A "key" that is part of a class uniquely identifies the instances 2954 of that class any meaningful context of use. For example, a "key" 2955 of a network element class must identify its instances (NE's) in 2956 the whole network. A "key" for a mobile equipment class must 2957 uniquely identify the equipment among all other mobile equipments 2958 (so an attribute capable of holding the 15 digit IMEI might do the 2959 job). 2961 o In contrast to that, "keys" that are part of structures may only 2962 uniquely identify the structure instance inside its containing 2963 object. In this case the scope of the key is 'local'. It is also 2964 possible that a "key" uniquely identifies the structure instance 2965 among all other instances. In this case, the scope of the "key" 2966 is 'global'. 2968 o In case a "key" is defined in an attribute group, its exact 2969 semantics is undefined. A concrete semantics is applied by using 2970 the attribute group in a class or structure. 2972 The member attributes of a "key" are enumerated by the member 2973 elements contained in the "key" element. 2975 5.15.1. Attributes 2977 +-----------+-----------------+--------------------------+----------+ 2978 | Attribute | Type | Description | Use | 2979 +-----------+-----------------+--------------------------+----------+ 2980 | scope | xsd:enumeration | The reference of the | required | 2981 | | | used attribute group. | | 2982 +-----------+-----------------+--------------------------+----------+ 2984 5.15.2. Leaf Sub-Elements 2986 +-------------+-------------+-----+-----------+---------------------+ 2987 | Sub-Element | Type | min | max oc. | Description | 2988 | | | oc. | | | 2989 +-------------+-------------+-----+-----------+---------------------+ 2990 | description | xsd:string | 0 | 1 | The description of | 2991 | | | | | the key. | 2992 | | | | | | 2993 | member | name-string | 0 | unbounded | The names of the | 2994 | | | | | member attributes. | 2995 +-------------+-------------+-----+-----------+---------------------+ 2997 5.15.3. Sub-Elements 2999 +-------------+--------+-----------+--------------------------------+ 3000 | Sub-Element | min | max | Description | 3001 | | occurs | occurs | | 3002 +-------------+--------+-----------+--------------------------------+ 3003 | annotation | 0 | unbounded | Annotations attached to the | 3004 | | | | use element. | 3005 | | | | | 3006 | member | 1 | unbounded | The members of the key | 3007 +-------------+--------+-----------+--------------------------------+ 3009 5.15.4. XSD 3011 3012 3013 3014 3015 3017 3018 3019 3020 3021 3022 3023 3024 3025 3026 3027 3029 5.15.5. Element Examples 3031 3032 Mobile Equipment 3033 3034 ... 3035 3036 3037 3038 kalua:string 3039 3041 3042 3043 kalua:string 3044 3045 . 3046 . 3047 3048 imei 3049 3050 3051 vendor 3052 serialNr 3053 3055 3057 5.15.6. NETCONF Payload Examples 3059 3060 . 3061 . 3062 SpaceMobil 3063 23-2308263673 3064 800282737266302 3065 . 3066 . 3067 3069 5.16. constraint 3071 "constraint" elements can be used to formulate constraints that are 3072 applied in the scope of the containing element. 3074 For example, "constraints" defined as child elements of an attribute 3075 element constrain the set of values that can be assigned to that 3076 attribute. "Constraints" defined as sub- elements of attribute 3077 containers (structures, attribute groups, classes) can express 3078 restrictions that values of one attribute can have to other 3079 attributes in that container. "Constraints" defined as part of 3080 relationships allows narrowing the set of instances that can actually 3081 be associated by that relationship. "Constraints" defined in classes 3082 could even navigate via relationship ends to other object in order to 3083 express constraints between instances of different classes. 3085 The "constraint" expression is specified as body value of the 3086 expression element. Therefore, exactly one expression element must 3087 be present. 3089 5.16.1. Attributes 3091 +---------+-------------+--------------------------------+----------+ 3092 | Feature | Type | Description | Use | 3093 +---------+-------------+--------------------------------+----------+ 3094 | name | name-string | The name of the constraint. | required | 3095 +---------+-------------+--------------------------------+----------+ 3097 5.16.2. Leaf Sub-Elements 3099 +-------------+------------+-----+-----+----------------------------+ 3100 | Sub-Element | Type | min | max | Description | 3101 | | | oc. | oc. | | 3102 +-------------+------------+-----+-----+----------------------------+ 3103 | description | xsd:string | 0 | 1 | The description of | 3104 | | | | | constraint | 3105 | | | | | | 3106 | expression | xsd:string | 0 | 1 | The constraint expression. | 3107 +-------------+------------+-----+-----+----------------------------+ 3109 5.16.3. Sub-Elements 3110 +-------------+--------+-----------+--------------------------------+ 3111 | Sub-Element | min | max | Description | 3112 | | occurs | occurs | | 3113 +-------------+--------+-----------+--------------------------------+ 3114 | annotation | 0 | unbounded | Annotations attached to the | 3115 | | | | attribute group. | 3116 +-------------+--------+-----------+--------------------------------+ 3118 5.16.4. XSD 3120 3122 3123 3124 3125 3127 3128 3130 3131 3133 5.16.5. Element Examples 3135 3136 @voltage * @ampere <= @maxPower 3137 3139 5.17. class 3141 "Classes" are used to describe objects that have an own identity and 3142 a potentially independent life cycle. "Classes" can represent 3143 concrete manageable resources in the network such as specific types 3144 of network elements or abstract concepts (e.g. managed objects or 3145 network resources). 3147 A "class" can have one superclass at the maximum. From the 3148 superclass a "class" does not only inherit all attributes and 3149 relationships, but also an implicit 'is-a' relationship is 3150 established between the "class" and its super class. This means that 3151 wherever the super class is used or referred to, also the derived 3152 "class" can be used. 3154 Kalua supports only single inheritance. This is to avoid the huge 3155 complexity caused by inheriting from multiple base classes. 3157 For reusing sets of attribute definitions that describe a certain 3158 aspect of an object, a "class" can use 0..n attribute groups (see 3159 Section 5.5). This means that all attributes of a used attribute 3160 group become members of the using "class". This does NOT mean that 3161 an 'is-a' relationship is established between the "class" and its 3162 base attribute groups. 3164 Instance of classes must be uniquely identifiable in case they are 3165 associated by reference relationships, so some kind of key needs to 3166 be available. Such a key is obtained in the following way: 3168 o If a key with global scope is defined in the "class" directly, 3169 inherited from a super class, or incorporated from an attribute 3170 group, this key is used. 3172 o In case a class is contained in another class and a key with local 3173 scope is defined, the global scope key for the actual class is 3174 composed from the key of the owing class and the own local scope 3175 key. 3177 o In case the class not contained in any another class and has a 3178 local key, this is used, as it is assumed that a NETCONF agent is 3179 able to uniquely identify the instance in its given context. 3181 In order to describe how class instances can be accessed, class 3182 definitions can contain a max-access element. Its body text value 3183 can have one of the following values: 3185 o not-accessible: The class is used only for internal purposes. 3186 Instances cannot be accessed in any way. 3188 o accessible-for-notify: Only notifications are generated when 3189 instances are created, modified or deleted. 3191 o read-only: It is only possible to read the actual state of 3192 instances of this class. 3194 o read-write: Instances of this class can be read and written, but 3195 not created. 3197 o read-create: It is possible to create, write, and read instances. 3199 In case instances of a class are readable, notifications might also 3200 be send when they are created, changed or deleted. 3202 5.17.1. Attributes 3204 +---------+-------------+--------------------------------+----------+ 3205 | Feature | Type | Description | use | 3206 +---------+-------------+--------------------------------+----------+ 3207 | name | name-string | The name of the class. | required | 3208 +---------+-------------+--------------------------------+----------+ 3210 5.17.2. Leaf Sub-Elements 3212 +--------------+-----------------+-----+-----+----------------------+ 3213 | Sub-Element | Type | min | max | Description | 3214 | | | oc. | oc. | | 3215 +--------------+-----------------+-----+-----+----------------------+ 3216 | description | xsd:string | 0 | 1 | The description of | 3217 | | | | | the class | 3218 | | | | | | 3219 | presentation | xsd:string | 0 | 1 | The presentation | 3220 | | | | | name used for the | 3221 | | | | | class respectively | 3222 | | | | | instances of the | 3223 | | | | | class. | 3224 | | | | | | 3225 | abstract | xsd:boolean | 0 | 1 | If present, the | 3226 | | | | | class is abstract. | 3227 | | | | | | 3228 | superclass | name-string | 0 | 1 | The name of the | 3229 | | | | | superclass. | 3230 | | | | | | 3231 | max-access | xsd:enumeration | | | Specifies how class | 3232 | | | | | instances can be | 3233 | | | | | accessed. | 3234 +--------------+-----------------+-----+-----+----------------------+ 3236 5.17.3. Sub-Elements 3238 +-------------+--------+-----------+--------------------------------+ 3239 | Sub-Element | min | max | Description | 3240 | | occurs | occurs | | 3241 +-------------+--------+-----------+--------------------------------+ 3242 | annotation | 0 | unbounded | Annotations attached to the | 3243 | | | | class. | 3244 | | | | | 3245 | constraint | 0 | unbounded | Constraints that apply in the | 3246 | | | | context of this class. | 3247 | | | | | 3248 | attribute | 0 | unbounded | The attributes directly | 3249 | | | | declared in the class. | 3250 | | | | | 3251 | use | 0 | unbounded | The attribute groups used by | 3252 | | | | the class. | 3253 | | | | | 3254 | key | 0 | unbounded | Key definitions | 3255 +-------------+--------+-----------+--------------------------------+ 3257 5.17.4. Constraints 3259 A class must not be its own super class - neither directly nor 3260 indirectly. This implies a cycle in the inheritance graph and does 3261 not have well-defined semantics. 3263 If a class is abstract and inherits from a superclass, this 3264 superclass must be abstract as well. 3266 A class must not inherit from an attribute group that is already 3267 inherited by one of its ancestor classes (that is, its super class or 3268 the super class of the super class, and so on). 3270 5.17.5. XSD 3271 3274 3275 3276 3277 3278 3279 3280 3283 3284 3285 3286 3287 3289 3291 5.17.6. Element Examples 3292 3295 3296 A site at which some network resources are located 3297 3298 3299 kalua:string 3300 3301 3302 3303 kalua:string 3304 3305 3306 kalua:string 3307 3308 3309 kalua:unsigedInt 3310 3311 3312 3313 3314 kalua:string 3315 3316 3317 kalua:string 3318 3319 3320 kalua:string 3321 3322 3323 3324 3325 name 3326 3327 3329 5.17.7. NETCONF Payload Examples 3330 . 3331 . 3332 3333 RANC 3334 Alphabet street 123 3335 Megalopolis 3336 65432 3337 3338 23o48'7'' 3339 56o23'45'' 3340 125m 3341 3342 3343 . 3344 . 3346 5.18. relationship 3348 "relationship" elements specify associations between two classes or 3349 an attribute group and a class. With "relationships", it is possible 3350 to describe the way instances of particular classes relate to each 3351 other. This covers the simple 'is-used-by' or 'is-managed-by' 3352 "relationship" as well as containment "relationships," such as the 3353 well-known parent-child "relationship" between managed objects. 3354 Three different types of relationships are distinguished: 3356 o reference: Simple bi-directional references between instances of 3357 two classes. For example, a 'managed-by' "relationship" indicates 3358 that the instance at the source end is managed by the instance at 3359 the target end. 3361 o containment: A containment "relationship" in which the instance at 3362 the source end contains all instances at the target end. This 3363 also means that if the containing object is deleted, all contained 3364 objects are also deleted. 3366 o calculated: Dynamically calculated "relationships". Instances of 3367 the classes at the source and target end are related if they are 3368 in the result set produced by the evaluation of a "relationship" 3369 expression at runtime. With this type of "relationship" you can 3370 define that two objects are related if they have the same parent 3371 in the containment tree and a particular attribute has the same 3372 value in both instances. 3374 A "relationship" can also refine an existing "relationship". This 3375 feature is usually used to narrow down the usage of a generic 3376 "relationship" inherited by the source and target end class. For 3377 example, an abstract class 'Resource' has a relationship 3378 'managedResources' that refers to all resources managed by a 3379 particular resource. If two concrete classes, 'ProtectionGroup' and 3380 'ProtectionUnit', inherit from 'Resource', you can refine the generic 3381 relationship 'managedResources' by creating a "relationship" 3382 definition 'managedUnits' between 'ProtectionGroup' and 3383 'ProtectionUnit' that has 'managedResource' as its base relationship. 3384 This would mean that a protection group could only manage protection 3385 units and no other types of resources. 3387 There are two main reasons to specify abstract relationships that are 3388 refined by concrete relationships: 3390 o The generic "relationship" can be used to navigate between object 3391 instances without needing to know what type of refined 3392 relationships exist for each concrete class. In the example 3393 above, this means that an application that only deals with 3394 resources can find out the managed units of a protection group 3395 instance by following the 'managedResources' relationship. 3397 o The system that has to store and restore class instances can take 3398 advantage of the fact that a "relationship" refines another one by 3399 reusing storage space. 3401 In the example above this means that if 'ProtectionGroup' and 3402 'ProtectionUnit' instances are stored in a relational database, the 3403 foreign key columns that are used to address the managing resource 3404 can be reused for addressing the controlling protection group. 3406 5.18.1. Attributes 3408 +-----------+------------+-------------------------------+----------+ 3409 | Attribute | Type | Description | Use | 3410 +-----------+------------+-------------------------------+----------+ 3411 | name | xsd:string | The name of the relationship | required | 3412 +-----------+------------+-------------------------------+----------+ 3414 5.18.2. Leaf Sub-Elements 3416 +--------------+-----------------+-----+-----+----------------------+ 3417 | Sub-Element | Type | min | max | Description | 3418 | | | oc. | oc. | | 3419 +--------------+-----------------+-----+-----+----------------------+ 3420 | description | xsd:string | 0 | 1 | The description of | 3421 | | | | | the relationship. | 3422 | | | | | | 3423 | kind | xsd:enumeration | 1 | 1 | The kind of | 3424 | | | | | relationship | 3425 | | | | | (reference, | 3426 | | | | | containment, | 3427 | | | | | calculated) | 3428 | | | | | | 3429 | readonly | xsd:boolean | 0 | 1 | Tells if | 3430 | | | | | relationship can be | 3431 | | | | | modifier, which is | 3432 | | | | | the default, or only | 3433 | | | | | read. | 3434 | | | | | | 3435 | base | name-string | 0 | 1 | The name of the base | 3436 | Relationship | | | | relationship | 3437 +--------------+-----------------+-----+-----+----------------------+ 3439 5.18.3. Sub-Elements 3441 +-------------+--------+-----------+--------------------------------+ 3442 | Sub-Element | min | max | Description | 3443 | | occurs | occurs | | 3444 +-------------+--------+-----------+--------------------------------+ 3445 | annotation | 0 | unbounded | Annotations attached to the | 3446 | | | | relationship | 3447 | | | | | 3448 | constraint | 0 | unbounded | Constraints that apply in the | 3449 | | | | context of this attribute | 3450 | | | | group. | 3451 | | | | | 3452 | source | 1 | 1 | The specification of the | 3453 | | | | source-end of the | 3454 | | | | relationship. | 3455 | | | | | 3456 | target | 1 | 1 | The specification of the | 3457 | | | | target-end of the relationship | 3458 +-------------+--------+-----------+--------------------------------+ 3460 5.18.4. Source and Target Leaf Sub-Elements 3462 The table below describes the simple typed XML elements that have to 3463 appear in source and target elements of a relationship element. 3465 +-------------+----------------+-----+-----+------------------------+ 3466 | Sub-Element | Type | min | max | Description | 3467 | | | oc. | oc. | | 3468 +-------------+----------------+-----+-----+------------------------+ 3469 | class | name-string | 1 | 1 | The class at one of | 3470 | | | | | the ends of the | 3471 | | | | | relationship. | 3472 | | | | | | 3473 | role | name-string | 1 | 1 | The role name of a | 3474 | | | | | relationship-end-class | 3475 | | | | | | 3476 | minCardinal | xsd:unsignedLo | 1 | 1 | The minimum number of | 3477 | ity | ng | | | objects that are | 3478 | | | | | addressed at the | 3479 | | | | | source or target end | 3480 | | | | | of this relationship. | 3481 | | | | | Typical values for the | 3482 | | | | | minimum cardinality | 3483 | | | | | are 0 (the target | 3484 | | | | | endpoint can remain | 3485 | | | | | undefined) or 1 (the | 3486 | | | | | target endpoint must | 3487 | | | | | be defined). | 3488 | | | | | | 3489 | maxCardinal | xsd:unsignedLo | 1 | 1 | The maximum number of | 3490 | ity | ng | | | objects that are | 3491 | | | | | addressed at the | 3492 | | | | | source or target end | 3493 | | | | | of this relationship. | 3494 | | | | | The value "unbounded" | 3495 | | | | | can be used to denoted | 3496 | | | | | an unlimited number of | 3497 | | | | | objects at the given | 3498 | | | | | relationship end. | 3499 +-------------+----------------+-----+-----+------------------------+ 3501 5.18.5. Constraints 3503 Several constraints must be fulfilled by an relationship: 3505 o A valid source end multiplicity requires that either the maximum 3506 cardinality is unbounded or the minimum cardinality is not greater 3507 than the maximum cardinality. 3509 o The source end multiplicity specification must allow that at least 3510 one object can be addressed at the source end, so source-end max 3511 cardinality must be greater than zero. 3513 o A valid target end multiplicity requires that either the maximum 3514 cardinality is unbounded or the minimum cardinality is not greater 3515 than the maximum cardinality. 3517 o The target end multiplicity specification must allow that at least 3518 one object can be addressed at the source end, so target-end max 3519 cardinality must be greater than zero. 3521 o An object can only be contained in another object at the same 3522 point in time. So in case of an containment relationship, it 3523 implies that the source-end max cardinality is one. 3525 When refining relationships, several constraints have to be 3526 considered: 3528 o If the relationship refines a base relationship, the source end 3529 class must be equal or derived from the base relationship source 3530 end class. 3532 o If the relationship refines a base relationship, the target end 3533 class must be equal or derived from the base relationship target 3534 end class. 3536 o If the relationship refines a base relationship, the relationship 3537 type must be the same as for the base relationship. 3539 o If the relationship refines a base relationship, the target 3540 minimum cardinality must be equal or greater than the target 3541 minimum cardinality at the base relationship. 3543 o If the relationship refines a base relationship, the target 3544 maximum cardinality must be equal or smaller than the target 3545 maximum cardinality at the base relationship. 3547 o If the relationship refines a base relationship, the source 3548 minimum cardinality must be equal or greater than the source 3549 minimum cardinality at the base relationship. 3551 o If the relationship refines a base relationship, the source 3552 maximum cardinality must be equal or smaller than the source 3553 maximum cardinality at the base relationship. 3555 5.18.6. XSD 3557 3560 3561 3562 3563 3566 3567 3568 3569 3570 3571 3572 3573 3574 3575 3576 3577 3578 3579 3580 3581 3582 3583 3584 3585 3587 3590 3591 3592 3593 3594 3595 3596 3597 3598 3599 3600 3601 3602 3604 3605 3606 3608 3609 3610 3611 3612 3614 3616 3617 3618 3619 3620 3622 3623 3624 3625 3626 3627 3628 3630 5.18.7. Element Examples 3632 3633 3634 3635 $source/ipAdEntIfIndex=$target/ifIndex 3636 3637 3638 3639 ipAddrEntry 3640 ipAddress 3641 0 3642 1 3643 3644 3645 ifEntry 3646 interface 3647 1 3648 1 3649 3650 3651 3657 3658 3659 3660 kalua:string 3661 3662 3663 3664 kalua:string 3665 3666 3667 3668 kalua:string 3669 3670 3671 objectId 3672 3673 3674 commonName 3675 3676 3678 3679 3680 RootEntity 3681 3682 3683 kalua:string 3684 3685 3687 3688 3689 3690 3691 3692 3693 3694 3695 3696 3697 3698 3700 3702 3703 3704 Entity 3705 3706 ManagementMethod 3707 3708 3709 3710 ManagementMethod 3711 3712 3713 3715 3716 3717 ManagedEnity 3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3733 3734 3735 Resource 3736 3737 kalua:dateTime 3738 3739 3740 kalua:string 3741 3742 3743 3744 3745 3746 3748 3749 3750 3751 3752 kalua:string 3753 3754 3755 kalua:string 3756 3757 3759 3760 3761 Resource 3762 3763 3764 3765 3766 3767 3768 3769 3770 3771 3772 3773 3774 3775 3776 3777 3778 3779 3780 3781 3782 3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3796 3797 3798 3799 3800 kalua:boolean 3801 3802 3804 3805 3806 3807 3808 3809 PhysicalResource 3810 physicalResource 3811 0 3812 unbounded 3813 3814 3815 LogicalResource 3816 logicalResource 3817 0 3818 unbounded 3819 3820 3822 5.18.8. NETCONF Payload Examples 3824 3825 . 3826 3827 . 3828 . 3829 NW-Card-11783 3830 C12 3831 . 3832 . 3833 N-737362183-34 3834 . 3835 . 3836 3837 3838 TP-83838 3839 3840 3841 3842 TP-83845 3843 3844 3846 3848 3850 3851 . 3852 . 3853 TP-83838 3854 IP-TP-3 3855 . 3856 . 3857 true 3858 . 3859 . 3860 3861 3862 NW-Card-11783 3863 3864 3866 3868 3869 . 3870 . 3871 TP-83845 3872 IP-TP-10 3873 . 3874 . 3875 false 3876 . 3877 . 3878 3879 3880 3881 NW-Card-11783 3882 3883 3885 3887 5.19. annotation 3889 Kalua supports an "annotation" mechanism to allow extensions to the 3890 model language, "annotation" is a set of additional properties 3891 associated with a model element. There can be several "annotations" 3892 associated with the same model element. 3894 "Annotations" are 'typed', that is, each "annotation" must 3895 instantiate a particular annotation type also defined in the module 3896 or in a directly or indirectly imported module. The annotation type 3897 specifies which entries can be or must be present in an "annotation". 3898 The annotation type also implies semantics of the annotation data; 3899 however, semantics are not modeled and are conveyed in the 3900 description within the annotation-type definition only. 3902 An annotation type is defined with an annotation-type element. 3903 Reader of the module must not treat unrecognized annotation types as 3904 errors. 3906 A model element is annotated by adding an annotation sub-element to 3907 the element definition. This element contains any number of 3908 annotation-property elements, which are pairs made up of a name and a 3909 value. The order of annotation-property elements has no semantic 3910 value. 3912 The name and values in the annotation-property elements must match a 3913 corresponding element specification contained in the annotation- 3914 property elements of the referred annotation-type element. 3916 5.19.1. Element Attributes 3918 +-----------+------------+--------------------------------------+---+ 3919 | Attribute | Type | Description | S | 3920 | | [Default] | | | 3921 +-----------+------------+--------------------------------------+---+ 3922 | name | xsd:string | Defines type of the annotation. | M | 3923 +-----------+------------+--------------------------------------+---+ 3925 5.19.2. Sub-Elements 3927 +-------------+-----------+-----------+-----------------------------+ 3928 | Sub-Element | MinOccurs | MaxOccurs | Description | 3929 +-------------+-----------+-----------+-----------------------------+ 3930 | e: | 0 | unbounded | Defines values for the | 3931 | annotation- | | | properties of the | 3932 | property | | | annotation. | 3933 +-------------+-----------+-----------+-----------------------------+ 3935 5.19.3. Constraints 3937 The annotation-type element, which is available in the module and 3938 which has the same value for attribute name as the annotation element 3939 has, must be applicable to the model element type which contains the 3940 "annotation". 3942 5.19.4. XSD 3944 3945 3946 3950 3951 3952 3954 5.19.5. Element Examples 3956 3957 objectStorage 3958 true 3959 true 3960 3962 5.20. annotation-property 3964 "annotation-property" element defines value of a property within an 3965 annotation. Semantics of the "annotation-property" values depend on 3966 the annotation-type element referred to by the annotation element 3967 containing the "annotation-property". 3969 5.20.1. Element Attributes 3971 +-----------+------------+--------------------------------------+---+ 3972 | Attribute | Type | Description | S | 3973 | | [Default] | | | 3974 +-----------+------------+--------------------------------------+---+ 3975 | name | xsd:string | A name of the annotation property. | M | 3976 | | | The name must match with id | | 3977 | | | attribute of one of the Annotation | | 3978 | | | Entry Type elements within | | 3979 | | | Annotation Type element to which the | | 3980 | | | containing Annotation refers to. | | 3981 +-----------+------------+--------------------------------------+---+ 3983 Table 1: Annotation-property element attributes 3985 5.20.2. Constraints 3987 No two "annotation-property" elements within one annotation element 3988 may have the same value for attribute name. 3990 For each "annotation-property" element, there must be an annotation- 3991 property-type element in the referred annotation-type element. 3993 Content of the "annotation-property" element must match with the 3994 pattern of the corresponding annotation-property-type element. 3996 All annotation properties which are defined for the annotation-type 3997 of the annotation must be present in the annotation, or must be 3998 defined as optional in the annotation- type. 4000 5.20.3. XSD 4002 4003 4004 4005 4006 4007 4008 4010 5.20.4. Element Examples 4012 true 4014 5.21. annotation-type 4016 A module can define "annotation types" for use in that module, or 4017 other modules that import the module. "annotation-types" define the 4018 structure of additional information that can be added to the Kalua 4019 model elements. Each "annotation-type" applies to a selected subset 4020 of model elements. 4022 5.21.1. Element Attributes 4024 +-----------+-------------+-------------------------------------+---+ 4025 | Attribute | Type | Description | S | 4026 | | [Default] | | | 4027 +-----------+-------------+-------------------------------------+---+ 4028 | Name | xsd:string | Identifies the annotation type. | M | 4029 | | | | | 4030 | multiple | xsd:boolean | If true, multiple instances of the | O | 4031 | | [true] | annotation type can be attached to | | 4032 | | | a model element. If false, only | | 4033 | | | one instance with this annotation | | 4034 | | | type can be attached to a model | | 4035 | | | element. | | 4036 +-----------+-------------+-------------------------------------+---+ 4038 5.21.2. Leaf Sub-Elements 4040 +--------------+------------+-----------------------------------+---+ 4041 | Sub-Element | Type | Description | S | 4042 | | [Default] | | | 4043 +--------------+------------+-----------------------------------+---+ 4044 | presentation | xsd:string | See Section 5.1.2 | O | 4045 | | | | | 4046 | description | xsd:string | See Section 5.1.3 | O | 4047 +--------------+------------+-----------------------------------+---+ 4049 5.21.3. Sub-Elements 4051 +----------------+-----------+-----------+--------------------------+ 4052 | Sub-Element | MinOccurs | MaxOccurs | Description | 4053 +----------------+-----------+-----------+--------------------------+ 4054 | annotable-type | 1 | unbounded | Defines to which Kalua | 4055 | | | | element types | 4056 | | | | annotations with this | 4057 | | | | type can be added. | 4058 | | | | | 4059 | annotation | 0 | unbounded | See Section 5.19 | 4060 | | | | | 4061 | annotation- | 0 | unbounded | Defines which properties | 4062 | property | | | must or may be present | 4063 | | | | in annotations of this | 4064 | | | | type. | 4065 +----------------+-----------+-----------+--------------------------+ 4067 5.21.4. XSD 4069 4070 4071 4072 4076 4080 4081 4082 4083 4085 5.21.5. Element Examples 4087 4088 class 4089 4090 true|false 4091 4092 4093 true|false 4094 4095 4097 5.22. annotable-type 4099 "annotable-type" defines that an annotation, of the type, which 4100 contains this element, can be attached to the model elements of the 4101 given type. The content of this element is the name of the model 4102 element type. 4104 5.22.1. XSD 4106 4107 4108 4109 4110 4111 4112 4113 4114 4115 4116 4117 4118 4119 4120 4121 4122 4123 4124 4125 4126 4128 5.22.2. Element Examples 4130 class 4132 5.23. annotation-property-type 4134 "annotation-property-type" defines a property within the annotation- 4135 type element. It defines the allowed values for the property and 4136 whether property is optional. 4138 5.23.1. Leaf Sub-Elements 4140 +--------------+------------+-----------------------------------+---+ 4141 | Sub-Element | Type | Description | S | 4142 | | [Default] | | | 4143 +--------------+------------+-----------------------------------+---+ 4144 | presentation | xsd:string | See Section 5.1.2 | O | 4145 | | | | | 4146 | description | xsd:string | See Section 5.1.3 | O | 4147 | | | | | 4148 | optional | none | Defines whether a property is | O | 4149 | | | optional or mandatory in the | | 4150 | | | annotation element. If the | | 4151 | | | element is present, the property | | 4152 | | | is optional. If the element is | | 4153 | | | not present, the property is | | 4154 | | | mandatory. | | 4155 | | | | | 4156 | pattern | xsd:string | Language of the allowed values | O | 4157 | | [.*] | for the property. The language | | 4158 | | | is defined using a regular | | 4159 | | | expression, according to regular | | 4160 | | | expression syntax and semantics | | 4161 | | | specified in the 'XML Schema Part | | 4162 | | | 2: Datatypes Second Edition' | | 4163 | | | [XSD-TYPES]. | | 4164 +--------------+------------+-----------------------------------+---+ 4166 5.23.2. Sub-Elements 4168 +-------------+-----------+-----------+-----------------------------+ 4169 | Sub-Element | MinOccurs | MaxOccurs | Description | 4170 +-------------+-----------+-----------+-----------------------------+ 4171 | annotation | 0 | unbounded | See Section 5.19 | 4172 +-------------+-----------+-----------+-----------------------------+ 4174 5.23.3. XSD 4176 4177 4178 4179 4180 4181 4182 4183 4185 5.23.4. Element Examples 4187 4188 true|false 4189 4191 4192 4193 true|false 4194 4196 4197 4199 6. IANA Considerations 4201 A registry for standard Kalua modules needs to be set up. Each entry 4202 shall contain the unique module name, the unique XML namespace from 4203 the Kalua URI Scheme and some reference to the module's 4204 documentation. 4206 The URIs for the Kalua XML namespace will be registered in the IETF 4207 XML registry RFC 3688 [RFC3688]. 4209 7. Security Considerations 4211 Kalua DML itself has no security impact on the Internet. Security 4212 issues might be related to the usage of data, which is modeled with 4213 Kalua. These issues need to be discussed in documents describing the 4214 data models and related interfaces. 4216 8. Acknowledgements 4218 We would like to thank to David Kessens and Leo Hippelainen for their 4219 contributions and review. 4221 9. References 4223 9.1. Normative References 4225 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4226 Requirement Levels", BCP 14, RFC 2119, March 1997. 4228 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 4229 January 2004. 4231 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 4232 December 2006. 4234 [XSD-TYPES] 4235 Biron, P V. and A. Malhotra, "XML Schema Part 2: Datatypes 4236 Second Edition, W3C REC REC-xmlschema-2-20041028", 4237 October 2004, . 4240 9.2. Informative References 4242 [RFC3139] Sanchez, L., McCloghrie, K., and J. Saperia, "Requirements 4243 for Configuration Management of IP-based Networks", 4244 RFC 3139, June 2001. 4246 [RFC3216] Elliott, C., Harrington, D., Jason, J., Schoenwaelder, J., 4247 Strauss, F., and W. Weiss, "SMIng Objectives", RFC 3216, 4248 December 2001. 4250 [Linowski] 4251 Linowski, B., "NETCONF Data Modeling Language 4252 Requirements", February 2008, 4253 . 4255 [RCDML] Presuhn, R., "Requirements for a Configuration Data 4256 Modeling Language", February 2008, 4257 . 4259 [I-D.bjorklund-netconf-yang] 4260 Bjorklund, M., "YANG - A data modeling language for 4261 NETCONF", draft-bjorklund-netconf-yang-02 (work in 4262 progress), February 2008. 4264 Appendix A. Kalua XML Schema 4266 4267 4271 4272 4273 4274 4275 4276 4277 4278 4279 4280 4281 4282 4284 4287 4288 4289 4290 4291 4292 4293 4294 4295 4296 4297 4298 4299 4300 4301 4302 4303 4304 4305 4306 4307 4308 4310 4311 4312 4313 4315 4316 4317 4318 4319 4320 4321 4322 4324 4325 4326 4327 4328 4330 4331 4332 4334 4336 4337 4338 Keys on classes can be globally unique or locally 4339 unique (i.e unique within the scope of their containing 4340 element). 4341 Keys on structures are always locally unique. 4342 Keys on attribute-groups are merged to the set of keys 4343 of the element using them. If a class uses the 4344 attribute-group, the key can be globally unique. 4345 4346 4347 4348 4349 4350 4352 4353 4354 4355 4356 4357 4358 4359 4361 4362 4363 4364 4365 4366 4367 4368 4369 4370 4371 4372 4373 4374 4376 4377 4378 4379 4380 4381 4382 4383 4384 4385 4386 4387 4388 4389 4390 4391 4392 4393 4396 4397 4399 4402 4405 4408 4411 4414 4417 4418 4419 4420 4422 4423 4424 4425 4426 4427 4428 4429 4430 4432 4434 4437 4439 4440 4441 4442 4443 4444 4445 4446 4447 4449 4450 4451 4452 4453 4454 4455 4456 4457 4458 4460 4461 4464 4466 4467 4469 4470 4472 4474 4475 4476 4477 4478 4479 4481 4483 4484 4485 4486 4487 4488 4489 4490 4491 4492 4493 4494 4495 4496 4497 4498 4499 4500 4502 4503 4504 4505 4506 4507 4508 4509 4510 4511 4512 4513 4514 4515 4516 4517 4518 4519 4520 4521 If present it means that this class cannot be 4522 instantiated. 4523 4524 4525 4526 4529 4530 4531 Do we really want a restriction to single 4532 inheritance? 4533 4534 4535 4536 4537 4538 4539 4540 4541 4542 4543 4544 4545 4546 4547 4548 4549 4550 4551 4552 4553 4554 4555 4556 4557 4558 4559 4560 4561 4562 4563 4564 4566 4568 4570 4572 4573 4574 4575 4576 4577 4578 4579 4582 4583 4584 4585 4586 4587 4588 4589 4590 4591 4592 4593 4594 4595 4596 4597 4598 4599 4600 4601 4603 4606 4607 4608 4609 4610 4611 4612 4613 4614 4615 4616 4617 4618 4619 4620 4621 4622 4623 4624 4626 4627 4630 4632 4633 4634 4635 4636 4637 4638 4639 4640 4641 4642 4643 4644 4645 4646 4647 4650 4653 4654 4656 4658 4659 4660 4661 4662 4663 4664 4665 4666 4667 4668 4670 4671 4672 4673 4674 4675 4678 4679 4680 4681 4682 4683 4684 4685 4687 4688 4689 4690 4701 4702 4703 4704 4705 4706 4708 4709 4710 4711 4712 4713 4714 4715 4716 4717 4718 4719 4720 4721 4722 4723 4724 4725 4726 4727 4728 4729 4730 4731 4732 4733 4735 4737 4739 4741 4743 4744 4745 4746 4749 4750 4751 4752 4753 4755 4757 4759 4761 4763 4764 4765 4766 4767 4769 4770 4771 4772 4773 4774 4776 4778 4780 4781 4782 4783 4784 4785 4786 4787 4789 4790 4791 4792 4793 4795 4796 4797 4798 4799 4802 4803 4805 4806 4807 4808 4809 4810 4811 4812 4813 4814 4815 4816 4817 4818 4819 4820 4821 4822 4824 4825 4826 4827 4829 Appendix B. Module Example: RFC1213-MIB 4831 The example below shows how the contents of the MIB RFC1213-MIB is 4832 represented in Kalua. 4834 4835 4841 4842 RFC1213-MIB 4843 Extracted from rfc1213.txt 4844 iso.org.dod.internet.mgmt.mib-2.rfc1213 4845 4847 rfc1213 4848 1 4849 RFC 4850 4851 iso.org.dod.internet.mgmt.mib-2.rfc1155-smi 4852 rfc1155-smi 4853 1 4854 Structure of Management Information 4855 4856 4857 4858 iso.org.dod.internet.mgmt.mib-2.rfc1212 4859 rfc1212 4860 1 4861 Object type definition macros 4862 4863 4864 This data type is used to model textual 4865 information taken from the NVT ASCII character set. 4866 By convention, objects with this syntax are declared 4867 as having SIZE (0..255) 4868 kalua:string 4869 4870 4871 This data type is used to model media 4872 addresses. For many types of media, this will be in 4873 a binary representation. For example, an ethernet 4874 address would be represented as a string of 6 octets. 4875 4876 kalua:string 4878 4879 4880 System group 4881 4882 Implementation of the System group is mandatory 4883 for all systems. If an agent is not configured to have a 4884 value for any of these variables, a string of length 0 is 4885 returned. 4886 4887 4888 A textual description of the entity. 4889 This value should include the full name and version 4890 identification of the system's hardware type, 4891 software operating-system, and networking 4892 software. It is mandatory that this only contain 4893 printable ASCII characters. 4894 4895 4896 4897 DisplayString 4898 4906 4907 4908 4909 4910 4911 4912 4913 The vendor's authoritative identification 4914 of the network management subsystem contained in the 4915 entity. This value is allocated within the SMI 4916 enterprises subtree (1.3.6.1.4.1) and provides an 4917 easy and unambiguous means for determining `what 4918 kind of box' is being managed. For example, if 4919 vendor `Flintstones, Inc.' was assigned the 4920 subtree 1.3.6.1.4.1.4242, it could assign the 4921 identifier 1.3.6.1.4.1.4242.1.1 to its `Fred 4922 Router'. 4923 4924 4925 kalua:string 4927 4928 4929 4930 4931 The time (in hundredths of a second) since the 4932 network management portion of the system was last 4933 re-initialized. 4934 4935 4936 rfc1155-smi:TimeTicks 4937 4938 4939 4940 The textual identification of the contact person 4941 for this managed node, together with information 4942 on how to contact this person. 4943 4944 4945 4946 DisplayString 4947 4948 4949 4950 4951 4952 4953 4954 An administratively-assigned name for this 4955 managed node. By convention, this is the node's 4956 fully-qualified domain name. 4957 4958 4959 4960 DisplayString 4961 4962 4963 4964 4965 4966 4967 4968 The physical location of this node (e.g., 4969 'telephone closet, 3rd floor'). 4970 4971 4972 4973 DisplayString 4974 4975 4976 4977 4978 4979 4980 4981 A value which indicates the set of services that 4982 this entity primarily offers. 4984 The value is a sum. This sum initially takes the 4985 value zero, Then, for each layer, L, in the range 4986 1 through 7, that this node performs transactions 4987 for, 2 raised to (L - 1) is added to the sum. For 4988 example, a node which performs primarily routing 4989 functions would have a value of 4 (2^(3-1)). In 4990 contrast, a node which is a host offering 4991 application services would have a value of 72 4992 (2^(4-1) + 2^(7-1)). Note that in the context of 4993 the Internet suite of protocols, values should be 4994 calculated accordingly: 4996 layer 1 physical (e.g., repeaters) 4997 layer 2 datalink/subnetwork (e.g., bridges) 4998 layer 3 internet (e.g., IP gateways) 4999 layer 4 end-to-end (e.g., IP hosts) 5000 layer 7 applications (e.g., mail relays) 5002 For systems including OSI protocols, layers 5 and 5003 6 may also be counted." 5004 5005 5006 5007 5008 kalua:integer 5009 5010 5011 5012 5013 5014 sysName 5015 5016 5017 5018 5019 5020 The number of network interfaces 5021 (regardless of their current state) present on 5022 this system. 5024 5025 5026 kalua:integer 5027 5028 5029 5030 5031 A list of interface entries. The number 5032 of entries is given by the value of ifNumber. 5033 5034 5035 5036 5037 5038 5039 interfaces 5040 parent 5041 1 5042 1 5043 5044 5045 ifEntry 5046 children 5047 0 5048 unbounded 5049 5050 5051 5052 5053 An interface entry containing objects at 5054 the subnetwork layer and below for a particular 5055 interface. 5056 5057 5058 5059 A unique value for each interface. Its value 5060 ranges between 1 and the value of ifNumber. The 5061 value for each interface must remain constant at 5062 least from one re-initialization of the entity's 5063 network management system to the next re- 5064 initialization. 5065 5066 5067 kalua:integer 5068 5069 5070 5071 A textual string containing information about the 5072 interface. This string should include the name of 5073 the manufacturer, the product name and the version 5074 of the hardware interface. 5075 5076 5077 5078 5079 DisplayString 5080 5081 5082 5083 5084 5085 5086 5087 The type of interface, distinguished according to 5088 the physical/link protocol(s) immediately 'below' 5089 the network layer in the protocol stack. 5090 5091 5092 5093 5094 5095 5096 5097 5098 ddn-x25 5099 5100 5101 rfc877-x25 5102 5103 5104 5106 ethernet-csmacd 5107 5108 5109 5111 iso88023-csmacd 5112 5113 5114 5116 iso88024-tokenBus 5117 5118 5119 5121 iso88025-tokenRing 5122 5123 5124 5126 iso88026-man 5127 5128 5129 5130 5132 frame-relay 5133 5134 5135 5136 5137 5138 5139 5140 The size of the largest datagram which can be 5141 sent/received on the interface, specified in 5142 octets. For interfaces that are used for 5143 transmitting network datagrams, this is the size 5144 of the largest network datagram that can be sent 5145 on the interface. 5146 5147 5148 kalua:integer 5149 octets 5150 5151 5152 5153 An estimate of the interface's current bandwidth 5154 in bits per second. For interfaces which do not 5155 vary in bandwidth or for those where no accurate 5156 estimation can be made, this object should contain 5157 the nominal bandwidth. 5158 5159 5160 rfc1155-smi:Gauge 5161 bit/sec 5162 5163 5164 5165 The interface's address at the protocol layer 5166 immediately `below' the network layer in the 5167 protocol stack. For interfaces which do not have 5168 such an address (e.g., a serial line), this object 5169 should contain an octet string of zero length. 5170 5171 5172 PhysAddress 5173 5174 5175 5176 The desired state of the interface. The 5177 testing(3) state indicates that no operational 5178 packets can be passed. 5179 5180 5181 5183 5185 5187 5188 5189 5190 5191 5192 The current operational state of the interface. 5193 The testing(3) state indicates that no operational 5194 packets can be passed. 5195 5196 5197 5198 5200 5202 5204 5205 5206 5207 5208 5211 5212 A reference to MIB definitions specific to the 5213 particular media being used to realize the 5214 interface. For example, if the interface is 5215 realized by an ethernet, then the value of this 5216 object refers to a document defining objects 5217 specific to ethernet. If this information is not 5218 present, its value should be set to the OBJECT 5219 IDENTIFIER { 0 0 }, which is a syntatically valid 5220 object identifier, and any conformant 5221 implementation of ASN.1 and BER must be able to 5222 generate and recognize this value. 5223 5224 5225 kalua:string 5226 5227 5228 ifIndex 5229 5230 5231 5232 5233 the Address Translation group 5234 Implementation of the Address Translation group is 5235 mandatory for all systems. Note however that this group 5236 is deprecated by MIB-II. That is, it is being included 5237 solely for compatibility with MIB-I nodes, and will most 5238 likely be excluded from MIB-III nodes. From MIB-II and 5239 onwards, each network protocol group contains its own 5240 address translation tables. 5242 The Address Translation group contains one table which is 5243 the union across all interfaces of the translation tables 5244 for converting a NetworkAddress (e.g., an IP address) into 5245 a subnetwork-specific address. For lack of a better term, 5246 this document refers to such a subnetwork-specific address 5247 as a `physical' address. 5249 Examples of such translation tables are: for broadcast 5250 media where ARP is in use, the translation table is 5251 equivalent to the ARP cache; or, on an X.25 network where 5252 non-algorithmic translation to X.121 addresses is 5253 required, the translation table contains the 5254 NetworkAddress to X.121 address equivalences. 5255 5256 5257 5258 5259 The Address Translation tables contain the 5260 NetworkAddress to `physical' address equivalences. 5261 Some interfaces do not use translation tables for 5262 determining address equivalences (e.g., DDN-X.25 5263 has an algorithmic method); if all interfaces are 5264 of this type, then the Address Translation table 5265 is empty, i.e., has zero entries. 5266 5267 5268 5269 5270 5271 at 5272 parent 5273 1 5274 1 5275 5276 5277 atEntry 5278 children 5279 0 5280 unbounded 5281 5282 5283 5284 5285 Each entry contains one NetworkAddress to 5286 'physical' address equivalence. 5287 5288 5289 5290 5291 5292 5293 The interface on which this entry's equivalence 5294 is effective. The interface identified by a 5295 particular value of this index is the same 5296 interface as identified by the same value of 5297 ifIndex. 5298 5299 5300 5301 5302 kalua:int 5303 5304 5305 5306 The media-dependent `physical' address. 5307 Setting this object to a null string (one of zero 5308 length) has the effect of invaliding the 5309 corresponding entry in the atTable object. That 5310 is, it effectively dissasociates the interface 5311 identified with said entry from the mapping 5312 identified with said entry. It is an 5313 implementation-specific matter as to whether the 5314 agent removes an invalidated entry from the table. 5315 Accordingly, management stations must be prepared 5316 to receive tabular information from agents that 5317 corresponds to entries not currently in use. 5318 Proper interpretation of such entries requires 5319 examination of the relevant atPhysAddress object. 5320 5321 5322 5323 5324 PhysAddress 5325 5326 5327 5328 The NetworkAddress (e.g., the IP address) 5329 corresponding to the media-dependent `physical' 5330 address. 5331 5332 5333 5334 5335 NetworkAddress 5336 5337 5338 atIfIndex 5339 atNetAddress 5340 5341 5342 5343 5344 5345 $source/atIfIndex= 5346 $target/ifIndex 5347 5348 5349 5350 5351 atEntry 5352 atEntry 5353 0 5354 1 5355 5356 5357 ifEntry 5358 ifEntry 5359 1 5360 1 5361 5362 5363 5364 5365 5366 The indication of whether this entity is acting 5367 as an IP gateway in respect to the forwarding of 5368 datagrams received by, but not addressed to, this 5369 entity. IP gateways forward datagrams. IP hosts 5370 do not (except those source-routed via the host). 5372 Note that for some managed nodes, this object may 5373 take on only a subset of the values possible. 5374 Accordingly, it is appropriate for an agent to 5375 return a 'badValue' response if a management 5376 station attempts to change this object to an 5377 inappropriate value. 5378 5379 5380 5381 5383 acting as a gateway 5384 5385 5386 5388 not-forwarding 5389 5390 5391 NOT acting as a gateway 5392 5393 5394 5395 5396 5397 5398 5399 5400 The table of addressing information relevant to this 5401 entity's IP addresses. 5402 5403 5404 5405 5406 ip 5407 parent 5408 1 5409 1 5410 5411 5412 ipAddrEntry 5413 children 5414 0 5415 unbounded 5416 5417 5418 5419 5420 5421 The IP address to which this entry's 5422 addressing information pertains. 5423 5424 5425 rfc1155-smi:IpAddress 5426 5427 5428 5429 The index value which uniquely identifies the 5430 interface to which this entry is applicable. The 5431 interface identified by a particular value of this 5432 index is the same interface as identified by the 5433 same value of ifIndex. 5434 5435 5436 kalua:integer 5437 5438 5439 ipAdEntAddr 5440 5441 5442 5443 5444 5445 $source/ipAdEntIfIndex= 5446 $target/ifIndex 5447 5448 5449 5450 5451 ipAddrEntry 5452 ipAddress 5453 0 5454 1 5455 5456 5457 ifEntry 5458 interface 5459 1 5460 1 5461 5462 5463 5464 5465 5466 5467 5468 5469 5470 5471 5472 5473 annotation-property-type 5474 5475 annotation-type 5476 attribute 5477 attribute-group 5478 class 5479 constraint 5480 enum 5481 enum-literal 5482 import 5483 key 5484 member 5485 module 5486 relationship 5487 sequence 5488 structure 5489 typedef 5490 use 5491 5493 5494 5495 A linkDown trap signifies that the SNMP entity, acting in 5496 an agent role, has detected that the ifOperStatus object for 5497 one of its communication links is about to enter the down 5498 state from some other state (but not from the notPresent 5499 state). This other state is indicated by the included value 5500 of ifOperStatus. 5501 5502 accessible-for-notify 5503 5504 kalua:int 5505 5506 5507 5508 5509 kalua:int 5510 5511 5512 5513 The desired state of the interface. The testing(3) state 5514 indicates that no operational packets can be passed. When a 5515 managed system initializes, all interfaces start with 5516 ifAdminStatus in the down(2) state. As a result of either 5517 explicit management action or per configuration information 5518 retained by the managed system, ifAdminStatus is then 5519 changed to either the up(1) or testing(3) states (or remains 5520 in the down(2) state). 5521 5522 5523 5525 5527 5529 5530 5531 5532 5533 5534 5535 5536 5537 kalua:int 5538 5539 5540 5541 The current operational state of the interface. The 5542 testing(3) state indicates that no operational packets can 5543 be passed. If ifAdminStatus is down(2) then ifOperStatus 5544 should be down(2). If ifAdminStatus is changed to up(1) 5545 then ifOperStatus should change to up(1) if the interface is 5546 ready to transmit and receive network traffic; it should 5547 change to dormant(5) if the interface is waiting for 5548 external actions (such as a serial line waiting for an 5549 incoming connection); it should remain in the down(2) state 5550 if and only if there is a fault that prevents it from going 5551 to the up(1) state; it should remain in the notPresent(6) 5552 state if the interface has missing (typically, hardware) 5553 components. 5554 5555 5556 5557 5558 5559 5560 5561 5562 5563 5564 5565 5566 5567 5568 5569 5570 5572 Appendix C. Netconf Payload Example 5574 The XML example below shows a Netconf payload that is in line with 5575 the Kalua module shown in the previous sections: 5577 5578 5582 5584 5585 5586 IP Router 5587 8.0.1.2.3.5.63.22.3.4 5588 646467347 5589 Bob's phone: (352) 465 3746 available 24/7 5590 5591 Bob's router 5592 Bob's garage 5593 6 5594 5595 5596 1 5597 5599 1 5600 Flintstone Inc Ethernet A562 5601 10 5602 5604 1500 5605 10000000 5606 0:12:3f:7d:b5:8b 5607 1 5608 1 5609 5610 5611 5612 5613 1 5614 0:23:be:8e:00:6a 5615 192.168.2.1 5616 5617 5618 5619 1 5620 5621 1 5622 10.34.120.3 5623 5624 5625 1 5626 10.22.255.255 5627 5628 5629 5630 5631 5632 5633 5635 Appendix D. NETCONF Notification Example 5637 The XML example below shows a NETCONF notification for the Kalua 5638 module rfc1213-mib.xml: 5640 5641 5644 5646 5648 5650 2007-07-08T00:01:00Z 5651 5652 1 5653 5654 1 5655 1 5656 5657 5658 2 5659 1 5660 5661 5662 5663 5664 5666 Appendix E. DHCP example from RCDML Requirements Document 5668 The following XML example demonstrates the Kalua variant of the DHCP 5669 example in RCDML Requirements Document [RCDML]. 5671 5675 DHCP 5676 5677 DHCP example, as in draft-presuhn-rcdml-03#appendix-C 5678 5679 http://example.org/ns/dhcp 5680 dhcp 5681 1 5682 Nokia Siemens Networks 5683 5684 urn:ietf:params:xml:ns:netmod:base 5685 ndl 5686 5687 5688 http://example.com/ns/int 5689 int 5690 interfaces 5691 5692 5693 5694 default-lease-time 5695 kalua:int 5696 5697 5698 max-lease-time 5699 kalua:int 5700 5701 5702 5703 5704 5705 5706 5707 dhcp 5708 parent 5709 5710 5711 subnet 5712 children 5713 5715 5716 5717 5718 ndl:ipAddress 5719 5720 5721 prefix-length 5722 kalua:int 5723 5724 5725 5726 rangeType 5727 5728 5729 max-lease-time 5730 kalua:int 5731 5732 5733 5734 5735 5736 5737 ip-address 5738 ndl:ipAddress 5739 5740 5741 kalua:dateTime 5742 5743 5744 kalua:dateTime 5745 5746 5747 mac-address 5748 ndl:nsapAddress 5749 5750 5751 ip_address 5752 5753 5754 5755 5756 5757 5758 kalua:string 5759 5760 5761 5762 network 5763 prefix_length 5764 5765 5766 5767 5768 5769 dynamic-bootp 5770 kalua:boolean 5771 true 5772 5773 5774 5775 ndl:ipAddress 5776 5777 5778 5779 ndl:ipAddress 5780 5781 5782 5783 5784 5785 5786 5787 5788 dhcp 5789 dhcp 5790 5791 5792 dhcp_options 5793 dhcp_options 5794 5795 5796 5797 dhcp-options 5798 5799 router-list 5800 5801 ndl:ipAddress 5802 5803 5804 5805 domain-list 5806 5807 ndl:ipAddress 5808 5809 5810 5811 5812 5813 kalua:int 5814 5815 5816 ip-address 5817 ndl:ipAddress 5818 5819 5820 kalua:string 5821 5822 5823 5824 5825 5826 5827 5828 5829 $source/interface_filter/interface=$target/ifName 5830 5831 5832 5833 5834 subnet 5835 filtering_subnet 5836 unbounded 5837 5838 5839 int:interface 5840 filtered_interface 5841 unbounded 5842 5843 5844 5845 5846 kalua:string 5847 5848 5849 name 5850 5851 5852 5853 5854 5855 5856 5857 shared_network 5858 parent 5860 5861 5862 subnet 5863 children 5864 5865 5866 5867 Appendix F. DHCP augmentation example from RCDML Requirements Document 5869 The XML example below shows the Kalua variant of the DHCP 5870 augmentation example in RCDML Requirements Document [RCDML]. 5872 5877 DHCP_augment 5878 DHCP augmentation example, as in 5879 http://tools.ietf.org/html/draft-presuhn-rcdml-03#appendix-C 5880 5881 http://example.org/ns/cal 5882 cal 5883 1 5884 Nokia Siemens Networks 5885 5886 http://example.org/ns/dhcp 5887 dhcp 5888 5889 5890 5891 Inheritance would imply substitution of the element 5892 name as well, which is not the case here. An additional 5893 augmentation mechanism would be needed to truly support 5894 this case. 5895 5896 dhcp:dhcp_options 5897 5898 kalua:string 5899 5900 5901 5902 Appendix G. Example for Partial Lock RPC for NETCONF 5904 The XML example below shows a Kalua example for Partial Lock RPC for 5905 NETCONF. 5907 5911 NETCONF partial lock 5912 NETCONF partial lock operations 5913 urn:ietf:params:xml:ns:netconf:partial-lock:1.0 5914 ncpl 5915 1 5916 IETF 5917 5918 urn:ietf:params:xml:ns:netconf:base:1.0 5919 nc 5920 5921 5922 5923 kalua:unsignedInt 5924 5925 5926 5927 5928 This operation defines the element for partial-lock RPC 5929 operation. Positive response to this operation is the 5930 "lock-id" element. 5931 5932 5933 5934 nc:config_name 5935 5936 5937 5938 kalua:string 5939 5940 5941 5942 5943 5944 sadasd 5945 5946 5947 5948 5949 5950 This operation defines the element for partial-unlock RPC 5951 operation. The standard positive response 5952 (rpc-reply with <nc:ok/>) is sent if the operation 5953 succeeds. 5954 5955 5956 5957 sadasd 5958 5959 5960 5961 5962 Appendix H. Support of RCDML Requirements in Kalua 5964 Following table shows the support of RCDML Requirements in Kalua. 5966 +--------------------------------------+-----------+----------------+ 5967 | RCDML Requirements | Kalua | Comments | 5968 | | support | | 5969 +--------------------------------------+-----------+----------------+ 5970 | 1. Consequences of NETCONF | | | 5971 | | | | 5972 | 1.1. Notification Definition | Yes | | 5973 | (Agreed) | | | 5974 | | | | 5975 | 1.2. Notification Get (NOT Agreed) | Yes (*) | Reuse of | 5976 | | | config | 5977 | | | definitions | 5978 | | | possible, not | 5979 | | | mandatory | 5980 | | | | 5981 | 1.3. Locking (Agreed) | Yes | | 5982 | | | | 5983 | 1.4. All Base Operations (Agreed) | Yes | | 5984 | | | | 5985 | 1.5. Define new NETCONF Operations | Yes (wo) | | 5986 | (Agreed) | | | 5987 | | | | 5988 | 1.6. Separation of Operations and | Yes | | 5989 | Payload (Agreed) | | | 5990 | | | | 5991 | 1.7. Error Annotation (Agreed) | Yes (wo) | In parallel to | 5992 | | | Req. # 1.5 | 5993 | | | | 5994 | 1.8. No Mixed Content (Agreed) | Yes | | 5995 | | | | 5996 | 2. Model Representation | | | 5997 | Requirements | | | 5998 | | | | 5999 | 2.1. Human Readable (Agreed) | Yes | | 6000 | | | | 6001 | 2.2. Machine Readable (Agreed) | Yes | | 6002 | | | | 6003 | 2.3. Textual Representation | Yes | | 6004 | (Agreed) | | | 6005 | | | | 6006 | 2.4. Document Information (Agreed) | Yes | | 6007 | | | | 6008 | 2.5. Ownership and Change Control | Yes | | 6009 | (Agreed) | | | 6010 | 2.6. Dependency Risk Reduction | Yes | | 6011 | (Agreed) | | | 6012 | | | | 6013 | 2.7. Diff-Friendly (Agreed) | Yes | | 6014 | | | | 6015 | 2.8. Internationalization and | Yes | | 6016 | Localization | | | 6017 | | | | 6018 | 2.8.1. Descriptions using Local | Yes | | 6019 | Languages (Agreed) | | | 6020 | | | | 6021 | 2.8.2. UTF-8 Encoding (Agreed) | Yes | | 6022 | | | | 6023 | 2.8.3. Localization Support | Yes | | 6024 | (Agreed) | | | 6025 | | | | 6026 | 2.8.4. Error String Localization | Yes | | 6027 | (Agreed) | | | 6028 | | | | 6029 | 2.8.5. Tag Names and Strings in | No | | 6030 | Local Languages (NOT agreed) | | | 6031 | | | | 6032 | 3. Reusability Requirements | | | 6033 | | | | 6034 | 3.1. Modularity (Agreed) | Yes | | 6035 | | | | 6036 | 3.2. Reusable Definitions (Agreed) | Yes | | 6037 | | | | 6038 | 3.3. Modular extension (Agreed) | Yes | | 6039 | | | | 6040 | 4. Instance Data Requirements | | | 6041 | | | | 6042 | 4.1. Default Values on the Wire | Yes (wo) | | 6043 | (Agreed) | | | 6044 | | | | 6045 | 4.2. Ordering | | | 6046 | | | | 6047 | 4.2.1. Ordered Lists (Agreed) | Yes | | 6048 | | | | 6049 | 4.2.2. Order within Containers (NOT | No | Not for | 6050 | Agreed) | | containment | 6051 | | | relationships. | 6052 | | | | 6053 | 4.2.3. Interleaving (NOT Agreed) | Yes (*) | Order of | 6054 | | | contained | 6055 | | | elements is | 6056 | | | not defined | 6057 | | | | 6058 | 4.3. Validation | | | 6059 | | | | 6060 | 4.3.1. Validate Instance Data | Yes | No explicit | 6061 | (Agreed) | | definition of | 6062 | | | valid and | 6063 | | | well-formed | 6064 | | | | 6065 | 4.3.2. Tools to Validate Instance | No | | 6066 | Data (NOT Agreed) | | | 6067 | | | | 6068 | 4.4. Instance Canonicalization | Yes (wo) | | 6069 | (Agreed) | | | 6070 | | | | 6071 | 4.5. Character Set and Encoding | Yes | | 6072 | (Agreed) | | | 6073 | | | | 6074 | 4.6. Model Instance Localization | Yes (*) | | 6075 | (NOT Agreed) | | | 6076 | | | | 6077 | 5. Semantic Richness Requirements | | | 6078 | | | | 6079 | 5.1. Human-Readable Semantics | Yes | | 6080 | (Agreed) | | | 6081 | | | | 6082 | 5.2. Basic Types (Agreed) | Yes | | 6083 | | | | 6084 | 5.3. Handling Opaque Data (Agreed) | Yes (wo) | kalua:any type | 6085 | | | can be added | 6086 | | | easilly | 6087 | | | | 6088 | 5.4. Keys | | | 6089 | | | | 6090 | 5.4.1. Define Keys (Agreed) | Yes | | 6091 | | | | 6092 | 5.4.2. Deep Keys (NOT Agreed) | Yes | | 6093 | | | | 6094 | 5.5. Relationships | | | 6095 | | | | 6096 | 5.5.1. Simple Relationships | Yes | | 6097 | (Agreed) | | | 6098 | | | | 6099 | 5.5.2. Many-to-Many Relationships | Yes (*) | | 6100 | (NOT Agreed) | | | 6101 | | | | 6102 | 5.5.3. Retrieve Relationships | Yes (*) | | 6103 | instance (NOT Agreed) | | | 6104 | | | | 6105 | 5.5.4. Retrieve Relationships - | Yes (*) | | 6106 | qualified (NOT Agreed) | | | 6107 | | | | 6108 | 5.6. Hierarchical Data | Yes | | 6109 | | | | 6110 | 5.7. Referential Integrity | | | 6111 | | | | 6112 | 5.7.1. Referential Integrity (NOT | Yes (wo) | Calculated | 6113 | Agreed) | (*) | relationships | 6114 | | | do not imply | 6115 | | | referential | 6116 | | | integrity. | 6117 | | | Reference | 6118 | | | relationships | 6119 | | | only cover the | 6120 | | | key attributes | 6121 | | | | 6122 | 5.7.2. Extended Referential | No | Not really | 6123 | Integrity (NOT Agreed) | | clear what | 6124 | | | this is ... | 6125 | | | | 6126 | 5.7.3. Referential Integrity | Yes (*) | | 6127 | Robustness (NOT Agreed) | | | 6128 | | | | 6129 | 5.8. Characterize Data (Agreed) | Yes | | 6130 | | | | 6131 | 5.9. Defaults | | | 6132 | | | | 6133 | 5.9.1. Default Values (NOT Agreed) | Yes (*) | | 6134 | | | | 6135 | 5.9.2. Dynamic Defaults (NOT | No | | 6136 | Agreed) | | | 6137 | | | | 6138 | 5.10. Formal Constraints | | | 6139 | | | | 6140 | 5.10.1. Formal Description of | Yes | | 6141 | Constraints (Agreed) | | | 6142 | | | | 6143 | 5.10.2. Multi-element Constraints | No | | 6144 | (NOT Agreed) | | | 6145 | | | | 6146 | 5.10.3. Non-Key Uniqueness (Agreed) | Yes | | 6147 | | | | 6148 | 5.11. Units (Agreed) | Yes | | 6149 | | | | 6150 | 5.12. Define Actions (NOT Agreed) | No | | 6151 | | | | 6152 | 6. Extensibility Requirements | | | 6153 | 6.1. Language Extensibility | Yes | | 6154 | | | | 6155 | 6.1.1. Language Versioning (Agreed) | Yes | | 6156 | | | | 6157 | 6.1.2. User Extensions (NOT Agreed) | Yes (*) | | 6158 | | | | 6159 | 6.1.3. Mandatory Extensions (NOT | No | | 6160 | Agreed) | | | 6161 | | | | 6162 | 6.2. Model Extensibility | | | 6163 | | | | 6164 | 6.2.1. Model Version Identification | Yes | | 6165 | (Agreed) | | | 6166 | | | | 6167 | 6.2.2. Interaction with defaults | No | | 6168 | (NOT Agreed) | | | 6169 | | | | 6170 | 6.2.3. Conformance Interference | Yes (wo) | | 6171 | (NOT Agreed) | (*) | | 6172 | | | | 6173 | 6.2.4. Obsolete Portions of a Model | Yes | Solution | 6174 | (Agreed) | | assumes that | 6175 | | | the manager | 6176 | | | will select | 6177 | | | the correct | 6178 | | | version of a | 6179 | | | module | 6180 | | | (matching the | 6181 | | | agent) | 6182 | | | | 6183 | 6.3. Instance Data Extensibility | | | 6184 | | | | 6185 | 6.3.1. Schema Version of Instance | Yes (wo) | | 6186 | (NOT Agreed) | (*) | | 6187 | | | | 6188 | 6.3.2. Interaction with default | No | | 6189 | Values (NOT Agreed) | | | 6190 | | | | 6191 | 6.3.3. Backwards Compatibility | Partially | Additional | 6192 | (Agreed) | | inheritance | 6193 | | | may lead to | 6194 | | | element names | 6195 | | | not understood | 6196 | | | by old | 6197 | | | clients. | 6198 | | | | 6199 | 6.3.4. Forwards Compatibility (NOT | No | Unclear about | 6200 | Agreed) | | implications | 6201 | | | of this | 6202 | | | requirement | 6203 | | | | 6204 | 7. Talking About Conformance | | | 6205 | | | | 6206 | 7.1. Conformance to the Modeling | Yes (*) | | 6207 | Language (NOT Agreed) | | | 6208 | | | | 6209 | 7.2. Conformance to a Model | Yes | | 6210 | (Agreed) | | | 6211 | | | | 6212 | 8. Techno-Political Constraints | | | 6213 | | | | 6214 | 8.1. Standard Technology (NOT | Yes (*) | | 6215 | Agreed) | | | 6216 | | | | 6217 | 8.2. Translate Models to Other | Yes | | 6218 | Forms (Agreed) | | | 6219 | | | | 6220 | 8.3. Minimize SMI Translation Pain | No | | 6221 | (NOT Agreed) | | | 6222 | | | | 6223 | 8.4. Generate Models from Other | Yes (*) | | 6224 | Forms (NOT Agreed) | | | 6225 | | | | 6226 | 8.5. Isolate Models from Protocol | Yes (*) | | 6227 | (NOT Agreed) | | | 6228 | | | | 6229 | 8.6. Library Support (NOT Agreed) | Yes (*) | | 6230 | | | | 6231 | 8.7. RFC 3139 Considerations | Yes | | 6232 | | | | 6233 | 8.8. RFC 3216 Considerations | Yes | | 6234 +--------------------------------------+-----------+----------------+ 6236 Table 2: Support of RCDML Requirements in Kalua 6238 (wo): work ongoing 6240 (*): Not agreed RCDML requirement supported by Kalua 6242 Appendix I. Support of Use Cases for SMI and MIB Modules 6244 Following table shows the support of Use cases for SMI and MIB 6245 modules in Kalua. 6247 +----+--------------------------------------------------+-----------+ 6248 | # | Use cases for SMI and MIB modules | Supported | 6249 | | | by Kalua | 6250 +----+--------------------------------------------------+-----------+ 6251 | 1 | Agreement on a set of standard knobs (or | Yes | 6252 | | proprietary knobs in a proprietary MIB module). | | 6253 | | These knobs can be defined in a clear and | | 6254 | | unambiguous manner including the restrictions | | 6255 | | that apply to the knobs, such as range, | | 6256 | | character set, what gets counted in a counter, | | 6257 | | and so on. Ideally, Netconf knobs would support | | 6258 | | all the types of management object properties | | 6259 | | already supported by MIB modules, unless it can | | 6260 | | be shown that such properties do not apply to | | 6261 | | configuration. | | 6262 | | | | 6263 | 2 | clear specification in the schema of what | Yes (*) | 6264 | | MUST/SHOULD/MAY/MUST NOT/SHOULD NOT be supported | | 6265 | | to claim compliance to the standard, to support | | 6266 | | vendor-neutral interoperability | | 6267 | | | | 6268 | 3 | modular documents that can be formally validated | Yes | 6269 | | using tools such as smilint | | 6270 | | | | 6271 | 4 | enough information for implementers to | Yes | 6272 | | implement, with internal engineering choices | | 6273 | | being implementer-dependent, but with | | 6274 | | vendor-neutral formats on-the-wire | | 6275 | | | | 6276 | 5 | enough human-readable description/qualities that | Yes | 6277 | | operators can read the raw schema to understand | | 6278 | | the meaning of a managed object | | 6279 | | | | 6280 | 6 | enough machine-readability that applications can | Yes | 6281 | | effectively parse (and compare/contrast/utilize) | | 6282 | | the information across multiple vendor | | 6283 | | implementations, and across multiple vendor | | 6284 | | implementation releases. | | 6285 | | | | 6286 | 7 | the document can be used by network management | Yes | 6287 | | applications to programmatically create | | 6288 | | corresponding databases of information (i.e. an | | 6289 | | NMS can IMPORT a MIB module to create | | 6290 | | corresponding record formats in a database) | | 6291 | | | | 6292 | 8 | each managed object is clearly | Yes | 6293 | | instance-addressable such that a sender can | | 6294 | | label the object instance being sent in a | | 6295 | | message | | 6296 | | | | 6297 | 9 | the receiver of a message can clearly identify | Yes | 6298 | | the instance of any object contained in a | | 6299 | | message, and can validate the data types and | | 6300 | | values (such as range, character set, etc.) of | | 6301 | | objects being passed in a message | | 6302 | | | | 6303 | 10 | a protocol-dependent message MAY contain a very | Yes | 6304 | | small subset of the managed objects defined in a | | 6305 | | schema (e.g., one object from a schema) and | | 6306 | | still meet the previous requirements | | 6307 | | | | 6308 | 11 | a protocol-dependent message MAY contain a | Yes | 6309 | | mixture of managed objects defined in different | | 6310 | | modules/schemas, and still meet the previous | | 6311 | | requirements | | 6312 +----+--------------------------------------------------+-----------+ 6314 Table 3: Support of Use cases for SMI and MIB modules in Kalua 6316 (*): Kalua does not define optional elements. 6318 Authors' Addresses 6320 Bernd Linowski 6321 Nokia Siemens Networks 6322 Heltorfer Strasse 1 6323 40472 Duesseldorf 6324 Germany 6326 Email: bernd.linowski@nsn.com 6328 Martin Storch 6329 Nokia Siemens Networks 6330 Heltorfer Strasse 1 6331 40472 Duesseldorf 6332 Germany 6334 Email: martin.storch@nsn.com 6336 Mikko Lahdensivu 6337 Nokia Siemens Networks 6338 Hatanpaeaen valtatie 30 6339 33100 Tampere 6340 Finland 6342 Email: mikko.lahdensivu@nsn.com 6344 Mehmet Ersue 6345 Nokia Siemens Networks 6346 St.-Martin-Strasse 76 6347 81541 Munich 6348 Germany 6350 Email: mehmet.ersue@nsn.com 6352 Full Copyright Statement 6354 Copyright (C) The IETF Trust (2008). 6356 This document is subject to the rights, licenses and restrictions 6357 contained in BCP 78, and except as set forth therein, the authors 6358 retain all their rights. 6360 This document and the information contained herein are provided on an 6361 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 6362 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 6363 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 6364 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 6365 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 6366 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 6368 Intellectual Property 6370 The IETF takes no position regarding the validity or scope of any 6371 Intellectual Property Rights or other rights that might be claimed to 6372 pertain to the implementation or use of the technology described in 6373 this document or the extent to which any license under such rights 6374 might or might not be available; nor does it represent that it has 6375 made any independent effort to identify any such rights. Information 6376 on the procedures with respect to rights in RFC documents can be 6377 found in BCP 78 and BCP 79. 6379 Copies of IPR disclosures made to the IETF Secretariat and any 6380 assurances of licenses to be made available, or the result of an 6381 attempt made to obtain a general license or permission for the use of 6382 such proprietary rights by implementers or users of this 6383 specification can be obtained from the IETF on-line IPR repository at 6384 http://www.ietf.org/ipr. 6386 The IETF invites any interested party to bring to its attention any 6387 copyrights, patents or patent applications, or other proprietary 6388 rights that may cover technology that may be required to implement 6389 this standard. Please address the information to the IETF at 6390 ietf-ipr@ietf.org.