6 CoAP Message Mapping

6.1 Introduction

When AE or CSE binds oneM2M primitives to CoAP messages, or binds CoAP messages to oneM2M primitives, it is required that:

  • AE shall host a CoAP client and should host a CoAP server; or
  • CSE shall host both a CoAP client and a CoAP server.

In general a single oneM2M request primitive is mapped to a single CoAP request message, and a single oneM2M response primitive is mapped to a single CoAP response message. However, a single oneM2M request/response primitive is mapped to multiple CoAP request/response messages respectively when the CoAP block-wise transfer feature is used.

Mapping between CoAP message and oneM2M primitive shall be applied in the following cases:

  • when the Originator sends a request primitive;
  • when the Receiver receives a CoAP message(s);
  • when the Receiver sends a response primitive;
  • when the Originator receives a CoAP message(s).

The following sub-clauses specify how to map each oneM2M primitive parameter defined in oneM2M TS-0004 [2] to a corresponding CoAP message field to compose a CoAP request/response message.

6.2 Primitive Mapping to CoAP Message

6.2.0 Introduction

This clause describes where to map oneM2M parameters in a primitive to header, Option and payload fields in a CoAP message. The mappings are summarised in Table 6.2.0‑1 and more detail is given in subsequent clauses.

In Table 6.2.0‑1:

  • "CoAP option" means a oneM2M-specific CoAP option as defined in clause clause 6.2.2.4.
  • "Payload" in the second column means that the parameter is passed in a serialized oneM2M primitive. See clause clause 6.2.3.
  • "Uri-Query" means that the parameter is sent as part of the CoAP Uri-Query option. See clause clause 6.2.2.3.

Table 6.2.0‑1: oneM2M Primitive Parameter Mappings

Primitive Parameter
Release 5
Earlier releases
Operation
Header (blocking requests)
Uri-Query (other requests)
Header (blocking requests)
Uri-Query (other requests)
To
Standard CoAP options
Standard CoAP options
From
Payload or CoAP option
CoAP option
Request Identifier
Payload or CoAP option
CoAP option
Content
Payload
Payload
Originating Timestamp
Payload or CoAP option
CoAP option
Request Expiration Timestamp
Payload or CoAP option
CoAP option
Result Expiration Timestamp
Payload or CoAP option
CoAP option
Operation Execution Time
Payload or CoAP option
CoAP option
Role IDs
Payload
Uri-Query
Response Type - notificationURI
Payload
CoAP option
Response Type - responseTypeValue
Payload
Uri-Query
Result Persistence
Payload
Uri-Query
Result Content
Payload
Uri-Query
Event Category
Payload or CoAP option
CoAP option
Response Status Code
New CoAP option
CoAP option
Delivery Aggregation
Payload
Uri-Query
Group Request Identifier
Payload
CoAP option
Filter Criteria
Payload
Uri-Query
Desired Identifier Result Type
Payload
Uri-Query
Resource Type
Payload or CoAP option
CoAP option
Content Offset
Payload or CoAP option
CoAP option
Content Status
Payload or CoAP option
CoAP option
Assigned Token Identifiers
Payload
CoAP option
Tokens
Payload
Uri-Query
Token IDs
Payload
Uri-Query
Local Token IDs
Payload
Uri-Query
Token Request Indicator
Payload
Uri-Query
Token Request Information
Payload
Payload
Release Version Indicator
Payload or CoAP option
CoAP option
Vendor Information
Payload
CoAP option
Group Request Target Members
Payload
CoAP option
Group Somecast Target Number
Payload
Uri-Query
Authorization Signature Indicator
Payload
Uri-Query
Authorization Signatures
Payload
CoAP option
Authorization Signature Request Information
Payload
CoAP option
Authorization Relationship Indicator
Payload
Uri-Query
Semantic Query Indicator
Payload
Uri-Query
Ontology Mapping Resources
Payload
CoAP option
Primitive Profile Identifier
Payload
CoAP option
M2M Service User
Payload
CoAP option

This clause specifies how to configure CoAP header information:

  • The Version field shall be configured as 1.
  • The Type field shall be configured according to clause clause 6.3. The Reset message is used to indicate an error in response to a malformed message in the CoAP layer.
  • In case of a request, the Code field indicates the CoAP Method. If the oneM2M operation is sent as a Blocking request the oneM2M Operation parameter shall be mapped to a CoAP Method according to the tTable 6.2.1‑1. In non-blocking and flex blocking cases, the request shall use the CoAP POST method, and the Operation parameter shall be mapped as described in clause clause 6.2.2.3.
  • In case of a response, the Code field indicates the CoAP Response Code. The oneM2M Response Status Code parameter shall be mapped to a CoAP Response Code as specified in clause clause 6.2.4.
  • The Originator and Receiver shall set the 16-bit MessageId in accordance with the CoAP specification [1] and shall retry transmission of all unacknowledged Confirmable messages, as required by that specification.

Table 6.2.1‑1: oneM2M Operation Parameter Mapping

oneM2M Operation Parameter
CoAP Method
CoAP Method Code
CREATE
POST
0.02
RETRIEVE
FETCH or GET
0.05 (FETCH) or 0.01 (GET)
UPDATE
PUT
0.03
DELETE
DELETE
0.04
NOTIFY
POST
0.02

