idnits 2.17.00 (12 Aug 2021)
/tmp/idnits25948/draft-kiesewalter-asdf-yang-sdf-01.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 :
----------------------------------------------------------------------------
** There are 29 instances of too long lines in the document, the longest
one being 220 characters in excess of 72.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (7 November 2021) is 188 days in the past. Is this
intentional?
Checking references for intended status: Informational
----------------------------------------------------------------------------
== Outdated reference: A later version (-11) exists of
draft-ietf-asdf-sdf-08
Summary: 1 error (**), 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: 11 May 2022 Universität Bremen TZI
6 7 November 2021
8 Mapping between YANG and SDF
9 draft-kiesewalter-asdf-yang-sdf-01
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 11 May 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 . . . . . . . . . . . . . . . . . . . . . . . . 13
61 3.3. Container Statement . . . . . . . . . . . . . . . . . . . 13
62 3.4. Leaf Statement . . . . . . . . . . . . . . . . . . . . . 15
63 3.5. Leaf-List Statement . . . . . . . . . . . . . . . . . . . 17
64 3.6. List Statement . . . . . . . . . . . . . . . . . . . . . 18
65 3.7. Grouping Statement . . . . . . . . . . . . . . . . . . . 19
66 3.8. Uses Statement . . . . . . . . . . . . . . . . . . . . . 20
67 3.9. Choice Statement . . . . . . . . . . . . . . . . . . . . 21
68 3.10. RPC Statement . . . . . . . . . . . . . . . . . . . . . . 24
69 3.11. Action Statement . . . . . . . . . . . . . . . . . . . . 24
70 3.12. Notification Statement . . . . . . . . . . . . . . . . . 26
71 3.13. Augment Statement . . . . . . . . . . . . . . . . . . . . 27
72 3.14. Anydata and Anyxml Statements . . . . . . . . . . . . . . 28
73 3.15. Type Statement . . . . . . . . . . . . . . . . . . . . . 28
74 3.16. String Built-In Type . . . . . . . . . . . . . . . . . . 29
75 3.17. Decimal64 Built-In Type . . . . . . . . . . . . . . . . . 31
76 3.18. Integer Built-In Types . . . . . . . . . . . . . . . . . 33
77 3.19. Boolean Built-In Type . . . . . . . . . . . . . . . . . . 34
78 3.20. Binary Built-In Type . . . . . . . . . . . . . . . . . . 34
79 3.21. Enumeration Built-In Type . . . . . . . . . . . . . . . . 35
80 3.22. Bits Built-In Type . . . . . . . . . . . . . . . . . . . 35
81 3.23. Union Built-In Type . . . . . . . . . . . . . . . . . . . 36
82 3.24. Leafref and Identityref Built-In Types . . . . . . . . . 37
83 3.25. Empty Built-In Type . . . . . . . . . . . . . . . . . . . 37
84 3.26. Instance-Identifier Built-In Type . . . . . . . . . . . . 37
85 3.27. Typedef Statement . . . . . . . . . . . . . . . . . . . . 38
86 3.28. Identity Statement . . . . . . . . . . . . . . . . . . . 38
87 3.29. Config Statement . . . . . . . . . . . . . . . . . . . . 38
88 3.30. Status Statement . . . . . . . . . . . . . . . . . . . . 39
89 3.31. Reference Statement . . . . . . . . . . . . . . . . . . . 39
90 3.32. When and Must Statements . . . . . . . . . . . . . . . . 39
91 3.33. Extension Statement . . . . . . . . . . . . . . . . . . . 40
92 4. Mapping from SDF to YANG . . . . . . . . . . . . . . . . . . 40
93 4.1. Information Block . . . . . . . . . . . . . . . . . . . . 40
94 4.2. Namespace Section . . . . . . . . . . . . . . . . . . . . 41
95 4.3. SdfThing Quality . . . . . . . . . . . . . . . . . . . . 41
96 4.4. SdfObject Quality . . . . . . . . . . . . . . . . . . . . 41
97 4.5. Common Qualities . . . . . . . . . . . . . . . . . . . . 42
98 4.6. Data Qualities . . . . . . . . . . . . . . . . . . . . . 50
99 4.7. SdfData Quality . . . . . . . . . . . . . . . . . . . . . 57
100 4.8. SdfProperty Quality . . . . . . . . . . . . . . . . . . . 59
101 4.9. SdfAction Quality . . . . . . . . . . . . . . . . . . . . 62
102 4.10. SdfEvent Quality . . . . . . . . . . . . . . . . . . . . 63
103 5. Challenges . . . . . . . . . . . . . . . . . . . . . . . . . 64
104 5.1. Differences in Expressiveness of SDF and YANG . . . . . . 64
105 5.2. Round Trips . . . . . . . . . . . . . . . . . . . . . . . 66
106 5.3. Type References . . . . . . . . . . . . . . . . . . . . . 67
107 6. Implementation Considerations . . . . . . . . . . . . . . . . 70
108 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 70
109 8. Security considerations . . . . . . . . . . . . . . . . . . . 70
110 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 70
111 9.1. Normative References . . . . . . . . . . . . . . . . . . 70
112 9.2. Informative References . . . . . . . . . . . . . . . . . 70
113 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 71
114 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 71
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 to |
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. Examples
486 have been included where they serve to assist the reader's
487 understanding of the conversion.
489 3.1. Module
491 * YANG: Section 7.1 (module) of [RFC7950]
493 * SDF:
495 - Section 3.1 (information block) of [I-D.ietf-asdf-sdf]
497 - Sections 3.2 and 4 (namespaces section) of [I-D.ietf-asdf-sdf]
499 The module statement in YANG subsumes all other statements included
500 in a module. After conversion the SDF model as a whole corresponds
501 to the YANG module. The argument of the namespace statement of the
502 YANG module is added to the SDF namespace quality together with the
503 argument of the prefix statement of the YANG module which also
504 becomes the entry of the defaultNamespace quality in the SDF model.
505 Additionally, the namespaces and prefixes of each of the modules
506 mentioned in the import statements are added to the namespace quality
507 of the SDF model. Libyang loads the imported modules automatically
508 and in the correct version. These modules are then also converted
509 and stored so their definitions can be referenced via the sdfRef
510 common quality when necessary. Figure 2 and Figure 1 illustrate
511 these mappings.
513 The contents of the organization, contact and yang-version statements
514 are stored alongside the description of the YANG module in a special
515 sdfData definition designated to hold information on the module that
516 does not fit into the SDF information block. This is done in with a
517 conversion note to facilitate round trips in the future as described
518 in Section 5.2. To illustrate this conversion, Figure 2 contains a
519 converted model with an sdfData definition called ietf-foo-info. The
520 original YANG module can be found in Figure 1. The description of
521 the module is scanned for information regarding copyright and
522 licensing which are then transferred to the copyright and license
523 qualities of the information block in the SDF model. The version
524 quality of the information block is set to the first revision date
525 given in the YANG revision statement. All other revision dates are
526 ignored as of now.
528 YANG modules can define features via the feature statement to make
529 parts of the module conditional. The abilities of a server are
530 checked against the features stated in the module. Nodes reference
531 features as an argument to the if-feature statement. If a server
532 does not support a certain feature, nodes that reference that feature
533 are ignored by the server. Since this functionality cannot be
534 represented in SDF yet, YANG features are stored in the description
535 of the sdfData definition designated to hold information on the
536 module. The conversion note that is added to the descriptions looks
537 as described in Section 5.2.
539 If the deviation statement (introducing a deviation from the original
540 YANG module) is present in the YANG module, Libyang applies the
541 deviation directly and the converter converts the module that way.
542 The presence of the deviation in the original YANG module is not
543 indicated in the resulting SDF model as of now which might cause
544 inconsistencies after round trips. This is not believed to be of
545 great importance because deviations are supposed to only occur in
546 unpublished modules.
548 module ietf-foo {
549 namespace "urn:ietf:params:xml:ns:yang:ietf-foo";
550 prefix "foo";
551 organization "Foo Inc.";
552 contact "foo@mail.com";
553 description
554 "This is an example module
556 Copyright Foo Inc.
558 License XY";
559 revision 2016-03-20;
560 feature bar;
561 feature baz;
563 // ... more statements
564 }
566 Figure 1: Example YANG module
568 {
569 "defaultNamespace": "foo",
570 "info": {
571 "copyright": "Copyright Foo Inc.",
572 "license": "License XY",
573 "title": "ietf-foo",
574 "version": "2016-03-20"
575 },
576 "namespace": { "foo": "urn:ietf:params:xml:ns:yang:ietf-foo" },
577 "sdfData": {
578 "ietf-foo-info": {
579 "description": "This is an example module\n\nCopyright Foo Inc.\n\nLicense XY\n!Conversion note: revision 2016-03-20!\n\n!Conversion note: organization Foo Inc.!\n\n!Conversion note: contact foo@mail.com!\n!Conversion note: feature bar!\n\n!Conversion note: feature baz!\n"
580 }
581 }
582 }
584 Figure 2: SDF conversion of YANG module from the last figure
586 3.2. Submodule
588 * YANG: Section 7.2 (submodule) of [RFC7950]
590 If a complex YANG module is composed of several components, the
591 single components can be represented via the submodule statement.
592 For conversion, the nodes of a submodule that is included into its
593 super-module with the include statement are integrated into the
594 super-module and converted that way. This is due to the way Libyang
595 represents included submodules. Submodules on their own cannot be
596 converted since Libyang does not parse files that solely contain a
597 submodule.
599 3.3. Container Statement
601 * YANG: Section 7.5 (container) of [RFC7950]
603 * SDF:
605 - Sections 2.2.1 and 5.1 (sdfObject) of [I-D.ietf-asdf-sdf]
607 - Sections 2.2.6 and 6.3 (sdfThing) of [I-D.ietf-asdf-sdf]
609 YANG uses container nodes to group together other nodes. Containers
610 on the top-level of a module are converted to sdfObject definitions.
611 This is illustrated in the definition called level0 in Figure 3 and
612 Figure 4. A container that is a direct child node to a top-level
613 container is converted to a compound-type sdfProperty definition
614 inside an sdfObject, as illustrated in the definition called level1
615 in Figure 3 and Figure 4. Any other container becomes an entry to
616 the properties quality of the compound-type definition corresponding
617 to the parent node of the container. An example of this mapping can
618 be found in Figure 3 and Figure 4 in the definition called level2.
620 Since the first SDF Internet-Draft did not contain the compound-type
621 as a possible argument to the type quality, containers used to be
622 translated to sdfThing definitions. This, was not a very suitable
623 conversion semantically, however. At that time, sdfThings were the
624 only elements that could contain elements of the same class, that is
625 sdfThings could contain other sdfThings. This ability is required to
626 represent the tree structure of YANG where, for example, containers
627 can contain other containers. In the second SDF Internet-Draft the
628 compound-type was introduced. This feature effectively makes it
629 possible for elements of the sdfData and sdfProperty classes to
630 contain elements that share the same qualities.
632 A sub-statement to the container statement that cannot be represented
633 in SDF as of now is the optional presence statement. The argument of
634 the presence statement assigns a meaning to the presence or absence
635 of a container node in an instance of the module. This concept is
636 expressed in the description of the SDF definition in question as
637 shown in Section 5.2. This is also illustrated in the definition
638 level2 in Figure 3 and Figure 4.
640 module container-example {
641 // [...]
642 container level0 {
643 container level1 {
644 container level2 {
645 presence "Enables SSH";
646 // [...]
647 }
648 }
649 }
650 }
652 Figure 3: YANG module with multiple nested container statements
653 {
654 ; [...]
655 "sdfObject": {
656 "level0": {
657 "sdfProperty": {
658 "level1": {
659 "properties": {
660 "level2": {
661 "properties": {
662 "description": "!Conversion note: presence Enables SSH!\n",
663 ; [...]
664 },
665 "type": "object"
666 }
667 },
668 "type": "object"
669 }
670 }
671 }
672 }
673 }
675 Figure 4: SDF conversion of the YANG module from the last figure
677 3.4. Leaf Statement
679 * YANG: Section 7.6 (leaf) of [RFC7950]
681 * SDF:
683 - Sections 2.2.2 and 5.2 (sdfProperty) of [I-D.ietf-asdf-sdf]
685 - Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf]
687 Leaf nodes in YANG represent scalar variables. If a leaf statement
688 occurs at the top-level of the module or as a direct child node of a
689 top-level container (which is converted to sdfObject) it becomes an
690 sdfProperty. On any other level a leaf is mapped to an entry of the
691 properties quality of the compound-type definition corresponding to
692 the parent node of the leaf. In both cases the SDF type quality is
693 set to one of the simple data types because leaf nodes can only have
694 simple data types. Leaf nodes can be assigned default values which
695 are used in case the node does not exist in an instance of the YANG
696 module. The default value of a leaf is converted to SDF through the
697 quality default. The units sub-statement of a leaf node in YANG
698 becomes the SDF quality unit. An example of such a conversion can be
699 found in the level0 element in Figure 5 and Figure 6. The SDF
700 quality unit is constrained to the SenML unit names. Although it
701 could cause conformance issues, the content of the YANG units
702 statement is not processed to fit the SenML unit names as of now.
703 This is due to the low probability that a unit from a YANG module is
704 not listed in the SenML unit names in comparison to the time required
705 to implement a mechanism to check conformance and convert non-
706 conforming units. This feature might be added in later versions of
707 the converter. YANG leaf nodes can be marked as mandatory to occur
708 in an instance of the module by the mandatory statement. The
709 statement takes true and false as arguments. This can easily be
710 mapped to SDF through the sdfRequired quality. A reference to the
711 SDF equivalent of the mandatory YANG leaf node is added to the
712 sdfRequired quality of the containing sdfObject. If a mandatory leaf
713 is transformed to an entry in the properties quality of a compound-
714 type definition in SDF, said entry is mentioned in the required
715 quality. If the sdfRequired or required quality does not already
716 exist it is added at this point. The latter is demonstrated in the
717 level2 element in Figure 5 and Figure 6.
719 module leaf-example {
720 // [...]
721 leaf level0 {
722 type int32;
723 units "kg";
724 default 14;
725 }
726 container dummy0 {
727 leaf level1 { type string; }
728 container dummy1 {
729 leaf level2 {
730 type string;
731 mandatory true;
732 }
733 }
734 }
735 }
737 Figure 5: YANG module containing multiple leaf statements
739 {
740 ; [...]
741 "sdfObject": {
742 "dummy0": {
743 "sdfProperty": {
744 "dummy1": {
745 "properties": {
746 "level2": { "type": "string" }
747 },
748 "required": [ "level2" ],
749 "type": "object"
750 },
751 "level1": { "type": "string" }
752 }
753 }
754 },
755 "sdfProperty": {
756 "level0": {
757 "default": 14,
758 ; [...]
759 "type": "integer",
760 "unit": "kg"
761 }
762 }
763 }
765 Figure 6: SDF conversion of the YANG module from the last figure
767 3.5. Leaf-List Statement
769 * YANG: Section 7.7 (leaf-list) of [RFC7950]
771 * SDF:
773 - Sections 2.2.2 and 5.2 (sdfProperty) of [I-D.ietf-asdf-sdf]
775 - Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf]
777 Similarly to leaf nodes, leaf-list nodes hold data of simple types in
778 YANG but as items in an array. As such, leaf-lists are converted to
779 sdfProperties if they occur on the top-level or one level below in a
780 module. On any other level a leaf-list becomes an entry to the
781 properties quality of the compound-type definition corresponding to
782 the parent node of the leaf-list. In both cases the type is set to
783 array. The items of the array are of simple data types since leaf-
784 list nodes can only have simple data types as well. The minimal and
785 maximal number of elements in a YANG leaf-list can be specified by
786 the min-elements and max-elements sub-statements. This is analogue
787 to the minItems and maxItems qualities of SDF which are set
788 accordingly by the converter. A leaf-list can specify whether the
789 system or the user is responsible for ordering the entries of the
790 leaf-list. This information is stored in the ordered-by statement in
791 YANG which is represented in SDF by a remark in the description (as
792 shown in Section 5.2) of the SDF equivalent to the leaf-list node in
793 question. Since leaf-list nodes are just leaf nodes that can occur
794 multiple times, the units and default statements of leaf-list nodes
795 are converted as described for leaf nodes in Section 3.4.
797 3.6. List Statement
799 * YANG: Section 7.8 (list) of [RFC7950]
801 * SDF:
803 - Sections 2.2.2 and 5.2 (sdfProperty) of [I-D.ietf-asdf-sdf]
805 - Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf]
807 The list statement of YANG is similar to the leaf-list statement.
808 The only difference is that, opposed to leaf-lists, lists represent
809 an assortment of _nodes_ that can occur multiple times. Therefore,
810 YANG lists are mapped to SDF similarly to leaf-lists. List nodes on
811 the top-level or one level below become sdfProperties. On any other
812 level a list is converted to an entry to the properties quality of
813 the compound-type definition corresponding to the parent node of the
814 list. The type is set to array for both alternatives. Since lists
815 contain a set of nodes, the items of the corresponding array are of
816 type object. The minimal and maximal number of elements in a list
817 can be specified by the min-elements and max-elements sub-statements.
818 This is analogue to the minItems and maxItems qualities of SDF which
819 are set accordingly by the converter. List nodes in YANG can define
820 one or multiple keys leafs of the list via the key statement. There
821 is no SDF quality that could represent this feature. To preserve the
822 information the names of the list keys are stored in the description
823 of the SDF definition in question as described in section
824 Section 5.2. The unique sub-statement of the YANG list defines a
825 number of descendant leaf nodes of the list that must have a unique
826 combination of values in a module instance. This concept can be
827 partly represented through the uniqueItems quality of SDF. However,
828 the boolean-typed uniqueItems quality only specifies that the items
829 of an SDF array have to be unique with _all_ of their values
830 combined. The YANG statement unique specifies a _selection_ of leaf
831 node values in the list that must be unique when combined. Thus, in
832 addition to setting the uniqueItems quality of the SDF equivalent of
833 the YANG list to true, a conversion note is added to the SDF
834 equivalents of all leafs that are mentioned in the unique statement.
836 This is done as shown in Section Section 5.2. The ordered-by
837 statement of a list is also preserved in a conversion note. An
838 example conversion of a list node with the mentioned sub-statements
839 to SDF can be found in Figure 7 and Figure 8.
841 list server {
842 key "name";
843 unique "ip";
844 ordered-by user;
845 min-elements 1;
846 max-elements 100;
847 leaf name { type string; }
848 leaf ip { type string; }
849 }
851 Figure 7: YANG list node
853 "sdfProperty": {
854 "server": {
855 "description": "!Conversion note: key name!\n!Conversion note: ordered-by user!\n",
856 "items": {
857 "properties": {
858 "ip": {
859 "description": "!Conversion note: unique!\n",
860 "type": "string"
861 },
862 "name": { "type": "string" }
863 },
864 "type": "object"
865 },
866 "maxItems": 100.0,
867 "minItems": 1.0,
868 "type": "array",
869 "uniqueItems": true
870 }
871 }
873 Figure 8: SDF conversion of the YANG list node from the last figure
875 3.7. Grouping Statement
877 * YANG: Section 7.12 (grouping) of [RFC7950]
879 * SDF: Section 5.5 (sdfData) of [I-D.ietf-asdf-sdf]
881 Grouping nodes are very similar to container nodes with the
882 difference that the set of nodes contained in a grouping does not
883 occur in the data tree unless the grouping has been referenced at
884 least once by a uses node. Thus, a grouping node is converted to a
885 compound-type sdfData definition which defines a reusable definition
886 that is not a declaration as well. The nodes inside the grouping are
887 converted as entries to the properties quality in SDF. Figure 9 and
888 Figure 10 contain an example conversion of a grouping.
890 3.8. Uses Statement
892 * YANG: Section 7.13 (uses) of [RFC7950]
894 * SDF: Section 4.4 (sdfRef) of [I-D.ietf-asdf-sdf]
896 A uses node has the purpose of referencing a grouping node. The set
897 of child nodes of the referenced grouping are copied to wherever the
898 uses node is featured. Some of the sub-statements of the referenced
899 grouping can be altered via the refine statement of the uses node.
900 In SDF a uses node is represented by the sdfRef quality which is
901 added to the definition in question. As an argument the sdfRef
902 contains a reference to the sdfData definition corresponding to the
903 grouping referenced by the uses node. If the uses node contains a
904 refine statement, the specified refinements are also applied in the
905 target SDF definition. An example for such a conversion is
906 illustrated in Figure 9 and Figure 10.
908 module restaurant {
909 // [...]
910 grouping dish {
911 leaf name { type string; }
912 leaf price { type int32; }
913 }
914 list menu {
915 // [...]
916 uses dish {
917 refine name { mandatory true; }
918 }
919 }
920 }
922 Figure 9: YANG module with uses and grouping statements
924 {
925 ; [...]
926 "sdfData": {
927 "dish": {
928 "properties": {
929 "name": { "type": "string" },
930 "price": {
931 ; [...]
932 "type": "integer"
933 }
934 },
935 "type": "object"
936 }
937 },
938 "sdfProperty": {
939 "menu": {
940 "items": {
941 "properties": {
942 "dish": {
943 "sdfRef": "#/sdfData/dish",
944 "required": [ "name" ],
945 }
946 }
947 "type": "object"
948 },
949 "type": "array"
950 }
951 }
952 }
954 Figure 10: SDF conversion of the YANG module from the last figure
956 3.9. Choice Statement
958 * YANG: Section 7.9 (choice) of [RFC7950]
960 * SDF: Section 4.7.2 (sdfChoice) of [I-D.ietf-asdf-sdf]
962 Conversion of the choice statement from YANG is simple since it is
963 similar to the sdfChoice quality. The choice statement is used to
964 define alternative sub-trees for the node the choice occurs in. Only
965 one of the alternatives is present in the data tree. A YANG choice
966 is converted to an sdfProperty if it occurs on top-level or one level
967 below, like the snack definition in Figure 11 and Figure 12. On any
968 other level a choice is mapped to an entry of the properties quality
969 of the compound-type definition corresponding to the parent node of
970 the choice. The food-level2 definition in Figure 11 and Figure 12 is
971 an example of this kind of mapping. The SDF equivalent of the choice
972 contains the sdfChoice quality. Case or other child nodes of the
973 choice are mapped to SDF as one of the named alternatives of the
974 sdfChoice each. What cannot be represented is the default sub-
975 statement of the YANG choice that defines which of the alternatives
976 is considered the default one. This information is preserved in a
977 conversion note as described in Section 5.2.
979 container food {
980 container food-level2 {
981 choice dinner {
982 default home-cooked;
983 case restaurant {
984 leaf steak { type boolean; }
985 leaf pizza { type boolean; }
986 }
987 case home-cooked {
988 leaf pasta { type boolean; }
989 }
990 }
991 }
992 choice snack {
993 case sports-arena {
994 leaf pretzel { type boolean; }
995 leaf beer { type boolean; }
996 }
997 case late-night {
998 leaf chocolate { type boolean; }
999 }
1000 }
1001 }
1003 Figure 11: YANG container using the choice statement
1005 "sdfObject": {
1006 "food": {
1007 "sdfProperty": {
1008 "food-level2": {
1009 "properties": {
1010 "dinner": {
1011 "description": "!Conversion note: default home-cooked!\n",
1012 "sdfChoice": {
1013 "home-cooked": {
1014 "properties": {
1015 "pasta": { "type": "boolean" }
1016 },
1017 "type": "object"
1018 },
1019 "restaurant": {
1020 "properties": {
1021 "pizza": { "type": "boolean" },
1022 "steak": { "type": "boolean" }
1023 },
1024 "type": "object"
1025 }
1026 }
1027 }
1028 },
1029 "type": "object"
1030 },
1031 "snack": {
1032 "description": "!Conversion note: default late-night!\n",
1033 "sdfChoice": {
1034 "late-night": {
1035 "properties": {
1036 "chocolate": { "type": "boolean" }
1037 },
1038 "type": "object"
1039 },
1040 "sports-arena": {
1041 "properties": {
1042 "beer": { "type": "boolean" },
1043 "pretzel": { "type": "boolean" }
1044 },
1045 "type": "object"
1046 }
1047 }
1048 }
1049 }
1050 }
1051 }
1053 Figure 12: SDF conversion of the YANG container from the last figure
1055 3.10. RPC Statement
1057 * YANG: Section 7.14 (rpc) of [RFC7950]
1059 * SDF: Sections 2.2.3 and 5.3 (sdfAction) of [I-D.ietf-asdf-sdf]
1061 Remote procedure calls (RPCs) can be modeled in YANG with rpc nodes
1062 which have up to one input child node holding the commands input data
1063 and up to one output node for the output data. In YANG RPCs can only
1064 occur on the top-level because in contrast to actions in YANG they do
1065 not belong to a container. This can easily be represented by
1066 sdfActions. The corresponding sdfAction is not placed inside an
1067 sdfObject or sdfThing but at the top-level of the SDF model to
1068 represent independence from a container. The input node of the RPC
1069 is converted to the sdfInputData quality of the sdfAction which is of
1070 type object. Equivalently, the output node of the RPC becomes the
1071 sdfOutputData of the sdfAction, which is also of type object.
1072 Groupings and typedefs in the RPC are converted to sdfData
1073 definitions inside the sdfAction.
1075 3.11. Action Statement
1077 * YANG: Section 7.15 (action) of [RFC7950]
1079 * SDF: Sections 2.2.3 and 5.3 (sdfAction) of [I-D.ietf-asdf-sdf]
1081 Action nodes in YANG work similarly to rpc nodes in the way that they
1082 are used to model operations that can be invoked in the module and
1083 also have up to one input and output child node respectively. As
1084 mentioned before, YANG actions are affiliated to a container. The
1085 representation of this affiliation is not quite trivial because YANG
1086 containers are not translated to sdfObjects in all cases. Only
1087 sdfObjects can have sdfActions, however. If an action occurs in a
1088 container that is a below-top-level container (and thus not converted
1089 to sdfObject), as illustrated in Figure 13, the affiliation cannot be
1090 represented directly in SDF as of now. Figure 14 shows how an XML
1091 instance of calling the action in Figure 13 and the reply would look
1092 like. As an input, the action specifies the container server it is
1093 affiliated to and its name. The actual action, reset and the value
1094 of its input, reset-at are specified inside the container instance.
1095 The result after converting the container from Figure 13 to SDF can
1096 be found in Figure 15: To ensure equivalence of model instances a
1097 copy of the contents of the converted container is set as the
1098 sdfInputData of the sdfAction. The sdfInputData is of type object.
1099 The conversion of the actual action along with its input is added to
1100 the copy of the container conversion as another entry to its
1101 properties quality. Furthermore, a conversion note is added as
1102 described in Section 5.2. Equivalently, the output nodes of the
1103 action become the sdfOutputData of the sdfAction which is also of
1104 type object. Groupings and typedefs in the action node are converted
1105 to sdfData definitions inside the sdfAction.
1107 container example-container {}
1108 container server {
1109 leaf name { type string; }
1110 action reset {
1111 input {
1112 leaf reset-at { type string; }
1113 }
1114 output {
1115 leaf reset-finished-at { type string; }
1116 }
1117 }
1118 }
1119 }
1121 Figure 13: YANG container using the action statement
1123
1124
1125
1126 apache-1
1127
1128 2014-07-29T13:42:00Z
1129
1130
1131
1132
1134
1135
1136 2014-07-29T13:42:12Z
1137
1138
1140 Figure 14: XML instance of the action from the last figure
1141 "sdfObject": {
1142 "example-container": {
1143 "sdfAction": {
1144 "reset": {
1145 "description": "Action connected to server\n\n",
1146 "sdfInputData": {
1147 "properties": {
1148 "server": {
1149 "properties": {
1150 "name": { "type": "string" },
1151 "reset": {
1152 "properties": {
1153 "reset-at": { "type": "string" }
1154 },
1155 "type": "object"
1156 }
1157 },
1158 "type": "object"
1159 }
1160 },
1161 "required": [ "server" ],
1162 "type": "object"
1163 },
1164 "sdfOutputData": {
1165 "properties": {
1166 "reset-finished-at": { "type": "string" }
1167 },
1168 "type": "object"
1169 }
1170 }
1171 },
1172 "sdfProperty": {
1173 "server": {
1174 "properties": {
1175 "name": { "type": "string" }
1176 },
1177 "type": "object"
1178 }
1179 }
1180 }
1181 }
1183 Figure 15: SDF conversion of the YANG container from Figure 13
1185 3.12. Notification Statement
1187 * YANG: Section 7.16 (notification) of [RFC7950]
1188 * SDF: Sections 2.2.4 and 5.4 (sdfEvent) of [I-D.ietf-asdf-sdf]
1190 In YANG, notification nodes are used to model notification messages.
1191 Notification nodes are converted to sdfEvent definitions. Their
1192 child nodes are converted to the sdfOutputData of the sdfEvent which
1193 is of type object. Groupings and typedefs in the notification node
1194 are converted to sdfData definitions inside the sdfEvent.
1196 3.13. Augment Statement
1198 * YANG: Section 7.17 (augment) of [RFC7950]
1200 * SDF: Section 4.6. (common qualities) of [I-D.ietf-asdf-sdf]
1202 The augment statement can either occur at the top-level of a module
1203 to add nodes to an existing target module or sub-module, or in a uses
1204 statement to augment the targeted and thus integrated grouping. The
1205 conversion of the augment statement to SDF is not trivial because SDF
1206 does not feature this mechanism.
1208 The tool used to deserialize YANG modules, Libyang, adds the nodes
1209 into the target of the augment statement automatically for targets
1210 that are modules or sub-modules. This is adopted in the mapping: The
1211 SDF model that corresponds to target of the the augment statement is
1212 converted with the augmentation already applied. A conversion note
1213 is added to the description as described in Section 5.2 to preserve
1214 where the augmentation was issued from. This mapping is illustrated
1215 in Figure 16, Figure 17 and Figure 18. If the resulting SDF model
1216 has to be converted back to YANG, definitions that are marked as
1217 augmentations are converted back accordingly. This way of mapping
1218 the augment statement to SDF causes problems if the augmentation
1219 target lies within a module whose converted version is already
1220 available and should not be replaced. Because, as of now, SDF does
1221 not offer means to extend already existing models retroactively these
1222 augmentations cannot be converted to SDF.
1224 When the target of the augment is a grouping the augmentation cannot
1225 be represented in SDF, either. The reason for this is that grouping
1226 nodes are converted to SDF definitions with the type object. The
1227 nodes inside the grouping are converted with the help of the
1228 properties quality. It is currently not possible to add properties
1229 to the properties quality, it can only be overridden as a whole.
1231 module example-module {
1232 // [...]
1233 leaf leaf1 { type string; }
1234 }
1235 Figure 16: YANG module that serves as an augmentation target
1237 module augmenting-module {
1238 // [...]
1239 augment "/example" {
1240 leaf additional-leaf { type string; }
1241 }
1242 }
1244 Figure 17: YANG module using the augment statement on the module
1245 from the last figure
1247 {
1248 ; [...]
1249 "sdfProperty": {
1250 "leaf1": { "type": "string" },
1251 "additional-leaf": {
1252 "description": "!Conversion note: augmented-by augmenting-module!\n",
1253 "type": "string"
1254 }
1255 }
1256 }
1258 Figure 18: SDF conversion of the YANG module from Figure 16 after
1259 conversion of the YANG module from Figure 17
1261 3.14. Anydata and Anyxml Statements
1263 * YANG: Sections 7.10 and 7.11 (augment) of [RFC7950]
1265 * SDF: Section 4.6 (common qualities) of [I-D.ietf-asdf-sdf]
1267 The anydata and anyxml statements are designated for nodes in the
1268 schema tree whose structure is unknown at the design time of the
1269 module or in general. Since this is not a concept that can be
1270 represented in SDF as of now, anydata and anyxml nodes are not
1271 converted. Instead, to preserve the information a conversion note is
1272 added to the SDF element corresponding to the parent node of the
1273 anydata or anyxml node as described in Section 5.2.
1275 3.15. Type Statement
1277 * YANG: Section 7.4 (type) of [RFC7950]
1279 * SDF: Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf]
1280 The type statement of YANG is used to specify the built-in or derived
1281 type used by a leaf or typedef node. Mapping this statement to YANG
1282 is trivial if the argument is a simple data type because the SDF data
1283 qualities also contain a type quality. A derived type used as an
1284 argument to the YANG type statement is converted via the sdfRef
1285 quality. As an argument, the sdfRef quality contains a reference to
1286 the sdfData definition corresponding to the derived type. If the
1287 derived type is restricted, for example with the length statement,
1288 the restrictions are converted as they would be for the base type and
1289 added to the SDF definition containing the type in question.
1291 There are multiple sub-statements to the type statement that depend
1292 on its value. The conversion of those sub-statements is discussed in
1293 the section of the built-in type the sub-statement belongs to.
1295 3.16. String Built-In Type
1297 * YANG: Section 9.4 (string) of [RFC7950]
1299 * SDF: Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf]
1301 The YANG built-in type string is converted to the SDF built-in type
1302 string. Strings in YANG can be restricted in length and by regular
1303 expressions.
1305 The length statement can specify either a constant length, a lower
1306 inclusive length, an upper inclusive length or both a lower and upper
1307 inclusive length. A length statement can also specify more than one
1308 disjoint constant length or length ranges. The values min and max in
1309 a length statement represent the minimum and maximum lengths accepted
1310 for strings. If the length statement in YANG does not contain a
1311 constant value but a length range it is converted to the minLength
1312 and maxLength SDF qualities. This is illustrated in Figure 19 and
1313 Figure 20. If a constant value is defined through the YANG length
1314 statement the minLength and maxLength qualities are set to the same
1315 value. If the length statement specifies multiple length ranges or
1316 constant values the sdfChoice quality is used for conversion. The
1317 named alternatives of the sdfChoice contain the single converted
1318 length ranges or constant values each. If the min and max values are
1319 present in the YANG length statement they are converted to the
1320 respective minimum and maximum lengths accepted for strings.
1322 The YANG pattern statement can be used to hold regular expressions
1323 that the affiliated string has to match. To patterns from YANG in
1324 SDF the pattern quality can be used. One problem in the conversion
1325 of patterns is that YANG strings can be restricted by multiple
1326 patterns but SDF strings can have at most one pattern. To represent
1327 multiple patterns from YANG in SDF the patterns are combined into one
1328 regular expression with the help of positive look-ahead. Figure 19
1329 contains an example leaf of type string with multiple defined
1330 patterns which is converted as shown in Figure 20. This does not
1331 always convey the meaning of the original regular expression.
1332 Another issue is the possibility to declare invert-match patterns in
1333 YANG. These types of patterns are converted to SDF by adding
1334 negative look-ahead to the regular expression, as illustrated in
1335 Figure 21 and Figure 22. To preserve the original patterns and to
1336 facilitate round trips, the original patterns are stored with a
1337 conversion note in the description of the containing definition as
1338 described in section Section 5.2.
1340 leaf example {
1341 type string {
1342 length "1..4";
1343 pattern "[0-9]*";
1344 pattern "[a-z]*";
1345 }
1346 }
1348 Figure 19: YANG leaf node with type string, multiple pattern
1349 statements and a length statement
1351 "sdfProperty": {
1352 "example": {
1353 "description": "!Conversion note: pattern [0-9]*!\n!Conversion note: pattern [a-z]*!\n",
1354 "maxLength": 4.0,
1355 "minLength": 1.0,
1356 "pattern": "(?=[0-9]*)[a-z]*",
1357 "type": "string"
1358 }
1359 }
1361 Figure 20: SDF conversion of the YANG leaf from the last figure
1363 leaf example {
1364 type string {
1365 pattern "[0-9]*" { modifier invert-match; }
1366 }
1367 }
1369 Figure 21: YANG leaf definition with type string and an invert-
1370 match pattern
1372 "sdfProperty": {
1373 "example": {
1374 "description": "!Conversion note: pattern [0-9]*!\n",
1375 "pattern": "((?!([0-9]*)).)*",
1376 "type": "string"
1377 }
1378 }
1380 Figure 22: SDF conversion of the YANG leaf from the last figure
1382 Another, more general problem regarding the conversion of regular
1383 expressions from YANG to SDF is the fact that YANG uses a regular
1384 expression language as defined by W3C Schema while SDF adopts
1385 ECMAscript regular expressions. Both regular expression languages
1386 share most of their features. Since this does not cause problems in
1387 most cases and regarding the time constraints of this thesis, this
1388 issue is not given any further attention beyond what was stated in
1389 this paragraph. There is, however, a project of the IETF Network
1390 Working Group to create an interoperable regular expression format.
1391 Once the work on the draft has progressed the format might be adopted
1392 by the SDF/YANG converter.
1394 3.17. Decimal64 Built-In Type
1396 * YANG: Section 9.3 (decimal64) of [RFC7950]
1398 * SDF: Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf]
1400 The decimal64 built-in type of YANG is converted to the number type
1401 in SDF. A decimal64 type in YANG has a mandatory fraction-digits
1402 sub-statement that specifies the possible number of digits after the
1403 decimal separator. The value of the fraction-digits statement is
1404 converted to the multipleOf quality of SDF which states the
1405 resolution of a number, that is the size of the minimal distance
1406 between number values. Figure 23 and Figure 24 contain examples for
1407 the conversion of the decimal64 built-in type.
1409 A YANG decimal64 type can be restricted by means of the range
1410 statement specifying either a constant value, a lower inclusive
1411 bound, an upper inclusive bound or both a lower and upper inclusive
1412 value. The range statement can also be used to specify multiple
1413 disjoint constant values or ranges. The min and max key words in a
1414 range statement represent the minimum and maximum values of the type
1415 in question. If the range statement in YANG contains a range and not
1416 a constant value it is converted to the minimum and maximum data
1417 qualities in SDF. This is illustrated in the definition called my-
1418 sensor-value in the example. If a constant value is defined through
1419 the YANG range the SDF const quality is set accordingly, as shown for
1420 the definition room-temperature in the example. If the range
1421 specifies multiple ranges or constant values the sdfChoice quality is
1422 used for conversion. The named alternatives of the sdfChoice contain
1423 the single converted ranges or constant values each. An example for
1424 this conversion can be found in the my-sensor-value3 example
1425 definition. If the min and max values are present in the YANG range
1426 they are converted to the respective minimum and maximum values for
1427 the type in question, as shown for the max value in the example
1428 definition my-sensor-value2.
1430 module decimal64-example {
1431 // [...]
1432 leaf my-sensor-value {
1433 type decimal64 {
1434 fraction-digits 2;
1435 range "-50.0..150.0";
1436 }
1437 }
1438 leaf my-sensor-value2 {
1439 type decimal64 {
1440 fraction-digits 4;
1441 range "0..max";
1442 }
1443 }
1444 leaf my-sensor-value3 {
1445 type decimal64 {
1446 fraction-digits 6;
1447 range "0.0..1.0 | 5.0";
1448 }
1449 }
1450 leaf room-temperature {
1451 type decimal64 {
1452 fraction-digits 1;
1453 range "21.5";
1454 }
1455 }
1456 }
1458 Figure 23: YANG module using the decimal64 built-in type
1460 {
1461 ; [...]
1462 "sdfProperty": {
1463 "my-sensor-value": {
1464 "maximum": 150.0,
1465 "minimum": -50.0,
1466 "multipleOf": 0.01,
1467 "type": "number"
1468 },
1469 "my-sensor-value2": {
1470 "maximum": 3.3999999521443642e+38,
1471 "minimum": 0.0,
1472 "multipleOf": 0.0001,
1473 "type": "number"
1474 },
1475 "my-sensor-value3": {
1476 "sdfChoice": {
1477 "range_option_1": {
1478 "maximum": 0.0,
1479 "minimum": 1.0,
1480 "multipleOf": 0.000001,
1481 "type": "number"
1482 },
1483 "range_option_2": {
1484 "const": 5.0,
1485 "multipleOf": 0.000001,
1486 "type": "number"
1487 }
1488 }
1489 },
1490 "room-temperature": {
1491 "const": 21.5,
1492 "multipleOf": 0.1,
1493 "type": "number"
1494 }
1495 }
1496 }
1498 Figure 24: SDF conversion of the YANG module from the last figure
1500 3.18. Integer Built-In Types
1502 * YANG: Section 9.2 (integer) of [RFC7950]
1504 * SDF: Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf]
1505 In YANG there are 8 different integer types: int8, uint8, int16,
1506 uint16, int32, uint32, int64 and uint64. Each of them is converted
1507 to type integer in SDF. A conversion note specifying the exact type
1508 is added as described in Section 5.2. Additionally, the minimum and
1509 maximum qualities of the SDF definition that the converted type
1510 belongs to are set to the respective minimum and maximum values of
1511 the integer type in question. If the YANG type also specifies a
1512 range, the minimum and maximum SDF qualities are altered accordingly.
1513 Like the decimal64 YANG built-in type, the YANG integer types can
1514 also be restricted by a range statement. The integer range statement
1515 is converted as described in Section 3.17.
1517 leaf example {
1518 type int32;
1519 }
1521 Figure 25: YANG leaf with the int32 built-in type
1523 "sdfProperty": {
1524 "example": {
1525 "description": "!Conversion note: type int32!\n",
1526 "maximum": 2147483647,
1527 "minimum": -2147483648,
1528 "type": "integer"
1529 }
1530 }
1532 Figure 26: SDF conversion of the YANG leaf from the last figure
1534 3.19. Boolean Built-In Type
1536 * YANG: Section 9.5 (boolean) of [RFC7950]
1538 * SDF: Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf]
1540 The YANG boolean built-in type holds a boolean value, that is one of
1541 either true or false. It is converted to the SDF boolean type.
1542 There are no further sub-statements to this type in YANG.
1544 3.20. Binary Built-In Type
1546 * YANG: Section 9.8 (binary) of [RFC7950]
1548 * SDF: Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf]
1550 To represent binary data, the YANG built-in type binary can be used.
1551 If the argument of the YANG type statement is binary the SDF type
1552 quality is set to string. In addition, the sdfType quality is set to
1553 byte-string. A YANG binary can have a sub-statement restricting its
1554 length. This is converted to SDF via the minLength and maxLength
1555 qualities. Like the string YANG built-in type, the binary type can
1556 also be restricted by a length statement. This length statement is
1557 converted as described in Section 3.16.
1559 3.21. Enumeration Built-In Type
1561 * YANG: Section 9.6 (enumeration) of [RFC7950]
1563 * SDF: Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf]
1565 The YANG built-in type enumeration is used to map string-valued
1566 alternatives to integer values. Additionally each string can have a
1567 description and other sub-statements. SDF also specifies an enum
1568 quality which is used to represent YANG enumerations. The SDF enum
1569 quality only holds an array of strings. All other information is
1570 stored in conversion notes in the description of the SDF definition
1571 the enum belongs to, as specified in Section 5.2.
1573 3.22. Bits Built-In Type
1575 * YANG: Section 9.8 (bits) of [RFC7950]
1577 * SDF: Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf]
1579 SDF does not specify a built-in type to represent a set of named bits
1580 and their positions like YANG does with its built-in type bits.
1581 Therefore, this built-in type has to be converted to SDF type object
1582 with one entry to the properties quality of type boolean for each
1583 bit. The property is named after the name of the bit. The position
1584 of the bit is stored in a conversion note as described in
1585 Section 5.2. An example conversion of a leaf with type bits to SDF
1586 can be found in Figure 27 and Figure 28.
1588 leaf example {
1589 type bits {
1590 bit auto-adapt {
1591 description "1 if automatic adaption is enabled, 0 otherwise";
1592 position 1;
1593 }
1594 bit battery-only { position 2; }
1595 bit disable-sensor { position 0; }
1596 }
1597 }
1599 Figure 27: YANG leaf that is of the built-in type bits
1601 "sdfProperty": {
1602 "example": {
1603 "description": "!Conversion note: type bits!\n",
1604 "properties": {
1605 "auto-adapt": {
1606 "description": "Bit at position 1: 1 if automatic adaption is enabled, 0 otherwise",
1607 "type": "boolean"
1608 },
1609 "battery-only": {
1610 "description": "Bit at position 2",
1611 "type": "boolean"
1612 },
1613 "disable-sensor": {
1614 "description": "Bit at position 0",
1615 "type": "boolean"
1616 }
1617 },
1618 "type": "object"
1619 }
1620 }
1622 Figure 28: SDF conversion of the YANG leaf from the last figure
1624 3.23. Union Built-In Type
1626 * YANG: Section 9.12 (union) of [RFC7950]
1628 * SDF: Section 4.7.2 (sdfChoice) of [I-D.ietf-asdf-sdf]
1630 YANG unions hold a set of alternatives for the type statement.
1631 Although the union built-in type of YANG does not exist as a built-in
1632 type in SDF, its meaning can be easily represented by the sdfChoice
1633 quality. The sdfChoice corresponding to the union contains a set of
1634 named alternatives each named after the respective type in the YANG
1635 union and each containing nothing but the SDF type quality set to the
1636 SDF equivalent of the respective type. Figure 29 and Figure 30
1637 illustrate this mapping.
1639 leaf example {
1640 type union {
1641 type string;
1642 type boolean;
1643 }
1644 }
1646 Figure 29: YANG leaf that uses the union built-in type
1648 "sdfProperty": {
1649 "example": {
1650 "description": "!Conversion note: type union!\n",
1651 "sdfChoice": {
1652 "boolean": {
1653 "type": "boolean"
1654 },
1655 "string": {
1656 "type": "string"
1657 }
1658 }
1659 }
1660 }
1662 Figure 30: SDF conversion of the YANG leaf from the last figure
1664 3.24. Leafref and Identityref Built-In Types
1666 * YANG: Section 9.9 (leafref) of [RFC7950] Section 9.10
1667 (identityref) of [RFC7950]
1669 * SDF: Section 4.4 (sdfRef) of [I-D.ietf-asdf-sdf]
1671 The YANG built-in types leafref and identityref are used to reference
1672 a leaf node or identity definition respectively. They are
1673 represented in SDF by the sdfRef quality. As an argument said sdfRef
1674 quality contains a reference to the SDF element corresponding to the
1675 target of the leafref or identityref statement.
1677 3.25. Empty Built-In Type
1679 * YANG: Section 9.11 (empty) of [RFC7950]
1681 * SDF: Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf]
1683 Another concept that is not contained in SDF directly is that of the
1684 YANG built-in type empty. YANG elements with this type convey
1685 meaning by their mere existence or non-existence. This is
1686 represented in SDF using the compound-type with an empty set of
1687 properties.
1689 3.26. Instance-Identifier Built-In Type
1691 * YANG: Section 9.13 (instance-identifier) of [RFC7950]
1693 The instance-identifier built-in type of YANG is used to refer to a
1694 particular instance of a node in the data tree. As of now, it cannot
1695 be represented functionally in SDF because there is currently no
1696 possibility to refer to specific instances of SDF definitions. This
1697 feature might be added to SDF in the future. For now, this type is
1698 represented by the string built-in type of SDF. Furthermore, a
1699 conversion note is added to the resulting SDF definition as specified
1700 in Section 5.2. .
1702 3.27. Typedef Statement
1704 * YANG: Section 9.3 (typedef) of [RFC7950]
1706 * SDF: Section 4.4 (sdfRef) of [I-D.ietf-asdf-sdf]
1708 The typedef statement has the purpose to define derived types in
1709 YANG. The SDF class sdfData is used to represent typedefs after
1710 conversion. The usage of a derived type via the type statement is
1711 converted to an sdfRef to the corresponding sdfData definition. If a
1712 derived type is restricted according to its base type, for example
1713 with a range statement, the restrictions are converted as they would
1714 be for the base type and added to the sdfData definition.
1716 3.28. Identity Statement
1718 * YANG: Section 7.18 (identity) of [RFC7950]
1720 * SDF: Section 5.5 (sdfData) of [I-D.ietf-asdf-sdf]
1722 The YANG identity statement is used to denote the name and existence
1723 of an identity. Identities can be based on one or more other
1724 identities. They are referenced with the identityref statement.
1725 This concept is converted to SDF by sdfData definitions for each
1726 identity. If an identity is based on one other identity this is
1727 represented by an sdfRef reference to the sdfData definition
1728 corresponding to the base identity. If an identity has multiple base
1729 identities it is converted to a compound-type sdfData definition with
1730 one property for each base identity. Each property contains an
1731 sdfRef reference to the sdfData definition corresponding to one of
1732 the base identities.
1734 3.29. Config Statement
1736 * YANG: Section 7.21.1 (config) of [RFC7950]
1738 * SDF: Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf]
1740 The config statement of YANG can have the boolean values true or
1741 false as arguments. If config is set to true the element containing
1742 the config statement represents readable and writable configuration
1743 data. If the config statement is set to false the element containing
1744 the statement represents read-only state data. This is transferred
1745 to SDF via the readable and writable qualities. If the config
1746 statement is set to true it is mapped to the readable and writable
1747 qualities both being set to true. If the config statement is set to
1748 false it is converted by setting the readable quality to true and the
1749 writable quality to false. There are, however, cases in which the
1750 SDF definition corresponding to the YANG element containing the
1751 config statement is not one that can use data qualities. This is the
1752 case, for example, if a top-level container, which is converted to
1753 sdfObject, holds a config statement. In this case, all definitions
1754 inside the sdfObject that can use data qualities have the readable
1755 and writable qualities set as described above.
1757 3.30. Status Statement
1759 * YANG: Section 7.21.2 (status) of [RFC7950]
1761 * SDF: Section 4.6 (common qualities) of [I-D.ietf-asdf-sdf]
1763 The status statement of YANG is used to express whether a definition
1764 is either current, deprecated or obsolete. In SDF there is no
1765 quality with a similar meaning. Thus, the YANG status statement is
1766 represented by a conversion note in the description of the SDF
1767 definition corresponding to the YANG element the status statement
1768 occurred in as described in Section 5.2.
1770 3.31. Reference Statement
1772 * YANG: Section 7.21.4 (reference) of [RFC7950]
1774 * SDF: Section 4.6 (common qualities) of [I-D.ietf-asdf-sdf]
1776 In YANG the reference statement holds a human-readable reference to
1777 an external document related to its containing YANG definition. This
1778 information is preserved through a conversion note in the description
1779 of the SDF definition equivalent to the node containing the reference
1780 statement as described in Section 5.2.
1782 3.32. When and Must Statements
1784 * YANG: Section 7.5.3 (must) of [RFC7950] Section 7.21.5 (when) of
1785 [RFC7950]
1787 * SDF: Section 4.6 (common qualities) of [I-D.ietf-asdf-sdf]
1789 As mentioned before, YANG provides means to impose conditions on its
1790 definitions. If a node in the data tree has an unfulfilled must or
1791 when condition it is invalidated. Must and when conditions use XML
1792 Path Language expressions to indicate dependencies. This feature is
1793 not realizable in SDF as of now and is thus preserved through
1794 conversion notes as described in Section 5.2.
1796 There is a query language similar to XML Path Language for JSON
1797 called JSONPath. If SDF adopts JSONPath or something similar in the
1798 future the converter can be extended to process the functionality of
1799 must and when statements.
1801 3.33. Extension Statement
1803 * YANG: Section 7.19 (extension) of [RFC7950]
1805 * SDF: Section 4.6 (common qualities) of [I-D.ietf-asdf-sdf]
1807 The extension statement in YANG has the purpose of defining new
1808 statements for the YANG language. This is not a concept that can be
1809 transferred to SDF yet. When an extension is used, this fact has to
1810 be stored in a conversion note in the description of the SDF
1811 definition that is analogue to the YANG definition containing the
1812 extension statement, as described in Section 5.2. The definition of
1813 the extension is not converted.
1815 4. Mapping from SDF to YANG
1817 In this section the conversion of each element of SDF to YANG is
1818 explained in detail. For reference on the individual YANG statements
1819 see [RFC7950] and [I-D.ietf-asdf-sdf] for SDF. Examples have been
1820 inserted where they are necessary to understand the mapping.
1822 4.1. Information Block
1824 * SDF: Section 3.1 (information block) of [I-D.ietf-asdf-sdf]
1826 * YANG: Section 7.1 (module) of [RFC7950]
1828 At the top of an SDF model the information block holds meta data,
1829 that is the title, version, copyright and license information, about
1830 the model. When mapping an SDF model to YANG, the content of the
1831 title quality is used as the name for the YANG module. For this, the
1832 title string has to be modified to only contain lower case letters,
1833 digits and the characters "_", "-" and ".". If the version quality
1834 contains a date in the format _month-day-year_ it is analogue to the
1835 revision statement of YANG and converted as such. The strings from
1836 the copyright and license qualities are stored in the description of
1837 the resulting YANG module since there are no dedicated YANG
1838 statements equivalent to these qualities.
1840 4.2. Namespace Section
1842 * SDF: Sections 3.2 and 4 (namespaces section) of
1843 [I-D.ietf-asdf-sdf]
1845 * YANG: Section 7.1.3 (namespace) of [RFC7950] Section 7.1.5
1846 (import) of [RFC7950]
1848 The purpose of the namespace section in an SDF model is to specify
1849 its (optional) namespace and the namespaces of external models whose
1850 definitions are referenced. The namespace section has a namespace
1851 quality mapping namespace URIs to a shortened name for that URI. The
1852 shortened name is also used as a prefix when referring to external
1853 definitions. If an SDF model is supposed to contribute globally
1854 available definitions, a value is given to the defaultNamespace
1855 quality and mapped to a namespace URI in the namespace quality. To
1856 map this to YANG, three of its statements are necessary: the import,
1857 the prefix and the namespace statement. To be able to use
1858 definitions from external modules in YANG, their names have to be
1859 declared by one import statement each. As a first step, each
1860 external SDF model that is mentioned in the namespace map also has to
1861 be converted to a YANG module. The default namespaces of the
1862 external SDF models are represented in the prefix sub-statement of
1863 the respective import statement. To represent the namespace and
1864 short name of the model, if present, the YANG namespace and prefix
1865 statements that are set accordingly. Both are top-level statements.
1867 4.3. SdfThing Quality
1869 * SDF: Sections 2.2.6 and 6.3 (sdfThing) of [I-D.ietf-asdf-sdf]
1871 * YANG: Section 7.5 (container) of [RFC7950]
1873 An sdfThing definition holds the definition of a complex device that
1874 can be made up of multiple sdfObjects and multiple other sdfThings.
1875 SdfThings are converted to YANG container nodes. The sdf-spec
1876 extension is inserted to inform about the origin of the container as
1877 an sdfThing. This is necessary to facilitate round-trips because the
1878 container could also originate from an sdfObject.
1880 4.4. SdfObject Quality
1882 * SDF: Sections 2.2.1 and 5.1 (sdfObject) of [I-D.ietf-asdf-sdf]
1884 * YANG: Section 7.5 (container) of [RFC7950]
1885 SdfObject definitions are the main building blocks of an SDF model,
1886 grouping together definitions of the classes sdfProperty, sdfData,
1887 sdfAction and sdfEvent. They can also be used as arrays via their
1888 minItems and maxItems qualities. An sdfObject is mapped to a YANG
1889 container node if it is not defined as an array. Otherwise the
1890 sdfObject can be converted to a list node with the min-elements and
1891 max-elements statements set analogous to the minItems and maxItems
1892 qualities. This feature was only recently added to SDF and is thus
1893 not yet implemented neither in the SDF serializer/deserializer nor in
1894 the SDF/YANG converter.
1896 4.5. Common Qualities
1898 * SDF: Section 4.6 (common qualities) of [I-D.ietf-asdf-sdf]
1900 * YANG:
1902 - Section 7.21.3 (description) of [RFC7950]
1904 - Section 7.3 (typedef) of [RFC7950]
1906 - Section 9.9 (leafref) of [RFC7950]
1908 - Section 7.13 (uses) of [RFC7950]
1910 - Section 3 (terminology for mandatory) of [RFC7950]
1912 The set of qualities that is grouped under the name of _common
1913 qualities_ can be used to provide meta data for SDF definitions.
1915 The description quality is converted to the YANG description
1916 statement. The label quality is ignored because it is identical to
1917 the identifier of the definition in most cases.
1919 The sdfRef quality is supposed to hold references to other
1920 definitions whose qualities are then copied into the referencing
1921 definition. Qualities of the referenced definition can also be
1922 overridden by defining them again in the referencing definition. The
1923 conversion of an sdfRef depends on what is referenced by it and what
1924 that is converted to. Figure 31 and Figure 32, as well as Figure 33
1925 and Figure 34 illustrate different conversions of the sdfRef quality.
1926 If the referenced definition is converted to a typedef the sdfRef is
1927 analogous to the type statement in YANG which points to the typedef.
1928 Overridden qualities can be represented by the respective sub-
1929 statements of the type which in turn override the sub-statements of
1930 the type of the typedef. This is the case for simpleDataRef in
1931 Figure 31 and Figure 32. If the referenced definition is mapped to a
1932 leaf or leaf-list node it can be referenced by the leafref built-in
1933 type in YANG. This is the case for simplePropertyRef and
1934 simpleArrayPropertyRef in Figure 33 and Figure 34. In this case
1935 overridden qualities cannot be represented in SDF. If the YANG
1936 equivalent of the referenced definition is a grouping node the sdfRef
1937 is converted to a uses node which points to said grouping. The uses
1938 node is placed inside an additional container to preserve the name of
1939 the referencing SDF definition and to avoid sibling nodes with
1940 identical names (which is invalid in YANG). This is what is done for
1941 compoundDataRef, simpleArrayDataRef and compoundArrayDataRef in
1942 Figure 31 and Figure 32. In all other cases the YANG equivalent of
1943 the referenced SDF definition cannot be referenced directly but has
1944 first to be packaged in a grouping node. This is done by first
1945 creating a grouping on the top-level of the module in order for the
1946 grouping to be available globally (in case it is also referenced in
1947 another model). The YANG node that is equivalent to the referenced
1948 SDF definition is copied into the new grouping and afterwards
1949 replaced with a uses node referencing the grouping. This is done to
1950 avoid redundancy. Lastly, the actual sdfRef is represented by
1951 another uses node referencing the newly created grouping. The uses
1952 node is placed inside a container node that represents the SDF
1953 definition that contains the sdfRef to preserve the name of the SDF
1954 definition. Furthermore, there cannot be two sibling nodes with the
1955 same name in YANG. The definitions compoundPropertyRef and
1956 compoundArrayPropertyRef in Figure 33 and Figure 34 are examples of
1957 such conversions. If SDF qualities of the referenced definition are
1958 overridden in the referencing definition this is represented with the
1959 refine statement which can be a sub-statement to uses node (see
1960 compoundArrayPropertyRef in Figure 33 and Figure 34).
1962 {
1963 ; [...]
1964 "sdfObject": {
1965 "ExampleObject": {
1966 "sdfData": {
1967 "simpleData": { "type": "string" },
1968 "compoundData": {
1969 "type": "object",
1970 "properties": {
1971 "A": { "type": "string" },
1972 "B": { "type": "string" }
1973 }
1974 },
1975 "simpleArrayData": {
1976 "type": "array",
1977 "items": { "type": "string" }
1978 },
1979 "compoundArrayData": {
1980 "type": "array",
1981 "items": {
1982 "type": "object",
1983 "properties": {
1984 "A": { "type": "string" },
1985 "B": { "type": "string" }
1986 }
1987 }
1988 }
1989 },
1990 "sdfProperty": {
1991 "simpleDataRef": {
1992 "sdfRef": "#/sdfObject/ExampleObject/sdfData/simpleData",
1993 "pattern": "[a-z]*"
1994 },
1995 "compoundDataRef": { "sdfRef": "#/sdfObject/ExampleObject/sdfData/compoundData" },
1996 "simpleArrayDataRef": { "sdfRef": "#/sdfObject/ExampleObject/sdfData/simpleArrayData" },
1997 "compoundArrayDataRef": { "sdfRef": "#/sdfObject/ExampleObject/sdfData/compoundArrayData" }
1998 }
1999 }
2000 }
2001 }
2003 Figure 31: SDF model that uses the sdfRef with different sdfData
2004 definitions
2006 module exampleModel {
2007 // [...]
2008 typedef simpleData { type string; }
2009 grouping compoundArrayData {
2010 helper:sdf-spec "sdfData";
2011 list compoundArrayData {
2012 config false;
2013 leaf A { type string; }
2014 leaf B { type string; }
2015 }
2016 }
2017 grouping compoundData {
2018 helper:sdf-spec "sdfData";
2019 leaf A { type string; }
2020 leaf B { type string; }
2021 }
2022 grouping simpleArrayData {
2023 helper:sdf-spec "sdfData";
2024 leaf-list simpleArrayData { type string; }
2025 }
2026 container ExampleObject {
2027 helper:sdf-spec "sdfObject";
2028 container compoundArrayDataRef {
2029 helper:sdf-spec "sdfProperty";
2030 uses compoundArrayData;
2031 }
2032 container compoundDataRef {
2033 helper:sdf-spec "sdfProperty";
2034 uses compoundData;
2035 }
2036 container simpleArrayDataRef {
2037 helper:sdf-spec "sdfProperty";
2038 uses simpleArrayData;
2039 }
2040 leaf simpleDataRef {
2041 type simpleData { pattern "[a-z]*"; }
2042 }
2043 }
2044 }
2046 Figure 32: YANG conversion of the SDF model from the last figure
2047 {
2048 ; [...]
2049 "sdfObject": {
2050 "ExampleObject2": {
2051 "sdfProperty": {
2052 "simpleProperty": { "type": "string" },
2053 "compoundProperty": {
2054 "type": "object",
2055 "properties": {
2056 "A": { "type": "string" },
2057 "B": { "type": "string" }
2058 }
2059 },
2060 "simpleArrayProperty": {
2061 "type": "array",
2062 "items": { "type": "string" }
2063 },
2064 "compoundArrayProperty": {
2065 "type": "array",
2066 "items": {
2067 "type": "object",
2068 "properties": {
2069 "A": { "type": "string" },
2070 "B": { "type": "string" }
2071 }
2072 }
2073 },
2074 "simplePropertyRef": { "sdfRef": "#/sdfObject/ExampleObject2/sdfProperty/simpleProperty" },
2075 "compoundPropertyRef": { "sdfRef": "#/sdfObject/ExampleObject2/sdfProperty/compoundProperty" },
2076 "simpleArrayPropertyRef": { "sdfRef": "#/sdfObject/ExampleObject2/sdfProperty/simpleArrayProperty" },
2077 "compoundArrayPropertyRef": {
2078 "sdfRef": "#/sdfObject/ExampleObject2/sdfProperty/compoundArrayProperty",
2079 "minItems": 4
2080 }
2081 }
2082 }
2083 }
2084 }
2086 Figure 33: SDF model that uses the sdfRef with sdfProperty
2087 definitions
2089 module exampleModel {
2090 // [...]
2091 grouping compoundArrayProperty {
2092 list compoundArrayProperty {
2093 helper:sdf-spec "sdfProperty";
2094 key "A";
2095 leaf A { type string; }
2096 leaf B { type string; }
2097 }
2098 }
2099 grouping compoundProperty {
2100 helper:sdf-spec "sdfProperty";
2101 leaf A { type string; }
2102 leaf B { type string; }
2103 }
2104 container ExampleObject2 {
2105 helper:sdf-spec "sdfObject";
2106 container compoundPropertyRef {
2107 helper:sdf-spec "sdfProperty";
2108 uses compoundProperty;
2109 }
2110 uses compoundProperty;
2111 leaf-list simpleArrayProperty { type string; }
2113 leaf-list simpleArrayPropertyRef {
2114 type leafref { path "/ExampleObject2/simpleArrayProperty"; }
2115 }
2116 leaf simpleProperty { type string; }
2117 leaf simplePropertyRef {
2118 type leafref { path "/ExampleObject2/simpleProperty"; }
2119 }
2120 container compoundArrayPropertyRef {
2121 uses compoundArrayProperty {
2122 refine compoundArrayProperty { min-elements 4; }
2123 }
2124 }
2125 uses compoundArrayProperty;
2126 }
2127 }
2129 Figure 34: YANG conversion of the SDF model from the last figure
2131 The common quality sdfRequired contains a list of SDF declarations
2132 that are mandatory to be present in an instance of the SDF model.
2133 The issue with the conversion of this quality is that in YANG not all
2134 nodes can be marked with the mandatory statement while in SDF all
2135 declarations (that means sdfProperties, sdfActions and sdfEvents that
2136 occur in an sdfObject) can be mentioned in the sdfRequired list. In
2137 YANG only leaf and choice nodes (and anyxml and anydata nodes but
2138 these are not used for conversion) can be directly labeled as
2139 mandatory. List and leaf-list nodes can indirectly be made mandatory
2140 through the min-elements statement. Furthermore, container nodes
2141 without a presence statement that have at least one mandatory node as
2142 a child are also mandatory themselves. Not all SDF declarations are
2143 always converted to YANG leaf, choice, list or leaf-list nodes,
2144 however. Thus, if the YANG node equivalent to the mandatory SDF
2145 declaration is a non-presence container, its sub-tree is traversed
2146 until a leaf or choice node is found. This leaf or choice node is
2147 labeled as mandatory, now making its parent container mandatory as
2148 well because one of its child nodes is mandatory. An example for
2149 such a conversion is illustrated in the compoundProperty definition
2150 in Figure 35 and Figure 36. Consequently, if the parent node of the
2151 now mandatory container would be a container it would now be
2152 mandatory as well. Alternatively, if a list or leaf-list node is
2153 found first, the min-elements statement of the node is set to 1 if it
2154 is not already set to a value greater than zero, which also makes a
2155 node mandatory. This is illustrated in the simpleArrayProperty and
2156 compoundArrayProperty definitions in Figure 35 and Figure 36. To
2157 prevent loss of information and to facilitate round trips, the
2158 declaration originally listed in the sdfRequired quality is preserved
2159 in the sdf-spec extension as described in Section 5.2.
2161 "sdfObject": {
2162 "ExampleObject": {
2163 "sdfRequired": [
2164 "#/sdfObject/ExampleObject/sdfProperty/simpleProperty",
2165 "#/sdfObject/ExampleObject/sdfEvent/compoundProperty",
2166 "#/sdfObject/ExampleObject/sdfEvent/simpleArrayProperty",
2167 "#/sdfObject/ExampleObject/sdfEvent/compoundArrayProperty"
2168 ],
2169 "sdfProperty": {
2170 "simpleProperty": { "type": "string" },
2171 "compoundProperty": {
2172 "type": "object",
2173 "properties": {
2174 "A": { "type": "string" },
2175 "B": { "type": "string" }
2176 }
2177 },
2178 "simpleArrayProperty": {
2179 "type": "array",
2180 "items": { "type": "string" }
2181 },
2182 "compoundArrayProperty": {
2183 "type": "array",
2184 "items": {
2185 "type": "object",
2186 "properties": {
2187 "A": { "type": "string" },
2188 "B": { "type": "string" }
2189 }
2190 }
2191 }
2192 }
2193 }
2194 }
2196 Figure 35: SDF model that contains the sdfRequired quality
2198 container ExampleObject {
2199 helper:sdf-spec "sdfObject";
2201 list compoundArrayProperty {
2202 helper:sdf-spec "sdfProperty";
2203 helper:sdf-spec "sdfRequired";
2204 config false;
2205 min-elements 1;
2206 leaf A { type string; }
2207 leaf B { type string; }
2208 }
2210 container compoundProperty {
2211 helper:sdf-spec "sdfProperty";
2212 helper:sdf-spec "sdfRequired";
2213 leaf A {
2214 type string;
2215 mandatory true;
2216 }
2217 leaf B { type string; }
2218 }
2220 leaf-list simpleArrayProperty {
2221 helper:sdf-spec "sdfProperty";
2222 helper:sdf-spec "sdfRequired";
2223 type string;
2224 min-elements 1;
2225 }
2227 leaf simpleProperty {
2228 helper:sdf-spec "sdfRequired";
2229 type string;
2230 mandatory true;
2231 }
2232 }
2234 Figure 36: YANG conversion of the last figure
2236 4.6. Data Qualities
2238 * SDF: Section 4.7 (data qualities) of [I-D.ietf-asdf-sdf]
2240 * YANG:
2242 - Section 7.4.1 (type) of [RFC7950]
2244 The set of qualities labeled as _data qualities_ contains qualities
2245 inspired by the json-schema.org specifications that SDF adopted as
2246 well as qualities specifically defined for SDF. In the first group
2247 there is a total of 18 qualities out of which some are
2248 interdependent.
2250 The quality that a lot of the other qualities presence or absence
2251 depends on is the type quality. The type can be one of number,
2252 string, boolean, integer, array or object. This quality is directly
2253 converted to the YANG type statement for all simple type. The type
2254 number becomes decimal64, integer becomes int64. The types string
2255 and boolean have built-in type equivalents in YANG. The types array
2256 and object cannot be converted to a YANG built-in type directly.
2257 Instead SDF definitions with these types are converted as described
2258 in Section 4.8 and Section 4.7, that is type array is mapped to
2259 leaflist or list nodes and type object is mapped to container nodes.
2261 If a constant value is defined in an SDF definition, the data quality
2262 const is used to hold it. If the value of the type quality is number
2263 or integer the const quality is mapped to the range sub-statement of
2264 the type statement of YANG, which can also contain a single value.
2265 An example of such a conversion is illustrated in displayWidth in
2266 Figure 37 and Figure 38. For constant string values the YANG pattern
2267 statement containing the constant string is used, as shown in the
2268 displayText definition in Figure 37 and Figure 38. Unfortunately,
2269 constant values of types boolean and array can only be preserved in
2270 YANG through the sdf-spec extension.
2272 "sdfObject": {
2273 "Display": {
2274 "sdfProperty": {
2275 "displayText": {
2276 "type": "string",
2277 "const": "Hello World!"
2278 },
2279 "displayWidth": {
2280 "type": "integer",
2281 "const": 300
2282 }
2283 }
2284 }
2285 }
2287 Figure 37: SdfObject that contains the const quality
2289 container Display {
2290 helper:sdf-spec "sdfObject";
2291 leaf displayText {
2292 type string { pattern "Hello World!"; }
2293 }
2294 leaf displayWidth {
2295 type int64 { range "300"; }
2296 }
2297 }
2299 Figure 38: YANG conversion of the sdfObject from the last figure
2301 The default data quality in SDF holds the default value for its
2302 definition. Since YANG leaf and leaf-list nodes have a default sub-
2303 statement, SDF default values of simple types or of type array with
2304 items of simple types can easily be represented.
2306 The data qualities minimum, maximum, exclusiveMinimum and
2307 exclusiveMaximum which are only valid for the types number and
2308 integer are converted using the YANG range statement again. For
2309 exclusive boundaries the range is reduced accordingly in YANG. This
2310 is only possible for integer types or if the multipleOf quality
2311 specifies the size by which the number limit has to be reduced.
2312 Alternatives in the YANG range have to be disjoint, however. This
2313 poses a problem when the range statement is already used to map a
2314 constant value. Thus, if both minimum or maximum and constant values
2315 are defined, this is represented through the YANG union built-in
2316 type, instead. As illustrated in Figure 39 and Figure 40, in the
2317 YANG conversion of the definition the union contains the same type
2318 twice, but with different ranges.
2320 "sdfProperty": {
2321 "displayWidth": {
2322 "type": "integer",
2323 "const": 300,
2324 "minimum": 100,
2325 "maximum": 1000
2326 }
2327 }
2329 Figure 39: SdfProperty that uses the minimum and maximum qualities in
2330 conjunction with the const quality
2332 leaf displayWidth {
2333 type union {
2334 type int64 { range "300"; }
2335 type int64 { range "100..1000"; }
2336 }
2337 }
2339 Figure 40: YANG conversion of the sdfProperty from the last figure
2341 The multipleOf data quality is one that can only be used in
2342 conjunction with the number type in SDF and states the resolution of
2343 the decimal value, that is, of which decimal number the value is a
2344 multiple of. This quality is converted to the fraction-digits sub-
2345 statement to the type statement in YANG by counting the digits after
2346 the decimal separator of the value of the multipleOf quality. Since
2347 the fraction-digits statement is mandatory in YANG, it is set to 6 by
2348 default. This is done because six is also the default decimal
2349 resolution of the std::to_string() method of the C++ standard
2350 library. This method is used for transferring data from the C++
2351 objects that represent SDF definitions into JSON.
2353 The minLength and maxLength data qualities of SDF are used to hold
2354 the minimal and maximal length of strings. This concept can be
2355 transferred to YANG by using the length sub-statement of the type
2356 statement that specifies a length range.
2358 The SDF pattern data quality holds regular expressions for string
2359 typed definitions. This can be converted directly to the pattern
2360 sub-statement of the type statement in YANG. As already mentioned in
2361 Section 3.16 regular expressions cannot be converted directly between
2362 SDF and YANG in theory, due to the differing languages used for
2363 regular expressions. Because of the time limitations of this thesis
2364 no further measures are taken to insure the conformance of converted
2365 regular expressions.
2367 The string type in SDF can be supplemented by the format quality.
2368 This quality can specify one of the formats found on json-schema.org.
2369 This could be translated to YANG referencing typedefs from the widely
2370 used ietf-yang-types module. To not rely on external modules, the
2371 format is only preserved through an addition of the sdf-spec
2372 extension to the YANG equivalent of the SDF definition the format
2373 quality is contained in.
2375 The length of an array in SDF can be restricted by the minItems and
2376 maxItems qualities. In YANG, both list and leaf-list nodes use the
2377 sub-statements min-elements and max-elements to express the same
2378 concept. They are therefore used to convert the SDF array length
2379 qualities.
2381 Another restriction for SDF arrays is the uniqueItems quality that
2382 can be set to either true or false. If it is set to true all items
2383 of an array are required to be different. For this purpose, YANG
2384 specifies the key and the unique sub-statements for list nodes. The
2385 combined values of the mentioned nodes have to be unique. These
2386 statements can only be applied to leaf nodes in the sub-tree. This
2387 does not pose a problem, however, because the uniqueness of a
2388 definition can only be measured by the uniqueness of its scalar
2389 values anyway. Thus, if an SDF array is converted to a YANG list
2390 node and the uniqueItems SDF quality is set to true, the key
2391 statement of the list states the first descendant leaf node of the
2392 list as the key, as illustrated in the compoundArrayProperty
2393 definition in Figure 41 and Figure 42. The key statement is chosen
2394 over the unique statement because it must be present in all writable
2395 lists anyway. It is not possible to explicitly represent the
2396 uniqueItems quality in leaf-list nodes. However, the values of leaf-
2397 list nodes that represent configuration data, and are therefore
2398 writable, must be unique. The writable quality is set to true by
2399 default. Thus, to represent an SDF array with unique items, in YANG
2400 the config statement is set to true whenever the writable quality in
2401 SDF is not set to false. An example of such a conversion can be
2402 found in the simpleArrayProperty definition in Figure 41 and
2403 Figure 42. Non-writable arrays with unique items cannot be
2404 represented as YANG leaf-lists.
2406 "sdfObject": {
2407 "ExampleObject": {
2408 "sdfProperty": {
2409 "simpleArrayProperty": {
2410 "type": "array",
2411 "uniqueItems": true,
2412 "items": { "type": "string" }
2413 },
2414 "compoundArrayProperty": {
2415 "type": "array",
2416 "uniqueItems": true,
2417 "items": {
2418 "type": "object",
2419 "properties": {
2420 "A": { "type": "string" },
2421 "B": { "type": "string" }
2422 }
2423 }
2424 }
2425 }
2426 }
2427 }
2428 Figure 41: SdfObject containing the uniqueItems quality
2430 container ExampleObject {
2431 helper:sdf-spec "sdfObject";
2433 list compoundArrayProperty {
2434 helper:sdf-spec "sdfProperty";
2435 key "A";
2436 leaf A { type string; }
2437 leaf B { type string; }
2438 }
2440 leaf-list simpleArrayProperty {
2441 type string;
2442 config true;
2443 }
2444 }
2446 Figure 42: YANG conversion of the sdfObject from the last figure
2448 The items data quality of SDF is a quality that specifies item
2449 constraints for the items of an array-typed SDF definition using a
2450 subset of the common and data qualities. SDF definitions with the
2451 type array are converted to list or leaf-list nodes. These node
2452 types in themselves indicate that a node represents an array. Thus,
2453 the qualities defined in the item constraints of an array are
2454 converted to the sub-statements of the equivalent list or leaf-list
2455 node as described in this section. Figure 41 and Figure 42 contain
2456 an illustration of this mapping.
2458 Another SDF data quality is the properties quality. Properties
2459 defined through this quality are different from sdfProperties. The
2460 properties quality is used in conjunction with the object type and
2461 contains a set of named definitions made up of data qualities
2462 themselves. SDF definitions of type object are converted to
2463 container or grouping nodes. Thus, the named entries in the
2464 properties quality are each transformed to the child nodes of the
2465 container or grouping in question. This is illustrated in
2466 Section 4.8 in the compoundProperty definition of Figure 45 and
2467 Figure 46. To label the properties as mandatory the required quality
2468 is used. Since it is resembling the sdfRequired quality, it is
2469 translated in the same way. The SDF type object was first introduced
2470 in SDF version 1.1 and made conversion of SDF models to YANG
2471 significantly more complicated. On the other hand, it is crucial to
2472 represent the tree structure of YANG.
2474 The second group of qualities that is part of the data qualities
2475 includes 11 qualities that are defined specifically for SDF.
2477 The unit quality can be set to any of the SenML unit names to
2478 represent the unit of an SDF definition. There is also a similar
2479 statement that can be defined as a sub-statement to typedef
2480 definitions, leaf nodes and leaf-list nodes. The units statement in
2481 YANG can contain any string and thus is simply set to the SenML unit
2482 name from the SDF definition.
2484 An important data quality is the sdfChoice quality. It represents
2485 the choice between several sets of named definitions made up of data
2486 qualities themselves. YANG provides a very similar statement, the
2487 choice statement. An sdfChoice is turned into a YANG choice node.
2488 Each of the alternatives of the sdfChoice is converted like an
2489 sdfProperty (see Section 4.8) and added to the choice node inside its
2490 own case node. SdfChoice definitions that give the choice between
2491 the type quality could also be mapped to the YANG type union. This
2492 is omitted for reasons of simplicity. An example conversion of the
2493 sdfChoice quality can be found in Figure 43 and Figure 44.
2495 "sdfObject": {
2496 "ExampleObject": {
2497 "sdfProperty": {
2498 "choiceProperty": {
2499 "sdfChoice": {
2500 "foo": { "type": "string" },
2501 "bar": { "type": "boolean" },
2502 "baz": { "type": "integer" }
2503 }
2504 }
2505 }
2506 }
2507 }
2509 Figure 43: SdfObject with an sdfChoice quality
2511 container ExampleObject {
2512 helper:sdf-spec "sdfObject";
2513 choice choiceProperty {
2514 case bar {
2515 leaf bar { type boolean; }
2516 }
2517 case baz {
2518 leaf baz { type int64; }
2519 }
2520 case foo {
2521 leaf foo { type string; }
2522 }
2523 }
2524 }
2526 Figure 44: YANG conversion of the sdfObject from the last figure
2528 SDF also offers the possibility to define the choice between string
2529 values by means of the enum data quality. It consists of an array of
2530 strings. This concept also exists in YANG with the enumeration type
2531 and the corresponding enum sub-statement to the type statement. For
2532 an SDF definition that contains the enum quality the YANG type of its
2533 equivalent is set to enumeration. Each of the strings in the array
2534 of the enum SDF quality is converted to an enum entry in the type
2535 statement in YANG. The enum entries are also assigned an associated
2536 value.
2538 The scaleMinimum and scaleMaximum qualities represent limits in units
2539 as specified by the unit quality. They are not mapped to YANG
2540 because they will not be included in future versions of SDF. They
2541 are to be replaced in the future, therefore a mapping will have to be
2542 developed for their replacement.
2544 The contentFormat quality of SDF can provide an additional IANA
2545 content type. This information is preserved with the help of sdf-
2546 spec extension in the YANG equivalent of the SDF definition.
2548 Another way to complement the type quality is the sdfType quality
2549 that can either be set to byte-string or unix-time. A byte string is
2550 converted to the YANG type binary. There is no built-in YANG type
2551 corresponding to unix time it is thus converted through the YANG
2552 units statement. The unit of the YANG conversion mentions unix-time
2553 as an argument.
2555 SDF defines the readable and writable qualities to flag whether read
2556 or write operations are allowed on definitions. Read operations are
2557 always allowed in YANG modules so a readable quality that is set to
2558 false cannot be represented in YANG. The config YANG statement can
2559 be used to represent the value of the writable quality, however. If
2560 an SDF definition is explicitly marked as writable config is set to
2561 true. Otherwise, it is set to false.
2563 The observable and nullable qualities in SDF cannot be represented in
2564 YANG but are preserved by adding an sdf-spec extension to the YANG
2565 equivalent of their containing SDF definition.
2567 4.7. SdfData Quality
2569 * SDF: Sections 2.2.5 and 5.5 (sdfData) of [I-D.ietf-asdf-sdf]
2571 * YANG:
2573 - Section 7.13 (uses) of [RFC7950]
2574 - Section 7.12 (grouping) of [RFC7950]
2576 Elements of the sdfData class are meant to hold data type definitions
2577 to be shared by sdfProperty, sdfAction and sdfEvent definitions.
2578 SdfData definitions can make use of the data qualities and the common
2579 qualities described in Section 4.6 and Section 4.5 respectively.
2580 Because an sdfData definition embodies a data type definition the
2581 YANG statements typedef and grouping have to be used for conversion.
2582 Which of the two is used depends on the value of the type quality of
2583 the sdfData definition. If the type is one of the simple data types,
2584 that is integer, number, boolean or string, the sdfData definition is
2585 converted to a YANG typedef. If the type is object the sdfData
2586 definition is mapped to a grouping node with each of the entries of
2587 the properties quality of the compound-type being mapped to a child
2588 node of the grouping. When mapping sdfData definitions with type
2589 array to YANG, the type mentioned in the type quality of the items
2590 quality is essential as well. If an array has items of any of the
2591 simple types the resulting YANG element is a grouping node containing
2592 a single leaf-list node. Otherwise, if the array items are compound-
2593 types the sdfData definition is converted into a grouping node
2594 containing a single list node. The child nodes of the list node are
2595 equivalent to the entries of the properties quality that is contained
2596 in the item quality.
2598 One issue with converting sdfData definitions of type array is the
2599 added grouping node that is necessary to hold the equivalent leaf-
2600 list or list node. If the grouping is used in the schema tree the
2601 added level will cause model instances of the original and converted
2602 model to be in-equivalent. If the sdfData definition is referenced
2603 in the SDF model via the sdfRef common quality this is represented in
2604 YANG with the uses statement pointing to the grouping equivalent to
2605 the sdfData definition. The sdfRef quality can occur at most once in
2606 each definition while there can be multiple uses statements in a
2607 single container, list or grouping. Thus, instead of representing
2608 definitions containing an sdfRef by a parent node containing a uses
2609 node, the aforementioned issue with array-typed sdfData definitions
2610 could be solved by replacing the parent node with the uses node
2611 itself, effectively removing the excess level. This, however, gives
2612 rise to other issues because the name of the superordinate definition
2613 of the sdfRef is lost this way. An example for this issue is
2614 illustrated in Figure 53 and Figure 54. If the sdfData definition is
2615 converted to a typedef no such issues arise. The typedef in question
2616 is inserted as an argument to the YANG type quality wherever the
2617 original sdfData definition was referenced by an sdfRef.
2619 Another issue is a different view on global accessibility of data
2620 type definitions in YANG and SDF. In SDF, all definitions are
2621 globally available as long as a default namespace is defined in the
2622 SDF model. In YANG on the other hand, only data type definitions,
2623 that is groupings and typedefs, that occur on the top-level of a YANG
2624 module are globally accessible. Thus, to represent the global
2625 accessibility of all data type definitions in SDF, all converted
2626 sdfData definition equivalents in YANG are added to the top-level of
2627 the created module.
2629 Since these issues are also discussed in Section 4.5, examples
2630 conversion can be found there in Figure 31 and Figure 32.
2632 4.8. SdfProperty Quality
2634 * SDF: Sections 2.2.2 and 5.2 (sdfProperty) of [I-D.ietf-asdf-sdf]
2636 * YANG:
2638 - Section 7.6 (leaf) of [RFC7950]
2640 - Section 7.7 (leaf-list) of [RFC7950]
2642 - Section 7.8 (list) of [RFC7950]
2644 SdfProperty definitions represent elements of state as suggested by
2645 their name. SdfProperty definitions can make use of the data
2646 qualities and the common qualities described in Section 4.6 and
2647 Section 4.5. The mapping of an sdfProperty definition to YANG
2648 depends on the value of the type quality. SdfProperties with simple
2649 types are mapped to leaf nodes in YANG, as illustrated in the
2650 simpleProperty definition in Figure 45 and Figure 46. If the type is
2651 complex, that is type object, conversion results in a container node
2652 with each of the entries in the properties quality being mapped to a
2653 child node of the container. An example of such a conversion is the
2654 compoundProperty definition in Figure 45 and Figure 46. If the
2655 sdfProperty is of type array the deciding factor is the type quality
2656 inside the items quality. If an array has items of a simple type, it
2657 is converted to a leaf-list node. This is demonstrated by the
2658 simpleArrayProperty definition in Figure 45 and Figure 46.
2659 Otherwise, if the items are of compound-type the sdfProperty becomes
2660 a list node in YANG. The child nodes of the list node are equivalent
2661 to the entries of the properties quality in the compound-type, as
2662 illustrated in Figure 45 and Figure 46 through the
2663 compoundArrayProperty definition. List nodes that represent
2664 configuration data, that means data that is writable, must specify at
2665 least one of its descendant leaf nodes as a key identifier. In SDF
2666 definitions that use the data qualities, such as sdfProperties, the
2667 writable quality is set to true by default. Therefore, the key
2668 statement of the list node is set to the first descendant leaf node
2669 of the list by default by the converter to comply with this rule.
2670 For round trips, this work-around is noted through the sdf-spec
2671 extension.
2673 "sdfObject": {
2674 "ExampleObject": {
2675 "sdfProperty": {
2676 "simpleProperty": { "type": "string" },
2677 "compoundProperty": {
2678 "type": "object",
2679 "properties": {
2680 "A": { "type": "string" },
2681 "B": { "type": "string" }
2682 }
2683 },
2684 "simpleArrayProperty": {
2685 "type": "array",
2686 "items": { "type": "string" }
2687 },
2688 "compoundArrayProperty": {
2689 "type": "array",
2690 "items": {
2691 "type": "object",
2692 "properties": {
2693 "A": { "type": "string" },
2694 "B": { "type": "string" }
2695 }
2696 }
2697 }
2698 }
2699 }
2700 }
2702 Figure 45: SdfObject with an sdfProperty definition
2704 container ExampleObject {
2705 helper:sdf-spec "sdfObject";
2706 list compoundArrayProperty {
2707 key "A";
2708 leaf A { type string; }
2709 leaf B { type string; }
2710 }
2711 container compoundProperty {
2712 leaf A { type string; }
2713 leaf B { type string; }
2714 }
2715 leaf-list simpleArrayProperty { type string; }
2716 leaf simpleProperty { type string; }
2717 }
2719 Figure 46: YANG conversion of the sdfObject from the last figure
2721 4.9. SdfAction Quality
2723 * SDF: Sections 2.2.3 and 5.3 (sdfAction) of [I-D.ietf-asdf-sdf]
2725 * YANG:
2727 - Section 7.14 (rpc) of [RFC7950]
2729 - Section 7.15 (action) of [RFC7950]
2731 To represent operations that can be invoked in a model the sdfAction
2732 class is used. Since operations can have input and output data the
2733 sdfAction class is equipped with the sdfInputData and sdfOutputData
2734 qualities that can both make use of the data qualities and the common
2735 qualities described in Section 4.6 and Section 4.5. An sdfAction can
2736 also define its own set of data types in the form of sdfData
2737 definitions. Whether an sdfAction is converted to an rpc node (which
2738 can only occur at the top-level of a module) or an action node (which
2739 is always tied to a container node) depends on its location inside
2740 the SDF model. SdfActions that are not part of an sdfObject but can
2741 be found independently at the top of an SDF model are converted to
2742 rpc nodes. All other sdfActions occurring inside an sdfObject become
2743 action nodes inside the YANG container equivalent to the sdfObject,
2744 as illustrated in Figure 47 and Figure 48 . The sdfInputData and
2745 sdfOutputData of an sdfAction are converted like sdfProperties (see
2746 Section 4.8) and added as the input and output node of the YANG RPC/
2747 action respectively.
2749 "sdfObject": {
2750 "ExampleObject": {
2751 "sdfAction": {
2752 "printString": {
2753 "sdfInputData": {
2754 "type": "object",
2755 "properties": {
2756 "content": { "type": "string" },
2757 "colour": { "type": "string" }
2758 }
2759 },
2760 "sdfOutputData": {
2761 "type": "object",
2762 "properties": {
2763 "success": { "type": "boolean" }
2764 }
2765 }
2766 }
2767 }
2768 }
2769 }
2771 Figure 47: SdfObject definition that contains an sdfAction definition
2773 container ExampleObject {
2774 helper:sdf-spec "sdfObject";
2775 action printString {
2776 input {
2777 leaf colour { type string; }
2778 leaf content { type string; }
2779 }
2780 output {
2781 leaf success { type boolean; }
2782 }
2783 }
2784 }
2786 Figure 48: YANG conversion of the sdfObject from the last figure
2788 4.10. SdfEvent Quality
2790 * SDF: Sections 2.2.4 and 5.4 (sdfEvent) of [I-D.ietf-asdf-sdf]
2792 * YANG: Section 7.16 (notification) of [RFC7950]
2794 The purpose of the sdfEvent class is to model signals that inform
2795 about occurrences or events in an sdfObject. To represent the
2796 emitted output data, sdfEvents can make use of the sdfOutputData
2797 quality which in turn uses the data qualities. An sdfEvent is
2798 converted to a notification node with one child node representing the
2799 sdfOutputData definition. The sdfOutputData definition is converted
2800 like an sdfProperty (see Section 4.8). Figure 49 and Figure 50
2801 contain the SDF and YANG representations of a warning notification
2802 which communicates the device and reason of the warning.
2804 "sdfEvent": {
2805 "warning": {
2806 "sdfOutputData": {
2807 "type": "object",
2808 "properties": {
2809 "warningDevice": { "type": "string" },
2810 "warningReason": { "type": "string" }
2811 }
2812 }
2813 }
2814 }
2816 Figure 49: SdfEvent definition
2818 notification warning {
2819 leaf warningDevice { type string; }
2820 leaf warningReason { type string; }
2821 }
2823 Figure 50: YANG conversion of the sdfEvent from the last figure
2825 5. Challenges
2827 Since conversion between SDF and YANG is not always trivial this
2828 section takes a look at the various challenges that arose in the
2829 process of finding an adequate mapping for each of the language's
2830 features to one another.
2832 5.1. Differences in Expressiveness of SDF and YANG
2834 SDF and YANG differ in their expressiveness in different areas.
2835 Compared to the other format, both are stronger in some areas and
2836 weaker in others.
2838 Areas in which YANG is more expressive are regular expressions,
2839 operations, some of the built-in types (bits and empty) and the
2840 retrospective augmentation of existing definitions. In YANG,
2841 multiple regular expressions to be matched can be defined and they
2842 can also be labeled as invert-match expressions. Both features are
2843 difficult to express in SDF as of now. Furthermore, YANG and SDF use
2844 slightly different regular expression languages. YANG uses a regular
2845 expression language as defined by W3C Schema while SDF adopts
2846 ECMAscript regular expressions. Operations in YANG can be defined on
2847 their own or with an affiliation to a YANG container. This
2848 affiliation is not always trivial to represent in SDF. The YANG
2849 built-in types bits and empty do not have equivalents in SDF. The
2850 semantics of those types can, however, easily be mapped to SDF. A
2851 YANG statement whose semantics cannot be fully mapped to SDF is the
2852 augment statement. The augmentation can be applied and then
2853 converted but cannot be represented as a retrospective addition to an
2854 SDF definition or model. Another Language feature of YANG that SDF
2855 does not offer is the option to place constraints on valid data via
2856 XPath expressions and the option to make sections of the model
2857 conditional with the feature statement. YANG, furthermore, puts no
2858 constraints on the value of its units statement, whereas SDF does
2859 only allow SenML unit names in the unit quality.
2861 SDF offers more possibilities to define default and constant values,
2862 the latter especially in conjunction with minimum and maximum values.
2863 YANG uses a single statement, the range statement, for constant,
2864 minimum and maximum values. Although there can be multiple values or
2865 ranges in one range statement that are interpreted as alternatives
2866 they all need to be disjoint. This imposes a strict limit on what
2867 can be expressed through the statement. An example for a conversion
2868 where this is a problem would be an sdfData definition with values
2869 for the minimum and maximum qualities but also a given constant value
2870 that fits inside the given minimum and maximum range, like the
2871 example in Figure 51. Such a definition could be converted to a YANG
2872 typedef with a range that states the minimum and maximum value as one
2873 range and the constant as an alternative, like the example conversion
2874 in Figure 52. This example does not validate in YANG because the
2875 range alternatives are not disjoint. This problem is solved through
2876 use of the union built-in type. Furthermore, labeling definitions as
2877 readable, observable and nullable, as possible in SDF, is foreign to
2878 YANG. SDF is also more expressive in the way it labels definitions
2879 that must obligatorily occur in model instances. Basically all
2880 definitions can be labeled as such through the sdfRequired and
2881 required qualities. In YANG, only leaf, choice, anydata and anyxml
2882 nodes can be marked with the mandatory statement directly.
2883 Container, list and leaf-list nodes can only be made mandatory
2884 indirectly and there is no general mechanism in YANG for all kinds of
2885 nodes.
2887 "sdfData": {
2888 "someValue": {
2889 "type": "integer",
2890 "minimum": 1,
2891 "maximum": 5,
2892 "const": 3
2893 }
2894 }
2896 Figure 51: SdfData definition with the qualities minimum, maximum
2897 and const
2899 typedef someValue {
2900 type int32;
2901 range "1 .. 5 | 3" // invalid in YANG
2902 }
2904 Figure 52: YANG conversion of the SDF definition in the last figure
2906 5.2. Round Trips
2908 One of the bigger issues in building the converter is the
2909 facilitation of round trips, i.e. converting a model from one format
2910 to the other and in a next step back to the original. This issue is
2911 tightly linked to the differences in expressiveness between the two
2912 formats which makes mapping between them non-injective and thus non-
2913 traceable without additional measures.
2915 To be able to track the origins of an SDF element after conversion
2916 from YANG, currently, a so-called \textit{conversion note} is added
2917 to the description of the element. The note specifies a statement
2918 and optionally an argument to the statement. An example for a note
2919 stating that the original argument to the type statement was bits is:
2920 !Conversion note: type bits!. This approach is not able to preserve
2921 all information from the YANG module without exceptions since sub-
2922 statements cannot be specified. It is, however, sufficient in the
2923 majority of cases.
2925 This issue was also discussed in one of the meetings of the ASDF
2926 working group. The possibility to introduce a new mechanism for
2927 round trips was suggested. Instead of overloading the SDF file with
2928 information that adds no functionality, the possibility to preserve
2929 information from the original model in a separate mapping file for
2930 each model was proposed. Mapping files for SDF models could contain
2931 selectors that assign additional information to the selected SDF
2932 element or element group. No decision has been made yet on the
2933 definite structure of such mapping files. Therefore, some
2934 requirements from the perspective of the SDF/YANG converter are
2935 listed here. Generally speaking, the information attached to an SDF
2936 element should have at least the same information content in the
2937 mapping file as in the previously mentioned conversion note, that is
2938 a statement and optionally an argument. To also cater to statements
2939 with further sub-statements, nesting should be possible, that is
2940 defining further statements as arguments should be possible. It is
2941 also necessary to be able to specify multiple statements to attach to
2942 a selected SDF elements. Another solution to round trips with
2943 mapping files would be to reference the associated YANG element of
2944 the selected SDF element. This way, all information would be
2945 preserved. Round trips would be easy because the original YANG
2946 definition would stay attached to the converted SDF definition.
2947 Opposing to that, if the SDF conversion of the YANG model is used to
2948 be converted further into other languages, the supplementary
2949 information of the original YANG element would still have to be
2950 extracted. This defeats the purpose of SDF to reduce the number of
2951 necessary mappings between languages. Thus, to attach statements
2952 with arguments to SDF definitions in mapping files is the better
2953 solution, in our opinion.
2955 To preserve the original SDF language element after conversion to
2956 YANG a new sdf-spec extension is defined in YANG. The extension
2957 states the original SDF quality and optionally an argument, similarly
2958 to the conversion note used to preserve information from YANG.
2960 The eventuality that round trips occur in model conversion makes
2961 building the converter significantly more complex because all
2962 features of the target format have to be accounted for. Features of
2963 the target format that would otherwise not be used for conversion
2964 must now be considered in the case of a round trip.
2966 5.3. Type References
2968 Both SDF and YANG offer the possibility to reference predefined
2969 types. SDF uses only a single quality for this purpose (sdfRef)
2970 whereas YANG has several statements that are all used in different
2971 referencing contexts (leafref, identityref, type, uses). The way the
2972 uses statement and the sdfRef quality are converted regularly leads
2973 to additional containers in YANG or additional properties (when using
2974 the compound-type) in SDF that make instances of the same model in
2975 SDF and YANG in-equivalent and complicate round trips. If no
2976 additional elements are inserted, information, for example the name
2977 of an element, is lost.
2979 Both the uses statement and the sdfRef quality embed the content of
2980 the referenced expression where they are located. Issues arise
2981 because YANG provides only groupings to be embedded via the uses
2982 statement. Groupings are the non-declaration-equivalent to
2983 containers. There is no non-declaration-equivalent to YANG lists,
2984 however. This means that list definitions in YANG need to be
2985 packaged in a grouping. If such a grouping with a single list inside
2986 is transcribed from YANG to SDF there will be an extra layer that
2987 looks redundant but otherwise does no harm. For the reasons stated
2988 above, an sdfData definition of type array with items of compound-
2989 type is converted to a list node inside a grouping in YANG. Problems
2990 arise when said sdfData definition is embedded via sdfRef because
2991 this cannot be converted directly to YANG. Such a scenario is
2992 illustrated in Figure 53 and Figure 54. The sdfData definition menu
2993 is converted to the YANG list menu inside a grouping menu.
2994 Referencing the menu via sdfRef in the sdfProperty definitions
2995 menu_english and menu_german is equivalent to copying the qualities
2996 of the menu there. In the YANG conversion the containers menu_enlish
2997 and menu_german both use the grouping menu. This means the menu list
2998 from said grouping is copied into the containers. The containers are
2999 necessary to preserve the names menu_english and menu_german and also
3000 because there cannot be two sibling uses nodes with the same target
3001 grouping (because no two sibling nodes must have the same name).
3003 Another issue with the mapping of type references is the
3004 accessibility of elements. Only typedefs and groupings that appear
3005 on the top-level of the tree can be reused globally. If these nodes
3006 appear within a sub-tree they are only available in the scope of the
3007 sub-tree. Since there is no such restriction in SDF, mapping sdfData
3008 definitions directly would cause accessibility problems in the
3009 resulting YANG module. Thus, mapped sdfData definitions have to be
3010 moved to the top-level. In YANG it is furthermore assumed that every
3011 type of node in the tree is addressable, while SDF focuses on
3012 sdfProperties, sdfActions and sdfEvents as addressable affordances.
3014 ; [...]
3015 "sdfData": {
3016 "dish": {
3017 "type": "object",
3018 "properties": {
3019 "name": { "type": "string" },
3020 "price": { "type": "number" }
3021 }
3022 },
3023 "menu": {
3024 "type": "array",
3025 "items": { "sdfRef": "#/sdfData/dish" }
3026 }
3027 },
3028 "sdfObject": {
3029 "restaurant" : {
3030 "sdfProperty": {
3031 "menu_english": { "sdfRef": "#/sdfData/menu" },
3032 "menu_german": { "sdfRef": "#/sdfData/menu" },
3033 "dish_of_the_day": { "sdfRef": "#/sdfData/dish" }
3034 }
3035 }
3036 }
3037 }
3039 Figure 53: SDF model with type definitions of types object and array
3041 module restaurant {
3042 // [...]
3043 grouping dish {
3044 leaf name { type string; }
3045 leaf price {
3046 type decimal64 { fraction-digits 6; }
3047 }
3048 }
3049 grouping menu {
3050 list menu {
3051 key "name";
3052 uses dish;
3053 }
3054 }
3055 container restaurant {
3056 container dish_of_the_day { uses dish; }
3057 container menu_english { uses menu; }
3058 container menu_german { uses menu; }
3059 }
3060 }
3061 Figure 54: YANG conversion of the SDF model in the last figure
3063 6. Implementation Considerations
3065 An implementation of an initial converter between SDF and YANG can be
3066 found at [SDF-YANG-CONVERTER]; the source code can be found at
3067 [SDF-YANG-CONVERTER-IMPL].
3069 7. IANA Considerations
3071 This document makes no requests of IANA.
3073 8. Security considerations
3075 The security considerations of [RFC7950] and [I-D.ietf-asdf-sdf]
3076 apply.
3078 9. References
3080 9.1. Normative References
3082 [I-D.ietf-asdf-sdf]
3083 Koster, M. and C. Bormann, "Semantic Definition Format
3084 (SDF) for Data and Interactions of Things", Work in
3085 Progress, Internet-Draft, draft-ietf-asdf-sdf-08, 25
3086 October 2021, .
3089 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
3090 RFC 7950, DOI 10.17487/RFC7950, August 2016,
3091 .
3093 9.2. Informative References
3095 [LIBYANG] Vasko, M., Sedlák, D., and more contributors, "libyang",
3096 .
3098 [SDF-YANG-CONVERTER]
3099 Kiesewalter, J., "SDF YANG converter playground", n.d.,
3100 .
3102 [SDF-YANG-CONVERTER-IMPL]
3103 Kiesewalter, J., "SDF YANG converter", n.d.,
3104 .
3106 Acknowledgements
3108 TBD.
3110 Authors' Addresses
3112 Jana Kiesewalter
3113 Universität Bremen
3115 Email: jankie@uni-bremen.de
3117 Carsten Bormann (editor)
3118 Universität Bremen TZI
3119 Postfach 330440
3120 D-28359 Bremen
3121 Germany
3123 Phone: +49-421-218-63921
3124 Email: cabo@tzi.org