--- a/model/prov-dm.html Thu Mar 22 20:45:23 2012 +0000
+++ b/model/prov-dm.html Thu Mar 22 22:28:51 2012 +0000
@@ -311,33 +311,28 @@
<section id="structure-of-this-document">
<h3>Structure of this Document</h3>
-<p><a href="#prov-dm-overview">Section 2</a> provides an overview of PROV-DM listing its core types and their relations.</p>
-
-<p>In <a href="#prov-dm-example">section 3</a>, PROV-DM is
-applied to a short scenario, encoded in PROV-N, and illustrated
-graphically.</p>
+<p><a href="#starting-point">Section 2</a> provides a starting point for the PROV Data Model, listing some core types and their relations.</p>
+
+<p><a href="#prov-dm-example">Section 3</a> illustrates how PROV-DM can be used
+to express the provenance of a report published on the Web.</p>
<p><a href="#data-model-components">Section 4</a> provides the definition of PROV-DM concepts, structured according to six components.</p>
<p><a href="#extensibility-section">Section 5</a> summarizes PROV-DM extensibility points.</p>
<p><a href="#FurtherConsiderations">Section 6</a> introduces constraints that can be applied to the PROV data model
-and that are covered in [[PROV-DM-CONSTRAINTS]].</p>
+and that are covered in the companion specification [[PROV-DM-CONSTRAINTS]].</p>
</section>
<section id="prov-dm-namespace">
- <h3>PROV-DM Namespace</h3>
-
-
-<p>The PROV-DM namespace is <span class="name">http://www.w3.org/ns/prov-dm/</span> (TBC).</p>
-
-<p> All the elements, relations, reserved names and attributes introduced in this specification belong to the PROV-DM namespace.</p>
-
-<div class="issue">
-There is a desire to use a single namespace that all specifications of the PROV family can share to refer to common provenance terms. This is <a href="http://www.w3.org/2011/prov/track/issues/224">ISSUE-224</a>.
-</div>
+ <h3>PROV Namespace</h3>
+
+
+<p>The PROV namespace is <span class="name">http://www.w3.org/ns/prov#</span>.</p>
+
+<p> All the concepts, reserved names and attributes introduced in this specification belong to the PROV namespace.</p>
</section>
@@ -357,15 +352,19 @@
- <section id='conceptualization'>
-<h1>Overview</h1>
-
-<p>This section provides an overview of the main concepts found in the PROV data model. </p>
+<section id='starting-point'>
+<h1>PROV-DM Starting Point</h1>
+
+<p>This section provides an introduction to the PROV data model by
+overviewing its main concepts. Concepts are initially described in
+natural language, and illustrated by small examples. Since PROV-DM is
+a conceptual data model, its various types and relations are then exposed.
+</p>
- <section id='section-entity-activity-agent'>
-<h2>Entity, Activity, Agent</h2>
+ <section id='section-entity-activity'>
+<h2>Entity and Activity</h2>
<p>PROV-DM is a data model for describing the provenance of <em>Entities</em>, that is, of things in the world. The term "Things" encompasses a broad diversity of concepts, including digital objects such as a file or web page,
@@ -393,29 +392,8 @@
<p>An activity may be the publishing of a document on the web, sending a twitter message, extracting metadata embedded in a file, or driving a car from Boston to Cambridge, assembling a data set based on a set of measurements, performing a statistical analysis over a data set, sorting news items according to some criteria, running a SPARQL query over a triple store, and editing a file.</p>
</div>
-
-<p>
-<span class="glossary-ref" ref="glossary-agent" withspan="true">
-</span>
-</p>
-
-
-<p>The motivation for introducing agents in the model is to denote the agent's responsibility for activities.
-The definition of agent intentionally stays away from using concepts such as enabling, causing, initiating, affecting, etc, because many entities also enable, cause, initiate, and affect in some way
-the activities. Concepts such as initiating are themselves defined as relations between agent and activities. So the notion of having some degree of responsibility is really what makes an agent.</p>
-
-
-<p>An agent is a particular type of Entity. This means that the model can be
- used to express provenance of the agents themselves. </p>
-
-<div class="anexample" id="agent-example">
-<p>
-Software for checking the use of grammar in a document may be defined as an agent of a document preparation activity, and at the same time one can describe its provenance, including for instance the vendor and the version history.</p>
-</div>
</section>
-
-
<section id="section-generation-usage-derivation">
<h2>Generation, Usage, Derivation</h2>
@@ -463,8 +441,30 @@
</section>
- <section id="section-types-entities-agents">
-<h2>Types of Entities and Agents</h2>
+<section id="section-types-entities-agents">
+<h2>Agents and Other Types of Entities</h2>
+
+<p>
+<span class="glossary-ref" ref="glossary-agent" withspan="true">
+</span>
+</p>
+
+
+<p>The motivation for introducing agents in the model is to denote the agent's responsibility for activities.
+The definition of agent intentionally stays away from using concepts such as enabling, causing, initiating, affecting, etc, because many entities also enable, cause, initiate, and affect in some way
+the activities. Concepts such as initiating are themselves defined as relations between agent and activities. So the notion of having some degree of responsibility is really what makes an agent.</p>
+
+
+<p>An agent is a particular type of Entity. This means that the model can be
+ used to express provenance of the agents themselves. </p>
+
+<div class="anexample" id="agent-example">
+<p>
+Software for checking the use of grammar in a document may be defined as an agent of a document preparation activity, and at the same time one can describe its provenance, including for instance the vendor and the version history.</p>
+</div>
+
+
+
<p>There are some useful types of entities and agents that are commonly encountered in applications making data and documents available on the Web; we introduce them in this section. </p>
@@ -523,8 +523,9 @@
someone models software as an agent for an activity in the PROV-DM model, they mean the agent has some responsibility for that activity.</p>
</section>
- <section id="section-responsibility">
-<h2>Activity Association and Responsibility</h2>
+
+<section id="section-attribution-association-responsibility">
+<h2>Attribution, Association, and Responsibility</h2>
@@ -590,43 +591,108 @@
</section>
+
+
+
+
<section id="section-UML">
-<h2>Overview Diagram</h2>
-
-<p> The following diagram summarizes the elements and relations just described</p>
-
-<div class="note">
- TODO: short text required to explain the overview diagram
-<p> add a sentence saying that it is not complete coverage of the dm in diagram.</p>
-<p>The text should say that we introduce a few relations based on the concepts introduced in section 2.1-2.4, that these relations are used in the example of section 3, and are fully defined in section 4-5.</p>
-<p>The note should also say why relations are in past tense (we had something in previous version of prov-dm)</p>
-<p>I have the impression that the diagram presented in Section 2.5 would
- > be more useful if placed at the beginning of Section 2 [KB]
-<p>There is some comments that the picture does not print well. We need to check. </p>
-<p>Add links in the svg so that we can click on the figure. </p>
+<h2>Simplified Overview Diagram</h2>
+
+<p>So far, we have introduced a series of concepts underpinning provenance. PROV-DM is a conceptual data model consisting of types and relations between these. Table <a href="#overview-types-and-relations">(Mapping of Provenance concepts to types and relations in PROV-DM)</a> shows how provenance concepts can be mapped to types and relations in PROV-DM: the first column lists concepts introduced in this section, the second column indicates whether a concept maps to a type or a relation, whereas the third column contains the corresponding name. We note that names of relations have a verbal form in the past tense to express what happened in the past, as opposed to what may or will happen.
+</p>
+
+
+<div style="text-align: left;">
+<table border="1" style="margin-left: auto; margin-right: auto;">
+<caption id="overview-types-and-relations">Mapping of Provenance concepts to types and relations in PROV-DM</caption>
+<tr><td><a>Provenance Concepts</a></td><td></td><td>PROV-DM types or relations</td></tr>
+<tr>
+<td><a>Entity</a></td><td rowspan="3">Types in PROV-DM</td><td><a title="dfn-Entity">entity</a></td></tr>
+<tr><td><a>Activity</a></td><td><a title="dfn-Activity">activity</a></td></tr>
+<tr><td><a>Agent</a></td><td><a title="dfn-agent">agent</a></td></tr>
+<tr>
+<td><a>Generation</a></td><td rowspan="6">Relations in PROV-DM</td><td><a title="dfn-Generation">wasGeneratedBy</a></td></tr>
+<tr><td><a>Usage</a></td><td><a title="used">used</a></td></tr>
+<tr><td><a>Attribution</a></td><td><a title="wasAttributedTo">wasAttributedTo</a></td></tr>
+<tr><td><a>Association</a></td><td><a title="wasAssociatedWith">wasAssociatedWith</a></td></tr>
+<tr><td><a>Responsibility</a></td><td><a title="actedOnBehalfOf">actedOnBehalfOf</a></td></tr>
+<tr><td><a>Derivation</a></td><td><a title="wasDerivedFrom">wasDerivedFrom</a></td></tr>
+</table>
</div>
+<p>Figure <a href="#">overview-types-and-relations</a> illustrates the three types (entity, activity, and agent) and how they relate to each other. At this stage, all relations are shown to be binary. When examining PROV-DM in details,
+some relations, while involving two primary elements, are shown to be n-ary. </p>
+
<div style="text-align: center; ">
<figure style="max-width: 70%; " >
-
-
-<embed src="images/OverviewDiagram.svg" width="600" height="400" alt="PROV-DM overview" type="image/svg+xml"></embed>
+ <img src="images/OverviewDiagram.png" alt="PROV-DM overview" style="max-width: 70%; " />
+<figcaption id="prov-dm-overview">PROV-DM overview</figcaption>
+ </figure>
+</div>
+
+<p>Figure <a href="#">overview-types-and-relations</a> is not intended to be complete. It only illustrates the types and relations exploited in the example discussed in the next section. They will then be explained in detail in Section <a href="#data-model-components">data-model-components</a>.
+The third column of Table <a href="#overview-types-and-relations">(Mapping of Provenance concepts to types and relations in PROV-DM)</a> lists names that are part of a textual notation to write instances of the PROV-DM data model. This notation, referred to as the PROV-N notation, is outlined in the next section. </p>
<!--
- <img src="images/OverviewDiagram.svg" alt="PROV-DM overview" style="max-width: 70%; " />-->
-
-<figcaption>PROV-DM overview</figcaption>
- </figure>
+<div class="note">
+ TODO: short text required to explain the overview diagram
+<p>I have the impression that the diagram presented in Section 2.5 would
+ > be more useful if placed at the beginning of Section 2 [KB]
</div>
-
+-->
+</section>
+<section id="prov-n">
+<h2>PROV-N: The Provenance Notation</h2>
+
+<p>A key goal of PROV-DM is the specification of a machine-processable data model for provenance so that application can retrieve provenance and reason about it. As such, representations of PROV-DM are available in RDF and XML.
+</p>
+
+<p>However, it is important to provide instances of provenance for human consumption, as in this document or elsewhere.
+To this end, PROV-N is a notation that is designed to write instances of the PROV-DM data model in a compact textual form, without the syntactic bagage and constraints coming with a markup language such as XML or a description framework such as RDF. We outline here some of its key design principles. For full details, the reader is referred to the companion specification [[PROV-N]].</p>
+
+<ul>
+<li>PROV-N expressions adopt a <em>functional notation</em> consisting
+of a name and a series of arguments in bracket.</li>
+
+<li>The interpretation of PROV-N arguments is defined according to their <em>position</em> in the list of arguments. This convention allows for a compact notation. </li>
+
+<li><p>
+PROV-N <em>optional arguments</em> need not be specified. For cases where it is desirable to indicate which arguments have not been specified, PROV-N uses the <em>syntactic marker</em> <span class="name">-</span> for unspecified arguments.</p>
+</li>
+
+<li><p>Most expressions
+have an identifier which always occur in <em>first position</em>,
+and an optional set of attribute-value pairs, which occur in <em>last position</em>, and delimited by square brackets. </p>
+</li>
+</ul>
+
+<div class="anexample">
+<p>
+An activity with identifier <span class="name">a1</span> and an attribute <span class="name">type</span> with value <span class="name">createFile</span>.
+<pre class="codeexample" >
+activity(a1, [prov:type="createFile"])
+</pre>
+Two entities with identifiers <span class="name">e1</span> and identifiers <span class="name">e2</span>.
+<pre class="codeexample" >
+entity(e1)
+entity(e2)
+</pre>
+The activity <span class="name">a1</span> used <span class="name">e1</span>, and <span class="name">e2</span> was generated by <span class="name">a1</span>.
+<pre class="codeexample" >
+used(a1,e1)
+wasGeneratedBy(e2,a1)
+</pre>
+</div>
+
+</section>
</section>
</section>
<!-- </section> -->
<section id="prov-dm-example">
-<h2>Example</h2>
+<h2>Illustration of PROV-DM by an Example</h2>
<p>The World Wide Web Consortium publishes many technical reports. In this example, we consider a technical report, and describe its provenance. </p>
@@ -833,9 +899,9 @@
<section id="data-model-components">
-<h2>PROV-DM Concepts and Relations</h2>
-
-<p>PROV-DM Concepts are structured according to six components that are introduced here.
+<h2>PROV-DM Types and Relations</h2>
+
+<p>PROV-DM concepts are structured according to six components that are introduced here.
Components and their dependencies are illustrated in Figure <a href="#prov-dm-components">prov-dm-components</a>. A component that relies on concepts defined in another also sits above it, in this figure.
PROV-DM consists of the following components.</p>
--- a/model/prov-n.html Thu Mar 22 20:45:23 2012 +0000
+++ b/model/prov-n.html Thu Mar 22 22:28:51 2012 +0000
@@ -366,8 +366,8 @@
<li><p>The identifier always occur in <em>first position</em>. For expressions with optional identifier, it may be expressed by the syntactic marker <span class="name">-</span>.</p>
+<div class="anexample">
<p>Derivation has an optional identifier. In the first derivation, the identifier is not expressed. It is explicit in the second, and marked by a <span class="name">-</span> in the third.</p>
-<div class="anexample">
<pre class="codeexample" >
wasDerivedFrom(e2, e1)
wasDerivedFrom(d, e2, e1)
@@ -387,6 +387,8 @@
<li> PROV-N exposes attributes that PROV-DM provides an interpretation for [[PROV-DM-CONSTRAINTS]] directly as positional arguments of expressions, whereas those for which PROV-DM provides no interpretation need to be expressed among the optional attribute-value pairs.
</li>
+<div class="note">
+Subject appears first, object second, pointing to the past.
</ul>