jsonlines/index.html at gh-pages · atensoftware/jsonlines · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
<!DOCTYPE html>
<html>
  <head>
    <meta charset='utf-8'>
    <meta http-equiv="X-UA-Compatible" content="chrome=1">
    <link href='https://fonts.googleapis.com/css?family=Chivo:900' rel='stylesheet' type='text/css'>
    <link rel="stylesheet" type="text/css" href="stylesheets/stylesheet.css" media="screen" />
    <link rel="stylesheet" type="text/css" href="stylesheets/pygment_trac.css" media="screen" />
    <link rel="stylesheet" type="text/css" href="stylesheets/print.css" media="print" />
    <!--[if lt IE 9]>
    <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->
    <title>JSON Lines</title>
  </head>

  <body>
    <div id="container">
      <div class="inner">

        <header>
          <h1>JSON Lines</h1>
          <h2>Documentation for the JSON Lines text file format</h2>
        </header>

<nav><ul>
<li>Home</li>
<li><a href="/examples/">Examples</a></li>
<li><a href="/on_the_web/">On the web</a></li>
<li><a href="https://json.org/">json.org</a></li>
</ul></nav>

        <hr>

        <section id="main_content">
<p>This page describes the JSON Lines text format, also called newline-delimited JSON.
JSON Lines is a convenient format for storing
structured data that may be processed one record at a time. It works well with unix-style
text processing tools and shell pipelines. It's a great format for log files.
It's also a flexible format for passing messages between cooperating processes.</p>

<p>The JSON Lines format has three requirements:</p>

<h3>
<a name="utf-8-encoding" class="anchor" href="#utf-8-encoding"><span class="octicon octicon-link"></span></a>1. UTF-8 Encoding</h3>

<p>JSON allows encoding Unicode strings with only ASCII escape sequences,
however those escapes will be hard to read when viewed in a text editor.
The author of the
JSON Lines file may choose to escape characters to work with plain ASCII files.</p>

<p>Encodings other than UTF-8
are very unlikely to be valid when decoded as UTF-8 so the chance of
<a href="https://en.wikipedia.org/wiki/Mojibake">accidentally misinterpreting
characters</a> in JSON Lines files is low.</p>

<h3>
<a name="each-line-is-a-valid-json-value" class="anchor" href="#each-line-is-a-valid-json-value"><span class="octicon octicon-link"></span></a>2. Each Line is a Valid JSON Value</h3>

<p>The most common values will be objects or arrays, but any JSON value is permitted.</p>
<p>See <a href="https://json.org/">json.org</a> for more information about JSON values.</p>

<h3>
<a name="line-separator-is-n" class="anchor" href="#line-separator-is-n"><span class="octicon octicon-link"></span></a>3. Line Separator is <code>'\n'</code>
</h3>

<p>This means <code>'\r\n'</code> is also supported because surrounding white space is implicitly ignored when parsing JSON values.</p>

<p>The last character in the file <em>may</em> be a line separator, and it will be treated the same as
if there was no line separator present.</p>

<h3>
<a name="conventions" class="anchor" href="#conventions"><span class="octicon octicon-link"></span></a>Suggested Conventions</h3>

<p>JSON Lines files may be saved with the file extension <code>.jsonl</code>.</p>

<p>Stream compressors like <code>gzip</code> or <code>bzip2</code>
are recommended for saving space, resulting in <code>.jsonl.gz</code> or <code>.jsonl.bz2</code> files.</p>

<p>Text editing programs call the first line of a text file "line 1". The first value in a JSON Lines file should also be called "value 1".</p>
        </section>


        <footer>
          <a href="https://github.com/wardi/jsonlines/issues">Report a bug or make a suggestion</a> &bull;
          Tactile theme by <a href="https://twitter.com/jasonlong">Jason Long</a> &bull;
          This page is maintained by <a href="https://excess.org">Ian Ward</a>.
        </footer>


      </div>
    </div>
  </body>
</html>