feat: adds support for OpenAPI 3.2.0 emission

.chronus/changes/feat-oai-3-2-emission-2025-9-27-15-15-29.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/openapi3"
+---
+
+added support for OpenAPI 3.2.0 emission

packages/openapi3/src/cli/actions/convert/convert.ts

@@ -1,6 +1,6 @@
 import { AnyObject, dereference } from "@scalar/openapi-parser";
 import { formatTypeSpec } from "@typespec/compiler";
-import { OpenAPI3Document } from "../../../types.js";
+import { SupportedOpenAPIDocuments } from "../../../types.js";
 import { generateMain } from "./generators/generate-main.js";
 import { transform } from "./transforms/transforms.js";
 import { createContext } from "./utils/context.js";
@@ -17,7 +17,7 @@ export interface ConvertOpenAPI3DocumentOptions {
 }
 
 export async function convertOpenAPI3Document(
-  document: OpenAPI3Document,
+  document: SupportedOpenAPIDocuments,
   { disableExternalRefs, namespace }: ConvertOpenAPI3DocumentOptions = {},
 ) {
   const dereferenceOptions = disableExternalRefs

packages/openapi3/src/cli/actions/convert/generators/generate-model.ts

@@ -1,5 +1,5 @@
 import { printIdentifier } from "@typespec/compiler";
-import { OpenAPI3Encoding, OpenAPI3Schema, Refable } from "../../../../types.js";
+import { OpenAPI3Encoding, Refable, SupportedOpenAPISchema } from "../../../../types.js";
 import {
   TypeSpecAlias,
   TypeSpecDataTypes,
@@ -96,7 +96,7 @@ function generateUnion(union: TypeSpecUnion, context: Context): string {
 
   const schema = union.schema;
 
-  const getVariantName = (member: Refable<OpenAPI3Schema>) => {
+  const getVariantName = (member: Refable<SupportedOpenAPISchema>) => {
     if (union.schema.discriminator === undefined) {
       return "";
     }
@@ -159,7 +159,7 @@ function generateUnion(union: TypeSpecUnion, context: Context): string {
     }
   }
 
-  if (schema.nullable) {
+  if ("nullable" in schema && schema.nullable) {
     definitions.push("null,");
   }
 

packages/openapi3/src/cli/actions/convert/generators/generate-response-expressions.ts

@@ -359,10 +359,10 @@ function convertHeaderToProperty(
 
   return {
     name: normalizedName,
-    decorators: [headerDecorator, ...getDecoratorsForSchema(header.schema)],
-    doc: props.header.description ?? header.description ?? header.schema.description,
+    decorators: [headerDecorator, ...(header.schema ? getDecoratorsForSchema(header.schema) : [])],
+    doc: props.header.description ?? header.description ?? header.schema?.description,
     isOptional: !header.required,
-    schema: header.schema,
+    schema: header.schema ?? {},
   };
 }
 

packages/openapi3/src/cli/actions/convert/generators/generate-types.ts

@@ -1,9 +1,9 @@
 import { printIdentifier } from "@typespec/compiler";
 import {
   OpenAPI3Encoding,
-  OpenAPI3Schema,
-  OpenAPI3SchemaProperty,
+  OpenAPISchema3_2,
   Refable,
+  SupportedOpenAPISchema,
 } from "../../../../types.js";
 import { Context } from "../utils/context.js";
 import {
@@ -17,7 +17,7 @@ export class SchemaToExpressionGenerator {
   constructor(public rootNamespace: string) {}
 
   public generateTypeFromRefableSchema(
-    schema: Refable<OpenAPI3Schema>,
+    schema: Refable<SupportedOpenAPISchema>,
     callingScope: string[],
     isHttpPart = false,
     encoding?: Record<string, OpenAPI3Encoding>,
@@ -29,7 +29,7 @@ export class SchemaToExpressionGenerator {
       : this.getTypeFromSchema(schema, callingScope, isHttpPart, encoding, context);
   }
 
-  public generateArrayType(schema: OpenAPI3Schema, callingScope: string[]): string {
+  public generateArrayType(schema: SupportedOpenAPISchema, callingScope: string[]): string {
     const items = schema.items;
     if (!items) {
       return "unknown[]";
@@ -85,7 +85,7 @@ export class SchemaToExpressionGenerator {
   }
 
   private getTypeFromSchema(
-    schema: OpenAPI3Schema,
+    schema: SupportedOpenAPISchema,
     callingScope: string[],
     isHttpPart = false,
     encoding?: Record<string, OpenAPI3Encoding>,
@@ -103,7 +103,7 @@ export class SchemaToExpressionGenerator {
         } else {
           // Create a schema with a single type to reuse existing type extraction logic
           // Remove type array, nullable, and default to avoid double-processing
-          const singleTypeSchema: OpenAPI3Schema = {
+          const singleTypeSchema: SupportedOpenAPISchema = {
             ...schema,
             type: t as any,
             nullable: undefined,
@@ -154,7 +154,7 @@ export class SchemaToExpressionGenerator {
       type = this.generateArrayType(schema, callingScope);
     }
 
-    if (schema.nullable) {
+    if ("nullable" in schema && schema.nullable) {
       type += ` | null`;
     }
 
@@ -170,7 +170,7 @@ export class SchemaToExpressionGenerator {
   }
 
   private generateDefaultValue(
-    schema: OpenAPI3Schema,
+    schema: SupportedOpenAPISchema,
     callingScope: string[],
     context?: Context,
   ): string | undefined {
@@ -224,9 +224,9 @@ export class SchemaToExpressionGenerator {
     return undefined; // Return undefined to indicate no default found
   }
 
-  private getAllOfType(schema: OpenAPI3Schema, callingScope: string[]): string {
+  private getAllOfType(schema: SupportedOpenAPISchema, callingScope: string[]): string {
     const requiredProps: string[] = schema.required || [];
-    let properties: Record<string, Refable<OpenAPI3Schema>> = {};
+    let properties: Record<string, Refable<SupportedOpenAPISchema>> = {};
     const baseTypes: string[] = [];
 
     for (const member of schema.allOf || []) {
@@ -261,7 +261,9 @@ export class SchemaToExpressionGenerator {
     }
   }
 
-  private stripDefaultsFromSchema(schema: Refable<OpenAPI3Schema>): Refable<OpenAPI3Schema> {
+  private stripDefaultsFromSchema(
+    schema: Refable<SupportedOpenAPISchema>,
+  ): Refable<SupportedOpenAPISchema> {
     if ("$ref" in schema) {
       return schema;
     }
@@ -274,24 +276,31 @@ export class SchemaToExpressionGenerator {
       strippedSchema.items = this.stripDefaultsFromSchema(strippedSchema.items);
     }
 
+    // in the next blocks the casts are ugly but safe because the stripped schema is going to be the same as the original one
     if (strippedSchema.anyOf) {
-      strippedSchema.anyOf = strippedSchema.anyOf.map((item) => this.stripDefaultsFromSchema(item));
+      strippedSchema.anyOf = strippedSchema.anyOf.map((item) =>
+        this.stripDefaultsFromSchema(item),
+      ) as unknown as OpenAPISchema3_2[];
     }
 
     if (strippedSchema.oneOf) {
-      strippedSchema.oneOf = strippedSchema.oneOf.map((item) => this.stripDefaultsFromSchema(item));
+      strippedSchema.oneOf = strippedSchema.oneOf.map((item) =>
+        this.stripDefaultsFromSchema(item),
+      ) as unknown as OpenAPISchema3_2[];
     }
 
     if (strippedSchema.allOf) {
-      strippedSchema.allOf = strippedSchema.allOf.map((item) => this.stripDefaultsFromSchema(item));
+      strippedSchema.allOf = strippedSchema.allOf.map((item) =>
+        this.stripDefaultsFromSchema(item),
+      ) as unknown as OpenAPISchema3_2[];
     }
 
     if (strippedSchema.properties) {
-      const strippedProperties: Record<string, Refable<OpenAPI3Schema>> = {};
+      const strippedProperties: Record<string, Refable<SupportedOpenAPISchema>> = {};
       for (const [key, prop] of Object.entries(strippedSchema.properties)) {
         strippedProperties[key] = this.stripDefaultsFromSchema(prop);
       }
-      strippedSchema.properties = strippedProperties;
+      strippedSchema.properties = strippedProperties as unknown as Record<string, OpenAPISchema3_2>;
     }
 
     if (
@@ -306,7 +315,7 @@ export class SchemaToExpressionGenerator {
     return strippedSchema;
   }
 
-  private getAnyOfType(schema: OpenAPI3Schema, callingScope: string[]): string {
+  private getAnyOfType(schema: SupportedOpenAPISchema, callingScope: string[]): string {
     const definitions: string[] = [];
 
     for (const item of schema.anyOf ?? []) {
@@ -318,7 +327,7 @@ export class SchemaToExpressionGenerator {
     return definitions.join(" | ");
   }
 
-  private getOneOfType(schema: OpenAPI3Schema, callingScope: string[]): string {
+  private getOneOfType(schema: SupportedOpenAPISchema, callingScope: string[]): string {
     const definitions: string[] = [];
 
     for (const item of schema.oneOf ?? []) {
@@ -408,7 +417,7 @@ export class SchemaToExpressionGenerator {
   public static readonly decoratorNamesToExcludeForParts: string[] = ["minValue", "maxValue"];
 
   private getObjectType(
-    schema: OpenAPI3Schema,
+    schema: SupportedOpenAPISchema,
     callingScope: string[],
     isHttpPart = false,
     encoding?: Record<string, OpenAPI3Encoding>,
@@ -466,7 +475,7 @@ export class SchemaToExpressionGenerator {
 }
 
 export function isReferencedEnumType(
-  propSchema: OpenAPI3SchemaProperty,
+  propSchema: Refable<SupportedOpenAPISchema>,
   context: Context,
 ): boolean {
   let isEnumType = false;
@@ -486,7 +495,7 @@ export function isReferencedEnumType(
 }
 
 export function isReferencedUnionType(
-  propSchema: OpenAPI3SchemaProperty,
+  propSchema: Refable<SupportedOpenAPISchema>,
   context: Context,
 ): boolean {
   let isUnionType = false;
@@ -509,7 +518,7 @@ export function isReferencedUnionType(
   return isUnionType;
 }
 
-export function getTypeSpecPrimitiveFromSchema(schema: OpenAPI3Schema): string | undefined {
+export function getTypeSpecPrimitiveFromSchema(schema: SupportedOpenAPISchema): string | undefined {
   if (schema.type === "boolean") {
     return "boolean";
   } else if ((schema as any).type === "null") {
@@ -524,7 +533,7 @@ export function getTypeSpecPrimitiveFromSchema(schema: OpenAPI3Schema): string |
   return;
 }
 
-function getIntegerType(schema: OpenAPI3Schema): string {
+function getIntegerType(schema: SupportedOpenAPISchema): string {
   const format = schema.format ?? "";
   switch (format) {
     case "int8":
@@ -543,7 +552,7 @@ function getIntegerType(schema: OpenAPI3Schema): string {
   }
 }
 
-function getNumberType(schema: OpenAPI3Schema): string {
+function getNumberType(schema: SupportedOpenAPISchema): string {
   const format = schema.format ?? "";
   switch (format) {
     case "decimal":
@@ -559,7 +568,7 @@ function getNumberType(schema: OpenAPI3Schema): string {
   }
 }
 
-function getStringType(schema: OpenAPI3Schema): string {
+function getStringType(schema: SupportedOpenAPISchema): string {
   const format = schema.format ?? "";
   let type = "string";
   switch (format) {
@@ -588,6 +597,6 @@ function getStringType(schema: OpenAPI3Schema): string {
   return type;
 }
 
-function getEnum(schemaEnum: (string | number | boolean)[]): string {
+function getEnum(schemaEnum: (string | number | boolean | null)[]): string {
   return schemaEnum.map((e) => JSON.stringify(e)).join(" | ");
 }

packages/openapi3/src/cli/actions/convert/interfaces.ts

@@ -1,5 +1,10 @@
 import { Contact, License } from "@typespec/openapi";
-import { OpenAPI3Encoding, OpenAPI3Responses, OpenAPI3Schema, Refable } from "../../../types.js";
+import {
+  OpenAPI3Encoding,
+  OpenAPI3Responses,
+  Refable,
+  SupportedOpenAPISchema,
+} from "../../../types.js";
 
 export interface TypeSpecProgram {
   serviceInfo: TypeSpecServiceInfo;
@@ -87,7 +92,7 @@ export interface TypeSpecModel extends TypeSpecDeclaration {
   kind: "model";
 
   properties: TypeSpecModelProperty[];
-  additionalProperties?: Refable<OpenAPI3Schema>;
+  additionalProperties?: Refable<SupportedOpenAPISchema>;
   /**
    * Note: Only one of `extends` or `is` should be specified.
    */
@@ -99,7 +104,7 @@ export interface TypeSpecModel extends TypeSpecDeclaration {
   /**
    * Defaults to 'object'
    */
-  type?: OpenAPI3Schema["type"];
+  type?: SupportedOpenAPISchema["type"];
 
   spread?: string[];
 
@@ -120,17 +125,17 @@ export interface TypeSpecAlias extends Pick<TypeSpecDeclaration, "name" | "doc"
 
 export interface TypeSpecEnum extends TypeSpecDeclaration {
   kind: "enum";
-  schema: OpenAPI3Schema;
+  schema: SupportedOpenAPISchema;
 }
 
 export interface TypeSpecUnion extends TypeSpecDeclaration {
   kind: "union";
-  schema: OpenAPI3Schema;
+  schema: SupportedOpenAPISchema;
 }
 
 export interface TypeSpecScalar extends TypeSpecDeclaration {
   kind: "scalar";
-  schema: OpenAPI3Schema;
+  schema: SupportedOpenAPISchema;
 }
 
 export interface TypeSpecModelProperty {
@@ -143,7 +148,7 @@ export interface TypeSpecModelProperty {
    * Example: location decorators for parameters
    */
   decorators: TypeSpecDecorator[];
-  schema: Refable<OpenAPI3Schema>;
+  schema: Refable<SupportedOpenAPISchema>;
 }
 
 export interface TypeSpecOperation extends TypeSpecDeclaration {
@@ -160,13 +165,13 @@ export interface TypeSpecOperationParameter {
   doc?: string;
   decorators: TypeSpecDecorator[];
   isOptional: boolean;
-  schema: Refable<OpenAPI3Schema>;
+  schema: Refable<SupportedOpenAPISchema>;
 }
 
 export interface TypeSpecRequestBody {
   contentType: string;
   doc?: string;
   isOptional: boolean;
   encoding?: Record<string, OpenAPI3Encoding>;
-  schema?: Refable<OpenAPI3Schema>;
+  schema?: Refable<SupportedOpenAPISchema>;
 }

packages/openapi3/src/cli/actions/convert/transforms/transform-component-parameters.ts

@@ -1,5 +1,5 @@
 import { printIdentifier } from "@typespec/compiler";
-import { OpenAPI3Parameter } from "../../../../types.js";
+import { OpenAPI3Parameter, OpenAPIParameter3_2 } from "../../../../types.js";
 import { TypeSpecDataTypes, TypeSpecModelProperty } from "../interfaces.js";
 import { Context } from "../utils/context.js";
 import { getParameterDecorators } from "../utils/decorators.js";
@@ -22,14 +22,15 @@ export function transformComponentParameters(
 
   for (const name of Object.keys(parameters)) {
     const parameter = parameters[name];
+    if ("$ref" in parameter) continue;
     transformComponentParameter(dataTypes, name, parameter);
   }
 }
 
 function transformComponentParameter(
   dataTypes: TypeSpecDataTypes[],
   key: string,
-  parameter: OpenAPI3Parameter,
+  parameter: OpenAPI3Parameter | OpenAPIParameter3_2,
 ): void {
   const { name, scope } = getScopeAndName(key);
   // Parameters should live in the root Parameters namespace
@@ -44,12 +45,15 @@ function transformComponentParameter(
   });
 }
 
-function getModelPropertyFromParameter(parameter: OpenAPI3Parameter): TypeSpecModelProperty {
+function getModelPropertyFromParameter(
+  parameter: OpenAPI3Parameter | OpenAPIParameter3_2,
+): TypeSpecModelProperty {
+  const parameterSchema = "schema" in parameter ? (parameter.schema ?? {}) : {};
   return {
     name: printIdentifier(parameter.name),
     isOptional: !parameter.required,
-    doc: parameter.description ?? parameter.schema.description,
+    doc: parameter.description ?? parameterSchema.description,
     decorators: getParameterDecorators(parameter),
-    schema: parameter.schema,
+    schema: parameterSchema,
   };
 }