From 1deccc32a3ac5de32684ffd19d4ac24c2e45232c Mon Sep 17 00:00:00 2001 From: Brian Hulette Date: Thu, 13 Jun 2024 10:15:16 -0700 Subject: [PATCH 1/3] First draft of version compatibility documentation --- format-specs/geoparquet.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/format-specs/geoparquet.md b/format-specs/geoparquet.md index 3126675..fabae26 100644 --- a/format-specs/geoparquet.md +++ b/format-specs/geoparquet.md @@ -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 @@ -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. From fa2329b913e4db2f4b9424c665ee71e24887919b Mon Sep 17 00:00:00 2001 From: Kyle Barron Date: Mon, 17 Jun 2024 11:25:52 -0400 Subject: [PATCH 2/3] remove trailing space --- format-specs/geoparquet.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/format-specs/geoparquet.md b/format-specs/geoparquet.md index fabae26..d2686b4 100644 --- a/format-specs/geoparquet.md +++ b/format-specs/geoparquet.md @@ -292,7 +292,7 @@ Note: EPSG:4326 and OGC:CRS84 are equivalent with respect to 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 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. +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). From 3e0870889f21d99ba18ea900401ad3b0237e436d Mon Sep 17 00:00:00 2001 From: Brian Hulette Date: Mon, 17 Jun 2024 12:12:12 -0700 Subject: [PATCH 3/3] Adjust language for forward comatibility --- format-specs/geoparquet.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/format-specs/geoparquet.md b/format-specs/geoparquet.md index d2686b4..002a760 100644 --- a/format-specs/geoparquet.md +++ b/format-specs/geoparquet.md @@ -292,9 +292,9 @@ Note: EPSG:4326 and OGC:CRS84 are equivalent with respect to 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 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. +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. -Examples of a backwards compatible change include: +Examples of a forward 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.