{
  "asyncapi": "3.1.0",
  "id": "urn:waraps.api-declarations",
  "info": {
    "title": "WARA-PS Declarations MQTT API",
    "version": "1.0.3",
    "description": "### Overview\nDeclarative channels for WARA-PS agent communication. These messages announce an agent's existence and capabilities to the system.\n\n### Channels\n- **Heartbeat** — Mandatory for all agents. Periodic signal indicating the agent is alive, including identity, type, model, and capability levels.\n- **Sensor Info** — Mandatory for Level 1 agents (sensor agents). Declares which sensor data the agent provides.\n- **Direct Execution Info** — Mandatory for Level 2+ agents (task agents). Declares available tasks, supported signals, and currently executing tasks.",
    "contact": {
      "name": "waraps.org",
      "url": "https://portal.waraps.org/",
      "email": "info@waraps.org"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "defaultContentType": "application/json",
  "servers": {
    "localhost": {
      "host": "localhost:1883",
      "protocol": "mqtt",
      "protocolVersion": "3.1.1+",
      "description": "Development MQTT broker",
      "variables": {
        "port": {
          "enum": [
            "1882",
            "1883"
          ],
          "default": "1883",
          "description": "The port used for connecting to the locally hosted MQTT broker"
        }
      },
      "security": []
    },
    "production": {
      "host": "broker.waraps.org:8883",
      "protocol": "mqtt",
      "protocolVersion": "3.1.1+",
      "description": "Production MQTT broker",
      "variables": {
        "port": {
          "enum": [
            "8883"
          ],
          "default": "8883",
          "description": "The port used for connecting to the production MQTT broker"
        }
      },
      "security": [
        {
          "$ref": "#/components/securitySchemes/tls"
        }
      ]
    }
  },
  "channels": {
    "heartbeatChannel": {
      "address": "{AgentBaseTopic}/heartbeat",
      "bindings": {
        "$ref": "#/components/channelBindings/DeclarationMqttSettings"
      },
      "messages": {
        "sendHeartbeatDeclaration.message": {
          "$ref": "#/components/messages/HeartbeatMessage"
        }
      },
      "description": "Sends heartbeat declaration. Mandatory for all agent types.",
      "parameters": {
        "AgentBaseTopic": {
          "$ref": "#/components/parameters/AgentBaseTopic"
        }
      }
    },
    "sensorInfoChannel": {
      "address": "{AgentBaseTopic}/sensor_info",
      "bindings": {
        "$ref": "#/components/channelBindings/DeclarationMqttSettings"
      },
      "messages": {
        "sendSensorInfoDeclaration.message": {
          "$ref": "#/components/messages/SensorInfoMessage"
        }
      },
      "description": "Sends sensor info declaration. Mandatory for agents with sensors.",
      "parameters": {
        "AgentBaseTopic": {
          "$ref": "#/components/parameters/AgentBaseTopic"
        }
      }
    },
    "directExecutionInfoChannel": {
      "address": "{AgentBaseTopic}/direct_execution_info",
      "bindings": {
        "$ref": "#/components/channelBindings/DeclarationMqttSettings"
      },
      "messages": {
        "sendDirectExecutionInfoDeclaration.message": {
          "$ref": "#/components/messages/DirectExecutionInfoMessage"
        }
      },
      "description": "Sends direct execution info declaration. Mandatory for agents that can receive and execute commands.",
      "parameters": {
        "AgentBaseTopic": {
          "$ref": "#/components/parameters/AgentBaseTopic"
        }
      }
    }
  },
  "operations": {
    "sendHeartbeatDeclaration": {
      "action": "send",
      "channel": {
        "$ref": "#/channels/heartbeatChannel"
      },
      "summary": "Sends a heartbeat message",
      "messages": [
        {
          "$ref": "#/channels/heartbeatChannel/messages/sendHeartbeatDeclaration.message"
        }
      ]
    },
    "sendSensorInfoDeclaration": {
      "action": "send",
      "channel": {
        "$ref": "#/channels/sensorInfoChannel"
      },
      "summary": "Sends sensor information",
      "messages": [
        {
          "$ref": "#/channels/sensorInfoChannel/messages/sendSensorInfoDeclaration.message"
        }
      ]
    },
    "sendDirectExecutionInfoDeclaration": {
      "action": "send",
      "channel": {
        "$ref": "#/channels/directExecutionInfoChannel"
      },
      "summary": "Sends direct execution information",
      "messages": [
        {
          "$ref": "#/channels/directExecutionInfoChannel/messages/sendDirectExecutionInfoDeclaration.message"
        }
      ]
    }
  },
  "components": {
    "channelBindings": {
      "DeclarationMqttSettings": {
        "mqtt": {
          "qos": 0,
          "retain": false
        }
      }
    },
    "securitySchemes": {
      "tls": {
        "type": "X509",
        "x-securityScheme": "tls",
        "description": "TLS client certificate for secure connection"
      },
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "user",
        "description": "An API key is required for connecting to the MQTT broker"
      }
    },
    "parameters": {
      "AgentBaseTopic": {
        "description": "Full agent topic path: {organization}/{category}/{domain}/{real_sim}/{agent_name}. See AgentBaseTopic schema for structure.",
        "location": "$message.payload#/name"
      },
      "Organization": {
        "enum": [
          "waraps",
          "saab",
          "liu"
        ],
        "description": "The organization/owner of the agent."
      },
      "Category": {
        "enum": [
          "unit",
          "service",
          "general"
        ],
        "description": "The category of the agent."
      },
      "Domain": {
        "enum": [
          "air",
          "ground",
          "surface",
          "subsurface",
          "space",
          "virtual"
        ],
        "description": "The domain of the agent."
      },
      "RealSim": {
        "enum": [
          "real",
          "simulation"
        ],
        "description": "Indicates if agent is real or simulation"
      },
      "AgentName": {
        "description": "The name/ID of the agent"
      }
    },
    "schemas": {
      "AgentBaseTopic": {
        "description": "Base topic string composed of organization, category, domain, real_sim, agent_name",
        "type": "string",
        "properties": {
          "organization": {
            "enum": [
              "waraps",
              "saab",
              "liu",
              "etc."
            ]
          },
          "category": {
            "enum": [
              "unit",
              "service",
              "general"
            ]
          },
          "domain": {
            "enum": [
              "air",
              "ground",
              "surface",
              "subsurface",
              "space",
              "virtual"
            ]
          },
          "real_sim": {
            "enum": [
              "real",
              "simulation"
            ]
          },
          "agent_name": {
            "type": "string"
          }
        },
        "required": [
          "organization",
          "category",
          "domain",
          "real_sim",
          "agent_name"
        ],
        "example": "waraps/sensor/surface/simulation/SimUSV1",
        "pattern": "{organization}/{category}/{domain}/{real_sim}/{agent_name}"
      },
      "AgentUUID": {
        "type": "string",
        "description": "Agent UUID that is unique for each agent. Should be reused between sessions.",
        "format": "uuid"
      },
      "TaskUUID": {
        "type": "string",
        "description": "Task UUID that is unique for each sent task. Used for connecting signals($abort, $pause, ...) to its task.",
        "format": "uuid"
      },
      "AgentName": {
        "description": "The name/ID of the agent.",
        "type": "string",
        "value": "SimUSV1",
        "example": "SimUSV1"
      },
      "AgentDomain": {
        "description": "The type of the agent. Currently corresponding to domains.",
        "type": "string",
        "enum": [
          "air",
          "ground",
          "surface",
          "subsurface",
          "space",
          "virtual"
        ],
        "value": "surface",
        "example": "surface"
      },
      "AgentDescription": {
        "description": "The description of the agent.",
        "type": "string",
        "value": "surface vessel",
        "example": "surface vessel"
      },
      "AgentModel": {
        "description": "Identification of 3D model of the agent.",
        "type": "string",
        "value": "usv.mini_usv",
        "example": "usv.mini_usv"
      },
      "AgentLevel": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/AgentLevelTypes"
        }
      },
      "AgentLevelTypes": {
        "description": "Declaration of agent properties, e.g. L1 = sensor, L2 = direct execution, etc.",
        "type": "string",
        "enum": [
          "sensor",
          "direct execution",
          "tst execution",
          "delegation"
        ],
        "example": "sensor, direct execution"
      },
      "Rate": {
        "type": "number",
        "description": "Rate in frequency (Hz), e.g. 0.2 for declarations, 2.0 for position related sensors.",
        "example": 0.2,
        "format": "float"
      },
      "Stamp": {
        "type": "number",
        "description": "UTC timestamp in unix epoch format with millisecond precision.",
        "example": 1614080475.108,
        "format": "float"
      },
      "AvailableSensors": {
        "description": "Declaration of provided sensors.",
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "position",
            "speed",
            "course",
            "heading",
            "etc."
          ],
          "example": "position, speed, course, heading"
        }
      },
      "AvailableTasks": {
        "description": "Declaration of provided tasks with signals.",
        "type": "string",
        "enum": [
          "move-to",
          "move-path",
          "search-area",
          "look-at",
          "set-speed",
          "etc."
        ],
        "example": "move-to"
      },
      "AvailableSignals": {
        "type": "string",
        "description": "Declaration of supported signals for provided tasks.",
        "enum": [
          "$abort",
          "$enough",
          "$pause",
          "$continue"
        ],
        "examples": [
          "$abort",
          "$enough",
          "$pause",
          "$continue"
        ]
      }
    },
    "messages": {
      "HeartbeatMessage": {
        "name": "heartbeat",
        "description": "Message to indicate the existence of an agent.",
        "contentType": "application/json",
        "payload": {
          "type": "object",
          "properties": {
            "name": {
              "$ref": "#/components/schemas/AgentName"
            },
            "agent-uuid": {
              "$ref": "#/components/schemas/AgentUUID"
            },
            "agent-type": {
              "$ref": "#/components/schemas/AgentDomain"
            },
            "agent-description": {
              "$ref": "#/components/schemas/AgentDescription"
            },
            "agent-model": {
              "$ref": "#/components/schemas/AgentModel"
            },
            "levels": {
              "$ref": "#/components/schemas/AgentLevel"
            },
            "rate": {
              "$ref": "#/components/schemas/Rate"
            },
            "stamp": {
              "$ref": "#/components/schemas/Stamp"
            },
            "type": {
              "type": "string",
              "value": "HeartBeat",
              "example": "HeartBeat"
            }
          },
          "required": [
            "name",
            "agent-uuid",
            "agent-type",
            "levels",
            "rate",
            "stamp",
            "type"
          ]
        }
      },
      "SensorInfoMessage": {
        "name": "sensor_info",
        "description": "Message containing information about which sensors an agent has.",
        "contentType": "application/json",
        "payload": {
          "type": "object",
          "properties": {
            "name": {
              "$ref": "#/components/schemas/AgentName"
            },
            "sensor-data-provided": {
              "$ref": "#/components/schemas/AvailableSensors"
            },
            "rate": {
              "$ref": "#/components/schemas/Rate"
            },
            "stamp": {
              "$ref": "#/components/schemas/Stamp"
            },
            "type": {
              "type": "string",
              "value": "SensorInfo",
              "example": "SensorInfo"
            }
          },
          "required": [
            "name",
            "sensor-data-provided",
            "rate",
            "stamp",
            "type"
          ]
        }
      },
      "DirectExecutionInfoMessage": {
        "name": "direct_execution_info",
        "description": "Message providing information on tasks an agent can execute.",
        "contentType": "application/json",
        "payload": {
          "type": "object",
          "properties": {
            "name": {
              "$ref": "#/components/schemas/AgentName"
            },
            "tasks-available": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "$ref": "#/components/schemas/AvailableTasks"
                  },
                  "signals": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/AvailableSignals"
                    },
                    "example": [
                      "$abort",
                      "$enough",
                      "$pause",
                      "$continue"
                    ]
                  }
                }
              }
            },
            "tasks-executing": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "task-name": {
                    "$ref": "#/components/schemas/AvailableTasks"
                  },
                  "task-uuid": {
                    "$ref": "#/components/schemas/TaskUUID"
                  }
                }
              }
            },
            "rate": {
              "$ref": "#/components/schemas/Rate"
            },
            "stamp": {
              "$ref": "#/components/schemas/Stamp"
            },
            "type": {
              "type": "string",
              "value": "DirectExecutionInfo",
              "example": "DirectExecutionInfo"
            }
          },
          "required": [
            "name",
            "tasks-available",
            "rate",
            "stamp",
            "type"
          ]
        }
      }
    }
  }
}