diff --git a/LogicalTypes.md b/LogicalTypes.md index 1b7d5c26..6a8d6e4f 100644 --- a/LogicalTypes.md +++ b/LogicalTypes.md @@ -709,13 +709,18 @@ to values. `MAP` must annotate a 3-level structure: * The outer-most level must be a group annotated with `MAP` that contains a single field named `key_value`. The repetition of this level must be either - `optional` or `required` and determines whether the list is nullable. + `optional` or `required` and determines whether the map is nullable. * The middle level, named `key_value`, must be a repeated group with a `key` - field for map keys and, optionally, a `value` field for map values. + field for map keys and, optionally, a `value` field for map values. It must + not contain any other values. * The `key` field encodes the map's key type. This field must have - repetition `required` and must always be present. + repetition `required` and must always be present. I must be placed at the 0th + position of the `key_value` group. It is suggested to use a primitive as the + type. * The `value` field encodes the map's value type and repetition. This field can - be `required`, `optional`, or omitted. + be `required`, `optional`, or omitted. It must be placed at the 1st position + of the `key_value` group if present. In case of not present, the map can be + either represented with all null values or as a set of keys. The following example demonstrates the type for a non-null map from strings to nullable integers: @@ -741,18 +746,19 @@ keys. It is required that the repeated group of key-value pairs is named `key_value` and that its fields are named `key` and `value`. However, these names may not be used in existing data and should not be enforced as errors when reading. +(`key` and `value` can be identified by their position in case of misnaming.) Some existing data incorrectly used `MAP_KEY_VALUE` in place of `MAP`. For backward-compatibility, a group annotated with `MAP_KEY_VALUE` that is not contained by a `MAP`-annotated group should be handled as a `MAP`-annotated -group. +group. `MAP_KEY_VALUE` may be used for the `kay_value` group. Examples that can be interpreted using these rules: ``` // Map (nullable map, non-null values) optional group my_map (MAP) { - repeated group map { + repeated group map (MAP_KEY_VALUE) { required binary str (STRING); required int32 num; }