fix(cli): keep [] and null in authored error examples

[dimitropoulos]

Follow-up to 9192cdd (the cherry-pick of fern-api/fern#17776). That commit fixed explicit [] on the schema-aware path in ExampleTypeFactory, which handles request and success-response examples. It didn't cover error responses. fern check still fails on specs that have an error envelope like this:

"400":
  content:
    application/json:
      schema:
        $ref: "#/components/schemas/api-response-common-failure"   # messages is required
      examples:
        missing_query:
          value:
            success: false
            errors:
              - code: 1001
                message: "Missing required parameter: q"
            messages: []
            result: null

fatal valid-example-error __package__.yml -> errors -> BadRequestError -> type
  Example is missing required property "response.body.messages"

Cause

Authored error examples (and webhook payload examples) are not built by ExampleTypeFactory. generateIr passes them to convertToFullExample, which converts values without a schema. That function returned undefined for [] and for null, and the object branch drops any property whose value converts to undefined. As a result, messages and result were both missing from the generated error declaration:

errors:
  BadRequestError:
    examples:
      - value:
          errors: [...]
          success: false

Changes

• convertToFullExample now keeps [] as FullExample.array([]) and null as FullExample.null({}). The validator already accepts null for optional and nullable properties. This change also fixes the unknown schema case, where an explicit [] was being replaced with a generated {"key": "value"} placeholder.
• The optional-container guard from 9192cdd now keeps an empty array only when the example the array builder used was an authored []. Before, it kept any array example, so a non-empty example whose items all failed to build came out as []. That case is omitted again, as raised in review on the upstream PR.

Tests

• convertToFullExample.test.ts: a nested [] and null in an error body, a top-level [], and [null].
• ExampleTypeFactory.test.ts: a required array property set to [], an optional array with a schema-level example: [], and an optional array whose non-empty example has no buildable items.
• openapi-ir-to-fern-tests fixture error-examples-empty-arrays: the snapshot shows messages: [] and result: null on the generated BadRequestError and ServiceUnavailableError examples.
• An ETE validate fixture with the same spec. fern check reports "All checks passed". On the base branch it fails with the three errors shown above.

Results:

• openapi-ir-parser: all 106 tests pass, and tsc is clean.
• openapi-ir-to-fern-tests: all 321 tests pass. The only snapshot changes are the new fixture.
• ir-generator-tests: all pass.
• I also ran the built CLI against a large real-world bundle. It reports the same 73 findings before and after this change, so nothing new is flagged and nothing is lost.

Not in scope: hasExample ignores a schema-level example on arrays. When ignoreOptionals is set, an optional array with a schema-level example: [] is still left out of generated request examples. Leaving it out is valid (it's optional), and changing it would also pull non-empty array examples into every generated request example.

[Copilot]

🟢 Approval recommended

The focused implementation is consistent with its callers and has comprehensive regression coverage.

0 open findings

What changed in this PR

Fixes OpenAPI example conversion so authored empty arrays and nulls survive error/webhook processing and validation.

Changes:

• Preserve [] and null in schema-free example conversion.
• Distinguish authored empty arrays from arrays emptied by failed item conversion.
• Add unit, parser snapshot, and CLI end-to-end regression coverage.

File	Description
packages/​cli/​ete-tests/​src/​tests/​validate/​validate.test.ts	Registers the regression fixture.
packages/​cli/​ete-tests/​src/​tests/​validate/​fixtures/​error-examples-empty-arrays/​fern/​openapi.yml	Defines end-to-end error examples.
packages/​cli/​ete-tests/​src/​tests/​validate/​fixtures/​error-examples-empty-arrays/​fern/​generators.yml	Configures fixture input.
packages/​cli/​ete-tests/​src/​tests/​validate/​fixtures/​error-examples-empty-arrays/​fern/​fern.config.json	Configures the fixture project.
packages/​cli/​ete-tests/​src/​tests/​validate/​__snapshots__/​validate.test.ts.snap	Records successful validation.
packages/​cli/​cli/​changes/​unreleased/​fix-openapi-error-example-empty-arrays.yml	Documents the CLI fix.
packages/​cli/​api-importers/​openapi/​openapi-ir-to-fern-tests/​src/​__test__/​fixtures/​error-examples-empty-arrays/​openapi.yml	Adds importer regression input.
packages/​cli/​api-importers/​openapi/​openapi-ir-to-fern-tests/​src/​__test__/​fixtures/​error-examples-empty-arrays/​fern/​generators.yml	Configures importer fixture input.
packages/​cli/​api-importers/​openapi/​openapi-ir-to-fern-tests/​src/​__test__/​fixtures/​error-examples-empty-arrays/​fern/​fern.config.json	Configures the importer fixture.
packages/​cli/​api-importers/​openapi/​openapi-ir-to-fern-tests/​src/​__test__/​__snapshots__/​openapi/​error-examples-empty-arrays.json	Captures generated Fern definitions.
packages/​cli/​api-importers/​openapi/​openapi-ir-to-fern-tests/​src/​__test__/​__snapshots__/​openapi-ir/​error-examples-empty-arrays.json	Captures preserved IR values.
packages/​cli/​api-importers/​openapi/​openapi-ir-parser/​src/​schema/​examples/​ExampleTypeFactory.ts	Tightens explicit-empty-array detection.
packages/​cli/​api-importers/​openapi/​openapi-ir-parser/​src/​schema/​examples/​convertToFullExample.ts	Preserves empty arrays and nulls.
packages/​cli/​api-importers/​openapi/​openapi-ir-parser/​src/​schema/​examples/​__tests__/​ExampleTypeFactory.test.ts	Tests array-generation edge cases.
packages/​cli/​api-importers/​openapi/​openapi-ir-parser/​src/​schema/​examples/​__tests__/​convertToFullExample.test.ts	Tests schema-free conversion behavior.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.