--- a/bestpractices/BestPractices.html Mon Apr 16 16:57:54 2012 +0100
+++ b/bestpractices/BestPractices.html Mon Apr 16 16:58:10 2012 +0100
@@ -1122,6 +1122,42 @@
</section>
</section>
</section>
+
+ <section>
+ <h2>Using strings</h2>
+ Issues <a href="http://www.w3.org/2011/prov/track/issues/248">248</a> and <a href="http://www.w3.org/2011/prov/track/issues/222">222</a>.
+ prov:used is defined as an objectproperty. If the parameter to a program is a string, and we want to say that the invocation used the string, how do we model that?
+
+ This is only a concern if you want to be DL compliant. If you don't care about being DL compliant, then just do it.
+ Another concern is that tools will expect a resource instead of a string and will not handle it correctly.
+
+ <a href="http://www.w3.org/TR/Content-in-RDF10/">Content in RDF</a> can be used to model string values while maintaining the datatype/objectproperty distinction and complying with PROV-O.
+ Also, resource can use the rdf:value property to store the string value. We recommend NOT using a blank node, but to derive the URI from the string itself (using a hash) or just a UUID.
+ Note that altough the "extra resource" may appear to be an undesirable level of indirection, it allows for the arbitrary contextualization that is central to PROV. When describing this strings provenance, we're not talking about that string as it appears anywhere, but as it appeared to the activty using it at the time we're describing.
+
+ <pre>
+@prefix cnt: <http://www.w3.org/2008/content#> .
+
+:activity a prov:Activity;
+ prov:used [ # dont' use a blank node!
+ a prov:Entity, cnt:ContentAsText ;
+ cnt:chars "The magic string" ;
+] .
+
+:activity a prov:Activity;
+ prov:used :theMagicString .
+
+:magicString
+ a prov:Entity, cnt:ContentAsText ;
+ cnt:chars "The magic string" .
+</pre>
+
+
+(there's also cnt:ContentAsBase64 and cnt:bytes for verbose binaries,
+and cnt:ContentAsXML for literal XMLs)
+
+ </section>
+
<section class='appendix'>
<h2>Acknowledgements</h2>
<p>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/examples/eg-25-extended-crime-file-example/document/homepage Mon Apr 16 16:58:10 2012 +0100
@@ -0,0 +1,2 @@
+http://www.w3.org/2011/prov/wiki/Eg-25-extended-crime-file-example
+http://dvcs.w3.org/hg/prov/file/tip/examples/extended-crime-file-example
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/examples/eg-25-extended-crime-file-example/rdf/extended-crime-file-example.ttl Mon Apr 16 16:58:10 2012 +0100
@@ -0,0 +1,130 @@
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+@prefix prov: <http://www.w3.org/ns/prov#> .
+@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+@prefix ex: <http://example.org#> .
+@prefix sioc: <http://rdfs.org/sioc/ns#Post> .
+
+ex:accountPost{
+ ex:accountPost
+ a prov:Account
+ .
+ ex:derek
+ a prov:Agent;
+ a foaf:Person;
+ foaf:givenName "Derek"^^xsd:string;
+ foaf:mbox <mailto:dererk@example.org>;
+ prov:actedOnBehalfOf ex:chartgen
+ .
+ ex:monica
+ a prov:Agent;
+ a foaf:Person;
+ foaf:givenName "Monica"^^xsd:string;
+ foaf:mbox <mailto:monica@example.org>
+ .
+
+ ex:chartgen
+ a prov:Agent;
+ a prov:Organization;
+ foaf:name "Chart Generators"
+ .
+
+ ex:aggregatedByRegions
+ a prov:Entity;
+ prov:atLocation <file://Users/aggr.txt>
+ .
+
+ ex:post9821
+ a prov:Entity, sioc:Post;
+ prov:wasGeneratedBy ex:publicationActivity1123;
+ prov:atLocation ex:more-crime-happens-in-cities; ##PERMALINK of the post
+ ex:snapshotContent ex:postContent0; ##Snapshot with the content of this version
+ prov:qualifiedGeneration [
+ a prov:Generation;
+ prov:activity ex:publicationActivity1123;
+ prov:atTime "2011-07-16T01:52:02Z"^^xsd:dateTime;
+ prov:atLocation <http://dbpedia.org/resource/Madrid>.
+ ];
+ sioc:title "More crime happens in cities"^^xsd:string;
+ prov:hadOriginalSource ex:aggregatedByRegions;
+ prov:wasAttributedTo ex:dereck
+ .
+
+ ##Version 2 of the post
+ ex:post9821v1
+ a prov:Entity, sioc:Post;
+ prov:atLocation ex:more-crime-happens-in-cities; ##PERMALINK of the post
+ ex:snapshotContent ex:postContent1; ##Snapshot with the content of this version
+ prov:wasRevisionOf ex:post9821;
+ prov:specializationOf ex:post9821;
+ prov:wasAttributedTo ex:dereck
+ .
+
+ ##Rephrasing of the post in a new version
+ ex:post9821v2
+ a prov:Entity, sioc:Post;
+ prov:atLocation ex:more-crime-happens-in-cities-for-dummies; ##PERMALINK of the post
+ ex:snapshotContent ex:postContent2; ##Snapshot with the content of this version
+ prov:alternateOf ex:post9821v1;
+ prov:specializationOf ex:post9821;
+ sioc:title "More crime happens in cities for dummies"^^xsd:string;
+ prov:wasAttributedTo ex:monica
+ .
+
+
+ <http://dbpedia.org/resource/Madrid>
+ a prov:Location
+ .
+
+ ex:publicationActivity1123
+ a prov:Activity;
+ prov:wasStartedAt "2011-07-16T01:01:01Z"^^xsd:dateTime;
+ prov:wasEndedAt "2011-07-16T01:52:02Z"^^xsd:dateTime;
+ prov:wasAssociatedWith ex:derek;
+ prov:used ex:aggregatedByRegions;
+ prov:generated ex:post9821;
+ prov:wasStartedBy ex:dereck;
+ prov:wasEndedBy ex:dereck
+ .
+}
+
+ex:accountPost2{
+ ex:accountPost2
+ a prov:Account;
+ prov:hasAnnotation ex:noteMadeByParser
+ .
+
+ ex:john
+ a prov:Agent
+ .
+
+ ex:post19201
+ a prov:Entity, sioc:Post;
+ prov:wasAttributedTo ex:john;
+ prov:wasQuotedFrom post9821v1, post9821v2;
+ prov:hadOriginalSource ex:aggregatedByRegions
+ .
+}
+
+ex:noteMadeByParser{
+ ex:noteMadeByParser
+ a prov:Note;
+ prov:wasAttributedTo ex:boogleParser
+ .
+
+ ex:boogleParser
+ a prov:SoftwareAgent;
+ prov:actedOnBehalfOf ex:boogle
+ .
+ ex:boogle
+ a prov:Organization
+ .
+
+ ex:accountPost2
+ ex:parsedDate "2011-08-16T00:00:02Z"^^xsd:dateTime
+ .
+}
+
+
+
+
+
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/examples/eg-26-provo-collections-narrative/document/homepage Mon Apr 16 16:58:10 2012 +0100
@@ -0,0 +1,2 @@
+http://www.w3.org/2011/prov/wiki/Eg-26-provo-collections-narrative
+http://dvcs.w3.org/hg/prov/file/tip/examples/eg-26-provo-collections-narrative
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/examples/eg-26-provo-collections-narrative/rdf/eg-26-provo-collections-narrative.ttl Mon Apr 16 16:58:10 2012 +0100
@@ -0,0 +1,11 @@
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix dcterms: <http://purl.org/dc/terms/> .
+@prefix sd: <http://www.w3.org/ns/sparql-service-description#> .
+@prefix dcat: <http://www.w3.org/ns/dcat#> .
+@prefix void: <http://rdfs.org/ns/void#> .
+@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+@prefix prov: <http://www.w3.org/ns/prov#> .
+@prefix : <http://dvcs.w3.org/hg/prov/raw-file/tip/examples/eg-26-provo-collections-narrative/rdf/eg-26-provo-collections-narrative.ttl#> .
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/examples/eg-26-provo-collections-narrative/rdf/eg-26-provo-collections-narrative.ttl.sd_name Mon Apr 16 16:58:10 2012 +0100
@@ -0,0 +1,1 @@
+http://dvcs.w3.org/hg/prov/raw-file/tip/examples/eg-26-provo-collections-narrative/rdf/eg-26-provo-collections-narrative.ttl
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/examples/eg-26-provo-collections-narrative/rdf/start.ttl Mon Apr 16 16:58:10 2012 +0100
@@ -0,0 +1,21 @@
+@prefix prov: <http://www.w3.org/ns/prov#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+@prefix : <http://example.org/> .
+
+:e1 a prov:Entity .
+:e2 a prov:Entity .
+
+:c1 a prov:Collection;
+ prov:membership [
+ a prov:Membership;
+ prov:member [
+ a prov:KeyValuePair;
+ prov:key "k1"^^xsd:string;
+ prov:value :e1
+ ], [
+ a prov:KeyValuePair;
+ prov:key "k2"^^xsd:string;
+ prov:value :e2
+ ];
+ ];
+.
--- a/ontology/prov-o-html-sections/description-collections.inc.html Mon Apr 16 16:57:54 2012 +0100
+++ b/ontology/prov-o-html-sections/description-collections.inc.html Mon Apr 16 16:58:10 2012 +0100
@@ -2,145 +2,82 @@
<!-- This section is version controlled at http://dvcs.w3.org/hg/prov/file/tip/ontology and mirroed to
https://github.com/timrdf/prov-lodspeakr/tree/master/components/services/prov-o -->
<h3>Collections Terms</h3>
- <p><em>
- A collection is an entity that provides a structure to some
- constituents, which are themselves entities. These constituents
- are said to be member of the collections.
- </em></p>
- <p>
- Conceptually, a collection has a logical structure consisting of
- key-value pairs. This structure is often referred to as a map, and is a
- generic indexing mechanisms that can abstract commonly used data
- structures, including associative lists (also known as "dictionaries" in
- some programming languages), relational tables, ordered lists, and more
- (the specification of such specialized structures in terms of key-value
- pairs is out of the scope of this document).
- </p>
- <p>
- A given collection forms a given structure for its members. A
- different structure (obtained either by insertion or removal of
- members) constitutes a different collection. Hence, for the
- purpose of provenance, a collection entity is viewed as a
- snapshot of a structure. Insertion and removal operations result
- in new snapshots, each snapshot forming an identifiable
- collection entity.
- </p>
- <p>
- In PROV-O, an entity is indicated to be a collection by using the
- subclass <a class="qname" href='#Collection'>prov:Collection</a>. Its subclass <a class="qname" href='#EmptyCollection'>prov:EmptyCollection</a> indicates
- that the collection has no members.
- Members of a collection are expressed through <a class="qname" href='#KeyValuePair'>prov:KeyValuePair</a>s.
- The members can be expressed explicitly using <a class="qname" href='#knownMembership'>prov:knownMembership</a>, and indirectly
- through a series of collection derivations of insertions and
- removals, using <a class="qname" href='#derivedByInsertionFrom'>prov:derivedByInsertionFrom</a>
- and <a class="qname" href='#derivedByRemovalFrom'>prov:derivedByRemovalFrom</a>.
- </p>
- <p>
- To specify the key-value pairs inserted,
- <span class="repeated">prov:derivedByInsertionFrom</span> must be qualified using <a class="qname" href='#qualifiedInsertion'>prov:qualifiedInsertion</a> to a
- <a class="qname" href='#Insertion'>Insertion</a>, which indicates the pairs
- using <a class="qname" href='#inserted'>prov:inserted</a> to some <a class="qname" href='#KeyValuePair'>prov:KeyValuePair</a>. Its <a class="qname" href='#key'>prov:key</a> is any RDF literal, while the <a class="qname" href='#value'>prov:value</a> is a <a class="qname" href='#Entity'>prov:Entity</a>.
- Likewise, removal are qualified using <a class="qname" href='#qualifiedRemoval'>prov:qualifiedRemoval</a> to a <a class="qname" href='#Removal'>Removal</a>, which <a class="qname" href='#removedKey'>prov:removedKey</a>
- points to the removed key. <span class="repeated">prov:Insertion</span>,
- <span class="repeated">prov:Removal</span> and <span class="repeated">prov:Membership</span> can have
- custom properties and identifiers, as described in PROV-DM.
- </p>
- <div class="exampleOuter">
- <p>
- The example below shows how
- <code>:c</code> and <code>:c1</code> are
- collections. <code>:c</code> is empty, while <code>:c1</code>
- is derived by inserting the key-value pairs <code>{("k1", :e1),
- ("k2", :e2)}</code>.</p>
- <pre class="example">
-@prefix prov: <http://www.w3.org/ns/prov#> .
-@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
-@prefix : <http://example.org/> .
+ <p> A <code><a class="qname"
+href='#Collection'>prov:Collection</a></code> is an <code
+class="repeated">prov:Entity</code> that acts as a container to some members,
+which are themselves entities.
+Specifically, a collection is composed of set of key-value pairs, where a
+literal key is used to identify a constituent entity within the collection.
+
+To illustrate this, the example below describes a collection <code>:c1</code>
+that has as members the two key value pairs <code>("k1", :e1)</code>
+and <code>("k2", :e2)</code>.
+</p>
+
+<pre class="example">{% escape %}{% include "includes/prov/examples/eg-26-provo-collections-narrative/rdf/start.ttl" %}{% endescape %}</pre>
+
+<p>It is worth noting that <code>:c1</code> MAY also
+have other members (i.e. <code class="repeated">prov:knownMembership</code> is
+not functional). A collection MAY be empty and thus not have any known
+memberships, in which case it SHOULD be described as an instance of the
+subclass <a class="qname"
+href='#EmptyCollection'><code>prov:EmptyCollection</code></a>.
+</p>
+
+ <p> To describe the provenance of a collection, PROV-O provides two
+kinds of involvements: <code><a class="qname"
+href="qualifiedInsertion">prov:qualifiedInsertion</a></code> is used to
+describe that a collection was obtained from an existing collection by
+<em>inserting</em> a set of key-value pairs. <code><a class="qname"
+href="qualifiedRemoval">prov:qualifiedRemoval</a></code> is used to specify
+that a given collection was obtained from an existing collection by
+<em>removing</em> a set of key-value pairs. The example below specifies that
+the collection <code>:c1</code> was obtained from the empty collection
+<code>:c1</code> by <em>inserting</em> the key-value pairs <code>("k1",
+:e1)</code> and <code>("k2", :e2)</code>.
+</p>
+
+<pre class="example">
+@prefix prov: <http://www.w3.org/ns/prov#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
:e1 a prov:Entity .
:e2 a prov:Entity .
:c a prov:EmptyCollection .
-
-:c1 a prov:Collection;
- prov:derivedByInsertionFrom :c;
- prov:qualifiedInsertion [
- a prov:Insertion;
- prov:collection :c;
- prov:inserted [
- a prov:KeyValuePair;
- prov:key "k1"^^xsd:string;
- prov:value :e1;
- ], [
- a prov:KeyValuePair;
- prov:key "k2"^^xsd:string;
- prov:value :e2;
- ];
- ];
-.
- </pre>
- </div>
-
-
-
-
- <div class="exampleOuter">
- <p>
- The following example shows how <code>:c3</code> has been derived from
- <code>:c2</code>, whose content is not asserted. The keys
- <code>"k1"</code> and <code>"k3"</code> and their corresponding
- values have been removed in <code>:c3</code>.
- </p>
- <pre class="example">
-@prefix prov: <http://www.w3.org/ns/prov#> .
-@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
-@prefix : <http://example.org/> .
-
-:c2 a prov:Collection .
+:c1 a prov:Collection .
+ prov:derivedByInsertionFrom :c ;
+ prov:qualifiedInsertion [ a prov:Insertion ;
+ prov:collection :c ;
+ prov:inserted [ a prov:KeyValuePair ;
+ prov:key "k1"^^xsd:string ;
+ prov:value :e1 ;
+ ], [ a prov:KeyValuePair ;
+ prov:key "k2"^^xsd:string ;
+ prov:value :e2 ;
+ ]
+ ] .
+</pre>
-:c3 a prov:Collection;
- prov:derivedByRemovalFrom :c2;
- prov:qualifiedRemoval [
- a prov:Removal;
- prov:collection :c2;
- prov:removed "k1"^^xsd:string,
- "k3"^^xsd:string;
- ];
-.
- </pre>
- </div>
-
-
-
-
+ <p>
+ Similarly, the example below specifies that the collection
+ <code>:c3</code> was obtained by <em>removing</em> the key-value pairs associated with
+ the keys <code>"k1"</code> and <code>"k2"</code> from the collection
+ <code>:c2</code>. Thus, <code>:c3</code> does not contain the
+ members <code>("k1", :e1)</code> and <code>("k2",
+ :e2(</code> from <code>:c2</code>.
+ </p>
- <div class="exampleOuter">
- <p>
- The next example shows how the members of
- <code>:c1</code> has been described as the key-value
- pairs <code>{("k1", :e1), ("k2", :e2)}</code>. Note that this
- assertion does not claim there are not other members.
- </p>
- <pre class="example">
-@prefix prov: <http://www.w3.org/ns/prov#> .
-@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
-@prefix : <http://example.org/> .
+<pre class="example">
+@prefix prov: <http://www.w3.org/ns/prov#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
-:c1
- prov:knownMembership [
- a prov:Membership;
- prov:member [
- a prov:KeyValuePair;
- prov:key "k1"^^xsd:string;
- prov:value :e1
- ], [
- a prov:KeyValuePair;
- prov:key "k2"^^xsd:string;
- prov:value :e2
- ]
- ];
-.
- </pre>
- </div>
-
+:c2 a prov:Collection .
+:c3 a prov:Collection .
+ prov:derivedByRemovalFrom :c2 ;
+ prov:qualifiedRemoval [ a prov:Removal ;
+ prov:collection :c2 ;
+ prov:removed "k1"^^xsd:string, "k3"^^xsd:string
+ ] .
+</pre>
</section>