Fields it adds

FieldTypeRequiredDescription
approval_state string no The outcome, worked out by the product from the approvals that still stand and written here. Named apart from Stateful's `status`, so a thing keeps its lifecycle and its approval outcome side by side. Read-only: it is shown on the detail page and kept off the form.
approval_summary string no One kept line saying what the outcome rests on ("Approved by Ruth Adeyemi · version 3 · 2 Nov"), or why no approval was asked. It restates the Approval records, since a thing's own page lists its approvals only where the thing declares that list (metadata.relatedLists), and no shipped object does. Read-only.

What it shows in each context

detail
StatusBadge, Text

Parameters

levels string[], required
The levels of yes the product declares, least deliberate first, each named for the kind of yes asked for. Every level the rule names is one of these, and the approvals of this thing are asked at these levels (Decision's `levels`).
levelDefinitions Record<string, LevelDefinition>
What each level is, keyed by its name: who may give it, what it permits, what must be in front of the person, what a wrong one costs, how deliberate the act is, and when it lapses. Each key is a declared level. A product declares its own, beside its own levels; the four example levels' definitions are in this trait's metadata.
requiredLevels Record<string, string>
Which change needs which level: each key is a change (a lifecycle state the thing moves to, such as published, or a named action, such as resend), each value a declared level. Under this rule your product requires no approval for an unlisted change.
approvalsNeeded Record<string, number>
How many eligible approvers your product requires at each named level. The map starts empty. For a level with no count, the rule calls for one eligible approver. Your product checks and counts the answers.
askerMayAnswer boolean
Whether your product permits the asker to give the yes. The default is false. Your product checks who answered.
agentLevels string[]
The levels for which your product accepts an agent’s yes. The default list is empty. Your product checks who answered.
lapsesOnChange boolean
Whether your product marks an earlier yes out of date when the thing changes. OODS Foundry keeps the setting.
inAdvance string[]
The changes a standing yes, given in advance under a grant, may allow without a person being asked at the time. Each is a change `requiredLevels` names; where the rule declares two or more levels, none needs the last, most deliberate one, which is always asked. Empty by default, so every change the rule names is asked each time. The product checks a standing yes against its grant's terms; OODS Foundry keeps the setting and shows the outcome.
outcomes string[], required
The outcomes `approval_state` can hold, as the product works them out: not required, waiting, approved, declined, out of date by default. Not required means the rule asks for no approval for this change. Not needed is the ending of a particular Approval that is no longer needed. A rule that opens changes in advance may add allowed in advance (`allowed_in_advance`): the change needed a yes, and a grant's standing yes gave it, with no one asked this time.

Objects that use it

The trait file

traits/core/Approvable.trait.yaml
trait:
  name: Approvable
  version: 1.1.1
  description: |
    The ability to be approved: the thing's own rule for which change needs which level of yes, from how many and from
    whom, and its outcome, worked out from the approvals that still stand. The approvals themselves are records of
    their own (the Approval object, through the Decision trait): one ask to one actor that becomes their answer.

    The rule is the parameters. `levels` names the levels of yes the product declares, least deliberate first, as Decision does on
    the Approval; `levelDefinitions` says what each one is, in six short texts; `requiredLevels` says which change (a
    state the thing moves to, or a named action) needs which level; `approvalsNeeded`, `askerMayAnswer`,
    `agentLevels` and `lapsesOnChange` say how many, whether the asker may answer, which levels an agent's yes may
    satisfy, and whether a yes lapses when the thing changes. `inAdvance` names the changes a grant's standing yes may
    allow in advance, where the product lets a yes given earlier stand for one asked now; it is empty by default, so
    every change the rule names is asked each time. The definitions are kept with the rule; no screen changes by level.

    The outcome is two read-only fields: `approval_state`, under a name of its own so it never collides with the
    lifecycle's `status`, and `approval_summary`, one kept line ("Approved by Ruth Adeyemi · version 3 · 2 Nov").
    The product's own code works the outcome out from the approvals and writes both fields; they are kept off the
    thing's form and shown on its detail page. The summary restates the Approval records, since a thing's own page lists
    its approvals only where the thing declares that list (metadata.relatedLists), and no shipped object does.

    OODS Foundry shows the outcome; it does not work it out. It does not count approvals, check who may approve,
    expire an ask, lock the thing or stop a change.
  category: core
  # Compound tags, as Decision's: inherited by StatusBadge and Text, they change how no screen picks its components.
  tags:
    - approval-rule
    - approval-outcome
    - declared-levels

parameters:
  - name: levels
    type: string[]
    required: true
    description: |
      The levels of yes the product declares, least deliberate first, each named for the kind of yes asked for. Every
      level the rule
      names is one of these, and the approvals of this thing are asked at these levels (Decision's `levels`).
    default:
      - acknowledgement
      - review
      - approval
      - sign_off

  - name: levelDefinitions
    type: "Record<string, LevelDefinition>"
    required: false
    description: |
      What each level is, keyed by its name: who may give it, what it permits, what must be in front of the person,
      what a wrong one costs, how deliberate the act is, and when it lapses. Each key is a declared level. A product
      declares its own, beside its own levels; the four example levels' definitions are in this trait's metadata.
    default: {}

  - name: requiredLevels
    type: "Record<string, string>"
    required: false
    description: |
      Which change needs which level: each key is a change (a lifecycle state the thing moves to, such as published,
      or a named action, such as resend), each value a declared level. Under this rule your product requires no approval for an unlisted change.
    default: {}

  - name: approvalsNeeded
    type: "Record<string, number>"
    required: false
    description: |
      How many eligible approvers your product requires at each named level. The map starts empty.
      For a level with no count, the rule calls for one eligible approver. Your product checks and counts the answers.
    default: {}

  - name: askerMayAnswer
    type: boolean
    required: false
    description: Whether your product permits the asker to give the yes. The default is false. Your product checks who answered.
    default: false

  - name: agentLevels
    type: string[]
    required: false
    description: The levels for which your product accepts an agent’s yes. The default list is empty. Your product checks who answered.
    default: []

  - name: lapsesOnChange
    type: boolean
    required: false
    description: Whether your product marks an earlier yes out of date when the thing changes. OODS Foundry keeps the setting.
    default: true

  - name: inAdvance
    type: string[]
    required: false
    description: |
      The changes a standing yes, given in advance under a grant, may allow without a person being asked at the time.
      Each is a change `requiredLevels` names; where the rule declares two or more levels, none needs the last, most
      deliberate one, which is always asked. Empty by default, so every change the rule names is asked each time. The product checks a standing yes
      against its grant's terms; OODS Foundry keeps the setting and shows the outcome.
    default: []

  - name: outcomes
    type: string[]
    required: true
    description: |
      The outcomes `approval_state` can hold, as the product works them out: not required, waiting, approved,
      declined, out of date by default. Not required means the rule asks for no approval for this change.
      Not needed is the ending of a particular Approval that is no longer needed. A rule that opens changes in advance may add allowed in advance
      (`allowed_in_advance`): the change needed a yes, and a grant's standing yes gave it, with no one asked this time.
    default:
      - not_required
      - waiting
      - approved
      - declined
      - out_of_date

schema:
  approval_state:
    type: string
    required: false
    readOnly: true
    description: |
      The outcome, worked out by the product from the approvals that still stand and written here. Named apart from
      Stateful's `status`, so a thing keeps its lifecycle and its approval outcome side by side. Read-only: it is shown
      on the detail page and kept off the form.
    validation:
      enumFromParameter: outcomes
  approval_summary:
    type: string
    required: false
    readOnly: true
    description: |
      One kept line saying what the outcome rests on ("Approved by Ruth Adeyemi · version 3 · 2 Nov"), or why no
      approval was asked. It restates the Approval records, since a thing's own page lists its approvals only where the
      thing declares that list (metadata.relatedLists), and no shipped object does. Read-only.
    validation:
      maxLength: 240

semantics:
  approval_state:
    semantic_type: approval.outcome
    token_mapping: tokenMap(status.state.*)
    ui_hints:
      component: StatusBadge
      showIcon: true
  approval_summary:
    semantic_type: approval.outcome.summary
    token_mapping: tokenMap(text.body.*)
    ui_hints:
      component: Text
      label: Approvals

view_extensions:
  # The outcome sits on the detail page beside the record's other facts, as a labelled state and the line it rests on.
  # Approvable places nothing on the form: both fields are read-only, so the thing's form is the one it had.
  detail:
    - component: StatusBadge
      position: main
      priority: 58
      props:
        statusField: approval_state
        emphasis: subtle
        showIcon: true
    - component: Text
      position: main
      priority: 57
      props:
        field: approval_summary

dependencies: []

metadata:
  created: "2026-11-11"
  updated: "2026-11-14"
  owners:
    - Core team
  maturity: alpha
  accessibility:
    keyboard: Approvable adds no interactive control; its outcome renders as text.
    screenreader: The outcome is announced as visible text through StatusBadge, never by colour alone, with its summary as labelled text.
  regionsUsed:
    - detail
  # Illustrative only: the four example levels, each defined in the six parts a level names. A product declares its
  # own in levelDefinitions, beside its own levels.
  levelExamples:
    acknowledgement:
      who: Anyone the thing is shown to
      permits: Nothing; it records that the person has seen it
      shown: The thing, as it is now
      cost: Little; a missed one is asked again
      act: One step
      lapses: Never; it records a moment
    review:
      who: Someone who knows the subject
      permits: Nothing on its own; it counts toward an approval
      shown: The thing and what changed
      cost: A mistake that someone else may still catch
      act: A careful read, then one step
      lapses: When the thing changes
    approval:
      who: The person whose decision it is
      permits: The change it was asked for
      shown: Exactly what will change
      cost: The change happens when it should not
      act: A deliberate yes or no
      lapses: When the thing changes, or once it is used
    sign_off:
      who: The person who answers for the result
      permits: The thing to go out under their name
      shown: The exact version, and what the yes means
      cost: A person answers for something they did not mean to
      act: The most deliberate, with its meaning written down
      lapses: Never for that version; a new version needs a new sign-off
  examples:
    - Transaction
    - Article
  references:
    - "Gerrit: Code-Review +1 'Looks good to me, but someone else must approve' and +2 'Looks good to me, approved'"
    - "Docusign: 'Needs to View' recipients, and Part 11 signing that asks the signer for a reason"
    - "21 CFR Part 11 and eIDAS: a signature bound to the content and its meaning"