{
  "openapi": "3.1.0",
  "info": {
    "title": "Expanso Pipeline Validator API",
    "description": "Hallucination detection service for Benthos/Expanso YAML pipeline configurations. Validates YAML against ground truth schema and detects imagined components, wrong structure, invalid Bloblang syntax, and imagined fields.",
    "version": "1.0.0",
    "contact": {
      "name": "Expanso",
      "url": "https://expanso.io"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://validate.expanso.io",
      "description": "Production"
    }
  ],
  "paths": {
    "/validate": {
      "post": {
        "operationId": "validatePipeline",
        "summary": "Validate pipeline YAML",
        "description": "Validates a Benthos/Expanso pipeline YAML configuration against ground truth schema. Returns detected hallucinations with severity, corrections, and contextual messages.",
        "requestBody": {
          "required": true,
          "content": {
            "text/plain": {
              "schema": {
                "type": "string",
                "description": "Raw YAML pipeline configuration"
              },
              "example": "input:\n  kafka:\n    addresses: [localhost:9092]\n    topics: [events]\noutput:\n  stdout: {}"
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ValidateRequest"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "description": "Return formatted YAML in response",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "auto_correct",
            "in": "query",
            "description": "Attempt to auto-correct common hallucinations",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "summarize",
            "in": "query",
            "description": "Include grouped summary with prioritized top issues",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "max_per_group",
            "in": "query",
            "description": "Maximum hallucinations to show per group (default 3)",
            "schema": {
              "type": "integer",
              "default": 3,
              "minimum": 1
            }
          },
          {
            "name": "llm_format",
            "in": "query",
            "description": "Return LLM-optimized response format with fix instructions",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_metrics",
            "in": "query",
            "description": "Include validation metrics in response for feedback tracking",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Validation passed - no errors found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (missing YAML)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed - hallucinations detected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidateResponse"
                }
              }
            }
          }
        }
      }
    },
    "/schema": {
      "get": {
        "operationId": "getSchema",
        "summary": "Get component schema",
        "description": "Returns the ground truth schema for Benthos/Expanso pipeline components. Can return full schema or filter by component type/name.",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "description": "Filter by component type",
            "schema": {
              "type": "string",
              "enum": [
                "inputs",
                "outputs",
                "processors",
                "caches",
                "rate_limits",
                "buffers",
                "scanners",
                "metrics",
                "tracers"
              ]
            }
          },
          {
            "name": "component",
            "in": "query",
            "description": "Get specific component schema (requires type parameter)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "full",
            "in": "query",
            "description": "Return complete schema including all components",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Schema response",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/SchemaSummary"
                    },
                    {
                      "$ref": "#/components/schemas/SchemaFull"
                    },
                    {
                      "$ref": "#/components/schemas/ComponentSchema"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/components": {
      "get": {
        "operationId": "getComponents",
        "summary": "Component matching examples",
        "description": "Returns examples of fuzzy component name matching. Useful for understanding how typos are corrected.",
        "responses": {
          "200": {
            "description": "Component matching examples",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ComponentsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "healthCheck",
        "summary": "Health check",
        "description": "Returns service health status",
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok"
                      ]
                    }
                  },
                  "required": [
                    "status"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getOpenApiSpec",
        "summary": "OpenAPI specification",
        "description": "Returns this OpenAPI 3.1 specification document",
        "responses": {
          "200": {
            "description": "OpenAPI specification",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/analyze": {
      "post": {
        "operationId": "analyzePipeline",
        "summary": "Analyze pipeline structure",
        "description": "Parses YAML and returns detailed component breakdown, data flow analysis, complexity metrics, and performance hints.",
        "tags": [
          "Analysis"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "text/plain": {
              "schema": {
                "type": "string",
                "description": "Raw YAML pipeline configuration"
              },
              "example": "input:\n  kafka:\n    addresses: [localhost:9092]\n    topics: [events]\npipeline:\n  processors:\n    - mapping: root = this\noutput:\n  stdout: {}"
            }
          }
        },
        "responses": {
          "200": {
            "description": "Pipeline analysis result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyzeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid YAML",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/explain": {
      "post": {
        "operationId": "explainError",
        "summary": "Explain an error message",
        "description": "Takes an error message and optional context, returns detailed explanation with cause, fix suggestions, related documentation, and common mistakes to avoid.",
        "tags": [
          "Analysis"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExplainRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Error explanation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExplainResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/suggest": {
      "post": {
        "operationId": "suggestPatterns",
        "summary": "Suggest pipeline patterns",
        "description": "Takes a natural language use case description and returns scored pipeline suggestions with YAML examples and customization hints.",
        "tags": [
          "Analysis"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SuggestRequest"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of suggestions to return",
            "schema": {
              "type": "integer",
              "default": 5,
              "minimum": 1,
              "maximum": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pattern suggestions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuggestResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/compatibility": {
      "post": {
        "operationId": "checkCompatibility",
        "summary": "Check pipeline best practices",
        "description": "Analyzes YAML for anti-patterns, performance issues, and best practice violations. Returns warnings with suggestions for improvement.",
        "tags": [
          "Analysis"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "text/plain": {
              "schema": {
                "type": "string",
                "description": "Raw YAML pipeline configuration"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Compatibility check result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompatibilityResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid YAML",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/format": {
      "post": {
        "operationId": "formatYaml",
        "summary": "Format YAML",
        "description": "Reformats YAML to canonical style without validation. Useful for editor integrations and consistent formatting.",
        "tags": [
          "Utility"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "text/plain": {
              "schema": {
                "type": "string",
                "description": "Raw YAML pipeline configuration"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Formatted YAML",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FormatResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid YAML syntax",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/metrics/feedback": {
      "post": {
        "operationId": "submitMetricsFeedback",
        "summary": "Submit fix success feedback",
        "description": "Submit feedback on whether an LLM-suggested fix was successful. This helps track fix rates and improve the validation service over time.",
        "tags": [
          "Metrics"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MetricsFeedback"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Feedback received",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetricsFeedbackResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ValidateRequest": {
        "type": "object",
        "description": "JSON request body for validation",
        "properties": {
          "yaml": {
            "type": "string",
            "description": "YAML pipeline configuration to validate"
          },
          "format": {
            "type": "boolean",
            "description": "Return formatted YAML",
            "default": false
          },
          "auto_correct": {
            "type": "boolean",
            "description": "Attempt auto-correction of hallucinations",
            "default": false
          },
          "summarize": {
            "type": "boolean",
            "description": "Include grouped summary with prioritized top issues",
            "default": false
          },
          "max_per_group": {
            "type": "integer",
            "description": "Maximum hallucinations per group (default 3)",
            "default": 3,
            "minimum": 1
          }
        },
        "required": [
          "yaml"
        ]
      },
      "ValidateResponse": {
        "type": "object",
        "description": "Validation result with detected hallucinations",
        "properties": {
          "valid": {
            "type": "boolean",
            "description": "True if no ERROR-severity hallucinations were found"
          },
          "error_count": {
            "type": "integer",
            "description": "Number of ERROR-severity hallucinations",
            "minimum": 0
          },
          "hallucinations": {
            "type": "array",
            "description": "List of detected hallucinations",
            "items": {
              "$ref": "#/components/schemas/Hallucination"
            }
          },
          "corrected_yaml": {
            "type": "string",
            "description": "Auto-corrected YAML (only if auto_correct=true and corrections were made)"
          },
          "formatted_yaml": {
            "type": "string",
            "description": "Formatted YAML (only if format=true)"
          },
          "corrections_made": {
            "type": "array",
            "description": "List of corrections applied (only if auto_correct=true)",
            "items": {
              "type": "string"
            }
          },
          "summary": {
            "$ref": "#/components/schemas/ValidationSummary",
            "description": "Grouped and prioritized summary (only if summarize=true)"
          },
          "request_id": {
            "type": "string",
            "description": "Unique request identifier for feedback tracking (e.g., 'val_m6abc123_xyz789')"
          },
          "metrics": {
            "$ref": "#/components/schemas/ValidationMetrics",
            "description": "Validation metrics (only if include_metrics=true)"
          }
        },
        "required": [
          "valid",
          "error_count",
          "hallucinations",
          "request_id"
        ]
      },
      "Hallucination": {
        "type": "object",
        "description": "A detected hallucination in the pipeline configuration",
        "properties": {
          "category": {
            "$ref": "#/components/schemas/HallucinationType"
          },
          "severity": {
            "$ref": "#/components/schemas/Severity"
          },
          "path": {
            "type": "string",
            "description": "JSON path to the problematic element (e.g., 'input.kafka.brokrs')"
          },
          "hallucination": {
            "type": "string",
            "description": "The hallucinated/incorrect value"
          },
          "correction": {
            "type": "string",
            "nullable": true,
            "description": "Suggested correction (null if no suggestion available)"
          },
          "message": {
            "type": "string",
            "description": "Human-readable error message"
          },
          "line": {
            "type": "integer",
            "nullable": true,
            "description": "Line number in the YAML where the issue was found"
          },
          "context": {
            "type": "string",
            "nullable": true,
            "description": "Surrounding code context with line numbers"
          },
          "snippet_before": {
            "type": "string",
            "nullable": true,
            "description": "Code snippet before correction (for visual comparison)"
          },
          "snippet_after": {
            "type": "string",
            "nullable": true,
            "description": "Code snippet after correction (for visual comparison)"
          }
        },
        "required": [
          "category",
          "severity",
          "path",
          "hallucination",
          "message"
        ]
      },
      "HallucinationType": {
        "type": "string",
        "description": "Category of hallucination detected",
        "enum": [
          "IMAGINED_COMPONENT",
          "IMAGINED_FIELD",
          "IMAGINED_STRUCTURE",
          "IMAGINED_SYNTAX",
          "WRONG_TYPE",
          "DUPLICATE_LABEL",
          "UNDEFINED_RESOURCE",
          "POTENTIAL_LOOP",
          "UNREACHABLE_CODE",
          "UNKNOWN"
        ],
        "x-enum-descriptions": {
          "IMAGINED_COMPONENT": "Component name does not exist (e.g., 'kafak' instead of 'kafka')",
          "IMAGINED_FIELD": "Field does not exist on the component (e.g., 'brokrs' instead of 'brokers')",
          "IMAGINED_STRUCTURE": "Wrong configuration structure (e.g., Kubernetes wrappers, wrong nesting)",
          "IMAGINED_SYNTAX": "Invalid Bloblang syntax (e.g., JavaScript/Python patterns instead of Bloblang)",
          "WRONG_TYPE": "Incorrect value type for field (e.g., string instead of number)",
          "DUPLICATE_LABEL": "Duplicate processor label within pipeline",
          "UNDEFINED_RESOURCE": "Reference to undefined resource (cache, rate_limit, etc.)",
          "POTENTIAL_LOOP": "Same resource used for input and output (e.g., same Kafka topic, S3 bucket)",
          "UNREACHABLE_CODE": "Code that will never execute (e.g., processors after drop/reject, dead switch branches)",
          "UNKNOWN": "Unclassified validation error"
        }
      },
      "Severity": {
        "type": "string",
        "description": "Severity level of the hallucination",
        "enum": [
          "ERROR",
          "WARNING",
          "INFO"
        ],
        "x-enum-descriptions": {
          "ERROR": "Critical issue that will cause pipeline failure",
          "WARNING": "Potential issue or deprecated usage",
          "INFO": "Informational suggestion for improvement"
        }
      },
      "SchemaSummary": {
        "type": "object",
        "description": "Summary of available schema with component counts",
        "properties": {
          "title": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "description": "Where the schema was harvested from"
          },
          "harvested_at": {
            "type": "string",
            "format": "date-time"
          },
          "component_types": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                },
                "count": {
                  "type": "integer"
                }
              }
            }
          },
          "usage": {
            "type": "object",
            "description": "API usage examples"
          }
        }
      },
      "SchemaFull": {
        "type": "object",
        "description": "Complete component schema",
        "properties": {
          "$schema": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "components": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "additionalProperties": {
                "$ref": "#/components/schemas/ComponentSchema"
              }
            }
          }
        }
      },
      "ComponentSchema": {
        "type": "object",
        "description": "Schema for a single pipeline component",
        "properties": {
          "fields": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/FieldSchema"
            }
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of required field names"
          }
        }
      },
      "FieldSchema": {
        "type": "object",
        "description": "Schema for a component field",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "string",
              "number",
              "boolean",
              "object",
              "array"
            ],
            "description": "Field value type"
          },
          "optional": {
            "type": "boolean",
            "description": "Whether the field is optional"
          },
          "deprecated": {
            "type": "boolean",
            "description": "Whether the field is deprecated"
          },
          "advanced": {
            "type": "boolean",
            "description": "Whether this is an advanced configuration option"
          },
          "secret": {
            "type": "boolean",
            "description": "Whether this field contains sensitive data"
          },
          "children": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Child field names for object types"
          },
          "items_type": {
            "type": "string",
            "description": "Type of array items"
          }
        }
      },
      "ComponentsResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          },
          "fuzzy_matching_examples": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "input": {
                  "type": "string"
                },
                "suggestion": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message"
          }
        },
        "required": [
          "error"
        ]
      },
      "ValidationSummary": {
        "type": "object",
        "description": "Grouped and prioritized summary of validation results",
        "properties": {
          "error_count": {
            "type": "integer",
            "description": "Total number of ERROR-severity hallucinations"
          },
          "warning_count": {
            "type": "integer",
            "description": "Total number of WARNING-severity hallucinations"
          },
          "total_count": {
            "type": "integer",
            "description": "Total number of all hallucinations"
          },
          "groups": {
            "type": "array",
            "description": "Hallucinations grouped by component",
            "items": {
              "$ref": "#/components/schemas/HallucinationGroup"
            }
          },
          "top_issues": {
            "type": "array",
            "description": "Most impactful issues prioritized by category",
            "items": {
              "$ref": "#/components/schemas/Hallucination"
            }
          }
        },
        "required": [
          "error_count",
          "warning_count",
          "total_count",
          "groups",
          "top_issues"
        ]
      },
      "HallucinationGroup": {
        "type": "object",
        "description": "A group of related hallucinations",
        "properties": {
          "group_key": {
            "type": "string",
            "description": "Identifier for this group (e.g., 'input.kafka')"
          },
          "label": {
            "type": "string",
            "description": "Human-readable label (e.g., 'input.kafka (3 issues)')"
          },
          "count": {
            "type": "integer",
            "description": "Total number of hallucinations in this group"
          },
          "items": {
            "type": "array",
            "description": "Hallucinations shown (limited by max_per_group)",
            "items": {
              "$ref": "#/components/schemas/Hallucination"
            }
          },
          "additional_count": {
            "type": "integer",
            "description": "Number of additional items not shown (for '...and N more')"
          }
        },
        "required": [
          "group_key",
          "label",
          "count",
          "items",
          "additional_count"
        ]
      },
      "AnalyzeResponse": {
        "type": "object",
        "description": "Pipeline analysis result",
        "properties": {
          "input": {
            "$ref": "#/components/schemas/ComponentInfo",
            "description": "Input component details"
          },
          "output": {
            "$ref": "#/components/schemas/ComponentInfo",
            "description": "Output component details"
          },
          "processors": {
            "type": "array",
            "description": "List of processors in order",
            "items": {
              "$ref": "#/components/schemas/ComponentInfo"
            }
          },
          "buffer": {
            "$ref": "#/components/schemas/ComponentInfo",
            "nullable": true,
            "description": "Buffer component if present"
          },
          "resources": {
            "type": "object",
            "description": "Declared resources",
            "properties": {
              "caches": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "label": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string"
                    }
                  }
                }
              },
              "rate_limits": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "label": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "data_flow": {
            "type": "array",
            "description": "Data flow steps from input to output",
            "items": {
              "type": "string"
            }
          },
          "complexity": {
            "$ref": "#/components/schemas/ComplexityInfo"
          },
          "performance_hints": {
            "type": "array",
            "description": "Performance optimization suggestions",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "data_flow",
          "complexity"
        ]
      },
      "ComponentInfo": {
        "type": "object",
        "description": "Information about a pipeline component",
        "properties": {
          "type": {
            "type": "string",
            "description": "Component type name (e.g., 'kafka', 'mapping')"
          },
          "label": {
            "type": "string",
            "nullable": true,
            "description": "User-defined label if present"
          },
          "config_keys": {
            "type": "array",
            "description": "Configuration keys used",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "type"
        ]
      },
      "ComplexityInfo": {
        "type": "object",
        "description": "Pipeline complexity metrics",
        "properties": {
          "level": {
            "type": "string",
            "enum": [
              "simple",
              "moderate",
              "complex"
            ],
            "description": "Overall complexity level"
          },
          "processor_count": {
            "type": "integer",
            "description": "Number of processors"
          },
          "has_branching": {
            "type": "boolean",
            "description": "Whether pipeline has switch/branch logic"
          },
          "has_error_handling": {
            "type": "boolean",
            "description": "Whether pipeline has try/catch error handling"
          },
          "uses_resources": {
            "type": "boolean",
            "description": "Whether pipeline uses caches/rate_limits"
          }
        },
        "required": [
          "level",
          "processor_count",
          "has_branching",
          "has_error_handling",
          "uses_resources"
        ]
      },
      "ExplainRequest": {
        "type": "object",
        "description": "Request for error explanation",
        "properties": {
          "error_message": {
            "type": "string",
            "description": "The error message to explain"
          },
          "error_type": {
            "type": "string",
            "enum": [
              "validation",
              "runtime",
              "connection",
              "bloblang",
              "unknown"
            ],
            "description": "Type of error if known"
          },
          "context": {
            "type": "string",
            "description": "Additional context (e.g., YAML snippet, component name)"
          }
        },
        "required": [
          "error_message"
        ]
      },
      "ExplainResponse": {
        "type": "object",
        "description": "Detailed error explanation",
        "properties": {
          "error_type": {
            "type": "string",
            "enum": [
              "validation",
              "runtime",
              "connection",
              "bloblang",
              "unknown"
            ],
            "description": "Classified error type"
          },
          "explanation": {
            "type": "string",
            "description": "Human-readable explanation of what went wrong"
          },
          "cause": {
            "type": "string",
            "description": "What triggered this error"
          },
          "fix": {
            "type": "object",
            "description": "How to fix the error",
            "properties": {
              "description": {
                "type": "string",
                "description": "Explanation of the fix"
              },
              "before": {
                "type": "string",
                "nullable": true,
                "description": "Example of incorrect code"
              },
              "after": {
                "type": "string",
                "description": "Example of correct code"
              }
            },
            "required": [
              "description",
              "after"
            ]
          },
          "related_docs": {
            "type": "array",
            "description": "Links to relevant documentation",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "common_mistakes": {
            "type": "array",
            "description": "Similar mistakes to avoid",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "error_type",
          "explanation",
          "cause",
          "fix",
          "related_docs",
          "common_mistakes"
        ]
      },
      "SuggestRequest": {
        "type": "object",
        "description": "Request for pipeline pattern suggestions",
        "properties": {
          "use_case": {
            "type": "string",
            "description": "Natural language description of desired pipeline (e.g., 'read from Kafka and write to S3')"
          },
          "input_type": {
            "type": "string",
            "description": "Preferred input type if known (e.g., 'kafka', 'http')"
          },
          "output_type": {
            "type": "string",
            "description": "Preferred output type if known (e.g., 's3', 'elasticsearch')"
          }
        },
        "required": [
          "use_case"
        ]
      },
      "SuggestResponse": {
        "type": "object",
        "description": "Pipeline pattern suggestions",
        "properties": {
          "suggestions": {
            "type": "array",
            "description": "Scored pipeline suggestions",
            "items": {
              "$ref": "#/components/schemas/PatternSuggestion"
            }
          },
          "extracted_intent": {
            "$ref": "#/components/schemas/ExtractedIntent",
            "description": "What was understood from the use case description"
          }
        },
        "required": [
          "suggestions",
          "extracted_intent"
        ]
      },
      "PatternSuggestion": {
        "type": "object",
        "description": "A suggested pipeline pattern",
        "properties": {
          "pattern_name": {
            "type": "string",
            "description": "Name of the pattern (e.g., 'Kafka to S3 ETL')"
          },
          "description": {
            "type": "string",
            "description": "What this pattern does"
          },
          "relevance_score": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "How relevant this pattern is (0-1)"
          },
          "why_suggested": {
            "type": "string",
            "description": "Why this pattern was suggested"
          },
          "yaml": {
            "type": "string",
            "description": "Example YAML for this pattern"
          },
          "customization_hints": {
            "type": "array",
            "description": "Hints for customizing the pattern",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "pattern_name",
          "description",
          "relevance_score",
          "why_suggested",
          "yaml",
          "customization_hints"
        ]
      },
      "ExtractedIntent": {
        "type": "object",
        "description": "Extracted intent from use case description",
        "properties": {
          "source_concepts": {
            "type": "array",
            "description": "Detected source/input concepts",
            "items": {
              "type": "string"
            }
          },
          "destination_concepts": {
            "type": "array",
            "description": "Detected destination/output concepts",
            "items": {
              "type": "string"
            }
          },
          "transformation_concepts": {
            "type": "array",
            "description": "Detected transformation/processing concepts",
            "items": {
              "type": "string"
            }
          },
          "matched_categories": {
            "type": "array",
            "description": "Matched pipeline categories",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "source_concepts",
          "destination_concepts",
          "transformation_concepts",
          "matched_categories"
        ]
      },
      "CompatibilityResponse": {
        "type": "object",
        "description": "Compatibility check result",
        "properties": {
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Overall health score (0-100)"
          },
          "warnings": {
            "type": "array",
            "description": "Detected issues and suggestions",
            "items": {
              "$ref": "#/components/schemas/CompatibilityWarning"
            }
          },
          "categories": {
            "type": "object",
            "description": "Scores by category",
            "properties": {
              "performance": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "reliability": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "security": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "maintainability": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              }
            }
          }
        },
        "required": [
          "score",
          "warnings"
        ]
      },
      "CompatibilityWarning": {
        "type": "object",
        "description": "A compatibility warning",
        "properties": {
          "rule": {
            "type": "string",
            "description": "Rule identifier"
          },
          "severity": {
            "type": "string",
            "enum": [
              "error",
              "warning",
              "info"
            ],
            "description": "Severity level"
          },
          "message": {
            "type": "string",
            "description": "Description of the issue"
          },
          "suggestion": {
            "type": "string",
            "nullable": true,
            "description": "How to fix the issue"
          }
        },
        "required": [
          "rule",
          "severity",
          "message"
        ]
      },
      "FormatResponse": {
        "type": "object",
        "description": "Formatted YAML result",
        "properties": {
          "formatted_yaml": {
            "type": "string",
            "description": "Canonically formatted YAML"
          },
          "changes_made": {
            "type": "boolean",
            "description": "Whether any formatting changes were made"
          }
        },
        "required": [
          "formatted_yaml",
          "changes_made"
        ]
      },
      "ValidationMetrics": {
        "type": "object",
        "description": "Validation metrics for tracking and analysis",
        "properties": {
          "request_id": {
            "type": "string",
            "description": "Unique request identifier"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "When the validation occurred"
          },
          "yaml_size": {
            "type": "integer",
            "description": "Size of the YAML input in bytes"
          },
          "validation_time_ms": {
            "type": "integer",
            "description": "Time taken to validate in milliseconds"
          },
          "total_errors": {
            "type": "integer",
            "description": "Number of ERROR-severity issues"
          },
          "total_warnings": {
            "type": "integer",
            "description": "Number of WARNING-severity issues"
          },
          "by_category": {
            "type": "object",
            "description": "Count of issues by hallucination category",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "by_source": {
            "type": "object",
            "description": "Count of issues by validation source (rust, schema)",
            "additionalProperties": {
              "type": "integer"
            }
          }
        },
        "required": [
          "request_id",
          "timestamp",
          "yaml_size",
          "validation_time_ms",
          "total_errors",
          "total_warnings",
          "by_category",
          "by_source"
        ]
      },
      "MetricsFeedback": {
        "type": "object",
        "description": "Feedback on fix success for a validation request",
        "properties": {
          "request_id": {
            "type": "string",
            "description": "The request_id from the original validation response"
          },
          "fix_attempted": {
            "type": "boolean",
            "description": "Whether a fix was attempted"
          },
          "fix_succeeded": {
            "type": "boolean",
            "description": "Whether the fix resolved the issues"
          },
          "revalidation_errors": {
            "type": "integer",
            "description": "Number of errors after revalidation (optional)"
          },
          "feedback": {
            "type": "string",
            "description": "Additional text feedback (optional)"
          }
        },
        "required": [
          "request_id",
          "fix_attempted",
          "fix_succeeded"
        ]
      },
      "MetricsFeedbackResponse": {
        "type": "object",
        "description": "Response after submitting feedback",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "received"
            ],
            "description": "Status of the feedback submission"
          },
          "message": {
            "type": "string",
            "description": "Confirmation message"
          }
        },
        "required": [
          "status",
          "message"
        ]
      }
    }
  },
  "tags": [
    {
      "name": "Validation",
      "description": "Pipeline YAML validation endpoints"
    },
    {
      "name": "Analysis",
      "description": "Pipeline analysis, error explanation, and pattern suggestions"
    },
    {
      "name": "Schema",
      "description": "Component schema discovery"
    },
    {
      "name": "Utility",
      "description": "YAML formatting and other utilities"
    },
    {
      "name": "Metrics",
      "description": "Validation metrics and feedback tracking"
    },
    {
      "name": "Health",
      "description": "Service health monitoring"
    }
  ]
}