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

packages/cli/api-importers/openapi/openapi-ir-parser/src/schema/examples/ExampleTypeFactory.ts

@@ -148,8 +148,7 @@ export class ExampleTypeFactory {
                     result != null &&
                     result.type === "array" &&
                     result.value.length === 0 &&
-                    !Array.isArray(example) &&
-                    !Array.isArray(this.getSchemaExample(schema))
+                    !this.isExplicitEmptyArrayExample(example, schema.value)
                 ) {
                     return undefined;
                 }
@@ -915,6 +914,21 @@ export class ExampleTypeFactory {
         return schema;
     }
 
+    /**
+     * True when the example that the array builder uses is an authored `[]`. The
+     * array builder prefers a parsed array example and falls back to the schema
+     * example, so this follows the same order. A non-empty example whose items all
+     * fail to build is not an explicit empty array.
+     */
+    private isExplicitEmptyArrayExample(example: unknown, schema: SchemaWithExample): boolean {
+        const parsedExample = getFullExampleAsArray(example);
+        if (parsedExample != null) {
+            return parsedExample.length === 0;
+        }
+        const schemaExample = getFullExampleAsArray(this.getSchemaExample(schema));
+        return schemaExample != null && schemaExample.length === 0;
+    }
+
     private getSchemaExample(schema: SchemaWithExample): unknown | undefined {
         return schema._visit({
             primitive: (s) => s.schema.example,

packages/cli/api-importers/openapi/openapi-ir-parser/src/schema/examples/__tests__/ExampleTypeFactory.test.ts

@@ -170,10 +170,30 @@ function makeStringSchema(): SchemaWithExample {
     );
 }
 
-function makeArraySchema(): SchemaWithExample {
+function makeMissingReferenceSchema(): SchemaWithExample {
+    return SchemaWithExample.reference({
+        schema: "MissingSchema",
+        description: undefined,
+        availability: undefined,
+        generatedName: "MissingSchema",
+        nameOverride: undefined,
+        groupName: undefined,
+        namespace: undefined,
+        title: undefined,
+        source: undefined
+    });
+}
+
+function makeArraySchema({
+    items = makeStringSchema(),
+    example
+}: {
+    items?: SchemaWithExample;
+    example?: unknown[];
+} = {}): SchemaWithExample {
     return SchemaWithExample.array({
-        value: makeStringSchema(),
-        example: undefined,
+        value: items,
+        example,
         minItems: undefined,
         maxItems: undefined,
         default: undefined,
@@ -577,6 +597,54 @@ describe("ExampleTypeFactory", () => {
             expect(explicitResult).toMatchObject({ type: "array", value: [] });
             expect(absentResult).toBeUndefined();
         });
+
+        it("should keep a required array property whose example is []", () => {
+            const schema = makeObjectSchema({
+                properties: {
+                    success: makeStringSchema(),
+                    messages: makeArraySchema()
+                },
+                additionalProperties: false
+            });
+
+            const result = factory.buildExample({
+                schema,
+                exampleId: undefined,
+                example: { success: "false", messages: [] },
+                options: DEFAULT_OPTIONS
+            });
+
+            expect(result).toMatchObject({
+                type: "object",
+                properties: { messages: { type: "array", value: [] } }
+            });
+        });
+
+        it("should keep an optional array whose schema-level example is []", () => {
+            const schema = makeOptionalSchema(makeArraySchema({ example: [] }));
+
+            const result = factory.buildExample({
+                schema,
+                exampleId: undefined,
+                example: undefined,
+                options: DEFAULT_OPTIONS
+            });
+
+            expect(result).toMatchObject({ type: "array", value: [] });
+        });
+
+        it("should omit an optional array whose non-empty example has no buildable items", () => {
+            const schema = makeOptionalSchema(makeArraySchema({ items: makeMissingReferenceSchema() }));
+
+            const result = factory.buildExample({
+                schema,
+                exampleId: undefined,
+                example: [{ id: "unbuildable" }],
+                options: DEFAULT_OPTIONS
+            });
+
+            expect(result).toBeUndefined();
+        });
     });
 
     describe("warning message truncation", () => {

packages/cli/api-importers/openapi/openapi-ir-parser/src/schema/examples/__tests__/convertToFullExample.test.ts

@@ -0,0 +1,68 @@
+import { FullExample, PrimitiveExample } from "@fern-api/openapi-ir";
+import { describe, expect, it } from "vitest";
+
+import { convertToFullExample } from "../convertToFullExample.js";
+
+// FullExample values carry _visit functions, so compare their JSON shape.
+function plain(value: unknown): unknown {
+    return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+describe("convertToFullExample", () => {
+    it("keeps empty arrays and nulls in an authored error body", () => {
+        const result = convertToFullExample({
+            success: false,
+            errors: [{ code: 1001, message: "Missing required parameter: q" }],
+            messages: [],
+            result: null
+        });
+
+        expect(plain(result)).toEqual(
+            plain(
+                FullExample.map([
+                    {
+                        key: PrimitiveExample.string("success"),
+                        value: FullExample.primitive(PrimitiveExample.boolean(false))
+                    },
+                    {
+                        key: PrimitiveExample.string("errors"),
+                        value: FullExample.array([
+                            FullExample.map([
+                                {
+                                    key: PrimitiveExample.string("code"),
+                                    value: FullExample.primitive(PrimitiveExample.int(1001))
+                                },
+                                {
+                                    key: PrimitiveExample.string("message"),
+                                    value: FullExample.primitive(
+                                        PrimitiveExample.string("Missing required parameter: q")
+                                    )
+                                }
+                            ])
+                        ])
+                    },
+                    {
+                        key: PrimitiveExample.string("messages"),
+                        value: FullExample.array([])
+                    },
+                    {
+                        key: PrimitiveExample.string("result"),
+                        value: FullExample.null({})
+                    }
+                ])
+            )
+        );
+    });
+
+    it("keeps a top-level empty array", () => {
+        expect(plain(convertToFullExample([]))).toEqual(plain(FullExample.array([])));
+    });
+
+    it("keeps null array items", () => {
+        expect(plain(convertToFullExample([null]))).toEqual(plain(FullExample.array([FullExample.null({})])));
+    });
+
+    it("returns undefined for undefined", () => {
+        expect(convertToFullExample(undefined)).toBeUndefined();
+    });
+});

packages/cli/api-importers/openapi/openapi-ir-parser/src/schema/examples/convertToFullExample.ts

@@ -1,7 +1,15 @@
 import { FullExample, KeyValuePair, PrimitiveExample } from "@fern-api/openapi-ir";
 
+/**
+ * Converts an authored example value into a FullExample without consulting a schema.
+ *
+ * Empty arrays and nulls are values the author wrote, so they are kept. Only
+ * `undefined` and values that have no JSON representation produce `undefined`.
+ */
 export function convertToFullExample(value: unknown): FullExample | undefined {
-    if (typeof value === "string") {
+    if (value === null) {
+        return FullExample.null({});
+    } else if (typeof value === "string") {
         return FullExample.primitive(PrimitiveExample.string(value));
     } else if (typeof value === "number") {
         if (Number.isInteger(value)) {
@@ -11,11 +19,14 @@ export function convertToFullExample(value: unknown): FullExample | undefined {
     } else if (typeof value === "boolean") {
         return FullExample.primitive(PrimitiveExample.boolean(value));
     } else if (Array.isArray(value)) {
-        const examples = value.map((example) => convertToFullExample(example));
-        if (examples.length === 0) {
-            return undefined;
+        const examples: FullExample[] = [];
+        for (const item of value) {
+            const itemExample = convertToFullExample(item);
+            if (itemExample != null) {
+                examples.push(itemExample);
+            }
         }
-        return FullExample.array(examples.filter((example) => example != null) as FullExample[]);
+        return FullExample.array(examples);
     } else if (
         value != null &&
         typeof value === "object" &&