# Canonical Data Model

## Top-Level Incident

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `id` | string | yes | Stable incident ID, e.g. `INC-2026-00042` |
| `title` | string | yes | Human-readable title |
| `summary` | string | yes | Neutral factual summary |
| `category` | object | yes | Extensible taxonomy object, not enum |
| `severity` | object | yes | Internal severity, customer severity, security severity |
| `status` | string | yes | Current lifecycle state |
| `lifecycleTransitions` | array | yes | Append-only transitions |
| `createdAt` | datetime | yes | ISO 8601 |
| `updatedAt` | datetime | yes | ISO 8601 |
| `timezone` | string | yes | IANA timezone |
| `detectedAt` | datetime | no | When detected |
| `startedAt` | datetime | no | Best-known incident start |
| `resolvedAt` | datetime | no | When user impact ended |
| `closedAt` | datetime | no | Formal closure |
| `environment` | object | yes | Prod/staging/dev, regions, clusters |
| `ownership` | object | yes | Commander, leads, approvers, stakeholders |
| `affectedScope` | object | yes | Services, assets, customers, dependencies |
| `impactAssessments` | array | yes | Availability, integrity, confidentiality, etc. |
| `timeline` | array | yes | Structured event list |
| `evidence` | array | yes | Evidence register |
| `attachments` | array | yes | Non-evidence attachments and generated artifacts |
| `decisions` | array | yes | Decision log |
| `communications` | array | yes | Internal/external/status/regulatory updates |
| `rca` | object | no | RCA methods and findings |
| `actions` | array | yes | Corrective/preventive action items |
| `security` | object | no | Security extension |
| `reliability` | object | no | Reliability extension |
| `regulatory` | object | no | Notification and compliance assessment |
| `audit` | object | yes | Audit metadata |
| `customFields` | object | no | Namespaced future fields |

## Category Object

Categories are data records to avoid schema changes:

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string | `data_corruption`, `dns_incident`, `customer_escalation` |
| `name` | string | Display name |
| `family` | string | `security`, `reliability`, `privacy`, `business_continuity`, `operations` |
| `tags` | string[] | Search and automation routing |
| `playbookBindings` | object[] | Links to runbooks, templates, approval policies |
| `requiredExtensions` | string[] | e.g. `security`, `reliability`, `regulatory` |

## Timeline Event

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string | Unique event ID |
| `timestamp` | datetime | Event time |
| `timezone` | string | Original timezone if known |
| `actor` | object | User, system, vendor, automation |
| `source` | string | Slack, log, GCP, database, manual, vendor |
| `system` | string | Affected/observed system |
| `category` | string | detection, decision, mitigation, recovery, communication, evidence |
| `severity` | string | info, low, medium, high, critical |
| `description` | string | Fact-focused description |
| `evidenceRefs` | string[] | Evidence IDs |
| `visibility` | string | internal, executive, customer, regulator, legal |
| `automation` | boolean | Generated or human-authored |
| `confidence` | string | low, medium, high, confirmed |
| `correlatedEventIds` | string[] | Related events |

## Evidence Item

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string | `EV-0001` |
| `category` | string | logs, screenshot, audit_log, db_snapshot, chat_transcript, packet_capture, etc. |
| `description` | string | What it proves |
| `source` | string | System, bucket, channel, vendor |
| `collector` | object | Person or automation |
| `collectedAt` | datetime | Collection timestamp |
| `observedAt` | datetime | When evidence was produced |
| `timezone` | string | IANA timezone |
| `sha256` | string | Required for files |
| `fileSizeBytes` | integer | Required for files |
| `mimeType` | string | File/content type |
| `confidentiality` | string | public, internal, confidential, restricted, privileged |
| `integrityStatus` | string | unverified, verified, hash_mismatch, superseded |
| `chainOfCustody` | array | Transfers, accesses, exports |
| `relatedSystems` | string[] | Systems/services |
| `relatedUsers` | string[] | Users/accounts |
| `relatedTimelineEvents` | string[] | Timeline IDs |
| `tags` | string[] | Search |
| `retentionPolicy` | object | Duration, legal hold, disposal |
| `immutable` | boolean | Default true |
| `version` | integer | Starts at 1 |

## Impact Assessment

Each impact category has separate score and confidence:

- Availability
- Integrity
- Confidentiality
- Performance
- Financial
- Operational
- Legal
- Compliance
- Customer experience
- Reputation
- Safety
- Environmental

Fields: `category`, `severity`, `confidence`, `narrative`, `metrics`, `estimatedCost`, `customerCount`, `affectedRecords`, `evidenceRefs`.

## RCA

The RCA object supports multiple methods:

- Five Whys
- Fishbone/Ishikawa
- Fault Tree Analysis
- Contributing Factors
- Human Factors
- Technical Factors
- Process Factors
- Organizational Factors
- Detection Gaps
- Monitoring Gaps
- Documentation Gaps

Each finding links to evidence and action items.

## Action Item

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string | `ACT-0001` |
| `title` | string | Short action title |
| `description` | string | Detailed work |
| `owner` | object | Person/team |
| `priority` | string | P0-P4 |
| `status` | string | proposed, accepted, in_progress, blocked, complete, verified, canceled |
| `dueDate` | date | Required for accepted actions |
| `dependencies` | string[] | Other action IDs |
| `estimatedEffort` | string | hours/days/sprints |
| `riskReduction` | string | Expected reduction |
| `verificationMethod` | string | How completion is proven |
| `completionEvidenceRefs` | string[] | Evidence IDs |

## Validation Rules

- `id`, `title`, `category`, `severity`, `status`, `createdAt`, `timezone`, and `ownership.incidentCommander` are required before `open`.
- Every state transition must include `actor`, `timestamp`, `from`, `to`, and `reason`.
- `resolvedAt` is required before `resolved`.
- `rca.summary`, at least one contributing factor, and at least one accepted action item are required before `postmortem`.
- All customer-facing communications require approval if `impactAssessments.customerExperience.severity >= medium` or `regulatory.possibleNotificationRequired = true`.
- Evidence files require SHA-256, file size, MIME type, collector, source, collected timestamp, confidentiality, and retention policy.
- Attachments classified as `keys`, `credentials`, or `secrets` require secure-reference storage, never raw export.
- Security incidents require `security.exposureAssessment` before closure.
- Data loss/data corruption/privacy incidents require integrity/confidentiality impact assessments.
- Scheduled maintenance requires start/end windows and customer notice policy.

## Access Control

Access decisions should consider:

- Role: commander, engineer, security, legal, executive, auditor, support.
- Incident classification.
- Evidence classification.
- Customer/business-unit scope.
- Legal hold and privilege.
- Need-to-know for regulated data.

## Retention

Default retention:

- Operational incidents: 2 years
- Security incidents: 5 years
- Privacy/regulatory incidents: 7 years or legal requirement
- Evidence under legal hold: indefinite until released
- Customer-facing communications: 7 years