• Could be about comparing what we have with the standard industry spec
• To refine later with Kamil

Notes from estimation:

• https://docs.google.com/spreadsheets/d/1nxGsWvpu_GXD28Fw19A8WWJa5cumWNke2E9m-22Qxu4/edit?gid=0#gid=0 --> Has a list of the fields that we are actually writing rules for; could be helpful for review.
• Might be easier to run the linter in the terminal instead of the Toolforge version, just to make line number matching easier.
• The scope is only to enumerate the gaps. They can be documented here, and/or ideally create the follow up tickets for the work.
  • We do not expect the implementer to actually fix all of the framework gaps within this ticket.
• Further emphasizing that we only want to fix the issues for errors & warnings for now; hints & info are nice to jot down if there's time, but we are unlikely to fix them right now.

Spike report

Ran the Wikimedia Spectral ruleset against the OAD for all four active REST modules:

Framework gaps — errors

These fields are silently dropped or never generated regardless of what is declared in route definition files or handler code.

Errors

operationId not generated (48 errors, all modules)
operationId is missing from the $oasKeys list in SpecBasedModule::makeRouteInfo(). Even if declared in a route .json file, it is silently stripped. The framework also does not auto-generate it. → Existing task: T425428

requestBody.description not supported (14 errors)
Handler::getRequestSpec() builds the requestBody object with only required and content. There is no mechanism — neither from the handler nor from a route .json file — to add a description field. → T427355

Root-level externalDocs not supported (4 errors — one per module)
ModuleSpecHandler::run() only builds openapi, info, servers, paths, components. There is no way to inject externalDocs at the document root. Note: externalDocs at the *operation* level is already supported via $oasKeys. → T427356

info.version = "undefined" for default module (1 error)
For the default module (no .json definition file), getInfoSpec() falls back to the literal string "undefined", which fails semantic version validation. Named modules like content/v1 are unaffected because they declare a version in their definition file. → T427359

Warnings

Root-level tags array not generated (conditional — blocks all per-operation tags)
ModuleSpecHandler::run() never generates the root tags array. The linter requires that when operations use tags, each tag must also be declared in the root array. Since the root array is never generated, using operation-level tags produces linter warnings. → Existing task: T392154

requestBody.content[*].example not supported (32 warnings)
getRequestSpec() never generates example or examples under request body media types. There is no hook for this in the handler base class. The equivalent mechanism for path/query *parameters* (PARAM_EXAMPLE) was added in T420988; the same pattern is needed for request body content. → T427360

responses[200].content[*].example has no standard hook (20 warnings)
generateResponseSpec() builds responses['200'] with schema and headers but no examples. A workaround exists — SitemapHandlerBase overrides generateResponseSpec() entirely — but this duplicates base class logic and is not a general pattern. site/v1 is the only module with response examples today for this reason. → T427361

Path-level summary/description not supported (92 hints)
The limitation is explicitly noted in the source code with an XXX comment in getPathsSpec(). Low priority; T427362