Expound

For specs using s/keys or s/req-un, Expound generates a table when keys are missing. This table explicitly maps each missing key to its required spec, providing a clear checklist for validation.

(s/def :address.west-coast/city clojure.core/string?)
(s/def :address.west-coast/state #{"CA" "WA" "OR"})
(s/def :app/address (s/keys :req-un [:address.west-coast/city :address.west-coast/state]))

;; Input: {}
;; Expound output:
;; | key    | spec              |
;; |========+===================|
;; | :city  | string?           |
;; | :state | #{"CA" "WA" "OR"} |

If a value fails a spec defined by a set (e.g., a collection of allowed values), Expound lists the valid options that the value should have been one of.

(s/def :address.west-coast/state #{"CA" "WA" "OR"})

;; Input: {:state "ID"}
;; Expound output:
;; should be one of: "CA", "OR", "WA"

Expound provides specific syntax error messages for sequence-based specs (s/cat):

1. Too few elements: If a sequence is too short, Expound identifies the missing element and the spec it was expected to satisfy.
2. Too many elements: If a sequence has extra elements, Expound points to the specific extra input that should be removed.

(s/def :app/ingredient (s/cat :quantity clojure.core/number? :unit clojure.core/keyword?))

;; Too few elements: [100]
;; Expound: should have additional elements. The next element ":unit" should satisfy keyword?

;; Too many elements: [100 :teaspoon :sugar]
;; Expound: [... ... :sugar] has extra input

Expound highlights non-conforming values (NCV) within a larger context. However, if a Clojure spec uses a conformer to transform a value (e.g., treating a string as a sequence or a collection of characters), the NCV might not exist as an atomic value in the original context.

For example, if a spec uses (s/conformer seq) to validate a string against a regex, the NCV might be a single character (like \C) that is not an atomic element of the original string context.

If you encounter issues where Expound cannot correctly locate or print the non-conforming value due to transformations, you may need to provide a custom printer.

Expound's mental model for errors relies on two components:

1. Problem Value: The specific piece of data that failed a predicate (e.g., "456").
2. Context Value: The larger data structure containing the problem value (e.g., {:ids [123 "456" 789]}).

When an error is generated, Expound prints the context and uses visual markers to highlight the problem.

Example Output:

  {:ids [... "456" ...]}
             ^^^^^

should satisfy

  int?

When a value fails a spec inside a nested structure, Expound provides a visual pointer (using ^^^^^) to the exact location of the invalid data within the input map or vector, making it easier to debug than standard clojure.spec messages.

(s/def :db/id clojure.core/pos-int?)
(s/def :db/ids (s/coll-of :db/id))
(s/def :app/request (s/keys :req-un [:db/ids]))

;; Input: {:ids [123 "456" 789]}
;; Expound output highlights the invalid element:
;; {:ids [... "456" ...]}
;;             ^^^^^

When using s/or to define multiple valid paths, Expound groups the alternatives in the error message, showing the logical 'or' relationship between the possible satisfying specs.

(s/def :address.west-coast/zip (s/or :str clojure.core/string? :num clojure.core/pos-int?))

;; Input: :98109
;; Expound output:
;; should satisfy
;;   string?
;; or
;;   pos-int?

Due to how macros are expanded in ClojureScript, you must configure Expound in Clojure to receive Expound errors during macro-expansion. This requirement does not apply to self-hosted ClojureScript.

To enable this, you must set clojure.spec.alpha/*explain-out* to expound.alpha/printer using the -e argument when running cljs.main.

clj -Srepro -Sdeps '{:deps {expound/expound {:mvn/version "0.9.0"} org.clojure/test.check {:mvn/version "0.9.0"} org.clojure/clojurescript {:mvn/version "1.10.520"}}}' -e "(require '[expound.alpha :as expound]) (set! clojure.spec.alpha/*explain-out* expound.alpha/printer)" -m cljs.main -re node