GeoParquet 2.0 CRS: PROJJSON in geo metadata, flexible native Parquet crs, srid:0 for unknown

[cholmes]

Encodes the GeoParquet 2.0 CRS decisions reached on the June 1 community call. This supersedes the two exploratory PRs it grew out of:

• GeoParquet 2.0: allow <authority>:<code> CRS in addition to inline PROJJSON #284 (allow <authority>:<code> in the GeoParquet metadata crs) — the call leaned the other way: keep the GeoParquet metadata crs as inline PROJJSON, and instead allow the flexible forms on the native Parquet crs property.
• GeoParquet 2.0: discuss removing null from the crs field #285 (remove null from the crs field) — the call decided to keep null for backwards compatibility, and map it to srid:0 on the Parquet side.

This PR keeps the structure and explanations that #284 introduced (it's a nice approach), but reframes them around the decisions below. It is a docs-only change — schema.json and the schema tests are unchanged from main (crs stays object|null).

Decisions encoded

1. The GeoParquet geo metadata crs is PROJJSON; the native Parquet crs can be any form

The spec now clearly separates the two crs fields:

• GeoParquet column-metadata crs field — MUST be inline PROJJSON (or null). Writing geo metadata is itself optional (a writer may emit only the native Parquet geospatial types), but any file that does carry GeoParquet metadata states its CRS as inline PROJJSON there. This is the key guarantee: a reader of the GeoParquet metadata can always obtain a complete CRS definition directly, without resolving an authority code against an external registry.
• Native Parquet crs property (on the GEOMETRY/GEOGRAPHY logical type) — the source of truth, and not restricted by GeoParquet. It MAY use any Parquet-core form: inline PROJJSON, <authority>:<code>, srid:<identifier>, or projjson:<key_name>.
  • Writers SHOULD use inline PROJJSON or <authority>:<code>; <authority>:<code> is RECOMMENDED for writers that can't readily generate PROJJSON (pure-SQL pipelines, browser-side writers).
  • A writer that can't generate PROJJSON is encouraged to just write plain native Parquet geo with an <authority>:<code> crs and omit GeoParquet metadata. Such a file isn't conformant GeoParquet 2.0, but any GeoParquet reader should still read it.
• Readers MUST interpret both inline PROJJSON and <authority>:<code> in the native Parquet crs property, and SHOULD additionally tolerate srid:<identifier> / projjson:<key_name>.

Spec framing: producing the native Parquet geospatial types is the foundation of GeoParquet 2.0 and what every writer should do; the GeoParquet geo metadata is the optional, more-explicit layer on top.

2. null (unknown / undefined CRS) is kept, and maps to srid:0

• The GeoParquet column-metadata crs MAY still be null to mean "CRS undefined or unknown" (kept for 1.x compatibility — real use cases include local/engineering coordinates and legacy data).
• When the GeoParquet crs is null, the native Parquet crs property SHOULD be set to srid:0. The Parquet core spec mentions the srid:<identifier> form but assigns no meaning to 0; GeoParquet 2.0 adopts srid:0 to mean undefined/unknown CRS, following the GeoPackage convention discussed on the call.

Mirroring table (from the new spec text)

Parquet logical-type crs	GeoParquet column-metadata crs	Meaning
absent (Parquet default)	absent	OGC:CRS84
inline PROJJSON object	the same CRS as inline PROJJSON	CRS fully described in metadata
<authority>:<code> string	the resolved CRS as inline PROJJSON	CRS identified by an authority code
srid:0	null	CRS undefined or unknown

Changes

• format-specs/geoparquet.md:
  • Column-metadata crs row clarified (object|null; PROJJSON or null; must describe the same CRS as the native Parquet property).
  • §crs rewritten: the GeoParquet field is the inline-PROJJSON restatement; native Parquet property is the source of truth and may use other forms; null → srid:0.
  • §crs Parquet property rewritten: explicitly scoped to the native Parquet property; native types are primary/recommended; writer MAY use any Parquet form (<authority>:<code> recommended when not inlining PROJJSON); writers that can't do PROJJSON should write plain native Parquet and omit geo metadata; reader MUST/SHOULD rules; srid:0 for unknown; mirroring table.
  • OGC:CRS84 details: note that <authority>:<code> OGC:CRS84 and EPSG:4326 are equivalent to OGC:CRS84.
• schema.json, scripts/test_json_schema.py: no change (already object|null on main).

Test results

47 passed  (test_json_schema.py)
62 passed  (full scripts/ test suite)

🤖 Generated with Claude Code

[paleolimbot]

Others should have a look as well, but this looks good to me. It preserves the ability of existing metadata parsers to parse a CRS, and also gives practical advice nudging people towards the subset of values allowed by the Parquet spec that they should actually be using.