Skip to content

Commit 072eab2

Browse files
committed
Clarify the definition of invalid values
1 parent 87ee1a6 commit 072eab2

File tree

1 file changed

+29
-14
lines changed

1 file changed

+29
-14
lines changed

Geospatial.md

Lines changed: 29 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -95,9 +95,7 @@ min/max value pair of coordinates from each axis. Note that X and Y Values are
9595
always present. Z and M are omitted for 2D geospatial instances.
9696

9797
Writers should follow the guidelines below when calculating bounding boxes in
98-
the presence of invalid values. An invalid geospatial value refers to any of
99-
the following: `NaN`, `null`, `does not exist` (e.g., LINESTRING EMPTY), or
100-
`out of bounds` (e.g., `x < -180` or `x > 180` for `GEOGRAPHY` types):
98+
the presence of [invalid geospatial values](#invalid-geospatial-values).
10199

102100
* X and Y: Skip any invalid X or Y value and continue processing the remaining X or Y
103101
values. Do not produce a bounding box if all X or all Y values are invalid.
@@ -108,21 +106,23 @@ the following: `NaN`, `null`, `does not exist` (e.g., LINESTRING EMPTY), or
108106
* M: Skip any invalid M value and continue processing the remaining M values.
109107
Omit M from the bounding box if all M values are invalid.
110108

111-
Readers should follow the guidelines below when examining bounding boxes:
109+
Readers should follow the guidelines below when examining bounding boxes. If
110+
any values in the bounding box are [invalid](#invalid-geospatial-values),
111+
the bounding box is considered malformed and treated as a `no bounding box`case.
112112

113-
* No bounding box: No assumptions can be made about the presence or absence
114-
of invalid values. Readers may need to load all individual coordinate
113+
* No bounding box: No assumptions can be made about the presence or validity
114+
of coordinate values. Readers may need to load all individual coordinate
115115
values for validation.
116116

117117
* A bounding box is present:
118-
* X and Y: X and Y of the bounding box must be present. Readers should
119-
proceed using these values.
120-
* Z: If Z of the bounding box are missing, readers should make no
121-
assumptions about invalid values and may need to load individual
122-
coordinates for validation.
123-
* M: If M of the bounding box are missing, readers should make no
124-
assumptions about invalid values and may need to load individual
125-
coordinates for validation.
118+
* X and Y: Both X and Y of the bounding box must be present. Their absence
119+
renders the bounding box malformed.
120+
* Z: If Z of the bounding box is missing, readers should not assume
121+
anything about the presence or validity of Z values and may need to
122+
load individual coordinates for validation.
123+
* M: If M of the bounding box is missing, readers should not assume
124+
anything about the presence or validity of M values and may need to
125+
load individual coordinates for validation.
126126

127127
For the X values only, xmin may be greater than xmax. In this case, an object
128128
in this bounding box may match if it contains an X such that `x >= xmin` OR
@@ -192,3 +192,18 @@ The axis order of the coordinates in WKB and bounding box stored in Parquet
192192
follows the de facto standard for axis order in WKB and is therefore always
193193
(x, y) where x is easting or longitude and y is northing or latitude. This
194194
ordering explicitly overrides the axis order as specified in the CRS.
195+
196+
# Invalid geospatial values
197+
198+
An invalid geospatial value refers to any of the following cases:
199+
200+
* `null`: A null value in Parquet.
201+
* A non-`null` value that are encoded in a valid WKB or bounding box format
202+
but are not considered valid under this specification, including:
203+
* `NaN`: Not a Number. For example, `POINT EMPTY` in WKB is represented by a
204+
`Point` with each ordinate value set to an IEEE-754 quiet NaN value.
205+
* `Empty geometries`: Geometries explicitly marked as empty in WKB using
206+
indicators such as `numPoints`, `numRings`, or `numGeometries`. Examples
207+
include `LINESTRING EMPTY` or `POLYGON EMPTY`.
208+
* `Out-of-bounds coordinates`: Values that fall outside the valid range
209+
for `GEOGRAPHY` types. For example, `x < -180` or `x > 180`.

0 commit comments

Comments
 (0)