{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://dss.overbits.luz.uy/schemas/api.schema.json",
  "title": "DSS API Schema",
  "description": "Machine-readable API specification for Design System Server MCP tools",
  "version": "2.0.0",
  "x-immutable-notice": {
    "protected": true,
    "reason": "Core API specification - prevents unauthorized tool signature changes",
    "lastModified": "2025-12-09",
    "bypassMethod": "Use 'DSS_IMMUTABLE_BYPASS=1 git commit' or commit message '[IMMUTABLE-UPDATE] reason'"
  },
  "type": "object",
  "properties": {
    "tools": {
      "type": "object",
      "description": "MCP tools available in DSS",
      "additionalProperties": {
        "type": "object",
        "required": ["name", "description", "category", "parameters", "returns"],
        "properties": {
          "name": {
            "type": "string",
            "description": "Tool name (matches MCP tool identifier)"
          },
          "description": {
            "type": "string",
            "description": "What this tool does"
          },
          "category": {
            "type": "string",
            "enum": ["token", "figma", "browser", "project", "analysis", "storybook", "core"],
            "description": "Tool category for organization"
          },
          "parameters": {
            "type": "object",
            "description": "Input parameters schema"
          },
          "returns": {
            "type": "object",
            "description": "Return value schema"
          },
          "examples": {
            "type": "array",
            "description": "Usage examples",
            "items": {
              "type": "object",
              "properties": {
                "input": {"type": "object"},
                "output": {"type": "object"},
                "description": {"type": "string"}
              }
            }
          },
          "boundaries": {
            "type": "array",
            "description": "Boundary enforcement rules",
            "items": {
              "type": "string"
            }
          },
          "required_by": {
            "type": "array",
            "description": "Operations that require this tool",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "endpoints": {
      "type": "object",
      "description": "REST API endpoints (if applicable)",
      "additionalProperties": {
        "type": "object",
        "required": ["method", "path", "description"],
        "properties": {
          "method": {
            "type": "string",
            "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"]
          },
          "path": {
            "type": "string",
            "description": "API path pattern"
          },
          "description": {
            "type": "string"
          },
          "requestSchema": {
            "type": "object"
          },
          "responseSchema": {
            "type": "object"
          }
        }
      }
    }
  }
}