> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aigoframework.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 00 AIGO Schema Architecture v0.1

# AIGO — Schema Architecture

## 1. Purpose

This document defines the architecture of the AIGO machine-readable schema layer.

The schema architecture establishes how AIGO governance objects are represented, related, validated, versioned, governed, and consumed by future tooling and operational repositories.

The schema layer is designed to complement, rather than replace, the AIGO framework, guidance, procedures, templates, and external-framework mappings.

***

## 2. Scope

This architecture applies to the controlled schema repository:

`aigo-framework/schemas/`

It covers:

* common definitions;
* primary domain schemas;
* schema dependencies;
* cross-object references;
* validation;
* lifecycle state representation;
* versioning;
* traceability;
* schema registry;
* future tooling integration; and
* schema governance.

***

## 3. Architectural Position

The AIGO schema layer sits between the human-operational documentation model and machine-oriented tooling.

```text theme={null}
AIGO Framework
      │
      ▼
Implementation Guidance
      │
      ▼
Operational Procedures
      │
      ▼
Templates
      │
      ▼
Operational Records
      │
      ▼
AIGO JSON Schemas
      │
      ▼
Validation / Repository Tooling
      │
      ▼
Operational Platforms
```

The schemas define the structural model of operational records.

They do not independently define organizational policy, authority, or procedure.

***

## 4. Architecture Principles

The schema architecture follows these principles.

### 4.1 Single Semantic Foundation

Common concepts should be defined once and reused throughout the schema layer.

The common definitions schema is therefore the foundation for shared concepts such as:

* identifiers;
* versions;
* roles;
* organizations;
* dates;
* lifecycle stages;
* risk levels;
* control ratings;
* decisions;
* priorities;
* severity;
* evidence quality; and
* references.

### 4.2 Domain Separation

Each major governance object has its own schema.

This keeps responsibilities clear and allows domain-specific validation without requiring every record to contain the entire AIGO object model.

### 4.3 Stable Identity

Records are identified independently from their versions.

A record identifier should remain stable throughout the record's lifecycle unless the governance process explicitly establishes a new record.

### 4.4 Reference-Based Integration

Related records are connected through stable identifiers rather than uncontrolled duplication.

### 4.5 Controlled Extensibility

The architecture should allow future extensions without corrupting the meaning of the base AIGO schemas.

### 4.6 Explicit Governance

Schema changes are controlled changes because schema changes can affect operational records, reporting, evidence, auditability, integrations, and validation.

***

## 5. Schema Repository Structure

The schema repository is organized into a common layer and domain layers.

```text theme={null}
schemas/
│
├── 01-AIGO-Common-Definitions-v0.1.json
│
├── 01-ai-system/
│   └── 01-AIGO-AI-System-Schema-v0.1.json
│
├── 02-risk/
│   └── 02-AIGO-Risk-Schema-v0.1.json
│
├── 03-control/
│   └── 03-AIGO-Control-Schema-v0.1.json
│
├── 04-assessment/
│   └── 04-AIGO-Assessment-Schema-v0.1.json
│
├── 05-approval/
│   └── 05-AIGO-Approval-Schema-v0.1.json
│
├── 06-monitoring/
│   └── 06-AIGO-Monitoring-Schema-v0.1.json
│
├── 07-incident/
│   └── 07-AIGO-Incident-Schema-v0.1.json
│
├── 08-change/
│   └── 08-AIGO-Change-Schema-v0.1.json
│
├── 09-assurance/
│   └── 09-AIGO-Assurance-Schema-v0.1.json
│
├── 10-evidence/
│   └── 10-AIGO-Evidence-Schema-v0.1.json
│
├── 11-management-review/
│   └── 11-AIGO-Management-Review-Schema-v0.1.json
│
├── 12-improvement/
│   └── 12-AIGO-Improvement-Schema-v0.1.json
│
├── 13-retirement/
│   └── 13-AIGO-Retirement-Schema-v0.1.json
│
├── 14-governance/
│   └── 14-AIGO-Governance-Schema-v0.1.json
│
├── 00-AIGO-Schema-Registry-v0.1.json
└── 00-AIGO-Schema-Architecture-v0.1.md
```

The registry is the authoritative inventory of the schema layer.

