Added more explanations for Add and prefixes. Fixed some typos. ldpatch
authorAndrei Sambra <andrei.sambra@gmail.com>
Thu, 20 Nov 2014 13:42:01 -0500
branchldpatch
changeset 893 69d062ab6fc8
parent 892 25b18ffbdebe
child 894 3794fe350546
Added more explanations for Add and prefixes. Fixed some typos.
ldpatch.html
--- a/ldpatch.html	Thu Nov 20 17:53:51 2014 +0100
+++ b/ldpatch.html	Thu Nov 20 13:42:01 2014 -0500
@@ -410,21 +410,21 @@
     <section class='normative' id='semantics'>
       <h1>LD Patch Semantics</h1>
       <p>
-An LD Patch document is applied to a Linked Data resource identified by an IRI (the <dfn>target IRI</dfn>) and represented by an RDF graph (the <dfn>target graph</dfn>). It is made of a prologue and a list of statements, where the order is relevant. The prologue declares a number of <a>prefixes</a> used to abbreviate IRIs. Then each statement either binds a variable to a matching node from the <a>target graph</a>, or specified a modification on the <a>target graph</a>.
+An LD Patch document is applied to a Linked Data resource identified by an IRI (the <dfn>target IRI</dfn>) and represented by an RDF graph (the <dfn>target graph</dfn>). It is made of a prologue and a list of statements, where the order <strong>must be respected</strong>. The prologue declares a number of <a>prefixes</a> used to abbreviate IRIs. Then, each statement either binds a variable to a matching node from the <a>target graph</a>, or specifies a modification on the <a>target graph</a>.
       </p>
 
 
       <section id="prefixes">
         <h2><dfn>Prefixes</dfn></h2>
         <p>
-@@ TODO should defer to Turtle's syntax. Not only Prefixes, but everything in http://www.w3.org/TR/2014/REC-turtle-20140225/#language-features. Proposed section name: Inherited from (the?) Turtle language. @@
-An LD Patch document starts with a preamble that can contain a number of <code>@prefix</code> directives (similar to the <a href="http://www.w3.org/TR/turtle/#prefixed-name">same directive in Turtle</a> [[Turtle]]). They allow declaring a short prefix name for a long prefix of repeated IRIs. This is useful for many RDF vocabularies that are all defined in nearby namespace IRIs [[!rdf11-concepts]].
+<!-- @@ TODO should defer to Turtle's syntax. Not only Prefixes, but everything in http://www.w3.org/TR/2014/REC-turtle-20140225/#language-features. Proposed section name: Inherited from (the?) Turtle language. @@ -->
+An LD Patch document starts with a preamble that MAY contain a number of <code>@prefix</code> directives (similar to the <a href="http://www.w3.org/TR/turtle/#prefixed-name">same directive in Turtle</a> [[Turtle]]). They allow declaring a short prefix name for a long prefix of repeated IRIs. This is useful for many RDF vocabularies that are all defined in nearby namespace IRIs [[!rdf11-concepts]]. Note: the <code>@prefix</code> keyword is <em>case sensitive</em>.
         </p>
         <p>
 A prefix directive is defined by a prefix <var>p</var> and an IRI <var>ns</var>. Any further <a class="internalDFN" href="#grammar-production-PrefixedName">PrefixedName</a> in the LD Patch document whose <a class="internalDFN" href="#grammar-production-PNAME_NS">PNAME_NS</a> is <var>p</var> MUST be interpreted as the IRI formed by concatenating <var>ns</var> with the <a class="internalDFN" href="#grammar-production-PrefixedName">PrefixedName</a>'s <a class="internalDFN" href="#grammar-production-PN_LOCAL">PN_LOCAL</a>.
         </p>
         <p>
-For example, after the directive <code>@prefix foo: &lt;http://example.org/ns#&gt;</code> is defined, any <a class="internalDFN" href="#grammar-production-PrefixedName">PrefixedName</a> that starts with <code>foo:</code> can be interpreted as an IRI, <i>e.g.</i> <code>foo:bar</code> is a shorthand for the IRI <code>&lt;http://example.org/ns#bar&gt;</code>.
+For example, once the directive <code>@prefix foo: &lt;http://example.org/ns#&gt;</code> is defined, any <a class="internalDFN" href="#grammar-production-PrefixedName">PrefixedName</a> that starts with <code>foo:</code> can be interpreted as an IRI, <i>e.g.</i> <code>foo:bar</code> is a shorthand for the IRI <code>&lt;http://example.org/ns#bar&gt;</code>.
         </p>
       </section>
 
@@ -434,24 +434,24 @@
 LD Patch borrows much of its syntax and semantics from <a href="http://www.w3.org/TR/turtle/">Turtle</a> [[Turtle]] for describing nodes and triples. Especially, whenever production rules <a class="internalDFN" href="#grammar-production-triples">triples</a> or <a class="internalDFN" href="#grammar-production-collection">collection</a> are used, Turtle semantics must be applied to parse them as a set of triples that we call an <dfn>argument graph</dfn>.
         </p>
         <p>
-There are however a few points that need to be highlighted in the way LD-Patch parses an <a>argument graph</a> compared to Turtle:
+There are however a few points that need to be highlighted in the way LD Patch parses an <a>argument graph</a> compared to Turtle:
         </p>
         <ul>
           <li>
             The base IRI used to resolve relative IRIs MUST be <a>target IRI</a>.
           </li>
           <li>
-            LD Patch allows <a href="#grammar-production-Var">Var</a>iables in subject or object position. A variable MUST be <a title="bind">bound</a> prior to its first use in the LD Patch Document, and it must be replaced by the last node to which it has been bound (in case it appears in several <a>Bind</a> statements).
+            LD Patch allows <a href="#grammar-production-Var">Var</a>iables in subject or object positions. A variable MUST be <a title="bind">bound</a> prior to its first use in the LD Patch Document, and it must be replaced by the last node to which it has been bound (in case it appears in several <a>Bind</a> statements).
           </li>
           <li>
             <dfn id="blank-node-scoping">The scope of <a class="internalDFN" href="#grammar-production-BlankNode">Blank nodes</a> identifiers is the whole LD Patch document.</dfn> Hence several argument graphs can share the same blank nodes across statements.
           </li>
         </ul>
         <p>
-As IRIs and Literals have a global scopes, such nodes in an <a>argument graph</a> represent the same resource as in the <a>target graph</a>. <a class="internalDFN" href="#grammar-production-BlankNode">Blank nodes</a>, on the other hand, pose a problem, as they have no global identifier. Indeed, the scope of blank node identifiers is limited to the LD Patch document in which they appear. As a consequence, any blank node identifier appearing in an LD Patch document is understood to denote a <em>fresh</em> blank node, distinct from any node initially present in the <a>target graph</a>. Therefore blank node identifiers in LD Patch cannot interfere with pre-existing blank nodes in the <a>target graph</a>.
+As IRIs and Literals have global scopes, such nodes in an <a>argument graph</a> represent the same resource as in the <a>target graph</a>. <a class="internalDFN" href="#grammar-production-BlankNode">Blank nodes</a>, on the other hand, pose a problem, as they have no global identifiers. Indeed, the scope of blank node identifiers is limited to the LD Patch document in which they appear. As a consequence, any blank node identifier appearing in an LD Patch document is understood to denote a <em>fresh</em> blank node, distinct from any node initially present in the <a>target graph</a>. Therefore blank node identifiers in LD Patch cannot interfere with pre-existing blank nodes in the <a>target graph</a>.
         </p>
         <p>
-However, LD Patch provides mechanisms to address those pre-existing blank nodes: <a>bind</a>ing a variable to a blank node reachable with a <a>path expression</a>, <a>cut</a>ting a whole tree made of blank nodes, or using <a>UpdateList</a> to deal with those blank nodes that constitute RDF collections. There are cases where those mechanisms will not be able to unambiguously address a given blank node, but those cases are deemed <a href="#pathological-graph">pathological</a>, and are out of the scope of this specification.
+However, LD Patch provides mechanisms to address those pre-existing blank nodes: <a>bind</a>ing a variable to a blank node reachable through a <a>path expression</a>, <a>cut</a>ting a whole tree made of blank nodes, or using <a>UpdateList</a> to deal with those blank nodes that constitute RDF collections. There are cases where those mechanisms will not be able to unambiguously address a given blank node, but those cases are deemed <a href="#pathological-graph">pathological</a>, and are out of the scope of this specification.
         </p>
       </section>
 
@@ -463,19 +463,19 @@
         <ul>
           <li>A <dfn>StepForward</dfn> is defined by an IRI <var>p</var>, and consists in following the corresponding outgoing arcs: <var>N</var> is replaced by the set of the objects of all triples from the <a>target graph</a> with predicate <var>p</a> and their subject in <var>N</var>.</li>
           <li>A <dfn>StepBackward</dfn> is defined by an IRI <var>p</var> preceded with the caret ("<code>^</code>") sign, and consists in following the corresponding incoming arcs: <var>N</var> is replaced by the set of the subjects of all triples from the <a>target graph</a> with predicate <var>p</var> and their object in <var>N</var>.</li>
