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

Authoritative register lifecycle and relation metadata attached to a dated building snapshot. It complements GRB; it does not replace the separate GRB footprint evidence or its QA role.

Gebruik

• stable building object and version identity
• official lifecycle status and geometry method
• aggregate registered building-unit counts by lifecycle status
• aggregate address counts by register status
• classified reconciliation against persisted GRB geometry

Type

Official OGC API Features input, normalized polygon GeoJSON upload and PostGIS vector_features output.

Persisted contract

• dataset_role=reference
• source_name=digitaal_vlaanderen_buildings_addresses_register
• reference_layer_name=building_registry
• temporal_granularity=snapshot
• stable building identity within the register, but no fabricated historical observation between snapshots
• polygon geometry clipped in EPSG:31370 and persisted as EPSG:4326
• selection metrics: exact footprint hectares, building lifecycle counts, unit counts, address-status counts and confirmed GRB match counts

Privacy and semantics

Queryable properties may contain register object ids, lifecycle status, geometry method, aggregate unit/address counts and GRB reconciliation evidence. They must not contain VolledigAdres, Straatnaam, Huisnummer, HuisnummerLabel or Busnummer. Address and unit counts may not be labelled as population, residents, households or dwellings. Building footprint is ground area, not floor area, height or volume.

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

• DTM-maaiveldhoogte in meter TAW
• DSM-oppervlaktehoogte in meter TAW
• reliëf en helling in graden uit geldige rastercellen
• laagste punten als terreinindicator
• gebouwhoogte-inschatting alleen in een latere, gevalideerde DSM-DTM/gebouwketen

Governed product

• Digitaal Vlaanderen DHMV II, DTM/DSM raster 1 m
• WCS coverages DHMVII_DTM_1m en DHMVII_DSM_1m
• EPSG:31370, Float32, nodata -9999, verticale referentie TAW
• opnameperiode 2013-2015
• standaard GeoIntel-analysekopie 5 m, exact geclipt op Area

Waterdiepte, waterinhoud, actuele toestand en afstroming zijn geen directe DHMV-metingen. Zij blijven onbeschikbaar tot een afzonderlijke bron en gevalideerde methode bestaan.

Type

Raster / afgeleid van LiDAR.

Prioriteit

P4 operationeel voor Mol; regionale uitrol volgt dezelfde operatorgrenzen.

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.

BWK and Natura 2000 polygons

The governed state-2025 import uses BWK:Bwkhab polygons. Geometry is fetched in EPSG:4326, validated and clipped against the persisted Mol boundary in EPSG:31370, then persisted in EPSG:4326. Required retained fields include EVAL, EENH1..8, V1..3, HERK, BWKLABEL, HAB1..5, PHAB1..5, HERKHAB, HERKPHAB and HABLEGENDE.

BWK value classes remain independent. Natura 2000 codes, regionally important biotope codes and uncertain ohab knowledge gaps are also independent. PHAB shares can be theoretical source allocations; derived hectares therefore keep an estimate warning, especially for partial rectangle intersections. State 2025 is a product edition and must not be presented as a uniform 2025 field survey or an annual time series.

Annual agricultural-use parcels

Definitive Agentschap Landbouw en Zeevisserij editions from 2008 through 2025 are stored as separate annual vector Datasets. The retained source is the official ZIP archive containing a Belgian Lambert 72 GeoPackage. Queryable geometry is clipped against the persisted Area in EPSG:31370 and normalized to EPSG:4326 before canonical vector_features persistence.

Stable source fields include agpakey, parcel number, declared source area, reference id, spring crop, main crop, official main-crop group, production method and source municipality. All annual source properties remain available, but only maincropgroup_title is normalized to a controlled comparison key. Detailed crop codes and titles can change meaning or wording between editions; their complete annual code list is therefore retained with the source archive.

Historical analysis compares intersected hectares for the complete declaration and official main-crop groups. It must not compare individual parcel lineage: identifiers, boundaries and declarations are not stable between campaign years. The declaration can include water, hedges, buildings and infrastructure, so its total is not a cadastral ownership area or cultivated-crop area.

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