Install Allium

Before you start

Allium is a formal language that specifies software behavior at the domain level. Its own one-line description is “The specification language that talks back”. The project home is https://github.com/juxt/allium and the site is https://allium-lang.org/.

The normative source of this format is the Allium file specs/ubiquitous-language.allium.

You need no Allium for these three tasks:

• Read the reference pages of this site.
• Read the case files of the compatibility kit.
• Run the compatibility kit, because the kit is plain YAML.

Install Allium for these three tasks:

• Derive the obligations of the specification yourself.
• Validate a change to the specification.
• Generate a compatibility kit.

Install the command line interface

1. If you use Homebrew, run brew tap juxt/allium && brew install allium.
2. If you use Cargo, run cargo install allium-cli.
3. Run allium --version.
4. Read the language versions in the output.

The specification declares language version 3 on its first line. The command line interface (CLI) reports the language versions it supports in the output of allium --version.

Get the specification file

1. Clone the repository with git clone https://codeberg.org/tobiasbrennecke/ubiquitouslanguage-spec.git.
2. Change into the directory with cd ubiquitouslanguage-spec.

Read the specification with Allium

1. Run allium check specs/ubiquitous-language.allium. The command validates the file and reports structural diagnostics.
2. Run allium plan specs/ubiquitous-language.allium. The command derives the test obligations.
3. Run allium model specs/ubiquitous-language.allium. The command extracts the domain model as structured data.
4. Run allium parse specs/ubiquitous-language.allium. The command prints the syntax tree.

Every one of the four commands prints JSON.

Match the obligations to the kit

1. Run allium plan specs/ubiquitous-language.allium.
2. Read the obligation id of each entry in the output.
3. Compare those ids against the directory names under tck/.

The kit names each case directory after the obligation the case exercises. That shared id is the link between the specification and the kit, and it is the reason an implementor installs Allium.

Optional: the Claude Code plugin

If you work with Claude Code, install the optional plugin with the two commands below.

/plugin marketplace add juxt/claude-plugins
/plugin install allium

Result

The CLI runs on your machine. allium plan prints the obligation ids of the specification. Those ids name the case directories of the kit.

Related

The procedure for the kit is in Run the compatibility kit against your implementation.

The identifier of every obligation is in Obligations and findings.