From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc7946.txt | 1571 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1571 insertions(+) create mode 100644 doc/rfc/rfc7946.txt (limited to 'doc/rfc/rfc7946.txt') diff --git a/doc/rfc/rfc7946.txt b/doc/rfc/rfc7946.txt new file mode 100644 index 0000000..109adb8 --- /dev/null +++ b/doc/rfc/rfc7946.txt @@ -0,0 +1,1571 @@ + + + + + + +Internet Engineering Task Force (IETF) H. Butler +Request for Comments: 7946 Hobu Inc. +Category: Standards Track M. Daly +ISSN: 2070-1721 Cadcorp + A. Doyle + + S. Gillies + Mapbox + S. Hagen + + T. Schaub + Planet Labs + August 2016 + + + The GeoJSON Format + +Abstract + + GeoJSON is a geospatial data interchange format based on JavaScript + Object Notation (JSON). It defines several types of JSON objects and + the manner in which they are combined to represent data about + geographic features, their properties, and their spatial extents. + GeoJSON uses a geographic coordinate reference system, World Geodetic + System 1984, and units of decimal degrees. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc7946. + + + + + + + + + + + + +Butler, et al. Standards Track [Page 1] + +RFC 7946 GeoJSON August 2016 + + +Copyright Notice + + Copyright (c) 2016 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 + 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 4 + 1.2. Conventions Used in This Document . . . . . . . . . . . . 4 + 1.3. Specification of GeoJSON . . . . . . . . . . . . . . . . 4 + 1.4. Definitions . . . . . . . . . . . . . . . . . . . . . . . 5 + 1.5. Example . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 2. GeoJSON Text . . . . . . . . . . . . . . . . . . . . . . . . 6 + 3. GeoJSON Object . . . . . . . . . . . . . . . . . . . . . . . 6 + 3.1. Geometry Object . . . . . . . . . . . . . . . . . . . . . 7 + 3.1.1. Position . . . . . . . . . . . . . . . . . . . . . . 7 + 3.1.2. Point . . . . . . . . . . . . . . . . . . . . . . . . 8 + 3.1.3. MultiPoint . . . . . . . . . . . . . . . . . . . . . 8 + 3.1.4. LineString . . . . . . . . . . . . . . . . . . . . . 8 + 3.1.5. MultiLineString . . . . . . . . . . . . . . . . . . . 8 + 3.1.6. Polygon . . . . . . . . . . . . . . . . . . . . . . . 9 + 3.1.7. MultiPolygon . . . . . . . . . . . . . . . . . . . . 9 + 3.1.8. GeometryCollection . . . . . . . . . . . . . . . . . 9 + 3.1.9. Antimeridian Cutting . . . . . . . . . . . . . . . . 10 + 3.1.10. Uncertainty and Precision . . . . . . . . . . . . . . 11 + 3.2. Feature Object . . . . . . . . . . . . . . . . . . . . . 11 + 3.3. FeatureCollection Object . . . . . . . . . . . . . . . . 12 + 4. Coordinate Reference System . . . . . . . . . . . . . . . . . 12 + 5. Bounding Box . . . . . . . . . . . . . . . . . . . . . . . . 12 + 5.1. The Connecting Lines . . . . . . . . . . . . . . . . . . 14 + 5.2. The Antimeridian . . . . . . . . . . . . . . . . . . . . 14 + 5.3. The Poles . . . . . . . . . . . . . . . . . . . . . . . . 14 + 6. Extending GeoJSON . . . . . . . . . . . . . . . . . . . . . . 15 + 6.1. Foreign Members . . . . . . . . . . . . . . . . . . . . . 15 + 7. GeoJSON Types Are Not Extensible . . . . . . . . . . . . . . 16 + 7.1. Semantics of GeoJSON Members and Types Are Not Changeable 16 + 8. Versioning . . . . . . . . . . . . . . . . . . . . . . . . . 17 + + + +Butler, et al. Standards Track [Page 2] + +RFC 7946 GeoJSON August 2016 + + + 9. Mapping 'geo' URIs . . . . . . . . . . . . . . . . . . . . . 17 + 10. Security Considerations . . . . . . . . . . . . . . . . . . . 18 + 11. Interoperability Considerations . . . . . . . . . . . . . . . 18 + 11.1. I-JSON . . . . . . . . . . . . . . . . . . . . . . . . . 18 + 11.2. Coordinate Precision . . . . . . . . . . . . . . . . . . 18 + 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 + 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 + 13.1. Normative References . . . . . . . . . . . . . . . . . . 20 + 13.2. Informative References . . . . . . . . . . . . . . . . . 21 + Appendix A. Geometry Examples . . . . . . . . . . . . . . . . . 22 + A.1. Points . . . . . . . . . . . . . . . . . . . . . . . . . 22 + A.2. LineStrings . . . . . . . . . . . . . . . . . . . . . . . 22 + A.3. Polygons . . . . . . . . . . . . . . . . . . . . . . . . 23 + A.4. MultiPoints . . . . . . . . . . . . . . . . . . . . . . . 24 + A.5. MultiLineStrings . . . . . . . . . . . . . . . . . . . . 24 + A.6. MultiPolygons . . . . . . . . . . . . . . . . . . . . . . 25 + A.7. GeometryCollections . . . . . . . . . . . . . . . . . . . 26 + Appendix B. Changes from the Pre-IETF GeoJSON Format + Specification . . . . . . . . . . . . . . . . . . . 26 + B.1. Normative Changes . . . . . . . . . . . . . . . . . . . . 26 + B.2. Informative Changes . . . . . . . . . . . . . . . . . . . 27 + Appendix C. GeoJSON Text Sequences . . . . . . . . . . . . . . . 27 + Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 27 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 + +1. Introduction + + GeoJSON is a format for encoding a variety of geographic data + structures using JavaScript Object Notation (JSON) [RFC7159]. A + GeoJSON object may represent a region of space (a Geometry), a + spatially bounded entity (a Feature), or a list of Features (a + FeatureCollection). GeoJSON supports the following geometry types: + Point, LineString, Polygon, MultiPoint, MultiLineString, + MultiPolygon, and GeometryCollection. Features in GeoJSON contain a + Geometry object and additional properties, and a FeatureCollection + contains a list of Features. + + The format is concerned with geographic data in the broadest sense; + anything with qualities that are bounded in geographical space might + be a Feature whether or not it is a physical structure. The concepts + in GeoJSON are not new; they are derived from preexisting open + geographic information system standards and have been streamlined to + better suit web application development using JSON. + + GeoJSON comprises the seven concrete geometry types defined in the + OpenGIS Simple Features Implementation Specification for SQL [SFSQL]: + 0-dimensional Point and MultiPoint; 1-dimensional curve LineString + and MultiLineString; 2-dimensional surface Polygon and MultiPolygon; + + + +Butler, et al. Standards Track [Page 3] + +RFC 7946 GeoJSON August 2016 + + + and the heterogeneous GeometryCollection. GeoJSON representations of + instances of these geometry types are analogous to the well-known + binary (WKB) and well-known text (WKT) representations described in + that same specification. + + GeoJSON also comprises the types Feature and FeatureCollection. + Feature objects in GeoJSON contain a Geometry object with one of the + above geometry types and additional members. A FeatureCollection + object contains an array of Feature objects. This structure is + analogous to that of the Web Feature Service (WFS) response to + GetFeatures requests specified in [WFSv1] or to a Keyhole Markup + Language (KML) Folder of Placemarks [KMLv2.2]. Some implementations + of the WFS specification also provide GeoJSON-formatted responses to + GetFeature requests, but there is no particular service model or + Feature type ontology implied in the GeoJSON format specification. + + Since its initial publication in 2008 [GJ2008], the GeoJSON format + specification has steadily grown in popularity. It is widely used in + JavaScript web-mapping libraries, JSON-based document databases, and + web APIs. + +1.1. Requirements Language + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in + [RFC2119]. + +1.2. Conventions Used in This Document + + The ordering of the members of any JSON object defined in this + document MUST be considered irrelevant, as specified by [RFC7159]. + + Some examples use the combination of a JavaScript single-line comment + (//) followed by an ellipsis (...) as placeholder notation for + content deemed irrelevant by the authors. These placeholders must of + course be deleted or otherwise replaced, before attempting to + validate the corresponding JSON code example. + + Whitespace is used in the examples inside this document to help + illustrate the data structures, but it is not required. Unquoted + whitespace is not significant in JSON. + +1.3. Specification of GeoJSON + + This document supersedes the original GeoJSON format specification + [GJ2008]. + + + + +Butler, et al. Standards Track [Page 4] + +RFC 7946 GeoJSON August 2016 + + +1.4. Definitions + + o JavaScript Object Notation (JSON), and the terms object, member, + name, value, array, number, true, false, and null, are to be + interpreted as defined in [RFC7159]. + + o Inside this document, the term "geometry type" refers to seven + case-sensitive strings: "Point", "MultiPoint", "LineString", + "MultiLineString", "Polygon", "MultiPolygon", and + "GeometryCollection". + + o As another shorthand notation, the term "GeoJSON types" refers to + nine case-sensitive strings: "Feature", "FeatureCollection", and + the geometry types listed above. + + o The word "Collection" in "FeatureCollection" and + "GeometryCollection" does not have any significance for the + semantics of array members. The "features" and "geometries" + members, respectively, of these objects are standard ordered JSON + arrays, not unordered sets. + +1.5. Example + + A GeoJSON FeatureCollection: + + { + "type": "FeatureCollection", + "features": [{ + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [102.0, 0.5] + }, + "properties": { + "prop0": "value0" + } + }, { + "type": "Feature", + "geometry": { + "type": "LineString", + "coordinates": [ + [102.0, 0.0], + [103.0, 1.0], + [104.0, 0.0], + [105.0, 1.0] + ] + }, + "properties": { + + + +Butler, et al. Standards Track [Page 5] + +RFC 7946 GeoJSON August 2016 + + + "prop0": "value0", + "prop1": 0.0 + } + }, { + "type": "Feature", + "geometry": { + "type": "Polygon", + "coordinates": [ + [ + [100.0, 0.0], + [101.0, 0.0], + [101.0, 1.0], + [100.0, 1.0], + [100.0, 0.0] + ] + ] + }, + "properties": { + "prop0": "value0", + "prop1": { + "this": "that" + } + } + }] + } + +2. GeoJSON Text + + A GeoJSON text is a JSON text and consists of a single GeoJSON + object. + +3. GeoJSON Object + + A GeoJSON object represents a Geometry, Feature, or collection of + Features. + + o A GeoJSON object is a JSON object. + + o A GeoJSON object has a member with the name "type". The value of + the member MUST be one of the GeoJSON types. + + o A GeoJSON object MAY have a "bbox" member, the value of which MUST + be a bounding box array (see Section 5). + + o A GeoJSON object MAY have other members (see Section 6). + + + + + + +Butler, et al. Standards Track [Page 6] + +RFC 7946 GeoJSON August 2016 + + +3.1. Geometry Object + + A Geometry object represents points, curves, and surfaces in + 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 + seven geometry types (see Section 1.4). + + o A GeoJSON Geometry object of any type other than + "GeometryCollection" has a member with the name "coordinates". + The value of the "coordinates" member is an array. The structure + of the elements in this array is determined by the type of + geometry. GeoJSON processors MAY interpret Geometry objects with + empty "coordinates" arrays as null objects. + +3.1.1. Position + + A position is the fundamental geometry construct. The "coordinates" + member of a Geometry object is composed of either: + + o one position in the case of a Point geometry, + + o an array of positions in the case of a LineString or MultiPoint + geometry, + + o an array of LineString or linear ring (see Section 3.1.6) + coordinates in the case of a Polygon or MultiLineString geometry, + or + + o an array of Polygon coordinates in the case of a MultiPolygon + geometry. + + A position is an array of numbers. There MUST be two or more + elements. The first two elements are longitude and latitude, or + easting and northing, precisely in that order and using decimal + numbers. Altitude or elevation MAY be included as an optional third + element. + + Implementations SHOULD NOT extend positions beyond three elements + because the semantics of extra elements are unspecified and + ambiguous. Historically, some implementations have used a fourth + 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. + + + + +Butler, et al. Standards Track [Page 7] + +RFC 7946 GeoJSON August 2016 + + + A line between two positions is a straight Cartesian line, the + shortest line between those two points in the coordinate reference + system (see Section 4). + + In other words, every point on a line that does not cross the + antimeridian between a point (lon0, lat0) and (lon1, lat1) can be + calculated as + + F(lon, lat) = (lon0 + (lon1 - lon0) * t, lat0 + (lat1 - lat0) * t) + + with t being a real number greater than or equal to 0 and smaller + than or equal to 1. Note that 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 direction of the height is as specified in the coordinate + reference system. + + Note that, again, this does not mean that a surface with equal height + follows, for example, the curvature of a body of water. Nor is a + surface of equal height perpendicular to a plumb line. + + Examples of positions and geometries are provided in Appendix A, + "Geometry Examples". + +3.1.2. Point + + For type "Point", the "coordinates" member is a single position. + +3.1.3. MultiPoint + + For type "MultiPoint", the "coordinates" member is an array of + positions. + +3.1.4. LineString + + For type "LineString", the "coordinates" member is an array of two or + more positions. + +3.1.5. MultiLineString + + For type "MultiLineString", the "coordinates" member is an array of + LineString coordinate arrays. + + + + + + + + +Butler, et al. Standards Track [Page 8] + +RFC 7946 GeoJSON August 2016 + + +3.1.6. Polygon + + To specify a constraint specific to Polygons, it is useful to + introduce the concept of a linear ring: + + o A linear ring is a closed LineString with four or more positions. + + o The first and last positions are equivalent, and they MUST contain + identical values; their representation SHOULD also be identical. + + o A linear ring is the boundary of a surface or the boundary of a + hole in a surface. + + o A linear ring MUST follow the right-hand rule with respect to the + area it bounds, i.e., exterior rings are counterclockwise, and + holes 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 + geometry type, it leads to a canonical formulation of the Polygon + geometry type definition as follows: + + o For type "Polygon", the "coordinates" member MUST be an array of + linear ring coordinate arrays. + + 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 + exterior ring bounds the surface, and the interior rings (if + present) bound holes within the surface. + +3.1.7. MultiPolygon + + For type "MultiPolygon", the "coordinates" member is an array of + Polygon coordinate arrays. + +3.1.8. GeometryCollection + + A GeoJSON object with type "GeometryCollection" is a Geometry object. + A GeometryCollection has a member with the name "geometries". The + value of "geometries" is an array. Each element of this array is a + GeoJSON Geometry object. It is possible for this array to be empty. + + + + + + + +Butler, et al. Standards Track [Page 9] + +RFC 7946 GeoJSON August 2016 + + + Unlike the other geometry types described above, a GeometryCollection + can be a heterogeneous composition of smaller Geometry objects. For + example, a Geometry object in the shape of a lowercase roman "i" can + be composed of one point and one LineString. + + GeometryCollections 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 + GeometryCollection object has no "coordinates" member, it does have + coordinates: the coordinates of all its parts belong to the + collection. The "geometries" member of a GeometryCollection + describes the parts of this composition. Implementations SHOULD NOT + apply any additional semantics to the "geometries" array. + + To maximize interoperability, implementations SHOULD avoid nested + GeometryCollections. Furthermore, GeometryCollections 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 multipart 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] + ] + ] + } + + + + + + + + +Butler, et al. Standards Track [Page 10] + +RFC 7946 GeoJSON August 2016 + + + 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 + + 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 has a "type" member with the value "Feature". + + o A Feature object has a member with the name "geometry". The value + of the geometry member SHALL be either a Geometry object as + defined above or, in the case that the Feature is unlocated, a + JSON null value. + + o A Feature object has a member with the name "properties". The + value of the properties member is an object (any JSON object or a + JSON null value). + + + + + + + +Butler, et al. Standards Track [Page 11] + +RFC 7946 GeoJSON August 2016 + + + o If a Feature has a commonly used identifier, that identifier + 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 + number. + +3.3. FeatureCollection Object + + A GeoJSON object with the type "FeatureCollection" is a + FeatureCollection object. A FeatureCollection object has a member + with the name "features". The value of "features" is a JSON array. + Each element of the array is a Feature object as defined above. It + is possible for this array to be empty. + +4. Coordinate Reference System + + The coordinate reference system for all GeoJSON coordinates is a + geographic coordinate reference system, using the World Geodetic + System 1984 (WGS 84) [WGS84] datum, with longitude and latitude units + of decimal degrees. This is equivalent to the coordinate reference + system identified by the Open Geospatial Consortium (OGC) URN + urn:ogc:def:crs:OGC::CRS84. An OPTIONAL third-position element SHALL + be the height in meters above or below the WGS 84 reference + ellipsoid. In the absence of elevation values, applications + sensitive to height or depth SHOULD interpret positions as being at + local ground or sea level. + + Note: the use of alternative coordinate reference systems was + specified in [GJ2008], but it has been removed from this version of + the specification because the use of different coordinate reference + systems -- especially in the manner specified in [GJ2008] -- has + proven to have interoperability issues. In general, GeoJSON + processing software is not expected to have access to coordinate + reference system databases or to have network access to coordinate + 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 + + A GeoJSON object MAY have a member named "bbox" to include + information on the coordinate range for its Geometries, Features, or + FeatureCollections. The value of the bbox member MUST be an array of + length 2*n where n is the number of dimensions represented in the + contained geometries, with all axes of the most southwesterly point + followed by all axes of the more northeasterly point. The axes order + of a bbox follows the axes order of geometries. + + + + +Butler, et al. Standards Track [Page 12] + +RFC 7946 GeoJSON August 2016 + + + The "bbox" values define shapes with edges that follow lines of + constant longitude, latitude, and elevation. + + Example of a 2D bbox member on a Feature: + + { + "type": "Feature", + "bbox": [-10.0, -10.0, 10.0, 10.0], + "geometry": { + "type": "Polygon", + "coordinates": [ + [ + [-10.0, -10.0], + [10.0, -10.0], + [10.0, 10.0], + [-10.0, -10.0] + ] + ] + } + //... + } + + Example of a 2D bbox member on a FeatureCollection: + + { + "type": "FeatureCollection", + "bbox": [100.0, 0.0, 105.0, 1.0], + "features": [ + //... + ] + } + + Example of a 3D bbox member with a depth of 100 meters: + + { + "type": "FeatureCollection", + "bbox": [100.0, 0.0, -100.0, 105.0, 1.0, 0.0], + "features": [ + //... + ] + } + + + + + + + + + + +Butler, et al. Standards Track [Page 13] + +RFC 7946 GeoJSON August 2016 + + +5.1. The Connecting Lines + + The four lines of the bounding box are defined fully within the + coordinate reference system; that is, for a box bounded by the values + "west", "south", "east", and "north", every point on the northernmost + line can be expressed as + + (lon, lat) = (west + (east - west) * t, north) + + with 0 <= t <= 1. + +5.2. The Antimeridian + + Consider a set of point Features within the Fiji archipelago, + straddling the antimeridian between 16 degrees S and 20 degrees S. + The southwest corner of the box containing these Features is at 20 + degrees S and 177 degrees E, and the northwest corner is at 16 + degrees S and 178 degrees W. The antimeridian-spanning GeoJSON + bounding box for this FeatureCollection is + + "bbox": [177.0, -20.0, -178.0, -16.0] + + and covers 5 degrees of longitude. + + The complementary bounding box for the same latitude band, not + crossing the antimeridian, is + + "bbox": [-178.0, -20.0, 177.0, -16.0] + + and covers 355 degrees of longitude. + + The latitude of the northeast corner is always greater than the + latitude of the southwest corner, but bounding boxes that cross the + antimeridian have a northeast corner longitude that is less than the + longitude of the southwest corner. + +5.3. The Poles + + A bounding box that contains the North Pole extends from a southwest + corner of "minlat" degrees N, 180 degrees W to a northeast corner of + 90 degrees N, 180 degrees E. Viewed on a globe, this bounding box + approximates a spherical cap bounded by the "minlat" circle of + latitude. + + "bbox": [-180.0, minlat, 180.0, 90.0] + + + + + + +Butler, et al. Standards Track [Page 14] + +RFC 7946 GeoJSON August 2016 + + + 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 + "maxlat" degrees S, 180 degrees E. + + "bbox": [-180.0, -90.0, 180.0, maxlat] + + A bounding box that just touches the North Pole and forms a slice of + an approximate spherical cap when viewed on a globe extends from a + southwest corner of "minlat" degrees N and "westlon" degrees E to a + northeast corner of 90 degrees N and "eastlon" degrees E. + + "bbox": [westlon, minlat, eastlon, 90.0] + + 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 + than -90 to imply an extent that is not a spherical cap. + +6. Extending GeoJSON + +6.1. Foreign Members + + Members not described in this specification ("foreign members") MAY + be used in a GeoJSON document. Note that support for foreign members + can vary across implementations, and no normative processing model + for foreign members is defined. Accordingly, implementations that + rely too heavily on the use of foreign members might experience + reduced interoperability with other implementations. + + For example, in the (abridged) Feature object shown below + + { + "type": "Feature", + "id": "f1", + "geometry": {...}, + "properties": {...}, + "title": "Example Feature" + } + + the name/value pair of "title": "Example Feature" is a foreign + member. When the value of a foreign member is an object, all the + descendant members of that object are themselves foreign members. + + + + + +Butler, et al. Standards Track [Page 15] + +RFC 7946 GeoJSON August 2016 + + + GeoJSON semantics do not apply to foreign members and their + descendants, regardless of their names and values. For example, in + the (abridged) Feature object below + + { + "type": "Feature", + "id": "f2", + "geometry": {...}, + "properties": {...}, + "centerline": { + "type": "LineString", + "coordinates": [ + [-170, 10], + [170, 11] + ] + } + } + + the "centerline" member is not a GeoJSON Geometry object. + +7. GeoJSON Types Are Not Extensible + + Implementations MUST NOT extend the fixed set of GeoJSON types: + FeatureCollection, Feature, Point, LineString, MultiPoint, Polygon, + MultiLineString, MultiPolygon, and GeometryCollection. + +7.1. Semantics of GeoJSON Members and Types Are Not Changeable + + Implementations MUST NOT change the semantics of GeoJSON members and + types. + + The GeoJSON "coordinates" and "geometries" members define Geometry + objects. FeatureCollection and Feature objects, respectively, MUST + NOT contain a "coordinates" or "geometries" member. + + The GeoJSON "geometry" and "properties" members define a Feature + object. FeatureCollection and Geometry objects, respectively, MUST + NOT contain a "geometry" or "properties" member. + + The GeoJSON "features" member defines a FeatureCollection object. + Feature and Geometry objects, respectively, MUST NOT contain a + "features" member. + + + + + + + + + +Butler, et al. Standards Track [Page 16] + +RFC 7946 GeoJSON August 2016 + + +8. Versioning + + The GeoJSON format can be extended as defined here, but no explicit + versioning scheme is defined. A specification that alters the + semantics of GeoJSON members or otherwise modifies the format does + not create a new version of this format; instead, it defines an + entirely new format that MUST NOT be identified as GeoJSON. + +9. Mapping 'geo' URIs + + 'geo' URIs [RFC5870] identify geographic locations and precise (not + uncertain) locations can be mapped to GeoJSON Geometry objects. + + For this section, as in [RFC5870], "lat", "lon", "alt", and "unc" are + placeholders for 'geo' URI latitude, longitude, altitude, and + uncertainty values, respectively. + + 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 + each other. A GeoJSON Point is always converted to a 'geo' URI that + has no uncertainty parameter. + + 'geo' URI: + + geo:lat,lon + + GeoJSON: + + {"type": "Point", "coordinates": [lon, lat]} + + The mapping between 'geo' URIs and GeoJSON Points that specify + elevation is shown below. + + 'geo' URI: + + geo:lat,lon,alt + + GeoJSON: + + {"type": "Point", "coordinates": [lon, lat, alt]} + + GeoJSON has no concept of uncertainty; imprecise or uncertain 'geo' + URIs thus cannot be mapped to GeoJSON geometries. + + + + + + + + +Butler, et al. Standards Track [Page 17] + +RFC 7946 GeoJSON August 2016 + + +10. Security Considerations + + GeoJSON shares security issues common to all JSON content types. See + [RFC7159], Section 12 for additional information. GeoJSON does not + 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, Transport Layer Security (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 + details about the locations of sensitive persons, animals, habitats, + and facilities can expose them to unauthorized tracking or injury. + Data providers should recognize the risk of inadvertently identifying + individuals if locations in anonymized datasets are not adequately + 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]. + +11. Interoperability Considerations + +11.1. I-JSON + + GeoJSON texts should follow the constraints of Internet JSON (I-JSON) + [RFC7493] for maximum interoperability. + +11.2. Coordinate Precision + + The size of a GeoJSON text in bytes is a major interoperability + consideration, and precision of coordinate values has a large impact + on the size of texts. A GeoJSON text containing many detailed + Polygons can be inflated almost by a factor of two by increasing + coordinate precision from 6 to 15 decimal places. For geographic + coordinates with units of degrees, 6 decimal places (a default common + in, e.g., sprintf) amounts to about 10 centimeters, a precision well + within that of current GPS systems. Implementations should consider + the cost of using a greater precision than necessary. + + Furthermore, the WGS 84 [WGS84] datum is a relatively coarse + approximation of the geoid, with the height varying by up to 5 m (but + generally between 2 and 3 meters) higher or lower relative to a + surface parallel to Earth's mean sea level. + + + + + + +Butler, et al. Standards Track [Page 18] + +RFC 7946 GeoJSON August 2016 + + +12. IANA Considerations + + The media type for GeoJSON text is "application/geo+json" and is + registered in the "Media Types" registry described in [RFC6838]. The + entry for "application/vnd.geo+json" in the same registry should have + its status changed to be "OBSOLETED" with a pointer to the media type + "application/geo+json" and a reference added to this RFC. + + Type name: application + + Subtype name: geo+json + + Required parameters: n/a + + Optional parameters: n/a + + Encoding considerations: binary + + Security considerations: See Section 10 above + + Interoperability considerations: See Section 11 above + + Published specification: [[RFC7946]] + + 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: + + Magic number(s): n/a + + File extension(s): .json, .geojson + + Macintosh file type code: n/a + + Object Identifiers: n/a + + Windows clipboard name: GeoJSON + + Macintosh uniform type identifier: public.geojson conforms to + public.json + + + + + +Butler, et al. Standards Track [Page 19] + +RFC 7946 GeoJSON August 2016 + + + Person to contact for further information: Sean Gillies + (sean.gillies@gmail.com) + + Intended usage: COMMON + + Restrictions on usage: none + + Restrictions on usage: none + + Author: see "Authors' Addresses" section of [[RFC7946]]. + + Change controller: Internet Engineering Task Force + +13. References + +13.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type + Specifications and Registration Procedures", BCP 13, + RFC 6838, DOI 10.17487/RFC6838, January 2013, + . + + [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data + Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March + 2014, . + + [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, + DOI 10.17487/RFC7493, March 2015, + . + + [WGS84] National Imagery and Mapping Agency, "Department of + Defense World Geodetic System 1984: Its Definition and + Relationships with Local Geodetic Systems", Third Edition, + 1984. + + + + + + + + + + + + +Butler, et al. Standards Track [Page 20] + +RFC 7946 GeoJSON August 2016 + + +13.2. Informative References + + [GJ2008] Butler, H., Daly, M., Doyle, A., Gillies, S., Schaub, T., + and C. Schmidt, "The GeoJSON Format Specification", June + 2008. + + [KMLv2.2] Wilson, T., "OGC KML", OGC 07-147r2, Version 2.2.0, April + 2008. + + [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource + Identifier for Geographic Locations ('geo' URI)", + RFC 5870, DOI 10.17487/RFC5870, June 2010, + . + + [RFC6772] Schulzrinne, H., Ed., Tschofenig, H., Ed., Cuellar, J., + 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, . + + [RFC7464] Williams, N., "JavaScript Object Notation (JSON) Text + Sequences", RFC 7464, DOI 10.17487/RFC7464, February 2015, + . + + [SFSQL] OpenGIS Consortium, Inc., "OpenGIS Simple Features + 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, + DOI 10.1142/S0218488502001648, 2002. + + [WFSv1] Vretanos, P., "Web Feature Service Implementation + Specification", OGC 04-094, Version 1.1.0, May 2005. + + + + + + + + + + + + + + + + + +Butler, et al. Standards Track [Page 21] + +RFC 7946 GeoJSON August 2016 + + +Appendix A. Geometry Examples + + Each of the examples below represents a valid and complete GeoJSON + object. + +A.1. Points + + Point coordinates are in x, y order (easting, northing for projected + coordinates, longitude, and latitude for geographic coordinates): + + { + "type": "Point", + "coordinates": [100.0, 0.0] + } + +A.2. LineStrings + + Coordinates of LineString are an array of positions (see + Section 3.1.1): + + { + "type": "LineString", + "coordinates": [ + [100.0, 0.0], + [101.0, 1.0] + ] + } + + + + + + + + + + + + + + + + + + + + + + + + +Butler, et al. Standards Track [Page 22] + +RFC 7946 GeoJSON August 2016 + + +A.3. Polygons + + Coordinates of a Polygon are an array of linear ring (see + Section 3.1.6) coordinate arrays. The first element in the array + represents the exterior ring. Any subsequent elements represent + interior rings (or holes). + + No holes: + + { + "type": "Polygon", + "coordinates": [ + [ + [100.0, 0.0], + [101.0, 0.0], + [101.0, 1.0], + [100.0, 1.0], + [100.0, 0.0] + ] + ] + } + + With holes: + + { + "type": "Polygon", + "coordinates": [ + [ + [100.0, 0.0], + [101.0, 0.0], + [101.0, 1.0], + [100.0, 1.0], + [100.0, 0.0] + ], + [ + [100.8, 0.8], + [100.8, 0.2], + [100.2, 0.2], + [100.2, 0.8], + [100.8, 0.8] + ] + ] + } + + + + + + + + +Butler, et al. Standards Track [Page 23] + +RFC 7946 GeoJSON August 2016 + + +A.4. MultiPoints + + Coordinates of a MultiPoint are an array of positions: + + { + "type": "MultiPoint", + "coordinates": [ + [100.0, 0.0], + [101.0, 1.0] + ] + } + +A.5. MultiLineStrings + + Coordinates of a MultiLineString are an array of LineString + coordinate arrays: + + { + "type": "MultiLineString", + "coordinates": [ + [ + [100.0, 0.0], + [101.0, 1.0] + ], + [ + [102.0, 2.0], + [103.0, 3.0] + ] + ] + } + + + + + + + + + + + + + + + + + + + + + +Butler, et al. Standards Track [Page 24] + +RFC 7946 GeoJSON August 2016 + + +A.6. MultiPolygons + + Coordinates of a MultiPolygon are an array of Polygon coordinate + arrays: + + { + "type": "MultiPolygon", + "coordinates": [ + [ + [ + [102.0, 2.0], + [103.0, 2.0], + [103.0, 3.0], + [102.0, 3.0], + [102.0, 2.0] + ] + ], + [ + [ + [100.0, 0.0], + [101.0, 0.0], + [101.0, 1.0], + [100.0, 1.0], + [100.0, 0.0] + ], + [ + [100.2, 0.2], + [100.2, 0.8], + [100.8, 0.8], + [100.8, 0.2], + [100.2, 0.2] + ] + ] + ] + } + + + + + + + + + + + + + + + + +Butler, et al. Standards Track [Page 25] + +RFC 7946 GeoJSON August 2016 + + +A.7. GeometryCollections + + Each element in the "geometries" array of a GeometryCollection is one + of the Geometry objects described above: + + { + "type": "GeometryCollection", + "geometries": [{ + "type": "Point", + "coordinates": [100.0, 0.0] + }, { + "type": "LineString", + "coordinates": [ + [101.0, 0.0], + [102.0, 1.0] + ] + }] + } + +Appendix B. Changes from the Pre-IETF GeoJSON Format Specification + + This appendix briefly summarizes non-editorial changes from the 2008 + specification [GJ2008]. + +B.1. Normative Changes + + o Specification of coordinate reference systems has been removed, + i.e., the "crs" member of [GJ2008] is no longer used. + + o In the absence of elevation values, applications sensitive to + height or depth SHOULD interpret positions as being at local + ground or sea level (see Section 4). + + o Implementations SHOULD NOT extend position arrays beyond 3 + elements (see Section 3.1.1). + + o A line between two positions is a straight Cartesian line (see + Section 3.1.1). + + o Polygon rings MUST follow the right-hand rule for orientation + (counterclockwise 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 + Section 3.2). + + + + +Butler, et al. Standards Track [Page 26] + +RFC 7946 GeoJSON August 2016 + + + o Extensions MAY be used, but MUST NOT change the semantics of + GeoJSON members and types (see Section 6). + + o GeoJSON objects MUST NOT contain the defining members of other + types (see Section 7.1). + + o The media type for GeoJSON is "application/geo+json". + +B.2. Informative Changes + + o The definition of a GeoJSON text has been added. + + o Rules for mapping 'geo' URIs have been added. + + o A recommendation of the I-JSON [RFC7493] constraints has been + added. + + o Implementers are cautioned about the effect of excessive + coordinate precision on interoperability. + + o Interoperability concerns of GeometryCollections are noted. These + objects should be used sparingly (see Section 3.1.8). + +Appendix C. GeoJSON Text Sequences + + All GeoJSON objects defined in this specification -- + FeatureCollection, Feature, and Geometry -- consist of exactly one + JSON object. However, there may be circumstances in which + applications need to represent sets or sequences of these objects + (over and above the grouping of Feature objects in a + FeatureCollection), e.g., in order to efficiently "stream" large + numbers of Feature objects. The definition of such sets or sequences + is outside the scope of this specification. + + If such a representation is needed, a new media type is required that + has the ability to represent these sets or sequences. When defining + such a media type, it may be useful to base it on "JavaScript Object + Notation (JSON) Text Sequences" [RFC7464], leaving the foundations of + how to represent multiple JSON objects to that specification, and + only defining how it applies to GeoJSON objects. + +Acknowledgements + + The GeoJSON format is the product of discussion on the GeoJSON + mailing list, , before October 2015 and in the IETF's GeoJSON + WG after October 2015. + + + + +Butler, et al. Standards Track [Page 27] + +RFC 7946 GeoJSON August 2016 + + + Material in this document was adapted with changes from + [GJ2008], which is licensed + under . + +Authors' Addresses + + Howard Butler + Hobu Inc. + + Email: howard@hobu.co + + + Martin Daly + Cadcorp + + Email: martin.daly@cadcorp.com + + + Allan Doyle + + Email: adoyle@intl-interfaces.com + + + Sean Gillies + Mapbox + + Email: sean.gillies@gmail.com + URI: http://sgillies.net + + + Stefan Hagen + Rheinaustr. 62 + Bonn 53225 + Germany + + Email: stefan@hagen.link + URI: http://stefan-hagen.website/ + + + Tim Schaub + Planet Labs + + Email: tim.schaub@gmail.com + + + + + + + + +Butler, et al. Standards Track [Page 28] + -- cgit v1.2.3