--- a/paq/prov-aq.html Tue Feb 26 17:19:41 2013 +0000
+++ b/paq/prov-aq.html Tue Feb 26 18:12:07 2013 +0000
@@ -306,9 +306,13 @@
<dd>
the URI of a <a class="internalDFN">provenance query service</a>.
</dd>
+ <dt><a href="#dfn-forward-provenance"><dfn>Forward provenance</dfn></a></dt>
+ <dd>
+ provenance describing how a resource is used after it has been created
+ </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 (i.e. provenance describing how a resource is used after it has been created).
+ the URI of a provenance pingback service that can receive references to <a class="internalDFN">forward provenance</a>.
</dd>
<dt><a href="#dfn-accessing"><dfn>Accessing</dfn></a> provenance records</dt>
<dd>
@@ -955,8 +959,14 @@
<section>
<h2>Forward provenance</h2>
+ <p class="TODO">
+ REVIEW. This section describes an "at-risk" feature whose final inclusion in this document is undecided. Does the use of a "ping-back" for discovering forward provenance fall under the remit of "provenance access and query"? Is it a useful feature to define?
+ </p>
<p>
- The mechanisms discussed in previous sections are primarily concerned with how consumers access historical provenance from publishers, dealing with questions such as:
+ This section describes a discovery mechanism for <a href class="internalDFN">forward provenance</a>; i.e. provenance describing how a resource is used after it has been created .
+ </p>
+ <p>
+ The mechanisms discussed in previous sections are primarily concerned with access to historical provenance, dealing with questions such as:
</p>
<ul>
<li>what was this resource based upon?</li>
@@ -974,13 +984,13 @@
<li><i>etc.</i></li>
</ul>
<p>
- The ability to answer forward-looking 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 such downstream resource usage. To facilitate such cooperation, a publisher may implement a "ping-back" capability.
+ The ability to answer forward-looking 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 such downstream resource usage. To facilitate such cooperation, a publisher of a resource may implement a "ping-back" capability.
</p>
<p>
A resource may have an associated "ping-back" URI which can be presented with PROV assertions 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>hasProvenance</code>. A consumer of the resource, or some other system, may perform an HTTP POST operation to the pingback URI where the POST request body contains provenance in one of the recognized provenance formats. For interoperability, a ping-back receiving service SHOULD be able to accept at least PROV-O provenance presented as RDF/XML or Turtle.
</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 wile-e.example.org retrieving a copy of acme.example.org's resource:
+ 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:
</p>
<pre class="pattern">
C: GET /super-widget HTTP/1.1
@@ -994,35 +1004,119 @@
:
(super-widget resource data)</pre>
<p>
- The first of the links in the response is a <code>hasProvenance</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 action performed based upon the <code>acme.example.org/super-widget</code>, new provenance may be submitted to the pingback thus:
+ The first of the links in the response is a <code>hasProvenance</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 action performed based upon the <code>acme.example.org/super-widget</code>, a client MAY post a pingback request to any supplied <code>prov:pingback</code> URI:
</p>
- <pre class="pattern">
+ <pre class="example code">
C: POST /pingback/super-widget HTTP/1.1
C: Host: acme.example.org
- C: Content-type: text/turtle
- :
+ C: Content-Type: text/uri-list
C:
- C: <http://wile-e.example.org/contraption>
- C: prov:wasDerivedFrom <http://acme.example.org/super-widget> .
+ C: http://wile-e.example.org/contraption/provenance
+ C: http://wile-e.example.org/another/provenance
- S: 200 OK
+ S: 204 No Content
S: Link: <http://acme.example.org/provenance/super-widget>;
rel=http://www.w3.org/ns/prov#hasProvenance;
anchor="http://acme.example.org/super-widget"
- S: Link: <http://acme.example.org/pingback/super-widget>;
- rel=http://www.w3.org/ns/prov#pingback;
- anchor="http://acme.example.org/super-widget"</pre>
+</pre>
+
<p class="TODO">
Details to change with Stian's proposal
+ <br/>
+ Stian suggests also returning the following information - I agree it's an option for the server, but I'm not sure if this should be included here:
+ <br/>
+ <code><pre>
+ S: Link: <http://wile-e.example.org/contraption/provenance>;
+ rel=http://www.w3.org/ns/prov#hasProvenance;
+ anchor=http://acme.example.org/super-widget
+ S: Link: <http://wile-e.example.org/another/provenance>;
+ rel=http://www.w3.org/ns/prov#hasProvenance;
+ anchor=http://acme.example.org/super-widget
+ </pre></code>
+ </p>
+ <p class="TODO">
+ <br/>
+ </p>
+ <p>
+ The pingback requests contains a list of <a class="internalDFN">provenance-URI</a>s from which forward 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, or to publish the URIs along with other provenance information about the original entity to which they relate.
+ </p>
+ <p>The client MAY supply <code>#hasQueryService</code> <code>Link:</code> headers that indicate services which can describe the target-URI. The anchor MUST be included, and SHOULD be the target-URI of the resource which this pingback service belongs to, unless the submitted query service would expect a different target-URI to describe the given resource.
+ </p>
+ <pre class="example code">
+ C: POST http://acme.example.org/pingback/super-widget HTTP/1.1
+ C: Link: <http://wile-e.example.org/sparql>;
+ rel="http://www.w3.org/ns/prov#hasQueryService";
+ anchor="http://acme.example.org/pingback/super-widget"
+ C: Content-Type: text/uri-list
+ C: Content-Length: 0
+ C:
+
+ S: 204 No Content
+ S: Link: <http://acme.example.org/provenance/super-widget>;
+ rel=http://www.w3.org/ns/prov#hasProvenance;
+ anchor="http://acme.example.org/super-widget"
+</pre>
+ <p>
+ In the above example, the client did not submit any provenance-URIs and the URI list is therefore empty.
+ </p>
+ <p>The client MAY similarly include <code>#hasProvenance</code> <code>Link:</code> headers to specify a different anchor. The provenance-URIs of those headers SHOULD also be included in the content if the POSTed Content-Type is <code>text/uri-list</code>.
+ </p>
+ <p class="TODO">
+ I've downplayed MUST to SHOULD in the last. If the content is empty, should the Content-type be omitted? (see example above). I would be inclined to makje it optional, and omit it from the example.
</p>
<p>
There is no required information in the server response to a pingback POST request.
- In this example the pingback service responds with links to provenance and pingback for the original resource (note that the <code>Link:</code> headers returned contain explicit <code>anchor</code> parameters with the URI of the original resource; without these, the links would relate the indicated URIs to the POST request URI <code>http://acme.example.org/pingback/super-widget</code>).
+ 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 explicit <code>anchor</code> parameters with the URI of the original resource; without this, the links would relate the indicated URIs to the pingback URI <code>http://acme.example.org/pingback/super-widget</code>).
</p>
<p>
- The only defined operation for a pingback resource is a POST, which provides a PROV assertion about the original resource with which it is associated. A pingback service MAY respond to other requests, but no requirements are imposed on how it responds to such operations. 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 provides 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.
</p>
+ <!-- also in Stian's proposal
+
+ The pingback service MAY resolve the submitted URIs to validate and
+ check the provenance data, however reasonable care should be taken to
+ prevent malicious use of the pingback service for attacks such as
+ distributed denial of service (DDoS) and cross-site request forgery
+ (CSRF).
+
+ The server MAY, immediately or at a later time, include the submitted
+ *provenance-URI*s in responses to subsequent request to the provenance
+ service for the target-URI. (insert usual blurb about not trust on
+ such provenance)
+
+ The server SHOULD include a self-referential prov:pingback Link
+ header, which MUST include the anchor for the target-URI this pingback
+ service corresponds to. This serves the purpose for the client to
+ verify it has submitted a pingback to the correct service, in case it
+ has followed an untrusted prov:pingback Link header. The client MAY
+ for this purpose POST an empty text/uri-list to avoid side effects.
+
+ The server SHOULD indicate immediate acceptance by including the
+ corresponding {prov:hasProvenance} {Link} headers for the accepted
+ *provenance-URI*s. If all submitted provenance-URIs have been
+ immediately accepted, the server SHOULD respond with HTTP status {200
+ OK} or {204 No Content}.
+
+ If server acceptance is pending for any of the submitted URIs, for
+ instance because the provenance-URIs are being validated or due to be
+ approved by a moderator, the server SHOULD respond with HTTP status
+ {202 Accepted}, and only include corresponding {prov:hasProvenance}
+ {Link} headers for those provenance-URIs that have been immediately
+ accepted.
+
+ The server MAY respond with {401 Unauthorized} and standard
+ {{WWW-Authenticate}} headers if authentication is needed. The server
+ SHOULD respond with {403 Forbidden} if for any reason it refuses to
+ accept one or more of the submitted provenance-URIs or
+ provenance-service-URIs. If some URIs were accepted, but others were
+ refused, the server SHOULD respond with {403 Forbidden} and include
+ generated prov:hasProvenance and prov:hasQueryService Link headers for
+ the immediately accepted URIs.
+
+ -->
+
+
</section>
<!-- ==== Section 6 ===================================================================================== -->