summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc9100.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc9100.txt')
-rw-r--r--doc/rfc/rfc9100.txt339
1 files changed, 339 insertions, 0 deletions
diff --git a/doc/rfc/rfc9100.txt b/doc/rfc/rfc9100.txt
new file mode 100644
index 0000000..3deb2df
--- /dev/null
+++ b/doc/rfc/rfc9100.txt
@@ -0,0 +1,339 @@
+
+
+
+
+Internet Engineering Task Force (IETF) C. Bormann
+Request for Comments: 9100 Universität Bremen TZI
+Updates: 8428 August 2021
+Category: Standards Track
+ISSN: 2070-1721
+
+
+ Sensor Measurement Lists (SenML) Features and Versions
+
+Abstract
+
+ This short document updates RFC 8428, "Sensor Measurement Lists
+ (SenML)", by specifying the use of independently selectable "SenML
+ Features" and mapping them to SenML version numbers.
+
+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/rfc9100.
+
+Copyright Notice
+
+ Copyright (c) 2021 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
+ 1.1. Terminology
+ 2. Feature Codes and the Version Number
+ 2.1. Discussion
+ 2.2. Updating Section 4.4 of RFC 8428
+ 3. Features: Reserved0, Reserved1, Reserved2, Reserved3
+ 4. Feature: Secondary Units
+ 5. Security Considerations
+ 6. IANA Considerations
+ 7. References
+ 7.1. Normative References
+ 7.2. Informative References
+ Acknowledgements
+ Author's Address
+
+1. Introduction
+
+ The Sensor Measurement Lists (SenML) specification [RFC8428] provides
+ a version number that is initially set to 10, without further
+ specification on the way to make use of different version numbers.
+
+ The common idea of using a version number to indicate the evolution
+ of an interchange format generally assumes an incremental progression
+ of the version number as the format accretes additional features over
+ time. However, in the case of SenML, it is expected that the likely
+ evolution will be for independently selectable capability _features_
+ to be added to the basic specification that is indicated by version
+ number 10. To support this model, this document repurposes the
+ single version number accompanying a pack of SenML records so that it
+ is interpreted as a bitmap that indicates the set of features a
+ recipient would need to have implemented to be able to process the
+ pack.
+
+ This short document specifies the use of SenML Features and maps them
+ to SenML version number space, updating [RFC8428].
+
+1.1. 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.
+
+ Where bit arithmetic is explained, this document uses the notation
+ familiar from the programming language C [C], including the "0b"
+ prefix for binary numbers defined in Section 5.13.2 of the C++
+ language standard [CPLUSPLUS], except that superscript notation
+ (example for two to the power of 64: 2^64) denotes exponentiation; in
+ the plain text version of this document, superscript notation is
+ rendered in paragraph text by C-incompatible surrogate notation as
+ seen in this example, and in display math by a crude plain text
+ representation, as is the sum (Sigma) sign.
+
+2. Feature Codes and the Version Number
+
+ The present specification defines "SenML Features", each identified
+ by a "feature name" (a text string) and a "feature code" (an unsigned
+ integer less than 53).
+
+ The specific version of a SenML pack is composed of a set of
+ features. The SenML version number ("bver" field) is then a bitmap
+ of these features represented as an unsigned integer, specifically
+ the sum of, for each feature present, two taken to the power of the
+ feature code of that feature (Figure 1).
+
+ __ 52 fc
+ version = \ present(fc) ⋅ 2
+ /__ fc = 0
+
+ Figure 1: Feature Bitmap as a Sum (Sigma Symbol) of Feature Bits
+
+ where present(fc) is 1 if the feature with the feature code "fc" is
+ present, 0 otherwise. (The expression 2^fc can be implemented as "1
+ << fc" in C and related languages.)
+
+2.1. Discussion
+
+ Representing features as a bitmap within a number is quite efficient
+ as long as feature codes are sparingly allocated (see also
+ Section 6).
+
+ Compatibility with the existing SenML version number, 10 decimal
+ (0b1010), requires reserving four of the least significant bit
+ positions for the base version as described in Section 3. There is
+ an upper limit to the range of the integer numbers that can be
+ represented in all SenML representations: practical JSON limits this
+ to 2^53-1 [RFC7493]. This means the feature codes 4 to 52 are
+ available, one of which is taken by the feature defined in Section 4,
+ leaving 48 for allocation. (The current version 10 (with all other
+ feature codes unset) can be visualized as
+ "0b00000000000000000000000000000000000000000000000001010".) For a
+ lifetime of this scheme of several decades, approximately two feature
+ codes per year or fewer should be allocated. Note that less
+ generally applicable features can always be communicated via fields
+ labeled with names that end with the "_" character ("must-understand
+ fields"). See Section 4.4 of [RFC8428] for details.
+
+ Most representations visible to engineers working with SenML will use
+ decimal numbers. For instance, 26 (0b11010, 0x1a) denotes a version
+ that adds the "Secondary Units" feature (Section 4). This is
+ slightly unwieldy but will be quickly memorized in practice.
+
+ As a general observation, ending up over time with dozens of
+ individually selectable optional extensions may lead to too many
+ variants of what is supported by different implementations, reducing
+ interoperability. So, in practice, it is still desirable to batch up
+ extensions that are expected to be supported together into a single
+ feature bit, leading to a sort of hybrid between completely
+ independent extensions and a linear version scheme. This is also
+ another reason why a space of 48 remaining feature codes should
+ suffice for a while.
+
+2.2. Updating Section 4.4 of RFC 8428
+
+ The last paragraph of Section 4.4 of [RFC8428] may be read to give
+ the impression that SenML version numbers are totally ordered, i.e.,
+ that an implementation that understands version n also always
+ understands all versions k < n. If this ever was true for SenML
+ versions before 10, it certainly is no longer true with this
+ specification.
+
+ Any SenML pack that sets feature bits beyond the first four will lead
+ to a version number that actually is greater than 10, so the
+ requirement in Section 4.4 of [RFC8428] will prevent false
+ interoperability with version 10 implementations.
+
+ Implementations that do implement feature bits beyond the first four,
+ i.e., versions greater than 10, will instead need to perform a
+ bitwise comparison of the feature bitmap as described in this
+ specification and ensure that all features indicated are understood
+ before using the pack. For example, an implementation that
+ implements basic SenML (version number 10) plus only a future feature
+ code 5 will accept version number 42, but it would not be able to
+ work with a pack indicating version number 26 (base specification
+ plus feature code 4). (If the implementation _requires_ feature code
+ 5 without being backwards compatible, it will accept 42, but not 10.)
+
+3. Features: Reserved0, Reserved1, Reserved2, Reserved3
+
+ For SenML version 10 as described in [RFC8428], the feature codes 0
+ to 3 are already in use. Reserved1 (1) and Reserved3 (3) are always
+ present, and the features Reserved0 (0) and Reserved2 (2) are always
+ absent, i.e., the four least significant bits set to 0b1010 indicate
+ a version number of 10 if no other feature is in use. These four
+ reserved feature codes are not to be used with any more specific
+ semantics except in a specification that updates the present
+ specification. (Note that Reserved0 and Reserved2 could be used in
+ such a specification in a way similar to that of feature codes 4 to
+ 52 in the present specification.)
+
+4. Feature: Secondary Units
+
+ The feature "Secondary Units" (code number 4) indicates that
+ secondary unit names [RFC8798] MAY be used in the "u" field of SenML
+ records in addition to the primary unit names already allowed by
+ [RFC8428].
+
+ Note that the most basic use of this feature simply sets the SenML
+ version number to 26 (10 + 2^4).
+
+5. Security Considerations
+
+ The security considerations of [RFC8428] apply. This specification
+ provides structure to the interpretation of the SenML version number,
+ which poses no additional security considerations except for some
+ potential for surprise that version numbers do not simply increase
+ linearly.
+
+6. IANA Considerations
+
+ IANA has created a new "SenML Features" subregistry within the
+ "Sensor Measurement Lists (SenML)" registry [IANA.SENML] with the
+ registration policy "Specification Required" [RFC8126] and the
+ columns:
+
+ * Feature Code (an unsigned integer less than 53)
+
+ * Feature Name (text)
+
+ * Reference
+
+ To facilitate the use of feature names in programs, the designated
+ expert is requested to ensure that feature names are usable as
+ identifiers in most programming languages, after lowercasing the
+ feature name in the registry entry and replacing blank space with
+ underscores or hyphens, and that they also are distinct in this form.
+
+ The initial content of this registry is as follows:
+
+ +==============+=================+=====================+
+ | Feature Code | Feature Name | Reference |
+ +==============+=================+=====================+
+ | 0 | Reserved0 | [RFC9100] |
+ +--------------+-----------------+---------------------+
+ | 1 | Reserved1 | [RFC9100] |
+ +--------------+-----------------+---------------------+
+ | 2 | Reserved2 | [RFC9100] |
+ +--------------+-----------------+---------------------+
+ | 3 | Reserved3 | [RFC9100] |
+ +--------------+-----------------+---------------------+
+ | 4 | Secondary Units | [RFC9100] [RFC8798] |
+ +--------------+-----------------+---------------------+
+
+ Table 1: Features Defined for SenML at the Time of
+ Writing
+
+ As the number of features that can be registered has a hard limit (48
+ codes left at the time of writing), the designated expert is
+ specifically instructed to maintain a frugal regime of code point
+ allocation, keeping code points available for SenML Features that are
+ likely to be useful for non-trivial subsets of the SenML ecosystem.
+ Quantitatively, the expert could, for instance, steer the allocation
+ to a target of not allocating more than 10% of the remaining set per
+ year.
+
+ Where the specification of the feature code is provided in a document
+ that is separate from the specification of the feature itself (as
+ with feature code 4 above), both specifications should be listed.
+
+7. References
+
+7.1. Normative References
+
+ [C] International Organization for Standardization,
+ "Information technology - Programming languages - C", ISO/
+ IEC 9899:2018, Fourth Edition, June 2018,
+ <https://www.iso.org/standard/74528.html>.
+
+ [CPLUSPLUS]
+ International Organization for Standardization,
+ "Programming languages - C++", ISO/IEC 14882:2020, Sixth
+ Edition, December 2020,
+ <https://www.iso.org/standard/79358.html>.
+
+ [IANA.SENML]
+ IANA, "Sensor Measurement Lists (SenML)",
+ <https://www.iana.org/assignments/senml>.
+
+ [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>.
+
+ [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
+ Writing an IANA Considerations Section in RFCs", BCP 26,
+ RFC 8126, DOI 10.17487/RFC8126, June 2017,
+ <https://www.rfc-editor.org/info/rfc8126>.
+
+ [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>.
+
+ [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>.
+
+ [RFC8798] Bormann, C., "Additional Units for Sensor Measurement
+ Lists (SenML)", RFC 8798, DOI 10.17487/RFC8798, June 2020,
+ <https://www.rfc-editor.org/info/rfc8798>.
+
+7.2. Informative References
+
+ [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493,
+ DOI 10.17487/RFC7493, March 2015,
+ <https://www.rfc-editor.org/info/rfc7493>.
+
+Acknowledgements
+
+ Ari Keränen proposed to use the version number as a bitmap and
+ provided further input on this specification. Jaime Jiménez helped
+ clarify the document by providing a review and acted as Document
+ Shepherd. Elwyn Davies provided a detailed GENART review with
+ directly implementable text suggestions that now form part of this
+ specification. Rob Wilton supplied comments, one of which became the
+ last paragraph of Section 2.1; Éric Vyncke helped with Section 2.
+ Additional thanks go to the other IESG reviewers.
+
+Author's Address
+
+ Carsten Bormann
+ Universität Bremen TZI
+ Postfach 330440
+ D-28359 Bremen
+ Germany
+
+ Phone: +49-421-218-63921
+ Email: cabo@tzi.org