The Originator shall use the FETCH method as defined in IETF RFC 8132 [6] when sending a RETRIEVE request, except in when the Receiver is running Release 4 or earlier in which case it shall use the GET method. See clause clause 6.6 for more details on the use of FETCH.

At the Receiver, a CoAP request message with a POST method that does not carry an Operation parameter shall be mapped to a oneM2M CREATE or NOTIFY operation in accordance with the existence of the Resource Type parameter. If a Resource Type parameter exists then the value of the Operation parameter is CREATE and if the Resource Type parameter does not exist, the value of the Operation parameter is NOTIFY.

6.2.2 Configuration of Token and Options

6.2.2.0 Introduction

This clause describes configuration of Token and Options based on oneM2M parameters.

6.2.2.1 Token

The CoAP token is used by the CoAP layer to match a response to a request, in a manner that is similar to the oneM2M Request Identifier. Due to size limitations, a Request Identifier cannot be used directly as the CoAP Token.

The use of tokens by Originator and Receiver shall comply with requirements of the CoAP specification [1].

6.2.2.2 Content Format Negotiation Options

The CoAP Accept Option may be used to indicate which Content-Format is acceptable to an Originator. If a Hosting CSE supports the Content-Format specified in Accept Option of the request, the Hosting CSE shall respond with that Content-Format. If the Hosting CSE does not support the Content-Format specified in Accept Option of the request, 4.06 "Not Acceptable" shall be sent as a response, unless another error code takes precedence for this response.

Possible values for Content-Format and Accept options are listed below:

  • application/xml (41);
  • application/json (50);
  • application/cbor (60);
  • media types specified in clause 6.7 "oneM2M specific MIME media types" of oneM2M TS-0004 [2].

Numeric values for oneM2M defined media types are listed in tTable 6.2.2.2‑1.

Table 6.2.2.2‑1: CoAP oneM2M Specific Content-Formats

oneM2M Specific Media Type
ID
application/vnd.onem2m-res+xml
10014
application/vnd.onem2m-res+json
10015
application/vnd.onem2m-ntfy+xml
10016
application/vnd.onem2m-ntfy+json
10003
application/vnd.onem2m-preq+xml
10006
application/vnd.onem2m-preq+json
10007
application/vnd.onem2m-prsp+xml
10008
application/vnd.onem2m-prsp+json
10009
application/vnd.onem2m-res+cbor
10010
application/vnd.onem2m-ntfy+cbor
10011
application/vnd.onem2m-preq+cbor
10012
application/vnd.onem2m-prsp+cbor
10013

NOTE: ID values for oneM2M specific media type are subject to change after IANA registration.

6.2.2.3 URI Options

This clause describes how to configure CoAP Uri-Host, Uri-Port, Uri-Path, and Uri-Query Options.

Host and port part of the address specified in pointOfAccess attribute of <remoteCSE> resource shall be mapped to Uri-Host and Uri-Port respectively.

If To parameter contains absolute format, then the first URI-Path Option shall contain a letter "_" and map To parameter removing starting "//" into next URI-Path Option(s).

If To parameter contains SP-relative format, then the first URI-Path Option shall contain a letter "~" and map To parameter removing starting "/" into next URI-Path Option(s).

If To parameter contains CSE-relative format, then To parameter shall be mapped to URI-Path Option(s).

Table 6.2.2.3‑1 shows valid mappings between the To request primitive parameter and the Uri-Path of the CoAP.

CSEBase represents the resource name of a <CSEBase > resource, CSEBase/ae12/cont27/contInst696 represents a structured CSE-relative resource ID, and cin00856 an unstructured CSE-relative resource ID.

Table 6.2.2.3‑1: Mapping examples between To parameter and Uri-Path of the CoAP

Method
Request Scope
CSE-Relative
SP-Relative
Absolute
Structured
To
CSEBase/ae12/cont27/contInst696
/CSE178/CSEBase/ae12/cont27/contInst696
//mym2msp.org/CSE178/CSEBase/ae12/cont27/contInst696
Uri-Path
CSEBase
_ (underscore)
~ (tilde)
mym2msp.org
CSE178
CSE178
CSEBase
CSEBase
ae12
ae12
ae12
cont27
cont27
cont27
contInst696
contInst696
contInst696
Unstructured
To
cin00856
/CSE178/cin00856
//mym2msp.org/CSE178/cin00856
Uri-Path
cin00856
_(underscore)
~ (tilde)
mym2msp.org
CSE178
CSE178
cin00856
cin00856

NOTE: How to read this table: To primitive - from left to right, Uri-Path - from top to bottom.

NOTE: In oneM2M Release 4 or earlier some primitive parameters are mapped to the CoAP Uri-Query option. Implementations should accept parameters passed in this manner from a Release 4 (or earlier) implementation and should place them, if needed, in the Uri-Query when sending a primitive to such an implementation. These parameters are shown in tTable 6.2.0‑1. In the Uri-Query they are represented using the short names specified in clause 8.2.2 of oneM2M TS-0004 [2].

6.2.2.4 oneM2M-specific CoAP Options

6.2.2.4.0 Introduction

This clause describes additional CoAP Options used for binding several oneM2M primitive parameters. Tables 6.2.2.4.0‑1 and 6.2.2.4.0-2 contain definitions of the oneM2M-defined CoAP Options and the sub-clauses that follow this one specify the oneM2M parameter mappings to these CoAP Options.

