idnits 2.17.1 draft-kiesewalter-asdf-yang-sdf-00.txt: -(3): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(5): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding 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: ---------------------------------------------------------------------------- == There are 5 instances of lines with non-ascii characters in the document. 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 (12 July 2021) is 1019 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-18) exists of draft-ietf-asdf-sdf-06 Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Kiesewalter 3 Internet-Draft Universität Bremen 4 Intended status: Informational C. Bormann, Ed. 5 Expires: 13 January 2022 Universität Bremen TZI 6 12 July 2021 8 Mapping between YANG and SDF 9 draft-kiesewalter-asdf-yang-sdf-00 11 Abstract 13 YANG and SDF are two languages for modelling the interaction with and 14 the data interchanged with devices in the network. As their areas of 15 application (network management, IoT, resp.) overlap, it is useful to 16 be able to translate between the two. 18 The present specification provides information about how models in 19 one of the two languages can be translated into the other. This 20 specification is not intended to be normative, but to help with 21 creating translators. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on 13 January 2022. 40 Copyright Notice 42 Copyright (c) 2021 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 47 license-info) in effect on the date of publication of this document. 48 Please review these documents carefully, as they describe your rights 49 and restrictions with respect to this document. Code Components 50 extracted from this document must include Simplified BSD License text 51 as described in Section 4.e of the Trust Legal Provisions and are 52 provided without warranty as described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Pairing SDF and YANG features . . . . . . . . . . . . . . . . 3 58 3. Mapping from YANG to SDF . . . . . . . . . . . . . . . . . . 11 59 3.1. Module . . . . . . . . . . . . . . . . . . . . . . . . . 11 60 3.2. Submodule . . . . . . . . . . . . . . . . . . . . . . . . 12 61 3.3. Container Statement . . . . . . . . . . . . . . . . . . . 12 62 3.4. Leaf Statement . . . . . . . . . . . . . . . . . . . . . 13 63 3.5. Leaf-List Statement . . . . . . . . . . . . . . . . . . . 14 64 3.6. List Statement . . . . . . . . . . . . . . . . . . . . . 15 65 3.7. Grouping Statement . . . . . . . . . . . . . . . . . . . 16 66 3.8. Uses Statement . . . . . . . . . . . . . . . . . . . . . 16 67 3.9. Choice Statement . . . . . . . . . . . . . . . . . . . . 16 68 3.10. RPC Statement . . . . . . . . . . . . . . . . . . . . . . 16 69 3.11. Action Statement . . . . . . . . . . . . . . . . . . . . 17 70 3.12. Notification Statement . . . . . . . . . . . . . . . . . 17 71 3.13. Augment Statement . . . . . . . . . . . . . . . . . . . . 18 72 3.14. Anydata and Anyxml Statements . . . . . . . . . . . . . . 18 73 3.15. Type Statement . . . . . . . . . . . . . . . . . . . . . 18 74 3.16. String Built-In Type . . . . . . . . . . . . . . . . . . 19 75 3.17. Decimal64 Built-In Type . . . . . . . . . . . . . . . . . 20 76 3.18. Integer Built-In Types . . . . . . . . . . . . . . . . . 21 77 3.19. Boolean Built-In Type . . . . . . . . . . . . . . . . . . 21 78 3.20. Binary Built-In Type . . . . . . . . . . . . . . . . . . 21 79 3.21. Enumeration Built-In Type . . . . . . . . . . . . . . . . 21 80 3.22. Bits Built-In Type . . . . . . . . . . . . . . . . . . . 22 81 3.23. Union Built-In Type . . . . . . . . . . . . . . . . . . . 22 82 3.24. Leafref and Identityref Built-In Types . . . . . . . . . 22 83 3.25. Empty Built-In Type . . . . . . . . . . . . . . . . . . . 22 84 3.26. Instance-Identifier Built-In Type . . . . . . . . . . . . 23 85 3.27. Derived Type (Typedef) Statement . . . . . . . . . . . . 23 86 3.28. Identity Statement . . . . . . . . . . . . . . . . . . . 23 87 3.29. Config Statement . . . . . . . . . . . . . . . . . . . . 24 88 3.30. Status Statement . . . . . . . . . . . . . . . . . . . . 24 89 3.31. Reference Statement . . . . . . . . . . . . . . . . . . . 24 90 3.32. When and Must Statements . . . . . . . . . . . . . . . . 25 91 3.33. Extension Statement . . . . . . . . . . . . . . . . . . . 25 92 4. Mapping from SDF to YANG . . . . . . . . . . . . . . . . . . 25 93 4.1. Information Block . . . . . . . . . . . . . . . . . . . . 25 94 4.2. Namespace Section . . . . . . . . . . . . . . . . . . . . 26 95 4.3. sdfThing . . . . . . . . . . . . . . . . . . . . . . . . 26 96 4.4. sdfObject . . . . . . . . . . . . . . . . . . . . . . . . 26 97 4.5. Common Qualities . . . . . . . . . . . . . . . . . . . . 27 98 4.6. Data Qualities . . . . . . . . . . . . . . . . . . . . . 28 99 4.7. sdfData . . . . . . . . . . . . . . . . . . . . . . . . . 31 100 4.8. sdfProperty . . . . . . . . . . . . . . . . . . . . . . . 33 101 4.9. sdfAction . . . . . . . . . . . . . . . . . . . . . . . . 33 102 4.10. sdfEvent . . . . . . . . . . . . . . . . . . . . . . . . 34 103 5. Challenges . . . . . . . . . . . . . . . . . . . . . . . . . 34 104 5.1. Differences in Expressiveness of SDF and YANG . . . . . . 35 105 5.2. Round Trips . . . . . . . . . . . . . . . . . . . . . . . 35 106 5.3. Type References . . . . . . . . . . . . . . . . . . . . . 35 107 6. Implementation Considerations . . . . . . . . . . . . . . . . 36 108 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 109 8. Security considerations . . . . . . . . . . . . . . . . . . . 36 110 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 36 111 9.1. Normative References . . . . . . . . . . . . . . . . . . 36 112 9.2. Informative References . . . . . . . . . . . . . . . . . 37 113 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 37 114 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 37 116 1. Introduction 118 YANG [RFC7950] and SDF [I-D.ietf-asdf-sdf] are two languages for 119 modelling the interaction with and the data interchanged with devices 120 in the network. As their areas of application (network management, 121 IoT, resp.) overlap, it is useful to be able to translate between the 122 two. 124 The present specification provides information about how models in 125 one of the two languages can be translated into the other. This 126 specification is not intended to be normative, but to help with 127 creating translators. 129 2. Pairing SDF and YANG features 131 Table 1 gives an overview over how language features of YANG can be 132 mapped to SDF features. In many cases, several translations are 133 possible, and the right choice depends on the context. The mappings 134 in this draft often accommodate the use of the YANG parser Libyang 135 [LIBYANG]. 137 For YANG statements that are not mentioned in the table no conversion 138 to SDF was found that preserves the statement's semantics. 140 For possible conversions of YANG's built-in types please refer to 141 Section 3. Please note that a 'type object' is not the same as an 142 sdfObject but refers to SDF's built-in type 'object', also called 143 compound-type. This built-in type makes use of the 'properties' 144 quality which is not to be confused with the sdfProperty class. The 145 data types number/decimal64, integer, boolean, string are also 146 referred to as simple (data) types. In turn, the types array and 147 object are sometimes referred to as complex (data) types. Concerning 148 YANG, the expression 'schema tree' refers to the model's tree whereas 149 'data tree' describes the tree of an instance of the model. 151 +=================+==============+================================+ 152 | YANG statement | remark on | converted to SDF | 153 | | YANG | | 154 | | statement | | 155 +=================+==============+================================+ 156 | module | | SDF model (i.e., info block, | 157 | | | namespace section & | 158 | | | definitions) | 159 +-----------------+--------------+--------------------------------+ 160 | submodule | included in | integrated into SDF model of | 161 | | supermodule | supermodule | 162 +-----------------+--------------+--------------------------------+ 163 | | on its own | SDF model | 164 +-----------------+--------------+--------------------------------+ 165 | container | top-level | sdfObject | 166 +-----------------+--------------+--------------------------------+ 167 | | one level | sdfProperty of type object | 168 | | below top- | (compound-type) | 169 | | level | | 170 +-----------------+--------------+--------------------------------+ 171 | | on any other | property (type object) of the | 172 | | level | 'parent' definition of type | 173 | | | object (compound-type) | 174 +-----------------+--------------+--------------------------------+ 175 | leaf | on top-level | sdfProperty (type | 176 | | and one | integer/number/boolean/string) | 177 | | level below | | 178 +-----------------+--------------+--------------------------------+ 179 | | on any other | property (type | 180 | | level | integer/number/boolean/string) | 181 | | | of the 'parent' definition of | 182 | | | type object (compound-type) | 183 +-----------------+--------------+--------------------------------+ 184 | leaflist | on top-level | sdfProperty of type array | 185 | | and one | | 186 | | level below | | 187 +-----------------+--------------+--------------------------------+ 188 | | on any other | property (type array) of the | 189 | | level | 'parent' definition of type | 190 | | | object (compound-type) | 191 +-----------------+--------------+--------------------------------+ 192 | list | on top-level | sdfProperty of type array with | 193 | | and one | items of type object | 194 | | level below | (compound-type) | 195 +-----------------+--------------+--------------------------------+ 196 | | on any other | property (type array with | 197 | | level | items of type object | 198 | | | (compound-type)) of the | 199 | | | 'parent' definition of type | 200 | | | object* (compound-type) | 201 +-----------------+--------------+--------------------------------+ 202 | choice | | sdfChoice | 203 +-----------------+--------------+--------------------------------+ 204 | case | belonging to | element of the sdfChoice | 205 | | choice | | 206 +-----------------+--------------+--------------------------------+ 207 | grouping | | sdfData of compound-type (type | 208 | | | object) at the top level which | 209 | | | can then be referenced | 210 +-----------------+--------------+--------------------------------+ 211 | uses | referencing | sdfRef to the SDF definition | 212 | | a grouping | corresponding to the | 213 | | | referenced grouping | 214 +-----------------+--------------+--------------------------------+ 215 | rpc | | sdfAction at the top-level of | 216 | | | the SDF model | 217 +-----------------+--------------+--------------------------------+ 218 | action | | sdfAction of the sdfObject | 219 | | | corresponding to a container | 220 | | | the action is a descendant | 221 | | | node to | 222 +-----------------+--------------+--------------------------------+ 223 | notification | | sdfEvent | 224 +-----------------+--------------+--------------------------------+ 225 | anydata | | not converted | 226 +-----------------+--------------+--------------------------------+ 227 | anyxml | | not converted | 228 +-----------------+--------------+--------------------------------+ 229 | augment | | augment's target is converted | 230 | | | with the augmentation already | 231 | | | applied, mentioned in the | 232 | | | description | 233 +-----------------+--------------+--------------------------------+ 234 | type | referring to | type with other data qualities | 235 | | a built-in | (e.g., default) if necessary | 236 | | type | | 237 +-----------------+--------------+--------------------------------+ 238 | type | referring to | sdfRef to the corresponding | 239 | | a typedef | sdfData element | 240 +-----------------+--------------+--------------------------------+ 241 | base | | sdfRef to the sdfData | 242 | | | definition corresponding the | 243 | | | the base | 244 +-----------------+--------------+--------------------------------+ 245 | bit | | 'parent' definition is of | 246 | | | compound-type and gets one | 247 | | | entry in the properties | 248 | | | quality of type boolean for | 249 | | | each bit | 250 +-----------------+--------------+--------------------------------+ 251 | enum | | each enum statement's argument | 252 | | | is added as an element to the | 253 | | | SDF enum quality's string | 254 | | | array | 255 +-----------------+--------------+--------------------------------+ 256 | fraction-digits | | multipleOf quality | 257 +-----------------+--------------+--------------------------------+ 258 | length | single | minLength/maxLength qualities | 259 | | length range | | 260 +-----------------+--------------+--------------------------------+ 261 | | single value | minLength and maxLength | 262 | | | qualities set to the same | 263 | | | value | 264 +-----------------+--------------+--------------------------------+ 265 | | contains | sdfChoice with alternatives | 266 | | alternatives | for minLength/maxLength | 267 | | | qualities | 268 +-----------------+--------------+--------------------------------+ 269 | path | | sdfRef to the corresponding | 270 | | | SDF definition | 271 +-----------------+--------------+--------------------------------+ 272 | pattern | single | pattern quality | 273 | | pattern | | 274 +-----------------+--------------+--------------------------------+ 275 | | multiple | pattern quality, the regular | 276 | | patterns | expressions are combined using | 277 | | | positive lookahead | 278 +-----------------+--------------+--------------------------------+ 279 | | invert-match | pattern quality, the regular | 280 | | | expression is modified using | 281 | | | negative lookahead | 282 +-----------------+--------------+--------------------------------+ 283 | range | single range | minimum/maximum qualities | 284 +-----------------+--------------+--------------------------------+ 285 | | single value | const quality | 286 | | (constant) | | 287 +-----------------+--------------+--------------------------------+ 288 | | contains | sdfChoice with either minimum/ | 289 | | alternatives | maximum or const quality as | 290 | | | alternatives | 291 +-----------------+--------------+--------------------------------+ 292 | typedef | | sdfData definition, sdfRef | 293 | | | where it is used | 294 +-----------------+--------------+--------------------------------+ 295 | identity | | sdfData definition, sdfRef | 296 | | | where it is used | 297 +-----------------+--------------+--------------------------------+ 298 | config | of a | set writable for all elements | 299 | | container | in the sdfObject that can be | 300 | | that became | marked as writable (i.e., that | 301 | | an sdfObject | use the data qualities) | 302 +-----------------+--------------+--------------------------------+ 303 | | of any other | set writable | 304 | | YANG element | | 305 +-----------------+--------------+--------------------------------+ 306 | import | | the module that the import | 307 | | | references is converted | 308 | | | (elements can now be | 309 | | | referenced by sdfRef) and its | 310 | | | prefix and namespace are added | 311 | | | the to namespace section | 312 +-----------------+--------------+--------------------------------+ 313 | revisions | | first revision date becomes | 314 | | | version in information block | 315 +-----------------+--------------+--------------------------------+ 316 | namespace | | added to namespace section | 317 +-----------------+--------------+--------------------------------+ 318 | prefix | | added to namespace section | 319 +-----------------+--------------+--------------------------------+ 321 Table 1: Mapping YANG to SDF 323 Table 2 provides the inverse mapping. 325 +=============+=========================+===========================+ 326 | SDF quality | remark on SDF quality | converted to YANG | 327 +=============+=========================+===========================+ 328 | sdfThing | | container node | 329 +-------------+-------------------------+---------------------------+ 330 | sdfObject | | container node | 331 +-------------+-------------------------+---------------------------+ 332 | sdfProperty | type | leaf node | 333 | | integer/number/boolean/ | | 334 | | string | | 335 +-------------+-------------------------+---------------------------+ 336 | | type array with items | leaf-list node | 337 | | of type | | 338 | | integer/number/boolean/ | | 339 | | string | | 340 +-------------+-------------------------+---------------------------+ 341 | | type array with items | list node | 342 | | of type object | | 343 | | (compound-type) | | 344 +-------------+-------------------------+---------------------------+ 345 | | type object (compound- | container node | 346 | | type) | | 347 +-------------+-------------------------+---------------------------+ 348 | sdfAction | at the top-level, *not* | rpc node | 349 | | part of an sdfObject | | 350 +-------------+-------------------------+---------------------------+ 351 | | inside of an sdfObject | action node as child | 352 | | | node to the container | 353 | | | corresponding to the | 354 | | | sdfObject | 355 +-------------+-------------------------+---------------------------+ 356 | sdfEvent | | notification node with | 357 | | | child nodes that were | 358 | | | translated like | 359 | | | sdfProperty | 360 +-------------+-------------------------+---------------------------+ 361 | sdfData | type | typedef | 362 | | integer/number/boolean/ | | 363 | | string | | 364 +-------------+-------------------------+---------------------------+ 365 | | type array with items | grouping node with | 366 | | of type | leaf-list child node | 367 | | integer/number/boolean/ | | 368 | | string | | 369 +-------------+-------------------------+---------------------------+ 370 | | type array with items | grouping node with list | 371 | | of type object | child node | 372 | | (compound-type) | | 373 +-------------+-------------------------+---------------------------+ 374 | | type object (compound- | grouping node | 375 | | type) | | 376 +-------------+-------------------------+---------------------------+ 377 | sdfRef | referenced definition | type is set to the | 378 | | was converted to | typedef corresponding | 379 | | typedef | to the sdfData | 380 | | | definition | 381 +-------------+-------------------------+---------------------------+ 382 | | referenced definition | leafref | 383 | | was converted to leaf | | 384 | | or leaf-list node | | 385 +-------------+-------------------------+---------------------------+ 386 | | referenced definition | "uses" node that | 387 | | was converted to | references | 388 | | grouping node | corresponding grouping | 389 | | | (and refine if | 390 | | | necessary) | 391 +-------------+-------------------------+---------------------------+ 392 | sdfRequired | referenced definition | set the mandatory | 393 | | was converted to a leaf | statement of the | 394 | | or choice node | corresponding leaf/ | 395 | | | choice node to true | 396 +-------------+-------------------------+---------------------------+ 397 | | | find the first | 398 | | | descendant node that is | 399 | | | either a leaf/choice | 400 | | | node and set their | 401 | | | mandatory statement to | 402 | | | true or that is a leaf- | 403 | | | list/list node and set | 404 | | | their min-elements | 405 | | | statement to 1 (if not | 406 | | | already >= 0) | 407 +-------------+-------------------------+---------------------------+ 408 | sdfChoice | | choice node with one | 409 | | | case node for each | 410 | | | alternative of the | 411 | | | sdfChoice, each | 412 | | | alternative is | 413 | | | converted like | 414 | | | sdfProperty | 415 +-------------+-------------------------+---------------------------+ 416 | type | | | 417 +-------------+-------------------------+---------------------------+ 418 | const | corresponding YANG | range statement with a | 419 | | element has empty range | single value | 420 +-------------+-------------------------+---------------------------+ 421 | | range not empty | add single value | 422 | | | alternative to range | 423 | | | statement (must be | 424 | | | disjunct) | 425 +-------------+-------------------------+---------------------------+ 426 | default | type is one of | default statement of | 427 | | integer/number/boolean/ | leaf/leaf-list nodes | 428 | | string or array with | | 429 | | items of these types | | 430 +-------------+-------------------------+---------------------------+ 431 | minimum/ | corresponding YANG | range statement | 432 | maximum | element has empty range | | 433 +-------------+-------------------------+---------------------------+ 434 | | range not empty | add range alternative | 435 | | | to range statement | 436 | | | (must be disjunct) | 437 +-------------+-------------------------+---------------------------+ 438 | multipleOf | | fraction-digits | 439 | | | statement | 440 +-------------+-------------------------+---------------------------+ 441 | minLength/ | | length statement | 442 | maxLength | | | 443 +-------------+-------------------------+---------------------------+ 444 | pattern | | pattern statement | 445 +-------------+-------------------------+---------------------------+ 446 | minItems/ | | min-elements/max- | 447 | maxItems | | elements statements | 448 +-------------+-------------------------+---------------------------+ 449 | uniqueItems | if the 'parent' SDF | unique statement | 450 | set to true | definition is converted | mentioning all of the | 451 | | to a list node | leaf/leaf-list nodes in | 452 | | | the list node's sub- | 453 | | | tree | 454 +-------------+-------------------------+---------------------------+ 455 | items | | sub-statements of list/ | 456 | | | leaf-list node | 457 | | | corresponding to the | 458 | | | item quality's 'parent' | 459 | | | definition | 460 +-------------+-------------------------+---------------------------+ 461 | properties | | child nodes of | 462 | | | container/grouping node | 463 | | | corresponding to the | 464 | | | properties quality's | 465 | | | 'parent' definition | 466 +-------------+-------------------------+---------------------------+ 467 | unit | | units statement | 468 +-------------+-------------------------+---------------------------+ 469 | enum | | type enumeration with | 470 | | | enum statements for | 471 | | | each string in the SDF | 472 | | | enum quality | 473 +-------------+-------------------------+---------------------------+ 474 | sdfType | has value 'byte-string' | built-in type 'binary' | 475 +-------------+-------------------------+---------------------------+ 476 | writable | | config statement | 477 +-------------+-------------------------+---------------------------+ 479 Table 2: Mapping SDF to YANG 481 3. Mapping from YANG to SDF 483 This section specifies one possible mapping for each of the YANG 484 statements to SDF in detail. For reference on the individual YANG 485 statements see [RFC7950] and [I-D.ietf-asdf-sdf] for SDF. 487 3.1. Module 489 * YANG: Section 7.1 (module) of [RFC7950] 491 * SDF: 493 - Section 3.1 (information block) of [I-D.ietf-asdf-sdf] 495 - Sections 3.2 and 4 (namespaces section) of [I-D.ietf-asdf-sdf] 497 After conversion the SDF model as a whole corresponds to the YANG 498 module. The argument of the "namespace" statement of the YANG module 499 is added to the SDF "namespace section" together with the argument of 500 the YANG module's "prefix" statement which also becomes the "default 501 namespace" in the SDF model. Additionally, the namespaces and 502 prefixes of each of the modules mentioned in the "import" statements 503 are added to the namespace of the SDF model. Libyang loads the 504 imported modules automatically and in the correct revision. These 505 modules are then also converted and stored so their definitions can 506 be referenced via the "sdfRef" common quality when necessary. 508 The contents of the "organization", "contact" and "yang-version" 509 statements are stored alongside the actual "description" of the YANG 510 module in a special sdfData definition designated to hold information 511 on the module that does not fit into the SDF information block. This 512 is done in the way described in Section 5.2 to facilitate round trips 513 in the future. The module's description is scanned for information 514 regarding copyright and licensing which are then transferred to the 515 "copyright" and "license" qualities of the SDF model's information 516 block. The "version" quality of the SDF model's information block is 517 set to the first revision date given in the YANG module's "revision" 518 statement. All other revision dates are ignored as of now. 520 YANG modules can define features via the "feature" statement to make 521 parts of the module conditional. The abilities of a server are 522 checked against the module's features. Nodes reference features as 523 an argument to the "if-feature" statement. If a server does not 524 support a certain feature nodes that reference that feature are 525 ignored by the server. Since this functionality cannot be 526 represented in SDF yet, YANG features are stored in the description 527 of the sdfData definition designated to hold information on the 528 module. The note that is added to the descriptions looks as 529 described in Section 5.2. 531 If the "deviation" statement (introducing a deviation from the 532 original YANG module) is present in the YANG module Libyang applies 533 the deviation directly and the converter converts the module that 534 way. The presence of the deviation in the original YANG module is 535 not indicated in the resulting SDF model as of now which might cause 536 inconsistencies after round trips. 538 3.2. Submodule 540 * YANG: Section 7.2 (submodule) of [RFC7950] 542 A sub-module that is included into its super-module via the "include" 543 statement is integrated into the super-module and converted that way. 544 This is the simplest option due to the way Libyang represents 545 included sub-modules. A sub-module that occurs without its super- 546 module is converted to its own SDF model as described in Section 3.1. 548 3.3. Container Statement 550 * YANG: Section 7.5 (container) of [RFC7950] 552 * SDF: 554 - Sections 2.2.1 and 5.1 (sdfObject) of [I-D.ietf-asdf-sdf] 556 - Sections 2.2.6 and 6.3 (sdfThing) of [I-D.ietf-asdf-sdf] 558 YANG uses container nodes to group together other nodes. Containers 559 on the top-level of a module are converted to sdfObjects. A 560 container that is a direct child node to a top-level container node 561 is converted to a compound-type sdfProperty inside of said sdfObject. 562 Any other container becomes a property of the compound-type 563 definition corresponding to the container's parent node. Since the 564 first SDF draft did not contain the compound-type as a possible 565 argument to the type quality containers used to be translated to 566 sdfThings. This, however, was not a very fitting conversion 567 semantically. At that time, sdfThings were the only elements that 568 could contain elements of the same class, i.e., sdfThings could 569 contain other sdfThings. This ability is required to represent the 570 tree structure of YANG where e.g., containers can contain other 571 containers. In the next SDF draft the compound-type was introduced. 572 This feature effectively makes it possible for elements of the 573 sdfData and sdfProperty classes to contain elements that share the 574 same qualities. A sub-statement to the container statement that 575 cannot be represented in SDF as of now is the optional "presence" 576 statement. The argument of the presence statement assigns a meaning 577 to the presence or absence of a container node in an instance of the 578 module. This concept is expressed in the description of the SDF 579 definition analogously to the container node as shown in Section 5.2. 581 3.4. Leaf Statement 583 * YANG: Section 7.6 (leaf) of [RFC7950] 585 * SDF: 587 - Sections 2.2.2 and 5.2 (sdfProperty) of [I-D.ietf-asdf-sdf] 589 - Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf] 591 Leaf nodes in YANG represent scalar variables. If a leaf node occurs 592 at the top-level of the module or as a direct child node of a top- 593 level container (which is converted to sdfObject) it is transformed 594 to an sdfProperty. On any other level a leaf becomes a property of 595 the compound-type definition equivalent to the leaf's parent node. 596 In both cases the SDF "type" data quality is set to one of the simple 597 data types because leaf nodes can only be of simple data types. Leaf 598 nodes can be assigned default values which are used in case the leaf 599 node does not exist in an instance of the YANG module. A leaf's 600 default value is converted to SDF as the data quality "default". The 601 "units" sub-statement of a leaf node in YANG becomes the SDF data 602 quality "unit". This quality is constrained to the SenML unit names. 603 Although it could cause conformance issues, the content of the YANG 604 units statement is not processed to fit the SenML unit names as of 605 now. This is due to the low probability that a unit from a YANG 606 module is not listed in the SenML unit names in comparison to the 607 time required to implement a mechanism to check conformance and 608 convert non-conforming units. This feature might be added in later 609 versions of the converter, though. YANG leaf nodes can be marked as 610 mandatory to occur in an instance of the module by the "mandatory" 611 statement. The statement takes "true" and "false" as arguments. 612 This can easily be mapped to SDF through the sdfRequired common 613 quality. A reference to the SDF definition equivalent to the YANG 614 leaf node marked as mandatory is added to the containing sdfObject's 615 sdfRequired quality. If the sdfRequired quality does not already 616 exist in the sdfObject it is added now. 618 3.5. Leaf-List Statement 620 * YANG: Section 7.7 (leaf-list) of [RFC7950] 622 * SDF: 624 - Sections 2.2.2 and 5.2 (sdfProperty) of [I-D.ietf-asdf-sdf] 626 - Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf] 628 Similarly to leaf nodes, leaf-list nodes hold data of simple types in 629 YANG but as items in an array. As such, leaf-list definitions are 630 converted to sdfProperty if they occur on the top-level or one level 631 below in a module. On any other level a leaf-list becomes a property 632 of the compound-type definition corresponding to the leaf-list's 633 parent definition. In both cases the type is set to "array". The 634 items of the array are of simple data types since leaf-list 635 definitions can only have simple data types as well. The minimal and 636 maximal number of elements in a YANG leaf-list can be specified by 637 the "min-elements" and "max-elements" sub-statements. This is 638 analogous to SDF's "minItems" and "maxItems" data qualities which are 639 set accordingly by the converter. A YANG leaf-list can specify 640 whether the system or the user is responsible for ordering the leaf- 641 lists entries. This information is stored in the "ordered-by" 642 statement in YANG which is represented in SDF by a remark in the 643 description (as shown in Section 5.2) of the SDF equivalent to the 644 leaf-list node in question. Since leaf-list nodes are just leaf 645 nodes that can occur multiple times the "units" and "default" 646 statements of leaf-list nodes are converted as described in 647 Section 3.4. 649 3.6. List Statement 651 * YANG: Section 7.8 (list) of [RFC7950] 653 * SDF: 655 - Sections 2.2.2 and 5.2 (sdfProperty) of [I-D.ietf-asdf-sdf] 657 - Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf] 659 Since list nodes are similar to leaf-list nodes with the difference 660 that they represent an assortment of nodes that can occur multiple 661 times they are also converted similarly. List nodes one the top- 662 level or one level below become sdfProperties. On any other level a 663 list node is converted to a property of the compound-type definition 664 corresponding to the list's parent node. The type is set to "array" 665 for both alternatives. Since lists contain a set of nodes the items 666 of the corresponding array are of type object. The minimal and 667 maximal number of elements in a YANG list can be specified by the 668 "min-elements" and "max-elements" sub-statements. This is analogous 669 to SDF's "minItems" and "maxItems" data qualities which are set 670 accordingly by the converter. List nodes in YANG can define one or 671 multiple keys that identify the list entries via the "key" statement. 672 There is no SDF quality representing this feature. To preserve the 673 information the list keys are stored in the description of the SDF 674 definition analogously to the YANG list node as described in 675 Section 5.2. The YANG list's "unique" sub-statement defines a list 676 of descendant leaf nodes of the list that must have a unique 677 combination of values each. This concept is comparable SDF's 678 "uniqeItems" data quality. However, the boolean-typed uniqueItems 679 quality specifies whether all items of an SDF array have to be unique 680 as opposed to only a selection of unique items in the YANG statement 681 unique. To mitigate this discrepancy a note is added to the SDF 682 equivalents of all descendant leaf nodes of a list that are marked as 683 unique as shown in Section 5.2. Since list nodes are similar to 684 leaf-list nodes the "ordered-by" statement of a list node is 685 converted as described in Section 3.5. 687 3.7. Grouping Statement 689 * YANG: Section 7.12 (grouping) of [RFC7950] 691 * SDF: Section 5.5 (sdfData) of [I-D.ietf-asdf-sdf] 693 Grouping nodes are very similar to container nodes with the 694 difference that the set of nodes defined in a grouping do not occur 695 in the data tree unless the grouping has been referenced one or more 696 times by "uses" nodes. Thus, a grouping node is converted to a 697 compound-type sdfData definition which also defines a reusable 698 definition that is not a declaration. 700 3.8. Uses Statement 702 * YANG: Section 7.13 (uses) of [RFC7950] 704 * SDF: Section 4.4 (sdfRef) of [I-D.ietf-asdf-sdf] 706 A "uses" node has the purpose of referencing a grouping node. The 707 set of child nodes of the referenced grouping are copied to wherever 708 the "uses" node is featured. Some of the referenced grouping's sub- 709 statements can be altered via the refine statement of the "uses" 710 node. In SDF a "uses" node is represented by the sdfRef quality 711 which is added to the definition corresponding to the parent node of 712 the "uses" node. As an argument the sdfRef contains a reference to 713 the sdfData definition corresponding to the grouping referenced by 714 the "uses" node. If the "uses" node contains a refine statement its 715 contents are converted as they would be if they occurred in a node. 717 3.9. Choice Statement 719 * YANG: Section 7.9 (choice) of [RFC7950] 721 * SDF: Section 4.7.2 (sdfChoice) of [I-D.ietf-asdf-sdf] 723 Conversion of the choice definitions from YANG is quite simple since 724 it is similar to the sdfChoice quality. A choice definition is 725 converted to an sdfChoice definition. The case definitions or other 726 child definitions of the choice become one of the named alternatives 727 of the resulting sdfChoice each. 729 3.10. RPC Statement 731 * YANG: Section 7.14 (rpc) of [RFC7950] 733 * SDF: Sections 2.2.3 and 5.3 (sdfAction) of [I-D.ietf-asdf-sdf] 734 Remote procedure calls (RPCs) can be modelled in YANG with RPC nodes 735 which have up to one "input" child node holding the commands input 736 data and up to one "output" node for the output data. In YANG RPCs 737 can only occur on the top-level because in contrast to actions in 738 YANG they do not belong to a container. This can easily be 739 represented by sdfActions. The corresponding sdfAction is not placed 740 inside an sdfObject or sdfThing but at the top-level of the SDF model 741 to represent independence from a container. The input node of the 742 RPC is converted to the sdfInputData quality of the sdfAction which 743 is of type object. Equivalently the output node of the RPC becomes 744 the sdfAction's sdfOutputData which is also of type object. 745 Groupings and typedefs in the RPC are converted to sdfData 746 definitions inside the sdfAction. 748 3.11. Action Statement 750 * YANG: Section 7.15 (action) of [RFC7950] 752 * SDF: Sections 2.2.3 and 5.3 (sdfAction) of [I-D.ietf-asdf-sdf] 754 Action nodes in YANG work similarly to RPC nodes in the way that they 755 are used to model operations that can be invoked in the module and 756 also have up to one input and output child node respectively. As 757 mentioned before YANG actions are affiliated to a container though. 758 The representation of this affiliation is not quite trivial because 759 YANG containers are not translated to sdfObjects in all cases. Only 760 sdfObjects can have sdfActions, though. If an action occurs in a 761 container that is a below-top-level container (and thus not converted 762 to sdfObject) the affiliation cannot be represented directly in SDF 763 as of now. To keep the semantics of the affiliation a copy of the 764 contents of the converted container is added to the sdfAction's 765 sdfInputData. Like for RPC nodes, the input nodes of the action are 766 converted to the sdfInputData quality of the sdfAction which is of 767 type object. Equivalently the output nodes of the action become the 768 sdfAction's sdfOutputData which is also of type object. Groupings 769 and typedefs in the action node are converted to sdfData definitions 770 inside the sdfAction. 772 3.12. Notification Statement 774 * YANG: Section 7.16 (notification) of [RFC7950] 776 * SDF: Sections 2.2.4 and 5.4 (sdfEvent) of [I-D.ietf-asdf-sdf] 777 In YANG, notification nodes are used to model notification messages. 778 Notification nodes are converted to sdfEvent definitions. Their 779 child nodes are converted to the sdfEvent's sdfOutputData which is of 780 type object. Groupings and typedefs in the notification node are 781 converted to sdfData definitions inside the sdfEvent. 783 3.13. Augment Statement 785 * YANG: Section 7.17 (augment) of [RFC7950] 787 * SDF: Section 4.6. (common qualities) of [I-D.ietf-asdf-sdf] 789 The augment statement can either occur at the top-level of a module 790 to add nodes to an existing target module or sub-module or in a 791 "uses" statement to augment the targeted grouping. The conversion of 792 the augment statement to SDF is not trivial because SDF does not 793 feature this mechanism directly. Since the tool used to deserialize 794 YANG modules (Libyang) adds the nodes into the augment statement's 795 target automatically this is adopted for conversion. The SDF model 796 or sdfData definition that corresponds to the augment statement's 797 target is converted with the augmentation already applied. A comment 798 is added to the description as described in Section 5.2 to preserve 799 where the augmentation was made from. If the resulting SDF model has 800 to be converted back to YANG definitions that are marked as 801 augmentations are converted back accordingly. 803 3.14. Anydata and Anyxml Statements 805 * YANG: Sections 7.10 and 7.11 (augment) of [RFC7950] 807 * SDF: Section 4.6 (common qualities) of [I-D.ietf-asdf-sdf] 809 The "anydata" and "anyxml" statements are designated for nodes in the 810 schema tree whose structure is unknown at the module's design time or 811 in general. Since this is not a concept that can be represented in 812 SDF as of now, anydata and anyxml nodes are not converted. To 813 preserve the information (e.g., for round trips) a comment is added 814 to the SDF element corresponding to the anydata/anyxml node's parent 815 node as described in Section 5.2. 817 3.15. Type Statement 819 * YANG: Section 7.4 (type) of [RFC7950] 821 * SDF: Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf] 822 Conversion for the "type" statement from YANG is very straightforward 823 if the argument is a simple data type since the SDF data qualities 824 also contain a "type" quality. A derived type used as an argument to 825 the YANG "type" statement is converted to an "sdfRef" to the 826 "sdfData" corresponding to that derived type. If the derived type is 827 restricted (e.g., via the length statement) the restrictions are 828 converted as they would be for the base type and added to the SDF 829 definition containing the type in question. 831 There are multiple sub-statements to the type statement that depend 832 on its value. 834 3.16. String Built-In Type 836 * YANG: Section 9.4 (string) of [RFC7950] 838 * SDF: Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf] 840 The YANG built-in type string is converted to SDF's built-in type 841 string. Strings in YANG can be restricted regarding their length and 842 patterns (containing regular expressions). 844 The length statement can specify either a constant length, a lower 845 inclusive length, an upper inclusive length or both a lower and upper 846 inclusive length. A length statement can also specify more than one 847 disjoint constant length or length ranges. The values "min" and 848 "max" in a length statement represent the minimum and maximum lengths 849 accepted for strings. If the length statement in YANG does not 850 contain a constant value but a length range it is converted to the 851 "minLength" and "maxLength" data qualities in SDF. If a constant 852 value is defined through the YANG length statement the "minLength" 853 and "maxLength" qualities are set to the same value. If the length 854 statement specifies multiple length ranges or constant values the 855 sdfChoice quality is used for conversion. The named alternatives of 856 the sdfChoice contain the single converted length ranges or constant 857 values each. If the "min" and "max" values are present in the YANG 858 length statement they are converted to the respective minimum and 859 maximum lengths accepted for strings. 861 To represent YANG string patterns the "pattern" data quality of SDF 862 can be used. One problem in the conversion of patterns is that YANG 863 strings can be restricted by multiple patterns but SDF definitions of 864 type string can have at most one pattern. To represent multiple 865 patterns from YANG in SDF the patterns are combined into one regular 866 expression with the help of positive look-ahead. This, however, does 867 not always convey the meaning of the original regular expression. 868 Another issue is the possibility to declare invert-match patterns in 869 YANG. These types of patterns are converted to SDF by adding 870 negative look-ahead to the regular expression. To preserve the 871 original patterns and to facilitate round trips the original patterns 872 are stored in the description of the containing definition as 873 described in Section 5.2. 875 Another, more general problem regarding the conversion of regular 876 expressions from YANG to SDF is the fact that YANG uses a regular 877 expression language as defined by W3C Schema while SDF adopts the one 878 from JSON Schema. Both regular expression languages share most of 879 their features but differ in some details. Since this does not cause 880 problems in most cases and regarding the time constraints of this 881 thesis, this issue is not given any further attention beyond what was 882 stated in this paragraph. There is, however, a project of the IETF 883 Network Working Group to create an interoperable regular expression 884 format I-Regexp. Once the work on the draft has progressed the 885 format might be adopted by the converter. 887 3.17. Decimal64 Built-In Type 889 * YANG: Section 9.3 (decimal64) of [RFC7950] 891 * SDF: Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf] 893 The decimal64 built-in type of YANG is converted to the number type 894 in SDF. A decimal64 type in YANG has a mandatory "fraction-digits" 895 sub-statement that specifies the possible number of digits after the 896 decimal separator. The value of the fraction-digits statement is 897 converted to the "multipleOf" data quality of SDF which states the 898 resolution of a number, i.e., the size of the minimal distance 899 between number values. 901 A YANG decimal64 type can be restricted by means of the range 902 statement specifying either a constant value, a lower inclusive 903 bound, an upper inclusive bound or both a lower and upper inclusive 904 value. A range statement can also specify more than one disjoint 905 constant values or ranges. The values "min" and "max" in a range 906 represent the minimum and maximum values of the type in question. If 907 the range statement in YANG contains a range and not a constant value 908 it is converted to the "minimum" and "maximum" data qualities in SDF. 909 If a constant value is defined through the YANG range the SDF "const" 910 data quality is set accordingly. If the range specifies multiple 911 ranges or constant values, the sdfChoice quality is used for 912 conversion. The named alternatives of the sdfChoice contain the 913 single converted ranges or constant values each. If the "min" and 914 "max" values are present in the YANG range they are converted to the 915 respective minimum and maximum values for the type in question. 917 3.18. Integer Built-In Types 919 * YANG: Section 9.2 (integer) of [RFC7950] 921 * SDF: Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf] 923 In YANG there are 8 different integer types (int8, uint8, int16, 924 uint16, int32, uint32, int64, uint64). Each of them is converted to 925 integer in SDF. A comment specifying the exact type is added as 926 described in Section 5.2. Additionally, the "minimum" and "maximum" 927 qualities of the SDF definition the converted type belongs to are set 928 to the respective minimum and maximum values of the integer type in 929 question. If the YANG type also specifies a range the minimum and 930 maximum SDF qualities are altered accordingly. Like the decimal64 931 YANG built-in type integer types can also be restricted by a range 932 statement. This range statement is converted as described in 933 Section 3.17. 935 3.19. Boolean Built-In Type 937 * YANG: Section 9.5 (boolean) of [RFC7950] 939 * SDF: Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf] 941 YANG's boolean built-in type is converted to SDF's boolean type. 942 There are no further sub-statements to this type in YANG. 944 3.20. Binary Built-In Type 946 * YANG: Section 9.8 (binary) of [RFC7950] 948 * SDF: Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf] 950 If the argument of the YANG type statement is "binary" the SDF type 951 quality is set to string. In addition, the sdfType quality is set to 952 "byte-string". A YANG binary can have a sub-statement restricting 953 its length. This is converted to SDF via the "minLength" and 954 "maxLength" data qualities. Like the string YANG built-in type 955 binary types can also be restricted by a length statement. This 956 length statement is converted as described in Section 3.16 958 3.21. Enumeration Built-In Type 960 * YANG: Section 9.6 (enumeration) of [RFC7950] 962 * SDF: Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf] 963 The YANG built-in type "enumeration" is used to map string-valued 964 alternatives to integer values. Additionally, each string can have a 965 description and other sub-statements. SDF also specifies an "enum" 966 quality which is used to represent YANG enumerations. Since the SDF 967 enum quality only holds an array of strings all other information is 968 stored in the description of the SDF definition the enum belongs to. 970 3.22. Bits Built-In Type 972 * YANG: Section 9.8 (bits) of [RFC7950] 974 * SDF: Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf] 976 Since SDF does not specify a built-in type to represent a set of 977 named bits and their positions like YANG does this YANG built-in type 978 has to be converted to SDF type object with one property of type 979 boolean for each bit. The property is named after the bit's name and 980 the bit's position is stored in the property's description as 981 described in Section 5.2. 983 3.23. Union Built-In Type 985 * YANG: Section 9.12 (union) of [RFC7950] 987 * SDF: Section 4.7.2 (sdfChoice) of [I-D.ietf-asdf-sdf] 989 Although the "union" built-in type of YANG does not exist as a built- 990 in type in SDF its meaning can be easily represented by the sdfChoice 991 quality. YANG unions hold a set of alternative types. The 992 corresponding sdfChoice contains a set of named alternatives each 993 containing only the SDF type quality and named after the respective 994 type in the YANG union. 996 3.24. Leafref and Identityref Built-In Types 998 * YANG: Section 9.9 (leafref) of [RFC7950] Section 9.10 999 (identityref) of [RFC7950] 1001 * SDF: Section 4.4 (sdfRef) of [I-D.ietf-asdf-sdf] 1003 YANG's built-in types "leafref" and "identityref" are used to 1004 reference a leaf node or identity definition respectively. They are 1005 represented in SDF by the sdfRef quality. As an argument said sdfRef 1006 quality contains a reference to the SDF element corresponding to the 1007 target of the leafref or identityref statement. 1009 3.25. Empty Built-In Type 1010 * YANG: Section 9.11 (empty) of [RFC7950] 1012 * SDF: Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf] 1014 Another concept that is not contained in SDF directly is that of 1015 YANG's built-in type "empty". YANG elements with this type convey 1016 meaning by their mere existence or non-existence. This is 1017 represented in SDF using the compound-type with an empty set of 1018 properties. 1020 3.26. Instance-Identifier Built-In Type 1022 * YANG: Section 9.13 (instance-identifier) of [RFC7950] 1024 The "instance-indentifier" built-in type of YANG cannot be 1025 represented in SDF as of now since there is currently no possibility 1026 to specify SDF instances. This feature might be added to SDF in the 1027 future, though . 1029 3.27. Derived Type (Typedef) Statement 1031 * YANG: Section 9.3 (typedef) of [RFC7950] 1033 * SDF: Section 4.4 (sdfRef) of [I-D.ietf-asdf-sdf] 1035 The SDF class "sdfData" is used to represent YANG "typedefs" after 1036 conversion. The usage of a derived type via the "type" statement is 1037 converted to an "sdfRef" to the corresponding sdfData definition. If 1038 a derived type is restricted according to its base type (e.g., with a 1039 range statement) the restrictions are converted as they would be for 1040 the base type and added to the sdfData definition. 1042 3.28. Identity Statement 1044 * YANG: Section 7.18 (identity) of [RFC7950] 1046 * SDF: Section 5.5 (sdfData) of [I-D.ietf-asdf-sdf] 1048 The YANG identity statement is used to denote the name and existence 1049 of an identity. Identities can be based on one ore more other 1050 identities. They are referenced with the "identityref" statement. 1051 This concept is converted to SDF by sdfData definitions for each 1052 identity. If an identity is based on one other identity this is 1053 represented in by an sdfRef to the sdfData element corresponding to 1054 the base identity. If an identity has multiple base identities it is 1055 converted to a compound-type sdfData definition with one property for 1056 each base identity. Each property contains an sdfRef to the sdfData 1057 element corresponding to one of the base identities. 1059 3.29. Config Statement 1061 * YANG: Section 7.21.1 (config) of [RFC7950] 1063 * SDF: Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf] 1065 The config statement of YANG can have the boolean values "true" or 1066 "false" as arguments. If config is set to true the element 1067 containing the config statement represents readable and writable 1068 configuration data. If config is set to false, the element 1069 containing the config statement represents read-only state data. 1070 This is transferred to SDF via the "readable" and "writable" data 1071 qualities. YANG config with the argument true is converted to 1072 readable and writable being set to true, config with the argument 1073 false is converted as readable set to true and writable set to false. 1074 There are, however, cases in which the SDF definition corresponding 1075 to the YANG element containing the config statement is not one that 1076 can use data qualities (i.e., is not sdfData or sdfProperty). This 1077 is the case if a top-level container which is converted to sdfObject 1078 holds a config statement. In this case, all definitions inside the 1079 sdfObject that can use data qualities have readable and writable set 1080 as described above. 1082 3.30. Status Statement 1084 * YANG: Section 7.21.2 (status) of [RFC7950] 1086 * SDF: Section 4.6 (common qualities) of [I-D.ietf-asdf-sdf] 1088 The status statement of YANG is used to express whether a definition 1089 is current, deprecated or obsolete which are the three possible 1090 arguments of the statement. In SDF there is no quality with a 1091 similar meaning. Thus, the YANG status statement is represented by a 1092 note in the description of the SDF definition corresponding to the 1093 YANG element the status statement occurred in as described in 1094 Section 5.2. 1096 3.31. Reference Statement 1098 * YANG: Section 7.21.4 (reference) of [RFC7950] 1100 * SDF: Section 4.6 (common qualities) of [I-D.ietf-asdf-sdf] 1102 In YANG the reference statement holds a human-readable reference to 1103 an external document related to its containing YANG definition. This 1104 is simply stored in the description of the SDF definition analogously 1105 to the reference statement's parent YANG definition as described in 1106 Section 5.2. 1108 3.32. When and Must Statements 1110 * YANG: Section 7.5.3 (must) of [RFC7950] Section 7.21.5 (when) of 1111 [RFC7950] 1113 * SDF: Section 4.6 (common qualities) of [I-D.ietf-asdf-sdf] 1115 As mentioned before in Section 3.1 YANG provides means to impose 1116 conditions on its definitions. If a node in an instance of the YANG 1117 module has an unfulfilled must or when condition it is invalidated. 1118 Must and when conditions use XML Path Language expressions to 1119 indicate dependencies. This feature is not realizable in SDF as of 1120 now. However, there is a query language similar to XML Path Language 1121 for JSON called JSONPath (CITE!). If SDF adopts JSONPath or 1122 something similar in the future the converter can be extended to 1123 process the functionality of must and when statements. 1125 3.33. Extension Statement 1127 * YANG: Section 7.19 (extension) of [RFC7950] 1129 * SDF: Section 4.6 (common qualities) of [I-D.ietf-asdf-sdf] 1131 The extension statement in YANG has the purpose of defining new 1132 statements for the YANG language. This is not a concept that can be 1133 transferred to SDF yet and thus has to be stored in the description 1134 of the SDF definition analogously to the extension statement's parent 1135 YANG definition as described in Section 5.2. 1137 4. Mapping from SDF to YANG 1139 In this section the conversion of each element of SDF to YANG is 1140 explained in detail. For reference on the individual YANG statements 1141 see [RFC7950] and [I-D.ietf-asdf-sdf] for SDF. 1143 4.1. Information Block 1145 * SDF: Section 3.1 (information block) of [I-D.ietf-asdf-sdf] 1147 * YANG: Section 7.1 (module) of [RFC7950] 1149 At the top of an SDF model the information block holds metadata 1150 (title, version, copyright and license information) about the model. 1151 The content of the "title" quality is used as the name for the YANG 1152 module. For this, the title string has to be modified to only 1153 contain lower case letters, digits and the characters "_", "-" and 1154 ".". If the "version" quality contains a date in the format month- 1155 day-year it is analogous to YANG's revision statement and converted 1156 as such. The strings from the copyright and license qualities are 1157 stored in the description of the resulting YANG module since there 1158 are no dedicated YANG statements equivalent to these qualities. 1160 4.2. Namespace Section 1162 * SDF: Sections 3.2 and 4 (namespaces section) of 1163 [I-D.ietf-asdf-sdf] 1165 * YANG: Section 7.1.3 (namespace) of [RFC7950] Section 7.1.5 1166 (import) of [RFC7950] 1168 The purpose of SDF's namespace section is to specify the namespaces 1169 of the external models whose definitions are used in this model and 1170 possibly the namespace of this model. The namespace section has a 1171 "namespace" quality mapping namespace URIs to a shortened name for 1172 that URI (used as a prefix for external definitions). If an SDF 1173 model is supposed to contribute globally available definitions a 1174 value is given for the "defaultNamespace" quality and mapped to a 1175 namespace URI in the "namespace" quality. To map this to YANG three 1176 of its statements are necessary. To be able to use definitions from 1177 external modules in YANG the modules' names have to be declared by 1178 one "import" statement each. Thus, each external SDF model that is 1179 mentioned in the namespace map is converted to a YANG module as well. 1180 The corresponding SDF model files have to be available in the same 1181 directory as the model file of this model. The external SDF model's 1182 default namespace is represented in the "prefix" sub-statement of the 1183 "import" statement. To represent the own namespace and short name 1184 for it (if present) the YANG "namespace" and "prefix" statements that 1185 are both top-level statements are set accordingly. 1187 4.3. sdfThing 1189 * SDF: Sections 2.2.6 and 6.3 (sdfThing) of [I-D.ietf-asdf-sdf] 1191 * YANG: Section 7.5 (container) of [RFC7950] 1193 An sdfThing definition holds the model of a complex device that can 1194 be made up of one or more sdfObject and/or other sdfThing 1195 definitions. SdfThings are converted to YANG container nodes. 1197 4.4. sdfObject 1199 * SDF: Sections 2.2.1 and 5.1 (sdfObject) of [I-D.ietf-asdf-sdf] 1201 * YANG: Section 7.5 (container) of [RFC7950] 1202 SdfObject definitions are the main building blocks of an SDF model 1203 grouping together definitions of the classes sdfProperty, sdfData, 1204 sdfAction and sdfEvent. They can also be used as arrays via their 1205 "minItems" and "maxItems" qualities. An sdfObject is mapped to a 1206 YANG container node if it is not defined as an array. Otherwise the 1207 sdfObject is converted to a list node with the "min-elements" and 1208 "max-elements" statements set analogous to the "minItems" and 1209 "maxItems" qualities. 1211 4.5. Common Qualities 1213 * SDF: Section 4.6 (common qualities) of [I-D.ietf-asdf-sdf] 1215 * YANG: 1217 - Section 7.21.3 (description) of [RFC7950] 1219 - Section 7.3 (typedef) of [RFC7950] 1221 - Section 9.9 (leafref) of [RFC7950] 1223 - Section 7.13 (uses) of [RFC7950] 1225 - Section 3 (terminology for mandatory) of [RFC7950] 1227 The set of qualities that is grouped under the name of common 1228 qualities can be used to provide meta data for SDF definitions. The 1229 "description" quality is converted to the YANG description statement. 1230 The "label" quality is ignored because it is identical to the 1231 definitions identifier in most cases. 1233 The "sdfRef" quality is supposed to hold references to other 1234 definitions. The qualities of the referenced definition are copied 1235 into the referencing definition if they are not overwritten in the 1236 referencing definition. The conversion of an sdfRef depends on what 1237 is referenced by it and what that is converted to. If the referenced 1238 definition is converted to a typedef the sdfRef is analogous to the 1239 "type" statement in YANG which points to the typedef. If the 1240 referenced definition is mapped to a leaf or leaf-list node it can be 1241 referenced by the "leafref" built-in type in YANG. If the referenced 1242 definition's equivalent in YANG is a grouping node the sdfRef gets 1243 converted to a "uses" node which points to said grouping. In all 1244 other cases the referenced definition's equivalent cannot be 1245 referenced directly but has first to be packaged in a grouping node. 1246 This is done by first creating a grouping as a sibling node to the 1247 referenced definition's equivalent YANG node and copying the 1248 equivalent node into the new grouping. After that the equivalent 1249 node is replaced it with a "uses" node referencing the grouping. 1251 This is done to avoid redundancy. Lastly, the actual sdfRef is 1252 represented by another "uses" node referencing the newly created 1253 grouping. 1255 The common quality "sdfRequired" contains a list of SDF declarations 1256 that are mandatory to be present in an instance of the SDF model. 1257 The issue with the conversion of this quality is that in YANG only 1258 leaf and choice nodes (and anyxml and anydata nodes but these are not 1259 used for conversion) can be labelled as mandatory while in SDF all 1260 declarations (i.e., sdfProperties, sdfActions and sdfEvents that 1261 occur in an sdfObject) can be mentioned in the sdfRequired list. Not 1262 all SDF declarations are always converted to YANG leaf or choice 1263 nodes, however. To partially make up for this discrepancy, if the 1264 YANG node equivalent of the mandatory SDF declaration is container 1265 node the node's sub-tree is traversed until a leaf or choice node is 1266 found. This leaf or choice node is labelled as mandatory, now making 1267 its parent container mandatory as well because one of its child nodes 1268 is mandatory. Consequently, if the parent node of the now mandatory 1269 container was a container it would now be mandatory as well. 1270 Alternatively, if a list or leaf-list node is found first the node's 1271 "min-elements" statement is set to one if it is not already set to a 1272 value greater than zero. This also makes a node mandatory. To 1273 facilitate retracing the declaration originally listed in the 1274 "sdfRequired" quality, e.g., for round trips, the "sdf-spec" 1275 extension statement is set as described in Section 5.2. 1277 4.6. Data Qualities 1279 * SDF: Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf] 1281 * YANG: 1283 - Section 7.4.1 (type) of [RFC7950] 1285 The set of qualities labelled as data qualities contains qualities 1286 that SDF borrowed from json-schema.org as well as qualities 1287 specifically defined for SDF. In the first group there is a total of 1288 18 qualities out of which some are interdependent. 1290 The quality that a lot of the other qualities presence or absence 1291 depends on is the "type" quality. The type can be one of "number", 1292 "string", "boolean", "integer", "array" or "object". This quality is 1293 directly converted to the YANG "type" statement for all simple types 1294 (where "number" becomes "decimal64" and integer becomes "int64"). 1295 The types "array" and "object" cannot be converted to a YANG built-in 1296 type directly. Instead SDF definitions with these types are 1297 converted as described in sections Section 4.8 and Section 4.7. 1299 The SDF data quality "const" hold the constant value of a definition 1300 if there is one. If the value of the "type" quality is "number" or 1301 "integer" the "const" quality is mapped to the "range" sub-statement 1302 of YANG's "type" statement which can also contain a single value. 1303 For constant string values the YANG "pattern" statement containing 1304 the constant string is be used. Unfortunately, constant values of 1305 types boolean, array and object have to be ignored since there is no 1306 way to represent them in YANG. 1308 The "default" data quality in SDF holds the default value for its 1309 definition. Since YANG leaf and leaf-list nodes have a "default" 1310 sub-statement SDF default values of simple types or of type array 1311 with items of simple types can easily be represented. Default values 1312 of either compound-type or type array with compound-type items cannot 1313 be represented in YANG, unfortunately. 1315 The data qualities "minimum", "maximum", "exclusiveMinimum" and 1316 "exclusiveMaximum" which are only valid for the types number and 1317 integer are converted using the YANG "range" statement again. For 1318 exclusive boundaries the range is reduced accordingly in YANG. If 1319 the range already contains a constant value an alternative range can 1320 be added. The alternatives in the range have to be disjoint, 1321 however. If the constant value lies inside the range specified by 1322 the "minimum" and "maximum" qualities this cannot be represented 1323 simultaneously in YANG. Whichever of the two qualities is converted 1324 first is represented. 1326 The "multipleOf" data quality is one that can only be used in 1327 conjunction with the number type in SDF and states the resolution, 1328 i.e., the number of possible digits after the decimal separator, of 1329 the decimal number. This quality is converted to the "fraction- 1330 digits" sub-statement to the "type" statement in YANG. 1332 SDF's "minLength" and "maxLength" data qualities are used to hold a 1333 strings minimal and maximal length. This concept can be transferred 1334 to YANG by using the "length" sub-statement of the "type" statement 1335 that specifies a length range. 1337 The SDF "pattern" data quality holds regular expressions for string 1338 typed definitions. This can be converted directly to the "pattern" 1339 sub-statement to the "type" statement in YANG. As already mentioned 1340 in Section 3.16 regular expressions cannot be converted directly 1341 between SDF and YANG in theory due to the differing languages used 1342 for regular expressions. Due to the time limitations of this thesis, 1343 however, no further measures are taken to insure the conformance of 1344 converted regular expressions. 1346 The string type in SDF can be concertized by the "format" quality. 1347 This quality can specify one of the JSON schema formats. This could 1348 be translated to YANG referencing typedefs from the widely used 1349 "ietf-yang-types" module. However, to not rely on external modules 1350 the format is only mentioned in the description of the YANG 1351 equivalent to the "format" quality's SDF definition. 1353 The length of an array in SDF can be restricted by the "minLength" 1354 and "maxLength" data qualities. Both list and leaf-list nodes use 1355 the sub-statements "min-elements" and "max-elements" to express the 1356 same concept which are used to convert the SDF array length 1357 qualities. 1359 Another restriction for SDF arrays is the "uniqueItems" quality that 1360 can be set to either "true" or "false". If it is set to "true" all 1361 items of an array have to be unique. YANG specifies a "unique" sub- 1362 statement for list nodes but it can only be applied to leaf and leaf- 1363 list nodes in the sub-tree. Thus, if the SDF array in question is 1364 converted to a YANG list node and the "uniqueItems" quality is set to 1365 true, the list's "unique" statement mentions all of the list's 1366 descendant leaf or leaf-list nodes. It is not possible, 1367 unfortunately, to represent the "uniqueItems" quality in leaf-list 1368 nodes that stem from SDF arrays. 1370 The "items" data quality of SDF is a quality that specifies item 1371 constraints for the items of an array-typed SDF definition using a 1372 subset of the common and data qualities. SDF definitions with the 1373 type array are converted to list or leaf-list nodes. These node 1374 types in themselves indicate the type array. Thus, the qualities 1375 defined in the array's item constraints are converted to the list and 1376 leaf-list node's sub-statements as described in this section. 1378 The SDF data qualities include the "properties" quality. These 1379 properties are different from sdfProperties. The "properties" 1380 quality is used in conjunction with the object type and contains a 1381 set of named definitions made up of data qualities themselves. SDF 1382 definitions of type object are converted to container or grouping 1383 nodes thus the single named properties in the "properties" quality 1384 are transformed to the node's child nodes. The SDF type "object" was 1385 only introduced in SDF 1.1. This feature made conversion 1386 significantly more complicated. To label the properties as mandatory 1387 the "required" quality is used. Since it is resembling the 1388 "sdfRequired" quality it is translated in the same way. 1390 The second group of qualities that is part of the data qualities 1391 includes 11 qualities as well as the common qualities described in 1392 Section 4.5. 1394 The "unit" quality can be set to any of the SenML unit names to 1395 represent an SDF definitions unit. There is also a "unit" statement 1396 as a sub-statement to typedefs, leaf nodes and leaf-list nodes. The 1397 "unit" statement in YANG can contain any string and thus is simply 1398 set to the SenML unit name from the SDF definition. 1400 An important data quality is the "sdfChoice" quality. It represents 1401 the choice between several sets of named definitions made up of data 1402 qualities themselves. YANG provides a very similar statement, the 1403 "choice" statement. An sdfChoice is turned into a YANG choice node. 1404 Each of the sdfChoice's alternatives is converted like an sdfProperty 1405 (see Section 4.8) and added to the choice node inside its own case 1406 node. SdfChoice definitions that give the choice between the "type" 1407 quality could also be mapped to the YANG type union. This is omitted 1408 for reasons of simplicity. 1410 SDF also offers the possibility to define the choice between string 1411 values by means of the "enum" data quality. It consists of an array 1412 of strings. This concept also exists in YANG with the "enumeration" 1413 type and "enum" sub-statement to the "type" statement. For an SDF 1414 definition that contains the "enum" quality the YANG type of its 1415 equivalent is set to "enumeration". Each of the strings in the array 1416 of the "enum" SDF quality is converted to an "enum" entry in the 1417 "type" statement in YANG. 1419 SDF's "contentFormat" quality can provide an additional IANA content 1420 type. This is turned into a note in the description of the SDF 1421 definition's YANG equivalent. 1423 Another way to specify the "type" quality is the "sdfType" quality 1424 that can either be set to "byte-string" or "unix-time". A byte 1425 string is converted to the YANG type "binary". There is no built-in 1426 YANG type corresponding to unix time thus a note is added in the 1427 description of the SDF definition's YANG equivalent. 1429 SDF defines the "readable" and "writable" qualities to flag whether 1430 read or write operations are allowed on definitions. Read operations 1431 are always allowed in YANG modules so a "readable" quality that is 1432 set to false cannot be represented in YANG. YANG's "config" 1433 statement can be used to represent the value of the "writable" 1434 quality, however. If an SDF definition is explicitly marked as 1435 writable "config" is set to "true". Otherwise, it is set to "false". 1437 The "observable" and "nullable" qualities in SDF cannot be 1438 represented in YANG. 1440 4.7. sdfData 1441 * SDF: Sections 2.2.5 and 5.5 (sdfData) of [I-D.ietf-asdf-sdf] 1443 * YANG: 1445 - Section 7.13 (uses) of [RFC7950] 1447 - Section 7.12 (grouping) of [RFC7950] 1449 Elements of the sdfData class are meant to hold data type definitions 1450 to be shared by sdfProperty, sdfAction and sdfEvent definitions. 1451 SdfData definitions can make use of the data qualities and the common 1452 qualities described in sections Section 4.6 and Section 4.5 1453 respectively. Because an sdfData element embodies a data type 1454 definition, the YANG statements "typedef" and "grouping" have to be 1455 used for conversion. Which of the two is used depends on the value 1456 of the "type" quality of the sdfData element. If the type is one of 1457 the simple data types, i.e., integer, number, boolean or string, the 1458 sdfData definition is converted to a YANG typedef. If the type is 1459 compound-type the sdfData definition is mapped to a grouping node 1460 with each of the compound-type's properties being mapped to a child 1461 node of the grouping. For sdfData definitions with type array the 1462 type mentioned in the "type" quality of the "items" quality is 1463 essential as well. If an array has items of any of the simple types 1464 the resulting YANG element is a grouping node containing a single 1465 leaf-list node. Otherwise, if the array items are compound-types the 1466 sdfData definition is converted into a grouping node containing a 1467 single list node. The list node's child nodes are equivalent to the 1468 compound-type item's properties. One issue with converting sdfData 1469 definitions of type array is the added grouping node that is 1470 necessary to hold the leaf-list/list node. If the grouping is used 1471 in the schema tree the added level will cause model instances of the 1472 original and converted model to be in-equivalent. If the sdfData 1473 definition is referenced in the SDF model via the "sdfRef" common 1474 quality this is represented in YANG with the "uses" statement 1475 pointing to the grouping equivalent to the sdfData definition. 1477 The "sdfRef" quality can occur at most once in each definition while 1478 there can be multiple "uses" statements in the same container/list/ 1479 grouping. Thus, the aforementioned issue with array-typed sdfData 1480 definitions could be solved by, instead of representing definitions 1481 containing an sdfRef by a parent node containing a "uses" node, 1482 replacing the parent node with the "uses" node itself, effectively 1483 removing the excess level. This, however, gives rise to other issues 1484 because the name of the sdfRef's superordinate definition is lost. 1485 If the sdfData definition is converted to a typedef no such issues 1486 arise. The typedef in question is inserted as an argument to the 1487 YANG type quality wherever the original sdfData definition was 1488 referenced by an sdfRef. Another issue is a different view on global 1489 accessibility of data type definitions in YANG and SDF. In SDF all 1490 definitions are globally available as long as a default namespace is 1491 defined in the SDF model. In YANG on the other hand, only data type 1492 definitions (i.e., groupings and typedefs) that occur on the top- 1493 level of YANG module are globally accessible. Thus, to represent the 1494 global accessibility of all data type definitions in SDF, all 1495 converted sdfData definition equivalents in YANG are added to the 1496 top-level of the created module. 1498 4.8. sdfProperty 1500 * SDF: Sections 2.2.2 and 5.2 (sdfProperty) of [I-D.ietf-asdf-sdf] 1502 * YANG: 1504 - Section 7.6 (leaf) of [RFC7950] 1506 - Section 7.7 (leaf-list) of [RFC7950] 1508 - Section 7.8 (list) of [RFC7950] 1510 SdfProperty definitions represent elements of state as suggested by 1511 their name. SdfProperty definitions can make use of the data 1512 qualities and the common qualities described in sections Section 4.6 1513 and Section 4.5 respectively. The mapping of an sdfProperty 1514 definition to YANG depends on the value of the "type" quality. 1515 SdfProperties with simple types are mapped to leaf nodes in YANG. If 1516 the type is complex, i.e., compound-type, conversion results in a 1517 container node with each of the compound-type's properties being 1518 mapped to a child node of the container. If the sdfProperty is of 1519 type array the deciding factor is the "type" quality inside the 1520 "items" quality. If an array has items of a simple type it is 1521 converted to a leaf-list node. Otherwise, if the items are of 1522 compound-type the sdfProperty becomes a list node in YANG. The list 1523 node's child nodes are equivalent to the compound-type's properties. 1525 4.9. sdfAction 1527 * SDF: Sections 2.2.3 and 5.3 (sdfAction) of [I-D.ietf-asdf-sdf] 1529 * YANG: 1531 - Section 7.14 (rpc) of [RFC7950] 1533 - Section 7.15 (action) of [RFC7950] 1535 To represent commands/operations that can be invoked in a model the 1536 sdfAction class is used. Since commands can have input and output 1537 data the sdfAction class is equipped with the "sdfInputData" and 1538 "sdfOutputData" qualities that can both make use of the data 1539 qualities and the common qualities described in sections Section 4.6 1540 and Section 4.5 respectively. An sdfAction can also define its own 1541 set of data types in the form of sdfData definitions. Whether an 1542 sdfAction is converted to an RPC (which can only occur at the top- 1543 level of a module) or an action node (which is always tied to a 1544 container node) depends on its location inside the SDF model. 1545 SdfActions that are not part of an sdfObject but can be found 1546 independently at the top of an SDF model are converted to RPC nodes. 1547 All other actions occurring inside an sdfObject become action nodes 1548 inside the sdfObject's container equivalent in YANG. The 1549 sdfInputData and sdfOutputData of an sdfAction are converted like 1550 sdfProperties (see Section 4.8) and added as the input and output 1551 node of the RPC/action respectively. 1553 4.10. sdfEvent 1555 * SDF: Sections 2.2.4 and 5.4 (sdfEvent) of [I-D.ietf-asdf-sdf] 1557 * YANG: Section 7.16 (notification) of [RFC7950] 1559 The sdfEvent class' purpose is to model signals that inform about 1560 occurrences or "happenings" in an sdfObject. To represent the 1561 emitted output data sdfEvents can make use of the "sdfOutputData" 1562 quality which in turn uses the data qualities. An sdfEvent is 1563 converted to a notification node with one child node representing the 1564 sdfOutputData definition. The 1566 5. Challenges 1568 Since conversion between SDF and YANG is not always trivial this 1569 section takes a look at the various challenges that arose in the 1570 process of finding an adequate mapping for each of the language's 1571 features to one another. 1573 5.1. Differences in Expressiveness of SDF and YANG 1575 SDF and YANG differ in their expressiveness in different areas. 1576 Compared to the other format, both are stronger in some areas and 1577 weaker in others. Areas in which YANG is more expressive are type 1578 references, regular expressions, operations and some of the built-in 1579 types (specifically "bits", "empty" and "union"). SDF offers more 1580 possibilities to define default and constant values, the latter 1581 especially in conjunction with minimum and maximum values for which a 1582 single statement is used in YANG. Labelling definitions as readable, 1583 observable and nullable, as possible in SDF, is foreign to YANG. 1585 5.2. Round Trips 1587 One of the bigger issues in developing a mapping for each language 1588 feature of SDF and YANG was the facilitation of round trips, i.e., 1589 converting a model from one format to the other and in a next step 1590 back to the original. This issue is tightly linked to the 1591 differences in expressiveness between the two formats which makes 1592 mapping between them non-injective and thus non-traceable. 1594 To be able to track the origins of an SDF element after conversion 1595 from YANG, currently, a "conversion note" is added to the description 1596 of said element. The note states a statement and an argument. An 1597 example for a note hinting the original argument to the "type" 1598 statement was "union" could be: "!Conversion note: type union!". 1599 This issue was also discussed in one of the ASDF working group's 1600 Interim Meetings where the possibility to introduce a new round trip 1601 mechanism native to SDF was suggested. 1603 To preserve the original SDF language element after conversion to 1604 YANG a new extension is defined in YANG. The extension states the 1605 original SDF quality. 1607 The eventuality that round trips occur in model conversion makes 1608 implementing a converter significantly more complex because all 1609 features of the target format have to be accounted for. Features of 1610 the target format that would otherwise not be used for conversion 1611 must now be considered in the case of a round trip. 1613 5.3. Type References 1615 Both SDF and YANG offer the possibility to reference predefined 1616 types. SDF uses only a single quality for this purpose ("sdfRef") 1617 whereas YANG has several statements that are all used in different 1618 referencing contexts ("leafref", "identityref", "type", "uses"). 1620 The "sdfRef" quality is supposed to hold references to other 1621 definitions. The qualities of the referenced definition are copied 1622 into the referencing definition if they are not overwritten in the 1623 referencing definition. The conversion of an sdfRef depends on what 1624 is referenced by it and what that is converted to. If the referenced 1625 definition is converted to a typedef the sdfRef is analogous to the 1626 "type" statement in YANG which points to the typedef. If the 1627 referenced definition is mapped to a leaf or leaf-list node it can be 1628 referenced by the "leafref" built-in type in YANG. If the referenced 1629 definition's equivalent in YANG is a grouping node the sdfRef gets 1630 converted to a "uses" node which points to said grouping. In all 1631 other cases the referenced definition's equivalent cannot be 1632 referenced directly but has first to be packaged in a grouping node. 1633 This is done by first creating a grouping as a sibling node to the 1634 referenced definition's equivalent YANG node and copying the 1635 equivalent node into the new grouping. After that the equivalent 1636 node is replaced it with a "uses" node referencing the grouping. 1637 This is done to avoid redundancy. Lastly, the actual sdfRef is 1638 represented by another "uses" node referencing the newly created 1639 grouping. 1641 6. Implementation Considerations 1643 An implementation of an initial converter between SDF and YANG can be 1644 found at [SDF-YANG-CONVERTER]; the source code can be found at 1645 [SDF-YANG-CONVERTER-IMPL]. 1647 7. IANA Considerations 1649 This document makes no requests of IANA. 1651 8. Security considerations 1653 The security considerations of [RFC7950] and [I-D.ietf-asdf-sdf] 1654 apply. 1656 9. References 1658 9.1. Normative References 1660 [I-D.ietf-asdf-sdf] 1661 Koster, M. and C. Bormann, "Semantic Definition Format 1662 (SDF) for Data and Interactions of Things", Work in 1663 Progress, Internet-Draft, draft-ietf-asdf-sdf-06, 1 June 1664 2021, . 1667 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1668 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1669 . 1671 9.2. Informative References 1673 [LIBYANG] Vasko, M., Sedlák, D., and more contributors, "libyang", 1674 . 1676 [SDF-YANG-CONVERTER] 1677 Kiesewalter, J., "SDF YANG converter playground", n.d., 1678 . 1680 [SDF-YANG-CONVERTER-IMPL] 1681 Kiesewalter, J., "SDF YANG converter", n.d., 1682 . 1684 Acknowledgements 1686 TBD. 1688 Authors' Addresses 1690 Jana Kiesewalter 1691 Universität Bremen 1693 Email: jankie@uni-bremen.de 1695 Carsten Bormann (editor) 1696 Universität Bremen TZI 1697 Postfach 330440 1698 D-28359 Bremen 1699 Germany 1701 Phone: +49-421-218-63921 1702 Email: cabo@tzi.org