Architecture Management Simple Query Syntax

1.0 SPECIFICATION

Introduction

A common OSLC query specification is being drafted for multiple specifications. We will adopt this specification and supply the required details necessary for use in the Architecture Management space.

One issue with this spec, that we should change however is the predefined namespace prefixes. In our use of this spec we will not assume predefined prefixes.

Some of the queries we need to support include:

1. Find all resources of a certain type (dc:type) with a specific title (wildcarded). For example "all UML Interfaces whose name begins with IService"
2. Find all resources that have the property <acme:relatedTo rdf:resource="http://a.com/b#id" />

Using the current common query proposal the first query can be expressed with (before URL encoding):

?query=http://purl.org/dc/terms/title="IService*" 
           and http://purl.org/dc/terms/type=http://www.eclipse.org/uml2/3.0.0/UML/Interface

URL encoded this would look like:

?query=http%3A%2F%2Fpurl.org%2Fdc%2Fterms%2Ftitle%3D%22IService*%22+and+http%3A%2F%2Fpurl.org%2Fdc%2Fterms%2Ftype%3Dhttp%3A%2F%2Fwww.eclipse.org%2Fuml2%2F3.0.0%2FUML%2FInterface

The second would look like:

?query=http://acme.com/terms/relatedTo=http://a.com.b#id  

This will only work if we declare that the additional properties allowed to be included in an AM resources representation be RDF. Or put another way, there is an assumption that the value of a predicate like <acme:relatedTo> is expressed as the rdf:resource attribute in the XML element. The consistency of such assumptions is rationalized when we interpret the resource as RDF.

What is not clear is how do we augment this second query to look for relationships with a specific resource and some properties of that relationship? The simple query syntax proposed here does not cover this, and it should probably be stated that such complex queries are better suited to a more comprehensive language like SPARQL.

ATOM Result

In keeping with our architectural principals all query results will be returned in the form of an ATOM collection or feed.

The ATOM specification is flexible and we must state which fields are required and optional.

Service providers MAY extend a feed with any content they wish provided it does so within the rules and guidelines of the ATOM paging specification. Extensions defining new vocabularies MUST use XML namespaces.

Each Feed MUST include the proper namespace declarations (ATOM, Open Search, OSLC AM).

Each Feed MUST include

• Open Search:totalResults - element which specifies the total number of results found.
• Atom:updated - the date/time the collection was created.
• Atom:id - MUST be a URN(used in paging)
• Atom:link - rel=self a reference back to the query
• Atom:title - a human readable label for the feed (required by ATOM specification)

Example

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" 
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:dc="http://purl.org/dc/terms/"
      xmlns:oslc_am="http://open-services.net/xmlns/am/1.0/">

    <title>Query results</title>
    <id>urn:uuid:0003939e0af6</id>
    <updated>2003-12-13T18:30:02Z</updated>
    <opensearch:totalResults>2</opensearch:totalResults>

    <entry>   
    ...
    </entry>
    ...

</feed>

Note: may need to require a content or a summary in each entry.

Each Entry MUST include the following fields:

• Atom:title - with a human readable label of the entry
• Atom:link - the absolute URI referencing the resource identified by the entry
• Atom:updated - the datetime of the last modification of the resource

Example

<entry>
   <id>urn:uuid:23892382s7a7</id>
   <updated>2003-12-13T18:30:02Z</updated>
   <title>this is a title</title>
   <link href="http://example.org/resources/res158"/>
</entry> 

Service providers MAY include:

• OSLC_AM:etag - the etag value associated with the resource identified in the entry.
• Atom:content - includes OSLC AM representation of the resource

Example

<entry>
   <id>urn:uuid:8s23ks8aksd8</id>
   <updated>2003-12-13T18:30:02Z</updated>
   <title>ICustomerAudit</title>
   <link href="http://example.org/resources/res9276"/>
   <oslc_am:etag>scmSBvo1Ed6LKdTEkaDiws</oslc_am:etag>
   <content>
       <rdf:RDF>
           <rdf:Description>
               <dc:title>IAudit</dc:title>
               <dc:description>Used to access customer audit information.</dc:description>
               <dc:type rdf:resource="http://www.eclipse.org/uml2/3.0.0/UML/Interface" />
               <dc:format>application/x-uml+xml</dc:format>
           </rdf:Description>               
       </rdf:RDF>
   </content>       
</entry>

A full complete example

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" 
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:dc="http://purl.org/dc/terms/"
      xmlns:oslc_am="http://open-services.net/xmlns/am/1.0/">

    <title>Query results</title>
    <id>urn:uuid:0003939e0af6</id>
    <updated>2003-12-13T18:30:02Z</updated>
    <opensearch:totalResults>2</opensearch:totalResults>

    <entry>
       <id>urn:uuid:23892382s7a7</id>
       <updated>2003-12-13T18:30:02Z</updated>
       <title>IAudit</title>
       <link href="http://example.org/resources/res912"/>
       <oslc_am:etag>scmSBvo1Ed6LKdTEkaDiws</oslc_am:etag>
       <content>
           <rdf:RDF>
               <rdf:Description>
                   <dc:title>IAudit</dc:title>
                   <dc:description>Used to access audit information.</dc:description>
                   <dc:type rdf:resource="http://www.eclipse.org/uml2/3.0.0/UML/Interface" />
                   <dc:format>application/x-uml+xml</dc:format>
               </rdf:Description>               
           </rdf:RDF>
       </content>       
    </entry>

    <entry>
       <id>urn:uuid:8a93227fff7as</id>
       <updated>2003-12-13T18:30:02Z</updated>
       <title>ICustomerAudit</title>
       <link href="http://example.org/resources/res9276"/>
       <oslc_am:etag>scmSBvo1Ed6LKdTEkaDiws</oslc_am:etag>
       <content>
           <rdf:RDF>
               <rdf:Description>
                   <dc:title>ICustomerAudit</dc:title>
                   <dc:description>Used to access customer audit information.</dc:description>
                   <dc:type rdf:resource="http://www.eclipse.org/uml2/3.0.0/UML/Interface" />
                   <dc:format>application/x-uml+xml</dc:format>
               </rdf:Description>               
           </rdf:RDF>
       </content>       
    </entry>

</feed>
 

Paging

If the results to be returned in a collection exceed a prudent number of entries, a service provider MAY page the collection. Clients SHOULD be prepared to accept and manage paged collections.

The feed documents in a paged feed are tied together with the following <link> relations:

• rel="first" - A URI that refers to the first page in the set of pages.
• rel="last" - A URI that refers to the last page in the set of pages.
• rel="previous" - A URI that refers to the page just before the current page in the total set of pages.
• rel= "next" - A URI that refers to the page just after current page in the total set of pages.

Paged feed collections MUST have at least one of these link relations and SHOULD contain as many as practical and applicable.

In the following example the <link> relations are direct child elements of the root <feed> element.

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" 
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:oslc_am="http://open-services.net/xmlns/am/1.0/">
    <id>urn:uuid:0003939e0af6</id>
    <updated>2003-12-13T18:30:02Z</updated>
    <opensearch:totalResults>200</opensearch:totalResults>
    <link rel="first" href="http://example.com/query?id=2923&page=1" />
    <link rel="prev" href="http://example.com/query?id=2923&page=4" />
    <link rel="next" href="http://example.com/query?id=2923&page=6" />
    <link rel="last" href="http://example.com/query?id=2923&page=20" />

    <entry>
      ...
    </entry>

     ...

</feed>