OSLC Query provides a mechanism for a client to query or search for RDF resources that match a given criteria. The response to a successful query includes the RDF of a query result container that references the member resources found by the query, and optionally includes selected properties of each member resource.

Introduction

OSLC Query provides a mechanism for a client to query or search for RDF resources by performing a GET or POST on a oslc:queryBase URI. Clients may discover such query base URIs from a oslc:queryCapability declared in an OSLC service. The response to a successful query is a response body that includes the RDF of a query result container that references the member resources matching the query, and optionally contains selected properties of each member resource.

Two separate capabilities may be provided:

Servers may support a combined query and full-text search. Clients may also specify which member properties should be included in the query response.

Terminology

Terminology is based on OSLC Core Overview [[OSLC-Core-30-Part1]], W3C Linked Data Platform [[LDP]], W3C's Architecture of the World Wide Web [[WEBARCH]], and Hyper-text Transfer Protocol [[HTTP11]].

Query capability
Describes an HTTP endpoint that may be used to query for or search for artifacts that match the given criteria.
Query base URI
The URI associated with a query capability that a GET and/or POST on will perform a query or search for artifacts.
Query expression
A string that defines one or more query terms, where each term defines a property name, operator, and value.
Query result container
An RDF container in the response to a successful query or search that references the resources found.
Search term
A text string or keyword that is to be searched for in any text property of artifacts of a type specified by a query capability.
Sort key
A property to be used to sort the results of the query based on the value of the property for each member of the query result container.

References

Namespaces

In addition to the namespace URIs and namespace prefixes oslc, rdf, rdfs, dcterms, ldp and foaf defined in the [[OSLC-Core-30-Part1]], this specification also uses the following namespace prefix definitions:

Motivation

OSLC servers will often manage large amounts of potentially complex resources. Practical use of this information will require some query capability that minimally supports selection of matching elements, filtering of desired properties and ordering. Ideally OSLC Core would rely on existing standard query services such as [[RDF-SPARQL-QUERY]]. However, the reality is that many OSLC servers are adapters built on existing data management capabilities that are not built on an RDF foundation and do not provide SPARQL endpoints for query. In order to address the need for standard query capability to enable integration, [[OSLC-Core-30-Part1]] defines a Query Capability and a Query Syntax that are intended to be simple enough that they can be implemented on a wide range of existing server architectures and persistence technologies. This specification improves on the [[OSLCCore2]] query capability by:

Discovering a Query Capability

Clients may discover query capabilities as described in [[OSLC-Discovery-30]] using the oslc:queryCapability property of an oslc:Service. The relationship between these resources is shown in Figure 1.

Figure 1 - OSLC discovery resources

A query capability SHOULD specify exactly one oslc:resourceShape and that shape SHOULD describe the query result container.

The resource shape referenced by oslc:resourceShape MUST declare at least one OSLC property with oslc:isMemberProperty "true"^^xsd:boolean, and that property SHOULD specify exactly one oslc:valueShape referencing a resource shape that describes the referenced members of that container. 

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix oslc: <http://open-services.net/ns/core#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .


<https://example.org/jazz/oslc/context/_Q2fMII8EEd2Q-OW8dr3S5w/trs/shapes/workitems/query> a oslc:ResourceShape ;
    oslc:describes <https://example.org/jazz/oslc/contexts/_Q2fMII8EEd2Q-OW8dr3S5w/workitems> ;
    oslc:property <https://example.org/jazz/oslc/context/_Q2fMII8EEd2Q-OW8dr3S5w/trs/shapes/workitems/query/property/member> ;
    dcterms:title "Shape of Work Item query resource"^^rdf:XMLLiteral .


<https://example.org/jazz/oslc/context/_Q2fMII8EEd2Q-OW8dr3S5w/trs/shapes/workitems/query/property/member>
    a oslc:Property ;
    oslc:isMemberProperty "true"^^xsd:boolean ;
    oslc:name "member" ;
    oslc:occurs oslc:Zero-or-many ;
    oslc:propertyDefinition rdfs:member ;
    oslc:range <http://open-services.net/ns/cm#ChangeRequest> ;
    oslc:readOnly "true"^^xsd:boolean ;
    oslc:representation oslc:Inline ;
    oslc:valueShape <https://example.org/jazz/oslc/context/_Q2fMII8EEd2Q-OW8dr3S5w/shapes/workitems/defect> ;
    oslc:valueType oslc:AnyResource ;
    dcterms:title "Work Item Member"^^rdf:XMLLiteral .

The resource shape referenced by oslc:valueShape in the query result container's resource shape SHOULD declare the properties that can be used in oslc.select and optionally oslc.where.

OSLC properties that have a oslc:queryable "false"^^xsd:boolean value cannot be specified in oslc.where.

Where a member resource supports nested properties, for example, the foaf:name of a dcterms:creator, the member resource shape MAY provide a oslc:valueShape for that property.

This allows clients to discover both immediate and nested properties that might be used.

Using a Query Capability

Executing a query or search is achieved by performing either of the following:

Servers MUST support a GET on the oslc:queryBase of a query capability.

Servers SHOULD support POST on the oslc:queryBase of a query capability to avoid clients having to construct URIs that are too long for a GET.

A GET or POST request on the oslc:queryBase of a query capability MAY use zero, one or more of the OSLC query parameters listed in Table 1.

Clients should use the POST mechanism described above if the URI of a GET would otherwise be too long.

For a successful operation, the response status code MUST be 200 OK for a non-paged result, or for an OSLC paged result.

For a successful operation, the response body MUST be RDF that includes a query result container whose subject is the oslc:queryBase.

Table 1 - OSLC Query Parameters

