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

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 March 11, 2016.

Copyright Notice

   Copyright (c) 2015 IETF Trust and the persons identified as the
   document authors.  All rights reserved.




Mansfield, et al.        Expires March 11, 2016                 [Page 1]

Internet-Draft           Guidelines UML to YANG           September 2015


   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 . . . . . . . . . . . . . . . . . .   7
     4.4.  Mapping of Types  . . . . . . . . . . . . . . . . . . . .   9
       4.4.1.  Mapping of Primitive Types  . . . . . . . . . . . . .   9
       4.4.2.  Mapping of Enumeration Types  . . . . . . . . . . . .  10
       4.4.3.  Mapping of Basic Data Types . . . . . . . . . . . . .  10
       4.4.4.  Mapping of Complex Data Types . . . . . . . . . . . .  11
     4.5.  Mapping of Associations . . . . . . . . . . . . . . . . .  12
     4.6.  Mapping of Interfaces . . . . . . . . . . . . . . . . . .  13
     4.7.  Mapping of Operations . . . . . . . . . . . . . . . . . .  14
     4.8.  Mapping of Operation Parameters . . . . . . . . . . . . .  16
     4.9.  Mapping of Notifications  . . . . . . . . . . . . . . . .  17
     4.10. Mapping of Lifecycle  . . . . . . . . . . . . . . . . . .  19
     4.11. Other Mappings  . . . . . . . . . . . . . . . . . . . . .  19
   5.  Mapping Issues  . . . . . . . . . . . . . . . . . . . . . . .  19
     5.1.  Using types defined in YANG . . . . . . . . . . . . . . .  19
     5.2.  YANG 1.0 or YANG 1.1  . . . . . . . . . . . . . . . . . .  20
     5.3.  Mapping of UML Packages . . . . . . . . . . . . . . . . .  20
   6.  Mapping Patterns  . . . . . . . . . . . . . . . . . . . . . .  21
     6.1.  UML Recursion . . . . . . . . . . . . . . . . . . . . . .  21
     6.2.  UML Conditional Pacs  . . . . . . . . . . . . . . . . . .  21
     6.3.  XOR Relationship  . . . . . . . . . . . . . . . . . . . .  21
     6.4.  Mapping of UML Support and Condition  . . . . . . . . . .  21
   7.  Mapping Basics  . . . . . . . . . . . . . . . . . . . . . . .  22
     7.1.  UML-YANG or XMI-YANG  . . . . . . . . . . . . . . . . . .  22
   8.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  22
   9.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  22
   10. Security Considerations . . . . . . . . . . . . . . . . . . .  22
   11. Informative References  . . . . . . . . . . . . . . . . . . .  22
   Appendix A.  Example  . . . . . . . . . . . . . . . . . . . . . .  23
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  24



Mansfield, et al.        Expires March 11, 2016                 [Page 2]

Internet-Draft           Guidelines UML to YANG           September 2015