-          <li>A <dfn>StepAt</dfn> is defined by an integer <i>n</i>, and consists in following <var>n</var> <code>rdf:rest</code> arcs and one <code>rdf:first</code> arc in order to reach the corresponding member of an RDF collection. It is equivalent to a sequence of <var>n</var>+1 <a>StepForward</a>s wit the the corresponding IRIs.</li>
+          <li>A <dfn>StepAt</dfn> is defined by an integer <i>n</i>, and consists in following <var>n</var> <code>rdf:rest</code> arcs and one <code>rdf:first</code> arc in order to reach the corresponding member of an RDF collection. It is equivalent to a sequence of <var>n</var>+1 <a>StepForward</a>s with the corresponding IRIs.</li>
         </ul>
         <p>
 <a>Constraint</a>s can be of two kinds:
         </p>
         <ul>
-          <li>A <dfn>Unicity constraint</dfn>, described by the <em>bang</em> ("<code>!</code>") character, checks that <var>N</var> contains exactly one node. If this is not the case, <var>N</var> is replaced by the empty set (which amounts for the Path Expression to fail).</li>
+          <li>A <dfn>Unicity constraint</dfn>, described by the <em>bang</em> ("<code>!</code>") character, checks that <var>N</var> contains exactly one node. If this is not the case, <var>N</var> is replaced by the empty set (which triggers the Path Expression to fail).</li>
           <li>A <dfn>Filter</dfn>, consisting of a path <var>p</var> in square brackets ("<code>[</code>", "<code>]</code>"), keeps only nodes that “satisfy” the enclosed path, i.e. those from which the enclosed path reaches at least one node: <var>N</var> is replaced by the subset of its elements <var>n</var> such that applying <var>p</var> to {<var>n</var>} results in a non-empty set. </li>
           <li>Additionally, the path in a <a>filter</a> can be followed by the equal ("<code>=</code>") sign and a <tref>Value</tref> <var>v</var>. In that case, only the node for which that particular value is reached through the enclosed path are kept: <var>N</var> is replaced by the subset of its elements <var>n</var> such that applying <var>p</var> to {<var>n</var>} results in a set containing <var>v</var>.</li>
         </ul>
 
         <p>
