--- a/paq/prov-aq.html Tue Feb 26 14:40:02 2013 +0000
+++ b/paq/prov-aq.html Tue Feb 26 15:53:44 2013 +0000
@@ -533,7 +533,8 @@
<pre class="pattern">
Link: <<cite>service-URI</cite>>;
rel="http://www.w3.org/ns/prov#hasQueryService";
- anchor="<cite>entity-URI</cite>"</pre>
+ anchor="<cite>entity-URI</cite>"
+ </pre>
<p>
The <code>hasQueryService</code> link identifies the <a class="internalDFN">service-URI</a>. Dereferencing this URI yields a service description that provides further information to enable a client to submit a query to retrieve a <a class="internalDFN">provenance record</a> for a <a class="internalDFN">resource</a>; see <a href="#provenance-query-services" class="sectionRef"></a> for more details.
</p>
@@ -744,7 +745,15 @@
The remainder of this section covers the following topics:
</p>
<ul>
- <li><a class="sectionRef" href="#provenance-query-service-description"></a> - describes an RDF-based service description format and vocabularies to convey information about direct HTTP query and/or SPARQL service options.</li>
+ <li>
+ <a class="sectionRef" href="#provenance-query-service-description"></a> - describes an RDF-based service description format and vocabularies to convey information about direct HTTP query and/or SPARQL service options.
+ <ul>
+ <a class="sectionRef" href="#direct-http-query-service-description"></a> - RDF structure for describing a direct HTTP query service.
+ </ul>
+ <ul>
+ <a class="sectionRef" href="#sparql-query-service-description"></a> - RDF structure for describing a SPARQL query service.
+ </ul>
+ </li>
<li><a class="sectionRef" href="#direct-http-query-service-invocation"></a> - describes how to perform a direct HTTP query for provenance, using information obtained from the service description.</li>
<li><a class="sectionRef" href="#provenance-query-service-discovery"></a> - briefly discusses some possible approaches to discovery of provenance query services.
</ul>
@@ -752,10 +761,31 @@
<!-- <section class="informative"> -->
<section>
<h2>Provenance query service description</h2>
+ <p class="TODO">
+ Review. Stian suggests recommending use of JSON-LD. I am resisting this because it is clearly allowed by "RDF (in any of its common serializations as determined by HTTP content negotiation)", focusing on a particular format as part of the underlying mechanism seems to go against REST principles, and at this stage it seems that promoting any particular format will draw objections from proponents of other formats. I've taken a different tack, making the text more open about possible service description formats, while specifically presenting a description based on the RDF model.
+ </p>
<p>
- Dereferencing a <a class="internalDFN">service-URI</a> yields a service description. The service description described here may be supplied as RDF (in any of its common serializations as determined by HTTP content negotiation), and it may contain descriptions of one or more available query mechanisms. Each query mechanism is associated with an RDF resource of a given type, as described below.
+ Dereferencing a <a class="internalDFN">service-URI</a> yields a service description. The service description presented here may be supplied as RDF (in any of its common serializations as determined by HTTP content negotiation), and it may contain descriptions of one or more available query mechanisms. Each query mechanism is associated with an RDF type, as explained below.
+ (The presentation here of RDF service descriptions does not preclude use of non-RDF formats selectable by HTTP content negotiation.)
</p>
- <p>While use of RDF for service descriptions is a recommended option, this specification does not preclude the use of non-RDF formats that a service may choose to offer, and which may be selected using HTTP content negotiation.
+ <p>
+ The overall structure of a service description is as follows:
+ </p>
+ <pre class="pattern">
+<<cite>service-URI</cite>> a prov:ProvenanceQueryService ;
+ prov:describesService <<cite>direct-query-description</cite>>, <<cite>sparql-query-description</cite>> .
+
+<<cite>direct-query-description</cite>> a prov:DirectQueryService ;
+ prov:provenanceUriTemplate "<cite>direct-query-template</cite>"
+ .
+
+<<cite>sparql-query-description</cite>> a sd:Service ;
+ sd:endpoint <<cite>sparql-query</cite>> ;
+ # other details...
+ .
+</pre>
+ <p>
+ We see here that the <code><cite>service-URI</cite></code> identifies a resource of type <code>prov:ProvenanceQueryService</code>, which collects descriptions of one or more provenance query mechanisms. Each associated mechanism is indicated by a <code>prov:describesService</code> statement.
</p>
<p class="note">
We expect the presentation of service descriptions to be considered by the W3C Linked Data Platform group (<a href="http://www.w3.org/2012/ldp/" class="externalRef">www.w3.org/2012/ldp/</a>); at the time of writing, there is no consensus (cf. message at <a href="http://lists.w3.org/Archives/Public/public-ldp/2012Nov/0036.html" class="externalRef">lists.w3.org/Archives/Public/public-ldp/2012Nov/0036.html</a> and responses). As and when such consensus emerges, we recommend that provenance query service implementers consider adopting it, or at least consider making their implementations compatible with it.
@@ -763,17 +793,15 @@
<section>
<h2>Direct HTTP query service description</h2>
- <p class="TODO">
- Tim's point (20): I think this will be covered by Stian's proposal; leaving for now.
- </p>
<p>A direct HTTP query service is described by an RDF resource of type <code>prov:DirectQueryService</code></p>
<p>It allows for accessing provenance about a specified <a class="internalDFN">entity-URI</a>. The query URI to use is described by a URI Template [[URI-template]] (level 2 or above) in which which the variable <cite><code>uri</code></cite> stands for the entity-URI; e.g.</p>
<pre class="pattern">
- @prefix prov: <http://www.w3c.org/ns/prov#>
- <cite>query_option_node</cite> a prov:DirectQueryService ;
- prov:provenanceUriTemplate "<cite>service-URI</cite>?target={+uri}" .</pre>
+@prefix prov: <http://www.w3c.org/ns/prov#>
+<direct-query-description> a prov:DirectQueryService ;
+ prov:provenanceUriTemplate "<cite>query-URI</cite>?target={+uri}" .
+</pre>
<p>
- where <cite><code>service-URI</code></cite> is the URI of the provenance query service, and <code><cite>query_option_node</cite></code> is any distinct RDF subject node (i.e. a blank node or a URI).
+ where <cite><code>query-URI</code></cite> is the base URI of the direct query service, and <code><cite>direct-query-description</cite></code> is any distinct RDF subject node (i.e. a blank node or a URI).
</p>
<p>
The URI template indicated by <code>prov:provenanceUriTemplate</code> may expand to an absolute or relative URI reference. A URI for the desired provenance record is obtained by expanding the URI template with the variable <cite><code>uri</code></cite> set to the entity-URI for which provenance is requested. In this example, if the entity-URI contains '#' or '&' these must be %-escaped as <code>%23</code> or <code>%26</code> respectively before template expansion [[RFC3986]]. If the result is a relative reference, it is interpreted per [[RFC3986]] (section 5.2) using the URI of the service description as its base URI (which is generally the same as the query service-URI, unless HTTP redirection has been invoked).
@@ -782,26 +810,24 @@
A provenance query service MAY recognize additional parameters encoded as part of a URI for the provenance record. If it does, it SHOULD include these in the provenance URI template in the service description, so that clients may discover how a URI is formed using this additional information.
For example, a query service might offer to include just the immediate provenance of an entity, or to also supply provenance of entities from which the target resource is derived. Suppose a service accepts an additional parameter <code>steps</code> that defines the number of previous steps to include in a provenance trace, it might publish its service description thus:
</p>
- <pre class="pattern">
- <<cite>query_option_node</cite>> a prov:DirectQueryService ;
- prov:provenanceUriTemplate "http://www.example.com/provenance/service?target={+uri}{&steps}" .</pre>
+ <pre class="example code">
+<<cite>direct-query-description</cite>> a prov:DirectQueryService ;
+ prov:provenanceUriTemplate
+ "http://www.example.com/provenance/service?target={+uri}{&steps}" .
+</pre>
<p>
which might result in an HTTP query for provenance information that looks like this:
</p>
- <pre class="pattern">
- GET /provenance/service?<b>target</b>=http://www.example.com/entity&<b>steps</b>=2 HTTP/1.1
- Host: example.com</pre>
+ <pre class="example code">
+GET /provenance/service?<b>target</b>=http://www.example.com/entity&<b>steps</b>=2 HTTP/1.1
+Host: example.com</pre>
<p>
(Note that in this case, a "level 3" URI template feature is used [[URI-template]].)
</p>
</section>
-
<section>
<h2>SPARQL query service description</h2>
- <p class="TODO">
- Tim's point (22): I think this will be covered by Stian's proposal; leaving for now.
- </p>
<p>
A SPARQL query service is described by an RDF resource of type <code>sd:Service</code> [[SPARQL-SD]].
</p>
@@ -811,20 +837,21 @@
<p>
The SPARQL query service description is constructed as defined by <cite>SPARQL 1.1 Service Description</cite> [[SPARQL-SD]]; e.g.
</p>
- <pre class="pattern">
- @prefix sd: <http://www.w3.org/ns/sparql-service-description#>
- <cite>query_option_node</cite> a sd:Service ;
- sd:endpoint <<cite>service-URI</cite>/sparql/> ;
- sd:supportedLanguage sd:SPARQL11Query .</pre>
+ <pre class="example code">
+<cite>sparql-query-description</cite> a sd:Service ;
+ sd:endpoint <<cite>query-URI</cite>/sparql/> ;
+ sd:supportedLanguage sd:SPARQL11Query .
+</pre>
<p>
- where <cite><code>service-URI</code></cite> is the URI of the provenance service, and <code><cite>query_option_node</cite></code> is any distinct RDF subject node (i.e. a blank node or a URI).
+ where <cite><code>query-URI</code></cite> is the base URI of the provenance query service, and <code><cite>sparql-query-description</cite></code> is any distinct RDF subject node (i.e. a blank node or a URI).
</p>
<p>
The SPARQL service description may be detailed or sparse, provided that it includes at a minimum the following:
</p>
<pre class="pattern">
- <cite>query_option_node</cite> a sd:Service ;
- sd:endpoint <(SPARQL service endpoint URI reference)> .</pre>
+<cite>sparql-query-description</cite> a sd:Service ;
+ sd:endpoint <(SPARQL service endpoint URI reference)> .
+</pre>
<p>
The endpoint may be given as an absolute or relative URI reference. If a relative reference is given, it is interpreted in the normal way for the RDF format used, which will commonly be relative to the URI of the service document itself.
</p>
@@ -835,25 +862,36 @@
<p>
The following service description example uses Turtle [[TURTLE]] syntax to describe both direct HTTP and SPARQL query services:
</p>
- <pre class="example">
- @prefix prov: <http://www.w3c.org/ns/prov#>
- @prefix sd: <http://www.w3.org/ns/sparql-service-description#>
-
- <> a prov:ProvenanceQueryService .
+ <pre class="example code">
+@prefix prov: <http://www.w3c.org/ns/prov#>
+@prefix dcterms: <http://purl.org/dc/terms/>
+@prefix foaf: <http://xmlns.com/foaf/0.1/>
+@prefix sd: <http://www.w3.org/ns/sparql-service-description#>
- <#direct> a prov:DirectQueryService ;
- prov:provenanceUriTemplate "?target={+uri}"
- .
- <#sparql> a sd:Service ;
- sd:endpoint </sparql/> ;
- sd:supportedLanguage sd:SPARQL11Query ;
- sd:resultFormat <http://www.w3.org/ns/formats/RDF_XML> ,
- <http://www.w3.org/ns/formats/Turtle> ,
- <http://www.w3.org/ns/formats/SPARQL_Results_XML> ,
- <http://www.w3.org/ns/formats/SPARQL_Results_JSON> ,
- <http://www.w3.org/ns/formats/SPARQL_Results_CSV> ,
- <http://www.w3.org/ns/formats/SPARQL_Results_TSV>
- .</pre>
+<> a prov:ProvenanceQueryService ;
+ prov:describesService <#direct>, <#sparql> ;
+ dcterms:publisher <#us>
+ .
+
+<#us> a foaf:Organization ;
+ foaf:name "and not a service!"
+ .
+
+<#direct> a prov:DirectQueryService ;
+ prov:provenanceUriTemplate "/direct?target={+uri}"
+ .
+
+<#sparql> a sd:Service ;
+ sd:endpoint </sparql/> ;
+ sd:supportedLanguage sd:SPARQL11Query ;
+ sd:resultFormat <http://www.w3.org/ns/formats/RDF_XML> ,
+ <http://www.w3.org/ns/formats/Turtle> ,
+ <http://www.w3.org/ns/formats/SPARQL_Results_XML> ,
+ <http://www.w3.org/ns/formats/SPARQL_Results_JSON> ,
+ <http://www.w3.org/ns/formats/SPARQL_Results_CSV> ,
+ <http://www.w3.org/ns/formats/SPARQL_Results_TSV>
+ .
+</pre>
</section>
</section>
@@ -1047,6 +1085,31 @@
<td>Indicates a <a class="internalDFN">provenance query service</a> that can access provenance related to its subject or anchor resource.</td>
<td><a href="#specifying-provenance-query-services" class="sectionRef"></a></td>
</tr>
+
+ <tr style="vertical-align: top;">
+ <td><code>prov:describesService</code></td>
+ <td>...</td>
+ <td><a href="#..." class="sectionRef"></a></td>
+ </tr>
+ <tr style="vertical-align: top;">
+ <td><code>...</code></td>
+ <td>...</td>
+ <td><a href="#..." class="sectionRef"></a></td>
+ </tr>
+ <tr style="vertical-align: top;">
+ <td><code>...</code></td>
+ <td>...</td>
+ <td><a href="#..." class="sectionRef"></a></td>
+ </tr>
+ <tr style="vertical-align: top;">
+ <td><code>...</code></td>
+ <td>...</td>
+ <td><a href="#..." class="sectionRef"></a></td>
+ </tr>
+
+
+
+
<tr style="vertical-align: top;">
<td><code>provenanceUriTemplate</code></td>
<td>Indicates a URI template string for constructing provenance-URIs</td>