NETMOD Working Group | S. Mansfield, Ed. |
Internet-Draft | Ericsson Inc. |
Intended status: Informational | B. Zeuner |
Expires: March 11, 2016 | Deutsche Telekom AG |
N. Davis | |
Ciena | |
X. Yun | |
Fiberhome | |
Y. Tochio | |
Fujitsu | |
K. Lam | |
E. Varma | |
Alcatel Lucent | |
September 8, 2015 |
Guidelines for Translation of UML Information Model to YANG Data Model
draft-mansfield-netmod-uml-to-yang-01
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.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on March 11, 2016.
Copyright (c) 2015 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 (http://trustee.ietf.org/license-info) 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.
As discussed in draft-lam-teas-usage-info-model-net-topology [I-D.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 [OMG-UML-2.4] (as constrained by the ONF's UML Modeling Guidelines [ONF-TR-514]) to YANG (defined in RFC6020 [RFC6020] and YANG Update [I-D.ietf-netmod-rfc6020bis]) including mapping of object classes, attributes, data types, associations, interfaces, operations and operation parameters, notifications, and lifecycle.
The following terms are defined in RFC6020 [RFC6020]
The following terms are defined in UML 2.4 [OMG-UML-2.4]
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.
+-------------------------------------------------------------------+ | Object Class --> "list" statement (key property, multiple | | instances) or | | "container" statement (single instance) or | | "grouping" statement | +-------------------------------------------------------------------+ | UML Artifact | YANG Artifact | Comment | +-------------------------------------------------------------------+ | documentation | "description" | | | | substatement | | +-------------------------------------------------------------------+ | superclass(es) | abstract: "grouping" | | | |not abstract:"augment"?? | +-------------------------------------------------------------------+ | abstract | "grouping" statement | | +-------------------------------------------------------------------+ | objectCreationNotific-| "notification" | Goes beyond the | | ation | statement | simple "a notific-| | [YES/NO/NA] | | ation has to be | | | | sent": a tool can | | | | construct the sig-| | | | ature of the noti-| | | | cation by reading | | | | the created | | | | object. | +-------------------------------------------------------------------+ | objectDeletionNotific-| "notification" | Goes beyond the | | ation | statement | simple "a notific-| | [YES/NO/NA] | | ation has to be | | | | sent": a tool can | | | | construct the sig-| | | | ature of the noti-| | | | cation by reading | | | | the deleted | | | | object. (i.e. not | | | | necessary to | | | | provide the | | | | attributes of the | | | | deleted object. | +-------------------------------------------------------------------+ | 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 | +-------------------------------------------------------------------+ | XOR | "choice" | | | | substatement | | +-------------------------------------------------------------------+ | constraints between | "must" substatement | | | attribute values -> | | | | error notfication?? | | | | OCL?? | | | +-------------------------------------------------------------------+ | object identifier | list::"key" | | | | 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" | "current" | | | substatement | "deprecated" | | | | "obsolete" | | | | default="current"| +-------------------------------------------------------------------+ | constraint property | list::"unique" | | | | substatement | | +-------------------------------------------------------------------+ | complex attribute | "uses" substatement | use of a complex | | | | data type as the | | | | type of the | | | | attribute; e.g., | | | | date and time, | | | | object creation | | | | data | +-------------------------------------------------------------------+ | {<constraint>} | "when" substatement | | +-------------------------------------------------------------------+
Figure 1: Mapping of Object Classes
Figure 2: Example of Abstract Object Class Mapping (Available in PDF or HTML versions)
Figure 3: Example of Non-Abstract Object Class Mapping (Available in PDF or HTML versions)
+-------------------------------------------------------------------+ | Attribute --> "leaf" (single) or "leaf list" (multiple) | | statement | +-------------------------------------------------------------------+ | UML Artifact | YANG Artifact | Comment | +-------------------------------------------------------------------+ | documentation | "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 | "range" or "length" | | | | substatement of "type"| | | | substatement | | +-------------------------------------------------------------------+ | passedByReference | if passedByReference =| Relevant only to | | | true -> type leafref {| attributes that | | | path "/<object>/ | have an object | | | <objectidentifier>"} | 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 | 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. | +-------------------------------------------------------------------+ | error notfication?? | "must" | | | | substatement | | +-------------------------------------------------------------------+ | hyperlink?? | "reference" | Papyrus doesn't | | | substatement | support hyperlinks| +-------------------------------------------------------------------+ | lifecycle stereotypes | "status" | "current" | | | substatement | "deprecated" | | | | "obsolete" | | | | default="current"| +-------------------------------------------------------------------+ | unit?? | "units" substatement | | +-------------------------------------------------------------------+ | {<constraint>} | "when" substatement | | +-------------------------------------------------------------------+
Figure 4: Mapping of Attributes
Figure 5: Example of Attribute Mapping (Available in PDF or HTML versions)
+-------------------------------------------------------------------+ | Types | +-------------------------------------------------------------------+ | UML Artifact | YANG Artifact | Comment | +-------------------------------------------------------------------+ | Primitive Type | Built-In Type if | e.g., Integer | | | defined; otherwise ?? |new built-in type??| +-------------------------------------------------------------------+ | Enumeration | "enum" statement | | +-------------------------------------------------------------------+ | Basic Data Type | "typeDef" statement | e.g., MAC address,| | | | IPv4 Address | +-------------------------------------------------------------------+ | Complex Data Type | "grouping" statement | e.g., date-time | | | | object creation | | | | data | +-------------------------------------------------------------------+
Figure 6: Mapping of Types
Note: YANG allows also in-line enumerations which are not possible in UML
+-------------------------------------------------------------------+ | Primitive Type -> new built-in type?? | +-------------------------------------------------------------------+ | UML Artifact | YANG Artifact | Comment | +-------------------------------------------------------------------+ | documentation | ?? | | +-------------------------------------------------------------------+
Figure 7: Mapping of Primitive Types
+-------------------------------------------------------------------+ | Enumeration Type -> "enum" statement | +-------------------------------------------------------------------+ | UML Artifact | YANG Artifact | Comment | +-------------------------------------------------------------------+ | documentation | "description" | | | | substatement | | +-------------------------------------------------------------------+ | literal name | "value" | | | | substatement | | +-------------------------------------------------------------------+ | hyperlink?? | "reference" | Papyrus doesn't | | | substatement | support hyperlinks| +-------------------------------------------------------------------+ | lifecycle stereotypes | "status" | "current", | | | substatement | "deprecated", | | | | "obsolete" | | | | default=current | +-------------------------------------------------------------------+ | ?? | "if-feature" statement| | +-------------------------------------------------------------------+
Figure 8: Mapping of Enumeration Types
Figure 9: Example of Enumeration Type Mapping (Available in PDF or HTML versions)
+-------------------------------------------------------------------+ | Basic Data Type -> "typeDef" statement | +-------------------------------------------------------------------+ | UML Artifact | YANG Artifact | Comment | +-------------------------------------------------------------------+ | documentation | "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 | | +-------------------------------------------------------------------+
Figure 10: Mapping of Basic Data Types
Figure 11: Example of Basic Data Type Mapping (Available in PDF or HTML versions)
+-------------------------------------------------------------------+ | Complex Data Type -> "grouping" statement | +-------------------------------------------------------------------+ | UML Artifact | YANG Artifact | Comment | +-------------------------------------------------------------------+ | documentation | "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 | | +-------------------------------------------------------------------+
Figure 12: Mapping of Complex Data Types
Figure 13: Example of Complex Data Type Mapping (Available in PDF or HTML versions)
+-------------------------------------------------------------------+ | Associations | +-------------------------------------------------------------------+ | UML Artifact | YANG Artifact | Comment | +-------------------------------------------------------------------+ | Inheritance | "grouping" or | Multiple | | | "augment" statement | inheritance can | | | | also be mapped | | | | using "groupings" | | | | Need to define | | | | when augment is | | | | used. Note: | | | | Augmentation can | | | | be conditional. | +-------------------------------------------------------------------+ | Composition with | "container" statement | How to map "passed| | "passed by value" | containing "list" | by reference"?? | | | statement(s) (multiple| | | | contained instances) | | | | or "container" state- | | | | ment(s) (single | | | | contained instances) | | +-------------------------------------------------------------------+ | Aggregation with | "leafref" statement | How to map "passed| | "passed by reference" | | by value"?? | +-------------------------------------------------------------------+
Figure 14: Mapping of Associations
Figure 15: Association Mapping Example 1 (Available in PDF or HTML versions)
Figure 16: Association Mapping Example 2 (Available in PDF or HTML versions)
Figure 17: Association Mapping Example 3 (Available in PDF or HTML versions)
+-------------------------------------------------------------------+ | UML Interface -> Container?? | +-------------------------------------------------------------------+ | documentation | "description" | | | | substatement | | +-------------------------------------------------------------------+ | abstract | ?? | | +-------------------------------------------------------------------+ | 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. | +-------------------------------------------------------------------+
Figure 18: Mapping of Interfaces (grouping of operations
+-------------------------------------------------------------------+ | Operation -> "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" | | | | substatement | | +-------------------------------------------------------------------+ | pre-condition | "extension" | RFC 6020; During | | | substatement -> | the NETCONF | | | ompExt:preCondition | <edit-config> 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 | | | | ompExt:operationExceptions | +-------------------------------------------------------------------+ | 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 | +-------------------------------------------------------------------+
Figure 19: Mapping of Operations
Figure 20: Operation Mapping Example (Available in PDF or HTML versions)
+-------------------------------------------------------------------+ | Operation Parameters | +-------------------------------------------------------------------+ | documentation | "description" | | | | substatement | | +-------------------------------------------------------------------+ | direction | "input" or "output" | | | | substatement | | +-------------------------------------------------------------------+ | type | see mapping of | | +-----------------------| attribute types |-------------------+ | isOrdered | (grouping, leaf, | | +-----------------------| leaf-list, list, |-------------------+ | multiplicity | typedef, uses) | | +-----------------------| |-------------------+ | defaultValue | | | +-----------------------| |-------------------+ | valueRange | | | +-------------------------------------------------------------------+ | passedByReference | if passedByReference =| Relevant only to | | | true -> type leafref {| attributes that | | | path "/<object>/ | have an object | | | <objectidentifier>"} | 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 | | +-------------------------------------------------------------------+
Figure 21: Mapping of Operation Parameters
Figure 22: Parameter Mapping Example (Available in PDF or HTML versions)
+-------------------------------------------------------------------+ | Signal -> "notification" statement | +-------------------------------------------------------------------+ | documentation | "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 | | +-------------------------------------------------------------------+
Figure 23: Mapping of Notifications
Figure 24: Notification Mapping Example (Available in PDF or HTML versions)
+-------------------------------------------------------------------+ | UML Lifecycle | +-------------------------------------------------------------------+ | lifecycle stereotypes | "status" | YANG: "current", | | | substatement | "deprecated", | | | | "obsolete" | | | | default=current | | | | | | | | UML: <<Example>>, | | | | <<Experimental>>, | | | | <<Faulty>>, | | | | <<Preliminary>>, | | | | <<Obsolete>>, | | | | <<LikelyToChange>>| | | | | | | | How to map or | | | | enhance?? | +-------------------------------------------------------------------+
Figure 25: Mapping of Lifecycle
+-------------------------------------------------------------------+ | UML Lifecycle | +-------------------------------------------------------------------+ | Conditional Package | "container" statement | | | | with | | | | "presence" | | | | substatement | | +-------------------------------------------------------------------+ | Package?? | Submodule | | +-------------------------------------------------------------------+
Figure 26: Other Mappings
Many common types (primitive and complex) are already defined in YANG. E.g., ietf-inet-types, ietf-yang-types (others to be investigated):
ietf-inet-types - domain name and URI types - ietf-yang-types - DomainName - Counter32 - Uri - Counter64 - <<Union>> Host - DateAndTime - types related to IP addresses and hostnames - DottedQuad - Ip4Address - Gauge32 - Ipv4AddressNoZone - Gauge64 - Ipv4Prefix - HexString - Ipv6Address - MacAddress - Ipv6AddressNoZone - ObjectIdentifier - Ipv6Prefix - ObjectIdentifier128 - <<Union>> IpAddress - PhysAddress - <<Union>> IpAddressNoZone - Timestamp - <<Union>> IpPrefix - Timeticks - types related to protocol fields - Uuid - IpVersion - Xpath1.0 - DSCP - YangIdentifier - IpV6FlowLabel - ZeroBasedCounter32 - PortNumber - ZeroBasedCounter64
Figure 27: Re-engineered Example
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.
Figure 28: IP Address Mapping Examples (Available in PDF or HTML versions)
YANG 1.0 is approved and defined in RFC6020 [RFC6020].
YANG 1.1 is not currently approved and its definition is ongoing in draft-ietf-netmod-rfc6020bis [I-D.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 [I-D.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:
Figure 29: Reference Based Approach (Available in PDF or HTML versions)
Figure 30: Specific Number of Recusions (Available in PDF or HTML versions)
The reference-based approach is generally preferred because there is no arbitrary limitation set in the solution.
May use the "presence" property of the container statement?
Figure 31: Mapping of Conditional Packages (Available in PDF or HTML versions)
Use the "choice" property of the container statement.
The UML Modeling Guidelines [ONF-TR-514] 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.
Figure 32: Support and Condition Mapping Example (Available in PDF or HTML versions)
Figure 33: Example UML to YANG Mapping (Available in PDF or HTML versions)
Figure 34: Example XMI (Papyrus) to YANG Mapping (Available in PDF or HTML versions)
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].
The YANG data schema (in tree format) shown below was extracted from dharini-netmod-g-698-2-yang [I-D.dharini-netmod-g-698-2-yang] and represents the same data as UML model appearing in Figure 37 after the tree format. Note: The color code used in the tree format corresponds to the color code used in the UML class diagram.
Figure 35: Interfaces Tree (Available in PDF or HTML versions)
Figure 36: Notifications Tree (Available in PDF or HTML versions)
Figure 37: Interfaces UML Model (Available in PDF or HTML versions)