Why HCL?
A text format was needed that would be comfortable to edit by hand and strict enough to validate.
JSON was easy to validate but noisy to write. YAML was pleasant to write. HCL offered a useful feature: domain concepts could be blocks.
HCL was selected for the experiment.
For this project, the block form is useful because the source resembles the concepts being discussed.
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, then produces a typed model for the formatter, renderer, and other tools.
Tradeoffs
These formats solve different problems. This table describes the choices relevant to this project.
| JSON | YAML | .em.hcl | |
|---|---|---|---|
| Familiar ecosystem | Very broad | Very broad | Smaller |
| Human editing | Verbose | Compact | Block-oriented |
| References | Usually represented as data | Usually represented as 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 using YAML. It includes editing, validation, and diagram tooling. If YAML is natural for your team, it is useful to look at.
ESDM
Uses YAML manifests to model event-sourced domains and provides related validation, rendering, and editor tooling.
Martin Dilger's Event Modeling Specification
A JSON Schema representation of Event Models and an important input to this project.
Use the format that fits
HCL is not required for Event Modeling. It is the tradeoff this project explores.
If JSON or YAML fits your tooling better, use that.