1. oneM2M Service Layer Protocol Version Handling
Group Name: PRO WG
Source: Qualcomm Inc., Wolfgang Granzow, Nobu Uchida, Josef Blanz
Meeting Date: TP#30,
Agenda Item: Joint ARC/PRO/SEC

2. History of discussions
Version handling is a really long-standing Action Item …
Previous inputs for discussion and proposed solutions:
ARC REST_API_versioning (LAAS-CNRS), presented at TP#13
PRO Versioning_Solution (Fujitsu), presented at PRO#13.2
PRO R02-CR_API_version_info (Fujitsu), CR to TS-0004v0_8_0 noted at PRO#14.1
ARC (QCOM)
Presented as PRO at TP#24, discussed at ARC/PRO#26.1 telco ( )
PRO R01 (QCOM) discussed in joint ARC/PRO at TP#27

3. Version Handling in oneM2M
Entity A (Registree)
Entity B
(Registrar)
System Management / Configuration
oneM2M Application/SL Rxy
parameters
AE or CSE originator
and receiver processing
serialization
Primitives
protocol
selection
CoAP
Binding
HTTP
Binding
MQTT
Binding WS
Binding
request
SL version
(WS only)
CoAP
HTTP
MQTT WS V1
V1.1
V3.1.1
V13
response
cipher suite(s),
other params.
DTLS
TLS
V1.2
V1.2
UDP
TCP
IP version/
address
IP (IPv4, IPv6)
setup IP
connectivity
../LC/MAC/PHY

4. Notion of oneM2M Version
oneM2M Application / Common Service Layer protocol version
= “Release Version” of Mca or Mcc, e.g. R1, R2, R2A, R3
an indicator which identifies conformance with a specific set of requirements laid out in that version’s corresponding set of specifications
“Release Version” is not equal to the version number of specifications
The mapping between oneM2M “Release Version” and specification numbers/version needs to be defined (“oneM2M release control document”), but this is out of scope of this presentation

5. Notion of oneM2M Version
App / SL Version needs to cover following features:
Behavior of primitive processing at the originator and receiver
Representation of a primitive
“Control“ primitive parameters and their (XSD-) permitted values
“Content” primitive parameter
Global Elements permitted to appear in the primitive Content
Core resource types defined in „m2m:“ namespace
Specific resource types defined in other namespaces (e.g. „hd:“, „dcfg:“, „sec:“)
Serialization formats of primitive parameters, including Content
Binding scheme: mapping of primitive parameters to/from CoAP, HTTP, MQTT or WebSocket (WS)

6. Versions of protocols below oneM2M SL
Application data transfer protocols:
All protocols below oneM2M SL use the same fixed version for all current oneM2M Releases
Version is indicated explicitly in every request and response for CoAP and HTTP
MQTT: indication of version (“3”) used by a client in CONNECT message sent to the server. Server may refuse connection request indicating “unacceptable protocol version” in CONNACK response
WS: HTTP/1.1 or higher used in opening handshake (negotiable), WebSocket version 13 must be used, version negotiable in future WS versions, no explicit indication in WS frames

7. Version of protocol using WebSocket
WS: Allows negotiation of upper application protocol, including version and serialization format per WS connection
Sec-WebSocket-Protocol: oneM2M.R2.0.json, oneM2M.R2.0.xml
(NOTE: format may need to be changed when Release/Version scheme is fixed)
This is not applicable to CoAP and HTTP, as these protocols have no concept of a session or connection
These protocols may use different UDP or TCP port numbers to differentiate different applications using it

8. Versions of protocols below oneM2M SL
DTLS and TLS
Fixed versions v1.2 currently used
Version is on principle negotiable in the handshake
This feature may be used for future oneM2M releases supporting (D)TLS v1.3
UDP and TCP
Have no versions; TCP has optional negotiable extensions IP
IPv4 and IPv6, to be selected/configured at network connection configuration stage

9. SL Version indication or negotiation
When?
Each request/response transaction?
At connection establishment?
E.g. WS allows negotiation in opening handshake; then no version info in request/response primitive itself required
At registration?
SL version supported by registree and registrar is known to these two entities only
May cause issues when forwarding primitives in MNs

10. SL Version indication How?
Additional primitive parameter in every request and response
New parameter needs to be mapped by binding protocol for HTTP and CoAP
Resolves issues when forwarding primitives
“Content-Type” header could be used for CoAP and HTTP
By provisioning:
Version supported by registrar provisioned to registree, as separate parameter, or as part of PoA parameter
By indication in registration phase
Registree indicates its supported release as part of <AE> or <remoteCSE> resource
Release supported by registrar visible to registree in <CSEbase> resource of the registrar

