Merge pull request #109 from TREEcg/fix-85

Fixing #85: it’s a search tree now and not a graph and new meaning to tree:view

specs/0-introduction.md

@@ -5,7 +5,7 @@
 The TREE specification introduces these core concepts:
  * a <code>tree:Collection</code> is a subclass of <code>dcat:Dataset</code> ([[!vocab-dcat-3]]). The specialization being that it is a DCAT dataset a collection of members. It typically has these properties when described in a node:
      - <code>tree:member</code> points at the first focus node from which to retrieve and extract all quads of a member.
-     - <code>tree:view</code> points to a <code>tree:Node</code> from which all members can be reached.
+     - <code>tree:view</code> points to the current <code>tree:Node</code> you’re visiting.
      - <code>tree:shape</code> indicates the [[!SHACL]] shape to which each member in the collection adheres.
      - <code>tree:viewDescription</code> links to a description of the view (a <code>tree:ViewDescription</code>). Multiple descriptions MAY be provided that MUST be combined.
  * a <code>tree:Node</code>: is a page on which relations to other pages are described through the <code>tree:relation</code> predicate, and/or through which a next <code>tree:Node</code> can be found by using the <code>tree:search</code> form.
@@ -35,7 +35,7 @@ The first step when creating a TREE hypermedia interface is defining a collectio
     ```
 </div>
 
-From the moment this collection of members grows too big for one page, a fragmentation needs to be created in which an initial set of member can be found on an entry node, and more members can be found by interpreting the TREE hypermedia controls. This is illustrated by the next example:
+From the moment this collection of members grows too large for one page, a fragmentation needs to be created in which an initial set of member can be found on an entry node, and more members can be found by interpreting the TREE hypermedia controls. This is illustrated by the next example:
 
 <div class="example">
     ```turtle
@@ -46,9 +46,8 @@ From the moment this collection of members grows too big for one page, a fragmen
                 tree:member ex:Subject1, ex:Subject2 .
 
     ex:Node1 a tree:Node ;
-            tree:relation ex:R1,ex:R2 ;
-            tree:viewDescription ex:ViewDescription1 .
-
+            tree:relation ex:R1,ex:R2 .
+
     ex:R1 a tree:GreaterThanOrEqualToRelation ;
         tree:node ex:Node3 ; # This is the URL of another page
         tree:value 3;
@@ -92,19 +91,22 @@ A <code>tree:Collection</code> is a set of <code>tree:Member</code>s. The set of
 
 A <code>tree:Member</code> is a set of (at least one) quad(s) defined by the member extraction algorithm (next subsection).
 
-A <code>tree:Node</code> is a dereferenceable resource of <code>tree:Relation</code>s and a subset of (<code>⊆</code>) members of the collection. In a <code>tree:Node</code>, both the set of <code>tree:Relation</code>s as the subset of members MAY be empty. The same member MAY be contained in multiple nodes.
+A <code>tree:Node</code> is a dereferenceable resource containing <code>tree:Relation</code>s and a subset of (<code>⊆</code>) members of the collection. In a <code>tree:Node</code>, both the set of <code>tree:Relation</code>s as the subset of members MAY be empty. The same member MAY be contained in multiple nodes.
 
 A <code>tree:Relation</code> is a function denoting a conditional link to another <code>tree:Node</code>.
 
+A <code>tree:Node</code>, apart from the root node, has exactly one other <code>tree:Node</code> linking into it through one or more relations.
+
 Note: The condition of multiple <code>tree:Relation</code>s to the same <code>tree:Node</code> MUST be combined with a logical AND.
 
-A View is a specific set of interlinked <code>tree:Node</code>s, that together contain all members in a collection. A specific view will adhere to a certain growth or tree balancing strategy. In one view, completeness MUST be guaranteed.
+A View is a specific set of interlinked <code>tree:Node</code>s, that together contain all members in a collection. A specific view will adhere to a certain growth or tree balancing strategy. In one View, completeness MUST be guaranteed, unless the View has a retention policy which becomes possible in LDES.
 
