{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://deciduous.dev/schema/decision-graph.schema.json",
"title": "Decision Graph Schema",
"description": "Canonical type definitions for the Deciduous decision graph. Used by TUI (Rust), Web (TypeScript), and API.",
"version": "1.0.0",
"definitions": {
"NodeType": {
"type": "string",
"enum": ["goal", "decision", "option", "action", "outcome", "observation", "revisit"],
"description": "Valid node types in the decision graph"
},
"NodeStatus": {
"type": "string",
"enum": ["pending", "active", "completed", "rejected"],
"description": "Valid node statuses"
},
"EdgeType": {
"type": "string",
"enum": ["leads_to", "requires", "chosen", "rejected", "blocks", "enables"],
"description": "Valid edge types connecting nodes"
},
"NodeMetadata": {
"type": "object",
"description": "Metadata stored as JSON string in metadata_json field",
"properties": {
"confidence": {
"type": "integer",
"minimum": 0,
"maximum": 100,
"description": "Confidence score 0-100"
},
"commit": {
"type": "string",
"description": "Git commit hash (full 40 chars or short 7 chars)"
},
"prompt": {
"type": "string",
"description": "User prompt that triggered this decision"
},
"files": {
"type": "array",
"items": { "type": "string" },
"description": "Associated files"
},
"branch": {
"type": "string",
"description": "Git branch this node was created on"
}
},
"additionalProperties": true
},
"DecisionNode": {
"type": "object",
"description": "A node in the decision graph",
"required": ["id", "change_id", "node_type", "title", "status", "created_at", "updated_at"],
"properties": {
"id": {
"type": "integer",
"description": "Local database primary key (machine-specific)"
},
"change_id": {
"type": "string",
"format": "uuid",
"description": "Globally unique identifier for sync across machines"
},
"node_type": {
"$ref": "#/definitions/NodeType"
},
"title": {
"type": "string",
"description": "Short title for the node"
},
"description": {
"type": ["string", "null"],
"description": "Longer description (optional)"
},
"status": {
"$ref": "#/definitions/NodeStatus"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp when node was created"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp when node was last updated"
},
"metadata_json": {
"type": ["string", "null"],
"description": "JSON string containing NodeMetadata"
}
}
},
"DecisionEdge": {
"type": "object",
"description": "An edge connecting two nodes in the decision graph",
"required": ["id", "from_node_id", "to_node_id", "edge_type", "created_at"],
"properties": {
"id": {
"type": "integer",
"description": "Local database primary key"
},
"from_node_id": {
"type": "integer",
"description": "Source node ID (local)"
},
"to_node_id": {
"type": "integer",
"description": "Target node ID (local)"
},
"from_change_id": {
"type": ["string", "null"],
"format": "uuid",
"description": "Source node change_id (for sync)"
},
"to_change_id": {
"type": ["string", "null"],
"format": "uuid",
"description": "Target node change_id (for sync)"
},
"edge_type": {
"$ref": "#/definitions/EdgeType"
},
"weight": {
"type": ["number", "null"],
"default": 1.0,
"description": "Edge weight for graph algorithms"
},
"rationale": {
"type": ["string", "null"],
"description": "Explanation for why this edge exists"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp when edge was created"
}
}
},
"GraphData": {
"type": "object",
"description": "Full graph data structure for export/API",
"required": ["nodes", "edges"],
"properties": {
"nodes": {
"type": "array",
"items": { "$ref": "#/definitions/DecisionNode" }
},
"edges": {
"type": "array",
"items": { "$ref": "#/definitions/DecisionEdge" }
}
}
},
"ConfidenceLevel": {
"type": "string",
"enum": ["high", "med", "low"],
"description": "Confidence level category (high >= 70, med >= 40, low < 40)"
}
},
"type": "object",
"$ref": "#/definitions/GraphData"
}