Warning:
This wiki has been archived and is now read-only.

# Shacl-language

## Introduction

This page contains a list of the proposed SHACL language constructs and compares their meaning in the different SHACL proposals.

The goal is to identify the common terms which can be the basis of the SHACL vocabulary.

## Comparison of vocabulary terms

### Structural Definitions

This table contains a partial list of the high-level language constructs that have been identified in the different proposals. The comments section contains natural language explanations of their intended meaning.

As Peter has said: "Some of these correspondences are exact, some are close, and some are not so close".

Concept Abstract Syntax SHACL vocab, Eric SHACL SPARQL Peter SHACL spec Holger Comments
Condition sh:Condition rdfs:Class (for class-scoped shapes) Class of scoped constraints, generally a shape and a way of determining which nodes to validate the shape on.
Shape Shape sh:Shape sh:Shape sh:Shape Class of shapes, i.e., the things that nodes are validated against
shape sh:shape Link from a condition to the shape that it uses.
Constraint sh:Shape Class of constraints, i.e., pieces of shapes that provide the conditions required to validate in the shape.
PropertyConstraint Property Constraint sh:PropertyConstraint sh:Shape sh:Constraint Class of Property constraints, i.e., constraints that involve a property's values
Arc Arc sh:property sh:Shape with sh:predicate  ? defines the characteristics of matching triples associated with the focus node. Term constraints apply to the object of matching triples.
inverseArc InverseArc sh:inverseProperty sh:Shape with sh:inversePredicate  ? defines the characteristics of matching triples associated with the focus node. Term constraints apply to the subject of matching triples.
And And (implicit in a shape) sh:and (implicit in a shape) Conjunction. It produces true if evaluation of each of the conjuncts with the focus node produces true.
Or Or sh:choice sh:or sh:orConstraint Inclusive disjunction. It produces true if evaluation of any of the constituent constraints with the focus node produces true.
Type sh:type An RDFS type of the focus node itself (i.e., not the type of property values).
ValueShape ValueShape shape sh:valueShape sh:valueShape sh:hasValue ?? The result of matching the property values with a shape.
Value sh:hasValue The evaluated value of a property is this value.
AllowedValue AllowedValue value sh:allowedValue sh:allowedValues sh:allowedValues The evaluated value of a property is a member of the set of allowed values.
NodeType NodeType sh:nodeType sh:nodeType sh:nodeType sh:nodeKind The kind of node of property values (IRI, RDF literal, or Blank Node).
ValueType Type sh:valueType A class that the property values belong to.
ValueDatatype Datatype sh:valueType sh:valueDatatype sh:ValueType The datatype that property values have (or belong to).
Language tags LanguageTag - - - Language tag of a literal. Constraint the value of a string literal takiing into account its language tag.
Exact Cardinality sh:cardinality sh:count The exact number of values for a property (when minCount and maxCount are the same)
MinCardinality MinCardinality sh:minCard sh:minCardinality sh:minCount The minimum number of values for a property. Property constraints without a minimum cardinality use 1.
MaxCardinality MaxCardinality sh:maxCard sh:maxCardinality sh:maxCount The maximum number of values for a property. Property constraints without a maximum cardinality use 1 or unbounded.
Predicate Predicate sh:predicate sh:predicate and sh:inversePredicate sh:predicate identifies the triple's predicate
Empty Empty (doesn't need to be defined) (not needed) - Empty constraint. An empty shape can have sh:empty constraints. This construct is useful for semantic definitions.
XOr - - via SPARQL - Exclusive-or. It produces true if the evaluation of only one of the nodes is true. It could be defined as sh:oneOf
Not - - via SPARQL - Negation of arcs (or shapes)
Close - - - - Closed shapes
Group Group - - - Property groups (they appear in SHACL primer)
Interleave - - - - Interleave. Based on bag semantics. TODO: Explain with Iovka's example

#### Kinds of nodes

Identification of different types of nodes

Concept Abstract Syntax SHACL vocab, Eric SHACL SPARQL Peter SHACL spec Holger Comments
IRI IRI sh:IRI "IRI" sh:IRI Node type of IRIs
Literal Literal sh:Literal "literal" sh:Literal Node type of Literals
BNode BNode sh:BNode "blank" sh:BlankNode Node type of blank nodes
OtherNodeTypes - - (not needed) sh:BlankNodeOrIRI Other node types

Example of a shape that has a property 'foaf:knows' with values of type 'sh:IRI'

```ex:shape a sh:Shape
sh:property [
sh:predicate foaf:knows ;
sh:nodeType sh:IRI ;
] .
```

Name of property:

• In this email, Holger proposed to name the property 'sh:nodeKind'
• In this email, Richard proposed 'sh:termKind' and 'sh:kind'

#### Constraints on Datatypes

Holger proposes a datatype property constraints similar to their XSD equivalent

Concept Abstract Syntax SHACL vocab, Eric SHACL SPARQL Peter SHACL spec Holger Comments
? - - - sh:maxExclusive Maximum exclusive value (<)
? - - - sh:maxInclusive Maximum inclusive value (<=)
? - - - sh:minExclusive Minimum exclusive value (>)
? - - - sh:minInclusive Minimum inclusive value (>=)
? - - - sh:length Exact string length
? - - - sh:maxLength Maximum string length
? - - - sh:minLength Minimum string length
? - - - sh:pattern Regular expression string matching

Concept Abstract Syntax SHACL vocab, Eric SHACL SPARQL Peter SHACL spec Holger Comments
Violation - - sh:Violation sh:ConstraintViolation Class of Constraint violations
Warning - - sh:warning sh:Warning A non-critical constraint violation indicating a warning.
Error - - sh:error sh:Error A constraint violation indicating an error.
FatalError - - sh:fatalError sh:FatalError An error that cannot be recovered and further evaluation may terminate immediately.
Severity levels - - sh:severity sh:level This property is employed in the examples but I think there is no definition for it in the document
TargetNode - - (from return values) and sh:report sh:root point to an IRI or blank node that has caused the violation.
Failed properties - - - (via SPARQL CONSTRUCT) sh:path a SPARQL path expression that can be walked starting at the sh:root. ISSUE: This depends on SPARQL Path expressions
Error Values - - - (via SPARQL CONSTRUCT) sh:value points to specific nodes that caused the violation
Source - - - (via SPARQL CONSTRUCT) sh:source point to constraint that caused the violation
Error details - - - (via SPARQL CONSTRUCT) sh:detail link to a parent constraint violation? Description is not clear.
Error Message - - - - sh:message Human-readable message

### Scope and node selection

Concept Abstract Syntax SHACL vocab, Eric SHACL SPARQL Peter SHACL spec Holger Comments
NodeShape NodeShape sh:nodeShape sh:individualScope sh:nodeShape asserts that a particular node in some graph conforms to a specific shape
ClassShape ClassShape sh:classShape sh:classScope (sh:constraint, sh:property, sh:inverseProperty in inverse direction) asserts that every node of some type conforms to a specific shape.
- - - sh:shapeScope (sh:shape) link to a SHACL shape
- - - sh:sparqlScope (sh:shape) link to a string literal. Defines the scope of a SHACL constraint.
- - - sh:sparqlShape - TODO: Review definition
- - -  ?? sh:constraint In this table, Peter says that sh:constraint semantics is not so close

### Core evaluation mechanism

Concept Abstract Syntax SHACL vocab, Eric SHACL SPARQL Peter SHACL spec Holger Comments
?  ?  ? sh:condition via global constraints Gives the SPARQL query for a condition directly.
?  ?  ? sh:sparqlShape sh:sparql Gives the SPARQL query fragment for the shape associated with a condition or class.

### Extensibility mechanism and macros

Concept Abstract Syntax SHACL vocab, Eric SHACL SPARQL Peter SHACL spec Holger Comments
?  ?  ? sh:condition sh:sparql Gives the SPARQL query or query fragment directly.
Macros  ?  ?  ? sh:template a macro (also called template in Holger's spec)
Macros  ?  ?  ? sh:ConstraintTemplate the class of of constraint templates. It is a subclass of template
Macros  ?  ?  ? sh:Template the class of templates. It could contain other kinds of templates.
Macros  ?  ?  ? sh:argument Argument of the template
Macros  ?  ?  ? sh:defaultValue default value for the argument
Macros  ?  ?  ? sh:optional indicate that the argument is not mandatory
Macros  ?  ?  ? sh:labelTemplate suggest how instances of the template shall be rendered to humans
Functions  ?  ?  ? sh:Function defines a function
Functions  ?  ?  ? sh:returnType declares a single return type
Functions  ?  ?  ? sh:cachable always return the same value for the same combination of arguments, regardless of the query graphs. Engines can use this information to cache and reuse previous function calls without repeatedly evaluating their executable body.

### Other Definitions

TODO: This are the list of vocabulary terms from Peter's proposal that I still have to figure out where to put.

```sh:shape		sh:constraint
sh:report
sh:type
```

TODO: Where should I put the following SPARQL functions that appear in Holger's spec?

This templates are mentioned in Appendix B Holger's spec and it appears that they are part of "sh" namespace, so I included them. TODO: Decide what to do with following templates that appear in Holger's spec?

• sh:AbstractAllowedValuesPropertyConstraint
• sh:AbstractHasValuePropertyConstraint
• sh:AbstractCountPropertyConstraint
• sh:AbstractNodeTypePropertyConstraint
• sh:AbstractValueShapePropertyConstraint

## List of terms, examples and comments

### Structural definitions

#### Shape

Represents the class of Shapes.

Example:

```ex:Anything a sh:Shape .
```

#### Property constraint

Defines the class of Property Constraints

#### Arc

Defines a direct basic Arc

Example (a shape that identifies nodes that have rdfs:label with values of type xsd:string).

```ex:shape a sh:Shape
sh:property [
sh:predicate rdfs:label ;
sh:valueDatatype xsd:string ;
sh:minCount 1
] .
```

If there are more properties defined they are implicitly interpreted as conjunctions.

TODO: Talk about single occurrence vs multi-occurrence and the interaction between other property definitions with the

```same predicate and different values.
```

#### Inverse Arc

Defines an inverse Arc

Example (a shape that identifies nodes that receive arcs with predicate foaf:knows from subjects of type foaf:Person

```ex:shape a sh:Shape
sh:inverseProperty [
sh:predicate foaf:knows ;
sh:valueType foaf:Person ;
] .
```

#### And

If a shape contains more than one sh:property, it is implicitly assumed as an And.

Example of shape that identifies nodes that have both 'rdfs:label' and 'rdfs:comment' with values of type 'xsd:string'.

```ex:shape a sh:Shape
sh:property [
sh:predicate rdfs:label ;
sh:valueType xsd:string ;
];
sh:property [
sh:predicate rdfs:comment ;
sh:valueType xsd:string ;
] .
```

TODO: Insert some comment about multi-occurrence and overlapping definitions.

#### Or

Example of shape that identifies nodes that have either 'rdfs:label' or 'rdfs:comment' (or both) with values of type 'xsd:string'.

```ex:shape1 a sh:Shape
sh:someOf [
sh:property [
sh:predicate rdfs:label ;
sh:valueType xsd:string ;
];
sh:property [
sh:predicate rdfs:comment ;
sh:valueType xsd:string ;
]
] .
```

In the previous example we are assuming inclusive or, which means that a node can have also both 'rdfs:label' and 'rdfs:comment'.

In the next example, 'n1', 'n2', and 'n3' have shape 'ex:Shape1'

```:n1 rdfs:label "Node 1"
:n2 rdfs:comment "Node 2"
:n3 rdfs:label "Node 3"; rdfs:comment "Node 3" .
```

An alternative is exclusive or which can be modelled as 'oneOf'

```ex:shape2 a sh:Shape
sh:oneOf [
sh:property [
sh:predicate rdfs:label ;
sh:valueType xsd:string ;
];
sh:property [
sh:predicate rdfs:comment ;
sh:valueType xsd:string ;
]
] .
```

In this case, 'n3' would not have shape 'shape2'

#### Allowed Value

Example of a shape that has a property "ex:genre" with values "ex:Male" or "ex:Female"

```ex:shape a sh:Shape
sh:property [
sh:predicate ex:genre ;
sh:allowedValue ex:Male ;
sh:allowedValue ex:Female ;
] .
```

Eric proposes this property in singular and sh:hasValue for single values.

Holger also defines a special purpose sh:Set to define the set of Allowed Values using another special purpose property sh:member.

Eric uses just the property sh:allowedValue to associate the allowed value. There could be several ones.

Comment (Labra): Review what happens if there more than one sh:hasValue...

#### Value type

Example of a shape that has a property 'foaf:knows' whose values are of type 'foaf:Person'

```ex:shape a sh:Shape
sh:property [
sh:predicate foaf:knows ;
sh:valueType foaf:Person ;
] .
```

Comment (labra): Other names suggested in this thread: sh:type, sh:valueType, sh:rdfType, sh:class, sh:resourceType, ...

Comment (labra): I think this could even be avoided as it could be defined as:

```ex:shape a sh:Shape
sh:property [
sh:predicate foaf:knows ;
sh:valueShape [ a foaf:Person ] ;
] .
```

#### Value Datatype

Example of a shape that has a property rdfs:label whose values are of type xsd:string

```ex:shape a sh:Shape
sh:property [
sh:predicate rdfs:label ;
sh:valueDatatype xsd:string ;
] .
```

TODO: Add language constructs to support language tagged literals

Comment (labra): Other suggested names: sh:type, sh:literalType

#### Value shape

```ex:courseShape a sh:Shape
sh:property [
sh:predicate ex:student ;
sh:valueShape ex:studentShape ;
] .
ex:studentShape a sh:Shape
sh:property [
sh:predicate rdfs:label ;
sh:valueDatatype xsd:string ;
] .
```

ISSUE: This language construct can define recursive shapes which can increase the complexity of the SHACL processor.

ISSUE: Combining between recursive shapes and other language features like exclusive or can lead to ill-defined shapes.

TODO: Include Peter's examples here.

#### Exact Cardinality

Declare that there must be a fixed set of arcs. This property is a combination on minCardinality and maxCardinality when they have the same value.

```ex:shape a sh:Shape
sh:property [
sh:predicate bio:parent ;
sh:nodeType sh:IRI ;
sh:cardinality 2
] .
```

Comment (labra): Should we allow cardinality to be 0? It would be the same as negate that propery, which could be an alias for something like 'sh:nonPropery'

#### MinCardinality

Example of a shape that has at least two 2 arcs with predicate 'foaf:knows' .

```ex:shape a sh:Shape
sh:property [
sh:predicate foaf:knows ;
sh:nodeType sh:IRI ;
sh:minCardinality 2
] .
```

TODO: Explain why adding 'sh:minCardinality' with value 0 may not seem intuitive.

#### MaxCardinality

Example of a shape that doesn't have more than 2 arcs with predicate ex:parent.

```ex:shape a sh:Shape
sh:property [
sh:predicate ex:parent ;
sh:nodeType sh:IRI ;
sh:maxCardinality 2
] .
```

By default sh:maxCardinality is unbounded.

TODO: Adding sh:maxCardinality implicitly means a negation which must check that there are no other triples that match. This check can increase the complexity of SHACL processors.

#### Predicate

TODO: Talk about possible language extensions that enrich constraints on predicates.

#### sh:empty

Example of an empty Shape

```ex:shape a sh:Shape .
```

TODO: The meaning of Empty can vary depending on Closed or Open Shapes. If the Shape is closed, Empty means that the node must not have any arc at all...while if the Shape is open, it can have any arc.

#### Close

TODO: Talk about the implications of Closed shapes

#### Group

A group of several constraints.

Property groups can increase SHACL expressiveness if they can be associated cardinalities.

#### Exclusive-or

TODO: Talk about the implications when combining exclusive-or and other language constructs

#### Negation

TODO: Talk about the implications of negation.

#### Interleave

'interleave(S1,S2)' decomposes the set of triples to match in two subsets 'ts1' and 'ts2' and matches if 'S1' matches with 'ts1' and 'S2' matches with 'ts2'.

In most of the cases, the interleave operation is similar to 'and'.

TODO: Describe the difference between 'and' and 'interleave' with an example.

#### Literal

Represents node types that are literals. Comment (Labra): I miss some way to represent Language tagged literals so one can specify constraints on them.

```For example: An Spanish labelled node contains an rdfs:label literal in Spanish.
```

#### Language tags

Constraint a literal taking into account the value of the language tag

#### Other Node Types

Holger's spec contains several other combinations like:

• sh:BlankNodeOrIRI
• sh:BlankNodeOrLiteral
• sh:LiteralOrIRI

#### Datatype facets

Datatype facets suggested by Holger. Some examples in Primer

### Error reporting

#### Target Node

Indicates which is the target node of the error. Holger uses sh:root. Comment (Labra): I think the use of "root" is not intuitive here and it would be better some other term like "TargetNode", "FailedNode", etc.

#### Path

SPARQL path expression to signal some extra nodes in the reporting error. Comment (Labra): This implies that a SPARQL processor has to generate those Path expressions or that SHACL must implement a SPARQL Path expressions generator. From my point of view, this should be removed or at least not be normative.

### Node selection

#### Node Shape

Associate a node with a shape

#### Class Shape

Associate a class with a shape

### Extensibility mechanism and macros

#### Macros

TODO: Add some explanation and examples

#### Functions

TODO: Add some explanation and examples

#### External Actions

External actions enable SHACL processors to call a external application passing it some parameters (at least current node and graph). The result of the external application is assumed to be a boolean. If true, the constraint passes, otherwise it fails.

TODO: Add some explanation and examples