Contract Schema Reference (v1)

This document defines the Stoney YAML contract schema.

A contract file declares executable system invariants enforced in CI.

Note: fail_fast is an execution control (GitHub Action / CLI), not part of the YAML schema.

Top-Level Structure

version: 1
feature: core
description: "Smoke checks for the environment"
 
contracts:
  - name: example
    description: "Example contract group"
    checks:
      - id: example_check
        work_item: "KAN-123" # optional unless require_work_item is enabled
        says: "Human explanation of what must never drift"
        links:
          - "https://example.com/spec"
        steps:
          - http:
              method: GET
              path: /health
            expect:
              status: 200
              json:
                ok: true

Fields

version (required)

Schema version.

version: 1

feature (required)

Logical grouping name used in reporting and PR summaries.

feature: core

description (optional)

Human summary of what this file covers.

description: "Core invariants for staging"

contracts (required)

List of contract groups. Each contract contains:

• name (required)
• description (optional)
• checks (required)

contracts[].name (required)

Logical grouping for related checks.

contracts:
  - name: authentication

contracts[].description (optional)

Description of the contract group.

contracts:
  - name: authentication
    description: "Auth invariants"

contracts[].checks (required)

List of executable invariant checks.

Each check contains:

• id (required)
• steps (required, non-empty)
• traceability (work_item, says, links) (all optional)

checks[].id (required)

Unique identifier within the contract group.

checks:
  - id: login_success

checks[].work_item (optional)

Reference string that links the check back to a work item in your system (Jira/Linear/GitHub/etc).

Stoney v1 does not validate this against external systems. Enforcement is a CI policy:

• require_work_item=true (fail if missing)
• optional work_item_pattern (regex)

work_item: "KAN-42"

checks[].says (optional)

Human-readable statement of the invariant.

says: "Login must succeed with valid credentials"

checks[].links (optional)

Supporting URLs (specs, runbooks, dashboards, etc).

links:
  - "https://example.com/spec"

Step Model

A check contains one or more steps.

Supported step types:

• http
• exec
• sql

Steps run sequentially. If any step fails, the check fails.

Each step may include an expect block of assertions.

HTTP Step

- http:
    method: GET
    path: /health
    headers:
      Authorization: "Bearer ${STONEY_TOKEN}"
    query:
      verbose: true
    body:
      key: value
    timeout_ms: 15000
    retries: 2
  expect:
    status: 200
    json:
      ok: true
    bodyContains: "ok"

HTTP Options

• method (required)
• path (required; must start with /)
• headers (optional)
• query (optional)
• body (optional)
• timeout_ms (optional per-step override)
• retries (optional per-step override)

HTTP Expect Options

• status (number)
• json (deep subset match)
• bodyContains (string)

Exec Step

- exec:
    run: "node -v"
    cwd: "./"
    env:
      NODE_ENV: test
    timeout_ms: 15000
    retries: 0
    max_output_chars: 8192
  expect:
    exit_code: 0
    stdout_contains: "v"
    stderr_empty: true

Exec Options

• run (required)
• cwd (optional)
• env (optional)
• timeout_ms (optional)
• retries (optional)
• max_output_chars (optional)

Exec Expect Options

• exit_code
• stdout_contains
• stderr_contains
• stdout_regex
• stderr_regex
• stdout_not_contains
• stderr_not_contains
• stdout_empty
• stderr_empty
• max_duration_ms

SQL Step (Postgres)

- sql:
    driver: postgres
    url_env: STONEY_DB_URL
    query: "SELECT 1 AS ok;"
    timeout_ms: 15000
  expect:
    rows: 1
    equals:
      ok: 1

SQL Options

• driver (required; currently postgres)
• url_env (required; env var that contains the connection string)
• query (required; single statement)
• timeout_ms (optional)

SQL Expect Options

• rows (exact row count)
• equals (deep subset match against the first row)

Execution Model

• Checks execute in file order.
• Steps execute sequentially within each check.
• A failing step marks the check as failed.
• Any failed check fails the run.
• If fail_fast=true is enabled in CI, execution stops after the first failing check.

Reporting Fields

Each check produces:

• ok
• notes
• steps (per-step results)
• optional work_item metadata (if provided)

Design Philosophy

Contracts define invariants.

They are not full test suites.

They represent guarantees that must never drift.