Parse JSON text with gleam/json and decode it with decoder.

Text above 1 MiB (1,048,576 bytes of UTF-8) is rejected before parsing with json.UnableToDecode; its one error has an empty path, expected names the limit and found is "more than <limit> bytes". Use decode_with_max_bytes to accept larger text.

Return the constructor for any input, including a non-object value. The legacy schema describes an empty closed object, but this decoder does not enforce that description.

Like decode, but reject text above max_bytes bytes of UTF-8 instead of the 1 MiB default. A max_bytes below 1 rejects every non-empty text.

Prepend an encoded field for Some, or omit it for None. Pair this encoder with optional_field when absence represents None.

Example

fn tree_decoder() {
  blueprint.union_type_decoder([
    #(
      "node",
      blueprint.decode3(
        Node,
        blueprint.field("value", blueprint.int()),
        // This is an optional field for an optional value
        blueprint.optional_field("left", blueprint.self_decoder(tree_decoder)),
        // And this is a required field with an optional value
        blueprint.field(
          "right",
          blueprint.optional(blueprint.self_decoder(tree_decoder)),
        ),
      ),
    ),
  ])
  |> blueprint.reuse_decoder
}

fn encode_tree(tree: Tree) -> json.Json {
  blueprint.union_type_encoder(tree, fn(node) {
    case node {
      Node(value, left, right) -> #(
        "node",
        [
          #("value", json.int(value)),
          // This is a required field with an optional value
          #("right", json.nullable(right, encode_tree)),
        ]
          // And this is an optional field for an optional value
          |> blueprint.encode_optional_field("left", left, encode_tree)
          |> json.object(),
      )
    }
  })
}

Decode {"enum": label} using the listed label/value pairs. Test every enum value; the compiler cannot check that this list is exhaustive.

Example

type Color {
  Red
  Green
  Blue
}

let color_decoder = enum_type_decoder([
  #("red", Red),
  #("green", Green),
  #("blue", Blue),
])

Encode a constructor with no arguments as {"enum": label}. The callback selects its label; keep labels aligned with enum_type_decoder.

Example

type Color {
  Red
  Green
  Blue
}

let color_encoder = enum_type_encoder(fn(color) {
  case color {
    Red -> "red"
    Green -> "green"
    Blue -> "blue"
  }
})

The decoder as a function over Dynamic data, for use with a parser other than decode. Errors use gleam/dynamic/decode.DecodeError.

Decode null as None and another value with the inner decoder as Some. A missing field still fails; use optional_field for absence.

Example

type User {
  User(name: String, age: Option(Int))
}

let decoder = decode2(
  User,
  field("name", string()),
  field("age", optional(int()))  // Will handle "age": null
)

// These JSON strings will decode successfully:
// {"name": "Alice", "age": 25}  -> User("Alice", Some(25))
// {"name": "Bob", "age": null}  -> User("Bob", None)

Decode an absent or null field as None, and a present value with the inner decoder as Some. Use field with optional when the field must be present but may be null.

Example

type User {
  User(name: String, age: Option(Int))
}

let decoder = decode2(
  User,
  field("name", string()),
  optional_field("age", int())  // Will handle both missing "age" field and "age": null
)

// All these JSON strings will decode successfully:
// {"name": "Alice", "age": 25}     -> User("Alice", Some(25))
// {"name": "Bob", "age": null}     -> User("Bob", None)
// {"name": "Charlie"}              -> User("Charlie", None)

Put the decoder’s schema in $defs and return a decoder whose schema points to it with $ref. The name derives from the rendered schema’s SHA-1 hash; it is a deterministic definition key, not a collision guarantee.

Example

type Person {
  Person(name: String, friends: List(Pet))
}

type Pet {
  Pet(name: String)
}


let pet_decoder = reuse_decoder(
  decode2(
    Pet,
    field("name", string()),
  )
)

let person_decoder = reuse_decoder(
  decode2(
    Person,
    field("name", string()),
    field("friends", list(pet_decoder))
  )
)

Decode a recursive type through a function that returns its decoder. The schema uses $ref: "#" for a root self-reference.

Wrap recursive decoders in reuse_decoder. Nested recursive types need their root references rebased to distinct definitions.

Example

// A binary tree type that can contain itself
pub type Tree {
  Node(value: Int, left: Option(Tree), right: Option(Tree))
  Leaf(value: Int)
}

// Create a recursive decoder for the Tree type
pub fn tree_decoder() -> Decoder(Tree) {
  // Use union_type_decoder for handling different variants
  union_type_decoder([
    #("leaf", decode1(Leaf, field("value", int()))),
    #("node", decode3(
      Node,
      field("value", int()),
      // Use self_decoder to handle recursive fields
      field("left", optional(self_decoder(tree_decoder))),
      field("right", optional(self_decoder(tree_decoder))),
    )),
  ])
  |> reuse_decoder
}

Decode a type/data union using the payload decoder for its label. Test every variant; the compiler cannot check that this list is exhaustive.

Example

type Shape {
  Circle(Float)
  Rectangle(Float, Float)
}

let shape_decoder = union_type_decoder([
  #("circle", decode1(Circle, field("radius", float()))),
  #("rectangle", decode2(Rectangle,
    field("width", float()),
    field("height", float())
  ))
])

Encode a union as an object with type and data fields. The callback returns the variant label and its encoded payload. Keep the labels and payloads aligned with union_type_decoder.

Example

type Shape {
  Circle(Float)
  Rectangle(Float, Float)
}

let shape_encoder = union_type_encoder(fn(shape) {
  case shape {
    Circle(radius) -> #("circle", json.object([#("radius", json.float(radius))]))
    Rectangle(width, height) -> #(
      "rectangle",
      json.object([
        #("width", json.float(width)),
        #("height", json.float(height))
      ])
    )
  }
})