This specification describes conformance criteria SHACL SPARQL processors.

TODO: more?

Document Conventions

Throughout this document, IRIs are written in Turtle syntax, using the following mapping of prefixes to namespaces:

The remainder of this section is informative.

The Turtle serialization of the SHACL vocabulary will be uploaded to web URL of the graph that it represents.

Throughout the document, color-coded boxes containing RDF graphs in Turtle will appear. These fragments of Turtle documents use the prefix bindings given above.

	# This box represents an input shapes graph

	# Triples that can be omitted are marked as grey e.g.
	<s> <p> <o> .

	# This box represents an input data graph.
	# When highlighting is used in the examples:

	# Elements highlighted in blue are focus nodes
	ex:Bob a ex:Person .

	# Elements highlighted in red are focus nodes that fail validation
	ex:Alice a ex:Person .

	# This box represents an output results graph

SHACL or SPARQL Definitions appear in blue boxes:

	# This box contains textual definitions. 

Basic Terminology

Terminology that is linked to portions of RDF 1.1 Concepts and Abstract Syntax is used in SHACL as defined there. Terminology that is linked to portions of SPARQL 1.1 Query Language is used in SHACL as defined there. Terminology that is linked to portions of SHACL Shapes Constraints Lanugage is used in SHACL-SPARQL as defined there. TODO: perform the linking A single linkage is sufficient to provide a definition for all occurences of a particular term in this document.

Definitions are complete within this document, i.e., if there is no rule to make a some situation true in this document then the situation is false.

Relationship to SPARQL

This specification uses parts of SPARQL 1.1 in the normative definition of the semantics of the SHACL-SPARL.

SPARQL variables using the $ marker represent external bindings that are pre-bound or, in the case of $PATH, substituted in the SPARQL query before execution.

In some places, the specification assumes that the provided SPARQL engines are preserving the identity of blank nodes, so that repeated invocations of queries consistently identify and communicate the same blank nodes.

Access to the shapes graph is not a requirement for supporting the SHACL Core language. The variable shapesGraph can also be used in SPARQL-based constraints and SPARQL-based constraint components. However, such constraints may not be interoperable across different SHACL-SPARQL processors or not applicable to remote RDF datasets.

Relation to SHACL

Say it extends SHACL. SHACL-SPARQL support all SHACL constructs SHACL-SPARQL definitions go into shapes graph to define constraints. sh:SparqlSelectConstraintComponent is a constraint component similar to the SHACL Core components -> executed user query for value nodes. SPARQL-Based Constraint compontents provide a high level vocabulary to define custom constraint components. -> define parameters of constraint components and define how these parameters are prebind into SPARQL queries and executed on value nodes.

Pre-bound Variables in SPARQL Constraints ($this, $shapesGraph, $currentShape)

The following table enumerates the variables that have special meaning in SPARQL constraints. When SPARQL constraints are processed, the SHACL-SPARQL processor pre-binds values for these variables.

Mapping of Result Variables to Validation Results

If one of the solutions of the result set produced by a SELECT query during a validation process contains the binding true for the variable failure, then the SHACL-SPARQL processor MUST signal a failure.

Otherwise, each row of the result set produced by a SELECT query MUST be converted into one validation result node. The property values of those nodes are derived by the following rules, through a combination of result solutions and the values of the constraint itself. The rules are meant to be executed from top to bottom, so that the first bound value will be used.

Injecting Annotation Properties into Validation Results

It is possible to inject additional annotation properties into the validation result nodes created for each solution of the SELECT result sets. Any such property needs to be declared via a value of shs:resultAnnotation at the subject of the shs:select triple. The values of shs:resultAnnotation are either IRIs or blank nodes with the following properties. In this table, the Value type column states the required SHACL class or datatype of the property values, and the Count column indicates the minimum and maximum number of values that the properties may have. If these value types and counts are violated then the shapes graph is invalid.

For each solution of a SELECT result set, a SHACL-SPARQL processor MUST walk through the declared result annotations. The mapping from result annotations to SPARQL variables uses the following rules:

1. If a shs:resultAnnotation has a value for the property shs:annotationVarName then the SHACL-SPARQL processor MUST look for the variable with the same name as the value of shs:annotationVarName
2. Otherwise, the SHACL-SPARQL processor MUST use the local name of the value of shs:annotationProperty as the variable name

If a variable name could be determined, then the SHACL-SPARQL processor MUST copy the binding for the given variable as a value for the property specified using shs:annotationProperty into the validation result that is being produced for the current solution. If the variable has no binding in the result set solution, then the value of shs:annotationValue MUST be used, if present.

The remainder of this section is informative.

Here is a slightly complex example, illustrating the use of result annotations.

ex:ShapeWithPathViolationExample
	a sh:Shape ;
	sh:targetNode ex:ExampleRootResource ;
	shs:sparql [
		shs:resultAnnotation [
			shs:annotationProperty ex:time ;
			shs:annotationVarName "time"
		] ;
		shs:select """
			SELECT $this (ex:property1 AS ?path) (?first AS ?value) ?message ?time
			WHERE {
				$this ex:property1 ?first .
				?subject ex:property2 ?first .
				FILTER isBlank(?value) .
				BIND (CONCAT("The ", "message.") AS ?message) .
				BIND (NOW() AS ?time) .
			}
			""" ;
	] .

ex:ExampleRootResource
	ex:property1 ex:ExampleIntermediateResource .

ex:ExampleValueResource
	ex:property2 ex:ExampleIntermediateResource .

Validation produces the following validation result nodes:

[] a sh:ValidationReport ;
	sh:conforms "false"^^xsd:boolean ;
	sh:result [
		a sh:ValidationResult ;
		sh:resultSeverity sh:Violation ;
		sh:focusNode ex:ExampleRootResource ;
		sh:resultPath ex:property1 ;
		sh:value ex:ExampleIntermediateResource ;
		sh:resultMessage "The message." ;
		sh:sourceConstraintComponent shs:SPARQLConstraintComponent ;
		sh:sourceShape ex:ShapeWithPathViolationExample ;
		ex:time "2015-03-27T10:58:00"^^xsd:dateTime ;  # Example
	] .

Parameter Declarations (shs:parameter)

The parameters of a constraint component are declared via the property shs:parameter. The objects of triples with shs:parameter as predicate have shs:Parameter as expected type.

Each parameter has exactly one value p for the property shs:predicate and the value is an IRI, otherwise, the constraint component that has this parameter is an ill-formed constraint component. The local name of an IRI is defined as the longest NCNAME at the end of the IRI, not immediately preceded by the first colon in the IRI. The parameter name is defined as the local name of the value of shs:predicate. To ensure that a correct mapping from parameters into SPARQL variables is possible, every parameter name

• is a valid SPARQL VARNAME
• is not equal to this, shapesGraph, currentShape, focusNode, predicate, path or value
• is not equal to another parameter name in the same constraint component

An shs:Parameter may have its property shs:optional set to true to indicate that the parameter is not mandatory. Every constraint component has at least one non-optional parameter.

The class shs:Parameter is defined as a SHACL subclass of shs:PropertyConstraint, and all properties that are applicable to property constraints may also be used for parameters. This includes descriptive properties such as sh:name and sh:description but also constraint parameters such as sh:class. Some implementations MAY use these constraint parameters to prevent the execution of constraint components with invalid parameter values.

Label Templates (shs:labelTemplate)

The property shs:labelTemplate can be used at any constraint component to suggest how they could be rendered to humans. The values of shs:labelTemplate are strings (possibly with language tag) that can include the names of the declared parameters using the syntax {?varName} or {$varName}, where varName is the name of the SPARQL variable that corresponds to the parameter. At display time, these {?varName} and {$varName} blocks SHOULD be substituted with the actual parameter values. There may be multiple label templates for the same subject, assuming they do not have the same language tags.

Validators

For every supported context (i.e., property constraints or shape) the constraint component declares a suitable validator. For a given constraint, a validator is selected from the constraint component using the following rules, in order:

1. For shapes, use one of the values of shs:shapeSelfValidator, if present.
2. For property constraints, use one of the values of shs:shapePathValidator, if present.
3. Otherwise, use one of the values of shs:validator.

If no suitable validator can be found, a SHACL-SPARQL processor ignores the constraint. The SHACL WG is seeking practical feedback on what the default behavior should be, and whether we should report violations in those cases.

SHACL-SPARQL includes two types of validators, based on SPARQL SELECT (for shs:shapeSelfValidator and shs:shapePathValidator) or SPARQL ASK queries (for shs:validator).

ex:LanguageConstraintComponentUsingSELECT
	a shs:ConstraintComponent ;
	rdfs:label "Language constraint component" ;
	shs:parameter [
		shs:predicate ex:lang ;
		sh:datatype xsd:string ;
		sh:minLength 2 ;
		sh:name "language" ;
		sh:description "The language tag, e.g. \"de\"." ;
	] ;
	shs:labelTemplate "Values are literals with language \"{$lang}\"" ;
	shs:shapePathValidator [
		a shs:SPARQLSelectValidator ;
		shs:message "Values are literals with language \"{?lang}\"" ;
		shs:select """
			SELECT DISTINCT $this ?value
			WHERE {
				$this $PATH ?value .
				FILTER (!isLiteral(?value) || !langMatches(lang(?value), $lang))
			}
			"""
	] .

ex:LanguageExampleShape
	a sh:Shape ;
	sh:targetClass ex:Country ;
	sh:shape [
		sh:path ex:germanLabel ;
		ex:lang "de" ;
	] ;
	sh:shape [
		sh:path ex:englishLabel ;
		ex:lang "en" ;
	] .

	SELECT $this ?value
	WHERE {
		BIND ($this AS ?value) .
		FILTER NOT EXISTS ...
	}

	SELECT DISTINCT $this ?value
	WHERE {
		$this $PATH ?value .
		FILTER NOT EXISTS ...
	}

ex:LanguageConstraintComponentUsingASK
	a shs:ConstraintComponent ;
	rdfs:label "Language constraint component" ;
	shs:parameter [
		shs:predicate ex:lang ;
		sh:datatype xsd:string ;
		sh:minLength 2 ;
		sh:name "language" ;
		sh:description "The language tag, e.g. \"de\"." ;
	] ;
	shs:labelTemplate "Values are literals with language \"{$lang}\"" ;
	shs:validator ex:hasLang .

ex:hasLang
	a shs:SPARQLAskValidator ;
	shs:message "Values are literals with language \"{$lang}\"" ;
	shs:ask """
		ASK {
			FILTER (isLiteral($value) && langMatches(lang($value), $lang))
		}
		""" .

Pre-bound variables

SHACL-SPARQL defines two forms of variable pre-binding:

1. Global pre-bound variables that are available in all SPARQL-based constraints, SPARQL-based constraint components and SPARQL-based targets.
2. Local pre-bound variables available only within a SPARQL-based constraint component and defined through the component parameters

The variable PATH has a special treatment in SHACL property constraint components and MUST be processed before any other pre-bound variable. SHACL-SPARQL processors MUST perform string substitution of every occurrence of the variable PATH to the generated SPARQL property path before performing any pre-binding.