From 61b837402eb0b5ec19f7c19e7710fdfbdbf47d71 Mon Sep 17 00:00:00 2001 From: Stefan Drees Date: Wed, 15 May 2013 08:20:26 +0200 Subject: [PATCH] added T. Schaub to the list of authors as requested per the mailing list and handled middle.mkd merge conflict from attempted 2nd pull merge by cowardly ignoring changes for now. Please request pull again based on new revision. Thanks --- middle.mkd | 408 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 408 insertions(+) create mode 100644 middle.mkd diff --git a/middle.mkd b/middle.mkd new file mode 100644 index 0000000..167b77f --- /dev/null +++ b/middle.mkd @@ -0,0 +1,408 @@ +# Introduction + +Geospatial JavaScript Object Notation (GeoJSON) is a format for +encoding a variety of geographic data structures. A GeoJSON object may +represent a geometry, a feature, or a collection of features. + +GeoJSON supports the following seven geometry types: + +* Point + +* LineString + +* Polygon + +* MultiPoint + +* MultiLineString + +* MultiPolygon + +* GeometryCollection + +GeoJSON also comprises the types: + +* Feature + +* FeatureCollection + +Features in GeoJSON contain a geometry object and additional +properties, and a FeatureCollection contains an array 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 +JSON literals: true, false, and null. An array consists of elements +where each element is a value as described above. + +## Conventions Used in This Document + +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 [RFC2119]. + +The ordering of the members of any JSON object defined in this +document MUST be considered irrelevant, as specified by [RFC4627]. + +The ordering of the elements of any JSON array defined in this +document MUST at least follow a stable ordering unless the specific +object's type it is a member of defines an absolute ordering, which +then takes precedence. + +Some examples use the combination of a JavaScript single line comment +(//) followed by an ellipsis (...) as placeholder notation for +content deemed irrelevant by the authors and at that point. These +placeholders must of course be deleted or otherwise replaced, before +attempting to validate the corresponding JSON code example. + +Note-sdrees: The second and third paragraph of this section have been +added, to not forget to satisfy the need of issueing structural +constraints with strong impact on interoperability (but not necessarily +at this place or in this form). + +## Definitions + +* JavaScript Object Notation (JSON), and the terms object, name, value, + array, number, true, false, and null are to be interpreted as + defined in [RFC4627]. + +* The Hypertext Transfer Protocol (HTTP) is defined in [RFC2616]. + +* Transport Layer Security (TLS) is defined in [RFC5246]. + +* Hypertext Transfer Protocol Over TLS (HTTPS) is defined in [RFC2818]. + +* The Uniform Resource Identifier (URI) is defined in [RFC3986]. + +* The Uniform Resource Name (URN) is defined in [RFC5165]. + +* Inside this document the term geometry types refers to the seven + case-sensitive strings: "Point", "MultiPoint", "LineString", + "MultiLineString", "Polygon", "MultiPolygon", and + "GeometryCollection". + +* As another shorthand notation the term GeoJSON types refers to the + nine case-senisitve strings "Feature", "FeatureCollection" and those + considered geometry types. + +* A hole is considered, for the sake of illustration, as simply a + geometric shape that is to be excluded from the geometric shape + it appears in. + +* When using the term interior geometric shape it is assumed, that + there exists an exterior shape so that the former is fully included + inside the convex hull of the latter. + +Note-sdrees: The last four items in the list above are added, to not +forget to satisfy the need of defining these terms (but not necessarily +at this place or in this form). + +Note-sdrees: We should consider adding at least an optional member +on the top-level GeoJSON object with name "namespace" and a value +of say "http://geojson.org/ns/geojson" or maybe something (after +acceptance by the IETF like "http://docs.ietf.org/ns/rfc9876" +hypothetically assuming this ends up as RFC9876) but then we might have +also to adapt the "no action needed from IANA section". +Then we might somewhere have a section "Namespace" explaining it in +general and amend its usage with: + +* The namespace member SHOULD be on the top-level GeoJSON object in the + following canonical hierarchical ordering, i.e. if present on a + feature collection, else if present on a feature, else on a geometry + and MUST NOT be repeated or overridden on children or + grandchildren of the object. + +Motivation for above proposal: The benefit would be, that we a) remain +backwards compatible, but b) avoid future clashes with JSON of unclear +provenience when being consumed by the client. Alternatively one might +prefix all wonderful type names with say "geo" and a dot or so (not +preferred) or even the names of the members (shiver). +Ammendment-20130511-sdrees: I would not call it profile as I am used to +profiles as changing the look of some core construct: adding something, +removing some other thing. But as we have no core concept published, +but two wide used dialects GeoJSON vs. ArcGIS JSON a namespace should +be the concept that fits more natrually. + +## Example + +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" + } + } + }] + } + +Note that unquoted whitespace is not significant in JSON. +Whitespace is used in the examples inside this document to help +illustrate the data structures, but is not required. + +# GeoJSON Object + +As stated in the introduction, a complete Geospatial JSON (GeoJSON) +data structure is always represented as a single JSON object that +represents a geometry, feature, or collection of features and will be +referred to as the GeoJSON object in this document. + +* The GeoJSON object MUST have one or more members (name/value pairs) + including a member with the name "type". This member's value is a + case-sensitive string that determines the type of the GeoJSON object + by being one of GeoJSON types. If - depending on this + value - additional rules apply, then these are stated in the + following sections where each type is further defined. + +* A GeoJSON object MAY have a "bbox" member. If it is present, + the value of it MUST be a bounding box array (see + "4. Bounding Box"). + +## Geometry Object + +A geometry is a GeoJSON object where the type member's value is a +geometry type. + +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 is determined by the type of geometry. + +### Position + +A position is the fundamental geometry construct. The "coordinates" +member of a geometry object is composed of either: + +* one position (in the case of a Point geometry), + +* an array of positions (LineString or MultiPoint geometries), + +* an array of arrays of positions (Polygons, MultiLineStrings), + +* or a multidimensional array of positions (MultiPolygon). + +<<<<<<< HEAD +A position is represented by an array of numbers. There MUST be two or +more elements. In general the first two elements will be World Geodetic +System (WGS 84) longitude and latitude, precisely in that order, and +a third (optionally) will be altitude in meters. +======= +A position is represented by an array of numbers. There MUST be two +or more elements. The first two elements will be World Geodedic System +(WGS 84) longitude and latitude. The optional third element will be +altitude in meters. +>>>>>>> 3c77b1dc14538cfdd5d32474193271fff183cb33 + +Any number of additional elements are allowed -- interpretation and +meaning of additional elements is beyond the scope of this +specification. + +GeoJSON data producers MAY indicate a different sense of the position +elements by including a "crsURN" object in the position's context. See +the Coordinate Reference System section below for details. + +Examples of positions and geometries are provided in "Appendix A. +Geometry Examples". + +### Point + +For type "Point", the "coordinates" member MUST be a single position. + +### MultiPoint + +For type "MultiPoint", the "coordinates" member MUST be an array of +positions. + +### LineString + +For type "LineString", the "coordinates" member MUST be an array of two +or more positions. + +### MultiLineString + +For type "MultiLineString", the "coordinates" member MUST be an array +of LineString coordinate arrays. + +### Polygon + +To specify a constraint specific to polygons, it is useful to introduce +the concept of a linear ring (LinearRing): + +* A LinearRing is a closed LineString with 4 or more positions. + +* The first and last positions are equivalent (they represent + equivalent points). + +Though a LinearRing is not explicitly represented as a GeoJSON geometry +type, it leads to a canonical formulation of the Polygon geometry type +definition as follows: + +* For type "Polygon", the "coordinates" member MUST be an array of + LinearRing coordinate arrays. + +* For Polygons with more than one of these rings, the first MUST be the + exterior ring and any others MUST be interior rings or holes. + +### MultiPolygon + +For type "MultiPolygon", the "coordinates" member MUST be an array of +Polygon coordinate arrays. + +### 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. + +## Feature Object + +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". + +## Feature Collection Object + +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. + +# Coordinate Reference System (CRS) + +<<<<<<< HEAD +The coordinate reference system of a GeoJSON object and the sense of +coordinate order is determined by the value of its "crsURN" member +(referred to as the CRS reference below). If an object has no crsURN +member, then its parent or grandparent object's crsURN member may be +acquired. If no crsURN 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. In an array of coordinate values, longitude is first and is + followed by latitude. + +* The value of a member named "crsURN" must be a string (referred to + as the CRS reference below) or JSON null. If the value of "crsURN" is + null, no CRS can be assumed. Note-sdrees: FIXME or default CRS as + when crsURN member is left out? It is optional anyway. + +* The crsURN member SHOULD be on the top-level GeoJSON object in the + following canonical hierarchical ordering, i.e. if present on a + feature collection, else if present on a feature, else on a geometry + and MUST NOT be repeated or overridden on children or + grandchildren of the object. + +Note-sdrees: The name has been changed from crs to crsURN to not +irritate consumers that expect the crs object as of version 1.0 in the +community spec. + +If present the CRS reference MUST indicate a coordinate reference +system by name. In this case, the value of it 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": + + "crsURN": "urn:ogc:def:crs:OGC:1.3:CRS84" + +For the format of a valid URN cf. [RFC5165]. +======= +The coordinate reference system of a GeoJSON object is a geographic +coordinate reference system, using the World Geodedic System 1984 +(WGS 84) datum, and with longitude and latitude units of decimal +degrees. +>>>>>>> 3c77b1dc14538cfdd5d32474193271fff183cb33 + +# Bounding Box + +A GeoJSON object MAY have a member named "bbox" to include information +on the coordinate range for geometries, features, or feature +collections. The value of the bbox member MUST be an array of length +2*n 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 +(longitude, latitude). + +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": [ + //... + ] + }