Table 6.2.2.4.0‑1: Definition of oneM2M Options

No
C
U
N
R
Name
Format
Length
Default
279
X
X
oneM2M-FR
string
0-255
(None)
283
X
X
oneM2M-RQI
string
0-255
(None)
259
X
X
oneM2M-OT
string
15
(None)
291
X
X
oneM2M-RQET
string
15
(None)
295
X
X
oneM2M-RSET
string
15
(None)
299
X
X
oneM2M-OET
string
15
(None)
303
X
X
oneM2M-EC
uint
1
(None)
307
X
X
oneM2M-RSC
uint
2
(None)
267
X
X
oneM2M-TY
uint
2
(None)
319
X
X
oneM2M-CTO
uint
2
(None)
323
X
X
oneM2M-CTS
uint
2
(None)
271
X
X
oneM2M-RVI
string
1-2
(None)

NOTE 1: C, U, N, R means Critical, Unsafe, NoCacheKey and Repeatable respectively [1]. This table follows the template used in Table 6.2.2.4.0‑1 follows the template used in clause 5.10 Option Definitions of the CoAP specification [1].

NOTE 2: CoAP Option numbers specified in this table are subject to change after review by IANA registration.table 6.2.2.4.0‑1 are subject to change after review by IANA registration.

The Response Status Code in a response shall be carried using the CoAP option shown in tTable 6.2.2.4.0‑1.

The remaining CoAP options listed in tTable 6.2.2.4.0‑1 may be used to carry the corresponding Primitive Parameters, if needed, however these Primitive Parameters may instead be carried in the CoAP payload as described in clause clause 6.2.3.

  • The parameter shall be carried in the payload and not as a CoAP option if its value is longer than the maximum length permitted for the CoAP option (see the length column in tTable 6.2.2.4.0‑1).

NOTE 31: The CoAP option approach gives a more efficient encoding if the whole primitive is small enough to fit in a single CoAP message, however it could be less efficient if the primitive is larger and has to be split into multiple blocks (see clause clause 6.5). This is because CoAP options have to be repeated in each block.

NOTE 42: In Release 4 and earlier releases, some additional CoAP options are defined. These are shown in tTable 6.2.2.4.0‑2. A oneM2M implementation should accept parameters passed using these options from a Release 4 (or earlier) implementation and should use the options when sending a oneM2M primitive to such an implementation.

Table 6.2.2.4.0‑2: Additional Options used in Release 4 and earlier

No
C
U
N
R
Name
Format
Length
Default
263
X
X
oneM2M-RTURI
string
0-255
(None)
311
X
X
oneM2M-GID
string
0-255
(None)
327
X
X
oneM2M-ATI
string
0-255
(None)
331
X
X
oneM2M-VSI
string
0-255
(None)
335
X
X
oneM2M-GTM
string
0-512
(None)
339
X
X
oneM2M-AUS
string
0-255
(None)
275
X
X
oneM2M-ASRI
string
0-255
(None)
343
X
X
oneM2M-OMR
string
0-255
(None)
347
X
X
oneM2M-PRPI
string
0-255
(None)
351
X
X
oneM2M-MSU
string
0-255
(None)

NOTE 1: C, U, N, R means Critical, Unsafe, NoCacheKey and Repeatable respectively [1]. This table follows the template used in Table 6.2.2.4.0‑2 follows the template used in clause 5.10 Option Definitions of the CoAP specification [1].

NOTE 2: CoAP Option numbers specified in tTable 6.2.2.4.0‑1 are subject to change after review by IANA registration.

The options in tTable 6.2.2.4.0‑2 shall not be used when sending a oneM2M primitive to an implementation that is Release 5 or later.

6.2.2.4.1 From

The From parameter shall be mapped to the oneM2M-FR Option.

6.2.2.4.2 Request Identifier

The Request Identifier parameter shall be mapped to the oneM2M-RQI Option.

6.2.2.4.3 Void
6.2.2.4.4 Originating Timestamp

The Originating Timestamp parameter shall be mapped to the oneM2M-OT Option.

6.2.2.4.5 Request Expiration Timestamp

The Request Expiration Timestamp parameter shall be mapped to the oneM2M-RQET Option.

6.2.2.4.6 Result Expiration Timestamp

The Result Expiration Timestamp parameter shall be mapped to the oneM2M-RSET Option.

6.2.2.4.7 Operation Execution Time

The Operation Execution Time parameter shall be mapped to the oneM2M-OET Option.

6.2.2.4.8 notificationURI of Response Type

The notificationURI element of Response Type parameter shall be mapped to the oneM2M-RTURI Option.

6.2.2.4.9 Event Category

The Event Category parameter shall be mapped to the oneM2M-EC Option.

6.2.2.4.10 Response Status Code

The Response Status Code parameter shall be mapped to the oneM2M-RSC Option.

6.2.2.4.11 Group Request Identifier

The Group Request Identifier parameter shall be mapped to the oneM2M-GID Option.

6.2.2.4.12 Resource Type

The Resource Type parameter shall be mapped to the oneM2M-TY Option.

6.2.2.4.13 Content Offset

