============================
Data Event Formats - Ratings
============================


Summary
=======

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

Opinions
========

Opinion 1
---------

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

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

After implementation, the RatingStored messages published to various ``TS_STORED`` and ``REALTIME_OPS`` topics will be deprecated and removed.

Author: Mike Perryman


**Rating Templates**

Only "type", "office_id", and "template_id" values are required.

+-----------------------+------------------------------------------------------------------------------+
| Message Type          | Structure                                                                    |
+=======================+==============================================================================+
| RatingTemplateCreated | +------------+--------------------------+----------------------------------+ |
|                       | | Value Type |  Value Name              | Value                            | |
|                       | +============+==========================+==================================+ |
|                       | | String     | "type"                   | "rating_template_created"        | |
|                       | +------------+--------------------------+----------------------------------+ |
|                       | | String     | "office_id"              | The office identifier            | |
|                       | +------------+--------------------------+----------------------------------+ |
|                       | | String     | "template_id"            | The rating template identifier   | |
|                       | +------------+--------------------------+----------------------------------+ |
|                       | | String     | "description"            | The description for the template | |
|                       | +------------+--------------------------+----------------------------------+ |
+-----------------------+------------------------------------------------------------------------------+

.. code-block:: json

    {
        "type": "rating_template_created",
        "office_id": "SWT",
        "template_id": "Stage;Flow.Logarithmic",
        "description": "USGS-style stage/flow ratings"
    }

+-----------------------+------------------------------------------------------------------------------+
| Message Type          | Structure                                                                    |
+=======================+==============================================================================+
| RatingTemplateUpdated | +------------+--------------------------+----------------------------------+ |
|                       | | Value Type |  Value Name              | Value                            | |
|                       | +============+==========================+==================================+ |
|                       | | String     | "type"                   | "rating_template_updated"        | |
|                       | +------------+--------------------------+----------------------------------+ |
|                       | | String     | "office_id"              | The office identifier            | |
|                       | +------------+--------------------------+----------------------------------+ |
|                       | | String     | "template_id"            | The rating template identifier   | |
|                       | +------------+--------------------------+----------------------------------+ |
|                       | | String     | "description"            | The description for the template | |
|                       | +------------+--------------------------+----------------------------------+ |
+-----------------------+------------------------------------------------------------------------------+

.. code-block:: json

    {
        "type": "rating_template_updated",
        "office_id": "SWT",
        "template_id": "Stage;Flow.Logarithmic",
        "description": "USGS-style stage/flow BASE ratings"
    }

+-----------------------+------------------------------------------------------------------------------+
| Message Type          | Structure                                                                    |
+=======================+==============================================================================+
| RatingTemplateDeleted | +------------+--------------------------+----------------------------------+ |
|                       | | Value Type |  Value Name              | Value                            | |
|                       | +============+==========================+==================================+ |
|                       | | String     | "type"                   | "rating_template_deleted"        | |
|                       | +------------+--------------------------+----------------------------------+ |
|                       | | String     | "office_id"              | The office identifier            | |
|                       | +------------+--------------------------+----------------------------------+ |
|                       | | String     | "template_id"            | The rating template identifier   | |
|                       | +------------+--------------------------+----------------------------------+ |
+-----------------------+------------------------------------------------------------------------------+

.. code-block:: json

    {
        "type": "rating_template_deleted",
        "office_id": "SWT",
        "template_id": "Stage;Flow.Logarithmic"
    }

**Rating Specifications**

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

+----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Message Type               | Structure                                                                                                                                                       |
+============================+=================================================================================================================================================================+
| RatingSpecificationCreated | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | Value Type | Value Name                | Value                                                                                                              | |
|                            | +============+===========================+====================================================================================================================+ |
|                            | | String     | "type"                    | "rating_specification_created"                                                                                     | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | String     | "office_id"               | The office identifier                                                                                              | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | String     | "specification_id"        | The rating specification identifier                                                                                | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | String     | "source_agency"           | The entity that generates ratings for this specification                                                           | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | String     | "in_range_method"         | The interpoloation method used when values are in range of rating values                                           | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | String     | "out_range_low_method"    | The extrapolation method used when values are below the range of rating values                                     | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | String     | "out_range_high_method"   | The extrapolation method used when values are above the range of rating values                                     | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | boolean    | "active"                  | Whether the specification is active                                                                                | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | boolean    | "auto_update"             | Whether ratings with this specification should be automatically updated                                            | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | boolean    | "auto_activate"           | Whether ratings with this specification should be set to active when automatically updated                         | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | boolean    | "auto_migrate_extensions" | Whether ratings with this specification should have existing rating extensions migrated when automatically updated | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | String     | "independent_rounding"    | Rounding specifications for independent parameters, in order, comma separated                                      | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | String     | "dependent_rounding"      | Rounding specification for the dependent parameter                                                                 | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | String     | "description"             | The description for the specification                                                                              | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
+----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+

.. code-block:: json

    {
        "type": "rating_specification_created",
        "office_id": "SWT",
        "specification_id": "Tulsa.Stage;Flow.Logarithmic.Production",
        "source_agency": "ABRFC",
        "in_range_method": "LINEAR",
        "out_range_low_method": "NEAREST",
        "out_range_high_method": "NEAREST",
        "active": true,
        "auto_update": true,
        "auto_activate": true,
        "auto_migrate_extensions": true,
        "independent_rounding": "4444444444",
        "dependent_rounding": "4444444444",
        "description": "USGS streamflow rating for the Arkansas River at Tulsa, OK"
    }

+----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Message Type               | Structure                                                                                                                                                       |
+============================+=================================================================================================================================================================+
| RatingSpecificationUpdated | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | Value Type | Value Name                | Value                                                                                                              | |
|                            | +============+===========================+====================================================================================================================+ |
|                            | | String     | "type"                    | "rating_specification_updated"                                                                                     | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | String     | "office_id"               | The office identifier                                                                                              | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | String     | "specification_id"        | The rating specification identifier                                                                                | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | String     | "source_agency"           | The entity that generates ratings for this specification                                                           | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | String     | "in_range_method"         | The interpoloation method used when values are in range of rating values                                           | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | String     | "out_range_low_method"    | The extrapolation method used when values are below the range of rating values                                     | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | String     | "out_range_high_method"   | The extrapolation method used when values are above the range of rating values                                     | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | boolean    | "active"                  | Whether the specification is active                                                                                | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | boolean    | "auto_update"             | Whether ratings with this specification should be automatically updated                                            | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | boolean    | "auto_activate"           | Whether ratings with this specification should be set to active when automatically updated                         | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | boolean    | "auto_migrate_extensions" | Whether ratings with this specification should have existing rating extensions migrated when automatically updated | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | String     | "independent_rounding"    | Rounding specifications for independent parameters, in order, comma separated                                      | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | String     | "dependent_rounding"      | Rounding specification for the dependent parameter                                                                 | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | String     | "description"             | The description for the specification                                                                              | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
+----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+

.. code-block:: json

    {
        "type": "rating_specification_updated",
        "office_id": "SWT",
        "specification_id": "Tulsa.Stage;Flow.Logarithmic.Production",
        "source_agency": "ABRFC",
        "in_range_method": "LINEAR",
        "out_range_low_method": "NULL",
        "out_range_high_method": "NEAREST",
        "active": true,
        "auto_update": true,
        "auto_activate": true,
        "auto_migrate_extensions": true,
        "independent_rounding": "0223456782",
        "dependent_rounding": "0222233332",
        "description": "USGS streamflow rating for the Arkansas River at Tulsa, OK"
    }

+----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Message Type               | Structure                                                                                                                                                       |
+============================+=================================================================================================================================================================+
| RatingSpecificationDeleted | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | Value Type | Value Name                | Value                                                                                                              | |
|                            | +============+===========================+====================================================================================================================+ |
|                            | | String     | "type"                    | "rating_specification_deleted"                                                                                     | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | String     | "office_id"               | The office identifier                                                                                              | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
|                            | | String     | "specification_id"        | The rating specification identifier                                                                                | |
|                            | +------------+---------------------------+--------------------------------------------------------------------------------------------------------------------+ |
+----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+

