how to interpret body in bodyRoot

[qiaozha]

Playground Link
In this tsp

op test(@bodyRoot body: {@body body: Test}): void;

is the body parameter Test or an anonymous model with a property named body whose type is Test?
the openapi3 emitter result shows the former

but the type graph shows the later?

it's a real case https://github.com/Azure/azure-rest-api-specs/blob/ca4b71ab0e3bb7e4c44b44bf4d84d9c51f7b8264/specification/workloads/Workloads.SAPVirtualInstance.Management/SAPCentralServerInstance.tsp#L61, and seems quite common as azure operation template uses bodyRoot here
https://github.com/Azure/typespec-azure/blob/main/packages/typespec-azure-resource-manager/lib/operations.tsp#L502

According to #2868 (comment) it feels like the former is correct?

[qiaozha]

Can we have a linter rule to prevent the usage of body in bodyRoot? I wonder if there's a real case that customer has to write their typespec this way?

In the above case, the Azure operation template has been changed from @body to @bodyRoot according to this https://github.com/Azure/typespec-azure/pull/708/files pr, but is it really expected? I wonder if we can change the service typespec instead of changing the operation template here?

[timotheeguerin]

The azure specs shouldn't use @Body here it has no value and just pass start request

[allenjzhang]

@qiaozha , do you know the reason for them to declare this way? Why wouldn't it work just using StartRequest as Request parameter?

  start is ArmResourceActionAsync<
    SAPCentralServerInstance,
    {
      @doc("SAP Central Services instance start request body.")
      @body
      body?: StartRequest;
    },
    Foundations.OperationStatusResult
  >;

[qiaozha]

My guess is they want to override the body description, I can double confirm with the service team. But if service team should not use @body decorator in the operation template, would it be an indicator that we should add this linter rule?

[MaryGao]

@allenjzhang @timotheeguerin Just curious any reason we don't recommand to use it in this way? Personally I like the way to explicitly declare @body part within a @bodyRoot because it makes things simpler and easy to understand and we don't need to guess or infer the body part.

The reason we declare this way is we'd like to change the optionality for body parameter, the body parameter is optional for start but in our template this parameter is required. We see similar case in hybrid connectivity RP.

Back to the question the interpretion is clear for me, with the following case it means the body parameter is Test and relevant type graph just shows the spec definition, not shows the http operation information.

op test(@bodyRoot body: {@body body: Test}): void;

model Test {
  prop:string;
}

But if we remove the @body decorator here, the body part would be an anonymous model with a property named body whose type is Test and where the body optionality is inferred by bodyRoot parameter.

op test(@bodyRoot body: { body: Test }): void;

model Test {
  prop:string;
}

[MaryGao]

Offline confirmed with above comment, the idea of bodyRoot is just a replacement of body but the former one is allowed to add other query/path/header parameters. So any nesting like bodyRoot with body doesn't make sense if we are not in templates.

I'd like to confirm the followings:

• Is the nesting for bodyRoot with body not allowed(linter warning) or not recommended(an compiler error)? only for azure?
• how to update the body optionality with these arm templates? can we provide template like ArmResourceActionAsyncOptionalBody?

[markcowl]

Per discussion, sample template for the case in question here

[markcowl]

@timotheeguerin What does the BodyParameter actually show for one of these nested cases in HttpOperation? I suspect that if the OpenAPI emitters strip out a layer of nesting, so does getHttpOperation.