idnits 2.17.1 draft-ietf-core-senml-etch-04.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 (July 8, 2019) is 1755 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: January 9, 2020 u-blox UK 6 July 8, 2019 8 FETCH & PATCH with Sensor Measurement Lists (SenML) 9 draft-ietf-core-senml-etch-04 11 Abstract 13 The Sensor Measurement Lists (SenML) media type and data model can be 14 used to send collections of resources, such as batches of sensor data 15 or configuration parameters. The CoAP iPATCH, PATCH, and FETCH 16 methods enable accessing and updating parts of a resource or multiple 17 resources with one request. This document defines new media types 18 for the CoAP iPATCH, PATCH, and FETCH methods for resources 19 represented with the SenML data model. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at https://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on January 9, 2020. 38 Copyright Notice 40 Copyright (c) 2019 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (https://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 3. Using FETCH and (i)PATCH with SenML . . . . . . . . . . . . . 3 58 3.1. SenML FETCH . . . . . . . . . . . . . . . . . . . . . . . 4 59 3.2. SenML (i)PATCH . . . . . . . . . . . . . . . . . . . . . 4 60 4. Security Considerations . . . . . . . . . . . . . . . . . . . 5 61 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 62 5.1. CoAP Content-Format Registration . . . . . . . . . . . . 6 63 5.2. senml-etch+json Media Type . . . . . . . . . . . . . . . 6 64 5.3. senml-etch+cbor Media Type . . . . . . . . . . . . . . . 7 65 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8 66 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 67 7.1. Normative References . . . . . . . . . . . . . . . . . . 9 68 7.2. Informative References . . . . . . . . . . . . . . . . . 9 69 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 71 1. Introduction 73 The Sensor Measurement Lists (SenML) media type [RFC8428] and data 74 model can be used to transmit collections of resources, such as 75 batches of sensor data or configuration parameters. 77 An example of a SenML collection is shown below: 79 [ 80 {"bn":"2001:db8::2/3311/0/", "n":"5850", "vb":true}, 81 {"n":"5851", "v":42}, 82 {"n":"5750", "vs":"Ceiling light"} 83 ] 85 Here three resources "3311/0/5850", "3311/0/5851", and "3311/0/5750", 86 of an IPSO dimmable light smart object [IPSO] are represented using a 87 single SenML Pack with three SenML Records. All resources share the 88 same base name "2001:db8::2/3311/0/", hence full names for resources 89 are "2001:db8::2/3311/0/5850", etc. 91 The CoAP [RFC7252] iPATCH, PATCH, and FETCH methods [RFC8132] enable 92 accessing and updating parts of a resource or multiple resources with 93 one request. 95 This document defines two new media types, one using the JavaScript 96 Object Notation (JSON) [RFC8259] and one using the Concise Binary 97 Object Representation (CBOR) [RFC7049], that can be used with the 98 CoAP iPATCH, PATCH, and FETCH methods for resources represented with 99 the SenML data model. The semantics of the new media types are the 100 same for the CoAP PATCH and iPATCH methods. The rest of the document 101 uses term "(i)PATCH" when referring to both methods. 103 2. Terminology 105 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 106 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 107 "OPTIONAL" in this document are to be interpreted as described in BCP 108 14 [RFC2119] [RFC8174] when, and only when, they appear in all 109 capitals, as shown here. 111 Readers should also be familiar with the terms and concepts discussed 112 in [RFC8132] and [RFC8428]. Also the following terms are used in 113 this document: 115 Fetch Record: One set of parameters that is used to match SenML 116 Record(s). 118 Fetch Pack: One or more Fetch Records in an array structure. 120 Patch Record: One set of parameters similar to Fetch Record but also 121 containing instructions on how to change existing SenML Pack(s). 123 Patch Pack: One or more Patch Records in an array structure. 125 Target Record: A Record in a SenML Pack that is matching the 126 selection criteria of a Fetch or Patch Record and hence is a 127 target for a Fetch or Patch operation. 129 (i)PATCH: A term that refers to both CoAP "PATCH" and "iPATCH" 130 methods when there is no difference in this specification in which 131 one is used. 133 3. Using FETCH and (i)PATCH with SenML 135 The FETCH/(i)PATCH media types for SenML are modeled as extensions to 136 the SenML media type to enable re-use of existing SenML parsers and 137 generators, in particular on constrained devices. Unless mentioned 138 otherwise, FETCH and PATCH Packs are constructed with the same rules 139 and constraints as SenML Packs. 141 The key difference to the SenML media type is allowing the use of a 142 "null" value for removing records with the (i)PATCH method. Also the 143 Fetch and Patch Records do not have default time or base version when 144 the fields are omitted. 146 3.1. SenML FETCH 148 The FETCH method can be used to select and return a subset of 149 records, in sequence, of one or more SenML Packs. The SenML Records 150 are selected by giving a set of names that, when resolved, match 151 resolved names in a SenML Pack. The names for a Fetch Pack are given 152 using the SenML "name" and/or "base name" Fields. The names are 153 resolved by concatenating the base name with the name field as 154 defined in [RFC8428]. 156 For example, to select the IPSO resources "5850" and "5851" from the 157 example in Section 1, the following Fetch Pack can be used: 159 [ 160 {"bn":"2001:db8::2/3311/0/", "n":"5850"}, 161 {"n":"5851"} 162 ] 164 The result to a FETCH request with the example above would be: 166 [ 167 {"bn":"2001:db8::2/3311/0/", "n":"5850", "vb":true}, 168 {"n":"5851", "v":42}, 169 ] 171 When SenML Records contain also time values, a name may no longer 172 uniquely identify a single Record. When no time is given in a Fetch 173 Record, all SenML Records with the given name are matched (i.e., 174 unlike with SenML Records, lack of time field in a Fetch Record does 175 not imply time value zero). When time is given in the Fetch Record, 176 only a SenML Record (if any) with equal resolved time value and name 177 is matched. 179 The resolved form of records (Section 4.6 of [RFC8428]) is used when 180 comparing the names and times of the Target and Fetch Records to 181 accommodate for differences in use of the base values. 183 3.2. SenML (i)PATCH 185 The (i)PATCH method can be used to change the values of SenML 186 Records, to add new Records, and to remove existing Records. The 187 names and times of the Patch Records are given and matched in same 188 way as for the Fetch Records, except each Patch Record can match at 189 most one Target Record. Patch Packs can also include new values and 190 other SenML Fields for the Records. Application of Patch Packs is 191 idempotent. 193 When the name in a Patch Record matches with the name in an existing 194 Record, the resolved time values are compared. If the time values 195 either do not exist in both Records or are equal, the Target Record 196 is replaced with the contents of the Patch Record. 198 If a Patch Record contains a name, or combination of a time value and 199 a name, that do not exist in any existing Record in the Pack, the 200 given Record, with all the fields it contains, is added to the Pack. 202 If a Patch Record has a value ("v") field with value null, the 203 matched Record (if any) is removed from the Pack. 205 For example, the following document could be given as an (i)PATCH 206 payload to change/set values of two SenML Records for the example in 207 Section 1: 209 [ 210 {"bn":"2001:db8::2/3311/0/", "n":"5850", "vb":false}, 211 {"n":"5851", "v":10} 212 ] 214 If the request is successful, the resulting representation of the 215 example SenML Pack would be as follows: 217 [ 218 {"bn":"2001:db8::2/3311/0/", "n":"5850", "vb":false}, 219 {"n":"5851", "v":10}, 220 {"n":"5750", "vs":"Ceiling light"} 221 ] 223 As another example, the following document could be given as an 224 (i)PATCH payload to remove the two SenML Records: 226 [ 227 {"bn":"2001:db8::2/3311/0/", "n":"5850", "v":null}, 228 {"n":"5851", "v":null} 229 ] 231 4. Security Considerations 233 The security and privacy considerations of SenML apply also with the 234 FETCH and (i)PATCH methods. 236 In FETCH and (i)PATCH requests, the client can pass arbitrary names 237 to the target resource for manipulation. The resource implementer 238 must take care to only allow access to names that are actually part 239 of (or accessible through) the target resource. 241 If the client is not allowed to do a GET or PUT on the full target 242 resource (and thus all the names accessible through it), access 243 control rules must be evaluated for each record in the pack. 245 5. IANA Considerations 247 This document registers two new media types and CoAP Content-Format 248 IDs for both media types. 250 Note to RFC Editor: Please replace all occurrences of "RFC-AAAA" with 251 the RFC number of this document. 253 5.1. CoAP Content-Format Registration 255 IANA is requested to assign CoAP Content-Format IDs for the SenML 256 PATCH and FETCH media types in the "CoAP Content-Formats" sub- 257 registry, within the "CoRE Parameters" registry [RFC7252]. The 258 assigned IDs are shown in Table 1. 260 +-----------------------------+----------+---------+ 261 | Media type | Encoding | ID | 262 +-----------------------------+----------+---------+ 263 | application/senml-etch+json | - | TBD-320 | 264 | | | | 265 | application/senml-etch+cbor | - | TBD-322 | 266 +-----------------------------+----------+---------+ 268 Table 1: CoAP Content-Format IDs 270 5.2. senml-etch+json Media Type 272 Type name: application 274 Subtype name: senml-etch+json 276 Required parameters: none 278 Optional parameters: none 280 Encoding considerations: Must be encoded as using a subset of the 281 encoding allowed in [RFC8259]. This simplifies implementation of a 282 very simple system and does not impose any significant limitations as 283 all this data is meant for machine to machine communications and is 284 not meant to be human readable. 286 Security considerations: See Section 4 of RFC-AAAA. 288 Interoperability considerations: Applications MUST ignore any key 289 value pairs that they do not understand unless the key ends with the 290 '_' character in which case an error MUST be generated. This allows 291 backwards compatible extensions to this specification. 293 Published specification: RFC-AAAA 295 Applications that use this media type: Applications that use the 296 SenML media type for resource representation. 298 Fragment identifier considerations: N/A 300 Additional information: 302 Magic number(s): none 304 File extension(s): senml-etchj 306 Windows Clipboard Name: "SenML FETCH/PATCH format" 308 Macintosh file type code(s): none 310 Macintosh Universal Type Identifier code: org.ietf.senml-etch-json 311 conforms to public.text 313 Person & email address to contact for further information: Ari 314 Keranen ari.keranen@ericsson.com 316 Intended usage: COMMON 318 Restrictions on usage: None 320 Author: Ari Keranen ari.keranen@ericsson.com 322 Change controller: IESG 324 5.3. senml-etch+cbor Media Type 326 Type name: application 328 Subtype name: senml-etch+cbor 330 Required parameters: none 332 Optional parameters: none 334 Encoding considerations: Must be encoded as using [RFC7049]. 336 Security considerations: See Section 4 of RFC-AAAA. 338 Interoperability considerations: Applications MUST ignore any key 339 value pairs that they do not understand unless the key ends with the 340 '_' character in which case an error MUST be generated. This allows 341 backwards compatible extensions to this specification. 343 Published specification: RFC-AAAA 345 Applications that use this media type: Applications that use the 346 SenML media type for resource representation. 348 Fragment identifier considerations: N/A 350 Additional information: 352 Magic number(s): none 354 File extension(s): senml-etchc 356 Macintosh file type code(s): none 358 Macintosh Universal Type Identifier code: org.ietf.senml-etch-cbor 359 conforms to public.data 361 Person & email address to contact for further information: Ari 362 Keranen ari.keranen@ericsson.com 364 Intended usage: COMMON 366 Restrictions on usage: None 368 Author: Ari Keranen ari.keranen@ericsson.com 370 Change controller: IESG 372 6. Acknowledgements 374 The use of FETCH and (i)PATCH methods with SenML was first introduced 375 by the OMA SpecWorks LwM2M v1.1 specification. This document 376 generalizes the use to any SenML representation. The authors would 377 like to thank Carsten Bormann, Christian Amsuess, Jaime Jimenez, 378 Klaus Hartke, Michael Richardson, and other participants from the 379 IETF CoRE and OMA SpecWorks DMSE working groups who have contributed 380 ideas and reviews. 382 7. References 384 7.1. Normative References 386 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 387 Requirement Levels", BCP 14, RFC 2119, 388 DOI 10.17487/RFC2119, March 1997, 389 . 391 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 392 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 393 October 2013, . 395 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 396 Application Protocol (CoAP)", RFC 7252, 397 DOI 10.17487/RFC7252, June 2014, 398 . 400 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 401 FETCH Methods for the Constrained Application Protocol 402 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 403 . 405 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 406 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 407 May 2017, . 409 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 410 Interchange Format", STD 90, RFC 8259, 411 DOI 10.17487/RFC8259, December 2017, 412 . 414 [RFC8428] Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C. 415 Bormann, "Sensor Measurement Lists (SenML)", RFC 8428, 416 DOI 10.17487/RFC8428, August 2018, 417 . 419 7.2. Informative References 421 [IPSO] IPSO, "IPSO Light Control Smart Object", 2018, 422 . 425 Authors' Addresses 426 Ari Keranen 427 Ericsson 429 Email: ari.keranen@ericsson.com 431 Mojan Mohajer 432 u-blox UK 434 Email: Mojan.Mohajer@u-blox.com