hocon-parser — HOCON Parser for Rust

A Lightbend HOCON specification parser for Rust. Hand-written lexer, recursive-descent parser, and a typed Config API with optional Serde integration. See Spec Compliance for the current conformance rate.

日本語

Library stance — This library is a HOCON config loader. Its purpose is reading .hocon config files and providing typed access via the Config API (get_string, get_i64, get_f64, get_bool, get_duration, get_bytes). It is not a low-level parser API; internal types like ScalarValue may change between minor versions.

Cross-language conformance — This implementation is tested against shared expected-JSON fixtures from o3co/xx.hocon alongside ts.hocon and go.hocon, ensuring all three implementations meet the same Lightbend HOCON specification.

Quick Start

1. Install

cargo add hocon-parser

To enable Serde support:

cargo add hocon-parser --features serde

2. Use

use hocon;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = hocon::parse(r#"
        server {
            host = "localhost"
            port = 8080
        }
        database {
            url = "jdbc:postgresql://localhost/mydb"
            pool-size = 10
        }
    "#)?;

    let host = config.get_string("server.host")?;
    let port = config.get_i64("server.port")?;

    println!("Server: {}:{}", host, port);
    Ok(())
}

Why HOCON?

	`.env`	JSON	YAML	HOCON
Comments	No	No	Yes	Yes
Nesting	No	Yes	Yes	Yes
References / Substitution	No	No	No	Yes (`${var}`)
File inclusion	No	No	No	Yes (`include`)
Object merging	No	No	Anchors (fragile)	Yes (deep merge)
Optional values	No	No	No	Yes (`${?var}`)
Trailing commas	N/A	No	N/A	Yes
Unquoted strings	Yes	No	Yes	Yes

HOCON isn't just a serialization format — it's a config-injection language. JSON, YAML, and TOML describe data structures and leave file layering, environment variables, and reference resolution to your code (Pydantic, Serde, Zod, etc.). HOCON bakes those into the spec itself: by the time your program reads the config, fallback files are merged and ${VAR} references resolved into a single composed object. Conditional branching from "is this value present in this layer?" disappears at the format boundary.

On top of that, HOCON combines the readability of YAML with the structure of JSON — making it a strong fit for anything beyond flat key-value config.

Features

Complete HOCON syntax: objects, arrays, comments, multi-line strings, unquoted strings
Substitutions (${foo}, ${?foo}) with cycle detection
include directives (file, classpath, URL) with relative path resolution
Object merging and array concatenation per spec
String, array, and object value concatenation
Duration and byte-size parsing (10 seconds, 512 MB)
Environment variable substitution (${HOME})
Dot-separated path expressions (server.host)
Fallback configuration merging (with_fallback)
Deferred resolution lifecycle: parse_string_with_options → with_fallback → resolve() per Lightbend parseString / withFallback / resolve() API (E12, v1.4.0)
Optional Serde deserialization support
Passes Lightbend equivalence tests (equiv01 through equiv05)

API Reference

Parsing

// Parse a HOCON string
let config = hocon::parse(input)?;

// Parse a HOCON file (resolves include directives relative to file location)
let config = hocon::parse_file("application.conf")?;

// Parse with custom environment variables
use std::collections::HashMap;
let env: HashMap<String, String> = HashMap::new();
let config = hocon::parse_with_env(input, &env)?;
let config = hocon::parse_file_with_env("application.conf", &env)?;

Typed Getters

All typed getters return Result<T, ConfigError>. Paths use dot notation.

let host: String    = config.get_string("server.host")?;
let port: i64       = config.get_i64("server.port")?;
let rate: f64       = config.get_f64("rate")?;
let debug: bool     = config.get_bool("debug")?;        // also accepts "yes"/"no", "on"/"off"
let sub: Config     = config.get_config("database")?;    // sub-object as Config
let items: Vec<HoconValue> = config.get_list("items")?;

Option Variants

Return Option<T> instead of Result -- return None for missing keys or type mismatches.

let host: Option<String> = config.get_string_option("server.host");
let port: Option<i64>    = config.get_i64_option("server.port");
let rate: Option<f64>    = config.get_f64_option("rate");
let debug: Option<bool>  = config.get_bool_option("debug");

Duration and Byte-Size Values

use std::time::Duration;

// Supports: ns, us, ms, s/seconds, m/minutes, h/hours, d/days
let timeout: Duration = config.get_duration("server.timeout")?;

// Supports: B, KB, KiB, MB, MiB, GB, GiB, TB, TiB (and long forms)
let max_size: i64 = config.get_bytes("upload.max-size")?;

