Workspaces#

Warning

Workspace support is experimental and may change or be removed in any release. See workspaces tracking issue for planned functionality and changes.

It is common to have multiple related projects that are all developed together and that usually use each other’s functionality.

Sysand supports such uses with workspaces. Inside a workspace, a project can refer to a sibling project by any of its declared IRIs instead of a file:// URL with an absolute path, which keeps projects portable between machines. Running sysand build from the workspace root (outside any project) builds all projects in the workspace.

A workspace is a collection of projects, commonly structured like this:

workspace
 ├──project_1
 ├──project_2
 └──project_3

Such a structure is not a requirement, though. Projects can be anywhere under the workspace root directory.

Defining a workspace#

A workspace is defined by a .workspace.json file in its root directory.

.workspace.json contains a JSON object with the following keys:

  • projects: An array of objects having two keys:

    • path: A Unix-style path relative to workspace root, specifying the project’s directory

    • iris: An array of IRIs identifying the project. The IRIs can be freely chosen, but choose IRIs that will not clash with IRIs of third-party projects (the urn: scheme, as in the example below, is a safe choice). Any of the included IRIs can be used to refer to the project from other projects in the workspace instead of using file:// URLs

  • meta (optional): An object containing workspace-level metadata:

    • metamodel (optional): An IRI specifying the metamodel for all projects in the workspace. Individual projects may omit metamodel in their .meta.json or set the same value; setting a different value produces an error during build. During build, the workspace metamodel is written into each project that does not set one.

Example#

An example .workspace.json file:

{
  "projects": [
    {
      "path": "projectGroup1/project1",
      "iris": ["urn:local:project1"]
    },
    {
      "path": "projectGroup1/project2",
      "iris": ["urn:local:project2"]
    },
    {
      "path": "project3",
      "iris": ["urn:local:project3"]
    }
  ],
  "meta": {
    "metamodel": "https://www.omg.org/spec/SysML/20250201"
  }
}