Added Identifier Conventions section
authorStephan Zednik <zednis@rpi.edu>
Thu, 18 Apr 2013 00:39:33 -0600
changeset 6213 f99a7ea128c1
parent 6212 bf218fcb4f7d
child 6214 5561e8429610
Added Identifier Conventions section
xml/prov-xml.html
--- a/xml/prov-xml.html	Wed Apr 17 21:31:42 2013 -0600
+++ b/xml/prov-xml.html	Thu Apr 18 00:39:33 2013 -0600
@@ -434,7 +434,7 @@
 &lt;/prov:document&gt;
 </pre>
 <p>When an extension xml-type is used a prov-"type" may be inferred.</p>
-<p>Use of the <code>prov:type</code> xml-element to state prov-"type" information, even for cases where type information is determinable from xml-types, is highly encouraged.</p> 
+<p>Explicit type declarations made using the <code>prov:type</code> xml-element may be easier for some encoding transformation tools (such as XSLT) to process, therefore use of the <code>prov:type</code> xml-element is highly encouraged even in cases where prov-"type" information is determinable from schema defined ComplexTypes.</p> 
 <pre class="example" title="type information using schema defined types - type inferences" ignore>
 &lt;prov:document
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -487,6 +487,21 @@
 &lt;/prov:document&gt;
 </pre>
 </section> <!-- end type-conventions-xsi-type -->
+</section> <!-- end type-conventions -->
+
+<section id="identifier-conventions">
+<h3>Identifier Conventions</h3>
+<p>[[PROV-DM]] defines a PROV Identifier as a qualified name with the following definition:</p> 
+<span class="glossary-ref" data-ref="glossary-qualifiedName" data-withspan="true"></span>
+<p>[[PROV-DM]] also mandates that all qualified names be mappable to a URI by concatenating the namespace URI with a local name.</p>
+
+<p>PROV-XML uses the <code>prov:id</code> xml-attribute to denote a PROV Identifier and the <code>prov:ref</code> xml-attribute to denote a reference-by-id to an instance of a prov-"type" or prov-"relation" which has a matching PROV Identifier.  The value of <code>prov:ref</code> must be a valid PROV Identifier, but there is no requirement that for every <code>prov:ref</code> a corresponding <code>prov:id</code> must be known to exist.</p>
+
+<p>PROV-XML defines the type of both the <code>prov:id</code> and <code>prov:ref</code> xml-attributes to be <code>xsd:QName</code> as that is the XSD datatype that most closely matches the qualified name definition by [[PROV-DM]].  Care should be taken when generating PROV identifier values in PROV-XML such that there is a known mapping to a URI.</p>
+
+<div class="note">
+<p>The xsd:QName datatype is more restrictive than the QualifiedName defined in [[PROV-N]] (e.g. PROV-N allows local names to start with numbers), therefore valid identifier values in [[PROV-N]] serializations have to potential to not be valid identifier values in PROV-XML. It is recommended to enhance interoperability that provenance users strive to always use identifier schemes that map to valid xsd:QNames and URIs.</p>
+</div>
 
 </section>
 
@@ -2011,7 +2026,7 @@
 <section id="attribute-Identifier">
 <h4>Identifier</h4>
 <span class="glossary-ref" data-ref="glossary-identifier" data-withspan="true"></span>
-<p>The identifier attribute is used to identify instances of prov-"types" or prov-"relations".</p>
+<p>The xml-attribute used to identify an instances of a prov-"type" or prov-"relation".</p>
 <pre class="schema-attribute" attribute="prov:id" schemaType="xs:QName">
 &lt;xs:attribute xmlns:xs="http://www.w3.org/2001/XMLSchema" name="id" type="xs:QName"/&gt;
 </pre>
@@ -2035,7 +2050,7 @@
 <section id="attribute-Reference">
 <h4>Reference</h4>
 <span class="glossary-ref" data-ref="glossary-identifier" data-withspan="true"></span>
-<p>A reference-by-id to a PROV entity, activity, agent, or relation.</p>
+<p>A xml-attribute that denotes a reference-by-id to an instance of a prov-"type" or prov-"relation".</p>
 <pre class="schema-attribute" attribute="prov:ref" schemaType="xs:QName">
 &lt;xs:attribute ref="prov:ref" use="required" /&gt;
 </pre>
@@ -2406,6 +2421,7 @@
 <section>
 <h3>Change Log Since WD Working Draft 12 March 2013</h3>
 <ul>
+<li>Added Identifier Conventions section</li>
 <li>Updated naming conventions to clarify distinction between PROV elements, attributes, and types and XML elements, attributes, and types.</li>
 <li>Added links to PROV-DM term/concepts in Table 1.</li>
 <li>Removed inline schema, added links to published schemas.</li>