Ziggy Container Value Types

Arrays

Ziggy uses [] (square brackets) to denote arrays. An array can contain zero or more elements separated by commas. Trailing commas are allowed.

Ziggy arrays can contain different types of values and can be nested arbitrarily deep, although there are some caveats with how that interacts with Ziggy Schemas (more on that in the Ziggy Schema section).

Examples: [1, 2, 3], [true, null, 42], ["hello", [1], []]

Dictionaries

Dictionaries (or just ‘dicts’) are the first key-value mapping notation available in Ziggy.

Dictionaries are meant to denote key-value mappings where key names are controlled by the user.

It’s common for configuration files and API messages to have key-value mappings where key names are meant to be part of a schema, while some other key-value mappings are instead meant to be fully controlled by the user.

One example of this is NPM’s package.json:

{
  "name": "ziggy",
  "dependencies": {
    "react": "next",
    "leftpad": "^1.0.0"
  }
}

In this example you can see how "name" and "dependencies" are part of a schema, while dependency names are up to the user. In Ziggy the outer key-value mapping would be represented as a struct, while "dependencies" would be a dict.

Ziggy dictionary syntax looks like this:

{
  "hello": "world",
  "foo": true,
}

Ziggy dicts have the same notation as JSON objects but allow trailing commas, and in fact all valid JSON files are valid Ziggy files made up of dicts.

A hypothetical package.ziggy, where the outer key-value map is expressed as a struct, would look like this:

.{
  .name = "ziggy",
  .dependencies = {
    "react": "next",
    "leftpad": "^1.0.0",
  },
}

Structs

Structs are the second key-value mapping notation available in Ziggy. Structs are meant to denote key-value mappings where key names are controlled by the application (i.e. must follow a schema).

Judicious use of struct syntax should help users understand the data layout even before they reach for a Ziggy Schema or some other kind of documentation.

Basic struct syntax looks like this:

.{
  .hello = "world",
  .foo = true,
}

NOTE: like arrays and dicts, structs also allow trailing commas.

Omitting top-level curlies

When a Ziggy document has a top-level value of type struct, the outer curlies can be omitted to reclaim one level of indentation. This syntactical trick helps making Ziggy a more suitable language for config files and Markdown frontmatters.

This is the same as the previous example:

.hello = "world",
.foo = true,

Union literal

Union literals are the container counterpart to enum literals. They have the same structure as enum literals, immediately followed by a value enclosed between parentheses. There can be no space between the identifier and the opening parenthesis.

Similarly to enum literals, union literals are meant to represent one option out of a limited set. Differently from enums, which do not hold a payload, union literals have a single Ziggy value as their payload.

Examples: .unix(631148400), .foo(42), .bar("banana"), .baz({"foo": .bar})

Union literals are especially useful when the Ziggy Documents they appear in are paired with a Ziggy Schema.