Difference between revisions of "RFC-001"

From GeoJSON
Jump to: navigation, search
(Change srs to crs)
(Added notice that people should look at RFC-2.)
 
(12 intermediate revisions by 3 users not shown)
Line 1: Line 1:
Inspired in part by http://trac.gispython.org/projects/PCL/wiki/PythonFeatureProtocol (or maybe even a complete copy )
+
== NOTICE ==
 +
This is historical material. This page has been superseded by [[RFC-2]].  
  
 
== Definitions ==
 
== Definitions ==
* The terms object, name, value, array, and number are defined at http://json.org/
+
 
 +
* 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
 
* The terms may, should, and must are defined at http://www.ietf.org/rfc/rfc2119.txt
  
Line 10: Line 12:
 
# 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.)
 
# 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:
 
# The value of a geometry must itself be an object with the following name/value pairs:
#* 'type' - [Point | Line | Polygon | Box]
+
#* 'type' - [Point | LineString | Polygon | Box | MultiPoint | MultiLineString | MultiPolygon | GeometryCollection]
#* 'coordinates' - In the case of a Point, an array of two or three number values representing x, y, and optionally z. In all other cases, an array of arrays of number values as in Point, restricted as follows:
+
#* For 'type' [Point | LineString | Polygon | Box | MultiPoint]:
#** A Line must have at least two values.
+
#** '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 Polygon must have at least three values.
+
#*** A LineString must have at least two coordinates.
#** A Box must have exactly two values.
+
#*** A Box must have exactly two coordinates.
#* '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.
+
#*** A Polygon must have at least four coordinates, with the first and last coordinates coincident, i.e. the geometry must be closed.
 +
#*** A MultiPoint must have at least two coordinates.
 +
#* For 'type' [Polygon]:
 +
#** A Polygon may have a 'holes' name/value pair.  The value of holes must itself be an array of array of coordinates, with each array of coordinates restricted as per the Polygon 'coordinates' value, i.e. it must be a closed ring with four or more coordinates.  If present, the 'holes' array must contain at least one array of coordinates.
 +
#* 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:nnnnn', where 'nnnnn' is replaced by the [[#EPSG|EPSG]] crs code, e.g. 'EPSG:27700'.
 
# 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 '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 which has meaning within a specific community of interest.
+
# 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 3.
+
# 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 [http://www.ogp.org.uk International Associated of Oil & Gas Producers (OGP)] [http://www.epsg.org 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 [http://www.remotesensing.org/proj PROJ.4] library, not geodetic convention:
 +
*# When referencing a geographic crs "longitude, latitude [, elevation]" coordinate order is implied.
 +
*# When referencing a projected crs "easting, northing [, elevation]" coordinate order is implied.
  
 
== Examples ==
 
