Option
Options are instructions to translators on how a particular
definition should be regarded. Any translator can make use of any
option. Options can take a list of string arguments much like the
options and arguments to a program. If none are specified, the
option is considered to be a Boolean value that is true if
specified.
Options appear in with { } metadata blocks, not inside a
definition's body. The syntax is option is option_name with
optional string arguments:
Every vital definition in RIDDL allows a technology
option that takes any number of string arguments. These can specify
the technologies intended for the implementation. This idea was
adapted from a similar idea in
Simon Brown's
C4 Model For Software Architecture.
Other options are specific to the kind of vital definition. Non-vital definitions do not allow options.
The Option Registry¶
RIDDL keeps a single registry of recognized option names, their valid parent kinds, and their argument counts. An option not in the registry is not an error — it draws a StyleWarning, so the system stays extensible — but an option used on the wrong kind of definition draws a nudge.
One table, not two
Before RIDDL 2.0 the option relation was described twice, in two hand-maintained lists that had to be kept in step. They drifted three times, and each drift produced a spurious "not a recognized RIDDL option" warning on a perfectly valid option. In 2.0 the per-kind lists are derived from the registry, so they cannot disagree with it.
Consolidating them also exposed eight options RIDDL advertised but never registered — including six entity markers — every use of which had been drawing that spurious warning.
Options Valid on Any Definition¶
| Option | Arguments | Meaning |
|---|---|---|
technology |
1 | Names the implementation technology |
kind |
1 | A semantic categorization |
css |
1 | A CSS fragment for rendering |
color |
1 | A color for rendering |
faicon |
1 | A Font Awesome icon name |
event_catalog_version |
1 | Version pinning for EventCatalog generation |
sql_dialect, sql_table |
1 | SQL DDL generation hints |
backstage_owner, backstage_lifecycle, backstage_type |
1 | Backstage catalog generation hints |
message_envelope |
1 | Names the envelope a generator wraps messages in |
Options By Definition Kind¶
| Definition | Options |
|---|---|
| Entity | auto-id, bulkhead, finite-state-machine, message-queue, microservice, protocol, rate-limit, snapshots |
| Context | bulkhead, clustered, microservice, namespace, protocol |
| Domain | namespace, confluence_space, confluence_parent |
| Connector | ordered, unordered, partitioned, circuit-breaker |
| Inlet | async, ordered, unordered, error-sink |
| Outlet | async, lowering |
| Saga | parallel, timeout, retry, undo-retry, failure-message, microservice, protocol |
| Saga Step | timeout, retry, delay |
| Handler | timeout, retry, idempotent, cacheable, rate-limit |
| On Clause | timeout, idempotent |
| Adaptor | circuit-breaker, clustered, protocol |
| Projector | cacheable, batch, clustered, microservice, protocol |
| Repository | transient, available, consistent, batch, clustered, microservice, protocol |
| Streamlet | clustered, lowering, protocol |
| Epic | sync |
Every definition also takes the options in the table above. Both tables were checked against riddl 2.7.0's option registry.
Deprecated options
These still parse, emit [deprecated], and are slated for removal in 3.0.
See Deprecated Constructs
for each one's replacement:
- on an entity:
aggregate,available,consistent,event-sourced,transient,value. Write them as intentions beforeentity. - on a connector:
persistent,at-least-once,at-most-once,exactly-once. Write them beforeconnector. - on a context:
external,gateway,service,wrapper. - on a domain or context:
external, andpackage(usenamespace).
Notable Options¶
technology— Names the implementation technologies, adapted from Simon Brown's C4 Model:option is technology("Kafka")auto-id— An entity is assigned a ULID at instantiationparallel— A saga's steps all start at once, rather than in sequence. A saga is sequential by definition, soparalleldeclares the exception.async— Marks a port as a deliberate codegen async boundary, so the generator inserts a real boundary there instead of fusing the streampersistent— Messages crossing a connector are durably stored
Deprecated options
| Deprecated | Replacement | Since |
|---|---|---|
gateway, service, external on a Context |
the context intention prefix | 2.0.0 |
external on a Domain |
external before each of the domain's contexts: domain D is { external context C is { … } } |
2.0.0 |
wrapper |
an adaptor | 2.0.0 |
package |
namespace |
1.15.0 |
Each is still recognized — deliberately, so that using one draws only
the [deprecated] message rather than an additional and contradictory
"unrecognized option" warning.
sequential on a saga was dropped outright: it requested the default
behavior, so it said nothing.
Occurs In¶
Metadata blocks (with { }) on any
vital definition.
Contains¶
Option values which are simple identifiers with an optional set of string arguments.