Constructing DSLs in Clojure

Clojure makes people think about DSLs quickly because its syntax is small, its code is data, and its macro system is powerful. But the most important DSL lesson in Clojure is not “use macros everywhere.” It is that the simplest domain language is often just well-shaped data plus a small evaluator.

DSL (domain-specific language): A constrained language or notation built to express concepts from one problem domain more directly than a general-purpose programming language does.

That matters because many teams jump straight to custom syntax when what they really need is a clear domain model, a few constructors, and rules for interpretation.

Start with the Domain, Not the Syntax

The real job of a DSL is to make important domain decisions easier to express and harder to get wrong. That means the first design questions are:

• what concepts need names?
• what combinations are valid?
• what mistakes should become impossible or obvious?
• who will read and maintain the resulting language?

If the answers are not clear yet, inventing new syntax will only hide the confusion.

Data DSLs Are Usually the Best First Step

Because Clojure treats code and data in compatible ways, it is tempting to create a macro immediately. In practice, many successful Clojure DSLs start as data.

1(def workflow
2  [{:task :fetch-data
3    :from :orders}
4   {:task :filter
5    :where [:> :total 100]}
6   {:task :send
7    :to :billing}])

This already behaves like a DSL:

• it has domain vocabulary
• it can be validated
• it can be interpreted
• it can be stored, diffed, and tested

The interpreter can stay ordinary Clojure:

 1(defmulti execute-step :task)
 2
 3(defmethod execute-step :fetch-data [{:keys [from]} ctx]
 4  (assoc ctx :rows (load-source from)))
 5
 6(defmethod execute-step :filter [{:keys [where]} ctx]
 7  (update ctx :rows #(apply-filter where %)))
 8
 9(defmethod execute-step :send [{:keys [to]} ctx]
10  (deliver-result to (:rows ctx)))

That is often a better DSL than a macro-heavy notation because it stays inspectable, serializable, and testable.

Use Macros Only When Syntax Really Matters

Macros are valuable when the domain needs new binding, control-flow, or declaration forms that ordinary functions cannot express cleanly. The official macro reference is a good reminder that macros operate on code as data before evaluation, which is exactly why they are both powerful and easy to misuse.

Good reasons to use a macro in a DSL include:

• introducing a declaration form
• controlling evaluation order
• creating a highly readable authoring surface for repeated patterns
• hiding boilerplate that cannot be abstracted by a function

Weak reasons include:

• wanting the DSL to “look cool”
• avoiding plain data literals
• hiding normal function calls that were already clear

A small macro on top of a data-oriented core is often the healthiest design.

Build the Semantics in Layers

A durable Clojure DSL usually has three layers:

1. domain data model
2. validation and normalization
3. execution or interpretation

If you want custom syntax, add it as a fourth layer that compiles into the same core representation.

1(defmacro defrule [name & clauses]
2  `(def ~name
3     {:kind :rule
4      :clauses ~(vec clauses)}))

Even here, the macro should produce a plain data shape or a plain function shape that the rest of the system already understands.

Readability Beats Cleverness

Internal DSLs fail when authors optimize for novelty instead of maintainability. A DSL should reduce cognitive load for people who know the domain, not increase it for everyone else.

Good DSL design in Clojure usually means:

• small domain vocabulary
• explicit data shapes
• predictable evaluation rules
• ordinary debugging tools still work
• macro expansion is easy to inspect when macros exist

If you constantly need to explain how the DSL parser works, the design may be too clever.

A Small Decision Model

    graph TD;
	    A["Need a domain-specific layer"] --> B{"Can plain data express it clearly?"}
	    B -->|Yes| C["Start with a data DSL"]
	    B -->|No| D{"Need custom binding or evaluation rules?"}
	    D -->|Yes| E["Add a small macro layer"]
	    D -->|No| F["Prefer functions and constructors"]

The diagram below is the most important design rule in this chapter: start with data, then add syntax only when the domain truly benefits from it.

Quiz