feat: document cross-parameter dependencies and validation rules in OpenAPI schema

[cryptpenguin]

Proposal: Documenting Cross-Parameter Dependencies in OpenAPI Schema

Repository Context: nfa-llc/gexbot-openapi
Related Endpoint: GET /research/{ticker}/{metric}

---

1. Problem Statement

The /research/{ticker}/{metric} endpoint supports a wide array of query parameters (such as view, series, moneyness_filter, etc.). However, certain parameter combinations are mutually exclusive or invalid depending on the selected metric:

• When metric=gex_oi, parameters like series, view, contract_filter, and moneyness_filter are not supported.
• When view=term (term structure), parameters like moneyness_filter are not applicable.

Currently, the OpenAPI specification (OAS) defines these parameters as a flat array of optional query fields. Because standard OAS flat arrays cannot natively describe logical dependencies, client-side tools (like the Interactive URL Builder) cannot automatically determine which options to disable/grey out. This leads to invalid copy-paste URLs and redundant 400 Bad Request round-trips.

---

2. Proposed Solutions

We propose two methods to encode these validation rules directly inside the OpenAPI specification so that client generators can ingest them.

Option A: Custom OpenAPI Extensions (x-dependencies)

This is the most lightweight and backward-compatible option. We can introduce custom metadata tags directly on query parameter definitions. Frontend clients can parse these tags to dynamically disable input controls.

Example Spec Modification:

components:
  parameters:
    research_series:
      name: series
      in: query
      required: false
      description: "Group results into series lines. Not supported for summary metrics like gex_oi."
      schema:
        type: string
        enum: [none, deltas, moneyness, strikes]
      # --- Proposed Custom Dependency Extension ---
      x-dependencies:
        disabled-when:
          metric: ["gex_oi", "gex"]

    research_view:
      name: view
      in: query
      required: false
      schema:
        type: string
        enum: [skew, term, surface]
      # --- Proposed Custom Dependency Extension ---
      x-dependencies:
        disabled-when:
          metric: ["gex_oi"]

---

Option B: Polymorphic Path Definition (oneOf / anyOf)

If upgrading the OpenAPI pipeline to OpenAPI 3.1.0 (which supports draft 2020-12 of JSON Schema), we can define the request parameters as structured schemas instead of a flat list, allowing standard schema constraints like dependentRequired or polymorphic oneOf matching.

Example Spec Concept:

{
  "oneOf": [
    {
      "title": "GEX/OI Summary Query",
      "properties": {
        "metric": { "const": "gex_oi" },
        "format": { "type": "string" },
        "strikes": { "type": "number" }
      },
      "not": {
        "required": ["series", "view", "moneyness_filter"]
      }
    },
    {
      "title": "Greek Curves/Surfaces Query",
      "properties": {
        "metric": { "enum": ["gex_vol", "dex_vol", "gex_curve"] },
        "series": { "type": "string" },
        "view": { "type": "string" }
      }
    }
  ]
}

---

3. Benefits

1. Single Source of Truth: Frontend validation logic (greying out form controls) is instantly synchronized with backend routing rules.
2. Reduced Server Load: Clients block invalid queries before they ever cross the network.
3. Better Developer Experience: Developers using Gexbot's interactive API playground are guided to construct syntactically correct requests by default.