Shape Trees Specification

1. Introduction

This section is non-normative.

Realizing the value proposition of the Semantic Web lies in building useful and robust applications that can interoperate over linked data. Protocols such as [LDP] and [Solid] organize linked data graphs into resource hierarchies, providing a foundation upon which these robust and interoperable applications can be created.

Application interoperability depends on applications sharing semantics for relationships and data structures. Existing technologies fulfill portions of those dependencies:

• RDF's foundation in unambiguous identifiers provides an infrastructure that allows for interoperability, but does not specifically encourage or enforce it.

• Shape languages (e.g. [ShEx] and [SHACL]) provide machine-readable, enforceable data structure definitions on single resources.

For applications that operate on more complex and interconnected resources, Shape Trees express the layout of those resources and associate them with their respective shapes.

Shape trees marry RDF vocabularies, shapes, and resources into "little trees" that provide machine to machine interoperability, combining them into concepts that humans can easily comprehend, such as medical records, notes, notebooks, calendars, and financial records.

This allows one to treat a set of related resources as a single grouping, and apply that to a range of operations including access control, data organization, data validation, and data migration.

Shape trees are defined as an RDF graph structure that expresses a set of expected behaviors by agents that work with them. These semantics CAN be implemented by a server-side agent, or a client-side agent that pre-processes requests to a server. In the most typical use case, a server-side agent enforces the expected behaviors on data as it is manipulated by a client-side agent.

While shape trees are intended to adapt to different technology platforms that support the notion of containers and resources, examples in this specification will reflect usage in an [LDP] environment.

2. Shape Tree

A shape tree is a machine-readable template describing the expected layout of a tree of resources in a container-based ecosystem. A shape tree expresses a tree hierarchy by containing other shape trees. The terms used to express a shape tree are described using an [RDF] vocabulary.

A shape tree instance is a resource or set of resources assigned to and in conformance with a given shape tree. A resource in a shape tree instance is called a managed resource.

Every managed resource has an associated shape tree locator. A shape tree locator identifies the shape tree associated with a managed resource, and additional information needed to navigate nested hierarchies of managed resources.

The st:expectsType property specifies that the described managed resource be one of these three types:

The st:shape property specifies that the described managed resource conforms to the stated [ShEx] or [SHACL] shape.

Shape trees prescribe physical hierarchies and can reference other shape trees to form virtual hierarchies.

In a physical hierarchy, a shape tree expresses a managed resource that explicitly contains another managed resource via st:contains.

If shape tree S1 st:contains shape tree S2, S1 describes a container that contains another managed resource described by S2. For example, in [LDP], S1 describes an [LDP] container which ldp:contains nested resources described by S2.

PREFIX st: <http://www.w3.org/ns/st#>
PREFIX ex: <http://www.example.com/ns/ex#>

<#ProjectTree>
  a st:ShapeTree ;
  st:expectsType st:ShapeTreeContainer ;
  st:shape ex:ProjectShape ;
  st:contains <#MilestoneTree> ,
              st:AllowNone .

<#MilestoneTree>
  a st:ShapeTree ;
  st:expectsType st:ShapeTreeContainer ;
  st:shape ex:MilestoneShape ;
  st:contains <#TaskTree>, <#IssueTree> ; 
  st:AllowNone .

<#TaskTree>
  a st:ShapeTree ;
  st:expectsType st:ShapeTreeContainer ;
  st:shape ex:TaskShape ;
  st:contains <#AttachmentTree> ,
  st:AllowNone .

<#IssueTree>
  a st:ShapeTree ;
  st:expectsType st:ShapeTreeContainer ;
  st:shape ex:IssueShape ;
  st:contains <#AttachmentTree> ,
  st:AllowNone .

<#AttachmentTree>
  a st:ShapeTree ;
  st:expectsType st:ShapeNonRDFResource .

In a virtual hierarchy, a shape tree defines one or more shape tree references via st:references. A shape tree reference identifies the shape tree to be referenced via st:hasShapeTree, and the shape path through which it is linked via st:traverseViaShapePath.

A shape path is a string that defines a traversal of a shape schema. [SHEXPATH]

