CM 1.0 Simple Query Syntax, how we got here

Often I get asked about what how it was decided what was included into the CM 1.0 Simple Query Syntax, so I figured I'd take a couple of minutes to summarize some key points. The goals for the 1.0 were quite simple: produce a simple syntax that supports our scenarios and that will work with SQL and SPARQL based back-ends. One of the most obvious omissions from the query syntax is the "or " operator, or UNION if you are from SPARQL. This was intentional since the CM WG realized that all scenarios could be accomplished by having support for the "in" operator. By doing this, we avoided the complexity of having to support grouping of terms with parenthesis.

The type of query we saw as being key to support in 1.0 were queries such as: Show me all open change requests assigned to a specific user
?oslc_cm.query= owner="bob" and status in ["submitted","working"]

Beyond that, most other operators are quite common. Another primary scenario was the ability to retrieve a set of change requests that have been modified since a given date. Which is supported by both having the Dublin Core usage of dc:modified and comparison operators such as:
?oslc_cm.query=dc:modified>="12-02-2008T18:42:30"

This has been proven to be very powerful and easy to map to service provider search capabilities. At some point there may need to be support for a full query syntax service, which could be a unique URL end point to post a query to. We'll have to wait and see how this plays out over time.

Using Selective Properties (aka Partial Fetch)

Often is an issue when working with retrieving resources and their properties is getting the desired information efficiently. By definition of the CM 1.0 specification, when requesting a change request resource without any parameters to refine the list of properties you should retrieve ALL properties that resource has. Take for example this simple request:

GET http://example.com/bugs/2314
Accept: application/x-oslc-cm-change-request+xml

This will result in the change request identified by the URL to be retrieved:

<oslc_cm:ChangeRequest 
  rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
  dc="http://purl.org/dc/terms/" 
  oslc_cm="http://open-services.net/xmlns/cm/1.0/"
  xmlns="http://myserver/xmlns"
  about="http://example.com/bugs/2314">

  <dc:title> Provide import </dc:title>
  <dc:identifier> 2314 </dc:identifier>
  <dc:type> http://myserver/mycmapp/types/Enhancement </dc:type>
  <dc:description>
    Implement the system's import capabilities.
  </dc:description>
  <dc:subject> import, blocker </dc:subject>
  <dc:creator resource="http://example.com/users/aadams" />
  <dc:modified> 2008-09-16T08:42:11.265Z </dc:modified>
  <owner resource="http://example.com/users/john">
  <priority>High</priority>
  <severity>High</severity>
  <status>Working</status>
</oslc_cm:ChangeRequest>

This is useful when a consumer doesn't know which properties to request but can provide more information than is needed (both that the provider needs to generate and the consumer needs to process). To limit the amount of properties returned, the concept of selective properties can be used. If the consumer is only interested in the owner and the status, the request could be formulated such as:

GET http://example.com/bugs/2314?oslc_cm.properties=owner,status
Accept: application/x-oslc-cm-change-request+xml

Resulting in:

<oslc_cm:ChangeRequest 
  dc="http://purl.org/dc/terms/"
  oslc_cm="http://open-services.net/xmlns/cm/1.0/"
  xmlns="http://myserver/xmlns"
  about="http://example.com/bugs/2314">

  <owner resource="http://example.com/users/john" />
  <status>Working</status>
</oslc_cm:ChangeRequest>

Perhaps we are interested in the owner's name and email address, we can expand the owner entry and select only those properties to be returned such as:

GET http://example.com/bugs/2314?oslc_cm.properties=owner{fullname,email},status
Accept: application/x-oslc-cm-change-request+xml

Resulting in:

<oslc_cm:ChangeRequest 
  rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
  dc="http://purl.org/dc/terms/"
  oslc_cm="http://open-services.net/xmlns/cm/1.0/"
  xmlns="http://myserver/xmlns"
  about="http://example.com/bugs/2314">

  <owner>
    <User rdf:about="http://example.com/users/john">
      <fullname>John Doe</fullname>
      <email>jdoe@myco</email>
    </User>
  <status>Working</status>
</oslc_cm:ChangeRequest>

This technique is used in CM 1.0 not only for selective retrieval of properties on a change request resource, it is used for partial updates of resources as well as controlling the content on query responses.