This architecture document explains the structure and design principles represented by the registry.

***

## 6. Common Definitions Layer

The common definitions layer provides reusable building blocks.

Primary file:

`01-AIGO-Common-Definitions-v0.1.json`

The common layer should contain concepts that must retain consistent semantics across multiple schemas.

Examples include:

```text theme={null}
Identifier
Version
Date
DateTime
OrganizationMetadata
RoleReference
LifecycleStage
RiskLevel
ControlRating
ClassificationLevel
Priority
Severity
Decision
Finding
Condition
Reference
ReferenceList
EvidenceQuality
```

A domain schema should reference a common definition when the underlying concept is semantically the same.

***

## 7. Domain Schema Layer

The domain schemas represent the major operational objects in AIGO.

### 7.1 AI System

Represents the governed AI system and associated metadata.

The AI System object is the principal operational anchor for many other records.

### 7.2 Risk

Represents AI-related risk identification, analysis, treatment, acceptance, monitoring, and residual risk.

### 7.3 Control

Represents governance and risk controls, including design, ownership, operation, assessment, evidence, exceptions, and monitoring.

### 7.4 Assessment

Represents formal evaluations across multiple AIGO assessment types.

### 7.5 Approval

Represents authorization and controlled governance decisions.

### 7.6 Monitoring

Represents ongoing observation, metrics, thresholds, alerts, escalation, and monitoring response.

### 7.7 Incident

Represents AI incidents from detection through investigation, containment, remediation, recovery, and closure.

### 7.8 Change

Represents changes to AI systems and their governance environment.

### 7.9 Assurance

Represents independent or structured assurance activity and follow-up.

### 7.10 Evidence

Represents evidence supporting governance, risk, control, assurance, approval, and other decisions.

### 7.11 Management Review

Represents management-level review of governance suitability, adequacy, effectiveness, performance, risks, decisions, and improvement.

### 7.12 Improvement

Represents continual-improvement opportunities and actions.

### 7.13 Retirement

Represents controlled AI system retirement.

### 7.14 Governance

Represents the organization-level AI governance arrangement.

***

## 8. Logical Object Model

The principal relationships are:

```text theme={null}
                         GOVERNANCE
                             │
                             ▼
                         AI SYSTEM
                             │
             ┌───────────────┼────────────────┐
             │               │                │
             ▼               ▼                ▼
           RISK           CONTROL         ASSESSMENT
             │               │                │
             └───────┬───────┴────────┬───────┘
                     │                │
                     ▼                ▼
                 EVIDENCE          APPROVAL
                     │                │
                     └───────┬────────┘
                             │
                ┌────────────┼────────────┐
                ▼            ▼            ▼
            MONITORING     CHANGE      ASSURANCE
                │            │            │
                └─────┬──────┴──────┬─────┘
                      │             │
                      ▼             ▼
                   INCIDENT     IMPROVEMENT
                                    │
                                    ▼
                                RETIREMENT
                                    │
                                    ▼
                              MANAGEMENT REVIEW
```

This is a logical model rather than a requirement that all relationships be represented as embedded JSON objects.

***

## 9. Record Identity Model

Each primary object should have:

```text theme={null}
id
objectType
objectVersion
schemaVersion
```

For example:

```json theme={null}
{
  "id": "RISK-001",
  "objectType": "RISK",
  "objectVersion": "1.0",
  "schemaVersion": "0.1"
}
```

The distinction is important:

* `id` identifies the governed record;
* `objectVersion` identifies the version of that record;
* `schemaVersion` identifies the schema used to validate the record.

These values must not be treated as interchangeable.

***

## 10. Schema Version Versus Framework Version

AIGO maintains several related but distinct version concepts.

### Framework Version

Represents the AIGO framework release.

Example:

`0.1`

### Schema Version

Represents the structural schema release.

Example:

`0.1`

### Object Version

Represents the version of an individual operational record.

Example:

`1.0`

### Document Version

Represents the version of a Markdown framework artifact.

These version dimensions should remain explicitly separate.

***

## 11. Reference Architecture

Cross-object relationships should generally use identifier references.

Example:

