OSLC Simple Query Syntax V1

Early Draft

Table of Contents

Introduction

This cross-domain specification defines a standard set of OSLC URL query parameters that other OSLC domain-specific specifications (e.g. Change Management, Requirements Management, Quality Management, etc.) may use to query resources and resource containers. The query is executed by sending an HTTP GET request to a URL that is formed by appending a set of these query parameters to a base URL.

These query parameters can be used in the following use cases:

1. to select properties of an individual resource and
2. to find subsets of linked resources that satisfy simple conditions, and select properties of them.

In the first use case, the base URL MUST respond to an HTTP GET request by returning a representation of the resource. The query parameters let you control the contents of the response. The data model of the resource is viewed as consisting of a set of properties of the resource. The values of these properties are either literal values, such as numbers, strings, and dates, or links to other resources, which may have their own properties. Linked resources may link to other resources, and so on, to arbitrary depths. However, the scope of the query is limited to the boundaries of the service which is defined by the appropriate domain-specific specification.

Properties of linked resources may be viewed as nested properties of the initial resource. The query parameters let you select both the immediate and nested properties to include in the HTTP response.

In the second use case, the base URL is additionally viewed as having an associated set other resources. The members of this associated set are objects of one or more membership properties. The oslc.from query parameter lets you specify which subset of membership properties to use. This associated set may be all the resources managed by the service, or a some subset of it, e.g. the subset of resources of some given type such as Change Request or Requirement. The oslc.where query parameter lets you find associated 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 oslc.select query parameter lets you select which immediate and nested properties of the resources in the result set to include in the response. Other query parameters also let you sort the result set ( oslc.orderBy), limit the number of resources to include in the HTTP response ( oslc.limit), and specify where in the result set to start the HTTP response ( oslc.offset).

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.

The specification formally defines the syntax using BNF and informally illustrates the semantics with simple examples. For a more complete definition of the semantics see OSLC Simple Query Semantics V1.

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 */.

Background

Several domain scenarios, including those in Change Management, Quality Management, and Requirements Management, have outlined a need for a simple query mechanism. This is provided by supplying the query terms that can be URL-encoded and performed by using a HTTP GET.

The query syntax described here was originally specified by the OSLC Change Management workgroup (Change Management Query Syntax V1 specification) and was loosely based on the Library of Congress Contextual Query Language (CQL). But where CQL is for describing structured text searches the language here is intended for more precise queries. So, whereas CQL allows search terms that are not evaluated in the context of a property the language here always scopes a term to a particular property ( property op value). Also, while CQL does support a sort modifier we also introduce a limit modifier to return only a subset of possible results. Instead of interested OSLC domain workgroups copying and adapting the original CM Query spec, this common OSLC Query Syntax specification can be referred to as a whole from individual domain specifications. Evolution of this common specification will be managed by the OSLC Workgroup Leads.

The present specification differs from the previous ones in several ways. It cleans up and corrects the BNF. It splits the syntax into several query parameters, each prefixed with the string " oslc. " The benefit of splitting up the previous syntax into several query parameters is that overall syntax is simpler and we can rely on the standard URL parsers to do more of the work.

More significantly, this specification improves the description of the nested property syntax, and defines the syntax of nested properties for use in filtering.

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 summarize define these query parameters.

An OSLC domain-specific 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 URL. The behavior is undefined when a query parameter appears more than once.

oslc.properties

The oslc.properties query parameter lets you specify the set of properties to be included in the response to an HTTP GET request for a resource. Both immediate and nested properties may be specified. A nested property is a property that belongs to the resource referencd 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, suppose we have a bug report resource at the following URL:

 http://example.com/bugs/4242

Suppose this bug resource has properties such as dc:title, dc:description, and dc:creator, and that dc:creator refers to a person resource that has properties such as foaf:givenName and foaf:familyName. Suppose you want a representation of the bug report that includes its dc:title and the foaf:givenName and foaf:familyName of the person refered to by its dc:creator. The following URL illustrates the use of the oslc.properties query parameter to include those properties:

http://example.com/bugs/4242?oslc.properties=dc:title,dc:creator{foaf:givenName,foaf:familyName} 

Syntax

The normative syntax of the oslc.properties query parameter is specified in OSLC Syntax for Property Selection and Namespace Prefixes . The following BNF grammar for the properties term is copied here for ease of reference.

oslc_properties ::= "oslc.properties=" properties
properties      ::= property ("," property)*
property        ::= identifier | nested_prop | wildcard
identifier      ::= PrefixedName 
PrefixedName    ::= /* see "SPARQL Query Lanaguage for RDF", http://www.w3.org/TR/rdf-sparql-query/#rPrefixedName */
nested_prop     ::= property "{" properties "}"
wildcard        ::= "*"

