Asserts & tests

Asserts validate data. Add an assert: block with a list of tests to an action (to gate it) or to an interface (to check the final result). Each test resolves a value — with value (a JSON path), jq, pointer, or an action reference — then checks it with one or more conditions.

actions:
  - name: CheckBody
    input: a|body|
    assert:
      http_code_on_error: 400
      tests:
        - value: email
          is_not_null: true
          is_not_empty: true
        - value: age
          is_greater_than_or_equal_to: 18

The condition vocabulary is large — equality and ordering, string/pattern (contains, like, regex, …), type and emptiness, and specialized validators (is_valid_jwt, is_valid_hmac, verify_bcrypt, verify_signature, verify_schema, semver_matches, …). The filter transform reuses the same Test vocabulary. Every field of Assert and Test follows.

Assert

Assertion block for validating action output or interface results. Groups one or more tests with shared error handling and HTTP response codes.

Example - Action-level assertion

actions:
  - name: ValidateBody
    input: a|body|
    assert:
      tests:
        - value: email
          is_not_empty: true
          regex: "^[^@]+@[^@]+\\.[^@]+$"
        - value: age
          is_greater_than: 0
      error_message: "Validation failed"
      http_code_on_error: 400

Example - Interface-level assertion

interfaces:
  getUser:
    method: GET
    actions:
      - name: FetchUser
        database: main
        query: SELECT * FROM users WHERE id = $1
        params:
          - a|params::id|
    assert:
      tests:
        - value: count()
          is_equal_to: 1
      error_message: "User not found"
      http_code_on_error: 404
      http_code_on_success: 200

Field	Type	Description
`success_message`	string (nullable)	Message returned on successful assertion.
`error_message`	string (nullable)	Message returned when any test fails. Overrides individual test error messages at the assert level.
`http_code_on_error`	number (nullable)	HTTP status code to return when any test fails. Individual test-level `http_code_on_error` takes precedence when set.
`http_code_on_success`	number (nullable)	HTTP status code to return when all tests pass.
`tests`	Array<Test> (nullable)	List of test definitions to evaluate. All tests run concurrently; errors from all tests are collected and returned together.

Test

Test definition for asserting conditions against a resolved value. Tests support value resolution (via value, jq, pointer, or action), type-aware comparisons, pattern matching, and structural schema validation.

When used inside an assert block, multiple tests run concurrently. When used inside verify_schema via FieldType.validate, the test runs against the leaf value at that schema path.

Example - Basic value checks

tests:
  - value: email
    is_not_empty: true
    regex: "^[^@]+@[^@]+\\.[^@]+$"
    error_message: "Invalid email"
    http_code_on_error: 422

Example - Numeric comparisons

tests:
  - value: age
    is_greater_than: 0
    is_less_than: 150
  - value: count()
    is_greater_than_or_equal_to: 1

Example - Using jq for nested access

tests:
  - jq: ".data.users | length"
    is_greater_than: 0

Example - Cross-action reference

tests:
  - action: FetchUser
    value: email
    is_not_null: true

Example - Allowed/disallowed values

tests:
  - value: status
    contains:
      allowed:
        - "active"
        - "pending"
        - "suspended"
      disallowed:
        - "deleted"

Example - Schema validation with deep nested assertions

tests:
  - verify_schema:
      disallow_unknown_keys: true
      structure:
        email:
          type: String
          validate:
            is_not_empty: true
            regex: "^[^@]+@[^@]+\\.[^@]+$"
        age:
          type: Number
          validate:
            is_greater_than: 0
        settings:
          theme:
            type: String
          notifications:
            type: Boolean

Field	Type	Description
`name`	string (nullable)	Human-readable name for identifying this test in logs and error output.
`description`	string (nullable)	Description of what this test validates.
`value`	string (nullable)	JSON path to the target value within the input data (e.g., `email`, `user.name`). Also supports `count()` to get the length of an array.
`action`	string (nullable)	Reference a previous action's output as the target value.
`action_value`	string (nullable)	Reference a previous action's output using interpolation syntax.
`custom_value`	string (nullable)	Override the target value with a custom literal string.
`jq`	string (nullable)	Extract the target value using a jq filter expression.
`pointer`	string (nullable)	Extract the target value using a JSON pointer (RFC 6901).
`http_code_on_error`	number (nullable)	HTTP status code to return when this specific test fails. Takes precedence over the parent `Assert.http_code_on_error`.
`success_message`	string (nullable)	Message returned when this test succeeds.
`error_message`	string (nullable)	Custom error message when this test fails. Replaces the default auto-generated error detail.
`hide_errors`	boolean (nullable)	Suppress error details from the response output for this test.
`http_response`	any	Static HTTP response value to return when this test is evaluated.
`case_insensitive`	boolean (nullable)	Enable case-insensitive matching for `is_equal_to` and `contains` checks.
`is_equal_to`	any	Assert the value equals the expected value. Behavior varies by type: strings compare as text, numbers as numeric value, booleans as bool, arrays and objects compare as full…
`is_not_equal_to`	any	Assert the value does not equal the expected value.
`is_less_than`	any	Assert the value is less than the threshold. For strings and arrays, compares the length. For numbers, compares the numeric value.
`is_less_than_or_equal_to`	any	Assert the value is less than or equal to the threshold. Same type-dependent behavior as `is_less_than`.
`is_greater_than`	any	Assert the value is greater than the threshold. Same type-dependent behavior as `is_less_than`.
`is_greater_than_or_equal_to`	any	Assert the value is greater than or equal to the threshold. Same type-dependent behavior as `is_less_than`.
`starts_with`	any	Assert the string value starts with the given prefix.
`not_starts_with`	any
`ends_with`	any	Assert the string value ends with the given suffix.
`not_ends_with`	any
`contains_text`	boolean (nullable)	Assert the string contains at least one alphabetic character.
`contains_number`	boolean (nullable)	Assert the string contains at least one numeric digit.
`contains_upper`	boolean (nullable)	Assert the string contains at least one uppercase letter.
`contains_lower`	boolean (nullable)	Assert the string contains at least one lowercase letter.
`contains_special`	boolean (nullable)	Assert the string contains at least one special character.
`contains`	ContainOptions (nullable)	Assert containment. Behavior varies by target type: - String: substring match (or exact match in advanced/any mode) - Number: substring match against the string…
`like`	string (nullable)	SQL LIKE-style pattern matching (case-sensitive). Uses `%` as wildcard.
`ilike`	string (nullable)	SQL ILIKE-style pattern matching (case-insensitive). Uses `%` as wildcard.
`not_contains`	ContainOptions (nullable)	Inverse of `contains`. Assert the value does NOT contain the specified content. Same mode support as `contains` (standard, advanced, any).
`regex`	string (nullable)	Assert the string value matches a regular expression pattern.
`is_not_null`	boolean (nullable)	Assert the value is not null.
`is_not_empty`	boolean (nullable)	Assert the value is not empty. Checks strings, arrays, and objects.
`is_null`	boolean (nullable)	Assert the value is null (when `true`) or is not null (when `false`).
`is_uuid`	boolean (nullable)	Assert the value is a valid UUID string.
`is_array`	boolean (nullable)	Assert the value is a JSON array.
`is_valid_jwt`	JwtConfig (nullable)	Validate the value as a JWT token using the provided secret. On success, decoded claims are stored in `ok_data` under the key specified by `result_key` (default: `jwt_claims`).
`is_valid_hmac`	IsValidHmacConfig (nullable)	Verify an HMAC signature. The `value` field should point to the signature received in the request (e.g. `x-hub-signature-256`). The assertion recomputes HMAC over `body` using…
`is_authorization`	boolean (nullable)	Parse an HTTP Authorization header value. Supports `Basic` (decodes base64 username:password) and `Bearer` (extracts token). Decoded data is stored in `ok_data` keyed by scheme…
`result_key`	string (nullable)	Key name for storing extracted data (e.g., JWT claims) in the action's ok_data output.
`expression`	string (nullable)	Evaluate a string expression as a boolean condition. Supports interpolation via `a\|...\|` syntax before evaluation.
`compare_value`	CompareValue (nullable)	Compare the target value against another value or file for structural differences. Supports JSON, XML, and string comparison with optional field exclusions.
`bcrypt_verify`	string (nullable)	Verify a plaintext value against a bcrypt hash. Deprecated: use `verify_bcrypt`.
`verify_bcrypt`	string (nullable)	Verify a plaintext value against a bcrypt hash.
`verify_signature`	VerifySignature (nullable)	Verify an Ed25519 signature against the target value.
`verify_schema`	VerifySchema (nullable)	Validate the value against a structural schema with recursive type checking and optional per-field assertions. Supports nested objects, arrays, and leaf-level validation via…
`semver_matches`	string (nullable)	Assert the string value satisfies a semver version constraint.
`size_limit`	string (nullable)	Assert the serialized byte size of the value does not exceed a limit. Accepts human-readable sizes (e.g., `1 MB`, `500 KB`) or raw byte counts.

