The JSONUtil structure
Author: John Reppy
Keywords: Standard ML, SML, SML/NJ Library

The SML of NJ Library
The `JSONUtil` structure

The `JSONUtil` module defines a collection of utility functions for working with JSON values. These include operations for testing if a value is of a given type and navigating the structure of a JSON value.

## Synopsis

    structure JSONUtil

## Interface

    exception JSONError of exn * JSON.value

    exception NotBool
    exception NotInt
    exception NotNumber
    exception NotString

    exception NotObject

    exception FieldNotFound of string

    exception NotArray

    exception ArrayBounds of int

    exception ElemNotFound

    val exnMessage : exn -> string

    val asBool : JSON.value -> bool
    val asInt : JSON.value -> Int.int
    val asIntInf : JSON.value -> IntInf.int
    val asNumber : JSON.value -> Real.real
    val asString : JSON.value -> string

    val findField : JSON.value -> string -> JSON.value option
    val lookupField : JSON.value -> string -> JSON.value
    val hasField : string -> JSON.value -> bool
    val testField : string -> (JSON.value -> bool) -> JSON.value -> bool

    val asArray : JSON.value -> JSON.value vector

    val arrayMap : (JSON.value -> 'a) -> JSON.value -> 'a list

    datatype edge
      = SEL of string
      | SUB of int
      | FIND of JSON.value -> bool

    type path = edge list

    val get : JSON.value * path -> JSON.value

    val replace : JSON.value * path * JSON.value -> JSON.value

    val insert : JSON.value * path * string * JSON.value -> JSON.value

    val append : JSON.value * path * JSON.value list -> JSON.value

## Description

`exception JSONError of exn * JSON.value`

  raised when an error is detected during processing of a JSON value. The first argument, which is one of the exceptions described below, details the type of error and the second argument is the value that was being processed at the point of the error.

`exception NotBool of JSON.value`

  used by the `asBool` function when the argument is not a JSON boolean.

`exception NotInt of JSON.value`

  used by the `asInt` and `asIntInf` functions when the argument is not a JSON integer number.

`exception NotNumber of JSON.value`

  used by the `asNumber` function when the argument is not a JSON number.

`exception NotString of JSON.value`

  used by the `asString` function when the argument is not a JSON string.

`exception NotObject of JSON.value`

  used by the `findField` and `lookupField` functions when the argument is not a JSON object.

`exception FieldNotFound of JSON.value * string`

  This exception is used when the given field is not found in an object.

`exception NotArray of JSON.value`

  This exception is used when trying to process a non-array value as an array.

`exception ArrayBounds of JSON.value * int`

  This exception is used when access to an array value is out of bounds.

`exception ElemNotFound of JSON.value`

  This exception is used when there is no element of an array that satisfies the predicate of a `FIND` edge in a path. The argument will be the array in question.

`val exnMessage : exn -> string`

  `exnMessage exn` returns an error-message string for the exception value `exn`. This function produces specialized messages for the `JSONError` wrapped around the other exceptions defined in this structure (or the `Fail` exception). It falls back to the General.exnMessage function for other exceptions.

`val asBool : JSON.value -> bool`

  `asBool (JSON.BOOL b)` returns the value `b`. This function raises the exception value `JSONError(NotBool, jv)` if the argument `jv` is not a JSON boolean value.

`val asInt : JSON.value -> int`

  `asInt (JSON.INT n)` returns the value `n` converted to `int`. This function raises the exception value `JSONError(NotInt, jv)` if the argument `jv` is not a JSON integer value. It may also raise the exception value `JSONError(Overflow, jv)` if `n` is too large for the default `int` type.

`val asIntInf : JSON.value -> IntInf.int`

  `asIntInf (JSON.INT n)` returns the value `n`. This function raises the exception value `JSONError(NotInt, jv)` if the argument `jv` is not a JSON integer value.

`val asNumber : JSON.value -> Real.real`

  `asNumber jv` converts the JSON number `jv` to an SML `real` value. The `jv` argument can either have the form `JSON.INT n`, in which case `n` is converted to the `real` type and returned, or `JSON.FLOAT f`, in which case `f` is returned; otherwise, the exception value `JSONError(NotNumber, jv)` is raised.

`val asString : JSON.value -> string`

  `asBool (JSON.STRING s)` returns the value `s`. This function raises the exception value `JSONError(NotString, jv)` if the argument `jv` is not a JSON string.

`val findField : JSON.value -> string -> JSON.value option`

  `findField (JSON.OBJECT flds) key` returns `SOME jv` when the list of fields `flds` contains `(key, jv)` and `NONE` otherwise. If `findField` is called on a value `v` that is not a JSON object, then it raises the exception value `JSONError(NotObject, v)`

`val lookupField : JSON.value -> string -> JSON.value`

  `lookupField (JSON.OBJECT flds) key` returns `jv` when the list of fields `flds` contains `(key, jv)` and raises the exception value `JSONError(FieldNotFound key, v)` otherwise. If `lookupField` is called on a value `v` that is not a JSON object, then it raises the exception value `JSONError(NotObject, v)`.

`val hasField : string -> JSON.value -> bool`

  `hasField key v` returns `true` when the value `v` is a JSON object that has a field with `key` as its label and `false` otherwise.

`val testField : string -> (JSON.value -> bool) -> JSON.value -> bool`

  `testField key pred v` returns the result of `pred jv` when the value `v` is a JSON object that contains `(key, jv)`. It returns `false` otherwise.

`val asArray : JSON.value -> JSON.value vector`

  `asArray jv` converts the JSON array value `jv` to an SML vector value. It raises the exception value `JSONError(NotArray, jv)` when `jv` is not a JSON array.

`val arrayMap : (JSON.value -> 'a) -> JSON.value -> 'a list`

  map a conversion function over a JSON array to produce a list; this function raises the exception value `JSONError(NotArray, v)` if the second argument `v` is not an array.

`datatype edge = …​`

  specifies an edge of a path into a JSON value. The constructors have the following meaning:

  `SEL of string`

    `SEL key` specifies the value labeled by `key` in a JSON object.

  `SUB of int`

    `SUB i` specifies the `i`th element of a JSON array.

  `FIND of JSON.value -> bool`

    `FIND pred` specifies the first element of a JSON array that satisfies the given predicate.

`type path = edge list`

  specifies a path into a JSON value.

`val get : JSON.value * path -> JSON.value`

  `get (jv, path)` returns the component of `jv` named by `path`. It raises the `JSONError` exception if there is an inconsistency between the path and the structure of `jv`. The first argument to the `JSONError` exception will be one of the `NotObject`, `NotArray`, `FieldNotFound`, or `ElemNotFound` exceptions.

## See Also

`JSON`, `JSONDecode`, The JSON Library

SML/NJ Version 110.99.9 (November 4, 2025)
Last updated 2025-11-04 15:48:25 UTC