{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://ossa.io/schemas/openapi-extensions.json",
  "title": "OSSA OpenAPI/Swagger Specification Extensions Schema",
  "description": "JSON Schema for OSSA-specific OpenAPI 3.1 extensions that enable AI agent metadata, capabilities, and configuration within OpenAPI specifications.",
  "type": "object",
  "properties": {
    "rootLevelExtensions": {
      "type": "object",
      "description": "Extensions that can be added at the root level of an OpenAPI specification",
      "properties": {
        "x-ossa-metadata": {
          "$ref": "#/definitions/XOssaMetadata"
        },
        "x-ossa": {
          "$ref": "#/definitions/XOssa"
        },
        "x-agent": {
          "$ref": "#/definitions/XAgent"
        }
      }
    },
    "operationLevelExtensions": {
      "type": "object",
      "description": "Extensions that can be added to individual OpenAPI operations (GET, POST, etc.)",
      "properties": {
        "x-ossa-capability": {
          "$ref": "#/definitions/XOssaCapability"
        },
        "x-ossa-autonomy": {
          "$ref": "#/definitions/XOssaAutonomy"
        },
        "x-ossa-constraints": {
          "$ref": "#/definitions/XOssaConstraints"
        },
        "x-ossa-tools": {
          "$ref": "#/definitions/XOssaTools"
        },
        "x-ossa-llm": {
          "$ref": "#/definitions/XOssaLlm"
        }
      }
    },
    "parameterExtensions": {
      "type": "object",
      "description": "Extensions for OpenAPI parameters (headers, query params, etc.)",
      "properties": {
        "x-ossa-agent-id": {
          "$ref": "#/definitions/XOssaAgentId"
        },
        "x-ossa-version": {
          "$ref": "#/definitions/XOssaVersion"
        }
      }
    },
    "schemaExtensions": {
      "type": "object",
      "description": "Extensions for OpenAPI schema definitions",
      "properties": {
        "x-ossa-capability-schema": {
          "$ref": "#/definitions/XOssaCapabilitySchema"
        }
      }
    }
  },
  "definitions": {
    "XOssaMetadata": {
      "type": "object",
      "description": "Embeds comprehensive OSSA agent metadata in OpenAPI spec root",
      "properties": {
        "version": {
          "type": "string",
          "description": "OSSA specification version",
          "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9]+)?$",
          "examples": ["0.2.2", "1.0.0", "0.1.9"]
        },
        "compliance": {
          "type": "object",
          "properties": {
            "level": {
              "type": "string",
              "enum": ["basic", "standard", "advanced", "enterprise"],
              "description": "Compliance level"
            },
            "frameworks": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "List of compliance frameworks (e.g., OSSA, OpenAPI 3.1, RFC7807)",
              "examples": [["OSSA", "OpenAPI 3.1", "RFC7807"]]
            }
          },
          "required": ["level", "frameworks"]
        },
        "governance": {
          "type": "object",
          "properties": {
            "approved": {
              "type": "boolean",
              "description": "Whether the specification has been approved"
            },
            "approvedBy": {
              "type": "string",
              "description": "Entity that approved the specification"
            },
            "approvalDate": {
              "type": "string",
              "format": "date",
              "description": "Date of approval (YYYY-MM-DD format)"
            }
          }
        },
        "security": {
          "type": "object",
          "properties": {
            "classification": {
              "type": "string",
              "enum": ["public", "internal", "confidential", "restricted"],
              "description": "Security classification level"
            },
            "authentication": {
              "type": "string",
              "enum": ["required", "optional", "none"],
              "description": "Authentication requirements"
            },
            "encryption": {
              "type": "string",
              "description": "Encryption requirements (e.g., tls1.3, tls1.2)",
              "examples": ["tls1.3", "tls1.2"]
            }
          }
        },
        "observability": {
          "type": "object",
          "properties": {
            "tracing": {
              "type": "boolean",
              "description": "Enable distributed tracing"
            },
            "metrics": {
              "type": "boolean",
              "description": "Enable metrics collection"
            },
            "logging": {
              "type": "boolean",
              "description": "Enable structured logging"
            }
          }
        }
      },
      "required": ["version"]
    },
    "XOssa": {
      "type": "object",
      "description": "Core OSSA compliance information",
      "properties": {
        "version": {
          "type": "string",
          "description": "OSSA specification version",
          "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9]+)?$"
        },
        "agent": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique agent identifier",
              "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$"
            },
            "type": {
              "type": "string",
              "enum": ["orchestrator", "worker", "specialist", "critic", "judge", "monitor", "gateway", "governor", "integrator", "voice"],
              "description": "Agent type"
            },
            "compliance": {
              "type": "object",
              "properties": {
                "standards": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "List of architectural standards",
                  "examples": [["openapi-first", "dry", "crud", "solid", "type-safe"]]
                },
                "validated": {
                  "type": "boolean",
                  "description": "Whether the agent has been validated"
                },
                "validatedAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "ISO 8601 timestamp of validation"
                }
              }
            }
          },
          "required": ["id", "type"]
        }
      },
      "required": ["version", "agent"]
    },
    "XAgent": {
      "type": "object",
      "description": "Agent-specific capabilities and configuration",
      "properties": {
        "capabilities": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of agent capability names"
        },
        "tools": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of tools/MCP servers available to the agent"
        },
        "environment": {
          "type": "object",
          "description": "Environment-specific configuration",
          "additionalProperties": true
        },
        "rules": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of rules or policies the agent follows"
        }
      }
    },
    "XOssaCapability": {
      "oneOf": [
        {
          "type": "string",
          "description": "Simple capability name reference"
        },
        {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Capability name"
            },
            "description": {
              "type": "string",
              "description": "Capability description"
            },
            "inputSchema": {
              "type": "object",
              "description": "JSON Schema for capability input"
            },
            "outputSchema": {
              "type": "object",
              "description": "JSON Schema for capability output"
            }
          },
          "required": ["name"]
        }
      ],
      "description": "Links OpenAPI operation to OSSA agent capability"
    },
    "XOssaAutonomy": {
      "type": "object",
      "description": "Defines autonomy level for operation execution",
      "properties": {
        "level": {
          "type": "string",
          "enum": ["supervised", "autonomous", "semi-autonomous"],
          "description": "Autonomy level"
        },
        "approval_required": {
          "type": "boolean",
          "description": "Whether human approval is required before execution"
        },
        "allowed_actions": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of allowed actions for this operation"
        },
        "blocked_actions": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of blocked actions for this operation"
        }
      },
      "required": ["level"]
    },
    "XOssaConstraints": {
      "type": "object",
      "description": "Defines cost, token, and resource constraints for operation",
      "properties": {
        "cost": {
          "type": "object",
          "properties": {
            "maxTokensPerDay": {
              "type": "integer",
              "minimum": 0,
              "description": "Maximum tokens allowed per day"
            },
            "maxTokensPerRequest": {
              "type": "integer",
              "minimum": 0,
              "description": "Maximum tokens allowed per request"
            },
            "maxCostPerDay": {
              "type": "number",
              "minimum": 0,
              "description": "Maximum cost in USD per day"
            },
            "currency": {
              "type": "string",
              "default": "USD",
              "description": "Currency code (ISO 4217)"
            }
          }
        },
        "performance": {
          "type": "object",
          "properties": {
            "maxLatencySeconds": {
              "type": "number",
              "minimum": 0,
              "description": "Maximum acceptable latency in seconds"
            },
            "maxConcurrentRequests": {
              "type": "integer",
              "minimum": 1,
              "description": "Maximum concurrent requests"
            }
          }
        },
        "time": {
          "type": "object",
          "properties": {
            "maxExecutionTime": {
              "type": "integer",
              "minimum": 0,
              "description": "Maximum execution time in seconds"
            }
          }
        }
      }
    },
    "XOssaTools": {
      "type": "array",
      "description": "Specifies MCP servers or tools required for operation",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["mcp", "http", "custom"],
            "description": "Tool type"
          },
          "server": {
            "type": "string",
            "description": "Tool server identifier or URL"
          },
          "namespace": {
            "type": "string",
            "description": "Namespace for the tool (for MCP servers)"
          },
          "capabilities": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of tool capabilities"
          }
        },
        "required": ["type", "server"]
      }
    },
    "XOssaLlm": {
      "type": "object",
      "description": "Overrides LLM configuration for specific operation",
      "properties": {
        "provider": {
          "type": "string",
          "enum": ["openai", "anthropic", "google", "azure", "custom"],
          "description": "LLM provider"
        },
        "model": {
          "type": "string",
          "description": "Model identifier (e.g., gpt-4, claude-3-opus)",
          "examples": ["gpt-4", "claude-3-opus", "gemini-pro"]
        },
        "temperature": {
          "type": "number",
          "minimum": 0,
          "maximum": 2,
          "description": "Sampling temperature (0-2)"
        },
        "maxTokens": {
          "type": "integer",
          "minimum": 1,
          "description": "Maximum tokens in response"
        }
      },
      "required": ["provider", "model"]
    },
    "XOssaAgentId": {
      "type": "object",
      "description": "Header parameter extension for agent identification",
      "properties": {
        "name": {
          "type": "string",
          "default": "X-OSSA-Agent-ID",
          "description": "Header parameter name"
        },
        "description": {
          "type": "string",
          "description": "Parameter description"
        },
        "required": {
          "type": "boolean",
          "default": false,
          "description": "Whether the header is required"
        }
      }
    },
    "XOssaVersion": {
      "type": "object",
      "description": "Header parameter extension for OSSA version",
      "properties": {
        "name": {
          "type": "string",
          "default": "X-OSSA-Version",
          "description": "Header parameter name"
        },
        "description": {
          "type": "string",
          "description": "Parameter description"
        },
        "required": {
          "type": "boolean",
          "default": false,
          "description": "Whether the header is required"
        }
      }
    },
    "XOssaCapabilitySchema": {
      "type": "object",
      "description": "Extends schema definition with capability metadata",
      "properties": {
        "capabilityName": {
          "type": "string",
          "description": "Name of the capability this schema represents"
        },
        "input": {
          "type": "boolean",
          "default": false,
          "description": "Whether this is an input schema"
        },
        "output": {
          "type": "boolean",
          "default": false,
          "description": "Whether this is an output schema"
        },
        "validation": {
          "type": "object",
          "properties": {
            "required": {
              "type": "boolean",
              "description": "Whether validation is required"
            },
            "strict": {
              "type": "boolean",
              "description": "Whether to use strict validation"
            }
          }
        }
      }
    }
  }
}