--- a/paq/prov-aq.html Thu Apr 04 17:08:38 2013 +0100
+++ b/paq/prov-aq.html Fri Apr 05 14:17:29 2013 +0100
@@ -239,10 +239,12 @@
<li> <a href="http://www.w3.org/TR/2013/WD-prov-links-20130312/">PROV-LINKS</a> (To be published as Note) introduces a mechanism to link across bundles [[PROV-LINKS]].</li>
</ul>
+<!--
<h4>Third Public Working Draft</h4>
<p>
This is the third public working. This revision introduces a new definition of a provenance pingback service as well as making various clarifications about the definition of service descriptions and how they are retrieved.
</p>
+-->
</section>
@@ -348,7 +350,7 @@
In general, resources may vary over time and context. E.g., a resource describing the weather in London changes from day-to-day, or a listing of restaurants near you will vary depending on your location.
</p>
<p>
- Provenance records a history of the entities, activities, and people involved in producing an artifact, and may be collected from several sources at different times. In order to create a meaningful history, the individual provenance records used must remain valid and correct when interpreted in a context other than that in which they were collected.
+ Provenance records a history of the entities, activities, and people involved in producing an artifact, and may be collected from several sources at different times. In order to create a meaningful history, the individual provenance records used must retain their intended meaning when interpreted in a context other than that in which they were collected.
Yet we may still want to make provenance assertions about dynamic or context-dependent resources (e.g. a weather forecast for London on a particular day may have been derived from a particular set of Meteorological Office data).
</p>
<p>
@@ -385,6 +387,9 @@
<section>
<h2>URI types and dereferencing</h2>
+ <p class="TODO">
+ Proposed to drop Target-URI entry from this section.
+ </p>
<p>
A number of resource types are described above in <a href="#concepts" class="sectionRef"></a>. The table below summarizes what these various URIs are intended to denote, and the kind of information that should be returned if they are dereferenced:
</p>
@@ -473,9 +478,6 @@
</p>
<p>Provenance records may be offered by several <a class="internalDFN">provider</a>s other than that of the original resource publisher, each with different concerns, and presenting provenance at different locations. It is possible that these different providers may present contradictory provenance.
</p>
- <p class="note">
- The mechanisms used with HTTP and HTML/RDF are slightly inconsistent in their approach to specifying <code><cite>target-URI</cite></code> values. In HTTP <code>Link:</code> headers, an optional <code>anchor=</code> parameter may be supplied for each such header. In HTML and RDF, separate <code>#has_anchor</code> relations are defined. It was felt that avoiding reinvention of existing mechanisms was more important than being completely consistent. If anchors are processed as described in <a href="#interpreting-provenance-records" class="sectionRef"></a> (3rd paragraph), observable behaviour across all approaches should be consistent.
- </p>
<section>
<h2>Resource accessed by HTTP</h2>
@@ -506,14 +508,14 @@
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):
</p>
<pre class="example code">
- C: GET http://example.com/resource/ HTTP/1.1
+ C: GET http://example.com/resource123/ HTTP/1.1
C: Accept: text/html
S: HTTP/1.1 200 OK
S: Content-type: text/html
- S: Link: <http://example.com/resource/provenance/>;
+ S: Link: <http://example.com/resource123/provenance/>;
rel="http://www.w3.org/ns/prov#has_provenance";
- anchor="http://example.com/resource/"
+ anchor="http://example.com/resource123/"
S:
S: <html ...>
S: :
@@ -537,14 +539,14 @@
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/resource/ HTTP/1.1
+ C: GET http://example.com/resource123/ HTTP/1.1
C: Accept: text/html
S: HTTP/1.1 200 OK
S: Content-type: text/html
- S: Link: <http://example.com/resource/provenance/>;
+ S: Link: <http://example.com/resource123/provenance/>;
rel="http://www.w3.org/ns/prov#has_query_service";
- anchor="http://example.com/resource/"
+ anchor="http://example.com/resource123/"
S:
S: <html ...>
S: :
@@ -564,29 +566,32 @@
An example transaction using content negotiation and redirection 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/resource/ HTTP/1.1
+ C: GET http://example.com/resource123/ HTTP/1.1
C: Accept: text/html
S: HTTP/1.1 302 Found
- S: Location: /resource/content.html
+ S: Location: /resource123/content.html
S: Vary: Accept
S:
- S: HTML content for http://example.com/resource/
- S: is available at http://example.com/resource/content.html
+ S: HTML content for http://example.com/resource123/
+ S: is available at http://example.com/resource123/content.html
- C: GET http://example.com/resource/content.html HTTP/1.1
+ C: GET http://example.com/resource123/content.html HTTP/1.1
C: Accept: text/html
S: HTTP/1.1 200 OK
S: Content-type: text/html
- S: Link: <http://example.com/resource/provenance/>;
+ S: Link: <http://example.com/resource123/provenance/>;
rel="http://www.w3.org/ns/prov#has_provenance";
- anchor="http://example.com/resource/20130226/content.html"
+ anchor="http://example.com/resource123/20130226/content.html"
S:
S: <html>
S: <!-- HTML content here... -->
S: </html>
</pre>
+ <p>
+ This example indicates a provenance record at <code>http://example.com/resource123/provenance/</code>, which uses <code>http://example.com/resource123/20130226/content.html</code> as the target-URI for the requested resource. If the <code>anchor=</code> parameter were to be omitted from the <code>Link:</code> header, the indicated target-URI would be <code>http://example.com/resource123/content.html</code>.
+ </p>
</section>
</section>
@@ -621,6 +626,10 @@
An HTML document header MAY present multiple <code><cite>provenance-URI</cite></code>s over several <code>#has_provenance</code> link elements, indicating a number of different provenance records that are known to the publisher of the document, each of which may provide provenance about the document (see <a href="#interpreting-provenance-records" class="sectionRef"></a>).
</p>
+ <p class="note">
+ The mechanisms used with HTTP and HTML/RDF are slightly inconsistent in their approach to specifying <code><cite>target-URI</cite></code> values. In HTTP <code>Link:</code> headers, an optional <code>anchor=</code> parameter may be supplied for each such header. In HTML and RDF, separate <code>#has_anchor</code> relations are defined. It was felt that avoiding reinvention of existing mechanisms was more important than being completely consistent. If anchors are processed as described in <a href="#interpreting-provenance-records" class="sectionRef"></a> (3rd paragraph), observable behaviour across all approaches should be consistent.
+ </p>
+
<section>
<h2>Specifying Provenance Query Services</h2>
<p>
@@ -678,6 +687,8 @@
</p>
<p class="note">
These terms (<code>prov:has_provenance</code>, <code>prov:has_anchor</code>, and <code>prov:has_query_service</code>) may be also used in RDF statements with other subjects to indicate provenance of other resources, but discussion of such use is beyond the scope of this document.
+ <br/><br/>
+ See also the note about target-URIs at the end of <a href="#resource-represented-as-html" class="sectionRef"></a>.
</p>
</section>
@@ -775,7 +786,7 @@
<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 which the variable <cite><code>uri</code></cite> stands for the target-URI; e.g.</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>
<pre class="pattern">
@prefix prov: <http://www.w3c.org/ns/prov#>
<direct-query-description> a prov:DirectQueryService ;
@@ -940,7 +951,7 @@
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 additional provenance fall under the remit of "provenance access and query"? Is it a useful feature to define?
</p>
<p>
- This section describes a discovery mechanism for related provenance information that the publisher of a resource does not otherwise know about; e.g. provenance describing how it is used after it has been created.
+ This section describes a mechanism that may be used to discover related provenance information that the publisher of a resource does not otherwise know about; e.g. provenance describing how it is used after it has been created.
</p>
<p>
The mechanisms discussed in previous sections are primarily concerned with the publisher enabling access to known provenance about an entity, answering with questions such as:
@@ -970,7 +981,7 @@
<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:
</p>
- <pre class="pattern">
+ <pre class="example code">
C: GET http://acme.example.org/super-widget HTTP/1.1
S: 200 OK
@@ -981,7 +992,7 @@
:
(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 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
@@ -1007,7 +1018,37 @@
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>
- The client MAY further 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 the target-URI of the resource to which this pingback service belongs, or some related resource with relevant provenance.
+ 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.)
+ </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.
+ </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?
+ </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>;
+ 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
+
+ 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
@@ -1024,20 +1065,7 @@
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>has_provenance</code> links to specify provenance records with 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">
- Does this SHOULD requirement serve any useful purpose?
- </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.)
- </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.
+ 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).
</p>
<!-- also in Stian's proposal