--- a/paq/prov-aq.html Tue Feb 26 15:54:06 2013 +0000
+++ b/paq/prov-aq.html Tue Feb 26 16:10:55 2013 +0000
@@ -772,7 +772,7 @@
The overall structure of a service description is as follows:
</p>
<pre class="pattern">
-<<cite>service-URI</cite>> a prov:ProvenanceQueryService ;
+<<cite>service-URI</cite>> a prov:ServiceDescription ;
prov:describesService <<cite>direct-query-description</cite>>, <<cite>sparql-query-description</cite>> .
<<cite>direct-query-description</cite>> a prov:DirectQueryService ;
@@ -785,7 +785,7 @@
.
</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.
+ We see here that the <code><cite>service-URI</cite></code> identifies a resource of type <code>prov:ServiceDescription</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.
@@ -868,7 +868,7 @@
@prefix foaf: <http://xmlns.com/foaf/0.1/>
@prefix sd: <http://www.w3.org/ns/sparql-service-description#>
-<> a prov:ProvenanceQueryService ;
+<> a prov:ServiceDescription ;
prov:describesService <#direct>, <#sparql> ;
dcterms:publisher <#us>
.
@@ -897,15 +897,21 @@
<section>
<h2>Direct HTTP query service invocation</h2>
- <p>This protocol typically combines the <a class="internalDFN">entity-URI</a> with the <a class="internalDFN">service-URI</a> to formulate an HTTP GET request, according to the following convention:
- <pre class="pattern">
- GET /provenance/service?<b>target</b>=http://www.example.com/entity123 HTTP/1.1
- Host: example.com</pre>
- </p>
- <p>The embedded entity-URI (<code>http://www.example.com/entity123</code>) identifies the resource for which provenance is to be returned. Any server that implements this protocol and receives a request URI in this form SHOULD return a provenance record for the resource-URI embedded in the query component, where that URI is the result of percent-decoding the value associated with the provenance-resource key. The embedded URI MUST be an absolute URI and the server MUST respond with a 400 Bad Request if it is not. If the supplied resource-URI includes a fragment identifier, the '#' MUST be %-encoded as <code>%23</code> when constructing the provenance-URI value; similarly, any '&' character in the resource-URI must be %-encoded as <code>%26</code> [[RFC3986]].
+ <p>
+ This protocol combines the <a class="internalDFN">entity-URI</a> with a supplied URI template to formulate an HTTP GET request.
</p>
<p>
- If the provenance described by the request does not exist in the server, a <code>404 Not Found</code> response code SHOULD be returned.
+ Thus, if the URI template extrtacted from the service description is <code>http://example.com/provenance/service?target={+uri}</code> and the supplied entity-URI is <code>http://www.example.com/entity123</code>, the resulting HTTP request would be:
+ <pre class="example code">
+GET /provenance/service?<b>target</b>=http://www.example.com/entity123 HTTP/1.1
+Host: example.com
+</pre>
+ </p>
+ <p>
+ The embedded entity-URI (<code>http://www.example.com/entity123</code>) identifies the resource for which provenance is to be returned. Any server that implements this protocol and receives a request URI in this form SHOULD return a provenance record for the resource-URI embedded in the query component, where that URI is the result of percent-decoding the value associated with the provenance-resource key. The embedded URI MUST be an absolute URI and the server MUST respond with a 400 Bad Request if it is not. If the supplied resource-URI includes a fragment identifier, the '#' MUST be %-encoded as <code>%23</code> when constructing the provenance-URI value; similarly, any '&' character in the resource-URI must be %-encoded as <code>%26</code> [[RFC3986]].
+ </p>
+ <p>
+ If the provenance described by the request does not exist in the server, a suitable error response code SHOULD be returned. In the absence of any security of privacy concerns about the resource, that might be <code>404 Not Found</code>. But if the existence or non-existence of a resource is considered private, and authorization failure or other error response should be returned.
</p>
<p>
The format of the returned provenance record is not defined here, but may be established through content type negotiation using <code>Accept:</code> header fields in the HTTP request. A provenance query service SHOULD be capable of returning RDF using the vocabulary defined by [[PROV-O]], in at least one of the standard RDF serializations (e.g. RDF/XML), or any other standard serialization of the Provenance Model specification [[PROV-DM]]. Services MUST identify the <code>Content-Type</code> of the information returned.
@@ -922,7 +928,7 @@
Previously, <a href="#locating-provenance-records" class="sectionRef"></a> has described use of HTTP <code>Link:</code> header fields and HTML <code><link></code> elements to indicate provenance query services. Beyond that, this specification does not define any specific mechanism for discovering query services. Applications may use any appropriate mechanism, including but not limited to: prior configuration, search engines, service registries, etc.
</p>
<p>
- To facilitate service discovery, we recommend that RDF publication of dataset and service descriptions use the property <code>prov:hasQueryService</code> and the provenance service type <code>prov:ProvenanceQueryService</code> as appropriate (see the appendix <a href="#prov-namespace" class="sectionRef"></a>).
+ To facilitate service discovery, we recommend that RDF publication of dataset and service descriptions use the property <code>prov:hasQueryService</code> and the provenance service type <code>prov:ServiceDescription</code> as appropriate (see the appendix <a href="#prov-namespace" class="sectionRef"></a>).
</p>
<p>
For example, a VoID description [[VoID]] of a dataset might indicate a provenance query service providing information about that dataset:
@@ -931,7 +937,7 @@
<http://example.org/dataset/> a void:Dataset ;
prov:hasQueryService <http://example.org/provenance/> .</pre>
<p>
- The RDF service description example in <a href="#service-description-example" class="sectionRef"></a> shows use of the <code>prov:ProvenanceQueryService</code> type.
+ The RDF service description example in <a href="#service-description-example" class="sectionRef"></a> shows use of the <code>prov:ServiceDescription</code> type.
</p>
</section>
@@ -1060,7 +1066,7 @@
<th>Name</th><th>Description</th><th>Definition ref</th>
</tr>
<tr style="vertical-align: top;">
- <td><code>ProvenanceQueryService</code></td>
+ <td><code>ServiceDescription</code></td>
<td>Type for a generic provenance query service. Mainly for use in RDF provenance query service descriptions, to facilitate discovery in linked data environments.</td>
<td><a href="#provenance-query-service-discovery" class="sectionRef"></a></td>
</tr>
@@ -1122,10 +1128,10 @@
</tr>
</table>
<p class="note">
- It is tempting to think of <code>prov:DirectQueryService</code> as a particular kind of <code>prov:ProvenanceQueryService</code>, but they are, in practice, distinct resources.
+ It is tempting to think of <code>prov:DirectQueryService</code> as a particular kind of <code>prov:ServiceDescription</code>, but they are, in practice, distinct resources.
<br/>
<br/>
- This is seen when one considers that a <code>prov:ProvenanceQueryService</code> may have multiple query mechanisms associated with it (e.g. a <code>prov:DirectQueryService</code> <em>and</em> an <code>sd:Service</code>). Also, they serve quite different purposes in the process of using provenance query services: look for <code>prov:ProvenanceQueryService</code> to discover query services of any kind, then for associated <code>prov:DirectQueryService</code> or <code>sd:Service</code> resources to get details of specific mechanisms to use to access the service.
+ This is seen when one considers that a <code>prov:ServiceDescription</code> may have multiple query mechanisms associated with it (e.g. a <code>prov:DirectQueryService</code> <em>and</em> an <code>sd:Service</code>). Also, they serve quite different purposes in the process of using provenance query services: look for <code>prov:ServiceDescription</code> to discover query services of any kind, then for associated <code>prov:DirectQueryService</code> or <code>sd:Service</code> resources to get details of specific mechanisms to use to access the service.
</p>
<p class="TODO">
review provPingback in light of Stian's proposal