Reference

Decision Record Schema

Version: 0.1
Status: Draft
Lineage: System intent decisions

Purpose

A decision record captures an explicit human decision regarding an inferred system intent element.

Decision records:

  • Establish authority
  • Preserve rationale
  • Enable traceability
  • Support audit and review

Decision records are immutable and version-linked.

Schema overview

A decision record consists of:

  • Identification
  • Decision classification
  • Intent element reference
  • Human authorship
  • Evidence and rationale
  • Supersession linkage

All fields defined below are normative unless explicitly marked optional.

Field definitions

decisionRecordId

Type: string

Required: yes

Immutable: yes

Globally unique identifier for the decision record.

This identifier is never reused.

decisionType

Type: enum

Required: yes

Allowed values:

  • accept
  • modify
  • reject
  • defer

Defines the semantic outcome of the decision.

Each decision record MUST declare exactly one decision type.

intentElement

Type: object

Required: yes

Identifies the intent element under review.

intentElement.intentId

Type: string

Unique identifier of the intent element.

intentElement.axis

Type: enum

One of:

  • component
  • function
  • mode
  • scenario
  • interface
  • signal
  • hazard
  • safetyConstraint
  • uca

Axis names may be extended in project-specific schemas. See Intent Axes and the Axis Definition Schema for more information.

intentElement.label

Type: string

Human-readable description of the intent element at the time of review.

intentElement.version

Type: string

The intentSnapshotId of the intent snapshot in which the element appears.

decisionAuthor

Type: object

Required: yes

Identifies the human making the decision.

decisionAuthor.name

Type: string

Full name of the decision author.

decisionAuthor.role

Type: string

Engineering or review role.

decisionAuthor.organization

Type: string

Organizational affiliation.

decisionTimestamp

Type: string (ISO 8601 timestamp)

Required: yes

Records when the decision was made.

This timestamp refers to the decision, not the inference.

sourceArtifacts

Type: array of objects

Required: yes

Lists artifacts used to justify the decision.

Each entry includes:

sourceArtifacts[].artifactId

Type: string

Identifier of the artifact.

sourceArtifacts[].artifactType

Type: enum

Typical values include:

  • requirement
  • document
  • model
  • analysis
  • email
  • meetingNote
  • image

Artifact types are extensible.

sourceArtifacts[].reference

Type: string

Human-readable reference such as section number, filename, or description.

rationale

Type: string

Required: yes

Free-text explanation of the decision.

The rationale should explain:

  • Why the decision was made
  • Why alternatives were rejected
  • What assumptions apply

Empty rationales are not permitted.

supersedesDecisionId

Type: string or null

Required: no

References a prior decision record that is superseded by this one.

If present, the referenced decision record remains valid historically but is no longer active.

Formal JSON representation

{
  "decisionRecordId": "string",
  "decisionType": "accept | modify | reject | defer",
  "intentElement": {
    "intentId": "string",
    "axis": "component | function | mode | scenario | interface | signal | hazard | safetyConstraint | uca",
    "label": "string",
    "version": "string"
  },
  "decisionAuthor": {
    "name": "string",
    "role": "string",
    "organization": "string"
  },
  "decisionTimestamp": "YYYY-MM-DDThh:mm:ssZ",
  "sourceArtifacts": [
    {
      "artifactId": "string",
      "artifactType": "string",
      "reference": "string"
    }
  ],
  "rationale": "string",
  "supersedesDecisionId": "string | null"
}

Examples

Example: Accept decision

{
  "decisionRecordId": "DR-001",
  "decisionType": "accept",
  "intentElement": {
    "intentId": "INT-SAF-003",
    "axis": "safetyConstraint",
    "label": "Transition to inertial navigation on GNSS signal loss during approach",
    "version": "intent-v1.2"
  },
  "decisionAuthor": {
    "name": "A. Engineer",
    "role": "Systems Engineer",
    "organization": "Example Aerospace"
  },
  "decisionTimestamp": "2025-03-14T10:42:00Z",
  "sourceArtifacts": [
    {
      "artifactId": "R3",
      "artifactType": "requirement",
      "reference": "Navigation Spec §4.2"
    }
  ],
  "rationale": "The requirement explicitly describes behavior intended to preserve situational awareness under degraded conditions.",
  "supersedesDecisionId": null
}

Example: Modify decision

{
  "decisionRecordId": "DR-002",
  "decisionType": "modify",
  "intentElement": {
    "intentId": "INT-SCN-001",
    "axis": "scenario",
    "label": "GNSS signal loss",
    "version": "intent-v1.2"
  },
  "decisionAuthor": {
    "name": "A. Engineer",
    "role": "Systems Engineer",
    "organization": "Example Aerospace"
  },
  "decisionTimestamp": "2025-03-14T11:05:00Z",
  "sourceArtifacts": [
    {
      "artifactId": "R4",
      "artifactType": "requirement",
      "reference": "Navigation Spec §4.3"
    }
  ],
  "rationale": "Protected mode is entered under multiple conditions. Scenario description is too narrow.",
  "supersedesDecisionId": null
}

Example: Reject decision

{
  "decisionRecordId": "DR-003",
  "decisionType": "reject",
  "intentElement": {
    "intentId": "INT-MOD-004",
    "axis": "mode",
    "label": "Emergency mode",
    "version": "intent-v1.2"
  },
  "decisionAuthor": {
    "name": "A. Engineer",
    "role": "Certification Engineer",
    "organization": "Example Aerospace"
  },
  "decisionTimestamp": "2025-03-14T11:30:00Z",
  "sourceArtifacts": [
    {
      "artifactId": "NavSpec",
      "artifactType": "document",
      "reference": "Full document review"
    }
  ],
  "rationale": "No artifact supports the existence of an emergency mode.",
  "supersedesDecisionId": null
}

Notes on extensibility

  • Axis values may be extended in project-specific schemas
  • Artifact types are intentionally open-ended
  • Additional metadata fields may be added without altering core semantics

Backward compatibility is a design goal.

Intended use

This schema is intended to be:

  • Referenced by tools
  • Cited in audits
  • Used as a stable contract for decision traceability

It is not intended to encode workflow or approval logic.