From GitHub · · 3m
SOML: A Human-Friendly Config Format
SOML simplifies config files with clean syntax, no guessing, and strict rules.
In brief
SOML simplifies config files with clean syntax, no guessing, and strict rules. SOML is a config format that avoids JSON's noise and YAML's ambiguity by using syntax-driven types and block strings. Originally reported by GitHub.
What is SOML
SOML is a config format that is pleasant to write and easy to read.
SOML's Design Principles
The top level needs no braces, keys need no quotes, line breaks replace commas, and comments go almost anywhere.
Type Safety
A value's type comes from its syntax, never from its content, so '123' is a string and 123 is an int.
Real Values
Dates like 2026-09-19, instants like 2026-09-19T14:00:00Z, and durations like 30s are real values, so nobody has to guess the unit of timeout.
No Escaping Needed
Paths and regexes need no escaping, and prose goes in block strings.
One Canonical Form
One canonical form and a shared conformance suite mean every implementation reads your file the same way.
Why SOML
Less noise than JSON, and comments. Keys need no quotes, even with dashes, a line break replaces a comma, and the top level needs no braces.
What You See Is the Type
A string always has quotes, and a value without quotes must be a number, a date, an instant, a duration, or a keyword, or the file has an error.
Strict Where JSON Is Vague
Duplicate keys, lone surrogates, and numbers out of range are errors, not behavior that each parser decides.
Pleasant to Write
Literal strings, so paths and regexes need no escaping, and dedented block strings for prose.
Example Configuration
name: 'api-gateway', port: 8080, timeout: 30s, launch-date: 2027-09-19, windows-path: 'C:\Users\sindre\dev'.
Why Not YAML
SOML keeps what I like about YAML: comments, no braces around the file, no commas at the ends of lines, and keys without quotes.
What SOML Adds
Block comments with /* */, durations such as 30s, dates, instants, a canonical form, and a formatter whose rules are part of the spec.
What SOML Fixes
Values change type without warning, keys are not always strings, indentation changes meaning, block strings add a newline, and large ints lose precision.
Why Not TOML
SOML keeps what TOML gets right: predictable types, literal strings, insignificant indentation, and duplicate keys as errors.
SOML's Advantages
SOML has one syntax for each, one block string style, and one set of type rules, with no implicit tables or dotted keys.
The short version
SOML is a config format that avoids JSON's noise and YAML's ambiguity by using syntax-driven types and block strings.
