DocForge2/schemas/adapter-client-configuration.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://docforge.local/schema/adapter-client-configuration-v1.json",
  "title": "DocForge project-owned adapter client configuration",
  "$defs": {
    "sha256": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$"
    },
    "project": {
      "type": "object",
      "required": [
        "project_id",
        "project_root",
        "project_root_fingerprint",
        "adapter",
        "descriptor_hash"
      ],
      "properties": {
        "project_id": {
          "type": "string",
          "pattern": "^[a-z0-9][a-z0-9._-]{1,127}$"
        },
        "project_root": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "project_root_fingerprint": {
          "type": "string",
          "pattern": "^[0-9a-f]{16}$"
        },
        "adapter": {
          "type": "string",
          "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}@[A-Za-z0-9][A-Za-z0-9_.+-]{0,63}$"
        },
        "descriptor_hash": { "$ref": "#/$defs/sha256" }
      },
      "additionalProperties": false
    },
    "source_availability": {
      "type": "object",
      "required": [
        "schema_version",
        "status",
        "method",
        "revision",
        "source_hash"
      ],
      "properties": {
        "schema_version": { "const": 1 },
        "status": { "const": "available" },
        "method": {
          "enum": ["incremental-state", "complete-projection"]
        },
        "revision": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "source_hash": { "$ref": "#/$defs/sha256" }
      },
      "additionalProperties": false
    },
    "binding": {
      "type": "object",
      "required": [
        "transport",
        "capability_mode",
        "adapter_policy",
        "render_policy",
        "command",
        "args",
        "environment",
        "timeouts",
        "launcher_hash"
      ],
      "properties": {
        "transport": { "const": "stdio" },
        "capability_mode": {
          "enum": ["read", "proposal", "application"]
        },
        "adapter_policy": {
          "$ref": "https://docforge.local/schema/client-configuration-v1.json#/$defs/adapter_policy"
        },
        "render_policy": {
          "type": "object",
          "required": ["manual", "graph", "live_viewer"],
          "properties": {
            "manual": { "enum": ["auto", "explicit", "disabled"] },
            "graph": { "const": "disabled" },
            "live_viewer": { "const": "on-demand" }
          },
          "additionalProperties": false
        },
        "command": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "args": {
          "type": "array",
          "minItems": 7,
          "maxItems": 64,
          "prefixItems": [
            { "const": "-I" },
            { "const": "-m" },
            {
              "type": "string",
              "minLength": 1,
              "maxLength": 255,
              "pattern": "^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*){0,31}$",
              "not": { "const": "docforge.mcp_server" }
            },
            { "const": "--project-root" },
            {
              "type": "string",
              "minLength": 1,
              "maxLength": 4096
            },
            { "const": "--capability-mode" },
            { "enum": ["read", "proposal", "application"] }
          ],
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4096
          }
        },
        "environment": {
          "type": "object",
          "maxProperties": 0
        },
        "timeouts": {
          "type": "object",
          "required": ["startup_seconds", "tool_seconds"],
          "properties": {
            "startup_seconds": {
              "type": "integer",
              "minimum": 1,
              "maximum": 3600
            },
            "tool_seconds": {
              "type": "integer",
              "minimum": 1,
              "maximum": 86400
            }
          },
          "additionalProperties": false
        },
        "launcher_hash": { "$ref": "#/$defs/sha256" }
      },
      "additionalProperties": false
    },
    "projection_availability": {
      "type": "object",
      "required": [
        "manual_configured",
        "portable_graph_configured",
        "application_enabled",
        "live_viewer_available"
      ],
      "properties": {
        "manual_configured": { "type": "boolean" },
        "portable_graph_configured": { "type": "boolean" },
        "application_enabled": { "type": "boolean" },
        "live_viewer_available": { "const": true }
      },
      "additionalProperties": false
    }
  },
  "type": "object",
  "required": [
    "status",
    "schema_version",
    "docforge_version",
    "operation",
    "action",
    "client",
    "server_name",
    "project",
    "launcher",
    "launcher_hash",
    "source_availability",
    "source_availability_hash",
    "binding",
    "effective_policy",
    "projection_policy",
    "projection_policy_hash",
    "projection_availability",
    "artifact",
    "configuration_hash",
    "warnings"
  ],
  "properties": {
    "status": { "const": "ok" },
    "schema_version": { "const": 1 },
    "docforge_version": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "operation": { "const": "adapter_client.configure" },
    "action": { "enum": ["preview", "write"] },
    "client": { "enum": ["codex", "claude", "openclaw"] },
    "server_name": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
    },
    "project": { "$ref": "#/$defs/project" },
    "launcher": {
      "$ref": "https://docforge.local/schema/adapter-launcher-v1.json"
    },
    "launcher_hash": { "$ref": "#/$defs/sha256" },
    "source_availability": {
      "$ref": "#/$defs/source_availability"
    },
    "source_availability_hash": { "$ref": "#/$defs/sha256" },
    "binding": { "$ref": "#/$defs/binding" },
    "effective_policy": {
      "$ref": "https://docforge.local/schema/client-configuration-v1.json#/$defs/effective_policy"
    },
    "projection_policy": {
      "$ref": "https://docforge.local/schema/client-configuration-v1.json#/$defs/projection_policy"
    },
    "projection_policy_hash": { "$ref": "#/$defs/sha256" },
    "projection_availability": {
      "$ref": "#/$defs/projection_availability"
    },
    "artifact": {
      "$ref": "https://docforge.local/schema/client-configuration-v1.json#/properties/artifact"
    },
    "configuration_hash": { "$ref": "#/$defs/sha256" },
    "warnings": {
      "$ref": "https://docforge.local/schema/client-configuration-v1.json#/properties/warnings"
    }
  },
  "allOf": [
    {
      "if": {
        "properties": { "client": { "const": "codex" } },
        "required": ["client"]
      },
      "then": {
        "properties": {
          "artifact": {
            "properties": {
              "format": { "const": "codex-toml-fragment-v1" }
            }
          }
        }
      }
    },
    {
      "if": {
        "properties": { "client": { "const": "claude" } },
        "required": ["client"]
      },
      "then": {
        "properties": {
          "artifact": {
            "properties": {
              "format": { "const": "claude-json-fragment-v1" }
            }
          },
          "warnings": {
            "contains": {
              "properties": {
                "code": { "const": "timeout_format_unverified" }
              },
              "required": ["code"]
            }
          }
        }
      }
    },
    {
      "if": {
        "properties": { "client": { "const": "openclaw" } },
        "required": ["client"]
      },
      "then": {
        "properties": {
          "artifact": {
            "properties": {
              "format": { "const": "openclaw-json-fragment-v1" }
            }
          }
        }
      }
    },
    {
      "if": {
        "properties": { "action": { "const": "preview" } },
        "required": ["action"]
      },
      "then": {
        "properties": {
          "artifact": {
            "properties": {
              "output_path": { "type": "null" },
              "write_state": { "const": "not_requested" },
              "durability": { "const": "not_applicable" }
            }
          }
        }
      },
      "else": {
        "properties": {
          "artifact": {
            "properties": {
              "write_state": { "enum": ["created", "unchanged"] }
            }
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "binding": {
            "properties": {
              "adapter_policy": {
                "properties": {
                  "mode": { "const": "preserve-no-ast" }
                },
                "required": ["mode"]
              }
            },
            "required": ["adapter_policy"]
          }
        },
        "required": ["binding"]
      },
      "then": {
        "properties": {
          "binding": {
            "properties": {
              "args": {
                "contains": { "const": "--no-ast" },
                "minContains": 1,
                "maxContains": 1
              }
            }
          }
        }
      },
      "else": {
        "properties": {
          "binding": {
            "properties": {
              "args": {
                "not": {
                  "contains": { "const": "--no-ast" }
                }
              }
            }
          }
        }
      }
    }
  ],
  "additionalProperties": false
}