ContainOptions

Containment check options. Supports three modes depending on the YAML structure provided: standard (single value or array), advanced (with at_least threshold), and any (with allowed/disallowed lists).

Example - Standard single value

contains: "search_term"

Example - Standard array (match at least one)

contains:
  - "admin"
  - "editor"

Example - Advanced (at least N matches)

contains:
  values:
    - "read"
    - "write"
    - "delete"
  at_least: 2

Example - Allowed/disallowed lists

contains:
  allowed:
    - "active"
    - "pending"
  disallowed:
    - "banned"

One of:

ContainsAny — Allowed/disallowed list mode. Target must match an allowed value and must not match any disallowed value.
ContainsAdv — Advanced mode with explicit value list and minimum match threshold.
any — Standard mode: a single value or array of values to check for containment.

ContainsAny

Allowed/disallowed containment check. For strings, checks exact match against each list. For arrays, checks that all elements are in allowed and no elements are in disallowed.

Example

contains:
  allowed:
    - "published"
    - "draft"
    - "archived"
  disallowed:
    - "deleted"
    - "banned"

Field	Type	Description
`allowed`	Array<any> (nullable)	Values the target is allowed to match.
`disallowed`	Array<any> (nullable)	Values the target must not match.

ContainsAdv

Advanced containment check with a minimum match threshold.

Example

contains:
  values:
    - "read"
    - "write"
    - "admin"
  at_least: 2             # target must match at least 2 of the listed values

Field	Type	Description
`values`	Array<any>	Required. List of candidate values to check against.
`at_least`	number	Required. Minimum number of values that must match for the check to pass.

JwtConfig

Configuration for the is_valid_jwt assertion.

Accepts either a bare string (the HS256 shared secret — the original form, still supported) or an object for asymmetric algorithms and OIDC providers:

**HS256 (unchanged):**
is_valid_jwt: "my-shared-secret"

**RS256/ES256 with a static PEM public key:**
is_valid_jwt:
  alg: RS256
  public_key: a|ap_var::IDP_PUBLIC_KEY|

**RS256/ES256 verified against a provider's rotating JWKS (Auth0/Clerk/Cognito):**
is_valid_jwt:
  jwks_url: https://YOUR.auth0.com/.well-known/jwks.json
  alg: RS256          # optional; falls back to the token header's alg
  iss: https://YOUR.auth0.com/
  aud: https://your-api

One of:

string — Bare HS256 shared secret (back-compatible form).
JwtVerifyConfig — Structured verification config for HS*/RS*/ES*/EdDSA and JWKS.

JwtVerifyConfig

Structured form of [JwtConfig] — a symmetric secret, a static public key, or a JWKS URL, plus optional algorithm and issuer/audience checks.

Field	Type	Description
`secret`	string (nullable)	HS256/384/512 shared secret. Mutually exclusive with `public_key`/`jwks_url`.
`public_key`	string (nullable)	PEM-encoded public key for RS/ES/EdDSA verification (no network calls).
`jwks_url`	string (nullable)	URL of a JWKS document; the signing key is selected by the token's `kid`. Fetched once and cached (with a short TTL), so provider key rotation is handled.
`alg`	string (nullable)	Signature algorithm, e.g. `HS256`, `RS256`, `ES256`, `EdDSA`. Required for `public_key`; for `jwks_url` it defaults to the token header's `alg`.
`iss`	string (nullable)	Expected `iss` claim. When set, tokens with a different issuer are rejected.
`aud`	string (nullable)	Expected `aud` claim. When set, tokens with a different audience are rejected.

IsValidHmacConfig

Configuration for the is_valid_hmac assertion.

Field	Type	Description
`secret`	string	Required. HMAC secret key. Supports interpolation: `a\|env::MY_SECRET\|`
`body`	string	Required. The message to authenticate. Use `a\|raw_body\|` for webhook signature verification so the bytes match exactly what the sender signed.
`algorithm`	string (nullable)	Hash algorithm: `sha1`, `sha256` (default), or `sha512`.
`prefix`	string (nullable)	Optional prefix to strip from the target value before comparing. GitHub uses `"sha256="`, Stripe uses `"v1="`.

CompareValue

Value comparison configuration for diffing against an expected value. Supports inline target strings or file paths, with optional field exclusions.

Example - Inline comparison

compare_value:
  target: '{"status": "ok", "code": 200}'
  data_type: json
  ignore_fields:
    - timestamp
    - request_id

Example - File comparison

compare_value:
  file_path: "./fixtures/expected_response.json"
  data_type: json

One of:

target → string
file_path → string

CompareDataType

Type: string — one of: json, xml, string

VerifySignature

Ed25519 signature verification parameters.

Example

value: request_body
verify_signature:
  public_key: "a1b2c3d4e5f6..."     # hex-encoded Ed25519 public key
  signature: "f6e5d4c3b2a1..."       # hex-encoded signature bytes

Field	Type	Description
`public_key`	string	Required. Hex-encoded Ed25519 public key.
`signature`	string	Required. Hex-encoded signature bytes to verify against the target value.

VerifySchema

Schema validation configuration. Validates a JSON value against a recursive type structure with optional per-field assertions and unknown key rejection.

Example - Basic object validation

verify_schema:
  disallow_unknown_keys: true
  structure:
    name:
      type: String
      validate:
        is_not_empty: true
    email:
      type: String
      validate:
        regex: "^[^@]+@[^@]+\\.[^@]+$"
    age:
      type: Number
      validate:
        is_greater_than: 0
        is_less_than: 150

Example - Nested with unknown key rejection

verify_schema:
  disallow_unknown_keys: true
  structure:
    user:
      name:
        type: String
      role:
        type: String
        validate:
          contains:
            allowed:
              - "admin"
              - "editor"
              - "viewer"
    metadata:
      created_at:
        type: Number
      version:
        type: String
        validate:
          semver_matches: ">=1.0.0"

Example - Array of objects (positional)

verify_schema:
  structure:
    - id:
        type: Number
        validate:
          is_greater_than: 0
      status:
        type: String
        validate:
          is_not_empty: true
      settings:
        category:
          type: String
        featured:
          type: Boolean

Field	Type	Description
`disallow_unknown_keys`	boolean (nullable)	When `true`, any keys present in the value but not defined in the schema are reported as errors. Applies recursively to all nested objects.
`structure`	ValueType	Required. The expected structure definition. Can be a nested object map, a positional array, or a single leaf field type.

ValueType

Schema value type for recursive structural validation. Represents either a leaf field with a type constraint, a nested object with named fields, or a positional array of typed elements.

Example - Leaf field

email:
  type: String
  validate:
    is_not_empty: true

Example - Nested object

user:
  name:
    type: String
  settings:
    theme:
      type: String

Example - Positional array

structure:
  - name:
      type: String
    id:
      type: Number

One of:

FieldType — Leaf field with type constraint and optional validation.
Map<string, ValueType> — Nested object where each key maps to another ValueType.
Array<ValueType> — Positional array where each index maps to a ValueType.

FieldType

Leaf field definition within a verify_schema structure. Specifies the expected data type and optional validation assertions that run against the resolved value at this path.

Supported types: String, Number, Boolean, Array, Object, Null, Any.

Example - Type check only

email:
  type: String

Example - Type check with assertions

rating:
  type: Number
  validate:
    is_greater_than_or_equal_to: 0
    is_less_than_or_equal_to: 5

Example - String with pattern and length

slug:
  type: String
  validate:
    is_not_empty: true
    regex: "^[a-z0-9]+(-[a-z0-9]+)*$"
    is_less_than: 128

Example - Enum-like string constraint

status:
  type: String
  validate:
    contains:
      allowed:
        - "published"
        - "draft"
        - "archived"

Field	Type	Description
`type`	string	Required. Expected data type. One of: `String`, `Number`, `Boolean`, `Array`, `Object`, `Null`, `Any`.
`validate`	Test (nullable)	Optional test assertions to run against the leaf value after the type check passes. Uses the same `Test` definition as the normal assertion system, giving full access to all…

Asserts & tests

Assert​

Test​

ContainOptions​

ContainsAny​

ContainsAdv​

JwtConfig​

JwtVerifyConfig​

IsValidHmacConfig​

CompareValue​

CompareDataType​

VerifySignature​

VerifySchema​

ValueType​

FieldType​

Assert

Test

ContainOptions

ContainsAny

ContainsAdv

JwtConfig

JwtVerifyConfig

IsValidHmacConfig

CompareValue

CompareDataType

VerifySignature

VerifySchema

ValueType

FieldType