Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add version compatibility documentation #229

Merged
merged 4 commits into from
Jun 17, 2024
Merged

Add version compatibility documentation #229

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1deccc3
First draft of version compatibility documentation
TheNeuralBit Jun 13, 2024
fa2329b
remove trailing space
kylebarron Jun 17, 2024
ca57190
Merge branch 'main' into compatibility
cholmes Jun 17, 2024
3e08708
Adjust language for forward comatibility
TheNeuralBit Jun 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 18 additions & 1 deletion format-specs/geoparquet.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S

## Version and schema

This is version 1.1.0-dev of the GeoParquet specification. See the [JSON Schema](schema.json) to validate metadata for this version.
This is version 1.1.0-dev of the GeoParquet specification. See the [JSON Schema](schema.json) to validate metadata for this version. See [Version Compatibility](#version-compatibility) for details on version compatibility guarantees.

## Geometry columns

Expand Down Expand Up @@ -290,6 +290,23 @@ 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.

## 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 or non-breaking change 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.

Examples of a backwards compatible change include:
- Adding a new field in File or Column Metadata that can be ignored without changing the interpretation of the data (e.g. an index that can improve query performance).
- Adding a new option to an existing field.

Examples of a breaking change include:
- Adding a new field that cannot be ignored without changing the interpretation of the data.
- Changing the default value in an existing field.
- Changing the meaning of an existing field value.

In order to support data written according future minor relases, implementations of this specification:
- SHOULD NOT reject metadata with unknown fields.
- SHOULD explicitly validate all field values they rely on (e.g. an implementation of the 1.0.0 specification should validate enocoding = "WKB" even though it is the only allowed value, as new options might be added).

## File Extension

It is RECOMMENDED to use `.parquet` as the file extension for a GeoParquet file. This provides the best interoperability with existing Parquet tools. The file extension `.geoparquet` SHOULD NOT be used.
Expand Down
Loading