Workspace Intelligence / JSON Schema
Workspai Workspace Knowledge Graph Change Overlay
Portable graph-to-graph entity and relation changes with bounded impact and proof artifact projection.
- Schema version
workspace-knowledge-graph-change-overlay.v1- Contract path
contracts/workspace-intelligence/workspace-knowledge-graph-change-overlay.v1.json- Publication
- json-schema
- Defined fields
- 43
- 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/changes/change-id/actual-overlay.json | workspace-knowledge-graph-change-overlay.v1 | workspai change verify |
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.changeSet.added | any | Yes | Defines the added value at this contract boundary. | — |
| $defs.changeSet.changed | any | Yes | Defines the changed value at this contract boundary. | — |
| $defs.changeSet.removed | any | Yes | Defines the removed value at this contract boundary. | — |
| $defs.entityChange.after | reference | Yes | Defines the after value at this contract boundary. | ref: workspace-knowledge-graph.v1.json#/properties/entities/items |
| $defs.entityChange.before | reference | Yes | Defines the before value at this contract boundary. | ref: workspace-knowledge-graph.v1.json#/properties/entities/items |
| $defs.entityChange.changedFields | array | Yes | Defines the changedfields value at this contract boundary. | minItems: 1 |
| $defs.entityChange.id | string | Yes | Defines the id value at this contract boundary. | minLength: 1 |
| $defs.graphRevision.fingerprint | string | Yes | Defines the fingerprint value at this contract boundary. | pattern: ^[a-f0-9]{64}$ |
| $defs.graphRevision.generatedAt | string | Yes | Defines the generatedat value at this contract boundary. | format: date-time |
| $defs.graphRevision.schemaVersion | string | Yes | Defines the schemaversion value at this contract boundary. | const: "workspace-knowledge-graph.v1" |
| $defs.proofChange.after | reference | Yes | Defines the after value at this contract boundary. | ref: workspace-knowledge-graph.v1.json#/properties/proofs/items |
| $defs.proofChange.before | reference | Yes | Defines the before value at this contract boundary. | ref: workspace-knowledge-graph.v1.json#/properties/proofs/items |
| $defs.proofChange.changedFields | array | Yes | Defines the changedfields value at this contract boundary. | minItems: 1 |
| $defs.proofChange.id | string | Yes | Defines the id value at this contract boundary. | minLength: 1 |
| $defs.relationChange.after | reference | Yes | Defines the after value at this contract boundary. | ref: workspace-knowledge-graph.v1.json#/properties/relations/items |
| $defs.relationChange.before | reference | Yes | Defines the before value at this contract boundary. | ref: workspace-knowledge-graph.v1.json#/properties/relations/items |
| $defs.relationChange.changedFields | array | Yes | Defines the changedfields value at this contract boundary. | minItems: 1 |
| $defs.relationChange.id | string | Yes | Defines the id value at this contract boundary. | minLength: 1 |
| base | reference | Yes | Defines the base value at this contract boundary. | ref: #/$defs/graphRevision |
| changedArtifacts | array | Yes | Defines the changedartifacts value at this contract boundary. | — |
| entities | any | Yes | Defines the entities value at this contract boundary. | — |
| generatedAt | string | Yes | Defines the generatedat value at this contract boundary. | format: date-time |
| head | reference | Yes | Defines the head value at this contract boundary. | ref: #/$defs/graphRevision |
| impactedEntityIds | array | Yes | Defines the impactedentityids value at this contract boundary. | — |
| proofs | any | Yes | Defines the proofs value at this contract boundary. | — |
| relations | any | Yes | Defines the relations value at this contract boundary. | — |
| schemaVersion | string | Yes | Defines the schemaversion value at this contract boundary. | const: "workspace-knowledge-graph-change-overlay.v1" |
| summary | object | Yes | Defines the summary value at this contract boundary. | additionalProperties: false |
| summary.changedArtifacts | integer | Yes | Defines the changedartifacts value at this contract boundary. | minimum: 0 |
| summary.entityAdds | integer | Yes | Defines the entityadds value at this contract boundary. | minimum: 0 |
| summary.entityChanges | integer | Yes | Defines the entitychanges value at this contract boundary. | minimum: 0 |
| summary.entityRemovals | integer | Yes | Defines the entityremovals value at this contract boundary. | minimum: 0 |
| summary.impactedEntities | integer | Yes | Defines the impactedentities value at this contract boundary. | minimum: 0 |
| summary.proofAdds | integer | Yes | Defines the proofadds value at this contract boundary. | minimum: 0 |
| summary.proofChanges | integer | Yes | Defines the proofchanges value at this contract boundary. | minimum: 0 |
| summary.proofRemovals | integer | Yes | Defines the proofremovals value at this contract boundary. | minimum: 0 |
| summary.relationAdds | integer | Yes | Defines the relationadds value at this contract boundary. | minimum: 0 |
| summary.relationChanges | integer | Yes | Defines the relationchanges value at this contract boundary. | minimum: 0 |
| summary.relationRemovals | integer | Yes | Defines the relationremovals value at this contract boundary. | minimum: 0 |
| summary.risk | enum | Yes | Defines the risk value at this contract boundary. | enum: none, low, medium, high |
| 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://workspai.dev/schemas/workspace-intelligence/workspace-knowledge-graph-change-overlay.v1.json",
"title": "Workspai Workspace Knowledge Graph Change Overlay",
"description": "Portable graph-to-graph entity and relation changes with bounded impact and proof artifact projection.",
"type": "object",
"required": [
"schemaVersion",
"generatedAt",
"workspace",
"base",
"head",
"entities",
"relations",
"proofs",
"impactedEntityIds",
"changedArtifacts",
"summary"
],
"properties": {
"schemaVersion": {
"const": "workspace-knowledge-graph-change-overlay.v1"
},
"generatedAt": {
"type": "string",
"format": "date-time"
},
"workspace": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"profile": {
"type": "string"
}
},
"additionalProperties": false
},
"base": {
"$ref": "#/$defs/graphRevision"
},
"head": {
"$ref": "#/$defs/graphRevision"
},
"entities": {
"allOf": [
{
"$ref": "#/$defs/changeSet"
},
{
"type": "object",
"properties": {
"added": {
"type": "array",
"items": {
"$ref": "workspace-knowledge-graph.v1.json#/properties/entities/items"
}
},
"removed": {
"type": "array",
"items": {
"$ref": "workspace-knowledge-graph.v1.json#/properties/entities/items"
}
},
"changed": {
"type": "array",
"items": {
"$ref": "#/$defs/entityChange"
}
}
}
}
]
},
"relations": {
"allOf": [
{
"$ref": "#/$defs/changeSet"
},
{
"type": "object",
"properties": {
"added": {
"type": "array",
"items": {
"$ref": "workspace-knowledge-graph.v1.json#/properties/relations/items"
}
},
"removed": {
"type": "array",
"items": {
"$ref": "workspace-knowledge-graph.v1.json#/properties/relations/items"
}
},
"changed": {
"type": "array",
"items": {
"$ref": "#/$defs/relationChange"
}
}
}
}
]
},
"proofs": {
"allOf": [
{
"$ref": "#/$defs/changeSet"
},
{
"type": "object",
"properties": {
"added": {
"type": "array",
"items": {
"$ref": "workspace-knowledge-graph.v1.json#/properties/proofs/items"
}
},
"removed": {
"type": "array",
"items": {
"$ref": "workspace-knowledge-graph.v1.json#/properties/proofs/items"
}
},
"changed": {
"type": "array",
"items": {
"$ref": "#/$defs/proofChange"
}
}
}
}
]
},
"impactedEntityIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"uniqueItems": true
},
"changedArtifacts": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"not": {
"pattern": "^(?:/|[A-Za-z]:[\\\\/])"
}
},
"uniqueItems": true
},
"summary": {
"type": "object",
"required": [
"entityAdds",
"entityRemovals",
"entityChanges",
"relationAdds",
"relationRemovals",
"relationChanges",
"proofAdds",
"proofRemovals",
"proofChanges",
"impactedEntities",
"changedArtifacts",
"risk"
],
"properties": {
"entityAdds": {
"type": "integer",
"minimum": 0
},
"entityRemovals": {
"type": "integer",
"minimum": 0
},
"entityChanges": {
"type": "integer",
"minimum": 0
},
"relationAdds": {
"type": "integer",
"minimum": 0
},
"relationRemovals": {
"type": "integer",
"minimum": 0
},
"relationChanges": {
"type": "integer",
"minimum": 0
},
"proofAdds": {
"type": "integer",
"minimum": 0
},
"proofRemovals": {
"type": "integer",
"minimum": 0
},
"proofChanges": {
"type": "integer",
"minimum": 0
},
"impactedEntities": {
"type": "integer",
"minimum": 0
},
"changedArtifacts": {
"type": "integer",
"minimum": 0
},
"risk": {
"enum": [
"none",
"low",
"medium",
"high"
]
}
},
"additionalProperties": false
}
},
"$defs": {
"graphRevision": {
"type": "object",
"required": [
"schemaVersion",
"generatedAt",
"fingerprint"
],
"properties": {
"schemaVersion": {
"const": "workspace-knowledge-graph.v1"
},
"generatedAt": {
"type": "string",
"format": "date-time"
},
"fingerprint": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"additionalProperties": false
},
"changeSet": {
"type": "object",
"required": [
"added",
"removed",
"changed"
],
"properties": {
"added": {},
"removed": {},
"changed": {}
}
},
"entityChange": {
"type": "object",
"required": [
"id",
"before",
"after",
"changedFields"
],
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"before": {
"$ref": "workspace-knowledge-graph.v1.json#/properties/entities/items"
},
"after": {
"$ref": "workspace-knowledge-graph.v1.json#/properties/entities/items"
},
"changedFields": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"uniqueItems": true
}
},
"additionalProperties": false
},
"relationChange": {
"type": "object",
"required": [
"id",
"before",
"after",
"changedFields"
],
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"before": {
"$ref": "workspace-knowledge-graph.v1.json#/properties/relations/items"
},
"after": {
"$ref": "workspace-knowledge-graph.v1.json#/properties/relations/items"
},
"changedFields": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"uniqueItems": true
}
},
"additionalProperties": false
},
"proofChange": {
"type": "object",
"required": [
"id",
"before",
"after",
"changedFields"
],
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"before": {
"$ref": "workspace-knowledge-graph.v1.json#/properties/proofs/items"
},
"after": {
"$ref": "workspace-knowledge-graph.v1.json#/properties/proofs/items"
},
"changedFields": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"uniqueItems": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}