Resource Query

This document specifies the Query features that a Service Provider needs to implement on top of a domain specification for Reporting. The Reporting Consumer will base on this specification for their expectation of the Query features supported by a Service Provider on Reporting.

This document only makes references to the Query Resource as defined in the OSLC Core Specification (hereafter will be referred as OSLC Query Specification). The actual specification of the Query is defined in the OSLC Core Specification and won't be repeated in this document.

This document may tighten the constraints as specified in the OSLC Query Specification, but will not relax them.

Query Requirements

Based on the ReportingUseCases, the following requirements are identified for resource query.

1. Getting data on a list of resources of the same type and their properties.
   • identify a subset of the properties of the resource that the Reporting Consumer is interested in.
   • optionally, specify a filter based on the resource property values to constrain the data coming back.
   • optionally, specify a sort based on the resource property values to order the sequence of the data coming back.
2. Getting data on a resource and its property.
   • identify a subset of the properties of the resource that the Report Consumer is interested in.

Query Specification for Reporting

Use Case:

1. ETL
2. Live Reporting
3. Document Generation

1. OSLC Service MUST support query that returns at least those properties that were described in Resource Shape Resource. Reporting consumers MUST tolerate additional unknown properties that MAY be returned by oslc.properties=* and oslc.select=*.
   1. all properties of a resource as described by the Resource Shape Resource (support oslc.properties=*) [use case 2, 3]
   2. all properties of a resource as described by the Resource Shape Resource for all the resources in a collection (support oslc.select=*) [use case 1, 2, 3]
2. OSLC Service SHOULD support oslc.properties, oslc.select. [use case 1, 2, 3]
3. OSLC Service SHOULD support oslc.where. [use case 1, 2, 3]
4. OSLC Service SHOULD support oslc.orderBy. [use case 2, 3]
5. OSLC Service SHOULD support oslc.prefix. [use case 1, 2, 3]
6. OSLC Service SHOULD support oslc.limit. [use case 2, 3]
7. OSLC Service MAY support oslc.offset.
8. OSLC Servicer MUST support paging in the Core Spec. [use case 1, 2, 3]
9. OSLC Resources SHOULD have a property dc:modified for modification timestamp.Reporting Consumer will use this property in oslc.where to effect delta loading for the data warehouse use case. [use case 1]
10. OSLC Service MUST respond with error if any of the query parameters in the request (from Consumer) is not supported.
11. How the Reporting Consumer handles error is not specified by this document and left to the Reporting Consumer to decide. One possible scenario is :
    • Send request with MUST, SHOULD, MAY parameters
    • if error, send request with MUST, SHOULD parameters
    • if erro, send request with MUST parameters

Comments

Add your comments here:

>> it (SHOULD/MAY?) support oslc.orderBy. (Question: what is the behavior if oslc.orderBy is receieved by not supported?)
The service provider should throw an error specifying that orderBy is not supported. Failing to do so could lead to user failing to observe the document is not sorted as expected.

-- DragosCojocari - 01 Mar 2010

>> Service Provider MUST support query that returns a default set of properties.
What does this imply? That if oslc.select is omitted in the request, then it is up to the service provider to define what should be returned? OR that if oslc.select=* then service provider MUST return ALL properties or just its "default" properties?

-- SteveSpeicher - 11 Mar 2010

Following on Dragos comment, what happens when any of the "SHOULD" or "MAY" items are not supported? Can this be discovered? What error is given if not provided?

-- SteveSpeicher - 11 Mar 2010

The service such return an error response if it does not understand any semantically significant query parameter.

-- ArthurRyman - 15 Mar 2010

To Dragos and Steve's comment on non-supported "SHOULD" and "MAY", OSLC Service MUST respond with error as stated in item 10 of the spec above. The OSLC Core Spec. should define how OSLC Service respond with errors.

-- TackTong - 15 Mar 2010

To Steve's comment on "default set of properties", I updated item 1 above with the following for clarificaiton. OSLC Service MUST support query that returns at least those properties that were described in Resource Shape Resource. Reporting consumers MUST tolerate additional unknown properties that MAY be returned by oslc.properties=* and oslc.select=*.

-- TackTong - 15 Mar 2010