The jsonparse package

The jsonparse package provides a handy way to read in JSON data from files or strings in LaTeX documents, parse the data and store it in a user-defined token variable. The package allows accessing the stored data via a JavaScript-flavored syntax.

Using the commands \JSONParseFromFile or \JSONParse, JSON data can be stored in a token variable. Using the command \JSONParseValue, entries can be extracted from the stored data.

Let's assume a file with the name example.json is stored in the working directory with the following contents:

{
  "givenName": "Joe",
  "familyName": "Public",
  "points": 1.7,
  "hasCertification": true,
  "address": {
    "streetAddress": "10 Main St",
    "locality": "Cityville",
    "postalCode": "12345"
  },
  "contactPoint": [
    {
      "contactType": "office",
      "telephone": "+1 (555) 555-1234"
    },
    {
      "contactType": "mobile",
      "telephone": "+1 (555) 555-6789"
    }
  ],
  "children": [
    "Tom",
    "Doug",
    "Harry"
  ],
  "memberOf": null
}

We can store it in the token variable \myJSONdata using the command \JSONParseFromFile{\myJSONdata}{example.json}. Calling the command \JSONParseValue{\myJSONdata}{contactPoint[0].telephone} would then result in the output +1 (555) 555-1234 (indices are zero-based per default). The package allows for parsing JSON data inline as well.

The package also offers several commands for looping through arrays and accessing individual elements, for example to typeset them in tabular form or to plot their values using packages such as PGFPlots.

Adding commas between the items of the children array can be done with:

\JSONParseArrayUse{\myJSONdata}{children}{, }

A tabular listing the contact points of above JSON file can be created with:

\begin{tabular}{cc}
\textbf{Contact Type} & \textbf{Telephone} \\
\JSONParseArrayMapInline{\myJSONdata}{contactPoint}{%
  \JSONParseValue{\myJSONdata}{contactPoint[#1].contactType} & 
  \JSONParseValue{\myJSONdata}{contactPoint[#1].telephone} \\
}
\end{tabular}

The package also provides a few helper commands such as to validate a JSON number or to convert Unicode surrogate pairs to the relevant Unicode codepoint.

Frequently asked questions

Why does a comparison of two equal strings return false?

1) Note that if you probably need to use \JSONParseExpandableValue if you want to compare a value from parsed JSON data with the contents of another token list.

2) Also note that \JSONParseExpandableValue returns a string with specific category codes, namely category code 12 (other'') for all characters except spaces. Therefore, you need to test against another string. You can use \detokenize for conversion.

Why does parsing take so long?

1) Make sure that you use the most recent version of the package. Parsing speed is constantly monitored and updates typically increase parsing speed.

2) If you don't need to access whole objects or arrays from the JSON data, you can set the key skip structures which should increase parsing speed.

3) If the JSON data contains a considerable amount of numbers, parsing speed can be increased slightly by setting validate numbers=false.

4) If the JSON data does not change often, you can externalise the parsed result by setting the key externalize.

This package including all files is subject to the LPPL 1.3c license. Copyright 2024–2025 Jasper Habicht (mail(at)jasperhabicht.de).

Jason, the JSON parsing horse: Copyright 2024–2025 Hannah Klöber.