idnits 2.17.1 draft-ietf-geojson-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (May 13, 2016) is 2897 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFC5870' is mentioned on line 751, but not defined == Missing Reference: '-170' is mentioned on line 707, but not defined -- Looks like a reference, but probably isn't: '10' on line 707 -- Looks like a reference, but probably isn't: '170' on line 708 -- Looks like a reference, but probably isn't: '11' on line 708 ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Possible downref: Non-RFC (?) normative reference: ref. 'WGS84' Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 GeoJSON H. Butler 3 Internet-Draft Hobu Inc. 4 Intended status: Standards Track M. Daly 5 Expires: November 14, 2016 Cadcorp 6 A. Doyle 8 S. Gillies 9 Mapbox 10 S. Hagen 12 T. Schaub 13 Planet Labs 14 May 13, 2016 16 The GeoJSON Format 17 draft-ietf-geojson-03 19 Abstract 21 GeoJSON is a geospatial data interchange format based on JavaScript 22 Object Notation (JSON). It defines several types of JSON objects and 23 the manner in which they are combined to represent data about 24 geographic features, their properties, and their spatial extents. 25 This document recommends a single coordinate reference system based 26 on WGS 84. Other coordinate reference systems are not recommended. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at http://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on November 14, 2016. 45 Copyright Notice 47 Copyright (c) 2016 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 4 64 1.2. Conventions Used in This Document . . . . . . . . . . . . 4 65 1.3. Specification of GeoJSON . . . . . . . . . . . . . . . . 4 66 1.4. Definitions . . . . . . . . . . . . . . . . . . . . . . . 5 67 1.5. Example . . . . . . . . . . . . . . . . . . . . . . . . . 5 68 2. GeoJSON Text . . . . . . . . . . . . . . . . . . . . . . . . 7 69 3. GeoJSON Object . . . . . . . . . . . . . . . . . . . . . . . 7 70 3.1. Geometry Object . . . . . . . . . . . . . . . . . . . . . 7 71 3.1.1. Position . . . . . . . . . . . . . . . . . . . . . . 7 72 3.1.2. Point . . . . . . . . . . . . . . . . . . . . . . . . 8 73 3.1.3. MultiPoint . . . . . . . . . . . . . . . . . . . . . 9 74 3.1.4. LineString . . . . . . . . . . . . . . . . . . . . . 9 75 3.1.5. MultiLineString . . . . . . . . . . . . . . . . . . . 9 76 3.1.6. Polygon . . . . . . . . . . . . . . . . . . . . . . . 9 77 3.1.7. MultiPolygon . . . . . . . . . . . . . . . . . . . . 10 78 3.1.8. Geometry Collection . . . . . . . . . . . . . . . . . 10 79 3.1.9. Antimeridian Cutting . . . . . . . . . . . . . . . . 10 80 3.1.10. Uncertainty and Confidence . . . . . . . . . . . . . 11 81 3.2. Feature Object . . . . . . . . . . . . . . . . . . . . . 12 82 3.3. Feature Collection Object . . . . . . . . . . . . . . . . 12 83 4. Coordinate Reference System . . . . . . . . . . . . . . . . . 12 84 5. Bounding Box . . . . . . . . . . . . . . . . . . . . . . . . 13 85 5.1. The Connecting Lines . . . . . . . . . . . . . . . . . . 14 86 5.2. The Antimeridian . . . . . . . . . . . . . . . . . . . . 14 87 5.3. The Poles . . . . . . . . . . . . . . . . . . . . . . . . 15 88 6. Extending GeoJSON . . . . . . . . . . . . . . . . . . . . . . 15 89 6.1. Foreign Members . . . . . . . . . . . . . . . . . . . . . 15 90 7. GeoJSON Types are not Extensible . . . . . . . . . . . . . . 16 91 7.1. Semantics of GeoJSON Members and Types are not Changeable 16 92 8. Versioning . . . . . . . . . . . . . . . . . . . . . . . . . 17 93 9. Mapping 'geo' URIs . . . . . . . . . . . . . . . . . . . . . 17 94 10. Security Considerations . . . . . . . . . . . . . . . . . . . 18 95 11. Interoperability Considerations . . . . . . . . . . . . . . . 18 96 11.1. I-JSON . . . . . . . . . . . . . . . . . . . . . . . . . 18 97 11.2. Coordinate Precision . . . . . . . . . . . . . . . . . . 18 98 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 99 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 19 100 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 101 14.1. Normative References . . . . . . . . . . . . . . . . . . 20 102 14.2. Informative References . . . . . . . . . . . . . . . . . 20 103 Appendix A. Geometry Examples . . . . . . . . . . . . . . . . . 21 104 A.1. Points . . . . . . . . . . . . . . . . . . . . . . . . . 21 105 A.2. LineStrings . . . . . . . . . . . . . . . . . . . . . . . 21 106 A.3. Polygons . . . . . . . . . . . . . . . . . . . . . . . . 21 107 A.4. MultiPoints . . . . . . . . . . . . . . . . . . . . . . . 22 108 A.5. MultiLineStrings . . . . . . . . . . . . . . . . . . . . 23 109 A.6. MultiPolygons . . . . . . . . . . . . . . . . . . . . . . 23 110 A.7. GeometryCollections . . . . . . . . . . . . . . . . . . . 24 111 Appendix B. Changes from pre-IETF Specification . . . . . . . . 25 112 B.1. Normative Changes . . . . . . . . . . . . . . . . . . . . 25 113 B.2. Informative Changes . . . . . . . . . . . . . . . . . . . 26 114 Appendix C. GeoJSON Text Sequences . . . . . . . . . . . . . . . 26 115 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 117 1. Introduction 119 GeoJSON is a format for encoding a variety of geographic data 120 structures using JavaScript Object Notation (JSON) [RFC7159]. A 121 GeoJSON object may represent a region of space (a Geometry), a 122 spatially-bounded entity (a Feature), or a list of features (a 123 Feature Collection). GeoJSON supports the following geometry types: 124 Point, LineString, Polygon, MultiPoint, MultiLineString, 125 MultiPolygon, and GeometryCollection. Features in GeoJSON contain a 126 geometry object and additional properties, and a Feature Collection 127 contains a list of features. 129 The format is concerned with geographic data in the broadest sense; 130 any thing with qualities that are bounded in geographical space might 131 be a feature whether it is a physical structure or not. The concepts 132 in GeoJSON are not new; they are derived from pre-existing open 133 geographic information system standards and have been streamlined to 134 better suit web application development using JSON. 136 GeoJSON comprises the seven concrete geometry types defined in the 137 OpenGIS Simple Features Implementation Specification for SQL [SFSQL]: 138 0-dimensional Point and MultiPoint; 1-dimensional curve LineString 139 and MultiLineString; 2-dimensional surface Polygon and MultiPolygon; 140 and the heterogeneous GeometryCollection. GeoJSON representations of 141 instances of these geometry types are analogous to the well-known 142 binary (WKB) and text (WKT) representations described in that same 143 specification. 145 GeoJSON also comprises the types Feature and FeatureCollection. 146 Feature objects in GeoJSON contain a geometry object with one of the 147 above geometry types and additional members. A FeatureCollection 148 object contains an array of feature objects. This structure is 149 analogous to that of the Web Feature Service (WFS) response to 150 GetFeatures requests specified in [WFSv1] or to a KML Folder of 151 Placemarks [KMLv2.2]. Some implementations of the WFS specification 152 also provide GeoJSON formatted responses to GetFeature requests, but 153 there is no particular service model or feature type ontology implied 154 in the GeoJSON format specification. 156 Since its initial publication in 2008 [GJ2008], the GeoJSON format 157 specification has steadily grown in popularity. It is widely used in 158 JavaScript web mapping libraries, JSON-based document databases, and 159 web APIs. 161 1.1. Requirements Language 163 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 164 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 165 "OPTIONAL" in this document are to be interpreted as described in 166 [RFC2119]. 168 1.2. Conventions Used in This Document 170 The ordering of the members of any JSON object defined in this 171 document MUST be considered irrelevant, as specified by [RFC7159]. 173 Some examples use the combination of a JavaScript single line comment 174 (//) followed by an ellipsis (...) as placeholder notation for 175 content deemed irrelevant by the authors. These placeholders must of 176 course be deleted or otherwise replaced, before attempting to 177 validate the corresponding JSON code example. 179 Whitespace is used in the examples inside this document to help 180 illustrate the data structures, but is not required. Unquoted 181 whitespace is not significant in JSON. 183 1.3. Specification of GeoJSON 185 This document updates the original GeoJSON format specification 186 [GJ2008]. 188 1.4. Definitions 190 o JavaScript Object Notation (JSON), and the terms object, member, 191 name, value, array, number, true, false, and null are to be 192 interpreted as defined in [RFC7159]. 194 o Inside this document the term "geometry type" refers to the seven 195 case-sensitive strings: "Point", "MultiPoint", "LineString", 196 "MultiLineString", "Polygon", "MultiPolygon", and 197 "GeometryCollection". 199 o As another shorthand notation, the term "GeoJSON types" refers to 200 the nine case-sensitive strings "Feature", "FeatureCollection" and 201 the geometry types listed above. 203 o The word "Collection" in "FeatureCollection" and 204 "GeometryCollection" does not have any significance for the 205 semantics of array members. The "features" and "geometries" 206 members, respectively, of these objects are standard ordered JSON 207 arrays, not unordered sets. 209 1.5. Example 211 A GeoJSON feature collection: 213 { 214 "type": "FeatureCollection", 215 "features": [{ 216 "type": "Feature", 217 "geometry": { 218 "type": "Point", 219 "coordinates": [102.0, 0.5] 220 }, 221 "properties": { 222 "prop0": "value0" 223 } 224 }, { 225 "type": "Feature", 226 "geometry": { 227 "type": "LineString", 228 "coordinates": [ 229 [102.0, 0.0], 230 [103.0, 1.0], 231 [104.0, 0.0], 232 [105.0, 1.0] 233 ] 234 }, 235 "properties": { 236 "prop0": "value0", 237 "prop1": 0.0 238 } 239 }, { 240 "type": "Feature", 241 "geometry": { 242 "type": "Polygon", 243 "coordinates": [ 244 [ 245 [100.0, 0.0], 246 [101.0, 0.0], 247 [101.0, 1.0], 248 [100.0, 1.0], 249 [100.0, 0.0] 250 ] 251 ] 252 }, 253 "properties": { 254 "prop0": "value0", 255 "prop1": { 256 "this": "that" 257 } 258 } 259 }] 260 } 262 2. GeoJSON Text 264 A GeoJSON text is a JSON text and consists of a single GeoJSON 265 object. 267 3. GeoJSON Object 269 A GeoJSON object represents a geometry, feature, or collection of 270 features. 272 o A GeoJSON object is a JSON object. 274 o A GeoJSON object MUST have a member with the name "type". The 275 value of the member MUST be one of the GeoJSON types. 277 o A GeoJSON object MAY have a "bbox" member, the value of which MUST 278 be a bounding box array (see Section 5). 280 o A GeoJSON object MAY have any number of other members (see 281 Section 6). 283 3.1. Geometry Object 285 A Geometry object represents points, curves, and surfaces in 286 coordinate space. 288 o The value of a geometry object's "type" member MUST be one of the 289 seven geometry types (see Section 1.4). 291 o A GeoJSON geometry object of any type other than 292 "GeometryCollection" MUST have a member with the name 293 "coordinates". The value of the coordinates member is always an 294 array. The structure of the elements in this array is determined 295 by the type of geometry. GeoJSON processors MAY interpret 296 geometry objects with empty coordinates arrays as null objects. 298 3.1.1. Position 300 A position is the fundamental geometry construct. The "coordinates" 301 member of a geometry object is composed of either: 303 o one position in the case of a Point geometry, 305 o an array of positions in the case of a LineString or MultiPoint 306 geometry, 308 o an array of LineString or linear ring (see Section 3.1.6) 309 coordinates in the case of a Polygon or MultiLineString geometry, 311 o or an array of Polygon coordinates in the case of a MultiPolygon 312 geometry. 314 A position is an array of numbers. There MUST be two or more 315 elements. The first two elements are longitude and latitude, or 316 easting and northing, precisely in that order and using decimal 317 numbers. Altitude or elevation MAY be included as an optional third 318 element. 320 Implementations SHOULD NOT extend positions beyond 3 elements because 321 the semantics of extra elements are unspecified and ambiguous. 322 Historically, some implementations have used a 4th element to carry a 323 linear referencing measure (sometimes denoted as "M") or a numerical 324 timestamp, but in most situations a parser will not be able to 325 properly interpret these values. The interpretation and meaning of 326 additional elements is beyond the scope of this specification and 327 additional elements MAY be ignored by parsers. 329 A line between two positions is a straight Cartesian line, the 330 shortest line between those two points in the Coordinate Reference 331 System (see Section 4). 333 In other words, every point on a line that does not cross the 334 antimeridian between a point (lon0, lat0) and (lon1, lat1) can be 335 calculated as 337 F(lon, lat) = (lon0 + (lon1 - lon0) * t, lat0 + (lat1 - lat0) * t) 339 with t a real number greater or equal to 0 and smaller or equal to 1. 340 Note that this line may markedly differ from the geodesic path along 341 the curved surface of the reference ellipsoid. 343 The same applies to the optional height element with the proviso that 344 the direction of the height is as specified in the Coordinate 345 Reference System. 347 Note that, again, this does not mean that a surface with equal height 348 follows, for example, the curvature of a body of water. Nor is a 349 surface of equal height perpendicular to a plumb line. 351 Examples of positions and geometries are provided in "Appendix A. 352 Geometry Examples". 354 3.1.2. Point 356 For type "Point", the "coordinates" member MUST be a single position. 358 3.1.3. MultiPoint 360 For type "MultiPoint", the "coordinates" member MUST be an array of 361 positions. 363 3.1.4. LineString 365 For type "LineString", the "coordinates" member MUST be an array of 366 two or more positions. 368 3.1.5. MultiLineString 370 For type "MultiLineString", the "coordinates" member MUST be an array 371 of LineString coordinate arrays. 373 3.1.6. Polygon 375 To specify a constraint specific to polygons, it is useful to 376 introduce the concept of a linear ring: 378 o A linear ring is a closed LineString with 4 or more positions. 380 o The first and last positions are equivalent, they MUST contain 381 identical values; their representation SHOULD also be identical. 383 o A linear ring is the boundary of a surface or the boundary of a 384 hole in a surface. 386 o A linear ring SHOULD follow the right-hand rule with respect to 387 the area it bounds (i.e., exterior rings are counter-clockwise, 388 holes are clockwise) 390 Though a linear ring is not explicitly represented as a GeoJSON 391 geometry type, it leads to a canonical formulation of the Polygon 392 geometry type definition as follows: 394 o For type "Polygon", the "coordinates" member MUST be an array of 395 linear ring coordinate arrays. 397 o For Polygons with more than one of these rings, the first MUST be 398 the exterior ring and any others MUST be interior rings. The 399 exterior ring bounds the surface, and the interior rings (if 400 present) bound holes within the surface. 402 3.1.7. MultiPolygon 404 For type "MultiPolygon", the "coordinates" member MUST be an array of 405 Polygon coordinate arrays. 407 3.1.8. Geometry Collection 409 A GeoJSON object with type "GeometryCollection" is a geometry object. 410 A geometry collection MUST have a member with the name "geometries". 411 The value of "geometries" is an array. Each element of this array is 412 a GeoJSON geometry object. It is possible for this array to be 413 empty. 415 Unlike the other geometry types described above, a geometry 416 collection can be a heterogeneous composition of smaller geometry 417 objects. For example, a geometry object in the shape of a lowercase 418 roman "i" can be composed of one point and one line string. 420 Geometry collections have a different syntax from single type 421 geometry objects (Point, LineString, and Polygon) and homogeneously 422 typed multipart geometry objects (MultiPoint, MultiLineString, and 423 MultiPolygon) but have no different semantics. Although a geometry 424 collection object has no "coordinates" member, it does have 425 coordinates: the coordinates of all its parts belong to the 426 collection. The "geometries" member of a geometry collection 427 describes the parts of this composition. Implementations SHOULD NOT 428 apply any additional semantics to the "geometries" array. 430 To maximize interoperability implementations SHOULD avoid nested 431 geometry collections. Furthermore, geometry collections composed of 432 a single part or a number of parts of a single type SHOULD be avoided 433 when that single part or a single object of multi-part type 434 (MultiPoint, MultiLineString, or MultiPolygon) could be used instead. 436 3.1.9. Antimeridian Cutting 438 In representing features that cross the antimeridian, 439 interoperability is improved by modifying their geometry. Any 440 geometry that crosses the antimeridian SHOULD be represented by 441 cutting it in two such that neither part's representation crosses the 442 antimeridian. 444 For example, a line extending from 45 degrees N, 170 degrees E across 445 the antimeridian to 45 degrees N, 170 degrees W should be cut in two 446 and represented as a MultiLineString. 448 { 449 "type": "MultiLineString", 450 "coordinates": [ 451 [ 452 [170.0, 45.0], [180.0, 45.0] 453 ], [ 454 [-180.0, 45.0], [-170.0, 45.0] 455 ] 456 ] 457 } 459 A rectangle extending from 40 degrees N, 170 degrees E across the 460 antimeridian to 50 degrees N, 170 degrees W should be cut in two and 461 represented as a MultiPolygon. 463 { 464 "type": "MultiPolygon", 465 "coordinates": [ 466 [ 467 [ 468 [180.0, 40.0], [180.0, 50.0], [170.0, 50.0], 469 [170.0, 40.0], [180.0, 40.0] 470 ] 471 ], 472 [ 473 [ 474 [-170.0, 40.0], [-170.0, 50.0], [-180.0, 50.0], 475 [-180.0, 40.0], [-170.0, 40.0] 476 ] 477 ] 478 ] 479 } 481 3.1.10. Uncertainty and Confidence 483 As per [RFC7459] no measure of location uncertainty or confidence can 484 be known for "Point", "MultiPoint", "LineString", or 485 "MultiLineString" geometry types. 487 Applications such as PIDF-LO that are sensitive to location 488 uncertainty and confidence might treat a geometry object of type 489 "Polygon", "MultiPolygon", and "GeometryCollection" as a 490 representation of a 95% confidence surface. In probabilistic terms: 491 95 percent of the location's point set is contained within the 492 GeoJSON geometry. 494 As in [RFC5870] the number of digits of the values in coordinate 495 positions MUST NOT be interpreted as an indication to the level of 496 uncertainty. 498 3.2. Feature Object 500 A Feature object represents a spatially-bounded thing. 502 o A feature object MUST have a "type" member with the value 503 "Feature". 505 o A feature object MUST have a member with the name "geometry". The 506 value of the geometry member SHALL be either a geometry object as 507 defined above or, in the the case that the feature is unlocated, a 508 JSON null value. 510 o A feature object MUST have a member with the name "properties". 511 The value of the properties member is an object (any JSON object 512 or a JSON null value). 514 o If a feature has a commonly used identifier, that identifier 515 SHOULD be included as a member of the feature object with the name 516 "id", and the value of this member is either a JSON string or 517 number. 519 3.3. Feature Collection Object 521 A GeoJSON object with the type "FeatureCollection" is a feature 522 collection object. A feature collection object MUST have a member 523 with the name "features". The value of "features" is a JSON array. 524 Each element of the array is a feature object as defined above. It 525 is possible for this array to be empty. 527 4. Coordinate Reference System 529 The coordinate reference system for all GeoJSON coordinates is a 530 geographic coordinate reference system, using the WGS 84 [WGS84] 531 datum, and with longitude and latitude units of decimal degrees. 532 This coordinate reference system is equivalent to the OGC's "http:// 533 www.opengis.net/def/crs/OGC/1.3/CRS84" [OGCURL]. An OPTIONAL third 534 position element SHALL be the height in meters above or below the WGS 535 84 reference ellipsoid. In the absence of elevation values, 536 applications sensitive to height or depth SHOULD interpret positions 537 as being at local ground or sea level. 539 Note: the use of alternative coordinate reference systems was 540 specified in [GJ2008], but has been removed from this version of the 541 specification because the use of different coordinate reference 542 systems -- especially in the manner specified in [GJ2008] -- has 543 proven to have interoperability issues. In general, GeoJSON 544 processing software is not expected to have access to coordinate 545 reference systems databases or to to have network access to 546 coordinate reference system transformation parameters. However, 547 where all involved parties have a prior arrangement, alternative 548 coordinate reference systems can be used without risk of data being 549 misinterpreted. 551 5. Bounding Box 553 A GeoJSON object MAY have a member named "bbox" to include 554 information on the coordinate range for its geometries, features, or 555 feature collections. The value of the bbox member MUST be an array 556 of length 2*n where n is the number of dimensions represented in the 557 contained geometries, with all axes of the most south-westerly point 558 followed by all axes of the more north-easterly point. The axes 559 order of a bbox follows the axes order of geometries. 561 The "bbox" values define shapes with edges that follow lines of 562 constant longitude, latitude, and elevation. 564 Example of a 2D bbox member on a feature: 566 { 567 "type": "Feature", 568 "bbox": [-10.0, -10.0, 10.0, 10.0], 569 "geometry": { 570 "type": "Polygon", 571 "coordinates": [ 572 [ 573 [-10.0, -10.0], 574 [10.0, -10.0], 575 [10.0, 10.0], 576 [-10.0, -10.0] 577 ] 578 ] 579 } 580 //... 581 } 583 Example of a 2D bbox member on a feature collection: 585 { 586 "type": "FeatureCollection", 587 "bbox": [100.0, 0.0, 105.0, 1.0], 588 "features": [ 589 //... 590 ] 591 } 593 Example of a 3D bbox member with a depth of 100 meters: 595 { 596 "type": "FeatureCollection", 597 "bbox": [100.0, 0.0, -100.0, 105.0, 1.0, 0.0], 598 "features": [ 599 //... 600 ] 601 } 603 5.1. The Connecting Lines 605 The 4 lines of the bounding box are defined fully within the 606 coordinate reference system; i.e. every point on the northernmost 607 line can be expressed as 609 (lon, lat) = (%minlon% + (%maxlon% - %minlon%) * t, %maxlat%) 611 with 0 <= t <= 1. 613 5.2. The Antimeridian 615 Consider a set of point features within the Fiji archipelago, 616 straddling the antimeridian between 16 degrees S and 20 degrees S. 617 The southwest corner of the box containing these features is at 20 618 degrees S and 177 degrees E, the northwest corner is at 16 degrees S 619 and 178 degrees W. The antimeridian-spanning GeoJSON bounding box for 620 this feature collection is 622 "bbox": [177.0, -20.0, -178.0, -16.0] 624 and covers 5 degrees of longitude. 626 The complementary bounding box for the same latitude band, not 627 crossing the antimeridian, is 629 "bbox": [-178.0, -20.0, 177.0, -16.0] 631 and covers 355 degrees of longitude. 633 The latitude of the northeast corner is always greater than the 634 latitude of the southwest corner, but bounding boxes that cross the 635 antimeridian have a northeast corner longitude that is less than the 636 longitude of the southwest corner. 638 5.3. The Poles 640 A bounding box that contains the North Pole extends from a southwest 641 corner of %minlat% degrees N, 180 degrees W to a northeast corner of 642 90 degrees N, 180 degrees E. Viewed on a globe, this bounding box 643 approximates a spherical cap. 645 "bbox": [-180.0, %minlat%, 180.0, 90.0] 647 A bounding box that contains the South Pole extends from a southwest 648 corner of 90 degrees S, 180 degrees W to a northeast corner of 649 %maxlat% degrees S, 180 degrees E. 651 "bbox": [-180.0, -90.0, 180.0, %maxlat%] 653 A bounding box that just touches the North Pole and forms a slice of 654 an approximate spherical cap when viewed on a globe has as its 655 northeast corner coordinates the easternmost longitude value and 90 656 degrees N. 658 "bbox": [%westlon%, %minlat%, %eastlon%, 90.0] 660 A bounding box that just touches the South Pole and forms a slice of 661 an approximate spherical cap when viewed on a globe has as its 662 southwest corner coordinates the westernmost longitude value and 90 663 degrees S. 665 "bbox": [%westlon%, -90.0, %eastlon%, %maxlat%] 667 Implementers MUST NOT use latitude values greater than 90 or less 668 than -90 to imply an extent that is not a spherical cap. 670 6. Extending GeoJSON 672 6.1. Foreign Members 674 Members not described in this specification ("foreign members") MAY 675 be used in a GeoJSON document. Note that support for foreign members 676 can vary across implementations and no normative processing model for 677 foreign members is defined. Accordingly, implementations that rely 678 too heavily on the use of foreign members might experience reduced 679 interoperability with other implementations. 681 For example, in the (abridged) feature object shown below 683 { 684 "type": "Feature", 685 "id": "f1", 686 "geometry": {...}, 687 "properties": {...}, 688 "title": "Example Feature" 689 } 691 the name/value pair of "title": "Example Feature" is a foreign 692 member. When the value of a foreign member is an object, all the 693 descendant members of that object are themselves foreign members. 695 GeoJSON semantics do not apply to foreign members and their 696 descendants, regardless of their names and values. For example, in 697 the (abridged) feature object below 699 { 700 "type": "Feature", 701 "id": "f2", 702 "geometry": {...}, 703 "properties": {...}, 704 "centerline": { 705 "type": "LineString", 706 "coordinates": [ 707 [-170, 10], 708 [170, 11] 709 ] 710 } 711 } 713 the "centerline" member is not a GeoJSON geometry object. 715 7. GeoJSON Types are not Extensible 717 Implementations MUST NOT extend the fixed set of GeoJSON types: 718 FeatureCollection, Feature, Point, LineString, MultiPoint, Polygon, 719 MultiLineString, MultiPolygon, and GeometryCollection. 721 7.1. Semantics of GeoJSON Members and Types are not Changeable 723 Implementations MUST NOT change the the semantics of GeoJSON members 724 and types. 726 The GeoJSON "coordinates" and "geometries" members define Geometry 727 objects. FeatureCollection and Feature objects, respectively, MUST 728 NOT contain a "coordinates" or "geometries" member. 730 The GeoJSON "geometry" and "properties" members define a Feature 731 object. FeatureCollection and Geometry objects, respectively, MUST 732 NOT contain a "geometry" or "properties" member. 734 The GeoJSON "features" member defines a FeatureCollection object. 735 Feature and Geometry objects, respectively, MUST NOT contain a 736 "features" member. 738 8. Versioning 740 The GeoJSON format can be extended as defined here, but no explicit 741 versioning scheme is defined. A specification that alters the 742 semantics of GeoJSON members or otherwise modifies the format does 743 not create a new version of this format; instead, it defines an 744 entirely new format that MUST NOT be identified as GeoJSON. 746 9. Mapping 'geo' URIs 748 'geo' URIs [RFC5870] identify geographic locations and precise (not 749 uncertain) locations can be mapped to GeoJSON geometry objects. 751 For this section, as in [RFC5870], "%lat%", "%lon%", "%alt%", and 752 "%unc%" are placeholders for 'geo' URI latitude, longitude, altitude, 753 and uncertainty values, respectively. 755 A 'geo' URI with two coordinates and an uncertainty ('u') parameter 756 that is absent or zero, and a GeoJSON Point geometry may be mapped to 757 each other. A GeoJSON point is always converted to a 'geo' URI that 758 has no uncertainty parameter. 760 'geo' URI: 762 geo:%lat%,%lon% 764 GeoJSON: 766 {"type": "Point", "coordinates": [%lon%, %lat%]} 768 The mapping between 'geo' URIs and GeoJSON points that specify 769 elevation is shown below. 771 'geo' URI: 773 geo:%lat%,%lon%,%alt% 775 GeoJSON: 777 {"type": "Point", "coordinates": [%lon%, %lat%, %alt%]} 778 GeoJSON has no concept of uncertainty; imprecise or uncertain 'geo' 779 URIs thus can not be mapped to GeoJSON geometries. 781 10. Security Considerations 783 GeoJSON shares security issues common to all JSON content types. See 784 [RFC7159] Section 12 for additional information. GeoJSON does not 785 provide executable content. 787 As with other geographic data formats, e.g., [KMLv2.2], providing 788 details about the locations of sensitive persons, animals, habitats, 789 and facilities can expose them to unauthorized tracking or injury. 790 GeoJSON does not provide privacy or integrity services; if sensitive 791 data requires privacy or integrity protection the service must be 792 provided externally. 794 11. Interoperability Considerations 796 11.1. I-JSON 798 GeoJSON texts should follow the constraints of I-JSON [RFC7493] for 799 maximum interoperability. 801 11.2. Coordinate Precision 803 The size of a GeoJSON text in bytes is a major interoperability 804 consideration and precision of coordinate values has a large impact 805 on the size of texts. A GeoJSON text containing many detailed 806 polygons can be inflated almost by a factor of two by increasing 807 coordinate precision from 6 to 15 decimal places. For geographic 808 coordinates with units of degrees, 6 decimal places (a default common 809 in, e.g., sprintf) amounts to about 10 centimeters, a precision well 810 within that of current GPS systems. Implementations should consider 811 the cost of using a greater precision than necessary. 813 Furthermore the WGS 84 [WGS84] datum is a relatively coarse 814 approximation of the geoid; with the height varying by up to 5m (but 815 generally between 2 and 3 meters) higher or lower relative to a 816 surface parallel to Earth's mean sea level. 818 12. IANA Considerations 820 The media type for GeoJSON text is "application/geo+json" and is 821 registered in the "Media Types" registry described in [RFC6838]. The 822 entry for "application/vnd.geo+json" in the same registry should have 823 its status changed to be Obsolete with a pointer to the media type 824 "application/geo+json" and a reference added to this RFC. 826 Type name: application 828 Subtype name: geo+json 830 Required parameters: n/a 832 Optional parameters: n/a 834 Encoding considerations: binary 836 Security considerations: See section 9 above 838 Interoperability considerations: See section 10 above 840 Published specification: [[This document]] 842 Applications that use this media type: various 844 Additional information: 846 Magic number(s): n/a 848 File extension(s): .json, .geojson 850 Macintosh file type code: n/a 852 Object Identifiers: n/a 854 Windows clipboard name: GeoJSON 856 Macintosh uniform type identifier: public.geojson conforms to 857 public.json 859 Person to contact for further information: Sean Gillies 860 (sean.gillies@gmail.com) 862 Intended usage: COMMON 864 Restrictions on usage: none 866 13. Acknowledgements 868 The GeoJSON format is the product of discussion on the GeoJSON 869 mailing list, http://lists.geojson.org/listinfo.cgi/geojson- 870 geojson.org, before October 2015 and the IETF's GeoJSON WG after 871 October 2015. 873 Material in this document was adapted with changes from http:// 874 geojson.org/geojson-spec.html [GJ2008] which is licensed under http:/ 875 /creativecommons.org/licenses/by/3.0/us/. 877 14. References 879 14.1. Normative References 881 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 882 Requirement Levels", BCP 14, RFC 2119, March 1997. 884 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 885 Specifications and Registration Procedures", BCP 13, RFC 886 6838, DOI 10.17487/RFC6838, January 2013, 887 . 889 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 890 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 891 2014, . 893 [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, DOI 894 10.17487/RFC7493, March 2015, 895 . 897 [WGS84] National Imagery and Mapping Agency, "Department of 898 Defense World Geodetic System 1984, Third Edition", 1984. 900 14.2. Informative References 902 [GJ2008] Butler, H., Daly, M., Doyle, A., Gillies, S., Schaub, T., 903 and C. Schmidt, "The GeoJSON Format Specification", June 904 2008. 906 [KMLv2.2] Wilson, T., "OGC KML", OGC 07-147r2, April 2008. 908 [OGCURL] Cox, S., "OGC-NA Name type specification - definitions: 909 Part 1 - basic name", OGC 09-048r3, March 2010. 911 [RFC7459] Thomson, M. and J. Winterbottom, "Representation of 912 Uncertainty and Confidence in the Presence Information 913 Data Format Location Object (PIDF-LO)", RFC 7459, DOI 914 10.17487/RFC7459, February 2015, 915 . 917 [RFC7464] Williams, N., "JavaScript Object Notation (JSON) Text 918 Sequences", RFC 7464, DOI 10.17487/RFC7464, February 2015, 919 . 921 [SFSQL] OpenGIS Consortium, Inc., "OpenGIS Simple Features 922 Specification For SQL Revision 1.1", OGC 99-049, May 1999. 924 [WFSv1] Vretanos, P., "Web Feature Service Implementation 925 Specification", OGC 02-058, May 2002. 927 Appendix A. Geometry Examples 929 Each of the examples below represents a valid and complete GeoJSON 930 object. 932 A.1. Points 934 Point coordinates are in x, y order (easting, northing for projected 935 coordinates, longitude, latitude for geographic coordinates): 937 { 938 "type": "Point", 939 "coordinates": [100.0, 0.0] 940 } 942 A.2. LineStrings 944 Coordinates of LineString are an array of positions (see 945 Section 3.1.1): 947 { 948 "type": "LineString", 949 "coordinates": [ 950 [100.0, 0.0], 951 [101.0, 1.0] 952 ] 953 } 955 A.3. Polygons 957 Coordinates of a Polygon are an array of LinearRing (see 958 Section 3.1.6) coordinate arrays. The first element in the array 959 represents the exterior ring. Any subsequent elements represent 960 interior rings (or holes). 962 No holes: 964 { 965 "type": "Polygon", 966 "coordinates": [ 967 [ 968 [100.0, 0.0], 969 [100.0, 1.0], 970 [101.0, 1.0], 971 [101.0, 0.0], 972 [100.0, 0.0] 973 ] 974 ] 975 } 977 With holes: 979 { 980 "type": "Polygon", 981 "coordinates": [ 982 [ 983 [100.0, 0.0], 984 [100.0, 1.0], 985 [101.0, 1.0], 986 [101.0, 0.0], 987 [100.0, 0.0] 988 ], 989 [ 990 [100.8, 0.8], 991 [100.2, 0.8], 992 [100.2, 0.2], 993 [100.8, 0.2], 994 [100.8, 0.8] 995 ] 996 ] 997 } 999 A.4. MultiPoints 1001 Coordinates of a MultiPoint are an array of positions:: 1003 { 1004 "type": "MultiPoint", 1005 "coordinates": [ 1006 [100.0, 0.0], 1007 [101.0, 1.0] 1008 ] 1009 } 1011 A.5. MultiLineStrings 1013 Coordinates of a MultiLineString are an array of LineString 1014 coordinate arrays: 1016 { 1017 "type": "MultiLineString", 1018 "coordinates": [ 1019 [ 1020 [100.0, 0.0], 1021 [101.0, 1.0] 1022 ], 1023 [ 1024 [102.0, 2.0], 1025 [103.0, 3.0] 1026 ] 1027 ] 1028 } 1030 A.6. MultiPolygons 1032 Coordinates of a MultiPolygon are an array of Polygon coordinate 1033 arrays: 1035 { 1036 "type": "MultiPolygon", 1037 "coordinates": [ 1038 [ 1039 [ 1040 [102.0, 2.0], 1041 [102.0, 3.0], 1042 [103.0, 3.0], 1043 [103.0, 2.0], 1044 [102.0, 2.0] 1045 ] 1046 ], 1047 [ 1048 [ 1049 [100.0, 0.0], 1050 [100.0, 1.0], 1051 [101.0, 1.0], 1052 [101.0, 0.0], 1053 [100.0, 0.0] 1054 ], 1055 [ 1056 [100.2, 0.2], 1057 [100.8, 0.2], 1058 [100.8, 0.8], 1059 [100.2, 0.8], 1060 [100.2, 0.2] 1061 ] 1062 ] 1063 ] 1064 } 1066 A.7. GeometryCollections 1068 Each element in the geometries array of a GeometryCollection is one 1069 of the geometry objects described above: 1071 { 1072 "type": "GeometryCollection", 1073 "geometries": [{ 1074 "type": "Point", 1075 "coordinates": [100.0, 0.0] 1076 }, { 1077 "type": "LineString", 1078 "coordinates": [ 1079 [101.0, 0.0], 1080 [102.0, 1.0] 1081 ] 1082 }] 1083 } 1085 Appendix B. Changes from pre-IETF Specification 1087 This appendix briefly summarizes non-editorial changes from the 2008 1088 specification [GJ2008]. 1090 B.1. Normative Changes 1092 o Specification of coordinate reference systems has been removed, 1093 i.e., the "crs" member of [GJ2008] is no longer used. 1095 o In the absence of elevation values, applications sensitive to 1096 height or depth SHOULD interpret positions as being at local 1097 ground or sea level (see Section 4). 1099 o Implementations SHOULD NOT extend position arrays beyond 3 1100 elements (see Section 3.1.1). 1102 o A line between two positions is a straight Cartesian line (see 1103 Section 3.1.1). 1105 o The values of a "bbox" array are "[%west%, %south%, %east%, 1106 %north%]", not "[%minx%, %miny%, %maxx%, %maxy%]" (see Section 5). 1108 o A Feature object's "id" member is a string or number (see 1109 Section 3.2). 1111 o Extensions MAY be used, but MUST NOT change the the semantics of 1112 GeoJSON members and types (see Section 6). 1114 o GeoJSON objects MUST NOT contain the defining members of other 1115 types (see Section 7.1). 1117 o The media type for GeoJSON is application/geo+json. 1119 B.2. Informative Changes 1121 o The definition of a GeoJSON text has been added. 1123 o Rules for mapping 'geo' URIs have been added. 1125 o A recommendation of the I-JSON [RFC7493] constraints has been 1126 added. 1128 o Implementers are cautioned about the effect of excessive 1129 coordinate precision on interoperability. 1131 o Right-hand rule orientation of polygon rings (counter-clockwise 1132 external rings, clockwise internal rings) is recommended to 1133 improve interoperability. 1135 o Interoperability concerns of geometry collections are noted. 1136 These objects should be used sparingly (see Section 3.1.8). 1138 Appendix C. GeoJSON Text Sequences 1140 All GeoJSON objects defined in this specification - 1141 FeatureCollection, Feature, and Geometry - consist of exactly one 1142 JSON object. However, there may be circumstances in which 1143 applications need to represent sets or sequences of these objects 1144 (over and above the grouping of Feature objects in a 1145 FeatureCollection), e.g. in order to efficiently "stream" large 1146 numbers of Feature objects. The definition of such sets or sequences 1147 is outside the scope of this specification. 1149 If such a representation is needed, a new media type is required that 1150 has the ability to represent these sets or sequences. When defining 1151 such a media type, it may be useful to base it on "JSON Text 1152 Sequences" [RFC7464], leaving the foundations of how to represent 1153 multiple JSON objects to that specification, and only defining how it 1154 applies to GeoJSON objects. 1156 Authors' Addresses 1158 H. Butler 1159 Hobu Inc. 1161 Email: howard@hobu.co 1162 M. Daly 1163 Cadcorp 1165 Email: martin.daly@cadcorp.com 1167 A. Doyle 1169 Email: adoyle@intl-interfaces.com 1171 S. Gillies 1172 Mapbox 1174 Email: sean.gillies@gmail.com 1175 URI: http://sgillies.net 1177 S. Hagen 1178 Rheinaustr. 62 1179 Bonn 53225 1180 DE 1182 Email: stefan@hagen.link 1183 URI: http://stefan-hagen.website/ 1185 T. Schaub 1186 Planet Labs 1188 Email: tim.schaub@gmail.com