PREFIX st: <http://www.w3.org/ns/st#>
PREFIX ex: <http://www.example.com/ns/ex#>

<#VirtualProjectTree>
  a st:ShapeTree ;
  st:expectsType st:ShapeTreeResource ;
  st:shape ex:ProjectShape ;
  st:references [
    st:hasShapeTree <#VirtualMilestoneTree> ;
    st:traverseViaShapePath "@ex:ProjectShape/ex:hasMilestone"
  ] .

<#VirtualMilestoneTree>
  a st:ShapeTree ;
  st:expectsType st:ShapeTreeResource ;
  st:shape ex:MilestoneShape ;
  st:references [
    st:hasShapeTree <#VirtualTaskTree> ;
    st:traverseViaShapePath "@ex:MilestoneShape/ex:hasTask"
  ] ,
  [
    st:hasShapeTree <#VirtualIssueTree> ;
    st:traverseViaShapePath "@ex:IssueShape/ex:hasIssue"
  ] .

<#VirtualTaskTree>
  a st:ShapeTree ;
  st:expectsType st:ShapeTreeResource ;
  st:shape ex:TaskShape ;
  st:references [
    st:hasShapeTree <#VirtualAttachmentTree> ;
    st:traverseViaShapePath "@ex:AttachmentShape/ex:hasAttachment"
  ] .

<#VirtualIssueTree>
  a st:ShapeTree ;
  st:expectsType st:ShapeTreeContainer ;
  st:shape ex:IssueShape ;
  st:references [
    st:hasShapeTree <#VirtualAttachmentTree> ;
    st:traverseViaShapePath "@ex:AttachmentShape/ex:hasAttachment"
  ] .

<#VirtualAttachmentTree>
  a st:ShapeTree ;
  st:expectsType st:ShapeNonRDFResource .

Let ST be a shape tree. Let STI be a corresponding shape tree instance.

• An { ST st:expectsType T } arc identifies the resource type T of a corresponding managed resource R in STI where T MUST be one of st:ShapeTreeResource, st:ShapeTreeContainer, or st:ShapeTreeNonRDFResource.

• An { ST rdfs:label L } arc indicates that there is exactly one corresponding managed resource R in STI and it has the name L.

• An { ST st:shape SH } arc indicates that managed resource R has exactly one node which conforms to shape SH.

• An { ST st:contains ST2 } arc indicates a nested shape tree ST2.

• An { ST st:references STR } arc indicates that the shape tree identified in shape tree reference STR, is referenced through the instance data of STI.

  • An { STR st:hasShapeTree ST3 } arc indicates a shape tree referenced through the instance data of STI

  • An { STR st:traverseViaShapePath SHPH } arc identifies the shape path through which a shape tree instance of ST3 can be found via the instance data of STI

• An { ST st:supports ST4 } arc indicates that ST provides supporting or supplementary context to ST4.

A { ST st:hasShapeTreeDecoratorIndex DI } arc indicates the location of an index of SKOS hierarchies that describes ST.

2.1. Shape Tree Schema

PREFIX st: <http://www.w3.org/ns/st#>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>

<#ShapeTree> {
  a st:ShapeTree ;
  (
    st:expectsType [st:ShapeTreeContainer] ;
    st:contains @<#ShapeTree> +
    |
    st:expectsType [st:ShapeTreeResource, st:ShapeTreeNonRDFResource]
  ) ;
  rdfs:label xsd:string ? ;
  st:references @<#ReferencedShapeTree> * ;
  st:shape IRI ? ;
  st:contains IRI ? ;
  st:supports IRI ? ;
}

<#ReferencedShapeTree> {
  st:hasShapeTree IRI ;
  st:traverseViaShapePath xsd:string
}

3. Shape Tree Locator

A shape tree locator associates a managed resource with one or more shape trees. No more than one shape tree locator may be associated with a managed resource.

For example, in [Solid] a shape tree locator would be stored in an auxiliary resource associated with a given managed resource.

A shape tree locator includes one or more shape tree locations via st:location. Each shape tree location identifies a shape tree associated with the managed resource, the focus node for shape validation, and the information needed to navigate the physical hierarchy in which that managed resource resides.

