Skip to manual
gluon

GOL language

ActionType

An ActionType is a command people and clients can run, with parameters, preconditions, effects and approvals.

Model author or developer

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.

FieldPresenceShape
targetRequiredref
parametersOptionalobject
sectionsOptionalarray
preconditionsOptionalarray
effectsRequiredarray
sideEffectsOptionalarray
approvalOptionalobject
executionOptionalobject
riskTierOptionalenum: A, B, C, D
lifecycleOptionallifecycle
authorizationOptionalobject
auditOptionalenum: none, summary, full
exposeOptionalexpose
sagaOptionalboolean
revertibleOptionalboolean
revertWindowOptionalduration

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)

GOL · YAML
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):

TierMeaningThe validator requires
A Assistread, summarise, draft; no side effect outside Gluonnothing extra
B Adviseoutput influences a decision a person takesowners and a lifecycle.reviewBy
C Actwrites to a system or sends a communicationapproval, execution.idempotencyKey, execution.compensate (GLN-E581), audit: full
D High impactmaterially affects a person's benefits, employment or rightseverything 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:

LevelBehaviour the runtime permitsDerived when
L0 readretrieve, explain, compute; no effect of any kindviews and pure functions
L1 draftproduce 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 communicationan action whose effects are only such creates
L2 proposebuild the packet (parameters, checks, packet) and stop; nothing executes, a person initiatesany action when the effective level is capped at L2
L3 execute with bound authorisationexecute 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 runan action with effects beyond L1
L4 bounded automaticexecute 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

Shell
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.

Contoso's RenewContract ActionType in the designer's YAML pane, with its validation status.
Contoso's RenewContract ActionType in the designer's YAML pane, with its validation status.