Parameter Description
oslc.where Limits the query results to members that satisfy the specified query expression.
oslc.searchTerms Score each member resource using a full-text search on its text-valued properties, and sort them in descending order of score.
oslc.orderBy Sort the members using the specified sort keys. If supported, servers SHOULD include the oslc:order pseudo-property, and for a paged response, order the pages so that the first page contains the lowest ordered members, and the last page contains the highest ordered members. See oslc.orderBy for details.
oslc.select Include the specified immediate and nested properties of the member resources. See oslc.select for details.
oslc.prefix Specify a namespace prefix that may be used in oslc.where, oslc.orderBy, and oslc.select. See oslc.prefix in [[OSLC-Core-30-Part1]] for details.
oslc.paging Specifies whether a paged result is requested. See Resource paging in [[OSLC-Core-30-Part1]] and oslc.paging for details.
oslc.pageSize Specifies a suggested maximum page size for a paged result. See Resource paging in [[OSLC-Core-30-Part1]] and oslc.pageSize for details..

If a GET or POST on a oslc:queryBase neither specifies oslc.where nor oslc.searchTerms, the server MUST return a query response describing all the resources that have one or more of the RDF types specified by the oslc:resourceType of the oslc:QueryCapability that defines the oslc:queryBase.

Query Result Containers

The response body for a successful GET or POST on a oslc:queryBase MUST include a query result container whose subject is the oslc:queryBase URI.

The container SHOULD be a Linked Data Platform Container (LDPC) referencing each member resource found by the query. The response SHOULD include a Link header that describes the type of LDPC returned. This provides compatibility with OSLC Core 3.0 and its wider use of LDPCs. [[LDP]]

If the query capability that declared the base URI does not declare a oslc:resourceShape then the container MUST include an rdfs:member reference to each of the result members.

If the query capability that declared the base URI declares a oslc:resourceShape and that resource shape defines a container property with oslc:isMemberProperty "true"^^xsd:boolean then the query result container MUST include the specified member property referencing each of query result member. 

HTTP/1.1 200 OK
Content-Type: text/turtle
ETag: "_87e52ce291112"
Link: <http://www.w3.org/ns/ldp#DirectContainer>; rel="type",
      <http://www.w3.org/ns/ldp#Resource>; rel="type"


@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix ldp: <http://www.w3.org/ns/ldp#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix ex: <http://example.org/>.

<http://example.org/queryBase/>
   a ldp:DirectContainer;
   ldp:membershipResource <http://example.org/queryBase/>;
   ldp:hasMemberRelation rdfs:member;
   ldp:contains ex:member1, ex:member2;
   rdfs:member ex:member1, ex:member2.

If the query capability that declared the base URI declares a oslc:resourceShape and that resource shape defines a container property with oslc:isMemberProperty "true"^^xsd:boolean that is ldp:contains, the query result container may use any form of LDPC, such as ldp:BasicContainer. This provides the most compact representation of query result members that is compatible with OSLC Query 2.0 and conformant with LDPC [[LDP]]. All of the examples showing a query response following this section assume that the query capability resource shape defines that ldp:contains is the membership property. 

HTTP/1.1 200 OK
Content-Type: text/turtle
ETag: "_87e52ce291112"
Link: <http://www.w3.org/ns/ldp#BasicContainer>; rel="type",
      <http://www.w3.org/ns/ldp#Resource>; rel="type"


@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix ldp: <http://www.w3.org/ns/ldp#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix ex: <http://example.org/>.

<http://example.org/queryBase/>
   a ldp:BasicContainer;
   ldp:contains ex:member1, ex:member2.

Query Result Paging

A query capability MAY support Resource paging as described in [[OSLC-Core-30-Part1]].

A paged response MAY occur if paging is supported and the request includes a oslc.paging=true query parameter, or automatically if the server determines that the total query result set exceeds some implementation dependent threshold.

Query Parameters

Introduction

The query parameters defined here are intended to satisfy simple query requirements, and be easy to both use and implement. More complex query requirements should be satisfied using a full query language, e.g. SQL, SPARQL or whatever query language the server and/or its underlying data sources support.

This specification formally defines the syntax of the oslc.where, oslc.searchTerms, and oslc.orderBy parameters using Backus-Naur Form [[BNF]] and informally illustrates their semantics with simple examples. See oslc.where syntax, oslc.searchTerms syntax, and oslc.orderBy syntax for the formal syntax.

The query parameters MAY contain characters that MUST be URL encoded when transmitted in an HTTP request.

The examples below show both unencoded and encoded query parameters for clarity.

All query parameter names are prefixed with the characters "oslc." The following sections define these query parameters.

An OSLC domain specification MAY use some or all of these query parameters, and SHOULD use these rather than defining new query parameters that have the same or very similar meanings. Each of these query parameters SHOULD appear at most once in a query. The behavior is undefined when a query parameter appears more than once.

In the following sections, syntax is formally defined using a common extended form of BNF. Informal definitions and comments are delimited by /* and */.

oslc.where

Introduction

The oslc.where query parameter defines a query expression that is used to query for resources matching the query expression. It is serves a similar purpose to the WHERE clause of a SQL statement.

For example, suppose that a change management system provides a query capability with a oslc:queryBase of https://example.org/ccm/oslc/contexts/_by884MNWEeekg_dNxwf1pg/workitems, and a client wants to query for all change requests created by the user https://example.org/jts/users/deb. This can be performed using a GET on https://example.org/ccm/oslc/contexts/_by884MNWEeekg_dNxwf1pg/workitems using the query parameters shown in Table 2:

Table 2 - oslc.where parameter

