Resolve implicitOptionality for PATCH Operations in ARM services
- Dominant language
- TypeScript
- Stars
- 27
- Forks
- 90
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 156
Description
## Background
For PATCH operations, TypeSpec previously applied `implicitOptionality` to patch model properties following JSON merge patch semantics which would automatically making required properties optional in patch request bodies.
When TypeSpec changed the default, it explicitly set `implicitOptionality: true` on existing PATCH operations for backward compatibility.
But, this caused the problem of
1. SDK/Swagger discrepancy: typespec-autorest respects implicitOptionality: true and generates Swagger with optional properties, but TCGC does not support this decorator (https://github.com/Azure/typespec-azure/issues/3856)
2. There is ongoing discussion about the proper mechanism for handling patch model optionality. Until a decision is ready, service teams were advised to use `ArmCustomPatch*` templates and explicitly define their patch models, but many services were onboarded before this guidance.
## Impact Analysis
An analysis of all services using `implicitOptionality` in `azure-rest-api-specs` found:
SDK exposure:
5 services have API impact but no SDKs released yet in any language
25 services have API impact and have released TypeSpec-based SDKs
2 services have API impact and have released Swagger-based SDKs
2 services have API impact with SDKs released from both TypeSpec and Swagger
https://github.com/Azure/azure-rest-api-specs/pull/40140: Sets implicitOptionality to false for the 11 services with no API impact. But it does not solve all the problem : `implicitOptionality: true` is set across dozens of services, but no SDK emitter actually supports it, only typespec-autorest processes it for Swagger generation. This means every service using `implicitOptionality: true` has a inconsistency between their Swagger and their SDKs for certain languages.
## Proposed Options
Option A: TypeSpec / TCGC / Emitters support the update of Type graph to handle `implicitOptionality`
Option B: Eliminate the usage of implicitOptionality: true in ARM and migrate all existing specs to ArmCustomPatch*. Need linter rule to block service teams to set it.
Option C (Hybrid): Short-term lint & migration + long-term full support
Reference:
https://github.com/microsoft/typespec/issues/7279
https://github.com/Azure/typespec-azure/issues/2642
https://github.com/Azure/typespec-azure/issues/2643
Contributor guide
Assessment
This issue has not been assessed yet.