Notation designed to help users grok data layouts
Structs vs maps
Ziggy uses different notation for key-value pairs when the keys are controlled by the application (i.e. keys must follow a schema), versus when the user is in control, and thus expected to come up with key names.
Struct unions
Ever had to fight JSON to express a tagged union? Ziggy structs have names that can be used by both humans and tooling to discriminate between union cases.
Tagged literals
Tagged literals help you express things such as @date("2024-01-01")
, @keys("crtl+c")
, or @foo("bar")
.
...and more quality of life features!
Optional top-level curlies, multi-line string literals, trailing commas, comments, underscores in numeric literals, etc.
See an example package.json
vs a (hypotetical) Ziggy version.
{
"name": "ziggy",
"version": "1.0.0",
"license": "MIT",
"dependencies": {
"react": "next",
"leftpad": "^1.0.0"
},
"repository": {
"type": "git",
"url" : "https://github.com"
},
"description":
"# Ziggy\n\nA Data Serializa..."
}
{
.name = "ziggy",
.version = @v("1.0.0"),
.license = @spdx("MIT"),
.dependencies = {
"react": "next",
"leftpad": "^1.0.0",
},
.repository = Git {
// "type" is now the struct name
.url = "https://github.com",
},
.description =
\\# Ziggy
\\
\\A Data Serialization Language.
,
}
A schema language for creating and documenting clear data layouts
Ziggy schemas help you define data layouts that are easy to grasp and validate for correctness. Ziggy schemas can define struct unions, enums and custom string literals.
The Ziggy LSP will be able to use your schema definitions to show diagnostics, contextual help and give autocomplete suggestions to your users.
Other tooling will be able to use schemas to autogenerate compatible type definitions.
The best feature of Ziggy schemas is that they can't define every possible data layout!
root = Package
///A Semantic Versioning version string.
@v = bytes,
///A valid SPDX expression.
@spdx = bytes,
struct Package {
name: bytes,
version: @v,
license: @spdx,
description: bytes,
dependencies: map[bytes],
repository: Git | Npm,
}
struct Git { url: bytes, directory: ?bytes }
struct Npm { name: bytes }
root = Message
/// A UUIDv5 value.
@uuid = bytes,
@action = enum { clear_chat, ban_user },
struct Message {
id: @uuid,
time: int,
payload: Command | Notification,
}
struct Command {
do: @action,
sender: bytes,
roles: [bytes],
///Optional metadata.
extra: ?map[bytes],
}
struct Notification { text: bytes, lvl: int }
Tooling Supremacy
One official CLI tool that solves the most common needs, like auto-formatting, schema validation, format conversion, querying (coming soon) and LSP support for comfortable editing in your favorite text editor or IDE.
$ ziggy help
Usage: ziggy COMMAND [OPTIONS]
Commands:
fmt Format Ziggy files
query, q Query Ziggy files
check Check Ziggy files against a Ziggy schema
convert Convert between JSON, YAML, TOML files and Ziggy
lsp Start the Ziggy LSP
help Show this menu and exit
General Options:
--help, -h Print command specific usage