A schema family for executable enterprise architecture.
ea.codex/v1 defines a set of typed, versioned, machine-usable objects that let an enterprise architecture function carry intent, decisions, specifications, controls, and evidence as governed artifacts rather than as documents. The schemas are designed to be consumed by policy engines, agent runtimes, data catalogs, CI pipelines, and AI assistants without translation.
This repository accompanies the book AI-Augmented Enterprise Architecture: Semantics, Specification, and Continuous Execution by William El Kaim. The schemas, examples, and conventions here are the operational substrate the book describes.
Traditional enterprise architecture deliverables are documents: principles in slide decks, target states in diagrams, decisions in meeting minutes, controls in spreadsheets. They are useful for human inspection and almost useless for runtime governance. As enterprises adopt AI agents, federated data, and continuous delivery, architecture must be expressible in a form that delivery platforms, policy engines, and AI clients can read.
ea.codex/v1 proposes a small, opinionated set of typed objects that give the enterprise architecture function:
- A common header (
apiVersion,kind,metadata) consistent across all artifacts and matching the conventions used by Kubernetes-style declarative systems. - Explicit relationships between artifacts (intent → policy → decision → specification → evidence) that can be traversed by tooling.
- Lifecycle states that let the same artifact be in draft, approved, deprecated, or superseded status without losing identity.
- Validation hooks (Rego packages, LLM edge-evaluation prompts, scenario packs) that are part of the artifact, not separate.
The goal is not to replace existing enterprise architecture tooling, frameworks, or platforms. The goal is to give them a shared substrate.
ea-codex/
├── LICENSE MIT license
├── README.md This file
├── CHANGELOG.md Version history
├── CONTRIBUTING.md How to propose changes
├── schemas/
│ └── v1/
│ ├── _common.json Shared definitions (metadata, identifiers)
│ ├── enterprise-intent.json
│ ├── policy-constraint.json
│ ├── decision-record.json
│ ├── architecture-principle.json
│ ├── technology-standard.json
│ ├── reference-architecture.json
│ ├── continuous-architecture-contract.json
│ ├── architecture-package.json
│ ├── architecture-change-packet.json
│ ├── scenario-pack.json
│ ├── fitness-function.json
│ ├── rego-package.json
│ ├── evidence-record.json
│ ├── variability-specification.json
│ ├── edge-evaluation-prompt.json
│ ├── product-line-specification.json
│ ├── agent-contract.json
│ ├── agent-interaction-contract.json
│ ├── agent-memory-policy.json
│ ├── tool-access-policy.json
│ ├── business-object.json
│ ├── data-product-contract.json
│ ├── data-contract.json
│ ├── observability-profile.json
│ └── sovereignty-specification.json
├── examples/ ACME Pharma instance for each kind
├── docs/
│ ├── overview.md Conceptual model
│ ├── conventions.md Naming, identifiers, relationships
│ ├── relationships.md Cross-kind links
│ ├── inclusion-criteria.md What earns a typed kind
│ └── kinds/ One reference per kind
├── scripts/
│ ├── validate.py Per-artifact JSON Schema validation
│ └── check_consistency.py Corpus-wide cross-reference validation
└── .github/workflows/
└── validate.yml CI: validate all examples on every PR
The ea.codex/v1 family contains twenty-seven kinds, all stable. The list is deliberately short. The criteria for what earns a typed kind are documented in docs/inclusion-criteria.md; concepts that don't earn a typed kind (capability map, business processes, value chains, stakeholders, KPIs, etc.) are referenced from the Codex as string identifiers pointing into the EA platform's catalogue.
| Kind | Domain | Purpose |
|---|---|---|
EnterpriseIntent |
Intent & Decision | Structured statement of business outcome and constraints |
PolicyConstraint |
Intent & Decision | Typed enterprise or regulatory policy that constrains decisions and specifications |
DecisionRecord |
Intent & Decision | Typed architectural decision with explicit provenance |
ArchitecturePrinciple |
Intent & Decision | Stable architectural anchor with checkable validation criteria |
TechnologyStandard |
Architecture Foundations | Pattern catalogue classified for fitness-function enforcement |
ReferenceArchitecture |
Architecture Foundations | Typed reference architecture with layers, components, invariants |
ContinuousArchitectureContract |
Architecture Foundations | Living contract binding intent, decisions, controls, feedback |
ArchitecturePackage |
Execution & Governance | BMAD-staged unit of architectural change |
ArchitectureChangePacket |
Execution & Governance | TOGAF ADM-aligned change packet |
ScenarioPack |
Execution & Governance | Reusable validation scenarios for attractor harnesses |
FitnessFunction |
Execution & Governance | Typed architectural control proving a decision, principle, standard, or policy remains respected |
RegoPackage |
Execution & Governance | Typed reference to a policy package (Rego, Cedar, CEL, SQL, graph-query) |
EvidenceRecord |
Execution & Governance | Typed proof of control execution; closes the Decision -> Control -> Evidence chain |
VariabilitySpecification |
Variability & Product Lines | Permitted variation envelope for a product or platform family |
EdgeEvaluationPrompt |
Variability & Product Lines | LLM-evaluated transition condition between governance states |
ProductLineSpecification |
Variability & Product Lines | Software product line family definition |
DelegationPolicy |
Agent Governance | Authority model declaring delegation tiers, agent role per tier, and evidence requirements |
DesignAuthorityBody |
Agent Governance | Governing body (council, ARB, design board) with human and agent members under a DelegationPolicy |
AgentContract |
Agent Governance | Bounded contract for an enterprise AI agent (carries optional governance block for council members) |
AgentInteractionContract |
Agent Governance | Inter-agent communication contract |
AgentMemoryPolicy |
Agent Governance | Agent memory retention and jurisdiction policy |
ToolAccessPolicy |
Agent Governance | Tool catalog binding for an agent |
BusinessObject |
Data | Canonical enterprise data object with required semantic rules |
DataProductContract |
Data | Federated data product governance envelope |
DataContract |
Data | Consumer-facing contract for one consumption channel of a data product |
ObservabilityProfile |
Data | Required observability and evidence trace for an artifact |
SovereigntySpecification |
Sovereignty | Domain of architectural control over meaning, location, access, execution, evidence, exit |
Each kind has a JSON Schema in schemas/v1/, a reference doc in docs/kinds/, and at least one ACME Pharma example in examples/.
Every artifact in this family shares the same envelope:
apiVersion: ea.codex/v1
kind: <KindName>
metadata:
id: <STABLE-ID>
name: <human-readable-slug>
status: <draft | approved | approved-with-controls | deprecated | superseded>
version: "<semver-or-major-minor>"
owners:
<role>: <contact>
spec:
# kind-specific contentThe minimal example below is a real EnterpriseIntent for the ACME Pharma clinical-acceleration program:
apiVersion: ea.codex/v1
kind: EnterpriseIntent
metadata:
id: INT-CLINICAL-ACCELERATION
name: clinical-trial-acceleration
status: approved
version: "1.0"
owners:
enterpriseArchitect: ea.clinical@acmepharma.eu
spec:
outcome: >
Accelerate clinical trial execution without weakening
compliance, auditability, or patient safety.
successMeasures:
- name: trial-startup-lead-time
target: "< 90 days"
- name: regulated-finding-rate
target: "< 1 per release"
constraints:
- regulated-data-must-remain-under-eu-control
- immutable-audit-of-decisions
affectedCapabilities:
- ClinicalTrialOperations
- RegulatoryComplianceA Python validation script ships with the repo. It reads any YAML or JSON file, looks up the right schema based on apiVersion and kind, and reports violations.
pip install jsonschema pyyaml
python scripts/validate.py examples/enterprise-intent/intent-clinical-acceleration.yamlTo validate every example:
python scripts/validate.py examples/The same script runs in CI on every pull request (see .github/workflows/validate.yml).
Identifiers are short, stable, uppercase-with-dashes, and never recycled. ACME Pharma identifiers in the examples use the prefix ACP- plus a domain segment (ACP-SOV-001, ACP-REG-018, ACP-ARC-012). Cross-references between artifacts always use identifiers, never names. All kinds use camelCase for sub-fields. The family does not encode EA-platform vendor names; bindings to LeanIX, Ardoq, ServiceNow, or any other EA tool live in adopter-specific configuration, with the Codex side using a generic eaToolMapping block. Capability identifiers follow the eatool:bc.<domain>.<name> convention to make the EA-platform binding explicit without naming the platform.
ea.codex/v1 is framework-neutral. It composes with TOGAF (the kinds map onto Architecture Vision, Architecture Building Blocks, Architecture Contracts, Architecture Change Requests, and Architecture Repository content), with ArchiMate (the kinds carry references to capabilities and business objects that an ArchiMate model can name), and with engineering practices such as policy as code (Open Policy Agent / Rego), software product lines, and agentic AI governance. The schemas do not enforce a framework; they enforce structure.
ea.codex/v1 is a stable schema family used as the operational substrate for the book AI-Augmented Enterprise Architecture. All twenty-seven kinds carry committed field structures; existing artifacts will continue to validate as the family receives minor releases. Naming, envelope normalization, and the planned profile consolidation in v2 may still evolve before the book reaches publication. The shape of v2 is captured in docs/v2/design-intent.md: a smaller conceptual core of about a dozen first-class kinds with typed profiles for the implementation specializations that today appear as peer kinds.
The criteria for what earns a typed kind are documented in docs/inclusion-criteria.md. New kinds in any future v1 minor release must clear those criteria before the schema is added.
Two scripts run in CI on every push and pull request:
scripts/validate.py examples/validates each example against its JSON Schema.scripts/check_consistency.py examples/walks every cross-reference field across the corpus and verifies that each referenced identifier resolves to an existing artifact. Add--strictfor additional checks on identifier-prefix conventions and orphaned principles, standards, and capabilities.
Both must pass for a PR to merge.
If you use ea.codex/v1 in research, in a presentation, or in production, please cite the book and link back to this repository. Contributions are welcome via pull request; see CONTRIBUTING.md for the proposal flow and the rules for adding new kinds or fields.
Released under the MIT License. Copyright © 2026 William El Kaim.