```json theme={null}
{
  "id": "CTRL-001",
  "riskIds": [
    "RISK-001",
    "RISK-002"
  ],
  "evidenceIds": [
    "EVID-004"
  ],
  "assessmentIds": [
    "ASSESS-007"
  ]
}
```

The referenced records remain independent records.

This supports:

* reuse;
* auditability;
* independent versioning;
* controlled access;
* evidence preservation; and
* repository-scale validation.

***

## 12. Structural Versus Referential Validation

AIGO distinguishes two validation layers.

### 12.1 Schema Validation

JSON Schema validates the structure of an individual record.

It can determine whether:

* required fields are present;
* values have the correct type;
* enumerations are valid;
* nested objects conform;
* arrays conform; and
* local constraints are satisfied.

### 12.2 Repository Validation

Repository-level validation evaluates relationships between records.

It should determine whether:

* referenced records exist;
* identifiers are unique;
* references point to permitted object types;
* lifecycle relationships are valid;
* approval authority is appropriate;
* evidence exists;
* required records are complete;
* records are orphaned; and
* cross-object governance constraints are satisfied.

The two validation layers are complementary.

***

## 13. Lifecycle State Architecture

Schemas represent lifecycle state but do not authorize lifecycle transitions.

For example:

```text theme={null}
DRAFT
  ↓
SUBMITTED
  ↓
UNDER_REVIEW
  ↓
APPROVED
  ↓
ACTIVE
  ↓
UNDER_REASSESSMENT
  ↓
CLOSED / RETIRED
```

Actual transitions should be controlled by the applicable AIGO procedure and authority.

A schema therefore provides a vocabulary for state representation, not an independent authorization mechanism.

***

## 14. Evidence Architecture

Evidence is deliberately represented as an independent object.

This enables one evidence record to support multiple governance activities.

For example:

```text theme={null}
EVID-001
   │
   ├── supports RISK-001
   ├── supports CTRL-003
   ├── supports ASSESS-007
   ├── supports APPROVAL-004
   └── supports ASSURE-002
```

This reduces redundant copies and strengthens audit traceability.

Evidence should preserve information concerning:

* source;
* collection;
* integrity;
* authenticity;
* completeness;
* relevance;
* accuracy;
* timeliness;
* access;
* retention; and
* disposition.

***

## 15. Assessment Architecture

Assessment is a cross-cutting object.

The assessment schema supports multiple assessment purposes while preserving a common structural model.

Examples include:

```text theme={null}
Classification Assessment
Risk Assessment
Control Assessment
Security Assessment
Privacy Assessment
Fairness Assessment
Impact Assessment
Technical Validation
Model Validation
Monitoring Review
Assurance-related Assessment
Change Impact Assessment
Retirement Assessment
```

This avoids creating a separate schema for every assessment subtype while maintaining a common assessment structure.

***

## 16. Approval Architecture

Approvals are independent governance records.

A decision should identify:

* what is being approved;
* approval type;
* scope;
* approval authority;
* supporting assessments;
* relevant risks;
* relevant controls;
* conditions;
* decision;
* decision date;
* evidence; and
* review requirements.

An approval should not be inferred merely because another record contains `"status": "APPROVED"`.

Where formal approval is required, the approval record should provide the authoritative decision trail.

***

## 17. Monitoring Architecture

Monitoring is designed as an operational feedback mechanism.

The architecture separates:

```text theme={null}
Monitoring Objective
        ↓
Indicator
        ↓
Measurement
        ↓
Threshold
        ↓
Alert
        ↓
Response
        ↓
Escalation
        ↓
Reassessment / Incident / Change
```

This permits monitoring to feed back into the AIGO governance lifecycle.

***

## 18. Incident Architecture

The incident model follows:

```text theme={null}
Detection
   ↓
Registration
   ↓
Triage
   ↓
Containment
   ↓
Investigation
   ↓
Root Cause
   ↓
Impact Assessment
   ↓
Corrective Action
   ↓
Recovery
   ↓
Verification
   ↓
Closure
   ↓
Lessons Learned
   ↓
Improvement
```

Incident records can therefore generate new or modified:

* risks;
* controls;
* monitoring requirements;
* changes;
* assurance activities; and
* improvement actions.

***

## 19. Change Architecture

The change model supports both ordinary and emergency changes.

The logical pattern is:

