Traits / Approvable
Approvable
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.
Generated from @oods/foundry 0.18.0
- Group
- core
- Maturity
- alpha
- Contexts
- detail
Fields it adds
| Field | Type | Required | Description |
|---|---|---|---|
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
levelsstring[], 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`).
levelDefinitionsRecord<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.
requiredLevelsRecord<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.
approvalsNeededRecord<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.
askerMayAnswerboolean- Whether your product permits the asker to give the yes. The default is false. Your product checks who answered.
agentLevelsstring[]- The levels for which your product accepts an agent’s yes. The default list is empty. Your product checks who answered.
lapsesOnChangeboolean- Whether your product marks an earlier yes out of date when the thing changes. OODS Foundry keeps the setting.
inAdvancestring[]- 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.
outcomesstring[], 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"