README.md

# Overview
This project repository is a collaborative workspace. It consists of all messages transferred into and out of the Communications Backbone. Message type schemas will be developed once reviewing each platform's data and statuses defined by each partner.

The schemas are using OpenApi 3.0 (due to the `payload` sub-schemas that vary according to the `message_type`).

## Message Types
Each message below will be wrapped in a `payload` field and will have a `header` with message metadata information:
* `mission_plan`: these would be two message types, i. encoded (platform-specific serialized message) and ii. parsed, human-readable message.
* `platform_status`: these would be two message types, i. encoded (platform-specific serialized message) and ii. parsed, human-readable message.
* `observation`: this would be desired scientific data sent by the platform
* `acknowledgement`: level of acknowledgment where an acknowledgement is sent when a message is i. received, ii. sent to the next destination (e.g. platform in the water).
* `planning_configuration`: sent from the GUI to initialise the AI model (autonomy engine).

## Topics 

Messages are routed using either a publish/subscribe or broadcast mechanism. 

For published messages, the message is published for a given a topic. 

Clients create a subscription (stored in their config) to a topic pattern which may include wildcards. 

It's important to note that the client config documents the subscription. To change a client 
subscription it must be updated with the backbone.

Published messages are delivered to all clients where 
the message topic matches the client's subscription 
topic pattern.

Broadcast messages are delivered to all clients regardless of their subscription. 

### Field

The topic should be set in the `message.header.destination` for published messages. 
The `destination` field should be set to `broadcast` for any messages sent using broadcast. 

Because the `destination` field is a topic it defines what the message relates to - not 
who the intended recipient is. 

This means that the clients are not typically represented in the topics. A client publishes a message about a platform and subscribers interested in that project, platform or message type will receive that message.

### Structure

`<prefix>.<operator>.<platform_type>.<platform_identifier>.<to_platform|from_platform>.<message_type>`

e.g
* `soar.noc.autosub.ah1.from_platform.platform_status`
* `soar.planet-ocean.ecosub.eco1.to_platform.mission_plan`
* `soar.hydrosurv.reav.reav1.to_platform.mission_plan`

### Terms

* `prefix` - an agreed hard-coded/config setting prefix shared by all adapters and client subscriptions eg soar 
* `operator` - human readable organisation name for the platform operator one of [noc|planet-ocean|hydrosurv] 
* `platform_type` - one of [autosub|ecosub|reav?]
* `platform_identifier` - human readable identifier for the platform eg ah1, eco1, reav1 
* `to_platform|from_platform` - eg ..to_platform.mission_plan, ..from_platform.platform_status
missions are sent `to_platform` to be executed and status updates are received `from_platform` containing 
information about its position and health status
* `message_type` - one of `[acknowledgement|mission_plan|observation|planning_configuration|platform_status...]`

### Subscriptions

Subscriptions may contain multiword wildcards (#) or single word wildcards (*)
eg
* `soar.#` - everything 
* `soar.planet-ocean.#` - anything relating to the planet-ocean operator
* `soar.*.*.*.from_platform.*` - all messages inbound from platforms (autonomy engine)
* `soar.*.*.*.to_platform.*` - all messages outbound to platforms (hermes)
* `soar.*.slocum.#` - all messages relating to a slocum platform type

## Run Docs
Run the command below and go to `http://127.0.0.1:5000`
```
python3 generate_schema_config.py
```
## Run Tests
Run the command below
```
python3 -m unittest tests/test_schemas.py
```

## Quick Links
1. [Generated Swagger Docs (recommended to look at this)](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/blob/dev/project/soar/swagger.json)
2. [Schema Fields Definitions](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/tree/dev/formats)
3. [JSON Schema Examples](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/tree/dev/examples)
4. Ongoing Project: [SoAR README.md](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/blob/dev/project/soar/SOAR_README.md)

## Installing 

You can install the message formats as a package with pip

```requirements.txt
backbone-message-format @ git+https://git.noc.ac.uk/communications-backbone-system/backbone-message-format.git@v0.1.0#egg=backbone-message-format
```

### Importing the formats 

```python
import backbone_formats
```

### Importing the compiled schema 

```python
import importlib.resources
import soar_schema
import json
with importlib.resources.open_text(soar_schema, "swagger.json") as file:
    schema = json.load(file)
```