fix(core): inline string type for $ref binary fields in x-www-form-urlencoded bodies (#3422)

When a property in an application/x-www-form-urlencoded request body is
a $ref to a component schema whose body is { type: string, format: binary }
(the shape Swashbuckle emits for C# IFormFile parameters), the generated
body type used the imported component name. Because that standalone model
is generated as Blob, URLSearchParams.append(key, value) then failed to
type-check (TS2345: 'Blob' is not assignable to 'string').

Inline-binary properties already stayed as 'string' via formDataContext
.urlEncoded inside scalar.ts (#1624 / #3395), but the component-$ref
branch in resolveValue returned the import name without consulting that
flag. Short-circuit there: when the resolved component schema is a binary
scalar (string + format: binary, or contentMediaType: application/octet
-stream w/o contentEncoding) and we are inside a url-encoded body, fall
back to the inlined scalar so the property type collapses to 'string'.

The standalone IFormFile model is intentionally left as Blob — the same
component may be referenced by a multipart/form-data endpoint where Blob
is correct. Only the url-encoded body property is rewritten in place.

Runtime side is already correct: resolveSchemaPropertiesToFormData
unwraps the $ref before checking property.format === 'binary', so the
generated append call needs no change.

Fixes #2410

Author: wadakatu

packages/core/src/getters/scalar.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest';
 
 import type { ContextSpec, OpenApiSchemaObject } from '../types';
-import { getScalar } from './scalar';
+import { getScalar, isBinaryScalarSchema } from './scalar';
 
 const context = {
   output: {
@@ -60,3 +60,75 @@ describe('getScalar (contentMediaType: application/octet-stream)', () => {
     expect(result.value).toBe('string');
   });
 });
+
+describe('isBinaryScalarSchema', () => {
+  it('returns true for { type: "string", format: "binary" }', () => {
+    expect(isBinaryScalarSchema({ type: 'string', format: 'binary' })).toBe(
+      true,
+    );
+  });
+
+  it('returns true for { type: "string", contentMediaType: "application/octet-stream" }', () => {
+    expect(
+      isBinaryScalarSchema({
+        type: 'string',
+        contentMediaType: 'application/octet-stream',
+      }),
+    ).toBe(true);
+  });
+
+  it('returns false when contentMediaType has a contentEncoding (base64)', () => {
+    expect(
+      isBinaryScalarSchema({
+        type: 'string',
+        contentMediaType: 'application/octet-stream',
+        contentEncoding: 'base64',
+      }),
+    ).toBe(false);
+  });
+
+  it('returns false for plain string without binary signals', () => {
+    expect(isBinaryScalarSchema({ type: 'string' })).toBe(false);
+  });
+
+  it('returns false for non-string scalars (number)', () => {
+    expect(
+      isBinaryScalarSchema({
+        type: 'number',
+        format: 'binary',
+      } as OpenApiSchemaObject),
+    ).toBe(false);
+  });
+
+  it('accepts OAS 3.1 nullable union [string, null] + format: binary', () => {
+    // getScalar normalizes ['string','null'] → case 'string' before invoking
+    // this predicate, so the predicate must agree to keep the url-encoded
+    // $ref short-circuit firing for nullable binary scalars.
+    expect(
+      isBinaryScalarSchema({
+        type: ['string', 'null'],
+        format: 'binary',
+      } as unknown as OpenApiSchemaObject),
+    ).toBe(true);
+  });
+
+  it('accepts OAS 3.1 nullable union [string, null] + contentMediaType: octet-stream', () => {
+    expect(
+      isBinaryScalarSchema({
+        type: ['string', 'null'],
+        contentMediaType: 'application/octet-stream',
+      } as unknown as OpenApiSchemaObject),
+    ).toBe(true);
+  });
+
+  it('rejects mixed unions that include non-string non-null members', () => {
+    // e.g. ['string','integer'] would not dispatch to case 'string' in
+    // getScalar, so isBinaryScalarSchema must not promise binary semantics.
+    expect(
+      isBinaryScalarSchema({
+        type: ['string', 'integer'],
+        format: 'binary',
+      } as unknown as OpenApiSchemaObject),
+    ).toBe(false);
+  });
+});

packages/core/src/getters/scalar.ts

@@ -17,6 +17,43 @@ import { getObject } from './object';
 /** Bridge type for enum values extracted from OpenAPI schemas infected by AnyOtherAttribute */
 type SchemaEnumValue = string | number | boolean | null;
 
+/**
+ * Returns true when a schema describes a raw binary string scalar — i.e. one
+ * that getScalar's `case 'string':` branch would coerce to `Blob` outside a
+ * url-encoded context (see the formDataContext.urlEncoded gate below). Shared
+ * with resolveValue so the component-`$ref` urlEncoded short-circuit and the
+ * inline scalar path stay in lockstep when new binary shapes are added
+ * (#1624 / #3395 / #2410).
+ *
+ * Accepts OAS 3.1 nullable unions (`type: ['string', 'null']`) since getScalar
+ * normalizes those into `case 'string':` before invoking this predicate.
+ */
+export function isBinaryScalarSchema(schema: OpenApiSchemaObject): boolean {
+  const schemaType = schema.type as
+    | OpenApiSchemaObjectType
+    | OpenApiSchemaObjectType[]
+    | undefined;
+  const isStringLike =
+    schemaType === 'string' ||
+    (isArray(schemaType) &&
+      schemaType.includes('string') &&
+      schemaType.every((type) => type === 'string' || type === 'null'));
+  if (!isStringLike) {
+    return false;
+  }
+  if (schema.format === 'binary') {
+    return true;
+  }
+  // The @scalar/openapi-parser upgrader rewrites format: binary to
+  // contentMediaType: application/octet-stream during Swagger 2.0 / OAS 3.0 →
+  // OAS 3.1 upgrades; treat the upgraded shape the same. A non-empty
+  // contentEncoding signals an encoded string payload (e.g. base64), not raw
+  // binary.
+  const contentMediaType = schema.contentMediaType as string | undefined;
+  const contentEncoding = schema.contentEncoding as string | undefined;
+  return contentMediaType === 'application/octet-stream' && !contentEncoding;
+}
+
 interface GetScalarOptions {
   item: OpenApiSchemaObject;
   name?: string;
@@ -50,8 +87,6 @@ export function getScalar({
   const schemaConst = item.const as string | undefined;
   const schemaFormat = item.format as string | undefined;
   const schemaNullable = item.nullable as boolean | undefined;
-  const schemaContentMediaType = item.contentMediaType as string | undefined;
-  const schemaContentEncoding = item.contentEncoding as string | undefined;
 
   const nullable =
     (isArray(schemaType) && schemaType.includes('null')) ||
@@ -187,14 +222,11 @@ export function getScalar({
           if (fileType) {
             value = fileType === 'binary' ? 'Blob' : 'Blob | string';
           }
-        } else if (
-          schemaContentMediaType === 'application/octet-stream' &&
-          !schemaContentEncoding
-        ) {
-          // The @scalar/openapi-parser upgrader converts format: binary to
-          // contentMediaType: application/octet-stream when upgrading
-          // Swagger 2.0 / OAS 3.0 → OAS 3.1. Treat it the same as
-          // format: binary so $ref-based model types generate Blob.
+        } else if (isBinaryScalarSchema(item)) {
+          // The previous arm caught format: binary directly; this matches the
+          // OAS 3.1 contentMediaType: application/octet-stream variant via the
+          // shared predicate so any future binary shapes added there flow
+          // through here too (#2410).
           value = 'Blob';
         }
       }

packages/core/src/resolvers/value.ts

@@ -1,6 +1,7 @@
 import { getScalar } from '../getters';
 import type { FormDataContext } from '../getters/object';
 import { isComponentRef } from '../getters/ref';
+import { isBinaryScalarSchema } from '../getters/scalar';
 import type {
   ContextSpec,
   GeneratorImport,
@@ -70,6 +71,33 @@ export function resolveValue({
       return { ...scalar, originalSchema: schemaObject, isRef: false };
     }
 
+    // application/x-www-form-urlencoded bodies are serialized via
+    // URLSearchParams.append(), which only accepts strings. Inline binary
+    // properties already skip the Blob coercion via formDataContext.urlEncoded
+    // inside scalar.ts (#1624 / #3395), but the component-$ref path below
+    // returns the imported type name unconditionally — so e.g. C#'s
+    // `IFormFile` (= Blob) leaks into the body type and fails to type-check.
+    // When the resolved component schema is a binary scalar that scalar.ts
+    // would coerce to Blob, fall back to the inlined scalar (which becomes
+    // `string` under formDataContext.urlEncoded) instead of the import.
+    // The standalone IFormFile model is intentionally left as Blob — it may
+    // still be referenced by a multipart/form-data endpoint where Blob is
+    // correct. Fixes #2410.
+    if (formDataContext?.urlEncoded && isBinaryScalarSchema(schemaObject)) {
+      // Pass the resolveValue input `name` (the property name) so this branch
+      // truly behaves like an inline property schema. Using the component
+      // import name here would leak component-based naming into downstream
+      // scalar paths (validators/docs/naming) even though the resulting type
+      // is plain `string`.
+      const scalar = getScalar({
+        item: schemaObject,
+        name,
+        context,
+        formDataContext,
+      });
+      return { ...scalar, originalSchema: schemaObject, isRef: false };
+    }
+
     const resolvedImport = imports[0];
 
     let hasReadonlyProps = false;

tests/__snapshots__/fetch/form-url-encoded-with-custom-fetch/endpoints.ts

@@ -4,7 +4,13 @@
  * Swagger Petstore
  * OpenAPI spec version: 1.0.0
  */
-import type { CreatePetsBody, Error, Pet, UploadPetContentBody } from './model';
+import type {
+  CreatePetsBody,
+  Error,
+  Pet,
+  UploadPetContentBody,
+  UploadPetContentRefBody,
+} from './model';
 
 import { faker } from '@faker-js/faker';
 
@@ -150,6 +156,57 @@ export const uploadPetContent = async (
   });
 };
 
+export type uploadPetContentRefResponse200 = {
+  data: Pet;
+  status: 200;
+};
+
+export type uploadPetContentRefResponseDefault = {
+  data: Error;
+  status: Exclude<HTTPStatusCodes, 200>;
+};
+
+export type uploadPetContentRefResponseSuccess =
+  uploadPetContentRefResponse200 & {
+    headers: Headers;
+  };
+export type uploadPetContentRefResponseError =
+  uploadPetContentRefResponseDefault & {
+    headers: Headers;
+  };
+
+export type uploadPetContentRefResponse =
+  | uploadPetContentRefResponseSuccess
+  | uploadPetContentRefResponseError;
+
+export const getUploadPetContentRefUrl = () => {
+  return `/pets/upload-ref`;
+};
+
+/**
+ * @summary Upload pet content using a $ref to a binary component schema
+ */
+export const uploadPetContentRef = async (
+  uploadPetContentRefBody: UploadPetContentRefBody,
+  options?: RequestInit,
+): Promise<uploadPetContentRefResponse> => {
+  const formUrlEncoded = new URLSearchParams();
+  formUrlEncoded.append(`name`, uploadPetContentRefBody.name);
+  if (uploadPetContentRefBody.content !== undefined) {
+    formUrlEncoded.append(`content`, uploadPetContentRefBody.content);
+  }
+
+  return customFetch<uploadPetContentRefResponse>(getUploadPetContentRefUrl(), {
+    ...options,
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+      ...options?.headers,
+    },
+    body: formUrlEncoded,
+  });
+};
+
 export const getCreatePetsResponseMock = (
   overrideResponse: Partial<Extract<Pet, object>> = {},
 ): Pet => ({
@@ -206,6 +263,34 @@ export const getUploadPetContentResponseMock = (
   ...overrideResponse,
 });
 
+export const getUploadPetContentRefResponseMock = (
+  overrideResponse: Partial<Extract<Pet, object>> = {},
+): Pet => ({
+  '@id': faker.helpers.arrayElement([
+    faker.string.alpha({ length: { min: 10, max: 20 } }),
+    undefined,
+  ]),
+  id: faker.number.int(),
+  name: faker.string.alpha({ length: { min: 10, max: 20 } }),
+  tag: faker.helpers.arrayElement([
+    faker.string.alpha({ length: { min: 10, max: 20 } }),
+    undefined,
+  ]),
+  email: faker.helpers.arrayElement([faker.internet.email(), undefined]),
+  callingCode: faker.helpers.arrayElement([
+    faker.helpers.arrayElement(['+33', '+420', '+33'] as const),
+    undefined,
+  ]),
+  country: faker.helpers.arrayElement([
+    faker.helpers.arrayElement([
+      "People's Republic of China",
+      'Uruguay',
+    ] as const),
+    undefined,
+  ]),
+  ...overrideResponse,
+});
+
 export const getCreatePetsMockHandler = (
   overrideResponse?:
     | Pet
@@ -253,7 +338,32 @@ export const getUploadPetContentMockHandler = (
     options,
   );
 };
+
+export const getUploadPetContentRefMockHandler = (
+  overrideResponse?:
+    | Pet
+    | ((
+        info: Parameters<Parameters<typeof http.post>[1]>[0],
+      ) => Promise<Pet> | Pet),
+  options?: RequestHandlerOptions,
+) => {
+  return http.post(
+    '*/pets/upload-ref',
+    async (info: Parameters<Parameters<typeof http.post>[1]>[0]) => {
+      return HttpResponse.json(
+        overrideResponse !== undefined
+          ? typeof overrideResponse === 'function'
+            ? await overrideResponse(info)
+            : overrideResponse
+          : getUploadPetContentRefResponseMock(),
+        { status: 200 },
+      );
+    },
+    options,
+  );
+};
 export const getSwaggerPetstoreMock = () => [
   getCreatePetsMockHandler(),
   getUploadPetContentMockHandler(),
+  getUploadPetContentRefMockHandler(),
 ];

tests/__snapshots__/fetch/form-url-encoded-with-custom-fetch/model/iFormFile.ts

@@ -0,0 +1,8 @@
+/**
+ * Generated by orval v8.12.2 🍺
+ * Do not edit manually.
+ * Swagger Petstore
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type IFormFile = Blob;

tests/__snapshots__/fetch/form-url-encoded-with-custom-fetch/model/index.ts

@@ -7,7 +7,9 @@
 
 export * from './createPetsBody';
 export * from './error';
+export * from './iFormFile';
 export * from './pet';
 export * from './petCallingCode';
 export * from './petCountry';
 export * from './uploadPetContentBody';
+export * from './uploadPetContentRefBody';

tests/__snapshots__/fetch/form-url-encoded-with-custom-fetch/model/uploadPetContentRefBody.ts

@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.2 🍺
+ * Do not edit manually.
+ * Swagger Petstore
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type UploadPetContentRefBody = {
+  name: string;
+  content?: string;
+};