Difference between revisions of "GeoJSON draft version 5"

Revision as of 08:30, 1 June 2007

Overview

GeoJSON is a data-interchange format for a variety of geographic data structures. GeoJSON can be used to represent a geometry, a feature, a collection of geometries, or a collection of features. The geometry types supported in GeoJSON are Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, and Box. Features in GeoJSON are geometry objects with additional properties. A geometry collection represents a list of geometries and a feature collection represents a list of features.

A complete GeoJSON data structure is always an object (in JSON terms). In GeoJSON, an object consists of a collection of name/value pairs - also called members. For each member, the name is always a string. Member values are either a string, number, object, array or one of the literals: true, false, and null. An array consists of elements where each element is a value as described above. Note that while the term member generally refers to a name/value pair, GeoJSON does use the name "members" in geometry collections and feature collections.

Definitions

JavaScript Object Notation (JSON), and the terms object, name, value, array, and number, are defined at http://json.org/
The terms may, should, and must are defined at http://www.ietf.org/rfc/rfc2119.txt

Specification

GeoJSON always consists of a single object. This object (referred to as the GeoJSON object below) represents a geometry, feature, collection of geometries, or collection of features.
The GeoJSON object may have any number of members (name/value pairs).
The GeoJSON object names must support the full range of characters described by the JSON specification.
The GeoJSON object must have a member with the name "type". This member's value is a string that determines the type of the GeoJSON object.
1. The value of the type member must be one of: "Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon", "Box", "GeometryCollection", "Feature", or "FeatureCollection". "type" must be lower case, the case of the type member values must be as shown here.
2. A geometry is a GeoJSON object where the type member's value is one of: "Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon", or "Box". The case of the type member values must be as shown here.
  1. In addition to the type member, a GeoJSON object that represents a geometry (referred to as a geometry object below) must have a member with the name "coordinates". The value of the coordinates member is always an array (referred to as the coordinates array below). The structure for the elements in this array are determined by the type of geometry.
    1. For type "Point", each element in the coordinates array is a number representing the point coordinate in one dimension. The order of elements follows x, y, z order (or longitude, latitude, elevation for coordinates in decimal degrees).
    2. For type "MultiPoint", each element in the coordinates array is a coordinates array as described for type "Point".
    3. For type "LineString", each element in the coordinates array is a coordinates array as described for type "Point". The coordinates array for a LineString must have two or more elements. A LinearRing is a special case of type LineString where the first and last elements in the coordinates array are equivalent (they represent equivalent points). Though a LinearRing is not explicitly represented as a GeoJSON geometry type, it is referred to in the Polygon geometry type definition.
    4. For type "Polygon", each element in the coordinates array is a coordinates array as described for type "LineString". Furthermore, each LineString in the coordinates array must be a LinearRing. For Polygons with multiple LinearRings, the first must be the exterior ring and any others must be interior rings or holes.
    5. For type "MultiPolygon", each element in the coordinates array is a coordinates array as described for type Polygon.
    6. For type "Box", the coordinates array must have two elements. Each element in the coordinates array is a coordinates array as described for type "Point". The first element in the array represents the minx, miny corner of the box, and the second point represents the maxx, maxy corner of the box.
3. A GeoJSON object with type "GeometryCollection" represents a collection of geometry objects.
  1. An object of type "GeometryCollection" must have a member with the name "members". The value corresponding to "members" is an array. Each element in this array is a geometry object as defined above.
4. A GeoJSON object with the type "Feature" represents a geometry with additional properties (referred to as a feature object below).
  1. A feature object must have a member with the name "geometry". The value of the geometry member is a geometry object as defined above (a GeoJSON object with type "Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon", or "Box").
  2. A feature object must have a member with the name "properties". The value of the properties member is an object (any JSON object).
5. A GeoJSON object with the type "FeatureCollection" represents a collection of feature objects.
  1. An object of type "FeatureCollection" must have a member with the name "members". The value corresponding to "members" is an array. Each element in the array is a feature object as defined above.
A GeoJSON object without a member named "crs" contains geometries in a Geographic projection, in the WGS84 datum, with units in decimal degrees. A GeoJSON object may have a member with the name "crs". If a GeoJSON object has a member named "crs", it is assumed to represent the coordinate reference system of the included geometry or geometries.
1. The value of a member named "crs" must be an object. This object must have at least two named members: "type" and "properties". The value of the member named "type" must be a string. The value of the member named "properties" must be an object. This specification defines no further requirements for the structure of these objects. Instead, a convention is offered.
  1. To use EPSG codes to describe coordinate reference system, the "crs" member should have the following structure: "crs": {"type": "EPSG", "properties": {"code": 4267}}. "crs", "type", and "properties" must be lower case. When used as a value, "EPSG" must be upper case.
  2. Note that the use of EPSG codes does not change the meaning of the coordinate order for a GeoJSON data structure. All coordinates in GeoJSON are in x, y order (longitude, latitude). This is true regardless of the schema used to represent the coordinate reference system.
  3. The use of a "crs" member for EPSG:4326 is discouraged since the default of not having a "crs" member would result in the same coordinate values.

