Design decisions
The decisions behind CityParquet, each with the alternatives considered and the trade-off accepted.
This section records why CityParquet is designed the way it is. The Specification records what the format is; where the two overlap, the specification is authoritative on the what and this section explains the reasoning. Prior art weighed throughout: PostGIS, GeoParquet, Apache Iceberg, and 3DCityDB.
How to read a decision
Each decision follows the same shape:
- Decision — the one-line resolution.
- Alternatives considered — the options weighed, so the choice is positioned.
- Why this — the reasoning that selected it.
- Trade-off — the cost knowingly accepted.
- Status — decided or open.
Open items link to Open questions.
A · Table & schema strategy
One object per row; typed attribute columns; addresses.
B · Geometry encoding
WKB geometry, parallel property columns, one column per LoD, encode-time transform.
C · Spatial access
The bbox column and Hilbert ordering.
D · Appearance & shared resources
Geometry/appearance separation and shared-resource sidecars.
E · Files, CRS & metadata
The file package, one CRS per file, dataset metadata.
F · Extensions
How ADEs and CityJSON Extensions are encoded.
G · Bloom filters
Filters on the identifiers, placed after the last row group.