From fc506a3d1d58841ff3c8b6f8fc912f244d72b5c3 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Sat, 26 Sep 2026 12:34:36 +0200 Subject: [PATCH] Merge clarifications and editorial improvements --- CHANGELOG.md | 14 ++++++++++++++ core/README.md | 39 ++++++++++++++++++++++++++++----------- geojson/README.md | 6 +++--- geoparquet/README.md | 2 +- geoparquet/datatypes.md | 2 +- 5 files changed, 47 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e0b4f02..9f6b299 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ## [Unreleased] +### Added + +- Rules for merging collections + +### Changed + +- Clarified that collection-level data applies to all features, except for `schemas` + +### Fixed + +- The GeoParquet bit width of `uint32` is 32 +- Collection-level data can be used with at least two features (was: more than two) +- Various typos and an invalid JSON example + ## [v0.1.0] - 2025-08-15 - First release diff --git a/core/README.md b/core/README.md index 3e70104..1a53ef5 100644 --- a/core/README.md +++ b/core/README.md @@ -5,7 +5,7 @@ The specification doesn't distinguish between collection-level and feature-level common definitions are shared across these levels. - A Collection refers to a group of one or more features. -- A Feature is a single field geometry with additional properties. +- A Feature is a single geometry with additional properties. - **Schema:** @@ -15,6 +15,7 @@ common definitions are shared across these levels. - [schemas](#schemas) - [id](#id) - [collection](#collection) + - [Merging collections](#merging-collections) - [Spatial Properties](#spatial-properties) - [Schema Language](#schema-language) @@ -22,21 +23,19 @@ common definitions are shared across these levels. | Property Name | Data Type | Description | | ------------- | ------------------------------- | ----------- | -| schemas | object\> | **REQUIRED.** A list of schemas the collection implements. | +| schemas | object\> | **REQUIRED.** The schemas that each collection implements. | | id | string | **REQUIRED.** An identifier for the entity. | | collection | string | **REQUIRED.** The identifier of the collection. | ### schemas -The schemas the collection implements. -Each schema must be a valid HTTP(S) URLs to an existing YAML files compliant to Vecorel SDL. -The schema for this specification (see above) is required to be provided. +The schemas that each collection implements. +Each schema must be a valid HTTP(S) URL to an existing YAML file compliant to Vecorel SDL. +The schema URI for this specification (see above) is required to be present. Each `collection` must have a single set of applicable schemas. The key of the dictionary must be equal to the value provided for the `collection` property. -The schema URI for Vecorel that is listed above is required to be present. - **Example for `schemas`:** This describes two collections `abc` and `xyz`. @@ -48,7 +47,7 @@ This describes two collections `abc` and `xyz`. ], "xyz": [ "https://vecorel.org/specification/v0.1.0/schema.yaml", - "https://vecorel.org/crop-extension/v0.1.0/schema.yaml", + "https://vecorel.org/crop-extension/v0.1.0/schema.yaml" ] } ``` @@ -61,19 +60,37 @@ It must be unique per collection, i.e. `collection` and `id` form a unique ident A collection is a group of one or more features with a unique identifier, stored in the `collection` property. -Encodings may support to store properties that consists of the same value across all features at the collection-level. -This de-duplicates data for more efficient resource usage, but only applies if more than two features are available for the collection. +Encodings may support storing properties that have the same value across all features at the collection-level. +This de-duplicates data for more efficient resource usage, but only applies if at least two features are available. The specific location and behaviour of collection-level data is specified in the encoding-specific specifications. +Collection-level data always applies to all features, even if they belong to different collections. +The only exception is `schemas`, which is specified per collection. + **Example:** You have two different datasets named `abc` (CC-0 licensed) and `xyz` (CC-BY-4.0 licensed). If you store the datasets separately, you can store the license in the collection-level data as the value for the property is the same for all features. -Once you merged the two datasets, you must ensure that a unique identifier for the collection is provieded +Once you merged the two datasets, you must ensure that a unique identifier for the collection is provided (here: `abc` and `xyz`) so that IDs are unique. Additionally, you have to add the license property on the feature-level as the licenses are now twofold. +### Merging collections + +When features of multiple datasets are combined into a single dataset: + +- Each feature must provide the `collection` property at the feature-level, + unless all features belong to the same collection. +- The `schemas` of a collection that occurs in multiple datasets are combined. + A collection can't implement different versions of this specification. +- The `id` must remain unique per collection. +- Collection-level properties that don't have the same value for all features anymore + must be moved to the feature-level. +- Collection-only properties (see `collection` in [Vecorel SDL](#schema-language)) other than `schemas` + can't be moved to the feature-level. + If their values differ between the datasets, they must be removed. + ## Spatial Properties | Property Name | Data Type | Description | diff --git a/geojson/README.md b/geojson/README.md index 48ff17f..78e50b4 100644 --- a/geojson/README.md +++ b/geojson/README.md @@ -1,6 +1,6 @@ # GeoJSON Encoding Specification -The GeoJSON encoding defines to encode vector data compliant to Vecorel as +The GeoJSON encoding defines how to encode vector data compliant to Vecorel as GeoJSON as defined in [IETF RFC7946](https://datatracker.ietf.org/doc/html/rfc7946). A single Vecorel Feature must be encoded as a GeoJSON [`Feature`](#feature). @@ -29,7 +29,7 @@ The following properties are defined for a GeoJSON Feature (at the top-level of | bbox | array\ | A [GeoJSON Bounding Box](https://datatracker.ietf.org/doc/html/rfc7946#section-5) | | properties | object | An object with all additional properties (see [`properties`](#properties)) | -The mapping between the Parquet data types and the Vecorel SDL data types, can be found in the +The mapping between the GeoJSON data types and the Vecorel SDL data types, can be found in the [data type mapping](datatypes.md). > [!IMPORTANT] @@ -75,7 +75,7 @@ The following properties in Features can't be collection-level properties: - `geometry` - `bbox` -Properties with the following names can#t be moved to the collection-level due to conflicts with the +Properties with the following names can't be moved to the collection-level due to conflicts with the FeatureCollection properties defined by GeoJSON: - `features` diff --git a/geoparquet/README.md b/geoparquet/README.md index 0d8ad5a..971e47b 100644 --- a/geoparquet/README.md +++ b/geoparquet/README.md @@ -15,7 +15,7 @@ Properties that are optional can be omitted if all values are i.e. the column can be missing from the GeoParquet file. Properties can also be stored at the [collection-level](../core/README.md#collection) if all values in a column have the same value. -This de-duplicates data for more efficient resource usage and simplifies the sturcture of the Parquet file. +This de-duplicates data for more efficient resource usage and simplifies the structure of the Parquet file. The GeoParquet file must embed the properties in the Parquet metadata in a property named `collection`. The metadata must be JSON-encoded. diff --git a/geoparquet/datatypes.md b/geoparquet/datatypes.md index d0e5001..7b2715c 100644 --- a/geoparquet/datatypes.md +++ b/geoparquet/datatypes.md @@ -11,7 +11,7 @@ It also shows the mapping to the GeoParquet data types. | int16 | IntType
bitWidth: 16
isSigned: true
(deprecated: INT_16) | yes | | uint16 | IntType
bitWidth: 16
isSigned: false
(deprecated: UINT_16) | yes | | int32 | IntType
bitWidth: 32
isSigned: true
(deprecated: INT_32) | yes | -| uint32 | IntType
bitWidth: 64
isSigned: false
(deprecated: UINT_32) | yes | +| uint32 | IntType
bitWidth: 32
isSigned: false
(deprecated: UINT_32) | yes | | int64 | IntType
bitWidth: 64
isSigned: true
(deprecated: INT_64) | yes | | uint64 | IntType
bitWidth: 64
isSigned: false
(deprecated: UINT_64) | yes | | float
IEEE 32-bit | FLOAT | yes |