MODEL DEFINITIONS

A model definition is a YAML file that configures an instance of a model type. Definitions are stored in one of two locations depending on how they are created.

To inspect a model type's methods, arguments, and output specs before creating a definition, see model type describe below.

Definition Storage

models/ (via model create)

swamp model create command/shell my-shell --global-arg prefix="swamp says"

Definitions created with model create are stored in models/{type}/{id}.yaml. They are git-tracked and included in model search results.

models/
  command/
    shell/
      83e5906c-3d3f-4ffe-84f9-5e01f6e9037c.yaml
      53274ce2-c390-412b-93ac-48b205a13f4e.yaml

The directory path encodes the model type. The filename is the definition's UUID.

.swamp/auto-definitions/ (via direct type execution)

swamp model @command/shell method run execute my-shell --input 'run=echo hello'

When a definition with the given name does not exist, one is created automatically in .swamp/auto-definitions/{type}/{id}.yaml. On subsequent runs, the existing definition is reused after verifying the type matches. --input values are split between global arguments and method arguments using the type's schemas — method arguments take precedence on ambiguous keys. Unknown keys are rejected with an error listing valid inputs.

.swamp/
  auto-definitions/
    command/
      shell/
        a1b2c3d4-e5f6-7890-abcd-ef1234567890.yaml

The same directory and filename conventions apply. Auto-definitions are not git-tracked and are not included in model search results. They are findable by model get and are included in DEFAULT_DATASTORE_SUBDIRS for datastore sync.

Comparison

Top-Level Fields

type: command/shell
typeVersion: 2026.02.09.1
id: 83e5906c-3d3f-4ffe-84f9-5e01f6e9037c
name: hello-world
version: 1
tags: {}
globalArguments: {}
methods: {}

Optional fields omitted above: inputs, checks, reports. These appear in the YAML only when explicitly set.

type

Model type identifier.

The type value is normalized to a lowercase, slash-delimited path. Swamp applies these transformations:

• AWS::EC2::VPC → aws/ec2/vpc
• docker run → docker/run
• Microsoft.Resources/resourceGroup → microsoft/resources/resourcegroup

Consecutive, leading, and trailing slashes are removed.

typeVersion

CalVer version of the model type at definition creation time.

Tracks which version of the model type schema this definition was created against. Used for detecting when model type upgrades are available.

id

Unique identifier for the definition.

name

Human-readable name for the definition.

Constraints:

• Minimum 1 character.
• Must be unique within the repository.
• Must not contain .., \, or null bytes (path traversal protection).
• / is only allowed in scoped names matching @[a-z0-9_-]+/[a-z0-9_-]+(\/[a-z0-9_-]+)* (e.g., @john/pod-inventory).

version

Definition version number.

Must be a positive integer. Incremented when the definition is modified. This tracks changes to the definition itself — it is separate from typeVersion, which tracks the model type schema.

tags

Key-value labels attached to the definition.

Tags flow to data produced by the definition and can be overridden at runtime with --tag key=value.

tags:
  env: production
  team: platform
  owner: alice

globalArguments

Shared arguments available to all methods.

Values can be any JSON-serializable type: string, number, boolean, object, array, or null. CEL expressions are supported using the ${{ }} syntax.

globalArguments:
  repo: systeminit/swamp
  retries: 3
  verbose: true
  computed: "${{ 'https://' + self.tags.domain }}"
  secret: "${{ vault.get('my-vault', 'api-key') }}"

Global arguments are validated against the model type's globalArguments schema (if one is defined) when the definition is validated.

A global argument whose schema marks it sensitive must not be given a literal value. A literal is rejected when the definition is written — across model create, model edit, model run / workflow run auto-definitions, and the serve HTTP API — because it would be stored in cleartext in the definition YAML. The value must instead be a vault.get('<vault>', '<key>') expression. The write fails with:

Global argument 'apiKey' is marked sensitive and cannot be set to a literal value — it would be stored in cleartext in the definition YAML. Store the secret in a vault and reference it with a vault.get expression, e.g. --global-arg "apiKey=${{ vault.get('my-vault', 'api-key') }}".

See the Vaults and CEL Expressions references for the expression syntax.

methods

Per-method argument overrides.

Each key is a method name. The value is a MethodData object:

methods:
  execute:
    arguments:
      run: "echo hello"
      timeout: 5000
      env:
        MY_VAR: value

MethodData

arguments values support CEL expressions. They are merged with the model type's method argument schema and validated at execution time.

inputs

JSON Schema definition for structured inputs that can be provided at runtime.

InputsSchema

Additional JSON Schema keywords are allowed and preserved.

JsonSchemaProperty

All fields are optional. Properties nest recursively for objects and arrays.

inputs:
  type: object
  properties:
    environment:
      type: string
      enum: [dev, staging, production]
    count:
      type: integer
      default: 1
    config:
      type: object
      properties:
        verbose:
          type: boolean
          default: false
      additionalProperties: true
  required:
    - environment

Input values are available in CEL expressions as inputs.*.

checks

Pre-flight check selection.

CheckSelection

require lists check names to include. skip lists check names to exclude. Checks run before mutating methods (create, update, delete, action). Check names must be defined by the model type.

checks:
  require:
    - validate-permissions
    - check-resources
  skip:
    - expensive-validation

reports

Post-execution report selection.

ReportSelection

A ReportRef is either a report name (string) or an object:

When methods is omitted, the report runs for all methods.

reports:
  require:
    - summary-report
    - name: detailed-analysis
      methods:
        - execute
  skip:
    - verbose-debug

A name in require that cannot be resolved to a loaded or installed report (missing extension pull, typo, broken bundle) logs a warning naming the report and the remedy, writes a searchable error artifact (visible via swamp report search), and counts as a report failure — swamp model method run exits non-zero. A name in skip that also appears in require is exempted from the resolution check — skip wins over require.

CEL Expressions

String values in globalArguments and methods.*.arguments support CEL expressions using the ${{ }} wrapper:

globalArguments:
  url: "${{ 'https://' + self.tags.domain }}"
  pool: "${{ model.config.definition.globalArguments.pool_size * 2 }}"
  secret: "${{ vault.get('infra', 'api-key') }}"

When the entire YAML value is a single ${{ }} expression, the result preserves its type. When mixed with surrounding text, the result is coerced to a string.

Context Variables

See the CEL Expressions reference for the full expression language.

Per-Model Method Locking

Concurrent swamp model method run invocations on the same model definition serialize automatically. The engine acquires a per-model file lock before executing the method and releases it when the method completes, fails, or is cancelled. Different model definitions run in parallel — only runs targeting the same definition contend.

The lock uses a ~30-second TTL with a heartbeat. The executing process renews the lock periodically; if the process dies without releasing the lock, stale-lock detection checks whether the owning PID is still alive and reclaims the lock once the TTL expires. This prevents a crashed process from permanently blocking a model.

When a second run cannot acquire the lock within the timeout window, the CLI exits with code 75 and a lock_timeout error (see Exit codes and Error codes). The caller can retry with exponential backoff.

Breakglass: inspecting and releasing locks

If a lock is stuck — the owning process is gone but the TTL has not yet expired, or the PID check cannot reach the original host — use the datastore lock commands:

swamp datastore lock status                          # show who holds the lock
swamp datastore lock release --force                 # release the global lock
swamp datastore lock release --force --model <type/name>  # release a specific model's lock

See Operational Commands for the full flag reference.

Execution Cancellation

A running model method can be cancelled via swamp model cancel. Cancellation terminates the method run cooperatively and marks it as cancelled — a terminal status alongside succeeded and failed.

Commands

Signal-based cancellation

Pressing Ctrl+C (SIGINT) or sending SIGTERM during swamp model method run cancels the running method. The CLI intercepts the signal, sends a cancel request, waits for the method to terminate cooperatively, and exits with a non-zero status.

