Document why we don't allow shared object definitions to be reused in api.yaml

[melinath]

Affected Resource(s)

• google_*

A lot of GCP APIs have a concept of "shared objects" that get used multiple times inside a particular REST API. Currently developers need to hand-copy the definitions for these objects into all the places they're used, which is toilsome and error-prone, and can easily get out of sync over time. For example: https://cloud.google.com/datastream/docs/reference/rest/v1/projects.locations.streams#oraclesourceconfig includes two references to OracleRdbms, which is a complex nested structure.

We should allow defining these shared objects in api.yaml and then referencing them instead.

[rileykarson]

I am personally a strong opponent of this one. We've seen time and time again that they aren't as shared as they initially seem, with different sets of validations and required fields. https://github.com/GoogleCloudPlatform/declarative-resource-client-library represented resources this way, but actually took steps to revert it based on many of them being invalid.

Additionally, this significantly increases the complexity of the generator. We saw with the DCL generator that it required extensive annotations throughout- pretty much from top to bottom- as an implementation is pretty much required to be parasitic throughout the codebase.

[melinath]

that makes sense - I'm down with not implementing it but in that case I'd change this ticket to cover documenting the reasoning for not covering it, so that contributors understand why they're being asked to do the toil.