RFC-001

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

A feature is an object.
A feature may have a name/value pair whose name is 'geometry' and whose value conforms to rule 3. (A feature may have any other name/value pairs, without restriction.)
The value of a geometry must itself be an object with the following name/value pairs:
- 'type' - [Point | LineString | Polygon | Box | MultiPoint | MultiLineString | MultiPolygon | GeometryCollection]
- For 'type' [Point | LineString | Box | MultiPoint]:
  - 'coordinates' - A coordinate consists of an array of two or three number values representing x, y, and optionally z. In the case of a Point, the value of coordinates is an array consisting of a single coordinate (i.e. an array of two or three number values). In all other cases, an array of coordinates as in Point, restricted as follows:
    - A LineString must have at least two coordinates.
    - A Box must have exactly two coordinates.
    - A MultiPoint must have at least two coordinates.
- For 'type' [Polygon]:
  - 'exterior' - The value of an exterior must itself be a geometry object with the following name/value pairs:
    - 'type' - LinearRing
    - 'coordinates' - An array of coordinates as defined above, restricted as follows:
      - A LinearRing must have at least four coordinates, with the first and last coordinates coincident, i.e. the geometry must be closed.
  - A Polygon may have a 'holes' name/value pair. The value of holes must itself be an array of geometries of type LinearRing, as defined for exterior. If present, the array must contain at least one LinearRing.
- For 'type' [MultiLineString | MultiPolygon | GeometryCollection]:
  - 'members' - The value of members must be an array of geometry objects, restricted as follows:
    - A MultiLineString must contain only LineString geometry objects.
    - A MultiPolygon must contain only Polygon geometry objects.
    - A GeometryCollection must contain only Point, LineString or Polygon geometry objects.
    - In all cases, the members must not contain a 'crs' value.
- 'crs' - an optional string specifying a coordinate reference system of the coordinates. If not present, WGS84 is implied and coordinates represent decimal degrees ordered as "longitude, latitude [,elevation]" with z expressed as metres above mean sea level per WGS84. If present, the value of crs must be of the form 'EPSG:nnnn', where 'nnnn' represents the EPSG crs code.
A feature should have a name/value pair whose name is 'id' and whose value can be uniquely interpreted by the source of the GeoJSON string, generally identifying this GeoJSON object's resource.
A feature should have a name/value pair whose name is 'properties' and whose value is an object that has meaning within a specific community of interest.
A feature having multiple geometries should have an array of geometries contained within a properties object (see 5) which is called 'geometries' and whose values are as described in rule 3.

References

GISPython: Feature Protocol

GeoJSON is inspired in part by http://trac.gispython.org/projects/PCL/wiki/PythonFeatureProtocol (or maybe even a complete copy).

EPSG

The International Associated of Oil & Gas Producers (OGP) publishes a widely used and widely referenced database of well-known coordinate reference systems. The database was previously published by the European Petroluem Survey Group (EPSG), before EPSG was absorbed into OGP. The EPSG/OGP database references each crs by code number, e.g. EPSG code 4326 is a geographic (latitude/longitude) crs, using the WGS84 datum.

GeoJSON Exceptions

GeoJSON References to a EPSG crs are consistent with programming convention, for example in the PROJ.4 library, not geodetic convention:
1. When referencing a geographic crs "longitude, latitude [, elevetion]" coordinate order is implied.
2. When referencing a projected crs "easting, northing [, elevation]" coordinate order is implied.

Examples

Features

Adapted from Python example at GISPython: Feature Protocol

{
  "id": "1",
  "properties": {
    "title": "Feature 1",
    "summary": "The first feature",
    "link": "http://example.org/features/1"
  },
  "geometry": {
    "type": "Point",
    "coordinates": [[0.0,0.0]]
  }
}

As in JSON, whitespace is irrelevant::

{"id":"2","properties":{"title":"Feature 2","geometry":{"type":"Point","coordinates":[[1.0,1.0]]}}

Geometries

Each example is presented in isolation, without the containing feature object. The 'crs' name/value pair is included for reference only, 'EPSG:4326' being equivalent to having no 'crs' name/value pair at all.

Point

  "geometry": {
    "type": "Point",
    "crs": "EPSG:4326",
    "coordinates": [[0.0,0.0]]
  }

LineString

  "geometry": {
    "type": "LineString",
    "crs": "EPSG:4326",
    "coordinates": [[0.0,0.0],[1.0,0.0],[1.0,1.0]]
  }

Polygon

  "geometry": {
    "type": "Polygon",
    "crs": "EPSG:4326",
    "exterior": {
      "type": "LinearRing",
      "coordinates": [[0.0,0.0],[1.0,0.0],[1.0,1.0],[0.0,1.0],[0.0,0.0]]
    }
    "holes":[
      {
        "type": "LinearRing",
        "coordinates": [[0.25,0.25],[0.75,0.25],[0.75,0.75],[0.25,0.75],[0.25,0.25]]
      }
    ]
  }

Box

  "geometry": {
    "type": "Box",
    "crs": "EPSG:4326",
    "coordinates": [[0.0,0.0],[1.0,1.0]]
  }

MultiPoint

  "geometry": {
    "type": "MultiPoint",
    "crs": "EPSG:4326",
    "coordinates": [[0.0,0.0],[1.0,1.0]]
  }

MultiLineString

  "geometry": {
    "type": "MultiLineString",
    "crs": "EPSG:4326",
    "members": [
      "geometry": {
        "type": "LineString",
        "coordinates": [[0.0,0.0],[1.0,0.0],[1.0,1.0]]
      },
      "geometry": {
        "type": "LineString",
        "coordinates": [[2.0,2.0],[3.0,2.0],[3.0,3.0]]
      }
    ]
  }

MultiPolygon

  "geometry": {
    "type": "MultiPolygon",
    "crs": "EPSG:4326",
    "members": [
      "geometry": {
        "type": "Polygon",
        "exterior": {
          "type": "LinearRing",
          "coordinates": [[0.0,0.0],[1.0,0.0],[1.0,1.0],[0.0,1.0],[0.0,0.0]]
        }
        "holes":[
          {
            "type": "LinearRing",
            "coordinates": [[0.25,0.25],[0.75,0.25],[0.75,0.75],[0.25,0.75],[0.25,0.25]]
          }
        ]
      },
      "geometry": {
        "type": "Polygon",
        "exterior": {
          "type": "LinearRing",
          "coordinates": [[10.0,10.0],[11.0,0.0],[11.0,11.0],[10.0,11.0],[10.0,10.0]]
        }
      }
    ]
  }

GeometryCollection

  "geometry": {
    "type": "GeometryCollection",
    "crs": "EPSG:4326",
    "members": [
      "geometry": {
        "type": "Point",
        "coordinates": [[0.0,0.0]]
      },
      "geometry": {
        "type": "LineString",
        "coordinates": [[0.0,0.0],[1.0,0.0],[1.0,1.0]]
      },
      "geometry": {
        "type": "Polygon",
        "exterior": {
          "type": "LinearRing",
          "coordinates": [[0.0,0.0],[1.0,0.0],[1.0,1.0],[0.0,1.0],[0.0,0.0]]
        }
        "holes":[
          {
            "type": "LinearRing",
            "coordinates": [[0.25,0.25],[0.75,0.25],[0.75,0.75],[0.25,0.75],[0.25,0.25]]
          }
        ]
      }
    ]
 }

Authors

Allan Doyle
Sean Gillies
Martin Daly