```text theme={null}
Change Request
      ↓
Classification
      ↓
Impact Assessment
      ↓
Risk Assessment
      ↓
Control Assessment
      ↓
Testing
      ↓
Approval
      ↓
Deployment
      ↓
Validation
      ↓
Enhanced Monitoring
      ↓
Closure / Rollback
```

This supports controlled modification of AI systems without losing governance traceability.

***

## 20. Assurance Architecture

Assurance provides a structured challenge and verification layer.

The logical model is:

```text theme={null}
Assurance Objective
       ↓
Scope
       ↓
Criteria
       ↓
Work Program
       ↓
Evidence
       ↓
Testing
       ↓
Findings
       ↓
Management Response
       ↓
Corrective Action
       ↓
Follow-Up
       ↓
Conclusion
```

Assurance records should maintain sufficient independence and objectivity information where applicable.

***

## 21. Management Review Architecture

Management review operates at a higher governance aggregation level.

It may consume information from:

* AI portfolio status;
* risk;
* controls;
* incidents;
* changes;
* monitoring;
* assurance;
* stakeholder feedback;
* regulatory developments;
* resources;
* maturity; and
* continual improvement.

Management review may then produce:

* governance decisions;
* risk decisions;
* control decisions;
* resource decisions;
* governance changes;
* improvement actions; and
* future review requirements.

***

## 22. Improvement Architecture

Improvement closes the governance feedback loop.

The logical pattern is:

```text theme={null}
Observation / Finding / Opportunity
              ↓
          Root Cause
              ↓
          Prioritization
              ↓
          Action Plan
              ↓
          Implementation
              ↓
           Verification
              ↓
          Effectiveness
              ↓
      Standardization Decision
              ↓
             Closure
```

Improvement records may originate from virtually every other governance domain.

***

## 23. Retirement Architecture

Retirement is treated as a governed lifecycle transition rather than a technical deletion event.

The architecture supports:

* retirement trigger;
* business rationale;
* risk assessment;
* continuity;
* replacement transition;
* data disposition;
* model disposition;
* technical shutdown;
* access removal;
* monitoring closure;
* supplier closure;
* security and privacy closure;
* evidence retention;
* verification;
* post-retirement monitoring;
* final confirmation; and
* closure.

This preserves accountability after operational use has ended.

***

## 24. Governance Architecture

The governance schema represents organization-level arrangements.

It establishes structures for:

* governance authority;
* governance scope;
* governance objectives;
* principles;
* governance bodies;
* roles;
* decision authority;
* delegated authority;
* lifecycle governance;
* risk governance;
* control governance;
* monitoring;
* assurance;
* incidents;
* changes;
* retirement;
* external requirements;
* documentation;
* evidence;
* metrics;
* management review;
* improvement; and
* resource governance.

The governance schema therefore provides the top-level organizational context for the operational records.

***

## 25. Common Reference Dependencies

The primary schemas should depend on common definitions.

Conceptually:

```text theme={null}
                    Common Definitions
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
        ▼                  ▼                  ▼
     AI System            Risk             Control
        │                  │                  │
        └──────────────────┼──────────────────┘
                           │
                 Operational Domains
                           │
        ┌──────────────────┼──────────────────┐
        ▼                  ▼                  ▼
    Assessment         Evidence           Approval
        │                  │                  │
        └──────────────────┼──────────────────┘
                           │
         Monitoring / Incident / Change / Assurance
                           │
            Management Review / Improvement
                           │
                       Retirement
                           │
                       Governance
```

The exact `$ref` dependency graph is maintained in the schema registry.

***

## 26. Schema Registry

The schema registry is the authoritative machine-readable inventory.

Primary file:

`00-AIGO-Schema-Registry-v0.1.json`

The registry should identify:

* schema identifier;
* object type;
* title;
* version;
* path;
* status;
* dependencies;
* references;
* ownership;
* deprecation state;
* replacement schema;
* migration requirements; and
* traceability metadata.

The registry itself should be version controlled.

***

## 27. Tooling Integration

Future AIGO tooling should consume the schema registry rather than hard-code an independent schema inventory.

The tooling architecture should eventually support:

