Skip to content

Architecture Practice from Scratch — Part 6: Formal Governance & Validation

Part 5 produced the formal metamodel — OWL classes, SKOS vocabularies, viewpoint definitions. That tells tools what's possible. This part adds what's required: SHACL shapes that encode the governance rules from Part 4 as machine-enforceable constraints.

The result is an architecture practice that validates itself.

The series:

  1. Stakeholder Discovery & Viewpoint Elicitation
  2. Structuring Requirements into Viewpoints & Artifact Types
  3. Metamodel Conceptualized
  4. Governance & Lifecycle Management
  5. Formal Metamodel Definition
  6. Formal Governance & Validation ← you are here
  7. Tool Integration (upcoming)

What We're Producing

  1. SHACL shapes file (acme-shapes.ttl) — completeness, consistency, and governance constraints
  2. Severity mapping — governance gates → SHACL severity levels
  3. SPARQL governance queries — staleness detection, coverage analysis, compliance checks
  4. CI/CD integration pattern — validation on every commit

The Severity Model

Part 2 defined three completeness levels. Part 4 mapped them to quality gates. Now we map them to SHACL:

Completeness Level Quality Gate SHACL Severity Meaning
Minimum Viable Blocks submission sh:Violation Must fix before the artifact can enter review
Complete Blocks approval sh:Warning Should fix before governance body approves
Gold Standard Advisory sh:Info Nice to have — improves quality but not required

This gives governance bodies graduated control: - A CI pipeline can block merges on sh:Violation - A dashboard can flag warnings for the ARB agenda - An architecture quality report can track info for practice improvement

SHACL Shapes: What Gets Validated

Application Component (Central Entity)

The most connected type gets the richest validation:

:ApplicationComponentShape
    a               sh:NodeShape ;
    sh:targetClass  am4:ApplicationComponent ;

    ## Minimum Viable (sh:Violation)
    sh:property [
        sh:path     skos:prefLabel ;
        sh:minCount 1 ;
        sh:severity sh:Violation ;
        sh:message  "Application component must have a name."@en ;
    ] ;
    sh:property [
        sh:path     acme:ownedBy ;
        sh:minCount 1 ;
        sh:severity sh:Violation ;
        sh:message  "Application component must have an owning team."@en ;
    ] ;
    sh:property [
        sh:path     arch:lifecycleState ;
        sh:minCount 1 ;
        sh:severity sh:Violation ;
        sh:message  "Application component must have a lifecycle state."@en ;
    ] ;

    ## Complete (sh:Warning)
    sh:property [
        sh:path     skos:definition ;
        sh:minCount 1 ;
        sh:severity sh:Warning ;
        sh:message  "Application component should have a description."@en ;
    ] ;
    sh:property [
        sh:path     am4:realizes ;
        sh:minCount 1 ;
        sh:severity sh:Warning ;
        sh:message  "Application component should realize at least one service."@en ;
    ] ;

    ## Gold Standard (sh:Info)
    sh:property [
        sh:path     dcterms:modified ;
        sh:minCount 1 ;
        sh:severity sh:Info ;
        sh:message  "Application component should have a last-modified date."@en ;
    ] ;
.

Technology Component (Governance-Heavy)

The Technology Radar viewpoint requires every technology to have an adoption recommendation:

:TechnologyComponentShape
    a               sh:NodeShape ;
    sh:targetClass  am4:TechnologyComponent ;

    sh:property [
        sh:path     acme:hasRecommendation ;
        sh:minCount 1 ;
        sh:severity sh:Violation ;
        sh:message  "Technology component must have an adoption recommendation."@en ;
    ] ;
    sh:property [
        sh:path     acme:hasRecommendation ;
        sh:class    skos:Concept ;
        sh:severity sh:Violation ;
        sh:message  "Recommendation must be from the AdoptionLevels vocabulary."@en ;
    ] ;
.

Data Object (Compliance-Driven)

GDPR requires classification and processing purpose for personal data:

:DataObjectShape
    a               sh:NodeShape ;
    sh:targetClass  am4:DataObject ;

    sh:property [
        sh:path     acme:hasClassification ;
        sh:minCount 1 ;
        sh:severity sh:Violation ;
        sh:message  "Data object must have a data classification."@en ;
    ] ;
    sh:property [
        sh:path     acme:processedFor ;
        sh:minCount 1 ;
        sh:severity sh:Warning ;
        sh:message  "Data object should declare its processing purpose."@en ;
    ] ;
.

Full Shapes File

The complete acme-shapes.ttl covers all element types from Part 5's ontology. See examples/acme-corp/acme-shapes.ttl for the full implementation.

SPARQL Governance Queries

SHACL validates individual instances. SPARQL queries assess practice-level health — coverage, staleness, compliance:

Staleness Detection

PREFIX am4:     <https://meta.linked.archi/archimate4/onto#>
PREFIX dcterms: <http://purl.org/dc/terms/>
PREFIX xsd:     <http://www.w3.org/2001/XMLSchema#>

# Applications not updated in 6+ months (long-lived staleness threshold)
SELECT ?app ?label ?lastModified WHERE {
    ?app a am4:ApplicationComponent ;
         skos:prefLabel ?label .
    OPTIONAL { ?app dcterms:modified ?lastModified }
    FILTER (!BOUND(?lastModified) ||
            ?lastModified < "2026-01-01"^^xsd:date)
}
ORDER BY ?lastModified

Technology Radar Coverage

PREFIX am4:  <https://meta.linked.archi/archimate4/onto#>
PREFIX acme: <https://example.com/acme/onto#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

# Technologies without an adoption recommendation (governance gap)
SELECT ?tech ?label WHERE {
    ?tech a am4:TechnologyComponent ;
          skos:prefLabel ?label .
    FILTER NOT EXISTS { ?tech acme:hasRecommendation ?rec }
}

GDPR Compliance Check

PREFIX am4:  <https://meta.linked.archi/archimate4/onto#>
PREFIX acme: <https://example.com/acme/onto#>
PREFIX acmetax: <https://example.com/acme/tax#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

# Personal data objects without a declared processing purpose
SELECT ?data ?label WHERE {
    ?data a am4:DataObject ;
          skos:prefLabel ?label ;
          acme:hasClassification acmetax:Personal .
    FILTER NOT EXISTS { ?data acme:processedFor ?purpose }
}

Capability Maturity Coverage

PREFIX am4:  <https://meta.linked.archi/archimate4/onto#>
PREFIX acme: <https://example.com/acme/onto#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

# Capabilities without maturity assessment (heat map incomplete)
SELECT ?cap ?label WHERE {
    ?cap a am4:Capability ;
         skos:prefLabel ?label .
    FILTER NOT EXISTS { ?cap acme:hasMaturity ?assessment }
}

Orphaned Applications (No Owner)

PREFIX am4:  <https://meta.linked.archi/archimate4/onto#>
PREFIX acme: <https://example.com/acme/onto#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

# Applications without an owning team
SELECT ?app ?label WHERE {
    ?app a am4:ApplicationComponent ;
         skos:prefLabel ?label .
    FILTER NOT EXISTS { ?app acme:ownedBy ?team }
}

CI/CD Integration

Pipeline Pattern

# .gitlab-ci.yml (or equivalent)
validate-architecture:
  stage: test
  script:
    - .scripts/validate.sh --shacl acme-corp
  rules:
    - changes:
        - examples/acme-corp/**/*.ttl
  allow_failure:
    severity: warning  # Warnings don't block; violations do

Validation Script Behaviour

SHACL Result CI Behaviour Governance Meaning
All pass ✅ Merge allowed Artifact meets minimum viable criteria
sh:Info only ✅ Merge allowed Quality suggestions noted in report
sh:Warning present ⚠️ Merge allowed, flagged Added to ARB agenda for next review
sh:Violation present ❌ Merge blocked Must fix before submission

Governance Dashboard Inputs

The SPARQL queries feed a governance dashboard:

Query Dashboard Widget Review Body
Staleness detection "3 applications past review date" Enterprise Architect (quarterly)
Technology Radar coverage "5 technologies without recommendation" Technology Council (monthly)
GDPR compliance "2 personal data objects without purpose" DPO (on-demand)
Capability coverage "4 capabilities without maturity assessment" Steering Group (annually)
Orphaned applications "1 application without owner" Portfolio Manager (quarterly)

How Shapes Connect to Governance (Part 4)

Part 4 Governance Rule SHACL Implementation
"Every application must have an owner" sh:property [ sh:path acme:ownedBy; sh:minCount 1; sh:severity sh:Violation ]
"Technology must have adoption recommendation" sh:property [ sh:path acme:hasRecommendation; sh:minCount 1; sh:severity sh:Violation ]
"Data objects must be classified" sh:property [ sh:path acme:hasClassification; sh:minCount 1; sh:severity sh:Violation ]
"Capabilities should have maturity assessments" sh:property [ sh:path acme:hasMaturity; sh:minCount 1; sh:severity sh:Warning ]
"Staleness: 6 months without update" SPARQL query (not expressible in SHACL alone)
"Archive 30 days after project closure" Workflow automation (not SHACL — operational process)

Some governance rules map cleanly to SHACL. Others require SPARQL queries or operational workflows. The architecture practice uses all three: - SHACL — instance-level validation (is this artifact complete?) - SPARQL — practice-level health (is the practice current?) - Workflows — operational processes (who needs to act?)

Practical Tips

Do

  • Start with violations only. Ship the first version with just sh:Violation shapes. Add warnings and info incrementally as the practice matures.
  • Write messages for architects, not ontologists. The sh:message text appears in validation reports. "Application component must have an owning team" is useful. "sh:minCount constraint violated on path acme:ownedBy" is not.
  • Run validation locally before CI. Architects should see violations instantly in their editor, not 5 minutes later in a pipeline.
  • Version shapes with the metamodel. When you add a new required property (MINOR version bump), you add a new shape. Existing instances get a grace period before the shape becomes a violation.

Don't

  • Don't encode business logic in SHACL. "Applications in the finance domain must have SOX compliance evidence" is governance policy, not structural validation. Use SPARQL queries for conditional business rules.
  • Don't make everything a violation. If every rule is sh:Violation, architects will resist the practice. Graduated severity gives breathing room while maintaining direction.
  • Don't forget SPARQL for temporal rules. SHACL validates graph structure. Staleness (time-based) requires SPARQL with date comparisons.

What Comes Next

Part 7 completes the series with Tool Integration — the generation pipeline that turns TTL + SPARQL into browsable Markdown, the build-or-buy decision framework, and the connection to Build Your Own Modeling Tool for the full implementation path.

References

This is Part 6 of the Architecture Practice from Scratch series. Part 7: Tool Integration concludes the series with the generation pipeline and build-or-buy framing.