Skip to content

Commit a945ddc

Browse files
committed
Update docs on vertex ordering (#27963)
At time of writing, GeoJSON did not enforce a specific ordering of vertices in a polygon, but it now does. We occasionally get reports of Elasticsearch rejecting apparently-valid GeoJSON because of badly oriented polygons, and it's helpful to be able to point at this bit of the documentation when responding.
1 parent 88defd7 commit a945ddc

File tree

1 file changed

+18
-16
lines changed

1 file changed

+18
-16
lines changed

docs/reference/mapping/types/geo-shape.asciidoc

+18-16
Original file line numberDiff line numberDiff line change
@@ -378,22 +378,24 @@ POST /example/doc
378378
// CONSOLE
379379
// TEST[skip:https://github.com/elastic/elasticsearch/issues/23836]
380380

381-
*IMPORTANT NOTE:* GeoJSON and WKT do not enforce a specific order for vertices
382-
thus ambiguous polygons around the dateline and poles are possible. To alleviate
383-
ambiguity the Open Geospatial Consortium (OGC)
384-
http://www.opengeospatial.org/standards/sfa[Simple Feature Access] specification
385-
defines the following vertex ordering:
386-
387-
* Outer Ring - Counterclockwise
388-
* Inner Ring(s) / Holes - Clockwise
389-
390-
For polygons that do not cross the dateline, vertex order will not matter in
391-
Elasticsearch. For polygons that do cross the dateline, Elasticsearch requires
392-
vertex ordering to comply with the OGC specification. Otherwise, an unintended polygon
393-
may be created and unexpected query/filter results will be returned.
394-
395-
The following provides an example of an ambiguous polygon. Elasticsearch will apply
396-
OGC standards to eliminate ambiguity resulting in a polygon that crosses the dateline.
381+
*IMPORTANT NOTE:* WKT does not enforce a specific order for vertices thus
382+
ambiguous polygons around the dateline and poles are possible.
383+
https://tools.ietf.org/html/rfc7946#section-3.1.6[GeoJSON] mandates that the
384+
outer polygon must be counterclockwise and interior shapes must be clockwise,
385+
which agrees with the Open Geospatial Consortium (OGC)
386+
http://www.opengeospatial.org/standards/sfa[Simple Feature Access]
387+
specification for vertex ordering.
388+
389+
Elasticsearch accepts both clockwise and counterclockwise polygons if they
390+
appear not to cross the dateline (i.e. they cross less than 180° of longitude),
391+
but for polygons that do cross the dateline (or for other polygons wider than
392+
180°) Elasticsearch requires the vertex ordering to comply with the OGC and
393+
GeoJSON specifications. Otherwise, an unintended polygon may be created and
394+
unexpected query/filter results will be returned.
395+
396+
The following provides an example of an ambiguous polygon. Elasticsearch will
397+
apply the GeoJSON standard to eliminate ambiguity resulting in a polygon that
398+
crosses the dateline.
397399

398400
[source,js]
399401
--------------------------------------------------

0 commit comments

Comments
 (0)