[Ask] Do we allow mixed usage for models among mfd and non-mfd operations?

[MaryGao]

Background

Below cases are relevant to multipart/form-data I've derived from todo spec and I'd like to confirm if we have any limitation on model sharing among mfd and non-mfd operations in typespec side?

I am asking because if the model is used in a mfd operation, emitters may handle them differently and generate different APIs for that model. And previously tcgc tried to add some limitations on model mixed usage and would report errors(tcgc diagnostic code) and I guess this is for Azure scope? Then how about unbranded?

playground here

Todo Spec Cases

Say we have models with TodoFileAttachment. The first question would be:

• Do we allow File(spec) to be used as non-mfd operations for example op createJson(@header contentType: "application/json", contents: File): void;?

model TodoFileAttachment is File;

I would assume yes, since this is todo's pr demoed. Then we could have the model referenced by mfd and non-mfd ops.

• For Case1, TodoFileAttachment is used in application/json operation.
• For Case2, TodoFileAttachment is used as mfd body type directly.
• For Case3, TodoFileAttachment is used as a property of mfd body type.

Here are the questions on how to intercept them:

• For Case1, for bytes property contents in File, should we intercept as base64 string? How about it is used in other content type? Will we intercept bytes differently?
• Can Case1 and Case2 co-exist in the same spec? Currently this is NOT allowed in tcgc and tcgc would report errors(tcgc diagnostic code).
• Can Case1 and Case3 co-exist in the same spec? Currently tcgc would allow this case.

// Case1 - createJson: TodoFileAttachment is used as a normal operation
@post
@sharedRoute
op createJson(
  @header contentType: "application/json",
  item: TodoItem,
  attachments?: TodoFileAttachment[],
): TodoItem;

// Case2 - createForm: TodoFileAttachment is uesed as multipart body type
@post
op createForm(
  @header contentType: "multipart/form-data",
  @path itemId: TodoItem.id,
  @body contents: TodoFileAttachment,
): NoContentResponse | NotFoundResponse;

// Case3 - createFileAttachment: TodoUrlAttachment is used as multipart body property
@sharedRoute
@post
op createFileAttachment(
  @header contentType: "multipart/form-data",
  @multipartBody body: {
    item: HttpPart<TodoItem>;
    attachments?: HttpPart<TodoFileAttachment>[];
  },
): TodoItem;

This is a confirmation issue and feel free to close if above questions are clear and answered from typespec side.

[msyyc]

My understanding:

• For application/json, its default encode shall be base64 and we already have similar cadl-ranch case: https://github.com/Azure/cadl-ranch/blob/c04dcb2bbb3c8d1144ccb167cff89cdf54c3b3cf/packages/cadl-ranch-specs/http/encode/bytes/main.tsp#L96-L112
• For case 2, I haven't seen any real service use multipart like that and I am not sure whether it is valid case since File part in multipart payload needs fieldname which is usually same as property name of a body type.
• Python has no motivation to prohibit that Case1 and Case3 co-exist in the same spec

[markcowl]

I think this is the intention of how bytes should be interpreted @bterlson @witemple-msft @chrisradek @AlitzelMendez feedback appreciated.

• in a single part message body with a json content-type, like application/json, bytes should be treated as a base64 encoded string
• in a single part message body with a binary content-type, like application/octet-stream, bytes should be treated as raw bytes
• in a multipart message body
  • by default (no supplied media type), bytes should be treated as a stream of bytes
  • In a part with a json media type, bytes should be treated as a base64-encoded string
  • in a part with a binary media type, bytes should be treated as raw bytes

[MaryGao]

• Can Case1 and Case2 co-exist in the same spec? Currently this is NOT allowed in tcgc and tcgc would report errors(tcgc diagnostic code).
• Can Case1 and Case3 co-exist in the same spec? Currently tcgc would allow this case.

@markcowl Any idea if we allow to share the models among mfd and non-mfd operations for unbranded?

[qiaozha]

@markcowl I want to point out the previous bytes related discussion is still pending on typespec side bytes loop