Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Describe N3 Patch #346

Merged
merged 30 commits into from
Dec 15, 2021
Merged

Describe N3 Patch #346

Changes from all commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
169e0a9
Draft initial N3 Patch proposal.
RubenVerborgh Nov 10, 2021
9db73b8
Drop solid:patches as a patch requirement.
RubenVerborgh Nov 10, 2021
8428773
Only allow blank nodes for insertions.
RubenVerborgh Nov 10, 2021
ffb2a56
Require the Accept-Patch header.
RubenVerborgh Nov 10, 2021
9e90ea4
Add example.
RubenVerborgh Nov 10, 2021
e731f76
Allow the solid:Patch type.
RubenVerborgh Nov 10, 2021
cfdf6ff
Use 'media type' instead of 'MIME type'.
RubenVerborgh Nov 11, 2021
eecd630
Allow blank nodes for patch.
RubenVerborgh Nov 12, 2021
6627c65
Turn patch structure into formal requirements.
RubenVerborgh Nov 12, 2021
7fded28
Clarify language.
RubenVerborgh Nov 12, 2021
bae9aba
Expand processing to list.
RubenVerborgh Nov 12, 2021
b907715
Clarify May/MUST language.
RubenVerborgh Nov 12, 2021
043e8e4
Describe permissions.
RubenVerborgh Nov 12, 2021
06b7d63
Clarify 409 conditions.
RubenVerborgh Nov 12, 2021
94d4408
Clarify blank node creation.
RubenVerborgh Nov 16, 2021
9ac5899
Use 422 for semantically invalid patches.
RubenVerborgh Nov 16, 2021
7d94b2f
Alternative references for triple and triple pattern
kjetilk Nov 17, 2021
03aa9e0
Simplify wording.
RubenVerborgh Nov 29, 2021
9550f48
Split patches and identifier statements.
RubenVerborgh Nov 30, 2021
1fed0c4
Remove "structural".
RubenVerborgh Nov 30, 2021
21987eb
Split N3 Patch acceptance and advertising.
RubenVerborgh Nov 30, 2021
16c4b56
Add ID to extension statement.
RubenVerborgh Nov 30, 2021
50332c7
Hint a cumulative nature.
RubenVerborgh Nov 30, 2021
f53d94a
Add source for semaphore functionality.
RubenVerborgh Nov 30, 2021
3965a01
Fix typo.
RubenVerborgh Nov 30, 2021
b5d9e43
Use more recognizable example names.
RubenVerborgh Nov 30, 2021
466675c
Minor
csarven Dec 5, 2021
97da1c9
Minor
csarven Dec 5, 2021
970e809
Stabilise n3-patch spec:requirements
csarven Dec 6, 2021
2a99d6a
Allow arbitrary patch triples by requiring a specific type.
RubenVerborgh Dec 14, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 66 additions & 1 deletion protocol.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,9 +46,11 @@
figure .example-h {
margin-top:0;
text-align: left;
text-transform: uppercase;
color:#827017;
}
figure .example-h > span {
text-transform: uppercase;
}
header address a[href] {
float: right;
margin: 1rem 0 0.2rem 0.4rem;
Expand Down Expand Up @@ -719,6 +721,63 @@ <h4 property="schema:name"><span>Note</span>: Conditional Update</h4>

<p><span about="" id="server-etag" rel="spec:requirement" resource="#server-etag"><span property="spec:statement"><span rel="spec:requirementSubject" resource="spec:Server">Servers</span> <span rel="spec:requirementLevel" resource="spec:MAY">MAY</span> use the HTTP <code>ETag</code> header with a strong validator for RDF bearing representations in order to encourage clients to opt-in to using the <code>If-Match</code> header in their requests.</span></span></p>
</div>

<section id="n3-patch" inlist="" rel="schema:hasPart" resource="#n3-patch">
<h4 property="schema:name">Modifying Resources Using N3 Patches</h4>
<div datatype="rdf:HTML" property="schema:description">
<p><span about="" id="server-patch-n3-accept" rel="spec:requirement" resource="#server-patch-n3-accept"><span property="spec:statement"><span rel="spec:requirementSubject" resource="spec:Server">Servers</span> <span rel="spec:requirementLevel" resource="spec:MUST">MUST</span> accept a <code>PATCH</code> request with an <em>N3 Patch</em> body when the target of the request is an <em>RDF document</em> [<cite><a class="bibref" href="#bib-rdf11-concepts">RDF11-CONCEPTS</a></cite>].</span></span> <span about="" id="server-patch-n3-advertise" rel="spec:requirement" resource="#server-patch-n3-advertise"><span property="spec:statement"><span rel="spec:requirementSubject" resource="spec:Server">Servers</span> <span rel="spec:requirementLevel" resource="spec:MUST">MUST</span> indicate support of N3 Patch by listing <code>text/n3</code> as a value of the <code>Accept-Patch</code> header [<cite><a class="bibref" href="#bib-rfc5789">RFC5789</a></cite>] of relevant responses.</span></span> [<a href="https://github.com/solid/specification/issues/125#issuecomment-959518598" rel="cito:citesAsSourceDocument">Source</a>]</p>

<p>An <em>N3 Patch</em> is a document in the <em>Notation3 (N3)</em> format [<cite><a class="bibref" href="#bib-notation3">N3</a></cite>], identified by the media type <code>text/n3</code>, conforming to the following constraints:</p>

<ul>
<li id="server-patch-n3-patches" rel="spec:requirement" resource="#server-patch-n3-patches"><span property="spec:statement">A patch document <span rel="spec:requirementLevel" resource="spec:MUST">MUST</span> contain one or more patch resources.</span></li>
<li id="server-patch-n3-patch-identifier" rel="spec:requirement" resource="#server-patch-n3-patch-identifier"><span property="spec:statement">A patch resource <span rel="spec:requirementLevel" resource="spec:MUST">MUST</span> be identified by a URI or blank node, which we refer to as <code>?patch</code> in the remainder of this section.</span></li>
<li id="server-patch-n3-type" rel="spec:requirement" resource="#server-patch-n3-type">A patch resource <span rel="spec:requirementLevel" resource="spec:MAY">MAY</span> contain a triple [<cite><a class="bibref" href="#bib-rdf11-concepts">RDF11-CONCEPTS</a></cite>] <code><span property="spec:statement">?patch rdf:type solid:Patch</span></code>.</li>
<li id="server-patch-n3-deletes" rel="spec:requirement" resource="#server-patch-n3-deletes"><span property="spec:statement">A patch resource <span rel="spec:requirementLevel" resource="spec:MUST">MUST</span> contain at most one triple of the form <code>?patch solid:deletes ?deletions</code>.</span></li>
<li id="server-patch-n3-inserts" rel="spec:requirement" resource="#server-patch-n3-inserts">A patch resource <span rel="spec:requirementLevel" resource="spec:MUST">MUST</span> contain at most one triple of the form <code>?patch solid:inserts ?insertions</code>.</li>
<li id="server-patch-n3-where" rel="spec:requirement" resource="#server-patch-n3-where"><span property="spec:statement">A patch resource <span rel="spec:requirementLevel" resource="spec:MUST">MUST</span> contain at most one triple of the form <code>?patch solid:where ?conditions</code>.</span></li>
<li id="server-patch-n3-formulae" rel="spec:requirement" resource="#server-patch-n3-formulae"><span property="spec:statement">When present, <code>?deletions</code>, <code>?insertions</code>, and <code>?conditions</code> <span rel="spec:requirementLevel" resource="spec:MUST">MUST</span> be non-nested <em>cited formulae</em> [<cite><a class="bibref" href="#bib-notation3">N3</a></cite>] consisting only of triples and/or triple patterns [<cite><a class="bibref" href="#bib-sparql11-query">SPARQL11-QUERY</a></cite>]. When not present, they are presumed to be the empty formula <code>{}</code>.</span></li>
</ul>

<p id="server-patch-n3-default" rel="schema:hasPart" resource="#server-patch-n3-default"><span property="schema:description">While other specifications might provide a structure and interpretation for a wider class of N3 Patch documents, the present specification only governs the application of N3 Patch documents that additionally adhere to the following constraints:</span></p>

<ul about="#server-patch-n3-default">
<li id="server-patch-n3-single" rel="spec:requirement" resource="#server-patch-n3-single"><span property="spec:statement">The patch document <span rel="spec:requirementLevel" resource="spec:MUST">MUST</span> contain exactly one patch resource, identified by one or more of the triple patterns described above, which all share the same <code>?patch</code> subject.</span></li>
<li id="server-patch-n3-simple-type" rel="spec:requirement" resource="#server-patch-n3-type">A patch resource <span rel="spec:requirementLevel" resource="spec:MUST">MUST</span> contain a triple <code><span property="spec:statement">?patch rdf:type solid:InsertDeletePatch</span></code>.</li>
<li id="server-patch-n3-variables" rel="spec:requirement" resource="#server-patch-n3-variables"><span property="spec:statement">The <code>?insertions</code> and <code>?deletions</code> formulae <span rel="spec:requirementLevel" resource="spec:MUST-NOT">MUST NOT</span> contain variables that do not occur in the <code>?conditions</code> formula.</span></li>
<li id="server-patch-n3-blank-nodes" rel="spec:requirement" resource="#server-patch-n3-blank-nodes"><span property="spec:statement">The <code>?insertions</code> and <code>?deletions</code> formulae <span rel="spec:requirementLevel" resource="spec:MUST-NOT">MUST NOT</span> contain blank nodes.</span></li>
</ul>

<p><span about="" id="server-patch-n3-invalid" rel="spec:requirement" resource="#server-patch-n3-invalid"><span property="spec:statement"><span rel="spec:requirementSubject" resource="spec:Server">Servers</span> <span rel="spec:requirementLevel" resource="spec:MUST">MUST</span> respond with a <code>422</code> status code [<cite><a class="bibref" href="#bib-rfc4918">RFC4918</a></cite>] if a patch document does not satisfy all of the above constraints.</span></span></p>
RubenVerborgh marked this conversation as resolved.
Show resolved Hide resolved

<p><span about="" id="server-n3-patch-where" rel="spec:requirement" resource="#server-n3-patch-where"><span property="spec:statement">When <code>?conditions</code> is non-empty, <span rel="spec:requirementSubject" resource="spec:Server">servers</span> <span rel="spec:requirementLevel" resource="spec:MUST">MUST</span> treat the request as a <a href="#read-operation">Read operation</a>.</span></span> <span about="" id="server-n3-patch-insert" rel="spec:requirement" resource="#server-n3-patch-insert"><span property="spec:statement">When <code>?insertions</code> is non-empty, <span rel="spec:requirementSubject" resource="spec:Server">servers</span> <span rel="spec:requirementLevel" resource="spec:MUST">MUST</span> (also) treat the request as an <a href="#append-operation">Append operation</a>.</span></span> <span about="" id="server-n3-patch-delete" rel="spec:requirement" resource="#server-n3-patch-delete"><span property="spec:statement">When <code>?deletions</code> is non-empty, <span rel="spec:requirementSubject" resource="spec:Server">servers</span> <span rel="spec:requirementLevel" resource="spec:MUST">MUST</span> treat the request as a <a href="#read-operation">Read</a> and <a href="#write-operation">Write operation</a>.</span></span></p>

<p><span about="" id="server-patch-n3-semantics" rel="spec:requirement" resource="#server-patch-n3-semantics"><span property="spec:statement"><span rel="spec:requirementSubject" resource="spec:Server">Servers</span> <span rel="spec:requirementLevel" resource="spec:MUST">MUST</span> process a patch resource against the target document as follows:</span></span></p>

<ol about="#server-patch-n3-semantics">
<li>Start from the RDF dataset in the target document, or an empty RDF dataset if the target resource does not exist yet.</li>
<li>If <code>?conditions</code> is non-empty, find all (possibly empty) variable mappings such that all of the resulting triples occur in the dataset.</li>
<li>If no such mapping exists, or if multiple mappings exist, the <span id="server-patch-n3-semantics-no-mapping" rel="spec:requirement" resource="#server-patch-n3-semantics-no-mapping"><span property="spec:statement"><span rel="spec:requirementSubject" resource="spec:Server">server</span> <span rel="spec:requirementLevel" resource="spec:MUST">MUST</span> respond with a <code>409</code> status code.</span></span> [<a href="https://github.com/solid-archive/query-panel/issues/3" rel="cito:citesAsSourceDocument">Source</a>]</li>
<li>The resulting variable mapping is propagated to the <code>?deletions</code> and <code>?insertions</code> formulae to obtain two sets of resulting triples.</li>
<li>If the set of triples resulting from <code>?deletions</code> is non-empty and the dataset does not contain <em>all</em> of these triples, the <span id="server-patch-n3-semantics-deletions-non-empty-all-triples" rel="spec:requirement" resource="#server-patch-n3-semantics-deletions-non-empty-all-triples"><span property="spec:statement"><span rel="spec:requirementSubject" resource="spec:Server">server</span> <span rel="spec:requirementLevel" resource="spec:MUST">MUST</span> respond with a <code>409</code> status code.</span></span> [<a href="https://github.com/solid-archive/query-panel/issues/3" rel="cito:citesAsSourceDocument">Source</a>]</li>
<li>The triples resulting from <code>?deletions</code> are to be removed from the RDF dataset.</li>
<li>The triples resulting from <code>?insertions</code> are to be added to the RDF dataset, with each blank node from <code>?insertions</code> resulting in a newly created blank node.</li>
<li>The combination of deletions followed by insertions then forms the new resource state of the RDF document, and the server responds with the appropriate status code.</li>
</ol>
</div>

<figure id="n3-patch-example" class="example listing" rel="schema:hasPart" resource="#n3-patch-example">
<p class="example-h"><span>Example</span>: Applying an N3 patch.</p>
<pre about="#n3-patch-example" property="schema:description" typeof="fabio:Script"><code>@prefix solid: &lt;http://www.w3.org/ns/solid/terms#&gt;.</code>
<code>@prefix ex: &lt;http://www.example.org/terms#&gt;.</code>
<code></code>
<code>_:rename a solid:InsertDeletePatch;</code>
<code> solid:where { ?person ex:familyName "Garcia". };</code>
<code> solid:inserts { ?person ex:givenName "Alex". };</code>
<code> solid:deletes { ?person ex:givenName "Claudia". }.</code></pre>
<figcaption property="schema:name">This N3 Patch instructs to rename <em>Claudia Garcia</em> into <em>Alex Garcia</em>, on the condition that no other Garcia family members are present in the target RDF document.</figcaption>
</figure>
</section>
</section>

<section id="deleting-resources" inlist="" rel="schema:hasPart" resource="#deleting-resources">
Expand Down Expand Up @@ -1062,6 +1121,8 @@ <h3 property="schema:name">Normative References</h3>
<dd><a href="https://www.w3.org/TR/ldn/" rel="cito:citesAsAuthority"><cite>Linked Data Notifications</cite></a>. Sarven Capadisli; Amy Guy. W3C. 2 May 2017. W3C Recommendation. URL: <a href="https://www.w3.org/TR/ldn/">https://www.w3.org/TR/ldn/</a></dd>
<dt id="bib-ldp">[LDP]</dt>
<dd><a href="https://www.w3.org/TR/ldp/" rel="cito:citesAsAuthority"><cite>Linked Data Platform 1.0</cite></a>. Steve Speicher; John Arwe; Ashok Malhotra. W3C. 26 February 2015. W3C Recommendation. URL: <a href="https://www.w3.org/TR/ldp/">https://www.w3.org/TR/ldp/</a></dd>
<dt id="bib-notation3">[N3]</dt>
<dd><a href="https://w3c.github.io/N3/spec/" rel="cito:citesAsAuthority"><cite>Notation3</cite></a>. Dörthe Arndt; William Van Woensel;Dominik Tomaszuk; Gregg Kellogg. W3C. 5 September 2021. Draft Community Group Report. URL: <a href="https://w3c.github.io/N3/spec/">https://w3c.github.io/N3/spec/</a></dd>
<dt id="bib-rdf-schema">[RDF-SCHEMA]</dt>
<dd><a href="https://www.w3.org/TR/rdf-schema/" rel="cito:citesAsAuthority"><cite>RDF Schema 1.1</cite></a>. Dan Brickley; Ramanathan Guha. W3C. 25 February 2014. W3C Recommendation. URL: <a href="https://www.w3.org/TR/rdf-schema/">https://www.w3.org/TR/rdf-schema/</a></dd>
<dt id="bib-rdf11-concepts">[RDF11-CONCEPTS]</dt>
Expand All @@ -1072,6 +1133,8 @@ <h3 property="schema:name">Normative References</h3>
<dd><a href="https://datatracker.ietf.org/doc/html/rfc3864" rel="cito:citesAsAuthority"><cite>Registration Procedures for Message Header Fields</cite></a>. G. Klyne; M. Nottingham; J. Mogul. IETF. September 2004. Best Current Practice. URL: <a href="https://datatracker.ietf.org/doc/html/rfc3864">https://datatracker.ietf.org/doc/html/rfc3864</a></dd>
<dt id="bib-rfc3986">[RFC3986]</dt>
<dd><a href="https://datatracker.ietf.org/doc/html/rfc3986" rel="cito:citesAsAuthority"><cite>Uniform Resource Identifier (URI): Generic Syntax</cite></a>. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: <a href="https://datatracker.ietf.org/doc/html/rfc3986">https://datatracker.ietf.org/doc/html/rfc3986</a></dd>
<dt id="bib-rfc4918">[RFC4918]</dt>
<dd><a href="https://datatracker.ietf.org/doc/html/rfc4918" rel="cito:citesAsAuthority"><cite>HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)</cite></a>. L. Dusseault, Ed. IETF. June 2007. Proposed Standard. URL: <a href="https://datatracker.ietf.org/doc/html/rfc4918">https://datatracker.ietf.org/doc/html/rfc4918</a></dd>
<dt id="bib-rfc5023">[RFC5023]</dt>
<dd><a href="https://datatracker.ietf.org/doc/html/rfc5023" rel="cito:citesAsAuthority"><cite>The Atom Publishing Protocol</cite></a>. J. Gregorio, Ed.; B. de hOra, Ed.. IETF. October 2007. Proposed Standard. URL: <a href="https://datatracker.ietf.org/doc/html/rfc5023">https://datatracker.ietf.org/doc/html/rfc5023</a></dd>
<dt id="bib-rfc5789">[RFC5789]</dt>
Expand Down Expand Up @@ -1102,6 +1165,8 @@ <h3 property="schema:name">Normative References</h3>
<dd><a href="https://httpwg.org/specs/rfc8288.html" rel="cito:citesAsAuthority"><cite>Web Linking</cite></a>. M. Nottingham. IETF. October 2017. Proposed Standard. URL: <a href="https://httpwg.org/specs/rfc8288.html">https://httpwg.org/specs/rfc8288.html</a></dd>
<dt id="bib-solid-oidc">[SOLID-OIDC]</dt>
<dd><a href="https://solid.github.io/solid-oidc/" rel="cito:citesAsAuthority"><cite>SOLID-OIDC</cite></a>. Aaron Coburn; elf Pavlik; Dmitri Zagidulin. W3C Solid Community Group. W3C Editor's Draft. URL: <a href="https://solid.github.io/solid-oidc/">https://solid.github.io/solid-oidc/</a></dd>
<dt id="bib-sparql11-query">[SPARQL11-QUERY]</dt>
<dd><a href="https://www.w3.org/TR/sparql11-query/" rel="cito:citesAsAuthority"><cite>SPARQL 1.1 Query</cite></a>. Steve Harris; Andy Seaborne; Eric Prud'hommeaux. W3C. 21 March 2013. W3C Recommendation. URL: <a href="https://www.w3.org/TR/sparql11-query/">https://www.w3.org/TR/sparql11-query/</a></dd>
<dt id="bib-turtle">[Turtle]</dt>
<dd><a href="https://www.w3.org/TR/turtle/" rel="cito:citesAsAuthority"><cite>RDF 1.1 Turtle</cite></a>. Eric Prud'hommeaux; Gavin Carothers. W3C. 25 February 2014. W3C Recommendation. URL: <a href="https://www.w3.org/TR/turtle/">https://www.w3.org/TR/turtle/</a></dd>
<dt id="bib-w3c-html">[W3C-HTML]</dt>
Expand Down