What needs to be finished first
A question set with must-have questions and required data per question exists, so shapes can fix the properties needed for answers as constraints.
What needs to be ready before start
Shapes editor (Protégé with SHACL plugin, TopBraid, Stardog Studio) or text editor with Turtle highlighting; SHACL validator (for example pySHACL, Apache Jena SHACL, TopBraid); sample data as Turtle; repo with shapes/ folder; CI validation.
One shapes modeler (lead); one domain expert per class; one data producer (owner of data source) for reality check; one data consumer for expectations on the contract.
Class list with priority; sample data per class (at least 50 instances per top class); known data-quality issues; reuse plan for external vocabularies; license and language.
Half day per domain slice (4 h)
Repo with shapes/, data/ and tests/. Validator integrated into CI. Sample data loaded. One slot per class in the workshop plan, with domain expert available.
The one question this method answers
Which shapes define required properties, data types, cardinalities and relationships so that real data becomes validatable and contracts between producer and consumer are unambiguous?
Marker: Phase
| Step | Duration | Action | Hint |
|---|---|---|---|
1Phase 1: Prioritize classes | 30 min | Select the most important 3-5 node classes for the first slice, based on CQs and data flow. Note owner, sample-data path and known issues per class. | Trying to model everything at once delivers nothing validatable. Keep the slice small and extend in later iterations. |
2Phase 2: Required properties | 60 min per class | Per class: property list with sh:path, sh:datatype, sh:minCount, sh:maxCount, sh:nodeKind. Explicitly mark required properties (minCount 1) as contract anchors. | If required properties appear in less than 80% of real data, either the requirement is wrong or the data source is broken. Clarify before closing. |
3Phase 3: Relationships and cardinalities | 45 min per class | Properties with class range (sh:class) for references. Cardinality per relationship. sh:or for alternative target classes where needed. Explicitly check self-references and cycles. | Cardinality 1..* is often too lax. If no minimum amount is defined, empty lists pass. If the domain requires at least 2, set sh:minCount 2. |
4Phase 4: Validate against sample data | 30-45 min per class | Run validator against sample data. Review violations: legitimate data error or too-strict shape? Document decision per violation (loosen shape, fix data source, exception). | If 30% of sample instances trigger violations, the shape is not production-ready. Either loosen it with rationale or contact the data owner. |
5Phase 5: Version shapes and integrate into pipeline | 30 min | Commit shape file, tag version (for example shapes/v0.3/Service.ttl). Set up CI job that validates on data updates or shape updates. Store validation report as artifact. | Without CI integration, shapes are leftover cloth. CI must run shapes on every data PR (or ETL run) and enforce broken builds. |
6Phase 6: Documentation as data contract | 20 min | Export shape per class as human-readable table (property, required, type, cardinality, note). Store in repo under docs/shapes/. Review with data producers and consumers. | Shapes as TTL are readable for modelers, not for data producers. Without table documentation, the producer does not understand the contract. |
What comes out at the end
shapes/ directory with SHACL or ShEx files per class, validation-report directory, human-readable documentation tables per shape, CI job configuration and changelog for shape versions.
Shapes with their own SemVer (major for breaking contract changes). Each release has a changelog listing loosened/tightened constraints. Migration notes for producers documented.
Compact working template for Shape-First Modeling with context, input, output artifacts, and next step.
Modeling approach that defines data shapes and constraints before open ontology semantics.
When and for what do we use this method?
Which data, observations, decisions, or materials are available?
Short notes along the runsheet.
Owner, date, and success signal.
Concrete filled scenario, fictional example
Concrete filled scenario, fictional example
Example SHACL (excerpt):
:ServiceShape a sh:NodeShape ;
sh:targetClass :Service ;
sh:property [ sh:path :name ; sh:datatype xsd:string ; sh:minCount 1 ; sh:maxCount 1 ] ;
sh:property [ sh:path :tier ; sh:in ("critical" "standard" "experimental") ; sh:minCount 1 ] ;
sh:property [ sh:path :owner ; sh:class :Team ; sh:minCount 1 ; sh:maxCount 1 ] ;
sh:property [ sh:path :dependsOn ; sh:class :Service ; sh:minCount 0 ] .
Validation report (sample data as of 2026-05-18):
Documentation table (excerpt):
| Property | Required | Type | Cardinality | Note |
|---|---|---|---|---|
| name | yes | string | 1..1 | Unique, kebab-case |
| tier | yes | enum | 1..1 | critical / standard / experimental |
Maintenance: Owner @marcus, quarterly review. Breaking-change notice period 60 days after announcement.
Recognize symptoms and steer against them
Shapes are modeled without validating sample data, validation reports only appear in production.
Validate every shape iteration immediately against at least 50 real instances. Violations are learning data, not bug reports.
More than 30% of sample data triggers violations, ETL pipeline breaks in production.
Use strict constraints in several severities (sh:Violation, sh:Warning, sh:Info). Start as warning, then tighten in later release.
TTL files exist, but data producers do not understand the contract and keep delivering the wrong format.
Shape-to-table generator (for example SHACL Play or custom script) in CI. Documentation PR is mandatory for shape changes.
Shapes exist, but nobody checks data PRs against them. Violations land in production.
CI job that runs validator on every data or shape PR. Failed validation = blocked PR. Shape changes require migration notes.
Producer and consumer work with different shape versions, nobody knows which one applies.
SemVer for shapes, version IRI in every shape file. Producers pin a concrete version, update as deliberate step.
Shapes check only type and cardinality, not allowed values. Producer sends status "prod" instead of "production".
Use value lists (sh:in) and patterns (sh:pattern) consistently where values are bounded. ETL mappings where needed, but not instead of shape.
Done signals checkable in under a minute
Go to the profile for purpose, similar methods, and sources or continue to the next method in the catalog.