Skip to content
Jude Payne edited this page Jul 10, 2025 · 13 revisions

What is dictim?

dictim is a bridge between Clojure/script and the d2 and dot declarative diagram languages.

It has several parts:

  • A syntax for describing d2 using Clojure vectors and maps. Json works just as well. This syntax is called 'dictim syntax', and sticks as close to d2's syntax as possible - in 'datafied' form.
  • A unnested syntax called 'dictim-flat syntax' which can be converted to and from dictim syntax.
  • A higher level syntax for describing your data as graph. These are called 'graphspecs'.
  • A command line tool 'dict' for working with data described with these syntaxes and converting to/ from d2.
  • A Clojure library for direct integration into your Clojure programme.

dictim is a 'building block' library, designed to be built upon by other libraries. The command line tool 'dict' is designed to fit into your command line flow.

Motivation

Producing diagrams dynamically is super powerful when those diagrams are trying to represent aspects of a complex, fast changing system.

Diagrams are great, but hand crafted diagram 'lock knowledge away' at the point in time that they were created leaving some future viewer wondering if the information is stale or not. Better to produce diagrams from current data as much as we can.

For example, say you're working in Technology in a large organization which has hundreds of applications and thousands of flows of data betwen them, then it's very hard to keep up with a set of fixed, statically maintained architecture diagrams that probably don't show the exact view you were looking for.

A better approach would be to collect and maintain the metadata about the applications and flows and then dynamically produce diagrams of selections of that metadata on the fly.

d2 is a toolkit for producing (technology) architectural diagrams from a text description (the d2 language). The text description is a great building block, but is isn't data in a programming language environment, so still has to be produced either by hand or by something else.

dictim aims to be that something else!

Clone this wiki locally