Resource Identifier Scopes and Formats
Resource identifiers in oneM2M are used to identify and to point to resources. They are usually used in requests as well as in resource attributes. They are string of unreserved1 characters used to uniquely identify the target resource within the scope of a request to access the resources.
Resource Identifier Scopes
The possible address scope for a resource identifier is one of the following.
CSE-relative
The resource identifier addresses a resource that resides on the same CSE that is being targeted by a request or another resource.
In that case the CSE-relative format of a resource identifier can be used to address the resource.
SP-relative
The resource identifier addresses a resource that resides on a CSE within the same M2M Service Provider domain as the Originator of the request. This means that the resource identifier might point to a resource that is not necessarily hosted on the same CSE that is, for example, currently processing a request.
In this case an SP-relative format of a resource identifier can be used to address the resource.
Absolute
The resource identifier is targeting a resource that resides on a CSE that is located in an M2M Service Provider domain that may be different from the M2M Service Provider's domain of the originator of a request.
In this case the absolute format of a resource identifier shall be used to address the resource. Note, that the absolute format of the resource identifier will always be acceptable also in other cases.
How do Resource Identifiers look like
A single resource may be identified by all of the above resource identifier formats depending on the method and scopes that are summarized in the following table. There are two different methods for identifying a resource within the oneM2M resource structure with three different variants each depending on the scope of the request to access the resource.
The ways how the resource identifiers are constructed in each case shall follow:
| Method | CSE-relative Scope | SP-relative Scope | Absolute Scope |
|---|---|---|---|
| Unstructured | Unstructured-CSE-relative-Resource-ID format of the resource identifier. | SP-relative-Resource-ID format of the resource identifier constructed with a Unstructured-CSE-relative-Resource-ID. | Absolute-Resource-ID format of the resource identifier constructed with a Unstructured-CSE-relative-Resource-ID. |
| Structured | Structured-CSE-relative-Resource-ID format of the resource identifier. | SP-relative Resource-ID format of the resource identifier constructed with the Structured-CSE-relative-Resource-ID. | Absolute-Resource-ID format of the resource identifier constructed with the Structured-CSE-relative-Resource-ID. |
| Hybrid | Unstructured-CSE-relative-Resource-ID format of the resource identifier, and add the resourceName of a virtual resource. | SP-relative-Resource-ID format of the resource identifier constructed with a Unstructured-CSE-relative-Resource-ID, and add the resourceName of a virtual resource. | Absolute-Resource-ID format of the resource identifier constructed with a Unstructured-CSE-relative-Resource-ID, and add the resourceName of a virtual resource. |
See also What are Structured and Unstructured Resource Addresses?
Examples of Addressing Methods
The following examples show the different addressing methods for resources and CSE bases.
TODO better description here: Also, examples for the mapping to http URIs are given.
| Method | Examples |
|---|---|
| Unstructured ID | MyResourceID CSEResourceID |
| Unstructured HTTP | http://ipAddress:port/MyResourceID http://ipAddress:port/CSEResourceID |
| Structured ID | CSEName/MyAEName/MyResourceName CSEName |
| Structured HTTP | http://ipAddress:port/CSEName/MyAEName/MyResourceName http://ipAddress:port/CSEName |
| Hybrid ID | MyResourceID/MyVirtualResourceName CSEresourceID/MyVirtualResourceName |
| Hybrid HTTP | http://ipAddress:port/MyResourceID/MyVirtualResourceName http://ipAddress:port/CSEResourceID/MyVirtualResourceName |
| Method | Examples |
|---|---|
| Unstructured ID | /CSEID/MyResourceID /CSEID/CSEResourceID |
| Unstructured HTTP | http://ipAddress:port/~/CSEID/MyResourceID http://ipAddress:port/~/CSEID/CSEResourceID |
| Structured ID | /CSEID/CSEName/MyAEName/MyResourceName /CSEID/CSEName |
| Structured HTTP | http://ipAddress:port/~/CSEID/CSEName/MyAEName/MyResourceName http://ipAddress:port/~/CSEID/CSEName |
| Hybrid ID | /CSEID/MyResourceI/MyVirtualResourceNamebr /CSEID/CSEResourceID/MyVirtualResourceName |
| Hybrid HTTP | http://ipAddress:port/~/CSEID/MyResourceID/MyVirtualResourceName http://ipAddress:port/~/CSEID/CSEResourceID/MyVirtualResourceName |
| Method | Examples |
|---|---|
| Unstructured ID | //SPID/CSEID/MyResourceID //SPID/CSEID/CSEResourceID |
| Unstructured HTTP | http://ipAddress:port/_/SPID/CSEID/MyResourceID http://ipAddress:port/_/SPID/CSEID/MyResourceID |
| Structured ID | //SPID/CSEID/CSEName/MyAEName/MyResourceName //SPID/CSEID/CSEName |
| Structured HTTP | http://ipAddress:port/_/SPID/CSEID/CSEName/MyAEName/MyResourceName http://ipAddress:port/_/SPID/CSEID/CSEName |
| Hybrid ID | //SPID/CSEID/MyResourceID/MyVirtualResourceName //SPID/CSEID/CSEResourceID/MyVirtualResourceName |
| Hybrid HTTP | http://ipAddress:port/_/SPID/CSEID/MyResourceID/MyVirtualResourceName http://ipAddress:port/_/SPID/CSEID/MyResourceID/MyVirtualResourceName |
Notes
- A structured path is constructed out of the individual resourceNames of the resources that form the path. It always includes the resourceName of the CSE.
- A hybrid resource address always consists of the unstructured resource ID plus the resourceName of a virtual resource, for example
cnt1234/la. This is used to address, for example, the "latest" virtual resource of a container, using an unstructured address to access the container.
by Andreas Kraft, 2023-08-08