RFC 6095
Extending YANG with Language Abstractions
Pages: 75
Experimental
Experimental
Part 2 of 4 – Pages 15 to 33
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.2.2. 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]).
+------------------+-------------+ | 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.
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
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).2.4. 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 "min- elements" 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 "instance- list" 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
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.2.5. 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. +--------------+-------------+ | substatement | cardinality | +--------------+-------------+ | description | 0..1 | | reference | 0..1 | | status | 0..1 | +--------------+-------------+ Table 4: extends' Substatements2.6. abstract Extension Statement
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.
2.7. XML Encoding Rules
An "instance" node is encoded as an XML element, where an "instance- list" 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.2.8. 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.
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".2.9. 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 5.6.4 in [RFC6020]. <CODE BEGINS> file "ietf-complex-types@2011-03-15.yang" module ietf-complex-types { namespace "urn:ietf:params:xml:ns:yang:ietf-complex-types"; prefix "ct"; organization
"NETMOD WG";
contact
"Editor: Bernd Linowski
<bernd.linowski.ext@nsn.com>
Editor: Mehmet Ersue
<mehmet.ersue@nsn.com>
Editor: Siarhei Kuryla
<s.kuryla@gmail.com>";
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
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC 6095; see
the RFC itself for full legal notices.";
revision 2011-03-15 {
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;
}
}
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;
}
}
feature complex-types {
description "Indicates that the server supports
complex types and instance identifiers.";
}
}
<CODE ENDS>
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 1.5.1. <CODE BEGINS> module hw { namespace "http://example.com/hw"; 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>
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>6278279001</globalId> <cti:type>uc:Resource</cti:type> <cti:type>uc:PhysicalResource</cti:type> <otherIdentifier>Rack R322-1</otherIdentifier> <serialNumber>R-US-3276279a</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>548872003</globalId> <cti:type>uc:Resource</cti:type> <cti:type>uc:PhysicalResource</cti:type> <otherIdentifier>CU-Slot</otherIdentifier> <serialNumber>T-K4733890x45</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>89772001</globalId> <cti:type>uc:Resource</cti:type> <cti:type>uc:PhysicalResource</cti:type> <otherIdentifier>ATM-45252</otherIdentifier> <serialNumber>A-778911-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>
<usedSlots>1</usedSlots>
</equipment>
<cti:type>hw:Slot</cti:type>
<slotNumber>1</slotNumber>
</equipmentHolder>
<cti:type>hw:Chassis</cti:type>
<numberOfChassisSlots>6</numberOfChassisSlots>
// ...
</hardware>
2.12. 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.
2.13. Using Complex Types
All data nodes defined inside a complex type reside in the complex
type namespace, which is their parent node namespace.
2.13.1. 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.
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.
2.13.2. 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]).
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.
2.13.3. 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.
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.
3.2. 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.
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.3.3. 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":
<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-7786828</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: 6095
5. 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.
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 1997. [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004. [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, October 2010.7.2. Informative References
[IPFIXCONF] Muenz, G., Claise, B., and P. Aitken, "Configuration Data Model for IPFIX and PSAMP", Work in Progress, March 2011. [Libsmi] Kuryla, S., "Libsmi Extension for Complex Types", April 2010, <http://www.ibr.cs.tu-bs.de/svn/libsmi>. [Pyang] Bjorklund, M., "An extensible YANG validator and converter in python", October 2010, <http://code.google.com/p/pyang/>. [Pyang-ct] Kuryla, S., "Complex type extension for an extensible YANG validator and converter in python", April 2010, <http://code.google.com/p/pyang-ct/>. [RFC4133] Bierman, A. and K. McCloghrie, "Entity MIB (Version 3)", RFC 4133, August 2005.
[SID_V8] TeleManagement Forum, "GB922, Information Framework (SID) Solution Suite, Release 8.0", July 2008, <http:// www.tmforum.org/DocumentsInformation/ GB922InformationFramework/35499/article.html>. [UDM] NSN, "Unified Data Model SID Compliance Statement", May 2010, <http://www.tmforum.org/InformationFramework/ NokiaSiemensNetworks/8815/home.html>.
(next page on part 3)