--- a/paq/prov-aq.html Fri Apr 05 14:17:29 2013 +0100
+++ b/paq/prov-aq.html Fri Apr 05 18:10:22 2013 +0100
@@ -59,25 +59,25 @@
"PROV-DM":
"L. Moreau; P. Missier. "+
"<a href=\"http://www.w3.org/TR/prov-dm/\"><cite>The PROV Data Model and Abstract Syntax Notation</cite></a>. "+
- "2011, Work in progress. "+
+ "12 March 2013, W3C Proposed Recommendation. "+
"URL: <a href=\"http://www.w3.org/TR/prov-dm/\">http://www.w3.org/TR/prov-dm/</a>",
"PROV-O":
"S. Sahoo; D. McGuinness. "+
"<a href=\"http://www.w3.org/TR/prov-o/\"><cite>The PROV Ontology</cite></a>. "+
- "2011, Work in progress. "+
+ "12 March 2013, W3C Proposed Recommendation. "+
"URL: <a href=\"http://www.w3.org/TR/prov-o/\">http://www.w3.org/TR/prov-o/</a>",
"SPARQL-SD":
"G. T. Williams. "+
"<a href=\"http://www.w3.org/TR/sparql11-service-description/\"><cite>SPARQL 1.1 Service Description</cite></a>. "+
- "2011, Work in progress. "+
+ "21 March 2013, W3C Recommendation. "+
"URL: <a href=\"http://www.w3.org/TR/sparql11-service-description/\">http://www.w3.org/TR/sparql11-service-description/</a>",
"SPARQL-HTTP":
"Chimezie Ogbuji. "+
"<a href=\"http://www.w3.org/TR/sparql11-http-rdf-update/\"><cite>SPARQL 1.1 Graph Store HTTP Protocol</cite></a>. "+
- "W3C Candidate Recommendation 8 November 2012, "+
+ "21 March 2013, W3C Recommendation. "+
"URL: <a href=\"http://www.w3.org/TR/sparql11-http-rdf-update/\">http://www.w3.org/TR/sparql11-http-rdf-update/</a>",
"INFO-ACC":
@@ -275,6 +275,9 @@
<p>
For ease of reference, the main body of this document contains some links to external web pages. Such links are distinguished from internal references thus: <a href="http://www.w3.org/2011/prov/wiki/Main_Page" class="externalRef">W3C Provenance Working Group</a>.
</p>
+ <p>
+ This document is a W3C Note, not a formal W3C Specification. However, to clarify the description of intended behaviours, it does use the key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY and OPTIONAL as described in [[RFC2119]].
+ </p>
<section>
<h2>Concepts</h2>
@@ -366,16 +369,13 @@
<section>
<h2>Interpreting provenance records</h2>
- <p class="TODO">
- Review second para below.
- </p>
<p>
The mechanisms described in this document are intended to allow a provider to supply information that allows a consumer to access <a class="internalDFN">provenance record</a>s, which themselves explicitly identify the <a class="internalDFN" href="#dfn-entity">entities</a> they describe.
A provenance record may contain information about several entities, referring to them using their various <a class="internalDFN">target-URI</a>s.
Thus a consumer should be selective in its use of the information provided when interpreting a provenance record.
</p>
<p>
- A provenance record consumer will need to isolate information about the specific entity or entities of interest. These may be <a class="internalDFN">constrained resource</a>s identified by separate target-URIs than the original resource, in which case it will need to know about the target-URIs used. The mechanisms defined later allow a provider to expose such URIs.
+ A provenance record consumer will need to isolate information about the specific entity or entities of interest. These may be <a class="internalDFN">constrained resource</a>s identified by separate target-URIs that differ from the resource URI, in which case the consumer needs to discover those target-URIs. The mechanisms defined later allow a provider to expose such URIs.
</p>
<p>
While a provider should avoid giving spurious information, there are no fixed semantics, particularly when multiple resources are indicated, and a client should not assume that a specific given provenance-URI will yield information about a specific target-URI. In the general case, a client presented with multiple provenance-URIs and multiple target-URIs should look at all of the provenance-URIs for information about any or all of the target-URIs.
@@ -401,7 +401,7 @@
</tr>
<tr style="vertical-align: top;">
<td><a class="internalDFN">Target-URI</a></td>
- <td>Any resource that is described by some provenance - typically an <a class="externalRef" href="http://www.w3.org/TR/prov-dm/#section-entity-activity">entity</a> (in the sense of [[PROV-DM]], but may be an activity).</td>
+ <td>Any resource that is described by some provenance - typically an <a class="externalRef" href="http://www.w3.org/TR/prov-dm/#section-entity-activity">entity</a> (in the sense of [[PROV-DM]]), but may be of another type (such as [[PROV-DM]] activity).</td>
<td>If the URI is dereferencable, it should return a representation or description of the resource for which provenance is provided.</td>
</tr>
<tr style="vertical-align: top;">
@@ -496,16 +496,16 @@
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.
</p>
<p>
- This specification does not define the meaning of these links returned with other HTTP response codes: future revisions may define interpretations for these.
+ This note does not define the meaning of these links returned with other HTTP response codes: future revisions may define interpretations for these.
</p>
<p>
An HTTP response MAY include multiple <code>has_provenance</code> link header fields, indicating a number of different provenance resources (and anchors) that are known to the responding server, each referencing a provenance record about the accessed resource.
</p>
<p>
- The presence of a <code>has_provenance</code> link in an HTTP response does not preclude the possibility that other providers may offer provenance records about the same resource. In such cases, discovery of the additional provenance records must use other means (e.g. see <a href="#provenance-query-services" class="sectionRef"></a>).
+ The presence of a <code>has_provenance</code> link in an HTTP response does not preclude the possibility that other providers also may offer provenance records about the same resource. In such cases, discovery of the additional provenance records must use other means (e.g. see <a href="#provenance-query-services" class="sectionRef"></a>).
</p>
<p>
- An example request including provenance headers in its response might look like this (where <code>C:</code> and <code>S:</code> prefixes indicate client and server emitted data respectively):
+ An example HTTP response including provenance headers might look like this (where <code>C:</code> and <code>S:</code> prefixes indicate client and server emitted data respectively):
</p>
<pre class="example code">
C: GET http://example.com/resource123/ HTTP/1.1
@@ -536,7 +536,7 @@
The <code>has_query_service</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>
<p>
- There may be multiple <code>has_query_service</code> link header fields, and these MAY appear in an HTTP response together with <code>has_provenance</code> link header fields.
+ There MAY be multiple <code>has_query_service</code> link header fields, and these MAY appear in an HTTP response together with <code>has_provenance</code> link header fields.
</p>
<pre class="example code">
C: GET http://example.com/resource123/ HTTP/1.1
@@ -602,7 +602,7 @@
For a document presented as HTML or XHTML, without regard for how it has been obtained, a provenance record may be associated with a resource by adding a <code><link></code> element to the HTML <code><head></code> section.
Two link relation types for referencing provenance may be used:
<pre class="pattern">
- <html xmlns="http://www.w3.org/1999/xhtml">
+ <html>
<head>
<b><link rel="http://www.w3.org/ns/prov#has_provenance" href="<cite>provenance-URI</cite>"></b>
<b><link rel="http://www.w3.org/ns/prov#has_anchor" href="<cite>target-URI</cite>"></b>
@@ -785,37 +785,46 @@
<section>
<h2>Direct HTTP query service description</h2>
- <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">target-URI</a>. The query URI to use is described by a URI Template [[URI-template]] (level 2 or above) in which the variable <cite><code>uri</code></cite> stands for the target-URI; e.g.</p>
+ <p>
+ A direct HTTP query service is described by an RDF resource of type <code>prov:DirectQueryService</code>.
+ 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 the variable <cite><code>uri</code></cite> stands for the target-URI. The URI template is specified as:</p>
<pre class="pattern">
-@prefix prov: <http://www.w3c.org/ns/prov#>
<direct-query-description> a prov:DirectQueryService ;
- prov:provenanceUriTemplate "<cite>query-URI</cite>?target={+uri}" .
+ prov:provenanceUriTemplate "<cite>uri-template</cite>" .
</pre>
<p>
- 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).
+ where <code><cite>direct-query-description</cite></code> is any distinct RDF subject node (i.e. a blank node or a URI), and <code><cite>uri-template</cite></code> is a URI template [[RFC3986]].
</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 target-URI for which provenance is requested. 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>
+ <pre class="example code">
+<http://example.com/prov/service> a prov:ServiceDescription;
+ prov:describesService _:direct .
+
+_:direct a prov:DirectQueryService ;
+ prov:provenanceUriTemplate
+ "http://www.example.com/provenance/service?target={uri}" .
+</pre>
<p>
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 a target, or to also supply provenance of other resources from which the target 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="example code">
-<<cite>direct-query-description</cite>> a prov:DirectQueryService ;
+<http://example.com/prov/service> a prov:ServiceDescription;
+ prov:describesService _:direct .
+
+_:direct 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="example code">
-GET http://example.com/provenance/service?<b>target</b>=http://www.example.com/entity&<b>steps</b>=2 HTTP/1.1
+ "http://www.example.com/provenance/service?target={uri}{&steps}" .
</pre>
<p>
(Note that in this case, a "level 3" URI template feature is used [[URI-template]].)
</p>
+ <p>
+ Section <a href="#direct-http-query-service-invocation" class="sectionRef"></a> discusses how a client interacts with a direct HTTP query service.
+ </p>
+
</section>
<section>
@@ -830,20 +839,19 @@
The SPARQL query service description is constructed as defined by <cite>SPARQL 1.1 Service Description</cite> [[SPARQL-SD]]; e.g.
</p>
<pre class="example code">
-<cite>sparql-query-description</cite> a sd:Service ;
- sd:endpoint <<cite>query-URI</cite>/sparql/> ;
+<http://example.com/prov/service> a prov:ServiceDescription;
+ prov:describesService _:sparql .
+
+_:sparql a sd:Service ;
+ sd:endpoint <http://www.example.com/provenance/sparql> ;
sd:supportedLanguage sd:SPARQL11Query .
</pre>
<p>
- 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).
+ where <code>http://www.example.com/provenance/sparql</code> is the URI of a provenance query SPARQL endpoint.
</p>
<p>
- The SPARQL service description may be detailed or sparse, provided that it includes at a minimum the following:
+ The SPARQL service description may be detailed or sparse, provided that it includes at least a <code>sd:endpoint</code> statement with the SPARQL service endpoint URI.
</p>
- <pre class="pattern">
-<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>
@@ -855,10 +863,10 @@
The following service description example uses Turtle [[TURTLE]] syntax to describe both direct HTTP and SPARQL query services:
</p>
<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#>
+@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#> .
<> a prov:ServiceDescription ;
prov:describesService <#direct>, <#sparql> ;
@@ -890,26 +898,28 @@
<section>
<h2>Direct HTTP query service invocation</h2>
<p>
- This protocol combines the <a class="internalDFN">target-URI</a> with a supplied URI template to formulate an HTTP GET request.
+ This section describes the interaction between a client and a direct HTTP query service whose service description is as presented in <a href="#direct-http-query-service-description" class="sectionRef"></a>, once the service description has been analyzed and its URI template has been extracted.
</p>
<p>
- Thus, if the URI template extracted from the service description is <code>http://example.com/provenance/service?target={uri}</code> and the supplied target-URI is <code>http://www.example.com/entity123</code>, the resulting HTTP request would be:</p>
+ The <a class="internalDFN">target-URI</a> for which provenance is required is used in the expansion of the supplied URI template [[RFC3986]] to formulate an HTTP GET request.
+ </p>
+ <p>
+ Thus, in the first service description example in <a href="#direct-http-query-service-description" class="sectionRef"></a>, the URI template is <code>http://www.example.com/provenance/service?target={uri}</code>. If the supplied target-URI is <code>http://www.example.com/entity123</code>, this would be used as the value for variable <code>uri</code> when expanding the template. The resulting HTTP request used to retrieve a provenance record would be:</p>
<pre class="example code">
GET /provenance/service?<b>target</b>=http%3A%2F%2Fwww.example.com%2Fentity123 HTTP/1.1
Host: example.com
</pre>
-
<p>
- Any server that implements this protocol and receives a request URI in this form SHOULD return a provenance record for the target-URI embedded in the query component, where that URI is the result of percent-decoding [[RFC3986]] the part of the request URI corresponding to <code>{var}</code> in the URI template. E.g., in the above example, the decoded target-URI is <code>http://www.example.com/entity123</code>. The target-URI MUST be an absolute URI, and the server SHOULD respond with <code>400 Bad Request</code> if it is not.
+ Any server that implements this protocol and receives a request URI in a form corresponding to its published URI template SHOULD return a provenance record for the embedded target-URI. The target-URI is obtained by percent-decoding [[RFC3986]] the part of the request URI corresponding to occurrences of the variable <code>uri</code> in the URI template. E.g., in the above example, the decoded target-URI is <code>http://www.example.com/entity123</code>. The target-URI MUST be an absolute URI, and the server SHOULD respond with <code>400 Bad Request</code> if it is not.
</p>
<p>
A server SHOULD NOT offer a template containing <code>{+uri}</code> or other non-simple variable expansion options [[URI-template]] unless all valid target-URIs for which it can provide provenance do not contain problematic characters like <code>'#'</code> or <code>'&'</code>.
</p>
<p class="note">
- The defined URI template expansion process [[URI-template]] generally takes care of %-escaping characters that are not permitted in URIs. However, when expanding a template with <code>{+uri}</code>, some permitted characters such as <code>'#'</code> and <code>'&'</code> are not escaped. If the supplied target-URI contains these characters, then they may disrupt interpretation of the resulting query URI. To prevent this, <code>'#'</code> and <code>'&'</code> characters in the target-URI may be replaced with <code>%23</code> and <code>%26</code> respectively, before performing the URI template expansion. An alternative, simpler and more reliable approach is to use <code>{uri}</code> in the URI template string, which will cause all URI-reserved characters to be %-escaped as part of the URI-template expansion, as in the example above.
+ The defined URI template expansion process [[URI-template]] generally takes care of %-escaping characters that are not permitted in URIs. However, when expanding a template with <code>{+uri}</code> (or other non-simple variable expansion options), some permitted characters such as <code>'#'</code> and <code>'&'</code> are not escaped. If the supplied target-URI contains these characters, then they may disrupt interpretation of the resulting query URI. A generally more reliable approach is to use <code>{uri}</code> in the URI template string, which will cause all URI-reserved characters to be %-escaped as part of the URI-template expansion, as in the example above.
</p>
<p>
- If the provenance described by the request is unknown to 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 or sensitive, an authorization failure or other error response may be returned.
+ If the provenance described by the request is unknown to 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 or sensitive, an authorization failure or other response may be returned.
</p>
<p>
The direct HTTP query service may return provenance in any available format.
@@ -917,7 +927,13 @@
Services MUST identify the <code>Content-Type</code> of the provenance returned.
</p>
<p>
- Additional URI query parameters may be used as indicated by the service description in <a href="#direct-http-query-service-description" class="sectionRef"></a>.
+ Additional URI query parameters may be used as indicated by the service description in <a href="#direct-http-query-service-description" class="sectionRef"></a>. The second service description example specifies a URI template with an additional variable which may be used to control the scope of provenance information returned: <code>http://www.example.com/provenance/service?target={+uri}{&steps}</code>. Following [[RFC3986]], if no value for variable <code>steps</code> is provided when expanding the template, this extra element is effectively ignored. But if a <code>steps</code> value of (say) <code>2</code> is provided, then the resulting HTTP query would be:
+ </p>
+ <pre class="example code">
+GET http://example.com/provenance/service?<b>target</b>=http://www.example.com/entity&<b>steps</b>=2 HTTP/1.1
+</pre>
+ <p class="note">
+ The use of any specific URI template variable other than <code>uri</code> for the target-URI is a matter for agreement between the client and query service, and is not specified in this note. It is mentioned here simply to show that the possibility exists to formulate more detailed queries.
</p>
</section>
@@ -970,89 +986,71 @@
<li>what has this resource been used for?</li>
<li>who has used it?</li>
<li>what other resources are derived from the same sources as this resource?
- <li><i>etc.</i></li>
</ul>
<p>
- The ability to answer such broader questions requires some cooperation among the parties who use a resource; for example, a consumer could report use directly to the publisher, or a search engine could discover and report downstream resource usage. To facilitate such cooperation, a resource publisher may receive "ping-back"s.
+ The ability to answer such broader questions requires some cooperation among the parties who use a resource; for example, a consumer could report use directly to the publisher, or a search engine could discover and report downstream resource usage. To facilitate such cooperation, a resource publisher may receive provenance "ping-backs". (The mechanism described here is
+inspired by <a href="http://www.hixie.ch/specs/pingback/pingback" class="externalRef">blog pingbacks</a>, but avoids the need for XML-RPC and is specific for provenance records.)
</p>
<p>
- A resource may have an associated "ping-back" URI, which may be presented with references to provenance about the resource. The ping-back URI is associated with a resource using mechanisms similar to those used for presenting a <a class="internalDFN">provenance-URI</a>, but using a <code>pingback</code> link relation instead of <code>has_provenance</code>. A consumer of the resource, or some other system, may perform an HTTP POST operation to the pingback URI, with a request body containing a list of provenance-URIs for provenance records describing uses of the resource.
+ A resource may have an associated provenance ping-back URI, which may be presented with references to provenance about the resource. The ping-back URI is associated with a resource using mechanisms similar to those used for presenting a <a class="internalDFN">provenance-URI</a>, but using a <code>prov:pingback</code> link relation instead of <code>prov:has_provenance</code>. A consumer of the resource, or some other system, may perform an HTTP POST operation to the pingback URI, with a request body containing a list of provenance-URIs for provenance records describing uses of the resource.
</p>
<p>
- For example, consider a resource that is published by <code>acme.example.com</code>, and is subsequently used by <code>wile-e.example.org</code> in the construction of some new entity; we might see an exchange along the following lines. We start with <code>wile-e.example.org</code> retrieving a copy of <code>acme.example.org</code>'s resource:
+ For example, consider a resource that is published by <code>acme.example.com</code>, and is subsequently used by <code>coyote.example.org</code> in the construction of some new entity; we might see an exchange along the following lines. We start with <code>coyote.example.org</code> retrieving a copy of <code>acme.example.org</code>'s resource:
</p>
<pre class="example code">
C: GET http://acme.example.org/super-widget HTTP/1.1
S: 200 OK
S: Link: <http://acme.example.org/super-widget/provenance>;
- rel=http://www.w3.org/ns/prov#has_provenance
+ rel="http://www.w3.org/ns/prov#has_provenance"
S: Link: <http://acme.example.org/super-widget/pingback>;
- rel=http://www.w3.org/ns/prov#pingback
+ rel="http://www.w3.org/ns/prov#pingback"
:
(super-widget resource data)</pre>
<p>
- The first of the links in the response is a <code>has_provenance</code> link with a <a class="internalDFN">provenance-URI</a> that has been described previously (<a href="#resource-accessed-by-http" class="sectionRef"></a>). The second is a distinct resource that exists to receive provenance pingbacks. Later, when a new resource has been created or some related action performed based upon the <code>acme.example.org/super-widget</code>, a client MAY post a pingback request to any supplied <code>pingback</code> URI:
+ The first of the links in the response is a <code>has_provenance</code> link with a <a class="internalDFN">provenance-URI</a> that has been described previously (<a href="#resource-accessed-by-http" class="sectionRef"></a>). The second is a distinct resource that exists to receive provenance pingbacks. Later, when a new resource has been created or some related action performed based upon the <code>acme.example.org/super-widget</code>, a client may post a pingback request to any supplied <code>pingback</code> URI:
</p>
<pre class="example code">
C: POST http://acme.example.org/super-widget/pingback HTTP/1.1
C: Content-Type: text/uri-list
C:
- C: http://wile-e.example.org/contraption/provenance
- C: http://wile-e.example.org/another/provenance
+ C: http://coyote.example.org/contraption/provenance
+ C: http://coyote.example.org/another/provenance
S: 204 No Content
- S: Link: <http://acme.example.org/super-widget/provenance>;
- rel=http://www.w3.org/ns/prov#has_provenance;
- anchor="http://acme.example.org/super-widget"
</pre>
- <!--
- S: Link: <http://wile-e.example.org/contraption/provenance>;
- rel=http://www.w3.org/ns/prov#has_provenance;
- anchor=http://acme.example.org/super-widget
- S: Link: <http://wile-e.example.org/another/provenance>;
- rel=http://www.w3.org/ns/prov#has_provenance;
- anchor=http://acme.example.org/super-widget
- -->
<p>
The pingback request supplies a list of <a class="internalDFN">provenance-URI</a>s from which additional provenance may be retrieved. The pingback service may do as it chooses with these URIs; e.g., it may choose to save them for later use, to retrieve the associated provenance and save that, to publish the URIs along with other provenance information about the original entity to which they relate, or even to ignore them.
</p>
<p>
There is no required information in the server response to a pingback POST request.
- In the examples above, the pingback service responds with an empty response body, and links to provenance for the original resource.
- (Note that the <code>Link:</code> header returned contains an explicit <code>anchor</code> parameter with the URI of the original resource; without this, the link would relate the indicated URI to the pingback URI <code>http://acme.example.org/super-widget/pingback</code> rather than the original resource.)
+ In the examples here, the pingback service responds positively with <code>204 No Content</code> and an empty response body. Other HTTP status values like <code>200 OK</code>, <code>201 Created</code>, <code>202 Accepted</code>, and <code>303 See Other</code> might also be appropriate positive responses depending on the domain and application.
</p>
<p>
- The only defined operation on a pingback-URI is POST, which supplies links to provenance information or services as described above. A pingback-URI MAY respond to other requests, but no requirements are imposed on how it responds. In particular, it is not specified here how a pingback resource should respond to an HTTP GET request. This leaves open a possibility that the pingback resource MAY have the same URI as the original resource, provided that the original does not respond to POST in some different way.
+ The only defined operation on a pingback-URI is POST, which supplies links to provenance information or services as described above. A pingback-URI MAY respond to other requests, but no requirements are imposed on how it responds. In particular, it is not specified here how a pingback resource should respond to an HTTP GET request.
</p>
<p>
- The pingback client MAY include extra <code>has_provenance</code> links to indicate provenance records related to a different resources, specified with a correspondingly different anchor URIs. The provenance-URIs of those headers SHOULD also be included in the content if the POSTed Content-type is <code>text/uri-list</code>. For example:
- </p>
- <p class="TODO">
- Does this SHOULD requirement serve any useful purpose?
+ The pingback client MAY include extra <code>has_provenance</code> links to indicate provenance records related to a different resources, specified with correspondingly different anchor URIs. For example:
</p>
<pre class="example code">
C: POST http://acme.example.org/super-widget/pingback HTTP/1.1
- C: Link: <http://wile-e.example.org/extra/provenance>;
+ C: Link: <http://coyote.example.org/extra/provenance>;
rel="http://www.w3.org/ns/prov#has_provenance";
anchor="http://acme.example.org/extra-widget"
C: Content-Type: text/uri-list
C:
- C: http://wile-e.example.org/contraption/provenance
- C: http://wile-e.example.org/another/provenance
- C: http://wile-e.example.org/extra/provenance
+ C: http://coyote.example.org/contraption/provenance
+ C: http://coyote.example.org/another/provenance
+ C: http://coyote.example.org/extra/provenance
S: 204 No Content
- S: Link: <http://acme.example.org/super-widget/provenance>;
- rel=http://www.w3.org/ns/prov#has_provenance;
- anchor="http://acme.example.org/super-widget"
</pre>
<p>
The client MAY also supply <code>has_query_service</code> links indicating provenance query services that can describe the target-URI. The anchor MUST be included, and SHOULD be either the target-URI of the resource for which the pingback URI was provided (from the examples above, that would be <code>http://acme.example.org/super-widget</code>), or some related resource with relevant provenance. For example:
</p>
<pre class="example code">
C: POST http://acme.example.org/super-widget/pingback HTTP/1.1
- C: Link: <http://wile-e.example.org/sparql>;
+ C: Link: <http://coyote.example.org/sparql>;
rel="http://www.w3.org/ns/prov#has_query_service";
anchor="http://acme.example.org/super-widget"
C: Content-Type: text/uri-list
@@ -1060,9 +1058,6 @@
C:
S: 204 No Content
- S: Link: <http://acme.example.org/super-widget/provenance>;
- rel=http://www.w3.org/ns/prov#has_provenance;
- anchor="http://acme.example.org/super-widget"
</pre>
<p>
Here, the pingback client has supplied a query service URI, but did not submit any provenance-URIs and the URI list is therefore empty. The <code>Link:</code> header indicates that the resource <code>http://acme.example.org/super-widget/provenance</code> contains provenance information relating to <code>http://acme.example.org/super-widget</code> (that being the URI of the resource for which the pingback URI was provided).
@@ -1123,13 +1118,16 @@
Provenance is central to establishing trust in data. If provenance is corrupted, it may lead agents (human or software) to draw inappropriate and possibly harmful conclusions. Therefore, care is needed to ensure that the integrity of provenance is maintained. Just as provenance can help determine a level of trust in some information, a provenance record related to the provenance itself ("provenance of provenance") can help determine trust in the provenance.
</p>
<p>
+ The <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html" class="externalRef">HTTP security considerations</a> [[HTTP11]] generally apply for all of the resources and services located through the mechanism in this document.
+ </p>
+ <p>
Secure HTTP (https) SHOULD be used across unsecured networks when accessing provenance that may be used as a basis for trust decisions, or to obtain a provenance URI for same.
</p>
<p>
When retrieving a provenance URI from a document, steps SHOULD be taken to ensure the document itself is an accurate copy of the original whose author is being trusted (e.g. signature checking, or use of a trusted secure web service). (See also <a class="sectionRef" href="#interpreting-provenance-records"></a>.)
</p>
<p>
- Provenance may present a route for leakage of privacy-related information, combining as it does a diversity of information types with possible personally-identifying information; e.g. editing timestamps may provide clues to the working patterns of document editors, or derivation traces might indicate access to sensitive materials. In particular, note that the fact that a resource is openly accessible does not mean that its provenance should also be. When publishing provenance, its sensitivity SHOULD be considered and appropriate access controls applied where necessary. When a provenance-aware publishing service accepts some resource for publication, the contributors SHOULD have some opportunity to review and correct or conceal any provenance that they don't wish to be exposed. Provenance management systems SHOULD embody mechanisms for enforcement and auditing of privacy policies as they apply to provenance.
+ Provenance may present a route for leakage of privacy-related information, combining as it does a diversity of information types with possible personally-identifying information; e.g. editing timestamps may provide clues to the working patterns of document editors, or derivation traces might indicate access to sensitive materials. In particular, note that the fact that a resource is openly accessible does not mean that its provenance should also be. When publishing provenance, its sensitivity SHOULD be considered and appropriate access controls applied where necessary. When a provenance-aware publishing service accepts some resource for publication, the contributors SHOULD have some opportunity to review and correct or conceal any provenance that they don't wish to be exposed. Provenance management systems SHOULD embody mechanisms for enforcement and auditing of privacy policies as they apply to provenance. Implementations MAY choose to use standard HTTP authorization mechanisms to restrict access to resources, returning <code>401 Unauthorized</code>, <code>403 Forbidden</code> or <code>404 Not Found</code> as appropriate.
</p>
<p>Provenance may be used by audits to establish accountability for information use [[INFO-ACC]] and to verify use of proper processes in information processing activities. Thus, provenance management systems can provide mechanisms to support auditing and enforcement of information handling policies. In such cases, provenance itself may be a valuable target for attack by malicious agents, and care must be taken to ensure it is stored securely and in a fashion that resists attempts to tamper with it.
</p>
@@ -1139,8 +1137,8 @@
<p>
When clients and servers are retrieving submitted URIs such as provenance descriptions and following or registering links; reasonable care should be taken to prevent malicious use such as distributed denial of service attacks (DDoS), cross-site request forgery (CSRF), spamming and hosting of inappropriate materials. Reasonable preventions might include same-origin policy, HTTP authorization, SSL, rate-limiting, spam filters, moderation queues, user acknowledgements and validation. It is out of scope for this document to specify how such mechanisms work and should be applied.
</p>
- <p class="TODO">
- Is CSRF a real threat here? How?
+ <p>
+ Provenance pingback uses an HTTP POST operation, which may be used for non-"safe" interactions in the sense of [[WEBARCH]] (<a href="http://www.w3.org/TR/2004/REC-webarch-20041215/#safe-interaction" class="externalRef">section 3.4</a>). Care needs to be taken that user agents are not tricked into POSTing to incorrect URIs in such a way that may incur unintended effects or obligations. For example, a malicious site may present a pingback URI that executes an instruction on a different web site. Risks of such abuse may be mitigated by: performing pingbacks only to URIs from trusted sources; performing pingbacks only to the same origin as the provider of the pingback URI (like in-browser javascript same-origin restrictions), not sending credentials with pingback requests that were not obtained specifically for that purpose, and other measures rthat may be appropriate.
</p>
<p>Accessing provenance services might reveal to the service and third-parties information which is considered private, including which resources a client has taken interest in. For instance, a browser extension which collects all provenance data for a resource which is being saved to the local disk, could be revealing user interest in a sensitive resource to a third-party site listed by <code>prov:has_provenance</code> or <code>prov:has_query_service</code> relation. A detailed query submitted to a third-party provenance query service might be revealing personal information such as social security numbers. Accordingly, user agents in particular SHOULD NOT follow provenance and provenance service links without first obtaining the user's explicit permission to do so.
</p>