GENWiki

Premier IT Outsourcing and Support Services within the UK

User Tools

Site Tools


rfc:rfc7946

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,
            <http://www.rfc-editor.org/info/rfc2119>.
 [RFC6838]  Freed, N., Klensin, J., and T. Hansen, "Media Type
            Specifications and Registration Procedures", BCP 13,
            RFC 6838, DOI 10.17487/RFC6838, January 2013,
            <http://www.rfc-editor.org/info/rfc6838>.
 [RFC7159]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
            Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
            2014, <http://www.rfc-editor.org/info/rfc7159>.
 [RFC7493]  Bray, T., Ed., "The I-JSON Message Format", RFC 7493,
            DOI 10.17487/RFC7493, March 2015,
            <http://www.rfc-editor.org/info/rfc7493>.
 [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,
            <http://www.rfc-editor.org/info/rfc5870>.
 [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, <http://www.rfc-editor.org/info/rfc6772>.
 [RFC7464]  Williams, N., "JavaScript Object Notation (JSON) Text
            Sequences", RFC 7464, DOI 10.17487/RFC7464, February 2015,
            <http://www.rfc-editor.org/info/rfc7464>.
 [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, <http://lists.geojson.org/listinfo.cgi/
 geojson-geojson.org>, 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
 <http://geojson.org/geojson-spec.html> [GJ2008], which is licensed
 under <http://creativecommons.org/licenses/by/3.0/us/>.

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]

/data/webs/external/dokuwiki/data/pages/rfc/rfc7946.txt · Last modified: 2016/08/11 00:20 by 127.0.0.1

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki