feat(openapi3): Import OpenAPI deprecated field as #deprecated directive

.chronus/changes/copilot-fix-deprecated-decorators-import-2026-0-5-20-26-16.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/openapi3"
+---
+
+Add support for importing deprecated properties and types from OpenAPI

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

@@ -1,6 +1,14 @@
-import { TSValue, TypeSpecDecorator } from "../interfaces.js";
+import { TSValue, TypeSpecDecorator, TypeSpecDirective } from "../interfaces.js";
 import { stringLiteral } from "./common.js";
 
+function generateDirective({ name, message }: TypeSpecDirective): string {
+  return `#${name} ${stringLiteral(message)}`;
+}
+
+export function generateDirectives(directives: TypeSpecDirective[] = []): string[] {
+  return directives.map(generateDirective);
+}
+
 function generateDecorator({ name, args }: TypeSpecDecorator): string {
   const hasArgs = args.length;
   const stringifiedArguments = hasArgs

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

@@ -12,7 +12,7 @@ import {
 import { Context } from "../utils/context.js";
 import { getDecoratorsForSchema } from "../utils/decorators.js";
 import { generateDocs } from "../utils/docs.js";
-import { generateDecorators } from "./generate-decorators.js";
+import { generateDecorators, generateDirectives } from "./generate-decorators.js";
 import {
   getTypeSpecPrimitiveFromSchema,
   isReferencedEnumType,
@@ -52,6 +52,7 @@ function generateEnum(tsEnum: TypeSpecEnum): string {
     definitions.push(generateDocs(tsEnum.doc));
   }
 
+  definitions.push(...generateDirectives(tsEnum.directives));
   definitions.push(...generateDecorators(tsEnum.decorators));
   definitions.push(`enum ${tsEnum.name} {`);
 
@@ -73,6 +74,7 @@ function generateScalar(scalar: TypeSpecScalar, context: Context): string {
     definitions.push(generateDocs(scalar.doc));
   }
 
+  definitions.push(...generateDirectives(scalar.directives));
   definitions.push(...generateDecorators(scalar.decorators));
   const type = context.generateTypeFromRefableSchema(scalar.schema, scalar.scope);
 
@@ -231,6 +233,7 @@ function generateUnion(union: TypeSpecUnion, context: Context): string {
     definitions.push(generateDocs(union.doc));
   }
 
+  definitions.push(...generateDirectives(union.directives));
   definitions.push(...generateDecorators(union.decorators));
 
   definitions.push(`union ${union.name} {`);
@@ -331,6 +334,7 @@ function generateModel(model: TypeSpecModel, context: Context): string {
     definitions.push(generateDocs(model.doc));
   }
 
+  definitions.push(...generateDirectives(model.directives));
   definitions.push(...generateDecorators(model.decorators));
   definitions.push(modelDeclaration.open);
 
@@ -370,6 +374,9 @@ export function generateModelProperty(
 ): string {
   const propertyType = context.generateTypeFromRefableSchema(prop.schema, containerScope);
 
+  // Directives come before decorators
+  const directives = generateDirectives(prop.directives);
+
   // Decorators will be a combination of top-level (parameters) and
   // schema-level decorators.
   const decorators = generateDecorators(
@@ -384,7 +391,10 @@ export function generateModelProperty(
 
   const doc = prop.doc ? generateDocs(prop.doc) : "";
 
-  return `${doc}${decorators} ${prop.name}${prop.isOptional ? "?" : ""}: ${context.getPartType(propertyType, prop.name, isModelReferencedAsMultipartRequestBody ?? false, encoding, isEnumType, isUnionType)};`;
+  // Format: doc, directives (each on new line), decorators (space separated), property definition
+  const directiveLines = directives.length > 0 ? directives.join("\n") + "\n" : "";
+
+  return `${doc}${directiveLines}${decorators} ${prop.name}${prop.isOptional ? "?" : ""}: ${context.getPartType(propertyType, prop.name, isModelReferencedAsMultipartRequestBody ?? false, encoding, isEnumType, isUnionType)};`;
 }
 
 export function generateModelExpression(

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

@@ -39,9 +39,15 @@ export interface TypeSpecExternalDocs {
   description?: string;
 }
 
+export interface TypeSpecDirective {
+  name: string;
+  message: string;
+}
+
 export interface TypeSpecDeclaration {
   name: string;
   doc?: string;
+  directives?: TypeSpecDirective[];
   decorators: TypeSpecDecorator[];
   scope: string[];
   fixmes?: string[];
@@ -142,6 +148,7 @@ export interface TypeSpecModelProperty {
   name: string;
   isOptional: boolean;
   doc?: string;
+  directives?: TypeSpecDirective[];
   /**
    * A partial list of decorators that can't be ascertained from
    * the schema.

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

@@ -8,7 +8,7 @@ import {
   TypeSpecUnion,
 } from "../interfaces.js";
 import { Context } from "../utils/context.js";
-import { getDecoratorsForSchema } from "../utils/decorators.js";
+import { getDecoratorsForSchema, getDirectivesForSchema } from "../utils/decorators.js";
 import { getScopeAndName } from "../utils/get-scope-and-name.js";
 
 /**
@@ -78,6 +78,7 @@ export function transformComponentSchemas(context: Context, models: TypeSpecData
     const tsEnum: TypeSpecEnum = {
       kind: "enum",
       ...getScopeAndName(name),
+      directives: getDirectivesForSchema(schema),
       decorators: getDecoratorsForSchema(schema),
       doc: schema.description,
       schema,
@@ -109,6 +110,7 @@ export function transformComponentSchemas(context: Context, models: TypeSpecData
       kind: "model",
       name,
       scope,
+      directives: [...getDirectivesForSchema(effectiveSchema)],
       decorators: [...getDecoratorsForSchema(effectiveSchema)],
       doc: effectiveSchema.description || schema.description,
       properties: [
@@ -154,6 +156,7 @@ export function transformComponentSchemas(context: Context, models: TypeSpecData
     const union: TypeSpecUnion = {
       kind: "union",
       ...getScopeAndName(name),
+      directives: getDirectivesForSchema(schema),
       decorators,
       doc: schema.description ?? unionMetadata.description,
       schema,
@@ -214,6 +217,7 @@ export function transformComponentSchemas(context: Context, models: TypeSpecData
     types.push({
       kind: "scalar",
       ...getScopeAndName(name),
+      directives: getDirectivesForSchema(schema),
       decorators: getDecoratorsForSchema(schema),
       doc: schema.description,
       schema: "$ref" in schema ? {} : schema,
@@ -346,6 +350,7 @@ function getModelPropertiesFromObjectSchema({
       doc: property.description,
       schema: property,
       isOptional: !required.includes(name),
+      directives: [...getDirectivesForSchema(property)],
       decorators: [...getDecoratorsForSchema(property)],
     });
   }

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

@@ -10,7 +10,7 @@ import {
   Refable,
 } from "../../../../types.js";
 import { stringLiteral } from "../generators/common.js";
-import { TSValue, TypeSpecDecorator } from "../interfaces.js";
+import { TSValue, TypeSpecDecorator, TypeSpecDirective } from "../interfaces.js";
 
 const validLocations = ["header", "query", "path"];
 const extensionDecoratorName = "extension";
@@ -247,6 +247,22 @@ export function getDecoratorsForSchema(
   return decorators;
 }
 
+export function getDirectivesForSchema(
+  schema: Refable<OpenAPI3Schema | OpenAPISchema3_1 | OpenAPISchema3_2>,
+): TypeSpecDirective[] {
+  const directives: TypeSpecDirective[] = [];
+
+  if ("$ref" in schema) {
+    return directives;
+  }
+
+  if (schema.deprecated) {
+    directives.push({ name: "deprecated", message: "deprecated" });
+  }
+
+  return directives;
+}
+
 function createTSValue(value: string): TSValue {
   return { __kind: "value", value };
 }