methodatlas
Session Builder

Plan my session

Plan a concrete work block with agenda, roles, preparation, and a copyable result artifact.

Method sessionHalf day per domain slice (4 h)Workshop or asyncSHACL or ShEx Shapes

Session: Shape-First Modeling

The plan translates the method into a concrete facilitated work block. Your inputs flow directly into the session brief and work artifact.

Derived automatically

Method session with 1-4. The plan uses the existing method logic and the runsheet.

Runsheet
Participation logic
Team round, shared work and alignment

Use the session for shared understanding. Contributions are collected visibly, assumptions are aligned, and open differences remain traceable in the artifact.

Outcome logic
Finish artifact

The session works directly toward SHACL or ShEx Shapes. After the session, the artifact should be shareable, reviewable, or reusable.

  1. 1

    Phase 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. Hint: Trying to model everything at once delivers nothing validatable. Keep the slice small and extend in later iterations.

    FacilitatorSHACL or ShEx Shapes
  2. 2

    Phase 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. Hint: 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.

    FacilitatorValidation Reports
  3. 3

    Phase 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. Hint: 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.

    FacilitatorData Contracts
  4. 4

    Phase 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). Hint: If 30% of sample instances trigger violations, the shape is not production-ready. Either loosen it with rationale or contact the data owner.

    FacilitatorShape Documentation
  5. 5

    Phase 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. Hint: Without CI integration, shapes are leftover cloth. CI must run shapes on every data PR (or ETL run) and enforce broken builds.

    FacilitatorSHACL or ShEx Shapes
  6. 6

    Phase 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. Hint: Shapes as TTL are readable for modelers, not for data producers. Without table documentation, the producer does not understand the contract.

    OwnerValidation Reports
  7. 7

    Publish artifact

    10 min

    Check the artifact for completeness, define location, set version or status, and name review recipients.

    OwnerSHACL or ShEx Shapes
Usable artifact

Session Brief

For invitations, boards, tickets, PR descriptions, or workshop notes.

session-brief.md

Session Brief: Shape-First Modeling

Goal

Artifact: SHACL or ShEx Shapes

Working Question

Which shapes define required properties, data types, cardinalities and relationships so that real data becomes validatable and contracts between producer and consumer are unambiguous?

Context

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.

Setup

  • Format: Method session
  • Duration: Half day per domain slice (4 h)
  • Mode: Workshop or async
  • Participants: 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.
  • Owner: One shapes modeler (lead)
  • Participation mode: Team round, shared work and alignment
  • Outcome logic: Finish artifact

Participation Logic

Use the session for shared understanding. Contributions are collected visibly, assumptions are aligned, and open differences remain traceable in the artifact.

Outcome Logic

The session works directly toward SHACL or ShEx Shapes. After the session, the artifact should be shareable, reviewable, or reusable.

Input

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.

Preparation

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.

Agenda

  1. Phase 1: Prioritize classes (30 min) Owner: Facilitator Action: 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. Hint: Trying to model everything at once delivers nothing validatable. Keep the slice small and extend in later iterations. Output: SHACL or ShEx Shapes

  2. Phase 2: Required properties (60 min per class) Owner: Facilitator Action: Per class: property list with sh:path, sh:datatype, sh:minCount, sh:maxCount, sh:nodeKind. Explicitly mark required properties (minCount 1) as contract anchors. Hint: 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. Output: Validation Reports

  3. Phase 3: Relationships and cardinalities (45 min per class) Owner: Facilitator Action: 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. Hint: 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. Output: Data Contracts

  4. Phase 4: Validate against sample data (30-45 min per class) Owner: Facilitator Action: Run validator against sample data. Review violations: legitimate data error or too-strict shape? Document decision per violation (loosen shape, fix data source, exception). Hint: If 30% of sample instances trigger violations, the shape is not production-ready. Either loosen it with rationale or contact the data owner. Output: Shape Documentation

  5. Phase 5: Version shapes and integrate into pipeline (30 min) Owner: Facilitator Action: 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. Hint: Without CI integration, shapes are leftover cloth. CI must run shapes on every data PR (or ETL run) and enforce broken builds. Output: SHACL or ShEx Shapes

  6. Phase 6: Documentation as data contract (20 min) Owner: Owner Action: 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. Hint: Shapes as TTL are readable for modelers, not for data producers. Without table documentation, the producer does not understand the contract. Output: Validation Reports

  7. Publish artifact (10 min) Owner: Owner Action: Check the artifact for completeness, define location, set version or status, and name review recipients. Output: SHACL or ShEx Shapes

Closeout

  • Update result artifact: SHACL or ShEx Shapes
  • Define location, version, and review recipients.
  • Define owner, next step, and review date.
Usable artifact

Work artifact

Pre-filled starting point based on the matching template.

work-artifact.md

SHACL or ShEx Shapes: Shape-First Modeling

Working Question

Which shapes define required properties, data types, cardinalities and relationships so that real data becomes validatable and contracts between producer and consumer are unambiguous?

Context

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.

Participants

  • Owner: One shapes modeler (lead)
  • Participants: 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.

Input

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.

Template

Shape-First Modeling Working Template

Goal

Modeling approach that defines data shapes and constraints before open ontology semantics.

Context

When and for what do we use this method?

Input

Which data, observations, decisions, or materials are available?

Execution

Short notes along the runsheet.

Output artifacts

  • SHACL or ShEx shapes:
  • Validation reports:
  • Data contracts:
  • Shape documentation:

Assumptions and open questions

  • ...

Decision / next step

Owner, date, and success signal.

Completion Check

  • SHACL or ShEx Shapes is complete enough for review:
  • Location:
  • Version / status:
  • Review by:
  • Next step:

Next Step

  • Review result
  • Mark open questions
  • Schedule review or decision
Template base

Shape-First Modeling Working Template

View templateCompact working template for Shape-First Modeling with context, input, output artifacts, and next step.
markdown

shape-first-modeling-working-template.md

Compact working template for Shape-First Modeling with context, input, output artifacts, and next step.

Shape-First Modeling Working Template

Goal

Modeling approach that defines data shapes and constraints before open ontology semantics.

Context

When and for what do we use this method?

Input

Which data, observations, decisions, or materials are available?

Execution

Short notes along the runsheet.

Output artifacts

  • SHACL or ShEx shapes:
  • Validation reports:
  • Data contracts:
  • Shape documentation:

Assumptions and open questions

  • ...

Decision / next step

Owner, date, and success signal.

Ready to use when
  • Working question, owner, and target artifact are visible.
  • The result fits SHACL or ShEx Shapes.
  • Shapes with their own SemVer (major for breaking contract changes). Each release has a changelog listing loosened/tightened constraints. Migration notes for producers documented.
  • Open questions are noted as follow-ups.
  • The next review or decision point is scheduled.
ProfileRunsheet