Fix Openapi3.0 param with $ref schema and default

.chronus/changes/fix-openapi3.0-param-default-2026-0-30-15-34-2.md

@@ -0,0 +1,8 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: fix
+packages:
+  - "@typespec/openapi3"
+---
+
+Fix parameters with default value resulting in `$ref` with `default` as sibling for OpenAPI 3.0

packages/openapi3/src/openapi.ts

@@ -1577,15 +1577,21 @@ function createOAPIEmitter(
     if (!typeSchema) {
       return undefined;
     }
-    const schema = applyEncoding(
+    let schema = applyEncoding(
       program,
       param,
       applyIntrinsicDecorators(param, typeSchema),
       options,
     );
 
     if (param.defaultValue) {
-      schema.default = getDefaultValue(program, param.defaultValue, param);
+      const defaultValue = getDefaultValue(program, param.defaultValue, param);
+      // In OpenAPI 3.0, $ref cannot have sibling properties.
+      if ("$ref" in schema && specVersion === "3.0.0") {
+        schema = { allOf: [{ $ref: schema.$ref }], default: defaultValue };
+      } else {
+        schema.default = defaultValue;
+      }
     }
     // Description is already provided in the parameter itself.
     delete schema.description;

packages/openapi3/test/parameters.test.ts

@@ -4,7 +4,7 @@ import { describe, expect, it } from "vitest";
 import { OpenAPI3PathParameter, OpenAPI3QueryParameter } from "../src/types.js";
 import { supportedVersions, worksFor } from "./works-for.js";
 
-worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor }) => {
+worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor, version }) => {
   describe("query parameters", () => {
     async function getQueryParam(code: string): Promise<OpenAPI3QueryParameter> {
       const res = await openApiFor(code);
@@ -616,4 +616,24 @@ worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor }) => {
       });
     });
   });
+
+  it("parmeter with default value and $ref wraps $ref in allOf in OpenAPI 3.0 only", async () => {
+    const res = await openApiFor(
+      `
+      enum Example { a, b}
+      op test(@query example?: Example = Example.b): void;
+      `,
+    );
+
+    const schema = res.paths["/"].get.parameters[0].schema;
+    if (version === "3.0.0") {
+      // In OpenAPI 3.0, $ref cannot have sibling properties, so we wrap in allOf
+      expect(schema.allOf).toEqual([{ $ref: "#/components/schemas/Example" }]);
+      expect(schema.default).toBe("b");
+    } else {
+      // In OpenAPI 3.1+, $ref can have sibling properties
+      expect(schema.$ref).toBe("#/components/schemas/Example");
+      expect(schema.default).toBe("b");
+    }
+  });
 });