overrides.yml merges an operation's parameters array by position, renaming and dropping parameters

[2opremio]

Component

CLI

Priority

P1 - High (Strongly needed)

Bug Description

An entry under an operation's parameters in overrides.yml is merged by array position rather than matched by parameter name. A one-entry override lands on parameters[0], so it renames whichever parameter happens to sit there, leaves the parameter it named untouched, and drops its own schema on the floor. fern check reports no errors, so the reference is corrupted silently.

Steps to reproduce

1. fern/fern.config.json:

   { "organization": "example", "version": "5.80.2" }

2. fern/generators.yml:

   api:
     specs:
       - openapi: ./openapi/openapi.json
         overrides: ./openapi/overrides.yml

3. fern/openapi/openapi.json, one endpoint with three query parameters in this order:

   {
     "openapi": "3.0.1",
     "info": { "title": "Example API", "version": "0.1.0" },
     "servers": [{ "url": "https://api.example.com" }],
     "paths": {
       "/widgets": {
         "get": {
           "operationId": "listWidgets",
           "summary": "List widgets",
           "tags": ["widgets"],
           "parameters": [
             { "name": "cursor", "in": "query", "schema": { "type": "string" } },
             { "name": "limit", "in": "query", "schema": { "type": "integer" } },
             { "name": "color", "in": "query", "schema": { "type": "string" } }
           ],
           "responses": { "200": { "description": "OK" } }
         }
       }
     }
   }

4. fern/openapi/overrides.yml, overriding only the third parameter:

   paths:
     /widgets:
       get:
         parameters:
           - name: color
             in: query
             style: form
             explode: false
             schema:
               type: array
               items:
                 type: string
                 enum: [red, green, blue]

5. fern check, then fern export merged.yml.

Expected: color keeps its name and picks up style: form, explode: false and the array-of-enum schema. cursor and limit are untouched. Three parameters remain.

Actual: two parameters, and parameters[0] has been renamed:

parameters:
  - name: color        # this is cursor, renamed by the override
    in: query
    required: false
    schema:
      type: string     # the override's array/enum schema was not applied
  - name: limit
    in: query
    required: false
    schema:
      type: integer

cursor is gone, and so is the color the override was written for.

It reaches the rendered reference too, in a worse shape. Running fern docs dev on the same project, the endpoint page's query parameters come through as:

color   list of enums     <- the override, applied to what used to be cursor
limit   integer
color   string            <- the original color parameter

so the page shows two parameters with the same name and omits cursor entirely.

The positional behavior is easy to miss because an override happens to work whenever the entry's index lines up with its parameter, and it silently breaks later when the spec gains or reorders a parameter. In a generated spec that is regenerated upstream, that is not under the docs author's control.

Environment

• OS: macOS (darwin 25.5.0)
• Node.js: v22.19.0

Versions

Fern CLI version (from fern.config.json): 5.80.2

Workaround

Edit parameters from overlays.yml instead. JSONPath matches by name and survives a spec change that reorders or inserts parameters:

actions:
  - target: $.paths['/widgets'].get.parameters[?(@.name == 'color')]
    update:
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
          enum: [red, green, blue]

Are you interested in contributing a fix?

No