Self-validating semantic documentation - Author SHACL constraints in human-readable Markdown while maintaining full W3C standards compliance

The MDLD Shapes catalog is a breakthrough proof-of-concept that demonstrates how MDLD (Markdown Linked Data) enables semantic knowledge authoring where:

• 📚 Documentation = Validation Rules - No more separation between human docs and machine validation
• 🎯 W3C Standards Aligned - Full SHACL specification compliance with RDF export
• 🔧 Production Ready - Comprehensive constraint catalog with clean ontology separation
• 📖 Educational - Learn SHACL through interactive, self-documenting examples

• 23 constraint types with working examples
• 75% SHACL specification coverage including value types, cardinality, ranges, patterns
• Live validation with expected violation counts
• Real-world use cases from e-commerce, healthcare, finance

# Class Constraint {=sh:class .class:Constraint label}
> Expects each value to be an instance of a specific class {comment}

**Employee manager must be a Person instance** {=#managerClass .sh:PropertyShape message} 
requires the [manager] {+ex:manager ?sh:path} property to be an instance of [Person] {+ex:Person ?sh:class}.

• ig-cli - Command-line validation and querying
• Intelligraphs - Visual graph exploration
• RDF Export - Standard Turtle/JSON-LD output
• SPARQL Support - Query your validation rules

• Sidecar organization - Ontology (.md) and demo (.demo.md) files in same folders
• 23 constraint types with working examples and test data
• 75% SHACL specification coverage including value types, cardinality, ranges, patterns
• 4 targeting mechanisms for flexible validation
• Clean ontology assembly - 0 violations (production-ready)
• Demo assembly - 103+ violations (development/testing)

git clone https://github.com/davay42/mdld-shapes.git
cd mdld-shapes
curl -O https://app.intelligraphs.com/ig-cli.js
chmod +x ig-cli.js
mv ig-cli.js /usr/local/bin/ig-cli

# Explore the catalog
ig-cli stats
ig-cli validate ./constraints/class.demo.md
ig-cli get entity https://mdld.js.org/shacl/example/class/InvalidEmployee

👉 Open in Intelligraphs App

The catalog uses a sidecar file organization where ontology and demo content are kept together in the same folders:

mdld-shapes/
├── constraints/
│   ├── class.md              # Ontology: constraint definition
│   ├── class.demo.md         # Demo: test data and violations
│   ├── datatype.md           # Ontology
│   ├── datatype.demo.md      # Demo
│   └── ...
├── targeting/
│   ├── targetClass.md        # Ontology
│   ├── targetClass.demo.md   # Demo
│   └── ...
├── index.md                 # Main catalog (links to both)
├── index.ontology.md        # Ontology-only catalog
├── index.demo.md            # Demo-only catalog
└── assemble.js              # Unified assembly script (all/ontology/demo modes)

• shacl.md - Complete catalog (ontology + demo data) - 162+ violations
• shacl-ontology.md - Clean ontology only - 0 violations (production-ready)
• shacl-demo.md - Demo data only - 103+ violations (development/testing)

• assemble.js - Automatically assembles all 3 catalogs:

  node assemble.js  # Assembles all: shacl.md, shacl-ontology.md, shacl-demo.md

Complete guide to all SHACL constraints and targeting mechanisms

Validation rules organized by category:

• Value Type - Class, DataType, NodeKind
• Cardinality - Min/Max count validation
• String-based - Patterns, Length, Language
• Logical - AND, NOT constraints
• Range - Numeric/Date boundaries
• Advanced - Node, Qualified, JavaScript

Select which nodes to validate:

• Target Class - Validate all instances of a type
• Target Node - Validate specific nodes
• Target Subjects/Objects - Validate by property relationships

# Assemble all catalogs automatically
node assemble.js
# Produces: shacl.md, shacl-ontology.md, shacl-demo.md

# Test individual demo files
ig-cli validate ./constraints/class.demo.md
ig-cli validate ./targeting/targetClass.demo.md

# Validate assembled demo catalog
ig-cli validate ./shacl-demo.md

# Validate clean ontology (should have 0 violations)
ig-cli validate ./shacl.md

# Get detailed entity information
ig-cli get entity https://mdld.js.org/shacl/example/class/InvalidEmployee

# List all SHACL shapes
ig-cli shapes

# Find all constraint types
ig-cli types | grep "Constraint"

# Export to standard RDF formats
ig-cli dump --format=ttl > shapes.ttl

# Product validation with price ranges and required fields
{+schema:Product ?sh:targetClass}
**Product price must be between $10.00 and $1000.00** {sh:message}

# Patient data validation with HIPAA compliance
{+medical:Patient ?sh:targetClass}
**Patient records must have valid medical IDs** {sh:message}

# Transaction validation with audit requirements
{+financial:Transaction ?sh:targetClass}
**All transactions must be auditable** {sh:message}

• Value Type Constraints ✅
• Cardinality Constraints ✅
• String Constraints ✅
• Range Constraints ✅
• Logical Constraints (AND/NOT) ✅
• Targeting Mechanisms ✅

• Logical OR/XONE constraints
• Property path constraints
• JavaScript/SPARQL constraints
• Advanced qualified constraints

• Complete 100% SHACL specification coverage
• Performance optimization for large datasets
• Enhanced error reporting and debugging
• Integration with popular RDF stores
• Visual constraint editor
• Automated constraint generation from schemas

• ✅ Sidecar organization - Restructured from separate ontology/demo folders to sidecar files (.md + .demo.md)
• ✅ Clean ontology - Assembly produces 0 violations, safe for production use
• ✅ Fixed RDF list collisions - Unique identifiers prevent assembly conflicts
• ✅ Separated concerns - Ontology definitions and test data now properly separated

• Main files (.md) - Ontology definitions, syntax patterns, use cases
• Demo files (.demo.md) - Test data, shapes, expected violations, validation commands
• Assembly scripts - Separate scripts for ontology-only and demo-only assemblies
• Index files - Different entry points for different assembly needs

• ✅ Ontology assembly - 0 violations (clean, production-ready)
• ✅ Demo assembly - 103+ violations (comprehensive test coverage)
• ✅ Individual demos - All demo files validate correctly
• ✅ Complete assembly - 162+ violations (combined reference)

git clone https://github.com/davay42/mdld-shapes.git
cd mdld-shapes
# Add your constraint examples
# Test with ig-cli validate
# Submit pull request

• MDLD Specification - Markdown Linked Data format
• SHACL W3C Recommendation - Shapes Constraint Language
• Intelligraphs Platform - Visual semantic web tools
• ig-cli Documentation - Command-line RDF tools

🎯 Transform how you author semantic validation rules - Write once, validate everywhere, learn continuously.