-The following path expression (taken from the <a href="#examples">Examples section</a>) will look for all the events matching the predicate <code>schema:performerIn</code>, keeping only the one matching the URL <code>&lt;https://www.w3.org/2012/ldp/wiki/F2F5&gt;</code>.
+The following path expression (taken from the <a href="#examples">Examples section</a>) will look for all the events matching the predicate <code>schema:performerIn</code>, keeping only the one matching the IRI <code>&lt;https://www.w3.org/2012/ldp/wiki/F2F5&gt;</code>.
         <pre class='example'>
 /schema:performerIn[/schema:url = &lt;https://www.w3.org/2012/ldp/wiki/F2F5&gt;]
         </pre>
@@ -494,13 +494,13 @@
         <section id="bind-statement">
           <h2><dfn>Bind</dfn></h2>
           <p>
-              The <a>Bind</a> operation is used to create a new variable by binding or assigning an RDF Term to the variable. The process results in a variable being bound to exactly one node. The scope of the bound variable is the entire LD Patch document: uses of a given variable name anywhere in an LD Patch document identifies the same variable, although variables can be overriden in subsequent <a>Bind</a> statements. Following the example above, the <a>Bind</a> operation creates a new variable called <code>event</code>, starting from the RDF Term <code>&lt;#&gt;</code> and following the path expression <code>/schema:performerIn[/schema:url = &lt;https://www.w3.org/2012/ldp/wiki/F2F5&gt;]</code> in order to identify the RDF Term to which this variable will be bound to – i.e. <code>_:b2</code>.
+              The <a>Bind</a> operation is used to create a new variable by assigning an RDF Term to the variable. The process results in a variable being bound to exactly one node. The scope of the bound variable is the entire LD Patch document: uses of a given variable name anywhere in an LD Patch document identifies the same variable, although variables can be overriden in subsequent <a>Bind</a> statements. Following the example above, the <a>Bind</a> operation creates a new variable called <code>event</code>, starting from the RDF Term <code>&lt;#&gt;</code> and following the path expression <code>/schema:performerIn[/schema:url = &lt;https://www.w3.org/2012/ldp/wiki/F2F5&gt;]</code> in order to identify the RDF Term to which this variable will be bound to – i.e. <code>_:b2</code>.
           <pre class='example'>
 Bind ?event &lt;#&gt; /schema:performerIn[/schema:url = &lt;https://www.w3.org/2012/ldp/wiki/F2F5&gt;] .
           </pre>
           </p>
           <p>
-              The <a>Bind</a> operation is defined by three components: <a>Var</a>, <a>Value</a> and <a title="path expression">Path</a>, the last component being optional (it is then equivalent to the empty path).
+              The <a>Bind</a> operation is defined by three components: <a>Var</a>, <a>Value</a> and <a title="path expression">Path</a>, the last component being optional (can be considered equivalent to the empty path).
           </p>
           <p>
               <dfn>Var</dfn> contains a unique name for the new variable. Variables are prefixed by the "<code>?</code>" character, which is not part of the variable name.
@@ -519,7 +519,7 @@
 The <a>Add</a> operation is used to append new RDF triples to the <a>target graph</a>.
           </p>
           <p>
-It has a single argument: an <a>argument graph</a> <var>g</var>. All triples in <var>g</var> must be added to the <var>target graph</var>.
+It has a single argument: an <a>argument graph</a> <var>g</var>. All triples in <var>g</var> must be added to the <var>target graph</var>. Even if an argument graph contains one or more triples that already exist in the target graph, the Add operation MUST NOT fail.
           <pre class='example'>
 Add { 
     &lt;#&gt; profile:first_name "Timothy" ;
@@ -537,7 +537,7 @@
 The <a>Delete</a> operation is used to remove RDF triples from the <a>target graph</a>.
           </p>
           <p>
-It has a single argument: an <a>argument graph</a> <var>g</var>. All triples in <var>g</var> must be removed to the <var>target graph</var>. It MUST fail if one of those triples does not exists in the <a>target graph</a>. Blank nodes identifiers are allowed in <a>Delete</a> statements but <a href="#blank-node-scoping">they remain scoped to the LD Patch document</a>, so they can only match a blank node previously added by the same LD Patch document.
+It has a single argument: an <a>argument graph</a> <var>g</var>. All triples in <var>g</var> must be removed from the <var>target graph</var>. It MUST fail if one of those triples does not exists in the <a>target graph</a>. Blank nodes identifiers are allowed in <a>Delete</a> statements but <a href="#blank-node-scoping">they remain scoped to the LD Patch document</a>, so they can only match a blank node previously added by the same LD Patch document.
           </p>
           <pre class='example'>
 Delete { &lt;#&gt; profile:first_name "Tim" } .
@@ -550,7 +550,7 @@
         <section id="cut-statement">
           <h2><dfn>Cut</dfn></h2>
           <p>
-              The <a>Cut</a> operation is used to remove one or more triples from the <a>target graph</a> connected to a specific node (either a <a>IRI</a>, or a previously bound variable). The triples being removed correspond to the <a href="http://en.wikipedia.org/wiki/Connectivity_%28graph_theory%29">connected graph</a> whose nodes were accessible from the given node, as well as the triples having this node in the object position.
+              The <a>Cut</a> operation is used to remove one or more triples from the <a>target graph</a> connected to a specific node (either an <a>IRI</a>, or a previously bound variable). The triples being removed correspond to the <a href="http://en.wikipedia.org/wiki/Connectivity_%28graph_theory%29">connected graph</a> whose nodes were accessible from the given node, as well as the triples having this node in the object position.
           <pre class='example'>
 Cut ?workLocation .
           </pre>
@@ -560,7 +560,7 @@
         <section id="update-list-statement">
           <h2><dfn>UpdateList</dfn></h2>
           <p>
-              The <a>UpdateList</a> operation is used to update the members of an <a href="http://www.w3.org/TR/rdf-schema/#ch_collectionvocab">RDF collection</a>. The first two arguments are the <a class="internalDFN" href="#grammar-production-subject">subject</a> (up to <a>var</a>iable binding) and <a class="internalDFN" href="#grammar-production-predicate">predicate</a> of the RDF triple that unambiguously identifies the target collection to be updated: it is in the object position of this triple. The third argument specifies which <a>Slice</a> will be replaced by a new collection: this is the fourth argument of the statement.
+              The <a>UpdateList</a> operation is used to update the members of an <a href="http://www.w3.org/TR/rdf-schema/#ch_collectionvocab">RDF collection</a>. The first two arguments are the <a class="internalDFN" href="#grammar-production-subject">subject</a> (up to <a>var</a>iable binding) and <a class="internalDFN" href="#grammar-production-predicate">predicate</a> of the RDF triple that unambiguously identify the target collection to be updated: it is in the object position of this triple. The third argument specifies which <a>Slice</a> will be replaced by a new collection: this is the fourth argument of the statement.
           </p>
 
           <p>
@@ -1072,6 +1072,9 @@
             TAG Finding 3 June 2002 (Revised 4 September 2002)</dd>
 
         <p>The Internet Media Type / MIME Type for LD Patch is "text/ldpatch".</p>
+        <div class="ldp-issue">
+          Pending discussion/registration with IETF.
+        </div>
 
         <p>It is recommended that LD Patch files have the extension ".ldp" (all lowercase) on all platforms.</p>
         <div class="ldp-issue">