Workspace Intelligence / JSON Schema
Workspai Evidence-backed Workspace Knowledge Graph
Portable, provider-neutral workspace entities, relations and proof paths with the canonical project dependency topology embedded as a projection.
- Schema version
workspace-knowledge-graph.v1- Contract path
contracts/workspace-intelligence/workspace-knowledge-graph.v1.json- Publication
- embedded-type, json-schema
- Defined fields
- 73
- 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.
Produced artifacts
These durable files are emitted by registered commands and validated against this contract.
| Artifact path | Schema | Producer |
|---|---|---|
| .workspai/reports/workspace-knowledge-graph.json | workspace-knowledge-graph.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 |
|---|---|---|---|---|
| diagnostics | array | Yes | Defines the diagnostics value at this contract boundary. | — |
| diagnostics[].code | string | Yes | Defines the code value at this contract boundary. | minLength: 1 |
| diagnostics[].entityIds | array | No | Defines the entityids value at this contract boundary. | — |
| diagnostics[].message | string | Yes | Defines the message value at this contract boundary. | minLength: 1 |
| diagnostics[].recommendation | string | No | Defines the recommendation value at this contract boundary. | — |
| diagnostics[].relationIds | array | No | Defines the relationids value at this contract boundary. | — |
| diagnostics[].severity | enum | Yes | Defines the severity value at this contract boundary. | enum: info, warning, error |
| entities | array | Yes | Defines the entities value at this contract boundary. | — |
| entities[].attributes | object | Yes | Defines the attributes value at this contract boundary. | — |
| entities[].id | string | Yes | Defines the id value at this contract boundary. | minLength: 1 |
| entities[].identity | object | Yes | Defines the identity value at this contract boundary. | additionalProperties: false |
| entities[].identity.aliases | array | Yes | Defines the aliases value at this contract boundary. | — |
| entities[].identity.fingerprint | string | Yes | Defines the fingerprint value at this contract boundary. | pattern: ^[a-f0-9]{64}$ |
| entities[].identity.key | string | Yes | Defines the key value at this contract boundary. | minLength: 1 |
| entities[].identity.scope | enum | Yes | Defines the scope value at this contract boundary. | enum: workspace, project |
| entities[].kind | enum | Yes | Defines the kind value at this contract boundary. | enum: workspace, project, service, api, endpoint, schema, package, module, file, symbol, database, queue, container, deployment, pipeline, environment, document, decision, test-suite, owner |
| entities[].label | string | Yes | Defines the label value at this contract boundary. | minLength: 1 |
| entities[].projectId | string | No | Defines the projectid value at this contract boundary. | minLength: 1 |
| entities[].proofIds | array | Yes | Defines the proofids value at this contract boundary. | — |
| generatedAt | string | Yes | Defines the generatedat value at this contract boundary. | format: date-time |
| projectTopology | reference | Yes | Defines the projecttopology value at this contract boundary. | ref: workspace-dependency-graph.v1.json |
| proofs | array | Yes | Defines the proofs value at this contract boundary. | — |
| proofs[].artifact | string | Yes | Defines the artifact value at this contract boundary. | minLength: 1 |
| proofs[].column | integer | No | Defines the column value at this contract boundary. | minimum: 1 |
| proofs[].confidence | enum | Yes | Defines the confidence value at this contract boundary. | enum: high, medium, low |
| proofs[].contentHash | string | No | Defines the contenthash value at this contract boundary. | pattern: ^[a-f0-9]{64}$ |
| proofs[].derivation | enum | Yes | Defines the derivation value at this contract boundary. | enum: extracted, inferred, authored |
| proofs[].detail | string | No | Defines the detail value at this contract boundary. | — |
| proofs[].freshness | enum | Yes | Defines the freshness value at this contract boundary. | enum: fresh, stale, unknown |
| proofs[].id | string | Yes | Defines the id value at this contract boundary. | minLength: 1 |
| proofs[].line | integer | No | Defines the line value at this contract boundary. | minimum: 1 |
| proofs[].observedAt | string | Yes | Defines the observedat value at this contract boundary. | format: date-time |
| proofs[].pointer | string | No | Defines the pointer value at this contract boundary. | — |
| proofs[].provider | string | Yes | Defines the provider value at this contract boundary. | minLength: 1 |
| proofs[].trust | enum | Yes | Defines the trust value at this contract boundary. | enum: authoritative, corroborated, observed, ambiguous |
| providers | array | Yes | Defines the providers value at this contract boundary. | — |
| providers[].diagnostics | array | Yes | Defines the diagnostics value at this contract boundary. | — |
| providers[].discoveredEntities | integer | Yes | Defines the discoveredentities value at this contract boundary. | minimum: 0 |
| providers[].discoveredRelations | integer | Yes | Defines the discoveredrelations value at this contract boundary. | minimum: 0 |
| providers[].id | string | Yes | Defines the id value at this contract boundary. | minLength: 1 |
| providers[].permission | enum | Yes | Defines the permission value at this contract boundary. | enum: filesystem-read, git-read, runtime-probe, network |
| providers[].proofCount | integer | Yes | Defines the proofcount value at this contract boundary. | minimum: 0 |
| providers[].status | enum | Yes | Defines the status value at this contract boundary. | enum: passed, partial, skipped, failed |
| providers[].version | string | Yes | Defines the version value at this contract boundary. | minLength: 1 |
| quality | object | Yes | Defines the quality value at this contract boundary. | additionalProperties: false |
| quality.conflictCount | integer | Yes | Defines the conflictcount value at this contract boundary. | minimum: 0 |
| quality.entityCount | integer | Yes | Defines the entitycount value at this contract boundary. | minimum: 0 |
| quality.entityProofCoverageRatio | number | Yes | Defines the entityproofcoverageratio value at this contract boundary. | minimum: 0 · maximum: 1 |
| quality.portable | boolean | Yes | Defines the portable value at this contract boundary. | const: true |
| quality.proofCount | integer | Yes | Defines the proofcount value at this contract boundary. | minimum: 0 |
| quality.providerSuccessRatio | number | Yes | Defines the providersuccessratio value at this contract boundary. | minimum: 0 · maximum: 1 |
| quality.relationCount | integer | Yes | Defines the relationcount value at this contract boundary. | minimum: 0 |
| quality.relationProofCoverageRatio | number | Yes | Defines the relationproofcoverageratio value at this contract boundary. | minimum: 0 · maximum: 1 |
| quality.secretValuesEmitted | boolean | Yes | Defines the secretvaluesemitted value at this contract boundary. | const: false |
| quality.unknownCount | integer | Yes | Defines the unknowncount value at this contract boundary. | minimum: 0 |
| relations | array | Yes | Defines the relations value at this contract boundary. | — |
| relations[].confidence | enum | Yes | Defines the confidence value at this contract boundary. | enum: high, medium, low |
| relations[].derivation | enum | Yes | Defines the derivation value at this contract boundary. | enum: extracted, inferred, authored |
| relations[].from | string | Yes | Defines the from value at this contract boundary. | minLength: 1 |
| relations[].id | string | Yes | Defines the id value at this contract boundary. | minLength: 1 |
| relations[].kind | enum | Yes | Defines the kind value at this contract boundary. | enum: contains, defines, imports, depends-on, exposes, implements, calls, reads-from, writes-to, publishes, consumes, deploys, runs-on, routes-to, documents, decided-by, tests, owns, generated-by, configured-by, references |
| relations[].proofIds | array | Yes | Defines the proofids value at this contract boundary. | minItems: 1 |
| relations[].to | string | Yes | Defines the to value at this contract boundary. | minLength: 1 |
| relations[].trust | enum | Yes | Defines the trust value at this contract boundary. | enum: authoritative, corroborated, observed, ambiguous |
| schemaVersion | string | Yes | Defines the schemaversion value at this contract boundary. | const: "workspace-knowledge-graph.v1" |
| source | object | Yes | Defines the source value at this contract boundary. | additionalProperties: false |
| source.artifact | string | Yes | Defines the artifact value at this contract boundary. | minLength: 1 |
| source.hash | string | Yes | Defines the hash value at this contract boundary. | pattern: ^[a-f0-9]{64}$ |
| source.hashAlgorithm | string | Yes | Defines the hashalgorithm value at this contract boundary. | const: "sha256" |
| source.kind | enum | Yes | Defines the kind value at this contract boundary. | enum: workspace-model, workspace-contract, workspace-sources |
| workspace | object | Yes | Defines the workspace value at this contract boundary. | additionalProperties: false |
| workspace.name | string | Yes | Defines the name value at this contract boundary. | minLength: 1 |
| workspace.profile | string | No | Defines the profile 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://getrapidkit.com/schemas/workspace-knowledge-graph.v1.json",
"title": "Workspai Evidence-backed Workspace Knowledge Graph",
"description": "Portable, provider-neutral workspace entities, relations and proof paths with the canonical project dependency topology embedded as a projection.",
"type": "object",
"required": [
"schemaVersion",
"generatedAt",
"source",
"workspace",
"projectTopology",
"entities",
"relations",
"proofs",
"providers",
"quality",
"diagnostics"
],
"properties": {
"schemaVersion": {
"const": "workspace-knowledge-graph.v1"
},
"generatedAt": {
"type": "string",
"format": "date-time"
},
"source": {
"type": "object",
"required": [
"kind",
"artifact",
"hashAlgorithm",
"hash"
],
"properties": {
"kind": {
"enum": [
"workspace-model",
"workspace-contract",
"workspace-sources"
]
},
"artifact": {
"type": "string",
"minLength": 1
},
"hashAlgorithm": {
"const": "sha256"
},
"hash": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"additionalProperties": false
},
"workspace": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"profile": {
"type": "string"
}
},
"additionalProperties": false
},
"projectTopology": {
"$ref": "workspace-dependency-graph.v1.json"
},
"entities": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"kind",
"label",
"identity",
"attributes",
"proofIds"
],
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"kind": {
"enum": [
"workspace",
"project",
"service",
"api",
"endpoint",
"schema",
"package",
"module",
"file",
"symbol",
"database",
"queue",
"container",
"deployment",
"pipeline",
"environment",
"document",
"decision",
"test-suite",
"owner"
]
},
"label": {
"type": "string",
"minLength": 1
},
"projectId": {
"type": "string",
"minLength": 1
},
"identity": {
"type": "object",
"required": [
"key",
"scope",
"aliases",
"fingerprint"
],
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"scope": {
"enum": [
"workspace",
"project"
]
},
"aliases": {
"type": "array",
"items": {
"type": "string"
}
},
"fingerprint": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"additionalProperties": false
},
"attributes": {
"type": "object",
"additionalProperties": {
"type": [
"string",
"number",
"boolean",
"null",
"array"
],
"items": {
"type": [
"string",
"number",
"boolean",
"null"
]
}
}
},
"proofIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"uniqueItems": true
}
},
"additionalProperties": false
}
},
"relations": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"from",
"to",
"kind",
"derivation",
"trust",
"confidence",
"proofIds"
],
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"from": {
"type": "string",
"minLength": 1
},
"to": {
"type": "string",
"minLength": 1
},
"kind": {
"enum": [
"contains",
"defines",
"imports",
"depends-on",
"exposes",
"implements",
"calls",
"reads-from",
"writes-to",
"publishes",
"consumes",
"deploys",
"runs-on",
"routes-to",
"documents",
"decided-by",
"tests",
"owns",
"generated-by",
"configured-by",
"references"
]
},
"derivation": {
"enum": [
"extracted",
"inferred",
"authored"
]
},
"trust": {
"enum": [
"authoritative",
"corroborated",
"observed",
"ambiguous"
]
},
"confidence": {
"enum": [
"high",
"medium",
"low"
]
},
"proofIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"uniqueItems": true
}
},
"additionalProperties": false
}
},
"proofs": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"provider",
"artifact",
"observedAt",
"derivation",
"trust",
"confidence",
"freshness"
],
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"provider": {
"type": "string",
"minLength": 1
},
"artifact": {
"type": "string",
"minLength": 1,
"not": {
"pattern": "^(?:/|[A-Za-z]:[\\\\/])"
}
},
"pointer": {
"type": "string"
},
"line": {
"type": "integer",
"minimum": 1
},
"column": {
"type": "integer",
"minimum": 1
},
"contentHash": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"observedAt": {
"type": "string",
"format": "date-time"
},
"derivation": {
"enum": [
"extracted",
"inferred",
"authored"
]
},
"trust": {
"enum": [
"authoritative",
"corroborated",
"observed",
"ambiguous"
]
},
"confidence": {
"enum": [
"high",
"medium",
"low"
]
},
"freshness": {
"enum": [
"fresh",
"stale",
"unknown"
]
},
"detail": {
"type": "string"
}
},
"additionalProperties": false
}
},
"providers": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"version",
"status",
"permission",
"discoveredEntities",
"discoveredRelations",
"proofCount",
"diagnostics"
],
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"version": {
"type": "string",
"minLength": 1
},
"status": {
"enum": [
"passed",
"partial",
"skipped",
"failed"
]
},
"permission": {
"enum": [
"filesystem-read",
"git-read",
"runtime-probe",
"network"
]
},
"discoveredEntities": {
"type": "integer",
"minimum": 0
},
"discoveredRelations": {
"type": "integer",
"minimum": 0
},
"proofCount": {
"type": "integer",
"minimum": 0
},
"diagnostics": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
},
"quality": {
"type": "object",
"required": [
"entityCount",
"relationCount",
"proofCount",
"entityProofCoverageRatio",
"relationProofCoverageRatio",
"providerSuccessRatio",
"conflictCount",
"unknownCount",
"portable",
"secretValuesEmitted"
],
"properties": {
"entityCount": {
"type": "integer",
"minimum": 0
},
"relationCount": {
"type": "integer",
"minimum": 0
},
"proofCount": {
"type": "integer",
"minimum": 0
},
"entityProofCoverageRatio": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"relationProofCoverageRatio": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"providerSuccessRatio": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"conflictCount": {
"type": "integer",
"minimum": 0
},
"unknownCount": {
"type": "integer",
"minimum": 0
},
"portable": {
"const": true
},
"secretValuesEmitted": {
"const": false
}
},
"additionalProperties": false
},
"diagnostics": {
"type": "array",
"items": {
"type": "object",
"required": [
"code",
"severity",
"message"
],
"properties": {
"code": {
"type": "string",
"minLength": 1
},
"severity": {
"enum": [
"info",
"warning",
"error"
]
},
"message": {
"type": "string",
"minLength": 1
},
"entityIds": {
"type": "array",
"items": {
"type": "string"
}
},
"relationIds": {
"type": "array",
"items": {
"type": "string"
}
},
"recommendation": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}