idnits 2.17.1 draft-mansfield-netmod-uml-to-yang-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 27, 2016) is 2735 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Obsolete informational reference (is this intentional?): RFC 7223 (ref. '2') (Obsoleted by RFC 8343) -- Obsolete informational reference (is this intentional?): RFC 7277 (ref. '3') (Obsoleted by RFC 8344) == Outdated reference: A later version (-04) exists of draft-lam-teas-usage-info-model-net-topology-03 Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETMOD Working Group S. Mansfield, Ed. 3 Internet-Draft Ericsson Inc. 4 Intended status: Informational B. Zeuner 5 Expires: April 30, 2017 Deutsche Telekom AG 6 N. Davis 7 Ciena 8 Y. Yun 9 Fiberhome 10 Y. Tochio 11 Fujitsu 12 K. Lam 13 E. Varma 14 Nokia 15 October 27, 2016 17 Guidelines for Translation of UML Information Model to YANG Data Model 18 draft-mansfield-netmod-uml-to-yang-03 20 Abstract 22 This document defines guidelines for translation of data modeled with 23 UML to YANG including mapping of object classes, attributes, data 24 types, associations, interfaces, operations and operation parameters, 25 notifications, and lifecycle. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on April 30, 2017. 44 Copyright Notice 46 Copyright (c) 2016 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 63 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 4. Mapping Guidelines . . . . . . . . . . . . . . . . . . . . . 4 65 4.1. Mapping Guideline Considerations . . . . . . . . . . . . 4 66 4.2. Mapping of Object Classes . . . . . . . . . . . . . . . . 4 67 4.3. Mapping of Attributes . . . . . . . . . . . . . . . . . . 8 68 4.4. Mapping of Types . . . . . . . . . . . . . . . . . . . . 11 69 4.4.1. Mapping of Primitive Types . . . . . . . . . . . . . 12 70 4.4.2. Mapping of Complex Data Types . . . . . . . . . . . . 13 71 4.5. Mapping of Enumeration Types . . . . . . . . . . . . . . 15 72 4.6. Mapping of Associations . . . . . . . . . . . . . . . . . 16 73 4.7. Mapping of Interfaces . . . . . . . . . . . . . . . . . . 17 74 4.8. Mapping of Operations . . . . . . . . . . . . . . . . . . 18 75 4.9. Mapping of Operation Parameters . . . . . . . . . . . . . 21 76 4.10. Mapping of Notifications . . . . . . . . . . . . . . . . 23 77 4.11. Mapping of Lifecycle . . . . . . . . . . . . . . . . . . 24 78 5. Mapping Patterns . . . . . . . . . . . . . . . . . . . . . . 25 79 5.1. UML Recursion . . . . . . . . . . . . . . . . . . . . . . 25 80 5.1.1. Reference Based Approach . . . . . . . . . . . . . . 25 81 5.2. UML Conditional Pacs . . . . . . . . . . . . . . . . . . 25 82 5.3. XOR Relationship . . . . . . . . . . . . . . . . . . . . 25 83 5.4. Choice Stereotype . . . . . . . . . . . . . . . . . . . . 26 84 5.5. Mapping of UML Support and Condition . . . . . . . . . . 26 85 6. Mapping Basics . . . . . . . . . . . . . . . . . . . . . . . 26 86 6.1. UML-YANG or XMI-YANG . . . . . . . . . . . . . . . . . . 26 87 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 27 88 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 89 9. Security Considerations . . . . . . . . . . . . . . . . . . . 27 90 10. Informative References . . . . . . . . . . . . . . . . . . . 27 91 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 93 1. Introduction 95 As discussed in draft-lam-teas-usage-info-model-net-topology [5] a 96 Data Model (DM) may be derived from an Information Model (IM). 97 However, in order to assure a consistent and valid data modelling 98 language representation that enables maximum interoperability, 99 translation guidelines are required. A set of translation rules also 100 assists in development of automated tooling. 102 This draft defines guidelines for translation of data modelled with 103 UML [6] (as constrained by the ONF's UML Modeling Guidelines [7]) to 104 YANG (defined in RFC6020 [1] and YANG 1.1 [4]) including mapping of 105 object classes, attributes, data types, associations, interfaces, 106 operations and operation parameters, notifications, and lifecycle. 108 2. Terminology 110 The following terms are defined in RFC6020 [1] 112 o anydata 114 o anyxml 116 o augment 118 o container 120 o data node 122 o identity 124 o instance identifier 126 o leaf 128 o leaf-list 130 o list 132 o module 134 o submodule 136 The following terms are defined in UML 2.4 [6] 138 o association 140 o attribute 141 o data type 143 o interface 145 o object class 147 o operation 149 o parameter 151 o signal (used to model notifications) 153 3. Overview 155 This document defines translation rules for all constructs used in a 156 UML based IM to a data model using YANG. 158 While some mapping rules are straightforward, an IM in UML uses some 159 constructs that cannot be mapped directly to a DM using YANG and 160 conventions are described to make the translation predictable. 161 Additionally, in some cases multiple mapping approaches are possible 162 and selection among these is also necessary to assure 163 interoperability. 165 Mapping guidelines for these constructs are provided in the following 166 sections. 168 4. Mapping Guidelines 170 4.1. Mapping Guideline Considerations 172 Where "??" is inserted in the table, it means that the specific 173 mapping is for further study as it is either as yet unclear how to 174 map the construct or that there are multiple ways of doing the 175 mapping and a single one needs to be selected. 177 A table will be included summarizing constructs in UML that do not 178 directly map to YANG and where in this draft the associated 179 guidelines for mapping these constructs will be provided. 181 4.2. Mapping of Object Classes 183 +-------------------------------------------------------------------+ 184 | Object Class | 185 | - Real object classes having/inheriting at least one attribute | 186 | identified as "partOfObjectKey" will be mapped to a "list" | 187 | statement | 188 | - Real object classes not having/inheriting any attribute | 189 | identified as "partOfObjectKey" will be mapped to a "container" | 190 | statement | 191 | - Abstract object classes used for inheritance will be mapped | 192 | to a "grouping" statement | 193 +-------------------------------------------------------------------+ 194 | UML Artifact | YANG Artifact | Comment | 195 +-------------------------------------------------------------------+ 196 | documentation | "description" | Multiple "applied | 197 | "Applied comments" | substatement | comments" defined | 198 | (carried in XMI as | | in UML, need to be| 199 | "ownedComment") | | collapsed into a | 200 | | | single | 201 | | | "description" | 202 | | | substatement. | 203 +-------------------------------------------------------------------+ 204 | superclass(es) | "grouping" statement | Concrete | 205 | | | superclasses are | 206 | | | then mapped to | 207 | | | container/list | 208 | | | which uses these | 209 | | | groupings. | 210 +-------------------------------------------------------------------+ 211 | abstract | "grouping" statement | It is possible | 212 | | | that the | 213 | | | superclass or | 214 | | | abstract class | 215 | | | contains the key | 216 | | | attribute for the | 217 | | | instantiated | 218 | | | subclass, this | 219 | | | requires the | 220 | | | creation of the | 221 | | | grouping but later| 222 | | | when the subclass | 223 | | | is instantiated | 224 | | | the key value must| 225 | | | be identified from| 226 | | | within the | 227 | | | grouping. | 228 +-------------------------------------------------------------------+ 229 | object identifier | list::"key" | It is possible | 230 | | substatement | that the super- | 231 | Note: Attributes used | | class or abstract | 232 | as object identifier | | class contains the| 233 | are defined in UML by | | key attribute for | 234 | the attribute | | the instantiated | 235 | property | | subclass. | 236 | "partOfObjectKey". | | | 237 +-------------------------------------------------------------------+ 238 | object identifier list| | The splitting of a| 239 | | | list attribute | 240 | Does not appear in the| | (marked as key) | 241 | UML when mapping to | | into a single key | 242 | YANG. | | attribute and an | 243 | | | additional list | 244 | | | attribute will be | 245 | | | done in UML during| 246 | | | Pruning and | 247 | | | Refactoring. i.e.| 248 | | | The mapping tool | 249 | | | will never get a | 250 | | | list attribute | 251 | | | which is part of | 252 | | | the object | 253 | | | identifier. | 254 +-------------------------------------------------------------------+ 255 | objectCreationNotific-| "notification" | Goes beyond the | 256 | ation | statement | simple "a notific-| 257 | [YES/NO/NA] | | ation has to be | 258 | | | sent": a tool can | 259 | | | construct the sig-| 260 | | | ature of the noti-| 261 | | | cation by reading | 262 | | | the created | 263 | | | object. | 264 +-------------------------------------------------------------------+ 265 | objectDeletionNotific-| "notification" | Goes beyond the | 266 | ation | statement | simple "a notific-| 267 | [YES/NO/NA] | | ation has to be | 268 | | | sent": a tool can | 269 | | | construct the sig-| 270 | | | ature of the noti-| 271 | | | cation by reading | 272 | | | the deleted | 273 | | | object. (i.e. not | 274 | | | necessary to | 275 | | | provide the | 276 | | | attributes of the | 277 | | | deleted object). | 278 +-------------------------------------------------------------------+ 279 | muliplicity >1 on | list::"min-elements" | min-elements | 280 | association to the | "max-elements" | default = 0 | 281 | class | substatements | max-elements | 282 | | | default=unbounded| 283 | | | mandatory | 284 | | | default=false | 285 +-------------------------------------------------------------------+ 286 | <> | "reference" | | 287 | | substatement | | 288 +-------------------------------------------------------------------+ 289 | <> | Ignore Example | | 290 | | elements and all | | 291 | | composed parts | | 292 +-------------------------------------------------------------------+ 293 | lifecycleState | "status" | <> -> "YANG" | 294 | | substatement | <> | 295 | | | "deprecated", | 296 | | | <> | 297 | | | description, | 298 | | | <> | 299 | | | description, | 300 | | |<> | 301 | | | description, | 302 | | | <> | 303 | | | "current", | 304 | | | <> | 305 | | | "obsolete", | 306 | | | <> | 307 | | | description | 308 +-------------------------------------------------------------------+ 309 | Proxy Class | "choice" | | 310 | XOR | substatement | | 311 +-------------------------------------------------------------------+ 312 | support | "if-feature" | Support and | 313 | | substatement | condition belong | 314 +-----------------------+ | together. If the | 315 | condition | | "support" is cond-| 316 | | | itional, then the | 317 | | | "condition" | 318 | | | explains the cond-| 319 | | | itions under which| 320 | | | the class has to | 321 | | | be supported. | 322 +-------------------------------------------------------------------+ 323 | operation | "action" | YANG 1.0 supports | 324 | | substatement | only rpc -> add | 325 | | | prefix to the rpc | 326 | | | name; i.e. | 327 | | | objectClass::rpc; | 328 | | | "action" requires | 329 | | | YANG 1.1 | 330 +-------------------------------------------------------------------+ 331 | Conditional PACs | container::presence" | | 332 | | substatement | | 333 +-------------------------------------------------------------------+ 334 | constraint property | list::"unique" | UML is not able to| 335 | | substatement | define a group | 336 | | | of attributes to be 337 | | | unique as YANG can| 338 | | | do using the | 339 | | | "unique" | 340 | | | substatement. | 341 +-------------------------------------------------------------------+ 342 | {} | "when" substatement | | 343 +-------------------------------------------------------------------+ 345 Figure 1: Mapping of Object Classes 347 Figure 2: Example of Abstract Object Class Mapping (Available in PDF 348 or HTML versions) 350 Figure 3: Example of Non-Abstract Object Class Mapping (Available in 351 PDF or HTML versions) 353 4.3. Mapping of Attributes 355 +-------------------------------------------------------------------+ 356 | Attribute --> "leaf" (single) or "leaf list" (multiple) | 357 | statement | 358 +-------------------------------------------------------------------+ 359 | UML Artifact | YANG Artifact | Comment | 360 +-------------------------------------------------------------------+ 361 | documentation | "description" | Multiple "applied | 362 | "Applied comments" | substatement | comments" defined | 363 | (carried in XMI as | | in UML, need to be| 364 | "ownedComment") | | collapsed into a | 365 | | | single | 366 | | | "description" | 367 | | | substatement. | 368 +-------------------------------------------------------------------+ 369 | type | "type" substatement | | 370 | | (built-in or derived) | | 371 +-------------------------------------------------------------------+ 372 | readOnly | "config" substatement | config | 373 | | (false) | default = true | 374 +-------------------------------------------------------------------+ 375 | isOrdered | "ordered-by" | ordered-by | 376 | | substatement | default = system | 377 | |("system" or "user") | | 378 +-------------------------------------------------------------------+ 379 | isUnique | No unique | Only relevant for | 380 | | sub-statement in | multi-valued | 381 | | leaf-list | attributes. | 382 +-------------------------------------------------------------------+ 383 | Multiplicity | "mandatory" or | min-elements | 384 | (carried in XMI as | "min-elements" and | default = 0 | 385 | lowerValue and | "max-elements" | max-elements | 386 | upperValue) | substatements | default=unbounded| 387 | | [0..1]=>no mapping | mandatory | 388 | | needed; is default | default=false | 389 | | substatement=false | | 390 | | [1]=>mandatory | | 391 | | substatement=true | | 392 | | [0..x]=> no mapping | | 393 | | needed; is default | | 394 | | [1..x]=> min-elements | | 395 | | substatement = 1 | | 396 | | [0..3]=> max-elements | | 397 | | substatement = 3 | | 398 +-------------------------------------------------------------------+ 399 | defaultValue | "default" | If a default value| 400 | | substatement | exists and it is | 401 | | | the desired value,| 402 | | | the parameter does| 403 | | | not have to be | 404 | | | explicitly config-| 405 | | | ured by the user. | 406 +-------------------------------------------------------------------+ 407 | isInvariant | "extension" | | 408 | | substatement -> | | 409 | | ompExt:isInvariant | | 410 +-------------------------------------------------------------------+ 411 | valueRange | For string type: | The tool should | 412 | | "pattern" and/or | provide a warning | 413 | | "length substatement| at the output of | 414 | | of "type" substatement| mapping process | 415 | | For integer and | notifying when one| 416 | | decimal type: | or more UML | 417 | | "range" substatement| valueRange | 418 | | of "type" substatement| definitions are | 419 | | For all other typed | contained in the | 420 | | attributes and for | description | 421 | | string or integer or | substatement of | 422 | | decimal typed | the corresponding | 423 | | attributes where the | leaf or leaf-list.| 424 | | UML definition is not | When the value of | 425 | | compliant to YANG: | "valueRange" is | 426 | | "description" | "null", "NA", | 427 | | substatement | "See data type", | 428 | | | the tool ignores | 429 | | | it and doesn't | 430 | | | print out "range" | 431 | | | substatement. | 432 +-------------------------------------------------------------------+ 433 | passedByReference | if passedByReference =| Relevant only to | 434 | | true -> type leafref {| attributes that | 435 | | path "// | have an object | 436 | | "} | class defined as | 437 | | | their type. | 438 | | if passedByReference =| | 439 | | false -> either "list"| | 440 | | statement (key | | 441 | | property, multiple | | 442 | | instances) or | | 443 | | "container" statement(| | 444 | | single instance) | | 445 +-------------------------------------------------------------------+ 446 | partOfObjectKey > 0 | list::"key" | It is possible that 447 | | substatement | the (abstract) | 448 | | | superclass contains 449 | | | the key attribute | 450 | | | for the | 451 | | | instantiated | 452 | | | subclass. | 453 +-------------------------------------------------------------------+ 454 | unit | "units" substatement | | 455 +-------------------------------------------------------------------+ 456 | <> | "reference" | | 457 | | substatement | | 458 +-------------------------------------------------------------------+ 459 | <> | Ignore Example | | 460 | | elements and all | | 461 | | composed parts | | 462 +-------------------------------------------------------------------+ 463 | lifecycleState | "status" | <> -> "YANG" | 464 | | substatement | <> | 465 | | | "deprecated", | 466 | | | <> | 467 | | | description, | 468 | | | <> | 469 | | | description, | 470 | | |<> | 471 | | | description, | 472 | | | <> | 473 | | | "current", | 474 | | | <> | 475 | | | "obsolete", | 476 | | | <> | 477 | | | description | 478 +-------------------------------------------------------------------+ 479 | support | For conditional | Support and | 480 | | support only: | condition belong | 481 +-----------------------+ | together. If the | 482 | condition | "if-feature" | "support" is cond-| 483 | | substatement | itional, then the | 484 | | | "condition" | 485 | | "when" substatement if| explains the cond-| 486 | | condition can be | itions under which| 487 | | formalized as XPath | the class has to | 488 | | expression (i.e., it | be supported. | 489 | | is conditioned by the | | 490 | | value of another | | 491 | | attribute) | | 492 +-------------------------------------------------------------------+ 493 | error notfication?? | "must" | | 494 | | substatement | | 495 +-------------------------------------------------------------------+ 496 | {} | "when" substatement | | 497 +-------------------------------------------------------------------+ 499 Figure 4: Mapping of Attributes 501 Figure 5: Example of Attribute Mapping (Available in PDF or HTML 502 versions) 504 4.4. Mapping of Types 506 +-------------------------------------------------------------------+ 507 | Types | 508 +-------------------------------------------------------------------+ 509 | UML Artifact | YANG Artifact | Comment | 510 +-------------------------------------------------------------------+ 511 | Primitive Type | Built-In Type if | e.g., Integer | 512 | | defined | | 513 +-------------------------------------------------------------------+ 514 | Complex Data Type | "grouping" statement | e.g., date-time | 515 | | | | 516 +-------------------------------------------------------------------+ 517 | Enumeration | "enum" statement | | 518 +-------------------------------------------------------------------+ 520 Figure 6: Mapping of Types 522 4.4.1. Mapping of Primitive Types 524 +-------------------------------------------------------------------+ 525 | Primitive Type -> "typeDef" statement | 526 +-------------------------------------------------------------------+ 527 | UML Artifact | YANG Artifact | Comment | 528 +-------------------------------------------------------------------+ 529 | documentation | "description" | Multiple "applied | 530 | "Applied comments" | substatement | comments" defined | 531 | (carried in XMI as | | in UML, need to be| 532 | "ownedComment") | | collapsed into a | 533 | | | single | 534 | | | "description" | 535 | | | substatement. | 536 +-------------------------------------------------------------------+ 537 | type | "type" substatement | | 538 | | (built-in type or | | 539 | | derived type) | | 540 +-------------------------------------------------------------------+ 541 | defaultValue | "default" substatment | If a default value| 542 | | | exists and it is | 543 | | | the desired value,| 544 | | | the parameter does| 545 | | | not have to be | 546 | | | explicitly | 547 | | | configured by the | 548 | | | user. When the | 549 | | | value of | 550 | | | "defaultValue" is | 551 | | | "NA", the tool | 552 | | | ignores it and | 553 | | | doesn't print out | 554 | | | "default" | 555 | | | substatement. | 556 +-------------------------------------------------------------------+ 557 | unit | "units" substatement | | 558 +-------------------------------------------------------------------+ 559 | <> | "reference" | | 560 | | substatement | | 561 +-------------------------------------------------------------------+ 562 | <> | Ignore Example | | 563 | | elements and all | | 564 | | composed parts | | 565 +-------------------------------------------------------------------+ 566 | lifecycleState | "status" | <> -> "YANG" | 567 | | substatement | <> | 568 | | | "deprecated", | 569 | | | <> | 570 | | | description, | 571 | | | <> | 572 | | | description, | 573 | | |<> | 574 | | | description, | 575 | | | <> | 576 | | | "current", | 577 | | | <> | 578 | | | "obsolete", | 579 | | | <> | 580 | | | description | 581 +-------------------------------------------------------------------+ 583 Figure 7: Mapping of Primitive Types 585 4.4.2. Mapping of Complex Data Types 586 +-------------------------------------------------------------------+ 587 | Complex Data Type -> "grouping" statement | 588 +-------------------------------------------------------------------+ 589 | UML Artifact | YANG Artifact | Comment | 590 +-------------------------------------------------------------------+ 591 | documentation | "description" | Multiple "applied | 592 | "Applied comments" | substatement | comments" defined | 593 | (carried in XMI as | | in UML, need to be| 594 | "ownedComment") | | collapsed into a | 595 | | | single | 596 | | | "description" | 597 | | | substatement. | 598 +-------------------------------------------------------------------+ 599 | not used | "action" substatement | | 600 +-------------------------------------------------------------------+ 601 | XOR | "choice" | | 602 | | substatement | | 603 +-------------------------------------------------------------------+ 604 | <> | "reference" | | 605 | | substatement | | 606 +-------------------------------------------------------------------+ 607 | <> | Ignore Example | | 608 | | elements and all | | 609 | | composed parts | | 610 +-------------------------------------------------------------------+ 611 | lifecycleState | "status" | <> -> "YANG" | 612 | | substatement | <> | 613 | | | "deprecated", | 614 | | | <> | 615 | | | description, | 616 | | | <> | 617 | | | description, | 618 | | |<> | 619 | | | description, | 620 | | | <> | 621 | | | "current", | 622 | | | <> | 623 | | | "obsolete", | 624 | | | <> | 625 | | | description | 626 +-------------------------------------------------------------------+ 627 | complex attribute | "uses" statement | | 628 +-------------------------------------------------------------------+ 630 Figure 8: Mapping of Complex Data Types 632 Leaf and leaf-list can only use built-in types, typeDef types or 633 enumerations in their type substatement; i.e., not groupings. 635 Complex data types with more than one item (e.g., name value pair) 636 can only be defined using groupings. Groupings can only be used by 637 grouping, container and list statements. 639 Figure 9: Example of Complex Data Type Mapping (Available in PDF or 640 HTML versions) 642 4.5. Mapping of Enumeration Types 644 +-------------------------------------------------------------------+ 645 | Enumeration Type -> "enum" statement | 646 | typedef for reusable (indirect usage) enumerations | 647 | identity statement? | 648 +-------------------------------------------------------------------+ 649 | UML Artifact | YANG Artifact | Comment | 650 +-------------------------------------------------------------------+ 651 | documentation | "description" | Multiple "applied | 652 | "Applied comments" | substatement | comments" defined | 653 | (carried in XMI as | | in UML, need to be| 654 | "ownedComment") | | collapsed into a | 655 | | | single | 656 | | | "description" | 657 | | | substatement. | 658 +-------------------------------------------------------------------+ 659 | literal name | enum name | | 660 +-------------------------------------------------------------------+ 661 | literal integer | "value" | | 662 | | substatement | | 663 +-------------------------------------------------------------------+ 664 | isLeaf = true | "enum" | UML definition "" | 665 | isLeaf = false | substatement | | 666 | | "identity"/"base" | | 667 | | pattern | | 668 +-------------------------------------------------------------------+ 669 | <> | "reference" | | 670 | | substatement | | 671 +-------------------------------------------------------------------+ 672 | <> | Ignore Example | | 673 | | elements and all | | 674 | | composed parts | | 675 +-------------------------------------------------------------------+ 676 | lifecycleState | "status" | <> -> "YANG" | 677 | | substatement | <> | 678 | | | "deprecated", | 679 | | | <> | 680 | | | description, | 681 | | | <> | 682 | | | description, | 683 | | |<> | 684 | | | description, | 685 | | | <> | 686 | | | "current", | 687 | | | <> | 688 | | | "obsolete", | 689 | | | <> | 690 | | | description | 691 +-------------------------------------------------------------------+ 693 Figure 10: Mapping of Enumeration Types 695 Figure 11: Example of Enumeration Type Mapping (Available in PDF or 696 HTML versions) 698 4.6. Mapping of Associations 700 +-------------------------------------------------------------------+ 701 | Associations | 702 +-------------------------------------------------------------------+ 703 | UML Artifact | YANG Artifact | Comment | 704 +-------------------------------------------------------------------+ 705 | Inheritance | abstract superclass: | Multiple | 706 | | "grouping" statement | inheritance can | 707 | | | also be mapped | 708 | | concrete superclass: | using "groupings" | 709 | | "augment" statement | Need to define | 710 | | | when augment is | 711 | | | used. Note: | 712 | | | Augmentation can | 713 | | | be conditional. | 714 +-------------------------------------------------------------------+ 715 | Composition with | "container" statement | How to map "passed| 716 | (aggregation= | containing "list" | by reference"?? | 717 | 'composite') | statement(s) (multiple| | 718 | "passed by value" | contained instances) | | 719 | | or "container" state- | | 720 | | ment(s) (single | | 721 | | contained instances) | | 722 +-------------------------------------------------------------------+ 723 | Aggregation with | "leafref" statement | How to map "passed| 724 | (aggregation='shared')| | by value"?? | 725 | "passed by reference" | | | 726 +-------------------------------------------------------------------+ 728 Figure 12: Mapping of Associations 730 Figure 13: Association Mapping Example 1 (Available in PDF or HTML 731 versions) 733 Figure 14: Association Mapping Example 2 (Available in PDF or HTML 734 versions) 736 Figure 15: Association Mapping Example 3 (Available in PDF or HTML 737 versions) 739 Figure 16: Association Mapping Example 4 (Available in PDF or HTML 740 versions) 742 Figure 17: Association Mapping Example 5 (Available in PDF or HTML 743 versions) 745 +-------------------------------------------------+ 746 | UML | 747 +-------------------------------------------------+ 748 | containment | association | inheritance | 749 +-------------------------------------------------------------------+ 750 | YANG | nesting | X | | | 751 | +------------------------------------------------------------+ 752 | | grouping | | | X | 753 | | | | |abstract superclasses| 754 | +------------------------------------------------------------+ 755 | | augment | | | X | 756 | | | | |concrete superclasses| 757 | +------------------------------------------------------------+ 758 | | leafref | | X | | 759 +-------------------------------------------------------------------+ 761 Figure 18: Association Mapping Summary 763 4.7. Mapping of Interfaces 765 +-------------------------------------------------------------------+ 766 | UML Interface -> Container?? | 767 +-------------------------------------------------------------------+ 768 | documentation | "description" | Multiple "applied | 769 | "Applied comments" | substatement | comments" defined | 770 | (carried in XMI as | | in UML, need to be| 771 | "ownedComment") | | collapsed into a | 772 | | | single | 773 | | | "description" | 774 | | | substatement. | 775 +-------------------------------------------------------------------+ 776 | abstract | "grouping" statement | | 777 +-------------------------------------------------------------------+ 778 | <> | "reference" | | 779 | | substatement | | 780 +-------------------------------------------------------------------+ 781 | <> | Ignore Example | | 782 | | elements and all | | 783 | | composed parts | | 784 +-------------------------------------------------------------------+ 785 | lifecycleState | "status" | <> -> "YANG" | 786 | | substatement | <> | 787 | | | "deprecated", | 788 | | | <> | 789 | | | description, | 790 | | | <> | 791 | | | description, | 792 | | |<> | 793 | | | description, | 794 | | | <> | 795 | | | "current", | 796 | | | <> | 797 | | | "obsolete", | 798 | | | <> | 799 | | | description | 800 +-------------------------------------------------------------------+ 801 | support | "if-feature" | Support and | 802 | | substatement | condition belong | 803 +-----------------------+ | together. If the | 804 | condition | | "support" is cond-| 805 | | | itional, then the | 806 | | | "condition" | 807 | | | explains the cond-| 808 | | | itions under which| 809 | | | the class has to | 810 | | | be supported. | 811 +-------------------------------------------------------------------+ 813 Figure 19: Mapping of Interfaces (grouping of operations 815 4.8. Mapping of Operations 817 +-------------------------------------------------------------------+ 818 | Operation -> "action" and "rpc" statements | 819 | (RFC 6020: The difference between an action and an rpc is that an| 820 | action is tied to a node in the data tree, whereas an rpc is | 821 | associated at the module level.) | 822 +-------------------------------------------------------------------+ 823 | documentation | "description" | Multiple "applied | 824 | "Applied comments" | substatement | comments" defined | 825 | (carried in XMI as | | in UML, need to be| 826 | "ownedComment") | | collapsed into a | 827 | | | single | 828 | | | "description" | 829 | | | substatement. | 830 +-------------------------------------------------------------------+ 831 | pre-condition | "extension" | RFC 6020; During | 832 | | substatement -> | the NETCONF | 833 | | ompExt:preCondition | pro-| 834 | | | cessing errors are| 835 | | | already sent for: | 836 | | | - Delete requests | 837 | | | for non-existent| 838 | | | data. | 839 | | | - Create requests | 840 | | | for existing | 841 | | | data. | 842 | | | - Insert requests | 843 | | | with "before" or| 844 | | | "after" para- | 845 | | | meters that do | 846 | | | not exist. | 847 +-------------------------------------------------------------------+ 848 | post-condition | "extension" | | 849 | | substatement | | 850 | | ompExt:postCondition | | 851 +-------------------------------------------------------------------+ 852 | input parameter | "input" substatement | | 853 +-------------------------------------------------------------------+ 854 | output parameter | "output" substatement | | 855 +-------------------------------------------------------------------+ 856 | operation exceptions | "extension" | | 857 | | substatement | | 858 | Internal Error | ompExt:operationExceptions | 859 | Unable to Comply | | 860 | Comm Loss | +--------------------------------------+ | 861 | Invalid Input | | error-tag | error-app-tag | | 862 | Not Implemented | +--------------------------------------+ | 863 | Duplicate | | operation-failed | too-many-elements | | 864 | Entity Not Found | | | too-few-elements | | 865 | Object In Use | | | must-violation | | 866 | Capacity Exceeded | +--------------------------------------+ | 867 | Not In Valid State | | data-missing | instance-required | | 868 | Access Denied | | | missing-choice | | 869 | | +--------------------------------------+ | 870 | | | bad-attribute | missing-instance | | 871 | | +--------------------------------------+ | 872 +-------------------------------------------------------------------+ 873 | isOperationIdempotent | "extension" | | 874 | | substatement | | 875 | | ompExt:isOperationIdempotent | 876 +-------------------------------------------------------------------+ 877 | isAtomic | "extension" | Necessary?? Not in| 878 | | substatement | UML Guidelines | 879 | | ompExt:isAtomic | (TR-514); needs to| 880 | | | be added?? | 881 +-------------------------------------------------------------------+ 882 | <> | "reference" | | 883 | | substatement | | 884 +-------------------------------------------------------------------+ 885 | <> | Ignore Example | | 886 | | elements and all | | 887 | | composed parts | | 888 +-------------------------------------------------------------------+ 889 | lifecycleState | "status" | <> -> "YANG" | 890 | | substatement | <> | 891 | | | "deprecated", | 892 | | | <> | 893 | | | description, | 894 | | | <> | 895 | | | description, | 896 | | |<> | 897 | | | description, | 898 | | | <> | 899 | | | "current", | 900 | | | <> | 901 | | | "obsolete", | 902 | | | <> | 903 | | | description | 904 +-------------------------------------------------------------------+ 905 | support | "if-feature" | Support and | 906 | | substatement | condition belong | 907 +-----------------------+ | together. If the | 908 | condition | | "support" is cond-| 909 | | | itional, then the | 910 | | | "condition" | 911 | | | explains the cond-| 912 | | | itions under which| 913 | | | the class has to | 914 | | | be supported. | 915 +-------------------------------------------------------------------+ 917 Figure 20: Mapping of Operations 919 Figure 21: Operation Mapping Example (Available in PDF or HTML 920 versions) 922 4.9. Mapping of Operation Parameters 924 +-------------------------------------------------------------------+ 925 | Operation Parameters | 926 +-------------------------------------------------------------------+ 927 | documentation | "description" | Multiple "applied | 928 | "Applied comments" | substatement | comments" defined | 929 | (carried in XMI as | | in UML, need to be| 930 | "ownedComment") | | collapsed into a | 931 | | | single | 932 | | | "description" | 933 | | | substatement. | 934 +-------------------------------------------------------------------+ 935 | direction | "input" or "output" | | 936 | | substatement | | 937 +-------------------------------------------------------------------+ 938 | type | see mapping of | | 939 +-----------------------| attribute types |-------------------+ 940 | isOrdered | (grouping, leaf, | | 941 +-----------------------| leaf-list, list, |-------------------+ 942 | multiplicity | typedef, uses) | | 943 +-----------------------| |-------------------+ 944 | defaultValue | | | 945 +-----------------------| |-------------------+ 946 | valueRange | | | 947 +-------------------------------------------------------------------+ 948 | passedByReference | if passedByReference =| Relevant only to | 949 | | true -> type leafref {| attributes that | 950 | | path "// | have an object | 951 | | "} | class defined as | 952 | | | their type. | 953 | | if passedByReference =| | 954 | | false -> either "list"| | 955 | | statement (key | | 956 | | property, multiple | | 957 | | instances) or | | 958 | | "container" statement(| | 959 | | single instance) | | 960 +-------------------------------------------------------------------+ 961 | <> | "reference" | | 962 | | substatement | | 963 +-------------------------------------------------------------------+ 964 | <> | Ignore Example | | 965 | | elements and all | | 966 | | composed parts | | 967 +-------------------------------------------------------------------+ 968 | lifecycleState | "status" | <> -> "YANG" | 969 | | substatement | <> | 970 | | | "deprecated", | 971 | | | <> | 972 | | | description, | 973 | | | <> | 974 | | | description, | 975 | | |<> | 976 | | | description, | 977 | | | <> | 978 | | | "current", | 979 | | | <> | 980 | | | "obsolete", | 981 | | | <> | 982 | | | description | 983 +-------------------------------------------------------------------+ 984 | support | "if-feature" | Support and | 985 | | substatement not | condition belong | 986 +-----------------------+ defined for input and | together. If the | 987 | condition | output substatements | "support" is cond-| 988 | | in YANG?? | itional, then the | 989 | | | "condition" | 990 | | | explains the cond-| 991 | | | itions under which| 992 | | | the class has to | 993 | | | be supported. | 994 +-------------------------------------------------------------------+ 995 | XOR | "choice" | | 996 | | substatement | | 997 +-------------------------------------------------------------------+ 998 | error notification?? | "must" | | 999 | | substatement | | 1000 +-------------------------------------------------------------------+ 1001 | complex parameter | "uses" | | 1002 | | substatement | | 1003 +-------------------------------------------------------------------+ 1005 Figure 22: Mapping of Operation Parameters 1007 Figure 23: Parameter Mapping Example (Available in PDF or HTML 1008 versions) 1010 4.10. Mapping of Notifications 1012 +-------------------------------------------------------------------+ 1013 | Signal "grouping" statement -> "notification" statement | 1014 +-------------------------------------------------------------------+ 1015 | documentation | "description" | Multiple "applied | 1016 | "Applied comments" | substatement | comments" defined | 1017 | (carried in XMI as | | in UML, need to be| 1018 | "ownedComment") | | collapsed into a | 1019 | | | single | 1020 | | | "description" | 1021 | | | substatement. | 1022 +-------------------------------------------------------------------+ 1023 | <> | "reference" | | 1024 | | substatement | | 1025 +-------------------------------------------------------------------+ 1026 | <> | Ignore Example | | 1027 | | elements and all | | 1028 | | composed parts | | 1029 +-------------------------------------------------------------------+ 1030 | lifecycleState | "status" | <> -> "YANG" | 1031 | | substatement | <> | 1032 | | | "deprecated", | 1033 | | | <> | 1034 | | | description, | 1035 | | | <> | 1036 | | | description, | 1037 | | |<> | 1038 | | | description, | 1039 | | | <> | 1040 | | | "current", | 1041 | | | <> | 1042 | | | "obsolete", | 1043 | | | <> | 1044 | | | description | 1045 +-------------------------------------------------------------------+ 1046 | support | "if-feature" | Support and | 1047 | | substatement | condition belong | 1048 +-----------------------+ | together. If the | 1049 | condition | | "support" is cond-| 1050 | | | itional, then the | 1051 | | | "condition" | 1052 | | | explains the cond-| 1053 | | | itions under which| 1054 | | | the class has to | 1055 | | | be supported. | 1056 +-------------------------------------------------------------------+ 1057 | Proxy Class | "choice" | | 1058 | XOR | substatement | | 1059 +-------------------------------------------------------------------+ 1060 | error notification?? | "must" | | 1061 | | substatement | | 1062 +-------------------------------------------------------------------+ 1063 | attributes | see mapping of | | 1064 | | attribute types | | 1065 | | (grouping, leaf, | | 1066 | | leaf-list, container,| | 1067 | | list, typedef, uses) | | 1068 +-------------------------------------------------------------------+ 1069 | complex attribute | "uses" | | 1070 | | substatement | | 1071 +-------------------------------------------------------------------+ 1073 Figure 24: Mapping of Notifications 1075 Figure 25: Notification Mapping Example (Available in PDF or HTML 1076 versions) 1078 4.11. Mapping of Lifecycle 1080 +-------------------------------------------------------------------+ 1081 | UML Lifecycle | 1082 +-------------------------------------------------------------------+ 1083 | lifecycle stereotypes | "status" | <> -> "YANG" | 1084 | | substatement or | <> | 1085 | | "description" | "deprecated", | 1086 | | substatement | <> | 1087 | | | description, | 1088 | | | <> | 1089 | | | description, | 1090 | | |<> | 1091 | | | description, | 1092 | | | <> | 1093 | | | "current", | 1094 | | | <> | 1095 | | | "obsolete", | 1096 | | | <> | 1097 | | | description | 1098 +-------------------------------------------------------------------+ 1100 Figure 26: Mapping of Lifecycle 1102 5. Mapping Patterns 1104 5.1. UML Recursion 1106 As YANG defines hierarchical data store, any instances that need to 1107 store recursive containment will require translation. A mapping 1108 between object-oriented store and a hierarchical store is possible; 1109 however, there is more than one option: 1111 o Reference Based Approach approach - have a flat list of objects, 1112 where the objects are linked into a hierarchy using references. 1113 An example of a two-way navigable approach is in RFC7223 [2]. 1115 o Assume some specific number of "recursions"; i.e., specify some 1116 default number of recursion levels, and define a configurable 1117 parameter to allow changing the number of levels. 1119 5.1.1. Reference Based Approach 1121 Figure 27: Recursion Mapping Example 1 (Available in PDF or HTML 1122 versions) 1124 Figure 28: Recursion Mapping Example 2 (Available in PDF or HTML 1125 versions) 1127 5.2. UML Conditional Pacs 1129 Use the "presence" property of the container statement? 1131 Note: An example of this usage is given in the "Data nodes for the 1132 operational state of IP on interfaces." within ietf-ip.yang RFC7277 1133 [3]. 1135 Figure 29: Mapping of Conditional Packages (Available in PDF or HTML 1136 versions) 1138 5.3. XOR Relationship 1140 The associations related by the "xor" constraint are mapped to the 1141 "choice" property of the container/list statement. 1143 Figure 30: XOR Relationship Mapping Example (Available in PDF or HTML 1144 versions) 1146 5.4. Choice Stereotype 1148 The choice sterotype can be associated in UML to a class or a data 1149 type. The class or a data type which is annotated with the choice 1150 sterotype represents one of a set of classes/data types. This 1151 pattern is mapped to the "choice" property of the container/list/ 1152 grouping statement. 1154 Figure 31: Choice Stereotype Example (Available in PDF or HTML 1155 versions) 1157 5.5. Mapping of UML Support and Condition 1159 The UML Modeling Guidelines [7] define support and condition for all 1160 UML artifacts (M - Mandatory, O - Optional, C - Conditional, CM - 1161 Conditional-Mandatory, CO - Conditional-Optional). Support qualifies 1162 the support of the artifact at the management interface. Condition 1163 contains the condition for the condition-related support qualifiers. 1165 M - Mandatory maps to the "mandatory" substatement in choice and leaf 1166 or to the "min-elements" substatement in leaf-list and list. 1168 O - Optional need not be mapped since the per default the "mandatory" 1169 and "min-elements" substaments define optional. 1171 All conditional UML support qualifiers are mapped to the "if-feature" 1172 substatement. 1174 Figure 32: Support and Condition Mapping Example (Available in PDF or 1175 HTML versions) 1177 6. Mapping Basics 1179 6.1. UML-YANG or XMI-YANG 1181 Figure 33: Example UML to YANG Mapping (Available in PDF or HTML 1182 versions) 1184 Figure 34: Example XMI (Papyrus) to YANG Mapping (Available in PDF or 1185 HTML versions) 1187 7. Acknowledgements 1189 8. IANA Considerations 1191 This memo includes no request to IANA. 1193 9. Security Considerations 1195 This document defines defines guidelines for translation of data 1196 modeled with UML to YANG. As such, it doesn't contribute any new 1197 security issues beyond those discussed in Sec. 16 of RFC6020 [1]. 1199 10. Informative References 1201 [1] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1202 the Network Configuration Protocol (NETCONF)", RFC 6020, 1203 DOI 10.17487/RFC6020, October 2010, 1204 . 1206 [2] Bjorklund, M., "A YANG Data Model for Interface 1207 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1208 . 1210 [3] Bjorklund, M., "A YANG Data Model for IP Management", 1211 RFC 7277, DOI 10.17487/RFC7277, June 2014, 1212 . 1214 [4] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1215 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1216 . 1218 [5] Lam, H., Varma, E., Doolan, P., Davis, N., Zeuner, B., 1219 Betts, M., Busi, I., Mansfield, S., Vilata, R., and V. 1220 Lopezalvarez, "Usage of IM for network topology to support 1221 TE Topology YANG Module Development", draft-lam-teas- 1222 usage-info-model-net-topology-03 (work in progress), May 1223 2016. 1225 [6] OMG, "Unified Modeling Language (UML)", 2011, 1226 . 1228 [7] OMG, "ONF TR-514 v1.0 UML Modeling Guidelines", 2015, 1229 . 1233 Authors' Addresses 1235 Scott Mansfield (editor) 1236 Ericsson Inc. 1237 USA 1239 Phone: +1 724 931 9316 1240 Email: scott.mansfield@ericsson.com 1242 Bernd Zeuner 1243 Deutsche Telekom AG 1244 Heinrich-Hertz-Str, 3-7 1245 Darmstadt 64295 1246 Germany 1248 Phone: +49 6151 58-12086 1249 Email: b.zeuner@telekom.de 1251 Nigel Davis 1252 Ciena 1253 United Kingdom 1255 Email: ndavis@ciena.com 1257 Yun Xiang 1258 Fiberhome 1259 China 1261 Email: yunxig@fiberhome.com.cn 1263 Yuji Tochio 1264 Fujitsu 1265 Japan 1267 Email: tochio@jp.fujitsu.com 1269 Hing-Kam Lam 1270 Nokia 1271 USA 1273 Phone: +1 732 331 3476 1274 Email: kam.lam@nokia.com 1275 Eve Varma 1276 Nokia 1277 USA 1279 Email: eve.varma@nokia.com