OpenDEA Metamodel — Open Digital Enterprise Architecture Metamodel

Canonical entity definitions, relationships, and schemas for all DEA catalog repositories.

Overview

The DEA Metamodel is the foundation layer for the TechneHub Labs Enterprise Architecture space. Every entity, relationship, and attribute used across all dea-catalog-* repositories is defined here and referenced by version pin.

dea-metamodel (this repo)
       ↑
       │ version-pinned by all catalog repos
       │
   ┌───┴───────────────────────────────────────┐
   │  dea-catalog-tenets                       │
   │  dea-catalog-patterns                     │
   │  dea-catalog-guardrails                   │
   │  dea-catalog-blueprints                   │
   │  dea-catalog-metrics                      │
   │  dea-catalog-ontologies                   │
   │  dea-catalog-concepts                     │
   └───────────────────────────────────────────┘

Normative / Derived / Informative (CR-1)

There is one normative semantic model. Everything else is a representation, projection, serialization, implementation, or visualization of that model.

The canonical DEA metamodel is defined by the normative metamodel specification (metamodel/dea-metamodel.yaml). All schemas, database structures, viewer graphs, documentation diagrams and other representations MUST be generated from or validated against the normative specification.

Class	Content	Authority
Normative	metamodel/dea-metamodel.yaml, metamodel/manifest.yaml, metamodel/registry/	The semantic metamodel — the only source of truth
Derived	schemas/, sqlite/, typescript/, pydantic/, ttl/, viewer/entity-graph.json, viewer/metamodel.svg	Generated from or validated against the normative model — never edited to change semantics
Informative	docs/ narratives, examples/, diagrams, tutorials	Illustration only — no semantic authority

Change control: every metamodel modification requires a CR in change-requests/ following docs/versioning.md. The CR-1.6 semantic expansion freeze held through CR-003 and is now lifted — new entity types enter via the CR process and CR-4's core-ontology consolidation.

Structure

dea-metamodel/
├── metamodel/                 # NORMATIVE — dea-metamodel.yaml, manifest.yaml, registry/
├── change-requests/           # CR-based change control
├── docs/                      # architecture.md · semantics.md · temporal-semantics.md · governance-agentic-semantics.md · specification-and-conformance.md · runtime-architecture.md · versioning.md
├── specification/             # CR-8: the formal OpenDEA 1.0 specification (+ generated inventory/vocabulary/catalogues)
├── tools/                     # CR-8: opendea_validate.py — reference conformance validator
├── models/                    # CR-8: golden/ (must pass) + invalid/ (must fail for the expected rule)
├── mappings/                  # CR-8: external standard mappings (ArchiMate; DMN evaluated)
├── visualization/             # CR-8: presentation profile — viewers consume, never define
├── runtime/                   # CR-9: reference runtime — GraphStore, model loader, service API
├── tests/conformance/         # Conformance suite (runs in CI)
├── tests/runtime/             # CR-9: runtime suite — graph contract, loader, CRUD, provenance/temporal
├── VERSION                    # == metamodel version (CI-enforced)
├── CHANGELOG.md
├── metamodel.yaml             # LEGACY index (deprecated v0.6.0 — kept for compatibility)
├── schemas/                   # DERIVED — per-entity JSON Schema definitions
├── ttl/                       # DERIVED — OWL/RDF Turtle serializations
├── sqlite/                    # DERIVED — SQLite runtime projection
├── typescript/                # DERIVED — TypeScript interfaces
├── pydantic/                  # DERIVED — Python Pydantic models
└── viewer/                    # DERIVED — entity graph + rendered diagram

Assessment sub-metamodel

The assessment-models/ sub-tree defines the assessment sub-metamodel of OpenDEA — AssessmentModel, AssessmentInstrument, AssessmentExecution, AssessmentResult, Capability, Scenario, Measure, Evidence, ScoringModel, BenchmarkModel, plus MaturityModel as an optional interpretation layer.

This is the canonical home for assessment-domain schemas, vocabularies, governance, and the maturity scoring v2 scheme. Lands via CR-014. See assessment-models/README.md for entry point.

The existing assessment entities inside the core metamodel (Assessment, AssessmentResult, AssessmentFramework, AssessmentDimension, AssessmentCriterion, AssessmentSubject, AssessmentScope, AssessmentTarget, AssessmentGap, plus Capability, Scenario, Measure, Evidence, Benchmark) continue to be authoritative entity types within the core metamodel (pydantic/, metamodel/profiles/assessment/). The new sub-tree is the schemas, governance, and operational contracts for the assessment domain — the conceptual model that ties those entity types together as an end-to-end assessment workflow.

Semantic IDs

