Clarify the use of Structs vs Maps #34

Author: m-mohr

CHANGELOG.md

@@ -30,11 +30,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ### Fixed
 
 - Various minor clarifications and editorial enhancements
-- GeoParquet encoding: Properties that are optional can be omitted if all values are null values
-- GeoJSON encoding: Clarify the encoding of the top-level properties (including `links` and `fiboa`)
-- GeoJSON encoding: Clarify the use of RFC 7946
-- GeoParquet encoding for bounding boxes and objects
 - Added descriptions to the allowed values for `determination_method`
+- GeoJSON: Clarify the encoding of the top-level properties (including `links` and `fiboa`)
+- GeoJSON: Clarify the use of RFC 7946
+- GeoParquet: Properties that are optional can be omitted if all values are null values
+- GeoParquet: Added encoding for bounding boxes and objects
+- GeoParquet: Clarified the use of Map and Struct data types
 
 ## [v0.2.0] - 2024-04-10
 

geoparquet/datatypes.md

@@ -19,7 +19,7 @@ It also shows the mapping to the GeoParquet data types.
 | binary                                              | BYTE_ARRAY                                                   | as string, base64-encoded       |
 | string<br />charset: UTF-8                          | STRING (BYTE_ARRAY)                                          | yes                             |
 | array                                               | LIST                                                         | yes                             |
-| object<br />keys: string<br />values: any           | STRUCT / MAP                                                 | yes                             |
+| object<br />keys: string<br />values: any           | STRUCT or MAP (see below)                                    | yes                             |
 | date                                                | DATE (INT32)                                                 | as string, compliant to ISO8601 |
 | date-time<br />with milliseconds<br />timezone: UTC | TimestampType (INT64)<br />isAdjustedToUTC: true<br />unit:  MILLIS<br />(deprecated: TIMESTAMP_MILLIS) | as string, compliant to ISO8601 |
 | geometry                                            | BYTE_ARRAY<br />encoded as WKB                               | no                              |
@@ -29,6 +29,14 @@ It also shows the mapping to the GeoParquet data types.
 The integer data types and the data type string can also be mapped to the ENUM data type in Parquet
 if a pre-defined set of values is available.
 
+## Struct vs Map
+
+Parquet has both Map and Struct types. The struct type is similar to a named dictionary while the map type is similar to a list of ordered (key, value) pairs. The main difference is that you need to know up-front the keys for the struct type, while you don't for the map type.
+
+Due to this difference, the **Struct** type can only be used if `additionalProperties` is `false` (the default value) and only `properties` is provided to clearly specify the exact names of the properties.
+
+Any variability in the keys through the use of `additionalProperties` (except for the default `false`) or `patternProperties` requires the use of the **Map** data type. Please note that the order of the Map type is guaranteed to be preserved.
+
 ## Unsupported Data Types
 
 The following data types occur in Parquet, but are not currently supported in fiboa: