Warn usage of implicitOptionality in @patch with deprecation (#9884)

fix  #7235

---------

Co-authored-by: Copilot <copilot@github.com>

Author: timotheeguerin

.chronus/changes/replace-patch-implicit-optionality-warning-2026-2-3-15-59-37-2.md

@@ -0,0 +1,9 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: internal
+packages:
+  - "@typespec/http-specs"
+  - "@typespec/rest"
+---
+
+Add suppressions for deprecated behavior

.chronus/changes/replace-patch-implicit-optionality-warning-2026-2-3-15-59-37.md

@@ -0,0 +1,41 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: deprecation
+packages:
+  - "@typespec/http"
+---
+
+Deprecate use of `@patch(#{implicitOptionality: true})`.
+
+Migrate using one of the following patterns depending on intended semantics:
+
+1. Preserve previous behavior with an explicit patch model (optional properties)
+
+```diff lang=typespec
+  model Pet {
+    name: string;
+    age: int32;
+  }
+
++ model PetPatch {
++    name?: string;
++    age?: int32;
++ }
+
+  
+- @patch(#{implicitOptionality: true}) op updatePet(@body patch: Pet): void;
++ @patch op updatePet(@body patch: PetPatch): void;
+```
+
+2. Use merge-patch semantics explicitly with `MergePatchUpdate<T>`
+
+```typespec
+model Pet {
+  name: string;
+  age: int32;
+}
+
+@patch op updatePet(@body patch: MergePatchUpdate<Pet>): void;
+```
+
+Use `MergePatchCreateOrUpdate<T>` when the operation supports create-or-update behavior.

packages/http-specs/specs/type/model/visibility/main.tsp

@@ -88,6 +88,7 @@ op headModel(@bodyRoot input: VisibilityModel): OkResponse;
 @put
 op putModel(@body input: VisibilityModel): void;
 
+#suppress "@typespec/http/deprecated-implicit-optionality" "for legacy test"
 @scenario
 @scenarioDoc("""
   Generate abd send put model with write/update properties.

packages/http/README.md

@@ -344,11 +344,10 @@ Specify the HTTP verb for the target operation to be `PATCH`.
 @patch op update(pet: Pet): void;
 ```
 
+###### Using MergePatch template for proper merge-patch semantics
+
 ```typespec
-// Disable implicit optionality, making the body of the PATCH operation use the
-// optionality as defined in the `Pet` model.
-@patch(#{ implicitOptionality: false })
-op update(pet: Pet): void;
+@patch op update(@body pet: MergePatchUpdate<Pet>): void;
 ```
 
 #### `@path`

packages/http/generated-defs/TypeSpec.Http.ts

@@ -244,12 +244,9 @@ export type PostDecorator = (
  * ```typespec
  * @patch op update(pet: Pet): void;
  * ```
- * @example
+ * @example Using MergePatch template for proper merge-patch semantics
  * ```typespec
- * // Disable implicit optionality, making the body of the PATCH operation use the
- * // optionality as defined in the `Pet` model.
- * @patch(#{ implicitOptionality: false })
- * op update(pet: Pet): void;
+ * @patch op update(@body pet: MergePatchUpdate<Pet>): void;
  * ```
  */
 export type PatchDecorator = (

packages/http/lib/decorators.tsp

@@ -266,6 +266,12 @@ model PatchOptions {
   /**
    * If set to `false`, disables the implicit transform that makes the body of a
    * PATCH operation deeply optional.
+   *
+   * @deprecated `implicitOptionality` is deprecated and will be removed.
+   *   To preserve the previous behavior, define and use an explicit patch model
+   *   with optional properties for your `@body` parameter.
+   *   For actual JSON Merge Patch behavior, use `MergePatchUpdate<T>` as the
+   *   `@body` type (for example: `@patch op update(@body pet: MergePatchUpdate<Pet>): void;`).
    */
   implicitOptionality?: boolean;
 }
@@ -281,12 +287,9 @@ model PatchOptions {
  * @patch op update(pet: Pet): void;
  * ```
  *
- * @example
+ * @example Using MergePatch template for proper merge-patch semantics
  * ```typespec
- * // Disable implicit optionality, making the body of the PATCH operation use the
- * // optionality as defined in the `Pet` model.
- * @patch(#{ implicitOptionality: false })
- * op update(pet: Pet): void;
+ * @patch op update(@body pet: MergePatchUpdate<Pet>): void;
  * ```
  */
 extern dec patch(target: Operation, options?: valueof PatchOptions);

packages/http/src/decorators.ts

@@ -416,7 +416,15 @@ export const $patch: PatchDecorator = (
 ) => {
   _patch(context, entity);
 
-  if (options) setPatchOptions(context.program, entity, options);
+  if (options) {
+    if (options.implicitOptionality === true) {
+      reportDiagnostic(context.program, {
+        code: "deprecated-implicit-optionality",
+        target: entity,
+      });
+    }
+    setPatchOptions(context.program, entity, options);
+  }
 };
 
 /**

packages/http/src/lib.ts

@@ -195,6 +195,12 @@ export const $lib = createTypeSpecLibrary({
         default: paramMessage`The 'contents' property of the file model must be a scalar type that extends 'string' or 'bytes'. Found '${"type"}'.`,
       },
     },
+    "deprecated-implicit-optionality": {
+      severity: "warning",
+      messages: {
+        default: `The implicitOptionality option is deprecated. To preserve previous behavior, use an explicit patch model with optional properties. For actual merge-patch semantics, use MergePatchUpdate<T> for the @body type.`,
+      },
+    },
     "merge-patch-contains-null": {
       severity: "error",
       messages: {

packages/http/test/http-decorators.test.ts

@@ -50,6 +50,26 @@ describe("http: decorators", () => {
         message: `Argument of type '"/test"' is not assignable to parameter of type 'valueof TypeSpec.Http.PatchOptions'`,
       });
     });
+
+    it(`@patch emits deprecation warning when implicitOptionality: true`, async () => {
+      const diagnostics = await Tester.diagnose(`
+        @patch(#{ implicitOptionality: true }) op test(): string;
+        `);
+
+      expectDiagnostics(diagnostics, {
+        code: "@typespec/http/deprecated-implicit-optionality",
+        message:
+          "The implicitOptionality option is deprecated. To preserve previous behavior, use an explicit patch model with optional properties. For actual merge-patch semantics, use MergePatchUpdate<T> for the @body type.",
+      });
+    });
+
+    it(`@patch does not emit deprecation warning when implicitOptionality: false`, async () => {
+      const diagnostics = await Tester.diagnose(`
+        @patch(#{ implicitOptionality: false }) op test(): string;
+        `);
+
+      expectDiagnosticEmpty(diagnostics);
+    });
   });
 
   describe("@header", () => {

packages/openapi3/test/metadata.test.ts

@@ -99,6 +99,7 @@ worksFor(supportedVersions, ({ openApiFor }) => {
         @visibility(Lifecycle.Read, Lifecycle.Update, Lifecycle.Create) ruc?: string;
       }
       @parameterVisibility(Lifecycle.Create, Lifecycle.Update)
+      #suppress "@typespec/http/deprecated-implicit-optionality" "testing legacy behavior"
       @route("/") @patch(#{implicitOptionality: true}) op createOrUpdate(...M): M; 
     `);
 
@@ -176,7 +177,8 @@ worksFor(supportedVersions, ({ openApiFor }) => {
         person: Person;
         relationship: string;
       }
-      @route("/") @patch(#{implicitOptionality: true}) op update(...Person): Person; 
+      @route("/") #suppress "@typespec/http/deprecated-implicit-optionality" "testing legacy behavior"
+      @patch(#{implicitOptionality: true}) op update(...Person): Person; 
     `);
 
     const response = res.paths["/"].patch.responses["200"].content["application/json"].schema;
@@ -217,6 +219,7 @@ worksFor(supportedVersions, ({ openApiFor }) => {
         weight: float64;
       }
       @post op create(...Widget): void;
+      #suppress "@typespec/http/deprecated-implicit-optionality" "testing legacy behavior"
       @patch(#{implicitOptionality: true}) op update(...Widget): void;
   `);
 
@@ -358,6 +361,7 @@ worksFor(supportedVersions, ({ openApiFor }) => {
       @get get(...M): M;
       @post create(...M): M;
       @put createOrUpdate(...M): M;
+      #suppress "@typespec/http/deprecated-implicit-optionality" "testing legacy behavior"
       @patch(#{implicitOptionality: true}) update(...M): M;
       @delete delete(...M): void; 
     }
@@ -367,6 +371,7 @@ worksFor(supportedVersions, ({ openApiFor }) => {
       @get get(...D): D;
       @post create(...D): D;
       @put createOrUpdate(...D): D;
+      #suppress "@typespec/http/deprecated-implicit-optionality" "testing legacy behavior"
       @patch(#{implicitOptionality: true}) update(...D): D;
       @delete delete(...D): void; 
     }
@@ -376,6 +381,7 @@ worksFor(supportedVersions, ({ openApiFor }) => {
       @get op get(id: string): R;
       @post op create(...R): R;
       @put op createOrUpdate(...R): R;
+      #suppress "@typespec/http/deprecated-implicit-optionality" "testing legacy behavior"
       @patch(#{implicitOptionality: true}) op update(...R): R;
       @delete op delete(...D): void; 
     }
@@ -384,6 +390,7 @@ worksFor(supportedVersions, ({ openApiFor }) => {
       @get op get(id: string): U;
       @post op create(...U): U;
       @put op createOrUpdate(...U): U;
+      #suppress "@typespec/http/deprecated-implicit-optionality" "testing legacy behavior"
       @patch(#{implicitOptionality: true}) op update(...U): U;
       @delete op delete(...U): void;
     }
@@ -1087,6 +1094,7 @@ worksFor(supportedVersions, ({ openApiFor }) => {
         id: uuid;
       }
       
+      #suppress "@typespec/http/deprecated-implicit-optionality" "testing legacy behavior"
       @patch(#{implicitOptionality: true}) op test(...Bar): Bar;
     `);
 
@@ -1102,6 +1110,7 @@ worksFor(supportedVersions, ({ openApiFor }) => {
         id: string;
       }
       
+      #suppress "@typespec/http/deprecated-implicit-optionality" "testing legacy behavior"
       @patch(#{implicitOptionality: true}) op test(bar: Bar): void;
 
       model Foo {