02-shape-topologies.bs

<pre class='metadata'>
Title: The Shape Topologies algorithm
Shortname: ShapeTopologies
Level: 1
Status: w3c/CG-DRAFT
Markup Shorthands: markdown yes
URL: https://w3id.org/tree/specification/shape-topologies
Repository: https://github.com/treecg/specification
Mailing List: public-treecg@w3.org
Mailing List Archives: https://lists.w3.org/Archives/Public/public-treecg/
Editor: Pieter Colpaert, https://pietercolpaert.be
Abstract:
    This algorithm defines what quads are part of an entity description.
    It uses the concepts of Concise Bounded Descriptions, adds well-defined support for named graphs, and introduces the concept of a shape topology.
    A shape topology is a structure of an entity description that follows similar design principles as SHACL Node Shapes.
    The algorithm returns the quads that match, and also provides hooks for the client to fetch more quads elsewhere (i.e. by dereferencing the subject).
</pre>

# The algorithm # {#algorithm}

Input:
 * The subject IRI `M`. This is the first focus node.
 * An optional [shape topology](#shape-topology-extraction) and a Term for the shape to start from `S`
 * A list of other subject IRIs to ignore, because we do not want to include quads from other entity descriptions.

Process:
 1. When a shape topology was set, execute the shape topology extraction algorithm, yet exclude all quads that have another member (from the current context) set as their named graph
 2. If no shape topology was set, extract all quads with subject the focus node, and recursively include its blank nodes (see also [[!CBD]])
 3. Extract all quads with the graph name matching the focus node
 4. When no quads were extracted from steps 1-3, a client MUST fetch more information about the focus node (i.e. by dereferencing it) and re-execute 1-3.

## Shape Topology extraction ## {#shape-topology-extraction}

The Shape Topology is a structure that looks as follows:

<div class="example">
    ```typescript
    class ShapeTopology {
        closed: boolean;
        requiredPaths: Path[];
        optionalPaths: Path[];
        nodelinks: NodeLink[];
        atLeastOneLists: [ Shape[] ];
    }
    class NodeLink {
        shape: ShapeTopology;
        path: Path;
    }
    ```
</div>

Paths in the shape topologies are [SHACL Property Paths](https://www.w3.org/TR/shacl/#property-paths).

A Shape Topology has
 * <strong>Closed:</strong> A boolean telling whether it’s closed or not. If it’s open, a client MUST extract all quads, after a potential HTTP request to the focus node, with subject the focus node, and recursively include its blank nodes
 * <strong>Required paths:</strong> MUST trigger an HTTP request if the member does not have this path. All quads from paths, after a potential HTTP request, matching this required path MUST be added to the Member set.
 * <strong>Optional paths:</strong> All quads from paths, after a potential HTTP request, matching this path MUST be added to the Member set.
 * <strong>Node Links:</strong> A nodelink contains a reference to another Shape Topology, as well as a path. All quads, after a potential HTTP request, matching this path MUST be added to the Member set. The targets MUST be processed again using the shape topology extraction algorithm on that 
 * <strong>atLeastOneLists</strong>: Each atLeastOneList is an array of at least one shape with one or more required paths and atLeastOneLists that must be set. If none of the shapes match, it will trigger an HTTP request. Only the quads from paths matching valid shapes are included in the Member.

Note: Certain quads are going to be matched by the algorithm multiple times. Each quad will of course be part of the member only once.

This results in this algorithm:
 1. If it is open, a client MUST extract all quads, after a potential HTTP request to the focus node, with subject the focus node, and recursively include its blank nodes
 2. If the current focus node is a named node and it was not requested before:
    - test if all required paths are set, if not do an HTTP request, if they are set, then,
    - test if at least one of each list in the atLeastOneLists was set. If not, do an HTTP request.
 3. Visit all paths (required, optional, nodelinks and recursively the shapes in the atLeastOneLists if the shape is valid) paths and add all quads necessary to reach the targets to the result
 4. For the results of nodelinks, if the target is a named node, set it as a focus node and repeat this algorithm with that nodelink’s shape as a shape

### Generating a shape topology from SHACL ### {#shacl-to-shape-template}

On a <code>tree:Collection</code>, a SHACL shape MAY be provided with the <code>tree:shape</code> property.
In that case, the SHACL shape MUST be processed towards a Shape topology as follows:

 1. Checks if the shape is deactivated (<code>:S sh:deactivated true</code>), if it is, don’t continue
 2. Check if the shape is closed (<code>:S sh:closed true</code>), set the closed boolean to true.
 3. All <code>sh:property</code> elements with an <code>sh:node</code> link are added to the shape’s NodeLinks array
 4. Add all properties with <code>sh:minCount</code> > 0 to the Required Paths array, and all others to the optional paths.
 5. Processes the [conditionals](https://www.w3.org/TR/shacl/#core-components-logical) <code>sh:xone</code>, <code>sh:or</code> and <code>sh:and</code> (but doesn’t process <code>sh:not</code>):
    - <code>sh:and</code>: all properties on that shape topology MUST be merged with the current shape topology
    - <code>sh:xone</code> and <code>sh:or</code>: in both cases, at least one item must match at least one quad for all required paths. If not, it will do an HTTP request to the current namednode.