Parameter Unencoded value
oslc.where dcterms:creator=<https://example.org/jts/users/deb> 

    GET https://example.org/ccm/oslc/contexts/_by884MNWEeekg_dNxwf1pg/workitems
        ?oslc.where=dcterms%3Acreator%3D%3Chttps%3A%2F%2Fexample.org%2Fjts%2Fusers%2Fdeb%3E

    OSLC-Core-Version: 2.0
    Accept: text/turtle

    -- response --
    200 OK
    Etag:  "5f836103-c64e-3c3f-aa5e-dd0baec92511"
    OSLC-Core-Version:  2.0
    Vary:  Accept, OSLC-Core-Version
    Content-Type:  text/turtle;charset=UTF-8
    Content-Language:  en-US
    Link: <http://www.w3.org/ns/ldp#BasicContainer>; rel="type", <http://www.w3.org/ns/ldp#Resource>; rel="type"

    @prefix dcterms:  <http://purl.org/dc/terms/> .
    @prefix ldp:     <http://www.w3.org/ns/ldp#> .
    @prefix oslc:    <http://open-services.net/ns/core#> .
    @prefix rdfs:    <http://www.w3.org/2000/01/rdf-schema#> .
    @prefix rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

    <https://example.org/ccm/oslc/contexts/_by884MNWEeekg_dNxwf1pg/workitems>
        a ldp:BasicContainer ;
        ldp:contains
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/9> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/22> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/11> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/20> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/1> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/27> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/28> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/17> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/5> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/23> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/7> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/12> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/8> .
Note that the query result in the above example does not contain any properties of the members found by the query because oslc.select was not specified. Clients should specify oslc.select if they require a specific set of member properties to be included in the response.

Conditions may use the usual binary comparison operators and be combined using the boolean conjunction operator, and.

Suppose a client now wants to query for all change requests created by Deb that are not fixed. This can be performed using a GET on https://example.org/ccm/oslc/contexts/_by884MNWEeekg_dNxwf1pg/workitems using the query parameters shown in Table 3:

Table 3 - oslc.where parameter

Parameter Unencoded value
oslc.where dcterms:creator=<https://example.org/jts/users/deb> and oslc_cm:fixed=false 

    GET https://example.org/ccm/oslc/contexts/_by884MNWEeekg_dNxwf1pg/workitems
        ?oslc.where=dcterms%3Acreator%3D%3Chttps%3A%2F%2Fexample.org%2Fjts%2Fusers%2Fdeb%3E%20and%20oslc_cm%3Afixed%3Dfalse

    OSLC-Core-Version: 2.0
    Accept: text/turtle

    -- response --
    200 OK
    Etag:  "5f836103-c64e-3c3f-aa5e-dd0baec92511"
    OSLC-Core-Version:  2.0
    Vary:  Accept, OSLC-Core-Version
    Content-Type:  text/turtle;charset=UTF-8
    Content-Language:  en-US
    Link: <http://www.w3.org/ns/ldp#BasicContainer>; rel="type", <http://www.w3.org/ns/ldp#Resource>; rel="type"

    @prefix dcterms:  <http://purl.org/dc/terms/> .
    @prefix ldp:     <http://www.w3.org/ns/ldp#> .
    @prefix oslc:    <http://open-services.net/ns/core#> .
    @prefix rdfs:    <http://www.w3.org/2000/01/rdf-schema#> .
    @prefix rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

    <https://example.org/ccm/oslc/contexts/_by884MNWEeekg_dNxwf1pg/workitems>
        a ldp:BasicContainer ;
        ldp:contains
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/22> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/20> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/1> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/27> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/28> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/5> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/23> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/7> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/8> .
An oslc.where query expression may query for nested properties. The following example show a query for change requests created by any user named "Deb". This can be performed using a GET on https://example.org/ccm/oslc/contexts/_by884MNWEeekg_dNxwf1pg/workitems using the query parameters shown in Table 4:

Table 4 - oslc.where parameter

Parameter Unencoded value
oslc.where dcterms:creator {foaf:name="Deb"} 

    GET https://example.org/ccm/oslc/contexts/_by884MNWEeekg_dNxwf1pg/workitems
        ?oslc.where=dcterms%3Acreator%20%7Bfoaf%3Aname%3D%22Deb%22%7D

    OSLC-Core-Version: 2.0
    Accept: text/turtle

    -- response --
    200 OK
    Etag:  "5f836103-c64e-3c3f-aa5e-dd0baec92511"
    OSLC-Core-Version:  2.0
    Vary:  Accept, OSLC-Core-Version
    Content-Type:  text/turtle;charset=UTF-8
    Content-Language:  en-US
    Link: <http://www.w3.org/ns/ldp#BasicContainer>; rel="type", <http://www.w3.org/ns/ldp#Resource>; rel="type"

    @prefix dcterms:  <http://purl.org/dc/terms/> .
    @prefix ldp:     <http://www.w3.org/ns/ldp#> .
    @prefix oslc:    <http://open-services.net/ns/core#> .
    @prefix rdfs:    <http://www.w3.org/2000/01/rdf-schema#> .
    @prefix rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

    <https://example.org/ccm/oslc/contexts/_by884MNWEeekg_dNxwf1pg/workitems>
        a ldp:BasicContainer ;
        ldp:contains
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/9> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/22> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/11> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/20> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/1> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/27> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/28> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/17> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/5> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/23> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/7> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/12> ,
            <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/8> .

oslc.where Syntax

    oslc_where    ::= "oslc.where=" compound_term
    compound_term ::= simple_term (space? boolean_op space? simple_term)*
    simple_term   ::= term | scoped_term
    space         ::= " " /* a space character */
    boolean_op    ::= "and"
    term          ::= identifier_wc comparison_op value | identifier_wc space in_op space? in_val
    scoped_term   ::= identifier_wc "{" compound_term "}"
    identifier_wc ::= identifier | wildcard
    identifier    ::= PrefixedName
    PrefixedName  ::= /* see "SPARQL Query Language for RDF", http://www.w3.org/TR/rdf-sparql-query/#rPrefixedName */
    wildcard      ::= "*"
    comparison_op ::= "=" | "!=" | "<" | ">" | "<=" | ">="
    in_op         ::= "in"
    in_val        ::= "[" value ("," value)* "]"
    value         ::= uri_ref_esc | PrefixedName | literal_value
    uri_ref_esc   ::= /* an angle bracket-delimited URI reference in which > and \ are \-escaped. */
    literal_value ::= boolean | decimal | string_esc (LANGTAG | ("^^" PrefixedName))?
    boolean       ::= "true" | "false"
    decimal       ::= /* see "XML Schema Part 2: Datatypes Second Edition", http://www.w3.org/TR/xmlschema-2/ */
    string_esc    ::= /* a string enclosed in double quotes, with certain characters escaped. See below. */
    LANGTAG       ::= /* see "SPARQL Query Language for RDF", http://www.w3.org/TR/rdf-sparql-query/#rLANGTAG */

