]> 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
Nokia
USA +1 732 331 3476 kam.lam@nokia.com
Nokia
USA eve.varma@nokia.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 1.1) 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.
1 on | list::"min-elements" | min-elements | | association to the | "max-elements" | default = 0 | | class | substatements | max-elements | | | | default=unbounded| | | | mandatory | | | | default=false | +-------------------------------------------------------------------+ | <> | "reference" | | | | substatement | | +-------------------------------------------------------------------+ | <> | Ignore Example | | | | elements and all | | | | composed parts | | +-------------------------------------------------------------------+ | lifecycleState | "status" | <> -> "YANG" | | | substatement | <> | | | | "deprecated", | | | | <> | | | | description, | | | | <> | | | | description, | | | |<> | | | | description, | | | | <> | | | | "current", | | | | <> | | | | "obsolete", | | | | <> | | | | description | +-------------------------------------------------------------------+ | Proxy Class | "choice" | | | XOR | 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. | +-------------------------------------------------------------------+ | operation | "action" | YANG 1.0 supports | | | substatement | only rpc -> add | | | | prefix to the rpc | | | | name; i.e. | | | | objectClass::rpc; | | | | "action" requires | | | | YANG 1.1 | +-------------------------------------------------------------------+ | Conditional PACs | container::presence" | | | | substatement | | +-------------------------------------------------------------------+ | 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. | +-------------------------------------------------------------------+ | {} | "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") | | +-------------------------------------------------------------------+ | isUnique | No unique | Only relevant for | | | sub-statement in | multi-valued | | | leaf-list | attributes. | +-------------------------------------------------------------------+ | Multiplicity | "mandatory" or | min-elements | | (carried in XMI as | "min-elements" and | default = 0 | | lowerValue and | "max-elements" | max-elements | | upperValue) | 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 | For string type: | The tool should | | | "pattern" and/or | provide a warning | | | "length substatement| at the output of | | | of "type" substatement| mapping process | | | For integer and | notifying when one| | | decimal type: | or more UML | | | "range" substatement| valueRange | | | of "type" substatement| definitions are | | | For all other typed | contained in the | | | attributes and for | description | | | string or integer or | substatement of | | | decimal typed | the corresponding | | | attributes where the | leaf or leaf-list.| | | UML definition is not | When the value of | | | compliant to YANG: | "valueRange" is | | | "description" | "null", "NA", | | | substatement | "See data type", | | | | the tool ignores | | | | it and doesn't | | | | print out "range" | | | | 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 | | +-------------------------------------------------------------------+ | <> | "reference" | | | | substatement | | +-------------------------------------------------------------------+ | <> | Ignore Example | | | | elements and all | | | | composed parts | | +-------------------------------------------------------------------+ | lifecycleState | "status" | <> -> "YANG" | | | substatement | <> | | | | "deprecated", | | | | <> | | | | description, | | | | <> | | | | description, | | | |<> | | | | description, | | | | <> | | | | "current", | | | | <> | | | | "obsolete", | | | | <> | | | | description | +-------------------------------------------------------------------+ | 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 | | +-------------------------------------------------------------------+ | {} | "when" substatement | | +-------------------------------------------------------------------+ ]]>
"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 or | | | | derived type) | | +-------------------------------------------------------------------+ | defaultValue | "default" substatment | If a default value| | | | exists and it is | | | | the desired value,| | | | the parameter does| | | | not have to be | | | | explicitly | | | | configured by the | | | | user. When the | | | | value of | | | | "defaultValue" is | | | | "NA", the tool | | | | ignores it and | | | | doesn't print out | | | | "default" | | | | substatement. | +-------------------------------------------------------------------+ | unit | "units" substatement | | +-------------------------------------------------------------------+ | <> | "reference" | | | | substatement | | +-------------------------------------------------------------------+ | <> | Ignore Example | | | | elements and all | | | | composed parts | | +-------------------------------------------------------------------+ | lifecycleState | "status" | <> -> "YANG" | | | substatement | <> | | | | "deprecated", | | | | <> | | | | description, | | | | <> | | | | description, | | | |<> | | | | description, | | | | <> | | | | "current", | | | | <> | | | | "obsolete", | | | | <> | | | | description | +-------------------------------------------------------------------+ ]]>
"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 | | +-------------------------------------------------------------------+ | <> | "reference" | | | | substatement | | +-------------------------------------------------------------------+ | <> | Ignore Example | | | | elements and all | | | | composed parts | | +-------------------------------------------------------------------+ | lifecycleState | "status" | <> -> "YANG" | | | substatement | <> | | | | "deprecated", | | | | <> | | | | description, | | | | <> | | | | description, | | | |<> | | | | description, | | | | <> | | | | "current", | | | | <> | | | | "obsolete", | | | | <> | | | | description | +-------------------------------------------------------------------+ | 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.
"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 name | enum name | | +-------------------------------------------------------------------+ | literal integer | "value" | | | | substatement | | +-------------------------------------------------------------------+ | isLeaf = true | "enum" | UML definition "" | | isLeaf = false | substatement | | | | "identity"/"base" | | | | pattern | | +-------------------------------------------------------------------+ | <> | "reference" | | | | substatement | | +-------------------------------------------------------------------+ | <> | Ignore Example | | | | elements and all | | | | composed parts | | +-------------------------------------------------------------------+ | lifecycleState | "status" | <> -> "YANG" | | | substatement | <> | | | | "deprecated", | | | | <> | | | | description, | | | | <> | | | | description, | | | |<> | | | | description, | | | | <> | | | | "current", | | | | <> | | | | "obsolete", | | | | <> | | | | description | +-------------------------------------------------------------------+ ]]>
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 | | +-------------------------------------------------------------------+ | <> | "reference" | | | | substatement | | +-------------------------------------------------------------------+ | <> | Ignore Example | | | | elements and all | | | | composed parts | | +-------------------------------------------------------------------+ | lifecycleState | "status" | <> -> "YANG" | | | substatement | <> | | | | "deprecated", | | | | <> | | | | description, | | | | <> | | | | description, | | | |<> | | | | description, | | | | <> | | | | "current", | | | | <> | | | | "obsolete", | | | | <> | | | | description | +-------------------------------------------------------------------+ | 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?? | +-------------------------------------------------------------------+ | <> | "reference" | | | | substatement | | +-------------------------------------------------------------------+ | <> | Ignore Example | | | | elements and all | | | | composed parts | | +-------------------------------------------------------------------+ | lifecycleState | "status" | <> -> "YANG" | | | substatement | <> | | | | "deprecated", | | | | <> | | | | description, | | | | <> | | | | description, | | | |<> | | | | description, | | | | <> | | | | "current", | | | | <> | | | | "obsolete", | | | | <> | | | | description | +-------------------------------------------------------------------+ | 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. | +-------------------------------------------------------------------+ ]]>
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) | | +-------------------------------------------------------------------+ | <> | "reference" | | | | substatement | | +-------------------------------------------------------------------+ | <> | Ignore Example | | | | elements and all | | | | composed parts | | +-------------------------------------------------------------------+ | lifecycleState | "status" | <> -> "YANG" | | | substatement | <> | | | | "deprecated", | | | | <> | | | | description, | | | | <> | | | | description, | | | |<> | | | | description, | | | | <> | | | | "current", | | | | <> | | | | "obsolete", | | | | <> | | | | description | +-------------------------------------------------------------------+ | 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. | +-------------------------------------------------------------------+ | <> | "reference" | | | | substatement | | +-------------------------------------------------------------------+ | <> | Ignore Example | | | | elements and all | | | | composed parts | | +-------------------------------------------------------------------+ | lifecycleState | "status" | <> -> "YANG" | | | substatement | <> | | | | "deprecated", | | | | <> | | | | description, | | | | <> | | | | description, | | | |<> | | | | description, | | | | <> | | | | "current", | | | | <> | | | | "obsolete", | | | | <> | | | | description | +-------------------------------------------------------------------+ | 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. | +-------------------------------------------------------------------+ | Proxy Class | "choice" | | | XOR | substatement | | +-------------------------------------------------------------------+ | error notification?? | "must" | | | | substatement | | +-------------------------------------------------------------------+ | attributes | see mapping of | | | | attribute types | | | | (grouping, leaf, | | | | leaf-list, container,| | | | list, typedef, uses) | | +-------------------------------------------------------------------+ | complex attribute | "uses" | | | | substatement | | +-------------------------------------------------------------------+ ]]>
> -> "YANG" | | | substatement or | <> | | | "description" | "deprecated", | | | substatement | <> | | | | description, | | | | <> | | | | description, | | | |<> | | | | description, | | | | <> | | | | "current", | | | | <> | | | | "obsolete", | | | | <> | | | | description | +-------------------------------------------------------------------+ ]]>
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.
The associations related by the "xor" constraint are mapped to the "choice" property of the container/list statement.
The choice sterotype can be associated in UML to a class or a data type. The class or a data type which is annotated with the choice sterotype represents one of a set of classes/data types. This pattern is mapped to the "choice" property of the container/list/grouping 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; &RFC7950; &I-D.lam-teas-usage-info-model-net-topology; Unified Modeling Language (UML) OMG ONF TR-514 v1.0 UML Modeling Guidelines OMG