Sensor Measurement Lists (SenML)
updated by
- rfc-9100 — Sensor Measurement Lists (SenML) Features and Versions
Extracted elements (29)
Base fields (bn, bt, bu, bv, bs) are prepended/added to corresponding regular fields in subsequent Records, allowing a compact representation that avoids repeating identical sensor identifiers, units, or time offsets in every Record of a batch upload.
CBOR integer map keys for RFC 8428's defined fields are declared conclusive — no additional integer keys will be defined. Future extensions must use string keys. This design allows translators between CBOR and JSON to handle all future string-keyed labels without implementation updates.
Separate SenML (non-streaming) and SenSML (streaming) media types are defined because they are fundamentally different data formats: non-streaming implementations wait for an end-of-pack marker before processing, while streaming implementations cannot wait for such a marker. Separate negotiation is therefore required.
The integrated sum field is named 'Sum' rather than 'integral' for historical reasons. Cumulative sums are preferred over instantaneous values for measurements like energy because they remain accurate across network outages and reduce server-side aggregation error.
Applications MUST ignore unknown JSON/CBOR key-value pairs unless the key ends with '_', which signals a mandatory-to-understand extension and MUST trigger an error. This convention enables backwards-compatible extension while preserving the ability to mark breaking changes.
The cumulative Sum field may wrap to zero, reset on device power loss or replacement, or begin accumulation at an arbitrary time. Applications consuming Sum values must handle wrap-around and resets; a common heuristic is that non-negative-measurement sums should never decrease, so a decrease signals a reset event.
All SenML Records in a Pack MUST have the same version number. Systems reading a SenML object MUST check the Base Version field; if the version number is larger than what the system understands, the system MUST NOT use that object.
Exactly one Value field (v, vb, vs, or vd) MUST appear in a SenML Record unless a Sum field is present, in which case no Value field is allowed.
For streaming SenSML in CBOR, the array containing the records SHOULD use a CBOR indefinite-length array; for non-streaming SenML, a definite-length array MUST be used.
Implementations MUST ignore SenML fields they do not recognize, unless the field's label name ends with the '_' character, in which case an error MUST be generated. This enables backwards-compatible extension.
Systems or protocols using SenML in streaming (SenSML) fashion MUST specify that they are doing so. In SenSML Streams using relative time, 'now' is interpreted as the time when the specific Record is sent.
Systems receiving JSON SenML measurements MUST be able to process the full range of IEEE 754 double-precision floating-point numbers. The exponent character 'e' MUST be lowercase; the mantissa SHOULD be less than 19 characters and the exponent less than 5 characters.
The concatenated Name (Base Name + Name) MUST consist only of characters A-Z, a-z, 0-9, '-', ':', '.', '/', and '_', and MUST start with A-Z, a-z, or 0-9. It is RECOMMENDED that concatenated names be represented as URIs or URNs.
The EXI header MUST include EXI Options with schemaId set to 'a', indicating the schema provided in RFC 8428. An EXI Cookie SHOULD NOT be used when data is transported over CoAP or HTTP, as it is redundant and increases size.
Long-term stable unique identifiers in SenML names (e.g., device URNs, 1-wire addresses, UUIDs) can be used to track devices and, by extension, their owners or users over time. Implementers should consider whether their naming scheme exposes persistent identifiers and mitigate accordingly.
A SenML Pack is a single array containing a series of SenML Records. Each Record may contain base fields (which apply to the Record and all following Records until overridden) and regular fields (which apply only to that Record). All base fields are optional.
A SenML Record is 'resolved' when it contains no base fields (labels starting with 'b', except Base Version under certain conditions) and no relative times. Resolved Records must be in chronological order and have all applicable base values applied. This normalized form is used for big-data applications and format conversion.
Fragment identifiers for SenML use the 'rec' scheme: a single record number, a range (e.g., rec=3-6), an open-ended range (rec=19-*), or a comma-separated list. Record numbering starts at 1. XML and EXI formats additionally support XPointer element() scheme fragment identifiers.
Time values less than 2**28 (268,435,456) represent seconds relative to 'now'; values greater than or equal to 2**28 represent absolute seconds since the Unix epoch (1970-01-01T00:00Z). Base Time and Time fields are summed; care must be taken that relative times do not inadvertently cross the 2**28 boundary.
IANA has created the 'SenML Labels' registry with 15 initial entries (Table 7) covering all base and regular SenML fields, including their string label, CBOR integer label, JSON type, XML type, and EXI schema ID. New base labels MUST start with 'b'; new Value labels MUST include 'Value' in their long-form name. New entries require Expert Review.
IANA has created the 'SenML Units' registry (under the 'Sensor Measurement Lists (SenML)' top-level registry) with over 60 initial unit symbols covering SI base and derived units, ratios, percentages, and domain-specific quantities. New entries require Expert Review. Only one symbol per measurement type is allowed; SI units are preferred.
RFC 8428 registers 8 IANA media types: application/senml+json, application/sensml+json, application/senml+cbor, application/sensml+cbor, application/senml+xml, application/sensml+xml, application/senml-exi, and application/sensml-exi. File extensions include .senml, .sensml, .senmlc, and .sensmlc.
RFC 8428 registers CoAP Content-Format numbers for each of the eight SenML/SenSML media types in the IANA CoAP Content-Formats registry.
SenML data can include sensitive information such as sensor readings, device identifiers, and location data. Implementations MUST provide confidentiality and integrity protection (e.g., via TLS when using HTTP or DTLS when using CoAP) appropriate to the sensitivity of the data being transmitted.
CBOR SenML uses integer map keys (Table 4) for all fields defined in RFC 8428; future extension labels use string keys only. String Values use CBOR major type 3 (definite-length text string); Data Values use CBOR major type 2 (definite-length byte string). Numeric values MAY use integers, floats, or CBOR Tag 4 decimal fractions, but SHOULD round-trip identically through IEEE double.
EXI SenML encodes the XML Schema structure into binary using strict schema mode by default; non-strict MAY be used to preserve extensions. The EXI schemaId 'a' identifies the RFC 8428 schema. Byte-aligned EXI mode is noted as feasible for constrained sensors that hard-code the encoding.
JSON SenML uses UTF-8 encoding only. String Values use RFC 8259 escape sequences. Data Values (vd field) are base64url-encoded (RFC 4648 Section 5 URL-safe alphabet) with padding omitted.
SenML defines 15 labeled fields across base and regular categories. CBOR uses integer map keys (negative integers for base fields, non-negative for regular); JSON uses the string label names as object member names. Key mappings: bn=-2, bt=-3, bu=-4, bv=-5, bs=-6, bver=-1, n=0, u=1, v=2, vs=3, vb=4, s=5, t=6, ut=7, vd=8.
XML SenML uses a 'sensml' root element containing 'senml' child elements; SenML fields are XML attributes. Only UTF-8 is allowed. Data Values are base64url-encoded with padding omitted. The schema namespace is 'urn:ietf:params:xml:ns:senml'.