Why HCL?
The project needed a text format that people can edit by hand and a tool can validate.
JSON is easy to validate but noisy to write. YAML is pleasant to write. HCL has one more feature: domain concepts can be blocks.
The project chose HCL for this experiment.
In this project, the block form helps because the source looks like the concepts that people discuss.
References and validation
HCL parses this as a traversal expression. HCL does not know that it refers to an Event.
The .em.hcl validator supplies that meaning. It checks the reference kind, scope, and existence. A validated model becomes a typed model for the renderer and other tools. The formatter works on one source file at a time.
These checks do not establish business completeness. Review who triggers each action, where each field comes from, and what happens when a decision fails. HCL records the model; it does not replace that review.
Tradeoffs
These formats solve different problems. This table lists the differences that matter for this project.
| JSON | YAML | .em.hcl | |
|---|---|---|---|
| Familiar ecosystem | Very broad | Very broad | Smaller |
| Human editing | Verbose | Compact | Block-oriented |
| References | Usually plain data | Usually plain data | HCL traversals plus .em.hcl validation |
| Comments | No standard JSON comments | Yes | Yes |
| Structure | Brackets and braces | Indentation | Blocks and braces |
| Validation | JSON Schema ecosystem | Schema or tool dependent | Project validator |
| Fit here | Interchange | Lightweight authoring | Domain-oriented authoring |
| Cost | More syntax noise | Significant whitespace and YAML semantics | Custom language tooling |
Related work
EmLang
An Event Modeling language and toolchain that uses YAML. It includes editing, validation, and diagram tooling. If YAML suits your team, read about it.
ESDM
Uses YAML manifests to model event-sourced domains. It also provides validation, rendering, and editor tooling.
Martin Dilger's Event Modeling Specification
A JSON Schema representation of Event Models. It is a main input to this project.
Use the format that fits
Event Modeling does not require HCL. Start with business facts, decisions, and the information people need, not a choice of syntax. This project explores HCL as one tradeoff.
If JSON or YAML suits your tooling better, use that. The CLI can import and export slice-based Event Modeling JSON, but conversion is not a lossless canvas copy. It warns about details the other format cannot hold.