OSLC AM Simple Query Syntax V1
Table of Contents
Introduction
The Simple Query Specification for the OSLC Architecture Management 1.0 specification is derived from a snapshot of the
OSLC common query specification. Because the 1.0 AM specification will finalize before the completion of the common query specification we have made a copy of the current common specification and are including it as part of the AM specification.
The query is executed by sending an HTTP GET request to a URL that is formed by appending a set of query parameters to a base URL.
These query parameters are used to:
- find subsets of resources that satisfy simple conditions
- select the properties to return of them
- limit and order the result sets
The query parameters let you find resources that satisfy simple conditions. This operation is sometimes refered to as filtering since it eliminates those resources that fail to satisfy the conditions. The set of resources that pass the filter are sometimes referred to as a result set. The query parameters let you select which immediate and nested properties of the resources in the result set to include in the response. The query parameters also let you sort the result set, limit the number of resources to include in the HTTP response, and specify where in the result set to start the HTTP response.
The result set is returned as an
ATOM collection. The details of what is expected in the result sets can be found
here.
The query parameters are intended to satsify 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 or SPARQL, which is beyond the scope of this version of the specification.
The query parameters MAY contain characters that MUST be URL encoded when transmitted in an HTTP request. The examples below show unencoded query parameters for clarity. See
URL Encoding for a further discussion of this topic.
Notation and Conventions
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in
RFC2119. Domain name examples use
RFC2606.
In the following sections, syntax is formally defined using a common extended form of
Backus-Naur Form (BNF). Informal definitions and comments are delimited by /* and */.
Query Parameters
This specification defines the syntax of a set of related URL query parameters that can be used in HTTP GET requests to perform queries. We have adopted a consistent naming convention for these URL query parameters to identify them as common across all OSLC specification, namely all are prefixed with the characters "
oslc.
" The following query parameters are part of this specification:
-
oslc.prefix
- define namespace prefixes which can be used in the other parameters. These provide a means to compact the overall length of a query string.
-
oslc.properties
-specifies which properties to include in the result.
-
oslc.where
- defines the conditions of the query.
-
oslc.orderBy
- specifies how to order the results.
-
oslc.offset
-for queries with large results, specifies which result to skip to when constructing the return collection.
-
oslc.limit
- specifies the maximum number of results to return.
-
oslc.searchTerms
- specifies a text search across a number of properties (service provider defined).
Clients using this service SHOULD provide the
oslc.where
parameter, the other parameters are all optional. Each of these query parameters SHOULD appear at most once in a URL. The behavior is undefined when a query parameter appears more than once.
Implemeters of this specification MUST support the
oslc.prefix
,
oslc.where
parameters, and SHOULD support all parameters.
oslc.prefix
The
oslc.prefix
query parameter lets you specify namespace prefixes used in property names. The following URL illustrates the use of the
oslc.prefix
query parameter to define it:
http://am.acme.com/query?oslc.prefix=foaf=http://xmlns.com/foaf/0.1/&oslc.properties=dc:title,...
Syntax
The following is the BNF grammar for the
oslc.prefix
query parameter:
oslc_prefix ::= "oslc.prefix=" prefix_defs
prefix_defs ::= prefix_def ("," prefix_def)*
prefix_def ::= prefix "=" uri_ref
prefix ::= NCName
NCName ::= /* see "Namespaces in XML 1.0", http://www.w3.org/TR/REC-xml-names/ */
uri_ref_esc ::= /* a valid URI reference (RFC 2396) */
oslc.properties
The
oslc.properties
query parameter lets you specify the set of properties to be included in the response to the query. Both immediate and nested properties may be specified. A nested property is a property that belongs to the resource referenced by another property. Nested properties are enclosed in brace brackets, and this nesting may be done recursively, i.e. a nested property may contain other nested properties.
For example, we are just interested in the name and the given and family name of the creator of all resources that have been changed since a given date:
http://am.acme.com/query?
oslc.prefix=dc=http://purl.org/dc/terms/,foaf=http://xmlns.com/foaf/0.1/
&oslc.properties=dc:title,dc:creator{foaf:givenName,foaf:familyName}
&oslc.where=dc:type=<http://www.eclipse.org/gmf/runtime/1.0.2/notation#Diagram>
and dc:modified>="2009-10-20T19:49:47Z"^^xsd:dateTime
Syntax
The following is the BNF grammar for the properties term.
oslc_properties ::= "oslc.properties=" properties
properties ::= property ("," property)*
property ::= identifier | nested_prop | wildcard
identifier ::= QName
QName ::= /* see "Namespaces in XML 1.0", http://www.w3.org/TR/REC-xml-names/ */
nested_prop ::= property "{" properties "}"
wildcard ::= "*"
oslc.where
An OSLC service provides access to a set of interrelated resources and their properties. These resources MAY be of more than one type and MAY be organized into collections. Service consumers often need to search for subsets of resources that satisfy certain conditions. The
oslc.where
query parameter lets you specify the conditions that the resources must satisfy. It is like the
WHERE
clause of a SQL statement.
Note: The specification differs from the original common query spec by allowing typed values in terms. A value in a term of the oslc.where parameter can be a String, a URI, or a XSD typed value. An XSD typed value is represented as a String followed by double carets (^) and the XSD type. For example a date is represented as "2009-10-20T19:49:47Z"^^xsd:dateTime
. A URI that appears as the value of a term is surrounded by angled brackets. For example <http://acme.com/type/foo>
.
For example, suppose that the following URL represents the discoverable query URL for the AM service provider :
http://am.acme.com/query
AM resources all specify a dc:title property. The following URL queries the provider for all AM resources whose title is "IManager" :
http://am.acme.com/query?oslc.where=http://purl.org/dc/terms/title="IManager"
Alternatively the same query could be constructed with the use of a prefix. Using a prefix is convenient when multiple properties involved in the query share the same namespace.
http://am.acme.com/query?oslc.prefix=dc=http://purl.org/dc/terms/&oslc.where=dc:title="IManager"
Conditions may use the usual binary comparison operators and be combined using the boolean conjunction operator,
and
. For example, suppose we are looking for AM resources that have the property
acme:severity
property of "
high
" and were created after
20-Oct-2009 19:49:47 GMT
.
http://am.acme.com/query?
oslc.prefix=dc=http://purl.org/dc/terms/,acme=http://acme.com/ns/
&oslc.where=acme:severity="high"
and dc:created>"2009-10-20T19:49:47Z"^^xsd:dateTime
The following URL illustrates the use of nested properties. It finds the AM resources created by John Smith:
http://am.acme.com/query?
oslc.where=http://purl.org/dc/terms/creator{foaf:givenName="John" and foaf:familyName="Smith"}
Syntax
The syntax of the
oslc.where
query parameter is defined by the
oslc_where
term in the following BNF grammar:
oslc_where ::= "oscl.where=" compound_term
compound_term ::= term ( boolean_op simple_term)*
term ::= simple_term | scoped_term
space ::= " " /* a space character */
boolean_op ::= " and "
scoped_term ::= identifier "{" compound_term "}"
simple_term ::= identifier comparison_op value | identifier space in_op space? in_val
comparison_op ::= "=" | "!=" | "<" | ">" | "<=" | ">="
in_op ::= "in"
in_val ::= "[" value ("," value)* "]"
value ::= "*" | string_esc | uri_value | typed_value
typed_value ::= string_esc "^^" xsd_type
xsd_type ::= "xsd:dateTime" | "xsd:boolean" | "xsd:decimal"
identifier ::= qname | uri
uri_value ::= "<" uri ">"
qname ::= /* a qualified name (http://www.w3.org/TR/xmlschema-2/#QName) */
string_esc ::= /* a string enclosed in double quotes, with certain characters escaped. See below. */
uri ::= /* a valid URI reference (RFC 2396) */
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 finds bugs with severity "high" or "medium":
http://example.com/bugs?oslc.where=http://acme.com/terms/severity in ["high","medium"]
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:
= |
test for equality |
! = |
test for inequality |
< |
test less-than |
> |
test greater-than |
<= |
test less-than or equal |
>= |
test greater-than or equal |
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
.
decimal
The
decimal
term represents a
decimal number as defined in
XML Schema Part 2: Datatypes Second Edition.
string_esc
The
string_esc
term represents an arbritrary sequence of characters. The sequence of characters is enclosed in double quote (") characters. Therefore, the double quote character itself MUST be escaped. All occurances of the double quote character in the string MUST be replaced by the sequence \" and all occurances of the backslash character (\) MUST be replaced by the sequence \\. This escaping MUST be undone to give the actual value of the string.
uri
The
uri
term represents a
URI. It appears in this syntax as a
value
in between a pair of angled brackets (
< >
). The angle brackets identify this as a URI and not as another term or other type of value.
oslc.orderBy
The
oslc.orderBy
query parameter lets you sort the result set. It is like the
ORDER BY
clause of a SQL statement.
You can specify a list of one or more immediate or nested properties of the result set members, and a sort direction for each where "
+
" means ascending order and "
-"
means descending order. The following example sorts the high severity bugs by the family and given names of the creator, with most recently created first:
http://am.acme.com/query?
oslc.where=http://purl.org/dc/terms/title="IManager"
&oslc.orderBy=dc:creator{+foaf:familyName,+foaf:givenName},-dc:created
&oslc.where=cm:severity="high"
The properties in the oslc.orderBy list are sort keys. The result set is sorted by the sort keys, in the indicated direction. The sorting order of the property values MUST be the same as that used for evaluation the binary comparison operators in the oslc.where query parameter.
Each sort key SHOULD be the name of a single-valued property of the each resource in the result set. The sorting behavior is undefined if the sort key properties are not single-valued.
Syntax
The syntax of the
oslc.orderBy
query parameter is defined by the
oslc_orderBy
term in the following BNF grammar:
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.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 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 annoted with a special property,
oslc:score
, that gives its match score.
An OSLC domain-specific service specification that supports full text search SHOULD specify which resource properties are indexed so that search results are consistent across implementations.
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.
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
occuring 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.limit
and
oslc.offset
query parameters MAY be used in combination with
oslc.searchTerms
. For example, the following query returns the top 10 bugs that deal with database performance:
http://am.acme.com/query?oslc.limit=10&oslc.searchTerms="database","performance"
The
oslc.where
query parameter MAY be used with
oslc.searchTerms
. When
oslc.where
is used with
oslc.searchTerms
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 top 10 high severity bugs that deal with database performance:
http://am.acme.com/query?
oslc.where=http://purl.org/dc/terms/title="IManager"
&oslc.limit=10&oslc.searchTerms="database","performance"
Syntax
The syntax of the
oslc.searchTerms
query parameter is defined by the
oslc_searchTerms
terms in the following BNF grammar:
oslc_searchTerms ::= "oslc.searchTerms=" search_terms
search_terms ::= string_esc (, string_esc)*
URL Encoding
The query parameter syntax defined in this specification permits the use of characters that MUST be properly encoded when transmitted in HTTP requests. For example:
Not encoded:
?oslc.prefix=dc=http://purl.org/dc/terms/
&oslc.where=dc:title="test case 1" and dc:modified>="2008-12-02T18:42:30"^^xsd:dateTime
Encoded:
?oslc.where=dc%3Atitle%3D%22test%20case%201%22%20and%20dc%3Amodified%3E%3D%222008-12-02T18%3A42%3A30%22%5E%5Exsd%3AdateTime
References