The Content Offset parameter shall be mapped to the oneM2M-CTO Option.

6.2.2.4.14 Content Status

The Content Status parameter shall be mapped to the oneM2M-CTS Option.

6.2.2.4.15 Assigned Token Identifiers

The Assigned Token Identifiers parameter shall be mapped to the oneM2M-ATI Option. The format of the oneM2M-ATI option shall be represented as a sequence of lti-value:tkid-value pairs separated by a colon ':' and multiple pairs separated by a '+' character.

EXAMPLE: The option looks as follows:like oneM2M-ATI: lti-value1:tkid-value1 + lti-value2:tkid-value2 + ... if the XML representation of the Assigned Token Identifiers parameter is given as (using short element names):

oneM2M-ATI: lti-value1:tkid-value1 + lti-value2:tkid-value2 + ...
<ati>
   <ltia>
       <lti>lti-value1lti>
       <tkid>tkid-value1tkid>
   ltia>
   <ltia>
      <lti>lti-value2lti>
      <tkid>tkid-value2tkid>
   ltia>
   ...
ati>

if the XML representation of the Assigned Token Identifiers parameter is given as (using short element names):

<ati>
   <ltia>
       <lti>lti-value1lti>
       <tkid>tkid-value1tkid>
   ltia>
   <ltia>
      <lti>lti-value2lti>
      <tkid>tkid-value2tkid>
   ltia>
   ...
ati>

The data type m2m:dynAuthlocalTokenIdAssignments of the Assigned Token Identifiers parameter is defined in clause 6.3.5.43 of oneM2M TS-0004 [2].

6.2.2.4.16 Release Version Indicator

The Release Version Indicator parameter shall be mapped to the oneM2M-RVI Option.

6.2.2.4.17 Vendor Information

The Vendor Information parameter shall be mapped to the oneM2M-VSI Option.

6.2.2.4.18 Group Request Target Members

The Group Request Target Members parameter shall be mapped to the oneM2M-GTM Option.

6.2.2.4.19 Authorization Signatures

The Authorization Signatures parameter shall be mapped to the oneM2M-AUS Option.

6.2.2.4.20 Authorization Signature Request Information

The Authorization Signature Request Information parameter shall be mapped to the oneM2M-ASRI Option.

6.2.2.4.21 Ontology Mapping Resources

The Ontology Mapping Resources parameter shall be mapped to the oneM2M-OMR Option. The format of the oneM2M-OMR option shall be represented as a sequence of oneM2M resource identifiers separated by a '+'.

EXAMPLE: The option looks as follows:

oneM2M-OMR: /IN-CSE-0001/omr1+/IN-CSE-0001/omr2+...
6.2.2.4.22 Primitive Profile Identifier

The Primitive Profile Identifier parameter shall be mapped to the oneM2M-PRPI Option.

6.2.2.4.23 M2M Service User

The M2M Service User parameter shall be mapped to the oneM2M-MSU Option.

6.2.3 Payload

The CoAP payload shall contain a oneM2M primitive that is serialised using the rules given in clause 8 of oneM2M TS-0004 [2]. These rules shall be applied to the m2m:requestPrimitive defined in clause 6.4.1 of oneM2M TS-0004 [2] or the m2m:responsePrimitive defined in clause 6.4.2 of oneM2M TS-0004 [2].

  • Clause Clause 6.2.26.2.2 of the present document requires some Primitive Parameters (e.g. the To and Response Status Code parameters) to be mapped to CoAP Options and it permits some other parameters (listed in Table 6.2.2.4.0‑-1) either to be passed either as a CoAP option or to be serialised into the request or response primitive. If a parameter is passed as a CoAP option it shall not be included in the serialised primitive.

The CoAP block-wise transfer mechanism shall be used to deliver the payload if it is too large to fit into one CoAP message. Refer to clause Clause 6.5 for more information.

If the Content parameter contains URI and resource representation in a response to a create request, the URI shall be mapped to the CoAP Location-Path Option instead of being included in the CoAP payload.

The CoAP Content-Format option shall be included and shall be set to a value that complies with the data representation.

NOTE: In oneM2M Release 4 and earlier the CoAP payload is required to contain the value of the Token Request Information parameter (if present in a response primitive) and otherwise it is required to contain the value of the Content parameter (if present). Implementations should accept such CoAP payloads from an implementation that is Release 4 or earlier and should construct such payloads when sending oneM2M primitives to such implementations.

6.2.4 Response Codes Mapping

Table 6.2.4‑1 defines the mapping between oneM2M Response Status Code parameter specified in [2] and CoAP Response Code that is referenced in clause clause 6.2.1.

Table 6.2.4‑1: Mapping between oneM2M Response Status Code and CoAP Response Code<span id="table_6.2.4-1>

