Add guidelines to prefer "flat" over "nested" structures

[mikekistler]

Nesting complicates the user experience and should only be used when necessary. We should add guidance to use flat structures unless there is some significant value to nesting, with some specific examples where nesting does add value and where it does not.

[rkmanda]

Should we deprecate the use of x-ms-client-flatten and get rid of any guidance around it? while still keeping the guidance to encourage flatter schemas?

[JeffreyRichter]

Pasting my comment from Teams chat:
Well, getting rid of it now will probably break SDKs. However, I do not think that TypeSpec has an equivalent for flatten so breaking may happen anyway. For greenfield, services should design their schema as they want it and this is how it should appear to customers. x-ms-client-flatten was a bad idea; it makes debugging harder and it breaks json merge patch. We'd love to get rid of it but we prioritze not breaking customers who are using stuff that already GA'd.

[mikekistler]

I think we should deprecate the use of x-ms-flatten in greenfield services. As Jeffrey says, if it is already in place in a GA API, we'll just have to live with it.