RFC-001

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

Definitions

• 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

1. A feature is an object.
2. 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.)
3. 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 is 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]" and z is expressed as meters above mean sea level per WGS84. If present, the value of crs is to be interpreted as in PROJ4's EPSG tables and the values of the coordinates are to be interpreted accordingly.
4. 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.
5. 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.
6. 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 3.

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": [[-105.8, 40.05]]
  }
}

Geometries

Each example is presented in isolation, without the containing feature object.

Point

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

LineString

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

Polygon

  "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]]
      }
    ]
  }

Box

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

MultiPoint

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

MultiLineString

  "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

  "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

  "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