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

```yaml
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

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

## 3. Question

```yaml
question:
  text:
  decision_class:
  trigger:
```

## 4. Kind

```yaml
kind:
  primary: choice
  secondary:
    - experiment
```

Candidate values:

```text
choice
bet
experiment
commitment
delegation
allocation
authorization
exception
policy
constitutional
```

## 5. State

```yaml
state:
  lifecycle: committed
  since:
```

Candidate lifecycle values:

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

## 6. Frame

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

## 7. Alternatives

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

## 8. Evidence

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

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

Candidate epistemic statuses:

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

## 9. World model

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

## 10. Values

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

## 11. Analysis

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

  recommendation:
```

## 12. Uncertainty

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

## 13. Information options

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

## 14. Governance

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

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

  delegation:
  escalation:
  oversight:
```

## 15. Commitment

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

## 16. Effects

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

Candidate effect types:

```text
action
allocation
authorization
constraint
delegation
policy
incentive
default
prohibition
requirement
```

## 17. Execution

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

## 18. Outcome

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

## 19. Learning

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

## 20. Optionality

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

## 21. Relationships

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

Candidate relationship types:

```text
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

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

## 23. Metadata

```yaml
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?