Structurizr DSL

The Structurizr DSL provides a way to define a software architecture model (based upon the C4 model) using a text-based domain specific language (DSL). The Structurizr DSL has appeared on the ThoughtWorks Tech Radar - Techniques - Diagrams as code and is text-based wrapper around Structurizr for Java. The following video, “C4 models as code”, provides a good starting point for understanding the Structurizr DSL and related tooling.

Structurizr DSL vs PlantUML, Mermaid, Graphviz/DOT

The two key differences between the Structurizr DSL and other “diagrams as code” formats are:

1. The Structurizr DSL is model-based, making it possible to generate multiple diagrams, at different levels of abstraction, from a single DSL file.
2. The Structurizr DSL sits on top of the Java Virtual Machine, making it possible to execute Java/Groovy/Kotlin/JRuby code during the workspace generation process. This is particularly useful if you would like to reverse-engineer parts of your software architecture model.

	Structurizr DSL	PlantUML	Mermaid	Graphviz
Can generate multiple diagrams from a single file?	Yes	No	No	No
Can include/execute Java code?	Yes	No	No	No
Can include/execute Groovy/Kotlin/JRuby scripts?	Yes	No	No	No
Diagrams can be rendered with multiple tools?	Yes	No	No	No

Authoring

There are a number of options for authoring workspaces with the Structurizr DSL.

Tool	Summary	Recommended
Structurizr Lite	Structurizr Lite provides a way to quickly work with a single workspace. It’s free to use, and allows you to view/edit diagrams, view documentation, and view architecture decision records defined in a DSL workspace. The auto-sync feature provides the ability to sync your local changes with a workspace stored on the Structurizr cloud service or an on-premises installation.	Yes
Structurizr CLI	The Structurizr CLI is a command line utility, designed to be used in conjunction with the Structurizr DSL. It provides the ability to push/pull workspaces to/from the Structurizr cloud service or an on-premises installation, in additional to exporting the views defined in a DSL file to other formats (PlantUML, Mermaid, WebSequenceDiagrams, and Ilograph).	Yes
Browser-based DSL editor	If you’d rather not use Structurizr Lite or the Structurizr CLI, the Structurizr cloud service/on-premises installation provides a basic online DSL editor. The editor provides some rudimentary syntax highlighting and the ability to use the DSL without installing any tooling, but it does not provide access to the full feature set of the DSL - see the comparison table below. The DSL editor can be opened using the link on your workspace summary page.	No

Comparison

Here is a comparison of the various authoring tools.

Feature	DSL keyword	Structurizr Lite	Structurizr CLI	Browser-based DSL editor
DSL files are stored on local disk, and can be easily added to source code control		Yes	Yes
Diagrams		Yes	Yes	Yes
Documentation	!docs	Yes	Yes
Architecture decision records	!adrs	Yes	Yes
Image views	image	Yes	Yes	HTTPS URLs (with CORS headers) and data URIs only
Branding logo	logo	Yes	Yes	HTTPS URLs (with CORS headers) and data URIs only
Element style icons	icon	Yes	Yes	HTTPS URLs (with CORS headers) and data URIs only
Workspace extension	extends	Yes	Yes	HTTPS URLs only
DSL includes	!include	Yes	Yes	HTTPS URLs only
Plugins	!plugin	Yes	Yes
Scripts	!script	Yes	Yes
Export to PlantUML, Mermaid, DOT, WebSequenceDiagrams, and Ilograph			Yes	Demo page only
DSL keyword/feature deprecation warnings		Yes	Yes

Recommended workflow

The recommended workflow is to use Structurizr Lite and/or the Structurizr CLI, and to store your DSL file(s) in source code control. If you use the browser-based DSL editor, please note that (1) it does not provide access to the full feature set and (2) you should ensure your DSL is backed up outside of the Structurizr cloud service/on-premises installation.

Disabling the browser-based DSL editor

If you’d like to disable the online browser-based DSL editor, to ensure that team members don’t accidentally use it, you can set a workspace property named structurizr.dslEditor to false. For example:

workspace {

    properties {
        "structurizr.dslEditor" "false"
    }

    model {
        ...
    }

    views {
        ...
    }

}

If you are using the on-premises installation, you can disable the DSL editor for all workspaces via the structurizr.properties file, by setting a property named structurizr.dslEditor to false.

Editor and IDE plugins

See Community tooling for editor and IDE plugins.

Links

• GitHub
• Changelog