[Geojson] Editing the 1.0 text
Martin Daly
Martin.Daly at cadcorp.com
Thu May 15 07:28:53 PDT 2008
> I've taken it upon myself to edit the official 1.0 text. No changes
are
> being made to the spec, I'm only editing for clarity and consistency.
> Please reply with feedback ASAP, because the overwhelming consensus is
> that it's time to wrap this up.
>
> You can always see the latest at
>
>
http://zcologia.com/sgillies/hg/geojson-draft/file/tip/geojson-draft-6.t
xt
>
> with HTML version at
>
>
http://zcologia.com/sgillies/hg/geojson-draft/raw-file/tip/geojson-draft
-6.html
>
> and all changes logged at
>
> http://zcologia.com/sgillies/hg/geojson-draft/shortlog
I've attached an edited version of the draft text, with changes
summarised below:
1. Use keyword text from RFC2219
2. Clarify that x,y,z means easting,northing,altitude for a projected
crs
3. Move LinearRing description to its own paragraph
4. Allow null as the value for a feature object properties member
5. Reworded 3 to avoid (my) confusion between CRS, crs member, and crs
object
6. Added a clause to 3 to suggest that the top-level GeoJSON object
should be the crs owner
7. Changed the example file extension to be .crs, instead of .proj, and
the type to "ogcwkt" for variety
8. Changed a couple of mentions of "spatial reference" to "coordinate
reference system"
9. Changed a should to a must in 4. Bounding boxes
10. Fixed some typos
11. Moved myself to the top of the list of contributors.
12. I was joking about 11.
That means I did sneak one hard change to the spec in there, which is to
allowing as the value for the properties member of a feature object.
That was just for consistency with geometry. If you can have a feature
with properties and no geometry, then why not a feature with geometry
and no properties?
There is also a soft change related to crs objects being only on the
parent or grandparent of an object. This reflects my prejudice that the
feature collection should be the holder, if present, and that the crs
should (but not must, hence the soft change) be homogeneous within the
feature collection.
M
-------------- next part --------------
================================
The GeoJSON Format Specification
================================
:Editor: Sean Gillies
:Organization: Ancient World Mapping Center, University of North Carolina at Chapel Hill
:Contact Address: sgillies at frii.com
:revision: 1.0
:date: 9 May 2008
:copyright: This work is licensed under a `Creative Commons Attribution 3.0 United States License`__.
.. __: http://creativecommons.org/licenses/by/3.0/us/
:Abstract: GeoJSON is a geospatial data interchange format based on JavaScript Object Notation (JSON).
.. contents::
1. Introduction
===============
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 GeometryCollection. 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.
1.1. Examples
-------------
A GeoJSON feature collection::
{ "type": "FeatureCollection",
"features": [
{ "type": "Feature",
"geometry": {"type": "Point", "coordinates": [102.0, 0.5]},
"properties": {"prop0": "value0"}
},
{ "type": "Feature",
"geometry": {
"type": "LineString",
"coordinates": [
[102.0, 0.0], [103.0, 1.0], [104.0, 0.0], [105.0, 1.0]
]
},
"properties": {
"prop0": "value0",
"prop1": 0.0
}
},
{ "type": "Feature",
"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": {"this": "that"}
}
}
]
}
1.2. Definitions
----------------
* JavaScript Object Notation (JSON), and the terms object, name, value, array,
and number, are defined in IETF RTC 4627, at http://www.ietf.org/rfc/rfc4627.txt.
* The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in IETF RFC 2219, at http://www.ietf.org/rfc/rfc4627.txt.
2. GeoJSON Objects
==================
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 must have a member with the name "type". This member's
value is a string that determines the type of the GeoJSON object.
* The value of the type member must be one of: "Point", "MultiPoint",
"LineString", "MultiLineString", "Polygon", "MultiPolygon",
"GeometryCollection", "Feature", or "FeatureCollection". "type" must be lower
case, the case of the type member values must be as shown here.
* A GeoJSON object may have an optional "crs" member, the value of which must
be a coordinate reference system object (see `3. Coordinate Reference System
Objects`_).
* A GeoJSON object may have a "bbox" member, the value of which must be a
bounding box array (see `4. Bounding Boxes`_).
2.1 Geometry Objects
--------------------
A geometry is a GeoJSON object where the type member's value is one of the
following strings: "Point", "MultiPoint", "LineString", "MultiLineString",
"Polygon", "MultiPolygon", or "GeometryCollection".
A GeoJSON geometry object of any type other than "GeometryCollection" must have
a member with the name "coordinates". The value of the coordinates member is
always an array. The structure for the elements in this array are determined by
the type of geometry.
2.1.1. Point
............
For type "Point", each element in the coordinates array is a number
representing the point coordinate in one dimension. There must be at least two
elements, and may be more. The order of elements must follow x, y, z order
(easting, northing, altitude for coordinates in a projected coordinate reference
system, or longitude, latitude, altitude for coordinates in a geographic coordinate
reference system). Any number of additional dimensions are allowed, and
interpretation and meaning of these coordinates is beyond the scope of this
specification.
2.1.2. MultiPoint
.................
For type "MultiPoint", each element in the coordinates array is a coordinates
array as described for type "Point".
2.1.3. LineString
.................
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.
2.1.4. MultiLineString
......................
For type "MultiLineString", each element in the coordinates array is a
coordinates array as described for type "LineString".
2.1.5. Polygon
..............
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.
2.1.6. MultiPolygon
...................
For type "MultiPolygon", each element in the coordinates array is a coordinates
array as described for type "Polygon".
2.1.7 Geometry Collection
.........................
A GeoJSON object with type "GeometryCollection" is a geometry object
which represents a collection of geometry objects.
A geometry collection must have a member with the name "geometries". The value
corresponding to "geometries" is an array. Each element in this array is a
GeoJSON geometry object.
2.2. Feature Objects
--------------------
A GeoJSON object with the type "Feature" is a feature object.
* A feature object must have a member with the name "geometry". The value of
the geometry member is a geometry object as defined above or a JSON null
value.
* A feature object must have a member with the name "properties". The value of
the properties member is an object (any JSON object or a JSON null value).
* If a feature has a commonly used identifier, that identifier should be
included as a member of the feature object with the name "id".
2.3. Feature Collection Objects
-------------------------------
A GeoJSON object with the type "FeatureCollection" is a feature collection
object.
An object of type "FeatureCollection" must have a member with the name
"features". The value corresponding to "features" is an array. Each element in
the array is a feature object as defined above.
3. Coordinate Reference System Objects
======================================
The coordinate reference system (CRS) of a GeoJSON object is determined by its
"crs" member (referred to as the crs object below). If an object has no crs
member, then its parent or grandparent object's crs member may be acquired.
If no crs member can be so acquired, the default CRS shall apply to the GeoJSON object.
* The default CRS is a geographic coordinate reference system, using the WGS84
datum, and with longitude and latitude units of decimal degrees.
* The crs member should be on the top-level GeoJSON object in a hierarchy (in
feature collection, feature, geometry order) and should
not be repeated or overridden on children or grandchildren of the object.
* The value of the crs member must be a JSON object or a JSON null value. If the value of
the crs member is null, then the default CRS can be assumed. A non-null crs object has
two mandatory members: "type", and "properties".
* The value of the type member must be a string, indicating the type of crs
object.
* The value of the properties member must be an object. This specification
defines two types of crs objects.
3.1. Named CRS
--------------
A crs object may indicate a coordinate reference system by name. The value of
its "properties" member must be an object containing a "name" member. The value
of that "name" member must be a string identifying a coordinate reference
system. OGC CRS URNs such as "urn\:ogc:def:crs:OGC:1.3:CRS84" shall be
preferred over legacy identifiers such as "EPSG:4326"::
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:OGC:1.3:CRS84"
}
}
3.2. Linked CRS
---------------
A crs object may link to CRS parameters on the Web. In this case the value of
its "properties" member must be a Link object (see `3.2.1. Link Objects`_).
3.2.1. Link Objects
...................
A link object has one required member: "href", and one optional member: "type".
The value of the required "href" member must be a dereferenceable URI.
The value of the optional "type" member must be a string that hints at the
format used to represent CRS parameters at the provided URI. Suggested values
are: "proj4", "ogcwkt", "esriwkt", but others can be used::
"crs": {
"type": "link",
"properties": {
"href": "http://example.com/crs/42",
"type": "proj4"
}
}
Relative links may be used to direct processors to CRS parameters in an
auxiliary file::
"crs": {
"type": "link",
"properties": {
"href": "data.crs",
"type": "ogcwkt"
}
}
4. Bounding Boxes
=================
To include information on the coordinate range for geometries, features, or
feature collections, a GeoJSON object may have a member named "bbox". The value
of the bbox member must be a 2*n array where n is the number of
dimensions represented in the contained geometries, with the lowest values for all
axes followed by the highest values. The axes order of a bbox follows the axes order of
geometries. In addition, the coordinate reference system for the bbox is assumed to match
the coordinate reference system of the GeoJSON object of which it is a member.
Example of a bbox member on a feature::
{ "type": "Feature",
"bbox": [-180.0, -90.0, 180.0, 90.0],
"geometry": {
"type": "Polygon",
"coordinates": [[
[-180.0, 10.0], [20.0, 90.0], [180.0, -5.0], [-30.0, -90.0]
]]
}
...
}
Example of a bbox member on a feature collection::
{ "type": "FeatureCollection",
"bbox": [100.0, 0.0, 105.0, 1.0],
"features": [
...
]
}
Appendix A. Geometry 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.
Point
-----
Point coordinates are in x, y order (easting, northing for projected coordinates,
longitude, latitude for geographic coordinates)::
{ "type": "Point", "coordinates": [100.0, 0.0] }
LineString
----------
Coordinates of LineString are an array of Point coordinate arrays::
{ "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 coordinate arrays::
{ "type": "MultiPoint",
"coordinates": [ [100.0, 0.0], [101.0, 1.0] ]
}
MultiLineString
---------------
Coordinates of a MultiLineString are an array of LineString coordinate arrays::
{ "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 coordinate arrays::
{ "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]]]
]
}
GeometryCollection
------------------
Each element in the geometries array of a GeometryCollection is one of the
geometry objects described above::
{ "type": "GeometryCollection",
"geometries": [
{ "type": "Point",
"coordinates": [100.0, 0.0]
},
{ "type": "LineString",
"coordinates": [ [101.0, 0.0], [102.0, 1.0] ]
}
]
}
Appendix B. Contributors
========================
The GeoJSON format specification is the product of discussion on the GeoJSON
list:
http://lists.geojson.org/listinfo.cgi/geojson-geojson.org
The following people contributed to draft versions of this document:
* Steve Battey
* Howard Butler
* Martin Daly
* Allan Doyle
* Sean Gillies
* Tim Schaub
* Christopher Schmidt
* Andrew Turner
More information about the GeoJSON
mailing list