Skip to content

Library · Data Practice OS

Decision record schema

Template · Published · Source reviewed

One record per decision with a consequence. The reasoning behind each field is in Decision records and provenance. Field names follow W3C PROV where a PROV term fits, so the records can be exported as PROV later.

Status. A proposed template. Not an agreed standard. Retention and privacy treatment need confirming with records management and privacy for each decision type.

Record references, not payloads. Point to source records and their versions. Copy content only where the decision cannot be explained without it.

YAML

decision_record:
  schema_version: 0.1
  decision_id: DR-2026-000123              # carried into the work order, letter or case
  decision_type: defect-priority           # a row in the decision inventory
  subject_ref: defect:DEF-88412            # what the decision is about; never free-text PI
  decided_at: 2026-11-06T09:42:00+10:00
  supersedes: null                         # decision_id this record corrects, if any

  facts_used:                              # prov:used (entities)
    - ref: asset:RD-104/ch-12.40
      version: 2026-11-05T22:00:00+10:00   # as-at time of the data product
      source: maintenance.asset_condition
    - ref: defect:DEF-88412
      version: 3
      source: maintenance.open_defects

  rules_applied:                           # prov:used (plan)
    - rule_id: defect-priority-matrix
      version: 2026-07
      effective_from: 2026-07-01
      status: approved                     # only approved rules may be applied
      matched: row 2

  context_sources:                         # what the assistant retrieved
    - ref: doc:maintenance-standard
      version: "4.2"
      passage: section 3.1

  ai_involvement:                          # prov:wasAssociatedWith (software agent)
    mode: recommend                        # none | read | recommend | approve | execute
    service: defect-ranking-assistant
    model: <model id and route>
    prompt_version: 1.3
    recommendation: P2, 7 days
    confidence: 0.82

  authority:                               # prov:actedOnBehalfOf
    decided_by: role:district-works-planner
    delegation: <delegation instrument and level>

  human_review:
    reviewer: role:district-works-planner
    action: accepted                       # accepted | changed | overridden | escalated
    reason_code: null                      # required when changed or overridden
    review_seconds: 95

  result:
    decision: P2, respond within 7 days
    communicated: work order WO-55120

  outcome:                                 # appended later, never edited in place
    - recorded_at: 2026-11-12T14:00:00+10:00
      signal: repaired
      detail: within target
    - recorded_at: 2027-05-12T00:00:00+10:00
      signal: no-recurrence-6-months

  governance:
    classification: OFFICIAL               # at least that of the most sensitive fact used
    retention_class: <schedule and class>
    contains_personal_information: false

Table

Field Required Type PROV mapping Notes
decision_id Y string prov:Entity id Carry it into every downstream artefact
decision_type Y string Key into Decision inventory
subject_ref Y reference Identifier, not personal details
decided_at Y timestamp (AEST/AEDT offset) prov:generatedAtTime
supersedes N decision_id prov:wasRevisionOf Corrections are new records
facts_used[] Y ref, version, source prov:used Version or as-at time is mandatory (Effective dating)
rules_applied[] Y if rules apply rule_id, version, effective_from, status, matched prov:used / prov:Plan status must be approved (Rule authority)
context_sources[] Y if AI used ref, version, passage prov:used What the model saw
ai_involvement Y if AI used mode, service, model, prompt_version, recommendation, confidence prov:SoftwareAgent, prov:wasAssociatedWith Separates the AI's part from the human's
authority Y role, delegation prov:actedOnBehalfOf
human_review Y if mode ≠ execute reviewer, action, reason_code, review_seconds prov:Activity Reason code required for overrides (Human in the loop)
result Y decision, communicated prov:wasGeneratedBy
outcome[] Later recorded_at, signal, detail prov:wasInfluencedBy (reverse link) Append-only (Outcome feedback loops)
governance Y classification, retention_class, contains_personal_information Treat as sensitive as the facts used (Personal information)

Checks before go-live

  • [ ] Every field marked Y is populated by the workflow at decision time, not reconstructed later.
  • [ ] decision_id appears in the work order, letter, case or permit.
  • [ ] Records land in the platform as a contracted data product with classification and masking.
  • [ ] Retention is set per decision type and implemented as policy.
  • [ ] A decision can be replayed: facts at their versions, rules at their versions, same result.

Source links: Data Practice reading list.