]> Guidelines for Translation of UML Information Model to YANG Data Model Ericsson Inc.
USA +1 724 931 9316 scott.mansfield@ericsson.com
Deutsche Telekom AG
Heinrich-Hertz-Str, 3-7 Darmstadt 64295 Germany +49 6151 58-12086 b.zeuner@telekom.de
Ciena
United Kingdom ndavis@ciena.com
Fiberhome
China yunxig@fiberhome.com.cn
Fujitsu
Japan tochio@jp.fujitsu.com
Alcatel Lucent
USA +1 732 331 3476 kam.lam@alcatel-lucent.com
Alcatel Lucent
USA eve.varma@alcatel-lucent.com
Operations and Management NETMOD Working Group UML Information modeling This document defines guidelines for translation of data modeled with UML to YANG including mapping of object classes, attributes, data types, associations, interfaces, operations and operation parameters, notifications, and lifecycle.
As discussed in draft-lam-teas-usage-info-model-net-topology a Data Model (DM) may be derived from an Information Model (IM). However, in order to assure a consistent and valid data modelling language representation that enables maximum interoperability, translation guidelines are required. A set of translation rules also assists in development of automated tooling. This draft defines guidelines for translation of data modelled with UML (as constrained by the ONF's UML Modeling Guidelines) to YANG (defined in RFC6020 and YANG Update) including mapping of object classes, attributes, data types, associations, interfaces, operations and operation parameters, notifications, and lifecycle.
The following terms are defined in RFC6020 anydata anyxml augment container data node identity instance identifier leaf leaf-list list module submodule The following terms are defined in UML 2.4 association attribute data type interface object class operation parameter signal (used to model notifications)
This document defines translation rules for all constructs used in a UML based IM to a data model using YANG. While some mapping rules are straightforward, an IM in UML uses some constructs that cannot be mapped directly to a DM using YANG and conventions are described to make the translation predictable. Additionally, in some cases multiple mapping approaches are possible and selection among these is also necessary to assure interoperability. Mapping guidelines for these constructs are provided in the following sections.
Where "??" is inserted in the table, it means that the specific mapping is for further study as it is either as yet unclear how to map the construct or that there are multiple ways of doing the mapping and a single one needs to be selected. A table will be included summarizing constructs in UML that do not directly map to YANG and where in this draft the associated guidelines for mapping these constructs will be provided.
add | | | | prefix to the rpc | | | | name; i.e. | | | | objectClass::rpc; | | | | "action" requires | | | | YANG 1.1 | +-------------------------------------------------------------------+ | XOR | "choice" | | | | substatement | | +-------------------------------------------------------------------+ | muliplicity on | list::"min-elements" | min-elements | | association | "max-elements" | default = 0 | | | substatements | max-elements | | | | default=unbounded| | | | mandatory | | | | default=false | +-------------------------------------------------------------------+ | Conditional PACs | container::presence" | | | | substatement | | +-------------------------------------------------------------------+ | hyperlink?? | "reference" | Papyrus doesn't | | | substatement | support hyperlinks| +-------------------------------------------------------------------+ | lifecycle stereotypes | "status" | UML: | | | substatement | <>, | | | | <>, | | | | <>, | | | |<>,| | | | <>, | | | | <>, | | | | <> | | | | YANG: | | | | "current", | | | | "deprecated", | | | | "obsolete", | | | | default="current" | +-------------------------------------------------------------------+ | constraint property | list::"unique" | UML is not able to| | | substatement | define a group | | | | of attributes to be | | | unique as YANG can| | | | do using the | | | | "unique" | | | | substatement. | +-------------------------------------------------------------------+ | abstract superclass/ | "uses" substatement | use of a complex | | inheritance | | data type as the | | | | type of the | | complex attribute | | attribute; e.g., | | | | date and time, | | | | object creation | | | | data | | | | It is possible that | | | the superclass or | | | | abstract class | | | | contains the key | | | | attribute for the | | | | instantiated | | | | subclass. | +-------------------------------------------------------------------+ | {} | "when" substatement | | +-------------------------------------------------------------------+ ]]>
"leaf" (single) or "leaf list" (multiple) | | statement | +-------------------------------------------------------------------+ | UML Artifact | YANG Artifact | Comment | +-------------------------------------------------------------------+ | documentation | "description" | Multiple "applied | | "Applied comments" | substatement | comments" defined | | (carried in XMI as | | in UML, need to be| | "ownedComment") | | collapsed into a | | | | single | | | | "description" | | | | substatement. | +-------------------------------------------------------------------+ | type | "type" substatement | | | | (built-in or derived) | | +-------------------------------------------------------------------+ | readOnly | "config" substatement | config | | | (false) | default = true | +-------------------------------------------------------------------+ | isOrdered | "ordered-by" | ordered-by | | | substatement | default = system | | |("system" or "user") | | +-------------------------------------------------------------------+ | multiplicity | "mandatory" or | min-elements | | | "min-elements" and | default = 0 | | | "max-elements" | max-elements | | | substatements | default=unbounded| | | [0..1]=>no mapping | mandatory | | | needed; is default | default=false | | | substatement=false | | | | [1]=>mandatory | | | | substatement=true | | | | [0..x]=> no mapping | | | | needed; is default | | | | [1..x]=> min-elements | | | | substatement = 1 | | | | [0..3]=> max-elements | | | | substatement = 3 | | +-------------------------------------------------------------------+ | defaultValue | "default" | If a default value| | | substatement | exists and it is | | | | the desired value,| | | | the parameter does| | | | not have to be | | | | explicitly config-| | | | ured by the user. | +-------------------------------------------------------------------+ | isInvariant | "extension" | | | | substatement -> | | | | ompExt:isInvariant | | +-------------------------------------------------------------------+ | valueRange | "pattern", "range", or| | | | "length" substatement | | | | of "type" substatement| | +-------------------------------------------------------------------+ | passedByReference | if passedByReference =| Relevant only to | | | true -> type leafref {| attributes that | | | path "// | have an object | | | "} | class defined as | | | | their type. | | | if passedByReference =| | | | false -> either "list"| | | | statement (key | | | | property, multiple | | | | instances) or | | | | "container" statement(| | | | single instance) | | +-------------------------------------------------------------------+ | partOfObjectKey > 0 | list::"key" | It is possible that | | substatement | the (abstract) | | | | superclass contains | | | the key attribute | | | | for the | | | | instantiated | | | | subclass. | +-------------------------------------------------------------------+ | unit | "units" substatement | Need to discuss | | | | with the YANG | | | | community about a | | | | standard way to | | | | express units (e.g. | | | kilobitspersecond,| | | | kbit/s, | | | | kilobits/second, | | | | kbit/sec). | | | | | | | | Current | | | | description of the| | | | new "unit" property | | | in OpenModelProfile | | | v0.2.1 is: | | | | "This optional | | | | property contains a | | | textual definition| | | | of the unit | | | | associated with the | | | attribute value. | | | | The spelling of the | | | unit, including the | | | ones beyond SI | | | | scope, shall be in| | | | accordance to the | | | | NIST Publication | | | | 811 "Guide for the| | | | Use of the | | | | International | | | | System of Units | | | | (SI)" (http://www.| | | | nist.gov/pml/pubs/| | | | sp811/index.cfm), | | | | section 9 "Rules | | | | and Style | | | | Conventions for | | | | Spelling Unit | | | | Names"." | +-------------------------------------------------------------------+ | support | For conditional | Support and | | | support only: | condition belong | +-----------------------+ | together. If the | | condition | "if-feature" | "support" is cond-| | | substatement | itional, then the | | | | "condition" | | | "when" substatement if| explains the cond-| | | condition can be | itions under which| | | formalized as XPath | the class has to | | | expression (i.e., it | be supported. | | | is conditioned by the | | | | value of another | | | | attribute) | | +-------------------------------------------------------------------+ | error notfication?? | "must" | | | | substatement | | +-------------------------------------------------------------------+ | hyperlink?? | "reference" | Papyrus doesn't | | | substatement | support hyperlinks| +-------------------------------------------------------------------+ | lifecycle stereotypes | "status" | "current" | | | substatement | "deprecated" | | | | "obsolete" | | | | default="current"| +-------------------------------------------------------------------+ | {} | "when" substatement | | +-------------------------------------------------------------------+ ]]>
new built-in type?? | +-------------------------------------------------------------------+ | UML Artifact | YANG Artifact | Comment | +-------------------------------------------------------------------+ | documentation | Description field | | | (carried in XMI as | | | | "ownedComment") | | | +-------------------------------------------------------------------+ | Integer | int64 | | +-------------------------------------------------------------------+ | Boolean | boolean | | +-------------------------------------------------------------------+ | String | string | | +-------------------------------------------------------------------+ | Real | ?? | | +-------------------------------------------------------------------+ ]]>
"enum" statement | | typedef for reusable (indirect usage) enumerations | | identity statement? | +-------------------------------------------------------------------+ | UML Artifact | YANG Artifact | Comment | +-------------------------------------------------------------------+ | documentation | "description" | Multiple "applied | | "Applied comments" | substatement | comments" defined | | (carried in XMI as | | in UML, need to be| | "ownedComment") | | collapsed into a | | | | single | | | | "description" | | | | substatement. | +-------------------------------------------------------------------+ | literal integer | "value" | | | | substatement | | +-------------------------------------------------------------------+ | hyperlink?? | "reference" | Papyrus doesn't | | | substatement | support hyperlinks| +-------------------------------------------------------------------+ | lifecycle stereotypes | "status" | "current", | | | substatement | "deprecated", | | | | "obsolete" | | | | default=current | +-------------------------------------------------------------------+ | ?? | "if-feature" statement| | +-------------------------------------------------------------------+ ]]>
"typeDef" statement | +-------------------------------------------------------------------+ | UML Artifact | YANG Artifact | Comment | +-------------------------------------------------------------------+ | documentation | "description" | Multiple "applied | | "Applied comments" | substatement | comments" defined | | (carried in XMI as | | in UML, need to be| | "ownedComment") | | collapsed into a | | | | single | | | | "description" | | | | substatement. | +-------------------------------------------------------------------+ | type | "type" substatement | | | | (built-in type) | | +-------------------------------------------------------------------+ | defaultValue | "default" | If a default value| | | substatement | exists and it is | | | | the desired value,| | | | the parameter does| | | | not have to be | | | | explicitly config-| | | | ured by the user. | +-------------------------------------------------------------------+ | hyperlink?? | "reference" | Papyrus doesn't | | | substatement | support hyperlinks| +-------------------------------------------------------------------+ | lifecycle stereotypes | "status" | "current", | | | substatement | "deprecated", | | | | "obsolete" | | | | default=current | +-------------------------------------------------------------------+ | unit | "units" statement | | +-------------------------------------------------------------------+ ]]>
"grouping" statement | +-------------------------------------------------------------------+ | UML Artifact | YANG Artifact | Comment | +-------------------------------------------------------------------+ | documentation | "description" | Multiple "applied | | "Applied comments" | substatement | comments" defined | | (carried in XMI as | | in UML, need to be| | "ownedComment") | | collapsed into a | | | | single | | | | "description" | | | | substatement. | +-------------------------------------------------------------------+ | not used | "action" substatement | | +-------------------------------------------------------------------+ | XOR | "choice" | | | | substatement | | +-------------------------------------------------------------------+ | hyperlink?? | "reference" | Papyrus doesn't | | | substatement | support hyperlinks| +-------------------------------------------------------------------+ | lifecycle stereotypes | "status" | "current", | | | substatement | "deprecated", | | | | "obsolete" | | | | default=current | +-------------------------------------------------------------------+ | complex attribute | "uses" statement | | +-------------------------------------------------------------------+ ]]>
Leaf and leaf-list can only use built-in types, typeDef types or enumerations in their type substatement; i.e., not groupings. Complex data types with more than one item (e.g., name value pair) can only be defined using groupings. Groupings can only be used by grouping, container and list statements.
Container?? | +-------------------------------------------------------------------+ | documentation | "description" | Multiple "applied | | "Applied comments" | substatement | comments" defined | | (carried in XMI as | | in UML, need to be| | "ownedComment") | | collapsed into a | | | | single | | | | "description" | | | | substatement. | +-------------------------------------------------------------------+ | abstract | "grouping" statement | | +-------------------------------------------------------------------+ | support | "if-feature" | Support and | | | substatement | condition belong | +-----------------------+ | together. If the | | condition | | "support" is cond-| | | | itional, then the | | | | "condition" | | | | explains the cond-| | | | itions under which| | | | the class has to | | | | be supported. | +-------------------------------------------------------------------+ ]]>
"action" and "rpc" statements | | (RFC 6020: The difference between an action and an rpc is that an| | action is tied to a node in the data tree, whereas an rpc is | | associated at the module level.) | +-------------------------------------------------------------------+ | documentation | "description" | Multiple "applied | | "Applied comments" | substatement | comments" defined | | (carried in XMI as | | in UML, need to be| | "ownedComment") | | collapsed into a | | | | single | | | | "description" | | | | substatement. | +-------------------------------------------------------------------+ | pre-condition | "extension" | RFC 6020; During | | | substatement -> | the NETCONF | | | ompExt:preCondition | pro-| | | | cessing errors are| | | | already sent for: | | | | - Delete requests | | | | for non-existent| | | | data. | | | | - Create requests | | | | for existing | | | | data. | | | | - Insert requests | | | | with "before" or| | | | "after" para- | | | | meters that do | | | | not exist. | +-------------------------------------------------------------------+ | post-condition | "extension" | | | | substatement | | | | ompExt:postCondition | | +-------------------------------------------------------------------+ | input parameter | "input" substatement | | +-------------------------------------------------------------------+ | output parameter | "output" substatement | | +-------------------------------------------------------------------+ | operation exceptions | "extension" | | | | substatement | | | Internal Error | ompExt:operationExceptions | | Unable to Comply | | | Comm Loss | +--------------------------------------+ | | Invalid Input | | error-tag | error-app-tag | | | Not Implemented | +--------------------------------------+ | | Duplicate | | operation-failed | too-many-elements | | | Entity Not Found | | | too-few-elements | | | Object In Use | | | must-violation | | | Capacity Exceeded | +--------------------------------------+ | | Not In Valid State | | data-missing | instance-required | | | Access Denied | | | missing-choice | | | | +--------------------------------------+ | | | | bad-attribute | missing-instance | | | | +--------------------------------------+ | +-------------------------------------------------------------------+ | isOperationIdempotent | "extension" | | | | substatement | | | | ompExt:isOperationIdempotent | +-------------------------------------------------------------------+ | isAtomic | "extension" | Necessary?? Not in| | | substatement | UML Guidelines | | | ompExt:isAtomic | (TR-514); needs to| | | | be added?? | +-------------------------------------------------------------------+ | support | "if-feature" | Support and | | | substatement | condition belong | +-----------------------+ | together. If the | | condition | | "support" is cond-| | | | itional, then the | | | | "condition" | | | | explains the cond-| | | | itions under which| | | | the class has to | | | | be supported. | +-------------------------------------------------------------------+ | hyperlink?? | "reference" | Papyrus doesn't | | | substatement | support hyperlinks| +-------------------------------------------------------------------+ | lifecycle stereotypes | "status" | "current", | | | substatement | "deprecated", | | | | "obsolete" | | | | default=current | +-------------------------------------------------------------------+ ]]>
type leafref {| attributes that | | | path "// | have an object | | | "} | class defined as | | | | their type. | | | if passedByReference =| | | | false -> either "list"| | | | statement (key | | | | property, multiple | | | | instances) or | | | | "container" statement(| | | | single instance) | | +-------------------------------------------------------------------+ | support | "if-feature" | Support and | | | substatement not | condition belong | +-----------------------+ defined for input and | together. If the | | condition | output substatements | "support" is cond-| | | in YANG?? | itional, then the | | | | "condition" | | | | explains the cond-| | | | itions under which| | | | the class has to | | | | be supported. | +-------------------------------------------------------------------+ | XOR | "choice" | | | | substatement | | +-------------------------------------------------------------------+ | error notification?? | "must" | | | | substatement | | +-------------------------------------------------------------------+ | complex parameter | "uses" | | | | substatement | | +-------------------------------------------------------------------+ ]]>
"notification" statement | +-------------------------------------------------------------------+ | documentation | "description" | Multiple "applied | | "Applied comments" | substatement | comments" defined | | (carried in XMI as | | in UML, need to be| | "ownedComment") | | collapsed into a | | | | single | | | | "description" | | | | substatement. | +-------------------------------------------------------------------+ | support | "if-feature" | Support and | | | substatement | condition belong | +-----------------------+ | together. If the | | condition | | "support" is cond-| | | | itional, then the | | | | "condition" | | | | explains the cond-| | | | itions under which| | | | the class has to | | | | be supported. | +-------------------------------------------------------------------+ | XOR | "choice" | | | | substatement | | +-------------------------------------------------------------------+ | error notification?? | "must" | | | | substatement | | +-------------------------------------------------------------------+ | hyperlink?? | "reference" | Papyrus doesn't | | | substatement | support hyperlinks| +-------------------------------------------------------------------+ | lifecycle stereotypes | "status" | "current", | | | substatement | "deprecated", | | | | "obsolete" | | | | default=current | +-------------------------------------------------------------------+ | attributes | see mapping of | | | | attribute types | | | | (grouping, leaf, | | | | leaf-list, container,| | | | list, typedef, uses) | | +-------------------------------------------------------------------+ | complex attribute | "uses" | | | | substatement | | +-------------------------------------------------------------------+ ]]>
>, | | | | <>, | | | | <>, | | | | <>, | | | | <>, | | | | <>| | | | | | | | How to map or | | | | enhance?? | +-------------------------------------------------------------------+ ]]>
Many common types (primitive and complex) are already defined in YANG. E.g., ietf-inet-types, ietf-yang-types (others to be investigated):
> Host - DateAndTime + types related to - DottedQuad IP addresses and hostnames - Gauge32 - Ipv4Address - Gauge64 - Ipv4AddressNoZone - HexString - Ipv4Prefix - MacAddress - Ipv6Address - ObjectIdentifier - Ipv6AddressNoZone - ObjectIdentifier128 - Ipv6Prefix - PhysAddress - <> IpAddress - Timestamp - <> IpAddressNoZone - Timeticks - <> IpPrefix - Uuid + types related to protocol fields - Xpath1.0 - IpVersion - YangIdentifier - DSCP - ZeroBasedCounter32 - IpV6FlowLabel - ZeroBasedCounter64 - PortNumber ]]>
It is proposed to define for the commonly used YANG types corresponding UML primitive or complex data types respectively. These types will be available (by default) for use in all UML information models. This "re-engineering" needs to be done without making the UML models YANG-depended.
YANG 1.0 is approved and defined in RFC6020. YANG 1.1 is not currently approved and its definition is ongoing in draft-ietf-netmod-rfc6020bis. Main enhancements are the action and anydata statements.
Need to define mapping rules for UML package into YANG modules or the new draft YANG package statement (draft-bierman-netmod-yang-package)?
As YANG defines hierarchical data store, any instances that need to store recursive containment will require translation. A mapping between object-oriented store and a hierarchical store is possible; however, there is more than one option: Reference Based Approach approach - have a flat list of objects, where the objects are linked into a hierarchy using references. An example of a two-way navigable approach is in RFC7223. Assume some specific number of "recursions"; i.e., specify some default number of recursion levels, and define a configurable parameter to allow changing the number of levels.
Use the "presence" property of the container statement? Note: An example of this usage is given in the "Data nodes for the operational state of IP on interfaces." within ietf-ip.yang RFC7277.
Use the "choice" property of the container statement.
The UML Modeling Guidelines define support and condition for all UML artifacts (M - Mandatory, O - Optional, C - Conditional, CM - Conditional-Mandatory, CO - Conditional-Optional). Support qualifies the support of the artifact at the management interface. Condition contains the condition for the condition-related support qualifiers. M - Mandatory maps to the "mandatory" substatement in choice and leaf or to the "min-elements" substatement in leaf-list and list. O - Optional need not be mapped since the per default the "mandatory" and "min-elements" substaments define optional. All conditional UML support qualifiers are mapped to the "if-feature" substatement.
This memo includes no request to IANA.
This document defines defines guidelines for translation of data modeled with UML to YANG. As such, it doesn't contribute any new security issues beyond those discussed in Sec. 16 of RFC6020.
&RFC6020; &RFC7223; &RFC7277; &I-D.bierman-netmod-yang-package; &I-D.draft-ietf-netmod-rfc6020bis; &I-D.dharini-netmod-g-698-2-yang; &I-D.lam-teas-usage-info-model-net-topology; Unified Modeling Language (UML) OMG ONF TR-514 v1.0 UML Modeling Guidelines OMG
The YANG data schema (in tree format) shown below was extracted from dharini-netmod-g-698-2-yang and represents the same data as UML model appearing in after the tree format. Note: The color code used in the tree format corresponds to the color code used in the UML class diagram.