oslc.prefix

In the preceeding example, the bug report had property names that included a namespace prefix, e.g. dc: and foaf:. An OSLC service SHOULD predefine namespace prefixes for its properties. Here we have assumed that the bug reporting service has predefined the Dublin Core ( dc:) and Friend of a Friend ( foaf:) prefixes. However, OSLC resources SHOULD also be open to new content, which means that new properties may not belong to the predefined namespace. We therefore need a way to define new namespace prefixes on URLs. The oslc.prefix query parameter lets you specify namespace prefixes used in property names. For example, suppose the foaf: prefix was not predefined. The following URL illustrates the use of the oslc.prefix query parameter to define it:

http://example.com/bugs/4242?oslc.prefix=foaf=http://xmlns.com/foaf/0.1/&oslc.properties=dc:title,...

Syntax

The normative definition of the oslc.prefix query parameter is specified in OSLC Syntax for Property Selection and Namespace Prefixes . The following BNF grammar for this query parameter has been copied here for ease of reference:

oslc_prefix ::= "oslc.prefix=" prefix_defs
prefix_defs ::= prefix_def ("," prefix_def)*
prefix_def  ::= prefix "=" uri_ref_esc
prefix      ::= PN_PREFIX
PN_PREFIX   ::= /* see "SPARQL Query Lanaguage for RDF", http://www.w3.org/TR/rdf-sparql-query/#rPN_PREFIX */
uri_ref_esc ::= /* a URI reference in which certain characters are escaped, see below */

oslc.from

The OSLC resource data model is defined in terms of the properties that a given type of resource may have. Some properties define attributes of resources and some define links to other related resources. Membership is an important kind of link property. Membership properties are in general multi-valued and relate a given base resource to an associated set of zero or more member resources. A resource may have more than one kind of membership property, in which case the set of resources associated with the base resources is the set of all resources that are linked to the base resource by some membership property.

In general, there may be a very large number of member resources associated with a given base resource, and it is often useful to search this set for member resources that satify some conditions. The oslc.from query parameter lets you specify which membership properties to use for this search. It is like the FROM clause in a SQL statement.

If the oslc.from query parameter is absent, then all membership properties are used. The set of member resources thus defined may be further refined using boolean conditions specified in the oslc.where query parameter.

For example, suppose the following URL represents the set of all change requests managed by a service:

http://example.com/requests

Suppose that this service manages two kinds of change requests, namely bugs and features, and that these are related to the base URL via the membership properties cm:memberBug and cm:memberFeature. An HTTP GET request on the base URL would return all the bugs and features.

The following query would also return all the bugs and features since the base resource only has the two specified membership properties:

http://example.com/requests?oslc.from=cm.memberBug,cm:memberFeature 

However, the following query would return only the bugs:

http://example.com/requests?oslc.from=cm:memberBug

Syntax

The syntax of the oslc.from query parameter is defined by the oslc_from term in the following BNF grammar:

oslc_from             ::= "oslc.from=" identifiers
identifiers           ::= identifier ("," identifier)* 

oslc.where

As discussed in the section on oslc.from, a resource may have an associated set of related resources defined by one or more membership properties. Service consumers often need to search for subsets of these related resources that satisfy certain conditions. The oslc.where query parameter lets you specify the conditions that these related resources must satisfy. It is like the WHERE clause of a SQL statement.

For example, suppose that the following URL represents the set of all bug resources managed by a service, and that is has a single membership property, cm:memberBug:

http://example.com/bugs 

Suppose bug reports have a dc:identifier property that gives their bug number, e.g. 4242. The following URL filters this set and selects only those bugs that have a dc:identifier property whose value is 4242:

http://example.com/bugs?oslc.where=dc:identifier=4242 

Note that in the preceding query, the oslc.from query parameter is absent since it defaults to all the membership properties, and in this case there is only one.

Conditions may use the usual binary comparison operators and be combined using the boolean conjunction operator, and. For example, suppose bugs have cm:severity and dc:created properties. The following example finds high severity bugs created after April 1, 2010:

http://example.com/bugs?oslc.where=cm:severity="high" and dc:created>"2010-04-01"

The following URL illustrates the use of nested properties. It finds the set of bugs created by John Smith:

http://example.com/bugs?oslc.where=dc: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 ::= simple_term (space? boolean_op space? simple_term)*
simple_term   ::= term | scoped_term
space         ::= " " /* a space character */
boolean_op    ::= "and"
scoped_term   ::= identifier "{" compound_term "}"
term          ::= identifier comparison_op value | identifier space in_op space? in_val
comparison_op ::= "=" | "!=" | "<" | ">" | "<=" | ">="
in_op         ::= "in"
value         ::= decimal | string_esc
in_val        ::= "[" value ("," value)* "]"
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. */

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=cm: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:

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.

oslc.select

The oslc.select query parameter lets you specify the immediate and nested properties of the resources in the result set to include in the HTTP response. It is like the SELECT clause of a SQL statement.

The syntax of the oslc.select query parameter is the same as that of the oslc.properties query parameter. However, the property names that appear in the oslc.select query parameter are those that belong to the resources in the result set as opposed to the container resource.

For example, the following URL finds the high severity bugs and includes their creation date and the family name of the creator in the HTTP response:

 http://example.com/bugs?oslc.select=dc:created,dc:creator{foaf:familyName}&oslc.where=cm:severity="high"

Syntax

The oslc.select query parameter is defined by the term oslc_select in the following BNF grammar:

oslc_select ::= "oslc.select=" properties

The oslc.select query parameter uses the same syntax as the oslc.properties query parameter. The difference between them is in the meaning of the identifers. In oslc.properties, the identifiers are the names of properties of the base URL. In oslc.select, the base URL contains a set of resources, and the identifers are the names of properties of the resources that contained in that set.

For example, suppose that a bug resource contains a collection of comment resources, and that the bug and each comment have dc:modified properties that give their last modification dates. The following query specifes that the reponse should include the modification date of bug 4242 and the modification date of each of its comments:

 http://example.com/bugs/4242?oslc.properties=dc:modified&oslc.select=dc:modified

wildcard

As in the case of oslc.properties, the wildcard is equivalent to the list of all properties of the resources that are contained in the set associated with the base resource. The query parameter oslc.select=* specifies that the HTTP GET response MUST contain all the properties of the member resources.

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://example.com/bugs?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.limit

In practice, a result set may contain a large number of resources, so it is useful to limit the number of resources that are returned in the HTTP response. The oslc.limit query parameter lets you limit the number of resources included in the response.

For example, the following query returns the 100 most recently created high severity bugs:

http://example.com/bugs?oslc.where=cm:severity="high"&oslc.orderBy=-dc:created&oslc.limit=100

Syntax

The syntax of the oslc.limit query parameter is defined by the oslc_limit term in the following BNF grammar:

oslc_limit      ::= "oslc.limit=" positiveInteger
positiveInteger ::=  /* see "XML Schema Part 2: Datatypes Second Edition", http://www.w3.org/TR/xmlschema-2/ */

positiveInteger

The positiveInteger term represents a positive integer value as defined in XML Schema Part 2: Datatypes Second Edition.

oslc.offset

The oslc.offset query parameter lets you specify where in result set to begin the contents of the HTTP response. An oslc.offset of 0 omits no members of the result set. When you use oslc.offset used in conjunction with oslc.limit, you can break up the result set into pages that will be returned in the HTTP response.

For example, the following query returns the next 100 most recent high severity bugs:

http://example.com/bugs?oslc.where=cm:severity="high"&oslc.orderBy=-dc:created&oslc.limit&oslc.offset=100

Syntax

The syntax of the oslc.offset query parameter is defined by the oslc_offset term in the following BNF grammar:

oslc_offset        ::= "oslc.offset=" nonNegativeInteger
nonNegativeInteger ::=  /* see "XML Schema Part 2: Datatypes Second Edition", http://www.w3.org/TR/xmlschema-2/ */

nonNegativeInteger

The nonNegativeInteger term represents a non-negative integer value as defined in XML Schema Part 2: Datatypes Second Edition.

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://example.com/bugs?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://example.com/bugs?oslc.where=cm:severity="high"&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.where=dc:title="test case 1" and dc:modified>="2008-12-02T18:42:30"

?oslc.where=dc%3Atitle%3D%22test%20case%201%22%20and%20dc%3Amodified%3E%3D%222008-12-02T18%3A42%3A30%22

References

• Library of Congress Contextual Query Language (CQL)
• SPARQL Query Language for RDF
• Atom Feed Paging and Archiving
• Uniform Resource Identifier (URI): Generic Syntax
• Namespaces in XML 1.0 (Third Edition)
• XML Schema Part 2: Datatypes Second Edition

Comments

1. Just a nit: The above query syntax contains a number of vestigal references/suffixes (_qm) from the quality management query syntax
   specification. Those should either just be removed.
2. Other OSLC query syntax specifications propose rfc5005, the Atom Feed Paging and Archiving specification, as the proposed mechanism
   for ensuring that large query result sets can be broken into multiple, manageable buffers/pages. If that is the intent here, then that
   aim should be made specific. Moreover, examples of the application of that specification should be provided, as there are questions like
   what the top-level XML document element (atom:feed) and nested, top-level children (atom:entry) should be and the schema for
   those children should be that need examination and definition.

A few questions on the BNF:

• boolean_op "or" is missing
• sort should have an additional modifier for ascending/descending
• sort should be able to handle multiple sort keys
• fulltext is not defined. How would it be encoded?
• Should identifier or word support regular expressions?

-- JimAmsden - 12 Nov 2009

Should query support also include the ability to POST a SPRQL query entity body and return RDF/XML for queries that are not (easily) supported by the BNF?

-- JimAmsden - 12 Nov 2009

The examples should show the URL for the resource the query is acting on. And the examples should show the ATOM file contents returned.

-- JimAmsden - 12 Nov 2009

The behavior of "properties=*" is not documented here (or I'm missing it).

-- ScottBosworth - 12 Nov 2009

It is not all that clear how nested properties can be included in the query.

-- JimConallen - 09 Dec 2009

Thanks Arthur. - Namespaces: This design allows different workgroups to use different prefixes for the same namespaces; I also think it requires that supported namespaces are specified up-front. This means, for example, that properties from those namespaces can't be used in queries.

-- IanGreen - 10 Dec 2009

Namespaces: Can't we have a fixed design-time set of agreed prefixes (oslc, dc, and such link) and then a general mechanism (eg http://www.w3.org/TR/xptr-xmlns/) for other stuff? This offers convenience and extensibility.

-- IanGreen - 10 Dec 2009

-- IanGreen - 10 Dec 2009

Grammar: your non-terminal does not admit all RDF property names (XML tags). For example, I couldn't write a query for a property with the tag "oslc_rm:satisfiedBy" since "oslc_rm" wouldn't parse as a since it contains an underscore - and I assume an undercore is not a letter? I was expecting the grammar to be aligned with what is (currently) accepable in OSLC resource formats.

I wonder if we need a more precise grammar, or a reference implementation to check what is and what is not well-formed.

-- IanGreen - 10 Dec 2009

I think the following is a well-formed query title="a title" In what namespace would the title be interpreted? I wonder if we need to allow unqualified property names.

-- IanGreen - 10 Dec 2009

@Jim: The intention is to define the meaning of these queries by mapping query expressions to SPARQL. Using a property pattern would lead to some challenges in doing this since SPARQL does not property patterns. This might be interesting.

At another level however, the URI of a resource (in this case a property) should be entirely opaque and so "looking inside" a URI - writing a pattern - is bad. Do you have any examples that motivate your suggestion? I can see the need for (dc:contributor="ian" OR dc:creator="ian").

-- IanGreen - 10 Dec 2009

I would like to query for resources that have a relationship to some URI. So for example:

<oslc:resource>
  <dc:title>some resource</dc:title>
  <acme:relationship rdf:resource="http://cyote.com/res/res1"/>
</oslc:resource>

we could treat rdf:resource as a special case I guess, but what if the property was:

<acme:relationship priority="high" df:resource="http://cyote.com/res/res1"/>

and I wanted all resources with links that were high in priority.

-- JimConallen - 10 Dec 2009

-- ArthurRyman - 10 Dec 2009

Some general comments first. This is intended to be a "simple" query syntax for URLs. If we need very complex queries then SPARQL should be used. Of course, that implies RDF is the underlying data model.

This spec is based on a Jazz document that does give semantics by mapping the query parameters to SPARQL. We need to tighten up this spec though.

The question about finding resources related to a given URL is handled the same as for other property value types, i.e. the URL is just another value - we need to escape the dangerous characters in it though.

BTW, Jim's example is not valid RDF. You need to introduce a blank node.

-- ArthurRyman - 10 Dec 2009

The introduction says: "Also, while CQL does support a sort modifier we also introduce a limit modifier to return only a subset of possible results"

I don't see a limit modifier in the BNF

-- PaulMcMahan - 14 Dec 2009

Re: Paul's comment on the limit modifier. A quick check with Speicher revealed that this sentence in the opening paragraph is in error. While a limit modifier was considered early on, it was ditched in favor of the paging mechanisms. This sentence should probably just be deleted.

-- ScottBosworth - 16 Dec 2009

There is another facet to think of beyond a simple query (or complexity of the query itself): The the result to a "fuzzy" search, like a full text SEARCH. This is the case where a search is being refined across a sequence of searches. In this case the result can potentially have other aspects (beyond a oslc:score which I assume is for relevance): valid/available categories and tags for the result (to farther refine the search), suggestions ("did you mean ....") etc.

-- GiliMendel - 31 Dec 2009

Gili, Sounds interesting. Could you create a wiki page with some examples, i.e. query syntax and expected results?

-- ArthurRyman - 05 Jan 2010

-- IanGreen - 23 Feb 2010

Comments on http://open-services.net/bin/view/Main/OslcSimpleQuerySyntaxV1 (apologies that i could not attend the calls.)

Incomplete sentence: "The query parameters also let you sort the result set, limit the "

Perhaps declare up front that URL encoding applies, and that examples are not so encoded.

typeo: satify should be satisfy

I think "The following URL filters this set and selects only bug 4242:" would be more precisely stated as "The following URL filters this set and selects all of those bugs whose dc:identifier is 4242: "

Missing word in "The boolean_op term represents a boolean operation lets you combine simple..."

Typo: severals

Is the feeling that disjunction is not such a typical use case?

Some wording problems in this paragraph: "Grammatically, the value of the oslc.select query parameterhas the same syntax as that of the oslc.properties query parameter. However, the identifiers that appear in oslc.select are property names of resources that belong to the set resources associated with the base URL, whereas the identifiers that appear in oslc.properties are property names of the resource identified by the base URL. "

Missing "response" in: "begin the contents of the HTTP"

On scoring full test results. This might be too strong a requirement to place on providers: "Results MUST be ordered with the entry with the largest oslc:score occuring first. ". We could either consider weakening to SHOULD; perhaps a better way would be to mention (that is, emphasise) that all the scores MAY be the same.

On "oslc.limit" and "oslc.offset", and the suggestion that this could be used to page through results. How does this fit with the current use (by CM/QM) of rfc5005? Is the expectation that two mechanism might be exposed for paging? The nice thing about rfc5005 is that the server drives the paging and is in a position to optimize as a result. There are also freshness/consistency promises arcoss a paged result set (which some providers might choose to offer, despite what rfc5005 says about this) which I think would be problematic without server-driven paging. The 5005 spec states that clients SHOULD NOT treat paged responses as complete/consistent - what is the intention of limit/offset in this regard?

There are no specifications at the http request/response level - in particular, are providers/individual domain topics at liberty to define resource representations of failures, errors, result sets and so on? I think some standardization would be valuable here too. I think the specific case of rfc5005 encoded result sets should be addressed since there appears to be an unresolved overlap.

-- IanGreen - 23 Feb 2010

Is OSLC Core saying anything about how very long query uris are to be dealt with - is that out of scope or left to domain topics?

-- IanGreen - 23 Feb 2010

A related question is on recursion. Should the spec define a shorthand notation for recursion or leave it to the consumer to duplicate the request as much as necessary? This can also lead to very long URLs.

Assuming dc:creator has a dc:creator child element this would look like:

http://example.com/bugs/4242?oslc.properties=dc:title,dc:creator{foaf:givenName,foaf:familyName, dc:creator{foaf:givenName,foaf:familyName, dc:creator{foaf:givenName,foaf:familyName}}}

-- DragosCojocari - 01 Mar 2010

Ian - thx for the detailed comments. I've made the suggested corrections/improvements. Some of the questions are deeper. Here are my thoughts:

1. A full text search MUST rank order the hits since you often just want the first few (discard the rest).

2. oslc.limit and oslc.offset are requests, that indicate what the client prefers, but the server is authoritative and should indicate what the response contains - I believe that will be specified in the Reporting spec which should cite rfc5005 or Atom.

3. I agree that OSLC should specify error response formats, e.g. to allow the server to say that it does not support some query parameter.

4. URL length limits should be dealt with by the Core spec, e.g. specify how to POST them.

-- ArthurRyman - 03 Mar 2010

Dragos, my reaction is that you should just repeat the nested properties. The problem with defining a syntax for recursion is that we do not support unbounded recursion, i.e. following links to any depth. SPARQL can not handle that. Some SQL can.

-- ArthurRyman - 03 Mar 2010

For each property, should we add the parenthesis after the property name and equal mark when there are more than one value of the property or the value contains equal mark? Such as : oslc.select=(dc:created,dc:creator{foaf:familyName})&oslc.where=(cm:severity="high")

-- YaQiangLi - 11 Jun 2010

YaQiangLi - the brackets are illegal syntax. The query parameters are delimited by the '&' character, not the '=' character.Here is the correct syntax

oslc.select=dc:created,dc:creator{foaf:familyName}&oslc.where=cm:severity="high"

-- ArthurRyman - 21 Jul 2010