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.

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, driver, driverConfig. 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.

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

driver

Execution driver for running methods.

Specifies how methods execute. Built-in drivers include raw and docker. Custom drivers can be provided via extensions.

driverConfig

Configuration for the execution driver.

Available keys depend on the driver.

raw driver: No configuration keys.

docker driver:

driver: docker
driverConfig:
  image: "node:18"
  memory: "512m"
  network: "host"

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.

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).
• 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
driver: raw