If there is more than one shape tree location, they are all applied to the managed resource associated with the shape tree locator.

Shape tree locations identify key contextual points in a physical hierarchy:

• A shape tree root marks the primary, or parent shape tree in a physical hierarchy, and is set by the Plant Operation.

• A shape tree instance root marks the primary, or parent shape tree instance in a physical hierarchy, and is set by the Plant Operation.

A shape tree root, and its corresponding shape tree instance root can be planted within an existing managed hierarchy, alongside or within other shape tree roots and shape tree instance roots.

Shape tree locations in a given shape tree locator may have different focus nodes.

PREFIX st: <http://www.w3.org/ns/st#> 
PREFIX ex: <http://www.example.com/ns/ex#>
PREFIX data: <https://storage.example.com/data/>

<#locator>
  a st:ShapeTreeLocator ;
  st:location [
    st:hasRootShapeTree ex:DataTree ;
    st:hasShapeTree ex:DataTypeTree ;
    st:hasShapeTreeInstanceRoot data: ;
    st:node data:projects#collection ;
    st:shape ex:DataCollectionShape ;
  ], [
    st:hasRootShapeTree ex:ProjectsTree ;
    st:hasShapeTree ex:ProjectsTree ;
    st:hasShapeTreeInstanceRoot data:projects ;
    st:node data:projects#collection ;
    st:shape ex:ProjectCollectionShape ;
  ] .

PREFIX st: <http://www.w3.org/ns/st#> 
PREFIX ex: <http://www.example.com/ns/ex#>
PREFIX data: <https://storage.example.com/data/>
PREFIX task-48: <https://storage.example.com/data/projects/project-1/milestone-A/task-48>

<#locator>
  a st:ShapeTreeLocator ;
  st:location [
    st:hasRootShapeTree ex:ProjectsTree ;
    st:hasShapeTree ex:TaskTree ;
    st:hasShapeTreeInstanceRoot data:projects ;
    st:node task-48#task ;
    st:shape ex:TaskShape ;
  ] .

A shape tree location may be used to provide shape validation only, in which case only the focus node and shape are provided, via st:node and st:shape, respectively.

PREFIX st: <http://www.w3.org/ns/st#> 
PREFIX ex: <http://www.example.com/ns/ex#>
PREFIX project1: <https://storage.example.com/data/projects/project-1#>

<#locator>
  a st:ShapeTreeLocator ;
  st:location [
    st:node project1:project ;
    st:shape ex:ProjectShape ;
] .

3.1. Shape Tree Locator Schema

PREFIX st: <http://www.w3.org/ns/st#>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>

<#ShapeTreeLocatorShape> {
  a [st:ShapeTreeLocator] ;
  st:location @<#ShapeTreeLocationShape>+
}  

<#ShapeTreeLocationShape> {
  st:hasRootShapeTree IRI ;
  st:hasShapeTree IRI ;
  st:hasShapeTreeInstanceRoot IRI ;
  ( st:node IRI ;
    st:shape IRI )?
  |
  st:node IRI ;
  st:shape IRI
}

4. Shape Tree Operations

Working with shape trees entails using several higher-level operations —each of which may represent one or more HTTP requests and/or pieces of processing logic.

The key operations used to manage shape trees are:

• Discover Shape Tree

• Plant Shape Tree

• Create Shape Tree Instance

• Update Shape Tree Instance

• Delete Shape Tree Instance

• Unplant Shape Tree

These operations make use of reusable, internal algorithms defined in Shape Tree Algorithms.

4.1. Discover Shape Tree

PREFIX st: <http://www.w3.org/ns/st#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

<#DecoratorIndex> {
  a [ st:ShapeTreeDecoratorIndex ] ;
  st:defaultLanguage xsd:language ? ;
  st:hasSet IRI*
}

<#DecoratorSet> {
  a [ st:ShapeTreeDecoratorSet ] ;
  st:usesLanguage xsd:language ;
  st:hasShapeTreeDecoratorResource IRI
}

<#Decorator> {
  a [ st:ShapeTreeDecorator ] ;
  st:hasShapeTree IRI ;
  skos:prefLabel xsd:string ;
  skos:definition xsd:string ?
}