## 📦 Working with JSON in Liquidsoap

Liquidsoap makes it easy—and safe—to work with JSON data directly in your scripts. Whether you’re loading configuration files, interfacing with APIs, or managing playlist metadata, JSON is a powerful format to master.

This page walks you through how JSON parsing works in Liquidsoap, how type safety is enforced, and how to use advanced features like nullable types, custom keys, and associative object parsing.

Let’s start simple and build progressively toward the more advanced features. 🧗

### 🔹 Getting Started: Parsing a Simple JSON Object

You can parse a JSON string using the special `let json.parse` syntax:

    let json.parse v = '{"foo": "abc"}'
    print("We parsed a JSON object and got value " ^ v.foo ^ " for attribute foo!")

✅ Output:

    We parsed a JSON object and got value abc for attribute foo!

What’s happening here?

Liquidsoap watches how you use `v.foo` (as a string), and it checks at runtime that the JSON contains `"foo"` and that its value is indeed a string. If there’s a mismatch, you’ll get a clear error.

Example with incorrect type:

    let json.parse v = '{"foo": 123}'

⛔ Raises:

    Error 14: Uncaught runtime error:
    type: json,
    message: "Parsing error: json value cannot be parsed as type {foo: string, _}"

### 📁 Loading JSON from Files

Instead of hardcoding JSON as a string, you can load it from a file:

    let json.parse v = file.contents("/path/to/file.json")

Let’s look at a realistic example. Suppose you’re parsing a `package.json` file from an npm package:

    let json.parse package = file.contents("/path/to/package.json")

    name = package.name
    version = package.version
    test = package.scripts.test

    print("This is package " ^ name ^ ", version " ^ version ^ " with test script: " ^ test)

### ✅ Use Type Annotations for Reliable Parsing

Sometimes Liquidsoap can’t infer types correctly—especially when you use variables only inside string interpolations (`#{...}`). In those cases, values default to `null`, which might be confusing.

The solution: add an explicit type annotation to your parse statement. The type annotation is then used to drive the parser and pick the json data that you are expecting:

    let json.parse ({
      name,
      version,
      scripts = {
        test
      }
    } : {
      name: string,
      version: string,
      scripts: {
        test: string
      }
    }) = file.contents("/path/to/package.json")

Now everything works as expected—even if you only reference variables inside interpolations.

## 🧩 Understanding JSON Type Annotations

Liquidsoap’s JSON parser uses a rich type system that maps onto JSON’s structure. Let’s break it down:

### 🔤 Ground Types

Type | Description | Example value
--- | --- | ---
`string` | A sequence of characters | `"hello"`
`int` | An integer | `42`
`float` | A number, including decimals | `3.14` or `123.0`

Liquidsoap will coerce integers into floats if needed (e.g. `123` can be a `float`).

### ❓ Nullable Types

Add `?` to make a type optional:

    test: string?  # test is either a string or null

Useful when parsing data that may or may not include a field:

    let json.parse ({
      scripts
    } : {
      scripts: {
        test: string?
      }?
    }) = file.contents("package.json")

You can check for presence using:

    # Option 1: Explicit check
    test =
      if null.defined(scripts) then
        null.get(scripts.test)
      else
        null()
      end

    # Option 2: Fallback value
    test = (scripts ?? { test = null }).test

### 🔗 Tuples

Tuples parse fixed-size arrays with specific types for each position:

    (int * float * string)

This parses a JSON array like `[1, 2.5, "hello"]`.

Use `_` as a wildcard to ignore types you don’t care about:

    (_ * _ * float)  # Only the third element must be a float

### 📋 Lists

To parse a JSON array of values of the same type, use brackets:

    [int]     # list of integers
    [float?]  # list of optional floats

Example:

    [44.0, 55, 66.12]

Can be parsed as: `[float]`

### 🧱 Objects (Records)

Use `{...}` to parse JSON objects into named fields:

    {foo: int, bar: string}

This tells Liquidsoap to extract only the fields you care about. Extra fields in the JSON are ignored.

### 🏷️ Custom JSON Keys

JSON keys often contain characters or spaces that aren’t valid Liquidsoap variable names.

You can map them like this:

    {"foo bar" as foo_bar: int}

Example:

    { "foo bar": 123 }

Liquidsoap parses this as a variable `foo_bar = 123`.

### 🗂️ Associative Objects as Lists

What if you don’t know the keys in advance?

Use `[(string * < value type>)] as json.object` to treat an object like a list of key-value pairs.

Example JSON:

    { "a": 1, "b": 2, "c": 3 }

Use this type:

    [(string * int)] as json.object

Parsed as:

    [("a", 1), ("b", 2), ("c", 3)]

You can even use `int?` if some values might be missing or of a non-int type.

### ⚠️ Handling Errors

Parsing errors raise a `error.json` exception:

    try
      let json.parse ({status, data = {track}} : {...}) = response
      # Do something with data
    catch err: [error.json] do
      # Handle the parse failure
    end

## 🧪 Full Example

    data = '{
      "foo": 34.24,
      "gni gno": true,
      "nested": {
        "tuple": [123, 3.14, false],
        "list":  [44.0, 55, 66.12],
        "nullable_list": [12.33, 23, "aabb"],
        "object_as_list": {
          "foo": 123,
          "gni": 456.0,
          "gno": 3.14
        },
        "arbitrary object key ✨": true
      }
    }'

    let json.parse (x :
      {
        foo: float,
        "gni gno" as gni_gno: bool,
        nested: {
          tuple: (_ * float),
          list: [float],
          nullable_list: [int?],
          object_as_list: [(string * float)] as json.object,
          "arbitrary object key ✨" as arbitrary_key: bool,
          not_present: bool?
        }
      }
    ) = data

### 🛠️ Other Features

- JSON5 support (for trailing commas, comments, etc.):

    let json.parse[json5=true] x = ...

- Exporting to JSON:

    print(json.stringify({artist="Bla", title="Blo"}))

- Building JSON manually:

This can be useful when dynamically generating json output:

    j = json()
    j.add("foo", 1)
    j.add("bar", "baz")
    j.remove("foo")
    print(json.stringify(j))

## 🚀 Recap

✅ Liquidsoap gives you a safe and expressive way to work with JSON 🧠 Type annotations help catch issues early and make your code clearer 🛠️ Advanced types let you tackle real-world data with ease

Once you’ve got the hang of parsing, try exploring the actual `tests/language/json.liq` test file in the source repo—it’s full of neat examples and tricks!