1.  Introduction

   As discussed in draft-lam-teas-usage-info-model-net-topology [6] 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 [7] (as constrained by the ONF's UML Modeling Guidelines [8]) to
   YANG (defined in RFC6020 [1] and YANG Update [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 [7]

   o  association

   o  attribute



Mansfield, et al.        Expires March 11, 2016                 [Page 3]

Internet-Draft           Guidelines UML to YANG           September 2015


   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 --> "list" statement (key property, multiple   |
   |                           instances) or                           |
   |                        "container" statement (single instance) or |
   |                        "grouping" statement                       |
   +-------------------------------------------------------------------+



Mansfield, et al.        Expires March 11, 2016                 [Page 4]

Internet-Draft           Guidelines UML to YANG           September 2015


   | 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 |



Mansfield, et al.        Expires March 11, 2016                 [Page 5]

Internet-Draft           Guidelines UML to YANG           September 2015


   |                       |                       | 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   |                   |
   +-------------------------------------------------------------------+




Mansfield, et al.        Expires March 11, 2016                 [Page 6]

Internet-Draft           Guidelines UML to YANG           September 2015


                    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"         |                   |
   |                       | 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|



Mansfield, et al.        Expires March 11, 2016                 [Page 7]

Internet-Draft           Guidelines UML to YANG           September 2015


   |                       | 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"        |



Mansfield, et al.        Expires March 11, 2016                 [Page 8]

Internet-Draft           Guidelines UML to YANG           September 2015


   |                       |                       |  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)

4.4.  Mapping of Types

   +-------------------------------------------------------------------+
   |                             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

4.4.1.  Mapping of Primitive Types












Mansfield, et al.        Expires March 11, 2016                 [Page 9]

Internet-Draft           Guidelines UML to YANG           September 2015


   +-------------------------------------------------------------------+
   |               Primitive Type -> new built-in type??               |
   +-------------------------------------------------------------------+
   | UML Artifact          | YANG Artifact         | Comment           |
   +-------------------------------------------------------------------+
   | documentation         | ??                    |                   |
   +-------------------------------------------------------------------+

                   Figure 7: Mapping of Primitive Types

4.4.2.  Mapping of Enumeration 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)

4.4.3.  Mapping of Basic Data Types










Mansfield, et al.        Expires March 11, 2016                [Page 10]

Internet-Draft           Guidelines UML to YANG           September 2015


   +-------------------------------------------------------------------+
   |               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)

4.4.4.  Mapping of Complex Data Types














Mansfield, et al.        Expires March 11, 2016                [Page 11]

Internet-Draft           Guidelines UML to YANG           September 2015


   +-------------------------------------------------------------------+
   |               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)

4.5.  Mapping of Associations




















Mansfield, et al.        Expires March 11, 2016                [Page 12]

Internet-Draft           Guidelines UML to YANG           September 2015


   +-------------------------------------------------------------------+
   |                          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)

4.6.  Mapping of Interfaces









Mansfield, et al.        Expires March 11, 2016                [Page 13]

Internet-Draft           Guidelines UML to YANG           September 2015


   +-------------------------------------------------------------------+
   |                     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

4.7.  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.)                                  |
   +-------------------------------------------------------------------+
   | 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  |



Mansfield, et al.        Expires March 11, 2016                [Page 14]

Internet-Draft           Guidelines UML to YANG           September 2015


   |                       |                       |   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)



Mansfield, et al.        Expires March 11, 2016                [Page 15]

Internet-Draft           Guidelines UML to YANG           September 2015


4.8.  Mapping of Operation Parameters

   +-------------------------------------------------------------------+
   |                      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          |                   |
   +-------------------------------------------------------------------+



Mansfield, et al.        Expires March 11, 2016                [Page 16]

Internet-Draft           Guidelines UML to YANG           September 2015


   | 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)

4.9.  Mapping of Notifications





































Mansfield, et al.        Expires March 11, 2016                [Page 17]

Internet-Draft           Guidelines UML to YANG           September 2015


   +-------------------------------------------------------------------+
   |                 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)





Mansfield, et al.        Expires March 11, 2016                [Page 18]

Internet-Draft           Guidelines UML to YANG           September 2015


4.10.  Mapping of Lifecycle

   +-------------------------------------------------------------------+
   |                          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

4.11.  Other Mappings

   +-------------------------------------------------------------------+
   |                          UML Lifecycle                            |
   +-------------------------------------------------------------------+
   | Conditional Package   | "container" statement |                   |
   |                       | with                  |                   |
   |                       | "presence"            |                   |
   |                       | substatement          |                   |
   +-------------------------------------------------------------------+
   | Package??             | Submodule             |                   |
   +-------------------------------------------------------------------+

                         Figure 26: Other Mappings

5.  Mapping Issues

5.1.  Using types defined in YANG

   Many common types (primitive and complex) are already defined in
   YANG.  E.g., ietf-inet-types, ietf-yang-types (others to be
   investigated):






Mansfield, et al.        Expires March 11, 2016                [Page 19]

