-
Notifications
You must be signed in to change notification settings - Fork 33
/
index.html
2240 lines (2180 loc) · 99 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<head>
<title>Shapes Constraint Language (SHACL)</title>
<meta charset='utf-8'>
<script src='//www.w3.org/Tools/respec/respec-w3c-common' async class='remove'></script>
<script class='remove'>
var respecConfig = {
edDraftURI: "http://w3c.github.io/data-shapes/shacl/",
specStatus: "ED",
shortName: "shacl",
editors: [
{
name: "Holger Knublauch",
url: "http://knublauch.com/",
company: "TopQuadrant, Inc.",
companyURL: "http://topquadrant.com/"
},
{
name: "Eric Prud'hommeaux",
url: "http://www.w3.org/People/Eric/",
company: "W3C/MIT",
companyURL: "http://www.w3.org/"
}
],
wg: "RDF Data Shapes Working Group",
wgURI: "https://www.w3.org/2014/data-shapes/wiki/Main_Page",
wgPublicList: "public-data-shapes",
wgPatentURI: "http://www.w3.org/2004/01/pp-impl/73865/status",
};
</script>
<style>
pre {
tab-size: 4;
}
th {
text-align: left;
}
table.rule { background-color: #EBEBE0; }
table.rule td { text-align: center; }
td.up { border-bottom:1px solid black; }
.arg {
font-weight: bold;
color: #000080;
}
.def {
background: #fcfcfc;
border-left-style: solid;
border-left-width: .5em;
border-color: #c0c0c0;
margin-bottom: 16px;
padding: 8px;
}
.def-sparql {
}
.def-text {
}
.def-text-body {
margin-left: 2em;
}
.def-header {
color: #a0a0a0;
font-size: 16px;
padding-bottom: 8px;
}
.term {
font-style: italic;
}
.term-table {
border-collapse: collapse;
border-color: #000000;
margin: 16px;
}
.todo {
color: red;
}
</style>
</head>
<body>
<section id="abstract">
<p>
SHACL (Shapes Constraint Language) is an RDF vocabulary for describing RDF 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 either be stated globally or be associated with shapes using SPARQL and similar executable languages.
These executable languages can also be used to define new high-level vocabulary terms.
SHACL shapes can be used to communicate data structures associated with some process or interface, generate or validate data, or drive user interfaces.
This document defines the SHACL RDF vocabulary together with its underlying semantics.
</p>
</section>
<section id="sotd">
<p>
Proposal to RDF Data Shapes WG.
</p>
</section>
<section id="introduction">
<h2>Introduction</h2>
<p>
SHACL (Shapes Constraint Language) is an RDF vocabulary to formulate structural constraints on <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-graph">RDF graphs</a>.
The SHACL vocabulary includes high-level concepts to represent restrictions on predicates used in <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-triple">triples</a>.
These restrictions can be grouped into "<span class="term">shapes</span>".
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 <span class="term">SHACL Core Profile</span>
and is described in sections 2 to 6 of this document.
</p>
<p>
For more complex use cases, SHACL also includes facilities to express other restrictions in an executable language such as SPARQL and, possibly, other languages such as JavaScript.
SHACL includes macro facilities that encapsulate reusable building blocks based on these executable languages into <span class="term">templates</span> and <span class="term">functions</span>.
These advanced topics are covered from section 7 onwards.
</p>
<p>
SHACL definitions are represented in RDF and can be serialized in multiple RDF formats.
The example snippets in this document use Turtle [[turtle]] and <span class="todo">(not written yet:)</span> JSON-LD [[json-ld]] notation.
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]].
</p>
<section id="introduction-outline">
<h3>Document Outline</h3>
<p>
Unless otherwise noted in the section heading, all sections and appendices in this document are normative.
<span class="todo">TODO: We still need to mark non-normative sections.</span>
</p>
<p>
The remaining sub-sections of the Introduction provide an overview of the complete language and introduces relevant terminology.
</p>
<p>
The sections 2 - 6 cover the <span class="term">SHACL Core Profile</span> and may be read independently from the later sections.
<span class="todo">We could add details on every section here, but I am not sure this is really needed.</span>
</p>
<p>
The sections 7 onwards are about the full SHACL language and its formal definition.
The appendix includes SPARQL-related implementation details.
</p>
</section>
<section id="introduction-overview">
<h3>Overview and Terminology of Core Features</h3>
<p>
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 <code>ex:Issue</code> is used to represent issues, and the class <code>schema:Person</code> represents users.
Each <code>ex:Issue</code> must point to exactly one user via the property <code>ex:submittedBy</code> and may have one value for <code>ex:assignedTo</code>.
Users that have submitted an issue must also have a <code>schema:email</code> address, so that they can be notified when the issue has been updated.
</p>
<pre class="example" title="Definition of ex:Issue and ex:SubmitterShape">
ex:Issue
a rdfs:Class ;
sh:property [
sh:predicate ex:assignedTo ;
rdfs:label "assigned to" ;
rdfs:comment "The assignee of an issue must be a person." ;
sh:maxCount 1 ;
sh:valueType schema:Person ;
] ;
sh:property [
sh:predicate ex:submittedBy ;
rdfs:label "submitted by" ;
rdfs:comment "The submitter of an issue must be a person who also has an email address." ;
sh:minCount 1 ;
sh:maxCount 1 ;
sh:valueType schema:Person ;
sh:valueShape ex:SubmitterShape ;
] .
ex:SubmitterShape
a sh:Shape ;
rdfs:comment "A submitter must have at least one email address." ;
sh:property [
sh:predicate schema:email ;
sh:minCount 1 ;
] .</pre>
<p>
The basic building blocks of SHACL are <span class="term">constraints</span>.
Each <span class="term">constraint</span> defines a condition that can be validated against a graph.
A <a href="#shapes"><span class="term">shape</span></a> describes a group of <span class="term">local constraints</span> with the same <span class="term">focus node</span>.
Many of these constraints are about a certain property only, and these are called <a href="#property-constraints"><span class="term">property constraints</span></a>.
<span class="term">Local constraints</span> are evaluated against a given <span class="term">focus node</span>, which serves as starting point of property paths and other graph traversal algorithms.
In the current draft, the IRIs of classes (such as <code>ex:Issue</code> above) may also be used as shapes.
Shapes may be arranged in a <span class="term">specialization</span> hierarchy, allowing some shapes to further narrow down the constraints from other shapes.
</p>
<p>
In the Issue example above, the shape <code>ex:Issue</code> includes two local constraints.
These constraints are here represented as blank nodes via <code>sh:property</code>.
Each of these constraints specifies the restricted property via <code>sh:predicate</code>, and one or more constraint facets such as <code>sh:minCount</code> and <code>sh:valueType</code>.
The facet <code>sh:valueShape</code> points to another <code>sh:Shape</code> that defines additional constraints that the values of
the <code>ex:submittedBy</code> property must fulfill, in addition to being instances of <code>schema:User</code>.
</p>
<p>
One of the <a href="#operations"><span class="term">operations</span></a> that SHACL engines should support validates that a given RDF node matches a given shape.
This operation can be invoked based on any control logic, i.e. applications can pick their own mapping between RDF nodes and their shapes.
SHACL also provides two mapping mechanisms based on the RDF triples in the graph being validated.
Current proposals for these mechanisms include selection based on <code>sh:nodeShape</code> and <code>rdf:type</code> triples.
Based on such in-graph mappings, SHACL supports constraint validation over a complete graph.
The output of constraint validation is a set of <a href="#violations"><span class="term">constraint violations</span></a>.
</p>
<p>
The following example code defines two instances of the class <code>ex:Issue</code>.
When constraint validation is started, a SHACL engine may follow the <code>rdf:type</code> link of these instances to determine which shapes need to be used.
(If <code>ex:Issue</code> were not a class but a <code>sh:Shape</code>, then the property <code>sh:nodeShape</code> would have been used instead).
The first instance passes validation without producing any violations.
The second instance produces an <code>sh:Error</code>, because its value for <code>ex:submittedBy</code> does not have an <code>schema:email</code>.
</p>
<pre class="example" title="Sample Issue instances with resulting constraint violations">
ex:ValidExampleIssue
a ex:Issue ;
ex:assignedTo ex:UserWithoutEmail ;
ex:submittedBy ex:UserWithEmail .
ex:InvalidExampleIssue
a ex:Issue ;
ex:submittedBy ex:UserWithoutEmail .
ex:UserWithoutEmail
a schema:Person .
ex:UserWithEmail
a schema:Person ;
schema:email "someone@example.org" .</pre>
<p>
When this instance data is validated, a SHACL engine will produce the following constraint violations:
</p>
<pre class="example" title="Constraint violations for the sample instances">
[
a sh:Error ;
sh:root ex:InvalidExampleIssue ;
sh:path ex:submittedBy ;
sh:value ex:UserWithoutEmail ;
sh:message "Value does not have the shape ex:SubmitterShape." ;
]</pre>
</section>
<section id="introduction-overview-advanced">
<h3>Overview and Terminology of Advanced Features</h3>
<p>
The following paragraphs give an overview of the advanced features of SHACL.
Readers only interested in the Core Profile may skip this section.
</p>
<p>
In addition to <span class="term">local constraints</span> (attached to shapes), SHACL also supports <a href="#global-constraints"><span class="term">global constraints</span></a>.
<span class="term">Global constraints</span> are executed when constraint validation is invoked on the whole graph, and may verify arbitrary conditions.
</p>
<p>
The validation of each <span class="term">constraint</span> is formalized with one or more <span class="term">execution languages</span>.
This version of SHACL supports <a href="#sparql">SPARQL</a> as an <span class="term">execution language</span>, but other languages may be supported in future versions or by other communities.
Each constraint needs to be backed by at least one <span class="term">executable body</span> in SPARQL, and any alternative bodies need to follow the same semantics as the SPARQL queries.
Constraints may either directly define such an <span class="term">executable body</span> or point to a <a href="#templates"><span class="term">template</span></a>.
Constraints that directly include an <span class="term">executable body</span> are called <span class="term">native constraints</span>.
A <span class="term">template</span> serves as a parameterizable macro that wraps an <span class="term">executable body</span>.
Constraints that rely on a <span class="term">template</span> are called <span class="term">template constraints</span>.
The SHACL vocabulary includes a small library of such <span class="term">templates</span> for common constraint patterns, but anyone can add their own template libraries.
Templates can be grouped into so-called <a href="#profiles"><span class="term">profiles</span></a>.
Some SHACL engines may decide to only support certain <span class="term">profiles</span> and implement them differently than the provided (SPARQL) bodies.
</p>
<p>
The following example illustrates the use of a <span class="term">global native SPARQL constraint</span> to specify that there cannot be two instances of <code>schema:Person</code> with the same <code>schema:email</code>.
Note that each result set row produced by the SELECT clauses of the SPARQL query creates one constraint violation.
</p>
<pre class="example" title="A global SPARQL-based constraint">
ex:EmailsMustBeUnique
a sh:GlobalConstraint ;
sh:message "There cannot be two persons with the same email address." ;
sh:path schema:email ;
sh:sparql """
SELECT (?person1 AS ?root) ?value
WHERE {
?person1 schema:email ?email .
?person2 schema:email ?email .
?person1 a schema:Person .
?person2 a schema:Person .
FILTER (?person1 != ?person2) .
}
""" .</pre>
</section>
<section id="namespaces">
<h3>Namespaces</h3>
<p>
The SHACL system vocabulary is available as a <a href="shacl.shacl.ttl">SHACL Turtle File</a>.
<span class="todo">Currently contains slight differences from this spec.</span>
</p>
<p>
Within this document, the following namespace prefix bindings are used:
</p>
<table class="term-table" border="1" cellpadding="5">
<tr>
<th>Prefix</th>
<th>Namespace</th>
</tr>
<tr>
<td><code>rdf:</code></td>
<td><code>http://www.w3.org/1999/02/22-rdf-syntax-ns#</code></td>
</tr>
<tr>
<td><code>rdfs:</code></td>
<td><code>http://www.w3.org/2000/01/rdf-schema#</code></td>
</tr>
<tr>
<td><code>sh:</code></td>
<td><code>http://www.w3.org/ns/shacl#</code></td>
</tr>
<tr>
<td><code>xsd:</code></td>
<td><code>http://www.w3.org/2001/XMLSchema#</code></td>
</tr>
<tr>
<td><code>ex:</code></td>
<td><code>http://example.com/ns#</code></td>
</tr>
<tr>
<td><code>schema:</code></td>
<td><code>http://schema.org/</code></td>
</tr>
</table>
</section>
<div class="issue" title="Alternative Specifications">
This document defines the semantics of the high-level vocabulary in textual form and using SPARQL queries, consistent with the SHACL template mechanism.
Several individual working group members have also proposed alternative language definitions:
<ul>
<li><a href="http://w3c.github.io/data-shapes/semantics/">Eric's proposal</a></li>
<li><a href="http://w3c.github.io/data-shapes/semantics/Axiomatic">Jose's proposal</a></li>
<li><a href="https://www.w3.org/2014/data-shapes/wiki/Shacl-sparql">Peter's proposal</a></li>
</ul>
</div>
</section>
<section id="shapes">
<h2>Shapes</h2>
<div class="issue" title="Classes and/or Shapes">
There is no agreement in the WG on the relationship of sh:Shape with RDFS classes.
Proposals include:
<ul>
<li>Keep them completely separate, users only instantiate sh:Shape and use sh:extends</li>
<li>Have rdfs:Class rdfs:subClassOf sh:Shape, use rdfs:subClassOf</li>
<li>Have sh:Shape rdfs:subClassOf rdfs:Class, use rdfs:subClassOf</li>
<li>Allow both approaches in parallel: either rdfs:Class/subClassOf or sh:Shape/extends</li>
<li>Allow both and have sh:classShape to point from a class to its shape(s)</li>
</ul>
In the absence of such an agreement, this document uses sh:Shape in most examples.
Note that depending on the resolution, all examples could also use rdfs:Class instead of sh:Shape.
</div>
<p>
A <span class="term">Constraint</span> defines restrictions on the structure of an RDF graph.
Some constraints, called <span class="term">local constraints</span>, can be regarded as radiating out from a <span class="term">focus node</span>.
A <span class="term">Shape</span> is a group of constraints that have the same focus nodes.
For example, a shape can be used to state that all instances of a class must have a certain number of values for a given property.
In that example, the instances of the class are the focus nodes, and the restriction on property values is expressed via a constraint.
</p>
<p>
In the SHACL RDF vocabulary, Shapes are instances of the class <code>sh:Shape</code>
<span class="todo">(or, depending on the outcome of the ISSUE above, <code>rdfs:Class</code>)</span>.
</p>
<section id="shape-labels">
<h3>Shape Labels and Comments</h3>
<p>
Like many other types of RDF resources, shapes SHOULD have human-readable labels via <code>rdfs:label</code>.
The property <code>rdfs:comment</code> is recommended for documentation and definition purposes.
</p>
</section>
<section id="shape-specialization">
<h3>Shape Specialization Mechanism</h3>
<p>
Shape declarations can specialize other shapes.
If a (sub) shape is declared to specialize another (super) shape then all constraints
attached to the super-shape must also apply to the sub-shape.
In other words, the set of nodes that match a sub-shape is a sub-set of those that
match a super-shape.
</p>
<p class="todo">
In the currently discussed proposals, the property <code>sh:extends</code> would be used
for instances of <code>sh:Shape</code> assuming <code>sh:Shape</code> is not declared to be a
subclass or superclass of <code>rdfs:Class</code>.
In all other cases, the property <code>rdfs:subClassOf</code> would be used to link
a sub-shape with its super-shape(s).
</p>
<p class="issue" title="RDFS Entailment">
There is no agreement in the WG about the role of RDFS entailment.
RDFS entailment would potentially serve as an alternative to rdfs:subClassOf.
However, making RDFS entailment mandatory may exclude too many systems and have other drawbacks.
</p>
</section>
<section id="shape-constraints">
<h3>Shape Constraints</h3>
<p>
A shape can be regarded as a collection of local constraints on a <span class="term">focus node</span>.
These constraints can be grouped into three categories that are covered by subsequent sections.
</p>
<ul>
<li>
<a href="#property-constraints">Property Constraints</a> specify characteristics of a given property in the context of the Shape.
The properties <code>sh:property</code> and <code>sh:inverseProperty</code> are used to link a Shape with its property constraints.
</li>
<li>
<a href="#or">Disjunctive Constraints</a> can be used to define two or more alternative restrictions.
</li>
<li>
For complex use cases that cannot be handled by the SHACL Core Profile,
<a href="#general-constraints">General Constraints</a> may define constraints that are not related to only a single property.
The property <code>sh:constraint</code> is used to link a Shape with its general constraints.
</li>
</ul>
<p>
Orthogonal to these constraint types, SHACL has a notion of <a href="#scope">Scopes</a> that can be used to define pre-conditions
that must hold before a constraint is applied to a given <span class="term">focus node</span>.
</p>
</section>
</section>
<section id="property-constraints">
<h2>Property Constraints</h2>
<p>
In many cases, the constraints attached to a shape can be attributed to a given property of the focus nodes.
Depending on the direction of triple traversal, SHACL defines two properties to associate a shape with such property-related constraints:
</p>
<ul>
<li><a href="#property-constraints-property"><code>sh:property</code></a> is used to link a shape with property constraints (on the objects of triples)</li>
<li><a href="#property-constraints-inverseProperty"><code>sh:inverseProperty</code></a> is used to link a shape with inverse property constraints (on the subjects of triples)</li>
</ul>
<p>
The following sections describe the role of each of these properties in detail.
Note that this section only includes textual definitions of the semantics of those properties.
An alternative formal definition based on SPARQL is provided in an <a href="#sparql-template-defs">Appendix</a>.
<span class="todo">Additional formal definitions of the upcoming core templates may be published in separate deliverables.</span>
</p>
<section id="property-constraints-property">
<h3>Property Constraints (sh:property)</h3>
<p>
A <span class="term">property constraint</span> is a constraint that defines restrictions on the values of a given property in the context of the focus node.
Here, the focus node is the <span class="term">subject</span> and the property is the <span class="term">predicate</span> of relevant triples.
The property <code>sh:property</code> can be used to link a shape with its property constraints.
</p>
<p>
In the SHACL RDF vocabulary, property constraints are instances of the class <code>sh:PropertyConstraint</code>.
When used as values of <code>sh:property</code>, property constraints represented as blank nodes do not require an <code>rdf:type</code> triple.
Note that <code>sh:property</code> may also have values that are sub-classes of <code>sh:PropertyConstraint</code>,
but in this case the <code>rdf:type</code> triple is required.
It is not valid to use <code>sh:property</code> for constraints that are not instance of <code>sh:PropertyConstraint</code>.
</p>
<p>
The following examples illustrate two ways of using property constraints.
The first example uses a blank node:
</p>
<pre class="example" title="Property constraint represented by a blank node">
ex:InlinePropertyConstraintExampleShape
a sh:Shape ;
sh:property [
sh:predicate ex:someProperty ;
sh:minCount 1 ;
sh:valueType ex:SomeClass ;
rdfs:label "some property" ;
rdfs:comment "Description of the role of ex:someProperty (in the context of the constraint)" ;
] .</pre>
<p>
The second example defines a constraint as an IRI node, allowing it to be more easily referenced and shared across multiple shapes:
</p>
<pre class="example" title="Property constraint represented by a IRI">
ex:StandAlonePropertyConstraintExampleShape
a sh:Shape ;
sh:property ex:StandAloneConstraint .
ex:StandAloneConstraint
a sh:PropertyConstraint ;
sh:predicate ex:someProperty ;
sh:defaultValue ex:SomeInstance ;
sh:minCount 1 ;
sh:valueType ex:SomeClass .</pre>
<p>
Property constraints may have an <code>rdfs:label</code> to provide a human-readable label for the property in the context where it appears.
If present, tools SHOULD prefer those locally defined labels over globally defined labels at the <code>rdf:Property</code> itself.
Similarly, property constraints may have an <code>rdfs:comment</code> to provide a description of the property in the given context.
Both <code>rdfs:label</code> and <code>rdfs:comment</code> may have multiple values, but SHOULD only have one value per language tag.
</p>
<p id="defaultValue">
Property constraints may have a single value for <code>sh:defaultValue</code>.
The default value does not have fixed semantics in SHACL, but may be used by user interface tools to pre-populate input widgets.
The value type of the <code>sh:defaultValue</code> SHOULD align with the specified <code>sh:valueType</code> of the same constraint.
</p>
<p>
The following sections provide details on the facet properties that may be used with <code>sh:PropertyConstraint</code>.
Note that the textual definitions of those facets refers to the <a href="#violations">Constraint Violations Vocabulary</a>
introduced in a later section.
</p>
<table class="term-table" border="1" cellpadding="5">
<tr>
<th>Facet Properties</th>
<th>Summary</th>
</tr>
<tr>
<td><a href="#AbstractAllowedValuesPropertyConstraint"><code>sh:allowedValues</code></a></td>
<td>Enumeration of allowed values</td>
</tr>
<tr>
<td><a href="#AbstractHasValuePropertyConstraint"><code>sh:hasValue</code></a></td>
<td>A specific required value</td>
</tr>
<tr>
<td><a href="#AbstractCountPropertyConstraint"><code>sh:minCount</code>, <code>sh:maxCount</code></a></td>
<td>Minimum and maximum cardinality</td>
</tr>
<tr>
<td><a href="#AbstractNodeTypePropertyConstraint"><code>sh:nodeType</code></a></td>
<td>Node type (IRI, blank node, or literal) of all values</td>
</tr>
<tr>
<td><a href="#AbstractValueShapePropertyConstraint"><code>sh:valueShape</code></a></td>
<td>Nested shape of all values</td>
</tr>
<tr>
<td><a href="#AbstractValueTypePropertyConstraint"><code>sh:valueType</code></a></td>
<td>Type and datatype of all values</td>
</tr>
</table>
<p class="todo">
There appears to be a good chance that SHACL will also include the following datatype property constraints similar to their XSD counterparts.
</p>
<table class="term-table" border="1" cellpadding="5">
<tr>
<th>Facet Properties</th>
<th>Summary</th>
</tr>
<tr>
<td><a href="#AbstractMaxExclusivePropertyConstraint"><code>sh:maxExclusive</code></a></td>
<td>Maximum exclusive value (<)</td>
</tr>
<tr>
<td><a href="#AbstractMaxInclusivePropertyConstraint"><code>sh:maxInclusive</code></a></td>
<td>Maximum inclusive value (<=)</td>
</tr>
<tr>
<td><a href="#AbstractMinExclusivePropertyConstraint"><code>sh:minExclusive</code></a></td>
<td>Minimum exclusive value (>)</td>
</tr>
<tr>
<td><a href="#AbstractMinInclusivePropertyConstraint"><code>sh:minInclusive</code></a></td>
<td>Minimum inclusive value (>=)</td>
</tr>
<tr>
<td><a href="#AbstractLengthPropertyConstraint"><code>sh:length</code></a></td>
<td>Exact string length</td>
</tr>
<tr>
<td><a href="#AbstractMaxLengthPropertyConstraint"><code>sh:maxLength</code></a></td>
<td>Maximum string length</td>
</tr>
<tr>
<td><a href="#AbstractMinLengthPropertyConstraint"><code>sh:minLength</code></a></td>
<td>Minimum string length</td>
</tr>
<tr>
<td><a href="#AbstractPatternPropertyConstraint"><code>sh:pattern</code></a></td>
<td>Regular expression string matching</td>
</tr>
</table>
<p class="todo">
Potential other datatype facets to include are whiteSpace, fractionDigits and totalDigits (from XSD) or stepValue from schema.org.
</p>
<section id="AbstractAllowedValuesPropertyConstraint">
<h4>sh:allowedValues</h4>
<p>
The property <code>sh:allowedValues</code> can be used to specify that all values of the given predicate
at the <span class="term">focus node</span> 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.
</p>
<table class="term-table" border="1" cellpadding="5">
<tr>
<th>Facet Property</th>
<th>Value Type</th>
<th>Summary</th>
</tr>
<tr>
<td><code>sh:allowedValues</code></td>
<td><code>sh:Set</code></td>
<td>Enumeration of allowed values</td>
</tr>
</table>
<div id="def-allowedValues-text" class="def def-text">
<div class="def-header">TEXTUAL DEFINITION</div>
<div class="def-text-body">
The values of <code>sh:allowedValues</code> must be instances of <code>sh:Set</code>, with its values of
<code>sh:member</code> pointing at the nodes in the <code>sh:Set</code>.
An <code>sh:Error</code> must be reported for every triple that has the <span class="term">focus node</span> as its subject,
the <code>sh:predicate</code> as its predicate and an object that is not a member of the given set.
Matching of literals needs to be exact, e.g. <code>"04"^^xsd:byte</code> does not match <code>"4"^^xsd:integer</code>.
Each produced <code>sh:Error</code> must have the <span class="term">focus node</span> as its <code>sh:root</code>, the <code>sh:predicate</code>
as its <code>sh:path</code> and the respective invalid value as its <code>sh:value</code>.
</div>
</div>
<p>See also: <a href="#sparql-AbstractAllowedValuesPropertyConstraint">Definition in SPARQL</a>.</p>
<pre class="example" title="Shape with sh:allowedValues constraint">
ex:AllowedValuesExampleShape
a sh:Shape ;
sh:property [
sh:predicate ex:someProperty ;
sh:allowedValues ex:AllowedValuesExampleSet ;
] .
ex:AllowedValuesExampleSet
a sh:Set ;
sh:member ex:Value1 ;
sh:member ex:Value2 ;
sh:member ex:Value3 .
ex:AllowedValuesExampleValidResource
ex:property ex:Value2 .</pre>
<p class="todo">
TODO: Some examples should also include the validation results.
</p>
<p class="issue" title="sh:allowedValue">
It is not yet decided whether the language should also support <code>sh:allowedValue</code>
that would point directly to the enumerated values instead of having an intermediate sh:Set.
The downsides of having both is that it adds extra complexity to algorithm for something that feels redundant,
and that it is not yet clear how the execution of template arguments with multiple values should work.
If we allowed rdf:List, then the Turtle/JSON-LD syntax may look good yet a sh:Set is more extensible.
</p>
</section>
<section id="AbstractHasValuePropertyConstraint">
<h4>sh:hasValue</h4>
<p>
The property <code>sh:hasValue</code> can be used to verify
that the <span class="term">focus node</span> has a given RDF node among the values of the given
predicate.
</p>
<table class="term-table" border="1" cellpadding="5">
<tr>
<th>Facet Property</th>
<th>Value Type</th>
<th>Summary</th>
</tr>
<tr>
<td><code>sh:hasValue</code></td>
<td>any</td>
<td>A specific required value</td>
</tr>
</table>
<div id="def-hasValue-text" class="def def-text">
<div class="def-header">TEXTUAL DEFINITION</div>
<div class="def-text-body">
An <code>sh:Error</code> must be reported if there is no triple that has
the <span class="term">focus node</span> as its subject, the <code>sh:predicate</code>
as its predicate and the <code>sh:hasValue</code> as its object.
</div>
</div>
<p>See also: <a href="#sparql-AbstractHasValuePropertyConstraint">Definition in SPARQL</a>.</p>
<pre class="example" title="Shape with sh:hasValue constraint">
ex:HasValueExampleShape
a sh:Shape ;
sh:property [
sh:predicate ex:property ;
sh:hasValue ex:Green ;
] .
ex:HasValueExampleValidResource
ex:property ex:Green .</pre>
</section>
<section id="AbstractCountPropertyConstraint">
<h4>sh:minCount, sh:maxCount</h4>
<p>
The properties <code>sh:minCount</code> and <code>sh:maxCount</code>
restrict the number of values of the given property at the <span class="term">focus node</span>.
</p>
<table class="term-table" border="1" cellpadding="5">
<tr>
<th>Facet Property</th>
<th>Value Type</th>
<th>Summary</th>
</tr>
<tr>
<td><code>sh:minCount</code></td>
<td><code>xsd:integer</code></td>
<td>The minimum number of values. Optional. Default value is 0.</td>
</tr>
<tr>
<td><code>sh:maxCount</code></td>
<td><code>xsd:integer</code></td>
<td>The maximum number of values. Optional. Default interpretation is unlimited.</td>
</tr>
</table>
<div id="def-count-text" class="def def-text">
<div class="def-header">TEXTUAL DEFINITION</div>
<div class="def-text-body">
Both <code>sh:minCount</code> and <code>sh:maxCount</code> are optional.
The default value of <code>sh:minCount</code> is 0.
Let <code>?count</code> be the number of triples that have the <span class="term">focus node</span> as
subject and the <code>sh:predicate</code> as the predicate.
An <code>sh:Error</code> must be reported in either of the following cases:
If <code>?count</code> is less than the value of <code>sh:minCount</code>, or
if <code>sh:maxCount</code> is present and <code>?count</code> is greater than the value of <code>sh:maxCount</code>.
The resulting <code>sh:Error</code> must have the <span class="term">focus node</span> as <code>sh:root</code>
and the predicate as its <code>sh:path</code>.
</div>
</div>
<p>See also: <a href="#sparql-AbstractCountPropertyConstraint">Definition in SPARQL</a>.</p>
<pre class="example" title="Shape with sh:minCount and sh:maxCount constraints">
ex:CountExampleShape
a sh:Shape ;
sh:property [
sh:predicate ex:someProperty ;
sh:minCount 1 ;
sh:maxCount 1 ;
] .
ex:CountExampleValidResource
ex:someProperty ex:OneValue .</pre>
</section>
<section id="AbstractNodeTypePropertyConstraint">
<h4>sh:nodeType</h4>
<p>
The property <code>sh:nodeType</code> can be used to restrict the RDF node type of all values of the given property.
</p>
<table class="term-table" border="1" cellpadding="5">
<tr>
<th>Facet Property</th>
<th>Value Type</th>
<th>Summary</th>
</tr>
<tr>
<td><code>sh:nodeType</code></td>
<td><code>sh:NodeType</code></td>
<td>Node type (IRI, blank node, or literal) of all values</td>
</tr>
</table>
<p>
The values of <code>sh:nodeType</code> must be instances of the class <code>sh:NodeType</code>.
The SHACL system vocabulary defines that <code>sh:NodeType</code> has exactly 7 instances,
as defined in the <a href="#function-hasNodeType">Appendix</a>.
</p>
<p class="todo">
Dimitris suggests we only support sh:IRI, sh:Literal and sh:BlankNode and use some generic OR mechanism to combine them.
</p>
<div id="def-nodeType-text" class="def def-text">
<div class="def-header">TEXTUAL DEFINITION</div>
<div class="def-text-body">
An <code>sh:Error</code> must be reported for each triple that has
the <span class="term">focus node</span> as its subject, the <code>sh:predicate</code>
as its predicate and where the object does not match the node type tests
defined in the table above.
Each produced <code>sh:Error</code> must have the <code>sh:predicate</code>
as its <code>sh:path</code> and the respective violating value as its <code>sh:value</code>.
</div>
</div>
<p>See also: <a href="#sparql-AbstractNodeTypePropertyConstraint">Definition in SPARQL</a>.</p>
<pre class="example" title="Shape with sh:nodeType constraint">
ex:NodeTypeExampleShape
a sh:Shape ;
sh:property [
sh:predicate ex:someProperty ;
sh:nodeType ex:IRI ;
] .
ex:NodeTypeShapeExampleValidResource
ex:someProperty ex:SomeIRI .
ex:NodeTypeShapeExampleInvalidResource
ex:someProperty ex:SomeIRI ;
ex:someProperty "A literal" .</pre>
</section>
<section id="AbstractValueShapePropertyConstraint">
<h4>sh:valueShape</h4>
<p>
The property <code>sh:valueShape</code> can be used verify that all values of the given property must match a given shape.
The value type of <code>sh:valueShape</code> is <code>sh:Shape</code><span class="todo"> (and/or <code>rdfs:Class</code>)</span>.
If the value shapes are blank nodes, then their <code>rdf:type</code> triple can be omitted.
</p>
<table class="term-table" border="1" cellpadding="5">
<tr>
<th>Facet Property</th>
<th>Value Type</th>
<th>Summary</th>
</tr>
<tr>
<td><code>sh:valueShape</code></td>
<td><code>sh:Shape</code></td>
<td>The required shape of all values</td>
</tr>
</table>
<div id="def-valueShape-text" class="def def-text">
<div class="def-header">TEXTUAL DEFINITION</div>
<div class="def-text-body">
An <code>sh:Error</code> must be reported for each triple that has
the <span class="term">focus node</span> as its subject, the <code>sh:predicate</code>
as its predicate and where the object does not match the shape specified by <code>sh:valueShape</code>.
Each produced <code>sh:Error</code> must have the <code>sh:predicate</code>
as its <code>sh:path</code> and the respective violating value as its <code>sh:value</code>.
</div>
</div>
<p>See also: <a href="#sparql-AbstractValueShapePropertyConstraint">Definition in SPARQL</a>.</p>
<p class="issue" title="Recursion of sh:valueShape">
It is not yet decided how to handle recursive shape definitions in sh:valueShape.
</p>
<p>
In the following example, all values of the property <code>ex:someProperty</code> are supposed to match the shape
specified by a blank node that ensures that the property <code>ex:nestedProperty</code> has at least one value.
Note that the values of <code>sh:valueShape</code> do not require an <code>rdf:type</code> triple - <code>sh:Shape</code> is implicit.
</p>
<pre class="example" title="Shape with sh:valueShape constraint">
ex:ValueShapeExampleShape
a sh:Shape ;
sh:property [
sh:predicate ex:someProperty ;
sh:valueShape [
a sh:Shape ; # Optional
sh:predicate [
sh:predicate ex:nestedProperty ;
sh:minCount 1 ;
]
]
] .
ex:ValueShapeExampleValidResource
ex:someProperty [
ex:nestedProperty 42 ;
] .</pre>
</section>
<section id="AbstractValueTypePropertyConstraint">
<h4>sh:valueType</h4>
<p class="issue" title="sh:valueType">
The details of valueType validation need to be fully worked out.
In a nutshell, the goal is to have one or two properties to narrow down the type of values.
The user experience may be best if there was just one property, sh:valueType.
However, there are substantial differences between datatypes and class-based types.
For datatypes, we should exclude reified values such as instances of xsd:integer.
For resources, we need to make sure that (transitive) subclasses are accepted too.
What about typeless resources - I believe these should be allowed if the valueType is rdfs:Resource or rdf:Property.
Another question will be whether multiple valueTypes should be supported, and what their semantics should be.
For now we only include an example of sh:valueType, to illustrate a possible design.
</p>
</section>
<pre class="example" title="Shape with sh:valueType constraint">
ex:ValueTypeExampleShape
a sh:Shape ;
sh:property [
sh:predicate ex:someProperty ;
sh:valueType xsd:string ;
] .
ex:ValueTypeExampleValidResource
ex:someProperty "A string" .</pre>
</section>
<section id="property-constraints-inverseProperty">
<h3>Inverse Property Constraints (sh:inverseProperty)</h3>
<p class="todo">
TODO: This section is quite similar to the one about sh:property, only in the inverse direction.
Before writing all this down, we'd rather wait until the forward direction has stabilized.
A quick example should suffice for now:
</p>
<pre class="example" title="Shape with an inverse property constraint">
ex:InversePropertyConstraintExampleShape
a sh:Shape ;
sh:inverseProperty [
sh:predicate ex:someProperty ; # e.g. "child"
sh:minCount 1 ;
rdfs:label "is someProperty of" ; # e.g. "parent"
] .</pre>
<p class="todo">
TODO: Possibly use <code>sh:inversePredicate</code> instead of <code>sh:predicate</code>.
</p>
</section>
</section>
<section id="or">
<h2>Disjunctive Constraints (sh:OrConstraint)</h2>
<p class="issue">
The WG has not decided whether Or (and similar operands such as Not) will be part of the high-level vocabulary, or whether they will be limited to executable languages such as SPARQL.
</p>
<p class="todo">
TODO: The proposal here is just one possible syntax, based on a template.
Other alternatives include to hard-code it into a new kind of Shape with its own syntax
as outlined in Eric's version of the primer.
</p>
<p>
SHACL supports a high-level syntax for disjunctive local constraints that can be used to test whether the <span class="term">focus node</span> matches at least one out of several shapes.
This is comparable to a logical "or" operator.
</p>
<div id="def-orConstraint-text" class="def def-text">
<div class="def-header">TEXTUAL DEFINITION</div>
<div class="def-text-body">
An <code>sh:Error</code> must be reported if the <span class="term">focus node</span> produces error-level
constraint violations against both shapes <code>sh:shape1</code> and <code>sh:shape2</code>.
</div>
</div>
<p>See also: <a href="#sparql-or">Definition in SPARQL</a>.</p>
<p>
The following example illustrates the use of <code>sh:OrConstraint</code> in a shape to verify
that matching nodes have at least one value of <code>ex:exampleProperty1</code>
or at least one value of <code>ex:exampleProperty2</code>.
</p>
<pre class="example" title="Shape with a disjunction">
ex:OrConstraintExampleShape
a sh:Shape ;
sh:constraint [
a sh:OrConstraint ;
sh:shape1 [
sh:property [
sh:predicate ex:exampleProperty1 ;
sh:minCount 1 ;
] ;
] ;
sh:shape2 [
sh:property [
sh:predicate ex:exampleProperty2 ;
sh:minCount 1 ;
]
]
] .
ex:OrConstraintExampleValidResource
sh:exampleProperty1 ex:someValue .</pre>
</section>
<section id="scope">
<h2>Scope of Constraints (sh:scope)</h2>
<p class="todo">
This feature has been proposed but is not an accepted requirement and is fully not worked out yet.
Here is just one possible design, as a placeholder, for now.
</p>
<p>
Local constraints may have a property <code>sh:scope</code> to declare a <span class="term">scope</span> that serves as a <span class="term">pre-condition</span>
to narrow down when the constraint applies. The values of <code>sh:scope</code> must be shape definitions.
These shapes must be evaluated before the constraint is evaluated.
If the scope shape returns an error-level constraint violation, then the constraint will be ignored.
Values of <code>sh:scope</code> that are blank nodes do not require an <code>rdf:type</code> triple - the default type is <code>sh:Shape</code>.
</p>
<p>
The following example states that the <code>sh:minCount</code> constraint only applies to resources that have a certain value for <code>ex:requiredProperty</code>.
</p>
<pre class="example" title="Scoped constraint">
ex:ScopedExampleShape
a sh:Shape ;
sh:property [
sh:predicate ex:someProperty ;
sh:minCount 1 ;
sh:scope [
a sh:Shape ; # Optional triple
sh:property [
sh:predicate ex:requiredProperty ;
sh:hasValue ex:requiredValue ;
]
] ;
] .
ex:ScopedShapeValidExampleInstance
ex:someProperty ex:someValue ;
ex:requiredProperty ex:requiredValue .</pre>
</section>
<section id="violations">
<h2>Constraint Violations Vocabulary</h2>
<p>
The output of a SHACL constraint validation operation is a set of <span class="term">constraint violations</span>.
SHACL includes an RDF vocabulary to represent such constraint violations together with
structural information that may provide guidance on how to fix the violation, as well as
human-readable messages.
</p>
<p>
The following code snippet represents a valid constraint violation that may have been produced
by a constraint validation engine:
</p>
<pre class="example" title="A constructed constraint violation">
ex:ExampleConstraintViolation
a sh:Error ;
sh:root ex:MyCurrentNode ;
sh:path ex:someProperty ;
sh:value ex:someInvalidValue ;
sh:message "Incorrect value: expected something else here." .</pre>
<section id="violations-types">
<h3>Types of Constraint Violations</h3>
<p>
A constraint violation is represented by a IRI or blank node that has exactly one
asserted <code>rdf:type</code>.
The <code>rdf:type</code> arc of a constraint violation must point to one of the subclasses
of the ("abstract") base class <code>sh:ConstraintViolation</code>.
The SHACL system vocabulary includes the following constraint violation types:
</p>
<table class="term-table" border="1" cellpadding="5">
<tr>
<th>Constraint Violation Class</th>
<th>Superclass</th>
<th>Description</th>
</tr>
<tr>
<td><code>sh:Warning</code></td>
<td><code>sh:ConstraintViolation</code></td>
<td>A non-critical constraint violation indicating a warning.</td>
</tr>
<tr>