diegosouzapw HUML (Human-oriented Markup Language)
HUML is a strict, unambiguous serialization language similar to YAML but without YAML's quirks and gotchas. It's designed for configuration files and data serialization where human readability matters.
Core Syntax Rules
Indentation
- Strictly 2 spaces per nesting level (tabs not allowed)
- No trailing spaces (except in multiline strings)
Keys and Values
- Single colon
:for scalar values (strings, numbers, booleans, null) - Double colon
::for vectors (lists and dicts) - Single space required after
:and::
name: "MyApp" # scalar - single colon
settings:: # vector - double colon
debug: true
Strings
- Must be double-quoted (no barewords like YAML)
- Escape
\and"with backslash - Multi-line strings use triple quotes
"""
simple: "hello world"
escaped: "path\\to\\file"
multiline: """
Line one
Line two
"""
Numbers
integer: 42
float: 3.14
scientific: 1.5e-3
hex: 0x1A
binary: 0b1010
special: inf, -inf, nan
Booleans and Null
enabled: true
disabled: false
empty: null
Lists
# Inline
tags:: "web", "api", "v2"
# Multiline
items::
- "first"
- "second"
# Empty
empty:: []
Dicts
# Inline (scalars only)
point:: x: 1, y: 2
# Multiline (supports nesting)
database::
host: "localhost"
port: 5432
# Empty
empty:: {}
Comments
# Comment (space after # required)
key: "value" # inline comment
Version Directive (Optional)
%HUML v0.2.0
Quick Reference
| Feature | HUML Syntax |
|---|---|
| String | "quoted" |
| Number | 42, 3.14, 0xFF |
| Boolean | true, false |
| Null | null |
| Scalar key | key: value |
| Vector key | key:: items |
| List item | - item |
| Comment | # text |
Common Patterns
Configuration File
%HUML v0.2.0
app::
name: "MyService"
port: 8080
debug: false
database::
host: "localhost"
credentials::
user: "admin"
pass: "secret"
List of Objects
servers::
- name: "web1"
host: "10.0.0.1"
port: 80
- name: "web2"
host: "10.0.0.2"
port: 80
Validation
Use the bundled validation script to check HUML syntax and convert to JSON:
node scripts/validate.mjs path/to/file.huml
On success, outputs the parsed JSON. On failure, shows detailed error message.
Requirements: Node.js with @huml-lang/huml package installed.
Full Specification
See references/spec.md for the complete v0.2.0 specification including:
- All number formats and escape sequences
- Multiline string indentation rules
- Key naming rules
- Edge cases and formatting details
Resources
- Official site: https://huml.io
- Playground: https://huml.io/playground
- npm package:
@huml-lang/huml