Workspace Intelligence / JSON Schema

Workspai Project Knowledge Graph Reference

Portable, integrity-bound project reference to the canonical workspace Knowledge Graph.

Schema version: project-knowledge-graph-reference.v1
Contract path: contracts/workspace-intelligence/project-knowledge-graph-reference.v1.json
Publication: json-schema
Defined fields: 18
Artifact bindings: 1

Why this contract exists

Architecture role

Relates workspace structure and change so downstream reasoning remains traceable.

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 workspace model workspai workspace sync workspai workspace intelligence

Produced artifacts

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

Artifact path	Schema	Producer
.workspai/reports/project-knowledge-graph-reference.json	project-knowledge-graph-reference.v1	workspai adopt workspai import workspai workspace model workspai workspace sync workspai workspace intelligence run

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
canonical	object	Yes	Defines the canonical value at this contract boundary.	additionalProperties: false
canonical.boundedQuery	string	Yes	Defines the boundedquery value at this contract boundary.	minLength: 1
canonical.graph	string	Yes	Defines the graph value at this contract boundary.	const: "workspace:.workspai/reports/workspace-knowledge-graph.json"
canonical.projectionHash	string	Yes	Defines the projectionhash value at this contract boundary.	pattern: ^[a-f0-9]{64}$
canonical.sourceHash	string	Yes	Defines the sourcehash value at this contract boundary.	pattern: ^[a-f0-9]{64}$
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.absolutePathsEmitted	boolean	Yes	Defines the absolutepathsemitted value at this contract boundary.	const: false
integrity.algorithm	string	Yes	Defines the algorithm value at this contract boundary.	const: "sha256"
integrity.payloadHash	string	Yes	Defines the payloadhash value at this contract boundary.	pattern: ^[a-f0-9]{64}$
integrity.portable	boolean	Yes	Defines the portable value at this contract boundary.	const: true
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
schemaVersion	string	Yes	Defines the schemaversion value at this contract boundary.	const: "project-knowledge-graph-reference.v1"
summary	object	Yes	Defines the summary value at this contract boundary.	additionalProperties: false
summary.entityCount	integer	Yes	Defines the entitycount value at this contract boundary.	minimum: 0
summary.proofCount	integer	Yes	Defines the proofcount value at this contract boundary.	minimum: 0
summary.relationCount	integer	Yes	Defines the relationcount value at this contract boundary.	minimum: 0

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/workspace-intelligence/project-knowledge-graph-reference.v1.json",
  "title": "Workspai Project Knowledge Graph Reference",
  "description": "Portable, integrity-bound project reference to the canonical workspace Knowledge Graph.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schemaVersion",
    "generatedAt",
    "project",
    "canonical",
    "summary",
    "integrity"
  ],
  "properties": {
    "schemaVersion": {
      "const": "project-knowledge-graph-reference.v1"
    },
    "generatedAt": {
      "type": "string",
      "format": "date-time"
    },
    "project": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name"
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1
        }
      }
    },
    "canonical": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "graph",
        "boundedQuery",
        "sourceHash",
        "projectionHash"
      ],
      "properties": {
        "graph": {
          "const": "workspace:.workspai/reports/workspace-knowledge-graph.json"
        },
        "boundedQuery": {
          "type": "string",
          "minLength": 1
        },
        "sourceHash": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "projectionHash": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        }
      }
    },
    "summary": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "entityCount",
        "relationCount",
        "proofCount"
      ],
      "properties": {
        "entityCount": {
          "type": "integer",
          "minimum": 0
        },
        "relationCount": {
          "type": "integer",
          "minimum": 0
        },
        "proofCount": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "integrity": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "algorithm",
        "payloadHash",
        "portable",
        "absolutePathsEmitted"
      ],
      "properties": {
        "algorithm": {
          "const": "sha256"
        },
        "payloadHash": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "portable": {
          "const": true
        },
        "absolutePathsEmitted": {
          "const": false
        }
      }
    }
  }
}