From 8790bb4dd53173d2cbc6f22ec9859208590ecdf0 Mon Sep 17 00:00:00 2001
From: Jacob Wasserman <jwasserman@fb.com>
Date: Tue, 28 Nov 2023 14:56:05 -0500
Subject: [PATCH] Change to covering from geometry_bbox. Doc updates.

Change the geometry_bbox to the broader "covering" section. Update
tests and examples.

Made some documentation updates:
* Parquet schema -> group
* Do not require zmin/zmax if geometries have 3 dimensions
---
 examples/example.parquet       | Bin 29627 -> 29631 bytes
 examples/example_metadata.json |   8 +++++---
 format-specs/geoparquet.md     |  21 ++++++++++++++++-----
 format-specs/schema.json       |  16 +++++++++++-----
 scripts/generate_example.py    |   4 +++-
 scripts/test_json_schema.py    |  11 ++++++-----
 6 files changed, 41 insertions(+), 19 deletions(-)

diff --git a/examples/example.parquet b/examples/example.parquet
index 1e7bc885ae58391ccca1a666aacc08d8ae447fc4..2b5da28690fcc81b1f66a6aa32b42c339ca35fb9 100644
GIT binary patch
delta 697
zcmYjOzi--55Qe2<$k3reO*;gkpbQya?8I&8Qk{)$AS#7a6oWd12hB^20RzRPR26$N
zzIN)~xl+aq{d2N*?$o=ZiDJq3?#FlczVF`6ZTk0Z`q$-2`up|O$?#F3H%>lI&qpf%
zD)%KX#}|C|#?gE@LN_ld^;K`G4{4<nwY@R06@U%+Rh!p8)wj&!Q0{l4-Y}YXK385;
z$}{c7h1F?;AaC%uN1fIo*b8*)3v6@_0Ba$*06q^=6dw|t9Ds#Lguv4-y`vDuWcWs|
zI|GXQWL(BK$>q9VJ(v4P4<G}w{!$1t)Tfi}tR-8~oYLUQT_NbM3Pk!(yz`_TFdkHb
zaN?*+pm!&QtZ&4UOV0d19|ztpaoo<zJD^ceo8Hgz>tfyAXfUNR1K4HHA?x=eX&O<#
zT(vmqhS*ee(Xd)L<1DLNtL6BJY{xua1g0?v%=gRw7A9~Y?pD!SD-0vUi*P{ym~Q2K
zN_2x-5}581@iV$+a!<3V|HjXr`_`FkaTgd=DwfdDc3e-3S$0KS>`<E4UbkgMa>Ro0
z-5Tq4BTJ7q32ov*Z%vPSr`m=K${<Pn9th&y^!y?ULNQdte$<1E+Z@rz)YDwt)t_ds
MGqufBst(7-KkV$wQUCw|

delta 725
zcmYLH!A{#i5G5DHfm^FeJyg)B5eE(%0w|=n*|mWrBqA=cV+*OUAu&>8I|+$X;E+3<
zD)SYbkT`PSbNG$U%+h8huV;4NynS!%*SFluTkh%ZEcfU6{w!Ml8upT?HyL05)H?Z{
z|Gs{k?<Rw36l0j@qwGs~nrme@;kVULh5!<9)$HfT@L^>&4!p`F=s4Fsw~{r7g*g>r
zhR?ypK+oWiQUNx=QHYJI0WAQZaz#WIAq}HtZ3?l6ncb|?p~9;$p^a~>V<X5S<qmC<
za#Q!CTH2!w<nonBg*eZ4MjIc`y&XPu)3OkBQK;HkGAexXwk{1^DMDjKLBq-(M;jjo
zQ*No3-^Em+j9i8J<;3r>ASnH317F}myp*gEy3}hzW?>&e$xXHA7Q68;KKyZvO~n)3
z*sNlQYGH;!kPuTG9Lm1-oPOYSn&cb_XQ-8?YQzwVTdUST!hJKc#q<oJPtakvRO$OC
z4S@O$;y05l8L!Q`K}Y+OfT^rDmPC<c($HFMa{<$E$Pp_(Xr?-LhB|Vm7w>hn&wRMG
zNhSU<sFpu-YcU(!Vh~yZ*fkB@&m)vGy)FBJu}lPL+o!i#=ADhN?3LQ*rKMwVw*CTr
Ch|!q<

diff --git a/examples/example_metadata.json b/examples/example_metadata.json
index b31f1fd..22dc7ae 100644
--- a/examples/example_metadata.json
+++ b/examples/example_metadata.json
@@ -8,6 +8,11 @@
           180.0,
           83.6451
         ],
+        "covering": {
+          "box": {
+            "column": "bbox"
+          }
+        },
         "crs": {
           "$schema": "https://proj.org/schemas/v0.6/projjson.schema.json",
           "area": "World.",
@@ -108,9 +113,6 @@
         },
         "edges": "planar",
         "encoding": "WKB",
-        "geometry_bbox": {
-          "column": "bbox"
-        },
         "geometry_types": [
           "Polygon",
           "MultiPolygon"
diff --git a/format-specs/geoparquet.md b/format-specs/geoparquet.md
index 81bcaf4..6212718 100644
--- a/format-specs/geoparquet.md
+++ b/format-specs/geoparquet.md
@@ -58,7 +58,7 @@ Each geometry column in the dataset MUST be included in the `columns` field abov
 | edges          | string       | Name of the coordinate system for the edges. Must be one of `"planar"` or `"spherical"`. The default value is `"planar"`. |
 | bbox           | \[number]    | Bounding Box of the geometries in the file, formatted according to [RFC 7946, section 5](https://tools.ietf.org/html/rfc7946#section-5). |
 | epoch          | number       | Coordinate epoch in case of a dynamic CRS, expressed as a decimal year. |
-| geometry_bbox  | object       | Object specifying a column name of a [Bounding Box Column](#bounding-box-columns). |
+| covering       | object       | Object containing information like bounding boxes to help accelerate spatial data retrieval |
 
 
 #### crs
@@ -136,17 +136,28 @@ For non-geographic coordinate reference systems, the items in the bbox are minim
 
 The bbox values are in the same coordinate reference system as the geometry.
 
-#### geometry_bbox
+#### covering
+
+The covering field specifies optional simplified representations of each geometry. The keys of the "covering" object MUST be a supported encoding. Currently the only supported encoding is "box" which specifies the name of a [bounding box column](#bounding-box-columns)
+
+Example:
+```
+"covering": {
+    "box": {"column": "bbox"}
+}
+```
+
+##### box encoding
 
 Including a per-row bounding box can be useful for accelerating spatial queries by allowing consumers to inspect row group bounding box summary statistics. Furthermore a bounding box may be used to avoid complex spatial operations by first checking for bounding box overlaps. This field captures the name of a column containing the bounding box of the geometry for every row.
 
-The format of `geometry_bbox` is `{"name": "column_name"}` where `column_name` MUST exist in the Parquet file and meet the criteria in the [Bounding Box Column](#bounding-box-columns) definition.
+The format of `box` encoding is `{"name": "column_name"}` where `column_name` MUST exist in the Parquet file and meet the criteria in the [Bounding Box Column](#bounding-box-columns) definition.
 
-Note: the value specified in this field should not be confused with the [`bbox`](#bbox) field which contains the single bounding box of this geometry over the whole GeoParquet file.
+Note: the value specified in this field should not be confused with the top-level [`bbox`](#bbox) field which contains the single bounding box of this geometry over the whole GeoParquet file.
 
 ### Bounding Box Columns
 
-A bounding box column MUST be a Parquet struct with required fields `xmin`, `xmax`, `ymin`, and `ymax`. For three dimensions the additional fields `zmin` and `zmax` MUST be present. The fields MUST be of Parquet type `FLOAT` or `DOUBLE`. The repetition of a bounding box column MUST match the geometry column's [repetition](#repetition). A row MUST contain a bounding box value if and only if the row contains a geometry value. In cases where the geometry is optional and a row not contain a geometry value, the row MUST NOT contain a bounding box value.
+A bounding box column MUST be a Parquet group field with 4 child fields named `xmin`, `xmax`, `ymin`, and `ymax`. For three dimensions the additional fields `zmin` and `zmax` MAY be present but are not required. The fields MUST be of Parquet type `FLOAT` or `DOUBLE`. The repetition of a bounding box column MUST match the geometry column's [repetition](#repetition). A row MUST contain a bounding box value if and only if the row contains a geometry value. In cases where the geometry is optional and a row not contain a geometry value, the row MUST NOT contain a bounding box value.
 
 The bounding box column MUST be at the root of the schema. The bounding box column MUST NOT be nested in a group.
 
diff --git a/format-specs/schema.json b/format-specs/schema.json
index 6f27af6..e8dd90d 100644
--- a/format-specs/schema.json
+++ b/format-specs/schema.json
@@ -72,13 +72,19 @@
             "epoch": {
               "type": "number"
             },
-            "geometry_bbox": {
+            "covering": {
               "type": "object",
-              "required": ["column"],
+              "minProperties": 1,
               "properties": {
-                "column": {
-                  "type": "string",
-                  "minLength": 1
+                "box": {
+                  "type": "object",
+                  "required": ["column"],
+                  "properties": {
+                    "column": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  }
                 }
               }
             }
diff --git a/scripts/generate_example.py b/scripts/generate_example.py
index 50bc284..39632e7 100644
--- a/scripts/generate_example.py
+++ b/scripts/generate_example.py
@@ -48,7 +48,9 @@ def get_version() -> str:
             "crs": json.loads(df.crs.to_json()),
             "edges": "planar",
             "bbox": [round(x, 4) for x in df.total_bounds],
-            "geometry_bbox": {"column": "bbox"},
+            "covering": {
+                "box": {"column": "bbox"},
+            },
         },
     },
 }
diff --git a/scripts/test_json_schema.py b/scripts/test_json_schema.py
index dfafbce..2ef8d27 100644
--- a/scripts/test_json_schema.py
+++ b/scripts/test_json_schema.py
@@ -41,8 +41,10 @@ def get_version() -> str:
         "geometry": {
             "encoding": "WKB",
             "geometry_types": [],
-            "geometry_bbox": {
-                "column": "bbox",
+            "covering": {
+                "box": {
+                    "column": "bbox",
+                },
             },
         },
     },
@@ -216,16 +218,15 @@ def get_version() -> str:
 # Geometry Bbox
 
 metadata = copy.deepcopy(metadata_template)
-metadata["columns"]["geometry"]["geometry_bbox"].pop("column")
+metadata["columns"]["geometry"]["covering"].pop("box")
 invalid_cases["empty_geometry_bbox"] = metadata
 
 
 metadata = copy.deepcopy(metadata_template)
-metadata["columns"]["geometry"]["geometry_bbox"]["column"] = ""
+metadata["columns"]["geometry"]["covering"]["box"]["column"] = ""
 invalid_cases["empty_geometry_bbox_column"] = metadata
 
 
-
 # # Tests
 
 @pytest.mark.parametrize(