GeoParquet 1.1 vs 2.0 RC: Geometry Types, Metadata, and Validation

GeoParquet is Parquet plus a geospatial contract: it tells readers which columns contain geometry, how the bytes are encoded, which coordinate reference system applies, and what geometry types and bounds are claimed. That contract is what makes a geometry column interoperable; a BLOB that happens to contain WKB is not automatically a valid GeoParquet file.

The version matters. As of August 21, 2026, 1.1.0+p1 is the latest non-prerelease stable line. The main specification document identifies itself as 2.0.0, while the latest packaged 2.0 release is v2.0.0-rc.1 and is explicitly labeled a release candidate. Treat the 2.0 ecosystem as pre-final until the project publishes a non-RC release, and check the exact writer and reader versions you target.

What changed from 1.x to 2.0#

The current GeoParquet 2.0 specification document (opens in a new tab) requires root-level geometry columns and describes the GEOMETRY/GEOGRAPHY logical types. The project releases page (opens in a new tab) is the source for what is actually released. That distinction is more useful than treating “GeoParquet” as one timeless layout.

The 2.0 direction does not make every spatial query fast. Row-group bounding boxes help only when the writer emits useful statistics, the reader uses them, the query can exploit them, and the data is spatially ordered enough for row groups to have selective bounds. The project’s distribution guidance (opens in a new tab) calls out those conditions.

The minimum metadata you should understand#

In the 1.x family, the Parquet file metadata contains a UTF-8 JSON value under the geo key. Important fields include:

• specification version;
• the primary geometry column;
• every geometry column by name;
• encoding, commonly WKB in 1.x;
• geometry types;
• CRS as PROJJSON, null, or the version’s documented default;
• optional bounds and covering information.

In the current 2.0 document, the Parquet GEOMETRY or GEOGRAPHY logical type carries geospatial meaning, while conformant GeoParquet metadata supplies the additional specification-level contract. A writer may emit native Parquet geospatial types without that metadata, but the document says such a file is readable by a 2.0 reader rather than conformant GeoParquet 2.0. When both places describe CRS or geometry, they must agree.

Axis order is easy to mishandle. GeoParquet WKB uses x, y — normally longitude/easting, then latitude/northing — even when a CRS authority definition uses another axis order. Any area or distance result is suspect until the CRS and units are explicit.

Reproduce a five-row reader check#

The GeoParquet project publishes a tiny official example.parquet (opens in a new tab). The copy recorded in viewparquet’s public-dataset catalog was fully downloaded and decoded on June 12, 2026, then probed again on August 19. At full verification it had five rows and these six columns:

• pop_est
• continent
• name
• iso_a3
• gdp_md_est
• geometry

Download it, open it in the GeoParquet table inspector, and run:

SELECT count(*) AS rows FROM data;

The expected result for that verified file is:

Then sample only attributes:

SELECT name, continent, pop_est
FROM data
ORDER BY name;

This confirms that the current reader can open the table and query attributes. It does not validate GeoParquet metadata, decode every geometry, confirm the CRS, or prove compliance with the current development spec.

Inspect footer metadata in native DuckDB#

For a downloaded file:

DESCRIBE SELECT * FROM read_parquet('example.parquet');
 
SELECT *
FROM parquet_kv_metadata('example.parquet')
WHERE key = 'geo';

DESCRIBE shows the type exposed by that DuckDB version. parquet_kv_metadata exposes the raw key/value metadata so you can confirm a geo entry exists. You still need to parse the JSON and validate its required fields against the matching specification version.

Also inspect the physical schema:

SELECT
  file_name,
  name,
  type,
  logical_type
FROM parquet_schema('example.parquet')
WHERE name IS NOT NULL
ORDER BY name;

A 1.x file may expose geometry as BLOB/WKB. A 2.0-capable reader may expose the native logical type as GEOMETRY or GEOGRAPHY. Do not apply ST_GeomFromWKB blindly to a column already decoded as GEOMETRY.

Validate; do not infer validity from “it opened”#

The GeoParquet project recommends GeoParquet-aware validators. With GPQ (opens in a new tab), the documented command is:

gpq validate example.parquet

Another current option is the geoparquet-io check command (opens in a new tab). A useful validation report should cover more than JSON shape:

• metadata version and required fields;
• primary column and declared geometry columns;
• encoding and physical/logical type agreement;
• actual versus declared geometry types;
• CRS and coordinate bounds;
• null/empty geometry policy;
• row-level bbox covering claims for 1.1 when used;
• readable footer and geometry values.

Opening a file in a general Parquet reader proves only reader compatibility. viewparquet currently shows attribute columns, DuckDB types, raw geometry values, and SQL results; it does not load the spatial extension, render a map, or issue a GeoParquet validation certificate.

GeoParquet versus other common files#

Avoid absolute “smaller and faster” claims. Results depend on data, encoding, compression, spatial ordering, indexes, and workload.

Measure with the same source features and workload. Record writer versions, CRS, geometry validity policy, compression, row-group layout, spatial ordering, file size, query plan, and wall-clock distribution. Comparing an uncompressed GeoJSON export with a carefully sorted Zstandard GeoParquet file is not a neutral format benchmark.

Write for distribution, not just local success#

Before publishing:

1. Choose a released GeoParquet version that all required consumers support.
2. Preserve a stable feature identifier outside the geometry.
3. Normalize or explicitly record the CRS.
4. Validate geometry values and specification metadata.
5. Choose row groups based on actual scan and filter workloads.
6. Spatially order features if row-group bounds should prune by area.
7. Store immutable objects and publish checksums.
8. Add a STAC Collection or other catalog record when discoverability matters.
9. Test at least two independent readers.
10. Publish the validator and compatibility results beside the dataset.

The official distribution guide recommends .parquet, not .geoparquet, for interoperability and the media type application/vnd.apache.parquet when one is supplied.

A sensible inspection sequence#

Use the GeoParquet viewer page for quick table inspection, the DuckDB spatial SQL guide when you need geometry functions in native DuckDB, and the verified public datasets guide for the exact sample and verification caveats.

The sequence is:

• identify the specification version;
• inspect physical and logical schema;
• parse geo metadata;
• validate with a GeoParquet-aware tool;
• run attribute checks;
• load geometry with the correct reader path;
• verify CRS and units before spatial calculations;
• benchmark the actual query rather than repeating format folklore.

Primary references#

• GeoParquet stable repository and validation guidance (opens in a new tab)
• GeoParquet 2.0 specification document (opens in a new tab)
• GeoParquet releases (opens in a new tab)
• Best practices for distributing GeoParquet (opens in a new tab)
• Apache Parquet geospatial logical types (opens in a new tab)