Ziggy Schema Custom Types

In this section we’re going to see types that must be defined before they can be used in a type expression.

Struct

Definition

Here’s an example struct definition:

///An example struct representing a person.
struct Person {
  name: bytes,
  height: float,
  ///Null when person has no pet.
  pet_name: ?bytes,
  interests: []bytes,
}

In this example Person is the struct name. It’s recommended to use TitleCase for struct names, but not mandatory.

A struct can have zero or more comma separated field definitions. A field definition comprises an identifier, followed by : and a type expression.

Both struct definitions and their fields can have an optional doc comment attached to them which will be shown to users by the Ziggy LSP.

Expression

A struct can be referenced in a type expression by its name.

Examples: Person, {:}Person, []Command, ?Notification

Tagged Union

Sometimes also called “sum types”, tagged unions are containers where only one of the possible fields is active at a time.

Definition

Here’s an example union definition:

///An example struct representing a person.
union Date {
   /// An ISO something something date, e.g. "1990-01-01T00:00:00"
   iso: bytes, 
   /// A unix second timestamp, e.g. 1763128087
   unix: int,
   /// Unknown date
   unknown,
}

This type would match the following use in a Ziggy Document:

.title = "My blog post",
.date = .iso("2025-01-01T:00:00:00")

In this example we chose iso, which is a union case that has a bytes payload.

Union cases can also have no payload, in which case their syntax looks as follows:

.title = "A mystical blog post",
.date = .unknown,

Expression

Just like structs, a tagged union can be referenced in a type expression by its name.