🤔 Design Decision: Should validation and openapi be mutually exclusive?

[Uanela]

Context:
In the upcoming Arkos Router (v1.4-beta), you can define request validation using Zod or class-validator. You can also manually define OpenAPI specifications. The current implementation treats the validation and openapi configurations as mutually exclusive for the same request section (body, query, or params).

Current Behavior & Problem Statement:
The router currently works as follows:

• ✅ Using validation (e.g., validation.query):

  • Runtime validation is performed.
  • The OpenAPI specification is automatically generated from the validation schema (DTO/Zod schema) and added to the docs.
  • You cannot manually define the same section (e.g., openapi.parameters for query) if validation.query is used—it throws a startup error to prevent conflicts.

• ✅ Using openapi only:

  • The provided OpenAPI specification is used for documentation.
  • No automatic runtime validation occurs. The developer must handle validation inside the route handler.

The core question is about the behavior when only openapi is defined, without a corresponding validation schema.

Code Examples for Clarity:

// ❌ SCENARIO 1: CONFLICT - This correctly throws an error.
productRouter.get({
  validation: { query: ProductQueryDto }, // Auto-generates OpenAPI for query
  openapi: { 
    parameters: [ ... ] // Manual OpenAPI for query -> Conflict!
  }
}, handler);

// ✅ SCENARIO 2: AUTO-VALIDATION & AUTO-DOCS
productRouter.get({
  validation: { query: ProductQueryDto } // Runtime validation + Auto OpenAPI docs
}, handler);

// ❓ SCENARIO 3: MANUAL DOCS, WHAT ABOUT VALIDATION?
productRouter.get({
  openapi: {
    parameters: [
      { in: "query", name: "search", schema: { type: "string", minLength: 3 } }
    ]
  }
}, (req, res) => {
  // What is the type and content of `req.query.search` here?
  // Should the router validate it based on the OpenAPI schema?
});

The Decision:
When a route has an openapi specification but no validation schema, what should Arkos Router do?

Option A: No Automatic Validation (Docs Only)

• The openapi block is treated purely as documentation.
• The router performs no runtime validation based on the OpenAPI schema.
• The developer is fully responsible for any validation inside the handler.
• Pro: Clear separation of concerns, no performance overhead from a JSON Schema validator.
• Con: Potential duplication of validation logic if the dev implements checks that mirror the OpenAPI spec.

Option B: Automatic Validation using OpenAPI Schema

• The router uses the JSON Schemas from the openapi block to perform runtime validation.
• Requests that do not conform to the OpenAPI schema are automatically rejected.
• Pro: A single source of truth (the OpenAPI spec) drives both docs and validation.
• Con: Introduces a dependency on a JSON Schema validator, increasing bundle size. Could be surprising behavior if the OpenAPI spec was intended only for documentation.

Vote: