Data format

The fields of a release, its JSON Schema and the converters. The files and where to download them are on Downloads.

Fields

The JSON document has six top-level fields: format_version, release, conventions, licences, constituents and stations.

station

A stable station_id in the OTC namespace (never changed, never reused), name, country, position, IANA time zone, type (reference or subordinate), aliases in other systems (NOAA, GESLA, TICON, XTide, Kartverket, Slackwater), and the recommended_set_id. An alias id belongs to one station only in a release. A removed station stays as a tombstone with its reason.

constant set

One per source record: source, source type (official, gauge or model), quantity (water_level or current), record id and version, record span, datum, convention_id, licence_id, QC status and flags, the constituents, and provenance. A station can have several sets; one is recommended by a published rule.

constituent

OTC canonical name and the source's own name, Doodson number, speed (°/h), amplitude (m), Greenwich phase (°), uncertainties, and why it was kept. Dropped constituents are listed with the reason. Names are at most 15 characters.

constituent table

One row per constituent name and constituent-table version in the release: Doodson number, speed (°/h) and nodal formula id.

current bin

Only in a set with quantity current, which has no water-level constituents. One per depth bin: bin number, depth (m) and how it is measured (below_surface, below_chart_datum or unknown, from NOAA's S, B and U), major-axis azimuth (° true), mean flood and ebb directions, the mean current along the major and minor axes (m/s, signed), and per constituent the speed (°/h), major- and minor-axis amplitude (m/s) and Greenwich phase (°). The station's default_current_bin names the bin to show first.

subordinate offsets

Reference station, time offsets at high and low water (minutes), height offsets, and whether they are ratios or additive, as NOAA gives them. A subordinate current station has current_offsets instead, one per bin: reference station and bin, mean flood and ebb directions, time adjustments for maximum flood, slack before ebb, maximum ebb and slack before flood (minutes), and flood and ebb amplitude ratios.

convention

Phase reference, V0 model, nodal handling, constituent-table version, and the result of the per-source check that confirmed it. See Conventions.

validation

Per station and window: time mean absolute error, 95th percentile, bias, height error, range error, missed and extra events, the reference source and its distance, and the same numbers for the previous release. See Validation.

licence

SPDX id (or a LicenseRef- id), provider, required citation, and the assembled attribution text. See Licence and attribution.

JSON Schema

• otc-0.5.schema.json: the JSON Schema (draft 2020-12) for format_version 0.5. Each line of the .jsonl file validates against #/$defs/station, and the .meta.json file against #/$defs/meta.
• otc-0.4.schema.json, otc-0.3.schema.json, otc-0.2.schema.json and otc-0.1.schema.json: the earlier versions, for format_version 0.4, 0.3, 0.2 and 0.1. Kept for reference. 0.3 adds alias systems for the gauge and official sources (linz, shom, pegelonline, rws, mi, dmi, smhi, fmi, uhslc). 0.4 adds tidal-current constants (current_bins), current offsets and default_current_bin. 0.5 adds the mean current of a bin (mean_major_ms, mean_minor_ms) and the depth type below_chart_datum for NOAA's B, which 0.4 wrongly called above_bottom.
• example.json: a small example document with illustrative values (not data). It has one tide station with two constant sets, one tombstone, one current station (NOAA ACT1616, with five of its constituents and its mean current converted from NOAA's published values) and one subordinate current station.

The format version is separate from the release date. A new field is a minor change; a removed or renamed field, or a changed unit or convention, is a major change.

Converters

Converters, in both directions, with a lossless round trip as a release gate: TICON CSV, XTide TCD (through libtcd), and NOAA harmonic-constant JSON. The reference predictor publishes conformance vectors (expected high and low water times and heights at named stations and dates) so that other predictors can check their results.