oneM2M Response Status Code
Description
CoAP Response Code
Description
1000
ACCEPTED
None
Not used
1001
ACCEPTED for nonBlockingRequestSynch
2.01
Created (indicates that a resource has been created)
1002
ACCEPTED for nonBlockingRequestAsynch
2.01 or 2.04
2.01 (Created) is used if a <<request> > resource was created, otherwise 2.04 (Changed) is used
2000 (for RETRIEVE operation)
OK
2.05
Content
2000 (for NOTIFY operation)
OK
2.04
Changed. CoAP payload shall be empty.
2001
CREATED
2.01
Created
2002
DELETED
2.02
Deleted
2004
UPDATED
2.04
Changed
4000
BAD_REQUEST
4.00
Bad Request
4001
RELEASE_VERSION_NOT_SUPPORTED
5.01
Not Implemented
4004
NOT_FOUND
4.04
Not Found
4005
OPERATION_NOT_ALLOWED
4.05
Method Not Allowed
4008
REQUEST_TIMEOUT
5.04
Gateway Timeout
4015
UNSUPPORTED_MEDIA_TYPE
4.15
Unsupported Content-Format
4101
SUBSCRIPTION_CREATOR_HAS_NO_PRIVILEGE
4.03
Forbidden
4102
CONTENTS_UNACCEPTABLE
4.00
Bad Request
4103
ORIGINATOR_HAS_NO_PRIVILEGE
4.03
Forbidden
4104
GROUP_REQUEST_IDENTIFIER_EXISTS
4.00
Bad Request
4105
CONFLICT
4.03
Forbidden
4106
ORIGINATOR_NOT_AUTHENTICATED
4.03
Forbidden
4107
SECURITY_ASSOCIATION_REQUIRED
4.03
Forbidden
4108
INVALID_CHILD_RESOURCE_TYPE
4.03
Forbidden
4109
NO_MEMBERS
4.03
Forbidden
4110
GROUP_MEMBER_TYPE_INCONSISTENT
4.00
Bad Request
4111
ESPRIM_UNSUPPORTED_OPTION
4.03
Forbidden
4112
ESPRIM_UNKNOWN_KEY_ID
4.03
Forbidden
4113
ESPRIM_UNKNOWN_ORIG_RAND_ID
4.03
Forbidden
4114
ESPRIM_UNKNOWN_RECV_RAND_ID
4.03
Forbidden
4115
ESPRIM_BAD_MAC
4.03
Forbidden
4116
ESPRIM_IMPERSONATION_ERROR
4.03
Forbidden
4117
ORIGINATOR_HAS_ALREADY_REGISTERED
4.03
Forbidden
4118
ONTOLOGY_NOT_AVAILABLE
4.04
Not Found
4119
LINKED_SEMANTICS_NOT_AVAILABLE
4.04
Not Found
4120
INVALID_SEMANTICS
4.02
Bad Option
4121
MASHUP_MEMBER_NOT_FOUND
4.04
Not Found
4122
INVALID_TRIGGER_PURPOSE
4.02
Bad Option
4123
ILLEGAL_TRANSACTION_STATE_TRANSITION_ATTEMPTED
4.00
Bad Request
4124
BLOCKING_SUBSCRIPTION_ALREADY_EXISTS
4.00
Bad Request
4125
SPECIALIZATION_SCHEMA_NOT_FOUND
5.01
Not Implemented
4126
APP_RULE_VALIDATION_FAILED
4.03
Forbidden
4127
OPERATION_DENIED_BY_REMOTE_ENTITY
4.03
Forbidden
4128
SERVICE_SUBSCRIPTION_NOT_ESTABLISHED
4.03
Forbidden
4130
ONTOLOGY_MAPPING_ALGORITHM_NOT_AVAILABLE
4.04
Not Found
4131
ONTOLOGY_MAPPING_POLICY_NOT_MATCHED
4.00
Bad Request
4132
ONTOLOGY_MAPPING_NOT_AVAILABLE
4.04
Not Found
4133
BAD_FACT_INPUTS_FOR_REASONING
4.00
Bad Request
4134
BAD_RULE_INPUTS_FOR_REASONING
4.00
Bad Request
4135
DISCOVERY_LIMIT_EXCEEDED
4.03
Forbidden
4136
PRIMITIVE_PROFILE_NOT_ACCESSIBLE
4.03
Forbidden
4137
PRIMITIVE_PROFILE_BAD_REQUEST
4.00
Bad Request
4138
UNAUTHORIZED_USER
4.03
Forbidden
4139
SERVICE_SUBSCRIPTION_NOT_ACTIVE
4.03
Forbidden
4140
SOFTWARE_CAMPAIGN_CONFLICT
4.03
Forbidden
4141
SERVICE_SUBSCRIPTION_LIMITS_EXCEEDED
4.03
Forbidden
4142
INVALID_PROCESS_CONFIGURATION
4.00
Bad Request
4143
INVALID_SPARQL_QUERY
4.00
Bad Request
4144
SERVICE_SUBSCRIPTION_DURATION_EXCEEDS_EXPIRATION_TIME
4.03
Forbidden
5000
INTERNAL_SERVER_ERROR
5.00
Internal Server Error
5001
NOT_IMPLEMENTED
5.01
Not Implemented
5103
TARGET_NOT_REACHABLE
4.04
Not Found
5105
RECEIVER_HAS_NO_PRIVILEGE
4.03
Forbidden
5106
ALREADY_EXISTS
4.00
Bad Request
5107
REMOTE_ENTITY_NOT_REACHABLE
4.04
Not Found
5203
TARGET_NOT_ SUBSCRIBABLE
4.03
Forbidden
5204
SUBSCRIPTION_VERIFICATION_INITIATION_FAILED
5.00
Internal Server Error
5205
SUBSCRIPTION_HOST_HAS_NO_PRIVILEGE
4.03
Forbidden
5206
NON_BLOCKING_SYNCH_REQUEST_NOT_SUPPORTED
5.01
Not Implemented
5207
NOT_ACCEPTABLE
4.06
Not Acceptable
5208
DISCOVERY_DENIED_BY_IPE
4.03
Forbidden
5209
GROUP_MEMBERS_NOT_RESPONDED
5.00
Internal Server Error
5210
ESPRIM_DECRYPTION_ERROR
5.00
Internal Server Error
5211
ESPRIM_ENCRYPTION_ERROR
5.00
Internal Server Error
5212
SPARQL_UPDATE_ERROR
5.00
Internal Server Error
5214
TARGET_HAS_NO_SESSION_CAPABILITY
4.03
Forbidden
5215
SESSION_IS_ONLINE
4.03
Forbidden
5216
JOIN_MULTICAST_GROUP_FAILED
5.00
Internal Server Error
5217
LEAVE_MULTICAST_GROUP_FAILED
5.00
Internal Server Error
5218
TRIGGERING_DISABLED_FOR_RECIPIENT
5.03
Service Unavailable
5219
UNABLE_TO_REPLACE_REQUEST
5.03
Service Unavailable
5220
UNABLE_TO_RECALL_REQUEST
5.03
Service Unavailable
5221
CROSS_RESOURCE_OPERATION_FAILURE
5.00
Internal Server Error
5222
TRANSACTION_PROCESSING_IS_INCOMPLETE
4.03
Forbidden
5230
ONTOLOGY_MAPPING_ALGORITHM_FAILED
5.00
Internal Server Error
5231
ONTOLOGY_CONVERSION_FAILED
5.00
Internal Server Error
5232
REASONING_PROCESSING_FAILED
5.00
Internal Server Error
6003
EXTERNAL_OBJECT_NOT_REACHABLE
4.04
Not Found
6005
EXTERNAL_OBJECT_NOT_FOUND
4.04
Not Found
6010
MAX_NUMBER_OF_MEMBER_EXCEEDED
4.00
Bad Request
6020
MGMT_SESSION_CANNOT_BE_ESTABLISHED
5.00
Internal Server Error
6021
MGMT_SESSION_ESTABLISHMENT_TIMEOUT
5.00
Internal Server Error
6022
INVALID_CMDTYPE
4.00
Bad Request
6023
INVALID_ARGUMENTS
4.00
Bad Request
6024
INSUFFICIENT_ARGUMENTS
4.00
Bad Request
6025
MGMT_CONVERSION_ERROR
5.00
Internal Server Error
6026
MGMT_CANCELLATION_FAILED
5.00
Internal Server Error
6028
ALREADY_COMPLETE
4.00
Bad Request
6029
MGMT_COMMAND_NOT_CANCELLABLE
4.00
Bad Request
6030
EXTERNAL_OBJECT_NOT_REACHABLE_BEFORE_RQET_TIMEOUT
5.04
Gateway Timeout
6031
EXTERNAL_OBJECT_NOT_REACHABLE_BEFORE_OET_TIMEOUT
5.04
Gateway Timeout
6033
NETWORK_QOS_CONFIG_ERROR
5.03
Internal Server Error
6034
REQUESTED_ACTIVITY_PATTERN_NOT_PERMITTED
4.03
Forbidden

