| < draft-ietf-geojson-02.txt | draft-ietf-geojson-04.txt > | |||
|---|---|---|---|---|
| GeoJSON H. Butler | GeoJSON H. Butler | |||
| Internet-Draft Hobu Inc. | Internet-Draft Hobu Inc. | |||
| Intended status: Standards Track M. Daly | Intended status: Standards Track M. Daly | |||
| Expires: October 9, 2016 Cadcorp | Expires: December 25, 2016 Cadcorp | |||
| A. Doyle | A. Doyle | |||
| MIT | ||||
| S. Gillies | S. Gillies | |||
| Mapbox Inc. | Mapbox | |||
| T. Schaub | ||||
| Planet Labs | ||||
| S. Hagen | S. Hagen | |||
| April 07, 2016 | T. Schaub | |||
| Planet Labs | ||||
| June 23, 2016 | ||||
| The GeoJSON Format | The GeoJSON Format | |||
| draft-ietf-geojson-02 | draft-ietf-geojson-04 | |||
| Abstract | Abstract | |||
| GeoJSON is a geospatial data interchange format based on JavaScript | GeoJSON is a geospatial data interchange format based on JavaScript | |||
| Object Notation (JSON). It defines several types of JSON objects and | Object Notation (JSON). It defines several types of JSON objects and | |||
| the manner in which they are combined to represent data about | the manner in which they are combined to represent data about | |||
| geographic features, their properties, and their spatial extents. | geographic features, their properties, and their spatial extents. | |||
| This document recommends a single coordinate reference system based | GeoJSON uses a geographic coordinate reference system, World Geodetic | |||
| on WGS 84. Other coordinate reference systems are not recommended. | System 1984, and units of decimal degrees. | |||
| Status of This Memo | Status of This Memo | |||
| This Internet-Draft is submitted in full conformance with the | This Internet-Draft is submitted in full conformance with the | |||
| provisions of BCP 78 and BCP 79. | provisions of BCP 78 and BCP 79. | |||
| Internet-Drafts are working documents of the Internet Engineering | Internet-Drafts are working documents of the Internet Engineering | |||
| Task Force (IETF). Note that other groups may also distribute | Task Force (IETF). Note that other groups may also distribute | |||
| working documents as Internet-Drafts. The list of current Internet- | working documents as Internet-Drafts. The list of current Internet- | |||
| Drafts is at http://datatracker.ietf.org/drafts/current/. | Drafts is at http://datatracker.ietf.org/drafts/current/. | |||
| Internet-Drafts are draft documents valid for a maximum of six months | Internet-Drafts are draft documents valid for a maximum of six months | |||
| and may be updated, replaced, or obsoleted by other documents at any | and may be updated, replaced, or obsoleted by other documents at any | |||
| time. It is inappropriate to use Internet-Drafts as reference | time. It is inappropriate to use Internet-Drafts as reference | |||
| material or to cite them other than as "work in progress." | material or to cite them other than as "work in progress." | |||
| This Internet-Draft will expire on October 9, 2016. | This Internet-Draft will expire on December 25, 2016. | |||
| Copyright Notice | Copyright Notice | |||
| Copyright (c) 2016 IETF Trust and the persons identified as the | Copyright (c) 2016 IETF Trust and the persons identified as the | |||
| document authors. All rights reserved. | document authors. All rights reserved. | |||
| This document is subject to BCP 78 and the IETF Trust's Legal | This document is subject to BCP 78 and the IETF Trust's Legal | |||
| Provisions Relating to IETF Documents | Provisions Relating to IETF Documents | |||
| (http://trustee.ietf.org/license-info) in effect on the date of | (http://trustee.ietf.org/license-info) in effect on the date of | |||
| publication of this document. Please review these documents | publication of this document. Please review these documents | |||
| skipping to change at page 2, line 39 ¶ | skipping to change at page 2, line 39 ¶ | |||
| 3. GeoJSON Object . . . . . . . . . . . . . . . . . . . . . . . 7 | 3. GeoJSON Object . . . . . . . . . . . . . . . . . . . . . . . 7 | |||
| 3.1. Geometry Object . . . . . . . . . . . . . . . . . . . . . 7 | 3.1. Geometry Object . . . . . . . . . . . . . . . . . . . . . 7 | |||
| 3.1.1. Position . . . . . . . . . . . . . . . . . . . . . . 7 | 3.1.1. Position . . . . . . . . . . . . . . . . . . . . . . 7 | |||
| 3.1.2. Point . . . . . . . . . . . . . . . . . . . . . . . . 8 | 3.1.2. Point . . . . . . . . . . . . . . . . . . . . . . . . 8 | |||
| 3.1.3. MultiPoint . . . . . . . . . . . . . . . . . . . . . 9 | 3.1.3. MultiPoint . . . . . . . . . . . . . . . . . . . . . 9 | |||
| 3.1.4. LineString . . . . . . . . . . . . . . . . . . . . . 9 | 3.1.4. LineString . . . . . . . . . . . . . . . . . . . . . 9 | |||
| 3.1.5. MultiLineString . . . . . . . . . . . . . . . . . . . 9 | 3.1.5. MultiLineString . . . . . . . . . . . . . . . . . . . 9 | |||
| 3.1.6. Polygon . . . . . . . . . . . . . . . . . . . . . . . 9 | 3.1.6. Polygon . . . . . . . . . . . . . . . . . . . . . . . 9 | |||
| 3.1.7. MultiPolygon . . . . . . . . . . . . . . . . . . . . 10 | 3.1.7. MultiPolygon . . . . . . . . . . . . . . . . . . . . 10 | |||
| 3.1.8. Geometry Collection . . . . . . . . . . . . . . . . . 10 | 3.1.8. Geometry Collection . . . . . . . . . . . . . . . . . 10 | |||
| 3.2. Feature Object . . . . . . . . . . . . . . . . . . . . . 10 | 3.1.9. Antimeridian Cutting . . . . . . . . . . . . . . . . 10 | |||
| 3.3. Feature Collection Object . . . . . . . . . . . . . . . . 10 | 3.1.10. Uncertainty and Precision . . . . . . . . . . . . . . 11 | |||
| 4. Coordinate Reference System . . . . . . . . . . . . . . . . . 11 | 3.2. Feature Object . . . . . . . . . . . . . . . . . . . . . 11 | |||
| 5. Bounding Box . . . . . . . . . . . . . . . . . . . . . . . . 11 | 3.3. Feature Collection Object . . . . . . . . . . . . . . . . 12 | |||
| 5.1. The connecting lines . . . . . . . . . . . . . . . . . . 12 | 4. Coordinate Reference System . . . . . . . . . . . . . . . . . 12 | |||
| 5.2. The Antimeridian . . . . . . . . . . . . . . . . . . . . 13 | 5. Bounding Box . . . . . . . . . . . . . . . . . . . . . . . . 13 | |||
| 5.3. The Poles . . . . . . . . . . . . . . . . . . . . . . . . 13 | 5.1. The Connecting Lines . . . . . . . . . . . . . . . . . . 14 | |||
| 6. Extending GeoJSON . . . . . . . . . . . . . . . . . . . . . . 14 | 5.2. The Antimeridian . . . . . . . . . . . . . . . . . . . . 14 | |||
| 6.1. Foreign members . . . . . . . . . . . . . . . . . . . . . 14 | 5.3. The Poles . . . . . . . . . . . . . . . . . . . . . . . . 15 | |||
| 6.2. GeoJSON types are not extensible . . . . . . . . . . . . 15 | 6. Extending GeoJSON . . . . . . . . . . . . . . . . . . . . . . 15 | |||
| 6.3. Semantics of GeoJSON members and types are not changeable 15 | 6.1. Foreign Members . . . . . . . . . . . . . . . . . . . . . 15 | |||
| 7. Versioning . . . . . . . . . . . . . . . . . . . . . . . . . 15 | 7. GeoJSON Types are not Extensible . . . . . . . . . . . . . . 16 | |||
| 8. Mapping 'geo' URIs . . . . . . . . . . . . . . . . . . . . . 16 | 7.1. Semantics of GeoJSON Members and Types are not Changeable 16 | |||
| 9. Security Considerations . . . . . . . . . . . . . . . . . . . 16 | 8. Versioning . . . . . . . . . . . . . . . . . . . . . . . . . 17 | |||
| 10. Interoperability Considerations . . . . . . . . . . . . . . . 17 | 9. Mapping 'geo' URIs . . . . . . . . . . . . . . . . . . . . . 17 | |||
| 10.1. I-JSON . . . . . . . . . . . . . . . . . . . . . . . . . 17 | 10. Security Considerations . . . . . . . . . . . . . . . . . . . 18 | |||
| 10.2. Coordinate Precision . . . . . . . . . . . . . . . . . . 17 | 11. Interoperability Considerations . . . . . . . . . . . . . . . 18 | |||
| 10.3. Coordinate Order . . . . . . . . . . . . . . . . . . . . 17 | 11.1. I-JSON . . . . . . . . . . . . . . . . . . . . . . . . . 18 | |||
| 10.4. Antimeridian cutting . . . . . . . . . . . . . . . . . . 17 | 11.2. Coordinate Precision . . . . . . . . . . . . . . . . . . 18 | |||
| 10.5. Geometry Collections . . . . . . . . . . . . . . . . . . 18 | 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 | |||
| 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 | 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 20 | |||
| 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 | 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 | |||
| 12.1. Normative References . . . . . . . . . . . . . . . . . . 20 | 14.1. Normative References . . . . . . . . . . . . . . . . . . 20 | |||
| 12.2. Informative References . . . . . . . . . . . . . . . . . 20 | 14.2. Informative References . . . . . . . . . . . . . . . . . 21 | |||
| Appendix A. Geometry Examples . . . . . . . . . . . . . . . . . 21 | Appendix A. Geometry Examples . . . . . . . . . . . . . . . . . 21 | |||
| A.1. Points . . . . . . . . . . . . . . . . . . . . . . . . . 21 | A.1. Points . . . . . . . . . . . . . . . . . . . . . . . . . 21 | |||
| A.2. LineStrings . . . . . . . . . . . . . . . . . . . . . . . 21 | A.2. LineStrings . . . . . . . . . . . . . . . . . . . . . . . 21 | |||
| A.3. Polygons . . . . . . . . . . . . . . . . . . . . . . . . 21 | A.3. Polygons . . . . . . . . . . . . . . . . . . . . . . . . 22 | |||
| A.4. MultiPoints . . . . . . . . . . . . . . . . . . . . . . . 22 | A.4. MultiPoints . . . . . . . . . . . . . . . . . . . . . . . 23 | |||
| A.5. MultiLineStrings . . . . . . . . . . . . . . . . . . . . 23 | A.5. MultiLineStrings . . . . . . . . . . . . . . . . . . . . 23 | |||
| A.6. MultiPolygons . . . . . . . . . . . . . . . . . . . . . . 23 | A.6. MultiPolygons . . . . . . . . . . . . . . . . . . . . . . 24 | |||
| A.7. GeometryCollections . . . . . . . . . . . . . . . . . . . 24 | A.7. GeometryCollections . . . . . . . . . . . . . . . . . . . 25 | |||
| Appendix B. Changes from pre-IETF specification . . . . . . . . 25 | Appendix B. Changes from pre-IETF Specification . . . . . . . . 26 | |||
| B.1. Normative changes . . . . . . . . . . . . . . . . . . . . 25 | B.1. Normative Changes . . . . . . . . . . . . . . . . . . . . 26 | |||
| B.2. Informative changes . . . . . . . . . . . . . . . . . . . 26 | B.2. Informative Changes . . . . . . . . . . . . . . . . . . . 27 | |||
| Appendix C. GeoJSON Text Sequences . . . . . . . . . . . . . . . 26 | Appendix C. GeoJSON Text Sequences . . . . . . . . . . . . . . . 27 | |||
| Appendix D. Contributors . . . . . . . . . . . . . . . . . . . . 26 | ||||
| Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 | Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 | |||
| 1. Introduction | 1. Introduction | |||
| GeoJSON is a format for encoding a variety of geographic data | GeoJSON is a format for encoding a variety of geographic data | |||
| structures using JavaScript Object Notation (JSON) [RFC7159]. A | structures using JavaScript Object Notation (JSON) [RFC7159]. A | |||
| GeoJSON object may represent a region of space (a Geometry), a | GeoJSON object may represent a region of space (a Geometry), a | |||
| spatially-bounded entity (a Feature), or a list of features (a | spatially-bounded entity (a Feature), or a list of features (a | |||
| Feature Collection). GeoJSON supports the following geometry types: | Feature Collection). GeoJSON supports the following geometry types: | |||
| Point, LineString, Polygon, MultiPoint, MultiLineString, | Point, LineString, Polygon, MultiPoint, MultiLineString, | |||
| skipping to change at page 4, line 14 ¶ | skipping to change at page 4, line 13 ¶ | |||
| and the heterogeneous GeometryCollection. GeoJSON representations of | and the heterogeneous GeometryCollection. GeoJSON representations of | |||
| instances of these geometry types are analogous to the well-known | instances of these geometry types are analogous to the well-known | |||
| binary (WKB) and text (WKT) representations described in that same | binary (WKB) and text (WKT) representations described in that same | |||
| specification. | specification. | |||
| GeoJSON also comprises the types Feature and FeatureCollection. | GeoJSON also comprises the types Feature and FeatureCollection. | |||
| Feature objects in GeoJSON contain a geometry object with one of the | Feature objects in GeoJSON contain a geometry object with one of the | |||
| above geometry types and additional members. A FeatureCollection | above geometry types and additional members. A FeatureCollection | |||
| object contains an array of feature objects. This structure is | object contains an array of feature objects. This structure is | |||
| analogous to that of the Web Feature Service (WFS) response to | analogous to that of the Web Feature Service (WFS) response to | |||
| GetFeatures requests specified in [WFSv1] or to a KML Folder of | GetFeatures requests specified in [WFSv1] or to a Keyhole Markup | |||
| Placemarks [KMLv2.2]. Some implementations of the WFS specification | Language (KML) Folder of Placemarks [KMLv2.2]. Some implementations | |||
| also provide GeoJSON formatted responses to GetFeature requests, but | of the WFS specification also provide GeoJSON formatted responses to | |||
| there is no particular service model or feature type ontology implied | GetFeature requests, but there is no particular service model or | |||
| in the GeoJSON format specification. | feature type ontology implied in the GeoJSON format specification. | |||
| Since its initial publication in 2008 [GJ2008], the GeoJSON format | Since its initial publication in 2008 [GJ2008], the GeoJSON format | |||
| specification has steadily grown in popularity. It is widely used in | specification has steadily grown in popularity. It is widely used in | |||
| JavaScript web mapping libraries, JSON-based document databases, and | JavaScript web mapping libraries, JSON-based document databases, and | |||
| web APIs. | web APIs. | |||
| 1.1. Requirements Language | 1.1. Requirements Language | |||
| The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | |||
| "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and | "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and | |||
| skipping to change at page 4, line 49 ¶ | skipping to change at page 4, line 48 ¶ | |||
| content deemed irrelevant by the authors. These placeholders must of | content deemed irrelevant by the authors. These placeholders must of | |||
| course be deleted or otherwise replaced, before attempting to | course be deleted or otherwise replaced, before attempting to | |||
| validate the corresponding JSON code example. | validate the corresponding JSON code example. | |||
| Whitespace is used in the examples inside this document to help | Whitespace is used in the examples inside this document to help | |||
| illustrate the data structures, but is not required. Unquoted | illustrate the data structures, but is not required. Unquoted | |||
| whitespace is not significant in JSON. | whitespace is not significant in JSON. | |||
| 1.3. Specification of GeoJSON | 1.3. Specification of GeoJSON | |||
| This document updates the original GeoJSON format specification | This document supersedes the original GeoJSON format specification | |||
| [GJ2008]. | [GJ2008]. | |||
| 1.4. Definitions | 1.4. Definitions | |||
| o JavaScript Object Notation (JSON), and the terms object, member, | o JavaScript Object Notation (JSON), and the terms object, member, | |||
| name, value, array, number, true, false, and null are to be | name, value, array, number, true, false, and null are to be | |||
| interpreted as defined in [RFC7159]. | interpreted as defined in [RFC7159]. | |||
| o Inside this document the term "geometry type" refers to the seven | o Inside this document the term "geometry type" refers to the seven | |||
| case-sensitive strings: "Point", "MultiPoint", "LineString", | case-sensitive strings: "Point", "MultiPoint", "LineString", | |||
| skipping to change at page 7, line 17 ¶ | skipping to change at page 7, line 17 ¶ | |||
| A GeoJSON text is a JSON text and consists of a single GeoJSON | A GeoJSON text is a JSON text and consists of a single GeoJSON | |||
| object. | object. | |||
| 3. GeoJSON Object | 3. GeoJSON Object | |||
| A GeoJSON object represents a geometry, feature, or collection of | A GeoJSON object represents a geometry, feature, or collection of | |||
| features. | features. | |||
| o A GeoJSON object is a JSON object. | o A GeoJSON object is a JSON object. | |||
| o A GeoJSON object MUST have a member with the name "type". The | o A GeoJSON object has a member with the name "type". The value of | |||
| value of the member MUST be one of the GeoJSON types. | the member MUST be one of the GeoJSON types. | |||
| o A GeoJSON object MAY have a "bbox" member, the value of which MUST | o A GeoJSON object MAY have a "bbox" member, the value of which MUST | |||
| be a bounding box array (see Section 5). | be a bounding box array (see Section 5). | |||
| o A GeoJSON object MAY have any number of other members (see | o A GeoJSON object MAY have other members (see Section 6). | |||
| Section 6). | ||||
| 3.1. Geometry Object | 3.1. Geometry Object | |||
| A Geometry object represents points, curves, and surfaces in | A Geometry object represents points, curves, and surfaces in | |||
| coordinate space. | coordinate space. Every geometry object is a GeoJSON object no | |||
| matter where it occurs in a GeoJSON text. | ||||
| o The value of a geometry object's "type" member MUST be one of the | o The value of a geometry object's "type" member MUST be one of the | |||
| seven geometry types (see Section 1.4). | seven geometry types (see Section 1.4). | |||
| o A GeoJSON geometry object of any type other than | o A GeoJSON geometry object of any type other than | |||
| "GeometryCollection" MUST have a member with the name | "GeometryCollection" has a member with the name "coordinates". | |||
| "coordinates". The value of the coordinates member is always an | The value of the coordinates member is an array. The structure of | |||
| array. The structure of the elements in this array is determined | the elements in this array is determined by the type of geometry. | |||
| by the type of geometry. GeoJSON processors MAY interpret | GeoJSON processors MAY interpret geometry objects with empty | |||
| geometry objects with empty coordinates arrays as null objects. | coordinates arrays as null objects. | |||
| 3.1.1. Position | 3.1.1. Position | |||
| A position is the fundamental geometry construct. The "coordinates" | A position is the fundamental geometry construct. The "coordinates" | |||
| member of a geometry object is composed of either: | member of a geometry object is composed of either: | |||
| o one position in the case of a Point geometry, | o one position in the case of a Point geometry, | |||
| o an array of positions in the case of a LineString or MultiPoint | o an array of positions in the case of a LineString or MultiPoint | |||
| geometry, | geometry, | |||
| skipping to change at page 8, line 14 ¶ | skipping to change at page 8, line 14 ¶ | |||
| o or an array of Polygon coordinates in the case of a MultiPolygon | o or an array of Polygon coordinates in the case of a MultiPolygon | |||
| geometry. | geometry. | |||
| A position is an array of numbers. There MUST be two or more | A position is an array of numbers. There MUST be two or more | |||
| elements. The first two elements are longitude and latitude, or | elements. The first two elements are longitude and latitude, or | |||
| easting and northing, precisely in that order and using decimal | easting and northing, precisely in that order and using decimal | |||
| numbers. Altitude or elevation MAY be included as an optional third | numbers. Altitude or elevation MAY be included as an optional third | |||
| element. | element. | |||
| Implementations SHOULD NOT extend positions beyond 3 elements. | Implementations SHOULD NOT extend positions beyond 3 elements because | |||
| Parsers MAY ignore additional elements. Interpretation and meaning | the semantics of extra elements are unspecified and ambiguous. | |||
| of additional elements is beyond the scope of this specification. | Historically, some implementations have used a 4th element to carry a | |||
| linear referencing measure (sometimes denoted as "M") or a numerical | ||||
| timestamp, but in most situations a parser will not be able to | ||||
| properly interpret these values. The interpretation and meaning of | ||||
| additional elements is beyond the scope of this specification and | ||||
| additional elements MAY be ignored by parsers. | ||||
| A line between two positions is a straight Cartesian line, the | A line between two positions is a straight Cartesian line, the | |||
| shortest line between those two points in the Coordinate Reference | shortest line between those two points in the Coordinate Reference | |||
| System (see Section 4). | System (see Section 4). | |||
| In other words, every point on a line that does not cross the | In other words, every point on a line that does not cross the | |||
| antimeridian between a point (lon0, lat0) and (lon1, lat1) can be | antimeridian between a point (lon0, lat0) and (lon1, lat1) can be | |||
| calculated as | calculated as | |||
| F(lon, lat) = (lon0 + (lon1 - lon0) * t, lat0 + (lat1 - lat0) * t) | F(lon, lat) = (lon0 + (lon1 - lon0) * t, lat0 + (lat1 - lat0) * t) | |||
| with t a real number greater or equal to 0 and smaller or equal to 1. | with t a real number greater or equal to 0 and smaller or equal to 1. | |||
| Note that this line may markedly differ from the geodesic path along | ||||
| Note that - for example in the WGS 84 datum [WGS84], the default | the curved surface of the reference ellipsoid. | |||
| Coordinate Reference System - this line may markedly differ from the | ||||
| geodesic path along the curved surface of the reference ellipsoid. | ||||
| The same applies to the optional height element with the proviso that | The same applies to the optional height element with the proviso that | |||
| the direction of the height is as specified in the Coordinate | the direction of the height is as specified in the Coordinate | |||
| Reference System. | Reference System. | |||
| Note that, again, using the default WGS 84 datum as a starting point, | Note that, again, this does not mean that a surface with equal height | |||
| this does not mean that a surface with equal height follows, for | follows, for example, the curvature of a body of water. Nor is a | |||
| example, the curvature of a body of water. Nor is a surface of equal | surface of equal height perpendicular to a plumb line. | |||
| height perpendicular to a plumb line. | ||||
| Examples of positions and geometries are provided in "Appendix A. | Examples of positions and geometries are provided in "Appendix A. | |||
| Geometry Examples". | Geometry Examples". | |||
| 3.1.2. Point | 3.1.2. Point | |||
| For type "Point", the "coordinates" member MUST be a single position. | For type "Point", the "coordinates" member is a single position. | |||
| 3.1.3. MultiPoint | 3.1.3. MultiPoint | |||
| For type "MultiPoint", the "coordinates" member MUST be an array of | For type "MultiPoint", the "coordinates" member is an array of | |||
| positions. | positions. | |||
| 3.1.4. LineString | 3.1.4. LineString | |||
| For type "LineString", the "coordinates" member MUST be an array of | For type "LineString", the "coordinates" member is an array of two or | |||
| two or more positions. | more positions. | |||
| 3.1.5. MultiLineString | 3.1.5. MultiLineString | |||
| For type "MultiLineString", the "coordinates" member MUST be an array | For type "MultiLineString", the "coordinates" member is an array of | |||
| of LineString coordinate arrays. | LineString coordinate arrays. | |||
| 3.1.6. Polygon | 3.1.6. Polygon | |||
| To specify a constraint specific to polygons, it is useful to | To specify a constraint specific to polygons, it is useful to | |||
| introduce the concept of a linear ring: | introduce the concept of a linear ring: | |||
| o A linear ring is a closed LineString with 4 or more positions. | o A linear ring is a closed LineString with 4 or more positions. | |||
| o The first and last positions are equivalent, they MUST contain | o The first and last positions are equivalent, they MUST contain | |||
| identical values; their representation SHOULD also be identical. | identical values; their representation SHOULD also be identical. | |||
| o A linear ring is the boundary of a surface or the boundary of a | o A linear ring is the boundary of a surface or the boundary of a | |||
| hole in a surface. | hole in a surface. | |||
| o A linear ring SHOULD follow the right-hand rule with respect to | o A linear ring MUST follow the right-hand rule with respect to the | |||
| the area it bounds (i.e., exterior rings are counter-clockwise, | area it bounds (i.e., exterior rings are counter-clockwise, holes | |||
| holes are clockwise) | are clockwise). | |||
| Note: the [GJ2008] specification did not discuss linear ring winding | ||||
| order. For backwards compatibility, parsers SHOULD NOT reject | ||||
| polygons that do not follow the right-hand rule. | ||||
| Though a linear ring is not explicitly represented as a GeoJSON | Though a linear ring is not explicitly represented as a GeoJSON | |||
| geometry type, it leads to a canonical formulation of the Polygon | geometry type, it leads to a canonical formulation of the Polygon | |||
| geometry type definition as follows: | geometry type definition as follows: | |||
| o For type "Polygon", the "coordinates" member MUST be an array of | o For type "Polygon", the "coordinates" member MUST be an array of | |||
| linear ring coordinate arrays. | linear ring coordinate arrays. | |||
| o For Polygons with more than one of these rings, the first MUST be | o For Polygons with more than one of these rings, the first MUST be | |||
| the exterior ring and any others MUST be interior rings. The | the exterior ring and any others MUST be interior rings. The | |||
| exterior ring bounds the surface, and the interior rings (if | exterior ring bounds the surface, and the interior rings (if | |||
| present) bound holes within the surface. | present) bound holes within the surface. | |||
| 3.1.7. MultiPolygon | 3.1.7. MultiPolygon | |||
| For type "MultiPolygon", the "coordinates" member MUST be an array of | For type "MultiPolygon", the "coordinates" member is an array of | |||
| Polygon coordinate arrays. | Polygon coordinate arrays. | |||
| 3.1.8. Geometry Collection | 3.1.8. Geometry Collection | |||
| A GeoJSON object with type "GeometryCollection" is a geometry object. | A GeoJSON object with type "GeometryCollection" is a geometry object. | |||
| A geometry collection MUST have a member with the name "geometries". | A geometry collection has a member with the name "geometries". The | |||
| The value of "geometries" is an array. Each element of this array is | value of "geometries" is an array. Each element of this array is a | |||
| a GeoJSON geometry object. It is possible for this array to be | GeoJSON geometry object. It is possible for this array to be empty. | |||
| empty. | ||||
| Unlike the other geometry types described above, a geometry | Unlike the other geometry types described above, a geometry | |||
| collection can be a heterogeneous composition of smaller geometry | collection can be a heterogeneous composition of smaller geometry | |||
| objects. For example, a geometry object in the shape of a lowercase | objects. For example, a geometry object in the shape of a lowercase | |||
| roman "i" can be composed of one point and one line string. | roman "i" can be composed of one point and one line string. | |||
| Geometry collections have a different syntax from single type | ||||
| geometry objects (Point, LineString, and Polygon) and homogeneously | ||||
| typed multipart geometry objects (MultiPoint, MultiLineString, and | ||||
| MultiPolygon) but have no different semantics. Although a geometry | ||||
| collection object has no "coordinates" member, it does have | ||||
| coordinates: the coordinates of all its parts belong to the | ||||
| collection. The "geometries" member of a geometry collection | ||||
| describes the parts of this composition. Implementations SHOULD NOT | ||||
| apply any additional semantics to the "geometries" array. | ||||
| To maximize interoperability implementations SHOULD avoid nested | ||||
| geometry collections. Furthermore, geometry collections composed of | ||||
| a single part or a number of parts of a single type SHOULD be avoided | ||||
| when that single part or a single object of multi-part type | ||||
| (MultiPoint, MultiLineString, or MultiPolygon) could be used instead. | ||||
| 3.1.9. Antimeridian Cutting | ||||
| In representing features that cross the antimeridian, | ||||
| interoperability is improved by modifying their geometry. Any | ||||
| geometry that crosses the antimeridian SHOULD be represented by | ||||
| cutting it in two such that neither part's representation crosses the | ||||
| antimeridian. | ||||
| For example, a line extending from 45 degrees N, 170 degrees E across | ||||
| the antimeridian to 45 degrees N, 170 degrees W should be cut in two | ||||
| and represented as a MultiLineString. | ||||
| { | ||||
| "type": "MultiLineString", | ||||
| "coordinates": [ | ||||
| [ | ||||
| [170.0, 45.0], [180.0, 45.0] | ||||
| ], [ | ||||
| [-180.0, 45.0], [-170.0, 45.0] | ||||
| ] | ||||
| ] | ||||
| } | ||||
| A rectangle extending from 40 degrees N, 170 degrees E across the | ||||
| antimeridian to 50 degrees N, 170 degrees W should be cut in two and | ||||
| represented as a MultiPolygon. | ||||
| { | ||||
| "type": "MultiPolygon", | ||||
| "coordinates": [ | ||||
| [ | ||||
| [ | ||||
| [180.0, 40.0], [180.0, 50.0], [170.0, 50.0], | ||||
| [170.0, 40.0], [180.0, 40.0] | ||||
| ] | ||||
| ], | ||||
| [ | ||||
| [ | ||||
| [-170.0, 40.0], [-170.0, 50.0], [-180.0, 50.0], | ||||
| [-180.0, 40.0], [-170.0, 40.0] | ||||
| ] | ||||
| ] | ||||
| ] | ||||
| } | ||||
| 3.1.10. Uncertainty and Precision | ||||
| As in [RFC5870] the number of digits of the values in coordinate | ||||
| positions MUST NOT be interpreted as an indication to the level of | ||||
| uncertainty. | ||||
| 3.2. Feature Object | 3.2. Feature Object | |||
| A Feature object represents a spatially-bounded thing. | A Feature object represents a spatially-bounded thing. Every feature | |||
| object is a GeoJSON object no matter where it occurs in a GeoJSON | ||||
| text. | ||||
| o A feature object MUST have a "type" member with the value | o A feature object has a "type" member with the value "Feature". | |||
| "Feature". | ||||
| o A feature object MUST have a member with the name "geometry". The | o A feature object has a member with the name "geometry". The value | |||
| value of the geometry member SHALL be either a geometry object as | of the geometry member SHALL be either a geometry object as | |||
| defined above or, in the the case that the feature is unlocated, a | defined above or, in the case that the feature is unlocated, a | |||
| JSON null value. | JSON null value. | |||
| o A feature object MUST have a member with the name "properties". | o A feature object has a member with the name "properties". The | |||
| The value of the properties member is an object (any JSON object | value of the properties member is an object (any JSON object or a | |||
| or a JSON null value). | JSON null value). | |||
| o If a feature has a commonly used identifier, that identifier | o If a feature has a commonly used identifier, that identifier | |||
| SHOULD be included as a member of the feature object with the name | SHOULD be included as a member of the feature object with the name | |||
| "id", and the value of this member is either a JSON string or | "id", and the value of this member is either a JSON string or | |||
| number. | number. | |||
| 3.3. Feature Collection Object | 3.3. Feature Collection Object | |||
| A GeoJSON object with the type "FeatureCollection" is a feature | A GeoJSON object with the type "FeatureCollection" is a feature | |||
| collection object. A feature collection object MUST have a member | collection object. A feature collection object has a member with the | |||
| with the name "features". The value of "features" is a JSON array. | name "features". The value of "features" is a JSON array. Each | |||
| Each element of the array is a feature object as defined above. It | element of the array is a feature object as defined above. It is | |||
| is possible for this array to be empty. | possible for this array to be empty. | |||
| 4. Coordinate Reference System | 4. Coordinate Reference System | |||
| The default reference system for all GeoJSON coordinates SHALL be a | The coordinate reference system for all GeoJSON coordinates is a | |||
| geographic coordinate reference system, using the WGS 84 [WGS84] | geographic coordinate reference system, using the WGS 84 [WGS84] | |||
| datum, and with longitude and latitude units of decimal degrees. | datum, and with longitude and latitude units of decimal degrees. | |||
| This coordinate reference system is equivalent to the OGC's "http:// | This is equivalent to the coordinate reference system identified by | |||
| www.opengis.net/def/crs/OGC/1.3/CRS84" [OGCURL]. To maximize | the OGC URN urn:ogc:def:crs:OGC::CRS84. An OPTIONAL third position | |||
| interoperability, GeoJSON data SHOULD use this default coordinate | element SHALL be the height in meters above or below the WGS 84 | |||
| reference system. An OPTIONAL third position element SHALL be the | reference ellipsoid. In the absence of elevation values, | |||
| height in meters above the WGS 84 reference ellipsoid. In the | applications sensitive to height or depth SHOULD interpret positions | |||
| absence of elevation values, applications sensitive to height or | as being at local ground or sea level. | |||
| depth SHOULD interpret positions as being at local ground or sea | ||||
| level. | ||||
| Other coordinate reference systems, including ones described by CRS | Note: the use of alternative coordinate reference systems was | |||
| objects of the kind defined in [GJ2008] are NOT RECOMMENDED. GeoJSON | specified in [GJ2008], but has been removed from this version of the | |||
| processing software SHALL NOT be expected to have access to | specification because the use of different coordinate reference | |||
| coordinate reference systems databases. Applications requiring a CRS | systems -- especially in the manner specified in [GJ2008] -- has | |||
| other than the default MUST assume all responsibility for CRS | proven to have interoperability issues. In general, GeoJSON | |||
| identification, coordinate accuracy, and interpretation of missing | processing software is not expected to have access to coordinate | |||
| elevation values. Furthermore, GeoJSON coordinates MUST NOT under | reference systems databases or to have network access to coordinate | |||
| any circumstances use latitude, longitude order. | reference system transformation parameters. However, where all | |||
| involved parties have a prior arrangement, alternative coordinate | ||||
| reference systems can be used without risk of data being | ||||
| misinterpreted. | ||||
| 5. Bounding Box | 5. Bounding Box | |||
| A GeoJSON object MAY have a member named "bbox" to include | A GeoJSON object MAY have a member named "bbox" to include | |||
| information on the coordinate range for its geometries, features, or | information on the coordinate range for its geometries, features, or | |||
| feature collections. The value of the bbox member MUST be an array | feature collections. The value of the bbox member MUST be an array | |||
| of length 2*n where n is the number of dimensions represented in the | of length 2*n where n is the number of dimensions represented in the | |||
| contained geometries, with all axes of the most south-westerly point | contained geometries, with all axes of the most south-westerly point | |||
| followed by all axes of the more north-easterly point. The axes | followed by all axes of the more north-easterly point. The axes | |||
| order of a bbox follows the axes order of geometries. | order of a bbox follows the axes order of geometries. | |||
| In the default GeoJSON CRS (see Section 4), the "bbox" values define | The "bbox" values define shapes with edges that follow lines of | |||
| shapes with edges that follow lines of constant longitude, latitude, | constant longitude, latitude, and elevation. | |||
| and elevation. | ||||
| Example of a 2D bbox member on a feature: | Example of a 2D bbox member on a feature: | |||
| { | { | |||
| "type": "Feature", | "type": "Feature", | |||
| "bbox": [-10.0, -10.0, 10.0, 10.0], | "bbox": [-10.0, -10.0, 10.0, 10.0], | |||
| "geometry": { | "geometry": { | |||
| "type": "Polygon", | "type": "Polygon", | |||
| "coordinates": [ | "coordinates": [ | |||
| [ | [ | |||
| skipping to change at page 12, line 42 ¶ | skipping to change at page 14, line 13 ¶ | |||
| Example of a 3D bbox member with a depth of 100 meters: | Example of a 3D bbox member with a depth of 100 meters: | |||
| { | { | |||
| "type": "FeatureCollection", | "type": "FeatureCollection", | |||
| "bbox": [100.0, 0.0, -100.0, 105.0, 1.0, 0.0], | "bbox": [100.0, 0.0, -100.0, 105.0, 1.0, 0.0], | |||
| "features": [ | "features": [ | |||
| //... | //... | |||
| ] | ] | |||
| } | } | |||
| 5.1. The connecting lines | 5.1. The Connecting Lines | |||
| The 4 lines of the bounding box are defined fully within the | The 4 lines of the bounding box are defined fully within the | |||
| coordinate reference system; i.e. every point on the northernmost | coordinate reference system; i.e. for a box bounded by the values | |||
| "west", "south", "east", and "north" every point on the northernmost | ||||
| line can be expressed as | line can be expressed as | |||
| (lon, lat) = (%minlon% + (%maxlon% - %minlon%) * t, %maxlat%) | (lon, lat) = (west + (east - west) * t, north) | |||
| with 0 <= t <= 1. | with 0 <= t <= 1. | |||
| 5.2. The Antimeridian | 5.2. The Antimeridian | |||
| Consider a set of point features within the Fiji archipelago, | Consider a set of point features within the Fiji archipelago, | |||
| straddling the antimeridian between 16 degrees S and 20 degrees S. | straddling the antimeridian between 16 degrees S and 20 degrees S. | |||
| The southwest corner of the box containing these features is at 20 | The southwest corner of the box containing these features is at 20 | |||
| degrees S and 177 degrees E, the northwest corner is at 16 degrees S | degrees S and 177 degrees E, the northwest corner is at 16 degrees S | |||
| and 178 degrees W. In the default GeoJSON CRS (see Section 4) the | and 178 degrees W. The antimeridian-spanning GeoJSON bounding box | |||
| antimeridian-spanning GeoJSON bounding box for this feature | for this feature collection is | |||
| collection is | ||||
| "bbox": [177.0, -20.0, -178.0, -16.0] | "bbox": [177.0, -20.0, -178.0, -16.0] | |||
| and covers 5 degrees of longitude. | and covers 5 degrees of longitude. | |||
| The complementary bounding box for the same latitude band, not | The complementary bounding box for the same latitude band, not | |||
| crossing the antimeridian, is | crossing the antimeridian, is | |||
| "bbox": [-178.0, -20.0, 177.0, -16.0] | "bbox": [-178.0, -20.0, 177.0, -16.0] | |||
| and covers 355 degrees of longitude. | and covers 355 degrees of longitude. | |||
| The latitude of the northeast corner is always greater than the | The latitude of the northeast corner is always greater than the | |||
| latitude of the southwest corner, but bounding boxes that cross the | latitude of the southwest corner, but bounding boxes that cross the | |||
| antimeridian have a northeast corner longitude that is less than the | antimeridian have a northeast corner longitude that is less than the | |||
| longitude of the southwest corner. | longitude of the southwest corner. | |||
| 5.3. The Poles | 5.3. The Poles | |||
| In the default GeoJSON CRS (see Section 4), a bounding box that | A bounding box that contains the North Pole extends from a southwest | |||
| contains the North Pole extends from a southwest corner of %minlat% | corner of "minlat" degrees N, 180 degrees W to a northeast corner of | |||
| degrees N, 180 degrees W to a northeast corner of 90 degrees N, 180 | 90 degrees N, 180 degrees E. Viewed on a globe, this bounding box | |||
| degrees E. Viewed on a globe, this bounding box approximates a | approximates a spherical cap bounded by the "minlat" circle of | |||
| spherical cap. | latitude. | |||
| "bbox": [-180.0, %minlat%, 180.0, 90.0] | "bbox": [-180.0, minlat, 180.0, 90.0] | |||
| A bounding box that contains the South Pole extends from a southwest | A bounding box that contains the South Pole extends from a southwest | |||
| corner of 90 degrees S, 180 degrees W to a northeast corner of | corner of 90 degrees S, 180 degrees W to a northeast corner of | |||
| %maxlat% degrees S, 180 degrees E. | "maxlat" degrees S, 180 degrees E. | |||
| "bbox": [-180.0, -90.0, 180.0, %maxlat%] | "bbox": [-180.0, -90.0, 180.0, maxlat] | |||
| A bounding box that just touches the North Pole and forms a slice of | A bounding box that just touches the North Pole and forms a slice of | |||
| an approximate spherical cap when viewed on a globe has as its | an approximate spherical cap when viewed on a globe extends from a | |||
| northeast corner coordinates the easternmost longitude value and 90 | southwest corner of "minlat" degrees N and "westlon" degrees E to a | |||
| degrees N. | northeast corner of 90 degrees N and "eastlon" degrees E. | |||
| "bbox": [%westlon%, %minlat%, %eastlon%, 90.0] | "bbox": [westlon, minlat, eastlon, 90.0] | |||
| A bounding box that just touches the South Pole and forms a slice of | ||||
| an approximate spherical cap when viewed on a globe has as its | ||||
| southwest corner coordinates the westernmost longitude value and 90 | ||||
| degrees S. | ||||
| "bbox": [%westlon%, -90.0, %eastlon%, %maxlat%] | Similarly, a bounding box that just touches the South Pole and forms | |||
| a slice of an approximate spherical cap when viewed on a globe has | ||||
| the following representation in GeoJSON. | ||||
| "bbox": [westlon, -90.0, eastlon, maxlat] | ||||
| Implementers MUST NOT use latitude values greater than 90 or less | Implementers MUST NOT use latitude values greater than 90 or less | |||
| than -90 when using the default GeoJSON coordinate reference system | than -90 to imply an extent that is not a spherical cap. | |||
| to imply an extent that is not a spherical cap. | ||||
| 6. Extending GeoJSON | 6. Extending GeoJSON | |||
| 6.1. Foreign members | 6.1. Foreign Members | |||
| Members not described in this specification ("foreign members") MAY | Members not described in this specification ("foreign members") MAY | |||
| be used in a GeoJSON document. Note that support for foreign members | be used in a GeoJSON document. Note that support for foreign members | |||
| can vary across implementations and no normative processing model for | can vary across implementations and no normative processing model for | |||
| foreign members is defined. Accordingly, implementations that rely | foreign members is defined. Accordingly, implementations that rely | |||
| too heavily on the use of foreign members might experience reduced | too heavily on the use of foreign members might experience reduced | |||
| interoperability with other implementations. | interoperability with other implementations. | |||
| For example, in the (abridged) feature object shown below | For example, in the (abridged) feature object shown below | |||
| { | { | |||
| "type": "Feature", | "type": "Feature", | |||
| "id": "f1", | "id": "f1", | |||
| "geometry": {...}, | "geometry": {...}, | |||
| "properties": {...}, | "properties": {...}, | |||
| "title": "Example Feature" | "title": "Example Feature" | |||
| } | } | |||
| the name/value pair of "title": "Example Feature" is a foreign | the name/value pair of "title": "Example Feature" is a foreign | |||
| member. When the value of a foreign member is an object, all the | member. When the value of a foreign member is an object, all the | |||
| skipping to change at page 15, line 4 ¶ | skipping to change at page 16, line 19 ¶ | |||
| "title": "Example Feature" | "title": "Example Feature" | |||
| } | } | |||
| the name/value pair of "title": "Example Feature" is a foreign | the name/value pair of "title": "Example Feature" is a foreign | |||
| member. When the value of a foreign member is an object, all the | member. When the value of a foreign member is an object, all the | |||
| descendant members of that object are themselves foreign members. | descendant members of that object are themselves foreign members. | |||
| GeoJSON semantics do not apply to foreign members and their | GeoJSON semantics do not apply to foreign members and their | |||
| descendants, regardless of their names and values. For example, in | descendants, regardless of their names and values. For example, in | |||
| the (abridged) feature object below | the (abridged) feature object below | |||
| { | { | |||
| "type": "Feature", | "type": "Feature", | |||
| "id": "f2", | "id": "f2", | |||
| "geometry": {...}, | "geometry": {...}, | |||
| "properties": {...}, | "properties": {...}, | |||
| "centerline": { | "centerline": { | |||
| "type": "LineString", | "type": "LineString", | |||
| "coordinates": [ | "coordinates": [ | |||
| [-170, 10], | [-170, 10], | |||
| [170, 11] | [170, 11] | |||
| ] | ] | |||
| } | } | |||
| } | } | |||
| the "centerline" member is not a GeoJSON geometry object. | the "centerline" member is not a GeoJSON geometry object. | |||
| 6.2. GeoJSON types are not extensible | 7. GeoJSON Types are not Extensible | |||
| Implementations MUST NOT extend the fixed set of GeoJSON types: | Implementations MUST NOT extend the fixed set of GeoJSON types: | |||
| FeatureCollection, Feature, Point, LineString, MultiPoint, Polygon, | FeatureCollection, Feature, Point, LineString, MultiPoint, Polygon, | |||
| MultiLineString, MultiPolygon, and GeometryCollection. | MultiLineString, MultiPolygon, and GeometryCollection. | |||
| 6.3. Semantics of GeoJSON members and types are not changeable | 7.1. Semantics of GeoJSON Members and Types are not Changeable | |||
| Implementations MUST NOT change the the semantics of GeoJSON members | Implementations MUST NOT change the semantics of GeoJSON members and | |||
| and types. | types. | |||
| The GeoJSON "coordinates" and "geometries" members define Geometry | The GeoJSON "coordinates" and "geometries" members define Geometry | |||
| objects. FeatureCollection and Feature objects, respectively, MUST | objects. FeatureCollection and Feature objects, respectively, MUST | |||
| NOT contain a "coordinates" or "geometries" member. | NOT contain a "coordinates" or "geometries" member. | |||
| The GeoJSON "geometry" and "properties" members define a Feature | The GeoJSON "geometry" and "properties" members define a Feature | |||
| object. FeatureCollection and Geometry objects, respectively, MUST | object. FeatureCollection and Geometry objects, respectively, MUST | |||
| NOT contain a "geometry" or "properties" member. | NOT contain a "geometry" or "properties" member. | |||
| The GeoJSON "features" member defines a FeatureCollection object. | The GeoJSON "features" member defines a FeatureCollection object. | |||
| Feature and Geometry objects, respectively, MUST NOT contain a | Feature and Geometry objects, respectively, MUST NOT contain a | |||
| "features" member. | "features" member. | |||
| 7. Versioning | 8. Versioning | |||
| The GeoJSON format can be extended as defined here, but no explicit | The GeoJSON format can be extended as defined here, but no explicit | |||
| versioning scheme is defined. A specification that alters the | versioning scheme is defined. A specification that alters the | |||
| semantics of GeoJSON members or otherwise modifies the format does | semantics of GeoJSON members or otherwise modifies the format does | |||
| not create a new version of this format; instead, it defines an | not create a new version of this format; instead, it defines an | |||
| entirely new format that MUST NOT be identified as GeoJSON. | entirely new format that MUST NOT be identified as GeoJSON. | |||
| 8. Mapping 'geo' URIs | 9. Mapping 'geo' URIs | |||
| 'geo' URIs [RFC5870] identify geographic locations and precise (not | 'geo' URIs [RFC5870] identify geographic locations and precise (not | |||
| uncertain) locations can be mapped to GeoJSON geometry objects. | uncertain) locations can be mapped to GeoJSON geometry objects. | |||
| For this section, as in [RFC5870], "%lat%", "%lon%", "%alt%", and | For this section, as in [RFC5870], "lat", "lon", "alt", and "unc" are | |||
| "%unc%" are placeholders for 'geo' URI latitude, longitude, altitude, | placeholders for 'geo' URI latitude, longitude, altitude, and | |||
| and uncertainty values, respectively. | uncertainty values, respectively. | |||
| A 'geo' URI with two coordinates and an uncertainty ('u') parameter | A 'geo' URI with two coordinates and an uncertainty ('u') parameter | |||
| that is absent or zero, and a GeoJSON Point geometry may be mapped to | that is absent or zero, and a GeoJSON Point geometry may be mapped to | |||
| each other. A GeoJSON point is always converted to a 'geo' URI that | each other. A GeoJSON point is always converted to a 'geo' URI that | |||
| has no uncertainty parameter. | has no uncertainty parameter. | |||
| 'geo' URI: | 'geo' URI: | |||
| geo:%lat%,%lon% | geo:lat,lon | |||
| GeoJSON: | GeoJSON: | |||
| {"type": "Point", "coordinates": [%lon%, %lat%]} | {"type": "Point", "coordinates": [lon, lat]} | |||
| The mapping between 'geo' URIs and GeoJSON points that specify | The mapping between 'geo' URIs and GeoJSON points that specify | |||
| elevation is shown below. | elevation is shown below. | |||
| 'geo' URI: | 'geo' URI: | |||
| geo:%lat%,%lon%,%alt% | geo:lat,lon,alt | |||
| GeoJSON: | GeoJSON: | |||
| {"type": "Point", "coordinates": [%lon%, %lat%, %alt%]} | {"type": "Point", "coordinates": [lon, lat, alt]} | |||
| GeoJSON has no concept of uncertainty; imprecise or uncertain 'geo' | GeoJSON has no concept of uncertainty; imprecise or uncertain 'geo' | |||
| URIs thus can not be mapped to GeoJSON geometries. | URIs thus cannot be mapped to GeoJSON geometries. | |||
| 9. Security Considerations | 10. Security Considerations | |||
| GeoJSON shares security issues common to all JSON content types. See | GeoJSON shares security issues common to all JSON content types. See | |||
| [RFC7159] Section 12 for additional information. GeoJSON does not | [RFC7159] Section 12 for additional information. GeoJSON does not | |||
| provide executable content. | provide executable content. | |||
| GeoJSON does not provide privacy or integrity services. If sensitive | ||||
| data requires privacy or integrity protection, those must be provided | ||||
| by the transport -- for example TLS or HTTPS. There will be cases in | ||||
| which stored data need protection, which is out of scope for this | ||||
| document. | ||||
| As with other geographic data formats, e.g., [KMLv2.2], providing | As with other geographic data formats, e.g., [KMLv2.2], providing | |||
| details about the locations of sensitive persons, animals, habitats, | details about the locations of sensitive persons, animals, habitats, | |||
| and facilities can expose them to unauthorized tracking or injury. | and facilities can expose them to unauthorized tracking or injury. | |||
| GeoJSON does not provide privacy or integrity services; if sensitive | Data providers should recognize the risk of inadvertantly identifying | |||
| data requires privacy or integrity protection the service must be | individuals if locations in anonymized datasets are not adequately | |||
| provided externally. | skewed or not sufficiently fuzzed [Sweeney] and recognize that the | |||
| effectiveness of location obscuration is limited by a number of | ||||
| factors and is unlikely to be an effective defense against a | ||||
| determined attack [RFC6772]. | ||||
| 10. Interoperability Considerations | 11. Interoperability Considerations | |||
| 10.1. I-JSON | 11.1. I-JSON | |||
| GeoJSON texts SHOULD follow the constraints of I-JSON [RFC7493] for | GeoJSON texts should follow the constraints of I-JSON [RFC7493] for | |||
| maximum interoperability. | maximum interoperability. | |||
| 10.2. Coordinate Precision | 11.2. Coordinate Precision | |||
| The size of a GeoJSON text in bytes is a major interoperability | The size of a GeoJSON text in bytes is a major interoperability | |||
| consideration and precision of coordinate values has a large impact | consideration and precision of coordinate values has a large impact | |||
| on the size of texts. A GeoJSON text containing many detailed | on the size of texts. A GeoJSON text containing many detailed | |||
| polygons can be inflated almost by a factor of two by increasing | polygons can be inflated almost by a factor of two by increasing | |||
| coordinate precision from 6 to 15 decimal places. For geographic | coordinate precision from 6 to 15 decimal places. For geographic | |||
| coordinates with units of degrees, 6 decimal places (a default common | coordinates with units of degrees, 6 decimal places (a default common | |||
| in, e.g., sprintf) amounts to about 10 centimeters, a precision well | in, e.g., sprintf) amounts to about 10 centimeters, a precision well | |||
| within that of current GPS systems. Implementations should consider | within that of current GPS systems. Implementations should consider | |||
| the cost of using a greater precision than necessary. | the cost of using a greater precision than necessary. | |||
| Furthermore the default WGS 84 [WGS84] datum uses a relatively coarse | Furthermore the WGS 84 [WGS84] datum is a relatively coarse | |||
| geoid; with the WGS 84 [WGS84] height varying by up to 5m (but | approximation of the geoid; with the height varying by up to 5m (but | |||
| generally between 2 and 3 meters) higher or lower relative to a | generally between 2 and 3 meters) higher or lower relative to a | |||
| surface parallel to Earth's mean sea level. | surface parallel to Earth's mean sea level. | |||
| 10.3. Coordinate Order | 12. IANA Considerations | |||
| There are conflicting precedents among geographic data formats over | ||||
| whether latitude or longitude come first in a pair of numbers. | ||||
| Longitude comes first in GeoJSON coordinates as it does in [KMLv2.2]. | ||||
| Some commonly-used CRS definitions specify coordinate ordering that | ||||
| is not longitude then latitude (for a geographic CRS) or easting then | ||||
| northing (for a projected CRS). The CRS historically known as | ||||
| "EPSG:4326" and more accurately identified by "http://www.opengis.net | ||||
| /def/crs/EPSG/0/4326" is a prime example. Using such a CRS is NOT | ||||
| RECOMMENDED due to the potential disruption of interoperability. | ||||
| When such a CRS is encountered in GeoJSON, the document should be | ||||
| processed with caution. Heuristics may be necessary to interpret the | ||||
| coordinates properly; they may not be in the required longitude, | ||||
| latitude order. | ||||
| 10.4. Antimeridian cutting | ||||
| In representing features that cross the antimeridian, | ||||
| interoperability is improved by cutting geometries so that no single | ||||
| part crosses the antimeridian. For example, a line extending from 45 | ||||
| degrees N, 170 degrees E across the antimeridian to 45 degrees N, 170 | ||||
| degrees W SHOULD be cut in two and represented as a MultiLineString. | ||||
| { | ||||
| "type": "MultiLineString", | ||||
| "coordinates": [ | ||||
| [ | ||||
| [170.0, 45.0], [180.0, 45.0] | ||||
| ], [ | ||||
| [-180.0, 45.0], [-170.0, 45.0] | ||||
| ] | ||||
| ] | ||||
| } | ||||
| A rectangle extending from 40 degrees N, 170 degrees E across the | ||||
| antimeridian to 50 degrees N, 170 degrees W SHOULD be cut in two and | ||||
| represented as a MultiPolygon. | ||||
| { | ||||
| "type": "MultiPolygon", | ||||
| "coordinates": [ | ||||
| [ | ||||
| [ | ||||
| [180.0, 40.0], [180.0, 50.0], [170.0, 50.0], | ||||
| [170.0, 40.0], [180.0, 40.0] | ||||
| ] | ||||
| ], | ||||
| [ | ||||
| [ | ||||
| [-170.0, 40.0], [-170.0, 50.0], [-180.0, 50.0], | ||||
| [-180.0, 40.0], [-170.0, 40.0] | ||||
| ] | ||||
| ] | ||||
| ] | ||||
| } | ||||
| 10.5. Geometry Collections | ||||
| Geometry collections have a different syntax from single type | ||||
| geometry objects (Point, LineString, and Polygon) and homogeneously | ||||
| typed multipart geometry objects (MultiPoint, MultiLineString, and | ||||
| MultiPolygon) but have no different semantics. Although a geometry | ||||
| collection object has no "coordinates" member, it does have | ||||
| coordinates: the coordinates of all its parts belong to the | ||||
| collection. The "geometries" member of a geometry collection | ||||
| describes the parts of this composition. Implementations SHOULD NOT | ||||
| apply any additional semantics to the "geometries" array. | ||||
| To maximize interoperability implementations SHOULD avoid nested | ||||
| geometry collections. Furthermore, geometry collections composed of | ||||
| a single part or a number of parts of a single type SHOULD be avoided | ||||
| when that single part or a single object of multi-part type | ||||
| (MultiPoint, MultiLineString, or MultiPolygon) could be used instead. | ||||
| 11. IANA Considerations | ||||
| The media type for GeoJSON text is "application/geo+json" and is | The media type for GeoJSON text is "application/geo+json" and is | |||
| registered in the "Media Types" registry described in [RFC6838]. The | registered in the "Media Types" registry described in [RFC6838]. The | |||
| entry for "application/vnd.geo+json" in the same registry should have | entry for "application/vnd.geo+json" in the same registry should have | |||
| its status changed to be Obsolete with a pointer to the media type | its status changed to be Obsolete with a pointer to the media type | |||
| "application/geo+json" and a reference added to this RFC. | "application/geo+json" and a reference added to this RFC. | |||
| Type name: application | Type name: application | |||
| Subtype name: geo+json | Subtype name: geo+json | |||
| Required parameters: n/a | Required parameters: n/a | |||
| Optional parameters: n/a | Optional parameters: n/a | |||
| Encoding considerations: binary | Encoding considerations: binary | |||
| Security considerations: See section 9 above | Security considerations: See Section 10 above | |||
| Interoperability considerations: See section 10 above | Interoperability considerations: See Section 11 above | |||
| Published specification: [[This document]] | Published specification: [[This document]] | |||
| Applications that use this media type: various | Applications that use this media type: No known applications | |||
| currently use this media type. This media type is intended for | ||||
| GeoJSON applications currently using the "application/ | ||||
| vnd.geo+json" or "application/json" media types, of which there | ||||
| are several categories: web mapping, geospatial databases, | ||||
| geographic data processing APIs, data analysis and storage | ||||
| services, and data dissemination. | ||||
| Additional information: | Additional information: | |||
| Magic number(s): n/a | Magic number(s): n/a | |||
| File extension(s): .json, .geojson | File extension(s): .json, .geojson | |||
| Macintosh file type code: n/a | Macintosh file type code: n/a | |||
| Object Identifiers: n/a | Object Identifiers: n/a | |||
| skipping to change at page 20, line 4 ¶ | skipping to change at page 20, line 9 ¶ | |||
| Windows clipboard name: GeoJSON | Windows clipboard name: GeoJSON | |||
| Macintosh uniform type identifier: public.geojson conforms to | Macintosh uniform type identifier: public.geojson conforms to | |||
| public.json | public.json | |||
| Person to contact for further information: Sean Gillies | Person to contact for further information: Sean Gillies | |||
| (sean.gillies@gmail.com) | (sean.gillies@gmail.com) | |||
| Intended usage: COMMON | Intended usage: COMMON | |||
| Restrictions on usage: none | Restrictions on usage: none | |||
| 12. References | Restrictions on usage: none | |||
| 12.1. Normative References | Author: see "Authors' Addresses" section of [[This document]]. | |||
| Change controller: Internet Engineering Task Force | ||||
| 13. Acknowledgements | ||||
| The GeoJSON format is the product of discussion on the GeoJSON | ||||
| mailing list, http://lists.geojson.org/listinfo.cgi/geojson- | ||||
| geojson.org, before October 2015 and the IETF's GeoJSON WG after | ||||
| October 2015. | ||||
| Material in this document was adapted with changes from | ||||
| http://geojson.org/geojson-spec.html [GJ2008] which is licensed under | ||||
| http://creativecommons.org/licenses/by/3.0/us/. | ||||
| 14. References | ||||
| 14.1. Normative References | ||||
| [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | |||
| Requirement Levels", BCP 14, RFC 2119, March 1997. | Requirement Levels", BCP 14, RFC 2119, March 1997. | |||
| [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type | [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type | |||
| Specifications and Registration Procedures", BCP 13, RFC | Specifications and Registration Procedures", BCP 13, | |||
| 6838, DOI 10.17487/RFC6838, January 2013, | RFC 6838, DOI 10.17487/RFC6838, January 2013, | |||
| <http://www.rfc-editor.org/info/rfc6838>. | <http://www.rfc-editor.org/info/rfc6838>. | |||
| [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data | [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data | |||
| Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March | Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March | |||
| 2014, <http://www.rfc-editor.org/info/rfc7159>. | 2014, <http://www.rfc-editor.org/info/rfc7159>. | |||
| [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, DOI | [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, | |||
| 10.17487/RFC7493, March 2015, | DOI 10.17487/RFC7493, March 2015, | |||
| <http://www.rfc-editor.org/info/rfc7493>. | <http://www.rfc-editor.org/info/rfc7493>. | |||
| [WGS84] National Imagery and Mapping Agency, "Department of | [WGS84] National Imagery and Mapping Agency, "Department of | |||
| Defense World Geodetic System 1984, Third Edition", 1984. | Defense World Geodetic System 1984, Third Edition", 1984. | |||
| 12.2. Informative References | 14.2. Informative References | |||
| [GJ2008] Butler, H., Daly, M., Doyle, A., Gillies, S., Schaub, T., | [GJ2008] Butler, H., Daly, M., Doyle, A., Gillies, S., Schaub, T., | |||
| and C. Schmidt, "The GeoJSON Format Specification", June | and C. Schmidt, "The GeoJSON Format Specification", June | |||
| 2008. | 2008. | |||
| [KMLv2.2] Wilson, T., "OGC KML", OGC 07-147r2, April 2008. | [KMLv2.2] Wilson, T., "OGC KML", OGC 07-147r2, April 2008. | |||
| [OGCURL] Cox, S., "OGC-NA Name type specification - definitions: | [RFC6772] Schulzrinne, H., Ed., Tschofenig, H., Ed., Cuellar, J., | |||
| Part 1 - basic name", OGC 09-048r3, March 2010. | Polk, J., Morris, J., and M. Thomson, "Geolocation Policy: | |||
| A Document Format for Expressing Privacy Preferences for | ||||
| Location Information", RFC 6772, DOI 10.17487/RFC6772, | ||||
| January 2013, <http://www.rfc-editor.org/info/rfc6772>. | ||||
| [RFC7464] Williams, N., "JavaScript Object Notation (JSON) Text | [RFC7464] Williams, N., "JavaScript Object Notation (JSON) Text | |||
| Sequences", RFC 7464, DOI 10.17487/RFC7464, February 2015, | Sequences", RFC 7464, DOI 10.17487/RFC7464, February 2015, | |||
| <http://www.rfc-editor.org/info/rfc7464>. | <http://www.rfc-editor.org/info/rfc7464>. | |||
| [SFSQL] OpenGIS Consortium, Inc., "OpenGIS Simple Features | [SFSQL] OpenGIS Consortium, Inc., "OpenGIS Simple Features | |||
| Specification For SQL Revision 1.1", OGC 99-049, May 1999. | Specification For SQL Revision 1.1", OGC 99-049, May 1999. | |||
| [Sweeney] Sweeney, L., "k-anonymity: a model for protecting | ||||
| privacy", International Journal on Uncertainty, Fuzziness | ||||
| and Knowledge-based Systems 10 (5), 2002; 557-570, 2002. | ||||
| [WFSv1] Vretanos, P., "Web Feature Service Implementation | [WFSv1] Vretanos, P., "Web Feature Service Implementation | |||
| Specification", OGC 02-058, May 2002. | Specification", OGC 02-058, May 2002. | |||
| Appendix A. Geometry Examples | Appendix A. Geometry Examples | |||
| Each of the examples below represents a valid and complete GeoJSON | Each of the examples below represents a valid and complete GeoJSON | |||
| object. | object. | |||
| A.1. Points | A.1. Points | |||
| skipping to change at page 25, line 19 ¶ | skipping to change at page 26, line 19 ¶ | |||
| "coordinates": [100.0, 0.0] | "coordinates": [100.0, 0.0] | |||
| }, { | }, { | |||
| "type": "LineString", | "type": "LineString", | |||
| "coordinates": [ | "coordinates": [ | |||
| [101.0, 0.0], | [101.0, 0.0], | |||
| [102.0, 1.0] | [102.0, 1.0] | |||
| ] | ] | |||
| }] | }] | |||
| } | } | |||
| Appendix B. Changes from pre-IETF specification | Appendix B. Changes from pre-IETF Specification | |||
| This appendix briefly summarizes non-editorial changes from the 2008 | This appendix briefly summarizes non-editorial changes from the 2008 | |||
| specification [GJ2008]. | specification [GJ2008]. | |||
| B.1. Normative changes | B.1. Normative Changes | |||
| o Coordinate reference systems other than the default are NOT | o Specification of coordinate reference systems has been removed, | |||
| RECOMMENDED (see Section 4). | i.e., the "crs" member of [GJ2008] is no longer used. | |||
| o In the absence of elevation values, applications sensitive to | o In the absence of elevation values, applications sensitive to | |||
| height or depth SHOULD interpret positions as being at local | height or depth SHOULD interpret positions as being at local | |||
| ground or sea level (see Section 4). | ground or sea level (see Section 4). | |||
| o Implementations SHOULD NOT extend position arrays beyond 3 | o Implementations SHOULD NOT extend position arrays beyond 3 | |||
| elements (see Section 3.1.1). | elements (see Section 3.1.1). | |||
| o A line between two positions is a straight Cartesian line (see | o A line between two positions is a straight Cartesian line (see | |||
| Section 3.1.1). | Section 3.1.1). | |||
| o The values of a "bbox" array are "[%west%, %south%, %east%, | o Polygon rings MUST follow the right-hand rule for orientation | |||
| %north%]", not "[%minx%, %miny%, %maxx%, %maxy%]" (see Section 5). | (counter-clockwise external rings, clockwise internal rings). | |||
| o The values of a "bbox" array are "[west, south, east, north]", not | ||||
| "[minx, miny, maxx, maxy]" (see Section 5). | ||||
| o A Feature object's "id" member is a string or number (see | o A Feature object's "id" member is a string or number (see | |||
| Section 3.2). | Section 3.2). | |||
| o Extensions MAY be used, but MUST NOT change the the semantics of | o Extensions MAY be used, but MUST NOT change the semantics of | |||
| GeoJSON members and types (see Section 6). | GeoJSON members and types (see Section 6). | |||
| o GeoJSON objects MUST NOT contain the defining members of other | o GeoJSON objects MUST NOT contain the defining members of other | |||
| types (see Section 6.3). | types (see Section 7.1). | |||
| o The media type for GeoJSON is application/geo+json. | o The media type for GeoJSON is application/geo+json. | |||
| B.2. Informative changes | B.2. Informative Changes | |||
| o The definition of a GeoJSON text has been added. | o The definition of a GeoJSON text has been added. | |||
| o Rules for mapping 'geo' URIs have been added. | o Rules for mapping 'geo' URIs have been added. | |||
| o A recommendation of the I-JSON [RFC7493] constraints has been | o A recommendation of the I-JSON [RFC7493] constraints has been | |||
| added. | added. | |||
| o Implementers are cautioned about the effect of excessive | o Implementers are cautioned about the effect of excessive | |||
| coordinate precision on interoperability. | coordinate precision on interoperability. | |||
| o Right-hand rule orientation of polygon rings (counter-clockwise | ||||
| external rings, clockwise internal rings) is recommended to | ||||
| improve interoperability. | ||||
| o Interoperability concerns of geometry collections are noted. | o Interoperability concerns of geometry collections are noted. | |||
| These objects should be used sparingly (see Section 10.5). | These objects should be used sparingly (see Section 3.1.8). | |||
| Appendix C. GeoJSON Text Sequences | Appendix C. GeoJSON Text Sequences | |||
| All GeoJSON objects defined in this specification - | All GeoJSON objects defined in this specification - | |||
| FeatureCollection, Feature, and Geometry - consist of exactly one | FeatureCollection, Feature, and Geometry - consist of exactly one | |||
| JSON object. However, there may be circumstances in which | JSON object. However, there may be circumstances in which | |||
| applications need to represent sets or sequences of these objects | applications need to represent sets or sequences of these objects | |||
| (over and above the grouping of Feature objects in a | (over and above the grouping of Feature objects in a | |||
| FeatureCollection), e.g. in order to efficiently "stream" large | FeatureCollection), e.g. in order to efficiently "stream" large | |||
| numbers of Feature objects. The definition of such sets or sequences | numbers of Feature objects. The definition of such sets or sequences | |||
| is outside the scope of this specification. | is outside the scope of this specification. | |||
| If such a representation is needed, a new media type is required that | If such a representation is needed, a new media type is required that | |||
| has the ability to represent these sets or sequences. When defining | has the ability to represent these sets or sequences. When defining | |||
| such a media type, it may be useful to base it on "JSON Text | such a media type, it may be useful to base it on "JSON Text | |||
| Sequences" [RFC7464], leaving the foundations of how to represent | Sequences" [RFC7464], leaving the foundations of how to represent | |||
| multiple JSON objects to that specification, and only defining how it | multiple JSON objects to that specification, and only defining how it | |||
| applies to GeoJSON objects. | applies to GeoJSON objects. | |||
| Appendix D. Contributors | ||||
| The GeoJSON format is the product of discussion on the GeoJSON | ||||
| mailing list, http://lists.geojson.org/listinfo.cgi/geojson- | ||||
| geojson.org, before October 2015 and the IETF's GeoJSON WG after | ||||
| October 2015. | ||||
| Comments are solicited and should be addressed to the GeoJSON mailing | ||||
| list at geojson@ietf.org or to the GeoJSON issue tracker at https:// | ||||
| github.com/geojson/draft-geojson/issues. | ||||
| Authors' Addresses | Authors' Addresses | |||
| H. Butler | H. Butler | |||
| Hobu Inc. | Hobu Inc. | |||
| Email: howard@hobu.co | Email: howard@hobu.co | |||
| M. Daly | M. Daly | |||
| Cadcorp | Cadcorp | |||
| skipping to change at page 27, line 16 ¶ | skipping to change at page 28, line 4 ¶ | |||
| H. Butler | H. Butler | |||
| Hobu Inc. | Hobu Inc. | |||
| Email: howard@hobu.co | Email: howard@hobu.co | |||
| M. Daly | M. Daly | |||
| Cadcorp | Cadcorp | |||
| Email: martin.daly@cadcorp.com | Email: martin.daly@cadcorp.com | |||
| A. Doyle | A. Doyle | |||
| MIT | ||||
| Email: adoyle@intl-interfaces.com | Email: adoyle@intl-interfaces.com | |||
| S. Gillies | S. Gillies | |||
| Mapbox Inc. | Mapbox | |||
| Email: sean.gillies@gmail.com | Email: sean.gillies@gmail.com | |||
| URI: http://sgillies.net | URI: http://sgillies.net | |||
| T. Schaub | ||||
| Planet Labs | ||||
| Email: tim.schaub@gmail.com | ||||
| S. Hagen | S. Hagen | |||
| Rheinaustr. 62 | Rheinaustr. 62 | |||
| Bonn 53225 | Bonn 53225 | |||
| DE | DE | |||
| Email: stefan@hagen.link | Email: stefan@hagen.link | |||
| URI: http://stefan-hagen.website/ | URI: http://stefan-hagen.website/ | |||
| T. Schaub | ||||
| Planet Labs | ||||
| Email: tim.schaub@gmail.com | ||||
| End of changes. 97 change blocks. | ||||
| 291 lines changed or deleted | 306 lines changed or added | |||
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ | ||||