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 core Axiomatic semantics	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 core Axiomatic semantics	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 sh:BlankNodeOrLiteral sh:LiteralOrIRI sh:Node	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

Datatype Facets

Holger proposes a datatype property constraints similar to their XSD equivalent

Concept	Abstract Syntax SHACL core Axiomatic semantics	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

Definitions about error reporting

Concept	Abstract Syntax SHACL core Axiomatic semantics	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 core Axiomatic semantics	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 core Axiomatic semantics	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 core Axiomatic semantics	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?

• sh:hasShape
• sh:hasNodeType
• sh:inverseValueCount
• sh:label
• sh:valueCount

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.

TODO: Talk about the implications of groups. Add an example...

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.

IRI

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.

BNode

Language tags

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

TODO: Add an example

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

Violation

Warning

Error

FatalError

Severity levels

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.

Value

Source

Error details

Message

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