[GitHub] [jena-site] afs commented on a diff in pull request #131: RDF Patch documentation

[GitBox <gi...@apache.org>]

afs commented on code in PR #131:
URL: https://github.com/apache/jena-site/pull/131#discussion_r1025158734


##########
source/documentation/rdf-patch/__index.md:
##########
@@ -0,0 +1,191 @@
+---
+title: RDF Patch
+slug: index
+---
+
+This page describes RDF Patch. An RDF Patch is a set of changes to an
+[RDF dataset](https://www.w3.org/TR/rdf11-concepts/#section-dataset).
+The change are for triples, quads and prefixes.
+
+Changes to triples involving blank nodes are handled by using their system
+identifier which uniquely identifies a blank node. Unlike RDF syntaxes, blank
+nodes are not generated afresh each time the document is parsed.
+
+## Example
+
+This example ensures certain prefixes are in the dataset and adds some
+basic triples for a new subclass of `<http://example/SUPER_CLASS>`.
+
+```
+TX .
+PA "rdf" "http://www.w3.org/1999/02/22-rdf-syntax-ns#" .
+PA "owl" "http://www.w3.org/2002/07/owl#" .
+PA "rdfs" "http://www.w3.org/2000/01/rdf-schema#" .
+A <http://example/SubClass> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/2002/07/owl#Class> .
+A <http://example/SubClass> <http://www.w3.org/2000/01/rdf-schema#subClassOf> <http://example/SUPER_CLASS> .
+A <http://example/SubClass> <http://www.w3.org/2000/01/rdf-schema#label> "SubClass" .
+TC .
+```
+
+## Structure
+
+The text format for an RDF Patch is N-Triples-like: it is a series of
+rows, each row ends with a `.` (DOT).  The tokens on a row are keywords,
+URIs, blank nodes, writen with their label (see below) or RDF Literals,
+in N-triples syntax.  A keyword follows the same rules as
+Turtle prefix declarations without a trailing `:`.
+
+A line has an operation code, then some number of items depending on 
+the operation.
+
+| Operation |                   |
+| --------- | ----------------- |
+| `H`                  | Header |
+| `TX`<br/>`TC`<br/>`TA`     | Change block: transactions    |
+| `PA`<br/>`PD`<br/>         | Change: Prefix add and delete |
+| `A`<br/>`D`                | Change: Add and delete triples and quads |
+
+The general structure of an RDF patch is a header (possible empty), then a
+number of change blocks.
+
+Each change block is a transaction. Transactions can be explicit recorded ('TX'
+start, `TC` commit) to include multiple transaction in one patch. They are not
+required. If not present, the patch should be applied atomically to the data.
+
+```
+header
+TX
+Quad, triple or prefix changes
+TC or TA
+```
+
+Multiple transaction blocks are allowed for multiple sets of changes in one
+patch.
+
+A binary version based on [RDF Thrift](../io/rdf-binary/) is provided.
+Parsing binary compared to text for N-triples achieves a x3-x4 increase in
+throughput.
+
+### Header
+
+The header provides for basic information about patch. It is a series of
+(key, value) pairs.
+
+It is better to put complex metadata in a separate file and link to it
+from the header, but certain information is best kept with the patch. An example
+used by Delta is to keep the identifer of the global version id of the dataset

Review Comment:
   Delta is [RDF Delta](https://afs.github.io/rdf-delta)  - the whole change propagation, replication and high-availability system. 
   
   There should not be any mention of it in this patch documentation.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@jena.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org