.. code-block:: json

    {
        "type": "rating_specification_deleted",
        "office_id": "SWT",
        "specification_id": "Tulsa.Stage;Flow.Logarithmic.Production"
    }

**Ratings**

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

+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
| Message Type  | Structure                                                                                                                             |
+===============+=======================================================================================================================================+
| RatingCreated | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
|               | | Value Type | Value Name         | Value                                                                                           | |
|               | +============+====================+=================================================================================================+ |
|               | | String     | "type"             | "rating_created"                                                                                | |
|               | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
|               | | String     | "office_id"        | The office identifier                                                                           | |
|               | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
|               | | String     | "specification_id" | The rating specification identifier                                                             | |
|               | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
|               | | long       | "effective_time"   | The date/time the rating comes into effect, in epoch milliseconds                               | |
|               | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
|               | | long       | "transition_time"  | The date/time the to begin linear interpolation from the previous rating, in epoch milliseconds | |
|               | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
|               | | long       | "creation_time"    | The date/time before which no there is no knowlege of this rating, in epoch milliseconds        | |
|               | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
|               | | boolean    | "active"           | Whether this rating is active                                                                   | |
|               | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
|               | | String     | "rating_type"      | "lookup", "expression", "usgs", "virtual", or "transitional"                                    | |
|               | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
+---------------+---------------------------------------------------------------------------------------------------------------------------------------+

.. code-block:: json

    {
        "type": "rating_created",
        "office_id": "SWT",
        "specification_id": "Tulsa.Stage;Flow.Logarithmic.Production",
        "effective_time": 1782190800000,
        "transition_time": 1780981200000,
        "creation_time": 1787140800000,
        "active": false,
        "rating_type": "usgs"
    }

+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
| Message Type  | Structure                                                                                                                             |
+===============+=======================================================================================================================================+
| RatingUpdated | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
|               | | Value Type | Value Name         | Value                                                                                           | |
|               | +============+====================+=================================================================================================+ |
|               | | String     | "type"             | "rating_updated"                                                                                | |
|               | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
|               | | String     | "office_id"        | The office identifier                                                                           | |
|               | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
|               | | String     | "specification_id" | The rating specification identifier                                                             | |
|               | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
|               | | long       | "effective_time"   | The date/time the rating comes into effect, in epoch milliseconds                               | |
|               | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
|               | | long       | "transition_time"  | The date/time the to begin linear interpolation from the previous rating, in epoch milliseconds | |
|               | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
|               | | long       | "creation_time"    | The date/time before which no there is no knowlege of this rating, in epoch milliseconds        | |
|               | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
|               | | boolean    | "active"           | Whether this rating is active                                                                   | |
|               | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
|               | | String     | "rating_type"      | "lookup", "expression", "usgs", "virtual", or "transitional"                                    | |
|               | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
+---------------+---------------------------------------------------------------------------------------------------------------------------------------+

.. code-block:: json

    {
        "type": "rating_updated",
        "office_id": "SWT",
        "specification_id": "Tulsa.Stage;Flow.Logarithmic.Production",
        "effective_time": 1782190800000,
        "transition_time": 1780981200000,
        "creation_time": 1787140800000,
        "active": true,
        "rating_type": "usgs"
    }

+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
| Message Type  | Structure                                                                                                                             |
+===============+=======================================================================================================================================+
| RatingDeleted | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
|               | | Value Type | Value Name         | Value                                                                                           | |
|               | +============+====================+=================================================================================================+ |
|               | | String     | "type"             | "rating_deleted"                                                                                | |
|               | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
|               | | String     | "office_id"        | The office identifier                                                                           | |
|               | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
|               | | String     | "specification_id" | The rating specification identifier                                                             | |
|               | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
|               | | long       | "effective_time"   | The date/time the rating comes into effect, in epoch milliseconds                               | |
|               | +------------+--------------------+-------------------------------------------------------------------------------------------------+ |
+---------------+---------------------------------------------------------------------------------------------------------------------------------------+

.. code-block:: json

    {
        "type": "rating_deleted",
        "office_id": "SWT",
        "specification_id": "Tulsa.Stage;Flow.Logarithmic.Production",
        "effective_time": 1782190800000
    }


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

Status: request for comments

References
==========