idnits 2.17.1 draft-petrov-t2trg-youpi-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (November 04, 2019) is 1634 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group I. Petrov, Ed. 3 Internet-Draft Acklio 4 Intended status: Informational November 04, 2019 5 Expires: May 7, 2020 7 YANG Object Universal Parsing Interface 8 draft-petrov-t2trg-youpi-01 10 Abstract 12 YANG Object Universal Parsing Interface (YOUPI) specification 13 describes generic way to encode and decode binary data based on a 14 YANG model for use of constrainted devices. YOUPI is a generic 15 mechanism designed for great flexibility, so that it can be adapted 16 for any of the constainted devices. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on May 7, 2020. 35 Copyright Notice 37 Copyright (c) 2019 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (https://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 54 2. YOUPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2.1. YANG extentions . . . . . . . . . . . . . . . . . . . . . 3 56 2.2. Position . . . . . . . . . . . . . . . . . . . . . . . . 5 57 2.2.1. Bit positions . . . . . . . . . . . . . . . . . . . . 5 58 2.2.2. Cursor . . . . . . . . . . . . . . . . . . . . . . . 5 59 2.2.3. Absolute position . . . . . . . . . . . . . . . . . . 5 60 2.2.4. Relative position . . . . . . . . . . . . . . . . . . 5 61 2.3. FieldIndex . . . . . . . . . . . . . . . . . . . . . . . 6 62 2.4. Multiplier . . . . . . . . . . . . . . . . . . . . . . . 6 63 2.5. Offset . . . . . . . . . . . . . . . . . . . . . . . . . 6 64 2.6. Units-subject . . . . . . . . . . . . . . . . . . . . . . 6 65 2.7. Data definitions . . . . . . . . . . . . . . . . . . . . 6 66 2.7.1. Supported built-in type . . . . . . . . . . . . . . . 6 67 2.7.2. Leafs . . . . . . . . . . . . . . . . . . . . . . . . 7 68 2.7.3. Type min/max values . . . . . . . . . . . . . . . . . 7 69 2.7.4. Type fraction digits . . . . . . . . . . . . . . . . 7 70 2.7.5. Containers . . . . . . . . . . . . . . . . . . . . . 8 71 2.7.6. Condition . . . . . . . . . . . . . . . . . . . . . . 8 72 2.7.7. Lists . . . . . . . . . . . . . . . . . . . . . . . . 9 73 2.7.8. Enumerations as mappings . . . . . . . . . . . . . . 10 74 2.7.9. Groupings . . . . . . . . . . . . . . . . . . . . . . 10 75 2.7.10. Typedefs . . . . . . . . . . . . . . . . . . . . . . 10 76 3. Security Considerations . . . . . . . . . . . . . . . . . . . 10 77 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 78 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 11 79 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 11 80 7. Normative References . . . . . . . . . . . . . . . . . . . . 11 81 Appendix A. Complete examples . . . . . . . . . . . . . . . . . 11 82 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 84 1. Introduction 86 A huge number of very constraint IoT devices are expected to be 87 coming to the market. They are very constraint in terms of the MTU 88 (sometimes as small as 10b per message). As they are expected to be 89 running for many years without the need for external energy, energy 90 efficiency which is directly linked to the size of the payloads that 91 need to be sent, is also very important. For those devices JSON and 92 even CBOR formats might be too wasteful in terms of payload size. 93 The reality of the ecosystem is that currently a great number of 94 applications use proprietary binary formats for exchanging 95 information. A significant problem exists if those systems are to be 96 interacting in a purely M2M fashion. While there are a number of 97 possibilities to resolve those issues, due to the constraints it is 98 mandatory to have a way to extract and encode information from/to the 99 binary payload and be able to annotate it with semantic metadata. 101 While binary formats can be rather complicated to parse and sometimes 102 even context dependent (some entity needs to keep context in order to 103 parse a message), for most cases a simple description format could be 104 sufficient. 106 A good solution should not be bounded to the output format. It 107 should be a data modeling language like YANG [RFC7950] that simply 108 describes the structure of the obtained data and that allows 109 different serialization formats afterwards. 111 1.1. Terminology 113 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 114 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 115 "OPTIONAL" in this document are to be interpreted as described in BCP 116 14 [RFC2119] [RFC8174] when, and only when, they appear in all 117 capitals, as shown here. 119 2. YOUPI 121 YOUPI provides a number of yang extentions as defined in Section 2.1. 122 Thanks to that additional information in the YANG definitions, it is 123 possible to decode binary data and then transform it to a different 124 easier to parse format like JSON, XML or CBOR. Additionally it 125 defines extensions that allow meta information to be added so that 126 JSON-LD is generated. This draft is not describing how the data is 127 formatted as JSON or other format. For information how this could be 128 done, please refer to RESTCONF, NETCONF or CORECONF. 130 The opposite process is also possible - generating binary packets 131 from parsed data that comes from JSON or other format. 133 2.1. YANG extentions 135 The definitions of the YANG extensions. 137 file "petrov-youpi-file@2019-07-22.yang" 138 module youpi { 139 namespace "http://ackl.io/youpi"; 141 prefix "youpi"; 143 organization 144 "Acklio"; 146 contact 147 "Ivaylo Petrov 148 "; 150 description 151 "This module defines the extentions used by youpi."; 153 revision 2019-07-22 { 154 description "Initial revision."; 155 } 157 /** 158 * 159 * Extension for Binary data to CBOR mapping. 160 * 161 **/ 162 extension position { 163 argument object; 164 } 166 extension fieldIndex { 167 argument object; 168 } 170 extension condition { 171 argument object; 172 } 174 extension multiplier { 175 argument object; 176 } 178 extension offset { 179 argument object; 180 } 182 extension units-subject { 183 argument object; 184 } 186 extension js { 187 argument object; 188 } 189 } 191 2.2. Position 193 Information about which bits need to be used in order to find the 194 value of a field. 196 2.2.1. Bit positions 198 If the position is not present or is empty, the value contains 0 bits 199 and has a default value of 0 (or equivalent for the given type). 200 Could be useful if a field needs to be the result of arithmetic 201 operations from different fields. 203 It is possible to have a single bit read by giving only its value in 204 the position extension. 206 If continuous bits need to be used to obtain the value of a given 207 field, this can be achieved using the ".." syntax. For example 208 "0..3" means bits 0, 1, 2 and 3. 210 If non-continuous bits need to be used, one can use the concatenation 211 of bit ranges using the "|" operator. For example "0..1 | 3". 213 2.2.2. Cursor 215 Starts at 0 and changes with each read to the last bit index that was 216 read. Used in Section 2.2.4 to determine where the read will start 217 from. Section 2.2.3 is not affected by it, but changes its value. 219 2.2.3. Absolute position 221 The default one if no keyword is used. Alternatively "absolute" 222 keyword can be provided to explicitly request such position. 224 Example: 226 leaf temp { 227 type uint8; 228 default -19; 229 description "The temperature"; 230 youpi:position "0..6"; 231 } 233 2.2.4. Relative position 235 Example: 237 leaf temp { 238 type uint8; 239 default -19; 240 description "The temperature"; 241 youpi:position "relative 1..7"; 242 } 244 This means that the value starts 1 bit after the current cursor and 245 will read up to 7 bits after the current cursor position, including 246 that 7th bit. 248 2.3. FieldIndex 250 Can be used to change the order in which fields are processed. By 251 default the order in which fields appear in the document is the order 252 in which they are processed. 254 2.4. Multiplier 256 A value or another field by which a given field needs to be 257 multiplied before the final value is obtained. The operations are 258 executed in the order of appearance (this includes "offset" extension 259 defined in Section 2.5). 261 2.5. Offset 263 A value or another field to which a given field needs to be added 264 before the final value is obtained. The operations are executed in 265 the order of appearance (this includes "offset" extension defined in 266 Section 2.5). 268 2.6. Units-subject 270 Meta information used to compute JSON-LD. 272 2.7. Data definitions 274 2.7.1. Supported built-in type 276 o binary 278 o enumeration 280 o int8 282 o int16 284 o int32 285 o int64 287 o string 289 o uint8 291 o uint16 293 o uint32 295 o uint64 297 2.7.2. Leafs 299 Simple fields like integers and strings are represented by leafs in 300 YOUPI. 302 2.7.3. Type min/max values 304 "range" attribute can be used for giving a "min"/"max" acceptable 305 value for a type. If the value is outside of the defined range, it 306 is silently excluded from the final result. 308 Example: 310 typedef temp { 311 type int8 { 312 range "-20 .. 107"; 313 } 314 } 316 2.7.4. Type fraction digits 318 It is possible to specify how many fraction digits are expected for a 319 value to have. 321 Example: 323 leaf temp { 324 type decimal64 { 325 fraction-digits 2; 326 } 327 } 329 2.7.5. Containers 331 Complex fields like objects are represented by containers in YOUPI. 333 2.7.6. Condition 335 2.7.6.1. Choice 337 Inside a choice statement, the condition extension gives information 338 based on what value the choice will be decided. 340 For example considering that there is a value "mode" with the value 341 of btn inside the model 343 leaf mode { 344 ... 345 } 346 choice data { 347 case _btn { 348 container button-data { 349 ... 350 } 351 } 352 case _temp { 353 container temperature-data { 354 ... 355 } 356 } 357 youpi:condition "../mode"; 358 } 360 Then the button-data container will be used to parse the data. 362 2.7.6.2. When 364 With when statement it is possible to link the presence of some piece 365 of data to a value of another field. For example it is possible to 366 have button-data or temperature-data depending of the value of the 367 mode field. 369 container button-data { 370 when "../mode[.=1]" 371 ... 372 } 373 container temperature-data { 374 when "../mode[.=2]" 375 ... 376 } 378 2.7.7. Lists 380 List statements are supported and they generate an array of a given 381 composite type. 383 2.7.7.1. With explicit length 385 A list of minimum and maximum temperatures can be defined as: 387 leaf temperature-len { 388 type int32; 389 } 391 list temperatures { 392 youpi:length "../temperatures-len"; 393 leaf min-value { 394 type int32; 395 } 396 leaf max-value { 397 type int32; 398 } 399 } 401 2.7.7.2. Until the end of input 403 The list as defined in Section 2.7.7.1 can omit the length extension 404 statement if all the remaining bytes in the payload are part of the 405 list. 407 2.7.7.3. Until a specific value 409 The list as defined in Section 2.7.7.1 can also omit the length if it 410 has a defined key and if it only has one leaf or container in the 411 list apart from the key and it is a subject to when statement that 412 defines a stop value for the key. 414 list temperatures { 415 key option-id; 416 leaf option-id { 417 type int32; 418 } 419 container value { 420 when "../option-id[.!=0xffffffff]"; 421 ... 422 } 423 } 425 2.7.8. Enumerations as mappings 427 Enumerations can be used inside a typedef in order to restrict a 428 field only to a set of acceptable values or in order to accomplish 429 mapping between some values and other values (for example 0 stands 430 for "temperature", 1 stands for "humidity", etc). 432 Example: 434 typedef mode-type { 435 type enumeration { 436 enum temp { 437 value 0; 438 } 439 enum humidity { 440 value 1; 441 } 442 enum light { 443 value 2; 444 } 445 ... 446 } 447 ... 448 } 450 2.7.9. Groupings 452 Groupings can be used for better reuse of definitions. They don't 453 affect the generated output. 455 2.7.10. Typedefs 457 Typedefs can be used to provide extra information about the type of a 458 field, including semantic information about it. 460 3. Security Considerations 462 The YANG file should be valid. 464 Segmentation faults might result from invalid data being provided 465 with a given YANG model. 467 Resource exhaustion can be looked for. 469 4. IANA Considerations 471 This document registers a YANG model. 473 Acknowledgements 475 Contributors 477 7. Normative References 479 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 480 Requirement Levels", BCP 14, RFC 2119, 481 DOI 10.17487/RFC2119, March 1997, 482 . 484 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 485 RFC 7950, DOI 10.17487/RFC7950, August 2016, 486 . 488 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 489 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 490 May 2017, . 492 Appendix A. Complete examples 494 Author's Address 496 Ivaylo Petrov (editor) 497 Acklio 498 1137A avenue des Champs Blancs 499 Cesson-Sevigne, Bretagne 35510 500 France 502 Email: ivaylo@ackl.io