NETMOD Working Group S. Mansfield, Ed. Internet-Draft Ericsson Inc. Intended status: Informational B. Zeuner Expires: September 19, 2016 Deutsche Telekom AG N. Davis Ciena Y. Yun Fiberhome Y. Tochio Fujitsu K. Lam E. Varma Alcatel Lucent March 18, 2016 Guidelines for Translation of UML Information Model to YANG Data Model draft-mansfield-netmod-uml-to-yang-02 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 September 19, 2016. Copyright Notice Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved. Mansfield, et al. Expires September 19, 2016 [Page 1] Internet-Draft Guidelines UML to YANG March 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 . . . . . . . . . . . . . . . . 5 4.3. Mapping of Attributes . . . . . . . . . . . . . . . . . . 8 4.4. Mapping of Types . . . . . . . . . . . . . . . . . . . . 12 4.4.1. Mapping of Primitive Types . . . . . . . . . . . . . 12 4.4.2. Mapping of Enumeration Types . . . . . . . . . . . . 13 4.4.3. Mapping of Basic Data Types . . . . . . . . . . . . . 13 4.4.4. Mapping of Complex Data Types . . . . . . . . . . . . 14 4.5. Mapping of Associations . . . . . . . . . . . . . . . . . 15 4.6. Mapping of Interfaces . . . . . . . . . . . . . . . . . . 17 4.7. Mapping of Operations . . . . . . . . . . . . . . . . . . 18 4.8. Mapping of Operation Parameters . . . . . . . . . . . . . 20 4.9. Mapping of Notifications . . . . . . . . . . . . . . . . 21 4.10. Mapping of Lifecycle . . . . . . . . . . . . . . . . . . 23 4.11. Other Mappings . . . . . . . . . . . . . . . . . . . . . 23 5. Mapping Issues . . . . . . . . . . . . . . . . . . . . . . . 23 5.1. Using types defined in YANG? . . . . . . . . . . . . . . 23 5.2. YANG 1.0 or YANG 1.1 . . . . . . . . . . . . . . . . . . 24 5.3. Mapping of UML Packages . . . . . . . . . . . . . . . . . 24 5.4. Combination of different Associations . . . . . . . . . . 25 6. Mapping Patterns . . . . . . . . . . . . . . . . . . . . . . 25 6.1. UML Recursion . . . . . . . . . . . . . . . . . . . . . . 25 6.1.1. Reference Based Approach . . . . . . . . . . . . . . 25 6.2. UML Conditional Pacs . . . . . . . . . . . . . . . . . . 25 6.3. XOR Relationship . . . . . . . . . . . . . . . . . . . . 26 6.4. Mapping of UML Support and Condition . . . . . . . . . . 26 7. Mapping Basics . . . . . . . . . . . . . . . . . . . . . . . 26 7.1. UML-YANG or XMI-YANG . . . . . . . . . . . . . . . . . . 26 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 26 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 10. Security Considerations . . . . . . . . . . . . . . . . . . . 26 11. Informative References . . . . . . . . . . . . . . . . . . . 27 Mansfield, et al. Expires September 19, 2016 [Page 2] Internet-Draft Guidelines UML to YANG March 2016 Appendix A. Example . . . . . . . . . . . . . . . . . . . . . . 27 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 1. Introduction As discussed in draft-lam-teas-usage-info-model-net-topology [7] 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 [8] (as constrained by the ONF's UML Modeling Guidelines [9]) to YANG (defined in RFC6020 [1] and YANG Update [5]) 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 [8] Mansfield, et al. Expires September 19, 2016 [Page 3] Internet-Draft Guidelines UML to YANG March 2016 o association o attribute 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. Mansfield, et al. Expires September 19, 2016 [Page 4] Internet-Draft Guidelines UML to YANG March 2016 4.2. Mapping of Object Classes +-------------------------------------------------------------------+ | Object Class | | - Real object classes having/inheriting at least one attribute | | identified as "identifier" will be mapped to a "list" statement | | - Real object classes not having/inheriting any attribute | | identified as "identifier" 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 | Mansfield, et al. Expires September 19, 2016 [Page 5] Internet-Draft Guidelines UML to YANG March 2016 | | 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". | | | +-------------------------------------------------------------------+ | 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). | Mansfield, et al. Expires September 19, 2016 [Page 6] Internet-Draft Guidelines UML to YANG March 2016 +-------------------------------------------------------------------+ | support | "if-feature" | Support and | | | substatement | condition belong | +-----------------------+ | together. If the | | condition | | "support" is cond-| | | | itional, then the | | | | "condition" | | | | explains the cond-| | | | itions under which| | | | the class has to | | | | be supported. | +-------------------------------------------------------------------+ | operation | "action" | YANG 1.0 supports | | | substatement | only rpc -> add | | | | prefix to the rpc | | | | name; i.e. | | | | objectClass::rpc; | | | | "action" requires | | | | YANG 1.1 | +-------------------------------------------------------------------+ | XOR | "choice" | | | | substatement | | +-------------------------------------------------------------------+ | muliplicity on | list::"min-elements" | min-elements | | association | "max-elements" | default = 0 | | | substatements | max-elements | | | | default=unbounded| | | | mandatory | | | | default=false | +-------------------------------------------------------------------+ | Conditional PACs | container::presence" | | | | substatement | | +-------------------------------------------------------------------+ | hyperlink?? | "reference" | Papyrus doesn't | | | substatement | support hyperlinks| +-------------------------------------------------------------------+ | lifecycle stereotypes | "status" | UML: | | | substatement | <>, | | | | <>, | | | | <>, | | | |<>,| | | | <>, | | | | <>, | | | | <> | | | | YANG: | | | | "current", | | | | "deprecated", | | | | "obsolete", | Mansfield, et al. Expires September 19, 2016 [Page 7] Internet-Draft Guidelines UML to YANG March 2016 | | | default="current" | +-------------------------------------------------------------------+ | constraint property | list::"unique" | UML is not able to| | | substatement | define a group | | | | of attributes to be | | | unique as YANG can| | | | do using the | | | | "unique" | | | | substatement. | +-------------------------------------------------------------------+ | abstract superclass/ | "uses" substatement | use of a complex | | inheritance | | data type as the | | | | type of the | | complex attribute | | attribute; e.g., | | | | date and time, | | | | object creation | | | | data | | | | It is possible that | | | the superclass or | | | | abstract class | | | | contains the key | | | | attribute for the | | | | instantiated | | | | subclass. | +-------------------------------------------------------------------+ | {} | "when" substatement | | +-------------------------------------------------------------------+ 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 | Mansfield, et al. Expires September 19, 2016 [Page 8] Internet-Draft Guidelines UML to YANG March 2016 | (carried in XMI as | | in UML, need to be| | "ownedComment") | | collapsed into a | | | | single | | | | "description" | | | | substatement. | +-------------------------------------------------------------------+ | type | "type" substatement | | | | (built-in or derived) | | +-------------------------------------------------------------------+ | readOnly | "config" substatement | config | | | (false) | default = true | +-------------------------------------------------------------------+ | isOrdered | "ordered-by" | ordered-by | | | substatement | default = system | | |("system" or "user") | | +-------------------------------------------------------------------+ | multiplicity | "mandatory" or | min-elements | | | "min-elements" and | default = 0 | | | "max-elements" | max-elements | | | substatements | default=unbounded| | | [0..1]=>no mapping | mandatory | | | needed; is default | default=false | | | substatement=false | | | | [1]=>mandatory | | | | substatement=true | | | | [0..x]=> no mapping | | | | needed; is default | | | | [1..x]=> min-elements | | | | substatement = 1 | | | | [0..3]=> max-elements | | | | substatement = 3 | | +-------------------------------------------------------------------+ | defaultValue | "default" | If a default value| | | substatement | exists and it is | | | | the desired value,| | | | the parameter does| | | | not have to be | | | | explicitly config-| | | | ured by the user. | +-------------------------------------------------------------------+ | isInvariant | "extension" | | | | substatement -> | | | | ompExt:isInvariant | | +-------------------------------------------------------------------+ | valueRange | "pattern", "range", or| | | | "length" substatement | | | | of "type" substatement| | +-------------------------------------------------------------------+ Mansfield, et al. Expires September 19, 2016 [Page 9] Internet-Draft Guidelines UML to YANG March 2016 | passedByReference | if passedByReference =| Relevant only to | | | true -> type leafref {| attributes that | | | path "// | have an object | | | "} | class defined as | | | | their type. | | | if passedByReference =| | | | false -> either "list"| | | | statement (key | | | | property, multiple | | | | instances) or | | | | "container" statement(| | | | single instance) | | +-------------------------------------------------------------------+ | partOfObjectKey > 0 | list::"key" | It is possible that | | substatement | the (abstract) | | | | superclass contains | | | the key attribute | | | | for the | | | | instantiated | | | | subclass. | +-------------------------------------------------------------------+ | unit | "units" substatement | Need to discuss | | | | with the YANG | | | | community about a | | | | standard way to | | | | express units (e.g. | | | kilobitspersecond,| | | | kbit/s, | | | | kilobits/second, | | | | kbit/sec). | | | | | | | | Current | | | | description of the| | | | new "unit" property | | | in OpenModelProfile | | | v0.2.1 is: | | | | "This optional | | | | property contains a | | | textual definition| | | | of the unit | | | | associated with the | | | attribute value. | | | | The spelling of the | | | unit, including the | | | ones beyond SI | | | | scope, shall be in| | | | accordance to the | | | | NIST Publication | Mansfield, et al. Expires September 19, 2016 [Page 10] Internet-Draft Guidelines UML to YANG March 2016 | | | 811 "Guide for the| | | | Use of the | | | | International | | | | System of Units | | | | (SI)" (http://www.| | | | nist.gov/pml/pubs/| | | | sp811/index.cfm), | | | | section 9 "Rules | | | | and Style | | | | Conventions for | | | | Spelling Unit | | | | Names"." | +-------------------------------------------------------------------+ | support | For conditional | Support and | | | support only: | condition belong | +-----------------------+ | together. If the | | condition | "if-feature" | "support" is cond-| | | substatement | itional, then the | | | | "condition" | | | "when" substatement if| explains the cond-| | | condition can be | itions under which| | | formalized as XPath | the class has to | | | expression (i.e., it | be supported. | | | is conditioned by the | | | | value of another | | | | attribute) | | +-------------------------------------------------------------------+ | error notfication?? | "must" | | | | substatement | | +-------------------------------------------------------------------+ | hyperlink?? | "reference" | Papyrus doesn't | | | substatement | support hyperlinks| +-------------------------------------------------------------------+ | lifecycle stereotypes | "status" | "current" | | | substatement | "deprecated" | | | | "obsolete" | | | | default="current"| +-------------------------------------------------------------------+ | {} | "when" substatement | | +-------------------------------------------------------------------+ Figure 4: Mapping of Attributes Figure 5: Example of Attribute Mapping (Available in PDF or HTML versions) Mansfield, et al. Expires September 19, 2016 [Page 11] Internet-Draft Guidelines UML to YANG March 2016 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 4.4.1. Mapping of Primitive Types +-------------------------------------------------------------------+ | Primitive Type -> new built-in type?? | +-------------------------------------------------------------------+ | UML Artifact | YANG Artifact | Comment | +-------------------------------------------------------------------+ | documentation | Description field | | | (carried in XMI as | | | | "ownedComment") | | | +-------------------------------------------------------------------+ | Integer | int64 | | +-------------------------------------------------------------------+ | Boolean | boolean | | +-------------------------------------------------------------------+ | String | string | | +-------------------------------------------------------------------+ | Real | ?? | | +-------------------------------------------------------------------+ Figure 7: Mapping of Primitive Types Mansfield, et al. Expires September 19, 2016 [Page 12] Internet-Draft Guidelines UML to YANG March 2016 4.4.2. 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 integer | "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 September 19, 2016 [Page 13] Internet-Draft Guidelines UML to YANG March 2016 +-------------------------------------------------------------------+ | Basic Data 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) | | +-------------------------------------------------------------------+ | 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 September 19, 2016 [Page 14] Internet-Draft Guidelines UML to YANG March 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 | | +-------------------------------------------------------------------+ | 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 Leaf and leaf-list can only use built-in types, typeDef types or enumerations in their type substatement; i.e., not groupings. Complex data types with more than one item (e.g., name value pair) can only be defined using groupings. Groupings can only be used by grouping, container and list statements. Figure 13: Example of Complex Data Type Mapping (Available in PDF or HTML versions) 4.5. Mapping of Associations Mansfield, et al. Expires September 19, 2016 [Page 15] Internet-Draft Guidelines UML to YANG March 2016 +-------------------------------------------------------------------+ | 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 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) Mansfield, et al. Expires September 19, 2016 [Page 16] Internet-Draft Guidelines UML to YANG March 2016 +-------------------------------------------------+ | UML | +-------------------------------------------------+ | containment | association | inheritance | +-------------------------------------------------------------------+ | YANG | nesting | X | | | | +------------------------------------------------------------+ | | grouping | | | X | | | | | |abstract superclasses| | +------------------------------------------------------------+ | | augment | | | X | | | | | |concrete superclasses| | +------------------------------------------------------------+ | | leafref | | X | | +-------------------------------------------------------------------+ Figure 18: Association Mapping Summary 4.6. 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" | | | | substatement. | +-------------------------------------------------------------------+ | abstract | "grouping" statement | | +-------------------------------------------------------------------+ | support | "if-feature" | Support and | | | substatement | condition belong | +-----------------------+ | together. If the | | condition | | "support" is cond-| | | | itional, then the | | | | "condition" | | | | explains the cond-| | | | itions under which| | | | the class has to | | | | be supported. | +-------------------------------------------------------------------+ Figure 19: Mapping of Interfaces (grouping of operations Mansfield, et al. Expires September 19, 2016 [Page 17] Internet-Draft Guidelines UML to YANG March 2016 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" | Multiple "applied | | "Applied comments" | substatement | comments" defined | | (carried in XMI as | | in UML, need to be| | "ownedComment") | | collapsed into a | | | | single | | | | "description" | | | | substatement. | +-------------------------------------------------------------------+ | pre-condition | "extension" | RFC 6020; During | | | substatement -> | the NETCONF | | | ompExt:preCondition | pro-| | | | cessing errors are| | | | already sent for: | | | | - Delete requests | | | | for non-existent| | | | data. | | | | - Create requests | | | | for existing | | | | data. | | | | - Insert requests | | | | with "before" or| | | | "after" para- | | | | meters that do | | | | not exist. | +-------------------------------------------------------------------+ | post-condition | "extension" | | | | substatement | | | | ompExt:postCondition | | +-------------------------------------------------------------------+ | input parameter | "input" substatement | | +-------------------------------------------------------------------+ | output parameter | "output" substatement | | +-------------------------------------------------------------------+ | operation exceptions | "extension" | | | | substatement | | | Internal Error | ompExt:operationExceptions | | Unable to Comply | | | Comm Loss | +--------------------------------------+ | | Invalid Input | | error-tag | error-app-tag | | | Not Implemented | +--------------------------------------+ | Mansfield, et al. Expires September 19, 2016 [Page 18] Internet-Draft Guidelines UML to YANG March 2016 | Duplicate | | operation-failed | too-many-elements | | | Entity Not Found | | | too-few-elements | | | Object In Use | | | must-violation | | | Capacity Exceeded | +--------------------------------------+ | | Not In Valid State | | data-missing | instance-required | | | Access Denied | | | missing-choice | | | | +--------------------------------------+ | | | | bad-attribute | missing-instance | | | | +--------------------------------------+ | +-------------------------------------------------------------------+ | isOperationIdempotent | "extension" | | | | substatement | | | | ompExt:isOperationIdempotent | +-------------------------------------------------------------------+ | isAtomic | "extension" | Necessary?? Not in| | | substatement | UML Guidelines | | | ompExt:isAtomic | (TR-514); needs to| | | | be added?? | +-------------------------------------------------------------------+ | support | "if-feature" | Support and | | | substatement | condition belong | +-----------------------+ | together. If the | | condition | | "support" is cond-| | | | itional, then the | | | | "condition" | | | | explains the cond-| | | | itions under which| | | | the class has to | | | | be supported. | +-------------------------------------------------------------------+ | hyperlink?? | "reference" | Papyrus doesn't | | | substatement | support hyperlinks| +-------------------------------------------------------------------+ | lifecycle stereotypes | "status" | "current", | | | substatement | "deprecated", | | | | "obsolete" | | | | default=current | +-------------------------------------------------------------------+ Figure 20: Mapping of Operations Figure 21: Operation Mapping Example (Available in PDF or HTML versions) Mansfield, et al. Expires September 19, 2016 [Page 19] Internet-Draft Guidelines UML to YANG March 2016 4.8. 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 "// | have an object | | | "} | class defined as | | | | their type. | | | if passedByReference =| | | | false -> either "list"| | | | statement (key | | | | property, multiple | | | | instances) or | | | | "container" statement(| | | | single instance) | | +-------------------------------------------------------------------+ | support | "if-feature" | Support and | | | substatement not | condition belong | +-----------------------+ defined for input and | together. If the | | condition | output substatements | "support" is cond-| | | in YANG?? | itional, then the | | | | "condition" | | | | explains the cond-| | | | itions under which| | | | the class has to | Mansfield, et al. Expires September 19, 2016 [Page 20] Internet-Draft Guidelines UML to YANG March 2016 | | | 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) 4.9. Mapping of Notifications Mansfield, et al. Expires September 19, 2016 [Page 21] Internet-Draft Guidelines UML to YANG March 2016 +-------------------------------------------------------------------+ | Signal -> "notification" statement | +-------------------------------------------------------------------+ | documentation | "description" | Multiple "applied | | "Applied comments" | substatement | comments" defined | | (carried in XMI as | | in UML, need to be| | "ownedComment") | | collapsed into a | | | | single | | | | "description" | | | | substatement. | +-------------------------------------------------------------------+ | support | "if-feature" | Support and | | | substatement | condition belong | +-----------------------+ | together. If the | | condition | | "support" is cond-| | | | itional, then the | | | | "condition" | | | | explains the cond-| | | | itions under which| | | | the class has to | | | | be supported. | +-------------------------------------------------------------------+ | XOR | "choice" | | | | substatement | | +-------------------------------------------------------------------+ | error notification?? | "must" | | | | substatement | | +-------------------------------------------------------------------+ | hyperlink?? | "reference" | Papyrus doesn't | | | substatement | support hyperlinks| +-------------------------------------------------------------------+ | lifecycle stereotypes | "status" | "current", | | | substatement | "deprecated", | | | | "obsolete" | | | | default=current | +-------------------------------------------------------------------+ | attributes | see mapping of | | | | attribute types | | | | (grouping, leaf, | | | | leaf-list, container,| | | | list, typedef, uses) | | +-------------------------------------------------------------------+ | complex attribute | "uses" | | | | substatement | | +-------------------------------------------------------------------+ Figure 24: Mapping of Notifications Mansfield, et al. Expires September 19, 2016 [Page 22] Internet-Draft Guidelines UML to YANG March 2016 Figure 25: Notification Mapping Example (Available in PDF or HTML versions) 4.10. Mapping of Lifecycle +-------------------------------------------------------------------+ | UML Lifecycle | +-------------------------------------------------------------------+ | lifecycle stereotypes | "status" | YANG: "current", | | | substatement | "deprecated", | | | | "obsolete" | | | | default=current | | | | | | | | UML: <>, | | | | <>, | | | | <>, | | | | <>, | | | | <>, | | | | <>| | | | | | | | How to map or | | | | enhance?? | +-------------------------------------------------------------------+ Figure 26: Mapping of Lifecycle 4.11. Other Mappings +-------------------------------------------------------------------+ | UML Lifecycle | +-------------------------------------------------------------------+ | Conditional Package | "container" statement | | | | with | | | | "presence" | | | | substatement | | +-------------------------------------------------------------------+ | Package?? | Submodule | | +-------------------------------------------------------------------+ Figure 27: 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 September 19, 2016 [Page 23] Internet-Draft Guidelines UML to YANG March 2016 + ietf-inet-type + domain name and URI types + ietf-yang-types - DomainName - Counter32 - Uri - Counter64 - <> Host - DateAndTime + types related to - DottedQuad IP addresses and hostnames - Gauge32 - Ipv4Address - Gauge64 - Ipv4AddressNoZone - HexString - Ipv4Prefix - MacAddress - Ipv6Address - ObjectIdentifier - Ipv6AddressNoZone - ObjectIdentifier128 - Ipv6Prefix - PhysAddress - <> IpAddress - Timestamp - <> IpAddressNoZone - Timeticks - <> IpPrefix - Uuid + types related to protocol fields - Xpath1.0 - IpVersion - YangIdentifier - DSCP - ZeroBasedCounter32 - IpV6FlowLabel - ZeroBasedCounter64 - PortNumber Figure 28: 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 29: IP Address Mapping Example (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 [5]. 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 [4])? Mansfield, et al. Expires September 19, 2016 [Page 24] Internet-Draft Guidelines UML to YANG March 2016 5.4. Combination of different Associations Figure 30: Combination of different Associations Example (Available in PDF or HTML versions) 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 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. 6.1.1. Reference Based Approach Figure 31: Recursion Mapping Example 1 (Available in PDF or HTML versions) Figure 32: Recursion Mapping Example 2 (Available in PDF or HTML versions) 6.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 33: Mapping of Conditional Packages (Available in PDF or HTML versions) Mansfield, et al. Expires September 19, 2016 [Page 25] Internet-Draft Guidelines UML to YANG March 2016 6.3. XOR Relationship Use the "choice" property of the container statement. 6.4. Mapping of UML Support and Condition The UML Modeling Guidelines [9] 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 34: Support and Condition Mapping Example (Available in PDF or HTML versions) 7. Mapping Basics 7.1. UML-YANG or XMI-YANG Figure 35: Example UML to YANG Mapping (Available in PDF or HTML versions) Figure 36: 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]. Mansfield, et al. Expires September 19, 2016 [Page 26] Internet-Draft Guidelines UML to YANG March 2016 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, . [2] Bjorklund, M., "A YANG Data Model for Interface Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, . [3] Bjorklund, M., "A YANG Data Model for IP Management", RFC 7277, DOI 10.17487/RFC7277, June 2014, . [4] Bierman, A., "The YANG Package Statement", draft-bierman- netmod-yang-package-00 (work in progress), July 2015. [5] Bjorklund, M., "The YANG 1.1 Data Modeling Language", draft-ietf-netmod-rfc6020bis-11 (work in progress), February 2016. [6] 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. [7] 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-02 (work in progress), October 2015. [8] OMG, "Unified Modeling Language (UML)", 2011, . [9] OMG, "ONF TR-514 v1.0 UML Modeling Guidelines", 2015, . Appendix A. Example The YANG data schema (in tree format) shown below was extracted from dharini-netmod-g-698-2-yang [6] and represents the same data as UML model appearing in Figure 39 after the tree format. Note: The color Mansfield, et al. Expires September 19, 2016 [Page 27] Internet-Draft Guidelines UML to YANG March 2016 code used in the tree format corresponds to the color code used in the UML class diagram. Figure 37: Interfaces Tree (Available in PDF or HTML versions) Figure 38: Notifications Tree (Available in PDF or HTML versions) Figure 39: Interfaces UML Model (Available in PDF or HTML versions) 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 Mansfield, et al. Expires September 19, 2016 [Page 28] Internet-Draft Guidelines UML to YANG March 2016 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 Eve Varma Alcatel Lucent USA Email: eve.varma@alcatel-lucent.com Mansfield, et al. Expires September 19, 2016 [Page 29]