Scope
One of the most frequently asked questions is, “what should a workspace contain?”. Imagine that you’re the engineering manager for a department in your organisation, and you have three teams each building separate software systems - A, B, and C.
Software system scoped workspaces
As a starting point, and following the C4 model definition of a software system, it’s recommended that a workspace contains the model, views, and documentation for a single software system. Following this recommendation would result in three workspaces, each being owned by the respective teams:
- Workspace 1 defines the system context, container, component, dynamic, and deployment diagrams, plus documentation and decisions, for software system A.
- Workspace 2 defines the system context, container, component, dynamic, and deployment diagrams, plus documentation and decisions, for software system B.
- Workspace 3 defines the system context, container, component, dynamic, and deployment diagrams, plus documentation and decisions, for software system C.
Each of these workspaces is referred to as a “software system scoped workspace” because they describe implementation details related to an individual software system.
Landscape scoped workspaces
You may additionally wish to create another workspace (workspace 4) that describes the people and software systems in the landscape (e.g. department), along with the relationships between them, visualised using one or more system landscape diagrams.
This is referred to as a “landscape scoped workspace”. Organisations typically build one or more landscape scoped workspaces as “maps of their software systems”. The workspace could be configured so that double-clicking software system A in the system landscape diagram takes you workspace 1, where the details of that software system can be found.
Unscoped workspaces
It’s also possible, particularly for smaller software systems, to merge all the diagrams and documentation for a number of software systems into a single workspace. For example, a single workspace could contain all the diagrams and documentation for all software systems owned by a single group/department. These are referred to as “unscoped workspaces”.
Considerations
Creating all the diagrams and documentation for all of your software systems in a single large workspace is more straightforward, but the end-result will be cluttered. Distributing the diagrams and documentation across a number of smaller workspaces may better reflect the autonomous nature of teams within your organisation, but needs some effort with regard to modelling dependencies between teams/software systems. Structurizr DSL features such as workspace extension and !include can help. There are no right or wrong answers here, just trade-offs. You need to find a level of workspace modularity that works for your team/organisation.
Setting the workspace scope
Setting the workspace scope will trigger additional validation to ensure that workspaces are created with the desired content based upon that scope.
If you’re using Structurizr DSL, the scope keyword can be used to set the workspace scope to one of softwaresystem, landscape, or none. For example:
workspace {
...
configuration {
scope softwaresystem
}
}
The same can be achieved via the Structurizr for Java library as follows:
workspace.getConfiguration().setScope(WorkspaceScope.SoftwareSystem);
Setting the workspace scope is a relatively new feature, so you may need to update your Structurizr CLI installation, Structurizr for Java dependency, DSL parser, etc.
Validation
The specific workspace scope validation rules are:
- Landscape scoped: The workspace must not define containers or software system level documentation/decisions.
- Software system scoped: The workspace must define containers or software system level documentation/decisions for only one software system.
- Unscoped: (no validation rules)
In addition, there are two validation modes offered by each of the products that can prevent unscoped workspaces from being used:
- Strict: workspaces must be landscape scoped or software system scoped, with unscoped workspaces being rejected.
- Relaxed: workspaces can be landscape scoped, software system scoped, or unscoped.
| Product | Validation modes |
|---|---|
| Structurizr Lite | Strict or relaxed, based upon the workspace scope |
| Structurizr CLI | Strict or relaxed, based upon the workspace scope |
| Structurizr on-premises installation | Strict or relaxed, based upon configuration |
| Structurizr cloud service | Strict (free accounts) or relaxed (paid subscriptions) |
Troubleshooting
Cloud service
If you encounter the following error message when using a free cloud service account:
Strict workspace scope validation has been enabled for free cloud service accounts. Unscoped workspaces are not permitted - see https://docs.structurizr.com/workspaces for more information.
- Upgrade to the paid cloud service or
- Set the workspace scope to “software system” or “landscape” (you may need to modify your workspace content to meet the validation rules).
On-premises installation
If you encounter the following error message:
Strict workspace scope validation has been enabled for this on-premises installation. Unscoped workspaces are not permitted - see https://docs.structurizr.com/workspaces for more information.
- Ask your on-premises installation administrator to enable unscoped workspaces (set
structurizr.feature.workspace.scopetorelaxed) or - Set the workspace scope to “software system” or “landscape” (you may need to modify your workspace content to meet the validation rules).