--- 1/draft-ietf-core-senml-14.txt 2018-05-07 11:13:25.590833081 -0700 +++ 2/draft-ietf-core-senml-15.txt 2018-05-07 11:13:25.686835402 -0700 @@ -1,28 +1,28 @@ Network Working Group C. Jennings Internet-Draft Cisco Intended status: Standards Track Z. Shelby -Expires: October 4, 2018 ARM +Expires: November 8, 2018 ARM J. Arkko A. Keranen Ericsson C. Bormann Universitaet Bremen TZI - April 2, 2018 + May 7, 2018 - Media Types for Sensor Measurement Lists (SenML) - draft-ietf-core-senml-14 + Sensor Measurement Lists (SenML) + draft-ietf-core-senml-15 Abstract - This specification defines media types for representing simple sensor + This specification defines a format for representing simple sensor measurements and device parameters in the 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 CoAP to transport the measurements of the sensor or to be configured. Status of This Memo @@ -33,21 +33,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on October 4, 2018. + This Internet-Draft will expire on November 8, 2018. Copyright Notice Copyright (c) 2018 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 (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -59,75 +59,83 @@ Table of Contents 1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Requirements and Design Goals . . . . . . . . . . . . . . . . 4 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 4. SenML Structure and Semantics . . . . . . . . . . . . . . . . 6 4.1. Base Fields . . . . . . . . . . . . . . . . . . . . . . . 6 4.2. Regular Fields . . . . . . . . . . . . . . . . . . . . . 7 4.3. SenML Labels . . . . . . . . . . . . . . . . . . . . . . 7 - 4.4. Considerations . . . . . . . . . . . . . . . . . . . . . 8 - 4.5. Resolved Records . . . . . . . . . . . . . . . . . . . . 10 - 4.6. Associating Meta-data . . . . . . . . . . . . . . . . . . 10 - 4.7. Configuration and Actuation usage . . . . . . . . . . . . 11 - 5. JSON Representation (application/senml+json) . . . . . . . . 11 - 5.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 12 - 5.1.1. Single Datapoint . . . . . . . . . . . . . . . . . . 12 - 5.1.2. Multiple Datapoints . . . . . . . . . . . . . . . . . 12 - 5.1.3. Multiple Measurements . . . . . . . . . . . . . . . . 13 - 5.1.4. Resolved Data . . . . . . . . . . . . . . . . . . . . 14 - 5.1.5. Multiple Data Types . . . . . . . . . . . . . . . . . 15 - 5.1.6. Collection of Resources . . . . . . . . . . . . . . . 15 - 5.1.7. Setting an Actuator . . . . . . . . . . . . . . . . . 16 - 6. CBOR Representation (application/senml+cbor) . . . . . . . . 17 - 7. XML Representation (application/senml+xml) . . . . . . . . . 19 - 8. EXI Representation (application/senml-exi) . . . . . . . . . 21 - 9. Fragment Identification Methods . . . . . . . . . . . . . . . 24 - 9.1. Fragment Identification Examples . . . . . . . . . . . . 24 - 10. Usage Considerations . . . . . . . . . . . . . . . . . . . . 25 - 11. CDDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 - 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 - 12.1. Units Registry . . . . . . . . . . . . . . . . . . . . . 27 - 12.2. SenML Label Registry . . . . . . . . . . . . . . . . . . 31 - 12.3. Media Type Registrations . . . . . . . . . . . . . . . . 32 - 12.3.1. senml+json Media Type Registration . . . . . . . . . 33 - 12.3.2. sensml+json Media Type Registration . . . . . . . . 34 - 12.3.3. senml+cbor Media Type Registration . . . . . . . . . 35 - 12.3.4. sensml+cbor Media Type Registration . . . . . . . . 36 - 12.3.5. senml+xml Media Type Registration . . . . . . . . . 37 - 12.3.6. sensml+xml Media Type Registration . . . . . . . . . 39 - 12.3.7. senml-exi Media Type Registration . . . . . . . . . 40 - 12.3.8. sensml-exi Media Type Registration . . . . . . . . . 41 - 12.4. XML Namespace Registration . . . . . . . . . . . . . . . 42 - 12.5. CoAP Content-Format Registration . . . . . . . . . . . . 42 - 13. Security Considerations . . . . . . . . . . . . . . . . . . . 43 - 14. Privacy Considerations . . . . . . . . . . . . . . . . . . . 43 - 15. Acknowledgement . . . . . . . . . . . . . . . . . . . . . . . 44 - 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 44 - 16.1. Normative References . . . . . . . . . . . . . . . . . . 44 - 16.2. Informative References . . . . . . . . . . . . . . . . . 46 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 48 + 4.4. Extensibility . . . . . . . . . . . . . . . . . . . . . . 8 + 4.5. Records and Their Fields . . . . . . . . . . . . . . . . 9 + 4.5.1. Names . . . . . . . . . . . . . . . . . . . . . . . . 9 + 4.5.2. Units . . . . . . . . . . . . . . . . . . . . . . . . 9 + 4.5.3. Time . . . . . . . . . . . . . . . . . . . . . . . . 10 + 4.5.4. Values . . . . . . . . . . . . . . . . . . . . . . . 10 + 4.6. Resolved Records . . . . . . . . . . . . . . . . . . . . 11 + 4.7. Associating Meta-data . . . . . . . . . . . . . . . . . . 11 + 4.8. Sensor Streaming Measurement Lists (SensML) . . . . . . . 12 + 4.9. Configuration and Actuation usage . . . . . . . . . . . . 12 + 5. JSON Representation (application/senml+json) . . . . . . . . 12 + 5.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 13 + 5.1.1. Single Datapoint . . . . . . . . . . . . . . . . . . 14 + 5.1.2. Multiple Datapoints . . . . . . . . . . . . . . . . . 14 + 5.1.3. Multiple Measurements . . . . . . . . . . . . . . . . 15 + 5.1.4. Resolved Data . . . . . . . . . . . . . . . . . . . . 16 + 5.1.5. Multiple Data Types . . . . . . . . . . . . . . . . . 17 + 5.1.6. Collection of Resources . . . . . . . . . . . . . . . 17 + 5.1.7. Setting an Actuator . . . . . . . . . . . . . . . . . 17 + 6. CBOR Representation (application/senml+cbor) . . . . . . . . 18 + 7. XML Representation (application/senml+xml) . . . . . . . . . 20 + 8. EXI Representation (application/senml-exi) . . . . . . . . . 22 + 9. Fragment Identification Methods . . . . . . . . . . . . . . . 25 + 9.1. Fragment Identification Examples . . . . . . . . . . . . 25 + 9.2. Fragment Identification for the XML and EXI Formats . . . 26 + 10. Usage Considerations . . . . . . . . . . . . . . . . . . . . 26 + 11. CDDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 + 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 + 12.1. Units Registry . . . . . . . . . . . . . . . . . . . . . 29 + 12.2. SenML Label Registry . . . . . . . . . . . . . . . . . . 33 + 12.3. Media Type Registrations . . . . . . . . . . . . . . . . 34 + 12.3.1. senml+json Media Type Registration . . . . . . . . . 35 + 12.3.2. sensml+json Media Type Registration . . . . . . . . 36 + 12.3.3. senml+cbor Media Type Registration . . . . . . . . . 37 + 12.3.4. sensml+cbor Media Type Registration . . . . . . . . 38 + 12.3.5. senml+xml Media Type Registration . . . . . . . . . 39 + 12.3.6. sensml+xml Media Type Registration . . . . . . . . . 41 + 12.3.7. senml-exi Media Type Registration . . . . . . . . . 42 + 12.3.8. sensml-exi Media Type Registration . . . . . . . . . 43 + 12.4. XML Namespace Registration . . . . . . . . . . . . . . . 44 + 12.5. CoAP Content-Format Registration . . . . . . . . . . . . 44 + 13. Security Considerations . . . . . . . . . . . . . . . . . . . 45 + 14. Privacy Considerations . . . . . . . . . . . . . . . . . . . 46 + 15. Acknowledgement . . . . . . . . . . . . . . . . . . . . . . . 46 + 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 46 + 16.1. Normative References . . . . . . . . . . . . . . . . . . 46 + 16.2. Informative References . . . . . . . . . . . . . . . . . 49 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 51 1. Overview Connecting sensors to the Internet is not new, and there have been many protocols designed to facilitate it. This specification defines - new media types for carrying simple sensor information in a protocol - such as HTTP [RFC7230] or CoAP [RFC7252]. This format was designed - so that processors with very limited capabilities could easily encode - a sensor measurement into the media type, while at the same time a - server parsing the data could relatively efficiently collect a large - number of sensor measurements. SenML can be used for a variety of - data flow models, most notably data feeds pushed from a sensor to a - collector, and the web resource model where the sensor is requested - as a resource representation (e.g., "GET /sensor/temperature"). + a format and media types for carrying simple sensor information in a + protocol such as HTTP [RFC7230] or CoAP [RFC7252]. The SenML format + is designed so that processors with very limited capabilities could + easily encode a sensor measurement into the media type, while at the + same time a server parsing the data could relatively efficiently + collect a large number of sensor measurements. SenML can be used for + a variety of data flow models, most notably data feeds pushed from a + sensor to a collector, and the web resource model where the sensor is + requested as a resource representation (e.g., "GET /sensor/ + temperature"). There are many types of more complex measurements and measurements that this media type would not be suitable for. SenML strikes a balance between having some information about the sensor carried with the sensor data so that the data is self describing but it also tries to make that a fairly minimal set of auxiliary information for efficiency reason. Other information about the sensor can be discovered by other methods such as using the CoRE Link Format [RFC6690]. @@ -206,22 +213,22 @@ relative to the Unix epoch (1970-01-01T00:00Z in UTC time) and the time is counted same way as the Portable Operating System Interface (POSIX) "seconds since the epoch" [TIME_T]. Values of 0 or less represent a relative time in the past from the current time. A simple sensor with no absolute wall clock time might take a measurement every second, batch up 60 of them, and then send the batch to a server. It would include the relative time each measurement was made compared to the time the batch was sent in each SenML Record. The server might have accurate NTP time and use the time it received the data, and the relative offset, to replace the - times in the SenML with absolute times before saving the SenML Pack - in a document database. + times in the SenML with absolute times before saving the SenML + information in a document database. 3. 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. This document also uses the following terms: @@ -230,37 +237,45 @@ presented using the SenML data model. SenML Pack: One or more SenML Records in an array structure. SenML Label: A short name used in SenML Records to denote different SenML fields (e.g., "v" for "value"). SenML Field: A component of a record that associates a value to a SenML Label for this record. + SensML: Sensor Streaming Measurement List (see Section 4.8). + + SensML Stream: One or more SenML Records to be processed as a + stream. + This document uses the terms "attribute" and "tag" where they occur with the underlying technologies (XML, CBOR [RFC7049], and Link Format [RFC6690]), not for SenML concepts per se. Note that "attribute" has been widely used previously as a synonym for SenML "field", though. + All comparisons of text strings are performed byte-by-byte (and + therefore necessarily case-sensitive). + 4. SenML Structure and Semantics Each SenML Pack carries a single array that represents a set of measurements and/or parameters. This array contains a series of SenML Records with several fields described below. There are two - kinds of fields: base and regular. The base fields can be included - in any SenML Record and they apply to the entries in the Record. - Each base field also applies to all Records after it up to, but not - including, the next Record that has that same base field. All base - fields are optional. Regular fields can be included in any SenML - Record and apply only to that Record. + kinds of fields: base and regular. Both the base fields and the + regular fields can be included in any SenML Record. The base fields + apply to the entries in the Record and also to all Records after it + up to, but not including, the next Record that has that same base + field. All base fields are optional. Regular fields can be included + in any SenML Record and apply only to that Record. 4.1. Base Fields Base Name: This is a string that is prepended to the names found in the entries. Base Time: A base time that is added to the time found in an entry. Base Unit: A base unit that is assumed for all entries, unless otherwise indicated. If a record does not contain a Unit value, @@ -293,20 +308,21 @@ Value: Value of the entry. Optional if a Sum value is present, otherwise required. Values are represented using basic data types. This specification defines floating point numbers ("v" field for "Value"), booleans ("vb" for "Boolean Value"), strings ("vs" for "String Value") and binary data ("vd" for "Data Value"). Exactly one value field MUST appear unless there is Sum field in which case it is allowed to have no Value field. Sum: Integrated sum of the values over time. Optional. This field is in the unit specified in the Unit value multiplied by seconds. + For historical reason it is named sum instead of integral. Time: Time when value was recorded. Optional. Update Time: Period of time in seconds that represents the maximum time before this sensor will provide an updated reading for a measurement. Optional. This can be used to detect the failure of sensors or communications path from the sensor. 4.3. SenML Labels @@ -328,90 +344,123 @@ | String Value | vs | 3 | String | string | | Boolean Value | vb | 4 | Boolean | boolean | | Data Value | vd | 8 | String (*) | string (*) | | Value Sum | s | 5 | Number | double | | Time | t | 6 | Number | double | | Update Time | ut | 7 | Number | double | +---------------+-------+------------+------------+------------+ Table 1: SenML Labels - Data Value is base64 encoded string with URL safe alphabet as defined - in Section 5 of [RFC4648], with padding omitted. + (*) Data Value is base64 encoded string with URL safe alphabet as + defined in Section 5 of [RFC4648], with padding omitted. For details of the JSON representation see Section 5, for the CBOR Section 6, and for the XML Section 7. -4.4. Considerations +4.4. Extensibility The SenML format can be extended with further custom fields. Both new base and regular fields are allowed. See Section 12.2 for details. Implementations MUST ignore fields they don't recognize unless that field has a label name that ends with the '_' character in which case an error MUST be generated. All SenML Records in a Pack MUST have the same version number. This is typically done by adding a Base Version field to only the first - Record in the Pack. + Record in the Pack, or by using the default value. Systems reading one of the objects MUST check for the Version field. If this value is a version number larger than the version which the - system understands, the system SHOULD NOT use this object. This - allows the version number to indicate that the object contains - structure or semantics that is different from what is defined in the - present document beyond just making use of the extension points - provided here. New version numbers can only be defined in an RFC - that updates this specification or it successors. + system understands, the system MUST NOT use this object. This allows + the version number to indicate that the object contains structure or + semantics that is different from what is defined in the present + document beyond just making use of the extension points provided + here. New version numbers can only be defined in an RFC that updates + this specification or it successors. + +4.5. Records and Their Fields + +4.5.1. Names The Name value is concatenated to the Base Name value to yield the name of the sensor. The resulting concatenated name needs to uniquely identify and differentiate the sensor from all others. The concatenated name MUST consist only of characters out of the set "A" to "Z", "a" to "z", "0" to "9", "-", ":", ".", "/", and "_"; furthermore, it MUST start with a character out of the set "A" to "Z", "a" to "z", or "0" to "9". This restricted character set was chosen so that concatenated names can be used directly within various URI schemes (including segments of an HTTP path with no special - encoding) and can be used directly in many databases and analytic - systems. [RFC5952] contains advice on encoding an IPv6 address in a - name. See Section 14 for privacy considerations that apply to the - use of long-term stable unique identifiers. + encoding; note that a name that contains "/" characters maps into + multiple URI path segments) and can be used directly in many + databases and analytic systems. [RFC5952] contains advice on + encoding an IPv6 address in a name. See Section 14 for privacy + considerations that apply to the use of long-term stable unique + identifiers. Although it is RECOMMENDED that concatenated names are represented as URIs [RFC3986] or URNs [RFC8141], the restricted character set specified above puts strict limits on the URI schemes and URN namespaces that can be used. As a result, implementers need to take care in choosing the naming scheme for concatenated names, because such names both need to be unique and need to conform to the restricted character set. One approach is to include a bit string - that has guaranteed uniqueness (such as a 1-wire address). Some of - the examples within this document use the device URN namespace as - specified in [I-D.ietf-core-dev-urn]. UUIDs [RFC4122] are another - way to generate a unique name. However, the restricted character set - does not allow the use of many URI schemes, such as the 'tag' scheme - [RFC4151] and the 'ni' scheme [RFC6920], in names as such. The use - of URIs with characters incompatible with this set, and possible - mapping rules between the two, are outside of the scope of the - present document. + that has guaranteed uniqueness (such as a 1-wire address [AN1796]). + Some of the examples within this document use the device URN + namespace as specified in [I-D.ietf-core-dev-urn]. UUIDs [RFC4122] + are another way to generate a unique name. However, the restricted + character set does not allow the use of many URI schemes, such as the + 'tag' scheme [RFC4151] and the 'ni' scheme [RFC6920], in names as + such. The use of URIs with characters incompatible with this set, + and possible mapping rules between the two, are outside of the scope + of the present document. + +4.5.2. Units If the Record has no Unit, the Base Unit is used as the Unit. Having - no Unit and no Base Unit is allowed. + no Unit and no Base Unit is allowed; any information that may be + required about units applicable to the value then needs to be + provided by the application context. + +4.5.3. Time If either the Base Time or Time value is missing, the missing field is considered to have a value of zero. The Base Time and Time values are added together to get the time of measurement. A time of zero indicates that the sensor does not know the absolute time and the measurement was made roughly "now". A negative value is used to indicate seconds in the past from roughly "now". A positive value is used to indicate the number of seconds, excluding leap seconds, since the start of the year 1970 in UTC. + Obviously, "now"-referenced SenML records are only useful within a + specific communication context (e.g., based on information on when + the SenML pack, or a specific record in a SensML stream, was sent) or + together with some other context information that can be used for + deriving a meaning of "now"; the expectation for any archival use is + that they will be processed into UTC-referenced records before that + context would cease to be available. This specification deliberately + leaves the accuracy of "now" very vague as it is determined by the + overall systems that use SenML. In a system where a sensor without + wall-clock time sends a SenML record with a "now"-referenced time + over a high speed RS 485 link to an embedded system with accurate + time that resolves "now" based on the time of reception, the + resulting time uncertainty could be within 1 ms. At the other + extreme, a deployment that sends SenML wind speed readings over a LEO + satellite link from a mountain valley might have resulting reception + time values that are easily a dozen minutes off the actual time of + the sensor reading, with the time uncertainty depending on satellite + locations and conditions. + +4.5.4. Values + If only one of the Base Sum or Sum value is present, the missing field is considered to have a value of zero. The Base Sum and Sum values are added together to get the sum of measurement. If neither the Base Sum or Sum are present, then the measurement does not have a sum value. If the Base Value or Value is not present, the missing field(s) are considered to have a value of zero. The Base Value and Value are added together to get the value of the measurement. @@ -421,58 +470,74 @@ of the measurement. In summary, the structure of a SenML record is laid out to support a single measurement per record. If multiple data values are measured at the same time (e.g., air pressure and altitude), they are best kept as separate records linked through their Time value; this is even true where one of the data values is more "meta" than others (e.g., describes a condition that influences other measurements at the same time). -4.5. Resolved Records +4.6. Resolved Records Sometimes it is useful to be able to refer to a defined normalized format for SenML records. This normalized format tends to get used for big data applications and intermediate forms when converting to - other formats. + other formats. Also, if SenML Records are used outside of a SenML + Pack, they need to be resolved first to ensure applicable base values + are applied. A SenML Record is referred to as "resolved" if it does not contain any base values, i.e., labels starting with the character 'b', except for Version fields (see below), and has no relative times. To - resolve the records, the base values of the SenML Pack (if any) are - applied to the Record. That is, name and base name are concatenated, - base time is added to the time of the Record, if the Record did not - contain Unit the Base Unit is applied to the record, etc. In - addition the records need to be in chronological order. An example - of this is show in Section 5.1.4. + resolve the Records, the applicable base values of the SenML Pack (if + any) are applied to the Record. That is, for the base values in the + Record or before the Record in the Pack, name and base name are + concatenated, base time is added to the time of the Record, if the + Record did not contain Unit the Base Unit is applied to the record, + etc. In addition the records need to be in chronological order in + the Pack. An example of this is shown in Section 5.1.4. The Version field MUST NOT be present in resolved records if the SenML version defined in this document is used and MUST be present otherwise in all the resolved SenML Records. Future specification that defines new base fields need to specify how the field is resolved. -4.6. Associating Meta-data +4.7. Associating Meta-data SenML is designed to carry the minimum dynamic information about measurements, and for efficiency reasons does not carry significant static meta-data about the device, object or sensors. Instead, it is assumed that this meta-data is carried out of band. For web resources using SenML Packs, this meta-data can be made available using the CoRE Link Format [RFC6690]. The most obvious use of this link format is to describe that a resource is available in a SenML format in the first place. The relevant media type indicator is included in the Content-Type (ct=) link attribute (which is defined for the Link Format in Section 7.2.1 of [RFC7252]). -4.7. Configuration and Actuation usage +4.8. Sensor Streaming Measurement Lists (SensML) + + In some usage scenarios of SenML, the implementations store or + transmit SenML in a stream-like fashion, where data is collected over + time and continuously added to the object. This mode of operation is + optional, but systems or protocols using SenML in this fashion MUST + specify that they are doing this. SenML defines separate media types + to indicate Sensor Streaming Measurement Lists (SensML) for this + usage (see Section 12.3.2). In this situation, the SensML stream can + be sent and received in a partial fashion, i.e., a measurement entry + can be read as soon as the SenML Record is received and does not have + to wait for the full SensML Stream to be complete. + +4.9. Configuration and Actuation usage SenML can also be used for configuring parameters and controlling actuators. When a SenML Pack is sent (e.g., using a HTTP/CoAP POST or PUT method) and the semantics of the target are such that SenML is interpreted as configuration/actuation, SenML Records are interpreted as a request to change the values of given (sub)resources (given as names) to given values at the given time(s). The semantics of the target resource supporting this usage can be described, e.g., using [I-D.ietf-core-interfaces]. Examples of actuation usage are shown in Section 5.1.7. @@ -556,35 +620,24 @@ "bu":"A","bver":5, "n":"voltage","u":"V","v":120.1}, {"n":"current","t":-5,"v":1.2}, {"n":"current","t":-4,"v":1.3}, {"n":"current","t":-3,"v":1.4}, {"n":"current","t":-2,"v":1.5}, {"n":"current","t":-1,"v":1.6}, {"n":"current","v":1.7} ] - Note that in some usage scenarios of SenML the implementations MAY - store or transmit SenML in a stream-like fashion, where data is - collected over time and continuously added to the object. This mode - of operation is optional, but systems or protocols using SenML in - this fashion MUST specify that they are doing this. SenML defines - separate media types to indicate Sensor Streaming Measurement Lists - (SensML) for this usage (see Section 12.3.2). In this situation the - SensML stream can be sent and received in a partial fashion, i.e., a - measurement entry can be read as soon as the SenML Record is received - and not have to wait for the full SensML Stream to be complete. - - For instance, the following stream of measurements may be sent via a - long lived HTTP POST from the producer of a SensML to the consumer of - that, and each measurement object may be reported at the time it was - measured: + As an example of Sensor Streaming Measurement Lists (SensML), the + following stream of measurements may be sent via a long lived HTTP + POST from the producer of the stream to its consumer, and each + measurement object may be reported at the time it was measured: [ {"bn":"urn:dev:ow:10e2073a01080063","bt":1.320067464e+09, "bu":"%RH","v":21.2}, {"t":10,"v":21.3}, {"t":20,"v":21.4}, {"t":30,"v":21.4}, {"t":40,"v":21.5}, {"t":50,"v":21.5}, {"t":60,"v":21.5}, @@ -763,21 +815,23 @@ o Characters in the String Value are encoded using a definite length text string (type 3). Octets in the Data Value are encoded using a definite length byte string (type 2). o For compactness, the CBOR representation uses integers for the labels, as defined in Table 4. This table is conclusive, i.e., there is no intention to define any additional integer map keys; any extensions will use string map keys. This allows translators converting between CBOR and JSON representations to convert also - all future labels without needing to update implementations. + all future labels without needing to update implementations. The + base values are given negative CBOR labels and others non-negative + labels. +---------------+-------+------------+ | Name | Label | CBOR Label | +---------------+-------+------------+ | Version | bver | -1 | | Base Name | bn | -2 | | Base Time | bt | -3 | | Base Unit | bu | -4 | | Base Value | bv | -5 | | Base Sum | bs | -6 | @@ -1058,36 +1112,58 @@ The 3rd and 5th record can be selected with: coap://example.com/temp#rec=3,5 To select the Records from third to fifth, the 10th record, and all from 19th to the last: coap://example.com/temp#rec=3-5,10,19-* +9.2. Fragment Identification for the XML and EXI Formats + + In addition to the SenML Fragment Identifiers described above, with + the XML and EXI SenML formats also the syntax defined in the XPointer + element() Scheme [XPointerElement] of the XPointer Framework + [XPointerFramework] can be used. (This is required by [RFC7303] for + media types using the "+xml" structured syntax suffix. SenML allows + this for the EXI formats as well for consistency.) + + Note that fragment identifiers are available to the client side only; + they are not provided in transfer protocols such as CoAP or HTTP. + Thus, they cannot be used by the server in deciding which media type + to send. Where a server has multiple representations available for a + resource identified by a URI, it might send a JSON or CBOR + representation when the client was directed to use an XML/EXI + fragment identifier with this. Clients can prevent running into this + problem by explicitly requesting an XML or EXI media type (e.g., + using the CoAP Accept option) when XML/EXI-only fragment identifier + syntax is in use in the URI. + 10. Usage Considerations The measurements support sending both the current value of a sensor - as well as the an integrated sum. For many types of measurements, - the sum is more useful than the current value. For example, an - electrical meter that measures the energy a given computer uses will - typically want to measure the cumulative amount of energy used. This - is less prone to error than reporting the power each second and - trying to have something on the server side sum together all the - power measurements. If the network between the sensor and the meter - goes down over some period of time, when it comes back up, the - cumulative sum helps reflect what happened while the network was - down. A meter like this would typically report a measurement with - the unit set to watts, but it would put the sum of energy used in the - "s" field of the measurement. It might optionally include the - current power in the "v" field. + as well as an integrated sum. For many types of measurements, the + sum is more useful than the current value. For historical reasons, + this field is called "sum" instead of "integral" which would more + accurately describe its function. For example, an electrical meter + that measures the energy a given computer uses will typically want to + measure the cumulative amount of energy used. This is less prone to + error than reporting the power each second and trying to have + something on the server side sum together all the power measurements. + If the network between the sensor and the meter goes down over some + period of time, when it comes back up, the cumulative sum helps + reflect what happened while the network was down. A meter like this + would typically report a measurement with the unit set to watts, but + it would put the sum of energy used in the "s" field of the + measurement. It might optionally include the current power in the + "v" field. While the benefit of using the integrated sum is fairly clear for measurements like power and energy, it is less obvious for something like temperature. Reporting the sum of the temperature makes it easy to compute averages even when the individual temperature values are not reported frequently enough to compute accurate averages. Implementers are encouraged to report the cumulative sum as well as the raw value of a given sensor. Applications that use the cumulative sum values need to understand @@ -1105,20 +1181,26 @@ 3. Applications cannot make assumptions about when the device started accumulating values into the sum. Typically applications can make some assumptions about specific sensors that will allow them to deal with these problems. A common assumption is that for sensors whose measurement values are always positive, the sum should never get smaller; so if the sum does get smaller, the application will know that one of the situations listed above has happened. + Despite the name sum, the sum field is not useful for applications + that maintain a running count of the number of times that an event + happened or keeping track of a counter such as the total number of + bytes sent on an interface. Data like that can be sent directly in + the value field. + 11. CDDL As a convenient reference, the JSON and CBOR representations can be described with the common CDDL [I-D.ietf-cbor-cddl] specification in Figure 1 (informative). SenML-Pack = [1* record] record = { ? bn => tstr, ; Base Name @@ -1355,68 +1437,65 @@ Units of Measure [UCUM]. 12.2. SenML Label Registry IANA will create a new registry for SenML labels. The initial content of the registry is: +--------------+-------+----+-----------+----------+----+-----------+ | Name | Label | CL | JSON Type | XML Type | EI | Reference | +--------------+-------+----+-----------+----------+----+-----------+ - | Base Name | bn | -2 | String | string | a | RFCXXXX | - | Base Time | bt | -3 | Number | double | a | RFCXXXX | - | Base Unit | bu | -4 | String | string | a | RFCXXXX | - | Base Value | bv | -5 | Number | double | a | RFCXXXX | - | Base Sum | bs | -6 | Number | double | a | RFCXXXX | - | Base Version | bver | -1 | Number | int | a | RFCXXXX | - | Name | n | 0 | String | string | a | RFCXXXX | - | Unit | u | 1 | String | string | a | RFCXXXX | - | Value | v | 2 | Number | double | a | RFCXXXX | - | String Value | vs | 3 | String | string | a | RFCXXXX | - | Boolean | vb | 4 | Boolean | boolean | a | RFCXXXX | + | Base Name | bn | -2 | String | string | a | RFC-AAAA | + | Base Time | bt | -3 | Number | double | a | RFC-AAAA | + | Base Unit | bu | -4 | String | string | a | RFC-AAAA | + | Base Value | bv | -5 | Number | double | a | RFC-AAAA | + | Base Sum | bs | -6 | Number | double | a | RFC-AAAA | + | Base Version | bver | -1 | Number | int | a | RFC-AAAA | + | Name | n | 0 | String | string | a | RFC-AAAA | + | Unit | u | 1 | String | string | a | RFC-AAAA | + | Value | v | 2 | Number | double | a | RFC-AAAA | + | String Value | vs | 3 | String | string | a | RFC-AAAA | + | Boolean | vb | 4 | Boolean | boolean | a | RFC-AAAA | | Value | | | | | | | - | Data Value | vd | 8 | String | string | a | RFCXXXX | - | Value Sum | s | 5 | Number | double | a | RFCXXXX | - | Time | t | 6 | Number | double | a | RFCXXXX | - | Update Time | ut | 7 | Number | double | a | RFCXXXX | + | Data Value | vd | 8 | String | string | a | RFC-AAAA | + | Value Sum | s | 5 | Number | double | a | RFC-AAAA | + | Time | t | 6 | Number | double | a | RFC-AAAA | + | Update Time | ut | 7 | Number | double | a | RFC-AAAA | +--------------+-------+----+-----------+----------+----+-----------+ Table 7: IANA Registry for SenML Labels, CL = CBOR Label, EI = EXI ID This is the same table as Table 1, with notes removed, and with columns added for the information that is all the same for this initial set of registrations, but will need to be supplied with a different value for new registrations. - Note to RFC Editor. Please replace RFCXXXX with the number for this - RFC. - All new entries must define the Label Name, Label, and XML Type but the CBOR labels SHOULD be left empty as CBOR will use the string encoding for any new labels. The EI column contains the EXI schemaId value of the first Schema which includes this label or is empty if this label was not intended for use with EXI. The Note field SHOULD contain information about where to find out more information about this label. The JSON, CBOR, and EXI types are derived from the XML type. All XML numeric types such as double, float, integer and int become a JSON Number. XML boolean and string become a JSON Boolean and String respectively. CBOR represents numeric values with a CBOR type that does not lose any information from the JSON value. EXI uses the XML types. New entries can be added to the registration by Expert Review as defined in [RFC8126]. Experts should exercise their own good judgment but need to consider that shorter labels should have more strict review. New entries should not be made that counteract the - advice at the end of Section 4.4. + advice at the end of Section 4.5.4. All new SenML labels that have "base" semantics (see Section 4.1) MUST start with the character 'b'. Regular labels MUST NOT start with that character. All new SenML labels with Value semantics (see Section 4.2) MUST have "Value" in their (long form) name. Extensions that add a label that is intended for use with XML need to create a new RelaxNG scheme that includes all the labels in the IANA registry. @@ -1428,24 +1507,40 @@ values SHOULD be updated in the IANA table to have their ID set to this new schemaId value. Extensions that are mandatory to understand to correctly process the Pack MUST have a label name that ends with the '_' character. 12.3. Media Type Registrations The following registrations are done following the procedure specified in [RFC6838] and [RFC7303]. This document registers media - types for each serialization format of SenML (JSON, CBOR, and EXI) - and also media types for the same formats of the streaming use - (SensML). Clipboard formats are defined for the JSON and XML form of - lists but do not make sense for streams or other formats. + types for each serialization format of SenML (JSON, CBOR, XML, and + EXI) and also a corresponding set of media types for the streaming + use (SensML, see Section 4.8). Clipboard formats are defined for the + JSON and XML forms of SenML but not for streams or non-textual + formats. + + The reason there are both SenML and the streaming SensML formats is + that they are not the same data formats and they require separate + negotiation to understand if they are supported and which one is + being used. The non streaming format is required to have some sort + of end of pack syntax which indicates there will be no more records. + Many implementations that receive SenML wait for this end of pack + marker before processing any of the records. On the other hand, with + the streaming formats, it is explicitly not required to wait for this + end of pack marker. Many implementations that produce streaming + SensML will never send this end of pack marker so implementations + that receive streaming SensML can not wait for the end of pack marker + before they start processing the records. Given the SenML and + streaming SenML are different data formats, and the requirement for + separate negotiation, a media type for each one is needed. Note to RFC Editor - please remove this paragraph. Note that a request for media type review for senml+json was sent to the media- types@iana.org on Sept 21, 2010. A second request for all the types was sent on October 31, 2016. Please change all instances of RFC- AAAA with the RFC number of this document. 12.3.1. senml+json Media Type Registration Type name: application @@ -1899,59 +1993,73 @@ 12.5. CoAP Content-Format Registration IANA is requested to assign CoAP Content-Format IDs for the SenML media types in the "CoAP Content-Formats" sub-registry, within the "CoRE Parameters" registry [RFC7252]. IDs for the JSON, CBOR, and EXI Content-Formats are assigned from the "Expert Review" (0-255) range and for the XML Content-Format from the "IETF Review or IESG Approval" range. The assigned IDs are shown in Table 8. - +-------------------------+-----+ - | Media type | ID | - +-------------------------+-----+ - | application/senml+json | TBD | - | application/sensml+json | TBD | - | application/senml+cbor | TBD | - | application/sensml+cbor | TBD | - | application/senml-exi | TBD | - | application/sensml-exi | TBD | - | application/senml+xml | TBD | - | application/sensml+xml | TBD | - +-------------------------+-----+ + +-------------------------+----------+---------+-----------+ + | Media type | Encoding | ID | Reference | + +-------------------------+----------+---------+-----------+ + | application/senml+json | - | TBD:110 | RFC-AAAA | + | application/sensml+json | - | TBD:111 | RFC-AAAA | + | application/senml+cbor | - | TBD:112 | RFC-AAAA | + | application/sensml+cbor | - | TBD:113 | RFC-AAAA | + | application/senml-exi | - | TBD:114 | RFC-AAAA | + | application/sensml-exi | - | TBD:115 | RFC-AAAA | + | application/senml+xml | - | TBD:310 | RFC-AAAA | + | application/sensml+xml | - | TBD:311 | RFC-AAAA | + +-------------------------+----------+---------+-----------+ Table 8: CoAP Content-Format IDs 13. Security Considerations - Sensor data can contain a wide range of information ranging from - information that is very public, such as the outside temperature in a - given city, to very private information that requires integrity and - confidentiality protection, such as patient health information. The - SenML formats do not provide any security and instead rely on the - protocol that carries them to provide security. Applications using - SenML need to look at the overall context of how these media types - will be used to decide if the security is adequate. The SenML - formats defined by this specification do not contain any executable - content. However, future extensions could potentially embed - application specific executable content in the data. + Sensor data presented with SenML can contain a wide range of + information ranging from information that is very public, such as the + outside temperature in a given city, to very private information that + requires integrity and confidentiality protection, such as patient + health information. When SenML is used for configuration or + actuation, it can be used to change the state of systems and also + impact the physical world, e.g., by turning off a heater or opening a + lock. + + The SenML formats alone do not provide any security and instead rely + on the protocol that carries them to provide security. Applications + using SenML need to look at the overall context of how these formats + will be used to decide if the security is adequate. In particular + for sensitive sensor data and actuation use it is important to ensure + that proper security mechanisms are used. + + The SenML formats defined by this specification do not contain any + executable content. However, future extensions could potentially + embed application specific executable content in the data. + + SenML Records are intended to be interpreted in the context of any + applicable base values. If records become separated from the record + that establishes the base values, the data will be useless or, worse, + wrong. Care needs to be taken in keeping the integrity of a Pack + that contains unresolved SenML Records (see Section 4.6). See also Section 14. 14. Privacy Considerations - Sensor data can range from information with almost no security + Sensor data can range from information with almost no privacy considerations, such as the current temperature in a given city, to highly sensitive medical or location data. This specification provides no security protection for the data but is meant to be used - inside another container or transport protocol such as S/MIME - [RFC5751] or HTTP with TLS [RFC5246] that can provide integrity, + inside another container or transfer protocol such as S/MIME + [RFC5751] or HTTP with TLS [RFC2818] that can provide integrity, confidentiality, and authentication information about the source of the data. The name fields need to uniquely identify the sources or destinations of the values in a SenML Pack. However, the use of long-term stable unique identifiers can be problematic for privacy reasons [RFC6973], depending on the application and the potential of these identifiers to be used in correlation with other information. They should be used with care or avoided as for example described for IPv6 addresses in [RFC7721]. @@ -2056,22 +2164,38 @@ xml-20081126, November 2008, . [W3C.REC-xmlschema-1-20041028] Thompson, H., Beech, D., Maloney, M., and N. Mendelsohn, "XML Schema Part 1: Structures Second Edition", World Wide Web Consortium Recommendation REC-xmlschema-1-20041028, October 2004, . + [XPointerElement] + Grosso, P., Maler, E., Marsh, J., and N. Walsh, "XPointer + element() Scheme", W3C Recommendation REC-xptr-element, + March 2003, . + + [XPointerFramework] + Grosso, P., Maler, E., Marsh, J., and N. Walsh, "XPointer + Framework", W3C Recommendation REC-XPointer-Framework, + March 2003, + . + 16.2. Informative References + [AN1796] Linke, B., "Overview of 1-Wire Technology and Its Use", + June 2008, + . + [I-D.ietf-cbor-cddl] Birkholz, H., Vigano, C., and C. Bormann, "Concise data definition language (CDDL): a notational convention to express CBOR data structures", draft-ietf-cbor-cddl-02 (work in progress), February 2018. [I-D.ietf-core-dev-urn] Arkko, J., Jennings, C., and Z. Shelby, "Uniform Resource Names for Device Identifiers", draft-ietf-core-dev-urn-01 (work in progress), March 2018. @@ -2088,44 +2212,43 @@ Applications in Bridged Local Area Networks", 2011. [IEEE802.1ba-2011] IEEE, "IEEE Standard for Local and metropolitan area networks--Audio Video Bridging (AVB) Systems", 2011. [ISO-80000-5] "Quantities and units - Part 5: Thermodynamics", ISO 80000-5, Edition 1.0, May 2007. + [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, DOI 10.17487/ + RFC2818, May 2000, . + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, . [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally Unique IDentifier (UUID) URN Namespace", RFC 4122, DOI 10.17487/RFC4122, July 2005, . [RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", RFC 4151, DOI 10.17487/RFC4151, October 2005, . [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, "Transmission of IPv6 Packets over IEEE 802.15.4 Networks", RFC 4944, DOI 10.17487/RFC4944, September 2007, . - [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security - (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/ - RFC5246, August 2008, . - [RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet Mail Extensions (S/MIME) Version 3.2 Message Specification", RFC 5751, DOI 10.17487/RFC5751, January 2010, . [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 Address Text Representation", RFC 5952, DOI 10.17487/ RFC5952, August 2010, .