Internet-Draft           Guidelines UML to YANG           September 2015


   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)

5.2.  YANG 1.0 or YANG 1.1

   YANG 1.0 is approved and defined in RFC6020 [1].

   YANG 1.1 is not currently approved and its definition is ongoing in
   draft-ietf-netmod-rfc6020bis [4].  Main enhancements are the action
   and anydata statements.

5.3.  Mapping of UML Packages

   Need to define mapping rules for UML package into YANG modules or the
   new draft YANG package statement (draft-bierman-netmod-yang-package
   [3])?





Mansfield, et al.        Expires March 11, 2016                [Page 20]

Internet-Draft           Guidelines UML to YANG           September 2015


6.  Mapping Patterns

6.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 - 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].  See example in
      Figure 29 below.

   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.  See example in
      Figure 30 below, in which there is one level of recursion.


       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.

6.2.  UML Conditional Pacs

   May use the "presence" property of the container statement?


   Figure 31: Mapping of Conditional Packages (Available in PDF or HTML
                                 versions)

6.3.  XOR Relationship

   Use the "choice" property of the container statement.

6.4.  Mapping of UML Support and Condition

   The UML Modeling Guidelines [8] define support and condition for all
   UML artifacts (M - Mandatory, O - Optional, C - Conditional, CM -
   Conditional-Mandatory, CO - Conditional-Optional).  Support qualifies




Mansfield, et al.        Expires March 11, 2016                [Page 21]

Internet-Draft           Guidelines UML to YANG           September 2015


   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)

7.  Mapping Basics

7.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)

8.  Acknowledgements

9.  IANA Considerations

   This memo includes no request to IANA.

10.  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].

11.  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>.





Mansfield, et al.        Expires March 11, 2016                [Page 22]

Internet-Draft           Guidelines UML to YANG           September 2015


   [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]        Bierman, A., "The YANG Package Statement", draft-bierman-
              netmod-yang-package-00 (work in progress), July 2015.

   [4]        Bjorklund, M., "YANG - A Data Modeling Language for the
              Network Configuration Protocol (NETCONF)", draft-ietf-
              netmod-rfc6020bis-06 (work in progress), July 2015.

   [5]        Galimberti, G., Kunze, R., Lam, H., Hiremagalur, D.,
              Grammel, G., Fang, L., and G. Ratterree, "A YANG model to
              manage the optical interface parameters of "G.698.2 single
              channel" in DWDM applications", draft-dharini-netmod-
              g-698-2-yang-04 (work in progress), July 2015.

   [6]        Lam, H., Varma, E., Doolan, P., Davis, N., Zeuner, B.,
              Betts, M., Busi, I., and S. Mansfield, "Usage of IM for
              network topology to support TE Topology YANG Module
              Development", draft-lam-teas-usage-info-model-net-
              topology-01 (work in progress), July 2015.

   [7]        OMG, "Unified Modeling Language (UML)", 2011,
              <http://www.omg.org/spec/UML/2.4/>.

   [8]        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>.

Appendix A.  Example

   The YANG data schema (in tree format) shown below was extracted from
   dharini-netmod-g-698-2-yang [5] 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)




Mansfield, et al.        Expires March 11, 2016                [Page 23]

Internet-Draft           Guidelines UML to YANG           September 2015


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


   Xiang Yun
   Fiberhome
   China

   Email: yunxig@fiberhome.com.cn


   Yuji Tochio
   Fujitsu
   Japan

   Email: tochio@jp.fujitsu.com


   Hing-Kam Lam
   Alcatel Lucent
   USA

   Phone: +1 732 331 3476
   Email: kam.lam@alcatel-lucent.com




Mansfield, et al.        Expires March 11, 2016                [Page 24]

Internet-Draft           Guidelines UML to YANG           September 2015


   Eve Varma
   Alcatel Lucent
   USA

   Email: eve.varma@alcatel-lucent.com














































Mansfield, et al.        Expires March 11, 2016                [Page 25]