Ziggy Schema File Structure

File Extension

A Ziggy Schema file has a .ziggy-schema file extension.

File structure

Here’s an example Ziggy Schema:

$ = Foo

struct Foo {
   /// Fields can have doc comments.
   foo: Bar,
   bar: Baz,

   /// Type definitions too can have doc comments.
   struct Bar {
      baz: any,
   }
}

union Baz {
   qux: int,
   qax: bytes,
   qix,
}

A Ziggy schema is comprised of two main sections:

• the $ definition
• a series of custom type definitions

The $ definition

The first line of a Ziggy Schema defines the type of the top-level value of matching Ziggy Documents.

In Ziggy lingo, $ represents the top-level value (a concept shared with Scripty and other tooling in the Zine ecosystem), to which we assign a type expression.

The $ definition accepts a type expression because Ziggy Documents are allowed to have non-struct values at the top level. For comparison, while this is technically true also for JSON, in practice many JSON parsers expect the top-level value to be a JSON object, something that we want to avoid for Ziggy Documents.

For example the following are all valid Ziggy Schemas:

/// This matches the following Ziggy Document:
/// `"banana"`
$ = bytes

/// This matches the following Ziggy Document:
/// `[1,2,3]`
$ = []int

/// This matches the following Ziggy Document:
/// `{"foo": null, "bar": [true]}`
$ = {:}?[]bool

Type definitions

The main section of a Ziggy Schema is a list of type definitions.

Ziggy Schemas allow you to specify struct and union types. See the Custom Types page for more information.

Schema - Document pairing

This is how Ziggy tooling decides which Ziggy Schema should be used for a given Ziggy Document.

1. Same name

When a Ziggy Document and a Ziggy Schema share the same name and are located in the same directory. You can also optionally add a dot in front of the Ziggy Schema file to hide it. If both alternatives are present, the dotless (i.e. visible) file will take precedence.

Examples:

path/to/foo.ziggy -> path/to/foo.ziggy-schema
path/to/foo.ziggy -> path/to/.foo.ziggy-schema

2. Dot schema

When a directory contains a .ziggy-schema file, it will be used for all Ziggy Documents in the entire directory subtree that do not have a Schema with the same name (as explained above).

For example, given this directory structure:

foo
├── .ziggy-schema
├── bar.ziggy
├── baz.ziggy
├── baz.ziggy-schema
├── fruits
│   ├── apple.ziggy
│   └── banana.ziggy
└── qux
    ├── .ziggy-schema
    ├── qax.ziggy
    └── qix.ziggy

Results in the following pairings:

foo/bar.ziggy           -> foo/.ziggy-schema 
foo/baz.ziggy           -> foo/baz.ziggy-schema 
foo/fruits/apple.ziggy  -> foo/.ziggy-schema
foo/fruits/banana.ziggy -> foo/.ziggy-schema
foo/qux/qax.ziggy       -> foo/qux/.ziggy-schema 
foo/qux/qix.ziggy       -> foo/qux/.ziggy-schema 

SuperMD Frontmatter

Ziggy is the frontmatter language of SuperMD, the content language of Zine. To provide users with code intelligence in their editor, the Ziggy LSP can be run on SuperMD files.

When analyzing a SuperMD file, the Ziggy LSP will apply the same rules as above, but on the full document name, inclusive of the .smd extension.

Examples (in order of decreasing priority):

path/to/foo.smd -> path/to/foo.smd.ziggy-schema
path/to/foo.smd -> path/to/.foo.smd.ziggy-schema
path/to/foo.smd -> path/.smd.ziggy-schema

Note how even the ‘dot schema’ approach still preserves the file extension. This is done to prevent SuperMD-specific schemas from polluting the Ziggy Document schema space.