idnits 2.17.1 draft-ietf-geojson-04.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 23, 2016) is 2863 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 744, but not defined == Missing Reference: '-170' is mentioned on line 700, but not defined -- Looks like a reference, but probably isn't: '10' on line 700 -- Looks like a reference, but probably isn't: '170' on line 701 -- Looks like a reference, but probably isn't: '11' on line 701 ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Possible downref: Non-RFC (?) normative reference: ref. 'WGS84' Summary: 1 error (**), 0 flaws (~~), 3 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: December 25, 2016 Cadcorp 6 A. Doyle 8 S. Gillies 9 Mapbox 10 S. Hagen 12 T. Schaub 13 Planet Labs 14 June 23, 2016 16 The GeoJSON Format 17 draft-ietf-geojson-04 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 GeoJSON uses a geographic coordinate reference system, World Geodetic 26 System 1984, and units of decimal degrees. 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 December 25, 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 Precision . . . . . . . . . . . . . . 11 81 3.2. Feature Object . . . . . . . . . . . . . . . . . . . . . 11 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 . . . . . . . . . . . . . . . . . . . . . 19 99 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 20 100 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 101 14.1. Normative References . . . . . . . . . . . . . . . . . . 20 102 14.2. Informative References . . . . . . . . . . . . . . . . . 21 103 Appendix A. Geometry Examples . . . . . . . . . . . . . . . . . 21 104 A.1. Points . . . . . . . . . . . . . . . . . . . . . . . . . 21 105 A.2. LineStrings . . . . . . . . . . . . . . . . . . . . . . . 21 106 A.3. Polygons . . . . . . . . . . . . . . . . . . . . . . . . 22 107 A.4. MultiPoints . . . . . . . . . . . . . . . . . . . . . . . 23 108 A.5. MultiLineStrings . . . . . . . . . . . . . . . . . . . . 23 109 A.6. MultiPolygons . . . . . . . . . . . . . . . . . . . . . . 24 110 A.7. GeometryCollections . . . . . . . . . . . . . . . . . . . 25 111 Appendix B. Changes from pre-IETF Specification . . . . . . . . 26 112 B.1. Normative Changes . . . . . . . . . . . . . . . . . . . . 26 113 B.2. Informative Changes . . . . . . . . . . . . . . . . . . . 27 114 Appendix C. GeoJSON Text Sequences . . . . . . . . . . . . . . . 27 115 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 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 Keyhole Markup 151 Language (KML) Folder of Placemarks [KMLv2.2]. Some implementations 152 of the WFS specification also provide GeoJSON formatted responses to 153 GetFeature requests, but there is no particular service model or 154 feature type ontology implied 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 supersedes 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 has a member with the name "type". The value of 275 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 other members (see Section 6). 282 3.1. Geometry Object 284 A Geometry object represents points, curves, and surfaces in 285 coordinate space. Every geometry object is a GeoJSON object no 286 matter where it occurs in a GeoJSON text. 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" has a member with the name "coordinates". 293 The value of the coordinates member is an array. The structure of 294 the elements in this array is determined by the type of geometry. 295 GeoJSON processors MAY interpret geometry objects with empty 296 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 is a single position. 358 3.1.3. MultiPoint 360 For type "MultiPoint", the "coordinates" member is an array of 361 positions. 363 3.1.4. LineString 365 For type "LineString", the "coordinates" member is an array of two or 366 more positions. 368 3.1.5. MultiLineString 370 For type "MultiLineString", the "coordinates" member is an array of 371 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 MUST follow the right-hand rule with respect to the 387 area it bounds (i.e., exterior rings are counter-clockwise, holes 388 are clockwise). 390 Note: the [GJ2008] specification did not discuss linear ring winding 391 order. For backwards compatibility, parsers SHOULD NOT reject 392 polygons that do not follow the right-hand rule. 394 Though a linear ring is not explicitly represented as a GeoJSON 395 geometry type, it leads to a canonical formulation of the Polygon 396 geometry type definition as follows: 398 o For type "Polygon", the "coordinates" member MUST be an array of 399 linear ring coordinate arrays. 401 o For Polygons with more than one of these rings, the first MUST be 402 the exterior ring and any others MUST be interior rings. The 403 exterior ring bounds the surface, and the interior rings (if 404 present) bound holes within the surface. 406 3.1.7. MultiPolygon 408 For type "MultiPolygon", the "coordinates" member is an array of 409 Polygon coordinate arrays. 411 3.1.8. Geometry Collection 413 A GeoJSON object with type "GeometryCollection" is a geometry object. 414 A geometry collection has a member with the name "geometries". The 415 value of "geometries" is an array. Each element of this array is a 416 GeoJSON geometry object. It is possible for this array to be empty. 418 Unlike the other geometry types described above, a geometry 419 collection can be a heterogeneous composition of smaller geometry 420 objects. For example, a geometry object in the shape of a lowercase 421 roman "i" can be composed of one point and one line string. 423 Geometry collections have a different syntax from single type 424 geometry objects (Point, LineString, and Polygon) and homogeneously 425 typed multipart geometry objects (MultiPoint, MultiLineString, and 426 MultiPolygon) but have no different semantics. Although a geometry 427 collection object has no "coordinates" member, it does have 428 coordinates: the coordinates of all its parts belong to the 429 collection. The "geometries" member of a geometry collection 430 describes the parts of this composition. Implementations SHOULD NOT 431 apply any additional semantics to the "geometries" array. 433 To maximize interoperability implementations SHOULD avoid nested 434 geometry collections. Furthermore, geometry collections composed of 435 a single part or a number of parts of a single type SHOULD be avoided 436 when that single part or a single object of multi-part type 437 (MultiPoint, MultiLineString, or MultiPolygon) could be used instead. 439 3.1.9. Antimeridian Cutting 441 In representing features that cross the antimeridian, 442 interoperability is improved by modifying their geometry. Any 443 geometry that crosses the antimeridian SHOULD be represented by 444 cutting it in two such that neither part's representation crosses the 445 antimeridian. 447 For example, a line extending from 45 degrees N, 170 degrees E across 448 the antimeridian to 45 degrees N, 170 degrees W should be cut in two 449 and represented as a MultiLineString. 451 { 452 "type": "MultiLineString", 453 "coordinates": [ 454 [ 455 [170.0, 45.0], [180.0, 45.0] 456 ], [ 457 [-180.0, 45.0], [-170.0, 45.0] 458 ] 459 ] 460 } 462 A rectangle extending from 40 degrees N, 170 degrees E across the 463 antimeridian to 50 degrees N, 170 degrees W should be cut in two and 464 represented as a MultiPolygon. 466 { 467 "type": "MultiPolygon", 468 "coordinates": [ 469 [ 470 [ 471 [180.0, 40.0], [180.0, 50.0], [170.0, 50.0], 472 [170.0, 40.0], [180.0, 40.0] 473 ] 474 ], 475 [ 476 [ 477 [-170.0, 40.0], [-170.0, 50.0], [-180.0, 50.0], 478 [-180.0, 40.0], [-170.0, 40.0] 479 ] 480 ] 481 ] 482 } 484 3.1.10. Uncertainty and Precision 486 As in [RFC5870] the number of digits of the values in coordinate 487 positions MUST NOT be interpreted as an indication to the level of 488 uncertainty. 490 3.2. Feature Object 492 A Feature object represents a spatially-bounded thing. Every feature 493 object is a GeoJSON object no matter where it occurs in a GeoJSON 494 text. 496 o A feature object has a "type" member with the value "Feature". 498 o A feature object has a member with the name "geometry". The value 499 of the geometry member SHALL be either a geometry object as 500 defined above or, in the case that the feature is unlocated, a 501 JSON null value. 503 o A feature object has a member with the name "properties". The 504 value of the properties member is an object (any JSON object or a 505 JSON null value). 507 o If a feature has a commonly used identifier, that identifier 508 SHOULD be included as a member of the feature object with the name 509 "id", and the value of this member is either a JSON string or 510 number. 512 3.3. Feature Collection Object 514 A GeoJSON object with the type "FeatureCollection" is a feature 515 collection object. A feature collection object has a member with the 516 name "features". The value of "features" is a JSON array. Each 517 element of the array is a feature object as defined above. It is 518 possible for this array to be empty. 520 4. Coordinate Reference System 522 The coordinate reference system for all GeoJSON coordinates is a 523 geographic coordinate reference system, using the WGS 84 [WGS84] 524 datum, and with longitude and latitude units of decimal degrees. 525 This is equivalent to the coordinate reference system identified by 526 the OGC URN urn:ogc:def:crs:OGC::CRS84. An OPTIONAL third position 527 element SHALL be the height in meters above or below the WGS 84 528 reference ellipsoid. In the absence of elevation values, 529 applications sensitive to height or depth SHOULD interpret positions 530 as being at local ground or sea level. 532 Note: the use of alternative coordinate reference systems was 533 specified in [GJ2008], but has been removed from this version of the 534 specification because the use of different coordinate reference 535 systems -- especially in the manner specified in [GJ2008] -- has 536 proven to have interoperability issues. In general, GeoJSON 537 processing software is not expected to have access to coordinate 538 reference systems databases or to have network access to coordinate 539 reference system transformation parameters. However, where all 540 involved parties have a prior arrangement, alternative coordinate 541 reference systems can be used without risk of data being 542 misinterpreted. 544 5. Bounding Box 546 A GeoJSON object MAY have a member named "bbox" to include 547 information on the coordinate range for its geometries, features, or 548 feature collections. The value of the bbox member MUST be an array 549 of length 2*n where n is the number of dimensions represented in the 550 contained geometries, with all axes of the most south-westerly point 551 followed by all axes of the more north-easterly point. The axes 552 order of a bbox follows the axes order of geometries. 554 The "bbox" values define shapes with edges that follow lines of 555 constant longitude, latitude, and elevation. 557 Example of a 2D bbox member on a feature: 559 { 560 "type": "Feature", 561 "bbox": [-10.0, -10.0, 10.0, 10.0], 562 "geometry": { 563 "type": "Polygon", 564 "coordinates": [ 565 [ 566 [-10.0, -10.0], 567 [10.0, -10.0], 568 [10.0, 10.0], 569 [-10.0, -10.0] 570 ] 571 ] 572 } 573 //... 574 } 576 Example of a 2D bbox member on a feature collection: 578 { 579 "type": "FeatureCollection", 580 "bbox": [100.0, 0.0, 105.0, 1.0], 581 "features": [ 582 //... 583 ] 584 } 586 Example of a 3D bbox member with a depth of 100 meters: 588 { 589 "type": "FeatureCollection", 590 "bbox": [100.0, 0.0, -100.0, 105.0, 1.0, 0.0], 591 "features": [ 592 //... 593 ] 594 } 596 5.1. The Connecting Lines 598 The 4 lines of the bounding box are defined fully within the 599 coordinate reference system; i.e. for a box bounded by the values 600 "west", "south", "east", and "north" every point on the northernmost 601 line can be expressed as 603 (lon, lat) = (west + (east - west) * t, north) 605 with 0 <= t <= 1. 607 5.2. The Antimeridian 609 Consider a set of point features within the Fiji archipelago, 610 straddling the antimeridian between 16 degrees S and 20 degrees S. 611 The southwest corner of the box containing these features is at 20 612 degrees S and 177 degrees E, the northwest corner is at 16 degrees S 613 and 178 degrees W. The antimeridian-spanning GeoJSON bounding box 614 for this feature collection is 616 "bbox": [177.0, -20.0, -178.0, -16.0] 618 and covers 5 degrees of longitude. 620 The complementary bounding box for the same latitude band, not 621 crossing the antimeridian, is 623 "bbox": [-178.0, -20.0, 177.0, -16.0] 625 and covers 355 degrees of longitude. 627 The latitude of the northeast corner is always greater than the 628 latitude of the southwest corner, but bounding boxes that cross the 629 antimeridian have a northeast corner longitude that is less than the 630 longitude of the southwest corner. 632 5.3. The Poles 634 A bounding box that contains the North Pole extends from a southwest 635 corner of "minlat" degrees N, 180 degrees W to a northeast corner of 636 90 degrees N, 180 degrees E. Viewed on a globe, this bounding box 637 approximates a spherical cap bounded by the "minlat" circle of 638 latitude. 640 "bbox": [-180.0, minlat, 180.0, 90.0] 642 A bounding box that contains the South Pole extends from a southwest 643 corner of 90 degrees S, 180 degrees W to a northeast corner of 644 "maxlat" degrees S, 180 degrees E. 646 "bbox": [-180.0, -90.0, 180.0, maxlat] 648 A bounding box that just touches the North Pole and forms a slice of 649 an approximate spherical cap when viewed on a globe extends from a 650 southwest corner of "minlat" degrees N and "westlon" degrees E to a 651 northeast corner of 90 degrees N and "eastlon" degrees E. 653 "bbox": [westlon, minlat, eastlon, 90.0] 655 Similarly, a bounding box that just touches the South Pole and forms 656 a slice of an approximate spherical cap when viewed on a globe has 657 the following representation in GeoJSON. 659 "bbox": [westlon, -90.0, eastlon, maxlat] 661 Implementers MUST NOT use latitude values greater than 90 or less 662 than -90 to imply an extent that is not a spherical cap. 664 6. Extending GeoJSON 666 6.1. Foreign Members 668 Members not described in this specification ("foreign members") MAY 669 be used in a GeoJSON document. Note that support for foreign members 670 can vary across implementations and no normative processing model for 671 foreign members is defined. Accordingly, implementations that rely 672 too heavily on the use of foreign members might experience reduced 673 interoperability with other implementations. 675 For example, in the (abridged) feature object shown below 676 { 677 "type": "Feature", 678 "id": "f1", 679 "geometry": {...}, 680 "properties": {...}, 681 "title": "Example Feature" 682 } 684 the name/value pair of "title": "Example Feature" is a foreign 685 member. When the value of a foreign member is an object, all the 686 descendant members of that object are themselves foreign members. 688 GeoJSON semantics do not apply to foreign members and their 689 descendants, regardless of their names and values. For example, in 690 the (abridged) feature object below 692 { 693 "type": "Feature", 694 "id": "f2", 695 "geometry": {...}, 696 "properties": {...}, 697 "centerline": { 698 "type": "LineString", 699 "coordinates": [ 700 [-170, 10], 701 [170, 11] 702 ] 703 } 704 } 706 the "centerline" member is not a GeoJSON geometry object. 708 7. GeoJSON Types are not Extensible 710 Implementations MUST NOT extend the fixed set of GeoJSON types: 711 FeatureCollection, Feature, Point, LineString, MultiPoint, Polygon, 712 MultiLineString, MultiPolygon, and GeometryCollection. 714 7.1. Semantics of GeoJSON Members and Types are not Changeable 716 Implementations MUST NOT change the semantics of GeoJSON members and 717 types. 719 The GeoJSON "coordinates" and "geometries" members define Geometry 720 objects. FeatureCollection and Feature objects, respectively, MUST 721 NOT contain a "coordinates" or "geometries" member. 723 The GeoJSON "geometry" and "properties" members define a Feature 724 object. FeatureCollection and Geometry objects, respectively, MUST 725 NOT contain a "geometry" or "properties" member. 727 The GeoJSON "features" member defines a FeatureCollection object. 728 Feature and Geometry objects, respectively, MUST NOT contain a 729 "features" member. 731 8. Versioning 733 The GeoJSON format can be extended as defined here, but no explicit 734 versioning scheme is defined. A specification that alters the 735 semantics of GeoJSON members or otherwise modifies the format does 736 not create a new version of this format; instead, it defines an 737 entirely new format that MUST NOT be identified as GeoJSON. 739 9. Mapping 'geo' URIs 741 'geo' URIs [RFC5870] identify geographic locations and precise (not 742 uncertain) locations can be mapped to GeoJSON geometry objects. 744 For this section, as in [RFC5870], "lat", "lon", "alt", and "unc" are 745 placeholders for 'geo' URI latitude, longitude, altitude, and 746 uncertainty values, respectively. 748 A 'geo' URI with two coordinates and an uncertainty ('u') parameter 749 that is absent or zero, and a GeoJSON Point geometry may be mapped to 750 each other. A GeoJSON point is always converted to a 'geo' URI that 751 has no uncertainty parameter. 753 'geo' URI: 755 geo:lat,lon 757 GeoJSON: 759 {"type": "Point", "coordinates": [lon, lat]} 761 The mapping between 'geo' URIs and GeoJSON points that specify 762 elevation is shown below. 764 'geo' URI: 766 geo:lat,lon,alt 768 GeoJSON: 770 {"type": "Point", "coordinates": [lon, lat, alt]} 771 GeoJSON has no concept of uncertainty; imprecise or uncertain 'geo' 772 URIs thus cannot be mapped to GeoJSON geometries. 774 10. Security Considerations 776 GeoJSON shares security issues common to all JSON content types. See 777 [RFC7159] Section 12 for additional information. GeoJSON does not 778 provide executable content. 780 GeoJSON does not provide privacy or integrity services. If sensitive 781 data requires privacy or integrity protection, those must be provided 782 by the transport -- for example TLS or HTTPS. There will be cases in 783 which stored data need protection, which is out of scope for this 784 document. 786 As with other geographic data formats, e.g., [KMLv2.2], providing 787 details about the locations of sensitive persons, animals, habitats, 788 and facilities can expose them to unauthorized tracking or injury. 789 Data providers should recognize the risk of inadvertantly identifying 790 individuals if locations in anonymized datasets are not adequately 791 skewed or not sufficiently fuzzed [Sweeney] and recognize that the 792 effectiveness of location obscuration is limited by a number of 793 factors and is unlikely to be an effective defense against a 794 determined attack [RFC6772]. 796 11. Interoperability Considerations 798 11.1. I-JSON 800 GeoJSON texts should follow the constraints of I-JSON [RFC7493] for 801 maximum interoperability. 803 11.2. Coordinate Precision 805 The size of a GeoJSON text in bytes is a major interoperability 806 consideration and precision of coordinate values has a large impact 807 on the size of texts. A GeoJSON text containing many detailed 808 polygons can be inflated almost by a factor of two by increasing 809 coordinate precision from 6 to 15 decimal places. For geographic 810 coordinates with units of degrees, 6 decimal places (a default common 811 in, e.g., sprintf) amounts to about 10 centimeters, a precision well 812 within that of current GPS systems. Implementations should consider 813 the cost of using a greater precision than necessary. 815 Furthermore the WGS 84 [WGS84] datum is a relatively coarse 816 approximation of the geoid; with the height varying by up to 5m (but 817 generally between 2 and 3 meters) higher or lower relative to a 818 surface parallel to Earth's mean sea level. 820 12. IANA Considerations 822 The media type for GeoJSON text is "application/geo+json" and is 823 registered in the "Media Types" registry described in [RFC6838]. The 824 entry for "application/vnd.geo+json" in the same registry should have 825 its status changed to be Obsolete with a pointer to the media type 826 "application/geo+json" and a reference added to this RFC. 828 Type name: application 830 Subtype name: geo+json 832 Required parameters: n/a 834 Optional parameters: n/a 836 Encoding considerations: binary 838 Security considerations: See Section 10 above 840 Interoperability considerations: See Section 11 above 842 Published specification: [[This document]] 844 Applications that use this media type: No known applications 845 currently use this media type. This media type is intended for 846 GeoJSON applications currently using the "application/ 847 vnd.geo+json" or "application/json" media types, of which there 848 are several categories: web mapping, geospatial databases, 849 geographic data processing APIs, data analysis and storage 850 services, and data dissemination. 852 Additional information: 854 Magic number(s): n/a 856 File extension(s): .json, .geojson 858 Macintosh file type code: n/a 860 Object Identifiers: n/a 862 Windows clipboard name: GeoJSON 864 Macintosh uniform type identifier: public.geojson conforms to 865 public.json 867 Person to contact for further information: Sean Gillies 868 (sean.gillies@gmail.com) 870 Intended usage: COMMON 872 Restrictions on usage: none 874 Restrictions on usage: none 876 Author: see "Authors' Addresses" section of [[This document]]. 878 Change controller: Internet Engineering Task Force 880 13. Acknowledgements 882 The GeoJSON format is the product of discussion on the GeoJSON 883 mailing list, http://lists.geojson.org/listinfo.cgi/geojson- 884 geojson.org, before October 2015 and the IETF's GeoJSON WG after 885 October 2015. 887 Material in this document was adapted with changes from 888 http://geojson.org/geojson-spec.html [GJ2008] which is licensed under 889 http://creativecommons.org/licenses/by/3.0/us/. 891 14. References 893 14.1. Normative References 895 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 896 Requirement Levels", BCP 14, RFC 2119, March 1997. 898 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 899 Specifications and Registration Procedures", BCP 13, 900 RFC 6838, DOI 10.17487/RFC6838, January 2013, 901 . 903 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 904 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 905 2014, . 907 [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, 908 DOI 10.17487/RFC7493, March 2015, 909 . 911 [WGS84] National Imagery and Mapping Agency, "Department of 912 Defense World Geodetic System 1984, Third Edition", 1984. 914 14.2. Informative References 916 [GJ2008] Butler, H., Daly, M., Doyle, A., Gillies, S., Schaub, T., 917 and C. Schmidt, "The GeoJSON Format Specification", June 918 2008. 920 [KMLv2.2] Wilson, T., "OGC KML", OGC 07-147r2, April 2008. 922 [RFC6772] Schulzrinne, H., Ed., Tschofenig, H., Ed., Cuellar, J., 923 Polk, J., Morris, J., and M. Thomson, "Geolocation Policy: 924 A Document Format for Expressing Privacy Preferences for 925 Location Information", RFC 6772, DOI 10.17487/RFC6772, 926 January 2013, . 928 [RFC7464] Williams, N., "JavaScript Object Notation (JSON) Text 929 Sequences", RFC 7464, DOI 10.17487/RFC7464, February 2015, 930 . 932 [SFSQL] OpenGIS Consortium, Inc., "OpenGIS Simple Features 933 Specification For SQL Revision 1.1", OGC 99-049, May 1999. 935 [Sweeney] Sweeney, L., "k-anonymity: a model for protecting 936 privacy", International Journal on Uncertainty, Fuzziness 937 and Knowledge-based Systems 10 (5), 2002; 557-570, 2002. 939 [WFSv1] Vretanos, P., "Web Feature Service Implementation 940 Specification", OGC 02-058, May 2002. 942 Appendix A. Geometry Examples 944 Each of the examples below represents a valid and complete GeoJSON 945 object. 947 A.1. Points 949 Point coordinates are in x, y order (easting, northing for projected 950 coordinates, longitude, latitude for geographic coordinates): 952 { 953 "type": "Point", 954 "coordinates": [100.0, 0.0] 955 } 957 A.2. LineStrings 959 Coordinates of LineString are an array of positions (see 960 Section 3.1.1): 962 { 963 "type": "LineString", 964 "coordinates": [ 965 [100.0, 0.0], 966 [101.0, 1.0] 967 ] 968 } 970 A.3. Polygons 972 Coordinates of a Polygon are an array of LinearRing (see 973 Section 3.1.6) coordinate arrays. The first element in the array 974 represents the exterior ring. Any subsequent elements represent 975 interior rings (or holes). 977 No 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 } 992 With holes: 994 { 995 "type": "Polygon", 996 "coordinates": [ 997 [ 998 [100.0, 0.0], 999 [100.0, 1.0], 1000 [101.0, 1.0], 1001 [101.0, 0.0], 1002 [100.0, 0.0] 1003 ], 1004 [ 1005 [100.8, 0.8], 1006 [100.2, 0.8], 1007 [100.2, 0.2], 1008 [100.8, 0.2], 1009 [100.8, 0.8] 1010 ] 1011 ] 1012 } 1014 A.4. MultiPoints 1016 Coordinates of a MultiPoint are an array of positions:: 1018 { 1019 "type": "MultiPoint", 1020 "coordinates": [ 1021 [100.0, 0.0], 1022 [101.0, 1.0] 1023 ] 1024 } 1026 A.5. MultiLineStrings 1028 Coordinates of a MultiLineString are an array of LineString 1029 coordinate arrays: 1031 { 1032 "type": "MultiLineString", 1033 "coordinates": [ 1034 [ 1035 [100.0, 0.0], 1036 [101.0, 1.0] 1037 ], 1038 [ 1039 [102.0, 2.0], 1040 [103.0, 3.0] 1041 ] 1042 ] 1043 } 1045 A.6. MultiPolygons 1047 Coordinates of a MultiPolygon are an array of Polygon coordinate 1048 arrays: 1050 { 1051 "type": "MultiPolygon", 1052 "coordinates": [ 1053 [ 1054 [ 1055 [102.0, 2.0], 1056 [102.0, 3.0], 1057 [103.0, 3.0], 1058 [103.0, 2.0], 1059 [102.0, 2.0] 1060 ] 1061 ], 1062 [ 1063 [ 1064 [100.0, 0.0], 1065 [100.0, 1.0], 1066 [101.0, 1.0], 1067 [101.0, 0.0], 1068 [100.0, 0.0] 1069 ], 1070 [ 1071 [100.2, 0.2], 1072 [100.8, 0.2], 1073 [100.8, 0.8], 1074 [100.2, 0.8], 1075 [100.2, 0.2] 1076 ] 1077 ] 1078 ] 1079 } 1081 A.7. GeometryCollections 1083 Each element in the geometries array of a GeometryCollection is one 1084 of the geometry objects described above: 1086 { 1087 "type": "GeometryCollection", 1088 "geometries": [{ 1089 "type": "Point", 1090 "coordinates": [100.0, 0.0] 1091 }, { 1092 "type": "LineString", 1093 "coordinates": [ 1094 [101.0, 0.0], 1095 [102.0, 1.0] 1096 ] 1097 }] 1098 } 1100 Appendix B. Changes from pre-IETF Specification 1102 This appendix briefly summarizes non-editorial changes from the 2008 1103 specification [GJ2008]. 1105 B.1. Normative Changes 1107 o Specification of coordinate reference systems has been removed, 1108 i.e., the "crs" member of [GJ2008] is no longer used. 1110 o In the absence of elevation values, applications sensitive to 1111 height or depth SHOULD interpret positions as being at local 1112 ground or sea level (see Section 4). 1114 o Implementations SHOULD NOT extend position arrays beyond 3 1115 elements (see Section 3.1.1). 1117 o A line between two positions is a straight Cartesian line (see 1118 Section 3.1.1). 1120 o Polygon rings MUST follow the right-hand rule for orientation 1121 (counter-clockwise external rings, clockwise internal rings). 1123 o The values of a "bbox" array are "[west, south, east, north]", not 1124 "[minx, miny, maxx, maxy]" (see Section 5). 1126 o A Feature object's "id" member is a string or number (see 1127 Section 3.2). 1129 o Extensions MAY be used, but MUST NOT change the semantics of 1130 GeoJSON members and types (see Section 6). 1132 o GeoJSON objects MUST NOT contain the defining members of other 1133 types (see Section 7.1). 1135 o The media type for GeoJSON is application/geo+json. 1137 B.2. Informative Changes 1139 o The definition of a GeoJSON text has been added. 1141 o Rules for mapping 'geo' URIs have been added. 1143 o A recommendation of the I-JSON [RFC7493] constraints has been 1144 added. 1146 o Implementers are cautioned about the effect of excessive 1147 coordinate precision on interoperability. 1149 o Interoperability concerns of geometry collections are noted. 1150 These objects should be used sparingly (see Section 3.1.8). 1152 Appendix C. GeoJSON Text Sequences 1154 All GeoJSON objects defined in this specification - 1155 FeatureCollection, Feature, and Geometry - consist of exactly one 1156 JSON object. However, there may be circumstances in which 1157 applications need to represent sets or sequences of these objects 1158 (over and above the grouping of Feature objects in a 1159 FeatureCollection), e.g. in order to efficiently "stream" large 1160 numbers of Feature objects. The definition of such sets or sequences 1161 is outside the scope of this specification. 1163 If such a representation is needed, a new media type is required that 1164 has the ability to represent these sets or sequences. When defining 1165 such a media type, it may be useful to base it on "JSON Text 1166 Sequences" [RFC7464], leaving the foundations of how to represent 1167 multiple JSON objects to that specification, and only defining how it 1168 applies to GeoJSON objects. 1170 Authors' Addresses 1172 H. Butler 1173 Hobu Inc. 1175 Email: howard@hobu.co 1177 M. Daly 1178 Cadcorp 1180 Email: martin.daly@cadcorp.com 1181 A. Doyle 1183 Email: adoyle@intl-interfaces.com 1185 S. Gillies 1186 Mapbox 1188 Email: sean.gillies@gmail.com 1189 URI: http://sgillies.net 1191 S. Hagen 1192 Rheinaustr. 62 1193 Bonn 53225 1194 DE 1196 Email: stefan@hagen.link 1197 URI: http://stefan-hagen.website/ 1199 T. Schaub 1200 Planet Labs 1202 Email: tim.schaub@gmail.com