Consider adding nested block support as alternative to nested attribute

[austinvalle]

Use Cases or Problem Statement

Currently, the OpenAPI provider spec generator will always default to nested attributes when generating resource/data source/provider schemas with structural/collection types. This however requires that a provider be implemented with protocol v6 support and may not be desired for provider developers who want to use this tool for migrating from SDKv2 to Framework.

The provider code spec and tfplugingen-framework already support blocks.

Proposal

Implement support for generating nested blocks which can be supported on protocol v5. We want to encourage using nested attributes whenever possible, so we could introduce this as an opt-in configuration per-resource.

Example:

provider:
  name: petstore

data_sources:
  pet:
    read:
      path: /pet/{petId}
      method: GET
    schema:
      # Object = SingleNestedBlock, Collection = ListNestedBlock, Set= SetNestedBlock
      v5: true

There are likely some edge-cases we might not be able to handle or express fully with the code generator (such as maps), so we'll need to determine how best to surface this information to users.

Additional Information

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[bflad]

While the intent is good here, I think a generic resource-level "protocol version 5" flag is likely too broad of an abstraction. Folks who upgrade their providers to protocol version 6 only can (and likely still will want to) use blocks for existing configuration to prevent breaking changes. They should also be able to decide to use nested attributes for new features, while leaving those existing blocks. I would suggest doing this within the schema configuration per-attribute so developers can opt-out of nested attribute handling where necessary. I think its okay if its slightly more burden to use non-defaults and maybe it is also another small carrot to stop using blocks when possible for new implementations.

Another thing to consider is that folks may/will need to control the schema version in generated code, which is unrelated to the protocol version.

You could, however, use something like a provider-level "protocol version 5" flag as an additional validation so folks can get error from this project when nested attributes would be injected into the provider spec rather than discovering the problem later on during/after code generation.