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.
Files changed (59) hide show
  1. package/README.md +34 -1
  2. package/dist/.nojekyll +0 -0
  3. package/dist/CNAME +1 -0
  4. package/dist/README.md +425 -0
  5. package/dist/docs/API.md +397 -0
  6. package/dist/docs/Architecture.md +190 -0
  7. package/dist/docs/Guide.md +322 -0
  8. package/dist/docs/LLM-MDLD-Inducer.md +550 -0
  9. package/dist/docs/Parser.md +654 -0
  10. package/dist/docs/Performance.md +238 -0
  11. package/dist/docs/Spec-render.md +1439 -0
  12. package/dist/docs/Subject.md +180 -0
  13. package/dist/docs/Syntax.md +463 -0
  14. package/dist/docs/TodoList.md +215 -0
  15. package/dist/docs/Use-Cases.md +354 -0
  16. package/dist/docs/index.html +108 -0
  17. package/dist/docs/index.md +56 -0
  18. package/dist/docs/origin.md +459 -0
  19. package/dist/docs/polarity.md +586 -0
  20. package/dist/docs/primary-subject.md +199 -0
  21. package/dist/docs/statements.md +226 -0
  22. package/dist/docs/tokenization-performance-report.md +164 -0
  23. package/dist/examples/Cookbook.md +32 -0
  24. package/dist/examples/Status-SHACL.md +33 -0
  25. package/dist/examples/demo/index.md +35 -0
  26. package/dist/examples/demo/journal.md +18 -0
  27. package/dist/examples/demo/minimal.md +11 -0
  28. package/dist/examples/demo/project.md +15 -0
  29. package/dist/examples/demo/recipe.md +31 -0
  30. package/dist/examples/demo/research.md +46 -0
  31. package/dist/examples/demo/space-mission.md +48 -0
  32. package/dist/examples/dogfood.md +288 -0
  33. package/dist/examples/few-shot.md +309 -0
  34. package/dist/examples/graph/rdf-graph.html +473 -0
  35. package/dist/examples/graph/rdf_force_graph_web_component.html +506 -0
  36. package/dist/examples/index.md +45 -0
  37. package/dist/examples/llm-time-workflow.md +173 -0
  38. package/dist/examples/prov-o.md +2367 -0
  39. package/dist/examples/rdf.md +827 -0
  40. package/dist/examples/shacl.md +3399 -0
  41. package/dist/examples/statements.md +43 -0
  42. package/dist/examples/workflow.md +150 -0
  43. package/dist/index.html +2827 -0
  44. package/dist/index.js +1548 -0
  45. package/dist/logo.svg +7 -0
  46. package/dist/spec/Spec-compact.md +363 -0
  47. package/dist/spec/Spec-ultra.md +221 -0
  48. package/dist/spec/Spec.md +1068 -0
  49. package/dist/spec/index.md +46 -0
  50. package/package.json +13 -8
  51. package/src/constants.js +0 -31
  52. package/src/generate.js +0 -245
  53. package/src/index.js +0 -13
  54. package/src/locate.js +0 -23
  55. package/src/merge.js +0 -157
  56. package/src/parse.js +0 -765
  57. package/src/render.js +0 -576
  58. package/src/shared.js +0 -577
  59. 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