--- a/paq/provenance-access.html Thu Sep 01 13:45:57 2011 +0100
+++ b/paq/provenance-access.html Thu Sep 01 14:50:35 2011 +0100
@@ -182,7 +182,7 @@
This specification thus recommends that if a publisher wishes to make <a class="internalDFN">provenance information</a> available, it is published as a normal web resource, and provision is made for the <a class="internalDFN">provenance-URI</a> to be discoverable using one or more of the mechanisms described in <a href="#locating-provenance-information" class="sectionRef"></a>.
</p>
<p>
- This presumption of using web retrieval to access provenance information does not preclude use of other mechanisms. In particular, alternative mechanisms may be needed if there is no URI associated with some particular provenance information. Possible mechanisms are suggested in <a href="#provenance-discovery-services" class="sectionRef"></a> and <a href="#querying-provenance-information" class="sectionRef"></a>.
+ This presumption of using web retrieval to access provenance information does not preclude use of other mechanisms. In particular, alternative mechanisms may be needed if there is no URI associated with some particular provenance information. Possible mechanisms are suggested in <a href="#provenance-services" class="sectionRef"></a> and <a href="#querying-provenance-information" class="sectionRef"></a>.
</p>
</section>
@@ -197,7 +197,7 @@
Once provenance information information is retrieved, one needs to know how to identify the view of that resource within that provenance information. This view is known as the <a class="internalDFN">context</a> and is identified by a <a class="internalDFN">context-URI</a>.
</p>
<p>
- We start by considering mechanisms for the resource provider to indicate a <a class="internalDFN">provenance-URI</a> along with a <a class="internalDFN">context-URI</a>. (Mechanisms that can be independent of the resource provision are discussed in <a href="#provenance-discovery-services" class="sectionRef"></a>). Three mechanisms are described here:
+ We start by considering mechanisms for the resource provider to indicate a <a class="internalDFN">provenance-URI</a> along with a <a class="internalDFN">context-URI</a>. (Mechanisms that can be independent of the resource provision are discussed in <a href="#provenance-services" class="sectionRef"></a>). Three mechanisms are described here:
<ul>
<li>The requester knows the resource URI <em>and</em> the resource is accessible using HTTP</li>
<li>The requester has a copy of a resource presented as HTML or XHTML</li>
@@ -247,7 +247,7 @@
An HTTP response MAY include multiple <code>provenance</code> link headers, indicating a number of different provenance resources that are known to the responding server, each providing provenance information about the accessed resource. Likewise, an HTTP response MAY include multiple <code>anchor</code> link headers, that indicate the resource may have provenance information associated with all of the indicated <code><cite>context-URIs</cite></code>.
</p>
<p>
- The presence of a provenance link in an HTTP response does not preclude the possibility that other publishers may offer provenance information about the same resource. In such cases, discovery of the additional provenance information must use other means (e.g. see <a href="#provenance-discovery-services" class="sectionRef"></a>).
+ The presence of a provenance link in an HTTP response does not preclude the possibility that other publishers may offer provenance information about the same resource. In such cases, discovery of the additional provenance information must use other means (e.g. see <a href="#provenance-services" class="sectionRef"></a>).
</p>
<p class="issue">
@@ -329,7 +329,7 @@
</pre>
</code>
<p>
- The <code>provenance-service</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 determine a <a class="internalDFN">provenance-URI</a> for a <a class="internalDFN">context</a>; see <a href="#provenance-discovery-services" class="sectionRef"></a> for more details.
+ The <code>provenance-service</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 determine a <a class="internalDFN">provenance-URI</a> for a <a class="internalDFN">context</a>; see <a href="#provenance-services" class="sectionRef"></a> for more details.
There may be multiple <code>provenance-service</code> link elements, and these MAY appear in the same document as <code>anchor</code> and <code>provenance</code> link elements (though, in simple cases, we anticipate that <code>provenance</code> and <code>provenance-service</code> link relations would not both be used).
</p>
</section>
@@ -404,43 +404,39 @@
<!-- == Sect 4 =================================================================================== -->
<section>
- <h2>Provenance discovery services</h2>
+ <h2>Provenance services</h2>
<p class="pending">
Propose simple HTTP interface for discovery. cf <a href="http://www.w3.org/2011/prov/track/issues/53">ISSUE 53</a>.
This should be properly RESTful, per <a href="http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven">http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven</a>. Have I properly interpreted the principles indicated here?
</p>
- <p class="pending">
- An earlier proposal was a simple HTTP-based service, with URI query parameters used in the construction of a specific URI for provenance information, and did not depend on a service description resource. Early but limited feedback suggested that an approach that does not prescribe URI formats (in line with REST style) would be preferable. Do other reviewers agree?
- </p>
- <p class="issue">
- Rework the text here around the notion of a "provenance service" with discovery and retrieval options. Add text to suggest how they may be applied in different situations.
+ <p>
+ This section describes a REST API [[REST-APIs]] for a provenance service with facilities for discovery and/or retrieval of provenance information, which can be implemented independently of the original resource delivery channels (e.g. by a third party service).
</p>
<p>
- This section describes a REST API [[REST-APIs]] for a provenance discovery and retrieval service, which can be implemented independently of the original resource delivery channels (e.g. by a third party service).
+ All service implementations must respond with a service description (<a href="#service-description" class="sectionRef"></a>) when the service URI is dereferenced.
+ Service implementations may provide either discovery, retrieval or both of these services, indicated by presence of the corresponding service URI templates in the service description. Which of these services to provide is a choice for individual service implementations.
</p>
-
- <p class="issue">
- @@TODO: Review functions provided; review terminology use and property naming; review structure - move different format examples to a separate area?; review correspondence between JSON and RDF-based formats (use JRON?);
+ <p>
+ On the Web, the normal mechanism for retrieving information is to associate it with a URI, and dereference the URI using normal retrieval mechanisms. This approach is enabled using the provenance discovery service mechanism: given the URI of some resource for which provenance information is required, the service returns one or more URIs from which provenance information may be obtained. This approach may be preferred when the provenance service cannot specify the form of URIs used for identifying provenance information, or when there may be more than one source of provenance information known to the provenance service.
+ </p>
+ <p>
+ The provenance retrieval service returns provenance information directly. This mechanism may be preferred when the provenance information is not already presented directly to the web, or is stored in a database with a complex query protocol, or when the provenance service can control the URI from which provenance information is served and avoid the intermediate step of URI discovery.
</p>
<section>
- <h2>Using the provenance discovery API</h2>
+ <h2>Using the provenance service API</h2>
<p>
- This section describes general procedures for using the provenance discovery service API. Later sections describe the resources presented by the API, and their representations using RDF, Turtle and JSON. Normal HTTP content negotiation mechanisms may be used to retrieve representations formats convenient for the client application.
- </p>
-
- <p class="issue">
- Do we need/want both of the following cases?
+ This section describes general procedures for using the provenance service API. Later sections describe the resources presented by the API, and their representations using JSON. <a href="#provenance-service-format-examples" class="sectionRef"></a>gives examples of alternative representations. Normal HTTP content negotiation mechanisms may be used to retrieve representations formats convenient for the client application.
</p>
<section>
<h2>Retrieve Provenance-URIs for a resource</h2>
<p>
- To use the provenance discovery service to retrieve a list of provenance-URIs for a resource, starting with the discovery service URI (<code>service-URI</code>) and the URI of the resource or context (<code>context-URI</code>):
+ To use the provenance service to retrieve a list of provenance-URIs for a resource, starting with the service URI (<code>service-URI</code>) and the URI of the resource or context (<code>context-URI</code>):
<ol>
- <li>Dereference <code>service-URI</code> to obtain a representation of the <a class="internalDFN">service description</a> in one of the formats described below.</li>
- <li>Extract the <cite>provenance location template</cite> from the service description.</li>
- <li>Use the provenance location template with <code>context-URI</code> for template variable <code>uri</code> to form <code>provenance-locations-URI</code>.</li>
+ <li>Dereference <code>service-URI</code> to obtain a representation of the <a class="internalDFN">service description</a>.</li>
+ <li>Extract the provenance locations template from the service description.</li>
+ <li>Use the provenance locations template with <code>context-URI</code> for template variable <code>uri</code> to form <code>provenance-locations-URI</code>.</li>
<li>Dereference <code>provenance-locations-URI</code> to obtain a <a class="internalDFN">provenance locations resource</a> in one of the formats described below.</li>
</ol>
</p>
@@ -452,10 +448,10 @@
<section>
<h2>Retrieve Provenance information for a resource</h2>
<p>
- To use the provenance discovery service to retrieve provenance information for a resource, starting with the discovery service URI (<code>service-URI</code>) and the URI of the resource or context (<code>context-URI</code>):
+ To use the provenance service to directly retrieve provenance information for a resource, starting with the service URI (<code>service-URI</code>) and the URI of the resource or context (<code>context-URI</code>):
<ol>
- <li>Dereference <code>service-URI</code> to obtain a representation of the <a class="internalDFN">service description</a> in one of the formats described below.</li>
- <li>Extract the <cite>provenance information template</cite> from the service description.</li>
+ <li>Dereference <code>service-URI</code> to obtain a representation of the <a class="internalDFN">service description</a>.</li>
+ <li>Extract the provenance information template from the service description.</li>
<li>Use the provenance information template with <code>context-URI</code> for template variable <code>uri</code> to form <code>provenance-URI</code>.</li>
<li>Dereference <code>provenance-URI</code> to obtain <a class="internalDFN">provenance information</a> as described by the Provenance Model specification [[PROV-MODEL]].</li>
</ol>
@@ -472,135 +468,51 @@
<p>
A provenance <dfn>service description</dfn> describes the provenance discovery and retrieval service and, in particular, provides URI templates [[URI-template]] for URIs to access <a title="provenance locations resource" class="internalDFN">provenance locations resources</a> and/or <a class="internalDFN">provenance information</a>. Dereferencing the service URI returns a representation of this service description. The service description MAY contain additional metadata about the service beyond that described here: API clients are expected to ignore any metadata elements they do not understand.
</p>
- <section>
- <h2>JSON example of service description</h2>
- <p>
- This example uses JSON format [[RFC4627]], presented as MIME content-type <code>application/json</code>.
- </p>
- <code>
- <pre class="example">
- {
- "provenance_service_uri": "http://example.info/provenance_service/",
- "provenance_location_template": "http://example.info/provenance_service/location/?uri={uri}",
- "provenance_content_template": "http://example.info/provenance_service/provenance/?uri={uri}"
- }
- </pre>
- </code>
- </section>
- <section>
- <h2>RDF Turtle example of service description</h2>
- <p>
- This example uses the RDF Turtle format [[TURTLE]], presented as MIME content-type <code>text/turtle</code>.
- </p>
- <code>
- <pre class="example">
- @prefix provds: <http://www.w3.org/2011/provenance_discovery/@@TBD@@#> .
- <http://example.info/provenance_service/> a provds:Service_description ;
- provds:provenance_service_uri <http://example.info/provenance_service/> ;
- provds:provenance_location_template "http://example.info/provenance_service/location/?uri={uri}" ;
- provds:provenance_content_template "http://example.info/provenance_service/provenance/?uri={uri}"
- .
- </pre>
- </code>
- <p class="note">
- The provenance URI templates are encoded in RDF as plain string literals, <em>not</em> as resource URIs.
- </p>
- <p class="issue">
- The <code>provds:provenance_service_uri</code> property is redundant given the service description node itself is identified. I've included it for discussion, as it allows the RDF/Turtle form to be very similar to the JSON form of the service description, which may or may not be an advantage. I am personally in favour of using JRON (http://decentralyze.com/2010/06/04/from-json-to-rdf-in-six-easy-steps-with-jron/ <em>Hi Sandro :)</em>) for the JSON format, which would be a very small change: just use "__iri" for the "provenance_service_uri" property, and would allow all formats to be closely based on the RDF model, while affording developers the convenience of using simple JSON handling code where appropriate.
- </p>
- </section>
- <section>
- <h2>RDF/XML example of service description</h2>
- <p>This is essentially the same as the Turtle example above, but encoded in RDF/XML [[RDF-SYNTAX-GRAMMAR]], and presented as MIME content-type <code>application/xml+rdf</code>.</p>
- <code>
- <pre class="example">
- <rdf:RDF
- xmlns:rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
- xmlns:rdfs = "http://www.w3.org/2000/01/rdf-schema#"
- xmlns:provds = "http://www.w3.org/2011/provenance_discovery/@@TBD@@#"
- >
- <provds:Service_description rdf:about="http://example.info/provenance_service/">
- <provds:provenance_service_uri rdf:resource="http://example.info/provenance_service/" /> ;
- <provds:provenance_location_template>http://example.info/provenance_service/location/?uri={uri}</provds:location_template> ;
- <provds:provenance_provenance_template>http://example.info/provenance_service/provenance/?uri={uri}</provds:provenance_template> ;
- </provds:Service_description>
- </rdf:RDF>
- </pre>
- </code>
- </section>
+ <p>
+ This example shows a provenance service description using JSON format [[RFC4627]], which is presented as MIME content-type <code>application/json</code>.
+ Other examples may be seen in <a href="#provenance-service-format-examples" class="sectionRef"></a>.
+ </p>
+ <code>
+ <pre class="example">
+ {
+ "provenance_service_uri": "http://example.info/provenance_service/",
+ "provenance_locations_template": "http://example.info/provenance_service/locations/?uri={uri}",
+ "provenance_content_template": "http://example.info/provenance_service/provenance/?uri={uri}"
+ }
+ </pre>
+ </code>
+ <p class="issue">
+ Is there any point in including the provenance service URI here? It has been included for consistency with RDF representations, but is functionally redundant.
+ </p>
</section>
<section>
<h2>Provenance locations</h2>
<p>
- A <dfn>provenance locations resource</dfn> enumerates one or more provenance-URIs associated with a given resource.
+ A <dfn>provenance locations resource</dfn> enumerates one or more <a class="internalDFN">provenance-URI</a>s identifying <a class="internalDFN">provenance information</a> associated with a given resource.
</p>
<p>
- The examples below are for a given resource URI <code>http://example.info/qdata/</code>, and using the service description example above, its URI would be <code>http://example.info/provenance_service/location/?uri=http%3A%2F%2Fexample.info%2Fqdata%2F</code>.
+ The examples below and in <a href="#provenance-service-format-examples" class="sectionRef"></a> are for a given resource URI <code>http://example.info/qdata/</code>, and using the service description example above, its URI would be <code>http://example.info/provenance_service/location/?uri=http%3A%2F%2Fexample.info%2Fqdata%2F</code>.
</p>
+ <p>
+ This example uses JSON format [[RFC4627]], presented as MIME content type <code>application/json</code>.
+ Other examples may be seen in <a href="#provenance-service-format-examples" class="sectionRef"></a>.
+ </p>
+ <code>
+ <pre class="example">
+ {
+ "uri": "http://example.info/qdata/",
+ "provenance": [
+ "http://source1.example.info/provenance/qdata/",
+ "http://source2.example.info/prov/qdata/",
+ "http://source3.example.com/prov?id=qdata"
+ ]
+ }
+ </pre>
+ </code>
<p class="note">
The template might use <code>?uri={+uri}</code> rather than just <code>?uri={uri}</code>, and thereby avoid %-escaping the <code>:</code> and <code>/</code> characters in the given URI, but this could cause difficulties for URIs containing query parameters and/or fragment identifiers. In this case, the client application would need to ensure that any such characters were %-escaped <em>before</em> being passed into a URI-template expansion processor.
</p>
- <section>
- <h2>JSON example of provenance locations</h2>
- <p>
- This example uses JSON format [[RFC4627]], presented as MIME content type <code>application/json</code>.
- </p>
- <code>
- <pre class="example">
- {
- "uri": "http://example.info/qdata/",
- "provenance": [
- "http://source1.example.info/provenance/qdata/",
- "http://source2.example.info/prov/qdata/",
- "http://source3.example.com/prov?id=qdata"
- ]
- }
- </pre>
- </code>
- </section>
- <section>
- <h2>RDF Turtle example of provenance locations</h2>
- <p>
- This example uses the RDF Turtle format [[TURTLE]], presented as MIME content type <code>text/turtle</code>.
- </p>
- <code>
- <pre class="example">
- @prefix prov: <http://www.w3.org/2011/provenance/@@TBD@@#> .
- <http://example.info/qdata/> a prov:Entity ;
- prov:hasProvenance <http://source1.example.info/provenance/qdata/> ;
- prov:hasProvenance <http://source2.example.info/prov/qdata/> ;
- prov:hasProvenance <http://source3.example.com/prov?id=qdata>
- .
- </pre>
- </code>
- <p class="issue">
- NOTE: The namespace URI used here for the provenance properties is different from that used in the service description. I am anticipating that it will be defined as part of the provenance model. If it is not defined as part of the provenance model, then a property name should be allocated in the provenance discovery service namespace.
- </p>
- <p class="issue">@@TODO: revise to conform with Provenance Model vocabulary</p>
- </section>
- <section>
- <h2>RDF/XML example of provenance locations</h2>
- <p>
- This is essentially the same as the Turtle example above, but encoded in RDF/XML [[RDF-SYNTAX-GRAMMAR]], and presented with MIME content type <code>application/rdf+xml</code>.
- </p>
- <code>
- <pre class="example">
- <rdf:RDF
- xmlns:rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
- xmlns:rdfs = "http://www.w3.org/2000/01/rdf-schema#"
- xmlns:prov = "http://www.w3.org/2011/provenance/@@TBD@@#"
- >
- <prov:Entity rdf:about="http://example.info/qdata/">
- <prov:hasProvenance rdf:resource="http://source1.example.info/provenance/qdata/" /> ;
- <prov:hasProvenance rdf:resource="http://source2.example.info/prov/qdata/" /> ;
- <prov:hasProvenance rdf:resource="http://source3.example.com/prov?id=qdata" /> ;
- </prov:Entity>
- </rdf:RDF>
- </pre>
- </code>
- <p class="issue">@@TODO: revise to conform with Provenance Model vocabulary</p>
- </section>
</section>
<section>
@@ -826,6 +738,112 @@
<!-- ===================================================================================== -->
+ <section class='appendix'>
+ <h2>Provenance service format examples</h2>
+ <p>
+ In <a href="#provenance-services" class="sectionRef"></a>, the provenance service description was presented as a JSON-formatted document. As noted, HTTP content negotiation MAY be enabled to retrieve the document in alternative formats. This appendix provides examples of service description document presented using RDF Turtle and XML sybntaxes, and XML.
+ </p>
+
+ <section>
+ <h2>RDF Turtle example of service description</h2>
+ <p>
+ This example uses the RDF Turtle format [[TURTLE]], presented as MIME content-type <code>text/turtle</code>.
+ </p>
+ <code>
+ <pre class="example">
+ @prefix provds: <http://www.w3.org/2011/provenance_discovery/@@TBD@@#> .
+ <http://example.info/provenance_service/> a provds:Service_description ;
+ provds:provenance_locations_template "http://example.info/provenance_service/locations/?uri={uri}" ;
+ provds:provenance_content_template "http://example.info/provenance_service/provenance/?uri={uri}"
+ .
+ </pre>
+ </code>
+ <p class="note">
+ The provenance URI templates are encoded in RDF as plain string literals, <em>not</em> as resource URIs.
+ </p>
+ </section>
+
+ <section>
+ <h2>RDF/XML example of service description</h2>
+ <p>This is essentially the same as the Turtle example above, but encoded in RDF/XML [[RDF-SYNTAX-GRAMMAR]], and presented as MIME content-type <code>application/xml+rdf</code>.</p>
+ <code>
+ <pre class="example">
+ <rdf:RDF
+ xmlns:rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:rdfs = "http://www.w3.org/2000/01/rdf-schema#"
+ xmlns:provds = "http://www.w3.org/2011/provenance_discovery/@@TBD@@#"
+ >
+ <provds:Service_description rdf:about="http://example.info/provenance_service/">
+ <provds:provenance_locations_template>http://example.info/provenance_service/locations/?uri={uri}</provds:location_template> ;
+ <provds:provenance_content_template>http://example.info/provenance_service/provenance/?uri={uri}</provds:provenance_template> ;
+ </provds:Service_description>
+ </rdf:RDF>
+ </pre>
+ </code>
+ </section>
+
+ <section>
+ <h2>Plain XML example of service description</h2>
+ <p class="issue">
+ @@TODO: provide example and schema
+ </p>
+ </section>
+
+ <section>
+ <h2>RDF Turtle example of provenance locations</h2>
+ <p>
+ This example uses the RDF Turtle format [[TURTLE]], presented as MIME content type <code>text/turtle</code>.
+ </p>
+ <code>
+ <pre class="example">
+ @prefix prov: <http://www.w3.org/2011/provenance/@@TBD@@#> .
+ <http://example.info/qdata/> a prov:Entity ;
+ prov:hasProvenance <http://source1.example.info/provenance/qdata/> ;
+ prov:hasProvenance <http://source2.example.info/prov/qdata/> ;
+ prov:hasProvenance <http://source3.example.com/prov?id=qdata>
+ .
+ </pre>
+ </code>
+ <p class="issue">
+ NOTE: The namespace URI used here for the provenance properties is different from that used in the service description. I am anticipating that it will be defined as part of the provenance model. If it is not defined as part of the provenance model, then a property name should be allocated in the provenance discovery service namespace.
+ </p>
+ <p class="issue">@@TODO: revise to conform with Provenance Model vocabulary</p>
+ </section>
+
+ <section>
+ <h2>RDF/XML example of provenance locations</h2>
+ <p>
+ This is essentially the same as the Turtle example above, but encoded in RDF/XML [[RDF-SYNTAX-GRAMMAR]], and presented with MIME content type <code>application/rdf+xml</code>.
+ </p>
+ <code>
+ <pre class="example">
+ <rdf:RDF
+ xmlns:rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:rdfs = "http://www.w3.org/2000/01/rdf-schema#"
+ xmlns:prov = "http://www.w3.org/2011/provenance/@@TBD@@#"
+ >
+ <prov:Entity rdf:about="http://example.info/qdata/">
+ <prov:hasProvenance rdf:resource="http://source1.example.info/provenance/qdata/" /> ;
+ <prov:hasProvenance rdf:resource="http://source2.example.info/prov/qdata/" /> ;
+ <prov:hasProvenance rdf:resource="http://source3.example.com/prov?id=qdata" /> ;
+ </prov:Entity>
+ </rdf:RDF>
+ </pre>
+ </code>
+ <p class="issue">@@TODO: revise to conform with Provenance Model vocabulary</p>
+ </section>
+
+ <section>
+ <h2>Plain XML example of provenance locations</h2>
+ <p class="issue">
+ @@TODO: provide example and schema
+ </p>
+ </section>
+
+ </section>
+
+<!-- ===================================================================================== -->
+
<section class="appendix">
<h2>Motivating scenario</h2>
<p class="pending">