Examples

$ swamp model cancel my-server
$ swamp model cancel --all
$ swamp model cancel my-server --reason 'No longer needed'

Validation

swamp model validate checks a definition against its model type schema:

$ swamp model validate greeter
Validating: greeter (command/shell)
  ✓ Definition schema
  ✓ Global arguments
  ✓ Method arguments
  ✓ Expression paths
  ✓ Check selection
Summary: 5/5 validations passed
Result: PASSED

Omit the name to validate all definitions in the repository.

Validation rules:

• id must be a valid UUID v4.
• name must be at least 1 character, unique within the repository, with no path traversal sequences.
• version must be a positive integer.
• tags values must be strings.
• globalArguments must match the model type's global argument schema (if defined).
• A sensitive global argument must be a vault.get(...) expression, not a literal value.
• methods.*.arguments must match the model type's method argument schema.
• typeVersion must be valid CalVer (YYYY.MM.DD.MICRO) or absent.
• CEL expression syntax in ${{ }} wrappers must parse correctly.
• Expression paths must reference existing models and valid schema paths.
• checks.require and checks.skip names must exist on the model type.

Complete Example

type: command/shell
typeVersion: 2026.02.09.1
id: 53274ce2-c390-412b-93ac-48b205a13f4e
name: greeter
version: 1
tags:
  env: dev
  team: platform
globalArguments:
  prefix: "swamp says"
methods:
  execute:
    arguments:
      run: "echo \"${{ self.globalArguments.prefix }}: hello!\""
inputs:
  type: object
  properties:
    name:
      type: string
      description: Name to greet
      default: world
  required:
    - name
checks:
  require:
    - validate-permissions
reports:
  require:
    - name: execution-summary
      methods:
        - execute

model type describe

swamp model type describe prints the schema of a model type — its methods, arguments, data output specifications, and version. It accepts a type identifier (e.g., command/shell, @swamp/issue-lifecycle) and renders a human-readable summary by default.

$ swamp model type describe command/shell
Type: command/shell
Version: 2026.02.09.1

Data Outputs:
  result [resource] - Shell command execution result (exit code, timing, command) (infinite)
  log [file] - Shell command output (stdout and stderr) (text/plain, infinite)

Methods:
  execute - Execute the shell command and capture stdout, stderr, and exit code
    Inputs:
      run (string) *required
      workingDir (string)
      timeout (integer)
      env (object)
      ignoreExitCode (boolean)

For the YAML definition layer that configures model instances, see Definition Storage above.

--json

Produces structured JSON output. The full JSON includes complete JSON Schema definitions for every method's arguments and every data output spec's schema.

$ swamp model type describe command/shell --json

{
  "type": {
    "raw": "command/shell",
    "normalized": "command/shell"
  },
  "version": "2026.02.09.1",
  "dataOutputSpecs": [
    {
      "specName": "result",
      "kind": "resource",
      "description": "Shell command execution result (exit code, timing, command)",
      "schema": { ... },
      "lifetime": "infinite",
      "garbageCollection": 10
    },
    {
      "specName": "log",
      "kind": "file",
      "description": "Shell command output (stdout and stderr)",
      "contentType": "text/plain",
      "lifetime": "infinite",
      "garbageCollection": 10,
      "streaming": true
    }
  ],
  "methods": [
    {
      "name": "execute",
      "description": "Execute the shell command and capture stdout, stderr, and exit code",
      "arguments": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "run": {
            "type": "string",
            "minLength": 1,
            "description": "The shell command to execute"
          },
          ...
        },
        "required": ["run"],
        "additionalProperties": false
      }
    }
  ]
}

Full JSON shape

Each dataOutputSpecs entry includes the complete JSON Schema for resource specs, or contentType and streaming fields for file specs.

Each methods entry includes the full JSON Schema for that method's arguments, including description, type constraints, and validation rules for every property.

--compact

Produces a minimal digest suited to agent discovery. Strips full JSON Schema definitions down to property names and types, and reduces data output specs to names only.

$ swamp model type describe command/shell --compact --json

{
  "type": {
    "raw": "command/shell",
    "normalized": "command/shell"
  },
  "version": "2026.02.09.1",
  "dataOutputSpecs": [
    "result",
    "log"
  ],
  "methods": [
    {
      "name": "execute",
      "description": "Execute the shell command and capture stdout, stderr, and exit code",
      "arguments": {
        "properties": {
          "run": { "type": "string" },
          "workingDir": { "type": "string" },
          "timeout": { "type": "integer" },
          "env": { "type": "object" },
          "ignoreExitCode": { "type": "boolean" }
        },
        "required": ["run"]
      }
    }
  ]
}

Compact JSON shape

The compact form omits JSON Schema metadata ($schema, description, minLength, additionalProperties, constraints) from method arguments, and replaces full data output spec objects with their specName strings.

model type search

swamp model type search searches for model types available in the repository's installed extensions.

swamp model type search [query]

$ swamp model type search shell

Returns matching model types with their version and description. Use --json for structured output.

CLI Commands

swamp model create

Create a new model definition.

swamp model create <type> <name>

Creates a definition file in models/{type}/{id}.yaml. See Definition Storage for the directory layout.

$ swamp model create command/shell greeter --global-arg prefix="swamp says"

swamp model get

Show details of a model definition.

swamp model get <model_id_or_name>

Use --json for structured output. Resolves definitions from both models/ and .swamp/auto-definitions/.

swamp model search

Search model definitions in the repository.

swamp model search [query]

Returns definitions stored in models/. Auto-definitions in .swamp/auto-definitions/ are excluded. Use --json for structured output.

swamp model edit

Open a model definition in $EDITOR.

swamp model edit [model_id_or_name]

When the name is omitted, Swamp presents a selector. The definition is validated after the editor exits.

swamp model delete

Delete a model definition and its related artifacts.

swamp model delete <model_id_or_name>

swamp model validate

Validate a definition against its model type schema.

swamp model validate [model_id_or_name]

When the name is omitted and --all is not set, Swamp presents a selector. See Validation above for the rules checked.

swamp model evaluate

Evaluate CEL expressions in a definition without executing any method.

swamp model evaluate [model_id_or_name]

Resolves all ${{ }} expressions in globalArguments and methods.*.arguments and prints the evaluated values.

swamp model cancel

Cancel a running method run.

swamp model cancel [model_id_or_name]

See Execution Cancellation for signal-based cancellation and examples.

Method Execution

swamp model method run

Execute a method on a model. This is the single most important command in Swamp.

swamp model method run <model_or_type> <method> [definition_name]

Exit codes

Error codes (JSON on stderr)

Example

$ swamp model method run greeter execute
Running method: execute
Model: greeter (command/shell)
...

$ swamp model method run @command/shell execute my-shell \
    --input 'run=echo hello' --tag env=dev

swamp model method describe

Describe a method with its arguments, types, and constraints.

swamp model method describe <model_id_or_name> <method>

Use --json for the full JSON Schema of the method's arguments.

swamp model method history get

Show details of a model method run.

swamp model method history get <output_id_or_model_name>

When a model name is given, shows the most recent run for that model.

swamp model method history search

Search method run history.

swamp model method history search [query]

Use --json for structured output.

swamp model method history logs

Show logs for a method run.

swamp model method history logs <output_id_or_model_name>

Output Management

swamp model output get

Show details of a model output.

swamp model output get <output_id_or_model_name>

When a model name is given, shows the most recent output for that model.

Example

$ swamp model output get greeter
$ swamp model output get greeter --json

swamp model output search

Search model outputs.

swamp model output search [query]

Use --json for structured output.

swamp model output logs

Show log artifact content for an output.

swamp model output logs <output_id>

swamp model output data

Show data artifact content for an output.

swamp model output data <output_id>