{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://behavioralstate.io/v1/schemas/agents/commands.json",
  "title": "BSP Commands",
  "description": "Schema for the command ingestion and discovery capability (io.bsp.agents.commands).",
  "$defs": {
    "command": {
      "allOf": [
        { "$ref": "../cloudEvent.json#/$defs/cloudEvent" },
        { "required": ["dataschema"] }
      ],
      "description": "A command sent to an BSP-compliant service. CloudEvent 1.0 envelope — the type field must match a type in the command catalogue, and the data property is validated against the JSON Schema at the dataschema URI before the command is queued. dataschema is required for commands."
    },
    "commandCatalogueEntry": {
      "type": "object",
      "description": "An entry in the command catalogue — one available command type with its schema name, version, and dataschema URI.",
      "required": ["schema", "version", "dataschema"],
      "properties": {
        "schema": {
          "type": "string",
          "description": "Command schema name in kebab-case (e.g. propose-counter, submit-order). Used as the {schema} path segment in GET /commands/{schema}/{version}. Distinct from the CloudEvent 'type' field."
        },
        "version": {
          "type": "string",
          "description": "Schema version string (e.g. 1.0, 2.1). Used as the {version} path segment in GET /commands/{schema}/{version}. First-class field — callers do not need to parse the dataschema URI to determine the version."
        },
        "dataschema": {
          "type": "string",
          "format": "uri",
          "description": "Resolvable URI to the JSON Schema for this command's data payload. Canonical value for the dataschema field of a CloudEvent command. Kept for CloudEvent compatibility."
        },
        "description": {
          "type": "string",
          "description": "Human-readable description of what this command does."
        }
      },
      "additionalProperties": false
    },
    "commandCatalogue": {
      "type": "object",
      "description": "Response body for GET /commands. Lists all command types this service accepts, with their schema URIs. This is the discovery surface for callers (Process Managers, AI agents, UIs) to learn what they can send.",
      "required": ["commands"],
      "properties": {
        "commands": {
          "type": "array",
          "items": { "$ref": "#/$defs/commandCatalogueEntry" }
        }
      },
      "additionalProperties": false
    },
    "schemaEntry": {
      "type": "object",
      "description": "An entry describing one available command schema with its version. Returned in the command catalogue entry's dataschema URI path.",
      "required": ["schema", "version"],
      "properties": {
        "schema": {
          "type": "string",
          "description": "Schema name (e.g. ProposeCounter, SubmitOrder). Matches the command type name."
        },
        "version": {
          "type": "string",
          "description": "Schema version string (e.g. 1.0, 2.1). Used as the second path segment in GET /commands/{schema}/{version}."
        },
        "description": {
          "type": "string",
          "description": "Human-readable description of what this schema validates."
        }
      },
      "additionalProperties": false
    }
  }
}