feat: Districts table and geojson stub

api/openapi.yaml

@@ -251,6 +251,72 @@ paths:
         "400": { $ref: "#/components/responses/BadRequest" }
         "404": { $ref: "#/components/responses/NotFound" }
 
+  /datasets/{id}.geojson:
+    parameters:
+      - $ref: "#/components/parameters/IdParam"
+    get:
+      tags: [Datasets]
+      summary: Get a dataset as GeoJSON (vector / vector_with_kato)
+      description: |
+        Assembles a GeoJSON `FeatureCollection` (RFC 7946) from the dataset.
+
+        A plain `vector` dataset has no KATO mapping or observations, so the
+        result is a single Feature wrapping the dataset's own (dissolved)
+        geometry. Its extracted attribute table (e.g. a GeoPackage's table data,
+        stored in `properties`) is exposed as the Feature's top-level properties:
+        a single row becomes the properties object directly, multiple rows are
+        kept under a `rows` key. An empty collection is returned when the dataset
+        has no geometry.
+
+        A `vector_with_kato` dataset is built from its observations. When it has
+        its own (dissolved) geometry, the observations are taken to describe that
+        whole geometry: a single Feature wraps it, and its properties hold only
+        the observations, keyed by KATO code at the top level (each KATO mapping
+        to its date->value pairs). Otherwise one Feature is emitted per KATO, its
+        boundary taken from the `districts` table and the per-year values
+        flattened into the Feature's properties keyed by date; KATO codes with
+        no matching district are skipped.
+
+        Only `ready` datasets are served: a dataset still being processed
+        returns 409. Other file types (e.g. `raster`) return 422.
+      responses:
+        "200":
+          description: The dataset as a GeoJSON FeatureCollection
+          content:
+            application/geo+json:
+              schema: { $ref: "#/components/schemas/GeoJSONFeatureCollection" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "404": { $ref: "#/components/responses/NotFound" }
+        "409": { $ref: "#/components/responses/Conflict" }
+        "422": { $ref: "#/components/responses/ValidationError" }
+
+  /datasets/{id}.kato.geojson:
+    parameters:
+      - $ref: "#/components/parameters/IdParam"
+    get:
+      tags: [Datasets]
+      summary: Get a dataset as district-joined GeoJSON (vector_with_kato)
+      description: |
+        Like `/datasets/{id}.geojson`, but ignores any geometry the dataset
+        carries and always joins the `districts` table on KATO code: one Feature
+        is emitted per KATO, its boundary taken from the matching district and
+        the per-year observation values mapped into the Feature's properties
+        keyed by date (alongside `kato` and `name`). KATO codes with no matching
+        district are skipped.
+
+        Only `ready` datasets are served: a dataset still being processed
+        returns 409. Other file types return 422.
+      responses:
+        "200":
+          description: The dataset as a district-joined GeoJSON FeatureCollection
+          content:
+            application/geo+json:
+              schema: { $ref: "#/components/schemas/GeoJSONFeatureCollection" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "404": { $ref: "#/components/responses/NotFound" }
+        "409": { $ref: "#/components/responses/Conflict" }
+        "422": { $ref: "#/components/responses/ValidationError" }
+
   /datasets/{id}/status:
     parameters:
       - $ref: "#/components/parameters/IdParam"
@@ -516,6 +582,39 @@ components:
           type: string
         coordinates: true
 
+    GeoJSONFeature:
+      type: object
+      description: A GeoJSON Feature (RFC 7946).
+      required: [type, geometry, properties]
+      properties:
+        type:
+          type: string
+          enum: [Feature]
+        geometry:
+          $ref: "#/components/schemas/GeoJSONGeometry"
+        properties:
+          type: [object, "null"]
+          description: |
+            Arbitrary key/value map. For per-KATO features (no dataset geometry)
+            this holds `kato`, `name`, and one entry per mapped year keyed by
+            date (YYYY-MM-DD). For the single-feature case (dataset has its own
+            geometry) it holds only the observations, keyed by KATO code, each
+            mapping to its date->value pairs.
+          additionalProperties: true
+
+    GeoJSONFeatureCollection:
+      type: object
+      description: A GeoJSON FeatureCollection (RFC 7946).
+      required: [type, features]
+      properties:
+        type:
+          type: string
+          enum: [FeatureCollection]
+        features:
+          type: array
+          items:
+            $ref: "#/components/schemas/GeoJSONFeature"
+
     DatasetSummary:
       type: object
       required: [id, category_id, name, file_type, size_bytes, status, created_at, updated_at]