11. „Levels“ of inter-release interworking
No interworking between release versions
All entities up to some level (e.g. IN-CSE) comply to the same release version
An MN or IN-CSE higher up in the hierarchical topology of nodes may support “perfect” conversion to higher version if supported by upper level entity
Higher release entities interwork with subordinate nodes of older releases (i.e. backward compatibility)
This seems feasible if both, primitives and resource representations would be maintained strictly backward compatible
This is not guaranteed between oneM2M R1 and R2 but can probably be ensured from some version R2.x into R3
Requires some extra “down-conversion” processing of response messages; notification request and response messages should be forward and backward compatible
Entities of any release interwork with each other
E.g. any unknown primitive parameters and elements of Content are ignored
Requires forward and backward compatible primitives and resource representations. Doesn’t seem feasible

12. Requirements to support levels A) and B)
Registrar should know the release version intended to be used by it’s registree(s)
This information can be exchanged in the registration procedure
The used release version is part of the context information between registree and registrar and therefore does not need to be exchanged with every request and response
Suggested procedure:
Registree includes its supported release in <AE> or <remoteCSE> in registration request message (i.e. create <AE> or create <remoteCSE>
Registrar indicates its release in the <CSEBase>
Registrar may explicitly reject the registration request if release versions don’t match. Successful registration response ensures the registree of matching release versions
Release version in <CSEBase>, <AE> and <remoteCSE> could be indicated in reserved labels (instead of defining new attributes, to keep resource type compatibility)

13. Differences between Interwork levels A) and B)
For interwork level A), registration is rejected if the release versions supported by Registree and Registrar differ
For interwork level B), the registrar accepts registration of a registree supporting a „backward compatible“ (BC) release
Support of B) has issues in following scenarios
Forwarding of primitives
Content primitive parameters returned from a higher release entity to the originator
Node communicating with lower release entity should apply some conversion, even for forwarding of response primitives
Aggregation of responses originating from Entities with mixed, possibly lower or higher SL versions
Reception of Notify request messages from higher SL version entity

14. Potential Issues with B)op
R2 Hosting CSE
R3 Hosting CSE R2
orig C 
No issue for BC resource R
R3 entity should not add attributes unknown in R2 U
No issue D R3
Unknown attributes to be rejected by hosting CSE
BC = Backward Compatible

15. Possible solution for exchange of release version
Registree indicates its own supported release version in <AE> or <remoteCSE>, e.g. label attribute
Registree mandated to indicate the same or a lower version
After successful registration, Registree can read release version supported by the registrar in <CSEBase>, e. g. label attribute
For unsuccessful registration due to release version mismatch, the registrar should send a respective new RSC and could also include its supported release version in the Content para,meter of the response
Any resource representation includes its version in the same way (i.e. in label)
Release version vs. XSD version? Two labels, e.g. XSDv2_10 and Rel2.a

16. Proposal (1)
Define reserved label attribute values to indicate Release versions
Use key:value format
Define reserved keys and values
Supported release: e.g. REL:2A, REL:3 (values of key & label to be defined)
XSD-version of resource representation on hosting CSE: e.g. XSD:2.12
Mandate that Registree indicates its release version label when creating <AE> and <remoteCSE> resources
labels attribute of <CSEBase> indicates Release Version supported by a CSE
labels attribute of <AE> indicates Release Version by an AE registree at its registrar
labels attribute of <remoteCSE> indicates Release Version supported by a CSE registree to its registrar
All other resource types which are created by entities other than the hosting CSE could also include release version label to indicate the version of the creator of the resource

17. Proposal (2) XSD representation label shall be added by hosting CSE
Registrar must choose XSD version compatible with its own release version as well as the XSD associated with the release supported by the registree
E.g. <remoteCSE> resource in registree and registrar may have different XSD version labels, but the higher version shall be „compatible“ with the lower version
Compatible release versions must be specified in the specs, i.e. TS-0004
Registrar shall reject registration request of incompatible release
New status code to be defined
Update of labels attribute
Release version should not change as long as there is no update of the supported release e.g. due to SW upgrade
SW upgrade to a newer release of an entity shall trigger re-registration
The respective elements of the labels attribute should be maintained by the hosting CSE as read-only information

18. Proposal (3)
Initially, ensure that „inter-release interworking Level A)“ works appropriately
Minor update of registration procedure required:
Registrar shall check labels indicated by the registree
Accept registration request for matching release version
Reject registration request for non-matching release versions , with RSC to be defined
More detailed work is needed to clarify under which conditions Level B) is feasible
clarify how to deal with the issues listed on slides 13 and 14 above
Also conformance testing procedures for inter-release interworking procedures would need to be defined