Workspace operations / JSON Schema

Workspace Watch Event V1

Defines the versioned workspace watch event v1 boundary used by Workspai and its consumers.

Schema version: workspace-watch-event.v1
Contract path: contracts/workspace-watch-event.v1.json
Publication: json-schema
Defined fields: 17
Artifact bindings: 0

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.

This is a supporting, capability, cache, compatibility, or consumer contract. It has no single direct producer command in the canonical Workspace Intelligence execution registry.

Produced artifacts

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

No canonical file artifact is registered for this contract. It may describe capabilities, embedded data, runtime exchange, or supporting state instead of a standalone report.

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
addedProjects	array	Yes	Defines the addedprojects value at this contract boundary.	—
changedProjects	array	Yes	Defines the changedprojects value at this contract boundary.	—
durationMs	number	Yes	Defines the durationms value at this contract boundary.	minimum: 0
error	string	No	Defines the error value at this contract boundary.	—
graph	object	Yes	Defines the graph value at this contract boundary.	additionalProperties: false
graph.edgeCount	integer	Yes	Defines the edgecount value at this contract boundary.	minimum: 0
graph.edgesAdded	array	Yes	Defines the edgesadded value at this contract boundary.	—
graph.edgesRemoved	array	Yes	Defines the edgesremoved value at this contract boundary.	—
graph.nodeCount	integer	Yes	Defines the nodecount value at this contract boundary.	minimum: 0
kind	enum	Yes	Defines the kind value at this contract boundary.	enum: ready, changed, unchanged, error
mode	enum	Yes	Defines the mode value at this contract boundary.	enum: initial, full, incremental, unchanged
modelHash	string	Yes	Defines the modelhash value at this contract boundary.	pattern: ^(?:[a-f0-9]{64})?$
modelHashChanged	boolean	Yes	Defines the modelhashchanged value at this contract boundary.	—
removedProjects	array	Yes	Defines the removedprojects value at this contract boundary.	—
schemaVersion	string	Yes	Defines the schemaversion value at this contract boundary.	const: "workspace-watch-event.v1"
sequence	integer	Yes	Defines the sequence value at this contract boundary.	minimum: -1
timestamp	string	Yes	Defines the timestamp value at this contract boundary.	format: date-time

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",
  "type": "object",
  "required": [
    "schemaVersion",
    "kind",
    "sequence",
    "timestamp",
    "mode",
    "modelHash",
    "modelHashChanged",
    "changedProjects",
    "addedProjects",
    "removedProjects",
    "graph",
    "durationMs"
  ],
  "properties": {
    "schemaVersion": {
      "const": "workspace-watch-event.v1"
    },
    "kind": {
      "enum": [
        "ready",
        "changed",
        "unchanged",
        "error"
      ]
    },
    "sequence": {
      "type": "integer",
      "minimum": -1
    },
    "timestamp": {
      "type": "string",
      "format": "date-time"
    },
    "mode": {
      "enum": [
        "initial",
        "full",
        "incremental",
        "unchanged"
      ]
    },
    "modelHash": {
      "type": "string",
      "pattern": "^(?:[a-f0-9]{64})?$"
    },
    "modelHashChanged": {
      "type": "boolean"
    },
    "changedProjects": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "addedProjects": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "removedProjects": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "graph": {
      "type": "object",
      "required": [
        "nodeCount",
        "edgeCount",
        "edgesAdded",
        "edgesRemoved"
      ],
      "properties": {
        "nodeCount": {
          "type": "integer",
          "minimum": 0
        },
        "edgeCount": {
          "type": "integer",
          "minimum": 0
        },
        "edgesAdded": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "edgesRemoved": {
          "type": "array",
          "items": {
            "type": "object"
          }
        }
      },
      "additionalProperties": false
    },
    "durationMs": {
      "type": "number",
      "minimum": 0
    },
    "error": {
      "type": "string"
    }
  },
  "additionalProperties": true
}