NETMOD Working Group S. Mansfield, Ed.
Internet-Draft Ericsson Inc.
Intended status: Informational B. Zeuner
Expires: April 30, 2017 Deutsche Telekom AG
N. Davis
Ciena
Y. Yun
Fiberhome
Y. Tochio
Fujitsu
K. Lam
E. Varma
Nokia
October 27, 2016
Guidelines for Translation of UML Information Model to YANG Data Model
draft-mansfield-netmod-uml-to-yang-03
Abstract
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.
Status of This Memo
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 April 30, 2017.
Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved.
Mansfield, et al. Expires April 30, 2017 [Page 1]
Internet-Draft Guidelines UML to YANG October 2016
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.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4. Mapping Guidelines . . . . . . . . . . . . . . . . . . . . . 4
4.1. Mapping Guideline Considerations . . . . . . . . . . . . 4
4.2. Mapping of Object Classes . . . . . . . . . . . . . . . . 4
4.3. Mapping of Attributes . . . . . . . . . . . . . . . . . . 8
4.4. Mapping of Types . . . . . . . . . . . . . . . . . . . . 11
4.4.1. Mapping of Primitive Types . . . . . . . . . . . . . 12
4.4.2. Mapping of Complex Data Types . . . . . . . . . . . . 13
4.5. Mapping of Enumeration Types . . . . . . . . . . . . . . 15
4.6. Mapping of Associations . . . . . . . . . . . . . . . . . 16
4.7. Mapping of Interfaces . . . . . . . . . . . . . . . . . . 17
4.8. Mapping of Operations . . . . . . . . . . . . . . . . . . 18
4.9. Mapping of Operation Parameters . . . . . . . . . . . . . 21
4.10. Mapping of Notifications . . . . . . . . . . . . . . . . 23
4.11. Mapping of Lifecycle . . . . . . . . . . . . . . . . . . 24
5. Mapping Patterns . . . . . . . . . . . . . . . . . . . . . . 25
5.1. UML Recursion . . . . . . . . . . . . . . . . . . . . . . 25
5.1.1. Reference Based Approach . . . . . . . . . . . . . . 25
5.2. UML Conditional Pacs . . . . . . . . . . . . . . . . . . 25
5.3. XOR Relationship . . . . . . . . . . . . . . . . . . . . 25
5.4. Choice Stereotype . . . . . . . . . . . . . . . . . . . . 26
5.5. Mapping of UML Support and Condition . . . . . . . . . . 26
6. Mapping Basics . . . . . . . . . . . . . . . . . . . . . . . 26
6.1. UML-YANG or XMI-YANG . . . . . . . . . . . . . . . . . . 26
7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 27
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27
9. Security Considerations . . . . . . . . . . . . . . . . . . . 27
10. Informative References . . . . . . . . . . . . . . . . . . . 27
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28
Mansfield, et al. Expires April 30, 2017 [Page 2]
Internet-Draft Guidelines UML to YANG October 2016
1. Introduction
As discussed in draft-lam-teas-usage-info-model-net-topology [5] 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 [6] (as constrained by the ONF's UML Modeling Guidelines [7]) to
YANG (defined in RFC6020 [1] and YANG 1.1 [4]) including mapping of
object classes, attributes, data types, associations, interfaces,
operations and operation parameters, notifications, and lifecycle.
2. Terminology
The following terms are defined in RFC6020 [1]
o anydata
o anyxml
o augment
o container
o data node
o identity
o instance identifier
o leaf
o leaf-list
o list
o module
o submodule
The following terms are defined in UML 2.4 [6]
o association
o attribute
Mansfield, et al. Expires April 30, 2017 [Page 3]
Internet-Draft Guidelines UML to YANG October 2016
o data type
o interface
o object class
o operation
o parameter
o signal (used to model notifications)
3. Overview
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.
4. Mapping Guidelines
4.1. Mapping Guideline Considerations
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.
4.2. Mapping of Object Classes
+-------------------------------------------------------------------+
| Object Class |
| - Real object classes having/inheriting at least one attribute |
| identified as "partOfObjectKey" will be mapped to a "list" |
| statement |
| - Real object classes not having/inheriting any attribute |
Mansfield, et al. Expires April 30, 2017 [Page 4]
Internet-Draft Guidelines UML to YANG October 2016
| identified as "partOfObjectKey" will be mapped to a "container" |
| statement |
| - Abstract object classes used for inheritance will be mapped |
| to a "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. |
+-------------------------------------------------------------------+
| superclass(es) | "grouping" statement | Concrete |
| | | superclasses are |
| | | then mapped to |
| | | container/list |
| | | which uses these |
| | | groupings. |
+-------------------------------------------------------------------+
| abstract | "grouping" statement | It is possible |
| | | that the |
| | | superclass or |
| | | abstract class |
| | | contains the key |
| | | attribute for the |
| | | instantiated |
| | | subclass, this |
| | | requires the |
| | | creation of the |
| | | grouping but later|
| | | when the subclass |
| | | is instantiated |
| | | the key value must|
| | | be identified from|
| | | within the |
| | | grouping. |
+-------------------------------------------------------------------+
| object identifier | list::"key" | It is possible |
| | substatement | that the super- |
| Note: Attributes used | | class or abstract |
| as object identifier | | class contains the|
| are defined in UML by | | key attribute for |
| the attribute | | the instantiated |
| property | | subclass. |
| "partOfObjectKey". | | |
Mansfield, et al. Expires April 30, 2017 [Page 5]
Internet-Draft Guidelines UML to YANG October 2016
+-------------------------------------------------------------------+
| object identifier list| | The splitting of a|
| | | list attribute |
| Does not appear in the| | (marked as key) |
| UML when mapping to | | into a single key |
| YANG. | | attribute and an |
| | | additional list |
| | | attribute will be |
| | | done in UML during|
| | | Pruning and |
| | | Refactoring. i.e.|
| | | The mapping tool |
| | | will never get a |
| | | list attribute |
| | | which is part of |
| | | the object |
| | | identifier. |
+-------------------------------------------------------------------+
| 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). |
+-------------------------------------------------------------------+
| muliplicity >1 on | list::"min-elements" | min-elements |
| association to the | "max-elements" | default = 0 |
| class | substatements | max-elements |
| | | default=unbounded|
| | | mandatory |
| | | default=false |
Mansfield, et al. Expires April 30, 2017 [Page 6]
Internet-Draft Guidelines UML to YANG October 2016
+-------------------------------------------------------------------+
| <<Reference>> | "reference" | |
| | substatement | |
+-------------------------------------------------------------------+
| <<Example>> | Ignore Example | |
| | elements and all | |
| | composed parts | |
+-------------------------------------------------------------------+
| lifecycleState | "status" | <<UML>> -> "YANG" |
| | substatement | <<Deprecated>> |
| | | "deprecated", |
| | | <<Experimental>> |
| | | description, |
| | | <<Faulty>> |
| | | description, |
| | |<<LikelyToChange>> |
| | | description, |
| | | <<Mature>> |
| | | "current", |
| | | <<Obsolete>> |
| | | "obsolete", |
| | | <<Preliminary>> |
| | | 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 | |
Mansfield, et al. Expires April 30, 2017 [Page 7]
Internet-Draft Guidelines UML to YANG October 2016
+-------------------------------------------------------------------+
| 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. |
+-------------------------------------------------------------------+
| {<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)
4.3. Mapping of Attributes
+-------------------------------------------------------------------+
| Attribute --> "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") | |
+-------------------------------------------------------------------+
Mansfield, et al. Expires April 30, 2017 [Page 8]
Internet-Draft Guidelines UML to YANG October 2016
| 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", |
Mansfield, et al. Expires April 30, 2017 [Page 9]
Internet-Draft Guidelines UML to YANG October 2016
| | 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 "/<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) | |
+-------------------------------------------------------------------+
| partOfObjectKey > 0 | list::"key" | It is possible that
| | substatement | the (abstract) |
| | | superclass contains
| | | the key attribute |
| | | for the |
| | | instantiated |
| | | subclass. |
+-------------------------------------------------------------------+
| unit | "units" substatement | |
+-------------------------------------------------------------------+
| <<Reference>> | "reference" | |
| | substatement | |
+-------------------------------------------------------------------+
| <<Example>> | Ignore Example | |
| | elements and all | |
| | composed parts | |
+-------------------------------------------------------------------+
| lifecycleState | "status" | <<UML>> -> "YANG" |
| | substatement | <<Deprecated>> |
| | | "deprecated", |
| | | <<Experimental>> |
| | | description, |
| | | <<Faulty>> |
| | | description, |
| | |<<LikelyToChange>> |
| | | description, |
| | | <<Mature>> |
| | | "current", |
| | | <<Obsolete>> |
Mansfield, et al. Expires April 30, 2017 [Page 10]
Internet-Draft Guidelines UML to YANG October 2016
| | | "obsolete", |
| | | <<Preliminary>> |
| | | 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 | |
+-------------------------------------------------------------------+
| {<constraint>} | "when" substatement | |
+-------------------------------------------------------------------+
Figure 4: Mapping of Attributes
Figure 5: Example of Attribute Mapping (Available in PDF or HTML
versions)
4.4. Mapping of Types
+-------------------------------------------------------------------+
| Types |
+-------------------------------------------------------------------+
| UML Artifact | YANG Artifact | Comment |
+-------------------------------------------------------------------+
| Primitive Type | Built-In Type if | e.g., Integer |
| | defined | |
+-------------------------------------------------------------------+
| Complex Data Type | "grouping" statement | e.g., date-time |
| | | |
+-------------------------------------------------------------------+
| Enumeration | "enum" statement | |
+-------------------------------------------------------------------+
Figure 6: Mapping of Types
Mansfield, et al. Expires April 30, 2017 [Page 11]
Internet-Draft Guidelines UML to YANG October 2016
4.4.1. Mapping of Primitive Types
+-------------------------------------------------------------------+
| Primitive Type -> "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>> | "reference" | |
| | substatement | |
+-------------------------------------------------------------------+
| <<Example>> | Ignore Example | |
| | elements and all | |
| | composed parts | |
+-------------------------------------------------------------------+
| lifecycleState | "status" | <<UML>> -> "YANG" |
| | substatement | <<Deprecated>> |
| | | "deprecated", |
| | | <<Experimental>> |
Mansfield, et al. Expires April 30, 2017 [Page 12]
Internet-Draft Guidelines UML to YANG October 2016
| | | description, |
| | | <<Faulty>> |
| | | description, |
| | |<<LikelyToChange>> |
| | | description, |
| | | <<Mature>> |
| | | "current", |
| | | <<Obsolete>> |
| | | "obsolete", |
| | | <<Preliminary>> |
| | | description |
+-------------------------------------------------------------------+
Figure 7: Mapping of Primitive Types
4.4.2. Mapping of Complex Data Types
Mansfield, et al. Expires April 30, 2017 [Page 13]
Internet-Draft Guidelines UML to YANG October 2016
+-------------------------------------------------------------------+
| Complex Data Type -> "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>> | "reference" | |
| | substatement | |
+-------------------------------------------------------------------+
| <<Example>> | Ignore Example | |
| | elements and all | |
| | composed parts | |
+-------------------------------------------------------------------+
| lifecycleState | "status" | <<UML>> -> "YANG" |
| | substatement | <<Deprecated>> |
| | | "deprecated", |
| | | <<Experimental>> |
| | | description, |
| | | <<Faulty>> |
| | | description, |
| | |<<LikelyToChange>> |
| | | description, |
| | | <<Mature>> |
| | | "current", |
| | | <<Obsolete>> |
| | | "obsolete", |
| | | <<Preliminary>> |
| | | description |
+-------------------------------------------------------------------+
| complex attribute | "uses" statement | |
+-------------------------------------------------------------------+
Figure 8: Mapping of Complex Data Types
Leaf and leaf-list can only use built-in types, typeDef types or
enumerations in their type substatement; i.e., not groupings.
Mansfield, et al. Expires April 30, 2017 [Page 14]
Internet-Draft Guidelines UML to YANG October 2016
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.
Figure 9: Example of Complex Data Type Mapping (Available in PDF or
HTML versions)
4.5. Mapping of Enumeration Types
+-------------------------------------------------------------------+
| Enumeration Type -> "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>> | "reference" | |
| | substatement | |
+-------------------------------------------------------------------+
| <<Example>> | Ignore Example | |
| | elements and all | |
| | composed parts | |
+-------------------------------------------------------------------+
| lifecycleState | "status" | <<UML>> -> "YANG" |
| | substatement | <<Deprecated>> |
| | | "deprecated", |
| | | <<Experimental>> |
| | | description, |
| | | <<Faulty>> |
Mansfield, et al. Expires April 30, 2017 [Page 15]
Internet-Draft Guidelines UML to YANG October 2016
| | | description, |
| | |<<LikelyToChange>> |
| | | description, |
| | | <<Mature>> |
| | | "current", |
| | | <<Obsolete>> |
| | | "obsolete", |
| | | <<Preliminary>> |
| | | description |
+-------------------------------------------------------------------+
Figure 10: Mapping of Enumeration Types
Figure 11: Example of Enumeration Type Mapping (Available in PDF or
HTML versions)
4.6. Mapping of Associations
+-------------------------------------------------------------------+
| Associations |
+-------------------------------------------------------------------+
| UML Artifact | YANG Artifact | Comment |
+-------------------------------------------------------------------+
| Inheritance | abstract superclass: | Multiple |
| | "grouping" statement | inheritance can |
| | | also be mapped |
| | concrete superclass: | using "groupings" |
| | "augment" statement | Need to define |
| | | when augment is |
| | | used. Note: |
| | | Augmentation can |
| | | be conditional. |
+-------------------------------------------------------------------+
| Composition with | "container" statement | How to map "passed|
| (aggregation= | containing "list" | by reference"?? |
| 'composite') | statement(s) (multiple| |
| "passed by value" | contained instances) | |
| | or "container" state- | |
| | ment(s) (single | |
| | contained instances) | |
+-------------------------------------------------------------------+
| Aggregation with | "leafref" statement | How to map "passed|
| (aggregation='shared')| | by value"?? |
| "passed by reference" | | |
+-------------------------------------------------------------------+
Figure 12: Mapping of Associations
Mansfield, et al. Expires April 30, 2017 [Page 16]
Internet-Draft Guidelines UML to YANG October 2016
Figure 13: Association Mapping Example 1 (Available in PDF or HTML
versions)
Figure 14: Association Mapping Example 2 (Available in PDF or HTML
versions)
Figure 15: Association Mapping Example 3 (Available in PDF or HTML
versions)
Figure 16: Association Mapping Example 4 (Available in PDF or HTML
versions)
Figure 17: Association Mapping Example 5 (Available in PDF or HTML
versions)
+-------------------------------------------------+
| UML |
+-------------------------------------------------+
| containment | association | inheritance |
+-------------------------------------------------------------------+
| YANG | nesting | X | | |
| +------------------------------------------------------------+
| | grouping | | | X |
| | | | |abstract superclasses|
| +------------------------------------------------------------+
| | augment | | | X |
| | | | |concrete superclasses|
| +------------------------------------------------------------+
| | leafref | | X | |
+-------------------------------------------------------------------+
Figure 18: Association Mapping Summary
4.7. Mapping of Interfaces
+-------------------------------------------------------------------+
| UML Interface -> 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" |
Mansfield, et al. Expires April 30, 2017 [Page 17]
Internet-Draft Guidelines UML to YANG October 2016
| | | substatement. |
+-------------------------------------------------------------------+
| abstract | "grouping" statement | |
+-------------------------------------------------------------------+
| <<Reference>> | "reference" | |
| | substatement | |
+-------------------------------------------------------------------+
| <<Example>> | Ignore Example | |
| | elements and all | |
| | composed parts | |
+-------------------------------------------------------------------+
| lifecycleState | "status" | <<UML>> -> "YANG" |
| | substatement | <<Deprecated>> |
| | | "deprecated", |
| | | <<Experimental>> |
| | | description, |
| | | <<Faulty>> |
| | | description, |
| | |<<LikelyToChange>> |
| | | description, |
| | | <<Mature>> |
| | | "current", |
| | | <<Obsolete>> |
| | | "obsolete", |
| | | <<Preliminary>> |
| | | 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. |
+-------------------------------------------------------------------+
Figure 19: Mapping of Interfaces (grouping of operations
4.8. Mapping 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.) |
Mansfield, et al. Expires April 30, 2017 [Page 18]
Internet-Draft Guidelines UML to YANG October 2016
+-------------------------------------------------------------------+
| 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 | <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 | |
| 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 | |
| | +--------------------------------------+ |
Mansfield, et al. Expires April 30, 2017 [Page 19]
Internet-Draft Guidelines UML to YANG October 2016
| | | 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>> | "reference" | |
| | substatement | |
+-------------------------------------------------------------------+
| <<Example>> | Ignore Example | |
| | elements and all | |
| | composed parts | |
+-------------------------------------------------------------------+
| lifecycleState | "status" | <<UML>> -> "YANG" |
| | substatement | <<Deprecated>> |
| | | "deprecated", |
| | | <<Experimental>> |
| | | description, |
| | | <<Faulty>> |
| | | description, |
| | |<<LikelyToChange>> |
| | | description, |
| | | <<Mature>> |
| | | "current", |
| | | <<Obsolete>> |
| | | "obsolete", |
| | | <<Preliminary>> |
| | | 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. |
+-------------------------------------------------------------------+
Figure 20: Mapping of Operations
Mansfield, et al. Expires April 30, 2017 [Page 20]
Internet-Draft Guidelines UML to YANG October 2016
Figure 21: Operation Mapping Example (Available in PDF or HTML
versions)
4.9. Mapping of Operation Parameters
+-------------------------------------------------------------------+
| Operation Parameters |
+-------------------------------------------------------------------+
| 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. |
+-------------------------------------------------------------------+
| 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) | |
+-------------------------------------------------------------------+
| <<Reference>> | "reference" | |
| | substatement | |
+-------------------------------------------------------------------+
| <<Example>> | Ignore Example | |
| | elements and all | |
| | composed parts | |
Mansfield, et al. Expires April 30, 2017 [Page 21]
Internet-Draft Guidelines UML to YANG October 2016
+-------------------------------------------------------------------+
| lifecycleState | "status" | <<UML>> -> "YANG" |
| | substatement | <<Deprecated>> |
| | | "deprecated", |
| | | <<Experimental>> |
| | | description, |
| | | <<Faulty>> |
| | | description, |
| | |<<LikelyToChange>> |
| | | description, |
| | | <<Mature>> |
| | | "current", |
| | | <<Obsolete>> |
| | | "obsolete", |
| | | <<Preliminary>> |
| | | 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 | |
+-------------------------------------------------------------------+
Figure 22: Mapping of Operation Parameters
Figure 23: Parameter Mapping Example (Available in PDF or HTML
versions)
Mansfield, et al. Expires April 30, 2017 [Page 22]
Internet-Draft Guidelines UML to YANG October 2016
4.10. Mapping of Notifications
+-------------------------------------------------------------------+
| Signal "grouping" statement -> "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>> | "reference" | |
| | substatement | |
+-------------------------------------------------------------------+
| <<Example>> | Ignore Example | |
| | elements and all | |
| | composed parts | |
+-------------------------------------------------------------------+
| lifecycleState | "status" | <<UML>> -> "YANG" |
| | substatement | <<Deprecated>> |
| | | "deprecated", |
| | | <<Experimental>> |
| | | description, |
| | | <<Faulty>> |
| | | description, |
| | |<<LikelyToChange>> |
| | | description, |
| | | <<Mature>> |
| | | "current", |
| | | <<Obsolete>> |
| | | "obsolete", |
| | | <<Preliminary>> |
| | | 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" | |
Mansfield, et al. Expires April 30, 2017 [Page 23]
Internet-Draft Guidelines UML to YANG October 2016
| XOR | substatement | |
+-------------------------------------------------------------------+
| error notification?? | "must" | |
| | substatement | |
+-------------------------------------------------------------------+
| attributes | see mapping of | |
| | attribute types | |
| | (grouping, leaf, | |
| | leaf-list, container,| |
| | list, typedef, uses) | |
+-------------------------------------------------------------------+
| complex attribute | "uses" | |
| | substatement | |
+-------------------------------------------------------------------+
Figure 24: Mapping of Notifications
Figure 25: Notification Mapping Example (Available in PDF or HTML
versions)
4.11. Mapping of Lifecycle
+-------------------------------------------------------------------+
| UML Lifecycle |
+-------------------------------------------------------------------+
| lifecycle stereotypes | "status" | <<UML>> -> "YANG" |
| | substatement or | <<Deprecated>> |
| | "description" | "deprecated", |
| | substatement | <<Experimental>> |
| | | description, |
| | | <<Faulty>> |
| | | description, |
| | |<<LikelyToChange>> |
| | | description, |
| | | <<Mature>> |
| | | "current", |
| | | <<Obsolete>> |
| | | "obsolete", |
| | | <<Preliminary>> |
| | | description |
+-------------------------------------------------------------------+
Figure 26: Mapping of Lifecycle
Mansfield, et al. Expires April 30, 2017 [Page 24]
Internet-Draft Guidelines UML to YANG October 2016
5. Mapping Patterns
5.1. UML Recursion
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:
o 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 [2].
o 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.
5.1.1. Reference Based Approach
Figure 27: Recursion Mapping Example 1 (Available in PDF or HTML
versions)
Figure 28: Recursion Mapping Example 2 (Available in PDF or HTML
versions)
5.2. UML Conditional Pacs
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
[3].
Figure 29: Mapping of Conditional Packages (Available in PDF or HTML
versions)
5.3. XOR Relationship
The associations related by the "xor" constraint are mapped to the
"choice" property of the container/list statement.
Figure 30: XOR Relationship Mapping Example (Available in PDF or HTML
versions)
Mansfield, et al. Expires April 30, 2017 [Page 25]
Internet-Draft Guidelines UML to YANG October 2016
5.4. Choice Stereotype
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.
Figure 31: Choice Stereotype Example (Available in PDF or HTML
versions)
5.5. Mapping of UML Support and Condition
The UML Modeling Guidelines [7] 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)
6. Mapping Basics
6.1. UML-YANG or XMI-YANG
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)
Mansfield, et al. Expires April 30, 2017 [Page 26]
Internet-Draft Guidelines UML to YANG October 2016
7. Acknowledgements
8. IANA Considerations
This memo includes no request to IANA.
9. Security Considerations
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 [1].
10. Informative References
[1] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
the Network Configuration Protocol (NETCONF)", RFC 6020,
DOI 10.17487/RFC6020, October 2010,
<http://www.rfc-editor.org/info/rfc6020>.
[2] Bjorklund, M., "A YANG Data Model for Interface
Management", RFC 7223, DOI 10.17487/RFC7223, May 2014,
<http://www.rfc-editor.org/info/rfc7223>.
[3] Bjorklund, M., "A YANG Data Model for IP Management",
RFC 7277, DOI 10.17487/RFC7277, June 2014,
<http://www.rfc-editor.org/info/rfc7277>.
[4] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016,
<http://www.rfc-editor.org/info/rfc7950>.
[5] Lam, H., Varma, E., Doolan, P., Davis, N., Zeuner, B.,
Betts, M., Busi, I., Mansfield, S., Vilata, R., and V.
Lopezalvarez, "Usage of IM for network topology to support
TE Topology YANG Module Development", draft-lam-teas-
usage-info-model-net-topology-03 (work in progress), May
2016.
[6] OMG, "Unified Modeling Language (UML)", 2011,
<http://www.omg.org/spec/UML/2.4/>.
[7] OMG, "ONF TR-514 v1.0 UML Modeling Guidelines", 2015,
<https://www.opennetworking.org/images/stories/downloads/
sdn-resources/technical-reports/
UML_Modeling_Guidelines_V1.0.pdf>.
Mansfield, et al. Expires April 30, 2017 [Page 27]
Internet-Draft Guidelines UML to YANG October 2016
Authors' Addresses
Scott Mansfield (editor)
Ericsson Inc.
USA
Phone: +1 724 931 9316
Email: scott.mansfield@ericsson.com
Bernd Zeuner
Deutsche Telekom AG
Heinrich-Hertz-Str, 3-7
Darmstadt 64295
Germany
Phone: +49 6151 58-12086
Email: b.zeuner@telekom.de
Nigel Davis
Ciena
United Kingdom
Email: ndavis@ciena.com
Yun Xiang
Fiberhome
China
Email: yunxig@fiberhome.com.cn
Yuji Tochio
Fujitsu
Japan
Email: tochio@jp.fujitsu.com
Hing-Kam Lam
Nokia
USA
Phone: +1 732 331 3476
Email: kam.lam@nokia.com
Mansfield, et al. Expires April 30, 2017 [Page 28]
Internet-Draft Guidelines UML to YANG October 2016
Eve Varma
Nokia
USA
Email: eve.varma@nokia.com
Mansfield, et al. Expires April 30, 2017 [Page 29]