From 48707260a4aba377e8e75ea3c3ee6473a4fa3b74 Mon Sep 17 00:00:00 2001 From: Holger Knublauch Date: Wed, 2 Sep 2015 19:28:17 +1000 Subject: [PATCH] Included some edits in response to Peter's review --- shacl/index.html | 65 +++++++++++++++++++++++++++++------------------- 1 file changed, 39 insertions(+), 26 deletions(-) diff --git a/shacl/index.html b/shacl/index.html index a5258c1e..0edeafa5 100644 --- a/shacl/index.html +++ b/shacl/index.html @@ -124,7 +124,7 @@

- SHACL (Shapes Constraint Language) is an RDF vocabulary for describing RDF graph structures. + SHACL (Shapes Constraint Language) is a language for checking constraints against RDF graphs and for describing graph structures. Some of these graph structures are captured as "shapes", which group together constraints about the same RDF nodes. Shapes provide a high-level vocabulary to identify predicates and their associated cardinalities, datatypes and other constraints. Additional constraints can be associated with shapes using SPARQL and similar executable languages. @@ -164,11 +164,11 @@

Revision History

Introduction

- SHACL (Shapes Constraint Language) is an RDF vocabulary to formulate structural constraints on RDF graphs. - The SHACL vocabulary includes high-level concepts to represent restrictions on predicates used in triples. + SHACL (Shapes Constraint Language) is an RDF-based language to formulate structural constraints on RDF graphs. + SHACL includes high-level constructs to represent restrictions on predicates used in triples. These restrictions can be grouped into "shapes". Shapes can be used to restrict the number of property values and the permitted value types as well as other conditions. - Some users and implementors will be content with using the high-level shapes language only, which is called the SHACL Core Profile + Some users will be content with using the high-level language only, which is called the SHACL Core Profile and is described in sections 2 to 6 of this document.

@@ -177,8 +177,8 @@

Introduction

These advanced topics are covered from section 7 onwards.

- SHACL definitions are represented in RDF and can be serialized in multiple RDF formats. - The example snippets in this document use Turtle [[turtle]] and (not written yet:) JSON-LD [[json-ld]] notation. + SHACL is written in RDF and can be serialized in multiple RDF formats. + The examples in this document use Turtle [[turtle]]. The reader should be familiar with basic RDF concepts [[rdf11-concepts]] such as triples and (for the advanced concepts of SHACL) with SPARQL [[sparql11-overview]].

@@ -208,8 +208,8 @@

Overview and Terminology of Core Features

The following example illustrates the use of SHACL to define constraints on issues in a hypothetical bug tracking system. In the example scenario, the RDFS class ex:Issue is used to represent issues, and the class schema:Person represents users. - Each ex:Issue must point to exactly one user via the property ex:submittedBy and may have one value for ex:assignedTo. - Users that have submitted an issue must also have a schema:email address, so that they can be notified when the issue has been updated. + One shape requires that each instance of ex:Issue has exactly one value for ex:submittedBy, that that value is an instance of schema:Person that satisfies the constraints on submitters, has at most one value for ex:assignedTo, and that that value is an instance of schema:Person. + The submitter shape requires at least one value for schema:email. 

 ex:Issue
@@ -256,9 +256,8 @@ 
Overview and Terminology of Core Features

 					the ex:submittedBy property must fulfill, in addition to being instances of schema:Person.
 				

 				

-					One of the operations that SHACL engines should support validates a given RDF node against a given shape, producing validation results, including informational results, warnings and errors.
-					This operation can be invoked based on any control logic, i.e. applications can pick their own mapping between RDF nodes and their shapes.
-					Another supported operation is to validate a given graph using all applicable shapes.
+					One of the operations of SHACL is validating a given RDF node against a given shape, producing validation results, including informational results, warnings and errors.
+					Another operation is to validate a given graph using all applicable shapes.
 					In order to support that operation, SHACL has the concept of scopes.
 					Scopes are attached to shapes and produce a collection of nodes that shall be validated against the shape.
 					SHACL provides several scoping mechanisms, including node selection based on sh:nodeShape and rdf:type triples,
@@ -266,7 +265,7 @@ 
Overview and Terminology of Core Features

 					The scope of a shape can be narrowed down via filter shapes that define pre-conditions that all focus nodes need to fulfill before they are validated.
 				

 				

-					The following example code defines two instances of the class ex:Issue.
+					The following RDF graph defines two instances of the class ex:Issue.
 					When constraint validation is started, a SHACL engine may follow the rdf:type link of these instances to determine which shapes need to be used.
 					(If ex:Issue were not a class but a sh:Shape, then the property sh:nodeShape would have been used instead).
 					The first instance passes validation without producing any results.
@@ -425,7 +424,7 @@ 
Shapes and Classes

 					i.e. any resource that has the sh:scopeClass or one of its subclasses as its rdf:type.
 				

 				

-					If a sh:Shape is also an instance of rdfs:Class then the interpretation is that all instances of the class are expected to have the shape.
+					If a sh:Shape is also an instance of rdfs:Class then the validation will verify that all instances of the class have the shape.
 					There is a built-in subclass of sh:Shape called sh:ShapeClass that is also a subclass of rdfs:Class to simplify the declaration of shapes that are also classes.
 				

 				

@@ -511,6 +510,9 @@ 
Property Constraints (sh:property)

 					Here, the focus node is the subject and the property is the predicate of relevant triples.
 					The property sh:property can be used to link a shape with its property constraints.
 				

+				

