summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc8790.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc8790.txt')
-rw-r--r--doc/rfc/rfc8790.txt515
1 files changed, 515 insertions, 0 deletions
diff --git a/doc/rfc/rfc8790.txt b/doc/rfc/rfc8790.txt
new file mode 100644
index 0000000..6c0c28a
--- /dev/null
+++ b/doc/rfc/rfc8790.txt
@@ -0,0 +1,515 @@
+
+
+
+
+Internet Engineering Task Force (IETF) A. Keränen
+Request for Comments: 8790 Ericsson
+Category: Standards Track M. Mohajer
+ISSN: 2070-1721 June 2020
+
+
+ FETCH and PATCH with Sensor Measurement Lists (SenML)
+
+Abstract
+
+ The Sensor Measurement Lists (SenML) media type and data model can be
+ used to send collections of resources, such as batches of sensor data
+ or configuration parameters. The Constrained Application Protocol
+ (CoAP) FETCH, PATCH, and iPATCH methods enable accessing and updating
+ parts of a resource or multiple resources with one request. This
+ document defines new media types for the CoAP FETCH, PATCH, and
+ iPATCH methods for resources represented using the SenML data model.
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 7841.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ https://www.rfc-editor.org/info/rfc8790.
+
+Copyright Notice
+
+ Copyright (c) 2020 IETF Trust and the persons identified as the
+ document authors. All rights reserved.
+
+ This document is subject to BCP 78 and the IETF Trust's Legal
+ Provisions Relating to IETF Documents
+ (https://trustee.ietf.org/license-info) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with respect
+ to this document. Code Components extracted from this document must
+ include Simplified BSD License text as described in Section 4.e of
+ the Trust Legal Provisions and are provided without warranty as
+ described in the Simplified BSD License.
+
+Table of Contents
+
+ 1. Introduction
+ 2. Terminology
+ 3. Using FETCH and (i)PATCH with SenML
+ 3.1. SenML FETCH
+ 3.2. SenML (i)PATCH
+ 4. Fragment Identification
+ 5. Extensibility
+ 6. Security Considerations
+ 7. IANA Considerations
+ 7.1. CoAP Content-Format Registration
+ 7.2. senml-etch+json Media Type
+ 7.3. senml-etch+cbor Media Type
+ 8. References
+ 8.1. Normative References
+ 8.2. Informative References
+ Acknowledgements
+ Authors' Addresses
+
+1. Introduction
+
+ The Sensor Measurement Lists (SenML) media type [RFC8428] and data
+ model can be used to transmit collections of resources, such as
+ batches of sensor data or configuration parameters.
+
+ An example of a SenML collection is shown below:
+
+ [
+ {"bn":"2001:db8::2/3311/0/", "n":"5850", "vb":true},
+ {"n":"5851", "v":42},
+ {"n":"5750", "vs":"Ceiling light"}
+ ]
+
+ Here, three resources, "3311/0/5850", "3311/0/5851", and
+ "3311/0/5750", of a dimmable light smart object [IPSO] are
+ represented using a single SenML Pack with three SenML Records. All
+ resources share the same base name "2001:db8::2/3311/0/"; hence, full
+ names for the resources are "2001:db8::2/3311/0/5850", etc.
+
+ The CoAP [RFC7252] FETCH, PATCH, and iPATCH methods [RFC8132] enable
+ accessing and updating parts of a resource or multiple resources with
+ one request.
+
+ This document defines two new media types, one using the JavaScript
+ Object Notation (JSON) [RFC8259] and one using the Concise Binary
+ Object Representation (CBOR) [RFC7049], which can be used with the
+ CoAP FETCH, PATCH, and iPATCH methods for resources represented using
+ the SenML data model (i.e., for both SenML and Sensor Streaming
+ Measurement Lists (SenSML) data). The rest of the document uses the
+ term "(i)PATCH" when referring to both methods as the semantics of
+ the new media types are the same for the CoAP PATCH and iPATCH
+ methods.
+
+2. Terminology
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
+ "OPTIONAL" in this document are to be interpreted as described in
+ BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
+ capitals, as shown here.
+
+ Readers should also be familiar with the terms and concepts discussed
+ in [RFC8132] and [RFC8428]. The following additional terms are used
+ in this document:
+
+ Fetch Record: One set of parameters that is used to match SenML
+ Record(s).
+
+ Fetch Pack: One or more Fetch Records in an array structure.
+
+ Patch Record: One set of parameters similar to Fetch Record but also
+ containing instructions on how to change existing SenML Pack(s).
+
+ Patch Pack: One or more Patch Records in an array structure.
+
+ Target Record: A Record in a SenML Pack that matches the selection
+ criteria of a Fetch or Patch Record and hence is a target for a
+ Fetch or Patch operation.
+
+ Target Pack: A SenML Pack that is a target for a Fetch or Patch
+ operation.
+
+ (i)PATCH: A term that refers to both CoAP "PATCH" and "iPATCH"
+ methods when there is no difference in this specification as to
+ which one is used.
+
+3. Using FETCH and (i)PATCH with SenML
+
+ The FETCH/(i)PATCH media types for SenML are modeled as extensions to
+ the SenML media type to enable reuse of existing SenML parsers and
+ generators, in particular on constrained devices. Unless mentioned
+ otherwise, FETCH and PATCH Packs are constructed with the same rules
+ and constraints as SenML Packs.
+
+ The key differences from the SenML media type are allowing the use of
+ a "null" value for removing Records with the (i)PATCH method and the
+ lack of value fields in Fetch Records. Also, the Fetch and Patch
+ Records do not have a default time or base version when the fields
+ are omitted.
+
+3.1. SenML FETCH
+
+ The FETCH method can be used to select and return a subset of
+ Records, in sequence, of one or more SenML Packs. The SenML Records
+ are selected by giving a set of names that, when resolved, match
+ resolved names in a Target SenML Pack. The names for a Fetch Pack
+ are given using the SenML "name" and/or "base name" fields. The
+ names are resolved by concatenating the base name with the name field
+ as defined in [RFC8428].
+
+ A Fetch Pack MUST contain at least one Fetch Record. A Fetch Record
+ MUST contain a name and/or base name field.
+
+ For example, to select the resources "5850" and "5851" from the
+ example in Section 1, the following Fetch Pack can be used:
+
+ [
+ {"bn":"2001:db8::2/3311/0/", "n":"5850"},
+ {"n":"5851"}
+ ]
+
+ The result of a FETCH request with the example above would be:
+
+ [
+ {"bn":"2001:db8::2/3311/0/", "n":"5850", "vb":true},
+ {"n":"5851", "v":42},
+ ]
+
+ The SenML time and unit fields can be used in a Fetch Record to
+ further narrow the selection of matched SenML Records. When no time
+ or unit is given in a Fetch Record, all SenML Records with the given
+ name are matched (i.e., unlike with SenML Records, the lack of time
+ field in a Fetch Record does not imply a time value of zero). When
+ time is given in the Fetch Record, a Target Record is matched only
+ when its resolved time value and name are equal to those of the Fetch
+ Record. Similarly, when unit is given, a Target Record is matched
+ only when its resolved unit and name are equal to those of the Fetch
+ Record. If both the time and unit are given in the Fetch Record, a
+ Target Record is matched only when both are equal to those of the
+ Fetch Record. Each Target Record MUST be included in the response at
+ most once, even if multiple Fetch Records match with the same Target
+ Record.
+
+ For example, if the resource "5850" had multiple sensor readings
+ (SenML Records) with different time values, the following Fetch Pack
+ can be used to retrieve the Record with time "1.276020091e+09":
+
+ [
+ {"bn":"2001:db8::2/3311/0/", "n":"5850", "t":1.276020091e+09}
+ ]
+
+ The resolved form of Records (Section 4.6 of [RFC8428]) is used when
+ comparing the names, times, and units of the Target and Fetch Records
+ to accommodate differences in the use of the base values. In the
+ resolved form, the SenML name in the example above becomes
+ "2001:db8::2/3311/0/5850". Since there is no base time in the Pack,
+ the time in resolved form is equal to the time in the example.
+
+ If no SenML Records match, an empty SenML Pack (i.e., array with no
+ elements) is returned as a response.
+
+ Fetch Records MUST NOT contain other fields than name, base name,
+ time, base time, unit, and base unit. Implementations MUST reject
+ and generate an error for a Fetch Pack with other fields. [RFC8132],
+ Section 2.2 provides guidance for FETCH request error handling, e.g.,
+ using the 4.22 (Unprocessable Entity) CoAP error response code.
+
+3.2. SenML (i)PATCH
+
+ The (i)PATCH method can be used to change the fields of SenML
+ Records, to add new Records, and to remove existing Records. The
+ names, times, and units of the Patch Records are given and matched in
+ the same way as for the Fetch Records, except each Patch Record MUST
+ match at most one Target Record. A Patch Record matching more than
+ one Target Record is considered invalid (patching multiple Target
+ Records with one Patch Record would result in multiple copies of the
+ same Record). Patch Packs can also include new values and other
+ SenML fields for the Records. Application of Patch Packs is
+ idempotent; hence, the PATCH and iPATCH methods for SenML Packs are
+ equivalent.
+
+ When the name in a Patch Record matches with the name in an existing
+ Record, the resolved time values and units (if any) are compared. If
+ the time values and units either do not exist in both Records or are
+ equal, the Target Record is replaced with the contents of the Patch
+ Record. All Patch Records MUST contain at least a SenML Value or Sum
+ field.
+
+ If a Patch Record contains a name, or the combination of a time
+ value, unit, and name, that does not exist in any existing Record in
+ the Pack, the given Record, with all the fields it contains, is added
+ to the Pack.
+
+ If a Patch Record has a value ("v") field with a null value, it MUST
+ NOT be added, but the matched Record (if any) is removed from the
+ Target Pack.
+
+ The Patch Records MUST be applied in the same sequence as they are in
+ the Patch Pack. If multiple Patch Packs are being processed at the
+ same time, the result MUST be equivalent to applying them in one
+ sequence.
+
+ Implementations MUST reject and generate an error for Patch Packs
+ with invalid Records. If a Patch Pack is rejected, the state of the
+ Target Pack is not changed, i.e., either all or none of the Patch
+ Records are applied. [RFC8132], Section 3.4 provides guidance for
+ error handling with PATCH and iPATCH requests, e.g., using the 4.22
+ (Unprocessable Entity) and 4.09 (Conflict) CoAP error response codes.
+
+ For example, the following document could be given as an (i)PATCH
+ payload to change/set the values of two SenML Records for the example
+ in Section 1:
+
+ [
+ {"bn":"2001:db8::2/3311/0/", "n":"5850", "vb":false},
+ {"n":"5851", "v":10}
+ ]
+
+ If the request is successful, the resulting representation of the
+ example SenML Pack would be as follows:
+
+ [
+ {"bn":"2001:db8::2/3311/0/", "n":"5850", "vb":false},
+ {"n":"5851", "v":10},
+ {"n":"5750", "vs":"Ceiling light"}
+ ]
+
+ As another example, the following document could be given as an
+ (i)PATCH payload to remove the two SenML Records:
+
+ [
+ {"bn":"2001:db8::2/3311/0/", "n":"5850", "v":null},
+ {"n":"5851", "v":null}
+ ]
+
+4. Fragment Identification
+
+ Fragment identification for Records of Fetch and Patch Packs uses the
+ same mechanism as SenML JSON/CBOR fragment identification (see
+ Section 9 of [RFC8428]), i.e., the "rec" scheme followed by a comma-
+ separated list of Record positions or range(s) of Records. For
+ example, to select the 3rd and 5th Record of a Fetch or Patch Pack, a
+ fragment identifier "rec=3,5" can be used in the URI of the Fetch or
+ Patch Pack resource.
+
+5. Extensibility
+
+ The SenML mandatory-to-understand field extensibility mechanism (see
+ Section 4.4 of [RFC8428]) does not apply to Patch Packs, i.e.,
+ unknown fields MUST NOT generate an error, but such fields are
+ treated like any other field (e.g., added to Patch target Records
+ where applicable).
+
+ This specification allows only a small subset of SenML fields in
+ Fetch Records, but future specifications may enable new fields for
+ Fetch Records and possibly also new fields for selecting targets for
+ Patch Records.
+
+6. Security Considerations
+
+ The security and privacy considerations of SenML also apply to the
+ FETCH and (i)PATCH methods. CoAP's security mechanisms are used to
+ provide security for the FETCH and (i)PATCH methods.
+
+ In FETCH and (i)PATCH requests, the client can pass arbitrary names
+ to the target resource for manipulation. The resource implementer
+ must take care to only allow access to names that are actually part
+ of (or accessible through) the target resource. In particular, the
+ receiver needs to ensure that any input does not lead to uncontrolled
+ special interpretation by the system.
+
+ If the client is not allowed to do a GET or PUT on the full target
+ resource (and thus all the names accessible through it), access
+ control rules must be evaluated for each Record in the Pack.
+
+7. IANA Considerations
+
+ This document registers two new media types and CoAP Content-Format
+ IDs for both media types.
+
+7.1. CoAP Content-Format Registration
+
+ IANA has assigned CoAP Content-Format IDs for the SenML PATCH and
+ FETCH media types in the "CoAP Content-Formats" subregistry, within
+ the "Constrained RESTful Environments (CoRE) Parameters" registry
+ [RFC7252]. The assigned IDs are shown in Table 1.
+
+ +=============================+==========+=====+
+ | Media Type | Encoding | ID |
+ +=============================+==========+=====+
+ | application/senml-etch+json | - | 320 |
+ +-----------------------------+----------+-----+
+ | application/senml-etch+cbor | - | 322 |
+ +-----------------------------+----------+-----+
+
+ Table 1: CoAP Content-Format IDs
+
+7.2. senml-etch+json Media Type
+
+ Type name: application
+
+ Subtype name: senml-etch+json
+
+ Required parameters: N/A
+
+ Optional parameters: N/A
+
+ Encoding considerations: binary
+
+ Security considerations: See Section 6 of RFC 8790.
+
+ Interoperability considerations: N/A
+
+ Published specification: RFC 8790
+
+ Applications that use this media type: Applications that use the
+ SenML media type for resource representation.
+
+ Fragment identifier considerations: Fragment identification for
+ application/senml-etch+json is supported by using fragment
+ identifiers as specified by Section 4 of RFC 8790.
+
+ Additional information:
+
+ Deprecated alias names for this type: N/A
+
+ Magic number(s): N/A
+
+ File extension(s): senml-etchj
+
+ Windows Clipboard Name: "SenML FETCH/PATCH format"
+
+ Macintosh file type code(s): N/A
+
+ Macintosh Universal Type Identifier code:
+ org.ietf.senml-etch-json conforms to public.text
+
+ Person & email address to contact for further information:
+ Ari Keränen <ari.keranen@ericsson.com>
+
+ Intended usage: COMMON
+
+ Restrictions on usage: N/A
+
+ Author: Ari Keränen <ari.keranen@ericsson.com>
+
+ Change controller: IESG
+
+7.3. senml-etch+cbor Media Type
+
+ Type name: application
+
+ Subtype name: senml-etch+cbor
+
+ Required parameters: N/A
+
+ Optional parameters: N/A
+
+ Encoding considerations: binary
+
+ Security considerations: See Section 6 of RFC 8790.
+
+ Interoperability considerations: N/A
+
+ Published specification: RFC 8790
+
+ Applications that use this media type: Applications that use the
+ SenML media type for resource representation.
+
+ Fragment identifier considerations: Fragment identification for
+ application/senml-etch+cbor is supported by using fragment
+ identifiers as specified by Section 4 of RFC 8790.
+
+ Additional information:
+
+ Deprecated alias names for this type: N/A
+
+ Magic number(s): N/A
+
+ File extension(s): senml-etchc
+
+ Macintosh file type code(s): N/A
+
+ Macintosh Universal Type Identifier code:
+ org.ietf.senml-etch-cbor conforms to public.data
+
+ Person & email address to contact for further information:
+ Ari Keränen <ari.keranen@ericsson.com>
+
+ Intended usage: COMMON
+
+ Restrictions on usage: N/A
+
+ Author: Ari Keränen <ari.keranen@ericsson.com>
+
+ Change controller: IESG
+
+8. References
+
+8.1. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119,
+ DOI 10.17487/RFC2119, March 1997,
+ <https://www.rfc-editor.org/info/rfc2119>.
+
+ [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
+ Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
+ October 2013, <https://www.rfc-editor.org/info/rfc7049>.
+
+ [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
+ Application Protocol (CoAP)", RFC 7252,
+ DOI 10.17487/RFC7252, June 2014,
+ <https://www.rfc-editor.org/info/rfc7252>.
+
+ [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and
+ FETCH Methods for the Constrained Application Protocol
+ (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017,
+ <https://www.rfc-editor.org/info/rfc8132>.
+
+ [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
+ 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
+ May 2017, <https://www.rfc-editor.org/info/rfc8174>.
+
+ [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
+ Interchange Format", STD 90, RFC 8259,
+ DOI 10.17487/RFC8259, December 2017,
+ <https://www.rfc-editor.org/info/rfc8259>.
+
+ [RFC8428] Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C.
+ Bormann, "Sensor Measurement Lists (SenML)", RFC 8428,
+ DOI 10.17487/RFC8428, August 2018,
+ <https://www.rfc-editor.org/info/rfc8428>.
+
+8.2. Informative References
+
+ [IPSO] IPSO, "IPSO Light Control Smart Object", 2019,
+ <http://www.openmobilealliance.org/tech/profiles/
+ lwm2m/3311.xml>.
+
+Acknowledgements
+
+ The use of the FETCH and (i)PATCH methods with SenML was first
+ introduced by the OMA SpecWorks Lightweight Machine to Machine
+ (LwM2M) v1.1 specification. This document generalizes the use to any
+ SenML representation. The authors would like to thank Carsten
+ Bormann, Christian Amsüss, Jaime Jiménez, Klaus Hartke, Michael
+ Richardson, and other participants from the IETF CoRE and OMA
+ SpecWorks DMSE working groups who have contributed ideas and reviews.
+
+Authors' Addresses
+
+ Ari Keränen
+ Ericsson
+ FI-02420 Jorvas
+ Finland
+
+ Email: ari.keranen@ericsson.com
+
+
+ Mojan Mohajer
+
+ Email: mojanm@hotmail.com