How to mix json- and dsl-workspaces

[mathias-muench]

I have my own approach that I've showing at conferences over the past few months too (https://github.com/structurizr/examples/tree/main/dsl/system-catalog ... it similarly parses DSL files owned by each team, albeit with a central catalog to avoid reconciliation/merging issues), so it would be nice to centralise the various approaches to using the DSL at scale, because they all have trade-offs. Originally posted by @simonbrowndotje in https://github.com/structurizr/dsl/discussions/238

Following a similar approach I would like to use json-workspaces in the chain (or as "system-catalog") that were created by structurizr-java (groovy in my case). The reason is that I want to connect to enterprise catalogs (databases or the infamous Excel files) to create actors, systems and so on.

I cannot figure out how to refer to an element in a json workspace in a dsl workspace extending the json. I use this groovy to create the json.

@Grab('com.structurizr:structurizr-client')
import com.structurizr.Workspace
import com.structurizr.api.StructurizrClient
import com.structurizr.model.Model
import com.structurizr.model.Person
import com.structurizr.model.SoftwareSystem
import com.structurizr.model.Tags
import com.structurizr.view.Shape
import com.structurizr.view.Styles
import com.structurizr.view.SystemContextView
import com.structurizr.view.ViewSet

import com.structurizr.util.WorkspaceUtils

Workspace workspace = new Workspace("Getting Started", "This is a model of my software system.")
Model model = workspace.getModel();      

// create a model to describe a user using a software system
Person user = model.addPerson("User", "A user of my software system.")
SoftwareSystem softwareSystem = model.addSoftwareSystem("Software System", "My software system.")
softwareSystem.addProperty("structurizr.dsl.identifier", "s")
user.uses(softwareSystem, "Uses")

// create a system context diagram showing people and software systems
ViewSet views = workspace.getViews()
SystemContextView contextView = views.createSystemContextView(softwareSystem, "SystemContext", "An example of a System Context diagram.")
contextView.addAllSoftwareSystems()
contextView.addAllPeople()

// add some styling to the diagram elements
Styles styles = views.getConfiguration().getStyles()
styles.addElementStyle(Tags.SOFTWARE_SYSTEM).background("#1168bd").color("#ffffff")
styles.addElementStyle(Tags.PERSON).background("#08427b").color("#ffffff").shape(Shape.Person)

WorkspaceUtils.saveWorkspaceToJson(workspace, new File("hello.json"))

Using the DSL:

workspace extends hello.json {
  model {
	world = softwareSystem "World"
	s -> world "analyzes"
  }
}

This results in workspace.dsl: The source element "s" does not exist at line 4 of /usr/local/structurizr/workspace.dsl: s -> world "analyzes".

How can I refer to an element in DSL that was created in Java?

[simonbrowndotje]

You can use the DSL !ref keyword in conjunction with the element's "canonical name"; for example:

workspace extends https://raw.githubusercontent.com/structurizr/examples/main/json/getting-started/workspace.json {

    model {
        world = softwareSystem "World"
        
        ss = !ref "SoftwareSystem://Software System" {
            this -> world "analyzes"
        }
    }
    
    views {
        systemContext world {
            include *
            autolayout
        }
    }

}

At the moment, the workspace extension feature doesn't load any of the structurizr.dsl.identifier names, but I don't see why it couldn't be modified to do that (I've contemplated this a couple of times in the past) ... and it would be a better/more stable approach than using !ref when element names change.

[mathias-muench]

Thank you, that makes sense. I had tried the canonical name (without !ref) and !ref together with my approach, both without success. So this will keep me going.
Still - since the canonical names depend on the structure, they may change frequently and a more stable identifier would be helpful. Is there reason why not all properties are loaded when extending a workspace?

[simonbrowndotje]

Is there reason why not all properties are loaded when extending a workspace?

Nobody asked for it yet. 😀