wildcard
The "*" wildcard matches any property.

Implementations MAY support the use of the wildcard in property names and nested properties.



boolean_op
The boolean_op term represents a boolean operation that lets you combine simple boolean expressions to form a compound boolean expression. The only boolean operation allowed is " and " which represents conjunction. The boolean operator " or " for disjunction is not allowed in the interests of keeping the syntax simple. The effect of " or " in the simple case of testing a property for equality with one of several values can be achieved through the use of the " in " operator. For example, the following query expression might find change requests with severity "high" or "medium":

Table 5 - oslc.where parameter

Parameter Unencoded value
oslc.where oslc_cm:severity in ["high","medium"] 

            GET http://example.org/queryBase?oslc.where=oslc_cm%3Aseverity%20in%20%5B%22high%22%2C%22medium%22%5D
space
The space term represents a single space character.

A space character MAY be used to delimit the binary_op term in the compound_term term to improve readability.



comparison_op
The comparison_op term represents one of the following binary comparison operators:

Table 6 - Binary Comparison Operators

= test for equality
!= test for inequality
< test less-than
> test greater-than
<= test less-than or equal
>= test greater-than or equal

Semantics of datatypes and operations on these datatypes are described in oslc.where Semantics.

in_op
The in_op term represents the operator " in " which is a test for equality to any of the values in a list. The list is a comma-separated sequence of values, enclosed in square brackets, whose syntax is defined by the term in_val.

value
The value term represents either a URI reference (uri_ref_esc), a PrefixedName or a literal value (literal_value). The use of values and comparison operators is described in oslc.where semantics

literal_value
The literal_value term represents either a plain literal or a typed literal. A plain literal is a quoted string (string_esc), optionally followed by a language tag (LANGTAG). For example, "Bonjour"@fr is a plain literal with a language tag for French.

A typed literal is formed by suffixing a quoted string (string_esc) with "^^" followed by the prefixed name (PrefixedName) of a datatype URI.

If the range of a property includes literal values from more than one datatype, then a typed literal MUST be used in order to avoid ambiguity. Otherwise a plain literal MAY be used and the service SHOULD infer the datatype.

The terms boolean and decimal are short forms for typed literals. For example, true is a short form for "true"^^xsd:boolean, 42 is a short form for "42"^^xsd:integer and 3.14159 is a short form for "3.14159"^^xsd:decimal.

decimal
The decimal term represents a decimal number as defined in XML Schema Part 2: Datatypes Second Edition. As mentioned above, this term is a short form for typed literals whose datatype URIs are either xsd:integer or xsd:decimal. An integer literal value is a special case of a decimal literal value, namely one in which the decimal point is omitted from the lexical representation. For example, 42 is a valid decimal number which happens also to be a valid integer and so it is a short form for the typed literal "42"^^xsd:integer.

string_esc

The string_esc term represents an arbitrary sequence of characters. The sequence of characters is enclosed in double quote (") characters. Therefore, the double quote character itself MUST be escaped. More generally, all occurrences of the double quote character in the string MUST be replaced by the sequence \" and all occurrences of the backslash character \ in the actual value MUST be replaced by the sequence \\ in the escaped value. This escaping process MUST be reversed to give the actual value of the string.


scoped_term

The scoped_term represents the ability to query on nested properties. Servers MAY choose not to support such nested property queries, and SHOULD respond with 501 Not Implemented if they are not supported.

oslc.where Semantics

The data types supported in OSLC resource shapes are described in Literal Value Types in [[OSLCShape]]. The table below shows the forms of value that might be used with a comparison operator, and which comparison operators must or may be supported, and their semantics.

Table 7 - oslc.where Semantics

Value type Supported value forms Comparison operators
rdf:XMLLiteral

An [[XMLLiteral]], such as "abc"^^rdf:XMLLiteral, MUST be supported. A server MAY treat the literal in the same way as a plain string literal with the data type removed such as "abc".

A plain string literal, such as "abc" MUST be supported. A server MAY treat the literal in the same way as an XML literal string such as "abc"^^rdf:XMLLiteral.

An xsd:string typed literal [[xsdDatatypes]], such as "abc"^^xsd:string, MUST be supported. A server MAY treat the literal in the same way as an XML literal string such as "abc"^^rdf:XMLLiteral.

Servers MAY validate the string for compliance to an [[XMLLiteral]].

The operators =, !=, and in MUST be supported.

Servers MUST implement, and SHOULD document, one of the following semantics:

  • case sensitive string compare
  • case insensitive string compare
  • case insensitive string pattern match where % means match zero or more characters, and _ means match any single character.

A server MAY choose which of the above to apply based on whether the string contains a % or _ character, and/or the property being compared. A server SHOULD document if this is the case.

Other operators MAY be supported and MAY have implementation-dependent semantics. A server MAY report such usage as unsupported.

xsd:boolean

The values true and false MUST be supported.

The xsd:boolean [[xsdDatatypes]] values "true"^^xsd:boolean and "false"^^xsd:boolean MUST be supported and MUST have the same meaning as true and false respectively.

The values "true" and "false" MAY be supported, and if so, MUST have the same meaning as true and false respectively.

A language tagged literal, such as "true"@en MAY be supported and MAY have implementation and/or locale dependent behavior.

The operators =, !=, and in MUST be supported.

Other operators MAY be supported and MAY have implementation-dependent semantics.
xsd:dateTime

Values that are conformant with an xsd:dateTime [[xsdDatatypes]] [[xsdDateTime]], such as "2018-01-30T12:25:00"^^xsd:dateTime, MUST be supported.

Plain string literals whose string value conforms to an xsd:dateTime, such as "2018-01-30T12:25:00", MAY be supported, and if so, MUST have the same meaning as an xsd:dateTime typed literal such as "2018-01-30T12:25:00"^^xsd:dateTime”.

The operators =, !=, <, >, <=, >=, and in MUST be supported, and MUST have the semantics of a xsd:dateTime comparison.

xsd:decimal

Decimal literals with or without a decimal point, such as 42 and 42.0, MUST be supported if the server supports xsd:decimal property values.

An xsd:decimal typed literal [[xsdDatatypes]], such as "42"^^xsd:decimal or "42.0"^^xsd:decimal, MUST be supported if the server supports xsd:decimal property values.

A plain string literal with a decimal value, such as "42" or "42.0", MAY be supported, and if so, MUST have the same meaning as the xsd:decimal typed literal.

The operators =, !=, <, >, <=, >=, and in MUST be supported if the server supports xsd:decimal property values, and if so, MUST have the semantics of a xsd:decimal comparison.

xsd:double

Decimal literals with or without a decimal point, such as 42 and 42.0, MUST be supported if the server supports xsd:double property values.

An xsd:double typed literal [[xsdDatatypes]], such as "42"^^xsd:double or "42.0"^^xsd:double, MUST be supported if the server supports xsd:double property values.

A plain string literal with a double value, such as "42" or "42.0", MAY be supported, and if so, MUST have the same meaning as the xsd:double typed literal.

The operators =, !=, <, >, <=, >=, and in MUST be supported if the server supports xsd:double property values, and if so, MUST have the semantics of an xsd:double comparison.

xsd:float

Decimal literals with or without a decimal point, such as 42 and 42.0, MUST be supported if the server supports xsd:float property values.

An xsd:float typed literal [[xsdDatatypes]], such as "42"^^xsd:float or "42.0"^^xsd:float, MUST be supported if the server supports xsd:float property values.

A plain string literal with a float value, such as "42" or "42.0", MAY be supported, and if so, MUST have the same meaning as the xsd:float typed literal.

The operators =, !=, <, >, <=, >=, and in MUST be supported if the server supports xsd:float property values, and if so, MUST have the semantics of an xsd:float comparison.

xsd:integer

Decimal literals without a decimal point, such as 42, MUST be supported.

An xsd:integer typed literal [[xsdDatatypes]], such as "42"^^xsd:integer, MUST be supported.

An xsd:decimal typed literal [[xsdDatatypes]] without a decimal point, such as "42"^^xsd:decimal, MAY be supported, and if so, MUST have the same meaning as an xsd:integer typed literal.

A plain string literal with a decimal value, such as "42", or a language tag string with a decimal value, such as "42"@en, MAY be supported, and if so, MUST have the same meaning as a decimal value.

The operators =, !=, <, >, <=, >=, and in MUST be supported and MUST have the semantics of an xsd:integer comparison.

xsd:string

A plain string literal, such as "abc" MUST be supported.

An xsd:string typed literal [[xsdDatatypes]], such as "abc"^^xsd:string, MUST be supported. A server MUST treat the literal in the same way as an plain string literal string such as "abc".

An [[XMLLiteral]], such as "abc"^^rdf:XMLLiteral, MUST be supported. A server MAY treat the literal in the same way as a plain literal string such as "abc".

A string with a language tag, such as "abc"@en, MAY be supported. The string MAY be treated as a plain string literal, or it MAY be treated as a language specific string that only matches a string with an identical value and language tag.

The operators =, !=, and in MUST be supported.

Servers MUST implement, and SHOULD document, one of the following semantics:

  • case sensitive string compare
  • case insensitive string compare
  • case insensitive string pattern match where % means match zero or more characters, and _ means match any single character.

A server MAY choose which of the above to apply based on whether the string contains a % or _ character, and/or the property being compared. A server SHOULD document if this is the case.

Other operators MAY be supported and MAY have implementation-dependent semantics. A server MAY report such usage as unsupported.

oslc:Resource

A uri_ref_esc such as <http://example.org> MUST be supported.

A PrefixedName such as oslc:Zero-or-many, MAY be supported. If supported, the value MUST be treated as equivalent to its corresponding uri_ref_esc.

The operators =, !=, and in MUST be supported. A server MUST implement this as a case-sensitive URI string comparison.

Other operators MAY be supported and MAY have implementation-dependent semantics, or a server MAY report such usage as unsupported.

If oslc.where specifies a property that has a defined namespace prefix but the property is not known, an implementation MAY either:

  1. Respond with a 400 Bad Request as described in Error Handling.
  2. Execute the query and return a normal query response.

An unknown property is one that is not defined in the resource shape for that type of resource. Responding with an error code is appropriate for implementations that have finite and enumerable properties of resources that cannot determine how to query for undefined properties. Responding with a normal query response is appropriate for implementations that have open sets of properties, not all of which might be in a resource shape.

oslc.searchTerms

Resource properties often contain text so it is useful to search for resources that contain specified terms. The oslc.searchTerms query parameter lets you perform a full-text search [[FULLTEXT-SEARCH]] on a set of resources. In a full-text search, each resource is matched against the list of search terms and assigned a numeric score. A high score indicates a good match. The matching resources are returned in the response, sorted by the score in descending order. Each resource that is returned in the response is annotated with a special property, oslc:score, that gives its match score.

An OSLC domain specification that supports full-text search SHOULD specify which resource properties may be supported in a full-text search.

When oslc.searchTerms is used in the request, each matching resource (hit) in the response MAY contain an oslc:score property. Note that oslc:score is not purely a property of the resource since it also depends on the search terms. It is therefore a pseudo-property whose validity is limited to the HTTP response, and for a paged response, its subsequent pages.

The oslc:score property MUST be a non-negative number and SHOULD be in the range from 0-100. Results MUST be ordered with the entry with the largest oslc:score occurring first.

The oslc.orderBy query parameter MAY be used with oslc.searchTerms. When oslc.orderBy is used with oslc.searchTerms the result MUST be first sorted in descending order by the oslc:score pseudo-property, and then by the other sort keys specified in oslc.orderBy. This behavior is like prepending the list of sort keys specified in oslc.orderBy with the key -oslc:score. However, the pseudo-property oslc:score MUST NOT appear explicitly in oslc.orderBy.

The oslc.where query parameter MAY be used with oslc.searchTerms. When oslc.where is used with oslc.searchTerms and is supported, then the set of resources searched for matches MUST be restricted to only those resources that satisfy the conditions in oslc.where.

For example, the following query returns the high severity change requests that deal with database performance:

Table 8 - query parameters

Parameter Unencoded value
oslc.where oslc_cm:severity="high"
oslc.searchTerms "database","performance" 

    GET http://example.org/queryBase?oslc.where=oslc_cm%3Aseverity%3D%22high%22
        &oslc.searchTerms=%22database%22%2C%22performance%22
Syntax
    oslc_searchTerms ::= "oslc.searchTerms=" search_terms
    search_terms     ::= string_esc ("," string_esc)*

oslc.orderBy

The oslc.orderBy query parameter lets you sort the result set. It is like the ORDER BY clause of a SQL statement.

If a server supports the oslc.orderBy parameter and this is specified in the request:

If oslc.orderBy is not specified, the ordering of the results is undefined and MAY be implementation-dependent.

You can specify a list of one or more immediate or nested properties of the resources in the member list, and a sort direction for each where " + " means ascending order and " -" means descending order. The following example sorts the high severity change requests by the name of the creator, with most recently created first:

Table 9 - query parameters

Parameter Unencoded value
oslc.where oslc_cm:severity="high"
oslc.orderBy dcterms:creator{+foaf:name},-dcterms:created 

    GET http://example.org/queryBase
        ?oslc.orderBy=dcterms%3Acreator%7B%2Bfoaf%3Aname%7D%2C-dcterms%3Acreated
        &oslc.where=oslc_cm%3Aseverity%3D%22high%22
Syntax
    oslc_orderBy        ::= "oslc.orderBy=" sort_terms
    sort_terms          ::= sort_term ("," sort_term)*
    sort_term           ::= scoped_sort_terms | ("+" | "-") identifier
    scoped_sort_terms   ::= identifier "{" sort_terms "}"

oslc.select

The oslc.select query parameter lets you specify which immediate and nested properties of the resources in the member list to be included in the response. It is like the SELECT clause of a SQL statement.

If oslc.select is not specified, the response MAY include some or none of the properties of members in the query result container.

Servers SHOULD avoid returning a large number of properties of members by default.

If a server chooses to include a multi-valued property by default, and the query response is not paged, it MUST include all the values of that property.

Clients should specify oslc.select if they require particular properties to be returned in the query response.

If oslc.where specifies a property that has a defined namespace prefix but the property is not known, an implementation MAY either:

  1. Respond with a 400 Bad Request as described in Error Handling.
  2. Execute the query and return a normal query response.

Servers SHOULD accept the value rdf:nil. If specified as the only property, servers SHOULD omit all properties of the member resources. If oslc.select specifies rdf:nil and other properties, servers MAY choose to respond with 400 Bad Request, or ignore the rdf:nil, or have other implementation dependent behavior.

The syntax of the oslc.select query parameter is the same as that of the oslc.properties query parameter. See [[OSLC-Core-30-Part1]] for the syntax.

The difference between oslc.select and oslc.properties is that:

As in the case of oslc.properties, the wildcard is equivalent to the list of all properties of the member resources.

Implementations MAY support the use of the wildcard for immediate and/or nested properties of member resources. Servers SHOULD document any restriction on the use of the wildcard.

A server MAY include additional member properties in the response to those specified in the oslc.select query parameter. Clients should not assume that only the specified properties will be included.

For example, the following query finds the change requests created by any user named "Deb" and includes the dcterms:title and dcterms:creator for each change request found by the query and the foaf:name of the person that last modified the change request.

Table 10 - query parameters

Parameter Unencoded value
oslc.where dcterms:creator {foaf:name="Deb"}
oslc.select dcterms:title,dcterms:creator,oslc:modifiedBy{foaf:name} 

GET https://example.org/ccm/oslc/contexts/_by884MNWEeekg_dNxwf1pg/workitems
    ?oslc.where=dcterms%3Acreator%20%7Bfoaf%3Aname%3D%22Deb%22%7D
    &oslc.select=dcterms%3Atitle%2Cdcterms%3Acreator%2Coslc%3AmodifiedBy%3Amodifier%7Bfoaf%3Aname%7D

OSLC-Core-Version: 2.0
Accept: text/turtle

 -- response --
200 OK
Etag:  "5f836103-c64e-3c3f-aa5e-dd0baec92511"
OSLC-Core-Version:  2.0
Vary:  Accept, OSLC-Core-Version
Content-Type:  text/turtle;charset=UTF-8
Content-Language:  en-US
Link: <http://www.w3.org/ns/ldp#BasicContainer>; rel="type", <http://www.w3.org/ns/ldp#Resource>; rel="type"

@prefix dcterms:  <http://purl.org/dc/terms/> .
@prefix ldp:     <http://www.w3.org/ns/ldp#> .
@prefix oslc:    <http://open-services.net/ns/core#> .
@prefix rdfs:    <http://www.w3.org/2000/01/rdf-schema#> .
@prefix rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

<https://example.org/ccm/oslc/contexts/_by884MNWEeekg_dNxwf1pg/workitems>
    a ldp:BasicContainer ;
    ldp:contains
        <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/9> ,
        <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/22> ,
        <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/11> ,
        <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/20> ,
        <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/1> ,
        <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/27> ,
        <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/28> ,
        <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/17> ,
        <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/5> ,
        <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/23> ,
        <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/7> ,
        <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/12> ,
        <https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/8> .

<https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/9>
      a       oslc_cm:ChangeRequest ;
      dcterms:creator <https://example.org/jts/users/deb> ;
      oslc:modifiedBy <https://example.org/jts/users/deb> ;
      dcterms:title "To many messages logged in the console"^^rdf:XMLLiteral .

<https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/22>
      a       oslc_cm:ChangeRequest ;
      dcterms:creator <https://example.org/jts/users/deb> ;
      oslc:modifiedBy <https://example.org/jts/users/bob> ;
      dcterms:title "Calculation error"^^rdf:XMLLiteral .

<https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/11>
      a       oslc_cm:ChangeRequest ;
      dcterms:creator <https://example.org/jts/users/deb> ;
      oslc:modifiedBy <https://example.org/jts/users/deb> ;
      dcterms:title "Some accessibility issues"^^rdf:XMLLiteral .

<https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/20>
      a       oslc_cm:ChangeRequest ;
      dcterms:creator <https://example.org/jts/users/deb> ;
      oslc:modifiedBy <https://example.org/jts/users/bob> ;
      dcterms:title "Browser Exception"^^rdf:XMLLiteral .

<https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/1>
      a       oslc_cm:ChangeRequest ;
      dcterms:creator <https://example.org/jts/users/deb> ;
      oslc:modifiedBy <https://example.org/jts/users/deb> ;
      dcterms:title "Not possible to change a user password"^^rdf:XMLLiteral .

<https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/27>
      a       oslc_cm:ChangeRequest ;
      dcterms:creator <https://example.org/jts/users/deb> ;
      oslc:modifiedBy <https://example.org/jts/users/deb> ;
      dcterms:title "Improve link colors"^^rdf:XMLLiteral .

<https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/28>
      a       oslc_cm:ChangeRequest ;
      dcterms:creator <https://example.org/jts/users/deb> ;
      oslc:modifiedBy <https://example.org/jts/users/deb> ;
      dcterms:title "Login not working anymore"^^rdf:XMLLiteral .

<https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/17>
      a       oslc_cm:ChangeRequest ;
      dcterms:creator <https://example.org/jts/users/deb> ;
      oslc:modifiedBy <https://example.org/jts/users/deb> ;
      dcterms:title "Increase size of overall application window"^^rdf:XMLLiteral .

<https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/5>
      a       oslc_cm:ChangeRequest ;
      dcterms:creator <https://example.org/jts/users/deb> ;
      dcterms:title "Improve loan calculation algorithm"^^rdf:XMLLiteral .

<https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/23>
      a       oslc_cm:ChangeRequest ;
      dcterms:creator <https://example.org/jts/users/deb> ;
      oslc:modifiedBy <https://example.org/jts/users/deb> ;
      dcterms:title "Search is not finding this term"^^rdf:XMLLiteral .

<https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/12>
      a       oslc_cm:ChangeRequest ;
      dcterms:creator <https://example.org/jts/users/deb> ;
      dcterms:title "Button sizes are too small"^^rdf:XMLLiteral .

<https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/7>
      a       oslc_cm:ChangeRequest ;
      dcterms:creator <https://example.org/jts/users/deb> ;
      oslc:modifiedBy <https://example.org/jts/users/deb> ;
      dcterms:title "Offer more services related to loans"^^rdf:XMLLiteral .

<https://example.org/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/8>
      a       oslc_cm:ChangeRequest ;
      dcterms:creator <https://example.org/jts/users/deb> ;
      oslc:modifiedBy <https://example.org/jts/users/bob> ;
      dcterms:title "Add context sensitive help support everywhere"^^rdf:XMLLiteral .

<https://example.org/jts/users/deb>
      foaf:name "Deb" .

<https://example.org/jts/users/bob>
      foaf:name "Bob" .

oslc.paging

Servers MAY support a oslc.paging query parameter. Implementations MAY choose to ignore the parameter.

Servers that support paging of query results SHOULD use a paged response when oslc.paging=true is specified.

Servers MAY also provide a paged response if the oslc.paging parameter is not specified and the query result includes a large number of members or a large number of RDF statements. 

        GET https://example.org/jazz/oslc/contexts/_Q2fMII8EEd2Q-OW8dr3S5w/workitems&oslc.paging=true
Accept: text/turtle
OSLC-Core-Version: 2.0

 -- response --
200 OK
Date:  Fri, 11 May 2018 09:49:35 GMT
X-Powered-By:  Servlet/3.0
Etag:  "ca3acc7e-36b4-3c35-a51c-08d29266c24c"
Expires:  Fri, 11 May 2018 09:49:35 GMT
OSLC-Core-Version:  2.0
Vary:  Accept,OSLC-Core-Version
Content-Type:  text/turtle;charset=UTF-8
Content-Language:  en-US
Cache-Control:  private, must-revalidate, max-age=0, no-cache=set-cookie
X-Cluster-SA:  Node-Jazz
Set-Cookie:  JSA_AUTH_COMPLETE=true; Path=/; Secure
X-jazzweb3:  D=466712 t=1526032175078031
Transfer-Encoding:  chunked
Strict-Transport-Security:  max-age=31536000; includeSubDomains

@prefix dcterms:  <http://purl.org/dc/terms/> .
@prefix rdfs:    <http://www.w3.org/2000/01/rdf-schema#> .
@prefix rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix oslc:    <http://open-services.net/ns/core#> .

<https://example.org/jazz/oslc/contexts/_Q2fMII8EEd2Q-OW8dr3S5w/workitems>
    a ldp:BasicContainer ;
        ldp:contains
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/126544> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/163518> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/99398> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/157559> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/128024> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/126992> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/90641> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/163178> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/276059> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/95469> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/217716> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/161823> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/42317> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/70584> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/126434> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/104751> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/139381> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/263005> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/105938> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/133616> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/204463> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/250934> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/66180> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/52981> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/69789> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/112342> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/210019> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/78577> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/100271> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/109336> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/72037> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/128115> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/71659> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/104241> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/75103> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/182157> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/156808> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/108460> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/47283> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/285162> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/135240> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/206800> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/117595> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/59362> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/135620> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/222107> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/133136> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/80140> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/251947> ,
            <https://example.org/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/74496> .


<https://example.org/jazz/oslc/contexts/_Q2fMII8EEd2Q-OW8dr3S5w/workitems?_resultToken=_nIokIFUAEeibptZOC98gng&oslc.pageSize=50&_startIndex=0>
    a       oslc:ResponseInfo ;
    oslc:nextPage <https://example.org/jazz/oslc/contexts/_Q2fMII8EEd2Q-OW8dr3S5w/workitems?_resultToken=_nIokIFUAEeibptZOC98gng&oslc.pageSize=50&_startIndex=50> ;
    oslc:totalCount "82991" ;
    dcterms:title "Work Items" .

oslc.pageSize

Servers MAY support a oslc.pageSize query parameter. Implementations MAY choose to ignore the parameter, or MAY use it as a hint for how a response should be paged and use page boundaries that do not exactly match the specified page size.

The page size is expressed in terms of the number of RDF statements that are included in the response body.

Error Handling

If a GET or POST of a oslc:queryBase cannot be executed, the response MUST include a response body whose RDF contains at least one oslc:Error describing the cause of the error.

If the error is due to use of oslc.where, oslc.searchTerms, oslc.orderBy, or oslc.select and that query parameter is not supported, the response status SHOULD be 501 Not Implemented. Implementations that do not support a specific query parameter need not parse or validate its value.

If the error is due to a supported but malformed query parameter value, such as one that does not match the supported syntax, then the response status code SHOULD be 400 Bad Request.

If the error is due to a supported oslc.where, oslc.select, or oslc.orderBy parameter, and its value references a namespace that is not defined by default or with oslc.prefix, the response status code SHOULD be 400 Bad Request.

If oslc.where specifies a property that has a defined namespace prefix, and the property is defined in the resource shape for the query capability with oslc:queryable of "false"^^xsd:boolean, the server MUST Respond with a 400 Bad Request.

If a query uses a supported query parameter, and the parameter value is syntactically valid, but the implementation does not support a specific use of such a query parameter, the response status SHOULD be 501 Not Implemented. For example, this might apply if a specific use of the wildcard in oslc.select is not supported.

If the query is valid, but the server failed to execute the request in some unexpected way, then the response status SHOULD be 500 Internal Server Error.

Version Compatibility

This specification follows the specification version guidelines given in [[OSLC-Core-30-Part1]].

Relationship with OSLC Query 2.0

This appendix summarizes OSLC Query 3.0 changes from, and compatibility with OSLC Query 2.0, [[OSLCQuery2]].

Topic Details
Query result container Query result containers are compatible with OSLC 2.0 clients. OSLC 2.0 clients should ignore the additional LDPC triples and response headers. The default rdfs:member predicate when no resource shape is specified ensures that OSLC 2.0 clients can consume the query response from a Query 3.0 server.
Query comparison semantics The OSLC Query 2.0 specification required strict adherence to SPARQL semantics for relational operators and property comparisons. Most implementations based on a standard relational database could only satisfy that requirement by maintaining RDF datasets and using SPARQL on them. Few existing implementations did this because it was overly burdensome, resulting in most implementations being non-compliant. In practice, few clients could assume complete compliance. While it is possible that an OSLC 2.0 client might get results from a OSLC Query 3.0 server that are are not compliant with Query 2.0, it is expected that in the majority of cases this will be inconsequential.
oslc.where syntax The only change of oslc.where syntax between OSLC Query 3.0 and OSLC Query 2.0 is the addition of PrefixedName in the value element. The ability to use a prefixed name in a value is useful, especially for enumerated values, and its omission was an oversight in the OSLC Query 2.0 specification.
wildcard in oslc.select syntax The use of a wildcard in oslc.select has been made optional.
oslc.orderBy The semantics of oslc.orderBy has been clarified. A new optional oslc:order pseudo-property has been defined to allow clients to determining the ordering of result members within a non-paged or paged response.
Error handling The error handling in Query 2.0 was not explicitly described. Query 3.0 clarifies expected and required error handling for consistency and to make it easier for clients to consume.
Discovery of selectable or queryable properties OSLC Query 2.0 described that a client could discover the resource shape of the returned members but did not define whether those properties were queryable or just selectable with oslc.select. OSLC Core 3.0 introduced a new oslc:queryable property for an OSLC property in an OSLC resource shape. This allows OSLC 3.0 clients to differentiate which properties are supported in a query expression specified by oslc.where or are supported in a oslc.select value.

Acknowledgements

The following individuals have participated in the creation of this specification and are gratefully acknowledged:

Participants:

James Amsden, IBM (Editor)
Geoff Clemm, IBM
Nick Crossley, IBM (Chair)
Ian Green, IBM
Peter Hack, IBM
David Honey, IBM
Sam Padget, IBM
Martin Pain, IBM
Martin Sarabura, PTC
Brian Steele, IBM

Change History

Revision Date Editor Changes Made
01 2018-12-14 Jim Amsden Committee Specification Public Review Draft revision 01 published.