| 1 |
<pre>Internet Engineering Task Force (IETF) S. Gillies |
| 2 |
Request for Comments: 8142 Mapbox |
| 3 |
Category: Standards Track April 2017 |
| 4 |
ISSN: 2070-1721 |
| 5 |
|
| 6 |
|
| 7 |
<span class="h1">GeoJSON Text Sequences</span> |
| 8 |
|
| 9 |
Abstract |
| 10 |
|
| 11 |
This document describes the GeoJSON text sequence format and |
| 12 |
"application/geo+json-seq" media type. This format is based on |
| 13 |
JavaScript Object Notation (JSON) text sequences and GeoJSON, and it |
| 14 |
makes arbitrarily large geographic datasets incrementally parseable |
| 15 |
without restricting the form of GeoJSON texts within a sequence. |
| 16 |
|
| 17 |
Status of This Memo |
| 18 |
|
| 19 |
This is an Internet Standards Track document. |
| 20 |
|
| 21 |
This document is a product of the Internet Engineering Task Force |
| 22 |
(IETF). It represents the consensus of the IETF community. It has |
| 23 |
received public review and has been approved for publication by the |
| 24 |
Internet Engineering Steering Group (IESG). Further information on |
| 25 |
Internet Standards is available in <a href="./rfc7841#section-2">Section 2 of RFC 7841</a>. |
| 26 |
|
| 27 |
Information about the current status of this document, any errata, |
| 28 |
and how to provide feedback on it may be obtained at |
| 29 |
<a href="http://www.rfc-editor.org/info/rfc8142">http://www.rfc-editor.org/info/rfc8142</a>. |
| 30 |
|
| 31 |
Copyright Notice |
| 32 |
|
| 33 |
Copyright (c) 2017 IETF Trust and the persons identified as the |
| 34 |
document authors. All rights reserved. |
| 35 |
|
| 36 |
This document is subject to <a href="https://www.rfc-editor.org/bcp/bcp78">BCP 78</a> and the IETF Trust's Legal |
| 37 |
Provisions Relating to IETF Documents |
| 38 |
(<a href="http://trustee.ietf.org/license-info">http://trustee.ietf.org/license-info</a>) in effect on the date of |
| 39 |
publication of this document. Please review these documents |
| 40 |
carefully, as they describe your rights and restrictions with respect |
| 41 |
to this document. Code Components extracted from this document must |
| 42 |
include Simplified BSD License text as described in Section 4.e of |
| 43 |
the Trust Legal Provisions and are provided without warranty as |
| 44 |
described in the Simplified BSD License. |
| 45 |
|
| 46 |
|
| 47 |
|
| 48 |
|
| 49 |
|
| 50 |
|
| 51 |
|
| 52 |
<span class="grey">Gillies Standards Track [Page 1]</span></pre> |
| 53 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-2" ></span> |
| 54 |
<span class="grey"><a href="./rfc8142">RFC 8142</a> GeoJSON Text Sequences April 2017</span> |
| 55 |
|
| 56 |
|
| 57 |
Table of Contents |
| 58 |
|
| 59 |
<a href="#section-1">1</a>. Introduction ....................................................<a href="#page-2">2</a> |
| 60 |
<a href="#section-1.1">1.1</a>. Requirements Language ......................................<a href="#page-2">2</a> |
| 61 |
<a href="#section-2">2</a>. GeoJSON Text Sequence Format ....................................<a href="#page-2">2</a> |
| 62 |
<a href="#section-3">3</a>. Security Considerations .........................................<a href="#page-3">3</a> |
| 63 |
<a href="#section-4">4</a>. Interoperability Considerations .................................<a href="#page-3">3</a> |
| 64 |
<a href="#section-5">5</a>. IANA Considerations .............................................<a href="#page-3">3</a> |
| 65 |
<a href="#section-6">6</a>. References ......................................................<a href="#page-4">4</a> |
| 66 |
<a href="#section-6.1">6.1</a>. Normative References .......................................<a href="#page-4">4</a> |
| 67 |
<a href="#section-6.2">6.2</a>. Informative References .....................................<a href="#page-5">5</a> |
| 68 |
Author's Address ...................................................<a href="#page-5">5</a> |
| 69 |
|
| 70 |
<span class="h2"><a class="selflink" id="section-1" href="#section-1">1</a>. Introduction</span> |
| 71 |
|
| 72 |
Arbitrarily large sequences of values pose a problem for JavaScript |
| 73 |
Object Notation (JSON) [<a href="./rfc7159" title=""The JavaScript Object Notation (JSON) Data Interchange Format"">RFC7159</a>] that is well explained in the |
| 74 |
motivation for JSON text sequences [<a href="./rfc7464" title=""JavaScript Object Notation (JSON) Text Sequences"">RFC7464</a>]. The GeoJSON format |
| 75 |
[<a href="./rfc7946" title=""The GeoJSON Format"">RFC7946</a>] faces the same kind of problem. Geographic datasets often |
| 76 |
run to the tens of thousands or millions of features. The problem is |
| 77 |
often amplified by the presence of large arrays of coordinates for |
| 78 |
each of the features. |
| 79 |
|
| 80 |
This document describes a specialization of JSON text sequences. A |
| 81 |
GeoJSON text sequence is a document of arbitrarily large size |
| 82 |
containing one or more GeoJSON objects (e.g., multiple GeoJSON texts |
| 83 |
that can be produced and parsed incrementally) and not just a single |
| 84 |
GeoJSON FeatureCollection, Feature, or Geometry. |
| 85 |
|
| 86 |
<span class="h3"><a class="selflink" id="section-1.1" href="#section-1.1">1.1</a>. Requirements Language</span> |
| 87 |
|
| 88 |
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", |
| 89 |
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and |
| 90 |
"OPTIONAL" in this document are to be interpreted as described in |
| 91 |
[<a href="./rfc2119" title=""Key words for use in RFCs to Indicate Requirement Levels"">RFC2119</a>]. |
| 92 |
|
| 93 |
<span class="h2"><a class="selflink" id="section-2" href="#section-2">2</a>. GeoJSON Text Sequence Format</span> |
| 94 |
|
| 95 |
Defined in prose similar to the description of the JSON text sequence |
| 96 |
in [<a href="./rfc7464" title=""JavaScript Object Notation (JSON) Text Sequences"">RFC7464</a>], a GeoJSON text sequence is any number of GeoJSON |
| 97 |
[<a href="./rfc7946" title=""The GeoJSON Format"">RFC7946</a>] texts, each encoded in UTF-8 [<a href="./rfc3629" title=""UTF-8, a transformation format of ISO 10646"">RFC3629</a>], preceded by one |
| 98 |
ASCII [<a href="./rfc20" title=""ASCII format for network interchange"">RFC20</a>] record separator (RS) character, and followed by a line |
| 99 |
feed (LF). |
| 100 |
|
| 101 |
The GeoJSON text sequence format conforms to all the rules of |
| 102 |
[<a href="./rfc7464" title=""JavaScript Object Notation (JSON) Text Sequences"">RFC7464</a>] and adds the following constraint: each JSON text MUST |
| 103 |
contain a single GeoJSON object as defined in [<a href="./rfc7946" title=""The GeoJSON Format"">RFC7946</a>]. |
| 104 |
|
| 105 |
|
| 106 |
|
| 107 |
|
| 108 |
<span class="grey">Gillies Standards Track [Page 2]</span></pre> |
| 109 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-3" ></span> |
| 110 |
<span class="grey"><a href="./rfc8142">RFC 8142</a> GeoJSON Text Sequences April 2017</span> |
| 111 |
|
| 112 |
|
| 113 |
Heterogeneous sequences containing a mix of GeoJSON Geometry, |
| 114 |
Feature, and FeatureCollection objects are permitted. How producers |
| 115 |
and parsers of GeoJSON text sequences communicate rules for allowed |
| 116 |
GeoJSON types in exchanged sequences is not specified in this |
| 117 |
document. |
| 118 |
|
| 119 |
<span class="h2"><a class="selflink" id="section-3" href="#section-3">3</a>. Security Considerations</span> |
| 120 |
|
| 121 |
GeoJSON text sequences have no security considerations beyond those |
| 122 |
of JSON text sequences [<a href="./rfc7464" title=""JavaScript Object Notation (JSON) Text Sequences"">RFC7464</a>] and the GeoJSON format [<a href="./rfc7946" title=""The GeoJSON Format"">RFC7946</a>]. |
| 123 |
|
| 124 |
<span class="h2"><a class="selflink" id="section-4" href="#section-4">4</a>. Interoperability Considerations</span> |
| 125 |
|
| 126 |
The advantage of using ASCII character RS "0x1e" to denote a text is |
| 127 |
that sequence producers and parsers need not enforce a canonical form |
| 128 |
of GeoJSON. Any valid GeoJSON, pretty-printed or compact, can be |
| 129 |
used in a GeoJSON text sequence. |
| 130 |
|
| 131 |
A variety of parsers designed for newline-delimited sequences of |
| 132 |
compact JSON text are deployed on the internet today. While there is |
| 133 |
no canonical form for JSON texts, and pretty-printed and compact |
| 134 |
forms are equally valid, GeoJSON text sequences containing compact |
| 135 |
GeoJSON texts with no internal newlines are more interoperable with |
| 136 |
existing non-standardized parsers. |
| 137 |
|
| 138 |
In a distributed system where order and exactly-once delivery of |
| 139 |
messages are difficult to achieve, GeoJSON text sequences that do not |
| 140 |
rely on order of texts for extra semantics are more interoperable |
| 141 |
than those that do. |
| 142 |
|
| 143 |
<span class="h2"><a class="selflink" id="section-5" href="#section-5">5</a>. IANA Considerations</span> |
| 144 |
|
| 145 |
The MIME media type for GeoJSON text sequences is "application/ |
| 146 |
geo+json-seq" (which uses the suffix established in [<a href="./rfc8091" title=""A Media Type Structured Syntax Suffix for JSON Text Sequences"">RFC8091</a>]). IANA |
| 147 |
has registered it in the "Media Types" registry |
| 148 |
<<a href="https://www.iana.org/assignments/media-types/">https://www.iana.org/assignments/media-types/</a>>. |
| 149 |
|
| 150 |
Type name: application |
| 151 |
|
| 152 |
Subtype name: geo+json-seq |
| 153 |
|
| 154 |
Required parameters: n/a |
| 155 |
|
| 156 |
Optional parameters: n/a |
| 157 |
|
| 158 |
Encoding considerations: binary |
| 159 |
|
| 160 |
Security considerations: See <a href="./rfc8142#section-3">Section 3 of RFC 8142</a> |
| 161 |
|
| 162 |
|
| 163 |
|
| 164 |
<span class="grey">Gillies Standards Track [Page 3]</span></pre> |
| 165 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-4" ></span> |
| 166 |
<span class="grey"><a href="./rfc8142">RFC 8142</a> GeoJSON Text Sequences April 2017</span> |
| 167 |
|
| 168 |
|
| 169 |
Interoperability considerations: See <a href="./rfc8142#section-4">Section 4 of RFC 8142</a> |
| 170 |
|
| 171 |
Published specification: <a href="./rfc8142">RFC 8142</a> |
| 172 |
|
| 173 |
Applications that use this media type: Geographic information |
| 174 |
systems (GIS) |
| 175 |
|
| 176 |
Additional information: |
| 177 |
|
| 178 |
Deprecated alias names for this type: n/a |
| 179 |
|
| 180 |
Magic number(s): n/a |
| 181 |
|
| 182 |
File extension(s): n/a |
| 183 |
|
| 184 |
Macintosh file type code(s): n/a |
| 185 |
|
| 186 |
Person to contact for further information: Sean Gillies |
| 187 |
([email protected]) |
| 188 |
|
| 189 |
Intended usage: COMMON |
| 190 |
|
| 191 |
Restrictions on usage: none |
| 192 |
|
| 193 |
Author: Sean Gillies ([email protected]) |
| 194 |
|
| 195 |
Change controller: IETF |
| 196 |
|
| 197 |
<span class="h2"><a class="selflink" id="section-6" href="#section-6">6</a>. References</span> |
| 198 |
|
| 199 |
<span class="h3"><a class="selflink" id="section-6.1" href="#section-6.1">6.1</a>. Normative References</span> |
| 200 |
|
| 201 |
[<a id="ref-RFC20">RFC20</a>] Cerf, V., "ASCII format for network interchange", STD 80, |
| 202 |
<a href="./rfc20">RFC 20</a>, DOI 10.17487/RFC0020, October 1969, |
| 203 |
<<a href="http://www.rfc-editor.org/info/rfc20">http://www.rfc-editor.org/info/rfc20</a>>. |
| 204 |
|
| 205 |
[<a id="ref-RFC2119">RFC2119</a>] Bradner, S., "Key words for use in RFCs to Indicate |
| 206 |
Requirement Levels", <a href="https://www.rfc-editor.org/bcp/bcp14">BCP 14</a>, <a href="./rfc2119">RFC 2119</a>, |
| 207 |
DOI 10.17487/RFC2119, March 1997, |
| 208 |
<<a href="http://www.rfc-editor.org/info/rfc2119">http://www.rfc-editor.org/info/rfc2119</a>>. |
| 209 |
|
| 210 |
[<a id="ref-RFC3629">RFC3629</a>] Yergeau, F., "UTF-8, a transformation format of ISO |
| 211 |
10646", STD 63, <a href="./rfc3629">RFC 3629</a>, DOI 10.17487/RFC3629, November |
| 212 |
2003, <<a href="http://www.rfc-editor.org/info/rfc3629">http://www.rfc-editor.org/info/rfc3629</a>>. |
| 213 |
|
| 214 |
[<a id="ref-RFC7159">RFC7159</a>] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data |
| 215 |
Interchange Format", <a href="./rfc7159">RFC 7159</a>, DOI 10.17487/RFC7159, March |
| 216 |
2014, <<a href="http://www.rfc-editor.org/info/rfc7159">http://www.rfc-editor.org/info/rfc7159</a>>. |
| 217 |
|
| 218 |
|
| 219 |
|
| 220 |
<span class="grey">Gillies Standards Track [Page 4]</span></pre> |
| 221 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-5" ></span> |
| 222 |
<span class="grey"><a href="./rfc8142">RFC 8142</a> GeoJSON Text Sequences April 2017</span> |
| 223 |
|
| 224 |
|
| 225 |
[<a id="ref-RFC7464">RFC7464</a>] Williams, N., "JavaScript Object Notation (JSON) Text |
| 226 |
Sequences", <a href="./rfc7464">RFC 7464</a>, DOI 10.17487/RFC7464, February 2015, |
| 227 |
<<a href="http://www.rfc-editor.org/info/rfc7464">http://www.rfc-editor.org/info/rfc7464</a>>. |
| 228 |
|
| 229 |
[<a id="ref-RFC7946">RFC7946</a>] Butler, H., Daly, M., Doyle, A., Gillies, S., Hagen, S., |
| 230 |
and T. Schaub, "The GeoJSON Format", <a href="./rfc7946">RFC 7946</a>, |
| 231 |
DOI 10.17487/RFC7946, August 2016, |
| 232 |
<<a href="http://www.rfc-editor.org/info/rfc7946">http://www.rfc-editor.org/info/rfc7946</a>>. |
| 233 |
|
| 234 |
<span class="h3"><a class="selflink" id="section-6.2" href="#section-6.2">6.2</a>. Informative References</span> |
| 235 |
|
| 236 |
[<a id="ref-RFC8091">RFC8091</a>] Wilde, E., "A Media Type Structured Syntax Suffix for JSON |
| 237 |
Text Sequences", <a href="./rfc8091">RFC 8091</a>, DOI 10.17487/RFC8091, February |
| 238 |
2017, <<a href="http://www.rfc-editor.org/info/rfc8091">http://www.rfc-editor.org/info/rfc8091</a>>. |
| 239 |
|
| 240 |
Author's Address |
| 241 |
|
| 242 |
Sean Gillies |
| 243 |
Mapbox |
| 244 |
|
| 245 |
Email: [email protected] |
| 246 |
URI: <a href="http://sgillies.net">http://sgillies.net</a> |
| 247 |
|
| 248 |
|
| 249 |
|
| 250 |
|
| 251 |
|
| 252 |
|
| 253 |
|
| 254 |
|
| 255 |
|
| 256 |
|
| 257 |
|
| 258 |
|
| 259 |
|
| 260 |
|
| 261 |
|
| 262 |
|
| 263 |
|
| 264 |
|
| 265 |
|
| 266 |
|
| 267 |
|
| 268 |
|
| 269 |
|
| 270 |
|
| 271 |
|
| 272 |
|
| 273 |
|
| 274 |
|
| 275 |
|
| 276 |
Gillies Standards Track [Page 5] |
| 277 |
</pre> |