--- a/ldpatch.html Mon Nov 17 10:04:44 2014 -0500
+++ b/ldpatch.html Tue Nov 18 13:30:44 2014 -0500
@@ -239,114 +239,31 @@
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 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>
+
+ <section class='normative' id='language-features'>
+ <h1>LD Patch Syntax</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 <tref>prefixes</tref> used to abbreviate URIs. Then each statement either binds a variable to a matching node, or defines a modification on the graph.
+ </p>
+ <section id="operational-semantics">
+ <h2><tdef>HTTP Semantics</tdef></h2>
- <h2 id="intro-example">Example</h2>
+ <p>
+LD Patch abides to the semantics of the <a href="http://tools.ietf.org/html/rfc5789" target="_blank">HTTP PATCH method</a>, in that the server "MUST apply the entire set of changes atomically and never provide (e.g., in response to a GET during this operation) a partially modified representation. If the entire patch document cannot be successfully applied (e.g., one of the instructions has failed), then the server MUST NOT apply any of the changes".
+
+@@TODO: describe from an HTTP perspective what happens when a patch operation fails.
+ </p>
+ </section>
<p>
- The following RDF Graph will be used as an example through this specification. It describes the relation between a person named Tim Berners-Lee (denoted by <code><http://example.org/timbl#></code>) and two events he attended.
</p>
- <pre class='example'>
-@prefix schema: <http://schema.org/> .
-@prefix profile: <http://ogp.me/ns/profile#> .
-@prefix ex: <http://example.org/vocab#> .
-@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
-<http://example.com/timbl#> a schema:Person ;
- schema:alternateName "TimBL" ;
- profile:first_name "Tim" ;
- profile:last_name "Berners-Lee" ;
- schema:workLocation [ schema:name "W3C/MIT" ] ;
- schema:performerIn _:b1, _:b2 ;
- ex:preferredLanguages ( "en" "fr" ).
-
-_:b1 schema:name "F2F5 - Linked Data Platform" ;
- schema:url <https://www.w3.org/2012/ldp/wiki/F2F5> .
-
-_:b2 a schema:Event ;
- schema:name "TED 2009" ;
- schema:startDate "2009-02-04" ;
- schema:url <http://conferences.ted.com/TED2009/> .
- </pre>
- <p>
-The following is an example HTTP Patch request, conveying an LD Patch document:
- </p>
- <pre class='example'>
-PATCH /timbl HTTP/1.1
-Host: example.org
-Content-Length: 478
-Content-Type: text/ldpatch
-If-Match: "abc123"
-
-@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
-@prefix schema: <http://schema.org/> .
-@prefix profile: <http://ogp.me/ns/profile#> .
-@prefix ex: <http://example.org/vocab#> .
-
-Delete <#> profile:first_name "Tim" .
-Add <#> profile:first_name "Timothy" .
-
-UpdateList <#> ex:preferredLanguages 1..2 ( "fr-CH" ) .
-
-Bind ?event <#> /schema:performerIn[/schema:url = <https://www.w3.org/2012/ldp/wiki/F2F5>] .
-Add ?event rdf:type schema:Event .
-Bind ?ted <http://conferences.ted.com/TED2009/> /^schema:url! .
-Delete ?ted schema:startDate "2009-02-04".
-Add ?ted schema:location _:loc .
-Add _:loc schema:name "Long Beach, California" .
-Add _:loc schema:geo _:geo .
-Add _:geo schema:latitude "33.7817" .
-Add _:geo schema:longitude "-118.2054" .
- </pre>
- <p>
- This example introduces most features of the LD Patch format: <code>@prefix</code> and prefixed names, the <tref>Add</tref>, <tref>Delete</tref> and <tref>UpdateList</tref> operations, the <tref>Bind</tref>-ing mechanism and blank node creation. The "text/ldpatch" media type is <a href="#media-registration">prospectively</a> used to identify such LD Patch documents.
- </p>
- <p>
-The following is the resulting (patched) document.
- </p>
- <pre class='example'>
-@prefix schema: <http://schema.org/> .
-@prefix profile: <http://ogp.me/ns/profile#> .
-@prefix ex: <http://example.org/vocab#> .
-
-<http://example.com/timbl#> a schema:Person ;
- schema:alternateName "TimBL" ;
- profile:first_name "Timothy" ;
- profile:last_name "Berners-Lee" ;
- schema:workLocation [ schema:name "W3C/MIT" ] ;
- schema:performerIn _:b1, _:b2 ;
- ex:preferredLanguages ( "en" "fr-CH" ).
-
-_:b1 a schema:Event ;
- schema:name "F2F5 - Linked Data Platform" ;
- schema:url <https://www.w3.org/2012/ldp/wiki/F2F5> .
-
-_:b2 a schema:Event ;
- schema:name "TED 2009" ;
- schema:url <http://conferences.ted.com/TED2009/> ;
- schema:location [
- schema:name "Long Beach, California";
- schema:geo [ schema:latitude "33.7817" ; schema:longitude "-118.2054" ]
- ] .
- </pre>
-
-
- </section>
-
-
-
- <section class='informative' id='language-features'>
- <h1>LD Patch format</h1>
- <p>
-A LD Patch document is made of a prologue and a list of statements, where the order is relevant. The prologue declares a numver of <tref>prefixes</tref> used to abbreviate URIs. Then each statement either binds a variable to a matching node, or defines a modification on the graph.
- </p>
- <p>
-
- </p>
<section id="prefixes">
<h2><tdef>Prefixes</tdef></h2>
<p>
-LD Patch offers the possibility to abbreviate URIs by using Turtle's <i>@prefix</i> directive that allows declaring a short prefix name for a long prefix of repeated URIs. This is useful for many RDF vocabularies that are all defined in nearby namespace URIs, possibly using XML's namespace mechanism that works in a similar fashion.
+LD Patch offers the possibility to abbreviate URIs by using <a href="http://www.w3.org/TR/turtle/">Turtle</a>'s <i>@prefix</i> directive that allows declaring a short prefix name for a long prefix of repeated URIs. This is useful for many RDF vocabularies that are all defined in nearby namespace URIs [[!rdf11-concepts]], possibly using XML's namespace mechanism [[!xml-names11]] that works in a similar fashion.
</p>
<p>
Once a prefix such as <code>@prefix foo: <http://example.org/ns#></code> is defined, any mention of a URI later in the document may use a <tref>PrefixedName</tref> that starts with <code>foo:</code> to stand for the longer URI. So for example, the <tref>PrefixedName</tref> <code>foo:bar</code> is a shorthand for the URI <code><http://example.org/ns#bar></code>.
@@ -354,62 +271,17 @@
</section>
<section id="node-matching-semantics">
- <h2><tdef>Node matching semantics</tdef></h2>
+ <h2><tdef>Node Matching Semantics</tdef></h2>
<p>
-LD Patch borrows much of its syntax to <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. IRIs (either abbreviated or not) and literals represent the corresponding node in the graph being patched. Blank nodes, 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, whenever a blank node identifiers appears in an LD Patch document, it is understood to denote a <em>fresh</em> blank node, 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 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. IRIs (either abbreviated or not) and literals represent the corresponding node in the graph being patched. Blank nodes, 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, whenever blank node identifiers appears in an LD Patch document, it is understood to denote a <em>fresh</em> blank node, that needs to be created in the patched RDF graph. They cannot interfere with existing blank nodes in the graph.
</p>
<p>
- In order to be able to address blank nodes already present in the graph, LD Patch has two mechanisms: <tref>Bind</tref>ing a variable to a blank node reachable with a <tref>path expression</tref>, and <tref>UpdateList</tref> to deal with those blank nodes that constitute RDF collections. There are cases where those mechanisms will not be able to unambiuously adress a given blank node, but those cases are deemed <a href="#pathological-graph">pathological</a>, and out of the scope of this specification.
+In order to be able to address blank nodes already present in the graph, LD Patch has two mechanisms: <tref>Bind</tref>ing a variable to a blank node reachable with a <tref>path expression</tref>, and <tref>UpdateList</tref> 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 out of the scope of this specification.
</p>
</section>
-
- <section id="pathological-graph">
- <h2><tdef>Pathological graph</tdef></h2>
- <p>
- 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
- <ul>
- <li><em>n</em> is a URI or a literal</li>
- <li><em>p</em> is an LD Path expression</li>
- </ul>
- such that applying <em>p</em> to <em>n</em> results in a unique <em>{b}</em>.
- </p>
-
- <p>
-It is easy to see that only the unambiguous blank nodes of a graph can be handled in LD Patch.
- </p>
-
- <p>
-Consider for example the following graph:
- </p>
-
- <pre class='example'>
-<#> foaf:name "Alice" ; foaf:knows _:b1, _:b2 .
-_:b1 a foaf:Person .
-_:b2 a foaf:Person ; schema:workLocation _:b3 .
-_:b3 schema:name "W3C/MIT" .
- </pre>
-
- <p>
- The blank nodes <code>_:b2</code> and <code>_:b3</code> are unambiguous (they can for example be reached unambiguoulsy from the literal <code>"W3C/MIT"</code>). The blank node <code>_:b1</code>, on the other hand, is ambigious as all path expressions that can can match it would also match <code>_:b2</code>.
- </p>
-
- <!-- p>
- This kind of node is not particularly interesting in RDF, as its presence does not change the semantics of the graph. Indeed, if we remove <code>_:b2</code> and all its triples from the graph above, the resulting graph would be semantically equivalent to the original graph.
- </p-->
-
- <p>
- Another example is a graph containing only blank nodes. All its nodes are therefore ambiguous as they can not be reached from a URI or a literal. Such a graph is not interesting in the context of linked data as it contains no URI to link to or from it.
- </p>
-
- <p>
- Therefore, ambiguous blank nodes are considered a pathological case in the context of Linked Data, and so the fact that they cannot be coped with in LD Patch is deemed acceptable. Furthermore, their presence in a graph does not prevent the other nodes of that graph to be handled by LD Patch.
- </p>
-
- </section>
-
<section id="path-expression">
- <h2><tdef>Path expression</tdef></h2>
+ <h2><tdef>Path Expression</tdef></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 steps, which can be of three kinds:
</p>
@@ -425,14 +297,14 @@
A Path may also contains <tref>Constraint</tref>s, which are of two kinds:
</p>
<ul>
- <li>A unicity constraint, described by the <em>bang</em> ("<code>!</code>") character, ensures that the result of the path so far contains exactly one node.</li>
+ <li>A unicity constraint, 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 <tref>filter</tref>, 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>
</ul>
<p>
-The path below (taken from our running example) will look for all the events attended by the starting node, and keep only those having <code><http://conferences.ted.com/TED2009/></code> as their URL.
+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><https://www.w3.org/2012/ldp/wiki/F2F5></code>.
<pre class='example'>
-/schema:performerIn[/schema:url = <http://conferences.ted.com/TED2009/>]
+/schema:performerIn[/schema:url = <https://www.w3.org/2012/ldp/wiki/F2F5>]
</pre>
</p>
@@ -443,91 +315,156 @@
</section>
- <section id="bind-statement">
- <h2><dfn id="foobar">Bind</dfn></h2>
- <p>
-The Bind operation is used to create a new variable by binding or assigning an RDF Term to the variable. 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 Bound statements. Following the example above, the Bind operation creates a new variable called <code>event</code>, starting from the RDF Term <code><#></code> and following the path expression <code>/schema:performerIn[/schema:url = <http://conferences.ted.com/TED2009/>]</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 <#> /schema:performerIn[/schema:url = <http://conferences.ted.com/TED2009/>] .
- </pre>
- </p>
- <p>
-The Bind operation is defined by three components: <tref>Var</tref>, <tref>Value</tref> and <tref>Path</tref>, the last component being optional.
- </p>
- <p>
-<tref>Var</tref> contains a unique name for the new variable. Variables are prefixed by "<code>?</code>"; the "<code>?</code>" character is not part of the variable name.
- </p>
- <p>
-<tref>Value</tref> is the RDF Term that will be used as starting point when following the path expression.
- </p>
- <p>
-<tref>Path</tref> is the expression that is used to identify the RDF Term to which the Variable will be bound. It is comprised of <tref>Step</tref>(s) and/or <tref>Constraint</tref>(s).
- </p>
+ <section id="patch-operations">
+ <h2>Patch Operations</h2>
+
+ <section id="bind-statement">
+ <h2><tdef>Bind</tdef></h2>
+ <p>
+ The Bind 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 Bind statements. Following the example above, the Bind operation creates a new variable called <code>event</code>, starting from the RDF Term <code><#></code> and following the path expression <code>/schema:performerIn[/schema:url = <https://www.w3.org/2012/ldp/wiki/F2F5>]</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 <#> /schema:performerIn[/schema:url = <https://www.w3.org/2012/ldp/wiki/F2F5>] .
+ </pre>
+ </p>
+ <p>
+ The Bind operation is defined by three components: <tref>Var</tref>, <tref>Value</tref> and <tref>Path</tref>, the last component being optional.
+ </p>
+ <p>
+ <tref>Var</tref> contains a unique name for the new variable. Variables are prefixed by "<code>?</code>"; the "<code>?</code>" character is not part of the variable name.
+ </p>
+ <p>
+ <tref>Value</tref> is the RDF Term that will be used as starting point when following the path expression.
+ </p>
+ <p>
+ <tref>Path</tref> is the expression that is used to identify the RDF Term to which the Variable will be bound. It is comprised of <tref>Step</tref>(s) and/or <tref>Constraint</tref>(s).
+ </p>
+ </section>
+
+ <section id="add-statement">
+ <h2><tdef>Add</tdef></h2>
+ <p>
+ The Add 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>. Variables can also be used, provided they have been previously defined.
+ <pre class='example'>
+ Add {
+ <#> profile:first_name "Timothy" ;
+ profile:image <https://example.org/timbl.jpg> .
+ } .
+
+ Add { ?event rdf:type schema:Event } .
+ </pre>
+ </p>
+ </section>
+
+ <section id="delete-statement">
+ <h2><tdef>Delete</tdef></h2>
+ <p>
+ The Delete operation is used to remove one or more RDF triples from the existing graph. The syntax for the Delete 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 Add operation, variables can also be used within the Delete operation.
+ <pre class='example'>
+ Delete { <#> profile:first_name "Tim" } .
+
+ Delete { ?ted schema:startDate "2009-02-04" } .
+ </pre>
+ </p>
+ </section>
+
+ <section id="cut-statement">
+ <h2><tdef>Cut</tdef></h2>
+ <p>
+ The Cut operation is used to remove one or more triples from the existing graph, having a matching <tref>Subject</tref> that corresponds to either an IRI or a previously bound varible.
+ <pre class='example'>
+ @@TODO use UpdateList example .
+ </pre>
+ </p>
+ </section>
+
+ <section id="update-list-statement">
+ <h2><tdef>UpdateList</tdef></h2>
+ <p>
+ The UpdateList operation is used to update the members of an <a href="http://www.w3.org/TR/rdf-schema/#ch_collectionvocab">RDF collection</a>. That collection is supposed to be the object of a triple, specified by its <tref>Subject</tref> and <tref>Predicate</tref>. A <tref>Slice</tref> specification then describes which members (if any) of the collections are affected by the operation, and then a <tref>List</tref> of new members is provided. In the example below, UpdateList is used to replace the second member of a collection by the literal "fr-CH".
+ <pre class='example'>
+ UpdateList <#> ex:preferredLanguages 1..2 ( "fr-CH" ) .
+ </pre>
+ </p>
+ <p>
+ UpdateList works in a similar way to <a href="https://docs.python.org/3/reference/expressions.html#slicings">slicing in Python</a> or similar languages. In general, it replaces a part (“slice”) of a list by another list. To remove members, one can replace them by an empty list. To insert new values between two members, one can set a non empty list to the empty slice comprised between those two members.
+ </p>
+
+ <p>
+ In LD Patch, a slice is described by two positive integers separated by "<code>..</code>". The second integer can be omitted, in that case it denotes the end of the list. If both integers are omitted (i.e. "<code>..</code>" alone), this denotes by convention the empty slice at the end of the list. Indexes start at 0.
+ </p>
+
+ <p>
+ The following example shows the syntax for appending elements to a list:
+ </p>
+
+ <pre class='example'>
+ UpdateList <#> ex:preferredLanguages .. ( "fr-CH" ) .
+ </pre>
+
+ <p>
+ In this final example, we replace all the elements after index 2 with the provided list:
+ </p>
+
+ <pre class='example'>
+ UpdateList <#> ex:preferredLanguages 2.. ( "fr-CH" ) .
+ </pre>
+
+
+ </section>
</section>
- <section id="add-statement">
- <h2><tdef>Add</tdef></h2>
- <p>
-The Add operation is used to add or append new RDF triples to the existing graph. To add new RDF triple, the operation requires a <tref>Subject</tref>, a <tref>Predicate</tref> and either an <tref>Object</tref> or a <tref>List</tref>.
- <pre class='example'>
-Add <#> profile:first_name "Timothy" .
-
-Add ?event rdf:type schema:Event .
- </pre>
-When the third component is an <tref>Object</tref>, then a single statement will be added. On the other hand, when it is a <tref>List</tref>, all the intermediate blank nodes and corresponding statements will be added to construct a well formed <a href="http://www.w3.org/TR/rdf-schema/#ch_collectionvocab">RDF collection</a> (in addition to the triple with the given <tref>Subject</tref>, <tref>Predicate</tref> and that collection as the object).
- </p>
+ <section id="error-handling">
+ <h2><tdef>Error Handling</tdef></h2>
+ <p>@@TODO</p>
</section>
- <section id="delete-statement">
- <h2><tdef>Delete</tdef></h2>
+ <section id="pathological-graph">
+ <h2><tdef>Pathological Graph</tdef></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
+ <ul>
+ <li><em>n</em> is a URI or a literal</li>
+ <li><em>p</em> is an LD Path expression</li>
+ </ul>
+ such that applying <em>p</em> to <em>n</em> results in a unique <em>{b}</em>.
+ </p>
+
+ <p>
+ It is easy to see that only the unambiguous blank nodes of a graph can be handled in LD Patch.
+ </p>
+
+ <p>
+ Consider for example the following graph:
+ </p>
+
+ <pre class='example'>
+ <#> foaf:name "Alice" ; foaf:knows _:b1, _:b2 .
+ _:b1 a foaf:Person .
+ _:b2 a foaf:Person ; schema:workLocation _:b3 .
+ _:b3 schema:name "W3C/MIT" .
+ </pre>
+
<p>
-The Delete operation is used to remove a single RDF triple from the existing graph. The syntax for the Delete operation requires a <tref>Subject</tref>, a <tref>Predicate</tref> and an <tref>Object</tref>.
- <pre class='example'>
-Delete <#> profile:first_name "Tim" .
-
-Delete ?ted schema:startDate "2009-02-04".
- </pre>
+ The blank nodes <code>_:b2</code> and <code>_:b3</code> are unambiguous (they can for example be reached unambiguoulsy from the literal <code>"W3C/MIT"</code>). The blank node <code>_:b1</code>, on the other hand, is ambigious as all path expressions that can can match it would also match <code>_:b2</code>.
</p>
- </section>
- <section id="update-list-statement">
- <h2><tdef>UpdateList</tdef></h2>
+ <!-- p>
+ This kind of node is not particularly interesting in RDF, as its presence does not change the semantics of the graph. Indeed, if we remove <code>_:b2</code> and all its triples from the graph above, the resulting graph would be semantically equivalent to the original graph.
+ </p-->
+
<p>
-The UpdateList operation is used to update the members of an <a href="http://www.w3.org/TR/rdf-schema/#ch_collectionvocab">RDF collection</a>. That collection is supposed to be the object of a triple, specified by its <tref>Subject</tref> and <tref>Predicate</tref>. A <tref>Slice</tref> specification then describes which members (if any) of the collections are affected by the operation, and then a <tref>List</tref> of new members is provided. In the example below, UpdateList is used to replace the second member of a collection by the literal "fr-CH".
- <pre class='example'>
-UpdateList <#> ex:preferredLanguages 1..2 ( "fr-CH" ) .
- </pre>
- </p>
- <p>
-UpdateList works in a similar way to <a href="https://docs.python.org/3/reference/expressions.html#slicings">slicing in Python</a> or similar languages. In general, it replaces a part (“slice”) of a list by another list. To remove members, one can replace them by an empty list. To insert new values between two members, one can set a non empty list to the empty slice comprised between those two members.
+ Another example is a graph containing only blank nodes. All its nodes are therefore ambiguous as they can not be reached from a URI or a literal. Such a graph is not interesting in the context of Linked Data as it contains no URI to link to or from it.
</p>
<p>
-In LD Patch, a slice is described by two positive integers separated by "<code>..</code>". The second integer can be omitted, in that case it denotes the end of the list. If both integers are omitted (i.e. "<code>..</code>" alone), this denotes by convention the empty slice at the end of the list. Indexes start at 0.
- </p>
-
- <p>
- The following example shows the syntax for appending elements to a list:
+ Therefore, ambiguous blank nodes are considered a pathological case in the context of Linked Data, and so the fact that they cannot be coped with in LD Patch is deemed acceptable. Furthermore, their presence in a graph does not prevent the other nodes of that graph to be handled by LD Patch.
</p>
- <pre class='example'>
-UpdateList <#> ex:preferredLanguages .. ( "fr-CH" ) .
- </pre>
-
- <p>
- In this final example, we replace all the elements after index 2 with the provided list:
- </p>
-
- <pre class='example'>
-UpdateList <#> ex:preferredLanguages 2.. ( "fr-CH" ) .
- </pre>
-
+ </section>
</section>
-
</section>
-
<section id='concrete-syntax'>
<h1>Concrete Syntax</h1>
<p>
@@ -898,81 +835,105 @@
</tbody>
</table>
-
</section>
- <section id='abstract-syntax'>
- <h1>Abstract Syntax</h1>
- <p>
-The LD Patch data model makes use of the commonly defined <a href="http://en.wikipedia.org/wiki/Abstract_data_type">Abstract Data Types</a> <a href="http://en.wikipedia.org/wiki/Set_(computer_science)">Set</a>, <a href="http://en.wikipedia.org/wiki/List_(computer_science)">List</a> and <a href="http://en.wikipedia.org/wiki/Option_type">Option</a>, used here as type constructors. For example, <code>Set(A)</code> denotes the type for the sets of elements of type <code>A</code>. <!--We assume that they come with their common operations, such as the function <code>size : Set → Int</code>.-->
- </p>
- <pre>
-<tref>LDPatch</tref> ::= <tref>List</tref>(<tref>Statement</tref>)
-
-<tref>Statement</tref> ::= <tref>Add</tref> | <tref>AddList</tref> | <tref>Delete</tref> | <tref>Bind</tref> | <tref>UpdateList</tref>
-<tref>Add</tref> ::= (<tref>Subject</tref>, <tref>Predicate</tref>, <tref>Object</tref>)
-<tdef>AddList</tdef> ::= (<tref>Subject</tref>, <tref>Predicate</tref>, <tref>List</tref>(<tref>Object</tref>))
-<tref>Delete</tref> ::= (<tref>Subject</tref>, <tref>Predicate</tref>, <tref>Object</tref>)
-<tref id="my-bind">Bind</tref> ::= (<tref>Var</tref>, <tref>Value</tref>, <tref>Path</tref>)
-<tref>UpdateList</tref> ::= (<tref>Subject</tref>, <tref>Predicate</tref>, <tref>Slice</tref>, <tref>List</tref>(<tref>Object</tref>))
-
-<tdef>Path</tdef> ::= <tref>List</tref>(<tref>PathElement</tref>)
-<tdef>PathElement</tdef> ::= <tref>Step</tref> | <tref>Constraint</tref>
-<tref>Step</tref> ::= <tref>StepForward</tref> | <tref>StepBackward</tref> | <tref>StepAt</tref>
-<tref>Constraint</tref> ::= <tref>Filter</tref> | UNICITY_CONSTRAINT
-<tdef>StepForward</tdef> ::= <tref>IRI</tref>
-<tdef>StepBackward</tdef> ::= <tref>IRI</tref>
-<tdef>StepAt</tdef> ::= <tref>Integer</tref>
-<tdef>Filter</tdef> ::= (<tref>Path</tref>, Option(<tref>Value</tref>))
-
-<tref>Slice</tref> ::= <tref>Range</tref> | <tref>EverythingAfter</tref> | END
-<tdef>Range</tdef> ::= (<tref>Integer</tref>, <tref>Integer</tref>)
-<tdef>EverythingAfter</tdef> ::= <tref>Integer</tref>
-
-<tref>Subject</tref> ::= <tref>IRI</tref> | <tref>BlankNode</tref> | <tref>Var</tref>
-<tref>Predicate</tref> ::= <tref>IRI</tref>
-<tref>Object</tref> ::= <tref>IRI</tref> | <tref>BlankNode</tref> | <tref>Literal</tref> | <tref>Var</tref>
-<tref>Value</tref> ::= <tref>IRI</tref> | <tref>Literal</tref> | <tref>Var</tref>
-
-<tdef>Var</tdef> ::= <tref>String</tref>
-<tdef>IRI</tdef> ::= RDF URI-reference http://www.w3.org/TR/2014/REC-rdf11-concepts-20140225/#section-IRIs as subsequently restricted by SPARQL http://www.w3.org/TR/rdf-sparql-query/#docTerminology
-<tdef>BlankNode</tdef> ::= RDF blank node http://www.w3.org/TR/2014/REC-rdf11-concepts-20140225/#section-blank-nodes
-<tdef>Literal</tdef> ::= RDF Literal http://www.w3.org/TR/2014/REC-rdf11-concepts-20140225/#section-Graph-Literal
-<tdef>String</tdef> ::= a Unicode String
- </pre>
-
- </section>
-
- <section id='operational-semantics'>
- <h1>Operational Semantics</h1>
+ <section id="examples" class="informative">
+ <h2>Examples</h2>
<p>
- LD Patch abides to the semantics of the <a href="http://tools.ietf.org/html/rfc5789" target="_blank">HTTP PATCH method</a>, in that the server MUST apply the entire set of changes atomically and never provide (e.g., in response to a GET during this operation) a partially modified representation. If the entire patch document cannot be successfully applied (e.g., one of the instructions has failed), then the server MUST NOT apply any of the changes.
- </p>
-
- <p>
+ The following RDF Graph will be used as an example through this specification. It describes the relation between a person named Tim Berners-Lee (denoted by <code><http://example.org/timbl#></code>) and two events he attended.
</p>
-
- <h2></h2>
-
- <!-- p>The formal semantics of a statement is a function from state to state. That state carries the current graph and a map from variables to RDF nodes. The semantics of an LD Patch document is defined by applying its statements in order while carrying the state. The initial state is made of the original graph and of an empty mapping. If no runtime errors occurs, the final state has the final value of the graph.</p>
-
- <p>The semantics of a Subject, an Object and Value a ground RDF node ie. it is itself if it is a RDF node, or its value in the map if it is a variable. The semantics of all the statements, including Bind, is defined on ground terms.</p>
+ <pre class='example'>
+@prefix schema: <http://schema.org/> .
+@prefix profile: <http://ogp.me/ns/profile#> .
+@prefix ex: <http://example.org/vocab#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+<http://example.com/timbl#> a schema:Person ;
+ schema:alternateName "TimBL" ;
+ profile:first_name "Tim" ;
+ profile:last_name "Berners-Lee" ;
+ schema:workLocation [ schema:name "W3C/MIT" ] ;
+ schema:performerIn _:b1, _:b2 ;
+ ex:preferredLanguages ( "en" "fr" ).
- <p>The semantics of Bind is defined by evaluating the path on the starting node, and adding a binding from the variable to the result.</p>
-
- <p>The semantics of Add is defined by adding the triple made of the (Subject, Predicate, Object) to the current graph.</p>
-
- <p>The semantics of AddList is defined by adding the triple made of the (Subject, Predicate, Object) to the current graph.</p>
+_:b1 schema:name "F2F5 - Linked Data Platform" ;
+ schema:url <https://www.w3.org/2012/ldp/wiki/F2F5> .
- <p>The semantics of Delete is defined by removing the triple made of the (Subject, Predicate, Object) from the current graph.</p>
-
- <p></p-->
+_:b2 a schema:Event ;
+ schema:name "TED 2009" ;
+ schema:startDate "2009-02-04" ;
+ schema:url <http://conferences.ted.com/TED2009/> .
+ </pre>
+ <p>
+The following is an example HTTP Patch request, conveying an LD Patch document:
+ </p>
+ <pre class='example'>
+PATCH /timbl HTTP/1.1
+Host: example.org
+Content-Length: 478
+Content-Type: text/ldpatch
+If-Match: "abc123"
- <p>TODO</p>
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix schema: <http://schema.org/> .
+@prefix profile: <http://ogp.me/ns/profile#> .
+@prefix ex: <http://example.org/vocab#> .
+Delete { <#> profile:first_name "Tim" } .
+Add {
+ <#> profile:first_name "Timothy" ;
+ profile:image <https://example.org/timbl.jpg>.
+} .
- </pre-->
+UpdateList <#> ex:preferredLanguages 1..2 ( "fr-CH" ) .
+
+Bind ?event <#> /schema:performerIn[/schema:url = <https://www.w3.org/2012/ldp/wiki/F2F5>] .
+Add { ?event rdf:type schema:Event } .
+
+Bind ?ted <http://conferences.ted.com/TED2009/> /^schema:url! .
+Delete { ?ted schema:startDate "2009-02-04" } .
+Add {
+ ?ted schema:location [
+ schema:name "Long Beach, California" ;
+ schema:geo [
+ schema:latitude "33.7817" ;
+ schema:longitude "-118.2054"
+ ]
+ ]
+} .
+ </pre>
+ <p>
+ This example introduces most features of the LD Patch format: <code>@prefix</code> and prefixed names, the <tref>Add</tref>, <tref>Delete</tref> and <tref>UpdateList</tref> operations, the <tref>Bind</tref>-ing mechanism and blank node creation. The "text/ldpatch" media type is <a href="#media-registration">prospectively</a> used to identify such LD Patch documents.
+ </p>
+ <p>
+The following is the resulting (patched) document.
+ </p>
+ <pre class='example'>
+@prefix schema: <http://schema.org/> .
+@prefix profile: <http://ogp.me/ns/profile#> .
+@prefix ex: <http://example.org/vocab#> .
+
+<http://example.com/timbl#> a schema:Person ;
+ schema:alternateName "TimBL" ;
+ profile:first_name "Timothy" ;
+ profile:last_name "Berners-Lee" ;
+ proflie:image <https://example.org/timbl.jpg> ;
+ schema:workLocation [ schema:name "W3C/MIT" ] ;
+ schema:performerIn _:b1, _:b2 ;
+ ex:preferredLanguages ( "en" "fr-CH" ).
+
+_:b1 a schema:Event ;
+ schema:name "F2F5 - Linked Data Platform" ;
+ schema:url <https://www.w3.org/2012/ldp/wiki/F2F5> .
+
+_:b2 a schema:Event ;
+ schema:name "TED 2009" ;
+ schema:url <http://conferences.ted.com/TED2009/> ;
+ schema:location [
+ schema:name "Long Beach, California";
+ schema:geo [ schema:latitude "33.7817" ; schema:longitude "-118.2054" ]
+ ] .
+ </pre>
</section>
<section id="acknowledgements" class="appendix informative">