Workspace operations / JSON Schema

Workspai Project Workspace Link

Machine-local, gitignored binding from a Workspai project to its canonical workspace. Absolute paths are permitted only in this local contract.

Schema version: project-workspace-link.v1
Contract path: contracts/project-workspace-link.v1.json
Publication: json-schema
Defined fields: 16
Artifact bindings: 1

Why this contract exists

Architecture role

Defines a versioned interoperability boundary used by Workspai and contract-aware consumers.

Consumption boundary

• Workspai CLI
• Workspace Intelligence consumers
• IDEs and agents

Related commands

Commands are linked only when the runtime contract identifies a direct production relationship. Supporting contracts may be consumed without having a single producer command.

workspai adopt workspai import workspai project workspace workspai workspace sync

Produced artifacts

These durable files are emitted by registered commands and validated against this contract.

Artifact path	Schema	Producer
.workspai/workspace-link.local.json	project-workspace-link.v1	workspai adopt workspai import workspai project workspace relink workspai workspace sync

Field reference

Every declared schema property or published capability path is listed here. Required means the contract declares or publishes that field at the shown boundary.

Field path	Type	Required	Meaning	Constraints
generatedAt	string	Yes	Defines the generatedat value at this contract boundary.	format: date-time
integrity	object	Yes	Defines the integrity value at this contract boundary.	additionalProperties: false
integrity.algorithm	string	Yes	Defines the algorithm value at this contract boundary.	const: "sha256"
integrity.binding	string	Yes	Defines the binding value at this contract boundary.	pattern: ^[a-f0-9]{64}$
kind	string	Yes	Defines the kind value at this contract boundary.	const: "workspai.project-workspace-link"
project	object	Yes	Defines the project value at this contract boundary.	additionalProperties: false
project.name	string	Yes	Defines the name value at this contract boundary.	minLength: 1
project.relationship	enum	Yes	Defines the relationship value at this contract boundary.	enum: managed, adopted, imported, linked, restored
project.relativePath	string	Yes	Defines the relativepath value at this contract boundary.	minLength: 1
schemaVersion	string	Yes	Defines the schemaversion value at this contract boundary.	const: "project-workspace-link.v1"
state	string	Yes	Defines the state value at this contract boundary.	const: "active"
workspace	object	Yes	Defines the workspace value at this contract boundary.	additionalProperties: false
workspace.contract	string	Yes	Defines the contract value at this contract boundary.	const: ".workspai/workspace.contract.json"
workspace.marker	enum	Yes	Defines the marker value at this contract boundary.	enum: .workspai-workspace, .workspai/workspace.json
workspace.name	string	Yes	Defines the name value at this contract boundary.	minLength: 1
workspace.root	string	Yes	Machine-local absolute workspace path. This file must remain gitignored.	pattern: ^(?:/\|[A-Za-z]:[\\/]) · minLength: 1

Canonical machine-readable definition

The raw synchronized contract remains authoritative. The educational sections above are projections of this definition.

Show raw JSON

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://workspai.dev/schemas/project-workspace-link.v1.json",
  "title": "Workspai Project Workspace Link",
  "description": "Machine-local, gitignored binding from a Workspai project to its canonical workspace. Absolute paths are permitted only in this local contract.",
  "type": "object",
  "required": [
    "schemaVersion",
    "kind",
    "generatedAt",
    "state",
    "workspace",
    "project",
    "integrity"
  ],
  "properties": {
    "schemaVersion": {
      "const": "project-workspace-link.v1"
    },
    "kind": {
      "const": "workspai.project-workspace-link"
    },
    "generatedAt": {
      "type": "string",
      "format": "date-time"
    },
    "state": {
      "const": "active"
    },
    "workspace": {
      "type": "object",
      "required": [
        "name",
        "root",
        "marker",
        "contract"
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1
        },
        "root": {
          "type": "string",
          "minLength": 1,
          "pattern": "^(?:/|[A-Za-z]:[\\\\/])",
          "description": "Machine-local absolute workspace path. This file must remain gitignored."
        },
        "marker": {
          "enum": [
            ".workspai-workspace",
            ".workspai/workspace.json"
          ]
        },
        "contract": {
          "const": ".workspai/workspace.contract.json"
        }
      },
      "additionalProperties": false
    },
    "project": {
      "type": "object",
      "required": [
        "name",
        "relativePath",
        "relationship"
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1
        },
        "relativePath": {
          "type": "string",
          "minLength": 1,
          "not": {
            "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)|^(?:/|[A-Za-z]:[\\\\/])"
          }
        },
        "relationship": {
          "enum": [
            "managed",
            "adopted",
            "imported",
            "linked",
            "restored"
          ]
        }
      },
      "additionalProperties": false
    },
    "integrity": {
      "type": "object",
      "required": [
        "algorithm",
        "binding"
      ],
      "properties": {
        "algorithm": {
          "const": "sha256"
        },
        "binding": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}