Debian Codegraph @

rfc8142.html

raw
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&nbsp;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="&quot;The JavaScript Object Notation (JSON) Data Interchange Format&quot;">RFC7159</a>] that is well explained in the
74 motivation for JSON text sequences [<a href="./rfc7464" title="&quot;JavaScript Object Notation (JSON) Text Sequences&quot;">RFC7464</a>]. The GeoJSON format
75 [<a href="./rfc7946" title="&quot;The GeoJSON Format&quot;">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="&quot;Key words for use in RFCs to Indicate Requirement Levels&quot;">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="&quot;JavaScript Object Notation (JSON) Text Sequences&quot;">RFC7464</a>], a GeoJSON text sequence is any number of GeoJSON
97 [<a href="./rfc7946" title="&quot;The GeoJSON Format&quot;">RFC7946</a>] texts, each encoded in UTF-8 [<a href="./rfc3629" title="&quot;UTF-8, a transformation format of ISO 10646&quot;">RFC3629</a>], preceded by one
98 ASCII [<a href="./rfc20" title="&quot;ASCII format for network interchange&quot;">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="&quot;JavaScript Object Notation (JSON) Text Sequences&quot;">RFC7464</a>] and adds the following constraint: each JSON text MUST
103 contain a single GeoJSON object as defined in [<a href="./rfc7946" title="&quot;The GeoJSON Format&quot;">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="&quot;JavaScript Object Notation (JSON) Text Sequences&quot;">RFC7464</a>] and the GeoJSON format [<a href="./rfc7946" title="&quot;The GeoJSON Format&quot;">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="&quot;A Media Type Structured Syntax Suffix for JSON Text Sequences&quot;">RFC8091</a>]). IANA
147 has registered it in the "Media Types" registry
148 &lt;<a href="https://www.iana.org/assignments/media-types/">https://www.iana.org/assignments/media-types/</a>&gt;.
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&nbsp;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&nbsp;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 &lt;<a href="http://www.rfc-editor.org/info/rfc20">http://www.rfc-editor.org/info/rfc20</a>&gt;.
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 &lt;<a href="http://www.rfc-editor.org/info/rfc2119">http://www.rfc-editor.org/info/rfc2119</a>&gt;.
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, &lt;<a href="http://www.rfc-editor.org/info/rfc3629">http://www.rfc-editor.org/info/rfc3629</a>&gt;.
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, &lt;<a href="http://www.rfc-editor.org/info/rfc7159">http://www.rfc-editor.org/info/rfc7159</a>&gt;.
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 &lt;<a href="http://www.rfc-editor.org/info/rfc7464">http://www.rfc-editor.org/info/rfc7464</a>&gt;.
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 &lt;<a href="http://www.rfc-editor.org/info/rfc7946">http://www.rfc-editor.org/info/rfc7946</a>&gt;.
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, &lt;<a href="http://www.rfc-editor.org/info/rfc8091">http://www.rfc-editor.org/info/rfc8091</a>&gt;.
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>