idnits 2.17.1 draft-ietf-core-senml-etch-07.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 : ---------------------------------------------------------------------------- == There are 2 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 9, 2020) is 1502 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Keranen 3 Internet-Draft Ericsson 4 Intended status: Standards Track M. Mohajer 5 Expires: September 10, 2020 March 9, 2020 7 FETCH & PATCH with Sensor Measurement Lists (SenML) 8 draft-ietf-core-senml-etch-07 10 Abstract 12 The Sensor Measurement Lists (SenML) media type and data model can be 13 used to send collections of resources, such as batches of sensor data 14 or configuration parameters. The CoAP FETCH, PATCH, and iPATCH 15 methods enable accessing and updating parts of a resource or multiple 16 resources with one request. This document defines new media types 17 for the CoAP FETCH, PATCH, and iPATCH methods for resources 18 represented with the SenML data model. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on September 10, 2020. 37 Copyright Notice 39 Copyright (c) 2020 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 3. Using FETCH and (i)PATCH with SenML . . . . . . . . . . . . . 3 57 3.1. SenML FETCH . . . . . . . . . . . . . . . . . . . . . . . 4 58 3.2. SenML (i)PATCH . . . . . . . . . . . . . . . . . . . . . 5 59 4. Fragment Identification . . . . . . . . . . . . . . . . . . . 7 60 5. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 7 61 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7 62 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 63 7.1. CoAP Content-Format Registration . . . . . . . . . . . . 8 64 7.2. senml-etch+json Media Type . . . . . . . . . . . . . . . 8 65 7.3. senml-etch+cbor Media Type . . . . . . . . . . . . . . . 9 66 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 67 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 68 9.1. Normative References . . . . . . . . . . . . . . . . . . 10 69 9.2. Informative References . . . . . . . . . . . . . . . . . 11 70 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 72 1. Introduction 74 The Sensor Measurement Lists (SenML) media type [RFC8428] and data 75 model can be used to transmit collections of resources, such as 76 batches of sensor data or configuration parameters. 78 An example of a SenML collection is shown below: 80 [ 81 {"bn":"2001:db8::2/3311/0/", "n":"5850", "vb":true}, 82 {"n":"5851", "v":42}, 83 {"n":"5750", "vs":"Ceiling light"} 84 ] 86 Here three resources "3311/0/5850", "3311/0/5851", and "3311/0/5750", 87 of an IPSO dimmable light smart object [IPSO] are represented using a 88 single SenML Pack with three SenML Records. All resources share the 89 same base name "2001:db8::2/3311/0/", hence full names for resources 90 are "2001:db8::2/3311/0/5850", etc. 92 The CoAP [RFC7252] FETCH, PATCH, and iPATCH methods [RFC8132] enable 93 accessing and updating parts of a resource or multiple resources with 94 one request. 96 This document defines two new media types, one using the JavaScript 97 Object Notation (JSON) [RFC8259] and one using the Concise Binary 98 Object Representation (CBOR) [RFC7049], which can be used with the 99 CoAP FETCH, PATCH, and iPATCH methods for resources represented with 100 the SenML data model (i.e., for both SenML and Sensor Streaming 101 Measurement Lists (SenSML) data). The rest of the document uses term 102 "(i)PATCH" when referring to both methods as the semantics of the new 103 media types are the same for the CoAP PATCH and iPATCH methods. 105 2. Terminology 107 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 108 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 109 "OPTIONAL" in this document are to be interpreted as described in BCP 110 14 [RFC2119] [RFC8174] when, and only when, they appear in all 111 capitals, as shown here. 113 Readers should also be familiar with the terms and concepts discussed 114 in [RFC8132] and [RFC8428]. The following additional terms are used 115 in this document: 117 Fetch Record: One set of parameters that is used to match SenML 118 Record(s). 120 Fetch Pack: One or more Fetch Records in an array structure. 122 Patch Record: One set of parameters similar to Fetch Record but also 123 containing instructions on how to change existing SenML Pack(s). 125 Patch Pack: One or more Patch Records in an array structure. 127 Target Record: A Record in a SenML Pack that matches the selection 128 criteria of a Fetch or Patch Record and hence is a target for a 129 Fetch or Patch operation. 131 Target Pack: A SenML Pack that is a target for a Fetch or Patch 132 operation. 134 (i)PATCH: A term that refers to both CoAP "PATCH" and "iPATCH" 135 methods when there is no difference in this specification in which 136 one is used. 138 3. Using FETCH and (i)PATCH with SenML 140 The FETCH/(i)PATCH media types for SenML are modeled as extensions to 141 the SenML media type to enable re-use of existing SenML parsers and 142 generators, in particular on constrained devices. Unless mentioned 143 otherwise, FETCH and PATCH Packs are constructed with the same rules 144 and constraints as SenML Packs. 146 The key differences to the SenML media type are allowing the use of a 147 "null" value for removing records with the (i)PATCH method and lack 148 of value fields in Fetch Records. Also the Fetch and Patch Records 149 do not have default time or base version when the fields are omitted. 151 3.1. SenML FETCH 153 The FETCH method can be used to select and return a subset of 154 records, in sequence, of one or more SenML Packs. The SenML Records 155 are selected by giving a set of names that, when resolved, match 156 resolved names in a Target SenML Pack. The names for a Fetch Pack 157 are given using the SenML "name" and/or "base name" fields. The 158 names are resolved by concatenating the base name with the name field 159 as defined in [RFC8428]. 161 A Fetch Pack MUST contain at least one Fetch Record. A Fetch Record 162 MUST contain a name and/or a base name field. 164 For example, to select the IPSO resources "5850" and "5851" from the 165 example in Section 1, the following Fetch Pack can be used: 167 [ 168 {"bn":"2001:db8::2/3311/0/", "n":"5850"}, 169 {"n":"5851"} 170 ] 172 The result to a FETCH request with the example above would be: 174 [ 175 {"bn":"2001:db8::2/3311/0/", "n":"5850", "vb":true}, 176 {"n":"5851", "v":42}, 177 ] 179 The SenML time and unit fields can be used in a Fetch Record to 180 further narrow the selection of matched SenML Records. When no time 181 or unit is given in a Fetch Record, all SenML Records with the given 182 name are matched (i.e., unlike with SenML Records, lack of time field 183 in a Fetch Record does not imply time value zero). When time is 184 given in the Fetch Record, only the SenML Records (if any) with equal 185 resolved time value and name are matched. Similarly, when unit is 186 given, only the SenML Records with equal resolved unit and name are 187 matched. If both time and unit are given in the Fetch Record, both 188 MUST to match for the SenML Record to match. Each Target Record MUST 189 be included in the response at most once, even if multiple Fetch 190 Records match with the same Target Record. 192 For example, if the IPSO resource "5850" would have multiple sensor 193 readings (SenML Records) with different time values, the following 194 Fetch Pack can be used to retrieve the Record with time 195 "1.276020091e+09": 197 [ 198 {"bn":"2001:db8::2/3311/0/", "n":"5850", "t":1.276020091e+09} 199 ] 201 The resolved form of records (Section 4.6 of [RFC8428]) is used when 202 comparing the names, times, and units of the Target and Fetch Records 203 to accommodate for differences in use of the base values. In 204 resolved form the SenML name in the example above becomes 205 "2001:db8::2/3311/0/5850". Since there is no base time in the Pack, 206 the time in resolved form is equal to the time in the example. 208 If no SenML Records match, empty SenML Pack (i.e., array with no 209 elements) is returned as a response. 211 Fetch Records MUST NOT contain other fields than name, base name, 212 time, base time, unit, and base unit. Implementations MUST reject 213 and generate an error for a Fetch Pack with other fields. [RFC8132] 214 Section 2.2 provides guidance for FETCH request error handling, e.g., 215 using the 4.22 (Unprocessable Entity) CoAP error response code. 217 3.2. SenML (i)PATCH 219 The (i)PATCH method can be used to change the fields of SenML 220 Records, to add new Records, and to remove existing Records. The 221 names, times, and units of the Patch Records are given and matched in 222 same way as for the Fetch Records, except each Patch Record MUST 223 match at most one Target Record. A Patch Record matching more than 224 one Target Record is considered invalid (patching multiple Target 225 Records with one Patch Record would result in multiple copies of the 226 same record). Patch Packs can also include new values and other 227 SenML fields for the Records. Application of Patch Packs is 228 idempotent; hence PATCH and iPATCH methods for SenML Packs are 229 equivalent. 231 When the name in a Patch Record matches with the name in an existing 232 Record, the resolved time values and units (if any) are compared. If 233 the time values and units either do not exist in both Records or are 234 equal, the Target Record is replaced with the contents of the Patch 235 Record. All Patch Records MUST contain at least a SenML Value or Sum 236 field. 238 If a Patch Record contains a name, or combination of a time value, 239 unit, and a name, that do not exist in any existing Record in the 240 Pack, the given Record, with all the fields it contains, is added to 241 the Pack. 243 If a Patch Record has a value ("v") field with value null, it MUST 244 NOT be added but the matched Record (if any) is removed from the 245 Target Pack. 247 The Patch Records MUST be applied in the same sequence they are in 248 the Patch Pack. If multiple Patch Packs are being processed at the 249 same time, the result MUST be equivalent to applying them in one 250 sequence. 252 Implementations MUST reject and generate an error for Patch Packs 253 with invalid Records. If a Patch Pack is rejected, the state of the 254 Target Pack is not changed, i.e., either all or none of the Patch 255 Records are applied. [RFC8132] Section 3.4 provides guidance for 256 error handling with PATCH and iPATCH requests, e.g., using the 4.22 257 (Unprocessable Entity) and 4.09 (Conflict) CoAP error response codes. 259 For example, the following document could be given as an (i)PATCH 260 payload to change/set values of two SenML Records for the example in 261 Section 1: 263 [ 264 {"bn":"2001:db8::2/3311/0/", "n":"5850", "vb":false}, 265 {"n":"5851", "v":10} 266 ] 268 If the request is successful, the resulting representation of the 269 example SenML Pack would be as follows: 271 [ 272 {"bn":"2001:db8::2/3311/0/", "n":"5850", "vb":false}, 273 {"n":"5851", "v":10}, 274 {"n":"5750", "vs":"Ceiling light"} 275 ] 277 As another example, the following document could be given as an 278 (i)PATCH payload to remove the two SenML Records: 280 [ 281 {"bn":"2001:db8::2/3311/0/", "n":"5850", "v":null}, 282 {"n":"5851", "v":null} 283 ] 285 4. Fragment Identification 287 Fragment identification for Records of Fetch and Patch Packs uses the 288 same mechanism as SenML JSON/CBOR fragment identification (see 289 Section 9 of [RFC8428]), i.e., "rec" scheme followed by a comma- 290 separated list of Record positions or range(s) of Records. For 291 example, to select the 3rd and 5th Record of a Fetch or Patch Pack, a 292 fragment identifier "rec=3,5" can be used in the URI of the Fetch or 293 Patch Pack resource. 295 5. Extensibility 297 The SenML mandatory to understand fields extensibility mechanism (see 298 section 4.4 in [RFC8428]) does not apply to Patch Packs, i.e., 299 unknown fields MUST NOT generate an error but such fields are treated 300 like any other field (e.g., added to Patch target records where 301 applicable). 303 This specification allows only a small subset of SenML fields in 304 Fetch Records but future specifications may enable new fields for 305 Fetch Records and possibly also new fields for selecting targets for 306 Patch Records. 308 6. Security Considerations 310 The security and privacy considerations of SenML apply also with the 311 FETCH and (i)PATCH methods. CoAP's security mechanisms are used to 312 provide security for the FETCH and (i)PATCH methods. 314 In FETCH and (i)PATCH requests, the client can pass arbitrary names 315 to the target resource for manipulation. The resource implementer 316 must take care to only allow access to names that are actually part 317 of (or accessible through) the target resource. In particular the 318 receiver needs to ensure that any input does not lead to uncontrolled 319 special interpretation by the system. 321 If the client is not allowed to do a GET or PUT on the full target 322 resource (and thus all the names accessible through it), access 323 control rules must be evaluated for each record in the pack. 325 7. IANA Considerations 327 This document registers two new media types and CoAP Content-Format 328 IDs for both media types. 330 Note to RFC Editor: Please replace all occurrences of "RFC-AAAA" with 331 the RFC number of this document. 333 7.1. CoAP Content-Format Registration 335 IANA is requested to assign CoAP Content-Format IDs for the SenML 336 PATCH and FETCH media types in the "CoAP Content-Formats" sub- 337 registry, within the "CoRE Parameters" registry [RFC7252]. The 338 assigned IDs are shown in Table 1. 340 +-----------------------------+----------+---------+ 341 | Media type | Encoding | ID | 342 +-----------------------------+----------+---------+ 343 | application/senml-etch+json | - | TBD-320 | 344 | | | | 345 | application/senml-etch+cbor | - | TBD-322 | 346 +-----------------------------+----------+---------+ 348 Table 1: CoAP Content-Format IDs 350 7.2. senml-etch+json Media Type 352 Type name: application 354 Subtype name: senml-etch+json 356 Required parameters: N/A 358 Optional parameters: N/A 360 Encoding considerations: binary 362 Security considerations: See Section 6 of RFC-AAAA. 364 Interoperability considerations: N/A 366 Published specification: RFC-AAAA 368 Applications that use this media type: Applications that use the 369 SenML media type for resource representation. 371 Fragment identifier considerations: Fragment identification for 372 application/senml-etch+json is supported by using fragment 373 identifiers as specified by RFC AAAA. 375 Additional information: 377 Deprecated alias names for this type: N/A 379 Magic number(s): N/A 380 File extension(s): senml-etchj 382 Windows Clipboard Name: "SenML FETCH/PATCH format" 384 Macintosh file type code(s): N/A 386 Macintosh Universal Type Identifier code: org.ietf.senml-etch-json 387 conforms to public.text 389 Person & email address to contact for further information: Ari 390 Keranen ari.keranen@ericsson.com 392 Intended usage: COMMON 394 Restrictions on usage: N/A 396 Author: Ari Keranen ari.keranen@ericsson.com 398 Change controller: IESG 400 7.3. senml-etch+cbor Media Type 402 Type name: application 404 Subtype name: senml-etch+cbor 406 Required parameters: N/A 408 Optional parameters: N/A 410 Encoding considerations: binary 412 Security considerations: See Section 6 of RFC-AAAA. 414 Interoperability considerations: N/A 416 Published specification: RFC-AAAA 418 Applications that use this media type: Applications that use the 419 SenML media type for resource representation. 421 Fragment identifier considerations: Fragment identification for 422 application/senml-etch+cbor is supported by using fragment 423 identifiers as specified by RFC AAAA. 425 Additional information: 427 Deprecated alias names for this type: N/A 428 Magic number(s): N/A 430 File extension(s): senml-etchc 432 Macintosh file type code(s): N/A 434 Macintosh Universal Type Identifier code: org.ietf.senml-etch-cbor 435 conforms to public.data 437 Person & email address to contact for further information: Ari 438 Keranen ari.keranen@ericsson.com 440 Intended usage: COMMON 442 Restrictions on usage: N/A 444 Author: Ari Keranen ari.keranen@ericsson.com 446 Change controller: IESG 448 8. Acknowledgements 450 The use of FETCH and (i)PATCH methods with SenML was first introduced 451 by the OMA SpecWorks LwM2M v1.1 specification. This document 452 generalizes the use to any SenML representation. The authors would 453 like to thank Carsten Bormann, Christian Amsuess, Jaime Jimenez, 454 Klaus Hartke, Michael Richardson, and other participants from the 455 IETF CoRE and OMA SpecWorks DMSE working groups who have contributed 456 ideas and reviews. 458 9. References 460 9.1. Normative References 462 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 463 Requirement Levels", BCP 14, RFC 2119, 464 DOI 10.17487/RFC2119, March 1997, 465 . 467 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 468 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 469 October 2013, . 471 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 472 Application Protocol (CoAP)", RFC 7252, 473 DOI 10.17487/RFC7252, June 2014, 474 . 476 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 477 FETCH Methods for the Constrained Application Protocol 478 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 479 . 481 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 482 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 483 May 2017, . 485 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 486 Interchange Format", STD 90, RFC 8259, 487 DOI 10.17487/RFC8259, December 2017, 488 . 490 [RFC8428] Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C. 491 Bormann, "Sensor Measurement Lists (SenML)", RFC 8428, 492 DOI 10.17487/RFC8428, August 2018, 493 . 495 9.2. Informative References 497 [IPSO] IPSO, "IPSO Light Control Smart Object", 2018, 498 . 501 Authors' Addresses 503 Ari Keranen 504 Ericsson 506 Email: ari.keranen@ericsson.com 508 Mojan Mohajer 510 Email: mojanm@hotmail.com