Where it goes
Contoso keeps RenewContract in domains/procurement/actions/renew-contract.yaml. The loader reads every YAML file under the package root, so folders are a convention you can change. Name it in PascalCase. The name must be unique within its domain across all type kinds.
Fields
The keys under spec. Nested shapes follow ActionTypeSpec in the GOL JSON Schema.
| Field | Presence | Shape |
|---|---|---|
target | Required | ref |
parameters | Optional | object |
sections | Optional | array |
preconditions | Optional | array |
effects | Required | array |
sideEffects | Optional | array |
approval | Optional | object |
execution | Optional | object |
riskTier | Optional | enum: A, B, C, D |
lifecycle | Optional | lifecycle |
authorization | Optional | object |
audit | Optional | enum: none, summary, full |
expose | Optional | expose |
saga | Optional | boolean |
revertible | Optional | boolean |
revertWindow | Optional | duration |
Syntax and rules
The examples are fragments. Put them in a package next to the resources they reference. A ... stands for a CEL expression you write yourself.
9.1 ActionType (command)
kind: ActionType
metadata: { name: RenewContract, title: Renew contract }
spec:
target: Contract # aggregate root the command addresses
parameters:
contract: { type: Contract, required: true }
newExpiry: { type: date, required: true }
note: { type: text }
preconditions: # submission criteria
- {
expr: "params.contract.state in ['active','expiring']",
message: Only live contracts can be renewed.,
}
- { expr: "params.newExpiry > params.contract.expiryDate", message: New expiry must be later. }
effects: # ordered, atomic
- modify: { object: params.contract, set: { expiryDate: params.newExpiry, state: active } }
- create:
{
type: ContractEvent,
set: { kind: renewed, note: params.note },
link: { contract: params.contract },
}
- emit: { event: ContractRenewed, with: { contractId: params.contract.contractId } }
sideEffects:
- notify: { to: params.contract.owner, template: contract-renewed }
- webhook:
{
target: "source:erp-contracts",
operation: updateExpiry,
retry: { max: 5, backoff: exponential },
}
approval:
{
required: "params.contract.value.amount > 100000.0",
approvers: ["role:procurement-lead"],
quorum: 1,
expiresAfter: P3D,
}
execution:
{
idempotencyKey: "params.contract.contractId + string(params.newExpiry)",
timeout: PT30S,
durable: true,
}
authorization: { policy: "policy:renew-contracts" }
audit: full # none | summary | full
expose: { chat: true, api: true, mcp: { tool: renew_contract }, apps: true }
Parameters accept every property type plus Object, list<Object>, an Interface, an ObjectView (object set) and marking. Per parameter: required default prefill (currentUser | now | expr) visible editable constraints choices: {from: ObjectView, where} and overrides: [{when: CEL, set: {visible, required, editable, default}}] for conditional forms. sections group parameters for generated forms in chat and apps.
Effect verbs: create modify upsert delete link unlink call emit. Effects may target an Interface (modify: {interface: core.Agreement, ...}), in which case every implementer must permit the edit (GLN-E252). revertible: true records the inverse edit so the action can be undone within revertWindow. Only successful executions write the action log; rejected submissions go to the audit log. call invokes a Function. An action whose effects touch more than one aggregate must set saga: true and give each effect a compensate.
9.1.1 Risk tier, autonomy level, lifecycle
Every ActionType and ObjectView carries a risk tier that classifies its consequence, not its data (data is classified by markings):
| Tier | Meaning | The validator requires |
|---|---|---|
| A Assist | read, summarise, draft; no side effect outside Gluon | nothing extra |
| B Advise | output influences a decision a person takes | owners and a lifecycle.reviewBy |
| C Act | writes to a system or sends a communication | approval, execution.idempotencyKey, execution.compensate (GLN-E581), audit: full |
| D High impact | materially affects a person's benefits, employment or rights | everything in C, lifecycle.evaluation naming the assessment, and the deployment cannot grant more than L2 (GLN-E582) |
riskTier defaults to A for views and pure functions and to C for every action with an effect beyond L1; an author lowers it only explicitly, and the compatibility pass reports the lowering as W652.
The autonomy level is a behaviour, never a label the author writes. It is derived from the definition and enforced by the decision point as a behaviour table, shown on the action card, the MCP tool description and the deployment page:
| Level | Behaviour the runtime permits | Derived when |
|---|---|---|
L0 read | retrieve, explain, compute; no effect of any kind | views and pure functions |
L1 draft | produce an artefact a person will edit or send; the only permitted effect is create of an object whose lifecycle state is a declared draft state, inside Gluon; no notification, no webhook, no external communication | an action whose effects are only such creates |
L2 propose | build the packet (parameters, checks, packet) and stop; nothing executes, a person initiates | any action when the effective level is capped at L2 |
L3 execute with bound authorisation | execute after a human approval bound to actor, parameters, target revision and ontology version, or after a human initiation when approval.required evaluates false for that run | an action with effects beyond L1 |
L4 bounded automatic | execute without a per-run human, only inside execution.rateLimit, a Capability.budget, an allow-listed action set and a shadow match rate on the scorecard; every non-revertible effect has a compensate (GLN-E583) | an action the deployment and the Capability both allow at L4 |
The effective level of a run is the minimum of the action's derived level, the Capability's maxAutonomy and the Deployment's maxAutonomy. Capping to L2 or lower means no execution at all, whatever the approval rule says; a tier D action can never run above L2 (GLN-E582). The transaction-level approval rule is a separate control that applies at L3 and L4 and is never waived by a level. notify, webhook, emit, link, unlink, delete, modify, upsert, an effectful call and any create outside a draft state are all effects beyond L1.
lifecycle: {reviewBy: 2027-03-31, expires: 2027-09-30, evaluation: eval-2026-09} puts a review date on anything exposed. GLN-W584 from 30 days before reviewBy; GLN-E585 after expires blocks publish and the deployed element is disabled at that date. execution.rateLimit: {perSubject: 20, perDeployment: 500, window: PT1H} bounds runs; execution.compensate is an effect run when the action fails after a side effect was sent.
Check your package
gluon validate examples/contoso
gluon test examples/contoso
validate reports each problem with a GLN code and its place in the file. test runs the package's Test resources. See the language guide and the diagnostics.
