[deathanatos]

I'm not sure what you mean by "it is very hard to give contextuality on it"; OAS does supports referring to a type by reference, so that higher level types can reuse the definition of structs they might contain.

But even so, here the problem is that the APIs aren't actual PUT/GETs: they payload types aren't the same going up as they are coming down. It is really two separate types, one for PUT, one for GET.

Some of that is to be expected (there will be some information after the create that is only added by the VM coming into being) but how Kubernetes handles this with a separate "status" for the item I think ends up letting the rest of the type (spec, in k8s's case) be the same type. (… ish. K8s has variants of this problem, too.)

To expand a bit, I'm largely relegated to the API docs themselves. Browsing the actual schema is hard:

  Start at: https://github.com/Azure/azure-rest-api-specs
  Descend into specification.
  Descend into … so many choices … compute.
  Descend into resource-manager.
  Descend into Microsoft.Compute
  Descend into stable
  Descend into — and this is tricky!
    the latest version isn't the latest version.
    The latest version is 2022-04-04, but for VM creation it's 2022-03-01.
    The only way I know to determine this is to seek backwards, or find it in the docs.
  Descend into ComputeRP
  Descend into virtualMachine.json.

And it's 3.3k LoC! Some of this verbosity is JSONSchema, to be sure… but still. And then you might have to wade back up to common.json, though I forget what circumstances cause me to need to look there.