DocForge2/schemas/graph-view-plan.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://docforge.local/schema/graph-view-plan-v1.json",
  "title": "DocForge immutable portable graph view plan",
  "$comment": "plan_id is the SHA-256 of canonical JSON without plan_id and is verified by the runtime contract validator. The version-1 nested graph vocabulary remains planner-owned.",
  "$defs": {
    "sha256": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$"
    },
    "project": {
      "type": "object",
      "required": [
        "project_id",
        "project_root_fingerprint",
        "adapter",
        "revision",
        "source_hash"
      ],
      "properties": {
        "project_id": { "type": "string", "minLength": 1 },
        "project_root_fingerprint": {
          "type": "string",
          "pattern": "^[0-9a-f]{16}$"
        },
        "adapter": { "type": "string", "minLength": 1 },
        "revision": { "type": "string", "minLength": 1 },
        "source_hash": { "$ref": "#/$defs/sha256" }
      },
      "additionalProperties": false
    },
    "filter": {
      "type": "array",
      "maxItems": 64,
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 1024
      },
      "uniqueItems": true
    },
    "edge": {
      "type": "object",
      "required": ["source_id", "relation", "target_id"],
      "properties": {
        "source_id": { "type": "string", "minLength": 1 },
        "relation": { "type": "string", "minLength": 1 },
        "target_id": { "type": "string", "minLength": 1 }
      },
      "additionalProperties": false
    },
    "node": {
      "type": "object",
      "required": [
        "node_id",
        "title",
        "family",
        "authority",
        "status",
        "tags",
        "summary",
        "content_hash"
      ],
      "properties": {
        "node_id": { "type": "string", "minLength": 1 },
        "title": { "type": "string", "minLength": 1 },
        "family": { "type": "string", "minLength": 1 },
        "authority": { "type": "string", "minLength": 1 },
        "status": { "type": "string", "minLength": 1 },
        "tags": { "$ref": "#/$defs/filter" },
        "summary": { "type": "string" },
        "content_hash": { "$ref": "#/$defs/sha256" }
      },
      "additionalProperties": false
    },
    "omission": {
      "oneOf": [
        {
          "type": "object",
          "required": ["code", "subject", "limit", "minimum_omitted"],
          "properties": {
            "code": { "const": "node_result_limit" },
            "subject": { "const": "nodes" },
            "limit": { "type": "integer", "minimum": 1, "maximum": 1000 },
            "minimum_omitted": { "type": "integer", "minimum": 1 }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": ["code", "subject", "limit", "minimum_omitted"],
          "properties": {
            "code": { "const": "edge_result_limit" },
            "subject": { "const": "edges" },
            "limit": { "type": "integer", "minimum": 0, "maximum": 4000 },
            "minimum_omitted": { "type": "integer", "minimum": 1 }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "code",
            "subject",
            "limit",
            "examined",
            "minimum_omitted"
          ],
          "properties": {
            "code": { "const": "work_limit" },
            "subject": { "const": "selection" },
            "limit": { "type": "integer", "minimum": 1, "maximum": 1000000 },
            "examined": { "type": "integer", "minimum": 0 },
            "minimum_omitted": { "type": "integer", "minimum": 1 }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": ["code", "subject", "minimum_omitted"],
          "properties": {
            "code": { "const": "logic_forbidden" },
            "subject": { "const": "logic" },
            "minimum_omitted": { "type": "integer", "minimum": 1 }
          },
          "additionalProperties": false
        }
      ]
    }
  },
  "type": "object",
  "required": [
    "schema_version",
    "contract",
    "plan_id",
    "project",
    "view",
    "bounds",
    "policy",
    "graph",
    "omissions",
    "diagnostics"
  ],
  "properties": {
    "schema_version": { "const": 1 },
    "contract": { "const": "docforge.graph-view-plan" },
    "plan_id": { "$ref": "#/$defs/sha256" },
    "project": { "$ref": "#/$defs/project" },
    "view": {
      "type": "object",
      "required": [
        "view_id",
        "title",
        "initial_mode",
        "scope",
        "filters",
        "detail_fields"
      ],
      "properties": {
        "view_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 1024
        },
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 1024
        },
        "initial_mode": { "enum": ["nodes", "flow", "web", "logic"] },
        "scope": {
          "oneOf": [
            {
              "type": "object",
              "required": ["kind", "root_node_id", "depth"],
              "properties": {
                "kind": { "const": "exact_root" },
                "root_node_id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 1024
                },
                "depth": { "type": "integer", "minimum": 1, "maximum": 32 }
              },
              "additionalProperties": false
            },
            {
              "type": "object",
              "required": ["kind", "query"],
              "properties": {
                "kind": { "const": "lexical" },
                "query": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 10000
                }
              },
              "additionalProperties": false
            }
          ]
        },
        "filters": {
          "type": "object",
          "required": [
            "families",
            "relations",
            "authorities",
            "statuses",
            "tags"
          ],
          "properties": {
            "families": { "$ref": "#/$defs/filter" },
            "relations": { "$ref": "#/$defs/filter" },
            "authorities": { "$ref": "#/$defs/filter" },
            "statuses": { "$ref": "#/$defs/filter" },
            "tags": { "$ref": "#/$defs/filter" }
          },
          "additionalProperties": false
        },
        "detail_fields": {
          "const": [
            "node_id",
            "title",
            "family",
            "authority",
            "status",
            "tags",
            "summary",
            "content_hash"
          ]
        }
      },
      "additionalProperties": false
    },
    "bounds": {
      "type": "object",
      "required": ["depth", "max_nodes", "max_edges", "max_work"],
      "properties": {
        "depth": { "type": "integer", "minimum": 1, "maximum": 32 },
        "max_nodes": { "type": "integer", "minimum": 1, "maximum": 1000 },
        "max_edges": { "type": "integer", "minimum": 0, "maximum": 4000 },
        "max_work": { "type": "integer", "minimum": 1, "maximum": 1000000 }
      },
      "additionalProperties": false
    },
    "policy": {
      "type": "object",
      "required": [
        "visibility",
        "source_paths",
        "source_bodies",
        "database_queries",
        "executable_content",
        "logic",
        "logic_requested"
      ],
      "properties": {
        "visibility": { "const": "selected_graph_only" },
        "source_paths": { "const": "excluded" },
        "source_bodies": { "const": "excluded" },
        "database_queries": { "const": "forbidden" },
        "executable_content": { "const": "forbidden" },
        "logic": { "enum": ["allowed", "forbidden"] },
        "logic_requested": { "type": "boolean" }
      },
      "additionalProperties": false
    },
    "graph": {
      "type": "object",
      "required": ["root_node_id", "nodes", "edges", "logic_projections"],
      "properties": {
        "root_node_id": {
          "type": ["string", "null"],
          "minLength": 1,
          "maxLength": 1024
        },
        "nodes": {
          "type": "array",
          "maxItems": 1000,
          "items": { "$ref": "#/$defs/node" }
        },
        "edges": {
          "type": "array",
          "maxItems": 4000,
          "items": { "$ref": "#/$defs/edge" }
        },
        "logic_projections": {
          "type": "array",
          "maxItems": 0
        }
      },
      "additionalProperties": false
    },
    "omissions": {
      "type": "array",
      "maxItems": 4,
      "items": { "$ref": "#/$defs/omission" }
    },
    "diagnostics": {
      "type": "object",
      "required": [
        "selection",
        "returned_nodes",
        "returned_edges",
        "examined_work_units",
        "truncated",
        "ordering"
      ],
      "properties": {
        "selection": { "enum": ["exact_root", "lexical"] },
        "returned_nodes": { "type": "integer", "minimum": 0, "maximum": 1000 },
        "returned_edges": { "type": "integer", "minimum": 0, "maximum": 4000 },
        "examined_work_units": { "type": "integer", "minimum": 0 },
        "truncated": { "type": "boolean" },
        "ordering": { "const": "node_id;source_id,relation,target_id" }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}