Inspection

let exists: bool     = config.has("server.host");
let keys: Vec<&str>  = config.keys();           // top-level keys in insertion order
let raw: Option<&HoconValue> = config.get("server.host");

Fallback Merge

// Receiver wins; fallback fills missing keys. Objects are deep-merged.
let merged = app_config.with_fallback(&defaults);

Deferred Resolution (v1.4.0)

Parse without resolving, add a runtime fallback, then resolve in a single pass:

use hocon::{parse_string_with_options, ParseOptions, ResolveOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cfg = parse_string_with_options(
        r#"version = ${shortversion}-${CI_RUN_NUMBER}
           variables { shortversion = "1.2.3" }"#,
        ParseOptions::defaults().with_resolve_substitutions(false),
    )?;
    assert!(!cfg.is_resolved());

    let runtime = hocon::empty(None); // or from_map with runtime values
    let vars = cfg.get_config("variables")?;
    let resolved = cfg
        .with_fallback(&runtime)
        .with_fallback(&vars)
        .resolve(ResolveOptions::defaults())?;

    println!("{}", resolved.get_string("version")?); // e.g. "1.2.3-42"
    Ok(())
}

You can also use resolve_with to supply a resolved source for substitution lookup without merging its keys into the result:

let resolved = cfg.resolve_with(&source_config, ResolveOptions::defaults())?;

Serde Deserialization

Requires the serde feature.

use serde::Deserialize;

#[derive(Deserialize)]
struct ServerConfig {
    host: String,
    port: u16,
}

let config = hocon::parse(input)?;
let server: ServerConfig = config
    .get_config("server")?
    .deserialize()?;

Error Types

Type	When
`ParseError`	Syntax errors during lexing/parsing (includes line and column)
`ResolveError`	Substitution failures, cyclic references, missing required variables
`ConfigError`	Missing keys or type mismatches during value access
`ConfigError` (use `.is_not_resolved()` to detect "value not yet resolved")	Getter called on a path containing an unresolved substitution placeholder (v1.4.0)
`DeserializeError`	Serde deserialization failures (with `serde` feature)

HOCON Examples

# Comments start with // or #
server {
    host = "0.0.0.0"
    port = 8080
    timeout = 30 seconds
    max-upload = 512 MB
}

# Substitutions
app {
    name = "my-app"
    title = "Welcome to "${app.name}
}

# Array concatenation
base-tags = ["production"]
tags = ${base-tags} ["v2"]

# Include other files
include "defaults.conf"

# Unquoted strings
path = /usr/local/bin

# Multi-line strings
description = """
    This is a multi-line
    string value.
"""

# Object merging
defaults { color = "blue", size = 10 }
defaults { size = 20 }  # merges: color stays, size updated

Performance

Measured with Criterion. Each iteration includes parsing and a get_string lookup. Run cargo bench to reproduce.

Scenario	ops/sec	Time per op
Small config (10 keys)	~62,000	~16 µs
Medium config (100 keys)	~19,000	~52 µs
Large config (1,000 keys)	~2,400	~408 µs
10 substitutions	~37,000	~27 µs
50 substitutions	~12,000	~86 µs
100 substitutions	~6,400	~156 µs
Depth 5 nesting	~58,000	~17 µs
Depth 10 nesting	~50,000	~20 µs
Depth 20 nesting	~39,000	~26 µs

For typical application configs (loaded once at startup), the parsing cost is negligible — even a 1,000-key config parses in under 0.5 ms.

Comparison

✅ Full support / ⚠️ Partial / ❌ Not supported

HOCON Implementation

Feature	rs.hocon	hocon-rs
Substitutions (`${path}`)	✅	✅
Optional substitutions (`${?path}`)	✅	✅
Include	✅	✅
`include required(file(...))`	✅	❌
Object/Array concatenation	✅	✅
Type coercion	✅	⚠️
Duration parsing	✅	✅
Byte size parsing	✅	✅
`+=` append	✅	❌
Serde deserialization	✅	✅
Env variable fallback	✅	❌
Circular include detection	✅	❌

Config Framework

	rs.hocon	config-rs
Formats
HOCON	✅	❌
JSON	✅	✅
YAML	❌	✅
TOML	❌	✅
Env vars	✅ (fallback)	✅
.properties	✅ (via include)	❌
Features
Substitutions	✅	❌
File includes	✅	❌
Type coercion	✅	✅
Serde support	✅	✅
Watch/reload	❌	❌
Layered config	❌	✅

Spec Compliance

