Skip to content
Tutorials Center
My learning

Topics

Lesson 128 of 134 ยท Projects

Project: A JSON Parser

Build a complete JSON parser in Kotlin: a sealed value tree, a recursive descent parser with precise error positions, a compact writer, a pretty printer and path queries.

JSON looks simple, and that is exactly why writing a parser for it is such a good project. The whole grammar fits in a short list: objects, arrays, strings, numbers, true, false and null. Yet building a parser forces you to use the features that make Kotlin pleasant: sealed interfaces for the data model, exhaustive when for walking it, extension functions for operations, and custom exceptions for clear error messages.

By the end you will have four tools that work together: a typed tree for JSON values, a parser that turns text into that tree, a writer that turns the tree back into text (compact and pretty), and a small query function such as doc.at("users[0].name"). Everything runs in the browser, with no libraries. In real projects you would use kotlinx.serialization; the lesson Working with JSON Text explains when. Writing it once yourself shows you what such a library does.

Step 1: a tree for JSON values

A JSON value is exactly one of seven shapes. That is the textbook use of a sealed interface: the compiler knows every case, so a when over it needs no else branch, and adding an eighth case later makes every incomplete when fail to compile.

Kotlin The JSON tree and a compact writer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

Notice what the when does. JsonNull is a data object, so you match it directly without is. Each other branch smart-casts this, which is why value, items and fields are available without a cast. Numbers are stored as Double, as JavaScript does; the writer prints whole numbers without .0 so 36.0 reads 36.

The quote function is where hand-written JSON usually goes wrong. A string must escape the quote and the backslash, and every control character below space. Anything else can stay as it is.

Step 2: a recursive descent parser

The idea behind a recursive descent parser is that each grammar rule becomes one function, and rules that contain other rules call each other. An array is [, then zero or more values separated by commas, then ]; so array() calls value() for every element, and value() may call array() again. The recursion in your code mirrors the nesting in the text.

The parser keeps one piece of state, pos, the index of the next unread character. It never builds a separate list of tokens; it looks at text[pos] and decides what to do. When something is wrong it calls fail, which returns Nothing, so the compiler knows control never continues past it.

Kotlin Parsing text into the tree

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

Study the structure of array(). It checks for the empty array first, then loops: parse a value, skip spaces, and either consume a comma and continue or require the closing bracket. obj() has the same shape with a key and a colon in front of each value. Because every function consumes exactly its own text and leaves pos right after it, the functions compose without any bookkeeping.

The error messages carry a position, the index where the parser stopped. That is cheap to add (you already track pos) and it turns "invalid JSON" into something a user can act on. A production parser would also report line and column.

Step 3: pretty printing and queries

The compact writer is ideal for machines, but people want indentation. A pretty printer is the same walk over the tree with one extra parameter, the current depth. Queries are another walk: follow a path such as users[0].name one step at a time, returning null as soon as a step does not exist.

Kotlin Pretty printing and path queries

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

Two details deserve attention. ?: return null inside the loop uses the elvis operator with an early return, so a missing step ends the function immediately. And as? turns "the wrong kind of value" into null instead of an exception, so title.length (asking for a field of a string) quietly answers null.

Step 4: put it together and test the round trip

The best test for a parser and a writer is the round trip: parse some text, write the tree back, parse again, and check that you get an equal tree. Because the tree is made of data classes, == compares the whole structure. The program below contains all four tools in about a hundred and fifty lines, plus a small recursive generator that creates a varied tree from a seeded random source, so the output is the same on every run.

Kotlin The complete JSON toolkit with a round-trip test

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

If the writer or the parser had a bug, check would stop the program with the failing text. That is a tiny example of property-based testing: instead of a handful of fixed examples, you state a rule (parse after write gives the original) and try it on many generated inputs. See Testing in Kotlin for the basics.

Where to go from here

You now have a working JSON library in roughly two hundred lines. To make it production-grade, extend it step by step:

  • Add the \uXXXX, \b, \f and \r escapes to the Step 4 parser (the Step 2 parser already reads them) and make the writer escape control characters (Step 1 does).
  • Reject numbers JSON forbids, such as 01 or +1. The parser above accepts what toDouble() accepts, which is more than the specification allows.
  • Report line and column in errors, by counting newlines up to pos.
  • Limit nesting depth. A malicious input of a million [ characters would overflow the stack of a recursive parser; real libraries cap the depth.
  • Use BigDecimal for numbers when exactness matters, because Double cannot represent every integer above 2^53.

Never evaluate or trust parsed JSON blindly. The parser tells you the text is well formed, not that a field you need exists, has the right type or is within range. Validate the values you use.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why is a sealed interface a good fit for the JSON value tree?

    A sealed hierarchy is closed, so when can be checked for exhaustiveness. Adding a new case makes incomplete when expressions fail to compile.
  2. 2. What does a recursive descent parser do for the grammar rule 'an array contains values'?

    Each grammar rule becomes a function, and nested rules become recursive calls, so the code's call structure mirrors the nesting of the input.
  3. 3. Why does the parser's fail function return Nothing?

    Nothing is the type of expressions that never complete. It lets fail(...) be used where a value is expected, for example as the last branch of a when or after ?:.
  4. 4. What does the round-trip test in step 4 check?

    The test writes a tree to text, parses it again and compares the two trees with ==, which data classes implement structurally.
  5. 5. What does doc.at("title.length") return when title is a JSON string?

    The step looks up a field in something that is not a JsonObject; as? yields null and ?: return null ends the function with null.

Summary

  • Model JSON as a sealed interface with one case per kind of value; use data object for null and data classes for the rest.
  • A recursive descent parser has one function per grammar rule and one piece of state, the position.
  • Make failures precise: a custom exception with a message and a position, raised through a helper that returns Nothing.
  • Operations on the tree (writing, pretty printing, querying) are extension functions with an exhaustive when.
  • Test a parser and a writer together with a round trip over many generated inputs.
  • Real parsers also limit nesting depth, follow the number grammar strictly and report line and column.

Next: Kotlin Cheat Sheet