The Receiver shall use this table to determine the CoAP response code that is to be used in the response, based on the value of the oneM2M Response Status Code parameter.

6.3 Accessing Resources in CSEs

6.3.0 Introduction

This clause describes the behaviour of the CoAP layer depending on the Response Type parameter. Note that the CoAP messaging model defined in [1] applies to all message exchanges.

oneM2M Requests should be sent as CoAP Confirmable (CON) messages, although an Originator can send a request as a Non-confirmable (NON) message if there is a good reason for doing this. An Originator that relies on getting a response to its request should use a Confirmable rather than a Non-confirmable message for its request.

oneM2M Responses should be sent as CoAP CON messages, although there is one case where a NON message should be used. This is indicated in clause clause 6.3.1.

If the Originator or Receiver sends a CON message it shall retransmit that message if it does not receive a CoAP acknowledgement message, as required by [1]. The recipient (Receiver or Originator) shall take care to de-duplicate CON messages as described in [1].

The recipient of a CoAP message shall process the oneM2M request or response it contains, even if it was sent as Non-confirmable.

6.3.1 Blocking case

  1. If the

    If the Response Type parameter is configured as "blockingRequest" (blocking case), the Originator (CoAP client) shall send the oneM2M request to the Receiver (CoAP server). The oneM2M Operation parameter shall be mapped to a CoAP Method according to Table 6.2.1‑1.

    Response Type parameter is configured as "blockingRequest" (blocking case), the Originator (CoAP client) shall send the oneM2M request to the Receiver (CoAP server). The oneM2M Operation parameter shall be mapped to a CoAP Method according to Table 6.2.1‑1.
  2. After processing the oneM2M request, the Receiver shall send the oneM2M response in a CoAP response with a CoAP response code as given by

    After processing the oneM2M request, the Receiver shall send the oneM2M response in a CoAP response with a CoAP response code as given by Table 6.2.4‑1.

    Table 6.2.4‑1.
    • If the oneM2M request was sent as a CoAP Confirmable message, the Receiver may either piggyback this response to the request on the CoAP ACK message, or send the response as a separate CoAP Confirmable message after it has sent the CoAP ACK.
    • If the oneM2M request was sent as a Non-confirmable message, the oneM2M response shall be returned as a separate CoAP message. This response should be sent as a Non-confirmable CoAP message but it may be sent as Confirmable (this means that a receiver can, if it so chooses, send all Responses as Confirmable regardless of how the Request was sent).
  3. The Originator's CoAP binding may generate a response primitive containing a oneM2M

    The Originator's CoAP binding may generate a response primitive containing a oneM2M Response Status Code of "REQUEST_TIMEOUT" if it considers that it has taken too long for the CoAP response to come back from the Receiver. It shall ignore any response to the original request that it might receive after it has done this.

    Response Status Code of "REQUEST_TIMEOUT" if it considers that it has taken too long for the CoAP response to come back from the Receiver. It shall ignore any response to the original request that it might receive after it has done this.

