Consider raising an implementation diagnostic for mismatched `CustomType` / `Attributes` combinations

[austinvalle]

Module version

github.com/hashicorp/terraform-plugin-framework v1.12.0

Relevant provider source code

func (r *thingResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
    resp.Schema = schema.Schema{
        Attributes: map[string]schema.Attribute{
            "nested_attr": schema.SingleNestedAttribute{
                // If this CustomType doesn't fully match the attributes below, you'll receive a confusing decoder error that suggests
                // there is a bug in terraform-plugin-framework. This is actually a provider implementation
                // error and should be surfaced earlier.
                CustomType: xtypes.CustomObjectType{
                    ObjectType: basetypes.ObjectType{
                        AttrTypes: map[string]attr.Type{
                            "attr_1": types.StringType,

                            // The following line is commented out to simulate a mismatch between the custom type
                            // and attributes below.
                            // "attr_2": types.StringType,
                        },
                    },
                },
                Required: true,
                Attributes: map[string]schema.Attribute{
                    "attr_1": schema.StringAttribute{
                        Required: true,
                    },
                    "attr_2": schema.StringAttribute{
                        Required: true,
                    },
                },
            },
        },
    }
}

Terraform Configuration Files

resource "examplecloud_thing" "this" {
  nested_attr = {
    attr_1 = "hello"
    attr_2 = "world"
  }
}

Actual Behavior

When a CustomType for a nested attribute or nested block does not match the Attributes/Blocks defined underneath, you'll receive an error when decoding any objects from Terraform (most likely, the configuration during validation). This occurs because the provider has an invalid implementation, due to the CustomType attributes not matching the actual schema attributes. Framework uses the attributes directly for GetProviderSchema (which is sent to Terraform core), but for all decoding operations, uses the actual type of the schema (including the custom types).

This issue exists for all nested attributes and nested blocks that define a custom object type. You'll receive a confusing decoding error that suggests there is a bug in terraform-plugin-framework.

 $ terraform validate
╷
│ Error: Unable to Convert Configuration
│ 
│   with examplecloud_thing.this,
│   on resource.tf line 13, in resource "examplecloud_thing" "this":
│   13: resource "examplecloud_thing" "this" {
│ 
│ An unexpected error was encountered when converting the configuration from the protocol type. This is always an issue in terraform-plugin-framework used to implement the provider and should be reported to the provider developers.
│ 
│ Please report this to the provider developer:
│ 
│ Unable to unmarshal DynamicValue: AttributeName("nested_attr"): error decoding object; expected 1 attributes, got 2

Expected Behavior

As this is a provider implementation problem, we should have received a more explicit error message indicating that the CustomType field does not match the Attributes provided and that the provider needs to update it's implementation to match the two. This can be returned during GetProviderSchema, similar to the other invalid implementation diagnostics we do today.

References

• Semi-related to #https://github.com/hashicorp/terraform-plugin-framework/issues/947
• Semi-related to #https://github.com/hashicorp/terraform-plugin-framework/issues/774