{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://synacl.com/protocol/v1/schemas/gateway-cmd-ack.json",
  "title": "Gateway command acknowledgement",
  "description": "The reply to a GATEWAY command (see gateway-cmd) that carried a `correlationId` — `identify`, `bus/tap/start`, `bus/scan`, `bus/capture` and any future command that names one — published on `<prefix>/cmd/ack`. It is the gateway-level sibling of the per-device `devices/{deviceId}/cmd/ack` (cmd-ack): same idea, no device. Publish exactly one ack per such command, as soon as the command is accepted or refused and BEFORE the work it starts (a tap, a scan) produces its own stream, so the app can show 'running' at once and the refusal reason otherwise. Commands without a correlationId (`bus/tap/stop`, `bus/scan/stop`, `restart`, …) get no ack. Relayed live to the gateway's debug room as `gw:cmd:ack`; never stored. Keep `error` short and stable (`PIN_IN_USE`, `BUS_BUSY`, `NOT_SUPPORTED`): the app shows it verbatim and may key behaviour off it.",
  "type": "object",
  "required": [
    "correlationId",
    "command",
    "status"
  ],
  "properties": {
    "correlationId": {
      "description": "Copied from the command being acknowledged.",
      "type": "string",
      "maxLength": 64
    },
    "command": {
      "description": "The `command` string of the command being acknowledged, e.g. `identify` or `bus/tap/start`, so a reader that lost track of the correlationId still knows what was answered.",
      "type": "string",
      "maxLength": 64
    },
    "status": {
      "description": "`ok` = accepted and, where applicable, started. `error` = refused or failed to start; `error` says why.",
      "type": "string",
      "enum": [
        "ok",
        "error"
      ]
    },
    "error": {
      "description": "Why the command was refused, or null on success. Prefer short upper-snake-case codes: `PIN_IN_USE` (identify cannot drive the LED because a configured device claims GPIO2), `BUS_BUSY` (a scan or capture already holds the bus), `NOT_SUPPORTED` (this build cannot do it).",
      "type": [
        "string",
        "null"
      ],
      "maxLength": 512
    },
    "ts": {
      "description": "Epoch milliseconds (gateway clock).",
      "type": "integer",
      "minimum": 0
    }
  },
  "additionalProperties": false
}
