Context block schemas

Pass bounded code, diffs, logs, metrics, links, JSON, and key-value evidence with an Action.

The top-level context array carries evidence that helps a reviewer check an Action. It is separate from decision_context: the Decision Brief explains the decision, while context blocks contain the supporting material.

An Action accepts up to 12 blocks. Each block has a required type and an optional title of up to 120 characters. The complete context array has a schema ceiling of 128 KB. Plan limits are Developer 16 KB, Pro and Founder 64 KB, and Team 128 KB.

Supported block types

`type`	Required fields	Optional fields	Limits
`key_value`	`items` object	`title`	1 to 50 entries. Values must be a string, number, boolean, or `null`.
`code`	`content`	`title`, `language`	`content` is 1 to 20,000 characters; `language` is up to 40 characters.
`diff`	`content`	`title`, `language`	Same limits as `code`.
`logs`	`content`	`title`, `language`	Same limits as `code`.
`command`	`content`	`title`, `language`	Same limits as `code`.
`json`	`value`	`title`	`value` may be any valid JSON value, subject to the total context limit.
`metrics`	`items` array	`title`	1 to 20 metric items.
`links`	`items` array	`title`	1 to 20 link items.

Key-value evidence

{
  "type": "key_value",
  "title": "Release",
  "items": {
    "version": "2.18.0",
    "replicas": 6,
    "canary_passed": true
  }
}

Code, diffs, logs, and commands

These four types use the same shape. Choose the type that describes the content so clients can render a useful label and treatment.

{
  "type": "diff",
  "title": "Write-path change",
  "language": "diff",
  "content": "- schema = cached_schema\n+ schema = fetch_live_schema()"
}

JSON

{
  "type": "json",
  "title": "Deployment plan",
  "value": {
    "strategy": "canary",
    "percent": 10
  }
}

Metrics

Each metric item requires a label from 1 to 120 characters and a string or numeric value. The optional unit is limited to 40 characters.

{
  "type": "metrics",
  "title": "Staging checks",
  "items": [
    { "label": "Passed", "value": 482, "unit": "checks" },
    { "label": "Error rate", "value": 0.02, "unit": "%" }
  ]
}

Links

Each link requires a label from 1 to 120 characters and an HTTP or HTTPS url of up to 2,048 characters. ActionBox validates links before storing the Action.

{
  "type": "links",
  "title": "Runbooks",
  "items": [
    {
      "label": "Rollback procedure",
      "url": "https://docs.example.com/runbooks/rollback"
    }
  ]
}

Context is customer-provided content

Do not include passwords, API keys, signing secrets, private credentials, or unrestricted customer records. Keep excerpts small and link to the system of record when reviewers need a larger artifact.

Complete Action example

{
  "title": "Deploy release 2.18.0?",
  "options": [
    { "id": "approve", "label": "Approve" },
    { "id": "hold", "label": "Hold" }
  ],
  "context": [
    {
      "type": "key_value",
      "title": "Release",
      "items": { "version": "2.18.0", "replicas": 6 }
    },
    {
      "type": "links",
      "title": "Evidence",
      "items": [
        { "label": "Deployment run", "url": "https://ci.example.com/runs/4821" }
      ]
    }
  ]
}

Context contributes to the Action fingerprint. Updating it advances action_version and changes the fingerprint, so a response against an older snapshot fails with ACTION_CHANGED.

Next: Decision context, Creating Actions, or the live OpenAPI document.