mdld-parse 0.9.1 → 0.9.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +34 -1
- package/dist/.nojekyll +0 -0
- package/dist/CNAME +1 -0
- package/dist/README.md +425 -0
- package/dist/docs/API.md +397 -0
- package/dist/docs/Architecture.md +190 -0
- package/dist/docs/Guide.md +322 -0
- package/dist/docs/LLM-MDLD-Inducer.md +550 -0
- package/dist/docs/Parser.md +654 -0
- package/dist/docs/Performance.md +238 -0
- package/dist/docs/Spec-render.md +1439 -0
- package/dist/docs/Subject.md +180 -0
- package/dist/docs/Syntax.md +463 -0
- package/dist/docs/TodoList.md +215 -0
- package/dist/docs/Use-Cases.md +354 -0
- package/dist/docs/index.html +108 -0
- package/dist/docs/index.md +56 -0
- package/dist/docs/origin.md +459 -0
- package/dist/docs/polarity.md +586 -0
- package/dist/docs/primary-subject.md +199 -0
- package/dist/docs/statements.md +226 -0
- package/dist/docs/tokenization-performance-report.md +164 -0
- package/dist/examples/Cookbook.md +32 -0
- package/dist/examples/Status-SHACL.md +33 -0
- package/dist/examples/demo/index.md +35 -0
- package/dist/examples/demo/journal.md +18 -0
- package/dist/examples/demo/minimal.md +11 -0
- package/dist/examples/demo/project.md +15 -0
- package/dist/examples/demo/recipe.md +31 -0
- package/dist/examples/demo/research.md +46 -0
- package/dist/examples/demo/space-mission.md +48 -0
- package/dist/examples/dogfood.md +288 -0
- package/dist/examples/few-shot.md +309 -0
- package/dist/examples/graph/rdf-graph.html +473 -0
- package/dist/examples/graph/rdf_force_graph_web_component.html +506 -0
- package/dist/examples/index.md +45 -0
- package/dist/examples/llm-time-workflow.md +173 -0
- package/dist/examples/prov-o.md +2367 -0
- package/dist/examples/rdf.md +827 -0
- package/dist/examples/shacl.md +3399 -0
- package/dist/examples/statements.md +43 -0
- package/dist/examples/workflow.md +150 -0
- package/dist/index.html +2827 -0
- package/dist/index.js +1548 -0
- package/dist/logo.svg +7 -0
- package/dist/spec/Spec-compact.md +363 -0
- package/dist/spec/Spec-ultra.md +221 -0
- package/dist/spec/Spec.md +1068 -0
- package/dist/spec/index.md +46 -0
- package/package.json +13 -8
- package/src/constants.js +0 -31
- package/src/generate.js +0 -245
- package/src/index.js +0 -13
- package/src/locate.js +0 -23
- package/src/merge.js +0 -157
- package/src/parse.js +0 -765
- package/src/render.js +0 -576
- package/src/shared.js +0 -577
- package/src/utils.js +0 -430
|
@@ -0,0 +1,3399 @@
|
|
|
1
|
+
<a id="index"></a>
|
|
2
|
+
|
|
3
|
+
[mdld] <https://mdld.js.org/>
|
|
4
|
+
[cat] <mdld:shacl/>
|
|
5
|
+
[class] <cat:class/>
|
|
6
|
+
|
|
7
|
+
# MDLD SHACL Catalog {=cat:index .Container label}
|
|
8
|
+
|
|
9
|
+
> A comprehensive guide to SHACL validation in MDLD (Markdown Linked Data) - self-validating documentation for semantic authors. {?comment}
|
|
10
|
+
|
|
11
|
+
This catalog [includes] {+cat:includes .rdf:Property label} all constraints and targeting mechanisms available in SHACL.
|
|
12
|
+
|
|
13
|
+
## Contents
|
|
14
|
+
|
|
15
|
+
[Getting Started](#teach-getting-started)
|
|
16
|
+
[Choosing Constraints](#teach-choosing-constraints)
|
|
17
|
+
[Practical Workflow](#teach-practical-workflow)
|
|
18
|
+
[Advanced Techniques](#teach-advanced)
|
|
19
|
+
[Targeting](#targeting-index)
|
|
20
|
+
[Constraints](#constraints-index)
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
{=}
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
<a id="teach-getting-started"></a>
|
|
32
|
+
|
|
33
|
+
[mdld] <https://mdld.js.org/>
|
|
34
|
+
[cat] <mdld:shacl/>
|
|
35
|
+
|
|
36
|
+
# Getting Started with MDLD SHACL
|
|
37
|
+
|
|
38
|
+
> Learn the fundamentals of SHACL validation in MDLD (Markdown Linked Data) {comment}
|
|
39
|
+
|
|
40
|
+
## What is SHACL?
|
|
41
|
+
|
|
42
|
+
SHACL (Shapes Constraint Language) is a W3C standard for validating RDF graphs. In MDLD, SHACL constraints are written directly in Markdown, making validation rules human-readable and machine-processable.
|
|
43
|
+
|
|
44
|
+
## Core Concepts
|
|
45
|
+
|
|
46
|
+
**Shapes** define validation rules for your data. Think of a shape as a template that your data must conform to.
|
|
47
|
+
|
|
48
|
+
**Targets** determine which nodes in your data get validated. You can target by class, specific node, or relationship.
|
|
49
|
+
|
|
50
|
+
**Constraints** define the actual validation rules (e.g., required properties, value ranges, string patterns).
|
|
51
|
+
|
|
52
|
+
## Your First Shape
|
|
53
|
+
|
|
54
|
+
Let's create a simple shape for validating user accounts:
|
|
55
|
+
|
|
56
|
+
~~~~~~md
|
|
57
|
+
[ex] <tag:my@example.org,2026:users/>
|
|
58
|
+
|
|
59
|
+
**User Validation Shape** {=ex:UserShape .sh:NodeShape label}
|
|
60
|
+
Validates all [User] {+ex:User ?sh:targetClass} instances to have a [name] {+ex:UsernameRule ?sh:property sh:name} and an [email] {+ex:EmailRule ?sh:property sh:name}.
|
|
61
|
+
|
|
62
|
+
**Username is required** {=ex:UsernameRule .sh:PropertyShape sh:message} requires [username] {+ex:username ?sh:path} to have exactly [1] {sh:minCount sh:maxCount ^^xsd:integer} value.
|
|
63
|
+
|
|
64
|
+
**Email is required** {=ex:EmailRule .sh:PropertyShape sh:message} requires [email] {+ex:email ?sh:path} must have at least [1] {sh:minCount ^^xsd:integer} value.
|
|
65
|
+
~~~~~~
|
|
66
|
+
|
|
67
|
+
## Key MDLD Syntax Patterns
|
|
68
|
+
|
|
69
|
+
| Pattern | Meaning | Example |
|
|
70
|
+
|---------|---------|---------|
|
|
71
|
+
| `{=}` | Subject declaration (persists) | `{=ex:shape .sh:NodeShape}` |
|
|
72
|
+
| `{+}` | Object introduction (temporary) | `{+ex:target ?sh:targetClass}` |
|
|
73
|
+
| `?` | Object predicate (Subject → Object) | `?sh:targetClass`, `?sh:path` |
|
|
74
|
+
| `.` | Class type declaration | `.sh:NodeShape` |
|
|
75
|
+
| `^^` | Literal datatype | `^^xsd:integer` |
|
|
76
|
+
|
|
77
|
+
## Basic Workflow
|
|
78
|
+
|
|
79
|
+
1. **Define your shape** - Create a NodeShape with a descriptive name
|
|
80
|
+
2. **Set your target** - Choose how to select data (targetClass, targetNode, etc.)
|
|
81
|
+
3. **Add property rules** - Define PropertyShapes for each property to validate
|
|
82
|
+
4. **Add constraints** - Apply constraint rules (minCount, datatype, pattern, etc.)
|
|
83
|
+
5. **Test with data** - Create test data with valid and invalid examples
|
|
84
|
+
|
|
85
|
+
## Next Steps
|
|
86
|
+
|
|
87
|
+
- Learn about [Targeting Mechanisms](#targeting-index) to select your data
|
|
88
|
+
- Explore [Constraints](#constraints-index) to define validation rules
|
|
89
|
+
- See practical examples in the constraint documentation
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
{=}
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
<a id="targeting-index"></a>
|
|
101
|
+
|
|
102
|
+
[mdld] <https://mdld.js.org/>
|
|
103
|
+
[cat] <mdld:shacl/>
|
|
104
|
+
[class] <cat:class/>
|
|
105
|
+
|
|
106
|
+
# Catalog {=cat:index}
|
|
107
|
+
|
|
108
|
+
## Targeting Mechanism {+class:Targeting ?member .Class label}
|
|
109
|
+
|
|
110
|
+
These are targeting predicates that determine which nodes get validated (not constraints themselves):
|
|
111
|
+
|
|
112
|
+
- [Target Class](#targeting-targetclass) {+sh:targetClass ?cat:includes .class:TargetingPredicate}
|
|
113
|
+
- [Target Node](#targeting-targetnode) {+sh:targetNode ?cat:includes .class:TargetingPredicate}
|
|
114
|
+
- [Target Subjects](#targeting-targetsubjectsof) {+sh:targetSubjectsOf ?cat:includes .class:TargetingPredicate}
|
|
115
|
+
- [Target Objects](#targeting-targetobjectsof) {+sh:targetObjectsOf ?cat:includes .class:TargetingPredicate}
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
[Syntax Reference](#syntax-reference)
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
{=}
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
<a id="targeting-targetclass"></a>
|
|
131
|
+
|
|
132
|
+
[mdld] <https://mdld.js.org/>
|
|
133
|
+
[cat] <mdld:shacl/>
|
|
134
|
+
[ex] <mdld:shacl/example/targeting/>
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
# Target Class {=sh:targetClass .class:TargetingMechanism label}
|
|
138
|
+
|
|
139
|
+
> Targets all nodes that are instances of a specific RDF class (rdf:type) for shape validation. Essential for class-based validation scenarios across entire domains. {comment}
|
|
140
|
+
|
|
141
|
+
<http://www.w3.org/ns/shacl#targetClass> {?cat:fullIRI}
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## 📋 Quick Start Pattern
|
|
146
|
+
|
|
147
|
+
The targetClass constraint targets all nodes that are instances of a specific RDF class. This example validates all Product instances for business requirements.
|
|
148
|
+
|
|
149
|
+
~~~~~~md
|
|
150
|
+
[ex] <mdld:shacl/example/targeting/>
|
|
151
|
+
|
|
152
|
+
## Product Validation Shape {=ex:ProductValidationShape .sh:NodeShape label}
|
|
153
|
+
|
|
154
|
+
Targets all [Product] {+ex:Product ?sh:targetClass} instances to validate core product requirements: [name] {+#productName ?sh:property sh:name} and [price] {+#productPrice ?sh:property sh:name}.
|
|
155
|
+
|
|
156
|
+
**Product must have exactly one name** {=#productName .sh:PropertyShape sh:message} requires the [name] {+ex:name ?sh:path} property to have exactly [1] {sh:minCount sh:maxCount ^^xsd:integer} value.
|
|
157
|
+
|
|
158
|
+
**Product price must be positive** {=#productPrice .sh:PropertyShape sh:message} requires the [price] {+ex:price ?sh:path} property to be at least [0.01] {sh:minInclusive ^^xsd:decimal}.
|
|
159
|
+
|
|
160
|
+
---
|
|
161
|
+
|
|
162
|
+
## Test Data {=ex:data .Container}
|
|
163
|
+
|
|
164
|
+
### Laptop {=ex:Laptop .ex:Product}
|
|
165
|
+
Name: [MacBook Pro] {ex:name}
|
|
166
|
+
Price: [1299.99] {ex:price ^^xsd:decimal}
|
|
167
|
+
|
|
168
|
+
### Invalid Product {=ex:InvalidProduct .ex:Product}
|
|
169
|
+
Price: [-50.00] {ex:price ^^xsd:decimal}
|
|
170
|
+
|
|
171
|
+
### Service {=ex:Service .ex:Service}
|
|
172
|
+
Name: [Consulting] {ex:name}
|
|
173
|
+
Price: [200.00] {ex:price ^^xsd:decimal}
|
|
174
|
+
~~~~~~
|
|
175
|
+
|
|
176
|
+
**Expected Result:** 2 violations (InvalidProduct fails twice: missing name AND negative price; Service not validated since it's not a Product)
|
|
177
|
+
|
|
178
|
+
---
|
|
179
|
+
|
|
180
|
+
## 📝 MDLD Syntax Patterns
|
|
181
|
+
|
|
182
|
+
Target class targets all nodes that are instances of a specific RDF class for shape validation.
|
|
183
|
+
|
|
184
|
+
~~~~~~md
|
|
185
|
+
**[Shape] targets [Class] instances** {=ex:ShapeName .sh:NodeShape label}
|
|
186
|
+
|
|
187
|
+
[Shape Name] {=ex:ShapeName .sh:NodeShape label} targets all [Class] {+ex:Class ?sh:targetClass} instances to validate requirements.
|
|
188
|
+
~~~~~~
|
|
189
|
+
|
|
190
|
+
**Key components:**
|
|
191
|
+
- **Shape declaration** - The shape being defined (`{=ex:ShapeName .sh:NodeShape label}`)
|
|
192
|
+
- **Target class** - The class to target (`{+ex:Class ?sh:targetClass}`)
|
|
193
|
+
- **Validation rules** - Property constraints within the shape
|
|
194
|
+
- **Class-based selection** - Validates all instances of the specified class
|
|
195
|
+
|
|
196
|
+
**Important notes:**
|
|
197
|
+
- Target class validates all instances of the specified class
|
|
198
|
+
- Ideal for domain-wide validation rules
|
|
199
|
+
- Works with rdf:type relationships
|
|
200
|
+
- Combine with targeting mechanisms for complex scenarios
|
|
201
|
+
- Use for consistent validation across class instances
|
|
202
|
+
|
|
203
|
+
---
|
|
204
|
+
|
|
205
|
+
## 🎯 Use Cases
|
|
206
|
+
|
|
207
|
+
- **Domain validation** - Validate all instances of a domain class
|
|
208
|
+
- **Business rules** - Enforce class-specific business requirements
|
|
209
|
+
- **Data quality** - Ensure data consistency across class instances
|
|
210
|
+
- **Schema enforcement** - Apply validation rules to entire class hierarchies
|
|
211
|
+
- **Compliance** - Validate regulatory requirements for specific entity types
|
|
212
|
+
|
|
213
|
+
---
|
|
214
|
+
|
|
215
|
+
## 🔧 Implementation Guidelines
|
|
216
|
+
|
|
217
|
+
**When to use target class:**
|
|
218
|
+
- **Domain-wide validation** - When validating entire classes of entities
|
|
219
|
+
- **Business rules** - Enforce class-specific business requirements
|
|
220
|
+
- **Data quality** - Ensure consistency across class instances
|
|
221
|
+
- **Schema enforcement** - Apply validation to class hierarchies
|
|
222
|
+
- **Compliance** - Validate regulatory requirements
|
|
223
|
+
|
|
224
|
+
**Best practices:**
|
|
225
|
+
- Use descriptive shape names that reflect the target class
|
|
226
|
+
- Combine with other targeting mechanisms for complex scenarios
|
|
227
|
+
- Test with valid and invalid instances
|
|
228
|
+
- Document the validation scope clearly
|
|
229
|
+
- Consider performance for large class instances
|
|
230
|
+
|
|
231
|
+
**Common pitfalls:**
|
|
232
|
+
- ❌ Forgetting that target class validates all instances
|
|
233
|
+
- ❌ Not testing with instances outside the target class
|
|
234
|
+
- ❌ Confusing target class with target node
|
|
235
|
+
- ❌ Not considering performance for large datasets
|
|
236
|
+
- ❌ Overusing target class when target node would be more appropriate
|
|
237
|
+
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
{=}
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
|
|
247
|
+
<a id="targeting-targetnode"></a>
|
|
248
|
+
|
|
249
|
+
[mdld] <https://mdld.js.org/>
|
|
250
|
+
[cat] <mdld:shacl/>
|
|
251
|
+
[ex] <mdld:shacl/example/targeting/>
|
|
252
|
+
|
|
253
|
+
|
|
254
|
+
# Target Node {=sh:targetNode .class:TargetingMechanism label}
|
|
255
|
+
|
|
256
|
+
> Targets specific individual nodes identified by their IRI for precise, node-by-node validation. Perfect for critical infrastructure, testing scenarios, and executive-level validation. {comment}
|
|
257
|
+
|
|
258
|
+
<http://www.w3.org/ns/shacl#targetNode> {?cat:fullIRI}
|
|
259
|
+
|
|
260
|
+
---
|
|
261
|
+
|
|
262
|
+
## 📋 Quick Start Pattern
|
|
263
|
+
|
|
264
|
+
The targetNode constraint targets specific individual nodes for validation. This example demonstrates critical infrastructure and executive validation scenarios.
|
|
265
|
+
|
|
266
|
+
~~~~~~md
|
|
267
|
+
[ex] <mdld:shacl/example/targeting/>
|
|
268
|
+
|
|
269
|
+
## Critical Infrastructure Demo
|
|
270
|
+
|
|
271
|
+
The **Database Validation Shape** {=ex:DatabaseValidationShape .sh:NodeShape ?cat:hasShape label} targets the [Main Database] {+ex:MainDatabase ?sh:targetNode} for critical infrastructure validation: [status] {+#databaseStatus ?sh:property sh:name} and [uptime] {+#databaseUptime ?sh:property sh:name}.
|
|
272
|
+
|
|
273
|
+
**Main database must be online** {=#databaseStatus .sh:PropertyShape sh:message} requires the [status] {+ex:status ?sh:path} property to be exactly [online] {sh:hasValue}.
|
|
274
|
+
|
|
275
|
+
**Database uptime must be at least 99.9%** {=#databaseUptime .sh:PropertyShape sh:message} that requires the [uptime] {+ex:uptime ?sh:path} property to be at least [99.9] {sh:minInclusive ^^xsd:decimal}.
|
|
276
|
+
|
|
277
|
+
## Executive Validation Demo
|
|
278
|
+
|
|
279
|
+
**CEO Validation Shape** {=ex:CEOValidationShape .sh:NodeShape ?cat:hasShape label} targets the [CEO] {+ex:CEO ?sh:targetNode} for [executive] {+#executiveClearance ?sh:property sh:name} level clearance.
|
|
280
|
+
|
|
281
|
+
**CEO must have top-secret security clearance** {=#executiveClearance .sh:PropertyShape sh:message} requires the [securityClearance] {+ex:securityClearance ?sh:path} property to be exactly [top-secret] {sh:hasValue}.
|
|
282
|
+
|
|
283
|
+
---
|
|
284
|
+
|
|
285
|
+
## Test Data {=ex:data .Container}
|
|
286
|
+
|
|
287
|
+
### Main Database {=ex:MainDatabase}
|
|
288
|
+
Status: [offline] {ex:status}
|
|
289
|
+
Uptime: [95.5] {ex:uptime ^^xsd:decimal}
|
|
290
|
+
|
|
291
|
+
### Backup Database {=ex:BackupDatabase}
|
|
292
|
+
Status: [online] {ex:status}
|
|
293
|
+
Uptime: [99.8] {ex:uptime ^^xsd:decimal}
|
|
294
|
+
|
|
295
|
+
### CEO {=ex:CEO}
|
|
296
|
+
Security Clearance: [secret] {ex:securityClearance}
|
|
297
|
+
|
|
298
|
+
### CFO {=ex:CFO}
|
|
299
|
+
Security Clearance: [secret] {ex:securityClearance}
|
|
300
|
+
~~~~~~
|
|
301
|
+
|
|
302
|
+
**Expected Result:** 3 violations (MainDatabase fails twice: status offline AND uptime < 99.9%; CEO fails: clearance is secret not top-secret; BackupDatabase and CFO not validated as they're not targeted)
|
|
303
|
+
|
|
304
|
+
---
|
|
305
|
+
|
|
306
|
+
## 📝 MDLD Syntax Patterns
|
|
307
|
+
|
|
308
|
+
Target node targets specific individual nodes identified by their IRI for precise validation.
|
|
309
|
+
|
|
310
|
+
~~~~~~md
|
|
311
|
+
**[Shape] targets [Node]** {=ex:ShapeName .sh:NodeShape label}
|
|
312
|
+
|
|
313
|
+
[Shape Name] {=ex:ShapeName .sh:NodeShape label} targets the [Node] {+ex:Node ?sh:targetNode} for validation.
|
|
314
|
+
~~~~~~
|
|
315
|
+
|
|
316
|
+
**Key components:**
|
|
317
|
+
- **Shape declaration** - The shape being defined (`{=ex:ShapeName .sh:NodeShape label}`)
|
|
318
|
+
- **Target node** - The specific node to target (`{+ex:Node ?sh:targetNode}`)
|
|
319
|
+
- **Validation rules** - Property constraints within the shape
|
|
320
|
+
- **Node-specific selection** - Validates only the specified node
|
|
321
|
+
|
|
322
|
+
**Important notes:**
|
|
323
|
+
- Target node validates only the specified individual node
|
|
324
|
+
- Ideal for critical infrastructure and executive validation
|
|
325
|
+
- Provides precise control over validation scope
|
|
326
|
+
- Use for testing specific scenarios
|
|
327
|
+
- Combine with other targeting mechanisms for complex scenarios
|
|
328
|
+
|
|
329
|
+
---
|
|
330
|
+
|
|
331
|
+
## 🎯 Use Cases
|
|
332
|
+
|
|
333
|
+
- **Critical infrastructure** - Validate critical systems and infrastructure
|
|
334
|
+
- **Executive validation** - Validate executive-level entities
|
|
335
|
+
- **Testing scenarios** - Test specific nodes in isolation
|
|
336
|
+
- **Compliance** - Validate specific regulatory entities
|
|
337
|
+
- **Quality assurance** - Validate specific production nodes
|
|
338
|
+
|
|
339
|
+
---
|
|
340
|
+
|
|
341
|
+
## 🔧 Implementation Guidelines
|
|
342
|
+
|
|
343
|
+
**When to use target node:**
|
|
344
|
+
- **Critical infrastructure** - When validating specific critical systems
|
|
345
|
+
- **Executive validation** - When validating executive-level entities
|
|
346
|
+
- **Testing** - When testing specific nodes in isolation
|
|
347
|
+
- **Compliance** - When validating specific regulatory entities
|
|
348
|
+
- **Quality assurance** - When validating specific production nodes
|
|
349
|
+
|
|
350
|
+
**Best practices:**
|
|
351
|
+
- Use descriptive node identifiers for clarity
|
|
352
|
+
- Combine with target class for comprehensive validation
|
|
353
|
+
- Test with valid and invalid node states
|
|
354
|
+
- Document why specific nodes are targeted
|
|
355
|
+
- Consider using target class for broader validation
|
|
356
|
+
|
|
357
|
+
**Common pitfalls:**
|
|
358
|
+
- ❌ Forgetting that target node validates only one specific node
|
|
359
|
+
- ❌ Overusing target node when target class would be more appropriate
|
|
360
|
+
- ❌ Not testing with nodes outside the target
|
|
361
|
+
- ❌ Confusing target node with target class
|
|
362
|
+
- ❌ Not documenting why specific nodes are targeted
|
|
363
|
+
|
|
364
|
+
|
|
365
|
+
|
|
366
|
+
|
|
367
|
+
|
|
368
|
+
|
|
369
|
+
{=}
|
|
370
|
+
|
|
371
|
+
|
|
372
|
+
|
|
373
|
+
<a id="targeting-targetsubjectsof"></a>
|
|
374
|
+
|
|
375
|
+
[mdld] <https://mdld.js.org/>
|
|
376
|
+
[cat] <mdld:shacl/>
|
|
377
|
+
[ex] <mdld:shacl/example/targeting/>
|
|
378
|
+
|
|
379
|
+
|
|
380
|
+
# Target Subjects Of {=sh:targetSubjectsOf .class:TargetingMechanism label}
|
|
381
|
+
|
|
382
|
+
> Targets all subjects (nodes) that have a specific property pointing to any value. Useful for reverse relationship targeting, source validation, and validating entities that initiate relationships. {comment}
|
|
383
|
+
|
|
384
|
+
<http://www.w3.org/ns/shacl#targetSubjectsOf> {?cat:fullIRI}
|
|
385
|
+
|
|
386
|
+
---
|
|
387
|
+
|
|
388
|
+
## 📋 Quick Start Pattern
|
|
389
|
+
|
|
390
|
+
The targetSubjectsOf constraint targets all subjects (nodes) that have a specific property pointing to any value. This example demonstrates management and approval scenarios where we validate entities that initiate relationships.
|
|
391
|
+
|
|
392
|
+
~~~~~~md
|
|
393
|
+
[ex] <mdld:shacl/example/targeting/>
|
|
394
|
+
|
|
395
|
+
## Management Validation Demo
|
|
396
|
+
|
|
397
|
+
The **Manager Validation Shape** {=ex:ManagerValidationShape .sh:NodeShape label} targets all [managers] {+ex:manages ?sh:targetSubjectsOf} of the manages relationship to validate management requirements: [level] {+#managementLevel ?sh:property sh:name} and [teamSize] {+#teamSize ?sh:property sh:name}.
|
|
398
|
+
|
|
399
|
+
**Managers must have level 3 or higher** {=#managementLevel .sh:PropertyShape sh:message} requires the [level] {+ex:level ?sh:path} property to be at least [3] {sh:minInclusive ^^xsd:integer}.
|
|
400
|
+
|
|
401
|
+
**Managers can oversee at most 10 team members** {=#teamSize .sh:PropertyShape sh:message} that requires the [teamSize] {+ex:teamSize ?sh:path} property to be at most [10] {sh:maxInclusive ^^xsd:integer}.
|
|
402
|
+
|
|
403
|
+
## Approval Validation Demo
|
|
404
|
+
|
|
405
|
+
**Approver Validation Shape** {=ex:ApproverValidationShape .sh:NodeShape label} targets all [approvers] {+ex:approves ?sh:targetSubjectsOf} of the approves relationship to validate approval [authority] {+#approvalAuthority ?sh:property sh:name}.
|
|
406
|
+
|
|
407
|
+
**Approvers must have authority level 2 or higher** {=#approvalAuthority .sh:PropertyShape sh:message} requires the [authority] {+ex:authority ?sh:path} property to be at least [2] {sh:minInclusive ^^xsd:integer}.
|
|
408
|
+
|
|
409
|
+
---
|
|
410
|
+
|
|
411
|
+
## Test Data {=ex:data .Container}
|
|
412
|
+
|
|
413
|
+
### Engineering Manager {=ex:EngineeringManager}
|
|
414
|
+
Level: [2] {ex:level ^^xsd:integer}
|
|
415
|
+
Team Size: [15] {ex:teamSize ^^xsd:integer}
|
|
416
|
+
Manages: [EngineeringTeam] {ex:manages}
|
|
417
|
+
|
|
418
|
+
### Senior Manager {=ex:SeniorManager}
|
|
419
|
+
Level: [4] {ex:level ^^xsd:integer}
|
|
420
|
+
Team Size: [8] {ex:teamSize ^^xsd:integer}
|
|
421
|
+
Manages: [QATeam] {ex:manages}
|
|
422
|
+
|
|
423
|
+
### Junior Developer {=ex:JuniorDeveloper}
|
|
424
|
+
Level: [1] {ex:level ^^xsd:integer}
|
|
425
|
+
Team Size: [0] {ex:teamSize ^^xsd:integer}
|
|
426
|
+
|
|
427
|
+
### Finance Approver {=ex:FinanceApprover}
|
|
428
|
+
Authority: [1] {ex:authority ^^xsd:integer}
|
|
429
|
+
Approves: [ExpenseReport] {ex:approves}
|
|
430
|
+
|
|
431
|
+
### Executive Approver {=ex:ExecutiveApprover}
|
|
432
|
+
Authority: [3] {ex:authority ^^xsd:integer}
|
|
433
|
+
Approves: [BudgetRequest] {ex:approves}
|
|
434
|
+
|
|
435
|
+
### Regular Employee {=ex:RegularEmployee}
|
|
436
|
+
Authority: [0] {ex:authority ^^xsd:integer}
|
|
437
|
+
~~~~~~
|
|
438
|
+
|
|
439
|
+
**Expected Result:** 3 violations (EngineeringManager fails twice: level < 3 AND teamSize > 10; FinanceApprover fails: authority < 2; JuniorDeveloper and RegularEmployee not validated as they don't initiate the relationships)
|
|
440
|
+
|
|
441
|
+
---
|
|
442
|
+
|
|
443
|
+
## 📝 MDLD Syntax Patterns
|
|
444
|
+
|
|
445
|
+
Target subjects of targets all subjects that have a specific property pointing to any value.
|
|
446
|
+
|
|
447
|
+
~~~~~~md
|
|
448
|
+
**[Shape] targets subjects of [Property]** {=ex:ShapeName .sh:NodeShape label}
|
|
449
|
+
|
|
450
|
+
[Shape Name] {=ex:ShapeName .sh:NodeShape label} targets all subjects of [Property] {+ex:property ?sh:targetSubjectsOf} to validate requirements.
|
|
451
|
+
~~~~~~
|
|
452
|
+
|
|
453
|
+
**Key components:**
|
|
454
|
+
- **Shape declaration** - The shape being defined (`{=ex:ShapeName .sh:NodeShape label}`)
|
|
455
|
+
- **Target property** - The property to target subjects of (`{+ex:property ?sh:targetSubjectsOf}`)
|
|
456
|
+
- **Validation rules** - Property constraints within the shape
|
|
457
|
+
- **Subject-based selection** - Validates entities that initiate relationships
|
|
458
|
+
|
|
459
|
+
**Important notes:**
|
|
460
|
+
- Target subjects of validates entities that initiate relationships
|
|
461
|
+
- Ideal for management, approval, and source validation
|
|
462
|
+
- Works in reverse direction of the property
|
|
463
|
+
- Use for validating relationship sources
|
|
464
|
+
- Combine with other targeting mechanisms for complex scenarios
|
|
465
|
+
|
|
466
|
+
---
|
|
467
|
+
|
|
468
|
+
## 🎯 Use Cases
|
|
469
|
+
|
|
470
|
+
- **Management validation** - Validate managers who manage teams
|
|
471
|
+
- **Approval validation** - Validate approvers who approve requests
|
|
472
|
+
- **Source validation** - Validate entities that initiate relationships
|
|
473
|
+
- **Reverse relationship targeting** - Target based on outgoing relationships
|
|
474
|
+
- **Business rules** - Enforce rules on relationship initiators
|
|
475
|
+
|
|
476
|
+
---
|
|
477
|
+
|
|
478
|
+
## 🔧 Implementation Guidelines
|
|
479
|
+
|
|
480
|
+
**When to use target subjects of:**
|
|
481
|
+
- **Management validation** - When validating managers or supervisors
|
|
482
|
+
- **Approval validation** - When validating approvers or authorizers
|
|
483
|
+
- **Source validation** - When validating relationship sources
|
|
484
|
+
- **Reverse targeting** - When targeting based on outgoing relationships
|
|
485
|
+
- **Business rules** - When enforcing rules on relationship initiators
|
|
486
|
+
|
|
487
|
+
**Best practices:**
|
|
488
|
+
- Use descriptive property names for clarity
|
|
489
|
+
- Combine with target objects of for bidirectional validation
|
|
490
|
+
- Test with entities that do and don't have the property
|
|
491
|
+
- Document the relationship direction clearly
|
|
492
|
+
- Consider performance for large relationship graphs
|
|
493
|
+
|
|
494
|
+
**Common pitfalls:**
|
|
495
|
+
- ❌ Confusing target subjects of with target objects of
|
|
496
|
+
- ❌ Forgetting that it targets relationship sources, not destinations
|
|
497
|
+
- ❌ Not testing with entities that don't have the property
|
|
498
|
+
- ❌ Not considering the direction of the relationship
|
|
499
|
+
- ❌ Overusing when target class would be more appropriate
|
|
500
|
+
|
|
501
|
+
|
|
502
|
+
|
|
503
|
+
|
|
504
|
+
|
|
505
|
+
|
|
506
|
+
{=}
|
|
507
|
+
|
|
508
|
+
|
|
509
|
+
|
|
510
|
+
<a id="targeting-targetobjectsof"></a>
|
|
511
|
+
|
|
512
|
+
[mdld] <https://mdld.js.org/>
|
|
513
|
+
[cat] <mdld:shacl/>
|
|
514
|
+
[ex] <mdld:shacl/example/targeting/>
|
|
515
|
+
|
|
516
|
+
|
|
517
|
+
# Target Objects Of {=sh:targetObjectsOf .class:TargetingMechanism label}
|
|
518
|
+
|
|
519
|
+
> Targets all objects (values) that are pointed to by a specific property. Ideal for validating referenced entities, relationship targets, and entities that are the destination of relationships. {comment}
|
|
520
|
+
|
|
521
|
+
<http://www.w3.org/ns/shacl#targetObjectsOf> {?cat:fullIRI}
|
|
522
|
+
|
|
523
|
+
---
|
|
524
|
+
|
|
525
|
+
## 📋 Quick Start Pattern
|
|
526
|
+
|
|
527
|
+
The targetObjectsOf constraint targets all objects (nodes) that are referenced by a specific property. This example demonstrates team membership and product reference scenarios where we validate entities that are referenced by others.
|
|
528
|
+
|
|
529
|
+
~~~~~~md
|
|
530
|
+
[ex] <mdld:shacl/example/targeting/>
|
|
531
|
+
|
|
532
|
+
## Team Membership Demo
|
|
533
|
+
|
|
534
|
+
The **Team Member Validation Shape** {=ex:TeamMemberValidationShape .sh:NodeShape label} targets all [team members] {+ex:memberOf ?sh:targetObjectsOf} to validate team membership requirements: [workload] {+#workloadRule ?sh:property sh:name} and [status] {+#activeStatus ?sh:property sh:name}.
|
|
535
|
+
|
|
536
|
+
**Team members must not exceed 40 hours workload** {=#workloadRule .sh:PropertyShape sh:message} requires the [workload] {+ex:workload ?sh:path} property to be at most [40] {sh:maxInclusive ^^xsd:integer}.
|
|
537
|
+
|
|
538
|
+
**Team members must be active** {=#activeStatus .sh:PropertyShape sh:message} that requires the [status] {+ex:status ?sh:path} property to be exactly [active] {sh:hasValue}.
|
|
539
|
+
|
|
540
|
+
## Product Reference Demo
|
|
541
|
+
|
|
542
|
+
**Referenced Product Validation Shape** {=ex:ReferencedProductValidationShape .sh:NodeShape label} targets all [referenced products] {+ex:references ?sh:targetObjectsOf} to validate product reference requirements: [availability] {+#productAvailability ?sh:property sh:name} and [price] {+#productPrice ?sh:property sh:name}.
|
|
543
|
+
|
|
544
|
+
**Referenced products must be available** {=#productAvailability .sh:PropertyShape sh:message} requires the [available] {+ex:available ?sh:path} property to be exactly [true] {sh:hasValue}.
|
|
545
|
+
|
|
546
|
+
**Referenced products must cost $1000 or less** {=#productPrice .sh:PropertyShape sh:message} that requires the [price] {+ex:price ?sh:path} property to be at most [1000.00] {sh:maxInclusive ^^xsd:decimal}.
|
|
547
|
+
|
|
548
|
+
---
|
|
549
|
+
|
|
550
|
+
## Test Data {=ex:data .Container}
|
|
551
|
+
|
|
552
|
+
### EngineeringTeam {=ex:EngineeringTeam}
|
|
553
|
+
Workload: [45] {ex:workload ^^xsd:integer}
|
|
554
|
+
Status: [inactive] {ex:status}
|
|
555
|
+
|
|
556
|
+
### QATeam {=ex:QATeam}
|
|
557
|
+
Workload: [35] {ex:workload ^^xsd:integer}
|
|
558
|
+
Status: [active] {ex:status}
|
|
559
|
+
|
|
560
|
+
### Senior Developer {=ex:SeniorDeveloper}
|
|
561
|
+
Member Of: [Engineering team] {+ex:EngineeringTeam ?ex:memberOf}
|
|
562
|
+
|
|
563
|
+
### Junior Developer {=ex:JuniorDeveloper}
|
|
564
|
+
Member Of: [QATeam] {+ex:QATeam ?ex:memberOf}
|
|
565
|
+
|
|
566
|
+
### Expensive Product {=ex:ExpensiveProduct}
|
|
567
|
+
Price: [1500.00] {ex:price ^^xsd:decimal}
|
|
568
|
+
Available: [false] {ex:available}
|
|
569
|
+
|
|
570
|
+
### Affordable Product {=ex:AffordableProduct}
|
|
571
|
+
Price: [299.99] {ex:price ^^xsd:decimal}
|
|
572
|
+
Available: [true] {ex:available}
|
|
573
|
+
|
|
574
|
+
### Order123 {=ex:Order123}
|
|
575
|
+
References: [Expensive product] {+ex:ExpensiveProduct ?ex:references}
|
|
576
|
+
|
|
577
|
+
### Order456 {=ex:Order456}
|
|
578
|
+
References: [Affordable product] {+ex:AffordableProduct ?ex:references}
|
|
579
|
+
~~~~~~
|
|
580
|
+
|
|
581
|
+
**Expected Result:** 4 violations (EngineeringTeam fails twice: workload > 40 AND status inactive; ExpensiveProduct fails twice: price > 1000 AND unavailable; QATeam and AffordableProduct pass; developers and orders not validated as they're subjects, not objects)
|
|
582
|
+
|
|
583
|
+
---
|
|
584
|
+
|
|
585
|
+
## 📝 MDLD Syntax Patterns
|
|
586
|
+
|
|
587
|
+
Target objects of targets all objects that are pointed to by a specific property.
|
|
588
|
+
|
|
589
|
+
~~~~~~md
|
|
590
|
+
**[Shape] targets objects of [Property]** {=ex:ShapeName .sh:NodeShape label}
|
|
591
|
+
|
|
592
|
+
[Shape Name] {=ex:ShapeName .sh:NodeShape label} targets all objects of [Property] {+ex:property ?sh:targetObjectsOf} to validate requirements.
|
|
593
|
+
~~~~~~
|
|
594
|
+
|
|
595
|
+
**Key components:**
|
|
596
|
+
- **Shape declaration** - The shape being defined (`{=ex:ShapeName .sh:NodeShape label}`)
|
|
597
|
+
- **Target property** - The property to target objects of (`{+ex:property ?sh:targetObjectsOf}`)
|
|
598
|
+
- **Validation rules** - Property constraints within the shape
|
|
599
|
+
- **Object-based selection** - Validates entities that are referenced by others
|
|
600
|
+
|
|
601
|
+
**Important notes:**
|
|
602
|
+
- Target objects of validates entities that are referenced by others
|
|
603
|
+
- Ideal for team membership, product references, and destination validation
|
|
604
|
+
- Works in forward direction of the property
|
|
605
|
+
- Use for validating relationship destinations
|
|
606
|
+
- Combine with other targeting mechanisms for complex scenarios
|
|
607
|
+
|
|
608
|
+
---
|
|
609
|
+
|
|
610
|
+
## 🎯 Use Cases
|
|
611
|
+
|
|
612
|
+
- **Team membership validation** - Validate team members referenced by teams
|
|
613
|
+
- **Product reference validation** - Validate products referenced by orders
|
|
614
|
+
- **Destination validation** - Validate entities that are relationship targets
|
|
615
|
+
- **Referenced entity validation** - Validate entities referenced by others
|
|
616
|
+
- **Business rules** - Enforce rules on relationship destinations
|
|
617
|
+
|
|
618
|
+
---
|
|
619
|
+
|
|
620
|
+
## 🔧 Implementation Guidelines
|
|
621
|
+
|
|
622
|
+
**When to use target objects of:**
|
|
623
|
+
- **Team membership** - When validating team members
|
|
624
|
+
- **Product references** - When validating referenced products
|
|
625
|
+
- **Destination validation** - When validating relationship targets
|
|
626
|
+
- **Referenced entities** - When validating entities referenced by others
|
|
627
|
+
- **Business rules** - When enforcing rules on relationship destinations
|
|
628
|
+
|
|
629
|
+
**Best practices:**
|
|
630
|
+
- Use descriptive property names for clarity
|
|
631
|
+
- Combine with target subjects of for bidirectional validation
|
|
632
|
+
- Test with entities that do and don't have the property
|
|
633
|
+
- Document the relationship direction clearly
|
|
634
|
+
- Consider performance for large relationship graphs
|
|
635
|
+
|
|
636
|
+
**Common pitfalls:**
|
|
637
|
+
- ❌ Confusing target objects of with target subjects of
|
|
638
|
+
- ❌ Forgetting that it targets relationship destinations, not sources
|
|
639
|
+
- ❌ Not testing with entities that don't have the property
|
|
640
|
+
- ❌ Not considering the direction of the relationship
|
|
641
|
+
- ❌ Overusing when target class would be more appropriate
|
|
642
|
+
|
|
643
|
+
|
|
644
|
+
|
|
645
|
+
|
|
646
|
+
|
|
647
|
+
|
|
648
|
+
{=}
|
|
649
|
+
|
|
650
|
+
|
|
651
|
+
|
|
652
|
+
<a id="syntax-reference"></a>
|
|
653
|
+
|
|
654
|
+
## 📝 MDLD Syntax Reference
|
|
655
|
+
|
|
656
|
+
**Authors should refer to MDLD Spec and few-shot examples for complete syntax documentation. Key patterns:**
|
|
657
|
+
|
|
658
|
+
| Symbol | Meaning | Example |
|
|
659
|
+
|--------|---------|---------|
|
|
660
|
+
| `{=}` | Subject declaration (persists) | `{=ex:shape .sh:NodeShape}` |
|
|
661
|
+
| `{+}` | Object introduction (temporary for ?/! predicates) | `{+ex:target ?sh:targetClass}` |
|
|
662
|
+
| `?` | Object predicate (Subject → Object) | `?sh:targetClass`, `?sh:targetNode` |
|
|
663
|
+
| `!` | Reverse predicate (Object → Subject) | `!member` |
|
|
664
|
+
| `.` | Class type declaration | `.sh:NodeShape` |
|
|
665
|
+
| `^^` | Literal datatype | `^^xsd:integer` |
|
|
666
|
+
| `{}` | Subject reset (clears current subject) | `{=}` |
|
|
667
|
+
|
|
668
|
+
**Test data pattern:**
|
|
669
|
+
~~~~~~md
|
|
670
|
+
[Label] {+ex:instanceID ?ex:propertyName .ex:ClassName}
|
|
671
|
+
~~~~~~
|
|
672
|
+
|
|
673
|
+
**For detailed syntax, see:**
|
|
674
|
+
- MDLD Spec: `/Users/davay/Documents/DeFUCC/MDLD/mdld-parse/spec/Spec.md`
|
|
675
|
+
- Few-shot examples: `/Users/davay/Documents/DeFUCC/MDLD/mdld-parse/examples/few-shot.md`
|
|
676
|
+
|
|
677
|
+
|
|
678
|
+
|
|
679
|
+
|
|
680
|
+
|
|
681
|
+
|
|
682
|
+
{=}
|
|
683
|
+
|
|
684
|
+
|
|
685
|
+
|
|
686
|
+
<a id="constraints-index"></a>
|
|
687
|
+
|
|
688
|
+
[mdld] <https://mdld.js.org/>
|
|
689
|
+
[cat] <mdld:shacl/>
|
|
690
|
+
[class] <cat:class/>
|
|
691
|
+
|
|
692
|
+
### 📋 Constraint {=class:Constraint ?member .Class label}
|
|
693
|
+
|
|
694
|
+
> A SHACL constraint is a rule that defines a validation condition for a specific shape and target node. {comment}
|
|
695
|
+
|
|
696
|
+
We can broadly divide them into these type groups:
|
|
697
|
+
- Metadata Predicate {+class:MetadataPredicate !subClassOf label}
|
|
698
|
+
- Targeting Predicate {+class:TargetingPredicate !subClassOf label}
|
|
699
|
+
- Value Type Constraint {+class:ValueTypeConstraint !subClassOf label}
|
|
700
|
+
- Cardinality Constraint {+class:CardinalityConstraint !subClassOf label}
|
|
701
|
+
- String-based Constraint {+class:StringConstraint !subClassOf label}
|
|
702
|
+
- Property Pair Constraint {+class:PropertyPairConstraint !subClassOf label}
|
|
703
|
+
- Logical Constraint {+class:LogicalConstraint !subClassOf label}
|
|
704
|
+
- Shape-based Constraint {+class:ShapeConstraint !subClassOf label}
|
|
705
|
+
- Property Path {+class:PropertyPath !subClassOf label}
|
|
706
|
+
- JavaScript Constraint {+class:JSConstraint !subClassOf label}
|
|
707
|
+
- SPARQL Constraint {+class:SPARQLConstraint !subClassOf label}
|
|
708
|
+
|
|
709
|
+
---
|
|
710
|
+
|
|
711
|
+
[Syntax Reference](#syntax-reference)
|
|
712
|
+
|
|
713
|
+
---
|
|
714
|
+
|
|
715
|
+
# Catalog {=cat:index}
|
|
716
|
+
|
|
717
|
+
This catalog includes these constraints:
|
|
718
|
+
|
|
719
|
+
## Value Type Constraints
|
|
720
|
+
|
|
721
|
+
- [Class](#constraints-class) {+sh:class ?cat:includes .class:ValueTypeConstraint}
|
|
722
|
+
- [Data Type](#constraints-datatype) {+sh:datatype ?cat:includes .class:ValueTypeConstraint}
|
|
723
|
+
- [Node Kind](#constraints-nodekind) {+sh:nodeKind ?cat:includes .class:ValueTypeConstraint}
|
|
724
|
+
|
|
725
|
+
## Cardinality Constraints
|
|
726
|
+
|
|
727
|
+
- [Min Count](#constraints-count) {+sh:minCount ?cat:includes .class:CardinalityConstraint}
|
|
728
|
+
- [Max Count](#constraints-count) {+sh:maxCount ?cat:includes .class:CardinalityConstraint}
|
|
729
|
+
|
|
730
|
+
## Value Range Constraints
|
|
731
|
+
|
|
732
|
+
- [Min Inclusive](#constraints-range) {+sh:minInclusive ?cat:includes .class:ValueRangeConstraint}
|
|
733
|
+
- [Max Inclusive](#constraints-range) {+sh:maxInclusive ?cat:includes .class:ValueRangeConstraint}
|
|
734
|
+
- [Min Exclusive](#constraints-range) {+sh:minExclusive ?cat:includes .class:ValueRangeConstraint}
|
|
735
|
+
- [Max Exclusive](#constraints-range) {+sh:maxExclusive ?cat:includes .class:ValueRangeConstraint}
|
|
736
|
+
|
|
737
|
+
## Property Pair Constraints
|
|
738
|
+
|
|
739
|
+
- [Equals](#constraints-comparison) {+sh:equals ?cat:includes .class:PropertyPairConstraint}
|
|
740
|
+
- [Disjoint](#constraints-disjoint) {+sh:disjoint ?cat:includes .class:PropertyPairConstraint}
|
|
741
|
+
- [Less Than](#constraints-comparison) {+sh:lessThan ?cat:includes .class:PropertyPairConstraint}
|
|
742
|
+
- [Less Than or Equals](#constraints-comparison) {+sh:lessThanOrEquals ?cat:includes .class:PropertyPairConstraint}
|
|
743
|
+
|
|
744
|
+
## Logical Constraints
|
|
745
|
+
|
|
746
|
+
- [NOT](#constraints-not) {+sh:not ?cat:includes .class:LogicalConstraint}
|
|
747
|
+
- [AND](#constraints-and) {+sh:and ?cat:includes .class:LogicalConstraint}
|
|
748
|
+
- [OR](#constraints-or) {+sh:or ?cat:includes .class:LogicalConstraint}
|
|
749
|
+
- [XONE](#constraints-xone) {+sh:xone ?cat:includes .class:LogicalConstraint}
|
|
750
|
+
|
|
751
|
+
## String Constraints
|
|
752
|
+
|
|
753
|
+
- [Minimum Length](#constraints-length) {+sh:minLength ?cat:includes .class:StringConstraint}
|
|
754
|
+
- [Maximum Length](#constraints-length) {+sh:maxLength ?cat:includes .class:StringConstraint}
|
|
755
|
+
- [Pattern](#constraints-pattern) {+sh:pattern ?cat:includes .class:StringConstraint}
|
|
756
|
+
- [Pattern Flags](#constraints-pattern) {+sh:flags ?cat:includes .class:StringConstraint}
|
|
757
|
+
- [Language In](#constraints-language) {+sh:languageIn ?cat:includes .class:StringConstraint}
|
|
758
|
+
- [Unique Languages](#constraints-uniquelang) {+sh:uniqueLang ?cat:includes .class:StringConstraint}
|
|
759
|
+
|
|
760
|
+
## Other Constraints
|
|
761
|
+
|
|
762
|
+
- [Has Value](#constraints-hasvalue) {+sh:hasValue ?cat:includes}
|
|
763
|
+
- [Entity type](#constraints-node) {+sh:node ?cat:includes .class:ShapeConstraint}
|
|
764
|
+
- [Value enumeration](#constraints-in) {+sh:in ?cat:includes}
|
|
765
|
+
- [Qualified Min Count](#constraints-qualifiedcount) {+sh:qualifiedMinCount ?cat:includes}
|
|
766
|
+
- [Qualified Max Count](#constraints-qualifiedcount) {+sh:qualifiedMaxCount ?cat:includes}
|
|
767
|
+
- [Closed world](#constraints-closed) {+sh:closed ?cat:includes .class:MetadataPredicate}
|
|
768
|
+
- [Deactivation flag](#constraints-deactivated) {+sh:deactivated ?cat:includes .class:MetadataPredicate}
|
|
769
|
+
- [Severity levels](#constraints-severity) {+sh:severity ?cat:includes .class:MetadataPredicate}
|
|
770
|
+
- [Violation message](#constraints-message) {+sh:message ?cat:includes .class:MetadataPredicate}
|
|
771
|
+
|
|
772
|
+
Some parts are still completely uncovered and don't work even on ttl or pure quads - something might be wrong in the validator or in examples we use in tests, need deeper investigation:
|
|
773
|
+
|
|
774
|
+
- Ignored Properties {+sh:ignoredProperties ?cat:includes .class:MetadataPredicate .cat:notCovered}
|
|
775
|
+
|
|
776
|
+
## JavaScript Constraints
|
|
777
|
+
|
|
778
|
+
- [JavaScript Function](#constraints-js) {+sh:js ?cat:includes .class:JSConstraint}
|
|
779
|
+
- JS Function Name {+sh:jsFunctionName ?cat:includes .class:JSConstraint .cat:notCovered}
|
|
780
|
+
- JS Library {+sh:jsLibrary ?cat:includes .class:JSConstraint .cat:notCovered}
|
|
781
|
+
- JS Library URL {+sh:jsLibraryURL ?cat:includes .class:JSConstraint .cat:notCovered}
|
|
782
|
+
|
|
783
|
+
## SPARQL Constraints
|
|
784
|
+
|
|
785
|
+
- SPARQL ASK Query {+sh:ask ?cat:includes .class:SPARQLConstraint .cat:notCovered}
|
|
786
|
+
- SPARQL SELECT Query {+sh:select ?cat:includes .class:SPARQLConstraint .cat:notCovered}
|
|
787
|
+
- SPARQL CONSTRUCT Query {+sh:construct ?cat:includes .class:SPARQLConstraint .cat:notCovered}
|
|
788
|
+
- SPARQL UPDATE Query {+sh:update ?cat:includes .class:SPARQLConstraint .cat:notCovered}
|
|
789
|
+
|
|
790
|
+
|
|
791
|
+
|
|
792
|
+
## Property Path Constraints
|
|
793
|
+
|
|
794
|
+
Need to check if these are working:
|
|
795
|
+
|
|
796
|
+
- Qualified Value Shape {+sh:qualifiedValueShape ?cat:includes .class:ShapeConstraint .cat:notCovered}
|
|
797
|
+
- Qualified Value Shapes Disjoint {+sh:qualifiedValueShapesDisjoint ?cat:includes .class:ShapeConstraint .cat:notCovered}
|
|
798
|
+
- Inverse Path {+sh:inversePath ?cat:includes .class:PropertyPath .cat:notCovered}
|
|
799
|
+
- Alternative Path {+sh:alternativePath ?cat:includes .class:PropertyPath .cat:notCovered}
|
|
800
|
+
- Zero or More Path {+sh:zeroOrMorePath ?cat:includes .class:PropertyPath .cat:notCovered}
|
|
801
|
+
- One or More Path {+sh:oneOrMorePath ?cat:includes .class:PropertyPath .cat:notCovered}
|
|
802
|
+
- Zero or One Path {+sh:zeroOrOnePath ?cat:includes .class:PropertyPath .cat:notCovered}
|
|
803
|
+
|
|
804
|
+
---
|
|
805
|
+
|
|
806
|
+
## Some constraints are environment dependent, are not tested to be working and are [Not covered] {=cat:notCovered .Class label} by this calalog.
|
|
807
|
+
|
|
808
|
+
|
|
809
|
+
|
|
810
|
+
|
|
811
|
+
|
|
812
|
+
|
|
813
|
+
{=}
|
|
814
|
+
|
|
815
|
+
|
|
816
|
+
|
|
817
|
+
<a id="constraints-class"></a>
|
|
818
|
+
|
|
819
|
+
[mdld] <https://mdld.js.org/>
|
|
820
|
+
[cat] <mdld:shacl/>
|
|
821
|
+
|
|
822
|
+
# Class {=sh:class .class:Constraint label}
|
|
823
|
+
|
|
824
|
+
> Expects each value to be an instance of a specific class (RDF type) {comment}
|
|
825
|
+
|
|
826
|
+
<http://www.w3.org/ns/shacl#class> {?cat:fullIRI}
|
|
827
|
+
|
|
828
|
+
---
|
|
829
|
+
|
|
830
|
+
## 📋 Quick Start Pattern
|
|
831
|
+
|
|
832
|
+
The class constraint ensures property values are instances of a specific RDF class. This example validates that employee managers must be Person instances.
|
|
833
|
+
|
|
834
|
+
~~~~~~md
|
|
835
|
+
[ex] <tag:my@example.org,2026:class/>
|
|
836
|
+
|
|
837
|
+
## Employee Test Shape {=ex:EmployeeTestShape .sh:NodeShape label}
|
|
838
|
+
|
|
839
|
+
All [employees] {+member ?sh:targetObjectsOf} must have **manager** {+#managerClass ?sh:property sh:name} class assigned.
|
|
840
|
+
|
|
841
|
+
**Manager must be a Person instance** {=#managerClass .sh:PropertyShape sh:message} requires the [manager] {+ex:manager ?sh:path} property to be an instance of a [Person] {+ex:Person ?sh:class}.
|
|
842
|
+
|
|
843
|
+
---
|
|
844
|
+
|
|
845
|
+
## Test Data {=ex:data .Container}
|
|
846
|
+
|
|
847
|
+
### Valid Employee {=ex:ValidEmployee ?member}
|
|
848
|
+
Manager: [john] {+ex:john ?ex:manager .ex:Person}
|
|
849
|
+
|
|
850
|
+
### Invalid Employee {=ex:InvalidEmployee ?member}
|
|
851
|
+
Manager: [robot] {+ex:robot ?ex:manager ex:Role}
|
|
852
|
+
~~~~~~
|
|
853
|
+
|
|
854
|
+
**Expected Result:** 1 violation (InvalidEmployee fails because manager is not a Person)
|
|
855
|
+
|
|
856
|
+
---
|
|
857
|
+
|
|
858
|
+
## 📝 MDLD Syntax Patterns
|
|
859
|
+
|
|
860
|
+
~~~~~~md
|
|
861
|
+
[Property] {+ex:propertyName ?sh:path} must be an instance of [Class] {+ex:Class ?sh:class}
|
|
862
|
+
~~~~~~
|
|
863
|
+
|
|
864
|
+
**Use for:** Type safety, referential integrity, data quality
|
|
865
|
+
|
|
866
|
+
**Important:**
|
|
867
|
+
- Works with IRI values only (use nodeKind for literals)
|
|
868
|
+
- Class must be defined in ontology
|
|
869
|
+
- Combine with minCount for required properties
|
|
870
|
+
|
|
871
|
+
---
|
|
872
|
+
|
|
873
|
+
## 🔧 Implementation Guidelines
|
|
874
|
+
|
|
875
|
+
**When to use:** Ensure property values have correct RDF types
|
|
876
|
+
|
|
877
|
+
**Best practices:**
|
|
878
|
+
- Define classes in ontology first
|
|
879
|
+
- Use descriptive class names
|
|
880
|
+
- Combine with minCount for required properties
|
|
881
|
+
|
|
882
|
+
**Common pitfalls:**
|
|
883
|
+
- ❌ Using on literal values (use nodeKind instead)
|
|
884
|
+
- ❌ Forgetting to define the class
|
|
885
|
+
- ❌ Not combining with minCount for required properties
|
|
886
|
+
|
|
887
|
+
|
|
888
|
+
|
|
889
|
+
|
|
890
|
+
|
|
891
|
+
|
|
892
|
+
{=}
|
|
893
|
+
|
|
894
|
+
|
|
895
|
+
|
|
896
|
+
<a id="constraints-datatype"></a>
|
|
897
|
+
|
|
898
|
+
[mdld] <https://mdld.js.org/>
|
|
899
|
+
[cat] <mdld:shacl/>
|
|
900
|
+
[class] <cat:class/>
|
|
901
|
+
|
|
902
|
+
# Data Type {=sh:datatype .class:Constraint label}
|
|
903
|
+
|
|
904
|
+
> Expects a literal value to have certain datatype {comment}
|
|
905
|
+
|
|
906
|
+
<http://www.w3.org/ns/shacl#datatype> {?cat:fullIRI}
|
|
907
|
+
|
|
908
|
+
---
|
|
909
|
+
|
|
910
|
+
## 📋 Quick Start Pattern
|
|
911
|
+
|
|
912
|
+
The datatype constraint ensures literal values have the correct datatype. This example validates that product prices must be decimal values.
|
|
913
|
+
|
|
914
|
+
~~~~~~md
|
|
915
|
+
[ex] <tag:my@example.org,2026:datatype/>
|
|
916
|
+
|
|
917
|
+
## Product Test Shape {=ex:ProductTestShape .sh:NodeShape sh:name}
|
|
918
|
+
|
|
919
|
+
Validates [Valid Product] {+ex:ValidProduct ?sh:targetNode} and [Invalid Product] {+ex:InvalidProduct ?sh:targetNode} with **price** {+#priceDecimal ?sh:property sh:name}.
|
|
920
|
+
|
|
921
|
+
**Price must be decimal** {=#priceDecimal .sh:PropertyShape sh:message} requires the [price] {+ex:price ?sh:path} property to be a [decimal] {+xsd:decimal ?sh:datatype} value.
|
|
922
|
+
|
|
923
|
+
---
|
|
924
|
+
|
|
925
|
+
## Test Data {=ex:data .Container}
|
|
926
|
+
|
|
927
|
+
### Valid Product {=ex:ValidProduct ?member}
|
|
928
|
+
Price: [29.99] {ex:price ^^xsd:decimal}
|
|
929
|
+
|
|
930
|
+
### Invalid Product {=ex:InvalidProduct ?member}
|
|
931
|
+
Price: [29.99] {ex:price ^^xsd:string}
|
|
932
|
+
~~~~~~
|
|
933
|
+
|
|
934
|
+
**Expected Result:** 1 violation (InvalidProduct fails because price is string, not decimal)
|
|
935
|
+
|
|
936
|
+
---
|
|
937
|
+
|
|
938
|
+
## 📝 MDLD Syntax Patterns
|
|
939
|
+
|
|
940
|
+
~~~~~~md
|
|
941
|
+
[Property] {+ex:propertyName ?sh:path} must be a [Datatype] {+xsd:datatype ?sh:datatype} value.
|
|
942
|
+
~~~~~~
|
|
943
|
+
|
|
944
|
+
**Use for:** Type safety, data quality, calculations
|
|
945
|
+
|
|
946
|
+
**Important:**
|
|
947
|
+
- Works with literal values only (use nodeKind for IRIs)
|
|
948
|
+
- Common datatypes: xsd:string, xsd:integer, xsd:decimal, xsd:boolean, xsd:date
|
|
949
|
+
- Combine with minCount for required properties
|
|
950
|
+
|
|
951
|
+
---
|
|
952
|
+
|
|
953
|
+
## 🔧 Implementation Guidelines
|
|
954
|
+
|
|
955
|
+
**When to use:** Ensure literal values have correct datatypes
|
|
956
|
+
|
|
957
|
+
**Best practices:**
|
|
958
|
+
- Use appropriate datatypes (decimal for money, integer for counts)
|
|
959
|
+
- Combine with minCount for required properties
|
|
960
|
+
|
|
961
|
+
**Common pitfalls:**
|
|
962
|
+
- ❌ Using on IRI values (use nodeKind instead)
|
|
963
|
+
- ❌ Forgetting to specify the datatype prefix
|
|
964
|
+
- ❌ Not combining with minCount for required properties
|
|
965
|
+
|
|
966
|
+
|
|
967
|
+
|
|
968
|
+
|
|
969
|
+
|
|
970
|
+
|
|
971
|
+
{=}
|
|
972
|
+
|
|
973
|
+
|
|
974
|
+
|
|
975
|
+
<a id="constraints-nodekind"></a>
|
|
976
|
+
|
|
977
|
+
[mdld] <https://mdld.js.org/>
|
|
978
|
+
[cat] <mdld:shacl/>
|
|
979
|
+
[class] <cat:class/>
|
|
980
|
+
|
|
981
|
+
# Node Kind {=sh:nodeKind .class:Constraint label}
|
|
982
|
+
|
|
983
|
+
> Expects a node to be of a specific kind (blank node, IRI, or literal) {comment}
|
|
984
|
+
|
|
985
|
+
<http://www.w3.org/ns/shacl#nodeKind> {?cat:fullIRI}
|
|
986
|
+
|
|
987
|
+
---
|
|
988
|
+
|
|
989
|
+
## 📋 Quick Start Pattern
|
|
990
|
+
|
|
991
|
+
The nodeKind constraint expects a node to be of a specific kind (blank node, IRI, or literal). This example validates that content must be literal and references must be IRIs.
|
|
992
|
+
|
|
993
|
+
~~~~~~md
|
|
994
|
+
[ex] <tag:my@example.org,2026:nodekind/>
|
|
995
|
+
|
|
996
|
+
## Document Test Shape {=ex:DocumentTestShape .sh:NodeShape label}
|
|
997
|
+
|
|
998
|
+
Validates [Valid Document] {+ex:ValidDocument ?sh:targetNode} and [Invalid Document] {+ex:InvalidDocument ?sh:targetNode} with literal **content** {+#contentLiteral ?sh:property sh:name} and IRI for **reference** {+#referenceIRI ?sh:property sh:name}.
|
|
999
|
+
|
|
1000
|
+
**Content must be literal** {=#contentLiteral .sh:PropertyShape sh:message} requires [content] {+ex:content ?sh:path} to be a [Literal] {+sh:Literal ?sh:nodeKind}.
|
|
1001
|
+
|
|
1002
|
+
**Reference must be IRI** {=#referenceIRI .sh:PropertyShape sh:message} requires [reference] {+ex:reference ?sh:path} to be an [IRI] {+sh:IRI ?sh:nodeKind}.
|
|
1003
|
+
|
|
1004
|
+
---
|
|
1005
|
+
|
|
1006
|
+
## Test Data {=ex:data .Container}
|
|
1007
|
+
|
|
1008
|
+
### Valid Document {=ex:ValidDocument ?member}
|
|
1009
|
+
Content: [text] {ex:content}
|
|
1010
|
+
Reference: <https://example.org> {?ex:reference}
|
|
1011
|
+
|
|
1012
|
+
### Invalid Document {=ex:InvalidDocument ?member}
|
|
1013
|
+
Content: <https://example.org> {?ex:content}
|
|
1014
|
+
Reference: [text] {ex:reference}
|
|
1015
|
+
~~~~~~
|
|
1016
|
+
|
|
1017
|
+
**Expected Result:** 2 violations (InvalidDocument fails twice: content is IRI not literal, reference is text not IRI)
|
|
1018
|
+
|
|
1019
|
+
---
|
|
1020
|
+
|
|
1021
|
+
## 📝 MDLD Syntax Patterns
|
|
1022
|
+
|
|
1023
|
+
~~~~~~md
|
|
1024
|
+
[Property] {+ex:propertyName ?sh:path} must be a [NodeKind] {+sh:NodeKind ?sh:nodeKind}.
|
|
1025
|
+
~~~~~~
|
|
1026
|
+
|
|
1027
|
+
**Use for:** Type safety, IRI vs literal validation
|
|
1028
|
+
|
|
1029
|
+
**Important:**
|
|
1030
|
+
- MDLD doesn't produce blank nodes (focus on IRI/Literal)
|
|
1031
|
+
- IRI values use `<URL> {?property}` syntax
|
|
1032
|
+
- Literal values use `[text] {property}` syntax
|
|
1033
|
+
- Use datatype constraint for literal types, class for IRI types
|
|
1034
|
+
|
|
1035
|
+
---
|
|
1036
|
+
|
|
1037
|
+
## 🔧 Implementation Guidelines
|
|
1038
|
+
|
|
1039
|
+
**When to use:** Ensure references are IRIs, content is literal
|
|
1040
|
+
|
|
1041
|
+
**Best practices:**
|
|
1042
|
+
- Use correct syntax for IRI vs literal
|
|
1043
|
+
- Combine with datatype for literal types, class for IRI types
|
|
1044
|
+
|
|
1045
|
+
**Common pitfalls:**
|
|
1046
|
+
- ❌ Wrong syntax for IRI vs literal
|
|
1047
|
+
- ❌ Confusing with datatype (nodeKind for IRI/Literal, datatype for literal types)
|
|
1048
|
+
|
|
1049
|
+
|
|
1050
|
+
|
|
1051
|
+
|
|
1052
|
+
|
|
1053
|
+
|
|
1054
|
+
{=}
|
|
1055
|
+
|
|
1056
|
+
|
|
1057
|
+
|
|
1058
|
+
<a id="constraints-count"></a>
|
|
1059
|
+
|
|
1060
|
+
[mdld] <https://mdld.js.org/>
|
|
1061
|
+
[cat] <mdld:shacl/>
|
|
1062
|
+
[class] <cat:class/>
|
|
1063
|
+
|
|
1064
|
+
# Min Count {=sh:minCount .class:Constraint label}
|
|
1065
|
+
|
|
1066
|
+
> Specifies the minimum number of values a property must have {comment}
|
|
1067
|
+
|
|
1068
|
+
<http://www.w3.org/ns/shacl#minCount> {?cat:fullIRI}
|
|
1069
|
+
|
|
1070
|
+
# Max Count {=sh:maxCount .class:Constraint label}
|
|
1071
|
+
|
|
1072
|
+
> Specifies the maximum number of values a property can have {comment}
|
|
1073
|
+
|
|
1074
|
+
<http://www.w3.org/ns/shacl#maxCount> {?cat:fullIRI}
|
|
1075
|
+
|
|
1076
|
+
---
|
|
1077
|
+
|
|
1078
|
+
## 📋 Quick Start Pattern
|
|
1079
|
+
|
|
1080
|
+
Count constraints specify the minimum and maximum number of values a property must have. This example validates that email must be exactly one value.
|
|
1081
|
+
|
|
1082
|
+
~~~~~~md
|
|
1083
|
+
[ex] <tag:my@example.org,2026:count/>
|
|
1084
|
+
|
|
1085
|
+
## Person Test Shape {=ex:PersonTestShape .sh:NodeShape sh:name}
|
|
1086
|
+
|
|
1087
|
+
Validates all [member] {+member ?sh:targetObjectsOf} entities with **email** {+#emailExact ?sh:property sh:name}.
|
|
1088
|
+
|
|
1089
|
+
**Email must be exactly one** {=#emailExact .sh:PropertyShape sh:message} requires [email] {+ex:email ?sh:path} to have exactly [1] {sh:minCount sh:maxCount ^^xsd:integer} value.
|
|
1090
|
+
|
|
1091
|
+
---
|
|
1092
|
+
|
|
1093
|
+
## Test Data {=ex:data .Container}
|
|
1094
|
+
|
|
1095
|
+
### Valid Person {=ex:ValidPerson ?member}
|
|
1096
|
+
Email: [work@example.com] {ex:email}
|
|
1097
|
+
|
|
1098
|
+
### Invalid Person {=ex:InvalidPerson ?member}
|
|
1099
|
+
Email: [work@example.com] {ex:email}
|
|
1100
|
+
Email: [personal@example.com] {ex:email}
|
|
1101
|
+
~~~~~~
|
|
1102
|
+
|
|
1103
|
+
**Expected Result:** 1 violation (InvalidPerson fails because it has two emails instead of one)
|
|
1104
|
+
|
|
1105
|
+
---
|
|
1106
|
+
|
|
1107
|
+
## 📝 MDLD Syntax Patterns
|
|
1108
|
+
|
|
1109
|
+
~~~~~~md
|
|
1110
|
+
[Property] {+ex:propertyName ?sh:path} must have at least [min] {sh:minCount ^^xsd:integer} and at most [max] {sh:maxCount ^^xsd:integer} values.
|
|
1111
|
+
~~~~~~
|
|
1112
|
+
|
|
1113
|
+
**Use for:** Required properties, single-valued properties, multi-valued limits
|
|
1114
|
+
|
|
1115
|
+
**Important:**
|
|
1116
|
+
- Use minCount alone for "at least X values"
|
|
1117
|
+
- Use maxCount alone for "at most X values"
|
|
1118
|
+
- Use both with same value for "exactly X values"
|
|
1119
|
+
- Empty properties fail minCount validation
|
|
1120
|
+
|
|
1121
|
+
---
|
|
1122
|
+
|
|
1123
|
+
## 🔧 Implementation Guidelines
|
|
1124
|
+
|
|
1125
|
+
**When to use:** Ensure property has correct number of values
|
|
1126
|
+
|
|
1127
|
+
**Best practices:**
|
|
1128
|
+
- Use minCount: 1 for required properties
|
|
1129
|
+
- Use both minCount and maxCount: 1 for single-valued properties
|
|
1130
|
+
|
|
1131
|
+
**Common pitfalls:**
|
|
1132
|
+
- ❌ Forgetting to specify the datatype ^^xsd:integer
|
|
1133
|
+
- ❌ Using negative values for counts
|
|
1134
|
+
- ❌ Confusing minCount with maxCount
|
|
1135
|
+
|
|
1136
|
+
|
|
1137
|
+
|
|
1138
|
+
|
|
1139
|
+
|
|
1140
|
+
|
|
1141
|
+
{=}
|
|
1142
|
+
|
|
1143
|
+
|
|
1144
|
+
|
|
1145
|
+
<a id="constraints-range"></a>
|
|
1146
|
+
|
|
1147
|
+
[mdld] <https://mdld.js.org/>
|
|
1148
|
+
[cat] <mdld:shacl/>
|
|
1149
|
+
|
|
1150
|
+
# Minimum Inclusive {=sh:minInclusive .class:Constraint label}
|
|
1151
|
+
|
|
1152
|
+
> Specifies the minimum inclusive value for range constraints {comment}
|
|
1153
|
+
|
|
1154
|
+
<http://www.w3.org/ns/shacl#minInclusive> {?cat:fullIRI}
|
|
1155
|
+
|
|
1156
|
+
# Maximum Inclusive {=sh:maxInclusive .class:Constraint label}
|
|
1157
|
+
|
|
1158
|
+
> Specifies the maximum inclusive value for range constraints {comment}
|
|
1159
|
+
|
|
1160
|
+
<http://www.w3.org/ns/shacl#maxInclusive> {?cat:fullIRI}
|
|
1161
|
+
|
|
1162
|
+
# Minimum Exclusive {=sh:minExclusive .class:Constraint label}
|
|
1163
|
+
|
|
1164
|
+
> Specifies the minimum exclusive value for range constraints {comment}
|
|
1165
|
+
|
|
1166
|
+
<http://www.w3.org/ns/shacl#minExclusive> {?cat:fullIRI}
|
|
1167
|
+
|
|
1168
|
+
# Maximum Exclusive {=sh:maxExclusive .class:Constraint label}
|
|
1169
|
+
|
|
1170
|
+
> Specifies the maximum exclusive value for range constraints {comment}
|
|
1171
|
+
|
|
1172
|
+
<http://www.w3.org/ns/shacl#maxExclusive> {?cat:fullIRI}
|
|
1173
|
+
|
|
1174
|
+
---
|
|
1175
|
+
|
|
1176
|
+
## 📋 Quick Start Pattern
|
|
1177
|
+
|
|
1178
|
+
Range constraints specify minimum and maximum values for numeric or date properties. This example validates that product prices must be between 10 and 100 inclusive.
|
|
1179
|
+
|
|
1180
|
+
~~~~~~md
|
|
1181
|
+
[ex] <tag:my@example.org,2026:range/>
|
|
1182
|
+
|
|
1183
|
+
## Product Test Shape {=ex:ProductTestShape .sh:NodeShape label}
|
|
1184
|
+
|
|
1185
|
+
Validates all [member] {+member ?sh:targetObjectsOf} entities with conforming **price** {+#priceRange ?sh:property}.
|
|
1186
|
+
|
|
1187
|
+
**Price must be between 10 and 100 inclusive** {=#priceRange .sh:PropertyShape sh:message} requires [price] {+ex:price ?sh:path} to be at least [10] {sh:minInclusive ^^xsd:decimal} and at most [100] {sh:maxInclusive ^^xsd:decimal}.
|
|
1188
|
+
|
|
1189
|
+
---
|
|
1190
|
+
|
|
1191
|
+
## Test Data {=ex:data .Container}
|
|
1192
|
+
|
|
1193
|
+
### Valid Product {=ex:ValidProduct ?member}
|
|
1194
|
+
Price: [50] {ex:price ^^xsd:decimal}
|
|
1195
|
+
|
|
1196
|
+
### Invalid Product {=ex:InvalidProduct ?member}
|
|
1197
|
+
Price: [5] {ex:price ^^xsd:decimal}
|
|
1198
|
+
~~~~~~
|
|
1199
|
+
|
|
1200
|
+
**Expected Result:** 1 violation (InvalidProduct fails because price is 5, below the minimum of 10)
|
|
1201
|
+
|
|
1202
|
+
---
|
|
1203
|
+
|
|
1204
|
+
## 📝 MDLD Syntax Patterns
|
|
1205
|
+
|
|
1206
|
+
~~~~~~md
|
|
1207
|
+
[Property] {+ex:propertyName ?sh:path} must be at least [min] {sh:minInclusive ^^xsd:datatype} and at most [max] {sh:maxInclusive ^^xsd:datatype}.
|
|
1208
|
+
~~~~~~
|
|
1209
|
+
|
|
1210
|
+
**Use for:** Price validation, age restrictions, date validation, numeric ranges
|
|
1211
|
+
|
|
1212
|
+
**Important:**
|
|
1213
|
+
- Works with ordered datatypes (numbers, dates, times)
|
|
1214
|
+
- Inclusive bounds include boundary values
|
|
1215
|
+
- Exclusive bounds exclude boundary values
|
|
1216
|
+
- Use minInclusive for "at least X", maxInclusive for "at most X"
|
|
1217
|
+
|
|
1218
|
+
---
|
|
1219
|
+
|
|
1220
|
+
## 🔧 Implementation Guidelines
|
|
1221
|
+
|
|
1222
|
+
**When to use:** Values must be within numeric or date bounds
|
|
1223
|
+
|
|
1224
|
+
**Best practices:**
|
|
1225
|
+
- Use inclusive bounds for "at least/at most"
|
|
1226
|
+
- Use exclusive bounds for "greater than/less than"
|
|
1227
|
+
- Test with boundary values
|
|
1228
|
+
|
|
1229
|
+
**Common pitfalls:**
|
|
1230
|
+
- ❌ Using wrong inclusive/exclusive bound
|
|
1231
|
+
- ❌ Forgetting to specify the datatype
|
|
1232
|
+
- ❌ Confusing inclusive with exclusive bounds
|
|
1233
|
+
|
|
1234
|
+
|
|
1235
|
+
|
|
1236
|
+
|
|
1237
|
+
|
|
1238
|
+
|
|
1239
|
+
{=}
|
|
1240
|
+
|
|
1241
|
+
|
|
1242
|
+
|
|
1243
|
+
<a id="constraints-comparison"></a>
|
|
1244
|
+
|
|
1245
|
+
[mdld] <https://mdld.js.org/>
|
|
1246
|
+
[cat] <mdld:shacl/>
|
|
1247
|
+
|
|
1248
|
+
# Comparison Constraints {=sh:lessThan .class:ComparisonConstraint label}
|
|
1249
|
+
|
|
1250
|
+
> Validates property values against reference nodes using comparison operators {comment}
|
|
1251
|
+
|
|
1252
|
+
<http://www.w3.org/ns/shacl#lessThan> {?cat:fullIRI}
|
|
1253
|
+
<http://www.w3.org/ns/shacl#lessThanOrEquals> {?cat:fullIRI}
|
|
1254
|
+
<http://www.w3.org/ns/shacl#equals> {?cat:fullIRI}
|
|
1255
|
+
|
|
1256
|
+
---
|
|
1257
|
+
|
|
1258
|
+
## 📋 Quick Start Pattern
|
|
1259
|
+
|
|
1260
|
+
Comparison constraints validate property values against reference nodes using comparison operators. This example validates that order dates must be before shipping dates.
|
|
1261
|
+
|
|
1262
|
+
~~~~~~md
|
|
1263
|
+
[ex] <tag:my@example.org,2026:comparison/>
|
|
1264
|
+
|
|
1265
|
+
## Order Test Shape {=ex:OrderTestShape .sh:NodeShape label}
|
|
1266
|
+
|
|
1267
|
+
Validates all [member] {+member ?sh:targetObjectsOf} entities with **order date before shipping date** {+#orderDateRule ?sh:property sh:name}.
|
|
1268
|
+
|
|
1269
|
+
**Order date must be before shipping date** {=#orderDateRule .sh:PropertyShape sh:message} requires [order date] {+ex:orderDate ?sh:path} to be before [shipping date] {+ex:shippingDate ?sh:lessThan}.
|
|
1270
|
+
|
|
1271
|
+
---
|
|
1272
|
+
|
|
1273
|
+
## Test Data {=ex:data .Container}
|
|
1274
|
+
|
|
1275
|
+
### Valid Order {=ex:ValidOrder ?member}
|
|
1276
|
+
Order Date: [2024-06-15] {ex:orderDate ^^xsd:date}
|
|
1277
|
+
Shipping Date: [2024-06-20] {ex:shippingDate ^^xsd:date}
|
|
1278
|
+
|
|
1279
|
+
### Invalid Order {=ex:InvalidOrder ?member}
|
|
1280
|
+
Order Date: [2024-06-25] {ex:orderDate ^^xsd:date}
|
|
1281
|
+
Shipping Date: [2024-06-20] {ex:shippingDate ^^xsd:date}
|
|
1282
|
+
~~~~~~
|
|
1283
|
+
|
|
1284
|
+
**Expected Result:** 1 violation (InvalidOrder fails because order date is after shipping date)
|
|
1285
|
+
|
|
1286
|
+
---
|
|
1287
|
+
|
|
1288
|
+
## 📝 MDLD Syntax Patterns
|
|
1289
|
+
|
|
1290
|
+
~~~~~~md
|
|
1291
|
+
[Property] {+ex:propertyName ?sh:path} must be [operator] {sh:lessThan} [Reference] {+ex:reference ?sh:lessThan}.
|
|
1292
|
+
~~~~~~
|
|
1293
|
+
|
|
1294
|
+
**Use for:** Date validation, version control, business rules, ordering constraints
|
|
1295
|
+
|
|
1296
|
+
**Important:**
|
|
1297
|
+
- Works with comparable values (dates, numbers, strings)
|
|
1298
|
+
- Compares values within the same node
|
|
1299
|
+
- Use lessThan for strict ordering, lessThanOrEquals for inclusive, equals for exact matching
|
|
1300
|
+
- Both properties must be present
|
|
1301
|
+
|
|
1302
|
+
---
|
|
1303
|
+
|
|
1304
|
+
## 🔧 Implementation Guidelines
|
|
1305
|
+
|
|
1306
|
+
**When to use:** Enforce ordering constraints between properties
|
|
1307
|
+
|
|
1308
|
+
**Best practices:**
|
|
1309
|
+
- Ensure compatible datatypes
|
|
1310
|
+
- Test with boundary values
|
|
1311
|
+
|
|
1312
|
+
**Common pitfalls:**
|
|
1313
|
+
- ❌ Comparing incompatible datatypes
|
|
1314
|
+
- ❌ Forgetting both properties must be present
|
|
1315
|
+
- ❌ Using wrong comparison operator
|
|
1316
|
+
|
|
1317
|
+
|
|
1318
|
+
|
|
1319
|
+
|
|
1320
|
+
|
|
1321
|
+
|
|
1322
|
+
{=}
|
|
1323
|
+
|
|
1324
|
+
|
|
1325
|
+
|
|
1326
|
+
<a id="constraints-disjoint"></a>
|
|
1327
|
+
|
|
1328
|
+
[mdld] <https://mdld.js.org/>
|
|
1329
|
+
[cat] <mdld:shacl/>
|
|
1330
|
+
|
|
1331
|
+
# Disjoint {=sh:disjoint .class:DisjointConstraint label}
|
|
1332
|
+
|
|
1333
|
+
> Ensures that values of a property are disjoint with values of another property {comment}
|
|
1334
|
+
|
|
1335
|
+
<http://www.w3.org/ns/shacl#disjoint> {?cat:fullIRI}
|
|
1336
|
+
|
|
1337
|
+
---
|
|
1338
|
+
|
|
1339
|
+
## 📋 Quick Start Pattern
|
|
1340
|
+
|
|
1341
|
+
The disjoint constraint ensures that values of a property are disjoint with values of another property. This example validates that preferred labels must be different from alternative labels.
|
|
1342
|
+
|
|
1343
|
+
~~~~~~md
|
|
1344
|
+
[ex] <tag:my@example.org,2026:disjoint/>
|
|
1345
|
+
|
|
1346
|
+
## Label Test Shape {=ex:DisjointExampleShape .sh:NodeShape label}
|
|
1347
|
+
|
|
1348
|
+
Validates all [member] {+member ?sh:targetObjectsOf} entities with **disjoint labels** {+#disjointRule ?sh:property sh:name}.
|
|
1349
|
+
|
|
1350
|
+
**Preferred labels must be different from alternative labels** {=#disjointRule .sh:PropertyShape sh:message} requires [preferred labels] {+ex:prefLabel ?sh:path} to be disjoint with [alternative labels] {+ex:altLabel ?sh:disjoint}.
|
|
1351
|
+
|
|
1352
|
+
---
|
|
1353
|
+
|
|
1354
|
+
## Test Data {=ex:data .Container}
|
|
1355
|
+
|
|
1356
|
+
### Valid Case {=ex:USA ?member}
|
|
1357
|
+
Preferred Label: [USA] {ex:prefLabel}
|
|
1358
|
+
Alternative Label: [United States] {ex:altLabel}
|
|
1359
|
+
|
|
1360
|
+
### Invalid Case {=ex:Germany ?member}
|
|
1361
|
+
Preferred Label: [Germany] {ex:prefLabel}
|
|
1362
|
+
Alternative Label: [Germany] {ex:altLabel}
|
|
1363
|
+
~~~~~~
|
|
1364
|
+
|
|
1365
|
+
**Expected Result:** 1 violation (Germany fails because preferred and alternative labels are the same)
|
|
1366
|
+
|
|
1367
|
+
---
|
|
1368
|
+
|
|
1369
|
+
## 📝 MDLD Syntax Patterns
|
|
1370
|
+
|
|
1371
|
+
~~~~~~md
|
|
1372
|
+
[Property] {+ex:propertyName ?sh:path} must be [disjoint] {+ex:otherProperty ?sh:disjoint} with [Other Property].
|
|
1373
|
+
~~~~~~
|
|
1374
|
+
|
|
1375
|
+
**Use for:** Label validation, category separation, mutually exclusive attributes
|
|
1376
|
+
|
|
1377
|
+
**Important:**
|
|
1378
|
+
- Prevents any value from appearing in both properties
|
|
1379
|
+
- Works with both literal values and IRIs
|
|
1380
|
+
- Both properties must be present
|
|
1381
|
+
|
|
1382
|
+
---
|
|
1383
|
+
|
|
1384
|
+
## 🔧 Implementation Guidelines
|
|
1385
|
+
|
|
1386
|
+
**When to use:** Properties must not share values
|
|
1387
|
+
|
|
1388
|
+
**Best practices:**
|
|
1389
|
+
- Use for mutually exclusive properties
|
|
1390
|
+
- Test with overlapping and non-overlapping values
|
|
1391
|
+
|
|
1392
|
+
**Common pitfalls:**
|
|
1393
|
+
- ❌ Using disjoint when properties should be related
|
|
1394
|
+
- ❌ Forgetting both properties must be present
|
|
1395
|
+
|
|
1396
|
+
|
|
1397
|
+
|
|
1398
|
+
|
|
1399
|
+
|
|
1400
|
+
|
|
1401
|
+
{=}
|
|
1402
|
+
|
|
1403
|
+
|
|
1404
|
+
|
|
1405
|
+
<a id="constraints-not"></a>
|
|
1406
|
+
|
|
1407
|
+
[mdld] <https://mdld.js.org/>
|
|
1408
|
+
[cat] <mdld:shacl/>
|
|
1409
|
+
|
|
1410
|
+
# NOT Constraint {=sh:not .class:LogicalConstraint label}
|
|
1411
|
+
|
|
1412
|
+
> Requires value nodes to NOT conform to a given shape {comment}
|
|
1413
|
+
|
|
1414
|
+
<http://www.w3.org/ns/shacl#not> {?cat:fullIRI}
|
|
1415
|
+
|
|
1416
|
+
---
|
|
1417
|
+
|
|
1418
|
+
## 📋 Quick Start Pattern
|
|
1419
|
+
|
|
1420
|
+
The NOT constraint requires value nodes to NOT conform to a given shape. This example validates that users cannot have a deleted status.
|
|
1421
|
+
|
|
1422
|
+
~~~~~~md
|
|
1423
|
+
[ex] <tag:my@example.org,2026:not/>
|
|
1424
|
+
|
|
1425
|
+
## User Status Shape {=ex:UserStatusShape .sh:NodeShape label}
|
|
1426
|
+
|
|
1427
|
+
Validates all [member] {+member ?sh:targetObjectsOf} entities to not conform to the forbidden **shape** {+ex:ForbiddenStatusShape ?sh:not}.
|
|
1428
|
+
|
|
1429
|
+
**Forbidden Status Shape** {=ex:ForbiddenStatusShape .sh:NodeShape} requires [status] {+ex:status ?sh:path} to be exactly [deleted] {sh:hasValue}.
|
|
1430
|
+
|
|
1431
|
+
---
|
|
1432
|
+
|
|
1433
|
+
## Test Data {=ex:data .Container}
|
|
1434
|
+
|
|
1435
|
+
### Valid User {=ex:ValidActiveUser ?member}
|
|
1436
|
+
Status: [active] {ex:status}
|
|
1437
|
+
|
|
1438
|
+
### Invalid User {=ex:InvalidDeletedUser ?member}
|
|
1439
|
+
Status: [deleted] {ex:status}
|
|
1440
|
+
~~~~~~
|
|
1441
|
+
|
|
1442
|
+
**Expected Result:** 1 violation (InvalidDeletedUser fails because status is deleted, which conforms to the forbidden shape)
|
|
1443
|
+
|
|
1444
|
+
---
|
|
1445
|
+
|
|
1446
|
+
## 📝 MDLD Syntax Patterns
|
|
1447
|
+
|
|
1448
|
+
~~~~~~md
|
|
1449
|
+
[Shape] {=ex:Shape .sh:NodeShape} must not conform to [Forbidden Shape] {+ex:ForbiddenShape ?sh:not}.
|
|
1450
|
+
~~~~~~
|
|
1451
|
+
|
|
1452
|
+
**Use for:** Forbidden values, exclusion patterns, business rule negation
|
|
1453
|
+
|
|
1454
|
+
**Important:**
|
|
1455
|
+
- Forbidden shape defines pattern to reject
|
|
1456
|
+
- Nodes not matching forbidden shape pass automatically
|
|
1457
|
+
- Can be used with PropertyShape and NodeShape
|
|
1458
|
+
|
|
1459
|
+
---
|
|
1460
|
+
|
|
1461
|
+
## 🔧 Implementation Guidelines
|
|
1462
|
+
|
|
1463
|
+
**When to use:** Certain values must be explicitly prohibited
|
|
1464
|
+
|
|
1465
|
+
**Best practices:**
|
|
1466
|
+
- Keep forbidden shapes simple
|
|
1467
|
+
- Use descriptive names for forbidden shapes
|
|
1468
|
+
|
|
1469
|
+
**Common pitfalls:**
|
|
1470
|
+
- ❌ Creating circular dependencies
|
|
1471
|
+
- ❌ Making forbidden shapes too complex
|
|
1472
|
+
|
|
1473
|
+
|
|
1474
|
+
|
|
1475
|
+
|
|
1476
|
+
|
|
1477
|
+
|
|
1478
|
+
{=}
|
|
1479
|
+
|
|
1480
|
+
|
|
1481
|
+
|
|
1482
|
+
<a id="constraints-and"></a>
|
|
1483
|
+
|
|
1484
|
+
[mdld] <https://mdld.js.org/>
|
|
1485
|
+
[cat] <mdld:shacl/>
|
|
1486
|
+
|
|
1487
|
+
# AND Constraint {=sh:and .class:LogicalConstraint label}
|
|
1488
|
+
|
|
1489
|
+
> Requires all constraints in the list to be satisfied {comment}
|
|
1490
|
+
|
|
1491
|
+
<http://www.w3.org/ns/shacl#and> {?cat:fullIRI}
|
|
1492
|
+
|
|
1493
|
+
---
|
|
1494
|
+
|
|
1495
|
+
## 📋 Quick Start Pattern
|
|
1496
|
+
|
|
1497
|
+
The AND constraint requires all specified constraints to be satisfied. This example validates that products must have both a price and a category.
|
|
1498
|
+
|
|
1499
|
+
~~~~~~md
|
|
1500
|
+
[ex] <tag:my@example.org,2026:and/>
|
|
1501
|
+
|
|
1502
|
+
## Product Validation Shape {=ex:ProductValidationShape .sh:NodeShape label}
|
|
1503
|
+
|
|
1504
|
+
Validates all [member] {+member ?sh:targetObjectsOf} entities with **Product must have price and category** {sh:message}.
|
|
1505
|
+
|
|
1506
|
+
**Constraints List** {=ex:and-l1 ?sh:and .rdf:List}: [Price Required] {+ex:priceRequired ?rdf:first}, then [followed] {=ex:and-l2 ?rdf:rest} by [Category Required] {+ex:categoryRequired ?rdf:first} and [nil] {+rdf:nil ?rdf:rest}. {=}
|
|
1507
|
+
|
|
1508
|
+
**Price Required** {=ex:priceRequired .sh:PropertyShape} ensures [price] {+ex:price ?sh:path} has at least [1] {sh:minCount ^^xsd:integer} value.
|
|
1509
|
+
|
|
1510
|
+
**Category Required** {=ex:categoryRequired .sh:PropertyShape} ensures [category] {+ex:category ?sh:path} has at least [1] {sh:minCount ^^xsd:integer} value.
|
|
1511
|
+
|
|
1512
|
+
---
|
|
1513
|
+
|
|
1514
|
+
## Test Data {=ex:data .Container}
|
|
1515
|
+
|
|
1516
|
+
### Valid Product {=ex:ValidProduct ?member}
|
|
1517
|
+
Price: [999] {ex:price ^^xsd:integer}
|
|
1518
|
+
Category: [Electronics] {ex:category}
|
|
1519
|
+
|
|
1520
|
+
### Invalid Product {=ex:MissingPriceProduct ?member}
|
|
1521
|
+
Category: [Electronics] {ex:category}
|
|
1522
|
+
~~~~~~
|
|
1523
|
+
|
|
1524
|
+
**Expected Result:** 1 violation (MissingPriceProduct fails because it lacks price)
|
|
1525
|
+
|
|
1526
|
+
---
|
|
1527
|
+
|
|
1528
|
+
## 📝 MDLD Syntax Patterns
|
|
1529
|
+
|
|
1530
|
+
~~~~~~md
|
|
1531
|
+
[Constraints List] {=ex:and-l1 ?sh:and .rdf:List}: [First] {+ex:first ?rdf:first}, then [rest] {=ex:and-l2 ?rdf:rest} by [Second] {+ex:second ?rdf:first} and [nil] {+rdf:nil ?rdf:rest}. {=}
|
|
1532
|
+
~~~~~~
|
|
1533
|
+
|
|
1534
|
+
**Use for:** Multi-property validation, cross-field validation, business rule combinations
|
|
1535
|
+
|
|
1536
|
+
**Important:**
|
|
1537
|
+
- Uses RDF list syntax (rdf:first, rdf:rest, rdf:nil)
|
|
1538
|
+
- All constraints in list must be satisfied
|
|
1539
|
+
- Use unique list identifiers (and-l1, and-l2)
|
|
1540
|
+
- Always reset subject with {=} after list definition
|
|
1541
|
+
|
|
1542
|
+
---
|
|
1543
|
+
|
|
1544
|
+
## 🔧 Implementation Guidelines
|
|
1545
|
+
|
|
1546
|
+
**When to use:** Multiple conditions must all pass
|
|
1547
|
+
|
|
1548
|
+
**Best practices:**
|
|
1549
|
+
- Keep list short (2-3 constraints)
|
|
1550
|
+
- Test each constraint individually first
|
|
1551
|
+
|
|
1552
|
+
**Common pitfalls:**
|
|
1553
|
+
- ❌ Forgetting subject reset {=} after list
|
|
1554
|
+
- ❌ Reusing list identifiers causing collisions
|
|
1555
|
+
|
|
1556
|
+
|
|
1557
|
+
|
|
1558
|
+
|
|
1559
|
+
|
|
1560
|
+
|
|
1561
|
+
{=}
|
|
1562
|
+
|
|
1563
|
+
|
|
1564
|
+
|
|
1565
|
+
<a id="constraints-or"></a>
|
|
1566
|
+
|
|
1567
|
+
[mdld] <https://mdld.js.org/>
|
|
1568
|
+
[cat] <mdld:shacl/>
|
|
1569
|
+
|
|
1570
|
+
# OR Constraint {=sh:or .class:LogicalConstraint label}
|
|
1571
|
+
|
|
1572
|
+
> Requires at least one constraint in the list to be satisfied {comment}
|
|
1573
|
+
|
|
1574
|
+
<http://www.w3.org/ns/shacl#or> {?cat:fullIRI}
|
|
1575
|
+
|
|
1576
|
+
---
|
|
1577
|
+
|
|
1578
|
+
## 📋 Quick Start Pattern
|
|
1579
|
+
|
|
1580
|
+
The OR constraint requires at least one of the specified constraints to be satisfied. This example validates that a contact must be either an email (contains @) or a phone number (contains -).
|
|
1581
|
+
|
|
1582
|
+
~~~~~~md
|
|
1583
|
+
[ex] <tag:my@example.org,2026:or/>
|
|
1584
|
+
|
|
1585
|
+
## Contact Validation Shape {=ex:ContactValidationShape .sh:NodeShape label}
|
|
1586
|
+
|
|
1587
|
+
Validates all [member] {+member ?sh:targetObjectsOf} entities with **Contact must be email or phone** {sh:message}.
|
|
1588
|
+
|
|
1589
|
+
**Options List** {=ex:or-l1 ?sh:or .rdf:List}: [Email Contact] {+ex:emailContact ?rdf:first}, then [followed] {=ex:or-l2 ?rdf:rest} by [Phone Contact] {+ex:phoneContact ?rdf:first} and [nil] {+rdf:nil ?rdf:rest}. {=}
|
|
1590
|
+
|
|
1591
|
+
**Email Contact** {=ex:emailContact .sh:PropertyShape} ensures [contact] {+ex:contact ?sh:path} contains [@] {sh:pattern}.
|
|
1592
|
+
|
|
1593
|
+
**Phone Contact** {=ex:phoneContact .sh:PropertyShape} ensures [contact] {+ex:contact ?sh:path} contains [-] {sh:pattern}.
|
|
1594
|
+
|
|
1595
|
+
---
|
|
1596
|
+
|
|
1597
|
+
## Test Data {=ex:data .Container}
|
|
1598
|
+
|
|
1599
|
+
### Valid Email Contact {=ex:ValidEmail ?member}
|
|
1600
|
+
Contact: [user@example.com] {ex:contact}
|
|
1601
|
+
|
|
1602
|
+
### Valid Phone Contact {=ex:ValidPhone ?member}
|
|
1603
|
+
Contact: [555-123-4567] {ex:contact}
|
|
1604
|
+
|
|
1605
|
+
### Invalid Contact {=ex:InvalidContact ?member}
|
|
1606
|
+
Contact: [invalid] {ex:contact}
|
|
1607
|
+
~~~~~~
|
|
1608
|
+
|
|
1609
|
+
**Expected Result:** 1 violation (InvalidContact fails because it matches neither email nor phone pattern)
|
|
1610
|
+
|
|
1611
|
+
---
|
|
1612
|
+
|
|
1613
|
+
## 📝 MDLD Syntax Patterns
|
|
1614
|
+
|
|
1615
|
+
~~~~~~md
|
|
1616
|
+
[Options List] {=ex:or-l1 ?sh:or .rdf:List}: [First] {+ex:first ?rdf:first}, then [rest] {=ex:or-l2 ?rdf:rest} by [Second] {+ex:second ?rdf:first} and [nil] {+rdf:nil ?rdf:rest}. {=}
|
|
1617
|
+
~~~~~~
|
|
1618
|
+
|
|
1619
|
+
**Use for:** Alternative value formats, optional properties, multiple valid patterns
|
|
1620
|
+
|
|
1621
|
+
**Important:**
|
|
1622
|
+
- Uses RDF list syntax (rdf:first, rdf:rest, rdf:nil)
|
|
1623
|
+
- At least one constraint in list must be satisfied
|
|
1624
|
+
- Use unique list identifiers (or-l1, or-l2)
|
|
1625
|
+
- Always reset subject with {=} after list definition
|
|
1626
|
+
|
|
1627
|
+
---
|
|
1628
|
+
|
|
1629
|
+
## 🔧 Implementation Guidelines
|
|
1630
|
+
|
|
1631
|
+
**When to use:** Multiple valid alternatives exist
|
|
1632
|
+
|
|
1633
|
+
**Best practices:**
|
|
1634
|
+
- Keep list short (2-3 alternatives)
|
|
1635
|
+
- Test each alternative individually first
|
|
1636
|
+
- Ensure alternatives are mutually exclusive when appropriate
|
|
1637
|
+
|
|
1638
|
+
**Common pitfalls:**
|
|
1639
|
+
- ❌ Forgetting subject reset {=} after list
|
|
1640
|
+
- ❌ Reusing list identifiers causing collisions
|
|
1641
|
+
- ❌ Overlapping alternatives causing ambiguity
|
|
1642
|
+
|
|
1643
|
+
|
|
1644
|
+
|
|
1645
|
+
|
|
1646
|
+
|
|
1647
|
+
|
|
1648
|
+
{=}
|
|
1649
|
+
|
|
1650
|
+
|
|
1651
|
+
|
|
1652
|
+
<a id="constraints-xone"></a>
|
|
1653
|
+
|
|
1654
|
+
[mdld] <https://mdld.js.org/>
|
|
1655
|
+
[cat] <mdld:shacl/>
|
|
1656
|
+
|
|
1657
|
+
# XONE Constraint {=sh:xone .class:LogicalConstraint label}
|
|
1658
|
+
|
|
1659
|
+
> Requires exactly one constraint in the list to be satisfied (exclusive OR) {comment}
|
|
1660
|
+
|
|
1661
|
+
<http://www.w3.org/ns/shacl#xone> {?cat:fullIRI}
|
|
1662
|
+
|
|
1663
|
+
---
|
|
1664
|
+
|
|
1665
|
+
## 📋 Quick Start Pattern
|
|
1666
|
+
|
|
1667
|
+
The XONE constraint requires exactly one of the specified constraints to be satisfied. This example validates that a role must be exactly one type (admin or user), not both and not neither.
|
|
1668
|
+
|
|
1669
|
+
~~~~~~md
|
|
1670
|
+
[ex] <tag:my@example.org,2026:xone/>
|
|
1671
|
+
|
|
1672
|
+
## Role Validation Shape {=ex:RoleValidationShape .sh:NodeShape label}
|
|
1673
|
+
|
|
1674
|
+
Validates all [member] {+member ?sh:targetObjectsOf} entities with **Role must be exactly one type** {sh:message}.
|
|
1675
|
+
|
|
1676
|
+
**Options List** {=ex:xone-l1 ?sh:xone .rdf:List}: [Admin Role] {+ex:adminRole ?rdf:first}, then [followed] {=ex:xone-l2 ?rdf:rest} by [User Role] {+ex:userRole ?rdf:first} and [nil] {+rdf:nil ?rdf:rest}. {=}
|
|
1677
|
+
|
|
1678
|
+
**Admin Role** {=ex:adminRole .sh:PropertyShape} ensures [role] {+ex:role ?sh:path} is exactly [admin] {sh:hasValue}.
|
|
1679
|
+
|
|
1680
|
+
**User Role** {=ex:userRole .sh:PropertyShape} ensures [role] {+ex:role ?sh:path} is exactly [user] {sh:hasValue}.
|
|
1681
|
+
|
|
1682
|
+
---
|
|
1683
|
+
|
|
1684
|
+
## Test Data {=ex:data .Container}
|
|
1685
|
+
|
|
1686
|
+
### Valid Admin {=ex:ValidAdmin ?member}
|
|
1687
|
+
Role: [admin] {ex:role}
|
|
1688
|
+
|
|
1689
|
+
### Valid User {=ex:ValidUser ?member}
|
|
1690
|
+
Role: [user] {ex:role}
|
|
1691
|
+
|
|
1692
|
+
### Invalid - No Role {=ex:NoRole ?member}
|
|
1693
|
+
Role: [guest] {ex:role}
|
|
1694
|
+
~~~~~~
|
|
1695
|
+
|
|
1696
|
+
**Expected Result:** 1 violation (NoRole fails because it matches neither admin nor user)
|
|
1697
|
+
|
|
1698
|
+
---
|
|
1699
|
+
|
|
1700
|
+
## 📝 MDLD Syntax Patterns
|
|
1701
|
+
|
|
1702
|
+
~~~~~~md
|
|
1703
|
+
[Options List] {=ex:xone-l1 ?sh:xone .rdf:List}: [First] {+ex:first ?rdf:first}, then [rest] {=ex:xone-l2 ?rdf:rest} by [Second] {+ex:second ?rdf:first} and [nil] {+rdf:nil ?rdf:rest}. {=}
|
|
1704
|
+
~~~~~~
|
|
1705
|
+
|
|
1706
|
+
**Use for:** Mutually exclusive options, single-choice validation, exclusive categories
|
|
1707
|
+
|
|
1708
|
+
**Important:**
|
|
1709
|
+
- Uses RDF list syntax (rdf:first, rdf:rest, rdf:nil)
|
|
1710
|
+
- Exactly one constraint in list must be satisfied
|
|
1711
|
+
- Use unique list identifiers (xone-l1, xone-l2)
|
|
1712
|
+
- Always reset subject with {=} after list definition
|
|
1713
|
+
|
|
1714
|
+
---
|
|
1715
|
+
|
|
1716
|
+
## 🔧 Implementation Guidelines
|
|
1717
|
+
|
|
1718
|
+
**When to use:** Mutually exclusive alternatives where exactly one must match
|
|
1719
|
+
|
|
1720
|
+
**Best practices:**
|
|
1721
|
+
- Ensure alternatives are truly mutually exclusive
|
|
1722
|
+
- Test each alternative individually first
|
|
1723
|
+
- Consider edge cases (no match, multiple matches)
|
|
1724
|
+
|
|
1725
|
+
**Common pitfalls:**
|
|
1726
|
+
- ❌ Forgetting subject reset {=} after list
|
|
1727
|
+
- ❌ Reusing list identifiers causing collisions
|
|
1728
|
+
- ❌ Overlapping alternatives causing ambiguous results
|
|
1729
|
+
|
|
1730
|
+
|
|
1731
|
+
|
|
1732
|
+
|
|
1733
|
+
|
|
1734
|
+
|
|
1735
|
+
{=}
|
|
1736
|
+
|
|
1737
|
+
|
|
1738
|
+
|
|
1739
|
+
<a id="constraints-length"></a>
|
|
1740
|
+
|
|
1741
|
+
[mdld] <https://mdld.js.org/>
|
|
1742
|
+
[cat] <mdld:shacl/>
|
|
1743
|
+
|
|
1744
|
+
# Min Length {=sh:minLength .class:Constraint label}
|
|
1745
|
+
|
|
1746
|
+
> Specifies the minimum length of string values {comment}
|
|
1747
|
+
|
|
1748
|
+
<http://www.w3.org/ns/shacl#minLength> {?cat:fullIRI}
|
|
1749
|
+
|
|
1750
|
+
# Max Length {=sh:maxLength .class:Constraint label}
|
|
1751
|
+
|
|
1752
|
+
> Specifies the maximum length of string values {comment}
|
|
1753
|
+
|
|
1754
|
+
<http://www.w3.org/ns/shacl#maxLength> {?cat:fullIRI}
|
|
1755
|
+
|
|
1756
|
+
---
|
|
1757
|
+
|
|
1758
|
+
## 📋 Quick Start Pattern
|
|
1759
|
+
|
|
1760
|
+
Length constraints specify the minimum and maximum length of string values. This example validates that usernames must be between 3 and 20 characters.
|
|
1761
|
+
|
|
1762
|
+
~~~~~~md
|
|
1763
|
+
[ex] <tag:my@example.org,2026:length/>
|
|
1764
|
+
|
|
1765
|
+
## User Account Test Shape {=ex:UserAccountTestShape .sh:NodeShape label}
|
|
1766
|
+
|
|
1767
|
+
Validates all [member] {+member ?sh:targetObjectsOf} entities with correct length of the **username** {+#usernameLength ?sh:property sh:name}.
|
|
1768
|
+
|
|
1769
|
+
**Username must be 3-20 characters** {=#usernameLength .sh:PropertyShape sh:message} requires [username] {+ex:username ?sh:path} to have at least [3] {sh:minLength ^^xsd:integer} and at most [20] {sh:maxLength ^^xsd:integer} characters.
|
|
1770
|
+
|
|
1771
|
+
---
|
|
1772
|
+
|
|
1773
|
+
## Test Data {=ex:data .Container}
|
|
1774
|
+
|
|
1775
|
+
### Valid User {=ex:ValidUser ?member}
|
|
1776
|
+
Username: [john_doe] {ex:username}
|
|
1777
|
+
|
|
1778
|
+
### Invalid User {=ex:InvalidUser ?member}
|
|
1779
|
+
Username: [jd] {ex:username}
|
|
1780
|
+
~~~~~~
|
|
1781
|
+
|
|
1782
|
+
**Expected Result:** 1 violation (InvalidUser fails because username is only 2 characters, below the minimum of 3)
|
|
1783
|
+
|
|
1784
|
+
---
|
|
1785
|
+
|
|
1786
|
+
## 📝 MDLD Syntax Patterns
|
|
1787
|
+
|
|
1788
|
+
~~~~~~md
|
|
1789
|
+
[Property] {+ex:propertyName ?sh:path} must have at least [min] {sh:minLength ^^xsd:integer} and at most [max] {sh:maxLength ^^xsd:integer} characters.
|
|
1790
|
+
~~~~~~
|
|
1791
|
+
|
|
1792
|
+
**Use for:** Username validation, password policies, content limits, form validation
|
|
1793
|
+
|
|
1794
|
+
**Important:**
|
|
1795
|
+
- Works with literal string values only
|
|
1796
|
+
- Length measured in characters, not bytes
|
|
1797
|
+
- Empty strings have length 0
|
|
1798
|
+
|
|
1799
|
+
---
|
|
1800
|
+
|
|
1801
|
+
## 🔧 Implementation Guidelines
|
|
1802
|
+
|
|
1803
|
+
**When to use:** String length must be controlled
|
|
1804
|
+
|
|
1805
|
+
**Best practices:**
|
|
1806
|
+
- Use reasonable length limits
|
|
1807
|
+
- Test with boundary values
|
|
1808
|
+
|
|
1809
|
+
**Common pitfalls:**
|
|
1810
|
+
- ❌ Forgetting datatype ^^xsd:integer
|
|
1811
|
+
- ❌ Using negative values for lengths
|
|
1812
|
+
|
|
1813
|
+
|
|
1814
|
+
|
|
1815
|
+
|
|
1816
|
+
|
|
1817
|
+
|
|
1818
|
+
{=}
|
|
1819
|
+
|
|
1820
|
+
|
|
1821
|
+
|
|
1822
|
+
<a id="constraints-pattern"></a>
|
|
1823
|
+
|
|
1824
|
+
[mdld] <https://mdld.js.org/>
|
|
1825
|
+
[cat] <mdld:shacl/>
|
|
1826
|
+
|
|
1827
|
+
# Pattern {=sh:pattern .class:PatternConstraint label}
|
|
1828
|
+
|
|
1829
|
+
> Validates string values against regular expression patterns {comment}
|
|
1830
|
+
|
|
1831
|
+
<http://www.w3.org/ns/shacl#pattern> {?cat:fullIRI}
|
|
1832
|
+
<http://www.w3.org/ns/shacl#flags> {?cat:fullIRI}
|
|
1833
|
+
|
|
1834
|
+
---
|
|
1835
|
+
|
|
1836
|
+
## 📋 Quick Start Pattern
|
|
1837
|
+
|
|
1838
|
+
The pattern constraint validates string values against regular expression patterns. This example validates that emails must end with example.com.
|
|
1839
|
+
|
|
1840
|
+
~~~~~~md
|
|
1841
|
+
[ex] <tag:my@example.org,2026:pattern/>
|
|
1842
|
+
|
|
1843
|
+
## Email Validation Shape {=ex:PatternExampleShape .sh:NodeShape label}
|
|
1844
|
+
|
|
1845
|
+
Validates all [member] {+member ?sh:targetObjectsOf} entities with corporate **email** {+ex:EmailPatternConstraint ?sh:property sh:name}.
|
|
1846
|
+
|
|
1847
|
+
**Email must end with example.com** {=ex:EmailPatternConstraint .sh:PropertyShape sh:message} requires [email] {+ex:email ?sh:path} to match [example\.com$] {sh:pattern} with [i] {sh:flags}.
|
|
1848
|
+
|
|
1849
|
+
---
|
|
1850
|
+
|
|
1851
|
+
## Test Data {=ex:data .Container}
|
|
1852
|
+
|
|
1853
|
+
### Valid Email {=ex:ValidEmail ?member}
|
|
1854
|
+
Email: [user@example.com] {ex:email}
|
|
1855
|
+
|
|
1856
|
+
### Invalid Email {=ex:InvalidEmail ?member}
|
|
1857
|
+
Email: [user@example.org] {ex:email}
|
|
1858
|
+
~~~~~~
|
|
1859
|
+
|
|
1860
|
+
**Expected Result:** 1 violation (InvalidEmail fails because it doesn't match the pattern - ends with .org not .com)
|
|
1861
|
+
|
|
1862
|
+
---
|
|
1863
|
+
|
|
1864
|
+
## 📝 MDLD Syntax Patterns
|
|
1865
|
+
|
|
1866
|
+
~~~~~~md
|
|
1867
|
+
[Property] {+ex:propertyName ?sh:path} must match [regex pattern] {sh:pattern} with [flags] {sh:flags}.
|
|
1868
|
+
~~~~~~
|
|
1869
|
+
|
|
1870
|
+
**Use for:** Email validation, phone number formatting, identifier patterns, URL validation
|
|
1871
|
+
|
|
1872
|
+
**Important:**
|
|
1873
|
+
- Works with literal string values only
|
|
1874
|
+
- Supports standard regex syntax
|
|
1875
|
+
- Common flags: i (case-insensitive), m (multiline), s (dotall)
|
|
1876
|
+
- Empty values automatically pass
|
|
1877
|
+
|
|
1878
|
+
---
|
|
1879
|
+
|
|
1880
|
+
## 🔧 Implementation Guidelines
|
|
1881
|
+
|
|
1882
|
+
**When to use:** Values must match specific format
|
|
1883
|
+
|
|
1884
|
+
**Best practices:**
|
|
1885
|
+
- Use well-tested regex patterns
|
|
1886
|
+
- Keep patterns simple
|
|
1887
|
+
- Test with valid and invalid examples
|
|
1888
|
+
|
|
1889
|
+
**Common pitfalls:**
|
|
1890
|
+
- ❌ Using overly complex regex
|
|
1891
|
+
- ❌ Forgetting pattern only works with strings
|
|
1892
|
+
|
|
1893
|
+
|
|
1894
|
+
|
|
1895
|
+
|
|
1896
|
+
|
|
1897
|
+
|
|
1898
|
+
{=}
|
|
1899
|
+
|
|
1900
|
+
|
|
1901
|
+
|
|
1902
|
+
<a id="constraints-language"></a>
|
|
1903
|
+
|
|
1904
|
+
[mdld] <https://mdld.js.org/>
|
|
1905
|
+
[cat] <mdld:shacl/>
|
|
1906
|
+
|
|
1907
|
+
# Language In {=sh:languageIn .class:StringConstraint label}
|
|
1908
|
+
|
|
1909
|
+
> Constrains string literals to have language tags from a specified list {comment}
|
|
1910
|
+
|
|
1911
|
+
<http://www.w3.org/ns/shacl#languageIn> {?cat:fullIRI}
|
|
1912
|
+
|
|
1913
|
+
---
|
|
1914
|
+
|
|
1915
|
+
## 📋 Quick Start Pattern
|
|
1916
|
+
|
|
1917
|
+
The languageIn constraint constrains string literals to have language tags from a specified list. This example validates that document titles must be in English or French.
|
|
1918
|
+
|
|
1919
|
+
~~~~~~md
|
|
1920
|
+
[ex] <tag:my@example.org,2026:language/>
|
|
1921
|
+
|
|
1922
|
+
## Multilingual Document Shape {=ex:MultilingualDocumentShape .sh:NodeShape label}
|
|
1923
|
+
|
|
1924
|
+
Validates all [member] {+member ?sh:targetObjectsOf} entities with english or french **title** {+#titleLanguage ?sh:property sh:name}.
|
|
1925
|
+
|
|
1926
|
+
**Title language must be en or fr** {=#titleLanguage .sh:PropertyShape sh:message} requires [title] {+ex:title ?sh:path} language tags to be in the **Allowed Languages List** {=ex:lang-l1 ?sh:languageIn .rdf:List}: **en** {rdf:first}, [or] {=ex:lang-l2 ?rdf:rest} **fr** {rdf:first} - [only these 2 languages are allowed] {+rdf:nil ?rdf:rest}. {=}
|
|
1927
|
+
|
|
1928
|
+
---
|
|
1929
|
+
|
|
1930
|
+
## Test Data {=ex:data .Container}
|
|
1931
|
+
|
|
1932
|
+
### English Document {=ex:EnglishDocument ?member}
|
|
1933
|
+
Title: [Hello World] {ex:title @en}
|
|
1934
|
+
|
|
1935
|
+
### Invalid Document {=ex:GermanDocument ?member}
|
|
1936
|
+
Title: [Hallo Welt] {ex:title @de}
|
|
1937
|
+
~~~~~~
|
|
1938
|
+
|
|
1939
|
+
**Expected Result:** 1 violation (GermanDocument fails because title language is de, not in the allowed list)
|
|
1940
|
+
|
|
1941
|
+
---
|
|
1942
|
+
|
|
1943
|
+
## 📝 MDLD Syntax Patterns
|
|
1944
|
+
|
|
1945
|
+
~~~~~~md
|
|
1946
|
+
[Property] {+ex:propertyName ?sh:path} language tags must be in allowed list.
|
|
1947
|
+
|
|
1948
|
+
**Allowed Languages List** {=ex:lang-l1 ?sh:languageIn .rdf:List}: [en] {rdf:first}, then [rest] {=ex:lang-l2 ?rdf:rest} by [fr] {rdf:first} and [nil] {+rdf:nil ?rdf:rest}. {=}
|
|
1949
|
+
~~~~~~
|
|
1950
|
+
|
|
1951
|
+
**Use for:** Multilingual content, regional compliance, content localization
|
|
1952
|
+
|
|
1953
|
+
**Important:**
|
|
1954
|
+
- Uses RDF list syntax (rdf:first, rdf:rest, rdf:nil)
|
|
1955
|
+
- Only validates language tags if they exist
|
|
1956
|
+
- Use @lang syntax for language-tagged literals
|
|
1957
|
+
- Use valid BCP 47 language codes (en, fr, de, etc.)
|
|
1958
|
+
|
|
1959
|
+
---
|
|
1960
|
+
|
|
1961
|
+
## 🔧 Implementation Guidelines
|
|
1962
|
+
|
|
1963
|
+
**When to use:** Content must be in specific languages
|
|
1964
|
+
|
|
1965
|
+
**Best practices:**
|
|
1966
|
+
- Use valid BCP 47 language codes
|
|
1967
|
+
- Keep language list short
|
|
1968
|
+
|
|
1969
|
+
**Common pitfalls:**
|
|
1970
|
+
- ❌ Forgetting subject reset {=} after list
|
|
1971
|
+
- ❌ Reusing list identifiers causing collisions
|
|
1972
|
+
|
|
1973
|
+
|
|
1974
|
+
|
|
1975
|
+
|
|
1976
|
+
|
|
1977
|
+
|
|
1978
|
+
{=}
|
|
1979
|
+
|
|
1980
|
+
|
|
1981
|
+
|
|
1982
|
+
<a id="constraints-uniquelang"></a>
|
|
1983
|
+
|
|
1984
|
+
[mdld] <https://mdld.js.org/>
|
|
1985
|
+
[cat] <mdld:shacl/>
|
|
1986
|
+
|
|
1987
|
+
# Unique Languages {=sh:uniqueLang .class:UniqueLanguageConstraint label}
|
|
1988
|
+
|
|
1989
|
+
> Ensures that language tags of string literals are unique within a property {comment}
|
|
1990
|
+
|
|
1991
|
+
<http://www.w3.org/ns/shacl#uniqueLang> {?cat:fullIRI}
|
|
1992
|
+
|
|
1993
|
+
---
|
|
1994
|
+
|
|
1995
|
+
## 📋 Quick Start Pattern
|
|
1996
|
+
|
|
1997
|
+
The uniqueLang constraint ensures that language tags of string literals are unique within a property. This example validates that document titles cannot have duplicate language tags.
|
|
1998
|
+
|
|
1999
|
+
~~~~~~md
|
|
2000
|
+
[ex] <tag:my@example.org,2026:uniqueLang/>
|
|
2001
|
+
|
|
2002
|
+
## Unique Language Example Shape {=ex:UniqueLangExampleShape .sh:NodeShape label}
|
|
2003
|
+
|
|
2004
|
+
Validates all [member] {+member ?sh:targetObjectsOf} entities with unique **language** {+ex:TitleProperty ?sh:property sh:name}.
|
|
2005
|
+
|
|
2006
|
+
**Each language tag must appear only once** {=ex:TitleProperty .sh:PropertyShape sh:message} requires [title] {+ex:title ?sh:path} values to have [true] {sh:uniqueLang ^^xsd:boolean}.
|
|
2007
|
+
|
|
2008
|
+
---
|
|
2009
|
+
|
|
2010
|
+
## Test Data {=ex:data .Container}
|
|
2011
|
+
|
|
2012
|
+
### Valid Document {=ex:ValidNode ?member}
|
|
2013
|
+
Title: [Hello World] {ex:title @en}
|
|
2014
|
+
Title: [Bonjour Monde] {ex:title @fr}
|
|
2015
|
+
|
|
2016
|
+
### Invalid Document {=ex:InvalidNode ?member}
|
|
2017
|
+
Title: [Hello World] {ex:title @en}
|
|
2018
|
+
Title: [Hola Mundo] {ex:title @en}
|
|
2019
|
+
~~~~~~
|
|
2020
|
+
|
|
2021
|
+
**Expected Result:** 1 violation (InvalidDocument fails because it has duplicate @en language tags)
|
|
2022
|
+
|
|
2023
|
+
---
|
|
2024
|
+
|
|
2025
|
+
## 📝 MDLD Syntax Patterns
|
|
2026
|
+
|
|
2027
|
+
~~~~~~md
|
|
2028
|
+
[Property] {+ex:propertyName ?sh:path} values have [true] {sh:uniqueLang ^^xsd:boolean}.
|
|
2029
|
+
~~~~~~
|
|
2030
|
+
|
|
2031
|
+
**Use for:** Multilingual content, translation management, content localization
|
|
2032
|
+
|
|
2033
|
+
**Important:**
|
|
2034
|
+
- Only applies to language-tagged string literals
|
|
2035
|
+
- Prevents duplicate language tags within same property
|
|
2036
|
+
- Use @lang syntax for language-tagged literals
|
|
2037
|
+
|
|
2038
|
+
---
|
|
2039
|
+
|
|
2040
|
+
## 🔧 Implementation Guidelines
|
|
2041
|
+
|
|
2042
|
+
**When to use:** Prevent duplicate language entries
|
|
2043
|
+
|
|
2044
|
+
**Best practices:**
|
|
2045
|
+
- Use with language-tagged string literals
|
|
2046
|
+
- Combine with languageIn for complete validation
|
|
2047
|
+
|
|
2048
|
+
**Common pitfalls:**
|
|
2049
|
+
- ❌ Using uniqueLang on non-language-tagged literals
|
|
2050
|
+
- ❌ Forgetting to use @lang syntax
|
|
2051
|
+
|
|
2052
|
+
|
|
2053
|
+
|
|
2054
|
+
|
|
2055
|
+
|
|
2056
|
+
|
|
2057
|
+
{=}
|
|
2058
|
+
|
|
2059
|
+
|
|
2060
|
+
|
|
2061
|
+
<a id="constraints-hasvalue"></a>
|
|
2062
|
+
|
|
2063
|
+
[mdld] <https://mdld.js.org/>
|
|
2064
|
+
[cat] <mdld:shacl/>
|
|
2065
|
+
|
|
2066
|
+
# Has Value {=sh:hasValue .class:Constraint label}
|
|
2067
|
+
|
|
2068
|
+
> Requires a property to have exactly this specific value {comment}
|
|
2069
|
+
|
|
2070
|
+
<http://www.w3.org/ns/shacl#hasValue> {?cat:fullIRI}
|
|
2071
|
+
|
|
2072
|
+
---
|
|
2073
|
+
|
|
2074
|
+
## 📋 Quick Start Pattern
|
|
2075
|
+
|
|
2076
|
+
The hasValue constraint requires a property to have exactly a specific value. This example validates that server status must be exactly "active".
|
|
2077
|
+
|
|
2078
|
+
~~~~~~md
|
|
2079
|
+
[ex] <tag:my@example.org,2026:hasvalue/>
|
|
2080
|
+
|
|
2081
|
+
## System Status Test Shape {=ex:SystemStatusTestShape .sh:NodeShape label}
|
|
2082
|
+
|
|
2083
|
+
Validates all [member] {+member ?sh:targetObjectsOf} entities with active **status** {+#statusRequired ?sh:property sh:name}.
|
|
2084
|
+
|
|
2085
|
+
**Status must be active** {=#statusRequired .sh:PropertyShape sh:message} requires [status] {+ex:status ?sh:path} to be exactly [active] {sh:hasValue ^^xsd:string}.
|
|
2086
|
+
|
|
2087
|
+
---
|
|
2088
|
+
|
|
2089
|
+
## Test Data {=ex:data .Container}
|
|
2090
|
+
|
|
2091
|
+
### Valid Server {=ex:MainServer ?member}
|
|
2092
|
+
Status: [active] {ex:status}
|
|
2093
|
+
|
|
2094
|
+
### Invalid Server {=ex:BackupServer ?member}
|
|
2095
|
+
Status: [standby] {ex:status}
|
|
2096
|
+
~~~~~~
|
|
2097
|
+
|
|
2098
|
+
**Expected Result:** 1 violation (BackupServer fails because status is standby, not active)
|
|
2099
|
+
|
|
2100
|
+
---
|
|
2101
|
+
|
|
2102
|
+
## 📝 MDLD Syntax Patterns
|
|
2103
|
+
|
|
2104
|
+
~~~~~~md
|
|
2105
|
+
[Property] {+ex:propertyName ?sh:path} must be exactly [Value] {sh:hasValue}.
|
|
2106
|
+
~~~~~~
|
|
2107
|
+
|
|
2108
|
+
**Use for:** Fixed status fields, required constants, environment flags, system identifiers
|
|
2109
|
+
|
|
2110
|
+
**Important:**
|
|
2111
|
+
- Requires exact match, no partial matches
|
|
2112
|
+
- Works with both literal values and IRIs
|
|
2113
|
+
- Property must have the value (use minCount for required properties)
|
|
2114
|
+
- Often used with NOT constraint to forbid specific values
|
|
2115
|
+
|
|
2116
|
+
---
|
|
2117
|
+
|
|
2118
|
+
## 🔧 Implementation Guidelines
|
|
2119
|
+
|
|
2120
|
+
**When to use:** Property must have a specific constant value
|
|
2121
|
+
|
|
2122
|
+
**Best practices:**
|
|
2123
|
+
- Use for fixed, unchanging values
|
|
2124
|
+
- Combine with NOT to forbid specific values
|
|
2125
|
+
|
|
2126
|
+
**Common pitfalls:**
|
|
2127
|
+
- ❌ Using hasValue for variable values
|
|
2128
|
+
- ❌ Forgetting hasValue requires exact match
|
|
2129
|
+
- ❌ Not combining with minCount for required properties
|
|
2130
|
+
|
|
2131
|
+
|
|
2132
|
+
|
|
2133
|
+
|
|
2134
|
+
|
|
2135
|
+
|
|
2136
|
+
{=}
|
|
2137
|
+
|
|
2138
|
+
|
|
2139
|
+
|
|
2140
|
+
<a id="constraints-node"></a>
|
|
2141
|
+
|
|
2142
|
+
[mdld] <https://mdld.js.org/>
|
|
2143
|
+
[cat] <mdld:shacl/>
|
|
2144
|
+
|
|
2145
|
+
# Node {=sh:node .class:NodeConstraint label}
|
|
2146
|
+
|
|
2147
|
+
> Requires property values to conform to a specific node shape {comment}
|
|
2148
|
+
|
|
2149
|
+
<http://www.w3.org/ns/shacl#node> {?cat:fullIRI}
|
|
2150
|
+
|
|
2151
|
+
---
|
|
2152
|
+
|
|
2153
|
+
## 📋 Quick Start Pattern
|
|
2154
|
+
|
|
2155
|
+
The node constraint requires property values to conform to a specific node shape. This example validates that employee addresses must conform to an AddressShape with minimum street length.
|
|
2156
|
+
|
|
2157
|
+
~~~~~~md
|
|
2158
|
+
[ex] <tag:my@example.org,2026:node/>
|
|
2159
|
+
|
|
2160
|
+
## Employee Validation Shape {=ex:EmployeeValidationShape .sh:NodeShape label}
|
|
2161
|
+
|
|
2162
|
+
Validates all [member] {+member ?sh:targetObjectsOf} entities to have correct **address** {+#addressRule ?sh:property sh:name}.
|
|
2163
|
+
|
|
2164
|
+
**Employee must have valid address** {=#addressRule .sh:PropertyShape sh:message} requires [address] {+ex:address ?sh:path} to conform to [Address Shape] {+ex:AddressShape ?sh:node}.
|
|
2165
|
+
|
|
2166
|
+
**Address Shape** {=ex:AddressShape .sh:NodeShape} requires [street] {+ex:street ?sh:path} to have at least [5] {sh:minLength ^^xsd:integer} characters.
|
|
2167
|
+
|
|
2168
|
+
---
|
|
2169
|
+
|
|
2170
|
+
## Test Data {=ex:data .Container}
|
|
2171
|
+
|
|
2172
|
+
### Valid Employee {=ex:ValidEmployee ?member}
|
|
2173
|
+
Address: [Valid Address] {=ex:ValidAddress .ex:Address ?ex:address}
|
|
2174
|
+
Street: [Main Street] {ex:street}
|
|
2175
|
+
|
|
2176
|
+
### Invalid Employee {=ex:InvalidEmployee ?member}
|
|
2177
|
+
Address: [Short Address] {=ex:ShortAddress .ex:Address ?ex:address}
|
|
2178
|
+
Street: [St] {ex:street}
|
|
2179
|
+
~~~~~~
|
|
2180
|
+
|
|
2181
|
+
**Expected Result:** 1 violation (InvalidEmployee fails because address doesn't conform to AddressShape - street is too short)
|
|
2182
|
+
|
|
2183
|
+
---
|
|
2184
|
+
|
|
2185
|
+
## 📝 MDLD Syntax Patterns
|
|
2186
|
+
|
|
2187
|
+
~~~~~~md
|
|
2188
|
+
[Property] {+ex:propertyName ?sh:path} must conform to [Shape] {+ex:ShapeName ?sh:node}.
|
|
2189
|
+
~~~~~~
|
|
2190
|
+
|
|
2191
|
+
**Use for:** Nested object validation, complex data models, structural integrity
|
|
2192
|
+
|
|
2193
|
+
**Important:**
|
|
2194
|
+
- Only applies to node values (IRIs/blank nodes), not literal values
|
|
2195
|
+
- Referenced shape must be defined in ontology
|
|
2196
|
+
- Enables validation of complex nested objects
|
|
2197
|
+
|
|
2198
|
+
---
|
|
2199
|
+
|
|
2200
|
+
## 🔧 Implementation Guidelines
|
|
2201
|
+
|
|
2202
|
+
**When to use:** Property values are complex objects
|
|
2203
|
+
|
|
2204
|
+
**Best practices:**
|
|
2205
|
+
- Define referenced shapes clearly
|
|
2206
|
+
- Use descriptive shape names
|
|
2207
|
+
|
|
2208
|
+
**Common pitfalls:**
|
|
2209
|
+
- ❌ Forgetting node only applies to nodes, not literals
|
|
2210
|
+
- ❌ Not defining the referenced shape
|
|
2211
|
+
- ❌ Confusing node with class constraint (node for structure, class for type)
|
|
2212
|
+
|
|
2213
|
+
|
|
2214
|
+
|
|
2215
|
+
|
|
2216
|
+
|
|
2217
|
+
|
|
2218
|
+
{=}
|
|
2219
|
+
|
|
2220
|
+
|
|
2221
|
+
|
|
2222
|
+
<a id="constraints-in"></a>
|
|
2223
|
+
|
|
2224
|
+
[mdld] <https://mdld.js.org/>
|
|
2225
|
+
[cat] <mdld:shacl/>
|
|
2226
|
+
|
|
2227
|
+
# Value Enumeration {=sh:in .class:PresenceConstraint label}
|
|
2228
|
+
|
|
2229
|
+
> Constrains property values to be within a specified list of allowed values {comment}
|
|
2230
|
+
|
|
2231
|
+
<http://www.w3.org/ns/shacl#in> {?cat:fullIRI}
|
|
2232
|
+
|
|
2233
|
+
---
|
|
2234
|
+
|
|
2235
|
+
## 📋 Quick Start Pattern
|
|
2236
|
+
|
|
2237
|
+
The in constraint constrains property values to be within a specified list of allowed values. This example validates that status must be either "Active" or "Inactive".
|
|
2238
|
+
|
|
2239
|
+
~~~~~~md
|
|
2240
|
+
[ex] <tag:my@example.org,2026:in/>
|
|
2241
|
+
|
|
2242
|
+
## Status Validation Shape {=ex:StatusValidationShape .sh:NodeShape label}
|
|
2243
|
+
|
|
2244
|
+
Validates all [member] {+member ?sh:targetObjectsOf} entities with correct **status** {+#allowedStatus ?sh:property sh:name}.
|
|
2245
|
+
|
|
2246
|
+
**Status must be Active or Inactive** {=#allowedStatus .sh:PropertyShape sh:message} requires [status] {+ex:status ?sh:path} to be in allowed list.
|
|
2247
|
+
|
|
2248
|
+
**Allowed Values List** {=ex:in-l1 ?sh:in .rdf:List}: **Active** {+ex:Active ?rdf:first} [or] {=ex:in-l2 ?rdf:rest} **Inactive** {+ex:Inactive ?rdf:first} - [only] {+rdf:nil ?rdf:rest} these 2 values are allowed.
|
|
2249
|
+
|
|
2250
|
+
---
|
|
2251
|
+
|
|
2252
|
+
## Test Data {=ex:data .Container}
|
|
2253
|
+
|
|
2254
|
+
### Valid Employee {=ex:ValidEmployee ?member}
|
|
2255
|
+
Status: [Active] {+ex:Active ?ex:status}
|
|
2256
|
+
|
|
2257
|
+
### Invalid Employee {=ex:InvalidStatusEmployee ?member}
|
|
2258
|
+
Status: [Pending] {+ex:Pending ?ex:status}
|
|
2259
|
+
~~~~~~
|
|
2260
|
+
|
|
2261
|
+
**Expected Result:** 1 violation (InvalidStatusEmployee fails because status is Pending, not in the allowed list)
|
|
2262
|
+
|
|
2263
|
+
---
|
|
2264
|
+
|
|
2265
|
+
## 📝 MDLD Syntax Patterns
|
|
2266
|
+
|
|
2267
|
+
~~~~~~md
|
|
2268
|
+
[Property] {+ex:propertyName ?sh:path} must be in allowed list.
|
|
2269
|
+
|
|
2270
|
+
**Allowed List** {=ex:in-l1 ?sh:in .rdf:List}: [First] {+ex:first ?rdf:first}, then [rest] {=ex:in-l2 ?rdf:rest} by [Second] {+ex:second ?rdf:first} and [nil] {+rdf:nil ?rdf:rest}. {=}
|
|
2271
|
+
~~~~~~
|
|
2272
|
+
|
|
2273
|
+
**Use for:** Controlled vocabularies, status codes, enumeration validation, category validation
|
|
2274
|
+
|
|
2275
|
+
**Important:**
|
|
2276
|
+
- Uses RDF list syntax (rdf:first, rdf:rest, rdf:nil)
|
|
2277
|
+
- Only validates values if property exists
|
|
2278
|
+
- Use minCount to check for required properties
|
|
2279
|
+
- Always reset subject with {=} after list definition
|
|
2280
|
+
|
|
2281
|
+
---
|
|
2282
|
+
|
|
2283
|
+
## 🔧 Implementation Guidelines
|
|
2284
|
+
|
|
2285
|
+
**When to use:** Values must be from a predefined set
|
|
2286
|
+
|
|
2287
|
+
**Best practices:**
|
|
2288
|
+
- Keep list short for maintainability
|
|
2289
|
+
- Combine with minCount for required properties
|
|
2290
|
+
|
|
2291
|
+
**Common pitfalls:**
|
|
2292
|
+
- ❌ Forgetting subject reset {=} after list
|
|
2293
|
+
- ❌ Reusing list identifiers causing collisions
|
|
2294
|
+
- ❌ Not combining with minCount for required properties
|
|
2295
|
+
|
|
2296
|
+
|
|
2297
|
+
|
|
2298
|
+
|
|
2299
|
+
|
|
2300
|
+
|
|
2301
|
+
{=}
|
|
2302
|
+
|
|
2303
|
+
|
|
2304
|
+
|
|
2305
|
+
<a id="constraints-qualifiedcount"></a>
|
|
2306
|
+
|
|
2307
|
+
[mdld] <https://mdld.js.org/>
|
|
2308
|
+
[cat] <mdld:shacl/>
|
|
2309
|
+
|
|
2310
|
+
# Qualified Count {=sh:qualifiedMinCount .class:QualifiedConstraint label}
|
|
2311
|
+
|
|
2312
|
+
> Applies count constraints only to values that meet additional shape criteria {comment}
|
|
2313
|
+
|
|
2314
|
+
<http://www.w3.org/ns/shacl#qualifiedMinCount> {?cat:fullIRI}
|
|
2315
|
+
<http://www.w3.org/ns/shacl#qualifiedMaxCount> {?cat:fullIRI}
|
|
2316
|
+
|
|
2317
|
+
---
|
|
2318
|
+
|
|
2319
|
+
## 📋 Quick Start Pattern
|
|
2320
|
+
|
|
2321
|
+
Qualified count constraints apply count constraints only to values that meet additional shape criteria. This example validates that employees must have exactly one work email (matching the WorkEmailShape pattern).
|
|
2322
|
+
|
|
2323
|
+
~~~~~~md
|
|
2324
|
+
[ex] <tag:my@example.org,2026:qualified/>
|
|
2325
|
+
|
|
2326
|
+
## Employee Validation Shape {=ex:EmployeeValidationShape .sh:NodeShape label}
|
|
2327
|
+
|
|
2328
|
+
Validates all [member] {+member ?sh:targetObjectsOf} entities with one work **email** {+#workEmailRule ?sh:property sh:name}.
|
|
2329
|
+
|
|
2330
|
+
**Employee must have exactly one work email** {=#workEmailRule .sh:PropertyShape sh:message} requires [email] {+ex:email ?sh:path} to have exactly [1] {sh:qualifiedMinCount sh:qualifiedMaxCount ^^xsd:integer} work email matching **Work Email Shape** {=ex:WorkEmailShape .sh:NodeShape ?sh:qualifiedValueShape}.
|
|
2331
|
+
|
|
2332
|
+
**Work Email Shape** {=ex:WorkEmailShape .sh:NodeShape} must be a [literal] {+sh:Literal ?sh:nodeKind} with pattern [company.org] {sh:pattern}.
|
|
2333
|
+
|
|
2334
|
+
---
|
|
2335
|
+
|
|
2336
|
+
## Test Data {=ex:data .Container}
|
|
2337
|
+
|
|
2338
|
+
### Valid Employee {=ex:ValidEmployee ?member}
|
|
2339
|
+
Email: [john@company.org] {ex:email}
|
|
2340
|
+
|
|
2341
|
+
### Invalid Employee {=ex:NoWorkEmployee ?member}
|
|
2342
|
+
Email: [bob@gmail.com] {ex:email}
|
|
2343
|
+
~~~~~~
|
|
2344
|
+
|
|
2345
|
+
**Expected Result:** 1 violation (NoWorkEmployee fails because it has 0 work emails - the email doesn't match the WorkEmailShape pattern)
|
|
2346
|
+
|
|
2347
|
+
---
|
|
2348
|
+
|
|
2349
|
+
## 📝 MDLD Syntax Patterns
|
|
2350
|
+
|
|
2351
|
+
~~~~~~md
|
|
2352
|
+
[Property] {+ex:propertyName ?sh:path} must have exactly [count] {sh:qualifiedMinCount sh:qualifiedMaxCount ^^xsd:integer} values that conform to [Shape] {=ex:ShapeName ?sh:qualifiedValueShape}.
|
|
2353
|
+
~~~~~~
|
|
2354
|
+
|
|
2355
|
+
**Use for:** Work email validation, primary contact validation, conditional counting
|
|
2356
|
+
|
|
2357
|
+
**Important:**
|
|
2358
|
+
- Only counts values that conform to the qualified shape
|
|
2359
|
+
- Other values are ignored for the count
|
|
2360
|
+
- Use for conditional validation scenarios
|
|
2361
|
+
|
|
2362
|
+
---
|
|
2363
|
+
|
|
2364
|
+
## 🔧 Implementation Guidelines
|
|
2365
|
+
|
|
2366
|
+
**When to use:** Only certain values should be counted
|
|
2367
|
+
|
|
2368
|
+
**Best practices:**
|
|
2369
|
+
- Define the qualified shape clearly
|
|
2370
|
+
- Test with mixed value scenarios
|
|
2371
|
+
|
|
2372
|
+
**Common pitfalls:**
|
|
2373
|
+
- ❌ Forgetting to define the qualified shape
|
|
2374
|
+
- ❌ Confusing qualified count with regular count
|
|
2375
|
+
|
|
2376
|
+
|
|
2377
|
+
|
|
2378
|
+
|
|
2379
|
+
|
|
2380
|
+
|
|
2381
|
+
{=}
|
|
2382
|
+
|
|
2383
|
+
|
|
2384
|
+
|
|
2385
|
+
<a id="constraints-closed"></a>
|
|
2386
|
+
|
|
2387
|
+
[mdld] <https://mdld.js.org/vocab/>
|
|
2388
|
+
[cat] <https://mdld.js.org/shacl/catalog/>
|
|
2389
|
+
[schema] <http://schema.org/>
|
|
2390
|
+
|
|
2391
|
+
|
|
2392
|
+
# Closed World Constraint {=sh:closed .class:ClosedWorldConstraint label}
|
|
2393
|
+
|
|
2394
|
+
> Enables closed world validation where only explicitly declared properties are allowed. Essential for strict data modeling, schema enforcement, and preventing property proliferation in RDF graphs. {comment}
|
|
2395
|
+
|
|
2396
|
+
<http://www.w3.org/ns/shacl#closed> {?cat:fullIRI}
|
|
2397
|
+
|
|
2398
|
+
---
|
|
2399
|
+
|
|
2400
|
+
## 📋 Quick Start Pattern
|
|
2401
|
+
|
|
2402
|
+
The closed constraint enables closed world validation where only explicitly declared properties are allowed. This example validates that person data can only have declared properties (name, age).
|
|
2403
|
+
|
|
2404
|
+
~~~~~~md
|
|
2405
|
+
[ex] <tag:my@example.org,2026:closed/>
|
|
2406
|
+
[schema] <http://schema.org/>
|
|
2407
|
+
|
|
2408
|
+
## Person Data Demo
|
|
2409
|
+
|
|
2410
|
+
**Only declared properties allowed** {=ex:ClosedExampleShape .sh:NodeShape label} targets [ValidPerson] {+ex:ValidPerson ?sh:targetNode} and [InvalidPerson] {+ex:InvalidPerson ?sh:targetNode} with **no additional properties** {sh:closed} constraint except [Name] {+ex:NameProperty ?sh:property sh:name} and [Age] {+ex:AgeProperty ?sh:property sh:name}.
|
|
2411
|
+
|
|
2412
|
+
**Person must have a name** {=ex:NameProperty .sh:PropertyShape sh:message} ensures [name] {+schema:name ?sh:path} is [string] {+xsd:string ?sh:datatype} and [1] {sh:minCount ^^xsd:integer}.
|
|
2413
|
+
|
|
2414
|
+
**Person must have exactly one age** {=ex:AgeProperty .sh:PropertyShape sh:message} ensures [age] {+ex:age ?sh:path} is [integer] {+xsd:integer ?sh:datatype} and exactly [1] {sh:minCount sh:maxCount ^^xsd:integer}.
|
|
2415
|
+
|
|
2416
|
+
---
|
|
2417
|
+
|
|
2418
|
+
## Test Data {=ex:data .Container}
|
|
2419
|
+
|
|
2420
|
+
### Valid Person {=ex:ValidPerson}
|
|
2421
|
+
|
|
2422
|
+
Person with only declared properties.
|
|
2423
|
+
|
|
2424
|
+
Name: [John Doe] {schema:name ^^xsd:string}
|
|
2425
|
+
Age: [30] {ex:age ^^xsd:integer}
|
|
2426
|
+
|
|
2427
|
+
### Invalid Person {=ex:InvalidPerson}
|
|
2428
|
+
|
|
2429
|
+
Person with undeclared property (violates closed world constraint).
|
|
2430
|
+
|
|
2431
|
+
Name: [Jane Smith] {schema:name ^^xsd:string}
|
|
2432
|
+
Age: [25] {ex:age ^^xsd:integer}
|
|
2433
|
+
Email: [<jane@example.com>] {ex:email}
|
|
2434
|
+
~~~~~~
|
|
2435
|
+
|
|
2436
|
+
**Expected Result:** 1 violation (InvalidPerson fails because it has undeclared email property)
|
|
2437
|
+
|
|
2438
|
+
---
|
|
2439
|
+
|
|
2440
|
+
## 📝 MDLD Syntax Patterns
|
|
2441
|
+
|
|
2442
|
+
The closed constraint enables closed world validation where only explicitly declared properties are allowed.
|
|
2443
|
+
|
|
2444
|
+
~~~~~~md
|
|
2445
|
+
**[Shape] with closed world validation** {=ex:ClosedShape .sh:NodeShape label}
|
|
2446
|
+
|
|
2447
|
+
[Shape Name] {=ex:ShapeName .sh:NodeShape} has **no additional properties** {sh:closed}.
|
|
2448
|
+
~~~~~~
|
|
2449
|
+
|
|
2450
|
+
**Key components:**
|
|
2451
|
+
- **Shape declaration** - The shape to apply closed world validation (`{=ex:ShapeName .sh:NodeShape}`)
|
|
2452
|
+
- **Closed constraint** - Enables closed world validation (`{sh:closed}`)
|
|
2453
|
+
- **Property declarations** - Only declared properties are allowed
|
|
2454
|
+
- **Property shapes** - Define allowed properties with constraints
|
|
2455
|
+
|
|
2456
|
+
**Important notes:**
|
|
2457
|
+
- Only explicitly declared properties are allowed
|
|
2458
|
+
- Undeclared properties cause validation violations
|
|
2459
|
+
- Apply at NodeShape level, not PropertyShape level
|
|
2460
|
+
- Useful for strict data modeling and schema enforcement
|
|
2461
|
+
- Prevents property proliferation in RDF graphs
|
|
2462
|
+
|
|
2463
|
+
---
|
|
2464
|
+
|
|
2465
|
+
## 🎯 Use Cases
|
|
2466
|
+
|
|
2467
|
+
- **Strict data modeling** - Enforce exact schema compliance
|
|
2468
|
+
- **Schema enforcement** - Prevent property proliferation
|
|
2469
|
+
- **Data validation** - Ensure only declared properties exist
|
|
2470
|
+
- **API contracts** - Enforce exact API contract compliance
|
|
2471
|
+
- **Data quality** - Prevent unexpected properties
|
|
2472
|
+
|
|
2473
|
+
---
|
|
2474
|
+
|
|
2475
|
+
## 🔧 Implementation Guidelines
|
|
2476
|
+
|
|
2477
|
+
**When to use closed:**
|
|
2478
|
+
- **Strict schemas** - When exact schema compliance is required
|
|
2479
|
+
- **API contracts** - Enforce exact API contract compliance
|
|
2480
|
+
- **Data quality** - Prevent unexpected properties
|
|
2481
|
+
- **Schema enforcement** - Strict property validation
|
|
2482
|
+
- **Closed world assumptions** - When business logic requires closed world
|
|
2483
|
+
|
|
2484
|
+
**Best practices:**
|
|
2485
|
+
- Declare all required properties explicitly
|
|
2486
|
+
- Combine with property constraints for complete validation
|
|
2487
|
+
- Use descriptive property names for clarity
|
|
2488
|
+
- Test with both valid and invalid data
|
|
2489
|
+
- Document why closed world validation is needed
|
|
2490
|
+
|
|
2491
|
+
**Common pitfalls:**
|
|
2492
|
+
- ❌ Forgetting to declare all required properties
|
|
2493
|
+
- ❌ Using closed when open world is more appropriate
|
|
2494
|
+
- ❌ Not combining with property constraints
|
|
2495
|
+
- ❌ Overusing closed world validation
|
|
2496
|
+
- ❌ Not documenting the closed world assumption
|
|
2497
|
+
|
|
2498
|
+
|
|
2499
|
+
|
|
2500
|
+
|
|
2501
|
+
|
|
2502
|
+
|
|
2503
|
+
{=}
|
|
2504
|
+
|
|
2505
|
+
|
|
2506
|
+
|
|
2507
|
+
<a id="constraints-deactivated"></a>
|
|
2508
|
+
|
|
2509
|
+
[mdld] <https://mdld.js.org/>
|
|
2510
|
+
[cat] <mdld:shacl/>
|
|
2511
|
+
|
|
2512
|
+
# Deactivated {=sh:deactivated .class:DeactivatedConstraint label}
|
|
2513
|
+
|
|
2514
|
+
> Temporarily disables specific constraints during validation {comment}
|
|
2515
|
+
|
|
2516
|
+
<http://www.w3.org/ns/shacl#deactivated> {?cat:fullIRI}
|
|
2517
|
+
|
|
2518
|
+
---
|
|
2519
|
+
|
|
2520
|
+
## 📋 Quick Start Pattern
|
|
2521
|
+
|
|
2522
|
+
The deactivated constraint temporarily disables specific constraints during validation. This example shows a deactivated category rule while the status rule remains active.
|
|
2523
|
+
|
|
2524
|
+
~~~~~~md
|
|
2525
|
+
[ex] <tag:my@example.org,2026:deactivated/>
|
|
2526
|
+
|
|
2527
|
+
## Deactivated Example Shape {=ex:DeactivatedExampleShape .sh:NodeShape label}
|
|
2528
|
+
|
|
2529
|
+
Validates all **member** {+member ?sh:targetObjectsOf} entities to be an active *user* {+ex:ActiveProperty ?sh:property sh:name} and have an active *category* {+ex:CategoryProperty ?sh:property sh:name}.
|
|
2530
|
+
|
|
2531
|
+
**User status must be active** {=ex:ActiveProperty .sh:PropertyShape sh:message} requires [status] {+ex:status ?sh:path} to be [active] {sh:hasValue}.
|
|
2532
|
+
|
|
2533
|
+
**Category rule** {=ex:DeactivatedProperty .sh:PropertyShape sh:message} requires [category] {+ex:category ?sh:path} to be [active] {sh:hasValue}. This rule is temporarily [deactivated] {sh:deactivated}.
|
|
2534
|
+
|
|
2535
|
+
---
|
|
2536
|
+
|
|
2537
|
+
## Test Data {=ex:data .Container}
|
|
2538
|
+
|
|
2539
|
+
### Valid Account {=ex:ValidNode ?member}
|
|
2540
|
+
Status: [active] {ex:status}
|
|
2541
|
+
Category: [active] {ex:status}
|
|
2542
|
+
|
|
2543
|
+
### Invalid Account {=ex:InvalidNode ?member}
|
|
2544
|
+
Status: [inactive] {ex:status}
|
|
2545
|
+
Category: [inactive] {ex:status}
|
|
2546
|
+
~~~~~~
|
|
2547
|
+
|
|
2548
|
+
**Expected Result:** 1 violation (InvalidAccount fails because status is inactive; category rule is deactivated so it doesn't cause a violation)
|
|
2549
|
+
|
|
2550
|
+
---
|
|
2551
|
+
|
|
2552
|
+
## 📝 MDLD Syntax Patterns
|
|
2553
|
+
|
|
2554
|
+
~~~~~~md
|
|
2555
|
+
[Constraint] {=ex:PropertyConstraint .sh:PropertyShape} is [deactivated] {sh:deactivated}.
|
|
2556
|
+
~~~~~~
|
|
2557
|
+
|
|
2558
|
+
**Use for:** Phased validation, conditional rules, schema evolution, testing
|
|
2559
|
+
|
|
2560
|
+
**Important:**
|
|
2561
|
+
- Deactivated constraints are skipped during validation
|
|
2562
|
+
- Useful for temporary constraint disabling
|
|
2563
|
+
- Can be reactivated by removing the flag
|
|
2564
|
+
|
|
2565
|
+
---
|
|
2566
|
+
|
|
2567
|
+
## 🔧 Implementation Guidelines
|
|
2568
|
+
|
|
2569
|
+
**When to use:** Temporarily disable constraints
|
|
2570
|
+
|
|
2571
|
+
**Best practices:**
|
|
2572
|
+
- Document why constraint is deactivated
|
|
2573
|
+
- Plan for reactivation
|
|
2574
|
+
|
|
2575
|
+
**Common pitfalls:**
|
|
2576
|
+
- ❌ Forgetting to reactivate deactivated constraints
|
|
2577
|
+
- ❌ Using deactivated instead of removing obsolete constraints
|
|
2578
|
+
|
|
2579
|
+
|
|
2580
|
+
|
|
2581
|
+
|
|
2582
|
+
|
|
2583
|
+
|
|
2584
|
+
{=}
|
|
2585
|
+
|
|
2586
|
+
|
|
2587
|
+
|
|
2588
|
+
<a id="constraints-severity"></a>
|
|
2589
|
+
|
|
2590
|
+
[mdld] <https://mdld.js.org/vocab/>
|
|
2591
|
+
[cat] <https://mdld.js.org/shacl/catalog/>
|
|
2592
|
+
[ex] <http://example.org/>
|
|
2593
|
+
|
|
2594
|
+
# Severity Levels {=sh:severity .class:SeverityConstraint label}
|
|
2595
|
+
|
|
2596
|
+
> Defines the severity level of validation violations (Info, Warning, Violation). Essential for prioritizing validation results and managing different types of constraint failures. {comment}
|
|
2597
|
+
|
|
2598
|
+
<http://www.w3.org/ns/shacl#severity> {?cat:fullIRI}
|
|
2599
|
+
<http://www.w3.org/ns/shacl#message> {?cat:fullIRI}
|
|
2600
|
+
|
|
2601
|
+
---
|
|
2602
|
+
|
|
2603
|
+
## 📋 Quick Start Pattern
|
|
2604
|
+
|
|
2605
|
+
The severity constraint defines the severity level of validation violations (Info, Warning, Violation). This example demonstrates user account validation with different severity levels for different constraints.
|
|
2606
|
+
|
|
2607
|
+
~~~~~~md
|
|
2608
|
+
[ex] <tag:my@example.org,2026:range/>
|
|
2609
|
+
|
|
2610
|
+
## User Validation Shape {=ex:UserValidationShape .sh:NodeShape label}
|
|
2611
|
+
|
|
2612
|
+
Targets all [users] {+ex:User ?sh:targetClass} to validate account requirements with different severity levels: critical **email** {+ex:CriticalRule ?sh:property sh:name}, warning **age** {+ex:WarningRule ?sh:property sh:name} and info **name** {+ex:InfoNameRule ?sh:property sh:name}.
|
|
2613
|
+
|
|
2614
|
+
**Email address is required and must be valid** {=ex:CriticalRule .sh:PropertyShape sh:message} requires [email] {+ex:email ?sh:path} to be [string] {+xsd:string ?sh:datatype} and at least [1] {sh:minCount ^^xsd:integer} corporate email [example.com] {sh:pattern} with [Violation severity] {+sh:Violation ?sh:severity}.
|
|
2615
|
+
|
|
2616
|
+
**Age should be between 18 and 120** {=ex:WarningRule .sh:PropertyShape sh:message} requires [age] {+ex:age ?sh:path} to be [integer] {+xsd:integer ?sh:datatype}, more than [18] {sh:minInclusive ^^xsd:integer} and less than [120] {sh:maxInclusive ^^xsd:integer} with [Warning severity] {+sh:Warning ?sh:severity}.
|
|
2617
|
+
|
|
2618
|
+
**Name should be a string of 2+ letters** {=ex:InfoNameRule .sh:PropertyShape sh:message} requires [name] {+ex:name ?sh:path} to be [string] {+xsd:string ?sh:datatype} at least [1] {sh:minCount} and longer than [3] {sh:minInclusive} with [Info severity] {+sh:Info ?sh:severity}.
|
|
2619
|
+
|
|
2620
|
+
---
|
|
2621
|
+
|
|
2622
|
+
## Test Data {=ex:data .Container}
|
|
2623
|
+
|
|
2624
|
+
### Valid User {=ex:ValidUser .ex:User}
|
|
2625
|
+
Email: [user@example.com] {ex:email}
|
|
2626
|
+
Age: [25] {ex:age ^^xsd:integer}
|
|
2627
|
+
Name: [John Doe] {ex:name}
|
|
2628
|
+
|
|
2629
|
+
### Invalid User {=ex:InvalidUser .ex:User}
|
|
2630
|
+
Email: [invalid-email] {ex:email}
|
|
2631
|
+
Age: [150] {ex:age ^^xsd:integer}
|
|
2632
|
+
Name: [] {ex:name}
|
|
2633
|
+
~~~~~~
|
|
2634
|
+
|
|
2635
|
+
**Expected Result:** 3 violations (InvalidUser fails three times: Critical for invalid email, Warning for age > 120, Info for missing name)
|
|
2636
|
+
|
|
2637
|
+
---
|
|
2638
|
+
|
|
2639
|
+
## 📝 MDLD Syntax Patterns
|
|
2640
|
+
|
|
2641
|
+
The severity constraint defines the severity level of validation violations.
|
|
2642
|
+
|
|
2643
|
+
~~~~~~md
|
|
2644
|
+
**[Constraint description]** {=ex:PropertyConstraint .sh:PropertyShape sh:message}
|
|
2645
|
+
|
|
2646
|
+
[Property Name] {+ex:propertyName ?sh:path} [constraint description] with [Severity] {+sh:SeverityLevel ?sh:severity}.
|
|
2647
|
+
~~~~~~
|
|
2648
|
+
|
|
2649
|
+
**Key components:**
|
|
2650
|
+
- **Validation message** - Human-readable error message (`{sh:message}`)
|
|
2651
|
+
- **Severity level** - Severity of the violation (`{+sh:Violation ?sh:severity}`, `{+sh:Warning ?sh:severity}`, `{+sh:Info ?sh:severity}`)
|
|
2652
|
+
- **Constraint description** - The constraint being validated
|
|
2653
|
+
- **Priority management** - Helps prioritize validation results
|
|
2654
|
+
- **Categorization** - Manages different types of constraint failures
|
|
2655
|
+
|
|
2656
|
+
**Important notes:**
|
|
2657
|
+
- Use `sh:Violation` for critical failures that must be fixed
|
|
2658
|
+
- Use `sh:Warning` for issues that should be addressed but aren't critical
|
|
2659
|
+
- Use `sh:Info` for informational violations or recommendations
|
|
2660
|
+
- Severity helps prioritize validation results
|
|
2661
|
+
- Combine with message for clear user feedback
|
|
2662
|
+
|
|
2663
|
+
---
|
|
2664
|
+
|
|
2665
|
+
## 🎯 Use Cases
|
|
2666
|
+
|
|
2667
|
+
- **Prioritization** - Prioritize critical vs non-critical issues
|
|
2668
|
+
- **User feedback** - Provide different feedback based on severity
|
|
2669
|
+
- **Compliance** - Distinguish between critical compliance issues and recommendations
|
|
2670
|
+
- **Data quality** - Manage different types of data quality issues
|
|
2671
|
+
- **Workflow management** - Route issues based on severity
|
|
2672
|
+
|
|
2673
|
+
---
|
|
2674
|
+
|
|
2675
|
+
## 🔧 Implementation Guidelines
|
|
2676
|
+
|
|
2677
|
+
**When to use severity:**
|
|
2678
|
+
- **Critical constraints** - Use `sh:Violation` for must-fix issues
|
|
2679
|
+
- **Warnings** - Use `sh:Warning` for should-fix issues
|
|
2680
|
+
- **Informational** - Use `sh:Info` for recommendations
|
|
2681
|
+
- **Prioritization** - Help users prioritize fixes
|
|
2682
|
+
- **Compliance** - Distinguish critical vs non-critical compliance issues
|
|
2683
|
+
|
|
2684
|
+
**Best practices:**
|
|
2685
|
+
- Use severity consistently across constraints
|
|
2686
|
+
- Document why certain constraints have specific severity
|
|
2687
|
+
- Combine with message for clear feedback
|
|
2688
|
+
- Consider user workflow when assigning severity
|
|
2689
|
+
- Test with violations at different severity levels
|
|
2690
|
+
|
|
2691
|
+
**Common pitfalls:**
|
|
2692
|
+
- ❌ Using wrong severity level for the constraint
|
|
2693
|
+
- ❌ Not using severity consistently
|
|
2694
|
+
- ❌ Overusing high severity for minor issues
|
|
2695
|
+
- ❌ Not combining severity with message
|
|
2696
|
+
- ❌ Forgetting to assign severity to constraints
|
|
2697
|
+
|
|
2698
|
+
|
|
2699
|
+
|
|
2700
|
+
|
|
2701
|
+
|
|
2702
|
+
|
|
2703
|
+
{=}
|
|
2704
|
+
|
|
2705
|
+
|
|
2706
|
+
|
|
2707
|
+
<a id="constraints-message"></a>
|
|
2708
|
+
|
|
2709
|
+
[mdld] <https://mdld.js.org/>
|
|
2710
|
+
[cat] <mdld:shacl/>
|
|
2711
|
+
|
|
2712
|
+
# Violation Message {=sh:message .class:MessageConstraint label}
|
|
2713
|
+
|
|
2714
|
+
> Provides human-readable error messages for constraint violations {comment}
|
|
2715
|
+
|
|
2716
|
+
<http://www.w3.org/ns/shacl#message> {?cat:fullIRI}
|
|
2717
|
+
|
|
2718
|
+
---
|
|
2719
|
+
|
|
2720
|
+
## 📋 Quick Start Pattern
|
|
2721
|
+
|
|
2722
|
+
The message constraint provides human-readable error messages for constraint violations. This example shows a custom violation message for contract value validation.
|
|
2723
|
+
|
|
2724
|
+
~~~~~~md
|
|
2725
|
+
[ex] <tag:my@example.org,2026:message/>
|
|
2726
|
+
|
|
2727
|
+
## Business Rule Validation Shape {=ex:BusinessRuleValidationShape .sh:NodeShape label}
|
|
2728
|
+
|
|
2729
|
+
Validates all [member] {+member ?sh:targetObjectsOf} entities with positive **contract** {+ex:ContractValueRule ?sh:property sh:name}.
|
|
2730
|
+
|
|
2731
|
+
**Contract value must be positive** {=ex:ContractValueRule .sh:PropertyShape sh:message} ensures [contract value] {+ex:contractValue ?sh:path} is greater than [0] {sh:minInclusive ^^xsd:decimal}.
|
|
2732
|
+
|
|
2733
|
+
---
|
|
2734
|
+
|
|
2735
|
+
## Test Data {=ex:data .Container}
|
|
2736
|
+
|
|
2737
|
+
### Valid Contract {=ex:ValidContract ?member}
|
|
2738
|
+
Value: [50000.00] {ex:contractValue ^^xsd:decimal}
|
|
2739
|
+
|
|
2740
|
+
### Invalid Contract {=ex:InvalidContract ?member}
|
|
2741
|
+
Value: [-1000.00] {ex:contractValue ^^xsd:decimal}
|
|
2742
|
+
~~~~~~
|
|
2743
|
+
|
|
2744
|
+
**Expected Result:** 1 violation (InvalidContract fails with message "Contract value must be positive")
|
|
2745
|
+
|
|
2746
|
+
---
|
|
2747
|
+
|
|
2748
|
+
## 📝 MDLD Syntax Patterns
|
|
2749
|
+
|
|
2750
|
+
~~~~~~md
|
|
2751
|
+
**[Business rule]** {=ex:PropertyConstraint .sh:PropertyShape sh:message}
|
|
2752
|
+
[Property] {+ex:propertyName ?sh:path} [constraint description].
|
|
2753
|
+
~~~~~~
|
|
2754
|
+
|
|
2755
|
+
**Use for:** User-friendly feedback, debugging, actionable reporting, business context
|
|
2756
|
+
|
|
2757
|
+
**Important:**
|
|
2758
|
+
- Messages should be specific and actionable
|
|
2759
|
+
- Use business terminology, not just technical
|
|
2760
|
+
- Keep messages concise but informative
|
|
2761
|
+
|
|
2762
|
+
---
|
|
2763
|
+
|
|
2764
|
+
## 🔧 Implementation Guidelines
|
|
2765
|
+
|
|
2766
|
+
**When to use:** Always provide messages for user-friendly feedback
|
|
2767
|
+
|
|
2768
|
+
**Best practices:**
|
|
2769
|
+
- Use semantic, business-focused language
|
|
2770
|
+
- Keep messages concise but informative
|
|
2771
|
+
|
|
2772
|
+
**Common pitfalls:**
|
|
2773
|
+
- ❌ Using technical jargon instead of business language
|
|
2774
|
+
- ❌ Writing vague or unclear messages
|
|
2775
|
+
|
|
2776
|
+
|
|
2777
|
+
|
|
2778
|
+
|
|
2779
|
+
|
|
2780
|
+
|
|
2781
|
+
{=}
|
|
2782
|
+
|
|
2783
|
+
|
|
2784
|
+
|
|
2785
|
+
<a id="constraints-js"></a>
|
|
2786
|
+
|
|
2787
|
+
[mdld] <https://mdld.js.org/>
|
|
2788
|
+
[cat] <mdld:shacl/>
|
|
2789
|
+
|
|
2790
|
+
# JavaScript Function {=sh:js .class:Constraint label}
|
|
2791
|
+
|
|
2792
|
+
> Allows custom JavaScript validation functions for complex constraint logic {comment}
|
|
2793
|
+
|
|
2794
|
+
<http://www.w3.org/ns/shacl#js> {?cat:fullIRI}
|
|
2795
|
+
|
|
2796
|
+
---
|
|
2797
|
+
|
|
2798
|
+
## 📋 Quick Start Pattern
|
|
2799
|
+
|
|
2800
|
+
The JavaScript constraint allows custom JavaScript validation functions for complex constraint logic. This example validates that event dates must be valid JavaScript dates.
|
|
2801
|
+
|
|
2802
|
+
~~~~~~md
|
|
2803
|
+
[ex] <tag:my@example.org,2026:js/>
|
|
2804
|
+
|
|
2805
|
+
## Date Validation Shape {=ex:DateValidationShape .sh:NodeShape label}
|
|
2806
|
+
|
|
2807
|
+
Validates all [member] {+member ?sh:targetObjectsOf} entities with valid **date** {+ex:DatePropertyShape ?sh:property sh:name}.
|
|
2808
|
+
|
|
2809
|
+
**Event date must be valid** {=ex:DatePropertyShape .sh:PropertyShape sh:message} requires [eventDate] {+ex:eventDate ?sh:path} to be a valid JS date:
|
|
2810
|
+
|
|
2811
|
+
~~~~~~js {=ex:DateJSConstraint ?sh:JSConstraint sh:js}
|
|
2812
|
+
const date = new Date(value);
|
|
2813
|
+
return !isNaN(date.getTime());
|
|
2814
|
+
~~~~~~
|
|
2815
|
+
|
|
2816
|
+
---
|
|
2817
|
+
|
|
2818
|
+
## Test Data {=ex:data .Container}
|
|
2819
|
+
|
|
2820
|
+
### Valid Event {=ex:ValidEvent ?member}
|
|
2821
|
+
Event Date: [2024-12-25] {ex:eventDate ^^xsd:date}
|
|
2822
|
+
|
|
2823
|
+
### Invalid Event {=ex:InvalidEvent ?member}
|
|
2824
|
+
Event Date: [not-a-date] {ex:eventDate}
|
|
2825
|
+
~~~~~~
|
|
2826
|
+
|
|
2827
|
+
**Expected Result:** 1 violation (InvalidEvent fails because "not-a-date" is not a valid JavaScript date)
|
|
2828
|
+
|
|
2829
|
+
---
|
|
2830
|
+
|
|
2831
|
+
## 📝 MDLD Syntax Patterns
|
|
2832
|
+
|
|
2833
|
+
~~~~~~md
|
|
2834
|
+
[Property] {+ex:propertyName ?sh:path} must pass custom validation.
|
|
2835
|
+
|
|
2836
|
+
~~~~~~js {=ex:JSConstraintName ?sh:JSConstraint sh:js}
|
|
2837
|
+
// Custom validation logic
|
|
2838
|
+
const result = validate(value);
|
|
2839
|
+
return result;
|
|
2840
|
+
~~~~~~
|
|
2841
|
+
~~~~~~
|
|
2842
|
+
|
|
2843
|
+
**Use for:** Custom validation, complex logic, cross-property validation
|
|
2844
|
+
|
|
2845
|
+
**Important:**
|
|
2846
|
+
- JavaScript code is executed during validation
|
|
2847
|
+
- Function receives `value` parameter
|
|
2848
|
+
- Return `true` for valid, `false` for invalid
|
|
2849
|
+
- Use for complex validation not possible with standard constraints
|
|
2850
|
+
|
|
2851
|
+
---
|
|
2852
|
+
|
|
2853
|
+
## 🔧 Implementation Guidelines
|
|
2854
|
+
|
|
2855
|
+
**When to use:** Standard constraints are insufficient
|
|
2856
|
+
|
|
2857
|
+
**Best practices:**
|
|
2858
|
+
- Keep JavaScript functions simple
|
|
2859
|
+
- Test JavaScript functions thoroughly
|
|
2860
|
+
|
|
2861
|
+
**Common pitfalls:**
|
|
2862
|
+
- ❌ Writing overly complex JavaScript functions
|
|
2863
|
+
- ❌ Not testing JavaScript functions thoroughly
|
|
2864
|
+
|
|
2865
|
+
|
|
2866
|
+
|
|
2867
|
+
|
|
2868
|
+
|
|
2869
|
+
|
|
2870
|
+
{=}
|
|
2871
|
+
|
|
2872
|
+
|
|
2873
|
+
|
|
2874
|
+
<a id="teach-choosing-constraints"></a>
|
|
2875
|
+
|
|
2876
|
+
[mdld] <https://mdld.js.org/>
|
|
2877
|
+
[cat] <mdld:shacl/>
|
|
2878
|
+
|
|
2879
|
+
# Choosing the Right Constraint
|
|
2880
|
+
|
|
2881
|
+
> A decision guide for selecting appropriate SHACL constraints for your validation needs {comment}
|
|
2882
|
+
|
|
2883
|
+
## Quick Decision Tree
|
|
2884
|
+
|
|
2885
|
+
**What do you need to validate?**
|
|
2886
|
+
|
|
2887
|
+
### Property Existence
|
|
2888
|
+
- **Property must be present** → Use `sh:minCount` with value `1`
|
|
2889
|
+
- **Property must have exactly one value** → Use both `sh:minCount` and `sh:maxCount` with value `1`
|
|
2890
|
+
- **Property can have multiple values** → Use `sh:maxCount` to set upper limit
|
|
2891
|
+
|
|
2892
|
+
### Property Values
|
|
2893
|
+
- **Value must be a specific constant** → Use `sh:hasValue`
|
|
2894
|
+
- **Value must be from a predefined list** → Use `sh:in` (enumeration)
|
|
2895
|
+
- **Value must be a specific type (IRI)** → Use `sh:class`
|
|
2896
|
+
- **Value must be a specific type (literal)** → Use `sh:datatype`
|
|
2897
|
+
- **Value must be IRI or literal** → Use `sh:nodeKind`
|
|
2898
|
+
|
|
2899
|
+
### Numeric Values
|
|
2900
|
+
- **Value must be within a range** → Use `sh:minInclusive`/`sh:maxInclusive` or `sh:minExclusive`/`sh:maxExclusive`
|
|
2901
|
+
- **Value must be positive** → Use `sh:minInclusive` with `0` or `0.01`
|
|
2902
|
+
- **Value must be less than another property** → Use `sh:lessThan`
|
|
2903
|
+
|
|
2904
|
+
### String Values
|
|
2905
|
+
- **String must have minimum/maximum length** → Use `sh:minLength`/`sh:maxLength`
|
|
2906
|
+
- **String must match a pattern** → Use `sh:pattern`
|
|
2907
|
+
- **String must have specific language tag** → Use `sh:languageIn`
|
|
2908
|
+
|
|
2909
|
+
### Complex Objects
|
|
2910
|
+
- **Property value must conform to a shape** → Use `sh:node` (nested validation)
|
|
2911
|
+
- **Property values must be unique in some way** → Use `sh:qualifiedMinCount`/`sh:qualifiedMaxCount`
|
|
2912
|
+
|
|
2913
|
+
### Relationships Between Properties
|
|
2914
|
+
- **Properties must have disjoint values** → Use `sh:disjoint`
|
|
2915
|
+
- **Properties must be equal** → Use `sh:equals`
|
|
2916
|
+
- **One property must be before another** → Use `sh:lessThan`
|
|
2917
|
+
|
|
2918
|
+
### Logical Combinations
|
|
2919
|
+
- **All conditions must pass** → Use `sh:and`
|
|
2920
|
+
- **Condition must not pass** → Use `sh:not`
|
|
2921
|
+
|
|
2922
|
+
### Metadata
|
|
2923
|
+
- **Add custom error message** → Use `sh:message`
|
|
2924
|
+
- **Set violation severity** → Use `sh:severity`
|
|
2925
|
+
- **Temporarily disable constraint** → Use `sh:deactivated`
|
|
2926
|
+
|
|
2927
|
+
## Common Validation Scenarios
|
|
2928
|
+
|
|
2929
|
+
### Required Field
|
|
2930
|
+
```md
|
|
2931
|
+
[Property] {+ex:propertyName ?sh:path} must have exactly [1] {sh:minCount sh:maxCount ^^xsd:integer} value.
|
|
2932
|
+
```
|
|
2933
|
+
|
|
2934
|
+
### Email Validation
|
|
2935
|
+
```md
|
|
2936
|
+
[Property] {+ex:propertyName ?sh:path} must match [pattern] {sh:pattern}.
|
|
2937
|
+
```
|
|
2938
|
+
|
|
2939
|
+
### Positive Number
|
|
2940
|
+
```md
|
|
2941
|
+
[Property] {+ex:propertyName ?sh:path} must be at least [0] {sh:minInclusive ^^xsd:decimal}.
|
|
2942
|
+
```
|
|
2943
|
+
|
|
2944
|
+
### Enumerated Values
|
|
2945
|
+
```md
|
|
2946
|
+
[Property] {+ex:propertyName ?sh:path} must be in allowed list.
|
|
2947
|
+
**Allowed List** {=ex:list ?sh:in .rdf:List}: [value1] {rdf:first}, then [rest] {=ex:rest ?rdf:rest} by [value2] {rdf:first} and [nil] {+rdf:nil ?rdf:rest}. {=}
|
|
2948
|
+
```
|
|
2949
|
+
|
|
2950
|
+
### Date Range
|
|
2951
|
+
```md
|
|
2952
|
+
[Property] {+ex:propertyName ?sh:path} must be at least [min-date] {sh:minInclusive ^^xsd:date} and at most [max-date] {sh:maxInclusive ^^xsd:date}.
|
|
2953
|
+
```
|
|
2954
|
+
|
|
2955
|
+
## Constraint Groups Reference
|
|
2956
|
+
|
|
2957
|
+
- **Value Type**: class, datatype, nodeKind
|
|
2958
|
+
- **Cardinality**: minCount, maxCount
|
|
2959
|
+
- **Value Range**: minInclusive, maxInclusive, minExclusive, maxExclusive
|
|
2960
|
+
- **String**: minLength, maxLength, pattern, languageIn
|
|
2961
|
+
- **Property Pair**: equals, disjoint, lessThan
|
|
2962
|
+
- **Logical**: and, not
|
|
2963
|
+
- **Shape-based**: node
|
|
2964
|
+
- **Other**: hasValue, in, qualifiedMinCount, qualifiedMaxCount
|
|
2965
|
+
|
|
2966
|
+
See [Constraints](#constraints-index) for detailed documentation on each constraint.
|
|
2967
|
+
|
|
2968
|
+
|
|
2969
|
+
|
|
2970
|
+
|
|
2971
|
+
|
|
2972
|
+
|
|
2973
|
+
{=}
|
|
2974
|
+
|
|
2975
|
+
|
|
2976
|
+
|
|
2977
|
+
<a id="teach-practical-workflow"></a>
|
|
2978
|
+
|
|
2979
|
+
[mdld] <https://mdld.js.org/>
|
|
2980
|
+
[cat] <mdld:shacl/>
|
|
2981
|
+
|
|
2982
|
+
# Practical Workflow: Designing a Complete Shape
|
|
2983
|
+
|
|
2984
|
+
> Step-by-step example of designing a multi-constraint shape for a real-world use case {comment}
|
|
2985
|
+
|
|
2986
|
+
## Use Case: E-Commerce Product Validation
|
|
2987
|
+
|
|
2988
|
+
We need to validate product data with these requirements:
|
|
2989
|
+
- Product must have a name (required)
|
|
2990
|
+
- Product must have a price (required, must be positive)
|
|
2991
|
+
- Product must have a category (must be from allowed list)
|
|
2992
|
+
- Product description is optional but if present must be at least 10 characters
|
|
2993
|
+
- Product SKU must follow pattern "PROD-XXXXX" (5 digits)
|
|
2994
|
+
|
|
2995
|
+
## Step 1: Define the Shape and Target
|
|
2996
|
+
|
|
2997
|
+
~~~~~~md
|
|
2998
|
+
[ex] <tag:my@example.org,2026:product/>
|
|
2999
|
+
|
|
3000
|
+
# Product Validation Shape {=ex:ProductShape .sh:NodeShape label}
|
|
3001
|
+
Validates all [Product] {+ex:Product ?sh:targetClass} instances to have mandatory [name] {+ex:NameRule ?sh:property sh:name}, [price] {+ex:PriceRule ?sh:property sh:name} and [category] {+ex:CategoryRule ?sh:property sh:name} assigned.
|
|
3002
|
+
|
|
3003
|
+
|
|
3004
|
+
~~~~~~
|
|
3005
|
+
|
|
3006
|
+
## Step 2: Add Required Properties
|
|
3007
|
+
|
|
3008
|
+
~~~~~~md
|
|
3009
|
+
[ex] <tag:my@example.org,2026:product/>
|
|
3010
|
+
|
|
3011
|
+
## Product Validation Shape required properties {=ex:ProductShape}
|
|
3012
|
+
|
|
3013
|
+
**Product name is required** {=ex:NameRule .sh:PropertyShape sh:message} requires that [name] {+ex:name ?sh:path} must have exactly [1] {sh:minCount sh:maxCount ^^xsd:integer} value.
|
|
3014
|
+
|
|
3015
|
+
**Product price is required** {=ex:PriceRule .sh:PropertyShape sh:message} requires that [price] {+ex:price ?sh:path} must have exactly [1] {sh:minCount sh:maxCount ^^xsd:integer} value.
|
|
3016
|
+
|
|
3017
|
+
**Product category is required** {=ex:CategoryRule .sh:PropertyShape sh:message} requires that [category] {+ex:category ?sh:path} must have exactly [1] {sh:minCount sh:maxCount ^^xsd:integer} value.
|
|
3018
|
+
~~~~~~
|
|
3019
|
+
|
|
3020
|
+
## Step 3: Add Value Constraints
|
|
3021
|
+
|
|
3022
|
+
~~~~~~md
|
|
3023
|
+
[ex] <tag:my@example.org,2026:product/>
|
|
3024
|
+
|
|
3025
|
+
**Product** {=ex:ProductShape} also must have a positive [price] {+ex:PriceRule ?sh:property sh:name}.
|
|
3026
|
+
|
|
3027
|
+
**Product price must be positive** {=ex:PriceRule .sh:PropertyShape sh:message}: [price] {+ex:price ?sh:path} must be at least [0.01] {sh:minInclusive ^^xsd:decimal}.
|
|
3028
|
+
~~~~~~
|
|
3029
|
+
|
|
3030
|
+
## Step 4: Add Enumeration Constraint
|
|
3031
|
+
|
|
3032
|
+
~~~~~~md
|
|
3033
|
+
[ex] <tag:my@example.org,2026:product/>
|
|
3034
|
+
|
|
3035
|
+
**Product** {=ex:ProductShape} must have an allowed [category] {+ex:CategoryRule ?sh:property sh:name}.
|
|
3036
|
+
|
|
3037
|
+
**Product category must be from allowed list** {=ex:CategoryRule .sh:PropertyShape sh:message}: [category] {+ex:category ?sh:path} must be in **Allowed Categories List** {=ex:cat-l1 ?sh:in .rdf:List}: [Electronics] {rdf:first}, then [followed by] {=ex:cat-l2 ?rdf:rest} by [Clothing] {rdf:first} - [only these] {+rdf:nil ?rdf:rest}. {=}
|
|
3038
|
+
~~~~~~
|
|
3039
|
+
|
|
3040
|
+
## Step 5: Add Optional Property with Conditional Constraint
|
|
3041
|
+
|
|
3042
|
+
~~~~~~md
|
|
3043
|
+
[ex] <tag:my@example.org,2026:product/>
|
|
3044
|
+
|
|
3045
|
+
**Product** {=ex:ProductShape} must have an optional [descripton] {+ex:DescriptionRule ?sh:property sh:name}.
|
|
3046
|
+
|
|
3047
|
+
**Product description is optional** {=ex:DescriptionRule .sh:PropertyShape sh:message}: [description] {+ex:description ?sh:path} must have at least [10] {sh:minLength ^^xsd:integer} characters.
|
|
3048
|
+
~~~~~~
|
|
3049
|
+
|
|
3050
|
+
## Step 6: Add Pattern Constraint
|
|
3051
|
+
|
|
3052
|
+
~~~~~~md
|
|
3053
|
+
[ex] <tag:my@example.org,2026:product/>
|
|
3054
|
+
|
|
3055
|
+
**Product** {=ex:ProductShape} must have an [SKU] {+ex:DescriptioSKURulenRule ?sh:property sh:name}.
|
|
3056
|
+
|
|
3057
|
+
**Product SKU must match pattern** {=ex:SKURule .sh:PropertyShape sh:message}: [sku] {+ex:sku ?sh:path} must match [PROD-\d{5}] {sh:pattern}.
|
|
3058
|
+
~~~~~~
|
|
3059
|
+
|
|
3060
|
+
## Complete Shape
|
|
3061
|
+
|
|
3062
|
+
~~~~~~md
|
|
3063
|
+
[ex] <tag:my@example.org,2026:product/>
|
|
3064
|
+
|
|
3065
|
+
**Product Validation Shape** {=ex:ProductShape .sh:NodeShape label}
|
|
3066
|
+
Validates all [Product] {+ex:Product ?sh:targetClass} instances to have mandatory [name] {+ex:NameRule ?sh:property sh:name}, [price] {+ex:PriceRule ?sh:property sh:name} and [category] {+ex:CategoryRule ?sh:property sh:name} assigned, must have a positive [price] {+ex:PriceRule ?sh:property sh:name}, must have an allowed [category] {+ex:CategoryRule ?sh:property sh:name}, an optional [descripton] {+ex:DescriptionRule ?sh:property sh:name} and a correct [SKU] {+ex:DescriptioSKURulenRule ?sh:property sh:name}.
|
|
3067
|
+
|
|
3068
|
+
**Product name is required** {=ex:NameRule .sh:PropertyShape}
|
|
3069
|
+
[name] {+ex:name ?sh:path} must have exactly [1] {sh:minCount sh:maxCount ^^xsd:integer} value.
|
|
3070
|
+
|
|
3071
|
+
**Product price is required and positive** {=ex:PriceRule .sh:PropertyShape}
|
|
3072
|
+
[price] {+ex:price ?sh:path} must have exactly [1] {sh:minCount sh:maxCount ^^xsd:integer} value and be at least [0.01] {sh:minInclusive ^^xsd:decimal}.
|
|
3073
|
+
|
|
3074
|
+
**Product category is required and from allowed list** {=ex:CategoryRule .sh:PropertyShape}
|
|
3075
|
+
[category] {+ex:category ?sh:path} must have exactly [1] {sh:minCount sh:maxCount ^^xsd:integer} value and be in allowed list.
|
|
3076
|
+
|
|
3077
|
+
**Allowed Categories List** {=ex:cat-l1 ?sh:in .rdf:List}: [Electronics] {rdf:first}, then [rest] {=ex:cat-l2 ?rdf:rest} by [Clothing] {rdf:first} and [nil] {+rdf:nil ?rdf:rest}. {=}
|
|
3078
|
+
|
|
3079
|
+
**Product description is optional but must be 10+ characters** {=ex:DescriptionRule .sh:PropertyShape}
|
|
3080
|
+
[description] {+ex:description ?sh:path} must have at least [10] {sh:minLength ^^xsd:integer} characters.
|
|
3081
|
+
|
|
3082
|
+
**Product SKU must match pattern** {=ex:SKURule .sh:PropertyShape}
|
|
3083
|
+
[sku] {+ex:sku ?sh:path} must match [PROD-\d{5}] {sh:pattern}.
|
|
3084
|
+
~~~~~~
|
|
3085
|
+
|
|
3086
|
+
## Test Data
|
|
3087
|
+
|
|
3088
|
+
~~~~~~md
|
|
3089
|
+
### Test Data {=ex:data .Container}
|
|
3090
|
+
|
|
3091
|
+
#### Valid Product {=ex:Laptop .ex:Product ?member}
|
|
3092
|
+
Name: [MacBook Pro] {ex:name}
|
|
3093
|
+
Price: [1299.99] {ex:price ^^xsd:decimal}
|
|
3094
|
+
Category: [Electronics] {ex:category}
|
|
3095
|
+
Description: [High-performance laptop] {ex:description}
|
|
3096
|
+
SKU: [PROD-12345] {ex:sku}
|
|
3097
|
+
|
|
3098
|
+
#### Invalid Product - Missing Name {=ex:InvalidProduct1 .ex:Product ?member}
|
|
3099
|
+
Price: [99.99] {ex:price ^^xsd:decimal}
|
|
3100
|
+
Category: [Clothing] {ex:category}
|
|
3101
|
+
|
|
3102
|
+
#### Invalid Product - Negative Price {=ex:InvalidProduct2 .ex:Product ?member}
|
|
3103
|
+
Name: [T-Shirt] {ex:name}
|
|
3104
|
+
Price: [-10.00] {ex:price ^^xsd:decimal}
|
|
3105
|
+
Category: [Clothing] {ex:category}
|
|
3106
|
+
|
|
3107
|
+
#### Invalid Product - Invalid Category {=ex:InvalidProduct3 .ex:Product ?member}
|
|
3108
|
+
Name: [Shoes] {ex:name}
|
|
3109
|
+
Price: [50.00] {ex:price ^^xsd:decimal}
|
|
3110
|
+
Category: [Books] {ex:category}
|
|
3111
|
+
|
|
3112
|
+
#### Invalid Product - Short Description {=ex:InvalidProduct4 .ex:Product ?member}
|
|
3113
|
+
Name: [Hat] {ex:name}
|
|
3114
|
+
Price: [25.00] {ex:price ^^xsd:decimal}
|
|
3115
|
+
Category: [Clothing] {ex:category}
|
|
3116
|
+
Description: [Small] {ex:description}
|
|
3117
|
+
~~~~~~
|
|
3118
|
+
|
|
3119
|
+
## Key Takeaways
|
|
3120
|
+
|
|
3121
|
+
1. **Start with targeting** - Define which data to validate first
|
|
3122
|
+
2. **Add required properties** - Use minCount/maxCount for required fields
|
|
3123
|
+
3. **Add value constraints** - Apply datatype, range, and pattern constraints
|
|
3124
|
+
4. **Combine constraints** - Multiple constraints can apply to the same property
|
|
3125
|
+
5. **Use RDF lists** - For enumeration (sh:in) and logical combinations (sh:and)
|
|
3126
|
+
6. **Test thoroughly** - Create valid and invalid test cases for each rule
|
|
3127
|
+
7. **Add error messages** - Use sh:message for user-friendly validation feedback
|
|
3128
|
+
|
|
3129
|
+
## Next Steps
|
|
3130
|
+
|
|
3131
|
+
- Explore [Targeting Mechanisms](#targeting-index) for more targeting options
|
|
3132
|
+
- Learn about specific [Constraints](#constraints-index) for detailed constraint patterns
|
|
3133
|
+
|
|
3134
|
+
|
|
3135
|
+
|
|
3136
|
+
|
|
3137
|
+
|
|
3138
|
+
|
|
3139
|
+
{=}
|
|
3140
|
+
|
|
3141
|
+
|
|
3142
|
+
|
|
3143
|
+
<a id="teach-advanced"></a>
|
|
3144
|
+
|
|
3145
|
+
[mdld] <https://mdld.js.org/>
|
|
3146
|
+
[cat] <mdld:shacl/>
|
|
3147
|
+
|
|
3148
|
+
# Advanced Shape Composition Techniques
|
|
3149
|
+
|
|
3150
|
+
> Learn advanced SHACL techniques for complex validation scenarios in MDLD {comment}
|
|
3151
|
+
|
|
3152
|
+
## Overview
|
|
3153
|
+
|
|
3154
|
+
Advanced SHACL techniques enable you to model complex business rules and validation requirements that go beyond simple property constraints. This guide covers shape composition, logical constraints, qualified counting, and proper test data structure.
|
|
3155
|
+
|
|
3156
|
+
## Key Advanced Techniques
|
|
3157
|
+
|
|
3158
|
+
### 1. Shape Composition with sh:node
|
|
3159
|
+
|
|
3160
|
+
Shape composition allows you to reuse validation logic across multiple shapes by referencing one shape within another.
|
|
3161
|
+
|
|
3162
|
+
~~~~~~md
|
|
3163
|
+
**Property must conform to shape** {=ex:PropertyRule .sh:PropertyShape ?sh:property}
|
|
3164
|
+
[propertyName] {+ex:propertyName ?sh:path} must conform to [Target Shape] {+ex:TargetShape ?sh:node}.
|
|
3165
|
+
~~~~~~
|
|
3166
|
+
|
|
3167
|
+
**Use cases:**
|
|
3168
|
+
- Reusing common validation patterns
|
|
3169
|
+
- Nested object validation
|
|
3170
|
+
- Complex type checking
|
|
3171
|
+
|
|
3172
|
+
**Important notes:**
|
|
3173
|
+
- The referenced shape is validated independently
|
|
3174
|
+
- All constraints in the referenced shape apply
|
|
3175
|
+
- Can chain multiple shapes together
|
|
3176
|
+
|
|
3177
|
+
### 2. NOT Constraint (sh:not)
|
|
3178
|
+
|
|
3179
|
+
The NOT constraint prevents data from conforming to a specific shape pattern.
|
|
3180
|
+
|
|
3181
|
+
~~~~~~md
|
|
3182
|
+
**Property must not conform to forbidden shape** {=ex:PropertyRule .sh:PropertyShape ?sh:property}
|
|
3183
|
+
[propertyName] {+ex:propertyName ?sh:path} must not conform to [Forbidden Shape] {+ex:ForbiddenShape ?sh:not}.
|
|
3184
|
+
~~~~~~
|
|
3185
|
+
|
|
3186
|
+
**Use cases:**
|
|
3187
|
+
- Forbidden status values
|
|
3188
|
+
- Preventing certain data patterns
|
|
3189
|
+
- Business rule enforcement
|
|
3190
|
+
|
|
3191
|
+
**Example:**
|
|
3192
|
+
```md
|
|
3193
|
+
**Employee status cannot be terminated** {=ex:StatusRule .sh:PropertyShape ?sh:property}
|
|
3194
|
+
Employee status must not conform to [Terminated Status Shape] {+ex:TerminatedStatusShape ?sh:not}.
|
|
3195
|
+
```
|
|
3196
|
+
|
|
3197
|
+
### 3. Qualified Count Constraints
|
|
3198
|
+
|
|
3199
|
+
Qualified count constraints allow you to count only values that conform to a specific shape, enabling conditional counting.
|
|
3200
|
+
|
|
3201
|
+
~~~~~~md
|
|
3202
|
+
**Property must have N values conforming to shape** {=ex:PropertyRule .sh:PropertyShape ?sh:property}
|
|
3203
|
+
[propertyName] {+ex:propertyName ?sh:path} must have at least [N] {sh:qualifiedMinCount ^^xsd:integer} values that conform to [Qualified Shape] {=ex:QualifiedShape .sh:NodeShape ?sh:qualifiedValueShape}.
|
|
3204
|
+
~~~~~~
|
|
3205
|
+
|
|
3206
|
+
**Use cases:**
|
|
3207
|
+
- Counting only active items
|
|
3208
|
+
- Conditional validation based on subset
|
|
3209
|
+
- Business rules with exceptions
|
|
3210
|
+
|
|
3211
|
+
**Example:**
|
|
3212
|
+
```md
|
|
3213
|
+
**Employee must have at least 2 completed projects** {=ex:ProjectsRule .sh:PropertyShape ?sh:property}
|
|
3214
|
+
[projects] {+ex:projects ?sh:path} must have at least [2] {sh:qualifiedMinCount ^^xsd:integer} values that conform to [Completed Project Shape] {=ex:CompletedProjectShape .sh:NodeShape ?sh:qualifiedValueShape}.
|
|
3215
|
+
```
|
|
3216
|
+
|
|
3217
|
+
### 4. Multiple Constraints on Same Property
|
|
3218
|
+
|
|
3219
|
+
You can apply multiple constraints to the same property by combining them in a single rule.
|
|
3220
|
+
|
|
3221
|
+
~~~~~~md
|
|
3222
|
+
**Property with multiple constraints** {=ex:PropertyRule .sh:PropertyShape ?sh:property}
|
|
3223
|
+
[propertyName] {+ex:propertyName ?sh:path} must have exactly [1] {sh:minCount sh:maxCount ^^xsd:integer} value and be at least [0.01] {sh:minInclusive ^^xsd:decimal}.
|
|
3224
|
+
~~~~~~
|
|
3225
|
+
|
|
3226
|
+
**Use cases:**
|
|
3227
|
+
- Combining cardinality with value constraints
|
|
3228
|
+
- Multi-factor validation rules
|
|
3229
|
+
- Complex business requirements
|
|
3230
|
+
|
|
3231
|
+
### 5. Proper Test Data Structure
|
|
3232
|
+
|
|
3233
|
+
When testing advanced shapes with nested objects, use subject chaining to create proper test data.
|
|
3234
|
+
|
|
3235
|
+
~~~~~~md
|
|
3236
|
+
#### Parent Entity {=ex:Parent1 .ex:Parent ?member}
|
|
3237
|
+
Property: [value1] {+ex:Child1 ?ex:property} and [value2] {+ex:Child2 ?ex:property}
|
|
3238
|
+
|
|
3239
|
+
##### Child 1 {=ex:Child1 .ex:Child}
|
|
3240
|
+
Status: [active] {ex:status}
|
|
3241
|
+
|
|
3242
|
+
##### Child 2 {=ex:Child2 .ex:Child}
|
|
3243
|
+
Status: [active] {ex:status}
|
|
3244
|
+
~~~~~~
|
|
3245
|
+
|
|
3246
|
+
**Key pattern:**
|
|
3247
|
+
```
|
|
3248
|
+
- Use `[literal] {+ex:Identifier ?property}` to link to nested objects
|
|
3249
|
+
- Use `#####` headings to define nested objects with `{=ex:Identifier .ex:Class}`
|
|
3250
|
+
- Use `and` to chain multiple values
|
|
3251
|
+
```
|
|
3252
|
+
|
|
3253
|
+
## Complete Example
|
|
3254
|
+
|
|
3255
|
+
The following example demonstrates multiple advanced techniques in a single validation scenario:
|
|
3256
|
+
|
|
3257
|
+
~~~~~~md
|
|
3258
|
+
[ex] <tag:my@example.org,2026:advanced/>
|
|
3259
|
+
|
|
3260
|
+
## Employee Validation Shape {=ex:EmployeeValidationShape .sh:NodeShape label}
|
|
3261
|
+
|
|
3262
|
+
Validates all [Employee] {+ex:Employee ?sh:targetClass} instances with comprehensive business rules: [department] {+ex:DepartmentRule ?sh:property sh:name}, [status] {+ex:StatusRule ?sh:property sh:name}, [projects] {+ex:ProjectsRule ?sh:property sh:name}, [salary] {+ex:SalaryRule ?sh:property sh:name}.
|
|
3263
|
+
|
|
3264
|
+
### Property Rules
|
|
3265
|
+
|
|
3266
|
+
**Employee must have valid department** {=ex:DepartmentRule .sh:PropertyShape} requires [department] {+ex:department ?sh:path} must have exactly [1] {sh:minCount sh:maxCount ^^xsd:integer} value and must be in **Allowed Departments List** {=ex:dept-l1 ?sh:in .rdf:List}: [Engineering] {rdf:first}, then [rest] {=ex:dept-l2 ?rdf:rest} by [Sales] {rdf:first} and [nil] {+rdf:nil ?rdf:rest}. {=}
|
|
3267
|
+
|
|
3268
|
+
**Employee status cannot be terminated** {=ex:StatusRule .sh:PropertyShape sh:message}: Employee status must not conform to [Terminated Status Shape] {+ex:TerminatedStatusShape ?sh:not}.
|
|
3269
|
+
|
|
3270
|
+
**Employee must have at least 2 completed projects** {=ex:ProjectsRule .sh:PropertyShape sh:message}: [projects] {+ex:projects ?sh:path} must have at least [2] {sh:qualifiedMinCount ^^xsd:integer} values that conform to [Completed Project Shape] {=ex:CompletedProjectShape .sh:NodeShape ?sh:qualifiedValueShape}.
|
|
3271
|
+
|
|
3272
|
+
**Salary must be positive** {=ex:SalaryRule .sh:PropertyShape sh:message}: [salary] {+ex:salary ?sh:path} must be at least [0.01] {sh:minInclusive ^^xsd:decimal}.
|
|
3273
|
+
|
|
3274
|
+
---
|
|
3275
|
+
|
|
3276
|
+
## Terminated Status Shape {=ex:TerminatedStatusShape .sh:NodeShape label}
|
|
3277
|
+
Defines the forbidden terminated [status] {+ex:TerminatedStatusRule ?sh:property sh:name} pattern.
|
|
3278
|
+
|
|
3279
|
+
**Status must be terminated** {=ex:TerminatedStatusRule .sh:PropertyShape sh:message}: [status] {+ex:status ?sh:path} must be exactly [terminated] {sh:hasValue}.
|
|
3280
|
+
|
|
3281
|
+
---
|
|
3282
|
+
|
|
3283
|
+
## Completed Project Shape {=ex:CompletedProjectShape .sh:NodeShape label}
|
|
3284
|
+
|
|
3285
|
+
Validates completed projects to have completed [status] {+ex:ProjectStatusRule ?sh:property sh:name} and positive [budget] {+ex:ProjectBudgetRule ?sh:property sh:name}.
|
|
3286
|
+
|
|
3287
|
+
**Project must be completed** {=ex:ProjectStatusRule .sh:PropertyShape sh:message}: [status] {+ex:status ?sh:path} must be exactly [completed] {sh:hasValue}.
|
|
3288
|
+
|
|
3289
|
+
**Project must have positive budget** {=ex:ProjectBudgetRule .sh:PropertyShape sh:message}: [budget] {+ex:budget ?sh:path} must be at least [0.01] {sh:minInclusive ^^xsd:decimal}.
|
|
3290
|
+
|
|
3291
|
+
---
|
|
3292
|
+
|
|
3293
|
+
## Test Data {=ex:data .Container}
|
|
3294
|
+
|
|
3295
|
+
### Valid Employee {=ex:Employee1 .ex:Employee ?member}
|
|
3296
|
+
Department: [Engineering] {ex:department}
|
|
3297
|
+
Status: [active] {ex:status}
|
|
3298
|
+
Salary: [75000.00] {ex:salary ^^xsd:decimal}
|
|
3299
|
+
Projects: [project1] {+ex:Project1 ?ex:projects} and [project2] {+ex:Project2 ?ex:projects}
|
|
3300
|
+
|
|
3301
|
+
##### Project 1 {=ex:Project1 .ex:Project}
|
|
3302
|
+
Status: [completed] {ex:status}
|
|
3303
|
+
Budget: [50000.00] {ex:budget ^^xsd:decimal}
|
|
3304
|
+
|
|
3305
|
+
##### Project 2 {=ex:Project2 .ex:Project}
|
|
3306
|
+
Status: [completed] {ex:status}
|
|
3307
|
+
Budget: [30000.00] {ex:budget ^^xsd:decimal}
|
|
3308
|
+
|
|
3309
|
+
### Invalid Employee - Invalid Department {=ex:Employee2 .ex:Employee ?member}
|
|
3310
|
+
Department: [invalid-dept] {ex:department}
|
|
3311
|
+
Status: [active] {ex:status}
|
|
3312
|
+
Salary: [65000.00] {ex:salary ^^xsd:decimal}
|
|
3313
|
+
Projects: [project3] {+ex:Project3 ?ex:projects} and [project3b] {+ex:Project3b ?ex:projects}
|
|
3314
|
+
|
|
3315
|
+
##### Project 3 {=ex:Project3 .ex:Project}
|
|
3316
|
+
Status: [completed] {ex:status}
|
|
3317
|
+
Budget: [40000.00] {ex:budget ^^xsd:decimal}
|
|
3318
|
+
|
|
3319
|
+
##### Project 3b {=ex:Project3b .ex:Project}
|
|
3320
|
+
Status: [completed] {ex:status}
|
|
3321
|
+
Budget: [20000.00] {ex:budget ^^xsd:decimal}
|
|
3322
|
+
|
|
3323
|
+
### Invalid Employee - Terminated Status {=ex:Employee3 .ex:Employee ?member}
|
|
3324
|
+
Department: [Engineering] {ex:department}
|
|
3325
|
+
Status: [terminated] {ex:status}
|
|
3326
|
+
Salary: [60000.00] {ex:salary ^^xsd:decimal}
|
|
3327
|
+
Projects: [project4] {+ex:Project4 ?ex:projects} and [project4b] {+ex:Project4b ?ex:projects}
|
|
3328
|
+
|
|
3329
|
+
##### Project 4 {=ex:Project4 .ex:Project}
|
|
3330
|
+
Status: [completed] {ex:status}
|
|
3331
|
+
Budget: [35000.00] {ex:budget ^^xsd:decimal}
|
|
3332
|
+
|
|
3333
|
+
##### Project 4b {=ex:Project4b .ex:Project}
|
|
3334
|
+
Status: [completed] {ex:status}
|
|
3335
|
+
Budget: [15000.00] {ex:budget ^^xsd:decimal}
|
|
3336
|
+
|
|
3337
|
+
### Invalid Employee - Insufficient Completed Projects {=ex:Employee4 .ex:Employee ?member}
|
|
3338
|
+
Department: [Engineering] {ex:department}
|
|
3339
|
+
Status: [active] {ex:status}
|
|
3340
|
+
Salary: [70000.00] {ex:salary ^^xsd:decimal}
|
|
3341
|
+
Projects: [project5] {+ex:Project5 ?ex:projects}
|
|
3342
|
+
|
|
3343
|
+
##### Project 5 {=ex:Project5 .ex:Project}
|
|
3344
|
+
Status: [completed] {ex:status}
|
|
3345
|
+
Budget: [45000.00] {ex:budget ^^xsd:decimal}
|
|
3346
|
+
|
|
3347
|
+
### Invalid Employee - Negative Salary {=ex:Employee5 .ex:Employee ?member}
|
|
3348
|
+
Department: [Engineering] {ex:department}
|
|
3349
|
+
Status: [active] {ex:status}
|
|
3350
|
+
Salary: [-1000.00] {ex:salary ^^xsd:decimal}
|
|
3351
|
+
Projects: [project6] {+ex:Project6 ?ex:projects} and [project6b] {+ex:Project6b ?ex:projects}
|
|
3352
|
+
|
|
3353
|
+
##### Project 6 {=ex:Project6 .ex:Project}
|
|
3354
|
+
Status: [completed] {ex:status}
|
|
3355
|
+
Budget: [20000.00] {ex:budget ^^xsd:decimal}
|
|
3356
|
+
|
|
3357
|
+
##### Project 6b {=ex:Project6b .ex:Project}
|
|
3358
|
+
Status: [completed] {ex:status}
|
|
3359
|
+
Budget: [15000.00] {ex:budget ^^xsd:decimal}
|
|
3360
|
+
~~~~~~
|
|
3361
|
+
|
|
3362
|
+
**Expected Result:** 4 violations (Employee2 fails: invalid department; Employee3 fails: terminated status (NOT constraint); Employee4 fails: only 1 completed project, needs 2; Employee5 fails: negative salary; Employee1 passes)
|
|
3363
|
+
|
|
3364
|
+
## Best Practices
|
|
3365
|
+
|
|
3366
|
+
**Shape Composition:**
|
|
3367
|
+
- Create reusable shapes for common validation patterns
|
|
3368
|
+
- Keep shapes focused and single-purpose
|
|
3369
|
+
- Document shape dependencies clearly
|
|
3370
|
+
|
|
3371
|
+
**NOT Constraint:**
|
|
3372
|
+
- Use for forbidden patterns rather than negative conditions
|
|
3373
|
+
- Combine with other constraints for comprehensive rules
|
|
3374
|
+
- Test with both valid and invalid cases
|
|
3375
|
+
|
|
3376
|
+
**Qualified Count:**
|
|
3377
|
+
- Define clear criteria for qualified values
|
|
3378
|
+
- Test boundary conditions (0, 1, N values)
|
|
3379
|
+
- Consider performance implications for large datasets
|
|
3380
|
+
|
|
3381
|
+
**Test Data:**
|
|
3382
|
+
- Always include valid test cases
|
|
3383
|
+
- Test each constraint independently
|
|
3384
|
+
- Use descriptive test case names
|
|
3385
|
+
- Structure nested data with proper subject chaining
|
|
3386
|
+
|
|
3387
|
+
## Common Pitfalls
|
|
3388
|
+
|
|
3389
|
+
- **Shape cycles** - Avoid circular shape references
|
|
3390
|
+
- **Over-composition** - Don't nest shapes too deeply
|
|
3391
|
+
- **Ambiguous constraints** - Ensure constraints are clear and specific
|
|
3392
|
+
- **Incomplete test coverage** - Test all constraint combinations
|
|
3393
|
+
- **Incorrect subject chaining** - Use proper syntax for nested objects
|
|
3394
|
+
|
|
3395
|
+
## Next Steps
|
|
3396
|
+
|
|
3397
|
+
|
|
3398
|
+
- Explore [Constraints](#constraints-index) for detailed constraint patterns
|
|
3399
|
+
- Learn about [Targeting Mechanisms](#targeting-index) for data selection
|