Specification 2026.06 (draft)
This is the normative specification of Cairn, an intermediate language for AI to read and write Minecraft builds. It avoids the inefficiency of NBT/SNBT, which is binary and one record per block, and aligns architectural knowledge (walls, roofs, symmetry) with the voxel world. The approach is generation-first, and therefore lossy on purpose.
Reading order
Section titled “Reading order”| # | Chapter | Contents |
|---|---|---|
| 1 | Purpose and Scope | Purpose, scope, non-goals |
| 2 | Design Principles | P1–P5 |
| 3 | Architecture | Three-layer IR, block-array pivot |
| 4 | Compilation Model | Phase evaluation, target axes, roof lowering |
| 5 | Syntax | Lexical rules, key=value, selectors, headers |
| 6 | Blockstate Model | Derivation and override, intent vs resolved, waterlogged |
| 7 | Materials and Themes | Slots, canonical vocabulary, themes |
| 8 | Entities | Two-tier entity model, anchor conventions |
| 9 | Components, Editing, and Multi-building | def, editing, site |
| 10 | Versioning and Editions | Target strategy, lock, portability |
| 11 | Lint | Diagnostic codes and constraint validation |
| 12 | Ecosystem Interop | Import, reverse conversion |
| 13 | Evaluation Framework | How the spec is iterated |
| 14 | Redstone | Logic circuits |
| 15 | Open Issues | What is still undecided |
| — | Compatibility Tiers | Stable / Evolving / Internal, per public surface |
| — | Glossary | Defined terms, cross-chapter |
Conventions
Section titled “Conventions”- Requirement words MUST / SHOULD / MUST NOT / OPTIONAL are used in the RFC 2119 sense.
- The language is Cairn, the CLI is
cairn, and source files use.crn. - Design principles are referenced as
P1–P5(see Design Principles).
Two version axes
Section titled “Two version axes”Cairn’s own releases use date-based versioning (CalVer) YYYY.M[.PATCH]: 2026.7 for a monthly
release, 2026.7.1 for an in-month patch. They sort chronologically as strings. A release bundles
the language spec, the reference compiler, the standard library, and the (edition, version)
registry and constraint catalogs.
Minecraft also moved to date-based versions, so the two cannot be told apart by format. They are distinguished by field, flag, or keyword, never by shape:
| Cairn’s own version | The Minecraft target | |
|---|---|---|
| Lock | cairn_version |
mc_version |
| Headers | @cairn |
@requires, @intended_targets |
| CLI | cairn --version |
--target |
In prose, disambiguate with a prefix: cairn:2026.06 and mc:1.21.4.
This document is 2026.6 (draft), superseding the former v0.2 label. A .crn file MAY declare
@cairn 2026.06, the language version it was written against. It is provenance only, so a future
compiler can parse and warn correctly — which is why the value is checked to be a CalVer even
though no pass branches on it. See Syntax §5.3.