idnits 2.17.1 draft-butler-geojson-02.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 (March 15, 2014) is 3694 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Independent H. Butler 3 Internet-Draft Hobu Inc. 4 Intended status: Informational M. Daly 5 Expires: September 16, 2014 Cadcorp 6 A. Doyle 7 MIT 8 S. Gillies 9 Mapbox Inc. 10 T. Schaub 11 OpenGeo 12 S. Drees 14 March 15, 2014 16 The GeoJSON Format 17 draft-butler-geojson-02 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 September 16, 2014. 45 Copyright Notice 47 Copyright (c) 2014 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 . . . . . . . . . . . . . . . . . . 3 64 1.2. Conventions Used in This Document . . . . . . . . . . . . 4 65 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 66 1.4. Example . . . . . . . . . . . . . . . . . . . . . . . . . 4 67 2. GeoJSON Object . . . . . . . . . . . . . . . . . . . . . . . 6 68 2.1. Geometry Object . . . . . . . . . . . . . . . . . . . . . 6 69 2.1.1. Position . . . . . . . . . . . . . . . . . . . . . . 6 70 2.1.2. Point . . . . . . . . . . . . . . . . . . . . . . . . 7 71 2.1.3. MultiPoint . . . . . . . . . . . . . . . . . . . . . 7 72 2.1.4. LineString . . . . . . . . . . . . . . . . . . . . . 7 73 2.1.5. MultiLineString . . . . . . . . . . . . . . . . . . . 7 74 2.1.6. Polygon . . . . . . . . . . . . . . . . . . . . . . . 7 75 2.1.7. MultiPolygon . . . . . . . . . . . . . . . . . . . . 8 76 2.1.8. Geometry Collection . . . . . . . . . . . . . . . . . 8 77 2.2. Feature Object . . . . . . . . . . . . . . . . . . . . . 8 78 2.3. Feature Collection Object . . . . . . . . . . . . . . . . 8 79 3. Coordinate Reference System Object . . . . . . . . . . . . . 8 80 3.1. Named CRS . . . . . . . . . . . . . . . . . . . . . . . . 9 81 3.2. Linked CRS . . . . . . . . . . . . . . . . . . . . . . . 10 82 4. Bounding Box . . . . . . . . . . . . . . . . . . . . . . . . 10 83 5. Security Considerations . . . . . . . . . . . . . . . . . . . 11 84 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 85 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 86 7.1. Normative References . . . . . . . . . . . . . . . . . . 11 87 7.2. Informative References . . . . . . . . . . . . . . . . . 12 88 Appendix A. Geometry Examples . . . . . . . . . . . . . . . . . 12 89 A.1. Points . . . . . . . . . . . . . . . . . . . . . . . . . 12 90 A.2. LineStrings . . . . . . . . . . . . . . . . . . . . . . . 12 91 A.3. Polygons . . . . . . . . . . . . . . . . . . . . . . . . 13 92 A.4. MultiPoints . . . . . . . . . . . . . . . . . . . . . . . 14 93 A.5. MultiLineStrings . . . . . . . . . . . . . . . . . . . . 14 94 A.6. MultiPolygons . . . . . . . . . . . . . . . . . . . . . . 14 95 A.7. GeometryCollections . . . . . . . . . . . . . . . . . . . 15 96 Appendix B. Contributors . . . . . . . . . . . . . . . . . . . . 16 97 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16 99 1. Introduction 101 GeoJSON is a format for encoding data about geographic features using 102 JavaScript Object Notation (JSON) [RFC7159]. The format is concerned 103 with features in the broadest sense; any thing with qualities that 104 are bounded in geographical space may be a feature whether it is a 105 physical structure or not. The concepts in GeoJSON are not new; they 106 are derived from pre-existing open geographic information system 107 standards (for COM, SQL, and XML) and have been streamlined to better 108 suit web application development using JSON. 110 GeoJSON comprises the seven concrete geometry types defined in the 111 OpenGIS Simple Features Implementation Specification for SQL [SFSQL]: 112 0-dimensional Point and MultiPoint; 1-dimensional curve LineString 113 and MultiLineString; 2-dimensional surface Polygon and MultiPolygon; 114 and the heterogeneous GeometryCollection. GeoJSON representations of 115 instances of these geometry types are analogous to the well-known 116 binary (WKB) and text (WKT) representations described in that same 117 specification. 119 GeoJSON also comprises the types Feature and FeatureCollection. 120 Feature objects in GeoJSON contain a geometry object with one of the 121 above geometry types and additional properties. A FeatureCollection 122 object contains an array of feature objects. This structure is 123 analogous to that of the Web Feature Service (WFS) response to 124 GetFeatures requests specified in [WFSv1] or to a KML Folder of 125 Placemarks [KMLv2.2]. Some implementations of the WFS specification 126 also provide GeoJSON formatted responses to GetFeature requests, but 127 there is no particular service model or feature type ontology implied 128 in the GeoJSON format specification. 130 Since its initial publication in 2008 [GeoJSON], the GeoJSON format 131 specification has steadily grown in popularity. It is widely used in 132 JavaScript web mapping libraries, JSON-based document databases, and 133 web APIs. 135 1.1. Requirements Language 137 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 138 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 139 "OPTIONAL" in this document are to be interpreted as described in 140 [RFC2119]. 142 1.2. Conventions Used in This Document 144 The ordering of the members of any JSON object defined in this 145 document MUST be considered irrelevant, as specified by [RFC7159]. 147 Some examples use the combination of a JavaScript single line comment 148 (//) followed by an ellipsis (...) as placeholder notation for 149 content deemed irrelevant by the authors. These placeholders must of 150 course be deleted or otherwise replaced, before attempting to 151 validate the corresponding JSON code example. 153 Whitespace is used in the examples inside this document to help 154 illustrate the data structures, but is not required. Unquoted 155 whitespace is not significant in JSON. 157 1.3. Definitions 159 o JavaScript Object Notation (JSON), and the terms object, name, 160 value, array, number, true, false, and null are to be interpreted 161 as defined in [RFC7159]. 163 o Inside this document the term "geometry type" refers to the seven 164 case-sensitive strings: "Point", "MultiPoint", "LineString", 165 "MultiLineString", "Polygon", "MultiPolygon", and 166 "GeometryCollection". 168 o As another shorthand notation the term GeoJSON types refers to the 169 nine case-sensitve strings "Feature", "FeatureCollection" and the 170 geometry types listed above. 172 1.4. Example 174 A GeoJSON feature collection: 176 { 177 "type": "FeatureCollection", 178 "features": [{ 179 "type": "Feature", 180 "geometry": { 181 "type": "Point", 182 "coordinates": [102.0, 0.5] 183 }, 184 "properties": { 185 "prop0": "value0" 186 } 187 }, { 188 "type": "Feature", 189 "geometry": { 190 "type": "LineString", 191 "coordinates": [ 192 [102.0, 0.0], 193 [103.0, 1.0], 194 [104.0, 0.0], 195 [105.0, 1.0] 196 ] 197 }, 198 "properties": { 199 "prop0": "value0", 200 "prop1": 0.0 201 } 202 }, { 203 "type": "Feature", 204 "geometry": { 205 "type": "Polygon", 206 "coordinates": [ 207 [ 208 [100.0, 0.0], 209 [101.0, 0.0], 210 [101.0, 1.0], 211 [100.0, 1.0], 212 [100.0, 0.0] 213 ] 214 ] 215 }, 216 "properties": { 217 "prop0": "value0", 218 "prop1": { 219 "this": "that" 220 } 221 } 222 }] 223 } 225 2. GeoJSON Object 227 GeoJSON always consists of a single object. This object (referred to 228 as the GeoJSON object below) represents a geometry, feature, or 229 collection of features. 231 o The GeoJSON object MUST have a member with the name "type". The 232 value of the member MUST be one of the GeoJSON types. 234 o The GeoJSON object MAY have any number of other members. 236 o A GeoJSON object MAY have a "bbox" member, the value of which MUST 237 be a bounding box array (see 4. Bounding Boxes). 239 2.1. Geometry Object 241 A geometry object is a GeoJSON object where the "type" value is one 242 of the geometry types. A GeoJSON geometry object of any type other 243 than "GeometryCollection" MUST have a member with the name 244 "coordinates". The value of the coordinates member is always an 245 array. The structure of the elements in this array is determined by 246 the type of geometry. 248 2.1.1. Position 250 A position is the fundamental geometry construct. The "coordinates" 251 member of a geometry object is composed of either: 253 o one position (in the case of a Point geometry), 255 o an array of positions (LineString or MultiPoint geometries), 257 o an array of arrays of positions (Polygons, MultiLineStrings), 259 o or a multidimensional array of positions (MultiPolygon). 261 A position is represented by an array of numbers. There MUST be two 262 or more elements. The first two elements will be longitude and 263 latitude, or easting and northing, precisely in that order and using 264 decimal numbers. Altitude or elevation MAY be included as an 265 optional third element. 267 Additional position elements MAY be included but MUST follow the 268 three specified above and MAY be ignored by software. Interpretation 269 and meaning of additional elements is beyond the scope of this 270 specification. 272 Examples of positions and geometries are provided in "Appendix A. 273 Geometry Examples". 275 2.1.2. Point 277 For type "Point", the "coordinates" member MUST be a single position. 279 2.1.3. MultiPoint 281 For type "MultiPoint", the "coordinates" member MUST be an array of 282 positions. 284 2.1.4. LineString 286 For type "LineString", the "coordinates" member MUST be an array of 287 two or more positions. 289 2.1.5. MultiLineString 291 For type "MultiLineString", the "coordinates" member MUST be an array 292 of LineString coordinate arrays. 294 2.1.6. Polygon 296 To specify a constraint specific to polygons, it is useful to 297 introduce the concept of a linear ring: 299 o A linear ring is a closed LineString with 4 or more positions. 301 o The first and last positions are equivalent (they represent 302 equivalent points). 304 o A linear ring is the boundary of a surface or the boundary of a 305 hole in a surface. 307 Though a linear ring is not explicitly represented as a GeoJSON 308 geometry type, it leads to a canonical formulation of the Polygon 309 geometry type definition as follows: 311 o For type "Polygon", the "coordinates" member MUST be an array of 312 linear ring coordinate arrays. 314 o For Polygons with more than one of these rings, the first MUST be 315 the exterior ring and any others MUST be interior rings. The 316 exterior ring bounds the surface and the interiors rings (if 317 present) bound holes within the surface. 319 2.1.7. MultiPolygon 321 For type "MultiPolygon", the "coordinates" member MUST be an array of 322 Polygon coordinate arrays. 324 2.1.8. Geometry Collection 326 A GeoJSON object with type "GeometryCollection" is a geometry object 327 which represents a collection of geometry objects. A geometry 328 collection MUST have a member with the name "geometries". The value 329 corresponding to "geometries" is an array. Each element in this 330 array is a GeoJSON geometry object. 332 2.2. Feature Object 334 A GeoJSON object with the type "Feature" is a feature object. 336 o A feature object MUST have a member with the name "geometry". The 337 value of the geometry member SHALL be either a geometry object as 338 defined above or, in the the case that the feature is unlocated, a 339 JSON null value. 341 o A feature object MUST have a member with the name "properties". 342 The value of the properties member is an object (any JSON object 343 or a JSON null value). 345 o If a feature has a commonly used identifier, that identifier 346 SHOULD be included as a member of the feature object with the name 347 "id" and the value of this member is either a JSON string or 348 number. 350 2.3. Feature Collection Object 352 A GeoJSON object with the type "FeatureCollection" is a feature 353 collection object. An object of type "FeatureCollection" MUST have a 354 member with the name "features". The value corresponding to 355 "features" is an array. Each element in the array is a feature 356 object as defined above. 358 3. Coordinate Reference System Object 360 The coordinate reference system (CRS) of a GeoJSON object is 361 determined by its OPTIONAL "crs" member (referred to as the CRS 362 object below). If an object has no crs member, then its parent or 363 grandparent object's crs member SHALL be acquired. If no crs member 364 can be so acquired, the default CRS SHALL apply to the GeoJSON 365 object. 367 The default coordinate reference system for all GeoJSON objects SHALL 368 be a geographic coordinate reference system, using the [WGS84] datum, 369 and with longitude and latitude units of decimal degrees. This 370 coordinate reference system is equivalent to the OGC's 371 urn:ogc:def:crs:OGC::CRS84 [OGCURN]. An OPTIONAL third position 372 element SHALL be the height in meters above the WGS 84 reference 373 ellipsoid. For widest interoperability, GeoJSON data SHOULD use this 374 default coordinate reference system and omit CRS objects. 376 If an application demands a different coordinate reference system, 377 the following specifications shall be followed: 379 o CRS SHOULD be defined as highly in GeoJSON object hierarchy as 380 possible, ideally in the FeatureCollection, and SHOULD NOT be 381 repeated or overridden in child objects. 383 o The value of a member named "crs" is a JSON object (referred to as 384 the CRS object below) or JSON null. If the value of CRS is null, 385 no CRS can be assumed. 387 o A non-null CRS object has two mandatory members: "type" and 388 "properties". 390 o The value of the type member indicates the type of CRS object. 392 o The value of the properties member must be an object. 394 o The presence of a CRS object SHALL NOT change the ordering of 395 coordinates specified in section 2.1.1. 397 3.1. Named CRS 399 A CRS object may indicate a coordinate reference system by name. In 400 this case, the value of its "type" member must be the string "name". 401 The value of its "properties" member must be an object containing a 402 "name" member. The value of that "name" member must be a string 403 identifying a coordinate reference system. OGC CRS URNs such as 404 "urn:ogc:def:crs:OGC::CRS84" are RECOMMENDED over legacy identifiers 405 such as "EPSG:4326". 407 "crs": { 408 "type": "name", 409 "properties": { 410 "name": "urn:ogc:def:crs:OGC::CRS84" 411 } 412 } 414 3.2. Linked CRS 416 A CRS object may link to CRS parameters on the Web. In this case, the 417 value of its "type" member must be the string "link", and the value 418 of its "properties" member must be a Link object. 420 A link object has one required member: "href", and one optional 421 member: "type". The value of the required "href" member must be a 422 dereferenceable URI. The value of the optional "type" member must be 423 a string that hints at the format used to represent CRS parameters at 424 the provided URI. Suggested values are: "proj4", "ogcwkt", 425 "esriwkt", but others can be used:: 427 "crs": { 428 "type": "link", 429 "properties": { 430 "href": "http://example.com/crs/42", 431 "type": "proj4" 432 } 433 } 435 Relative links may be used to direct processors to CRS parameters in 436 an auxiliary file: 438 "crs": { 439 "type": "link", 440 "properties": { 441 "href": "data.crs", 442 "type": "ogcwkt" 443 } 444 } 446 4. Bounding Box 448 A GeoJSON object MAY have a member named "bbox" to include 449 information on the coordinate range for its geometries, features, or 450 feature collections. The value of the bbox member MUST be an array 451 of length 2*n where n is the number of dimensions represented in the 452 contained geometries, with the lowest values for all axes followed by 453 the highest values. The axes order of a bbox follows the axes order 454 of geometries. 456 Example of a bbox member on a feature: 458 { 459 "type": "Feature", 460 "bbox": [-180.0, -90.0, 180.0, 90.0], 461 "geometry": { 462 "type": "Polygon", 463 "coordinates": [ 464 [ 465 [-180.0, 10.0], 466 [20.0, 90.0], 467 [180.0, -5.0], 468 [-30.0, -90.0] 469 ] 470 ] 471 } 472 //... 473 } 475 Example of a bbox member on a feature collection: 477 { 478 "type": "FeatureCollection", 479 "bbox": [100.0, 0.0, 105.0, 1.0], 480 "features": [ 481 //... 482 ] 483 } 485 5. Security Considerations 487 This memo raises no security issues. 489 6. IANA Considerations 491 There are no IANA considerations beyond those in [RFC7159]. 493 7. References 495 7.1. Normative References 497 [GeoJSON] Butler, H., Daly, M., Doyle, A., Gillies, S., Schaub, T., 498 and C. Schmidt, "The GeoJSON Format Specification", June 499 2008. 501 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 502 Requirement Levels", BCP 14, RFC 2119, March 1997. 504 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 505 Interchange Format", RFC 7159, March 2014. 507 7.2. Informative References 509 [KMLv2.2] Wilson, T., "OGC KML", OGC 07-147r2, April 2008. 511 [OGCURN] Whiteside, A., "Definition identifier URNs in OGC 512 namespace", OGC 07-092r3, January 2009. 514 [SFSQL] OpenGIS Consortium, Inc., "OpenGIS Simple Features 515 Specification For SQL Revision 1.1", OGC 99-049, May 1999. 517 [WFSv1] Vretanos, P., "Web Feature Service Implementation 518 Specification", OGC 02-058, May 2002. 520 [WGS84] National Imagery and Mapping Agency, "Department of 521 Defense World Geodetic System 1984, Third Edition", 1984. 523 Appendix A. Geometry Examples 525 Each of the examples below represents a valid and complete GeoJSON 526 object. 528 A.1. Points 530 Point coordinates are in x, y order (easting, northing for projected 531 coordinates, longitude, latitude for geographic coordinates): 533 { 534 "type": "Point", 535 "coordinates": [100.0, 0.0] 536 } 538 A.2. LineStrings 540 Coordinates of LineString are an array of positions (see "2.1.1. 541 Position"): 543 { 544 "type": "LineString", 545 "coordinates": [ 546 [100.0, 0.0], 547 [101.0, 1.0] 548 ] 549 } 551 A.3. Polygons 553 Coordinates of a Polygon are an array of LinearRing (cf. "2.1.6 554 Polygon") coordinate arrays. The first element in the array 555 represents the exterior ring. Any subsequent elements represent 556 interior rings (or holes). 558 No holes: 560 { 561 "type": "Polygon", 562 "coordinates": [ 563 [ 564 [100.0, 0.0], 565 [101.0, 0.0], 566 [101.0, 1.0], 567 [100.0, 1.0], 568 [100.0, 0.0] 569 ] 570 ] 571 } 573 With holes: 575 { 576 "type": "Polygon", 577 "coordinates": [ 578 [ 579 [100.0, 0.0], 580 [101.0, 0.0], 581 [101.0, 1.0], 582 [100.0, 1.0], 583 [100.0, 0.0] 584 ], 585 [ 586 [100.2, 0.2], 587 [100.8, 0.2], 588 [100.8, 0.8], 589 [100.2, 0.8], 590 [100.2, 0.2] 591 ] 592 ] 593 } 595 A.4. MultiPoints 597 Coordinates of a MultiPoint are an array of positions:: 599 { 600 "type": "MultiPoint", 601 "coordinates": [ 602 [100.0, 0.0], 603 [101.0, 1.0] 604 ] 605 } 607 A.5. MultiLineStrings 609 Coordinates of a MultiLineString are an array of LineString 610 coordinate arrays: 612 { 613 "type": "MultiLineString", 614 "coordinates": [ 615 [ 616 [100.0, 0.0], 617 [101.0, 1.0] 618 ], 619 [ 620 [102.0, 2.0], 621 [103.0, 3.0] 622 ] 623 ] 624 } 626 A.6. MultiPolygons 628 Coordinates of a MultiPolygon are an array of Polygon coordinate 629 arrays: 631 { 632 "type": "MultiPolygon", 633 "coordinates": [ 634 [ 635 [ 636 [102.0, 2.0], 637 [103.0, 2.0], 638 [103.0, 3.0], 639 [102.0, 3.0], 640 [102.0, 2.0] 641 ] 642 ], 643 [ 644 [ 645 [100.0, 0.0], 646 [101.0, 0.0], 647 [101.0, 1.0], 648 [100.0, 1.0], 649 [100.0, 0.0] 650 ], 651 [ 652 [100.2, 0.2], 653 [100.8, 0.2], 654 [100.8, 0.8], 655 [100.2, 0.8], 656 [100.2, 0.2] 657 ] 658 ] 659 ] 660 } 662 A.7. GeometryCollections 664 Each element in the geometries array of a GeometryCollection is one 665 of the geometry objects described above: 667 { 668 "type": "GeometryCollection", 669 "geometries": [{ 670 "type": "Point", 671 "coordinates": [100.0, 0.0] 672 }, { 673 "type": "LineString", 674 "coordinates": [ 675 [101.0, 0.0], 676 [102.0, 1.0] 677 ] 678 }] 679 } 681 Appendix B. Contributors 683 The GeoJSON format is the product of discussion on the GeoJSON 684 mailing list: http://lists.geojson.org/listinfo.cgi/geojson- 685 geojson.org. 687 Comments are solicited and should be addressed to the GeoJSON mailing 688 list at geojson@lists.geojson.org or to the GeoJSON issue tracker at 689 https://github.com/geojson/draft-geojson/issues. 691 Authors' Addresses 693 H. Butler 694 Hobu Inc. 696 M. Daly 697 Cadcorp 699 A. Doyle 700 MIT 702 S. Gillies 703 Mapbox Inc. 705 Email: sean.gillies@gmail.com 706 URI: http://sgillies.net 708 T. Schaub 709 OpenGeo 710 S. Drees 711 Rheinaustr. 62 712 Bonn 53225 713 DE 715 Email: stefan@drees.name 716 URI: http://sdre.es/