```text theme={null}
Schema Discovery
      ↓
Schema Loading
      ↓
Structural Validation
      ↓
Reference Validation
      ↓
Traceability Validation
      ↓
Governance Validation
      ↓
Repository Health Reporting
```

Tools should use the schema definitions as the authoritative structural source.

***

## 28. Example Data Layer

Representative JSON examples should be maintained separately from the schema definitions.

Recommended location:

`schemas/examples/`

Examples should:

* conform to the current schema;
* use realistic but non-sensitive data;
* demonstrate common relationships;
* demonstrate lifecycle states;
* illustrate required evidence and approvals; and
* support testing of future validation tools.

Examples should never be treated as schema definitions.

***

## 29. External Framework Mapping

The schema architecture supports mappings to external frameworks.

Current AIGO mapping domains include:

```text theme={null}
mappings/
├── iso-42001/
├── nist-ai-rmf/
├── eu-ai-act/
└── other/
```

External requirements should ultimately map into AIGO records through identifiers and traceable relationships.

The desired model is:

```text theme={null}
External Requirement
        ↓
AIGO Governance Requirement
        ↓
AIGO Risk
        ↓
AIGO Control
        ↓
AIGO Assessment
        ↓
AIGO Evidence
        ↓
AIGO Assurance
```

The schema architecture therefore serves as the machine-readable foundation for compliance and governance traceability.

***

## 30. Extension Model

Organizations may need additional fields or organization-specific objects.

Extensions should follow these principles:

1. Do not silently modify the base schema.
2. Identify the extension owner.
3. Identify the base schema being extended.
4. Define the extension purpose.
5. Define compatibility expectations.
6. Validate the extension separately.
7. Record the extension in controlled documentation.
8. Apply change management.
9. Maintain traceability to the base AIGO object.

Future AIGO releases may formalize a dedicated extension namespace.

***

## 31. Security Architecture

The schema layer itself does not enforce information security.

Implementations must apply appropriate controls around the records represented by the schemas.

These may include:

* authentication;
* authorization;
* least privilege;
* segregation of duties;
* encryption;
* repository access controls;
* audit logging;
* data classification;
* retention;
* secure backup; and
* secure disposal.

Sensitive evidence should not be exposed merely because the schema permits an evidence reference.

***

## 32. Privacy Architecture

Where records contain personal or sensitive information, the implementation should apply appropriate privacy controls.

The schema layer supports identification of privacy-related records and relationships, but privacy compliance depends on the operating organization's legal, contractual, procedural, and technical controls.

***

## 33. Data Integrity

AIGO records should maintain integrity across their lifecycle.

Implementations should consider:

* immutable or controlled record identifiers;
* version history;
* hashes or equivalent integrity mechanisms where required;
* controlled repositories;
* access logging;
* change logging;
* evidence preservation; and
* traceable approvals.

The evidence schema provides specific structures for integrity and authenticity information.

***

## 34. Change Management for Schemas

A schema change should be treated as a controlled framework change when it can materially affect:

* record structure;
* validation behavior;
* semantics;
* integrations;
* repository storage;
* reporting;
* assurance;
* evidence;
* external mappings; or
* governance processes.

The change process should assess:

```text theme={null}
Impact
Risk
Compatibility
Migration
Testing
Documentation
Approval
Release
```

***

## 35. Deprecation and Retirement

A schema should not be silently deleted when replaced.

A deprecated or retired schema should retain:

* identifier;
* version;
* historical status;
* reason;
* successor where applicable;
* migration guidance where applicable; and
* historical traceability.

This is particularly important for records that may need to be interpreted years after creation.

***

## 36. Validation Strategy

The minimum validation model is:

### Level 1 — Syntax

Confirm that the document is valid JSON.

### Level 2 — Schema

Validate against the correct JSON Schema.

### Level 3 — Reference

Verify referenced records and dependencies.

### Level 4 — Traceability

Verify that required relationships exist.

### Level 5 — Governance

Verify that the record is consistent with AIGO governance rules and applicable procedures.

### Level 6 — Assurance

Where required, verify the evidence and independent assessment supporting the record.

***

## 37. Schema Quality Requirements

A released AIGO schema should, at minimum:

