geointel/docs/DATA_SPECIFICATION.md

Data Specification v1.0

1. Principes

GeoIntel werkt documentatiegedreven met expliciete data-contracten.

Elke dataset krijgt:

• bron
• type
• formaat
• CRS
• bounds
• resolutie of schaal
• licentie
• updatefrequentie
• gebruiksdoel
• cache-strategie
• kwaliteitsstatus

2. Kernbronnen

GRB — Basiskaart Vlaanderen

Rol

GRB is een primaire referentiebron voor Vlaanderen. Voor GeoIntel is GRB belangrijker dan OSM wanneer officiële referentiegeometrieën nodig zijn.

Gebruik

• referentiegebouwen
• wegen en terreinobjecten
• QA/QC tegenover AI-detecties
• validatie van gebouwdetectie
• vergelijking met eigen detecties of segmentaties

Type

Vector.

Mogelijke toegang

• WFS per gebied
• downloadpakketten
• periodieke PostGIS-cache

Cache-strategie

Voor V1 is een gebiedsgerichte cache het beste:

1. gebruiker selecteert gebied
2. backend vraagt relevante GRB-lagen op
3. geometrieën worden opgeslagen in PostGIS
4. analysis runs verwijzen naar de gecachete versie

Belangrijk voor QA/QC

GRB-gebouwpolygonen worden gebruikt als ground-truth proxy. Niet absoluut perfect, maar zeer bruikbaar als officiële referentie.

Gebouwenregister

Rol

Aanvullende gebouwinformatie bij geometrieën.

Gebruik

• gebouwmetadata
• identificatie
• status
• koppeling met GRB-gebouwpolygonen indien mogelijk

Type

Vector/API/metadata.

Prioriteit

V2 of V1.5.

OpenStreetMap

Rol

Snelle open referentiedata, nuttig als fallback en voor POI's.

Gebruik

• gebouwen indien GRB nog niet beschikbaar is
• wegen
• water
• landuse
• POI's
• demo- en fallbackdata

Type

Vector.

Toegang

• Overpass API
• pyrosm/osmnx
• lokale extracten

Cache-strategie

Opslaan per project/area in PostGIS.

Sentinel-2

Rol

Remote sensing bron voor vegetatie, water en bebouwingsindices.

Gebruik

• NDVI
• NDWI
• NDBI
• seizoensvergelijking
• trendanalyse
• change detection

Type

Raster multispectral.

Prioriteit

V2.

DHMV / Hoogtemodel Vlaanderen

Rol

Hoogtedata voor terrein- en watergevoeligheidsanalyse.

Gebruik

• DEM
• DSM
• helling
• laagste punten
• hoogteprofiel
• gebouwhoogte-inschatting indien DSM + gebouwpolygonen beschikbaar zijn

Type

Raster / afgeleid van LiDAR.

Prioriteit

V3.

LAS/LAZ LiDAR

Rol

Advanced module voor puntenwolkanalyse.

Gebruik

• puntenwolk metadata
• clipping
• classificatie
• DEM/DSM generatie
• hoogteprofielen

Tools

• PDAL
• laspy

Prioriteit

V4/V5.

3. Dataset Types

Raster

Ondersteund:

• GeoTIFF
• TIFF
• JPEG2000 later
• PNG/JPG met worldfile later

Metadata:

• CRS
• transform
• bounds
• width/height
• band count
• dtype
• nodata
• resolution

Temporal orthophoto rasters additionally require a governed product key, WMS layer, observation label, observed_at, optional valid_from/valid_to, temporal granularity, request/spatial hash, attribution and a limitation that states whether the product is annual, multi-year or merely most recent.

Hydrological station observations

Waterinfo observations are persisted as EPSG:4326 Point features, one station and one observation year per immutable Dataset. Required properties are the station/timeseries identity, measurement type, numeric annual value, reported unit, observation year, provider/owner and attribution. Different station series may not be merged into one area-wide value. Point water level and discharge may not be converted to water volume without governed compatible depth/profile data.

Vector

Ondersteund:

• GeoJSON
• Shapefile
• GPKG
• WFS-resultaten

Metadata:

• CRS
• bounds
• geometry type
• feature count
• attributes
• validity summary

Model outputs

Ondersteund:

• bounding boxes
• polygons
• masks
• confidence scores
• class labels
• source tile reference

4. Data Quality Requirements

Elke dataset moet bij intake minimaal controleren:

• bestand leesbaar
• CRS aanwezig of expliciet onbekend
• geometrieën geldig of herstelbaar
• bounds binnen verwacht gebied
• raster heeft bruikbare resolutie
• geen lege lagen
• opslagpad bestaat

5. Data Lineage

Elke output moet kunnen terugwijzen naar:

• bronbestand
• processing step
• analysis run
• modelversie
• parameters
• tijdstip
• eventuele referentielaag

Sprint 7B Provider Contracts

Sprint 7B makes provider architecture operationally visible without performing live external fetches.

GRB

• provider_name: grb
• authority_level: authoritative
• configured: false
• status: not_configured
• supported_layers: buildings, roads, parcels
• supported_geometry_types: Polygon, MultiPolygon, LineString, MultiLineString
• supported_query_modes: area
• dataset mapping: dataset_role=reference, source_name=grb
• write path: future provider output must flow through DatasetService and VectorFeatureService
• limitation: no live WFS call, no download, no fake GRB data in Sprint 7B

OSM

• provider_name: osm
• authority_level: contextual
• configured: false
• status: not_configured
• supported_layers: buildings, roads, water, landuse
• supported_geometry_types: Polygon, MultiPolygon, LineString, MultiLineString
• supported_query_modes: area
• default dataset mapping: dataset_role=source, source_name=osm
• explicit reference mapping: dataset_role=reference, source_name=osm
• write path: future provider output must flow through DatasetService and VectorFeatureService
• limitation: no live Overpass call, no download, no fake OSM data in Sprint 7B

Manual

• provider_name: manual
• authority_level: manual
• configured: true
• status: configured
• dataset mapping: dataset_role=reference, source_name=manual
• write path: existing dataset upload/reference flow

Fixture

• provider_name: fixture
• authority_level: fixture
• configured: true
• status: configured
• dataset mapping: dataset_role=reference, source_name=fixture
• write path: checked-in demo/test fixture flow