Skip to content

Commit 47e5216

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 ad3af73 commit 47e5216

File tree

1 file changed

+18
-16
lines changed

1 file changed

+18
-16
lines changed

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

Lines changed: 18 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -372,22 +372,24 @@ POST /example/doc
372372
// CONSOLE
373373
// TEST[skip:https://github.com/elastic/elasticsearch/issues/23836]
374374

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

392394
[source,js]
393395
--------------------------------------------------

0 commit comments

Comments
 (0)