SOML for Rust: a strict reader, serde support, and a lossless syntax tree
Note
SOML is a config format for humans. The format is a draft.
- Checks every rule in the spec: duplicate keys, the int64 range, date, instant, and duration ranges, raw control characters, the nesting limit, and more
- Errors give a line and a column, also when a valid document does not fit your type
- Writes members in field order, or in canonical form, where the same value always gives the same bytes
- A lossless syntax tree that keeps comments and the author's spelling when you change a document
- A formatter that changes layout and nothing else
Spanned<T>for the position of any value, and error messages with a code frame- Reads and writes
std::time::Duration, and readsjiffandchronoinstants and durations, with optional features for native dates, instants, and durations - Passes the language-neutral conformance suite of the spec
- No unsafe code, and two required dependencies:
serde_coreandzmij
cargo add soml-langThe package is soml-lang, and the library is soml.
use serde::Deserialize;
#[derive(Deserialize)]
#[serde(rename_all = "kebab-case")]
struct Config {
name: String,
replicas: u32,
timeout: std::time::Duration,
deployed_at: soml::Instant,
launch_date: soml::Date,
labels: Vec<String>,
postgres: Postgres,
}
#[derive(Deserialize)]
struct Postgres {
host: String,
port: u16,
}
fn main() -> Result<(), soml::Error> {
let config: Config = soml::from_str("
/* The edge service. */
name: 'api-gateway'
replicas: 3
timeout: 1m30s # Including retries.
deployed-at: 2026-09-19T14:00:00Z
launch-date: 2027-09-19
labels: ['prod', 'eu-west']
postgres: {host: 'db.internal', port: 5432}
")?;
assert_eq!(config.postgres.port, 5432);
assert_eq!(config.timeout.as_secs(), 90);
Ok(())
}Indentation never matters in SOML, so a document can be indented like the code around it.
#[derive(serde::Serialize)]
struct Server {
port: u16,
hosts: Vec<&'static str>,
}
fn main() -> Result<(), soml::Error> {
let server = Server { port: 8080, hosts: vec!["a", "b"] };
assert_eq!(soml::to_string(&server)?, "port: 8080\nhosts: [\n\t'a'\n\t'b'\n]\n");
assert_eq!(soml::to_string_canonical(&server)?, "hosts: [\n\t'a'\n\t'b'\n]\nport: 8080\n");
Ok(())
}soml::to_string writes one member or item per line, with tab indentation and no commas. Members keep the order of the value: a struct's fields in declaration order, and a map's entries in iteration order.
soml::to_string_canonical also sorts members by key, so the same value always gives the same bytes. Use it to hash, sign, or compare documents, and to write a HashMap, whose order changes on each run.
fn main() -> Result<(), soml::Error> {
let value: soml::Value = "port: 8080\nhosts: ['a', 'b']".parse()?;
assert_eq!(value.get("port").and_then(soml::Value::as_i64), Some(8080));
assert_eq!(value.get("hosts").and_then(|hosts| hosts.get(1)).and_then(soml::Value::as_str), Some("b"));
Ok(())
}An int and a float are different types, so as_f64() does not convert an int. A soml::Value keeps object members sorted by key, because member order is not part of a value. Use soml::Document to keep the written order.
fn main() -> Result<(), soml::Error> {
let mut document: soml::Document = "/* The edge service. */\nport: 0x1F90 # The default.\nserver: {host: 'a'}\n".parse()?;
document.set(["port"], 8080)?;
document.set(["server", "port"], 443)?;
document.set(["replicas"], 3)?;
assert_eq!(document.to_string(), "/* The edge service. */\nport: 8080 # The default.\nserver: {host: 'a', port: 443}\nreplicas: 3\n");
Ok(())
}An unchanged document prints the exact text it was parsed from. A changed one keeps the comments, blank lines, indentation, member order, and spelling of everything outside the change. Changes follow the spec's editing rules: a new member goes after the last member of its object, a removed member or item takes its own comments with it, and a formatted document stays formatted. remove returns whether it removed something, and removing a missing value is not an error. Every parsed node also has its position, for linters and editors.
fn main() -> Result<(), soml::Error> {
assert_eq!(soml::format("a: {b: 1, c: [2,3]} # Note.")?, "a: {b: 1, c: [2, 3]} # Note.\n");
assert_eq!(soml::format("a: {\nb: 1, c: [2,3]}")?, "a: {\n\tb: 1\n\tc: [2, 3]\n}\n");
Ok(())
}The formatter changes layout and nothing else: one tab per level, one member or item per line, no commas, at most one blank line in a row, and no trailing whitespace. An object or array whose brackets are on one line stays on one line, with a comma and a space between its members or items. Put a line break anywhere inside it to expand it. Comments, member order, block strings, and the spelling of every value stay as they are. Formatting is idempotent. The spec's formatter rules are normative, so every conforming formatter gives the same text. The tree module lists them.
#[derive(serde::Deserialize, Debug)]
struct Server {
port: u16,
}
let text = "host: 'a'\nport: 70000";
let error = soml::from_str::<Server>(text).unwrap_err();
assert_eq!(error.to_string(), "invalid value: integer `70000`, expected u16 at line 2, column 7");
assert_eq!(error.kind(), soml::ErrorKind::Data);
// For a terminal:
assert_eq!(error.code_frame(text).unwrap(), " 1 | host: 'a'\n> 2 | port: 70000\n | ^");An error has a kind: Syntax for text that is not valid SOML, Data for a valid document that does not fit your type or a path that does not fit a Document, Write for a value that SOML cannot represent or a Document::set that would make the document invalid, and Io for reading and writing.
Error messages and code frames replace terminal controls and bidirectional controls with �. Tabs stay, and messages other than syntax errors may contain line breaks.
#[derive(serde::Deserialize)]
struct Server {
port: soml::Spanned<u16>,
}
fn main() -> Result<(), soml::Error> {
let text = "port: 0";
let server: Server = soml::from_str(text)?;
if *server.port == 0 {
let start = server.port.span().unwrap().start;
let error = soml::Error::with_position("Port 0 is reserved", text, start);
assert_eq!(error.to_string(), "Port 0 is reserved at line 1, column 7");
}
Ok(())
}Spanned<T> reads any value with its byte range, so your own checks after reading can point at the right place. The span is None for a value from from_value or another format, for a map key, and inside #[serde(flatten)], untagged enums, and internally tagged enums (see Limitations).
let value = soml::soml!({
name: "api",
"deployed-at": soml::Instant::from_unix(1_789_826_400, 0),
replicas: 3,
tags: ["prod", "eu-west"],
owner: null,
});
assert_eq!(value.get("replicas").and_then(soml::Value::as_i64), Some(3));A key is an identifier or a string literal, and a value is null, {…}, […], or any expression that converts to a Value. A key that is there twice panics.
soml::from_reader, soml::to_writer, and soml::to_writer_canonical read from an io::Read and write to an io::Write. A document is only valid as a whole, so from_reader reads everything first.
| Rust | SOML | Notes |
|---|---|---|
bool |
bool | |
i8…i128, u8…u128 |
int | Range-checked both ways. An int is 64-bit, so a larger value cannot be written. |
f32, f64 |
float | An int reads into a float only when it converts exactly. A float never reads into an int. An f32 round-trips with its own shortest digits, so 0.1f32 is 0.1. A float too large for the type reads as infinity, as in serde_json. NaN cannot be written. |
String, &str, char |
string | A &str borrows from the input when the string is '...' or "..." without escapes. Use String or Cow<str> when a document may hold other strings. |
Option<T> |
null or the value |
A missing field reads as None. |
(), a unit struct |
null |
|
Vec<T>, a tuple |
array | |
a struct, HashMap, BTreeMap |
object | A map key can be a string, a char, a bool, an integer (404: 'x'), or a unit enum variant. |
| an enum | string, or a one-member object | A unit variant is a string. The others are {variant: value}. |
soml::Date |
date | Validated proleptic Gregorian year, month, and day, years 0001 through 9999, without a timezone. |
soml::Instant |
instant | Exact, with nanoseconds. |
soml::Duration, std::time::Duration |
duration | A negative duration does not fit a std::time::Duration. serde has no duration type, so a std::time::Duration is recognized by its shape: a struct named Duration with the fields secs and nanos. Your own struct with that shape is also written as a duration. |
soml::Value |
any value |
Field names come from serde, so use #[serde(rename_all = "kebab-case")] for the usual SOML key style.
Adjacently tagged enums (#[serde(tag = "type", content = "value")]) keep native SOML types and spans in either field order, including when unknown fields are ignored.
A soml::Date preserves calendar components exactly: soml::Date::new(1582, 10, 10) validates them, and "2027-09-19".parse::<soml::Date>() requires exact ASCII syntax. It stays distinct from strings and instants in the native value tree and typed decoding. JSON sees its canonical string.
jiff::Timestamp, jiff::SignedDuration, chrono::DateTime<Utc>, and humantime fields read SOML instants and durations, because they ask for text, and an instant or a duration gives its canonical text. humantime reads only instants from 1970 on. As a result, a String field also accepts an instant or a duration. chrono::TimeDelta does not ask for text, so it needs soml::chrono::time_delta.
For chrono::NaiveDate and jiff::civil::Date, use the date modules below for native reading and writing. They convert Gregorian components directly and reject years outside SOML’s range. Their option modules handle nullable dates. A String field rejects a native date.
Those types write themselves as strings, such as '2026-09-19T14:00:00Z'. To write native instants and durations, use soml::Instant and soml::Duration, or turn on a feature and use its module with #[serde(with)]:
cargo add soml-lang --features jiff#[derive(serde::Serialize, serde::Deserialize)]
struct Deploy {
#[serde(with = "soml::jiff::timestamp")]
at: jiff::Timestamp,
#[serde(with = "soml::jiff::signed_duration::option", default)]
took: Option<jiff::SignedDuration>,
}| Feature | Modules | Conversions |
|---|---|---|
jiff |
soml::jiff::date, soml::jiff::timestamp, soml::jiff::signed_duration |
civil::Date, Timestamp, and SignedDuration to and from native SOML values |
chrono |
soml::chrono::naive_date, soml::chrono::date_time, soml::chrono::time_delta |
NaiveDate, DateTime<Utc>, and TimeDelta to and from native SOML values |
Each module has an option submodule for an Option, which needs #[serde(default)] to read a missing member as None. The modules read only native values, not strings (except through serde's buffer, see Limitations), and a value outside SOML's range is an error. jiff's timestamps end at 9999-12-30T22:00:00.999999999Z, about a day before SOML's.
Documents follow the SOML specification.
- File extension:
.soml - Encoding: UTF-8 without a byte order mark, with LF line endings
- Media type:
application/soml - Uniform type identifier:
com.sindresorhus.soml - Nesting limit: 100 levels, counting every object and array, including the document's own
cargo run --release --manifest-path bench/Cargo.toml -- --instructionsMillions of instructions to read, write, and format the spec's benchmark fixtures on an Apple M4 Pro with Rust 1.99.0, taking the median of three runs. Each fixture holds the same data in SOML, JSON, and TOML, and the sizes are of the SOML files. service and earthquakes are read into a struct and written from it, with JSON and TOML durations and JSON instants as jiff types. platform has hundreds of settings, so it is read into each library's value type (soml::Value, serde_json::Value, and toml::Table).
| soml-lang | serde_json | toml | |
|---|---|---|---|
| Read service (3 KB) | 0.13 M | 0.073 M | 0.36 M |
| Read platform (35 KB) | 1.4 M | 0.88 M | 3.2 M |
| Read earthquakes (733 KB) | 34 M | 20 M | 99 M |
| Write service | 0.066 M | 0.063 M | 0.30 M |
| Write platform | 0.46 M | 0.41 M | 2.2 M |
| Write earthquakes | 16 M | 16 M | 82 M |
| Format service | 0.51 M | ||
| Format platform | 3.9 M | ||
| Format earthquakes | 140 M |
soml::Document reads each fixture in 51% to 62% of the instructions of toml_edit::DocumentMut. Instruction counts are used instead of times because they stay stable on a busy machine. --instructions works only on macOS. Without it, the benchmark prints times.
Reading and writing check every rule of the spec, such as duplicate keys in a map, which serde_json does not check.
#[serde(flatten)], untagged enums, and internally tagged enums read values through serde's buffer, which has no date, instant, or duration type and no positions. There, a date, instant, or duration is its text: asoml::Valueholds it as a string,soml::Date,soml::Instant, andsoml::Durationstill read it, and astd::time::Durationcannot be read. An int reads into a float even when the float does not hold it exactly. Anf32is read through anf64, as in serde_json, so 2 of the 4.3 billionf32values read back one step away. ASpannedvalue has no span.- A document with an error, or one that does not fit the type, is read a second time to find the first error, so a
Deserializeimpl with side effects, such as logging, runs twice for it. Likewise, a value thatto_stringcannot write, or whoseSerializeimpl catches an error and goes on, is serialized a second time. - The
soml!macro reads one item or member at a time, so a literal with more than about 120 of them at one level reaches the compiler's recursion limit, as withjson!.