--- a/paq/prov-aq.html Fri Dec 21 09:07:50 2012 +0000
+++ b/paq/prov-aq.html Fri Jan 04 13:03:57 2013 +0000
@@ -91,10 +91,16 @@
"<a href=\"http://www.w3.org/TR/void/\">http://www.w3.org/TR/void/</a>",
"RDF-CONCEPTS11":
- "Richard Cyganiak; David Wood; eds. " +
+ "Richard Cyganiak, David Wood, eds. " +
"<a href=\"http://www.w3.org/TR/rdf11-concepts/\"><cite>RDF 1.1 Concepts and Abstract Syntax</cite></a>. Working Draft. "+
"URL: <a href=\"http://www.w3.org/TR/rdf11-concepts/\">http://www.w3.org/TR/rdf11-concepts/</a>",
+ "TURTLE":
+ "Eric Prud'hommeaux, Gavin Carothers. "+
+ "<a href=\"http://www.w3.org/TR/turtle/\"><cite>Turtle: Terse RDF Triple Language</cite></a>. "+
+ "10 July 2012. W3C Working Draft. @@update when published. "+
+ "URL: <a href=\"http://www.w3.org/TR/turtle/\">http://www.w3.org/TR/turtle/</a>",
+
};
var respecConfig = {
// specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
@@ -230,7 +236,7 @@
</ul>
<h4>Second Public Working Draft</h4>
<p>
-This is the second public working draft. The changes focus on revising the provenance-service specification to provide better guidance to developers as well as introducing better naming conventions for the use of link headers in locating provenance.
+This is the second public working draft. The changes focus on revising the provenance query service specification to provide better guidance to developers as well as introducing better naming conventions for the use of link headers in locating provenance.
</p>
</section>
@@ -250,7 +256,7 @@
Simple mechanisms for retrieving and discovering provenance descriptions are described in <a href="#accessing-provenance-descriptions" class="sectionRef"></a> and <a href="#locating-provenance-descriptions" class="sectionRef"></a> .
</li>
<li>
- Provenance service mechanisms that may be used for more demanding deployments are described in <a href="#provenance-services" class="sectionRef"></a>.
+ Provenance query service mechanisms that may be used for more demanding deployments are described in <a href="#provenance-query-services" class="sectionRef"></a>.
</li>
<li>
A simple "ping-back" mechanism allowing for collection of forward provenance is described in <a href="#forward-provenance" class="sectionRef"></a>
@@ -275,14 +281,14 @@
<dd>refers to provenance represented in some fashion.</dd>
<dt><a href="#dfn-provenance-uri"><dfn>Provenance-URI</dfn></a></dt>
<dd>a URI denoting some <a class="internalDFN">provenance description</a>.</dd>
- <dt><a href="#dfn-provenance-service"><dfn>Provenance service</dfn></a></dt>
- <dd>a service that provides a <a class="internalDFN">provenance description</a> given a <a class="internalDFN">target-URI</a>.</dd>
+ <dt><a href="#dfn-provenance-query-service"><dfn>Provenance query service</dfn></a></dt>
+ <dd>a query service that provides a <a class="internalDFN">provenance description</a> given a <a class="internalDFN">target-URI</a> or other information about the desired provenance.</dd>
<dt><a href="#dfn-service-uri"><dfn>Service-URI</dfn></a></dt>
- <dd>the URI of a <a class="internalDFN">provenance service</a>.</dd>
+ <dd>the URI of a <a class="internalDFN">provenance query service</a>.</dd>
<dt><a href="#dfn-pingback-uri"><dfn>Pingback-URI</dfn></a></dt>
<dd>the URI of a provenance pingback service that can receive forward provenance descriptions (i.e. provenance describing how a resource is used - see <a href="#forward-provenance" class="sectionRef"></a>).</dd>
<dt><a href="#dfn-accessing"><dfn>Accessing</dfn></a> provenance descriptions</dt>
- <dd>given the identity of a resource, the process of discovering and retrieving some <a class="internalDFN">provenance description</a>(s) about that resource. This may involve <a class="internalDFN">locating</a> a provenance description resource, then performing an HTTP GET to retrieve it, or locating a service and querying the service for provenance description about an identified resource, or some other mechanism not covered in this document.</dd>
+ <dd>given the identity of a resource, the process of discovering and retrieving some <a class="internalDFN">provenance description</a>(s) about that resource. This may involve <a class="internalDFN">locating</a> a provenance description resource, then performing an HTTP GET to retrieve it, or locating and using a query service for provenance description about an identified resource, or some other mechanism not covered in this document.</dd>
<dt><a href="#dfn-locating"><dfn>Locating</dfn></a> provenance descriptions</dt>
<dd>given the identity of a resource, discovery of a URI at which some <a class="internalDFN">provenance description</a> about that resource may be retrieved.</dd>
<!--
@@ -343,8 +349,8 @@
</tr>
<tr style="vertical-align: top;">
<td><a class="internalDFN">Service-URI</a></td>
- <td>A provenance service (i.e. a resource of type <code>prov:ProvenanceService</code>). This is the initial URI used when accessing a provenance service; following REST API style [[REST-APIs]], actual URIs for accessing provenance descriptions are obtained via the provenance service description.</td>
- <td>A provenance service description per <a href="#provenance-service-description" class="sectionRef"></a>. Alternative formats may be offered via HTTP content negotiation.</td>
+ <td>A provenance query service (i.e. a resource of type <code>prov:ProvenanceQueryService</code>). This is the initial URI used when accessing a provenance query service; following REST API style [[REST-APIs]], actual URIs for accessing provenance descriptions are determined via the query service description.</td>
+ <td>A provenance query service description per <a href="#provenance-query-service-description" class="sectionRef"></a>. Alternative formats may be offered via HTTP content negotiation.</td>
</tr>
<tr style="vertical-align: top;">
<td><a class="internalDFN">Pingback-URI</a></td>
@@ -367,13 +373,13 @@
</p>
<ol>
<li>Direct access: given a <a class="internalDFN">provenance-URI</a>, simply dereference it, and</li>
- <li>Indirectly via a service: given the URIs of some resource and a <a class="internalDFN">provenance service</a>, use the service to access provenance of the resource.</li>
+ <li>Indirectly via a query service: given the URIs of some resource (or maybe other information) and a <a class="internalDFN">provenance query service</a>, use the service to access provenance of the resource.</li>
</ol>
<p>
- Web applications may access provenance descriptions in the same way as any resource on the Web, by dereferencing its URI (commonly using an HTTP GET operation). Thus, any provenance description may be associated with a <a class="internalDFN">provenance-URI</a>, and may be accessed by dereferencing that URI using web mechanisms.
+ Web applications may access a provenance description in the same way as any resource on the Web, by dereferencing its URI (commonly using an HTTP GET operation). Thus, any provenance description may be associated with a <a class="internalDFN">provenance-URI</a>, and may be accessed by dereferencing that URI using web mechanisms.
</p>
<p>
- When there is no easy way to associate a provenance-URI with individual resources (e.g. for resources not directly web-accessible, or whose publication mechanism is controlled by someone else), one may provide provenance descriptions about multiple resources through a service interface. A REST protocol for provenance retrieval is defined in Section <a href="#provenance-services" class="sectionRef"></a>.
+ When there is no easy way to associate a provenance-URI with individual resources (e.g. for resources not directly web-accessible, or whose publication mechanism is controlled by someone else), one may provide provenance descriptions about multiple resources through a provenance query service. A REST protocol for provenance querying is defined in Section <a href="#provenance-query-services" class="sectionRef"></a>; also described there is a mechanism for locating a SPARQL query service.
</p>
<p>
How much or how little provenance is returned in response to a retrieval request is a matter for the provenance provider application.
@@ -393,7 +399,7 @@
<section>
<h2>Locating provenance descriptions</h2>
<p>
- If a <a class="internalDFN">provenance description</a> is a resource that can be accessed using web retrieval, one needs to know its <a class="internalDFN">provenance-URI</a> to dereference. If this is known in advance, there is nothing more to specify. If a provenance-URI is not known then a mechanism to discover one must be based on information that is available to the would-be accessor. Likewise, provenance descriptions may be exposed by a service, in which case, the <a class="internalDFN">service-URI</a> needs to be known.
+ If a <a class="internalDFN">provenance description</a> is a resource that can be accessed using web retrieval, one needs to know its <a class="internalDFN">provenance-URI</a> to dereference. If this is known in advance, there is nothing more to specify. If a provenance-URI is not known then a mechanism to discover one must be based on information that is available to the would-be accessor. Likewise, provenance descriptions may be exposed by a query service, in which case, the <a class="internalDFN">service-URI</a> needs to be known.
</p>
<p>
In the following, we refer to <a class="internalDFN">provider</a>s and <a class="internalDFN">consumer</a>s of provenance:
@@ -437,7 +443,7 @@
<p>
A <code>hasProvenance</code> link relation type for referencing a provenance description may be used thus:
</p>
- <pre class="pattern">Link: <cite>provenance-URI</cite>; rel="http://www.w3.org/ns/prov#hasProvenance"; anchor="<cite>target-URI</cite>"</pre>
+ <pre class="pattern">Link: <<cite>provenance-URI</cite>>; rel="http://www.w3.org/ns/prov#hasProvenance"; anchor="<cite>target-URI</cite>"</pre>
<p>When used in conjunction with an HTTP success response code (<code>2xx</code>), this HTTP header field indicates that <code><cite>provenance-URI</cite></code> is the URI of some provenance description about the originally requested resource, and that the requested resource is identified within the provenance description as <code><cite>target-URI</cite></code>. (See also <a href="#interpreting-provenance-descriptions" class="sectionRef"></a>.)</p>
<p>
If no <code>anchor</code> parameter is provided then the <code><cite>target-URI</cite></code> is assumed to be the URI of the requested resource used in the corresponding HTTP request.
@@ -449,21 +455,21 @@
An HTTP response MAY include multiple <code>hasProvenance</code> link header fields, indicating a number of different provenance resources that are known to the responding server, each presenting a provenance description about the accessed resource.
</p>
<p>
- The presence of a <code>hasProvenance</code> link in an HTTP response does not preclude the possibility that other publishers may offer provenance descriptions about the same resource. In such cases, discovery of the additional provenance descriptions must use other means (e.g. see <a href="#provenance-services" class="sectionRef"></a>).
+ The presence of a <code>hasProvenance</code> link in an HTTP response does not preclude the possibility that other publishers may offer provenance descriptions about the same resource. In such cases, discovery of the additional provenance descriptions must use other means (e.g. see <a href="#provenance-query-services" class="sectionRef"></a>).
</p>
<p>
Provenance indicated in this way is not guaranteed to be authoritative. Trust in the linked provenance descriptions must be determined separately from trust in the original resource. Just as in the web at large, it is a user's responsibility to determine an appropriate level of trust in any other linked resource; e.g. based on the domain that serves it, or an associated digital signature. (See also <a href="#security-considerations" class="sectionRef"></a>.)
</p>
<section>
- <h2>Specifying Provenance Services</h2>
+ <h2>Specifying Provenance Query Services</h2>
<p>
- The resource provider may indicate that provenance descriptions about the resource are provided by a <a class="internalDFN">provenance service</a>. This is done through the use of a <code>hasProvenanceService</code> link relation type following the same pattern as above:
+ The resource provider may indicate that provenance descriptions about the resource are provided by a <a class="internalDFN">provenance query service</a>. This is done through the use of a <code>hasProvenanceService</code> link relation type following the same pattern as above:
</p>
<pre class="pattern">
-Link: <cite>provenance-service-URI</cite>; rel="http://www.w3.org/ns/prov#hasProvenanceService"; anchor="<cite>target-URI</cite>"</pre>
+Link: <<cite>provenance-service-URI</cite>>; rel="http://www.w3.org/ns/prov#hasProvenanceService"; anchor="<cite>target-URI</cite>"</pre>
<p>
- The <code>hasProvenanceService</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 retrieve a <a class="internalDFN">provenance description</a> for a <a class="internalDFN">resource</a>; see <a href="#provenance-services" class="sectionRef"></a> for more details.
+ The <code>hasProvenanceService</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 description</a> for a <a class="internalDFN">resource</a>; see <a href="#provenance-query-services" class="sectionRef"></a> for more details.
</p>
<p>
There may be multiple <code>hasProvenanceService</code> link header fields, and these may appear in an HTTP response together with <code>hasProvenance</code> link header fields (though, in simple cases, we anticipate that <code>hasProvenance</code> and <code>hasProvenanceService</code> link relations will not be used together).
@@ -542,9 +548,9 @@
</p>
<section>
- <h2>Specifying Provenance Services</h2>
+ <h2>Specifying Provenance Query Services</h2>
<p>
- The document creator may specify that the provenance about the document is provided by a <a class="internalDFN">provenance service</a>. This is done through the use of a third link relation type following the same pattern as above:
+ The document creator may specify that the provenance about the document is provided by a <a class="internalDFN">provenance query service</a>. This is done through the use of a third link relation type following the same pattern as above:
</p>
<pre class="pattern">
<html xmlns="http://www.w3.org/1999/xhtml">
@@ -558,7 +564,7 @@
</body>
</html></pre>
<p>
- The <code>hasProvenanceService</code> link element identifies the <a class="internalDFN">service-URI</a>. Dereferencing this URI yields a service description that provides further information to enable a client to access <a class="internalDFN">provenance description</a> for a <a class="internalDFN">resource</a>; see <a href="#provenance-services" class="sectionRef"></a> for more details.
+ The <code>hasProvenanceService</code> link element identifies the <a class="internalDFN">service-URI</a>. Dereferencing this URI yields a service description that provides further information to enable a client to query for <a class="internalDFN">provenance description</a> for a <a class="internalDFN">resource</a>; see <a href="#provenance-query-services" class="sectionRef"></a> for more details.
</p>
<p>
There MAY be multiple <code>hasProvenanceService</code> link elements, and these MAY appear in the same document as <code>provenance</code> link elements (though, in simple cases, we anticipate that <code>hasProvenance</code> and <code>hasProvenanceService</code> link relations would not be used together).
@@ -588,7 +594,7 @@
<> dcterms:title "Welcome to example.com" ;
prov:hasAnchor <http://example.com/data/resource.rdf> ;
prov:hasProvenance <http://example.com/provenance/resource.rdf> ;
- prov:hasProvenanceService <http://example.com/provenance-service/> .
+ prov:hasProvenanceService <http://example.com/provenance-query-service/> .
:
(RDF data)
:
@@ -600,36 +606,150 @@
<!-- == Sect 4 =================================================================================== -->
<section>
- <h2>Provenance services</h2>
+ <h2>Provenance query services</h2>
<p>
- This section describes a REST-based protocol [[REST]] for provenance services with facilities for the retrieval of provenance descriptions. The protocol specifies HTTP operations for retrieving provenance descriptions from a provenance service. It follows the approach of the SPARQL Graph Store HTTP Protocol [[SPARQL-HTTP]].
+ This section describes a simple HTTP query protocol for accessing provenance descriptions, and also a mechanism for locating a SPARQL service endpoint. The HTTP protocol specifies HTTP operations for retrieving provenance descriptions from a provenance query service, following the approach of the SPARQL Graph Store HTTP Protocol [[SPARQL-HTTP]].
</p>
- <p>The introduction of this protocol is motivated by the following possible considerations: </p>
+ <p>The introduction of query services is motivated by the following possible considerations: </p>
<ul>
<li>the naming authority associated with the <a class="internalDFN">target-URI</a> is not the same as the service offering <a class="internalDFN">provenance description</a>s</li>
<li>multiple services have provenance descriptions about the same resource</li>
<li>the service associated with the target-URI is not accessible for adding additional information when handling retrieval requests</li>
- <li>there is no dereferencable <a class="internalDFN">provenance-URI</a> containing a provenance <a class="internalDFN"> for a particular resource</li>
- <li>provenance services may provide additional extensibility points for control over returned provenance.</li>
+ <li>there is no known dereferencable <a class="internalDFN">provenance-URI</a> returning a provenance for a particular resource</li>
+ <li>query services may provide additional control over what provenance is returned.</li>
</ul>
+ <p>
+ The query mechanisms provided by a <a class="internalDFN">provenance query service</a> are described by an RDF-format service description, which is obtained by dereferencing a <a class="internalDFN">service-URI</a>. A service description may contain information about additional mechanisms that are not described here. In keeping with REST practice, alternative non-RDF service description formats not described here may be offered and accessed using HTTP content negotiation, but such usage is not described here.
+ </p>
+ <p>
+ The general procedure for using a provenance query service is:
+ </p>
+ <ol>
+ <li>Retrieve the service description.</li>
+ <li>Within the service description, locate information about a recognized query mechanism. Any unrecognized descriptions should be ignored.</li>
+ <li>If a recognized query mechanism is described, extract information needed to use that mechanism (e.g. a URI template or a SPARQL service endpoint URI)</li>
+ <li>Use the information obtained to query for required provenance</li>
+ </ol>
+ <p>
+ The patterns for using provenance query services are designed around REST principles [[REST]], which aim to minimize coupling between client and server implementation details.
+ </p>
- <section>
- <h2>Provenance service invocation</h2>
- <div>This protocol combines the <a class="internalDFN">target-URI</a> with the <a class="internalDFN">service-URI</a> to formulate an HTTP GET request, according to the following convention:
+ <!-- <section class="informative"> -->
+ <section>
+ <h2>Provenance query service description</h2>
+ <p>
+ Dereferencing a provenance query service URI yields a service description. The service description should be available as RDF (in any of its common serializations as determined by HTTP content negotiation), and it should contain descriptions of one or more available query mechanisms. Each available query mechanism is associated with an RDF resource of a given type, as described below.
+ </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>
+ <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.
+ </p>
+
+ <section>
+ <h2>Direct HTTP query service</h2>
+ <p>A direct HTTP query service is described by an RDF resource of type <code>prov:ProvenanceQueryService</code></p>
+ <p>It allows for accessing provenance about a specified <a class="internalDFN">target-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 target-URI; e.g.</p>
+ <pre class="pattern">
+ @prefix prov: <http://www.w3c.org/ns/prov#>
+ <cite>query_option_node</cite> a prov:ProvenanceQueryService ;
+ prov:provenanceUriTemplate "<cite>service-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).
+ </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 description is obtained by expanding the URI template with the variable <cite><code>uri</code></cite> set to the target-URI for which provenance is required. In this example, if the target-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).
+ </p>
+ <p>
+ A provenance query service MAY recognize additional parameters encoded as part of a URI for the provenance description. 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:ProvenanceQueryService ;
+ 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>
+ <p>
+ (Note that in this case, a "level 3" URI template feature is used [[URI-template]].)
+ </p>
+ </section>
+
+ <section>
+ <h2>SPARQL query service</h2>
+ <p>
+ A SPARQL query service is described by an RDF resource of type <code>sd:Service</code> [[SPARQL-SD]].
+ </p>
+ <p>
+ It allows for accessing provenance information using a SPARQL query, which may be constructed to retrieve provenance for a particular entity, or for multiple entities. The query may be formulated using the PROVC-O vocabulary terms [[PROV-O]], and others supported by the SPARQL endpoint as appropriate.
+ </p>
+ <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>
+ <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).
+ </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>
+ <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>
+ </section>
+
+ <section>
+ <h2>Service description example</h2>
+ <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#>
+
+ <#direct> a prov:ProvenanceQueryService ;
+ 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>
+ </section>
+ </section>
+
+ <section>
+ <h2>Direct HTTP query service invocation</h2>
+ <p>This protocol typically combines the <a class="internalDFN">target-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/entity HTTP/1.1
Host: example.com</pre>
- </div>
- <div>The embedded target-URI (<code>http://www.example.com/entity</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 description 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]].
- </div>
- <p>
- If the provenance described by the request does not exist in the server, a 404 Not Found response code SHOULD be returned.
+ </p>
+ <p>The embedded target-URI (<code>http://www.example.com/entity</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 description 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>
- The format of the returned provenance description is not defined here, but may be established through content type negotiation using <code>Accept:</code> header fields in the HTTP request. A provenance service SHOULD be capable of returning RDF using the vocabulary defined by [[PROV-O]], in any standard RDF serialization (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.
+ If the provenance described by the request does not exist in the server, a <code>404 Not Found</code> response code SHOULD be returned.
</p>
<p>
- Additional URI query parameters may be used as indicated by the service description in <a href="#provenance-service-description" class="sectionRef"></a>.
+ The format of the returned provenance description 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 any standard RDF serialization (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.
+ </p>
+ <p>
+ Additional URI query parameters may be used as indicated by the service description in <a href="#provenance-query-service-description" class="sectionRef"></a>.
</p>
</section>
@@ -637,57 +757,19 @@
<section>
<h2>Provenance service discovery</h2>
<p>
- This specification does not define any specific mechanism for discovering provenance services. Applications may use any appropriate mechanism, including but not limited to: prior configuration, search engines, service registries, etc.
+ Previously, <a href="#locating-provenance-descriptions" 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:hasProvenanceService</code> and the provenance service type <code>prov:ProvenanceService</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:hasProvenanceService</code> and the provenance service type <code>prov:ProvenanceQueryService</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 service providing information about that dataset:
+ For example, a VoID description [[VoID]] of a dataset might indicate a provenance query service providing information about that dataset:
</p>
<pre class="pattern">
<http://example.org/dataset/> a void:Dataset ;
prov:hasProvenanceService <http://example.org/provenance/> .</pre>
<p>
- The RDF service description example below in <a href="#provenance-service-description" class="sectionRef"></a> shows use of the <code>prov:ProvenanceService</code> type.
- </p>
- </section>
-
- <!-- <section class="informative"> -->
- <section>
- <h2>Provenance service description</h2>
- <p>
- Dereferencing a provenance service URI should yield a provenance service description. This is to follow the constraints of [[REST-APIs]]. The provenance service description should be available as RDF (in any of its common serializations as determined by HTTP content negotiation), and it should contain RDF statements of the form:
- </p>
- <pre class="pattern">
- <<cite>service-URI</cite>> a prov:ProvenanceService ;
- prov:provenanceUriTemplate "<cite>service-URI</cite>?target={+uri}" .</pre>
- <p>
- where <cite><code>service-URI</code></cite> is the URI of the provenance service. Note that the object of the <code>prov:provenanceUriTemplate</code> statement is a literal text value, not a URI.
- </p>
- <p>
- A client should retrieve this service description and extract the associated value for <code>prov:provenance-URI-template</code>. This value is a string containing a URI template [[URI-template]] (level 2 or above). A URI for the desired provenance description is obtained by expanding the URI template with the variable <code>uri</code> set to the resource-URI for which provenance is required. If the target-URI contains '#' or '&' these must be %-escaped as <code>%23</code> or <code>%26</code> respectively before template expansion [[RFC3986]].
- </p>
- <p>
- A provenance service MAY recognize additional parameters encoded as part of a URI for the provenance description. If it does, it SHOULD include these in the provenance URI template in the service description, so that clients may know how a URI is formed using this additional information.
- For example, a 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>service-URI</cite>> a prov:ProvenanceService ;
- prov:provenanceUriTemplate "<cite>service-URI</cite>?target={+uri}{&steps}" .</pre>
- <p>
- which might result in an HTTP request for provenance looking 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>
- <p>
- Note that in this case, a "level 3" URI template feature is used [[URI-template]].
- </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 can be selected using HTTP content negotiation.
- </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 service implementers consider adopting it, or at least consider making their implementations compatible with it.
+ The RDF service description example in <a href="#provenance-query-service-description" class="sectionRef"></a> shows use of the <code>prov:ProvenanceQueryService</code> type.
</p>
</section>
@@ -813,8 +895,8 @@
<th>Name</th><th>Description</th><th>Definition ref</th>
</tr>
<tr style="vertical-align: top;">
- <td><code>ProvenanceService</code></td>
- <td>Class for a provenance service. Mainly for use in RDF provenance service descriptions, to facilitate discovery.</td>
+ <td><code>ProvenanceQueryService</code></td>
+ <td>Class for a provenance query service. Mainly for use in RDF provenance query service descriptions, to facilitate discovery.</td>
<td><a href="#provenance-service-description" class="sectionRef"></a></td>
</tr>
<tr style="vertical-align: top;">