Remote subgraph use cases

This page describes the use cases for the planned future development of the remote graph feature.

Trustable projects can export validated instances of their graph as TSF project artifacts. These can define subgraphs, such as a needs graph, which may be referenced or imported by other projects to expand upon them in their own context. The resolved evidence artifacts provided by the exporting projects can be referenced by a project consuming the artifact, but not imported.

Consuming projects use Junctions to specify the graphs and subgraphs they import. These specify the project artifact for the graph and namespaces for imported subgraphs. Statements in the local project can then include References to Statements in the remote graph, or link to Statements in an imported subgraph using the namespaces specified in the Junction.

A junction can also reference a Junction specified in another project, to consume the same version of a 'parent' graph.

• e.g. In the illustration above, Z is consuming a subgraph from the same version of X as specified by Y.

This junction-of-a-junction approach is included to enable the explicit selection and inclusion of a specific version of an upstream graph as specified by a given project.

• This is preferred over implicit inclusion because a project may have more than one remote graph, which may in turn have a shared remote
• An obvious example of a shared remote is the Trustable project itself

Types of subgraph

Imported subgraphs should include any artifacts referenced by the included Statements (ref. 1 in the diagram).

• e.g. A document referenced by a Statement to qualify / clarify its meaning
• For this reason, any such artifacts should be stored in coordination with the Statements that reference them

However, imported subgraphs should not include evidence artifacts that are specific to the originating project.

• Distinguishing these automatically is not possible with the current trudag / dotstop implementation.
• Future versions of the tooling and data format should make an explicit distinction between artifacts referenced as evidence and referenced artifacts that qualify a Statement
• See the TSF Architecture for the use of References and Evidence to facilitate these distinctions.

Given the Architecture as specified, subgraphs may include (or omit) evidence in a variety of ways:

• For ref. 2, only a Premise is included in the subgraph, so the importing project must attach context-specific Evidence to this.
• For ref. 3, an Evidence element is included, and this identifies the Validator that will be used, but this may need to be overridden in the consuming context to describe the evidence artifacts that the Validator will process.
• For ref. 4, an Evidence element with a Reference is included. The Reference identifies a file that is local to the git repository, which identifies the input evidence artifacts needed by the Validator. The consuming project may therefore provide a file in the same file path, which provides the Validator with the required information.