geointel/docs/17-max-prep/M9_DATA_CONTRACTS_DETAILED.md

M9 Detailed Data Contracts

Project

{
  "id": "uuid",
  "name": "Geel Building Detection Demo",
  "description": "Building detection and QA against reference features.",
  "region": "Kempen",
  "created_at": "2026-06-11T12:00:00Z",
  "updated_at": "2026-06-11T12:00:00Z"
}

Validation:

• name is required,
• region defaults to Kempen,
• description optional.

Area

{
  "id": "uuid",
  "project_id": "uuid",
  "name": "Geel center test area",
  "geometry": { "type": "Polygon", "coordinates": [] },
  "crs": "EPSG:4326",
  "area_m2": 12345.67,
  "bounds": [4.98, 51.15, 5.02, 51.18]
}

Validation:

• geometry must be Polygon or MultiPolygon,
• geometry must be valid,
• geometry must not be empty,
• area_m2 must be computed server-side,
• CRS is EPSG:4326 for API IO unless explicitly documented.

Dataset

{
  "id": "uuid",
  "project_id": "uuid",
  "name": "reference_buildings.geojson",
  "dataset_type": "vector",
  "source_mode": "demo",
  "source_name": "fixture",
  "storage_path": "storage/projects/.../raw/reference_buildings.geojson",
  "status": "uploaded|processing|ready|failed",
  "crs": "EPSG:4326",
  "bounds": [4.98, 51.15, 5.02, 51.18],
  "feature_count": 100,
  "metadata": {}
}

Analysis Run

{
  "id": "uuid",
  "project_id": "uuid",
  "area_id": "uuid",
  "analysis_type": "object_detection|segmentation|qaqc|raster_metadata|vector_metadata",
  "status": "queued|running|completed|failed|cancelled",
  "parameters": {},
  "started_at": null,
  "finished_at": null,
  "error": null
}

Detection Feature

{
  "id": "uuid",
  "analysis_run_id": "uuid",
  "class_name": "building",
  "confidence": 0.91,
  "geometry": { "type": "Polygon", "coordinates": [] },
  "bbox": [4.99, 51.16, 4.991, 51.161],
  "source_tile": "tile_001.tif",
  "metadata": {}
}

QA/QC Result

{
  "analysis_run_id": "uuid",
  "reference_dataset_id": "uuid",
  "predicted_dataset_id": "uuid",
  "match_threshold_iou": 0.5,
  "precision": 0.94,
  "recall": 0.91,
  "f1": 0.925,
  "true_positives": 94,
  "false_positives": 6,
  "false_negatives": 9,
  "findings": []
}