Internet Engineering Task Force (IETF) Category: Experimental. S. Kuryla 360 Treasury Systems March 2011

Transcription

1 Internet Engineering Task Force (IETF) Request for Comments: 6095 Category: Experimental ISSN: B. Linowski TCS/Nokia Siemens Networks M. Ersue Nokia Siemens Networks S. Kuryla 360 Treasury Systems March 2011 Extending YANG with Language Abstractions Abstract YANG -- the Network Configuration Protocol (NETCONF) Data Modeling Language -- supports modeling of a tree of data elements that represent the configuration and runtime status of a particular network element managed via NETCONF. This memo suggests enhancing YANG with supplementary modeling features and language abstractions with the aim to improve the model extensibility and reuse. Status of This Memo This document is not an Internet Standards Track specification; it is published for examination, experimental implementation, and evaluation. This document defines an Experimental Protocol for the Internet community. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Not all documents approved by the IESG are a candidate for any level of Internet Standard; see Section 2 of RFC Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at Linowski, et al. Experimental [Page 1]

2 Copyright Notice Copyright (c) 2011 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust s Legal Provisions Relating to IETF Documents ( in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction Key Words Motivation Modeling Improvements with Language Abstractions Design Approach Modeling Resource Models with YANG Example of a Physical Network Resource Model Modeling Entity MIB Entries as Physical Resources Complex Types Definition complex-type Extension Statement instance Extension Statement instance-list Extension Statement extends Extension Statement abstract Extension Statement XML Encoding Rules Type Encoding Rules Extension and Feature Definition Module Example Model for Complex Types NETCONF Payload Example Update Rules for Modules Using Complex Types Using Complex Types Overriding Complex Type Data Nodes Augmenting Complex Types Controlling the Use of Complex Types Typed Instance Identifier Definition instance-type Extension Statement Typed Instance Identifier Example IANA Considerations Security Considerations Linowski, et al. Experimental [Page 2]

3 6. Acknowledgements References Normative References Informative References Appendix A. YANG Modules for Physical Network Resource Model and Hardware Entities Model Appendix B. Example YANG Module for the IPFIX/PSAMP Model B.1. Modeling Improvements for the IPFIX/PSAMP Model with Complex Types and Typed Instance Identifiers B.2. IPFIX/PSAMP Model with Complex Types and Typed Instance Identifiers Introduction YANG -- the NETCONF Data Modeling Language [RFC6020] -- supports modeling of a tree of data elements that represent the configuration and runtime status of a particular network element managed via NETCONF. This document defines extensions for the modeling language YANG as new language statements, which introduce language abstractions to improve the model extensibility and reuse. The document reports from modeling experience in the telecommunication industry and gives model examples from an actual network management system to highlight the value of proposed language extensions, especially class inheritance and recursiveness. The language extensions defined in this document have been implemented with two open source tools. These tools have been used to validate the model examples through the document. If this experimental specification results in successful usage, it is possible that the language extensions defined herein could be updated to incorporate implementation and deployment experience, then pursued on the Standards Track, possibly as part of a future version of YANG Key Words The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14, [RFC2119] Motivation Following are non-exhaustive motivation examples highlighting usage scenarios for language abstractions. o Many systems today have a Management Information Base (MIB) that in effect is organized as a tree build of recursively nested container nodes. For example, the physical resources in the ENTITY-MIB conceptually form a containment tree. The index Linowski, et al. Experimental [Page 3]

4 entphysicalcontainedin points to the containing entity in a flat list. The ability to represent nested, recursive data structures of arbitrary depth would enable the representation of the primary containment hierarchy of physical entities as a node tree in the server MIB and in the NETCONF payload. o A manager scanning the network in order to update the state of an inventory management system might be only interested in data structures that represent a specific type of hardware. Such a manager would then look for entities that are of this specific type, including those that are an extension or specialization of this type. To support this use case, it is helpful to bear the corresponding type information within the data structures, which describe the network element hardware. o A system that is managing network elements is concerned, e.g., with managed objects of type "plug-in modules" that have a name, a version, and an activation state. In this context, it is useful to define the "plug-in module" as a concept that is supposed to be further detailed and extended by additional concrete model elements. In order to realize such a system, it is worthwhile to model abstract entities, which enable reuse and ease concrete refinements of that abstract entity in a second step. o As particular network elements have specific types of components that need to be managed (OS images, plug-in modules, equipment, etc.), it should be possible to define concrete types, which describe the managed object precisely. By using type-safe extensions of basic concepts, a system in the manager role can safely and explicitly determine that e.g., the "equipment" is actually of type "network card". o Currently, different SDOs are working on the harmonization of their management information models. Often, a model mapping or transformation between systems becomes necessary. The harmonization of the models is done e.g., by mapping of the two models on the object level or integrating an object hierarchy into an existing information model. On the one hand, extending YANG with language abstractions can simplify the adoption of IETF resource models by other SDOs and facilitate the alignment with other SDOs resource models (e.g., TM Forum SID [SID_V8]). On the other hand, the proposed YANG extensions can enable the utilization of the YANG modeling language in other SDOs, which usually model complex management systems in a top-down manner and use high-level language features frequently. Linowski, et al. Experimental [Page 4]

5 This memo specifies additional modeling features for the YANG language in the area of structured model abstractions, typed references, as well as recursive data structures, and it discusses how these new features can improve the modeling capabilities of YANG. Section contains a physical resource model that deals with some of the modeling challenges illustrated above. Section gives an example that uses the base classes defined in the physical resource model and derives a model for physical entities defined in the Entity MIB Modeling Improvements with Language Abstractions As an enhancement to YANG 1.0, complex types and typed instance identifiers provide different technical improvements on the modeling level: o In case the model of a system that should be managed with NETCONF makes use of inheritance, complex types enable an almost one-toone mapping between the classes in the original model and the YANG module. o Typed instance identifiers allow representing associations between the concepts in a type-safe way to prevent type errors caused by referring to data nodes of incompatible types. This avoids referring to a particular location in the MIB. Referring to a particular location in the MIB is not mandated by the domain model. o Complex types allow defining complete, self-contained type definitions. It is not necessary to explicitly add a key statement to lists, which use a grouping that defines the data nodes. o Complex types simplify concept refinement by extending a base complex type and make it superfluous to represent concept refinements with workarounds such as huge choice-statements with complex branches. o Abstract complex types ensure correct usage of abstract concepts by enforcing the refinement of a common set of properties before instantiation. o Complex types allow defining recursive structures. This enables representing complex structures of arbitrary depth by nesting instances of basic complex types that may contain themselves. Linowski, et al. Experimental [Page 5]

6 o Complex types avoid introducing metadata types (e.g., type code enumerations) and metadata leafs (e.g., leafs containing a type code) to indicate which concrete type of object is actually represented by a generic container in the MIB. This also avoids explicitly ruling out illegal use of subtype-specific properties in generic containers. o Complex type instances include the type information in the NETCONF payload. This allows determining the actual type of an instance during the NETCONF payload parsing and avoids the use in the model of additional leafs, which provide the type information as content. o Complex types may be declared explicitly as optional features, which is not possible when the actual type of an entity represented by a generic container is indicated with a type code enumeration. Appendix B, "Example YANG Module for the IPFIX/PSAMP Model", lists technical improvements for modeling with complex types and typed instance identifiers and exemplifies the usage of the proposed YANG extensions based on the IP Flow Information Export (IPFIX) / Packet Sampling (PSAMP) configuration model in [IPFIXCONF] Design Approach The proposed additional features for YANG in this memo are designed to reuse existing YANG statements whenever possible. Additional semantics is expressed by an extension that is supposed to be used as a substatement of an existing statement. The proposed features don t change the semantics of models that is valid with respect to the YANG specification [RFC6020] Modeling Resource Models with YANG Example of a Physical Network Resource Model The diagram below depicts a portion of an information model for manageable network resources used in an actual network management system. Note: The referenced model (UDM, Unified Data Model) is based on key resource modeling concepts from [SID_V8] and is compliant with selected parts of SID Resource Abstract Business Entities domain [UDM]. Linowski, et al. Experimental [Page 6]

7 The class diagram in Figure 1 and the corresponding YANG module excerpt focus on basic resource ("Resource" and the distinction between logical and physical resources) and hardware abstractions ("Hardware", "Equipment", and "EquipmentHolder"). Class attributes were omitted to achieve decent readability. Linowski, et al. Experimental [Page 7]

8 Resource /\ /\ LogicalResource Physical Resource < -+- PhysicalLink * physicallink equipment Holder 0..* * hardware Hardware < -+- ManagedHardware < -+- Equipment <> Holder 0..1 <> <> 0..* equipment Holder 0..* equipment equipment 0..* Equipment <> compositeequipment PhysicalConnector * source Physical physicalconnector 0..* Connector * targetphysicalconnector Figure 1: Physical Network Resource Model Linowski, et al. Experimental [Page 8]

9 Since this model is an abstraction of network-element-specific MIB topologies, modeling it with YANG creates some challenges. Some of these challenges and how they can be addressed with complex types are explained below: o Modeling of abstract concepts: Classes like "Resource" represent concepts that primarily serve as a base class for derived classes. With complex types, such an abstract concept could be represented by an abstract complex type (see "complex-type extension statement" and "abstract extension statement"). o Class Inheritance: Information models for complex management domains often use class inheritance to create specialized classes like "PhysicalConnector" from a more generic base class (here, "Hardware"), which itself might inherit from another base class ("PhysicalResource"), etc. Complex types allow creating enhanced versions of an existing (abstract or concrete) base type via an extension (see "extends extension statement"). o Recursive containment: In order to specify containment hierarchies, models frequently contain different aggregation associations, in which the target (contained element) is either the containing class itself or a base class of the containing class. In the model above, the recursive containment of "EquipmentHolder" is an example of such a relationship (see the description for the "complex-type EquipmentHolder" in the example model "udmcore" below). o Complex types support such a containment by using a complex type (or one of its ancestor types) as the type of an instance or instance list that is part of its definition (see "instance(-list) extension statement"). o Reference relationships: A key requirement on large models for network domains with many related managed objects is the ability to define inter-class associations that represent essential relationships between instances of such a class. For example, the relationship between "PhysicalLink" and "Hardware" tells which physical link is connecting which hardware resources. It is important to notice that this kind of relationship does not mandate any particular location of the two connected hardware instances in any MIB module. Such containment-agnostic relationships can be represented by a typed instance identifier that embodies one direction of such an association (see Section 3, "Typed Instance Identifier"). Linowski, et al. Experimental [Page 9]

10 The YANG module excerpt below shows how the challenges listed above can be addressed by the Complex Types extension (module import prefix "ct:"). The complete YANG module for the physical resource model in Figure 1 can be found in Appendix A, "YANG Modules for Physical Network Resource Model and Hardware Entities Model". Note: The YANG extensions proposed in this document have been implemented as the open source tools "Pyang Extension for Complex Types" [Pyang-ct], [Pyang], and "Libsmi Extension for Complex Types" [Libsmi]. All model examples in the document have been validated with the tools Pyang-ct and Libsmi. <CODE BEGINS> module udmcore { namespace " prefix "udm"; import ietf-complex-types {prefix "ct"; // Basic complex types... ct:complex-type PhysicalResource { ct:extends Resource; ct:abstract true; //... leaf serialnumber { type string; description " Manufacturer-allocated part number as defined in SID, e.g., the part number of a fiber link cable."; ct:complex-type Hardware { ct:extends PhysicalResource; ct:abstract true; //... leaf-list physicallink { type instance-identifier {ct:instance-type PhysicalLink; ct:instance-list containedhardware { ct:instance-type Hardware; ct:instance-list physicalconnector { ct:instance-type PhysicalConnector; Linowski, et al. Experimental [Page 10]

11 ct:complex-type PhysicalLink { ct:extends PhysicalResource; //... leaf-list hardware { type instance-identifier {ct:instance-type Hardware; ct:complex-type ManagedHardware { ct:extends Hardware; ct:abstract true; //... ct:complex-type PhysicalConnector { ct:extends Hardware; leaf location {type string; //... leaf-list sourcephysicalconnector { type instance-identifier {ct:instance-type PhysicalConnector; leaf-list targetphysicalconnector { type instance-identifier {ct:instance-type PhysicalConnector; ct:complex-type Equipment { ct:extends ManagedHardware; //... ct:instance-list equipment { ct:instance-type Equipment; ct:complex-type EquipmentHolder { ct:extends ManagedHardware; description "In the SID V8 definition, this is a class based on the M.3100 specification. A base class that represents physical objects that are both manageable as well as able to host, hold, or contain other physical objects. Examples of physical Linowski, et al. Experimental [Page 11]

12 objects that can be represented by instances of this object class are Racks, Chassis, Cards, and Slots. A piece of equipment with the primary purpose of containing other equipment."; leaf vendorname {type string; //... ct:instance-list equipment { ct:instance-type Equipment; ct:instance-list equipmentholder { ct:instance-type EquipmentHolder; //... <CODE ENDS> Modeling Entity MIB Entries as Physical Resources The physical resource module described above can now be used to model physical entities as defined in the Entity MIB [RFC4133]. For each physical entity class listed in the "PhysicalClass" enumeration, a complex type is defined. Each of these complex types extends the most specific complex type already available in the physical resource module. For example, the type "HWModule" extends the complex type "Equipment" as a hardware module. Physical entity properties that should be included in a physical entity complex type are combined in a grouping, which is then used in each complex type definition of an entity. This approach has following benefits: o The definition of the complex types for hardware entities becomes compact as many of the features can be reused from the basic complex type definition. o Physical entities are modeled in a consistent manner as predefined concepts are extended. o Entity-MIB-specific attributes as well as vendor-specific attributes can be added without having to define separate extension data nodes. Linowski, et al. Experimental [Page 12]

13 Module udmcore : Module hardware-entities : equipment : Holder : 0..* : : : : ManagedHardware < -+- Equipment <>--+ : Holder 0..1 : < Chassis : <> : 0..* equipment : Holder : -- Container : * equipment : : equipment : 0..* : : : : - Equipment <>--+ : < HWModule : compositeequipment : : : -- Backplane : Figure 2: Hardware Entities Model Below is an excerpt of the corresponding YANG module using complex types to model hardware entities. The complete YANG module for the Hardware Entities model in Figure 2 can be found in Appendix A, "YANG Modules for Physical Network Resource Model and Hardware Entities Model". Linowski, et al. Experimental [Page 13]

14 <CODE BEGINS> module hardware-entities { namespace " prefix "hwe"; import ietf-yang-types {prefix "yt"; import ietf-complex-types {prefix "ct"; import udmcore {prefix "uc"; grouping PhysicalEntityProperties { //... leaf mfgdate {type yang:date-and-time; leaf-list uris {type string; // Physical entities representing equipment ct:complex-type HWModule { ct:extends uc:equipment; description "Complex type representing module entries (entphysicalclass = module(9)) in entphysicaltable"; uses PhysicalEntityProperties; //... // Physical entities representing equipment holders ct:complex-type Chassis { ct:extends uc:equipmentholder; description "Complex type representing chassis entries (entphysicalclass = chassis(3)) in entphysicaltable"; uses PhysicalEntityProperties; //... <CODE ENDS> Linowski, et al. Experimental [Page 14]

15 2. Complex Types 2.1. Definition YANG type concept is currently restricted to simple types, e.g., restrictions of primitive types, enumerations, or union of simple types. Complex types are types with a rich internal structure, which may be composed of substatements defined in Table 1 (e.g., lists, leafs, containers, choices). A new complex type may extend an existing complex type. This allows providing type-safe extensions to existing YANG models as instances of the new type. Complex types have the following characteristics: o Introduction of new types, as a named, formal description of a concrete manageable resource as well as abstract concepts. o Types can be extended, i.e., new types can be defined by specializing existing types and adding new features. Instances of such an extended type can be used wherever instances of the base type may appear. o The type information is made part of the NETCONF payload in case a derived type substitutes a base type. This enables easy and efficient consumption of payload elements representing complex type instances complex-type Extension Statement The extension statement "complex-type" is introduced; it accepts an arbitrary number of statements that define node trees, among other common YANG statements ("YANG Statements", Section 7 of [RFC6020]). Linowski, et al. Experimental [Page 15]

16 substatement cardinality abstract 0..1 anyxml 0..n choice 0..n container 0..n description 0..1 ct:instance 0..n ct:instance-list 0..n ct:extends 0..1 grouping 0..n if-feature 0..n key 0..1 leaf 0..n leaf-list 0..n list 0..n must 0..n ordered-by 0..n reference 0..1 refine 0..n status 0..1 typedef 0..n uses 0..n Table 1: complex-type s Substatements Complex type definitions may appear at every place where a grouping may be defined. That includes the module, submodule, rpc, input, output, notification, container, and list statements. Complex type names populate a distinct namespace. As with YANG groupings, it is possible to define a complex type and a data node (e.g., leaf, list, instance statements) with the same name in the same scope. All complex type names defined within a parent node or at the top level of the module or its submodules share the same type identifier namespace. This namespace is scoped to the parent node or module. A complex type MAY have an instance key. An instance key is either defined with the "key" statement as part of the complex type or is inherited from the base complex type. It is not allowed to define an additional key if the base complex type or one of its ancestors already defines a key. Complex type definitions do not create nodes in the schema tree. Linowski, et al. Experimental [Page 16]

17 2.3. instance Extension Statement The "instance" extension statement is used to instantiate a complex type by creating a subtree in the management information node tree. The instance statement takes one argument that is the identifier of the complex type instance. It is followed by a block of substatements. The type of the instance is specified with the mandatory "ct: instance-type" substatement. The type of an instance MUST be a complex type. Common YANG statements may be used as substatements of the "instance" statement. An instance is optional by default. To make an instance mandatory, "mandatory true" has to be applied as a substatement substatement cardinality description 0..1 config 0..1 ct:instance-type 1 if-feature 0..n mandatory 0..1 must 0..n reference 0..1 status 0..1 when 0..1 anyxml 0..n choice 0..n container 0..n ct:instance 0..n ct:instance-list 0..n leaf 0..n leaf-list 0..n list 0..n Table 2: instance s Substatements The "instance" and "instance-list" extension statements (see Section 2.4, "instance-list Extension Statement") are similar to the existing "leaf" and "leaf-list" statements, with the exception that the content is composed of subordinate elements according to the instantiated complex type. It is also possible to add additional data nodes by using the corresponding leaf, leaf-list, list, and choice-statements, etc., as substatements of the instance declaration. This is an in-place Linowski, et al. Experimental [Page 17]

18 augmentation of the used complex type confined to a complex type instantiation (see also Section 2.13, "Using Complex Types", for details on augmenting complex types) instance-list Extension Statement The "instance-list" extension statement is used to instantiate a complex type by defining a sequence of subtrees in the management information node tree. In addition, the "instance-list" statement takes one argument that is the identifier of the complex type instances. It is followed by a block of substatements. The type of the instance is specified with the mandatory "ct: instance-type" substatement. In addition, it can be defined how often an instance may appear in the schema tree by using the "minelements" and "max-elements" substatements. Common YANG statements may be used as substatements of the "instance-list" statement. In analogy to the "instance" statement, YANG substatements like "list", "choice", "leaf", etc., MAY be used to augment the "instancelist" elements at the root level with additional data nodes substatementc cardinality description 0..1 config 0..1 ct:instance-type 1 if-feature 0..n max-elements 0..1 min-elements 0..1 must 0..n ordered-by 0..1 reference 0..1 status 0..1 when 0..1 anyxml 0..n choice 0..n container 0..n ct:instance 0..n ct:instance-list 0..n leaf 0..n leaf-list 0..n list 0..n Table 3: instance-list s Substatements Linowski, et al. Experimental [Page 18]

19 In case the instance list represents configuration data, the used complex type of an instance MUST have an instance key. Instances as well as instance lists may appear as arguments of the "deviate" statement extends Extension Statement A complex type MAY extend exactly one existing base complex type by using the "extends" extension statement. The keyword "extends" MAY occur as a substatement of the "complex-type" extension statement. The argument of the "complex-type" extension statement refers to the base complex type via its name. In case a complex type represents configuration data (the default), it MUST have a key; otherwise, it MAY have a key. A key is either defined with the "key" statement as part of the complex type or is inherited from the base complex type abstract Extension Statement substatement cardinality description 0..1 reference 0..1 status Table 4: extends Substatements Complex types may be declared to be abstract by using the "abstract" extension statement. An abstract complex type cannot be instantiated, meaning it cannot appear as the most specific type of an instance in the NETCONF payload. In case an abstract type extends a base type, the base complex type MUST be also abstract. By default, complex types are not abstract. The abstract complex type serves only as a base type for derived concrete complex types and cannot be used as a type for an instance in the NETCONF payload. The "abstract" extension statement takes a single string argument, which is either "true" or "false". In case a "complex-type" statement does not contain an "abstract" statement as a substatement, the default is "false". The "abstract" statement does not support any substatements. Linowski, et al. Experimental [Page 19]

20 2.7. XML Encoding Rules An "instance" node is encoded as an XML element, where an "instancelist" node is encoded as a series of XML elements. The corresponding XML element names are the "instance" and "instance-list" identifiers, respectively, and they use the same XML namespace as the module. Instance child nodes are encoded as subelements of the instance XML element. Subelements representing child nodes defined in the same complex type may appear in any order. However, child nodes of an extending complex type follow the child nodes of the extended complex type. As such, the XML encoding of lists is similar to the encoding of containers and lists in YANG. Instance key nodes are encoded as subelements of the instance XML element. Instance key nodes must appear in the same order as they are defined within the "key" statement of the corresponding complex type definition and precede all other nodes defined in the same complex type. That is, if key nodes are defined in an extending complex type, XML elements representing key data precede all other XML elements representing child nodes. On the other hand, XML elements representing key data follow the XML elements representing data nodes of the base type. The type of the actual complex type instance is encoded in a type element, which is put in front of all instance child elements, including key nodes, as described in Section 2.8 ("Type Encoding Rules"). The proposed XML encoding rules conform to the YANG XML encoding rules in [RFC6020]. Compared to YANG, enabling key definitions in derived hierarchies is a new feature introduced with the complex types extension. As a new language feature, complex types also introduce a new payload entry for the instance type identifier. Based on our implementation experience, the proposed XML encoding rules support consistent mapping of YANG models with complex types to an XML schema using XML complex types Type Encoding Rules In order to encode the type of an instance in the NETCONF payload, XML elements named "type" belonging to the XML namespace "urn:ietf:params:xml:ns:yang:ietf-complex-type-instance" are added to the serialized form of instance and instance-list nodes in the payload. The suggested namespace prefix is "cti". The "cti:type" XML elements are inserted before the serialized form of all members that have been declared in the corresponding complex type definition. Linowski, et al. Experimental [Page 20]

21 The "cti:type" element is inserted for each type in the extension chain to the actual type of the instance (most specific last). Each type name includes its corresponding namespace. The type of a complex type instance MUST be encoded in the reply to NETCONF <get> and <get-config> operations, and in the payload of a NETCONF <edit-config> operation if the operation is "create" or "replace". The type of the instance MUST also be specified in case <copy-config> is used to export a configuration to a resource addressed with an URI. The type of the instance has to be specified in user-defined remote procedure calls (RPCs). The type of the instance MAY be specified in case the operation is "merge" (either because this is explicitly specified or no operation attribute is provided). In case the node already exists in the target configuration and the type attribute (type of a complex type instance) is specified but differs from the data in the target, an <rpc-error> element is returned with an <error-app-tag> value of "wrong-complex-type". In case no such element is present in the target configuration but the type attribute is missing in the configuration data, an <rpc-error> element is returned with an <error-tag> value of "missing-attribute". The type MUST NOT be specified in case the operation is "delete" Extension and Feature Definition Module The module below contains all YANG extension definitions for complex types and typed instance identifiers. In addition, a "complex-type" feature is defined, which may be used to provide conditional or alternative modeling, depending on the support status of complex types in a NETCONF server. A NETCONF server that supports the modeling features for complex types and the XML encoding for complex types as defined in this document MUST advertise this as a feature. This is done by including the feature name "complex-types" in the feature parameter list as part of the NETCONF <hello> message as described in Section in [RFC6020]. <CODE BEGINS> file "ietf-complex-types@ yang" module ietf-complex-types { namespace "urn:ietf:params:xml:ns:yang:ietf-complex-types"; prefix "ct"; organization Linowski, et al. Experimental [Page 21]

22 "NETMOD WG"; contact "Editor: Bernd Linowski Editor: Mehmet Ersue Editor: Siarhei Kuryla description "YANG extensions for complex types and typed instance identifiers. Copyright (c) 2011 IETF Trust and the persons identified as authors of the code. All rights reserved. Redistribution and use in source and binary forms, with or without modification, is permitted pursuant to, and subject to the license terms contained in, the Simplified BSD License set forth in Section 4.c of the IETF Trust s Legal Provisions Relating to IETF Documents ( This version of this YANG module is part of RFC 6095; see the RFC itself for full legal notices."; revision { description "Initial revision."; extension complex-type { description "Defines a complex-type."; reference "Section 2.2, complex-type Extension Statement"; argument type-identifier { yin-element true; extension extends { description "Defines the base type of a complex-type."; reference "Section 2.5, extends Extension Statement"; argument base-type-identifier { yin-element true; Linowski, et al. Experimental [Page 22]

23 extension abstract { description "Makes the complex-type abstract."; reference "Section 2.6, abstract Extension Statement"; argument status; extension instance { description "Declares an instance of the given complex type."; reference "Section 2.3, instance Extension Statement"; argument ct-instance-identifier { yin-element true; extension instance-list { description "Declares a list of instances of the given complex type"; reference "Section 2.4, instance-list Extension Statement"; argument ct-instance-identifier { yin-element true; extension instance-type { description "Tells to which type instance the instance identifier refers."; reference "Section 3.2, instance-type Extension Statement"; argument target-type-identifier { yin-element true; <CODE ENDS> feature complex-types { description "Indicates that the server supports complex types and instance identifiers."; Linowski, et al. Experimental [Page 23]

24 2.10. Example Model for Complex Types The example model below shows how complex types can be used to represent physical equipment in a vendor-independent, abstract way. It reuses the complex types defined in the physical resource model in Section <CODE BEGINS> module hw { namespace " prefix "hw"; import ietf-complex-types {prefix "ct"; import udmcore {prefix "uc"; // Holder types ct:complex-type Slot { ct:extends uc:equipmentholder; leaf slotnumber { type uint16; config false; //... ct:complex-type Chassis { ct:extends uc:equipmentholder; leaf numberofchassisslots { type uint32; config false; //.. // Equipment types ct:complex-type Card { ct:extends uc:equipment; leaf position { type uint32; mandatory true; leaf slotsrequired {type unit32; // Root Element ct:instance hardware { type uc:managedhardware; // hw module <CODE ENDS> Linowski, et al. Experimental [Page 24]

25 2.11. NETCONF Payload Example Following example shows the payload of a reply to a NETCONF <get> command. The actual type of managed hardware instances is indicated with the "cti:type" elements as required by the type encoding rules. The containment hierarchy in the NETCONF XML payload reflects the containment hierarchy of hardware instances. This makes filtering based on the containment hierarchy possible without having to deal with values of leafs of type leafref that represent the tree structure in a flattened hierarchy. <hardware> <cti:type>uc:basicobject</cti:type> <distinguishedname>/r-t31/ch-2</distinguishedname> <globalid> </globalid> <cti:type>uc:resource</cti:type> <cti:type>uc:physicalresource</cti:type> <otheridentifier>rack R322-1</otherIdentifier> <serialnumber>r-us a</serialnumber> <cti:type>uc:hardware</cti:type> <cti:type>uc:managedhardware</cti:type> <cti:type>hw:equipmentholder</cti:type> <equipmentholder> <cti:type>uc:basicobject</cti:type> <distinguishedname>/r-t31/ch-2/sl-1</distinguishedname> <globalid> </globalid> <cti:type>uc:resource</cti:type> <cti:type>uc:physicalresource</cti:type> <otheridentifier>cu-slot</otheridentifier> <serialnumber>t-k x45</serialnumber> <cti:type>uc:hardware</cti:type> <cti:type>uc:managedhardware</cti:type> <cti:type>uc:equipmentholder</cti:type> <equipment> <cti:type>uc:basicobject</cti:type> <distinguishedname>/r-t31/ch-2/sl-1/c-3</distinguishedname> <globalid> </globalid> <cti:type>uc:resource</cti:type> <cti:type>uc:physicalresource</cti:type> <otheridentifier>atm-45252</otheridentifier> <serialnumber>a b</serialnumber> <cti:type>uc:hardware</cti:type> <cti:type>uc:managedhardware</cti:type> <cti:type>uc:equipment</cti:type> <installed>true</installed> <version>a2</version> <redundancy>1</redundancy> <cti:type>hw:card</cti:type> Linowski, et al. Experimental [Page 25]

26 <usedslots>1</usedslots> </equipment> <cti:type>hw:slot</cti:type> <slotnumber>1</slotnumber> </equipmentholder> <cti:type>hw:chassis</cti:type> <numberofchassisslots>6</numberofchassisslots> //... </hardware> Update Rules for Modules Using Complex Types In addition to the module update rules specified in Section 10 in [RFC6020], modules that define complex types, instances of complex types, and typed instance identifiers must obey following rules: o New complex types MAY be added. o A new complex type MAY extend an existing complex type. o New data definition statements MAY be added to a complex type only if: * they are not mandatory or * they are not conditionally dependent on a new feature (i.e., they do not have an "if-feature" statement that refers to a new feature). o The type referred to by the instance-type statement may be changed to a type that derives from the original type only if the original type does not represent configuration data Using Complex Types All data nodes defined inside a complex type reside in the complex type namespace, which is their parent node namespace Overriding Complex Type Data Nodes It is not allowed to override a data node inherited from a base type. That is, it is an error if a type "base" with a leaf named "foo" is extended by another complex type ("derived") with a leaf named "foo" in the same module. In case they are derived in different modules, there are two distinct "foo" nodes that are mapped to the XML namespaces of the module, where the complex types are specified. Linowski, et al. Experimental [Page 26]

27 A complex type that extends a basic complex type may use the "refine" statement in order to improve an inherited data node. The target node identifier must be qualified by the module prefix to indicate clearly which inherited node is refined. The following refinements can be done: o A leaf or choice node may have a default value, or a new default value if it already had one. o Any node may have a different "description" or "reference" string. o A leaf, anyxml, or choice node may have a "mandatory true" statement. However, it is not allowed to change from "mandatory true" to "mandatory false". o A leaf, leaf-list, list, container, or anyxml node may have additional "must" expressions. o A list, leaf-list, instance, or instance-list node may have a "min-elements" statement, if the base type does not have one or does not have one with a value that is greater than the minimum value of the base type. o A list, leaf-list, instance, or instance-list node may have a "max-elements" statement, if the base type does not have one or does not have one with a value that is smaller than the maximum value of the base type. It is not allowed to refine complex-type nodes inside "instance" or "instance-list" statements Augmenting Complex Types Augmenting complex types is only allowed if a complex type is instantiated in an "instance" or "instance-list" statement. This confines the effect of the augmentation to the location in the schema tree where the augmentation is done. The argument of the "augment" statement MUST be in the descendant form (as defined by the rule "descendant-schema-nodeid" in Section 12 in [RFC6020]). Linowski, et al. Experimental [Page 27]

28 ct:complex-type Chassis { ct:extends EquipmentHolder; container chassisinfo { config false; leaf numberofslots { type uint16; leaf occupiedslots { type uint16; leaf height {type unit16; leaf width {type unit16; ct:instance-list chassis { type Chassis; augment "chassisinfo" { leaf modelid { type string; When augmenting a complex type, only the "container", "leaf", "list", "leaf-list", "choice", "instance", "instance-list", and "if-feature" statements may be used within the "augment" statement. The nodes added by the augmentation MUST NOT be mandatory nodes. One or many "augment" statements may not cause the creation of multiple nodes with the same name from the same namespace in the target node. To achieve less-complex modeling, this document proposes the augmentation of complex type instances without recursion Controlling the Use of Complex Types A server might not want to support all complex types defined in a supported module. This issue can be addressed with YANG features as follows: o Features are defined that are used inside complex type definitions (by using "if-feature" as a substatement) to make them optional. In this case, such complex types may only be instantiated if the feature is supported (advertised as a capability in the NETCONF <hello> message). o The "deviation" statement may be applied to node trees, which are created by "instance" and "instance-list" statements. In this case, only the substatement "deviate not-supported" is allowed. Linowski, et al. Experimental [Page 28]

29 o It is not allowed to apply the "deviation" statement to node tree elements that may occur because of the recursive use of a complex type. Other forms of deviations ("deviate add", "deviate replace", "deviate delete") are NOT supported inside node trees spanned by "instance" or "instance-list". As complex type definitions do not contribute by themselves to the data node tree, data node declarations inside complex types cannot be the target of deviations. In the example below, client applications are informed that the leaf "occupiedslots" is not supported in the top-level chassis. However, if a chassis contains another chassis, the contained chassis may support the leaf that reports the number of occupied slots. deviation "/chassis/chassisspec/occupiedslots" { deviate not-supported; 3. Typed Instance Identifier 3.1. Definition Typed instance identifier relationships are an addition to the relationship types already defined in YANG, where the leafref relationship is location dependent, and the instance-identifier does not specify to which type of instances the identifier points. A typed instance identifier represents a reference to an instance of a complex type without being restricted to a particular location in the containment tree. This is done by using the extension statement "instance-type" as a substatement of the existing "type instance identifier" statement. Typed instance identifiers allow referring to instances of complex types that may be located anywhere in the schema tree. The "type" statement plays the role of a restriction that must be fulfilled by the target node, which is referred to with the instance identifier. The target node MUST be of a particular complex type, either the type itself or any type that extends this complex type instance-type Extension Statement The "instance-type" extension statement specifies the complex type of the instance to which the instance-identifier refers. The referred instance may also instantiate any complex type that extends the specified complex type. Linowski, et al. Experimental [Page 29]

30 The instance complex type is identified by the single name argument. The referred complex type MUST have a key. This extension statement MUST be used as a substatement of the "type instance-identifier" statement. The "instance-type" extension statement does not support any substatements Typed Instance Identifier Example In the example below, a physical link connects an arbitrary number of physical ports. Here, typed instance identifiers are used to denote which "PhysicalPort" instances (anywhere in the data tree) are connected by a "PhysicalLink". // Extended version of type Card ct:complex-type Card { ct:extends Equipment; leaf usedslot { type uint16; mandatory true; ct:instance-list port { type PhysicalPort; ct:complex-type PhysicalPort { ct:extends ManagedHardware; leaf portnumber { type int32; mandatory true; ct:complex-type PhysicalLink { ct:extends ManagedHardware; leaf media { type string; leaf-list connectedport { type instance-identifier { ct:instance-type PhysicalPort; min-elements 2; Below is the XML encoding of an element named "link" of type "PhysicalLink": Linowski, et al. Experimental [Page 30]

31 <link> <objectid>ftcl-771</objectid> <media>fiber</media> <connectedport>/hw:hardware[objectid= R-11 ] /hw:equipment[objectid= AT22 ]/hw:port[objectid= P12 ] </connectedport> <connectedport>/hw:hardware[objectid= R-42] /hw:equipment[objectid= AT30 ]/hw:port[objectid= P3 ] </connectedport> <serialnumber>f </serialnumber> <commonname>fibcon 7</commonName> </link> 4. IANA Considerations This document registers two URIs in the IETF XML registry. IANA registered the following URIs, according to [RFC3688]: URI: urn:ietf:params:xml:ns:yang:ietf-complex-types URI: urn:ietf:params:xml:ns:yang:ietf-complex-type-instance Registrant Contact: Bernd Linowski (bernd.linowski.ext@nsn.com) Mehmet Ersue (mehmet.ersue@nsn.com) Siarhei Kuryla (s.kuryla@gmail.com) XML: N/A, the requested URIs are XML namespaces. This document registers one module name in the "YANG Module Names" registry, defined in [RFC6020]. name: ietf-complex-types namespace: urn:ietf:params:xml:ns:yang:ietf-complex-types prefix: ct RFC: Security Considerations The YANG module "complex-types" in this memo defines YANG extensions for complex types and typed instance identifiers as new language statements. Complex types and typed instance identifiers themselves do not have any security impact on the Internet. Linowski, et al. Experimental [Page 31]

32 The security considerations described throughout [RFC6020] apply here as well. 6. Acknowledgements The authors would like to thank to Martin Bjorklund, Balazs Lengyel, Gerhard Muenz, Dan Romascanu, Juergen Schoenwaelder, and Martin Storch for their valuable review and comments on different versions of the document. 7. References 7.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, October Informative References [IPFIXCONF] Muenz, G., Claise, B., and P. Aitken, "Configuration Data Model for IPFIX and PSAMP", Work in Progress, March [Libsmi] [Pyang] [Pyang-ct] Kuryla, S., "Libsmi Extension for Complex Types", April 2010, < Bjorklund, M., "An extensible YANG validator and converter in python", October 2010, < Kuryla, S., "Complex type extension for an extensible YANG validator and converter in python", April 2010, < [RFC4133] Bierman, A. and K. McCloghrie, "Entity MIB (Version 3)", RFC 4133, August Linowski, et al. Experimental [Page 32]

33 [SID_V8] [UDM] TeleManagement Forum, "GB922, Information Framework (SID) Solution Suite, Release 8.0", July 2008, < GB922InformationFramework/35499/article.html>. NSN, "Unified Data Model SID Compliance Statement", May 2010, < NokiaSiemensNetworks/8815/home.html>. Linowski, et al. Experimental [Page 33]