diff --git a/specs/0-introduction.md b/specs/0-introduction.md index 487db04..07b2335 100644 --- a/specs/0-introduction.md +++ b/specs/0-introduction.md @@ -5,7 +5,7 @@ The TREE specification introduces these core concepts: * a tree:Collection is a subclass of dcat:Dataset ([[!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: - tree:member points at the first focus node from which to retrieve and extract all quads of a member. - - tree:view points to a tree:Node from which all members can be reached. + - tree:view points to the current tree:Node you’re visiting. - tree:shape indicates the [[!SHACL]] shape to which each member in the collection adheres. - tree:viewDescription links to a description of the view (a tree:ViewDescription). Multiple descriptions MAY be provided that MUST be combined. * a tree:Node: is a page on which relations to other pages are described through the tree:relation predicate, and/or through which a next tree:Node can be found by using the tree:search form. @@ -35,7 +35,7 @@ The first step when creating a TREE hypermedia interface is defining a collectio ``` -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:
```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 tree:Collection is a set of tree:Members. The set of A tree:Member is a set of (at least one) quad(s) defined by the member extraction algorithm (next subsection). -A tree:Node is a dereferenceable resource of tree:Relations and a subset of (⊆) members of the collection. In a tree:Node, both the set of tree:Relations as the subset of members MAY be empty. The same member MAY be contained in multiple nodes. +A tree:Node is a dereferenceable resource containing tree:Relations and a subset of (⊆) members of the collection. In a tree:Node, both the set of tree:Relations as the subset of members MAY be empty. The same member MAY be contained in multiple nodes. A tree:Relation is a function denoting a conditional link to another tree:Node. +A tree:Node, apart from the root node, has exactly one other tree:Node linking into it through one or more relations. + Note: The condition of multiple tree:Relations to the same tree:Node MUST be combined with a logical AND. -A View is a specific set of interlinked tree:Nodes, 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 tree:Nodes, 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 tree:search form is a IRI template, that when filled out with the right parameters becomes a tree:Node IRI, or when dereferenced will redirect to a tree:Node from which all members in the collection that adhere to the described comparator can be found. +A tree:search form is an IRI template, that when filled out with the right parameters becomes a tree:Node IRI, or when dereferenced will redirect to a tree:Node 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 sh:NodeShape from the tree:shape 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 sh:pattern 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 tree:member. diff --git a/specs/1-discovery.md b/specs/1-discovery.md index a0311d1..f6bbc05 100644 --- a/specs/1-discovery.md +++ b/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 tree:Collection 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 tree:Node, there MUST be a property linking the current page URL to the URI of the tree:Collection. However, not from all tree:Nodes all members can be reached, and therefore 2 other properties can be used: void:subset, or the inverse property, dcterms:isPartOf. -Three properties MAY thus be used: - 1. ex:C1 tree:view <> .
May be used *only* in the case when the entire tree:Collection can be found starting from the current node. - 2. ex:C1 void:subset <> .
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. <> dcterms:isPartOf ex:C1 .
The inverse property of 2. +ex:C1 tree:view <> . links the current page to the tree:Collection. We refer to next chapters for traversing across multiple relations, or for using search forms. ## View discovery ## {#multiple-views} -Every node linked from tree:view MUST be an entry point to retrieve **all** members of the collection. -Multiple tree:view 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 tree:ViewDescription’s properties can help in that regards. diff --git a/specs/2-traversing.md b/specs/2-traversing.md index 8e9ad50..1238e84 100644 --- a/specs/2-traversing.md +++ b/specs/2-traversing.md @@ -2,6 +2,8 @@ The initial configuration of the tree:Collection 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 tree:Node. +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 tree:Node element MAY have one or more tree:relation properties. A relation is an entity of the type tree:Relation, and MAY have a more specific type. A tree:Relation MUST have one tree:node object of the type tree:Node. 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 tree:view triple provided, a client MUST use the tree:Collection from the previous page and still continue extracting members, and extract further relations defined on the current page URL. + When there are no tree:members and/or no tree:Collection defined, then still a tree:Relation can be defined. The tree:path in the tree:Relation then refers to a pattern that can start from every triple in the page. When no tree:path is defined, the tree:value MUST be compared to all members’ triples that *can be compared to* the tree:value 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 rdfs:range 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 tree:path. The target object of a tree:path SHOULD be materialized in the current Node document, but when it is not, the object MAY be considered implicit on the condition both tree:path and tree:member are defined. -In contrast to shacl:path, a tree:path 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 tree:Collection, or retrieve it using URI dereferencing. +In contrast to sh:path, a tree:path 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 tree:Collection, or retrieve it using URI dereferencing. ## Specific relations ## {#relationsubclasses} diff --git a/tree.ttl b/tree.ttl index a5be0d0..7c82975 100644 --- a/tree.ttl +++ b/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 . diff --git a/vocabulary.md b/vocabulary.md index 87486e3..b1b1beb 100644 --- a/vocabulary.md +++ b/vocabulary.md @@ -91,7 +91,7 @@ See [](#relations) ### tree:view ### {#view} -Links the collection to a tree:Node 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 dcterms:isPartOf or void:subset. +Links the collection to the current tree:Node. **Domain**: tree:Collection