idnits 2.17.1 draft-ietf-core-senml-versions-03.txt: -(270): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There are 5 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (9 May 2021) is 1055 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'C' -- Possible downref: Non-RFC (?) normative reference: ref. 'Cplusplus' Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE C. Bormann 3 Internet-Draft Universitaet Bremen TZI 4 Updates: 8428 (if approved) 9 May 2021 5 Intended status: Standards Track 6 Expires: 10 November 2021 8 SenML Features and Versions 9 draft-ietf-core-senml-versions-03 11 Abstract 13 This short document updates RFC 8428, Sensor Measurement Lists 14 (SenML), by specifying the use of independently selectable "SenML 15 Features" and mapping them to SenML version numbers. 17 Discussion Venues 19 This note is to be removed before publishing as an RFC. 21 Discussion of this document takes place on the CORE Working Group 22 mailing list (core@ietf.org), which is archived at 23 https://mailarchive.ietf.org/arch/browse/core/ 24 (https://mailarchive.ietf.org/arch/browse/core/). 26 Source for this draft and an issue tracker can be found at 27 https://github.com/core-wg/senml-versions (https://github.com/core- 28 wg/senml-versions). 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at https://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on 10 November 2021. 47 Copyright Notice 49 Copyright (c) 2021 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 54 license-info) in effect on the date of publication of this document. 55 Please review these documents carefully, as they describe your rights 56 and restrictions with respect to this document. Code Components 57 extracted from this document must include Simplified BSD License text 58 as described in Section 4.e of the Trust Legal Provisions and are 59 provided without warranty as described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 64 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 65 2. Feature Codes and the Version number . . . . . . . . . . . . 3 66 2.1. Discussion . . . . . . . . . . . . . . . . . . . . . . . 3 67 2.2. Updating RFC8428 . . . . . . . . . . . . . . . . . . . . 4 68 3. Features: Reserved0, Reserved1, Reserved2, Reserved3 . . . . 5 69 4. Feature: Secondary Units . . . . . . . . . . . . . . . . . . 5 70 5. Security Considerations . . . . . . . . . . . . . . . . . . . 5 71 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 72 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 73 7.1. Normative References . . . . . . . . . . . . . . . . . . 6 74 7.2. Informative References . . . . . . . . . . . . . . . . . 7 75 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 7 76 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 78 1. Introduction 80 The Sensor Measurement Lists (SenML) specification [RFC8428] provides 81 a version number that is initially set to 10, without further 82 specification on the way to make use of different version numbers. 84 The traditional idea of using a version number to indicate the 85 evolution of an interchange format generally assumes an incremental 86 progression of the version number as the format accretes additional 87 features over time. However in the case of SenML it is expected that 88 the likely evolution will be for independently selectable capability 89 _features_ to be added to the basic specification that is indicated 90 by version number 10. To support this model, this document 91 repurposes the single version number accompanying a pack of SenML 92 records so that it is interpreted as a bitmap that indicates the set 93 of features a recipient would need to have implemented to be able to 94 process the pack. 96 This short document specifies the use of SenML Features and maps them 97 to SenML version number space, updating [RFC8428]. 99 1.1. Terminology 101 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 102 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 103 "OPTIONAL" in this document are to be interpreted as described in 104 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 105 capitals, as shown here. 107 Where bit arithmetic is explained, this document uses the notation 108 familiar from the programming language C [C], including the "0b" 109 prefix for binary numbers defined in Section 5.13.2 of the C++ 110 language standard [Cplusplus], except that superscript notation 111 (example for two to the power of 64: 2^64) denotes exponentiation; in 112 the plain text version of this draft, superscript notation is 113 rendered in paragraph text by C-incompatible surrogate notation as 114 seen in this example, and in display math by a crude plaintext 115 representation, as is the sum (Sigma) sign. 117 2. Feature Codes and the Version number 119 The present specification defines "SenML Features", each identified 120 by a "feature name" (a text string) and a "feature code", an unsigned 121 integer less than 53. 123 The specific version of a SenML pack is composed of a set of 124 features. The SenML version number ("bver" field) is then a bitmap 125 of these features, specifically the sum of, for each feature present, 126 two taken to the power of the feature code of that feature. 128 __ 52 fc 129 version = \ present(fc) ⋅ 2 130 /__ fc = 0 132 where present(fc) is 1 if the feature with the feature code "fc" is 133 present, 0 otherwise. (The expression 2^fc can be implemented as "1 134 << fc" in C and related languages.) 136 2.1. Discussion 138 Representing features as a bitmap within a number is quite efficient 139 as long as feature codes are sparingly allocated (see also 140 Section 6). 142 Compatibility with the existing SenML version number, 10 decimal 143 (0b1010), requires reserving four of the least significant bit 144 positions for the base version as described in Section 3. There is 145 an upper limit to the range of the integer numbers that can be 146 represented in all SenML representations: practical JSON limits this 147 to 2^53-1 [RFC7493]. This means the feature codes 4 to 52 are 148 available, one of which is taken by the feature defined in Section 4, 149 leaving 48 for allocation. (The current version 10 (with all other 150 feature codes unset) can be visualized as 151 "0b00000000000000000000000000000000000000000000000001010".) For a 152 lifetime of this scheme of several decades, approximately two feature 153 codes per year or less should be allocated. Note that less generally 154 applicable features can always be communicated via fields labeled 155 with names that end with the "_" character ("must-understand 156 fields"), see Section 4.4 of [RFC8428].) 158 Most representations visible to engineers working with SenML will use 159 decimal numbers, e.g. 26 (0b11010, 0x1a) for a version that adds the 160 "Secondary Units" feature (Section 4). This is sightly unwieldy, but 161 will be quickly memorized in practice. 163 2.2. Updating Section 4.4 of [RFC8428] 165 The last paragraph of Section 4.4 of [RFC8428] may be read to give 166 the impression that SenML version numbers are totally ordered, i.e., 167 that an implementation that understands version n also always 168 understands all versions k < n. If this ever was true for SenML 169 versions before 10, it certainly is no longer true with this 170 specification. 172 Any SenML pack that sets feature bits beyond the first four will lead 173 to a version number that actually is greater than 10, so the 174 requirement in Section 4.4 of [RFC8428] will prevent false 175 interoperability with version 10 implementations. 177 Implementations that do implement feature bits beyond the first four, 178 i.e., versions greater than 10, will instead need to perform a 179 bitwise comparison of the feature bitmap as described in this 180 specification and ensure that all features indicated are understood 181 before using the pack. E.g., an implementation that implements basic 182 SenML (version number 10) plus only a future feature code 5, will 183 accept version number 42, but would not be able to work with a pack 184 indicating version number 26 (base specification plus feature code 185 4). (If the implementation _requires_ feature code 5 without being 186 backwards compatible, it will accept 42, but not 10.) 188 3. Features: Reserved0, Reserved1, Reserved2, Reserved3 190 For SenML Version 10 as described in [RFC8428], the feature codes 0 191 to 3 are already in use. Reserved1 (1) and Reserved3 (3) are always 192 present and the features Reserved0 (0) and Reserved2 (2) are always 193 absent, yielding a version number of 10 if no other feature is in 194 use. These four reserved feature codes are not to be used with any 195 more specific semantics except in a specification that updates the 196 present specification. 198 4. Feature: Secondary Units 200 The feature "Secondary Units" (code number 4) indicates that 201 secondary unit names [RFC8798] MAY be be used in the "u" field of 202 SenML Records, in addition to the primary unit names already allowed 203 by [RFC8428]. 205 Note that the most basic use of this feature simply sets the SenML 206 version number to 26 (10 + 2^4). 208 5. Security Considerations 210 The security considerations of [RFC8428] apply. This specification 211 provides structure to the interpretation of the SenML version number, 212 which poses no additional security considerations except for some 213 potential for surprise that version numbers do not simply increase 214 linearly. 216 6. IANA Considerations 218 IANA is requested to create a new subregistry "SenML features" within 219 the SenML registry [IANA.senml], with the registration policy 220 "specification required" [RFC8126] and the columns: 222 * Feature code (an unsigned integer less than 53) 224 * Feature name (text) 226 * Specification 228 To facilitate the use of feature names in programs, the designated 229 expert is requested to ensure that feature names are usable as 230 identifiers in most programming languages, after lower-casing the 231 feature name in the registry entry and replacing whitespace with 232 underscores or hyphens, and that they also are distinct in this form. 234 The initial content of this registry is as follows: 236 +==============+=================+====================+ 237 | Feature code | Feature name | Specification | 238 +==============+=================+====================+ 239 | 0 | Reserved0 | RFCthis | 240 +--------------+-----------------+--------------------+ 241 | 1 | Reserved1 | RFCthis | 242 +--------------+-----------------+--------------------+ 243 | 2 | Reserved2 | RFCthis | 244 +--------------+-----------------+--------------------+ 245 | 3 | Reserved3 | RFCthis | 246 +--------------+-----------------+--------------------+ 247 | 4 | Secondary Units | RFCthis, [RFC8798] | 248 +--------------+-----------------+--------------------+ 250 Table 1: Features defined for SenML at the time of 251 writing 253 As the number of features that can be registered has a hard limit (48 254 codes left at the time of writing), the designated expert is 255 specifically instructed to maintain a frugal regime of code point 256 allocation, keeping code points available for SenML Features that are 257 likely to be useful for non-trivial subsets of the SenML ecosystem. 258 Quantitatively, the expert could for instance steer the allocation to 259 not allocate more than 10 % of the remaining set per year. 261 Where the specification of the feature code is provided in a document 262 that is separate from the specification of the feature itself (as 263 with feature code 4 above), both specifications should be listed. 265 7. References 267 7.1. Normative References 269 [C] International Organization for Standardization, 270 "Information technology — Programming languages — C", ISO/ 271 IEC 9899:2018, Fourth Edition, June 2018, 272 . 274 [Cplusplus] 275 International Organization for Standardization, 276 "Programming languages — C++", ISO/IEC 14882:2020, Sixth 277 Edition, December 2020, 278 . 280 [IANA.senml] 281 IANA, "Sensor Measurement Lists (SenML)", 282 . 284 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 285 Requirement Levels", BCP 14, RFC 2119, 286 DOI 10.17487/RFC2119, March 1997, 287 . 289 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 290 Writing an IANA Considerations Section in RFCs", BCP 26, 291 RFC 8126, DOI 10.17487/RFC8126, June 2017, 292 . 294 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 295 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 296 May 2017, . 298 [RFC8428] Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C. 299 Bormann, "Sensor Measurement Lists (SenML)", RFC 8428, 300 DOI 10.17487/RFC8428, August 2018, 301 . 303 [RFC8798] Bormann, C., "Additional Units for Sensor Measurement 304 Lists (SenML)", RFC 8798, DOI 10.17487/RFC8798, June 2020, 305 . 307 7.2. Informative References 309 [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, 310 DOI 10.17487/RFC7493, March 2015, 311 . 313 Acknowledgements 315 Ari Keränen proposed to use the version number as a bitmap and 316 provided further input on this specification. Jaime Jiménez helped 317 clarify the document by providing a review. Elwyn Davies provided a 318 detailed GENART review, with directly implementable text suggestions 319 that now form part of this specification. 321 Author's Address 323 Carsten Bormann 324 Universitaet Bremen TZI 325 Postfach 330440 326 D-28359 Bremen 327 Germany 329 Phone: +49-421-218-63921 330 Email: cabo@tzi.org