+					The WG has not yet decided whether the special treatment of blank nodes explained below (and in other places) will remain in the language.
+				

 				

 					In the SHACL RDF vocabulary, property constraints are instances of the class sh:PropertyConstraint.
 					When used as values of sh:property, property constraints represented as blank nodes do not require an rdf:type triple.
@@ -632,7 +634,6 @@ 
sh:allowedValues

 					

 						The property sh:allowedValues can be used to specify that all values of the given predicate
 						at the focus node must be members of a given set of allowed values.
-						The set of allowed values is assumed to be an exhaustive enumeration of all possible values.
 					

 					
@@ -804,18 +805,17 @@ 
sh:minCount, sh:maxCount

-							
+							
-							
+							

 						

 						

 							sh:minCount
 							xsd:integerThe minimum cardinality. Optional. Default value is 0.The minimum cardinality. Default value is 0.
 						

 						

 							sh:maxCount
 							xsd:integerThe maximum cardinality. Optional. Default interpretation is unlimited.The maximum cardinality. Default interpretation is unlimited.
 						

 					

 					

 						
TEXTUAL DEFINITION

 						

-							Both sh:minCount and sh:maxCount are optional.
 							The default value of sh:minCount is 0.
 							Let ?count be the number of triples that have the focus node as
 							the subject and the sh:predicate as the predicate.
@@ -843,7 +843,7 @@ 
sh:minCount, sh:maxCount

 					
sh:minLength, sh:maxLength

 					

 						The properties sh:minLength and sh:maxLength
-						restrict the string length of triples with the focus node
+						restrict the string length of objects of triples with the focus node
 						as the subject and the given property as the predicate.
 						This can be applied to any type of literal and IRIs, but not for blank nodes.
 					

@@ -856,18 +856,17 @@ 
sh:minLength, sh:maxLength

 						
 							sh:minLength
 							xsd:integer
-							The minimum length. Optional. Default value is 0.
+							The minimum length. Default value is 0.
 						
 						
 							sh:maxLength
 							xsd:integer
-							The maximum length. Optional. Default interpretation is unlimited.
+							The maximum length. Default interpretation is unlimited.
 						
 					
 					

 						
TEXTUAL DEFINITION

 						

-							Both sh:minLength and sh:maxLength are optional.
 							The default value of sh:minLength is 0.
 							A validation result must be produced for each triple that has
 							the focus node as its subject, the sh:predicate
@@ -1081,7 +1080,7 @@ 
sh:valueClass

 						

 							A validation result must be produced for each triple that has
 							the focus node as its subject, the sh:predicate
-							as its predicate and where the object is either a literal, or is an untyped non-literal, or a non-literal with a mismatching rdf:type.
+							as its predicate and where the object is either a literal or a non-literal without a matching rdf:type.
 							A non-literal matches a type if its rdf:type is equal to the type or one of its (transitive) subclasses, via rdfs:subClassOf.
 							Each produced validation result must have the focus node as its sh:root and sh:subject,
 							the sh:predicate as its sh:predicate and the respective violating value as its sh:object.
@@ -1189,13 +1188,16 @@ 
sh:qualifiedValueShape, sh:qualifiedMinCount, sh:qualifiedMaxCount

 							The maximum number of values that can have the shape
 						
 					
+					

+						There is an ongoing debate how to best represent multiple qualified shape constraints for the same property.
+					

 					

 						
TEXTUAL DEFINITION

 						

 							A validation result must be produced if the number of triples that have
 							the focus node as its subject, the sh:predicate
 							as its predicate and where validating the object against the shape specified by sh:qualifiedValueShape
-							produces error-level constraint violations is outside of the interval specified by sh:qualifiedMinCount and sh:qualifiedMaxCount.
+							produces no error-level constraint violations is outside of the interval specified by sh:qualifiedMinCount and sh:qualifiedMaxCount.
 							The interval defaults to 0 if the min count is not specified, and unlimited if the max count is not specified.
 							The produced validation result must have the focus node as its sh:root and sh:subject,
 							and the sh:predicate as its sh:predicate.
@@ -1254,7 +1256,7 @@ 
Inverse Property Constraints (sh:inverseProperty)
-

Other Core Constraints on Shapes

+

Other Core Constraints

While the previous sections have introduced constraints that focused on a single property within a shape, this section introduces other constraint types that can be used with shapes. @@ -1325,6 +1327,10 @@

sh:AndConstraint

List of shapes to validate +
+ The current specification of sh:AndConstraint and sh:OrConstraint does not yet reflect the resolution to ISSUE-76, + that the order of operands does not matter. +
TEXTUAL DEFINITION
@@ -1598,6 +1604,9 @@

Scopes

Individual scopes (sh:nodeShape)

+
+ There is an alternative proposal discussed that would reverse the direction of this, pointing from the shape to the nodes. +

Individual nodes can point to the shapes that they are supposed to be validated against using the property sh:nodeShape. The values of sh:nodeShape must be IRIs. @@ -1783,6 +1792,9 @@

Validation Results Vocabulary

structural information that may provide guidance on how to fix a violation, as well as human-readable messages.

+
+ This vocabulary is likely going to change once the WG resolves ISSUE-51 and ISSUE-75. +

The following code snippet represents a syntactically correct result that may have been produced by a constraint validation engine:

@@ -1831,8 +1843,6 @@

Types of Validation Results

-

-

SHACL extensions may define additional result types, as long as they are rooted in sh:Result. @@ -2761,6 +2771,9 @@

Pre-bound Variables in SPARQL Constraints (?this, ?shapesGraph, ?currentShap +
+ There is no consensus yet if and under which conditions SPARQL queries can access the shapes graph. +

Mapping of Result Variables to Validation Results