What Is HUML? Human-Oriented Markup Language (Experimental)
Originally published in Turkish. Read the original →
HUML is a simple, strict and human-readable markup language for documents, datasets and configuration. It looks similar to YAML but aims to reduce its ambiguities and pitfalls.
HUML (Human-oriented Markup Language, Experimental) is a simple and strict serialization language designed for documents, datasets and configuration. Its primary goal is to put human readability and editability first. It looks similar to YAML, but it aims to reduce YAML's complexity, ambiguities and common error-prone spots.
What Does HUML Look Like?
The example below shows the shape of a HUML document. Lists and dictionaries can be written inline or across multiple lines. Indentation expresses the hierarchy explicitly.
website::
hostname: "huml.io"
ports:: 80, 443 # Inline list
enabled: true
factor: 3.14
props:: mime_type: "text/html", encoding: "gzip" # Inline dictionary
tags:: # Multi-line list
- "markup"
- "webpage"
- "schema"
haikus::
one: """
A quiet language
Lines fall into their places
Nothing out of place
"""Why HUML?
HUML was born out of the frustrations of working with YAML in particular. In YAML, a single hard-to-spot indentation change can dangerously alter the meaning of a document. Other popular languages (TOML, HCL) mostly focus on configuration. NestedText offers an interesting approach, but it is too primitive for broader use cases. JSON is universal, but it has no comments, it does not offer a strict and consistent reading form, and the difficulties of matching and formatting brackets make editing by hand hard.
YAML comes closest when it comes to visually implying structure and hierarchy. Still, HUML draws inspiration from many languages and tries to prioritize one thing: human readability and a consistent form across contexts.
In short, "Why yet another markup language?" Because the goal is to enforce a format that is free of pitfalls, consistent and easy to scan by eye.
Goals
- Keep human readability and editability at the top
- Make data structures and hierarchies visually graspable
- Avoid ambiguities and "footguns" in syntax and data types
- Where possible, have only one way to express something
- Offer an environment-independent, formally strict and consistent form (without needing a formatter)
Key Features (Summary)
- Strict format: It does not allow arbitrary variations, so documents become more predictable.
- Support for inline and multi-line structures: Lists and dictionaries can be written in both short and long forms.
- Comment- and annotation-friendly: The aim is for people not to lose context while reading the document.
- Visual hierarchy: Meaning becomes clear through indentation, which makes it harder to break silently.
When Should You Use It?
- Configuration files edited by people
- Documents and datasets where readability is critical
- When choosing between YAML/TOML/JSON and you are looking for "one format, few surprises"
Final Word
HUML is a relatively new and experimental approach. Its ultimate goal is to produce documents that are "easy to read, safe to write" for both developers and non-technical users. For the specifications and details: "Read the specs →" (will be updated once the link is available).
