FETCH and PATCH with Sensor Measurement Lists (SenML)
Extracted elements (25)
A null value in a Patch Record's value ("v") field is used to signal record deletion. This reuses the SenML value field rather than introducing a separate deletion indicator, but requires that null not be a valid sensor value.
Application of Patch Packs is defined to be idempotent, making PATCH and iPATCH semantically equivalent for SenML. This reflects that SenML record replacement/addition/removal is a set operation with no ordering side-effects between identical requests.
Fetch and Patch Records do not have a default time or base version when fields are omitted, unlike standard SenML Records. The absence of a time field in a Fetch Record does not imply time zero — it means all Records with the given name are matched.
The FETCH/(i)PATCH media types are modeled as extensions to the SenML media type to enable reuse of existing SenML parsers and generators, which is particularly important on constrained devices.
Error handling for FETCH requests (e.g., invalid Fetch Records) follows RFC 8132, Section 2.2, using CoAP response code 4.22 (Unprocessable Entity). For PATCH/iPATCH, codes 4.22 and 4.09 (Conflict) apply per RFC 8132, Section 3.4.
Fragment identification for Fetch and Patch Packs uses the same "rec" scheme as SenML JSON/CBOR (Section 9 of RFC 8428), consisting of a comma-separated list of Record positions or ranges (e.g., "rec=3,5").
The resolved form of Records (Section 4.6 of RFC 8428) is used when comparing names, times, and units of Target and Fetch/Patch Records, to accommodate differences in the use of base values across packs.
A Fetch Pack MUST contain at least one Fetch Record, and each Fetch Record MUST contain a name and/or base name field.
All Patch Records MUST contain at least a SenML Value or Sum field.
Each Patch Record MUST match at most one Target Record. A Patch Record that matches more than one Target Record is considered invalid.
Each Target Record MUST be included in the FETCH response at most once, even if multiple Fetch Records match the same Target Record.
Fetch Records MUST NOT contain fields other than name, base name, time, base time, unit, and base unit. Implementations MUST reject and generate an error for a Fetch Pack containing other fields.
If a Patch Record has a value ("v") field with a null value, it MUST NOT be added to the Target Pack; instead, the matched Record (if any) is removed.
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 — either all or none of the Patch Records are applied (atomic semantics).
Patch Records MUST be applied in the same sequence as they appear in the Patch Pack. If multiple Patch Packs are processed simultaneously, the result MUST be equivalent to applying them in one sequence.
Unknown fields in Patch Packs MUST NOT generate an error; they are treated like any other field (e.g., added to Patch target Records where applicable). This differs from the SenML mandatory-to-understand extensibility mechanism.
A Fetch Pack is an array of one or more Fetch Records. It is used as the payload of a CoAP FETCH request to select a subset of records from one or more Target SenML Packs.
A Fetch Record is one set of parameters used to match SenML Record(s) by name, base name, time, base time, unit, and/or base unit. It contains no value fields.
A Patch Pack is an array of one or more Patch Records, used as the payload of a CoAP PATCH or iPATCH request. Application of Patch Packs is idempotent, making PATCH and iPATCH semantically equivalent for SenML.
A Patch Record is similar to a Fetch Record but also contains instructions (value fields) on how to change existing SenML Pack(s). A null value field signals record removal.
IANA registered the media type application/senml-etch+cbor (file extension senml-etchc) for SenML FETCH and PATCH operations using CBOR encoding, as defined in RFC 8790.
IANA registered two CoAP Content-Format IDs in the "CoAP Content-Formats" subregistry: application/senml-etch+json assigned ID 320, and application/senml-etch+cbor assigned ID 322.
If a client is not permitted to perform GET or PUT on the full target resource, access control rules must be evaluated per Record in the Pack rather than at the pack level.
In FETCH and (i)PATCH requests, the client can pass arbitrary names to the target resource. Implementers must ensure access is restricted to names that are actually part of (or accessible through) the target resource, and that input does not lead to uncontrolled special interpretation by the system.
The security and privacy considerations of SenML (RFC 8428) and CoAP's security mechanisms apply equally to the FETCH and (i)PATCH methods defined in this document.