== Examples ==
from [http://trac.gispython.org/projects/PCL/wiki/PythonFeatureProtocol GISPython: Feature Protocol]
+
=== Collection ===
  {  
+
A collection is an object with an array type "members" property
   'id': '1',
+
 
   'properties': {
+
{ "members":
     'title': u'Feature 1',
+
  [ feature0, feature1, ..., featureN ]
     'summary': u'The first feature',
+
}
     'link': http://example.org/features/1,
+
 
   }
+
This heads off at least one JavaScript security issue: http://bob.pythonmac.org/archives/2007/04/05/fortify-javascript-hijacking-fud/
   'geometry': {
+
     # WGS84 crs is implied
+
=== Features ===
    'type': 'Point',
+
Adapted from Python example at [http://trac.gispython.org/projects/PCL/wiki/PythonFeatureProtocol GISPython: Feature Protocol]
     'coordinates': [-105.8, 40.05],
+
 
 +
  {
 +
   "id": "1",
 +
   "properties": {
 +
     "title": "Feature 1",
 +
     "summary": "The first feature",
 +
     "link": "<nowiki>http://example.org/features/1</nowiki>"
 +
   },
 +
   "geometry": {
 +
     "type": "Point",
 +
     "coordinates": <nowiki>[[0.0,0.0]]</nowiki>
 
   }
 
   }
 
  }
 
  }
 +
 +
As in JSON, whitespace is irrelevant, so this is also valid GeoJSON:
 +
 +
{"id":"2","properties":{"title":"Feature 2","geometry":{"type":"Point","coordinates":<nowiki>[[1.0,1.0]]</nowiki>}}
 +
 +
=== 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": <nowiki>[[0.0,0.0]]</nowiki>
 +
  }
 +
 +
==== LineString ====
 +
  "geometry": {
 +
    "type": "LineString",
 +
    "crs": "EPSG:4326",
 +
    "coordinates": <nowiki>[[0.0,0.0],[1.0,0.0],[1.0,1.0]]</nowiki>
 +
  }
 +
 +
==== Polygon ====
 +
  "geometry": {
 +
    "type": "Polygon",
 +
    "crs": "EPSG:4326",
 +
    "coordinates": <nowiki>[[0.0,0.0],[1.0,0.0],[1.0,1.0],[0.0,1.0],[0.0,0.0]]</nowiki>,
 +
    "holes": [
 +
        <nowiki>[[0.25,0.25],[0.75,0.25],[0.75,0.75],[0.25,0.75],[0.25,0.25]],</nowiki>
 +
        <nowiki>[[0.1,0.1],[0.1,0.2],[0.2,0.2],[0.1,0.1]]</nowiki>
 +
    ]
 +
  }
 +
 +
==== Box ====
 +
  "geometry": {
 +
    "type": "Box",
 +
    "crs": "EPSG:4326",
 +
    "coordinates": <nowiki>[[0.0,0.0],[1.0,1.0]]</nowiki>
 +
  }
 +
 +
==== MultiPoint ====
 +
  "geometry": {
 +
    "type": "MultiPoint",
 +
    "crs": "EPSG:4326",
 +
    "coordinates": <nowiki>[[0.0,0.0],[1.0,1.0]]</nowiki>
 +
  }
 +
 +
==== MultiLineString ====
 +
  "geometry": {
 +
    "type": "MultiLineString",
 +
    "crs": "EPSG:4326",
 +
    "members": [
 +
      "geometry": {
 +
        "type": "LineString",
 +
        "coordinates": <nowiki>[[0.0,0.0],[1.0,0.0],[1.0,1.0]]</nowiki>
 +
      },
 +
      "geometry": {
 +
        "type": "LineString",
 +
        "coordinates": <nowiki>[[2.0,2.0],[3.0,2.0],[3.0,3.0]]</nowiki>
 +
      }
 +
    ]
 +
  }
 +
 +
==== MultiPolygon ====
 +
  "geometry": {
 +
    "type": "MultiPolygon",
 +
    "crs": "EPSG:4326",
 +
    "members": [
 +
      "geometry": {
 +
        "type": "Polygon",
 +
        "coordinates": <nowiki>[[0.0,0.0],[1.0,0.0],[1.0,1.0],[0.0,1.0],[0.0,0.0]]</nowiki>,
 +
        "holes": [
 +
            <nowiki>[[0.25,0.25],[0.75,0.25],[0.75,0.75],[0.25,0.75],[0.25,0.25]],</nowiki>
 +
            <nowiki>[[0.1,0.1],[0.1,0.2],[0.2,0.2],[0.1,0.1]]</nowiki>
 +
        ]
 +
      },
 +
      "geometry": {
 +
        "type": "Polygon",
 +
        "coordinates": <nowiki>[[10.0,10.0],[11.0,0.0],[11.0,11.0],[10.0,11.0],[10.0,10.0]]</nowiki>
 +
      }
 +
    ]
 +
  }
 +
 +
==== GeometryCollection ====
 +
  "geometry": {
 +
    "type": "GeometryCollection",
 +
    "crs": "EPSG:4326",
 +
    "members": [
 +
      "geometry": {
 +
        "type": "Point",
 +
        "coordinates": <nowiki>[[0.0,0.0]]</nowiki>
 +
      },
 +
      "geometry": {
 +
        "type": "LineString",
 +
        "coordinates": <nowiki>[[0.0,0.0],[1.0,0.0],[1.0,1.0]]</nowiki>
 +
      },
 +
      "geometry": {
 +
        "type": "Polygon",
 +
        "coordinates": <nowiki>[[0.0,0.0],[1.0,0.0],[1.0,1.0],[0.0,1.0],[0.0,0.0]]</nowiki>,
 +
        "holes": [
 +
            <nowiki>[[0.25,0.25],[0.75,0.25],[0.75,0.75],[0.25,0.75],[0.25,0.25]],</nowiki>
 +
            <nowiki>[[0.1,0.1],[0.1,0.2],[0.2,0.2],[0.1,0.1]]</nowiki>
 +
        ]
 +
      }
 +
    ]
 +
  }
 +
 +
==Authors==
 +
* Allan Doyle
 +
* Sean Gillies
 +
* Martin Daly

Latest revision as of 07:02, 25 May 2007

NOTICE

This is historical material. This page has been superseded by RFC-2.

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 | Polygon | 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 Polygon must have at least four coordinates, with the first and last coordinates coincident, i.e. the geometry must be closed.
        • A MultiPoint must have at least two coordinates.
    • For 'type' [Polygon]:
      • A Polygon may have a 'holes' name/value pair. The value of holes must itself be an array of array of coordinates, with each array of coordinates restricted as per the Polygon 'coordinates' value, i.e. it must be a closed ring with four or more coordinates. If present, the 'holes' array must contain at least one array of coordinates.
    • 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:nnnnn', where 'nnnnn' is replaced by the EPSG crs code, e.g. 'EPSG:27700'.
  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 [, elevation]" 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, so this is also valid GeoJSON:

{"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",
    "coordinates": [[0.0,0.0],[1.0,0.0],[1.0,1.0],[0.0,1.0],[0.0,0.0]],
    "holes": [
        [[0.25,0.25],[0.75,0.25],[0.75,0.75],[0.25,0.75],[0.25,0.25]],
        [[0.1,0.1],[0.1,0.2],[0.2,0.2],[0.1,0.1]]
    ]
  }

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",
        "coordinates": [[0.0,0.0],[1.0,0.0],[1.0,1.0],[0.0,1.0],[0.0,0.0]],
        "holes": [
            [[0.25,0.25],[0.75,0.25],[0.75,0.75],[0.25,0.75],[0.25,0.25]],
            [[0.1,0.1],[0.1,0.2],[0.2,0.2],[0.1,0.1]]
        ]
      },
      "geometry": {
        "type": "Polygon",
        "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",
        "coordinates": [[0.0,0.0],[1.0,0.0],[1.0,1.0],[0.0,1.0],[0.0,0.0]],
        "holes": [
            [[0.25,0.25],[0.75,0.25],[0.75,0.75],[0.25,0.75],[0.25,0.25]],
            [[0.1,0.1],[0.1,0.2],[0.2,0.2],[0.1,0.1]]
        ]
      }
    ]
 }

Authors

  • Allan Doyle
  • Sean Gillies
  • Martin Daly