decision-canon/DecisionObjectSchemaDraft.md

Decision Object Schema Draft v0.1

This is an intentionally loose structural draft.

It is not yet a normative JSON Schema.

The purpose is to identify modules and boundaries before freezing field names or validation rules.

1. Top-level shape

decision:
  identity:
  question:
  kind:
  state:

  frame:
  alternatives:
  evidence:
  world_model:
  values:
  analysis:
  uncertainty:
  information_options:
  governance:
  commitment:
  effects:
  execution:
  outcome:
  learning:
  optionality:
  relationships:
  temporal:
  metadata:

2. Identity

identity:
  id: DEC-...
  title:
  namespace:
  version:

3. Question

question:
  text:
  decision_class:
  trigger:

4. Kind

kind:
  primary: choice
  secondary:
    - experiment

Candidate values:

choice
bet
experiment
commitment
delegation
allocation
authorization
exception
policy
constitutional

5. State

state:
  lifecycle: committed
  since:

Candidate lifecycle values:

noticed
framed
open
recommended
committed
effective
observed
reviewed
closed
deferred
delegated
cancelled
expired
superseded
revoked

6. Frame

frame:
  situation:
  scope:
  horizon:
  boundaries:
  assumptions: []
  exclusions: []
  stakeholders: []
  dependencies: []

7. Alternatives

alternatives:
  - id: A
    label:
    action:
    description:
    prerequisites: []
    reversibility:
      level:
      cost:
      delay:

8. Evidence

evidence:
  claims:
    - id:
      statement:
      status:
      confidence:
      source:
      valid_at:

  observations: []
  assumptions: []
  sources: []

Candidate epistemic statuses:

unknown
not-applicable
not-investigated
estimated
assumed
observed
derived
inferred
decided

9. World model

world_model:
  states: []
  variables: []
  relationships: []
  causal_model:
  scenarios: []

10. Values

values:
  objectives: []
  constraints: []
  preferences: []
  thresholds: []
  vetoes: []
  tradeoffs: []

11. Analysis

analysis:
  analyses:
    - id:
      method:
      model:
      inputs:
      result:
      confidence:
      sensitivity:
      robustness:

  recommendation:

12. Uncertainty

uncertainty:
  known_unknowns: []
  model_uncertainty: []
  outcome_uncertainty: []
  ambiguity: []
  reducible: []
  irreducible: []

13. Information options

information_options:
  - question:
    method:
    cost:
    delay:
    expected_information_value:

14. Governance

governance:
  owner:
  authority:
    source:
    scope:
    can:
    may:
    must:

  advisors: []
  approvers: []
  challengers: []
  affected_parties: []

  delegation:
  escalation:
  oversight:

15. Commitment

commitment:
  selected:
  by:
  at:
  mode:
  confidence:
  conditions: []
  reservations: []

16. Effects

effects:
  - id:
    type:
    target:
    value:
    effective_when:
    expires_when:

Candidate effect types:

action
allocation
authorization
constraint
delegation
policy
incentive
default
prohibition
requirement

17. Execution

execution:
  intended_actions: []
  responsible: []
  status:
  started_at:
  completed_at:
  evidence: []

18. Outcome

outcome:
  observations: []
  metrics: []
  unintended_effects: []
  stakeholder_effects: []
  occurred_at:

19. Learning

learning:
  expected:
  observed:
  deviations: []
  hypothesis_updates: []
  calibration:
  lessons: []
  followup_decisions: []

20. Optionality

optionality:
  reversible:
  reversal_cost:
  reversal_delay:
  locks_in: []
  options_created: []
  options_destroyed: []

21. Relationships

relationships:
  - type: governed-by
    target: POLICY-SEC-001

Candidate relationship types:

derived-from
implements
governed-by
delegated-by
authorized-by
triggered-by
depends-on
challenges
reviews
supersedes
revokes
exception-to
resulted-in
learned-from

22. Temporal

temporal:
  created_at:
  decision_time:
  effective_from:
  effective_until:
  observed_at:
  reviewed_at:

23. Metadata

metadata:
  formality_level: D3
  tags: []
  schema_version:

24. Open design questions

• Which fields belong in the immutable kernel?
• Which fields should be versioned instead of overwritten?
• How should competing analyses be represented?
• How should probabilities and utility models be encoded?
• Should authority assertions use a separate canonical model?
• How should policy primitives map to executable rule systems such as DMN or OPA-style policy engines?
• How should nested or dependent decisions be modelled?
• Which relationship semantics should be normative?
• How should decision-time snapshots be preserved?
• What minimum structure is necessary for reliable decision lineage?