Styx

Styx Configuration Language

Styx is a configuration language with schema support, comments, and flexible syntax.

Quick Reference

// Line comment
/// Doc comment (attaches to next entry)

// Schema declaration (optional, enables validation)
@ path/to/schema.styx

// Key-value pairs
name "My Config"
port 8080
enabled true

// Nested objects (newline or comma separated)
server {
    host localhost
    port 8080
}
limits {max 100, timeout 30}

// Sequences
hosts (localhost "127.0.0.1" server.example.com)

// Tags for enums/variants
status @ok
level @warn
error @error{code 500, message "fail"}

// Heredocs for multi-line content
query <<SQL
SELECT * FROM users
WHERE active = true
SQL

Scalars (Values)

Four forms of string values:

Bare scalars: Any characters except {}(),"=@ \t\n\r. Cannot start with @.

Quoted strings: Escapes: \\, \", \n, \r, \t, \0, \u{hex}.

Raw strings: r"..." or r#"..."# (add # to include quotes).

Heredocs:

content <<DELIM
Multi-line text here.
Preserves all whitespace.
DELIM

// With language hint (for syntax highlighting)
code <<CODE,rust
fn main() {
    println!("Hello!");
}
CODE

Objects

Objects use { } with either newline or comma separation:

// Newline separated
server {
    host localhost
    port 8080
}

// Comma separated (single line)
server {host localhost, port 8080}

// Cannot mix separators in same block

Sequences

Sequences use ( ) with whitespace separation:

// Simple sequence
ports (80 443 8080)

// With quoted strings
hosts ("localhost" "example.com")

// Nested sequences
matrix ((1 2 3) (4 5 6))

// Sequence of objects
routes (
    @route{path "/", handler index}
    @route{path "/api", handler api}
)

Tags

Tags start with @ and optionally have a payload:

// Tag with unit payload
status @ok

// Tag with object payload
error @error{code 500, message "Internal error"}

// Tag with sequence payload
point @rgb(255 128 0)

// Tag with string payload
message @warn"Deprecated feature"

// Bare @ is the unit value
nothing @

Common tags: @ok, @err(...), @none, @some(...).

Unit Value

The bare @ is the unit value (like null/none):

optional_field @

Attributes

HTML-style key=value attributes (no space around =):

div id=main class="container" data-count=42

Comments

// Single-line comment

/// Doc comment - attaches to next entry
/// Can span multiple lines
name "documented field"

Schema Declaration

Documents can declare their schema for validation:

// External schema file
@ ./my-schema.styx

// Or inline schema
@ {
    schema {
        @ @object{name @string, port @int}
    }
}

Schema Language

Schema files define expected structure:

meta {
    id https://example.com/my-schema
    version 2026-01-16
    description "My configuration schema"
}

schema {
    // @ defines the document root structure
    @ @object{
        /// Server display name
        name @string
        /// Port number (1-65535)
        port @int{min 1, max 65535}
        /// Enable debug mode
        debug @optional(@bool)
        /// Default timeout in ms
        timeout @default(30000 @int)
    }
}

Type Tags

String Constraints

username @string{minLen 3, maxLen 20}
slug @string{pattern "^[a-z0-9-]+$"}

Named Types

Define reusable types with PascalCase names:

schema {
    @ @object{
        server @Server
        logging @optional(@Logging)
    }

    Server @object{
        host @string
        port @int{min 1, max 65535}
    }

    Logging @object{
        level @enum{debug, info, warn, error}
        output @optional(@string)
    }
}

Enums

Define variants with optional payloads:

schema {
    status @enum{
        ok
        pending
        error @object{message @string, code @int}
    }
}

Usage in document:

status @ok
status @pending
status @error{message "Failed", code 500}

Open Objects

By default objects are closed (unknown keys forbidden). Use @ key for open objects:

// Allow any additional string fields
Labels @object{
    @ @string
}

// Known fields plus extras
Config @object{
    name @string
    @ @string
}

CLI Usage

Files are detected by . or / in the name (or - for stdin). Bare words are subcommands.

# Format and print to stdout
styx config.styx

# Format in place
styx config.styx --in-place

# Validate against declared schema (no output on success)
styx config.styx --validate

# Convert to JSON
styx config.styx --json-out -

# Use different schema
styx config.styx --validate --schema other.schema.styx

# Show parse tree (debugging)
styx tree config.styx

# Start language server
styx lsp

# Generate shell completions
styx completions bash
styx completions zsh
styx completions fish

Common Mistakes

Wrong: Mixing separators in objects

// WRONG - can't mix newlines and commas
server {
    host localhost, port 8080
}

Right: Pick one separator style per block.

Wrong: Space around = in attributes

// WRONG
div id = main

Right: No spaces: div id=main

Wrong: Using null as a keyword

// WRONG - null is just a bare scalar
value null

Right: Use @ or @none for unit/absence:

value @none
nothing @

Wrong: Comma in sequences

// WRONG - sequences are whitespace-separated
ports (80, 443, 8080)

Right: Whitespace only:

ports (80 443 8080)

File Extensions

• .styx - Styx data files
• .schema.styx - Styx schema files (convention)

Editor Support

• Zed: Built-in support via tree-sitter grammar
• VS Code: Extension available
• LSP: Run styx lsp for any editor with LSP support

Converted and distributed by TomeVault — claim your Tome and manage your conversions.