* declare its JSON Schema dialect;
* declare a stable `$id`;
* identify its title;
* provide a useful description;
* define explicit object structure;
* declare important required fields;
* use reusable common definitions;
* avoid unnecessary semantic duplication;
* define status and lifecycle concepts consistently;
* support traceability;
* document breaking changes; and
* be registered in the schema registry.

***

## 38. Architectural Constraints

The following constraints apply to the schema architecture.

### 38.1 No Hidden Semantics

A field should have a clearly understood meaning.

### 38.2 No Uncontrolled Duplication

Shared concepts should use common definitions wherever practical.

### 38.3 No Implicit Authority

A schema status must not be interpreted as governance authorization without the corresponding decision process.

### 38.4 No Untracked Cross-Record Links

References should be identifiable and resolvable.

### 38.5 No Silent Breaking Changes

Material schema changes must be documented and controlled.

***

## 39. Future Architecture Extensions

Future AIGO releases may introduce:

* formal JSON Schema extension namespaces;
* reusable schema modules;
* event schemas;
* API contracts;
* evidence exchange formats;
* policy-as-code structures;
* workflow schemas;
* assessment scoring profiles;
* external-framework requirement schemas;
* machine-readable control catalogs;
* machine-readable lifecycle rules; and
* automated conformance profiles.

Such extensions should preserve the architecture principles defined in this document.

***

## 40. Implementation Sequence

The recommended implementation sequence is:

```text theme={null}
1. Common Definitions
2. Domain Schemas
3. Schema Registry
4. Schema Architecture
5. Example Records
6. Structural Validation
7. Reference Validation
8. Traceability Validation
9. Repository Health Tooling
10. External Mapping Integration
```

This sequence prevents tooling from developing against an unstable or undocumented data model.

***

## 41. Relationship to AIGO Governance

The schema architecture supports the central AIGO governance cycle:

```text theme={null}
Govern
  ↓
Identify
  ↓
Classify
  ↓
Assess
  ↓
Treat
  ↓
Control
  ↓
Approve
  ↓
Deploy
  ↓
Monitor
  ↓
Assure
  ↓
Improve
  ↓
Change / Retire
  ↓
Management Review
  ↓
Govern
```

The machine-readable schema layer ensures that the resulting governance records can be represented consistently and traced across that lifecycle.

***

## 42. Document Control

| Field               | Value                                    |
| ------------------- | ---------------------------------------- |
| Document            | AIGO — Schema Architecture               |
| Version             | 0.1                                      |
| Status              | Draft                                    |
| Document Identifier | `AIGO-SCHEMA-ARCH-001`                   |
| Document Type       | Schema Architecture                      |
| Framework           | AIGO — AI Governance Operating Framework |
| Owner               |                                          |
| Technical Reviewer  |                                          |
| Governance Reviewer |                                          |
| Approver            |                                          |
| Effective Date      |                                          |
| Next Review Date    |                                          |

***

## 43. Traceability

| AIGO Component          | Relationship                                                 |
| ----------------------- | ------------------------------------------------------------ |
| Framework Charter       | Defines overall framework authority and scope                |
| Framework Principles    | Defines architectural and governance principles              |
| Governance Domains      | Defines governance areas represented by schemas              |
| Governance Roles        | Defines responsibility and authority concepts                |
| AI Governance Lifecycle | Defines lifecycle concepts represented by schemas            |
| AI Risk Management      | Provides risk object and risk-management concepts            |
| AI Governance Controls  | Provides control concepts                                    |
| AI Governance Maturity  | Supports maturity assessment and governance review           |
| AI System Profiles      | Provides AI-system information requirements                  |
| Implementation Guidance | Defines operational implementation expectations              |
| Procedures              | Defines how records are created and controlled               |
| Templates               | Provides human-readable record structures                    |
| External Mappings       | Provides external-framework traceability                     |
| Tools                   | Provides future automated validation and repository services |

***

## 44. Document Status

**Document:** AIGO — Schema Architecture

**Version:** 0.1

**Status:** Draft

**Working Name:** AIGO

**Full Name:** AI Governance Operating Framework

**Document Identifier:** `AIGO-SCHEMA-ARCH-001`

**Document Type:** Schema Architecture

This document establishes the architectural model for the AIGO machine-readable schema repository and provides the foundation for schema governance, validation, interoperability, traceability, and future tooling.

End of Document