Spec text: allow <authority>:<code> crs in 2.0, mirror Parquet field

cholmes · claude · cholmes · commit d37c4abd4006 · 2026-06-01T10:50:16.000+02:00
Updates the column-metadata table and the crs / crs Parquet property
subsections to:
- permit either inline PROJJSON or an &lt;authority&gt;:&lt;code&gt; string,
- disallow srid:&lt;id&gt; and projjson:&lt;key&gt; on the writer side,
- preserve the reader SHOULD-tolerate language for the disallowed forms,
- require the GeoParquet column-metadata crs and the Parquet
  logical-type crs to mirror each other exactly,
- document the null/no-CRS corner case explicitly,
- note that authority-code OGC:CRS84 / EPSG:4326 are equivalent to
  OGC:CRS84 in §OGC:CRS84 details.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/format-specs/geoparquet.md b/format-specs/geoparquet.md
@@ -49,7 +49,7 @@ Each geometry column in the dataset MUST be included in the `columns` field abov
 | -------------- | ------------ | ----------- |
 | encoding       | string       | **REQUIRED.** Name of the geometry encoding format. Only `"WKB"` is supported. |
 | geometry_types | \[string]    | **REQUIRED.** The geometry types of all geometries, or an empty array if they are not known. |
-| crs            | object\|null | [PROJJSON](https://proj.org/specifications/projjson.html) object representing the Coordinate Reference System (CRS) of the geometry. If the field is not provided, the default CRS is [OGC:CRS84](https://www.opengis.net/def/crs/OGC/1.3/CRS84), which means the data in this column must be stored in longitude, latitude based on the WGS84 datum. |
+| crs            | object\|string\|null | [PROJJSON](https://proj.org/specifications/projjson.html) object, or an `<authority>:<code>` string (e.g. `"EPSG:4326"`), representing the Coordinate Reference System (CRS) of the geometry. The value MUST equal the Parquet logical-type `crs` property in the same form. If the field is not provided, the default CRS is [OGC:CRS84](https://www.opengis.net/def/crs/OGC/1.3/CRS84), which means the data in this column must be stored in longitude, latitude based on the WGS84 datum. |
 | orientation    | string       | Winding order of exterior ring of polygons. If present must be `"counterclockwise"`; interior rings are wound in opposite order. If absent, no assertions are made regarding the winding order. |
 | edges          | string       | Describes how to interpret the edges of the geometries. Must be one of `planar`, `spherical`, `vincenty`, `thomas`, `andoyer`, `karney`. The default value is `planar`.
 | bbox           | \[number]    | Bounding Box of the geometries in the file, formatted according to [RFC 7946, section 5](https://tools.ietf.org/html/rfc7946#section-5). |
@@ -59,27 +59,49 @@ Each geometry column in the dataset MUST be included in the `columns` field abov
 
 The Coordinate Reference System (CRS) is an optional parameter for each geometry column defined in GeoParquet format.
 
-The CRS MUST be provided in [PROJJSON](https://proj.org/specifications/projjson.html) format, which is a JSON encoding of [WKT2:2019 / ISO-19162:2019](https://docs.opengeospatial.org/is/18-010r7/18-010r7.html), which itself implements the model of [OGC Topic 2: Referencing by coordinates abstract specification / ISO-19111:2019](http://docs.opengeospatial.org/as/18-005r4/18-005r4.html). Apart from the difference of encodings, the semantics are intended to match WKT2:2019, and a CRS in one encoding can generally be represented in the other.
+In GeoParquet 2.0 the CRS is carried both on the Parquet `GEOMETRY`/`GEOGRAPHY` logical type's `crs` property and (mirrored) on the GeoParquet column-metadata `crs` field. The two MUST be equal and MUST be in the same form.
 
-If the `crs` key does not exist, all coordinates in the geometries MUST use longitude, latitude based on the WGS84 datum, and the default value is [OGC:CRS84](https://www.opengis.net/def/crs/OGC/1.3/CRS84) for CRS-aware implementations. Note that a missing `crs` key has different meaning than a `crs` key set to `null` (see below).
+The CRS MAY be expressed in one of two forms:
 
-[OGC:CRS84](https://www.opengis.net/def/crs/OGC/1.3/CRS84) is equivalent to the well-known [EPSG:4326](https://epsg.org/crs_4326/WGS-84.html) but changes the axis from latitude-longitude to longitude-latitude.
+1. **Inline [PROJJSON](https://proj.org/specifications/projjson.html)** — a complete CRS definition, which is a JSON encoding of [WKT2:2019 / ISO-19162:2019](https://docs.opengeospatial.org/is/18-010r7/18-010r7.html), itself implementing the model of [OGC Topic 2: Referencing by coordinates abstract specification / ISO-19111:2019](http://docs.opengeospatial.org/as/18-005r4/18-005r4.html). This is the canonical form.
+2. **An `<authority>:<code>` string** — e.g. `"OGC:CRS84"`, `"EPSG:4326"`, `"EPSG:3857"`, `"IGNF:ATI"`. The authority and code MUST be one published by a recognized CRS authority (well-known authorities include OGC, EPSG, ESRI, and IGNF; see <https://spatialreference.org/> for an index).
 
-See below for additional details about representing or identifying OGC:CRS84.
+If the `crs` key does not exist, all coordinates in the geometries MUST use longitude, latitude based on the WGS84 datum, and the default value is [OGC:CRS84](https://www.opengis.net/def/crs/OGC/1.3/CRS84) for CRS-aware implementations. Note that a missing `crs` key has different meaning than a `crs` key set to `null` (see below).
 
-The value of this key may be explicitly set to `null` to indicate that there is no CRS assigned to this column (CRS is undefined or unknown).
+[OGC:CRS84](https://www.opengis.net/def/crs/OGC/1.3/CRS84) is equivalent to the well-known [EPSG:4326](https://epsg.org/crs_4326/WGS-84.html) but changes the axis from latitude-longitude to longitude-latitude. See below for additional details about representing or identifying OGC:CRS84, including when it arrives as an `<authority>:<code>` string rather than as PROJJSON.
 
-The `crs` field of GeoParquet MUST reflect the crs of the Parquet `crs` property on the GEOMETRY or GEOGRAPHY logical type.
+The value of this key may be explicitly set to `null` to indicate that there is no CRS assigned to this column (CRS is undefined or unknown). Because the Parquet core specification has no native way to express "no CRS" (an absent Parquet `crs` defaults to OGC:CRS84), a writer that sets the GeoParquet column-metadata `crs` to `null` MUST omit the Parquet logical-type `crs` property; the GeoParquet `null` is authoritative and overrides Parquet's default-to-OGC:CRS84 interpretation in this case.
 
 ##### `crs` Parquet property
 
-The Parquet Geospatial definitions have a [crs customization](https://github.com/apache/parquet-format/blob/apache-parquet-format-2.12.0/Geospatial.md#crs-customization) section
-that gives flexibility for how to specify the crs.
+The Parquet Geospatial definitions have a [crs customization](https://github.com/apache/parquet-format/blob/apache-parquet-format-2.12.0/Geospatial.md#crs-customization) section that permits four forms: inline PROJJSON, `<authority>:<code>`, `srid:<identifier>`, and `projjson:<key_name>`.
+
+GeoParquet 2.0 is more restrictive:
+
+- A GeoParquet 2.0 writer MUST use one of:
+  - inline PROJJSON, or
+  - an `<authority>:<code>` string.
+- A GeoParquet 2.0 writer MUST NOT use `srid:<identifier>` (no authority context; ambiguous across systems) or `projjson:<key_name>` (indirect reference via another metadata key; no ergonomic benefit over inline PROJJSON).
+- A GeoParquet 2.0 writer SHOULD prefer inline PROJJSON. It is self-describing, requires no external CRS registry, and matches the GeoParquet 1.x convention.
+- A GeoParquet 2.0 writer MAY use `<authority>:<code>` when:
+  - the CRS is precisely identified by a well-known authority entry, AND
+  - the writing environment lacks a PROJJSON generator (e.g., pure-SQL pipelines, lightweight browser-side writers), OR
+  - reducing per-file metadata size is desirable (e.g., very many very small files).
 
-The GeoParquet 2.0 specification gives less flexibility. To comply with
-GeoParquet 2.0 if there is a non-default crs then the crs field in the Parquet geometry or geography type MUST be an in-line projjson representation of the crs. This is allowed by the Parquet specification, though it is not explicitly articulated.
+A GeoParquet 2.0 reader MUST handle both writer-permitted forms (inline PROJJSON and `<authority>:<code>`).
 
-Readers of geospatial Parquet data SHOULD try to parse other crs representations in the Parquet metadata.
+Readers of geospatial Parquet data SHOULD additionally try to parse the other Parquet-core `crs` representations (`srid:<identifier>` and `projjson:<key_name>`) when encountered. Such files are not conformant GeoParquet 2.0, but supporting them improves interoperability with the broader Parquet geospatial ecosystem.
+
+The GeoParquet column-metadata `crs` field and the Parquet logical-type `crs` property MUST mirror each other exactly:
+
+| Parquet logical-type `crs`              | GeoParquet column-metadata `crs`           | Meaning                                       |
+| --------------------------------------- | ------------------------------------------ | --------------------------------------------- |
+| absent (Parquet default)                | absent                                     | OGC:CRS84                                     |
+| inline PROJJSON object                  | the same inline PROJJSON object            | CRS fully described in metadata               |
+| `<authority>:<code>` string             | the same `<authority>:<code>` string       | CRS identified by authority code              |
+| absent (writer signaling "no CRS")      | `null`                                     | CRS explicitly undefined / unknown            |
+
+The two fields MUST NOT disagree in form (one being PROJJSON while the other is `<authority>:<code>`) or in value.
 
 #### epoch
 
@@ -232,6 +254,8 @@ It is reasonable for implementations to require that one of the above `id` eleme
 
 Note: EPSG:4326 and OGC:CRS84 are equivalent with respect to this specification because this specification specifically overrides the coordinate axis order in the `crs` to be longitude-latitude.
 
+When the CRS arrives in the `<authority>:<code>` form, the values `"OGC:CRS84"` and `"EPSG:4326"` are likewise equivalent to OGC:CRS84 for the purposes of this specification.
+
 ## Version Compatibility
 
 GeoParquet version numbers follow [SemVer](https://semver.org), meaning patch releases are for bugfixes, minor releases represent backwards compatible changes, and major releases represent breaking changes. For this specification, a backwards compatible change means that a file written with the older specification will always be compatible with the newer specification. Minor releases are also guaranteed to be forward compatible up the the next major release. Forward compatiblity means that an implementation that is only aware of the older specification MUST be able to correctly interpret data written according to the newer specification, OR recognize that it cannot correctly interpret that data.
