a few improvements on LD Patch Intro and Semantics ldpatch
authorPierre-Antoine <pchampin@liris.cnrs.fr>
Wed, 19 Nov 2014 22:34:49 +0100
branchldpatch
changeset 886 53e7f5b2f6f5
parent 885 91b421e26b16
child 887 998408515484
a few improvements on LD Patch Intro and Semantics
ldpatch.html
--- a/ldpatch.html	Wed Nov 19 10:40:22 2014 -0500
+++ b/ldpatch.html	Wed Nov 19 22:34:49 2014 +0100
@@ -226,7 +226,7 @@
     <section class='informative' id='introduction'>
       <h1>Introduction</h1>
       <p>
-Linked Data "describes a method of publishing structured data so that it can be interlinked and become more useful. It builds upon standard Web technologies such as HTTP, RDF and URIs, but rather than using them to serve web pages for human readers, it extends them to share information in a way that can be read automatically by computers. This enables data from different sources to be connected and queried." (source Wikipedia).
+Linked Data “describes a method of publishing structured data so that it can be interlinked and become more useful. It builds upon standard Web technologies such as HTTP, RDF and URIs, but rather than using them to serve web pages for human readers, it extends them to share information in a way that can be read automatically by computers. This enables data from different sources to be connected and queried.” (source Wikipedia).
       </p>
       <p>
 This document defines the Linked Data Patch Format (LD Patch), a format for describing changes to apply to Linked Data. It is suitable for use with <a href="http://tools.ietf.org/html/rfc5789">HTTP PATCH</a> [[!rfc5789]], a method to perform partial modifications to Web resources. <!-- The "text/ldpatch" media type is prospectively used to identify such LD Patch documents.-->
@@ -236,7 +236,7 @@
       </p>
 
       <p id="relation-sparql-update">
-        The LD Patch format described in this document should be seen as an "assembly language" for updating <a href="http://www.w3.org/TR/rdf11-concepts/#section-rdf-graph">RDF Graphs</a> in a resource-centric fashion. It is the intention to confine its expressive power to an RDF diff with <a class="internalDFN" href="#pathological-graph">partial support for blank nodes</a> and <code>rdf:List</code> manipulations. For more powerful operations on RDF Graphs and Quad Stores, the LDP WG recommends the reader to consider <a href="http://www.w3.org/TR/sparql11-update/">SPARQL Update</a> [[sparql11-update]].
+        The LD Patch format described in this document should be seen as an “assembly language” for updating <a href="http://www.w3.org/TR/rdf11-concepts/#section-rdf-graph">RDF Graphs</a> in a resource-centric fashion. It is the intention to confine its expressive power to an RDF diff with <a class="internalDFN" href="#pathological-graph">partial support for blank nodes</a> and <code>rdf:List</code> manipulations. For more powerful operations on RDF Graphs and Quad Stores, the LDP WG recommends the reader to consider <a href="http://www.w3.org/TR/sparql11-update/">SPARQL Update</a> [[sparql11-update]].
       </p>
 
     </section>
@@ -244,7 +244,7 @@
     <section class='normative' id='language-features'>
       <h1>LD Patch Semantics</h1>
       <p>
