[Epic] Design for PATCH operation models from TypeSpec

[pshao25]

Tasks

Preview Give feedback

1. Generate models with patch serialization.
2. Generate convenience methods for 1) models don’t contain array, and 2) models contain both array and etag
3. Deal with models containing array but not etag.

Related tasks

Preview Give feedback

1. Visibility User experience azure-sdk-for-net#47676
   Client CodeGen +2
   
2. Visibility Implementation azure-sdk-for-net#47677
   Client CodeGen +2
   

[chunyu3]

duplicate with #2492

[pshao25]

Original design

A model only in patch request

According to api guidelines,

• PUT request/response, PATCH response, GET response, and POST request/response could share the same schema.
• PATCH request schema should contain all the same fields with no required fields.

All the properties in the PATCH request of generated SDK should be optional.

Case 1: The properties in spec are all optional

@resource("testV2")
model TestV2 {
  optionalProperty?: string;
}

interface DynamicData {
  patch is ResourceCreateOrUpdate<TestV2>;
}

Option 1 (Don't change name): It follows the api guidance so just go with the design in Azure/azure-sdk-for-net#37341
Option 2 (Change name): Still change name to e.g. TestV2Update, for the purpose of 1) be consistent with case 2 below, 2) service driven scenario below.

Case 2: Still have required properties in spec because response could have the required properties

@resource("testV2")
model TestV2 {
  requiredProperty: string;
  optionalProperty?: string;
}

interface DynamicData {
  patch is ResourceCreateOrUpdate<TestV2>;
}

This means input is {optionalProperty: xxx} and response is {optionalProperty: xxx, requiredProperty: xxx}.

Option 1: We may need a linter in emitter to block required properties in spec. And let users to choose one of:

1. Declare a new model with only optional properties as input in client.net.tsp
2. Use @visibility("read") to exclude required properties.

Option2: We think it is valid spec by implicitly creating a new model e.g. TestV2Update with requiredProperty changing to optional.

A model in both patch request and other operations

@resource("testV2")
model TestV2 {
  optionalProperty?: string;
}

interface DynamicData {
  patch is ResourceCreateOrUpdate<TestV2>;
  put is ResourceCreateOrReplace<TestV2>;
  get is ResourceRead<TestV2>;
}

Option 1: block this by linter "same model cannot be both in the patch request and other operations". Again, let users to choose one of:

1. Declare a new model with only optional properties as input in client.net.tsp
2. Use e.g. @visibility("create") to exclude required properties. We don't support this now.

Option 2: generate normal TestV2 to PUT and GET, and a new model TestV2Update to PATCH with patch pattern.

Service driven story

Case 1: first has a PATCH and then has a PUT/GET

// V1
patch is ResourceCreateOrUpdate<TestV2>;

// V2
patch is ResourceCreateOrUpdate<TestV2>;
put is ResourceCreateOrReplace<TestV2>;

Case 2: first has a PUT/GET and then has a PATCH

// V1
put is ResourceCreateOrReplace<TestV2>;

// V2
patch is ResourceCreateOrUpdate<TestV2>;
put is ResourceCreateOrReplace<TestV2>;

Considering both of these two scenarios, it might be necessary to have a new model e.g. TestV2Update to patch operation.