Examples

Each of the examples below represents a complete GeoJSON object. Note that unquoted whitespace is not significant in JSON. Whitespace is used in the examples to help illustrate the data structures - though it is not required.

Geometries

Point

Point coordinates are in x, y order (longitude, latitude for geographic coordinates).

{
   "type": "Point",
   "coordinates": [100.0, 0.0]
}

LineString

Coordinates of LineString are an array of Point coordinates.

{
   "type": "LineString",
   "coordinates": [
       [100.0, 0.0], [101.0, 1.0]
   ]
}

Polygon

Coordinates of a Polygon are an array of LinearRing coordinates (LineString coordinates where the first and last points are equivalent). 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.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8], [100.2, 0.2] ]
   ]
}

MultiPoint

Coordinates of a MultiPoint are an array of Point coordinates.

{
   "type": "MultiPoint",
   "coordinates": [
       [100.0, 0.0], [101.0, 1.0]
   ]
}

MultiLineString

Coordinates of a MultiLineString are an array of LineString coordinates.

{
   "type": "MultiLineString",
   "coordinates": [
       [ [100.0, 0.0], [101.0, 1.0] ],
       [ [102.0, 2.0], [103.0, 3.0] ]
   ]
}

MultiPolygon

Coordinates of a MultiPolygon are an array of Polygon coordinates.

{
   "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.8, 0.2], [100.8, 0.8], [100.2, 0.8], [100.2, 0.2] ]
       ]
   ]
}

Box

Coordinates of a Box are an array of two Point coordinates. The first element in the array represents the minimum corner point (minx, miny). The second element in the array represents the maximum corner point (maxx, maxy).

{
   "type": "Box",
   "coordinates": [[100.0, 0.0], [101.0, 1.0]]
}

GeometryCollection

Each element in the members array of a GeometryCollection is one of the geometry objects described above.

{
   "type": "GeometryCollection",
   "members": [
       {
           "type": "Point",
           "coordinates": [100.0, 0.0]
       },
       {
           "type": "LineString",
           "coordinates": [
               [101.0, 0.0], [102.0, 1.0]
           ]
       }
   ]
}

Feature

A Feature is an object with a geometry and additional properties.

{
   "type": "Feature",
   "geometry": {
       "type": "LineString",
       "coordinates": [
           [100.0, 0.0], [101.0, 1.0]
       ]
   },
   "properties": {
       "prop0": "value0",
       "prop1": "value1"
   }
}

FeatureCollection

Each element in the members array of a FeatureCollection is a Feature object as described above.

{
   "type": "FeatureCollection",
   "members": [
       {
           "type": "Feature",
           "id": "id0",
           "geometry": {
               "type": "LineString",
               "coordinates": [
                   [102.0, 0.0], [103.0, 1.0], [104.0, 0.0], [105.0, 1.0]
               ]
           },
           "properties": {
               "prop0": "value0",
               "prop1": "value1"
           }
       },
       {
           "type": "Feature",
           "id": "id1",
           "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": "value1"
           }
       }
   ]
}

Same feature collection, with a member named "crs" to represent the coordinate reference system.

{
   "type": "FeatureCollection",
   "crs": {
       "type": "EPSG",
       "properties": {"code": 4267}
   },
   "members": [
       {
           "type": "Feature",
           "id": "id0",
           "geometry": {
               "type": "LineString",
               "coordinates": [
                   [102.0, 0.0], [103.0, 1.0], [104.0, 0.0], [105.0, 1.0]
               ]
           },
           "properties": {
               "prop0": "value0",
               "prop1": "value1"
           }
       },
       {
           "type": "Feature",
           "id": "id1",
           "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": "value1"
           }
       }
   ]
}

Including additional properties

GeoJSON also allows additional properties at the top level of each GeoJSON object. Parsers MUST parse JSON in this format correctly:

{
   "@namespaces":  {"":"http://geojson.org/ns#"},
   "type": "Feature",
   "geometry": {
       "type": "LineString",
       "coordinates": [
           [100.0, 0.0], [101.0, 1.0]
       ]
   },
   "properties": {
       "prop0": "value0",
       "prop1": "value1"
   }
}

Additionally, properties of GeoJSON are expected to be strings, so non-alphanumeric characters must be supported by parsers: parsers MUST support the following format:

{
   "@namespaces":  {"":"http://geojson.org/ns#", "atom":"http://www.w3.org/2005/Atom"},
   "type": "Feature",
   "geometry": {
       "type": "LineString",
       "coordinates": [
           [100.0, 0.0], [101.0, 1.0]
       ]
   },
   "properties": {
       "atom:summary": "Some GeoJSON Content"
   }
}

Authors

Tim Schaub
Allan Doyle
Sean Gillies
Martin Daly