-A <code>tree:search</code> form is a IRI template, that when filled out with the right parameters becomes a <code>tree:Node</code> IRI, or when dereferenced will redirect to a <code>tree:Node</code> from which all members in the collection that adhere to the described comparator can be found.
+A <code>tree:search</code> form is an IRI template, that when filled out with the right parameters becomes a <code>tree:Node</code> IRI, or when dereferenced will redirect to a <code>tree:Node</code> from which all members in the collection that adhere to the described comparator can be found.
 
-# The member extraction algorithm # {#member-extraction-algorithm}
+## The member extraction algorithm ## {#member-extraction-algorithm}
 
-TREE uses the [shape templates algorithm](https://w3id.org/tree/specification/shape-templates) to define the set of quads that are part of their members.
-It uses the `sh:NodeShape` from the `tree:shape` property on the collection 
+The set of quads the are part of the member, are defined by the [shape templates algorithm](https://w3id.org/tree/specification/shape-templates), provided as a separate report to this specification.
+It is a combination of Concise Bounded Descriptions, named graphs and Shape Templates.
+The latter uses the <code>sh:NodeShape</code> from the <code>tree:shape</code> property on the collections as an indication of the topology of the member graph.
 
 Note: The way we process SHACL shapes into Shape Template is important to understand in order to know when an HTTP request will be triggered when designing SHACL shapes. A cardinality constraint not being exactly matched or a <code>sh:pattern</code> not being respected will not trigger an HTTP request, and instead just add the invalid quads to the Member. This is a design choice: we only define triggers for HTTP request from the SHACL shape to come to a complete set of quads describing the member the data publisher pointed at using <code>tree:member</code>.

specs/1-discovery.md

@@ -1,6 +1,6 @@
 # Discovery and source selection# {#hypermedia}
 
-TREE tackles discovery on three levels: i) interface discovery, ii) view discovery, and iii) dataset discovery.
+TREE tackles discovery and source selection on three levels: i) interface discovery, ii) view discovery, and iii) dataset discovery.
 Interface discovery discovers what collection the current page is part of, and discovers what the next possible HTTP requests are through relations and search forms.
 One dataset can have multiple views that can be published across different servers, selecting one for a certain use case is part of the view discovery.
 Dataset discovery is then selecting a <code>tree:Collection</code> of interest.
@@ -13,18 +13,13 @@ A node from which all members of a collection can be discovered (an “entry nod
 
 When the current page is a <code>tree:Node</code>, there MUST be a property linking the current page URL to the URI of the <code>tree:Collection</code>. However, not from all <code>tree:Node</code>s all members can be reached, and therefore 2 other properties can be used: <code>void:subset</code>, or the inverse property, <code>dcterms:isPartOf</code>.
 
-Three properties MAY thus be used:
- 1. <code>ex:C1 tree:view <> .</code><br/>May be used *only* in the case when the entire <code>tree:Collection</code> can be found starting from the current node.
- 2. <code>ex:C1 void:subset <> .</code><br/>When the node is not a node from which all members can be found, but still is a subset of the collection that can be found.
- 3. <code><> dcterms:isPartOf ex:C1 .</code><br/>The inverse property of 2.
+<code>ex:C1 tree:view <> .</code> links the current page to the <code>tree:Collection</code>.
 
 We refer to next chapters for traversing across multiple relations, or for using search forms.
 
 ## View discovery ## {#multiple-views}
 
-Every node linked from <code>tree:view</code> MUST be an entry point to retrieve **all** members of the collection.
-Multiple <code>tree:view</code> links MAY be provided.
-If a TREE client wants to guarantee compleneteness, it picks one link and then traverses all relations.
+Todo: This will be reworked
 
 Note: How a client picks the right view is use case specific. The <code>tree:ViewDescription</code>’s properties can help in that regards.
 

specs/2-traversing.md

@@ -2,6 +2,8 @@
 
 The initial configuration of the <code>tree:Collection</code> and the description of the view is always provided when the view has been discovered, either in a separate document describing the view, either in the entry node itself. The configuration MUST be reused on any subsequent <code>tree:Node</code>.
 
+While discovering and traversing the interface, a client MUST take the descriptions on top of the Node, the View and the Collection with it.
+
 ## Traversing relations ## {#traversing}
 
 A <code>tree:Node</code> element MAY have one or more <code>tree:relation</code> properties. A relation is an entity of the type <code>tree:Relation</code>, and MAY have a more specific type. A <code>tree:Relation</code> MUST have one <code>tree:node</code> object of the type <code>tree:Node</code>. By default, all nodes need to be followed, unless the client is able to select this relation for pruning (see next section).
@@ -25,6 +27,8 @@ Note: This enables rebalancing search trees.
 
 ## Fallbacks ## {#fallbacks}
 
+When there is no <code>tree:view</code> triple provided, a client MUST use the <code>tree:Collection</code> from the previous page and still continue extracting members, and extract further relations defined on the current page URL.
+
 When there are no <code>tree:member</code>s and/or no <code>tree:Collection</code> defined, then still a <code>tree:Relation</code> can be defined. The <code>tree:path</code> in the <code>tree:Relation</code> then refers to a pattern that can start from every triple in the page.
 
 When no <code>tree:path</code> is defined, the <code>tree:value</code> MUST be compared to all members’ triples that *can be compared to* the <code>tree:value</code> as defined by the type of the relation (or when no members or collection are defined, on every triple in the page).
@@ -33,7 +37,7 @@ When due to <code>rdfs:range</code> incompatibility, the object cannot be compar
 Note: This may enable server developers to indicate an index on all literals of the members (e.g., a prefix relation on title, description and body text) without having to indicate all of the alternative paths in the <code>tree:path</code>.
 
 The target object of a <code>tree:path</code> SHOULD be materialized in the current Node document, but when it is not, the object MAY be considered implicit on the condition both <code>tree:path</code> and <code>tree:member</code> are defined.
-In contrast to <code>shacl:path</code>, a <code>tree:path</code> MAY refer to an implicit property and may not be materialized in the current response. This may break SPARQL processors that did not yet come across the object before in their query plan. However, the tree may still be useful for query processors that, for example, prioritize queries according to the user’s location, and first download nodes that are nearby the user. Therefore, the materialized location of the object is not needed. While not recommended, possible heuristics could try to infer the data, could try to fetch it through another <code>tree:Collection</code>, or retrieve it using URI dereferencing.
+In contrast to <code>sh:path</code>, a <code>tree:path</code> MAY refer to an implicit property and may not be materialized in the current response. This may break SPARQL processors that did not yet come across the object before in their query plan. However, the tree may still be useful for query processors that, for example, prioritize queries according to the user’s location, and first download nodes that are nearby the user. Therefore, the materialized location of the object is not needed. While not recommended, possible heuristics could try to infer the data, could try to fetch it through another <code>tree:Collection</code>, or retrieve it using URI dereferencing.
 
 ## Specific relations ## {#relationsubclasses}
 

tree.ttl

@@ -147,7 +147,7 @@ tree:path a rdf:Property ;
 
 tree:view a rdf:Property ;
           rdfs:label "View"@en ;
-          rdfs:comment "Links the collection to a `tree:Node` from which all other members can be found."@en ;
+          rdfs:comment "Links the collection to the current page."@en ;
           rdfs:domain tree:Collection ;
           rdfs:range tree:Node .
 

vocabulary.md

@@ -91,7 +91,7 @@ See [](#relations)
 
 ### tree:view ### {#view}
 
-Links the collection to a <code>tree:Node</code> from which all members can be found. If only a part of the collection’s members can be found from that point on, only use <code>dcterms:isPartOf</code> or <code>void:subset</code>.
+Links the collection to the current <code>tree:Node</code>.
 
 **Domain**: <code>tree:Collection</code>