6.3.2 Non-Blocking Asynchronous case

  1. If the

    If the Response Type parameter is configured as "nonBlockingRequestAsynch" (non-blocking asynchronous case), the Originator (CoAP client) should send the oneM2M request to the Receiver (CoAP server) as a CoAP Confirmable message. This request shall be sent using the CoAP POST method, and shall include the Operation parameter, mapped as described in clause 6.2.2.3.

    Response Type parameter is configured as "nonBlockingRequestAsynch" (non-blocking asynchronous case), the Originator (CoAP client) should send the oneM2M request to the Receiver (CoAP server) as a CoAP Confirmable message. This request shall be sent using the CoAP POST method, and shall include the Operation parameter, mapped as described in clause 6.2.2.3.
  2. The Receiver, after validating the request and before processing it fully, shall return a oneM2M response to the originator. It may either piggyback (2a) this response on the CoAP ACK message (if the request was sent as a Confirmable message) or send the response as a separate CoAP response message after it has sent the CoAP ACK (2b). In this latter case it shall send the response as a Confirmable message.

    The Receiver, after validating the request and before processing it fully, shall return a oneM2M response to the originator. It may either piggyback (2a) this response on the CoAP ACK message (if the request was sent as a Confirmable message) or send the response as a separate CoAP response message after it has sent the CoAP ACK (2b). In this latter case it shall send the response as a Confirmable message.

    • If the Receiver supports the <request> resource type, it shall respond with a 2.01 (Created) CoAP response code and a oneM2M Response Status Code of "ACCEPTED for nonBlockingRequestAsynch". The response shall include the URI of the new <request> resource in a sequence of one or more Location-Path and/or Location-Query Options.
    • If the Receiver does not support the <request> resource type, it shall respond with a 2.04 (Changed) CoAP response code and a oneM2M Response Status Code of "ACCEPTED for nonBlockingRequestAsynch".
  3. The Receiver, upon successful processing of the request, shall send a new CoAP Confirmable request message using the CoAP POST method. This message contains a oneM2M NOTIFY primitive whose content contains the response to the original request.

    The Receiver, upon successful processing of the request, shall send a new CoAP Confirmable request message using the CoAP POST method. This message contains a oneM2M NOTIFY primitive whose content contains the response to the original request.

  4. The Originator may either piggyback a response to this request (4a) or send it as a separate CoAP response after the acknowledgment message (4b). This response shall contain the appropriate CoAP response code as defined in

    The Originator may either piggyback a response to this request (4a) or send it as a separate CoAP response after the acknowledgment message (4b). This response shall contain the appropriate CoAP response code as defined in Table 6.2.4‑1 and have an empty payload.

    table 6.2.4‑1 and have an empty payload.
Figure 6.3.2-1: Non-Blocking Asynchronous CaseFigure 6.3.2-1: Non-Blocking Asynchronous Case
Figure 6.3.2‑1: Non-Blocking Asynchronous Case

Figure 6.3.2‑1: Non-Blocking Asynchronous Case

6.3.3 Non-Blocking Synchronous case

  1. If the

    If the Response Type parameter is configured as "nonBlockingRequestSynch" (non-blocking synchronous case), the Originator (CoAP client) should send the oneM2M request to the Receiver (CoAP server) as a CoAP Confirmable message. This request shall be sent using the CoAP POST method, and shall include the Operation parameter, mapped as described in clause 6.2.2.3.

    Response Type parameter is configured as "nonBlockingRequestSynch" (non-blocking synchronous case), the Originator (CoAP client) should send the oneM2M request to the Receiver (CoAP server) as a CoAP Confirmable message. This request shall be sent using the CoAP POST method, and shall include the Operation parameter, mapped as described in clause 6.2.2.3.
  2. The Receiver, after validating the request and before processing it fully, shall return a oneM2M response to the originator. It may either piggyback this response (2a) on the CoAP ACK message (if the request was sent as a CON message) or send the response as a separate CoAP message after it has sent the CoAP ACK (2b). In this latter case it shall send the response as a Confirmable message.

    The Receiver, after validating the request and before processing it fully, shall return a oneM2M response to the originator. It may either piggyback this response (2a) on the CoAP ACK message (if the request was sent as a CON message) or send the response as a separate CoAP message after it has sent the CoAP ACK (2b). In this latter case it shall send the response as a Confirmable message.

    • If the Receiver supports the <request> resource type, it shall respond with a 2.01 (Created) CoAP response code and a oneM2M Response Status Code of "ACCEPTED for nonBlockingRequestSynch". The response shall include the URI of the new <request> resource in a sequence of one or more Location-Path and/or Location-Query Options.
    • If the Receiver does not support the <request> resource type, it shall respond with a 5.01 (Not implemented) CoAP response code and a oneM2M Response Status Code of "NON_BLOCKING_SYNCH_REQUEST_NOT_SUPPORTED".
  3. The Originator can use the <

    The Originator can use the <request> resource reference to make a blocking synchronous request to retrieve the <request> resource that corresponds to the original request.

    request> resource reference to make a blocking synchronous request to retrieve the <request> resource that corresponds to the original request.
  4. The Receiver, upon receipt of this retrieve request, shall handle it as in clause

    The Receiver, upon receipt of this retrieve request, shall handle it as in clause 6.3.1 since it is a blocking request.

    6.3.1 since it is a blocking request.

