fix(openapi): infer binary responses from media types

Author: Andy Nguyen

packages/cli/api-importers/openapi-to-ir/src/3.1/paths/ResponseBodyConverter.ts

@@ -166,6 +166,15 @@ export class ResponseBodyConverter extends Converters.AbstractConverters.Abstrac
             if (mediaTypeObject == null) {
                 continue;
             }
+            if (this.isBinaryContentType(contentType)) {
+                return this.shouldReturnBytesResponse()
+                    ? this.returnBytesResponse({
+                          mediaTypeObject
+                      })
+                    : this.returnFileDownloadResponse({
+                          mediaTypeObject
+                      });
+            }
             const convertedSchema = this.parseMediaTypeObject({
                 mediaTypeObject,
                 schemaId,
@@ -454,6 +463,14 @@ export class ResponseBodyConverter extends Converters.AbstractConverters.Abstrac
         return contentType.includes("json");
     }
 
+    private isBinaryContentType(contentType: string): boolean {
+        const mediaType = MediaType.parse(contentType);
+        if (mediaType == null) {
+            return false;
+        }
+        return mediaType.isBinary() && !mediaType.isXML();
+    }
+
     private shouldReturnBytesResponse(): boolean {
         return this.context.settings.useBytesForBinaryResponse && this.streamingExtension == null;
     }

packages/cli/api-importers/openapi/openapi-ir-parser/src/openapi/v3/converters/endpoint/convertResponse.ts

@@ -341,14 +341,7 @@ function convertResolvedResponse({
             continue;
         }
 
-        if (
-            mimeType.isOctetStream() ||
-            mimeType.isPDF() ||
-            mimeType.isAudio() ||
-            mimeType.isImage() ||
-            mimeType.isVideo() ||
-            mimeType.isMultiPartMixed()
-        ) {
+        if (mimeType.isBinary() || mimeType.isMultiPartMixed()) {
             return ResponseWithExample.file({ description: resolvedResponse.description, source, statusCode });
         }
 

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

@@ -1,3 +1,4 @@
+import { MediaType } from "@fern-api/core-utils";
 import type { Logger } from "@fern-api/logger";
 import {
     type Availability,
@@ -57,6 +58,48 @@ export const SCHEMA_INLINE_REFERENCE_PREFIX = "#/components/responses/";
 // Module-level collision tracker for title-based name overrides
 const globalTitleCollisionTracker = createSchemaCollisionTracker();
 
+const RAW_BINARY_SCHEMA_ALLOWED_KEYS = new Set([
+    "$anchor",
+    "$comment",
+    "$id",
+    "$schema",
+    "contentMediaType",
+    "default",
+    "deprecated",
+    "description",
+    "example",
+    "examples",
+    "externalDocs",
+    "format",
+    "maxLength",
+    "minLength",
+    "pattern",
+    "readOnly",
+    "title",
+    "writeOnly"
+]);
+
+function isRawBinarySchema(schema: OpenAPIV3.SchemaObject): boolean {
+    const { contentEncoding, contentMediaType } = schema as Record<string, unknown>;
+    if (
+        schema.type != null ||
+        contentEncoding != null ||
+        typeof contentMediaType !== "string" ||
+        (schema.format != null && schema.format !== "binary")
+    ) {
+        return false;
+    }
+    if (
+        Object.keys(schema).some(
+            (key) => !RAW_BINARY_SCHEMA_ALLOWED_KEYS.has(key) && !key.toLowerCase().startsWith("x-")
+        )
+    ) {
+        return false;
+    }
+    const mediaType = MediaType.parse(contentMediaType);
+    return mediaType?.isBinary() === true && !mediaType.isXML();
+}
+
 // Reset the global collision tracker (called at the start of document processing)
 export function resetTitleCollisionTracker(): void {
     globalTitleCollisionTracker.reset();
@@ -1429,6 +1472,29 @@ export function convertSchemaObject(
             });
         }
 
+        // OpenAPI 3.1 raw binary data has no JSON type or content encoding.
+        if (isRawBinarySchema(schema)) {
+            return wrapPrimitive({
+                nameOverride,
+                generatedName,
+                title,
+                primitive: PrimitiveSchemaValueWithExample.string({
+                    default: getDefaultAsString(schema),
+                    pattern: schema.pattern,
+                    format: "binary",
+                    minLength: schema.minLength,
+                    maxLength: schema.maxLength,
+                    example: getExamplesString({ schema, logger: context.logger, fallback })
+                }),
+                namespace,
+                groupName,
+                wrapAsOptional,
+                wrapAsNullable,
+                description,
+                availability
+            });
+        }
+
         // handle null type (OpenAPI 3.1)
         // `type: "null"` means the value is always null.
         // Represent as nullable wrapping an unknown inner type.

packages/cli/api-importers/v3-importer-commons/src/converters/schema/PrimitiveSchemaConverter.ts

@@ -1,3 +1,4 @@
+import { MediaType } from "@fern-api/core-utils";
 import {
     ContainerType,
     IntegerValidationRules,
@@ -11,6 +12,27 @@ import { OpenAPIV3_1 } from "openapi-types";
 
 import { AbstractConverter, AbstractConverterContext } from "../../index.js";
 
+const RAW_BINARY_SCHEMA_ALLOWED_KEYS = new Set([
+    "$anchor",
+    "$comment",
+    "$id",
+    "$schema",
+    "contentMediaType",
+    "default",
+    "deprecated",
+    "description",
+    "example",
+    "examples",
+    "externalDocs",
+    "format",
+    "maxLength",
+    "minLength",
+    "pattern",
+    "readOnly",
+    "title",
+    "writeOnly"
+]);
+
 export declare namespace PrimitiveSchemaConverter {
     export interface Args extends AbstractConverter.AbstractArgs {
         schema: OpenAPIV3_1.SchemaObject;
@@ -26,6 +48,16 @@ export class PrimitiveSchemaConverter extends AbstractConverter<AbstractConverte
     }
 
     public convert(): TypeReference | undefined {
+        if (this.isRawBinarySchema(this.schema)) {
+            return TypeReference.primitive({
+                v1: PrimitiveTypeV1.String,
+                v2: PrimitiveTypeV2.string({
+                    default: this.context.getAsString(this.schema.default),
+                    validation: this.getStringValidation({ ...this.schema, format: "binary" })
+                })
+            });
+        }
+
         switch (this.schema.type) {
             case "string": {
                 const stringConst = this.context.getAsString(this.schema.const);
@@ -201,6 +233,28 @@ export class PrimitiveSchemaConverter extends AbstractConverter<AbstractConverte
         }
     }
 
+    private isRawBinarySchema(schema: OpenAPIV3_1.SchemaObject): boolean {
+        // OpenAPI 3.1 raw binary data has no JSON type or content encoding.
+        const { contentEncoding, contentMediaType } = schema as Record<string, unknown>;
+        if (
+            schema.type != null ||
+            contentEncoding != null ||
+            typeof contentMediaType !== "string" ||
+            (schema.format != null && schema.format !== "binary")
+        ) {
+            return false;
+        }
+        if (
+            Object.keys(schema).some(
+                (key) => !RAW_BINARY_SCHEMA_ALLOWED_KEYS.has(key) && !key.toLowerCase().startsWith("x-")
+            )
+        ) {
+            return false;
+        }
+        const mediaType = MediaType.parse(contentMediaType);
+        return mediaType?.isBinary() === true && !mediaType.isXML();
+    }
+
     private getNumberValidation(schema: OpenAPIV3_1.SchemaObject): IntegerValidationRules | undefined {
         // Handle both OpenAPI 3.0 (boolean) and OpenAPI 3.1 (number) formats for exclusive bounds
         // OpenAPI 3.0: exclusiveMinimum/exclusiveMaximum are booleans that modify minimum/maximum