Zillowe Docs - Syntax Reference

This is a complete reference for the Zoko format syntax.

Basic Structure

A Zoko file consists of key-value pairs:

key: "value",
another_key: 42,
nested: {
  inner_key: "inner_value",
},

Value Types

Strings

Zoko supports three types of strings:

Double-Quoted Strings

message: "Hello, World!",

Double-quoted strings support escape sequences like \n, \t, \\, etc.

Single-Quoted Strings

message: 'Hello, World!',

Single-quoted strings are literal and don't process escape sequences.

Multi-Line Strings

message: `This is a
multi-line string
that preserves formatting`,

Multi-line strings preserve the exact formatting, including newlines.

Multi-line strings automatically strip common leading whitespace, making them ideal for indented text blocks. They also support environment variable substitution.

Numbers

Zoko now supports distinct numeric types for precise data representation:

Integers

count: 42,
negative: -10,
large: 1000000,

Floats

price: 3.14,
scientific: 1.5e10,
negative_float: -0.5,

Decimals

price: decimal("19.99"),
precise: decimal("0.00000001"),

Decimals use the decimal("...") function-call syntax for high-precision decimal arithmetic, avoiding floating-point precision issues.

Temporal Types

Dates

release_date: date("2024-06-21"),
birthday: date("1990-01-15"),

Times

meeting_time: time("14:30:00"),
alarm: time("08:00:00"),

Durations

timeout: duration("30s"),
retry_delay: duration("5m"),
long_timeout: duration("2h"),

Durations support hours (h), minutes (m), and seconds (s) suffixes.

Binary Data

data: binary("SGVsbG8gV29ybGQ="),
signature: binary("dGVzdHNpZ25hdHVyZQ=="),

Binary data is encoded using base64 encoding.

Booleans

is_active: true,
is_debug: false,

Null

optional_value: null,

Arrays

// Simple array
tags: ["production", "api"],

// Array with objects
servers: [
  {host: "server1", port: 8080},
  {host: "server2", port: 8080},
],

// Nested arrays
matrix: [[1, 2], [3, 4]],

Objects (Maps)

// Simple object
config: {
  debug: true,
  timeout: 30,
},

// Nested objects
database: {
  primary: {
    host: "localhost",
    port: 5432,
  },
  replica: {
    host: "replica.local",
    port: 5432,
  },
},

Comments

Single-Line Comments

// This is a comment
key: "value", // Inline comment

Multi-Line Comments

/*
  This is a multi-line comment
  that can span multiple lines
*/
key: "value",

Identifiers

Keys and identifiers can contain:

Alphanumeric characters
Hyphens (-)
Underscores (_)
At signs (@)
Forward slashes (/)
Dots (.)

@package/name: "value",
my-key: "value",
my_key: "value",

Trailing Commas

Trailing commas are allowed everywhere:

objects: {
  key1: "value1",
  key2: "value2", // Trailing comma is OK
},
arrays: [
  "item1",
  "item2", // Trailing comma is OK
],

Whitespace

Zoko is flexible with whitespace:

Leading/trailing whitespace is ignored
Newlines can be used freely
Indentation is not enforced but recommended for readability

name: "value",
// These are all equivalent:
map: {id: "value", id2: "value2"},

map: {
  id: "value",
  id2: "value2",
},

Complete Example

// Package metadata
name: "@Main/Hello",
channel: "main",
branch: "Production",
status: "Release",
version: "1.0.0",
description: "Hello package for Zoil",

// Tags and metadata
tags: ["Hello", "Zoil", "production"],
website: "https://hello.nel.co",

// Dependencies with complex structures
dependencies: [
  {name: "Hola", version: "1.0.2"},
  {
    name: "@German/Hallo",
    channel: "main",
    version: "latest",
  },
],

/* Configuration block
   with detailed comments */
config: {
  debug: false,
  timeout: 30,
  retries: 3,
  servers: [
    {host: "primary.example.com", port: 8080},
    {host: "backup.example.com", port: 8080},
  ],
},

JSON Compatibility

Zoko is designed to be compatible with JSON structures. Any valid JSON object structure can be represented in Zoko (with additional features like comments and trailing commas).

Conversion Example

Zoko:

name: "value",
number: 42,
nested: {
  key: "value",
},

JSON:

{
  "entries": {
    "name": "value",
    "number": 42,
    "nested": {
      "key": "value"
    }
  }
}

Environment Variables

Multi-line strings support environment variable substitution using the ${VAR} syntax:

database_url: `${DATABASE_URL}`,
api_endpoint: `${API_ENDPOINT:-https://api.example.com}`,

Use ${VAR:-default} syntax to provide fallback values if the environment variable is not set.

File Includes

Split large configuration files into smaller, reusable modules:

// Include common configuration
@include("common.zo"),
@include("database.zo"),

// Override or add specific settings
app_name: "MyApp",

File paths are resolved relative to the current file's directory. Use absolute paths or careful relative path planning.

File includes are perfect for: - Shared configuration across environments - Modular configuration organization - Reusable component definitions

Type System

Zoko supports the following data types:

Type	Example	Description
String	`"hello"`, `'world'`, `multi`	Text data
Integer	`42`, `-10`	Whole numbers
Float	`3.14`, `1.5e10`	Floating-point numbers
Decimal	`decimal("19.99")`	High-precision decimals
Boolean	`true`, `false`	True/false values
Null	`null`	Absence of value
Date	`date("2024-06-21")`	Calendar dates
Time	`time("14:30:00")`	Times of day
Duration	`duration("30s")`	Time periods
Binary	`binary("SGVsbG8=")`	Encoded binary data
Array	`[1, 2, 3]`	Ordered list of values
Object	`{key: "value"}`	Key-value mappings

Escaping Rules

In double-quoted strings: Use \ for escapes (\n, \t, \", \\)
In single-quoted strings: No escaping (literal strings)
In multi-line strings: No escaping, preserves formatting exactly

Use single-quoted strings for Windows paths to avoid backslash escaping issues.

Syntax Errors

Common syntax errors to avoid:

Invalid numbers: version: 1.0.0 should be version: "1.0.0"
Unbalanced brackets: Always match {}, [], "", ''
Missing commas: Items in arrays/objects must be separated by commas
Invalid characters in identifiers: Stick to alphanumeric, -, _, @, /, .

Syntax Reference