Skip to content

Commit

Permalink
Stabilise n3-patch spec:requirements
Browse files Browse the repository at this point in the history
  • Loading branch information
@csarven @RubenVerborgh
csarven authored and RubenVerborgh committed Dec 14, 2021
1 parent 97da1c9 commit 970e809
Showing 1 changed file with 9 additions and 9 deletions.
18 changes: 9 additions & 9 deletions protocol.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -725,7 +725,7 @@ <h4 property="schema:name"><span>Note</span>: Conditional Update</h4>
<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">They</span> <span rel="spec:requirementLevel" resource="spec:MUST">MUST</span> indicate such support 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><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>

Expand All @@ -739,14 +739,14 @@ <h4 property="schema:name">Modifying Resources Using N3 Patches</h4>
<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">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:</p>
<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>
<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-matching-strategy" rel="spec:requirement" resource="#server-patch-n3-matching-strategy"><span property="spec:statement">The patch resource <span rel="spec:requirementLevel" resource="spec:MAY">MAY</span> contain one triple of the form <code>?patch solid:matchingStrategy solid:SingleMatch</code>.</span></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:MUSTNOT">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:MUSTNOT">MUST NOT</span> contain blank nodes.</span></li>
<li id="server-patch-n3-other-triples" rel="spec:requirement" resource="#server-patch-n3-other-triples"><span property="spec:statement">The patch document <span rel="spec:requirementLevel" resource="spec:MUSTNOT">MUST NOT</span> contain any other triples.</span></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>
<li id="server-patch-n3-other-triples" rel="spec:requirement" resource="#server-patch-n3-other-triples"><span property="spec:statement">The patch document <span rel="spec:requirementLevel" resource="spec:MUST-NOT">MUST NOT</span> contain any other triples.</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>
Expand All @@ -755,12 +755,12 @@ <h4 property="schema:name">Modifying Resources Using N3 Patches</h4>

<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>
<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 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. [<a href="https://github.com/solid-archive/query-panel/issues/3" rel="cito:citesAsSourceDocument">Source</a>]</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 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. [<a href="https://github.com/solid-archive/query-panel/issues/3" rel="cito:citesAsSourceDocument">Source</a>]</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>
Expand Down

0 comments on commit 970e809

Please sign in to comment.