Workspace Intelligence / JSON Schema
Workspai Workspace Intelligence Model
Defines the versioned workspace model v1 boundary used by Workspai and its consumers.
- Schema version
workspace-model.v1- Contract path
contracts/workspace-intelligence/workspace-model.v1.json- Publication
- embedded-type, json-schema
- Defined fields
- 64
- Artifact bindings
- 1
Why this contract exists
Architecture role
Defines canonical workspace state or a versioned projection of that state.
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.
Produced artifacts
These durable files are emitted by registered commands and validated against this contract.
| Artifact path | Schema | Producer |
|---|---|---|
| .workspai/reports/workspace-model.json | workspace-model.v1 | workspai workspace model --json --write |
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 |
|---|---|---|---|---|
| $defs.buildProvenance.engineStatus | enum | Yes | Defines the enginestatus value at this contract boundary. | enum: disabled, miss, hit, full, incremental, unchanged |
| $defs.buildProvenance.mode | enum | Yes | Defines the mode value at this contract boundary. | enum: full, cache, incremental |
| $defs.buildProvenance.outcome | enum | Yes | Defines the outcome value at this contract boundary. | enum: rebuilt, partially-reused, reused |
| $defs.buildProvenance.schemaVersion | string | Yes | Defines the schemaversion value at this contract boundary. | const: "workspace-model-build.v1" |
| $defs.factFreshness.category | enum | Yes | Defines the category value at this contract boundary. | enum: structure, verification, state |
| $defs.factFreshness.expiresAt | string | No | Defines the expiresat value at this contract boundary. | format: date-time |
| $defs.factFreshness.generatedAt | string | Yes | Defines the generatedat value at this contract boundary. | format: date-time |
| $defs.factFreshness.inputsHash | string | No | Defines the inputshash value at this contract boundary. | — |
| $defs.factFreshness.kind | enum | Yes | Defines the kind value at this contract boundary. | enum: durable, derived, evidence-backed, live, verify-before-use |
| $defs.factFreshness.reason | string | Yes | Defines the reason value at this contract boundary. | — |
| $defs.factFreshness.schemaVersion | string | Yes | Defines the schemaversion value at this contract boundary. | const: "rapidkit-fact-freshness-v1" |
| $defs.factFreshness.sourceArtifact | string | No | Defines the sourceartifact value at this contract boundary. | — |
| $defs.factFreshness.sourcePath | string | No | Defines the sourcepath value at this contract boundary. | — |
| $defs.factFreshness.status | enum | Yes | Defines the status value at this contract boundary. | enum: fresh, stale, unknown |
| $defs.factFreshness.ttlSeconds | integer | null | Yes | Defines the ttlseconds value at this contract boundary. | minimum: 0 |
| $defs.factFreshness.verifyBeforeUse | boolean | Yes | Defines the verifybeforeuse value at this contract boundary. | — |
| $defs.factFreshnessSummary.byCategory | object | Yes | Defines the bycategory value at this contract boundary. | — |
| $defs.factFreshnessSummary.byKind | object | Yes | Defines the bykind value at this contract boundary. | — |
| $defs.factFreshnessSummary.generatedAt | string | Yes | Defines the generatedat value at this contract boundary. | format: date-time |
| $defs.factFreshnessSummary.liveFacts | integer | Yes | Defines the livefacts value at this contract boundary. | minimum: 0 |
| $defs.factFreshnessSummary.schemaVersion | string | Yes | Defines the schemaversion value at this contract boundary. | const: "rapidkit-fact-freshness-v1" |
| $defs.factFreshnessSummary.staleFacts | integer | Yes | Defines the stalefacts value at this contract boundary. | minimum: 0 |
| $defs.factFreshnessSummary.status | enum | Yes | Defines the status value at this contract boundary. | enum: fresh, stale, unknown |
| $defs.factFreshnessSummary.totalFacts | integer | Yes | Defines the totalfacts value at this contract boundary. | minimum: 0 |
| $defs.factFreshnessSummary.unknownFacts | integer | Yes | Defines the unknownfacts value at this contract boundary. | minimum: 0 |
| $defs.factFreshnessSummary.verifyBeforeUseFacts | integer | Yes | Defines the verifybeforeusefacts value at this contract boundary. | minimum: 0 |
| $defs.governanceControl.evidence | array | Yes | Defines the evidence value at this contract boundary. | — |
| $defs.governanceControl.provider | string | null | Yes | Defines the provider value at this contract boundary. | — |
| $defs.governanceControl.reference | string | null | Yes | Defines the reference value at this contract boundary. | — |
| $defs.governanceControl.status | enum | Yes | Defines the status value at this contract boundary. | enum: repository, external-declared, external-observed, unknown |
| $defs.projectGovernance.ci | reference | Yes | Defines the ci value at this contract boundary. | ref: #/$defs/governanceControl |
| $defs.projectGovernance.ownership | reference | Yes | Defines the ownership value at this contract boundary. | ref: #/$defs/governanceControl |
| $defs.projectGovernance.release | reference | Yes | Defines the release value at this contract boundary. | ref: #/$defs/governanceControl |
| $defs.projectGovernance.schemaVersion | string | Yes | Defines the schemaversion value at this contract boundary. | const: "workspai.project-governance.v1" |
| $defs.workspaceFact.freshness | reference | Yes | Defines the freshness value at this contract boundary. | ref: #/$defs/factFreshness |
| $defs.workspaceFact.id | string | Yes | Defines the id value at this contract boundary. | — |
| $defs.workspaceFact.label | string | Yes | Defines the label value at this contract boundary. | — |
| $defs.workspaceFact.project | string | No | Defines the project value at this contract boundary. | — |
| $defs.workspaceFact.scope | enum | Yes | Defines the scope value at this contract boundary. | enum: workspace, project, evidence, policy, contract, command, graph |
| build | reference | No | Defines the build value at this contract boundary. | ref: #/$defs/buildProvenance |
| contracts | object | Yes | Defines the contracts value at this contract boundary. | additionalProperties: true |
| discovery | object | Yes | Defines the discovery value at this contract boundary. | additionalProperties: true |
| evidence | object | Yes | Defines the evidence value at this contract boundary. | additionalProperties: true |
| factFreshness | reference | No | Defines the factfreshness value at this contract boundary. | ref: #/$defs/factFreshnessSummary |
| facts | array | No | Defines the facts value at this contract boundary. | — |
| generatedAt | string | Yes | Defines the generatedat value at this contract boundary. | format: date-time |
| graph | object | No | Deprecated compatibility alias for projectTopology. Producers must emit identical content during the v1 migration window. | additionalProperties: true |
| identity | object | Yes | Defines the identity value at this contract boundary. | additionalProperties: true |
| identity.categories | array | No | Defines the categories value at this contract boundary. | — |
| identity.surfaces | array | No | Defines the surfaces value at this contract boundary. | — |
| policies | object | Yes | Defines the policies value at this contract boundary. | additionalProperties: true |
| projects | array | Yes | Defines the projects value at this contract boundary. | — |
| projects[].category | enum | No | Defines the category value at this contract boundary. | enum: backend, frontend, desktop, extension, platform, library, infrastructure, documentation, quality, unknown |
| projects[].governance | reference | No | Defines the governance value at this contract boundary. | ref: #/$defs/projectGovernance |
| projects[].kind | enum | No | Defines the kind value at this contract boundary. | enum: backend, frontend, desktop, extension, worker, platform, library, infra, docs, test-suite, unknown |
| projectTopology | object | No | Canonical compact project dependency topology (workspace-dependency-graph.v1). | additionalProperties: true |
| schemaVersion | string | Yes | Defines the schemaversion value at this contract boundary. | const: "workspace-model.v1" |
| summary | object | Yes | Defines the summary value at this contract boundary. | additionalProperties: true |
| validation | object | No | Defines the validation value at this contract boundary. | additionalProperties: true |
| workspace | object | Yes | Defines the workspace value at this contract boundary. | additionalProperties: true |
| workspace.name | string | Yes | Defines the name value at this contract boundary. | — |
| workspace.profile | string | No | Defines the profile value at this contract boundary. | — |
| workspace.root | string | Yes | Defines the root value at this contract boundary. | — |
| workspace.type | string | Yes | Defines the type value at this contract boundary. | — |
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/workspace-model.v1.json",
"title": "Workspai Workspace Intelligence Model",
"type": "object",
"required": [
"schemaVersion",
"generatedAt",
"workspace",
"identity",
"summary",
"projects",
"contracts",
"evidence",
"discovery",
"policies"
],
"properties": {
"schemaVersion": {
"const": "workspace-model.v1"
},
"generatedAt": {
"type": "string",
"format": "date-time"
},
"workspace": {
"type": "object",
"required": [
"name",
"root",
"type"
],
"properties": {
"name": {
"type": "string"
},
"root": {
"type": "string"
},
"type": {
"type": "string"
},
"profile": {
"type": "string"
}
},
"additionalProperties": true
},
"identity": {
"type": "object",
"properties": {
"surfaces": {
"type": "array",
"items": {
"enum": [
"backend",
"frontend",
"desktop",
"extension",
"service",
"worker",
"platform",
"library",
"infra",
"docs",
"test-suite",
"unknown"
]
}
},
"categories": {
"type": "array",
"items": {
"enum": [
"backend",
"frontend",
"desktop",
"extension",
"platform",
"library",
"infrastructure",
"documentation",
"quality",
"unknown"
]
}
}
},
"additionalProperties": true
},
"summary": {
"type": "object",
"additionalProperties": true
},
"factFreshness": {
"$ref": "#/$defs/factFreshnessSummary"
},
"facts": {
"type": "array",
"items": {
"$ref": "#/$defs/workspaceFact"
}
},
"projects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"enum": [
"backend",
"frontend",
"desktop",
"extension",
"worker",
"platform",
"library",
"infra",
"docs",
"test-suite",
"unknown"
]
},
"category": {
"enum": [
"backend",
"frontend",
"desktop",
"extension",
"platform",
"library",
"infrastructure",
"documentation",
"quality",
"unknown"
]
},
"governance": {
"$ref": "#/$defs/projectGovernance"
}
},
"additionalProperties": true
}
},
"contracts": {
"type": "object",
"additionalProperties": true
},
"projectTopology": {
"type": "object",
"description": "Canonical compact project dependency topology (workspace-dependency-graph.v1).",
"additionalProperties": true
},
"graph": {
"type": "object",
"deprecated": true,
"description": "Deprecated compatibility alias for projectTopology. Producers must emit identical content during the v1 migration window.",
"additionalProperties": true
},
"evidence": {
"type": "object",
"additionalProperties": true
},
"discovery": {
"type": "object",
"additionalProperties": true
},
"policies": {
"type": "object",
"additionalProperties": true
},
"validation": {
"type": "object",
"additionalProperties": true
},
"build": {
"$ref": "#/$defs/buildProvenance"
}
},
"$defs": {
"projectGovernance": {
"type": "object",
"required": [
"schemaVersion",
"ci",
"release",
"ownership"
],
"properties": {
"schemaVersion": {
"const": "workspai.project-governance.v1"
},
"ci": {
"$ref": "#/$defs/governanceControl"
},
"release": {
"$ref": "#/$defs/governanceControl"
},
"ownership": {
"$ref": "#/$defs/governanceControl"
}
},
"additionalProperties": false
},
"governanceControl": {
"type": "object",
"required": [
"status",
"provider",
"evidence",
"reference"
],
"properties": {
"status": {
"enum": [
"repository",
"external-declared",
"external-observed",
"unknown"
]
},
"provider": {
"type": [
"string",
"null"
]
},
"evidence": {
"type": "array",
"items": {
"type": "string"
},
"uniqueItems": true
},
"reference": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"buildProvenance": {
"type": "object",
"description": "Non-structural provenance for the model command execution. It is excluded from the canonical workspace-model hash.",
"required": [
"schemaVersion",
"mode",
"outcome",
"engineStatus"
],
"properties": {
"schemaVersion": {
"const": "workspace-model-build.v1"
},
"mode": {
"enum": [
"full",
"cache",
"incremental"
]
},
"outcome": {
"enum": [
"rebuilt",
"partially-reused",
"reused"
]
},
"engineStatus": {
"enum": [
"disabled",
"miss",
"hit",
"full",
"incremental",
"unchanged"
]
}
},
"additionalProperties": false
},
"factFreshness": {
"type": "object",
"required": [
"schemaVersion",
"kind",
"category",
"generatedAt",
"ttlSeconds",
"status",
"verifyBeforeUse",
"reason"
],
"properties": {
"schemaVersion": {
"const": "rapidkit-fact-freshness-v1"
},
"kind": {
"enum": [
"durable",
"derived",
"evidence-backed",
"live",
"verify-before-use"
]
},
"category": {
"enum": [
"structure",
"verification",
"state"
]
},
"generatedAt": {
"type": "string",
"format": "date-time"
},
"ttlSeconds": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"status": {
"enum": [
"fresh",
"stale",
"unknown"
]
},
"verifyBeforeUse": {
"type": "boolean"
},
"sourceArtifact": {
"type": "string"
},
"sourcePath": {
"type": "string"
},
"inputsHash": {
"type": "string"
},
"reason": {
"type": "string"
}
},
"additionalProperties": false
},
"workspaceFact": {
"type": "object",
"required": [
"id",
"label",
"scope",
"value",
"freshness"
],
"properties": {
"id": {
"type": "string"
},
"label": {
"type": "string"
},
"scope": {
"enum": [
"workspace",
"project",
"evidence",
"policy",
"contract",
"command",
"graph"
]
},
"project": {
"type": "string"
},
"value": true,
"freshness": {
"$ref": "#/$defs/factFreshness"
}
},
"additionalProperties": false
},
"factFreshnessSummary": {
"type": "object",
"required": [
"schemaVersion",
"generatedAt",
"status",
"totalFacts",
"staleFacts",
"unknownFacts",
"liveFacts",
"verifyBeforeUseFacts",
"byKind",
"byCategory"
],
"properties": {
"schemaVersion": {
"const": "rapidkit-fact-freshness-v1"
},
"generatedAt": {
"type": "string",
"format": "date-time"
},
"status": {
"enum": [
"fresh",
"stale",
"unknown"
]
},
"totalFacts": {
"type": "integer",
"minimum": 0
},
"staleFacts": {
"type": "integer",
"minimum": 0
},
"unknownFacts": {
"type": "integer",
"minimum": 0
},
"liveFacts": {
"type": "integer",
"minimum": 0
},
"verifyBeforeUseFacts": {
"type": "integer",
"minimum": 0
},
"byKind": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"byCategory": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
},
"additionalProperties": false
}
},
"additionalProperties": true
}