{
  "openapi": "3.1.0",
  "info": {
    "title": "HIWAS API",
    "version": "0.1.0",
    "description": "Hybrid Intelligent Water Allocation System — public API. OGC SensorThings API v1.1 (INSPIRE-compatible) + HIWAS-specific endpoints. Patent FR2510508. Inventor: Nizar Younes Mqam.",
    "contact": {"name": "HIWAS", "email": "contact@maramm.org", "url": "https://hiwas.eu"},
    "license": {"name": "Proprietary — Patent FR2510508", "url": "https://hiwas.eu/#patent-fr2510508"},
    "x-logo": {"url": "https://hiwas.eu/icon-192.png"}
  },
  "externalDocs": {"description": "OGC SensorThings API Specification", "url": "https://docs.ogc.org/is/18-088/18-088.html"},
  "servers": [
    {"url": "https://hiwas.eu", "description": "HIWAS Production VPS"},
    {"url": "https://hiwas.eu/sta/v1.1", "description": "OGC SensorThings API v1.1 root"}
  ],
  "paths": {
    "/sta/v1.1/": {
      "get": {
        "summary": "OGC SensorThings API root",
        "description": "Returns available entity set URLs (Things, Locations, HistoricalLocations, Datastreams, Sensors, ObservedProperties, Observations, FeaturesOfInterest)",
        "operationId": "getApiRoot",
        "tags": ["OGC SensorThings"],
        "responses": {"200": {"description": "API root with entity set list"}}
      }
    },
    "/sta/v1.1/Things": {
      "get": {
        "summary": "List all Things (water basins)",
        "description": "Returns all monitored water basins. Each Thing represents one river basin with its properties (name, location, regulatory framework, risk index R). Supports $filter, $top, $skip, $orderby, $select, $expand OGC query params.",
        "operationId": "listThings",
        "tags": ["OGC SensorThings"],
        "parameters": [
          {"name": "$filter", "in": "query", "description": "OData filter expression. E.g. $filter=name eq 'bassin-loire-amont'", "schema": {"type": "string"}},
          {"name": "$top", "in": "query", "description": "Max results to return", "schema": {"type": "integer", "default": 100}},
          {"name": "$skip", "in": "query", "description": "Results to skip (pagination)", "schema": {"type": "integer"}},
          {"name": "$expand", "in": "query", "description": "Expand related entities. E.g. $expand=Datastreams", "schema": {"type": "string"}}
        ],
        "responses": {"200": {"description": "Array of basin Things"}}
      }
    },
    "/sta/v1.1/Things('{id}')": {
      "get": {
        "summary": "Get a single basin by ID",
        "description": "Returns a single water basin Thing. Known IDs: bassin-loire-amont, bassin-med-sud, bassin-oum-er-rbia, bassin-gila-arizona.",
        "operationId": "getThingById",
        "tags": ["OGC SensorThings"],
        "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string", "enum": ["bassin-loire-amont", "bassin-med-sud", "bassin-oum-er-rbia", "bassin-gila-arizona"]}}],
        "responses": {"200": {"description": "Basin Thing object"}, "404": {"description": "Basin not found"}}
      }
    },
    "/sta/v1.1/Observations": {
      "get": {
        "summary": "List all sensor observations",
        "description": "Returns observed water allocation measurements. Each observation records: result (metric value), phenomenonTime (measurement time), resultTime, and links to its Datastream.",
        "operationId": "listObservations",
        "tags": ["OGC SensorThings"],
        "parameters": [
          {"name": "$filter", "in": "query", "schema": {"type": "string"}},
          {"name": "$top", "in": "query", "schema": {"type": "integer", "default": 100}},
          {"name": "$orderby", "in": "query", "schema": {"type": "string"}},
          {"name": "$count", "in": "query", "description": "Include @iot.count in response", "schema": {"type": "boolean"}}
        ],
        "responses": {"200": {"description": "Array of Observations"}}
      }
    },
    "/sta/v1.1/Datastreams": {
      "get": {
        "summary": "List all Datastreams",
        "description": "Returns all data streams. Each Datastream connects a Thing (basin) to an ObservedProperty (e.g. volume_alloue_m3, R, HCI) via a Sensor.",
        "operationId": "listDatastreams",
        "tags": ["OGC SensorThings"],
        "parameters": [
          {"name": "$filter", "in": "query", "schema": {"type": "string"}},
          {"name": "$expand", "in": "query", "schema": {"type": "string"}}
        ],
        "responses": {"200": {"description": "Array of Datastreams"}}
      }
    },
    "/api/v1/health": {
      "get": {
        "summary": "API health check",
        "description": "Returns pipeline health status, DB connectivity, Redis status, and last allocation cycle timestamps per basin.",
        "operationId": "healthCheck",
        "tags": ["HIWAS API"],
        "responses": {"200": {"description": "Health status object"}}
      }
    },
    "/api/v1/tues/{tue_id}/card": {
      "get": {
        "summary": "TUE certificate public card",
        "description": "Returns the public HTML card for a Water Use Certificate (TUE). Shows allocated volume, risk R, ESG score, HCI, validity period, and QR-verifiable JWS signature.",
        "operationId": "getTueCard",
        "tags": ["HIWAS API"],
        "parameters": [{"name": "tue_id", "in": "path", "required": true, "schema": {"type": "string"}}],
        "responses": {"200": {"description": "TUE HTML card"}, "404": {"description": "TUE not found"}}
      }
    }
  },
  "tags": [
    {"name": "OGC SensorThings", "description": "OGC SensorThings API v1.1 — INSPIRE-compatible water data endpoints"},
    {"name": "HIWAS API", "description": "HIWAS-specific endpoints for TUE certificates and system health"}
  ],
  "x-hiwas-concepts": {
    "TUE": "Titre d'Usage d'Eau — cryptographically-signed water use certificate (JWS/ECDSA)",
    "CEEau": "Certificat d'Économie d'Eau — water savings certificate (non-monetary)",
    "HCI": "Hydro-Confidence Index ∈ [0,1] — data quality score from multi-source reconciliation",
    "R": "Composite Risk Index = w1·R_clim + w2·R_sys + w3·R_qual + w4·R_hydro",
    "ESG": "Per-user ESG composite = Autonomy × Durability × Precedent"
  }
}