idnits 2.17.1 draft-petrov-t2trg-youpi-00.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 (July 23, 2019) is 1732 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 July 23, 2019 5 Expires: January 24, 2020 7 YANG Object Universal Parsing Interface 8 draft-petrov-t2trg-youpi-00 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 January 24, 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 . . . . . . . . . . . . . . . . . . . . . . . . 4 57 2.2.1. Bit positions . . . . . . . . . . . . . . . . . . . . 4 58 2.2.2. Cursor . . . . . . . . . . . . . . . . . . . . . . . 5 59 2.2.3. Absolute position . . . . . . . . . . . . . . . . . . 5 60 2.2.4. Relative position . . . . . . . . . . . . . . . . . . 5 61 2.3. FieldIndex . . . . . . . . . . . . . . . . . . . . . . . 5 62 2.4. Condition . . . . . . . . . . . . . . . . . . . . . . . . 6 63 2.5. Multiplier . . . . . . . . . . . . . . . . . . . . . . . 6 64 2.6. Offset . . . . . . . . . . . . . . . . . . . . . . . . . 6 65 2.7. Units-subject . . . . . . . . . . . . . . . . . . . . . . 6 66 2.8. Lists . . . . . . . . . . . . . . . . . . . . . . . . . . 6 67 3. Security Considerations . . . . . . . . . . . . . . . . . . . 7 68 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 69 5. Normative References . . . . . . . . . . . . . . . . . . . . 7 70 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 72 1. Introduction 74 A huge number of very constraint IoT devices are expected to be 75 coming to the market. They are very constraint in terms of the MTU 76 (sometimes as small as 10b per message). As they are expected to be 77 running for many years without the need for external energy, energy 78 efficiency which is directly linked to the size of the payloads that 79 need to be sent, is also very important. For those devices JSON and 80 even CBOR formats might be too wasteful in terms of payload size. 81 The reality of the ecosystem is that currently a great number of 82 applications use proprietary binary formats for exchanging 83 information. A significant problem exists if those systems are to be 84 interacting in a purely M2M fashion. While there are a number of 85 possibilities to resolve those issues, due to the constraints it is 86 mandatory to have a way to extract and encode information from/to the 87 binary payload and be able to annotate it with semantic metadata. 89 While binary formats can be rather complicated to parse and sometimes 90 even context dependent (some entity needs to keep context in order to 91 parse a message), for most cases a simple description format could be 92 sufficient. 94 A good solution should not be bounded to the output format. It 95 should be a data modeling language like YANG [RFC7950] that simply 96 describes the structure of the obtained data and that allows 97 different serialization formats afterwards. 99 1.1. Terminology 101 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 102 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 103 "OPTIONAL" in this document are to be interpreted as described in BCP 104 14 [RFC2119] [RFC8174] when, and only when, they appear in all 105 capitals, as shown here. 107 2. YOUPI 109 YOUPI provides a number of yang extentions as defined in Section 2.1. 110 Thanks to that additional information in the YANG definitions, it is 111 possible to decode binary data and then transform it to a different 112 easier to parse format like JSON, XML or CBOR. Additionally it 113 defines extensions that allow meta information to be added so that 114 JSON-LD is generated. This draft is not describing how the data is 115 formatted as JSON or other format. For information how this could be 116 done, please refer to RESTCONF, NETCONF or CORECONF. 118 The opposite process is also possible - generating binary packets 119 from parsed data that comes from JSON or other format. 121 2.1. YANG extentions 123 The definitions of the YANG extensions. 125 file "petrov-youpi-file@2019-07-22.yang" 126 module youpi { 127 namespace "http://ackl.io/youpi"; 129 prefix "youpi"; 131 organization 132 "Acklio"; 134 contact 135 "Ivaylo Petrov 136 "; 138 description 139 "This module defines the extentions used by youpi."; 141 revision 2019-07-22 { 142 description "Initial revision."; 143 } 145 /** 146 * 147 * Extension for Binary data to CBOR mapping. 148 * 149 **/ 150 extension position { 151 argument object; 152 } 154 extension fieldIndex { 155 argument object; 156 } 158 extension condition { 159 argument object; 160 } 162 extension multiplier { 163 argument object; 164 } 166 extension offset { 167 argument object; 168 } 170 extension units-subject { 171 argument object; 172 } 174 extension js { 175 argument object; 176 } 177 } 179 2.2. Position 181 Information about which bits need to be used in order to find the 182 value of a field. 184 2.2.1. Bit positions 186 If the position is not present or is empty, the value contains 0 bits 187 and has a default value of 0 (or equivalent for the given type). 188 Could be useful if a field needs to be the result of arithmetic 189 operations from different fields. 191 It is possible to have a single bit read by giving only its value in 192 the position extension. 194 If continuous bits need to be used to obtain the value of a given 195 field, this can be achieved using the ".." syntax. For example 196 "0..3" means bits 0, 1, 2 and 3. 198 If non-continuous bits need to be used, one can use the concatenation 199 of bit ranges using the "|" operator. For example "0..1 | 3". 201 2.2.2. Cursor 203 Starts at 0 and changes with each read to the last bit index that was 204 read. Used in Section 2.2.4 to determine where the read will start 205 from. Section 2.2.3 is not affected by it, but changes its value. 207 2.2.3. Absolute position 209 The default one if no keyword is used. Alternatively "absolute" 210 keyword can be provided to explicitly request such position. 212 Example: 214 leaf temp { 215 type uint8; 216 default -19; 217 description "The temperature"; 218 youpi:position "0..6"; 219 } 221 2.2.4. Relative position 223 Example: 225 leaf temp { 226 type uint8; 227 default -19; 228 description "The temperature"; 229 youpi:position "1..7"; 230 } 232 This means that the value starts 1 bit after the current cursor and 233 will read up to 7 bits after the current cursor position, including 234 that 7th bit. 236 2.3. FieldIndex 238 Can be used to change the order in which fields are processed. By 239 default the order in which fields appear in the document is the order 240 in which they are processed. 242 2.4. Condition 244 Inside a choice statement, the condition extension gives information 245 based on what value the choice will be decided. 247 For example considering that there is a value "mode" with the value 248 of btn inside the model 250 choice data { 251 case _btn { 252 container button-data { 253 ... 254 } 255 } 256 case _temp { 257 container temperature-data { 258 ... 259 } 260 } 261 youpi:condition "mode"; 262 } 264 Then the button-data container will be used to parse the data. 266 2.5. Multiplier 268 A value or another field by which a given field needs to be 269 multiplied before the final value is obtained. The operations are 270 executed in the order of appearance (this includes "offset" extension 271 defined in Section 2.6). 273 2.6. Offset 275 A value or another field to which a given field needs to be added 276 before the final value is obtained. The operations are executed in 277 the order of appearance (this includes "offset" extension defined in 278 Section 2.6). 280 2.7. Units-subject 282 Meta information used to compute JSON-LD. 284 2.8. Lists 286 TBD 288 3. Security Considerations 290 The YANG file should be valid. 292 Segmentation faults might result from invalid data being provided 293 with a given YANG model. 295 Resource exhaustion can be looked for. 297 4. IANA Considerations 299 This document registers a YANG model. 301 5. Normative References 303 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 304 Requirement Levels", BCP 14, RFC 2119, 305 DOI 10.17487/RFC2119, March 1997, 306 . 308 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 309 RFC 7950, DOI 10.17487/RFC7950, August 2016, 310 . 312 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 313 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 314 May 2017, . 316 Author's Address 318 Ivaylo Petrov (editor) 319 Acklio 320 1137A avenue des Champs Blancs 321 Cesson-Sevigne, Bretagne 35510 322 France 324 Email: ivaylo@ackl.io