==============================
Data Event Formats - Forecasts
==============================


Summary
=======

CWMS needs an message structure to notify clients of forecast-related events.

Opinions
========

Opinion 1
---------

Summary: Use the structure described below for forecast-related events.

All messages will be published to the appropriate ``REALTIME_OPS`` topic. Subscribers can set up appropriate filters to receive the desired messages.

Author: Mike Perryman


**Forecast Specifications**

Only "type", "office_id", "specification_id" and "designator" values are required.

+-----------------+--------------------------------------------------------------------------------------------------------+
| Message Type    | Structure                                                                                              |
+=================+========================================================================================================+
| FcstSpecCreated |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | Value Type | Value Name         | Value                                                           | |
|                 |  +============+====================+=================================================================+ |
|                 |  | String     | "type"             | "forecast_specification_created"                                | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "office_id"        | The office identifier                                           | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "specification_id" | The forecast specification identifier                           | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "designator"       | The forecast designator                                         | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "location_id"      | The specified location identifier of the primary location       | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "entity_id"        | The specified entity identifier                                 | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "description"      | The specified description                                       | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | int        | "num_time_series"  | The number of time series specified                             | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
+-----------------+--------------------------------------------------------------------------------------------------------+

.. code-block:: json

    {
        "type": "forecast_specification_created",
        "office_id": "SWT",
        "specification_id": "Keystone",
        "designator": "CAVI",
        "location_id": "Keystone Lake",
        "entity_id": "CESWT",
        "description": "Official USACE forecast for Keystone Lake, OK",
        "num_time_series": 12
    }

+-----------------+--------------------------------------------------------------------------------------------------------+
| Message Type    | Structure                                                                                              |
+=================+========================================================================================================+
| FcstSpecUpdated |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | Value Type | Value Name         | Value                                                           | |
|                 |  +============+====================+=================================================================+ |
|                 |  | String     | "type"             | "forecast_specification_updated"                                | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "office_id"        | The office identifier                                           | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "specification_id" | The forecast specification identifier                           | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "designator"       | The forecast designator                                         | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "location_id"      | The specified location identifier of the primary location       | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "entity_id"        | The specified entity identifier                                 | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "description"      | The specified description                                       | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | int        | "num_time_series"  | The number of time series specified                             | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
+-----------------+--------------------------------------------------------------------------------------------------------+

.. code-block:: json

    {
        "type": "forecast_specification_updated",
        "office_id": "SWT",
        "specification_id": "Keystone",
        "designator": "CAVI",
        "location_id": "Keystone Lake",
        "entity_id": "CESWT",
        "description": "Official USACE forecast for Keystone Lake, OK",
        "num_time_series": 14
    }

+-----------------+--------------------------------------------------------------------------------------------------------+
| Message Type    | Structure                                                                                              |
+=================+========================================================================================================+
| FcstSpecDeleted |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | Value Type | Value Name         | Value                                                           | |
|                 |  +============+====================+=================================================================+ |
|                 |  | String     | "type"             | "forecast_specification_deleted"                                | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "office_id"        | The office identifier                                           | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "specification_id" | The forecast specification identifier                           | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "designator"       | The forecast designator                                         | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
+-----------------+--------------------------------------------------------------------------------------------------------+

.. code-block:: json

    {
        "type": "forecast_specification_deleted",
        "office_id": "SWT",
        "specification_id": "Keystone",
        "designator": "CAVI"
    }

**Forecast Instances**

Only "type", "office_id", "specification_id", "designator, "forecast_time" and "issue_time" values are required.

+-----------------+--------------------------------------------------------------------------------------------------------+
| Message Type    | Structure                                                                                              |
+=================+========================================================================================================+
| FcstInstCreated |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | Value Type | Value Name         | Value                                                           | |
|                 |  +============+====================+=================================================================+ |
|                 |  | String     | "type"             | "forecast_instance_created"                                     | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "office_id"        | The office identifier                                           | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "specification_id" | The forecast specification identifier                           | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "designator"       | The forecast designator                                         | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | long       | "forecast_time"    | The forecast date/time in epoch milliseconds                    | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | long       | "issue_time"       | The issue date/time in epoch milliseconds                       | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | int        | "max_age"          | The number of hours after issue date that the forecast is valid | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "notes"            | Any notes specific to the forecast                              | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "info"             | Key/values pairs for the forecast, in JSON format               | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "blob_file_name"   | The file name of the specified blob                             | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "media_type"       | The media type of the specified blob                            | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
+-----------------+--------------------------------------------------------------------------------------------------------+

.. code-block:: json

    {
        "type": "forecast_instance_created",
        "office_id": "SWT",
        "specification_id": "Keystone",
        "designator": "CAVI",
        "forecast_time": 1787245200000,
        "issue_time": 1787158800000,
        "max_age": 24,
        "notes": "Revision 2",
        "info": "{\"forecaster\": \"M5ECHABC\"}",
        "blob_file_name": "keys_fcst2.zip",
        "media_type": "application/zip"
    }

+-----------------+--------------------------------------------------------------------------------------------------------+
| Message Type    | Structure                                                                                              |
+=================+========================================================================================================+
| FcstInstUpdated |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | Value Type | Value Name         | Value                                                           | |
|                 |  +============+====================+=================================================================+ |
|                 |  | String     | "type"             | "forecast_instance_updated"                                     | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "office_id"        | The office identifier                                           | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "specification_id" | The forecast specification identifier                           | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "designator"       | The forecast designator                                         | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | long       | "forecast_time"    | The forecast date/time in epoch milliseconds                    | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | long       | "issue_time"       | The issue date/time in epoch milliseconds                       | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | int        | "max_age"          | The number of hours after issue date that the forecast is valid | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "notes"            | Any notes specific to the forecast                              | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "info"             | Key/values pairs for the forecast, in JSON format               | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "blob_file_name"   | The file name of the specified blob                             | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "media_type"       | The media type of the specified blob                            | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
+-----------------+--------------------------------------------------------------------------------------------------------+

.. code-block:: json

    {
        "type": "forecast_instance_updated",
        "office_id": "SWT",
        "specification_id": "Keystone",
        "designator": "CAVI",
        "forecast_time": 1787245200000,
        "issue_time": 1787158800000,
        "max_age": 24,
        "notes": "Revision 2",
        "info": "{\"forecaster\": \"M5ECHABC\"}",
        "blob_file_name": "keys_fcst3.zip",
        "media_type": "application/zip"
    }

+-----------------+--------------------------------------------------------------------------------------------------------+
| Message Type    | Structure                                                                                              |
+=================+========================================================================================================+
| FcstInstDeleted |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | Value Type | Value Name         | Value                                                           | |
|                 |  +============+====================+=================================================================+ |
|                 |  | String     | "type"             | "forecast_instance_deleted"                                     | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "office_id"        | The office identifier                                           | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "specification_id" | The forecast specification identifier                           | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | String     | "designator"       | The forecast designator                                         | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | long       | "forecast_time"    | The forecast date/time in epoch milliseconds                    | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
|                 |  | long       | "issue_time"       | The issue date/time in epoch milliseconds                       | |
|                 |  +------------+--------------------+-----------------------------------------------------------------+ |
+-----------------+--------------------------------------------------------------------------------------------------------+

.. code-block:: json

    {
        "type": "forecast_instance_deleted",
        "office_id": "SWT",
        "specification_id": "Keystone",
        "designator": "CAVI",
        "forecast_time": 1787245200000,
        "issue_time": 1787158800000
    }


Decision Status
===============

Status: request for comments

References
==========