RFC-001

From GeoJSON
Revision as of 11:28, 24 April 2007 by Sgillies (Talk | contribs) (Added example of a feature collection)

Jump to: navigation, search

Definitions

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 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.
  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 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

Collection

A collection is an object with an array type "members" property 

{ "members":
  [ feature0, feature1, ..., featureN ]
}

This heads off at least one JavaScript security issue: http://bob.pythonmac.org/archives/2007/04/05/fortify-javascript-hijacking-fud/

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
Retrieved from "http://wiki.geojson.org/index.php?title=RFC-001&oldid=61"