Skip to main content

MODEL DEFINITIONS

A model definition is a YAML file that configures an instance of a model type. Definitions live in models/{model-type}/{definition-id}.yaml within a swamp repository.

File Structure

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.

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.

Property Value
Type string
Required No
Default Inferred from directory path

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.

Property Value
Type string
Required No
Default Set to the model type's current version on create
Format YYYY.MM.DD.MICRO (e.g., 2026.02.09.1)

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.

Property Value
Type string (UUID v4)
Required Yes
Default Auto-generated on create
Format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

name

Human-readable name for the definition.

Property Value
Type string
Required Yes
Default None

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.

Property Value
Type integer
Required No
Default 1

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.

Property Value
Type Record<string, string>
Required No
Default {}

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.

Property Value
Type Record<string, unknown>
Required No
Default {}

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.

Property Value
Type Record<string, MethodData>
Required No
Default {}

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

Field Type Required Default
arguments Record<string, unknown> No {}

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.

Property Value
Type InputsSchema
Required No
Default None

InputsSchema

Field Type Required
type "object" No
properties Record<string, JsonSchemaProperty> No
required string[] No
additionalProperties boolean or JsonSchemaProperty No

Additional JSON Schema keywords are allowed and preserved.

JsonSchemaProperty

Field Type Description
type "string", "number", "integer", "boolean", "array", "object" Value type
description string Human-readable description
default any Default value
enum unknown[] Allowed values
items JsonSchemaProperty Schema for array items
properties Record<string, JsonSchemaProperty> Nested object properties
required string[] Required nested properties
additionalProperties boolean or JsonSchemaProperty Extra property handling

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.

Property Value
Type CheckSelection
Required No
Default None

CheckSelection

Field Type Required Default
require string[] No []
skip string[] No []

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.

Property Value
Type ReportSelection
Required No
Default None

ReportSelection

Field Type Required Default
require ReportRef[] No []
skip string[] No []

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

Field Type Required Description
name string Yes Report name
methods string[] No Restrict to specific methods

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.

Property Value
Type string
Required No
Default raw (in-process execution)

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

driverConfig

Configuration for the execution driver.

Property Value
Type Record<string, unknown>
Required No
Default None

Available keys depend on the driver.

raw driver: No configuration keys.

docker driver:

Key Type Required Description
image string Yes Docker image to run
bundleImage string No Image for bundle mode (default: same as image)
command string No CLI binary — docker, podman, or nerdctl (default: docker)
timeout number No Timeout in milliseconds
network string No Docker network to attach
memory string No Memory limit (e.g., 512m)
cpus string No CPU limit (e.g., 1.5)
volumes string[] No Volume mounts (e.g., ["/host:/container"])
env Record<string, string> No Environment variables passed to the container
extraArgs string[] No Additional flags appended before the image 
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

Variable Description
self The current definition: self.name, self.version, self.tags.*, self.globalArguments.*
model Other definitions: model.<name>.definition.globalArguments.*, model.<name>.resource.<spec>.<instance>.attributes.*
inputs Runtime input values: inputs.<property>
env Process environment variables: env.<VAR_NAME>
vault Secrets: vault.get('<vault>', '<key>')
data Versioned data access: data.latest(...), data.version(...), data.findByTag(...)
file File contents: file.contents('<model>', '<spec>')

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
← PreviousCEL ExpressionsNext →OpenTelemetry