Every normative entity and relationship carries a stable identifier (dea:BusinessCapability, dea:realizes) — display names are labels, never identifiers. The authoritative inventory is metamodel/registry/. See docs/semantics.md for ID conventions, the canonical relationship ontology (CR-2), and lifecycle states.

Core Ontology & Profiles (CR-4)

OpenDEA Core defines stable semantic concepts; OpenDEA Profiles define specialized architectural viewpoints and frameworks.

• metamodel/core/ — 18 anchors (Entity, Actor, Organization, Capability, Behavior, Service, Resource, Information, Decision, Outcome, Requirement, Constraint, Change, …) + the 25-type core relationship grammar + O001–O009 constraints
• metamodel/profiles/ — 10 profiles (business, ecosystem, digital, data, technology, ai, governance, assessment, dmm, ecf) with explicit depends_on declarations; profiles extend Core, never redefine it

Core can be explained without mentioning DMM, ECF, ArchiMate, AI, cloud, any industry, or any vendor. DMM is an assessment lens over the semantic graph, not part of the Core.

Design rationale — the CR programme

Every structural decision in this repository traces to a numbered Change Request in change-requests/. The rationale matters as much as the artefact: readers should be able to see why the ontology is shaped the way it is.

CR	Rationale (why)	Consequence (what you see here)
CR-001	Scattered, divergent copies of the model made every consumer guess which was true.	One normative source (metamodel/dea-metamodel.yaml); everything else derived, version-pinned, drift-tested in CI.
CR-002	Untyped, directionless relationships made the graph semantically ambiguous.	A typed, directed, inverse-aware relationship ontology with cardinality, temporality and provenance.
CR-003	Relationship state duplicated on entities always drifted from the relationship store.	Entities carry no relationship state; canonical relationship instances are authoritative.
CR-004	Without a stable core, every framework (DMM, ECF, ArchiMate) leaked into the base vocabulary.	18-anchor Core + 10 profiles with depends_on; profiles extend, never redefine (O001–O009).
CR-005	capability.maturity = 3 conflates what the enterprise is with how it is assessed — one entity, one score, one framework, no evidence, no history.	A separate assessment layer: maturity belongs to frameworks, results carry evidence/confidence/provenance, and gaps connect to Change.
CR-006	"Application A exists" and "A existed in 2024 / is planned for 2027 / was retired" collapsed into one static catalogue entry. Architecture is a time-dependent state, not a catalogue.	Five clocks (transaction/valid/observation/planned/effective); lifecycle states and events; Baseline/Current/Target/Transition/Scenario states; snapshots, deltas, version chains; planned ≠ actual; history never overwritten (T001–T010).
CR-007	The graph knew what/when/how mature but not why a change is desired, who may decide it, what constrains it, what evidence informs it — "agentic EA" was degenerating into an agent inventory.	The causal/governance layer: Intent → Objective → Policy → Decision → Action → Change → Outcome → Evidence → reassessment. Authority ≠ capability; autonomy is not a boolean; agents are participants, not the center (G001–G016).
CR-008	A rich metamodel is not a standard: two independent implementations could reach different conclusions about the same model.	OpenDEA 1.0 — the consolidation into a formal specification: frozen Core, canonical vocabulary, envelope schema, reference validator, golden/negative model contract, conformance levels 0–5, generated documentation. See specification/.
CR-009	A specification without a runtime is a language nobody speaks: the model could be validated but not executed — no graph, no ingestion, no reasoning, no agent interaction, no closed loop.	OpenDEA Runtime — a semantic operating layer: vendor-independent GraphStore, canonical model loader (validate → atomic load), provenance/temporal-retaining graph, registry-validated CRUD, Assertion → Evidence → Source provenance chains with explicit approval transitions, governed rule registry and levelled explainable inference that materializes only as PROPOSED assertions, bitemporal temporal queries, event envelope and event log, frozen snapshots and structural diff for drift. Invariants: no silent inference (CR-9CQ), no autonomous mutation by default (CR-9CR). Milestones CR-9.1–9.10; CR-9.1/9.2/9.3/9.4/9.10a/9.10b/9.5/9.6/9.7/9.8/9.9 + CR-10 Phases 1/2/3/4/5/6/7 + CR-11 Phase 3 implemented. See runtime/ + docs/runtime-architecture.md.
CR-010	Runtime state that cannot be questioned is a snapshot, not a decision platform: "what if?" and "what should we do?" were unanswerable without mutating the live enterprise state.	Scenario & Decision Intelligence — scenarios as first-class semantic objects: immutable baselines + explicit deltas (ADD…SCALE), explicit assumptions/constraints/outcomes with uncertainty classes, simulated state isolated from production, frozen evaluated versions, reproducibility hashes, impact graphs with direct/indirect dependency paths, architecture deltas, explicit impact valence, semantic metrics, weighted criteria, decomposable scores, ranking and explainable recommendations that never become approved decisions. Plus the documentation consolidation: conceptual architecture, ADRs, glossary. Phases 1–3 implemented; Phases 4–7 queued. See docs/concepts/scenario.md.
CR-011	Enterprise knowledge lives in CMDBs, EA repos, ITSM, GRC, DMM assessments and SaaS platforms — without a formal interoperability architecture, every integration would distort the canonical model.	Interoperability & Federation — adapters absorb external complexity. First-class ExternalSystem / IntegrationAdapter (connector ≠ adapter) / SemanticMapping (relationship + confidence + lossiness, governed and versioned) / ExternalIdentifier (correlated, never adopted) / Exchange envelope / EntityResolution with full reconciliation states / KnowledgeConflict preservation / property-specific AuthorityPolicy. Extensions stay namespaced, never Core (ADR-013). Phases 1–2 implemented; Phases 3–8 queued. See docs/interoperability/.
CR-014	The assessment domain had profile-level coverage (metamodel/profiles/assessment/) but no coherent sub-metamodel — AssessmentModel / AssessmentResult / Capability / Scenario / Measure / Evidence / ScoringModel / BenchmarkModel were not defined as a unit; maturity scoring was CMMI-named with linear bands that hide the diminishing-returns curve.	assessment-models/ sub-tree — adds 12 JSON Schemas + PlantUML + 4 vocabularies + 3 governance docs + 5 examples as the conceptual model for the assessment domain; maturity scoring v2 lands alongside v1 (renames Emergent/Structured/Systematic/Adaptive/Self-Optimising, non-linear bands 20/25/25/18/12, per-level effort_multiplier 1.0×/1.5×/2.5×/4.0×/6.0×) with an explicit 4-phase migration plan (registry advisory → beta files → consumer support → promotion). v1 stays canonical until Phase D. Additive; canonical VERSION unchanged.
CR-CM-000	Domain and Stage were on a collision course: the Enterprise Concept Framework owns them as matrix axes, but the forthcoming Concepts Model needed thematic groupings of its own — reusing the same words would force every catalog and tool to guess which meaning was meant.	Terminology registry introduced before the first canonical Concepts Model (canonically homed at governance/terminology-registry.yaml in technehub-labs/dea-concepts-model since CR-CM-001; the local vocabulary/terminology-registry.yaml is a governed pointer): Domain/Stage reserved for the ECF (every use is ECF Domain or namespace-qualified); Concept Area, Concept Profile, Concept Classification, and ECF Context introduced for the Concepts Model — Concept Area ≠ ECF Domain, no automatic 1:1 mapping, concepts may hold multiple Concept Areas and zero-or-more ECF Contexts. See docs/concepts/terminology-alignment.md.
CR-AM-07	CR-AM-06 can say who is comparable but not what the comparison shows — its §10 boundary deliberately withheld percentile, rank, quartile, top-performer, and peer-position.	Comparative Benchmarking — BenchmarkComparison as a reproducible, governed derivation over an admitted cohort: distribution statistics, per-member percentile, rank + peer position (4/27), deterministic tie rules, minimum-sample enforcement, missing-data-is-N/A. Eligibility consumed, never redefined; ranking is derived, never stored as truth. Phase 1 (vocabulary + schema + worked example), Phase 2 (distribution engine), and Phase 3 (percentile & ranking + comparison composer) implemented; Phase 4 per §11.
CR-AM-08	The evidence chain is complete (result → view → eligibility → comparison) but nothing yet answers what the evidence tells us — comparison Policy's hand-off contract parks all narrative/interpretation vocabulary for exactly this CR.	Assessment Insights & Decision Support (proposal) — AssessmentInsight (evidence-mandatory, confidence ≠ significance, versioned lineage, declared generation method incl. ai-assisted), InsightRule (reproducible interpretation, never hard-coded), AssessmentGap (five explicit reference types — target/benchmark/trend/threshold/coverage never conflated), ImprovementObjective as the hand-off — actions, projects, and value realization deliberately excluded. Insight is interpretation of evidence, never a fact. Proposed; phase plan in §12.
CR-AM-09	A shared five-level shape is implicitly assumed by today's maturity content — but models legitimately differ in level count, names, progression, scoring, and conformance, and a benchmark must not change meaning when a maturity model is edited.	Maturity Scale, Progression & Conformance (proposal) — the metamodel standardizes HOW scales are represented; each model defines WHAT maturity means: model-owned MaturityScale (2..* levels, structural identifiers + explicit semantics), ProgressionModel (topology ≠ function), native evaluation without a universal 0–100, ProgressScoringBand (numeric / non-numeric / multi-dimensional), LevelResolutionRule (a score never implies a level without resolution logic), and immutable benchmark-locked MaturityScaleBaseline for historical reproducibility. Supersedes the earlier composable-maturity CR-AM-09 concept. Proposed; phase plan in §12.

The ontology in one picture

graph TD
    subgraph CORE["OpenDEA Core (18 anchors)"]
        C1[Capability] & C2[Service] & C3[Information]
        C4[Actor / Organization] & C5[Decision / Outcome] & C6[Change]
    end
    subgraph PROFILES["Profiles (extend, never redefine)"]
        P1[business · digital · data · technology · ai · ecosystem · governance · ecf]
    end
    subgraph ASSESS["Assessment layer (CR-5)"]
        AF[AssessmentFramework] --> D[Dimension] --> CR[Criterion] --> I[Indicator] --> M[Measure]
        A[Assessment] --> AR[AssessmentResult]
        M --> AR
        AR --> GAP[AssessmentGap]
        E[Evidence] -.supports.-> AR
    end
    subgraph LIFE["Lifecycle layer (CR-6)"]
        TI[TemporalInterval<br/>five clocks]
        AS[ArchitectureState<br/>baseline · current · target<br/>transition · scenario]
        TR[Transition] --> CH[Change]
        SS[Snapshot] --> DL[Delta]
    end
    subgraph GOV["Governance & agentic layers (CR-7)"]
        IN[Intent] --> OB[Objective]
        PO[Policy] --> DE[Decision]
        AU[Authority] --> DE
        DE --> AC[Action] --> CHG[Change]
        AG[Agent] -. performs .-> AC
        AG -. authorized-by .-> AU
    end
    DMM[DMM profile] -. implements .-> AF
    PROFILES --> CORE
    ASSESS -. assesses .-> CORE
    LIFE -. temporal bounds .-> CORE
    AS -. valid-during .-> TI
    GAP -- addressed-by --> C6
    TR -- realizes --> AS
    OB -. seeks .-> C5

