{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://hydro-look.vercel.app/api/schema/latest.schema.json",
  "title": "latest.json",
  "description": "The current state of the fleet and the national balance: one reading per reservoir, the latest closed day, and the adequacy headline.",
  "type": "object",
  "required": [
    "schema_version",
    "generated_at",
    "data_date",
    "as_of",
    "disclaimer",
    "reservoirs",
    "national",
    "live",
    "adequacy",
    "license",
    "attribution",
    "see_also"
  ],
  "properties": {
    "schema_version": {
      "type": "integer",
      "const": 1,
      "description": "The format version. Changes only when a field is removed, renamed or retyped; added fields do not change it."
    },
    "generated_at": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$",
      "description": "When the document was written, UTC."
    },
    "data_date": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "The Ecuadorian calendar day the document's readings describe."
    },
    "as_of": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "deprecated": true,
      "description": "Deprecated: the day the job ran. Use data_date. Removed in schema_version 2."
    },
    "disclaimer": {
      "type": "string"
    },
    "reservoirs": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "site": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "basin": {
            "type": "string"
          },
          "level": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "masl": {
                "type": "number"
              },
              "date": {
                "type": "string",
                "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
              },
              "first_reading": {
                "type": "string",
                "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
              },
              "days": {
                "type": "integer"
              },
              "observed_min_masl": {
                "type": "number"
              },
              "observed_max_masl": {
                "type": "number"
              },
              "previous": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "masl": {
                    "type": "number"
                  },
                  "date": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                  }
                },
                "required": [
                  "masl",
                  "date"
                ]
              },
              "delta_1d_m": {
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "required": [
              "masl",
              "date",
              "first_reading",
              "days",
              "observed_min_masl",
              "observed_max_masl",
              "previous",
              "delta_1d_m"
            ]
          },
          "bands": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "min_masl": {
                  "type": "number"
                },
                "max_masl": {
                  "type": "number"
                },
                "declaration": {
                  "type": "string",
                  "enum": [
                    "report_endpoint",
                    "dashboard_chart_title",
                    "operational_minimum"
                  ],
                  "description": "How CELEC declared the band, as a code."
                },
                "declaration_es": {
                  "type": "string"
                },
                "source": {
                  "type": "string"
                },
                "observed_from": {
                  "type": "string",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                },
                "observed_to": {
                  "type": "string",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                },
                "band_pct": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "(level - min) / (max - min) * 100. A position in the band, not stored water."
                },
                "metres_above_min": {
                  "type": [
                    "number",
                    "null"
                  ]
                }
              },
              "required": [
                "min_masl",
                "max_masl",
                "declaration",
                "declaration_es",
                "source",
                "observed_from",
                "observed_to",
                "band_pct",
                "metres_above_min"
              ]
            }
          },
          "slopes_m_per_day": {
            "type": "object",
            "properties": {
              "d7": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "d14": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "d30": {
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "required": [
              "d7",
              "d14",
              "d30"
            ]
          },
          "inflow": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "m3s": {
                "type": "number"
              },
              "date": {
                "type": "string",
                "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
              },
              "first_reading": {
                "type": "string",
                "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
              },
              "days": {
                "type": "integer"
              },
              "climatology": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "p10": {
                    "type": "number"
                  },
                  "p50": {
                    "type": "number"
                  },
                  "p90": {
                    "type": "number"
                  },
                  "years": {
                    "type": "integer"
                  },
                  "n": {
                    "type": "integer"
                  },
                  "percentile_today": {
                    "type": [
                      "number",
                      "null"
                    ]
                  }
                },
                "required": [
                  "p10",
                  "p50",
                  "p90",
                  "years",
                  "n",
                  "percentile_today"
                ]
              },
              "previous": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "m3s": {
                    "type": "number"
                  },
                  "date": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                  }
                },
                "required": [
                  "m3s",
                  "date"
                ]
              },
              "delta_1d_m3s": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "return_periods": {
                "type": "object",
                "description": "Today's inflow against the floods this river is known for, from two sources kept apart because they disagree: GEOGLOWS v2 (the model behind INAMHI's portal, inamhi.geoglows.org) and the same statistic fitted on CELEC's record. data/reports/return-periods.md compares them.",
                "properties": {
                  "geoglows": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "description": "The return periods INAMHI's Hydroviewer (inamhi.geoglows.org) draws for the GEOGLOWS v2 river matched to this dam, beside the GEOGLOWS store's own fits (data/reference/geoglows_return_periods.csv). Null where no river matched or `npm run geoglows` has not run. `inamhi` and `simulated_vs_measured` are computed here from GEOGLOWS' daily simulation (CC BY 4.0, attribution `geoglows`); `daily` and `hourly` are copied from its return-period store (CC BY-NC-SA 4.0, attribution `geoglows_return_periods`).",
                    "properties": {
                      "river_id": {
                        "type": "integer",
                        "description": "GEOGLOWS v2 / TDX-Hydro river id (LINKNO)."
                      },
                      "inamhi": {
                        "$ref": "#/$defs/return_period_table",
                        "description": "What INAMHI's Hydroviewer draws: a method-of-moments Gumbel on the annual maxima of GEOGLOWS' daily simulation from 1980, every calendar year counted. `reached_years` is read against these."
                      },
                      "daily": {
                        "$ref": "#/$defs/return_period_table",
                        "description": "The GEOGLOWS store's own fit on the daily simulation from 1940. CC BY-NC-SA 4.0."
                      },
                      "hourly": {
                        "$ref": "#/$defs/return_period_table",
                        "description": "The GEOGLOWS store's fit on hourly flow from 1940. CC BY-NC-SA 4.0."
                      },
                      "area_diff_pct": {
                        "type": "number",
                        "description": "GEOGLOWS' drainage area at the river's outlet against the catchment this repository delineated, %."
                      },
                      "store_revision_date": {
                        "type": "string"
                      },
                      "reached_years": {
                        "type": [
                          "integer",
                          "null"
                        ],
                        "description": "Against `inamhi`: the longest return period whose flow today's inflow reaches; null below the 2-year flow."
                      },
                      "simulated_vs_measured": {
                        "type": [
                          "object",
                          "null"
                        ],
                        "description": "GEOGLOWS' simulated daily flow against CELEC's measured inflow on the days both have: mean simulated ÷ mean measured, and the correlation of monthly means.",
                        "properties": {
                          "days": {
                            "type": "integer"
                          },
                          "ratio": {
                            "type": "number"
                          },
                          "r_monthly": {
                            "type": [
                              "number",
                              "null"
                            ]
                          }
                        },
                        "required": [
                          "days",
                          "ratio",
                          "r_monthly"
                        ]
                      }
                    },
                    "required": [
                      "river_id",
                      "inamhi",
                      "daily",
                      "hourly",
                      "area_diff_pct",
                      "store_revision_date",
                      "reached_years",
                      "simulated_vs_measured"
                    ]
                  },
                  "measured": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "description": "The same Gumbel fit on the annual maxima of CELEC's daily inflow, over calendar years with at least 330 readings. Null with fewer than five such years.",
                    "properties": {
                      "years": {
                        "type": "integer"
                      },
                      "first_year": {
                        "type": "integer"
                      },
                      "last_year": {
                        "type": "integer"
                      },
                      "values": {
                        "$ref": "#/$defs/return_period_table"
                      },
                      "reached_years": {
                        "type": [
                          "integer",
                          "null"
                        ],
                        "description": "The longest return period whose flow today's inflow reaches; null below the 2-year flow."
                      },
                      "record_m3s": {
                        "type": "number"
                      },
                      "record_date": {
                        "type": "string",
                        "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                      }
                    },
                    "required": [
                      "years",
                      "first_year",
                      "last_year",
                      "values",
                      "reached_years",
                      "record_m3s",
                      "record_date"
                    ]
                  }
                },
                "required": [
                  "geoglows",
                  "measured"
                ]
              }
            },
            "required": [
              "m3s",
              "date",
              "first_reading",
              "days",
              "climatology",
              "previous",
              "delta_1d_m3s",
              "return_periods"
            ]
          }
        },
        "required": [
          "site",
          "label",
          "basin",
          "level",
          "bands",
          "slopes_m_per_day",
          "inflow"
        ]
      }
    },
    "national": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "date": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        "supply_gwh": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "concept": {
                "type": "string"
              },
              "gwh": {
                "type": "number"
              },
              "pct": {
                "type": "number"
              }
            },
            "required": [
              "concept",
              "gwh",
              "pct"
            ]
          }
        },
        "total_generation_gwh": {
          "type": [
            "number",
            "null"
          ]
        },
        "total_import_gwh": {
          "type": [
            "number",
            "null"
          ]
        },
        "total_export_gwh": {
          "type": [
            "number",
            "null"
          ]
        },
        "distribution_demand_gwh": {
          "type": [
            "number",
            "null"
          ]
        },
        "transport_losses_gwh": {
          "type": [
            "number",
            "null"
          ]
        },
        "hydro_share_pct": {
          "type": [
            "number",
            "null"
          ]
        },
        "thermal_share_pct": {
          "type": [
            "number",
            "null"
          ]
        },
        "import_share_pct": {
          "type": [
            "number",
            "null"
          ]
        },
        "previous": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "date": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "total_generation_gwh": {
              "type": [
                "number",
                "null"
              ]
            },
            "total_import_gwh": {
              "type": [
                "number",
                "null"
              ]
            },
            "hydro_share_pct": {
              "type": [
                "number",
                "null"
              ]
            },
            "thermal_share_pct": {
              "type": [
                "number",
                "null"
              ]
            },
            "import_share_pct": {
              "type": [
                "number",
                "null"
              ]
            }
          },
          "required": [
            "date",
            "total_generation_gwh",
            "total_import_gwh",
            "hydro_share_pct",
            "thermal_share_pct",
            "import_share_pct"
          ]
        },
        "delta_1d": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "hydro_share_pct_points": {
              "type": [
                "number",
                "null"
              ]
            },
            "thermal_share_pct_points": {
              "type": [
                "number",
                "null"
              ]
            },
            "import_share_pct_points": {
              "type": [
                "number",
                "null"
              ]
            },
            "total_generation_gwh": {
              "type": [
                "number",
                "null"
              ]
            }
          },
          "required": [
            "hydro_share_pct_points",
            "thermal_share_pct_points",
            "import_share_pct_points",
            "total_generation_gwh"
          ]
        }
      },
      "required": [
        "date",
        "supply_gwh",
        "total_generation_gwh",
        "total_import_gwh",
        "total_export_gwh",
        "distribution_demand_gwh",
        "transport_losses_gwh",
        "hydro_share_pct",
        "thermal_share_pct",
        "import_share_pct",
        "previous",
        "delta_1d"
      ]
    },
    "live": {
      "type": [
        "object",
        "null"
      ],
      "description": "Today so far: CENACE Información Operativa's running total since local midnight (preliminary SCADA), newer than national and partial. Totals are not comparable with a closed day; shares are over production plus imports, as in national. Null when no real-time reading has been stored.",
      "properties": {
        "date": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "The Ecuadorian calendar day the running total covers."
        },
        "fetched_at": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$",
          "description": "When CENACE's page was read, UTC; the total covers local midnight up to about this instant."
        },
        "total_production_gwh": {
          "type": [
            "number",
            "null"
          ]
        },
        "hydro_gwh": {
          "type": [
            "number",
            "null"
          ]
        },
        "thermal_gwh": {
          "type": [
            "number",
            "null"
          ]
        },
        "nonconventional_gwh": {
          "type": [
            "number",
            "null"
          ]
        },
        "import_gwh": {
          "type": [
            "number",
            "null"
          ]
        },
        "export_gwh": {
          "type": [
            "number",
            "null"
          ]
        },
        "hydro_share_pct": {
          "type": [
            "number",
            "null"
          ]
        },
        "thermal_share_pct": {
          "type": [
            "number",
            "null"
          ]
        },
        "import_share_pct": {
          "type": [
            "number",
            "null"
          ]
        }
      },
      "required": [
        "date",
        "fetched_at",
        "total_production_gwh",
        "hydro_gwh",
        "thermal_gwh",
        "nonconventional_gwh",
        "import_gwh",
        "export_gwh",
        "hydro_share_pct",
        "thermal_share_pct",
        "import_share_pct"
      ]
    },
    "adequacy": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "origin_date": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        "tier": {
          "type": "string",
          "enum": [
            "holgado",
            "vigilancia",
            "ajustado",
            "deficit"
          ],
          "description": "The model's Spanish word. Kept in schema_version 1; use the *_code field beside it."
        },
        "tier_code": {
          "type": "string",
          "enum": [
            "comfortable",
            "watch",
            "tight",
            "deficit"
          ]
        },
        "tier_label_es": {
          "type": "string"
        },
        "worst_tier": {
          "type": "string",
          "enum": [
            "holgado",
            "vigilancia",
            "ajustado",
            "deficit"
          ],
          "description": "The model's Spanish word. Kept in schema_version 1; use the *_code field beside it."
        },
        "worst_tier_code": {
          "type": "string",
          "enum": [
            "comfortable",
            "watch",
            "tight",
            "deficit"
          ]
        },
        "worst_tier_label_es": {
          "type": "string"
        },
        "worst_tier_horizon_days": {
          "type": "integer"
        },
        "narrative_tier_field": {
          "type": "string",
          "const": "worst_tier",
          "description": "The tier the daily narrative is written about."
        },
        "worst_deficit_gwh_day": {
          "type": "number"
        },
        "run_id": {
          "type": "string"
        }
      },
      "required": [
        "origin_date",
        "tier",
        "tier_code",
        "tier_label_es",
        "worst_tier",
        "worst_tier_code",
        "worst_tier_label_es",
        "worst_tier_horizon_days",
        "narrative_tier_field",
        "worst_deficit_gwh_day",
        "run_id"
      ]
    },
    "deprecated": {
      "$ref": "#/$defs/deprecated"
    },
    "license": {
      "$ref": "#/$defs/license"
    },
    "attribution": {
      "$ref": "#/$defs/attribution"
    },
    "see_also": {
      "$ref": "#/$defs/see_also"
    }
  },
  "$defs": {
    "license": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "const": "MIT"
        },
        "code_url": {
          "type": "string",
          "pattern": "^https?://"
        },
        "data": {
          "type": "string"
        },
        "data_es": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "code_url",
        "data",
        "data_es"
      ]
    },
    "attribution": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "provides": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "pattern": "^https?://"
          },
          "terms": {
            "type": "string"
          },
          "terms_es": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "provides",
          "url",
          "terms",
          "terms_es"
        ]
      }
    },
    "see_also": {
      "type": "object",
      "required": [
        "schema",
        "documentation"
      ],
      "description": "Absolute URLs to the other documents, this document's schema and the documentation page.",
      "additionalProperties": {
        "type": "string",
        "pattern": "^https?://"
      }
    },
    "deprecated": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Fields kept for one more schema version, each with what replaces it."
    },
    "return_period_table": {
      "type": "array",
      "minItems": 6,
      "items": {
        "type": "object",
        "properties": {
          "years": {
            "type": "integer",
            "minimum": 2
          },
          "m3s": {
            "type": "number"
          }
        },
        "required": [
          "years",
          "m3s"
        ]
      },
      "description": "Flow reached on average once every `years` years, m³/s: a method-of-moments Gumbel fit on annual maxima, at 2, 5, 10, 25, 50 and 100 years."
    }
  }
}