Workspaces#

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

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.

For a conceptual overview, see Workspaces.

.workspace.json#

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