FETCH & PATCH with Sensor Measurement Lists (SenML)Ericssonari.keranen@ericsson.comu-blox UKMojan.Mohajer@u-blox.comInternet-DraftThe 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 CoAP iPATCH, PATCH, and FETCH methods
enable accessing and updating parts of a resource or multiple resources
with one request. This document defines new media types for the CoAP
iPATCH, and FETCH methods for resources represented with the SenML data
model.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.Example of a SenML collection is shown below:Here three resources “3306/0/5850”, “3306/0/5851”, and “3306/0/5750”,
of an IPSO dimmable light smart object are represented using
a single SenML Pack with three SenML Records. All resources share the
same base name “2001:db8::2/3306/0/”, hence full names for resources
are “2001:db8::2/3306/0/5850”, etc.The CoAP iPATCH and FETCH methods 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) and one using the Concise Binary
Object Representation (CBOR) , that can be used with the CoAP
iPATCH, PATCH, and FETCH methods for resources represented with the SenML
data model. The semantics of the new media types are the same for the
CoAP PATCH and iPATCH methods.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 when, and only when, they appear in
all capitals, as shown here.Readers should also be familiar with the terms and concepts discussed
in and . Also the following terms are used in
this document:
One set of parameters that is used to match SenML Record(s).
One or more Fetch Records in an array structure.
One set of parameters similar to Fetch Record but also containing
instructions on how to change existing SenML Pack(s).
One or more Patch Records in an array structure.
A Record in a SenML Pack that is matching the selection criteria of
a Fetch or Patch Record and hence is a target for a Fetch or Patch
operation.The FETCH/iPATCH media types for SenML are modeled as extensions to the
SenML media type to enable re-use 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 only difference to SenML media type is
allowing the use of “null” value for removing records with the iPATCH
method.The FETCH method can be used to select and return parts of one or more
SenML Packs. The SenML Records are selected by giving the name(s) of
the resources using the SenML “name” and/or “base name” Fields.For example, to select resources “5850” and “5851” from the example in
, the following Fetch Pack can be used:The result to a FETCH request with the example above would be:When SenML Records contain also time values, a name may no longer
uniquely identify a single Record. When no time is given in a Fetch
Record, all SenML Records with the given name are matched. When time
is given in the Fetch Record, only a SenML Record (if any) with equal
time value and name is matched.The resolved form of records (Section 4.6 of ) is used when
comparing the names and times of the Target and Fetch Records to
accommodate for differences in use of the base values.The iPATCH method can be used to change the values of SenML Records,
to add new Records, and to remove existing Records. The names and
times of the Patch Records are given and matched in same way as for
the Fetch Records, except each Patch Record can match at most one
Target Record. Patch Packs can also include new values and other SenML
Fields for the Records.When the name in a Patch Record matches with the name in an existing
Record, the time values are compared. If the time values do not exist
or are equal in both Records, the Target Record is replaced with the
contents of the Patch Record.If a Patch Record contains a name, or combination of a time value and
a name, that do 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 field with value null, the matched
Record (if any) is removed from the Pack.For example, the following document could be given as iPATCH payload
to change/set values of two SenML Records for the example in
:If the request is successful, the resulting representation of the
example SenML Pack would be as follows:The security and privacy considerations of SenML apply also with the
FETCH and iPATCH methods.In FETCH and iPATCH 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.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.This document registers two new media types and CoAP Content-Format IDs
for both media types.Note to RFC Editor: Please replace all occurrences of “RFC-AAAA” with
the RFC number of this document.IANA is requested to assign CoAP Content-Format IDs for the SenML
PATCH and FETCH media types in the “CoAP Content-Formats” sub-
registry, within the “CoRE Parameters” registry . All IDs
are assigned from the “Expert Review” (0-255) range. The assigned IDs
are show in .Media typeIDapplication/senml-etch+jsonTBDapplication/senml-etch+cborTBDType name: applicationSubtype name: senml-etch+jsonRequired parameters: noneOptional parameters: noneEncoding considerations: Must be encoded as using a subset of the
encoding allowed in . See RFC-AAAA for details. This
simplifies implementation of very simple system and does not impose
any significant limitations as all this data is meant for machine to
machine communications and is not meant to be human readable.Security considerations: See of RFC-AAAA.Interoperability considerations: Applications MUST ignore any key
value pairs that they do not understand unless the key ends with the
‘_’ character in which case an error MUST be generated. This allows
backwards compatible extensions to this specification.Published specification: RFC-AAAAApplications that use this media type: Applications that use the
SenML media type for resource representation.Fragment identifier considerations: N/AAdditional information:Magic number(s): noneFile extension(s): senml-etchjWindows Clipboard Name: “SenML FETCH/PATCH format”Macintosh file type code(s): noneMacintosh Universal Type Identifier code: org.ietf.senml-etch-json
conforms to public.textPerson & email address to contact for further information:
Ari Keranen ari.keranen@ericsson.comIntended usage: COMMONRestrictions on usage: NoneAuthor: Ari Keranen ari.keranen@ericsson.comChange controller: IESGType name: applicationSubtype name: senml-etch+cborRequired parameters: noneOptional parameters: noneEncoding considerations: Must be encoded as using . See
RFC-AAAA for details.Security considerations: See of RFC-AAAA.Interoperability considerations: Applications MUST ignore any key
value pairs that they do not understand unless the key ends with the
‘_’ character in which case an error MUST be generated. This allows
backwards compatible extensions to this specification.Published specification: RFC-AAAAApplications that use this media type: Applications that use the
SenML media type for resource representation.Fragment identifier considerations: N/AAdditional information:Magic number(s): noneFile extension(s): senml-etchcMacintosh file type code(s): noneMacintosh Universal Type Identifier code: org.ietf.senml-etch-cbor
conforms to public.dataPerson & email address to contact for further information:
Ari Keranen ari.keranen@ericsson.comIntended usage: COMMONRestrictions on usage: NoneAuthor: Ari Keranen ari.keranen@ericsson.comChange controller: IESGThe use of FETCH and iPATCH methods with SenML was first introduced by
the OMA SpecWorks LwM2M v1.1 specification. This document generalizes
the use to any SenML representation. The authors would like to thank
Carsten Bormann, Christian Amsuess, Jaime Jimenez, Klaus Hartke, and
also everyone in the IETF CoRE and OMA SpecWorks DMSE working groups
for their contributions and reviews.Sensor Measurement Lists (SenML)This specification defines a format for representing simple sensor measurements and device parameters in Sensor Measurement Lists (SenML). Representations are defined in JavaScript Object Notation (JSON), Concise Binary Object Representation (CBOR), Extensible Markup Language (XML), and Efficient XML Interchange (EXI), which share the common SenML data model. A simple sensor, such as a temperature sensor, could use one of these media types in protocols such as HTTP or the Constrained Application Protocol (CoAP) to transport the measurements of the sensor or to be configured.The Constrained Application Protocol (CoAP)The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with constrained nodes and constrained (e.g., low-power, lossy) networks. The nodes often have 8-bit microcontrollers with small amounts of ROM and RAM, while constrained networks such as IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs) often have high packet error rates and a typical throughput of 10s of kbit/s. The protocol is designed for machine- to-machine (M2M) applications such as smart energy and building automation.CoAP provides a request/response interaction model between application endpoints, supports built-in discovery of services and resources, and includes key concepts of the Web such as URIs and Internet media types. CoAP is designed to easily interface with HTTP for integration with the Web while meeting specialized requirements such as multicast support, very low overhead, and simplicity for constrained environments.PATCH and FETCH Methods for the Constrained Application Protocol (CoAP)The methods defined in RFC 7252 for the Constrained Application Protocol (CoAP) only allow access to a complete resource, not to parts of a resource. In case of resources with larger or complex data, or in situations where resource continuity is required, replacing or requesting the whole resource is undesirable. Several applications using CoAP need to access parts of the resources.This specification defines the new CoAP methods, FETCH, PATCH, and iPATCH, which are used to access and update parts of a resource.The JavaScript Object Notation (JSON) Data Interchange FormatJavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data.This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance.Concise Binary Object Representation (CBOR)The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack.Key words for use in RFCs to Indicate Requirement LevelsIn many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.Ambiguity of Uppercase vs Lowercase in RFC 2119 Key WordsRFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.IPSO Smart Object GuidelinesIPSO