Azure / Azure/typespec-azure

Resolve implicitOptionality for PATCH Operations in ARM services

Open
#4,266 3 comments 0 reactions 1 assignee Claimed by @pshao25 View on GitHub
emitter:client:all lib:azure-resource-manager
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.