Reference for .em.hcl v0.3.0
The cheat sheet
Blocks, attributes, values, and commands in one page. The normative specification remains authoritative.
Top-level blocks
| Block | Category | Purpose |
|---|---|---|
bounded_context | Catalog | Owns aggregates, field types, and Events |
actor | Catalog | A reusable human or system actor |
team | Catalog | A reusable owning team |
system | Catalog | A reusable external or internal system |
state_change | Workflow | Screen/API → Command → Event |
state_view | Workflow | Event → Read Model → Screen |
automation | Workflow | Internal Event → Processor → Command → Event |
translation | Workflow | External Event → Processor → Command → internal Event |
chapter | Workshop notation | Groups a contiguous range of workflows |
hotspot | Workshop notation | An unresolved question or blocker |
Inside a bounded_context
| Block | Purpose |
|---|---|
aggregate | A context-owned consistency boundary |
field_type | A reusable, ubiquitous-language field definition |
event | A canonical past-tense fact, with field children |
Inside a workflow
| Block | Used by | Purpose |
|---|---|---|
screen | State Change, State View | A human-facing interaction surface |
screen_image | Any workflow | A presentation-only rough wireframe or mockup with a url |
command | State Change, Automation, Translation | An intent that can succeed or fail; needs a reason (to-flow, api_endpoint, or external_trigger) |
readmodel | State View, Automation, Translation | Requires question |
processor | Automation, Translation | The "gear" — a machine reaction |
table | Any workflow | Presentation-only illustrative tabular or example data |
scenario | Any workflow | Pattern-specific Given/When/Then — see below |
Scenario grammar
| Workflow | Given | When | Then |
|---|---|---|---|
| State Change | Event, zero or more | one Command | Event or Error, one or more |
| State View | Event, one or more | none | Read Model or Error, one or more |
| Automation / Translation | Event or Read Model | one Processor or Command | Event or Error, one or more |
Reference forms
| Target | Form |
|---|---|
| Bounded context | bounded_context.clinic |
| Actor / Team / System | actor.clinic_staff / team.clinic_team / system.partner |
| Workflow | workflow.add_pet |
| Event | event.pet_management.pet_added |
| Aggregate | aggregate.pet_management.pet (or aggregate.pet inside its own context) |
| Field type | field_type.pet_management.pet_id (or field_type.pet_id inside its own context) |
| Local workflow element | command.add_pet |
| Workflow-qualified element (for a hotspot) | command.add_pet.add_pet_command |
Field types and flags
Built-in types: String, Boolean, Double, Decimal, Long, Custom, Date, DateTime, UUID, Int.
A field may omit type when a same-named field_type can be inferred. Use fields = [field_type.context.name] to add several reusable fields without per-field overrides. A field_type always declares its built-in type.
| Attribute | Meaning |
|---|---|
id_attribute = true | This field identifies the record |
optional = true | The field may be absent (fields are required by default) |
pii = true | Personally identifiable information |
cardinality = "List" | The field is list-valued |
example = ... | A native HCL literal, checked against the effective type |
Workflow status values
created, planned, assigned, in_progress, review, blocked, done, informational.
Validation profiles
| Profile | Judgment diagnostics (EM404, EM406, the four smells) |
|---|---|
workshop | Informational |
valid (default) | Warnings |
strict | EM404 / EM406 become errors; the four smells stay non-blocking |
Diagnostic families
| Prefix | Category |
|---|---|
EM0xx | Structural |
EM1xx | References |
EM2xx | Flow |
EM3xx | Scenarios |
EM4xx | Modeling judgment |
Diagnostics print as file:line:column: Severity EMxxx: message.
CLI commands
| Command | Does |
|---|---|
eventmodeling-hcl validate <model.em.hcl> | Validates with the default valid profile |
eventmodeling-hcl validate --profile <workshop|valid|strict> <model.em.hcl> | Validates with an explicit profile |
eventmodeling-hcl diagram <model.em.hcl> -o <file> | Renders a self-contained interactive HTML canvas (or writes to stdout without -o) |
eventmodeling-hcl fmt -w <model.em.hcl> | Canonicalizes whitespace and attribute order in place |
eventmodeling-hcl version | Prints the installed version |