Loading

The CR-5 closed loop

What the enterprise is (Core) and how it is assessed (profiles) are different semantic layers. The same Capability can be assessed by DMM, an AI-readiness model and a cyber framework at different dates and scopes — without conflict, because maturity lives on the AssessmentResult, never on the entity (rule A008, enforced in CI):

Describe → Assess → Identify Gap → Decide → Transform → Measure → Reassess
(Core)   (Result)  (derived Gap)  (Decision) (Change)   (Measure)  (new Baseline)

Diagram Design Tokens

The rendered metamodel diagram (viewer/metamodel.svg) follows a locked design defined in viewer/diagram-tokens.json — no canvas (transparent background inheriting the page), dark layer-colored packages, small italic relationship labels with no outline, light-grey attribute text on dark entity fills.

Every regeneration consumes these tokens: generate_puml.py (PlantUML skin params) and inject_svg_attributes.py (SVG post-processing) load them via .github/scripts/diagram_tokens.py. Do not hardcode design values in the pipeline scripts.

Per-layer accent/dark colors are not in the token file — they cascade from the OpenDEAM root model through viewer/entity-graph.json (layers[].color / layers[].dark_color), so new layers and packages pick up color coding automatically. Extend the token file (e.g. the dimension tokens) only when adding a new cross-cutting dimension.

Quick Start

Validate an entity against the metamodel

# Validate a JSON entity
python3 scripts/validate_entity.py --schema schemas/entities/tenet.json --entity my-tenet.json

# Validate RDF serialization
python3 scripts/validate_rdf.py --schema ttl/dea-metamodel.ttl --input my-entity.ttl

Run the conformance suite

python3 -m pytest tests/conformance/ -v

Query the SQLite runtime store

sqlite3 sqlite/dea-metamodel.db ".schema"
sqlite3 sqlite/dea-metamodel.db "SELECT * FROM entities WHERE type = 'ArchitecturePattern';"

Generate TypeScript types

cd typescript && npm install && npm run generate

Versioning Policy

Full policy: docs/versioning.md. Summary:

• MAJOR — breaking semantic changes (entity/relationship removal or redefinition, inheritance change, incompatible cardinality)
• MINOR — backward-compatible additions (new entity/relationship, optional attribute)
• PATCH — non-semantic corrections (docs, formatting, regenerated artifacts)
• Changing a relationship's definition is a semantic change even when the JSON schema stays compatible.
• Catalog repos pin to a specific tag (e.g., v0.6.0) in their metamodel-pointer.yaml

Contributing

1. Open a Change Request record under change-requests/ (see change-requests/README.md)
2. Submit a PR against the normative source (metamodel/dea-metamodel.yaml) — never against derived artifacts
3. CI validates: JSON Schema valid, TTL parses, SQLite schema applies, TypeScript compiles, conformance suite passes, no version/semantic drift
4. CODEOWNERS (platform-architecture team) must approve

License

Apache 2.0 — see LICENSE.