📦 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

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!