TS-0009 : Clarification and correction for partial RETRIEVE
oneM2M optionally allows for RETRIEVE requests to specify one or more attributes that shall be included in the result content. Unfortunately, there are two different ways to do this, as specified in TS-0004, 7.3.3.6:
Partial retrieve request: there are two cases:
Case 1) the request target is a resource given in the To parameter and specific attribute names are provided in the Content parameter:
The values of the resource attribute(s) provided in the Content parameter shall be retrieved.
Case 2) the request target is a resource given in the To parameter, the resource attribute is provided in the To parameter as a fragment identifier component of URI following '#' character [2]. The resource attribute shall be represented as a short name and shall belong to short name list in Table 8.2.31 to Table 8.2.35.
Actually, there is one further inaccuracy in the above specification: Is case 2) mandatory to use if there is only one target attribute in the request, or is it still allowed to use case 1) as well? Perhaps this is a question for another issue.
The problem in TS-0009, 6.2.2.2 Query component, is in the following paragraphs:
For partial Retrieve request primitives, the To parameter may include the name of a single attribute separated by a ‘#’ character from the resource ID. If multiple resource attributes are to be retrieved with a partial retrieve request primitive, these attributes are included in form of an attributeList object (as specified in Table 6.3.3-1 of TS-0004 [3]) in the Content parameter.
In both cases, the short resource attribute name(s) shall be included into the fragment component of request-target, i.e. it shall follow any required query-string separated by ‘#’ character. If more than a single attribute name is included into the fragment component, these shall be separated by a ‘+’ character.
For example, if three resource attributes with long names resourceID, labels and requestReachability are indicated in the Content primitive parameter, the query component atrl=ri+lbl+rr is attached to the request-target. In case just a single attribute “rr” is indicated in the To parameter separated by ‘#’ character, the query component atrl=rr is attached to the request-target. The ‘#’ character and following attribute name shall be omitted from the path component of the request line.
[ examples omitted ]
At the HTTP server side, the reverse operation shall take place, when constructing the retrieve request primitive from the receive HTTP request message. Single attribute names in the query component may either be mapped back into the To parameter following a ‘#’ character, or included into the Content parameter using the attributeList format with just a single list element included. Multiple attributes shall be included into the Content parameter as specified in oneM2M TS-0004 [3].
The problem is that the second and thirds paragraph contractict themselves. Following the second paragraph the target attributes are added to a URL like this:
<target resource URI>#ri+lbl+rr
The third paragraph, however, specifies the (IMHO correct) form:
<target resource URI>?atrl=ri+lbl+rr
Or for a a single attribute:
<target resource URI>?atrl=rr
Another problem is with the form of the third paragraph, which indicates at the beginning that it is an example, but the second sentence is actually a specification.
The last issue may be with paragraph four. Is the plural form in the sentence "Single attribute names in the query component may either be mapped back..." correct?
Also the procedure defined in the fourth paragraph allows to move a single attribute to the attributeList. Is this allowed? (see the question above).
Proposal
Change the text in TS-0009 to:
For partial Retrieve request primitives, the To parameter may include the name of a single attribute separated by a ‘#’ character from the resource ID. If multiple resource attributes are to be retrieved with a partial retrieve request primitive, these attributes are included in form of an attributeList object (as specified in Table 6.3.3-1 of TS-0004 [3]) in the Content parameter.
In case just a single attribute is indicated in the To parameter separated by ‘#’ character, the query component atrl=rr is attached to the request-target. The ‘#’ character and following attribute name shall be omitted from the path component of the request line.
In case the attributeList object is present in the Content parameter, the attribute names in that list are added to the query component atrl. If more than a single attribute name is included into the fragment component, these shall be separated by a ‘+’ character.
For example, if three resource attributes with long names resourceID, labels and requestReachability are indicated in the Content primitive parameter, the query component atrl=ri+lbl+rr is attached to the request-target.
[ examples omitted ]
At the HTTP server side, the reverse operation shall take place, when constructing the retrieve request primitive from the receive HTTP request message. Single attribute names in the query component shall be mapped back into the To parameter following a ‘#’ character. Multiple attributes shall be mapped into the Content parameter using the attributeList format as specified in oneM2M TS-0004 [3].