-An LD Patch document 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 URIs. Then each statement either binds a variable to a matching node, or defines a modification on the graph.
+An LD Patch document is applied to a Linked Data resource identified by an URI (the <dfn>target URI</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 URIs. 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>.
       </p>
 
 
@@ -261,7 +261,9 @@
       <section id="node-matching-semantics">
         <h2><dfn>Node Matching Semantics</dfn></h2>
         <p>
-            LD Patch borrows much of its syntax and semantics from <a href="http://www.w3.org/TR/turtle/">Turtle</a> [[turtle]] and <a href="http://www.w3.org/TR/sparql11-query/">SPARQL</a> [[sparql11-query]] for describing nodes. <a class="internalDFN" href="#grammar-production-iri">IRI</a>s (either abbreviated or not) and <a class="internalDFN" href="#grammar-production-literal">literals</a> represent the corresponding node in the graph being patched. <a class="internalDFN" href="#grammar-production-BlankNode">Blank nodes</a>, on the other hand, pose a problem, as they have no global identifier. Indeed, blank node identifiers have their scope limited to the document in which they appear. As a consequence, <dfn id="blank-node-scoping">whenever blank node identifiers appears in an LD Patch document, it is understood to denote a <em>fresh</em> blank node</dfn>, that needs to be created in the patched RDF graph. They cannot interfere with existing blank nodes in the graph.
+            LD Patch borrows much of its syntax and semantics from <a href="http://www.w3.org/TR/turtle/">Turtle</a> [[turtle]] and <a href="http://www.w3.org/TR/sparql11-query/">SPARQL</a> [[sparql11-query]] for describing nodes. <a class="internalDFN" href="#grammar-production-iri">IRI</a>s (either abbreviated or not) and <a class="internalDFN" href="#grammar-production-literal">literals</a> represent the corresponding node 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, blank node identifiers have a limited scope, which in the case of LD Patch is the LD Patch document in which they appear. As a consequence, <dfn id="blank-node-scoping">any blank node identifier appearing in an LD Patch document is understood to denote a <em>fresh</em> blank node</dfn>, that needs to be created in the <a>target graph</a>. Therefore blank node identifiers in LD Patch cannot interfere with existing blank nodes in the <a>target graph</a>.
         </p>
         <p>
 In order to be able to address blank nodes already present in the graph, LD Patch has two mechanisms: <a>Bind</a>ing a variable to a blank node reachable with a <a>path expression</a>, and <a>UpdateList</a> to deal with those blank nodes that constitute RDF collections. There are cases where those mechanisms will not be able to unambiuously 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.
@@ -271,24 +273,22 @@
       <section id="path-expression">
         <h2><dfn>Path Expression</dfn></h2>
         <p>
-            LD Patch uses path expressions to describe possible routes through a graph between two graph nodes. The main goal is to allow addressing a blank node by “walking” the arcs of the graph from an already identified node. A path is composed by a number of <dfn>Step</dfn>s, which can be of three kinds:
+LD Patch uses path expressions to describe possible routes through the <a>target graph</a> between two graph nodes. The main goal is to allow addressing a blank node by “walking” the arcs of the graph from an already identified node. A path is a sequence of <dfn>Step</dfn>s and <dfn>Constraint</dfn>s, which are applied in order to a set of nodes <var>ns</var>. <a>Step</a>s can be of three kinds:
         </p>
         <ul>
-          <li>A <dfn>StepForward</dfn> is defined by a URI, and consists in following outgoing arcs having that URI as their predicate.</li>
-          <li>A <dfn>StepBackward</dfn> is defined by a URI preceded with the caret ("<code>^</code>") sign, and consists in following incoming arcs having that URI as their predicate.</li>
-          <li>A <dfn>StepAt</dfn> is defined by an integer <i>n</i>, and consists in following <i>n</i> <code>rdf:rest</code> arcs and one <code>rdf:first</code> arc in order to reach the corresponding member of an RDF collection.</li>
+          <li>A <dfn>StepForward</dfn> is defined by a URI <var>p</var>, and consists in following the corresponding outgoing arcs: <var>ns</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>ns</var>.</li>
+          <li>A <dfn>StepBackward</dfn> is defined by a URI <var>p</var> preceded with the caret ("<code>^</code>") sign, and consists in following the corresponding incoming arcs: <var>ns</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>ns</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 URIs.</li>
         </ul>
         <p>
-Note that each step can, in general, result in <em>several</em> matching nodes, as a given node can have several (incoming or outgoing) arcs with the same predicate.
-        </p>
-        <p>
-            A <a>Path Expression</a> may also contains <dfn>constraint</dfn>s, which are of two kinds:
+<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, ensures that the result of the path so far contains exactly one node. In case a <code>!</code> contraint is not successfully met, the whole request MUST fail.</li>
-          <li>A <dfn>filter</dfn>, consisting of a path in square brackets ("<code>[</code>", "<code>]</code>"), keeps only from the matching nodes so far those that “satisfy” the enclosed path, i.e. those from which the enclosed path reaches at least one node.</li>
-          <li>Additionally, the path in a <tref>filter</tref> can be followed by the equal ("<code>=</code>") sign and a <tref>Value</tref>. In that case, only the node for which that particular value is reached through the enclosed path are kept.</li>
+          <li>A <dfn>Unicity constraint</dfn>, described by the <em>bang</em> ("<code>!</code>") character, checks that <var>ns</var> contains exactly one node. If this is not the case, <var>ns</var> is replaced by the empty set (which amounts for 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>ns</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>ns</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>.
         <pre class='example'>
@@ -309,7 +309,7 @@
         <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 bound variable has a global scope. Use 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 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: use 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>
@@ -331,7 +331,7 @@
         <section id="add-statement">
           <h2><dfn>Add</dfn></h2>
           <p>
-              The <a>Add</a> operation is used to add or append new RDF triples to the existing graph. To add new RDF triples, the operation requires valid <a href="http://www.w3.org/TR/turtle/#sec-grammar-grammar">Turtle syntax</a> between curly braces – i.e. <code>{</code> and <code>}</code>. <a>Var</a>iables can also be used, provided they have been previously defined.
+The <a>Add</a> operation is used to append new RDF triples to the <a>target graph</a>. To add new RDF triples, the operation requires valid <a href="http://www.w3.org/TR/turtle/#sec-grammar-grammar">Turtle syntax</a> between curly braces – i.e. <code>{</code> and <code>}</code>. <a>Var</a>iables can also be used, provided they have been previously defined.
           <pre class='example'>
 Add { 
     &lt;#&gt; profile:first_name "Timothy" ;
@@ -346,7 +346,7 @@
         <section id="delete-statement">
           <h2><dfn>Delete</dfn></h2>
           <p>
-              The <a>Delete</a> operation is used to remove one or more RDF triples from the existing graph. The syntax for the <a>Delete</a> operation requires valid <a href="http://www.w3.org/TR/turtle/#sec-grammar-grammar">Turtle syntax</a> between curly braces – i.e. <code>{</code> and <code>}</code>. Similar to the <a>Add</a> operation, variables can also be used within the <a>Delete</a> operation. Blank nodes are allowed in <a>Delete</a> statements but <a href="#blank-node-scoping">they remain scoped to the LD Patch document</a>, not the graph being patched.
+              The <a>Delete</a> operation is used to remove one or more RDF triples from the <a>target graph</a>. The syntax for the <a>Delete</a> operation requires valid <a href="http://www.w3.org/TR/turtle/#sec-grammar-grammar">Turtle syntax</a> between curly braces – i.e. <code>{</code> and <code>}</code>. Similar to the <a>Add</a> operation, variables can also be used within the <a>Delete</a> operation. 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.
 
           <pre class='example'>
 Delete { &lt;#&gt; profile:first_name "Tim" } .
@@ -359,7 +359,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 existing graph, having a matching <a class="internalDFN" href="#grammar-production-subject">subject</a> that corresponds to either an IRI or a previously bound varible.
+              The <a>Cut</a> operation is used to remove one or more triples from the <a>target graph</a>, having a matching <a class="internalDFN" href="#grammar-production-subject">subject</a> that corresponds to either an IRI or a previously bound varible.
           <pre class='example'>
 Bind ?workLocation &lt;#&gt; /schema:workLocation .
 Cut ?workLocation.
@@ -417,7 +417,7 @@
 
         <ul>
             <li id="bind-unique-match">If a <code>Bind</code> statement fails to match exactly one node, then a 422 (Unprocessable Entity) status MUST be returned.</li>
-            <li id="unicity-constraint-violated">If a <a>unicity constraint</a> is violated, then a 422 (Unprocessable Entity) status MUST be returned.</li>
+            <li id="unicity-constraint-violated">If a <a>Unicity constraint</a> is violated, then a 422 (Unprocessable Entity) status MUST be returned.</li>
             <li id="cut-nothing">If a <a>Cut</a> operation fail to remove any triple, then a 422 (Unprocessable Entity) status MUST be returned.</li>
             <li id="delete-non-existing-triple">If a <a>Delete</a> attempts to remove a non-existing triple, then a 422 (Unprocessable Entity) status MUST be returned.</li>
             <li id="updatelist-non-list-argument">If the <a class="internalDFN" href="#grammar-production-subject">subject</a> and <a class="internalDFN" href="#grammar-production-predicate">predicate</a> provided to a <a>UpdateList</a> operation fail to match a collection, then a 422 (Unprocessable Entity) status MUST be returned.</li>
@@ -433,12 +433,12 @@
       <section id="pathological-graph">
         <h2><dfn>Pathological Graph</dfn></h2>
           <p>
-            There exists a particular case which LD Patch is not able to address. Given an RDF graph <em>G</em>, a blank node <em>b</em> is said to be unambiguous in <em>G</em> if there exists a couple <em>(n, p)</em> where
+            There exists a particular case which LD Patch is not able to address. Given an RDF graph <var>G</var>, a blank node <var>b</var> is said to be unambiguous in <var>G</var> if there exists a couple <var>(n, p)</var> where
           <ul>
-            <li><em>n</em> is a URI or a literal</li>
-            <li><em>p</em> is an LD <a>Path Expression</a></li>
+            <li><var>n</var> is a URI or a literal</li>
+            <li><var>p</var> is an LD <a>Path Expression</a></li>
           </ul>
-          such that applying <em>p</em> to <em>n</em> results in the singleton set <em>{b}</em>.
+          such that applying <var>p</var> to {<var>n</var>} results in the singleton set {<var>b</var>}.
           </p>
 
           <p>