#####################
Vertical Datum Policy
#####################


Summary
=======

This ADR defines the policy for handling vertical datums in the CWMS Data API, specifically addressing the use of ``OTHER``, ``NATIVE``, and ``LOCAL`` datums and their representation within the system and at the API boundary.


Context
=======

When storing vertical datum information there's a need to support custom or non-standard datums.

In the database ``AT_VERTICAL_DATUM_OFFSET`` table, vertical datums are constrained to ``NGVD29``, ``NAVD88``, ``LOCAL``, and ``STAGE`` (though ``STAGE`` is never used).
Conversely, the ``VERTICAL_DATUM`` field in the ``AT_PHYSICAL_LOCATION`` table is unconstrained and can contain any text.

``LOCAL`` is used within the database to specify any datum that is not ``NGVD29`` or ``NAVD88``. The ``AT_VERT_DATUM_LOCAL`` table is used to specify the actual name of any ``LOCAL`` datum.

Outside the database (e.g., in HEC-DSS files or the vertical datum info XML), the term ``OTHER`` is used as a synonym for ``LOCAL``.

Proposed Changes
================

Vertical Datum Identification in CDA
------------------------------------

* **NATIVE**: Specifies the vertical datum that elevations are stored in for a location (whether that datum is ``NGVD29``, ``NAVD88``, or ``OTHER``). It is critical that all elevations for a location are stored in the same datum to ensure consistency and allow for proper datum conversion during storage or retrieval.
* **OTHER**: An outward-facing synonym for custom datums (represented as ``LOCAL`` in the database).
* **LOCAL**: To avoid confusion with the more general term "NATIVE", we will use ``OTHER`` as the outward-facing term for custom datums, while ``LOCAL`` will be used internally in the database to represent any datum that is not ``NGVD29`` or ``NAVD88``. The actual name of the custom datum will be stored in the ``AT_VERT_DATUM_LOCAL`` table.
* **NGVD29 / NAVD88**: Standard vertical datums.

Storage and Retrieval Logic
---------------------------

The database handles the normalization between ``OTHER`` and ``LOCAL``.

* **Normalization In (Storage)**: ``OTHER`` → ``LOCAL``
* **Normalization Out (Retrieval)**: ``LOCAL`` → ``OTHER``

The ``SET_VERTICAL_DATUM_INFO`` database procedure performs an explicit replacement of ``OTHER`` with ``LOCAL``. Actual custom datum names are stored in the ``AT_VERT_DATUM_LOCAL`` table.

Offset Management
-----------------

When using ``OTHER``/``LOCAL`` datums, offsets to standard datums (like ``NAVD-88``) must be manually provided during storage if they are expected to be retrieved.

* If an offset is stored for ``OTHER``/``LOCAL`` to ``NAVD-88``, the database may automatically create an ``NGVD29`` offset from ``NAVD-88`` on the first read if it doesn't exist.
* This behavior can result in multiple offset rows for a single location.
* It is expected that offsets stored for ``OTHER``/``LOCAL`` datums can be retrieved, but the existence of offsets is not guaranteed.

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

(Status: accept)