Conformance against the Lightbend HOCON specification is tracked at item granularity in docs/spec-compliance.md. The table below is a snapshot as of 2026-05-13; see xx.hocon/docs/compliance-matrix.md for live cross-impl values.

Metric	Status
Spec total (incl. out-of-scope)	75.6%
In-scope only	84.0%
Lightbend `equiv01`–`equiv05` suite	5/5 passing

Stricter than Lightbend

S8.6 leading-hyphen rejection (Unreleased): a = -foo, a = -bar, a = - etc. now raise a lex error per HOCON.md L270–276, where Lightbend silently falls back to unquoted strings. The same rule applies to substitution paths (${-foo}) and dotted key segments (a.-foo = 1). Mitigation: quote the value (a = "-foo"). See CHANGELOG and docs/spec-compliance.md §S8.6.

Minimum Supported Rust Version

The MSRV is 1.82.

Related Projects

Project	Language	Registry	Description
ts.hocon	TypeScript	npm	HOCON parser for TypeScript/Node.js
go.hocon	Go	pkg.go.dev	HOCON parser for Go
hocon2	Go	pkg.go.dev	HOCON → JSON/YAML/TOML/Properties CLI

The three parser implementations (ts.hocon, rs.hocon, go.hocon) are all tracked against the same Lightbend HOCON spec — see the cross-impl roll-up for per-impl conformance rates.

Best Practices

Config Structure

Split by domain: Separate configuration into logical units (database.conf, server.conf, logging.conf)
Use include for composition: Compose a full config from domain-specific files
Avoid logic in config: HOCON is for declarative data, not conditionals or computation

Environment Variables

Minimize ${ENV} usage: Prefer ${?ENV} (optional) with sensible defaults defined in the config itself
Never require env vars for local development: Defaults should work out of the box
Document required env vars: List them in your project's README or a .env.example

Dev / Prod Separation

config/
├── application.conf    # shared defaults
├── dev.conf            # include "application.conf" + dev overrides
└── prod.conf           # include "application.conf" + prod overrides

Validation

Always validate config at application startup, not at point-of-use
Use schema validation (Zod for TypeScript, struct unmarshaling for Go, Serde for Rust) to catch errors early

use serde::Deserialize;

#[derive(Deserialize)]
struct ServerConfig {
    host: String,
    port: u16,
}

#[derive(Deserialize)]
struct AppConfig {
    server: ServerConfig,
    debug: bool,
}

// requires the `serde` feature
let cfg: AppConfig = config.deserialize()?; // fails fast on startup

Known Limitations

include url(...) is not supported. Fetching remote configuration is outside the scope of this parser. Use your application's HTTP client to fetch the content, then pass it to parse().
include classpath(...) is not supported. This is a JVM-specific include form with no equivalent outside Java runtimes.
No watch/reload — the library parses config at load time. For live-reloading, call parse() / parse_file() again on change.
No streaming parser — the entire input is loaded into memory.
.properties include — supports basic key=value syntax. Does not support multiline values (backslash continuation), unicode escapes, or key escaping from the full Java .properties specification.

For full API documentation, see docs.rs (available after crate publication).

Security Considerations

When parsing untrusted HOCON input, be aware of:

Path traversal in includes: include "../../../etc/passwd" will resolve relative to base_dir. Validate include paths if parsing untrusted input.
Input size: The parser has no built-in input size limit. For untrusted input, validate size before calling parse().

License

Licensed under the Apache License, Version 2.0.

Attribution

Designed and built end-to-end with Claude Code. Reviewed by GitHub Copilot and OpenAI Codex.

Name		Name	Last commit message	Last commit date
Latest commit History 154 Commits
.github		.github
benches		benches
docs		docs
examples		examples
src		src
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
Makefile		Makefile
README.ja.md		README.ja.md
README.md		README.md
SECURITY.md		SECURITY.md
codecov.yml		codecov.yml
release.toml		release.toml

Folders and files

Latest commit

History

Repository files navigation

hocon-parser — HOCON Parser for Rust

Quick Start

1. Install

2. Use

Why HOCON?

Features

API Reference

Parsing

Typed Getters

Option Variants

Duration and Byte-Size Values

Inspection

Fallback Merge

Deferred Resolution (v1.4.0)

Serde Deserialization

Error Types

HOCON Examples

Performance

Comparison

HOCON Implementation

Config Framework

Spec Compliance

Stricter than Lightbend

Minimum Supported Rust Version

Related Projects

Best Practices

Config Structure

Environment Variables

Dev / Prod Separation

Validation

Known Limitations

Security Considerations

License

Attribution

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 11

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages