Workspaces#

Warning

Workspace support is experimental and may change or be removed in any release. See the 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 described from one root directory. The projects are commonly arranged 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.

How workspace references work#

Each workspace project can declare one or more IRIs. Other projects in the same workspace can use those IRIs in .project.json usage entries. During resolution, Sysand can map those IRIs to the local workspace projects, so the workspace does not need machine-specific absolute paths.

Use IRIs that are unlikely to clash with third-party projects. For local-only workspace aliases, urn: identifiers are a good fit.

Workspaces can also carry metadata that applies to the projects built from that workspace. This is useful when a group of projects should share the same metamodel and you do not want to repeat that value in every project’s .meta.json. See Build behavior below.

.workspace.json#

A workspace is defined by a .workspace.json file in the workspace root. Sysand discovers a workspace by looking for .workspace.json in the current directory and then in ancestor directories.

The file contains a JSON object with these fields:

  • projects (required): Array of workspace project entries.

  • meta (optional): Workspace-level metadata.

Each projects entry contains:

  • path (required): Unix-style path to the project directory, relative to the workspace root.

  • iris (required): Array of IRIs that identify the project inside the workspace.

Each value in iris must parse as an IRI. Any listed IRI can be used by other workspace projects in .project.json usage entries instead of a file:// URL.

The optional meta object currently supports:

  • metamodel (optional): IRI for the workspace metamodel.

If meta.metamodel is present and is not one of Sysand’s known SysML or KerML metamodel identifiers, Sysand warns but still accepts it. If it is not a valid IRI, workspace loading fails.

Build behavior#

Running sysand build from a workspace root, outside any project, builds all projects listed in .workspace.json.

The default workspace output directory is <workspace>/output. KPAR files are named from each project’s name and version.

When meta.metamodel is set:

  • A project that omits metamodel in .meta.json receives the workspace metamodel in the built KPAR metadata.

  • A project that sets the same metamodel builds normally.

  • A project that sets a different metamodel fails the build.

Building a workspace does not rewrite the source projects’ .project.json or .meta.json files.

Example#

{
  "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"
  }
}