NOTE: If the Receiver is a Transit CSE, the Receiver acts as CoAP client and CoAP server.

Figure 6.3.3-1: Non-Blocking Synchronous CaseFigure 6.3.3-1: Non-Blocking Synchronous Case
Figure 6.3.3‑1: Non-Blocking Synchronous Case

Figure 6.3.3‑1: Non-Blocking Synchronous Case

6.3.4 Flex Blocking case

  1. If the

    If the Response Type parameter is configured as "flex blocking", the Originator (CoAP client) should send the oneM2M request to the Receiver (CoAP server) as a CoAP Confirmable message. This request shall be sent using the CoAP POST method, and shall include the Operation parameter, mapped as described in clause 6.2.2.3.

    Response Type parameter is configured as "flex blocking", the Originator (CoAP client) should send the oneM2M request to the Receiver (CoAP server) as a CoAP Confirmable message. This request shall be sent using the CoAP POST method, and shall include the Operation parameter, mapped as described in clause 6.2.2.3.
  2. The Receiver shall determine whether to handle the request using "nonBlockingRequestSynch" or "nonBlockingRequestAsynch" mode:

    The Receiver shall determine whether to handle the request using "nonBlockingRequestSynch" or "nonBlockingRequestAsynch" mode:

    • If the Receiver chooses "nonBlockingRequestAsynch" processing proceeds as described in clause clause 6.3.2, starting from step 2).
    • If the Receiver chooses "nonBlockingRequestSynch" processing proceeds as described in clause clause 6.3.3, starting from step 2).

6.4 Mapping rules of caching

This clause specifies how to enable or disable CoAP caching mechanism and how to use cached information.

If the CoAP end point supports caching mechanism by freshness, the CoAP server shall:

  • set the Max-Age Option value to "0" (zero) to disable caching, in order to support complete oneM2M mapping; or
  • set the Max-Age option value to another value (such as the default value), in order to use CoAP caching mechanism for constrained environment. > NOTE 1: In the second case, the new request from oneM2M layer can get the stored fresh response from CoAP client, not from CoAP server.

NOTE 1: In the second case, the new request from oneM2M layer can get the stored fresh response from CoAP client, not from CoAP server.

If the CoAP end point supports caching mechanism by validity:

  • the CoAP server shall not present Etag in responses to disable caching, in order to support complete oneM2M mapping; or
  • the CoAP server shall present Etag in responses, in order to use CoAP caching mechanism for constrained environment. > NOTE 2: In the second case, the new request from oneM2M layer can get the stored fresh response from CoAP server, not from oneM2M layer.

NOTE 2: In the second case, the new request from oneM2M layer can get the stored fresh response from CoAP server, not from oneM2M layer.

6.5 Usage of Block-wise Transfers

Using Block Options, large oneM2M resource representations can be fragmented and reassembled by CoAP independently of the lower layers as well as the above application. The CoAP Block1 Option shall be used to define the size of the blocks used for oneM2M request primitives and the CoAP Block2 Option shall be used to define the size of the blocks used for oneM2M response responses. Refer to IETF RFC 7959 [3] for further details.

6.6 Use of the CoAP FETCH method

When both Originator and Receiver are using oneM2M Release 5 or later all Blocking RETRIEVE requests shall be sent using the CoAP FETCH method defined in IETF RFC 8132 [6]. The FETCH method differs from the GET method in that it contains a CoAP payload.

The CoAP payload shall be set to contain the oneM2M Request primitive, serialized as described in clause clause 6.2.2.

IETF RFC 8132 requires that the CoAP Content-Format option be present in the request to indicate the nature of the payload. The Content-Format shall be set to one of the oneM2M-specific MIME media type values defined in clause 6.2.2.2[6] requires that the CoAP Content-Format option be present in the request to indicate the nature of the payload. The Content-Format shall be set to one of the oneM2M-specific MIME media type values defined in clause 6.2.2.2. The value to use depends on the encoding used for the request as follows:

  • application/vnd.onem2m-preq+xml if the request is encoded using XML
  • application/vnd.onem2m-preq+json if the request is encoded using JSON
  • application/vnd.onem2m-preq+cbor if the request is encoded using CBOR