Bug: CustomType nested attributes silently ignore unknown attributes

[hanneshayashi]

Summary

Unknown/invalid attributes in nested blocks using CustomType are silently ignored instead of being rejected with an error.

Reproduction

resource "doit_alert" "test" {
  name = "test-alert"
  config = {
    metric = {
      type              = "basic"
      value             = "cost"
      this_is_invalid   = "should_fail"  # Should cause an error!
    }
    time_interval = "month"
    value         = 1000
    currency      = "USD"
    condition     = "value"
    operator      = "gt"
  }
}

Expected Behavior

terraform plan should fail with "Unsupported argument" error.

Actual Behavior

terraform plan succeeds. The invalid attribute is silently discarded.

Root Cause

The schema uses CustomType: MetricType{} for nested blocks. While MetricValue.AttributeTypes() only defines specific attributes, the Terraform Plugin Framework does not reject extra attributes when using custom types.

Affected Resources

All resources with nested blocks using CustomType: doit_alert, doit_budget, doit_allocation, doit_report

References

• Test configuration: .test/schema-validation-test/main.tf
• Schema definition: internal/provider/resource_alert/alert_resource_gen.go:84-105

[hanneshayashi]

Root Cause Analysis

After deeper investigation, here's the detailed explanation of why extra attributes are silently ignored:

How Schema Validation Works in Terraform Plugin Framework

Component	Used For	Source
Attributes map in SingleNestedAttribute	GetProviderSchema → Terraform core for HCL validation	Schema definition
CustomType.AttrTypes	Provider-side decoding/processing of values	CustomType initialization

The Flow

1. Terraform core validates HCL against the Attributes map in SingleNestedAttribute
2. When the schema has CustomType, the framework uses CustomType.AttrTypes for decoding
3. The code at ValueFromTerraform (in basetypes/object_type.go:92-98) iterates only over input keys:

   for k, v := range val {
       a, err := o.AttrTypes[k].ValueFromTerraform(ctx, v)
       // if k not in AttrTypes → nil pointer access
   }

Why No Drift?

Extra attributes are discarded during the initial parsing before terraform plan compares config vs state:

• Config (after parsing) = {type: "basic", value: "cost"} (extra attrs removed)
• State after apply = {type: "basic", value: "cost"}
• No drift detected! ✅ (but user intent was silently lost)

Why Top-Level Works But Nested Doesn't?

• Top-level attributes: Use regular schema validation (no CustomType) → validated by Terraform core → rejects unknown attrs
• Nested CustomType blocks: Bypass core validation channel → silently ignore unknown attrs

Test Results

Test Case	Result
extra_at_toplevel = "foo" at resource root	❌ Rejected with "Unsupported argument"
extra_in_config = "foo" inside config block	⚠️ Silently ignored
extra_in_metric = "foo" inside metric block	⚠️ Silently ignored

Affected Code

Looking at alert_resource_gen.go:97-105, the metric schema has BOTH Attributes map AND CustomType:

"metric": schema.SingleNestedAttribute{
    Attributes: map[string]schema.Attribute{
        "type":  schema.StringAttribute{...},
        "value": schema.StringAttribute{...},
    },
    CustomType: MetricType{
        ObjectType: types.ObjectType{
            AttrTypes: MetricValue{}.AttributeTypes(ctx),
        },
    },
    ...
}

These match correctly, but the validation just isn't happening at the Terraform core layer for CustomType nested attributes.

Conclusion

This is documented framework behavior, not a bug per se. The framework assumes the provider correctly aligns Attributes and CustomType.AttrTypes. Extra user-provided attributes are silently dropped during decoding.

Potential Fixes

1. Implement xattr.ValidateableAttribute on custom types to explicitly reject unknown attributes
2. Add custom validators that check for unexpected keys
3. File upstream issue with HashiCorp if stricter validation is desired

References

• Test config: .test/schema-validation-test/main.tf
• Framework source: basetypes/object_type.go:92-98
• tftypes validation (exists but not triggered): tftypes/object.go:211-214

[hanneshayashi]

Investigation: Provider-Level Fix Is Not Feasible

After in-depth investigation across three potential fix approaches, the conclusion is that this issue lives in Terraform core's type conversion layer and cannot be fixed at the provider or code generator level.

Background

When SingleNestedAttribute uses CustomType (as all our generated nested blocks do), unknown/invalid attribute keys like dataSource (camelCase) or this_is_totally_invalid are silently discarded instead of raising an "Unsupported argument" error. Without CustomType, the Terraform Plugin Framework correctly rejects unknown keys.

Approaches Investigated

Approach A: Modify ValueFromTerraform in code generator

The generated CustomType has a ValueFromTerraform method (template) that iterates over incoming tftypes.Value keys. The idea was to add unknown-key rejection here.

Result: ❌ Not feasible. The unknown keys are already stripped by Terraform core's tftypes.Object type conversion before ValueFromTerraform is called. This method never sees the invalid keys.

Approach B: Remove CustomType from generated code

Without CustomType, SingleNestedAttribute correctly rejects unknown keys via the framework's built-in validation.

Result: ⚠️ Technically works, but impractical. Removing CustomType means losing typed struct access (e.g., plan.Config.DataSource.ValueString() becomes plan.Config.Attributes()["data_source"].(types.String).ValueString()). This loses compile-time type safety, requires massive provider refactoring, and would never be accepted upstream.

Approach C: Per-resource ConfigValidator

Add a resource.ConfigValidator that reads req.Config.Raw (the raw tftypes.Value) and checks for unknown keys.

Result: ❌ Not feasible. Experiment proved that req.Config.Raw is also pruned by Terraform core.

Experiment

Added a debug ConfigValidator to doit_report that dumps all keys from req.Config.Raw:

func (v debugConfigValidator) ValidateResource(ctx context.Context, req resource.ValidateConfigRequest, resp *resource.ValidateConfigResponse) {
    var raw map[string]tftypes.Value
    req.Config.Raw.As(&raw)
    configVal := raw["config"]
    var configMap map[string]tftypes.Value
    configVal.As(&configMap)
    keys := make([]string, 0, len(configMap))
    for k := range configMap { keys = append(keys, k) }
    sort.Strings(keys)
    resp.Diagnostics.AddWarning("debug", fmt.Sprintf("%v (count: %d)", keys, len(keys)))
}

Test config included two invalid keys:

config = {
  dataSource              = "billing"   # ❌ camelCase (should be data_source)
  this_is_totally_invalid = "test"      # ❌ completely unknown
  data_source             = "billing"   # ✅ valid
  time_interval           = "month"     # ✅ valid
}

Output:

│ Warning: debug
│
│ [advanced_analysis aggregation currency custom_time_range data_source
│ dimensions display_values filters group include_promotional_credits
│ include_subtotals layout metric metric_filter metrics sort_dimensions
│ sort_groups splits time_interval time_range] (count: 20)

Only the 20 known schema keys appeared. Both dataSource and this_is_totally_invalid were silently stripped. No error was raised.

Root Cause

Terraform's core type system (tftypes.Object) is designed to accept any value containing at least the declared attributes, silently discarding extras during type conversion. This happens in Terraform CLI itself, before the provider plugin receives the config via gRPC. When CustomType is used, it defines a TerraformType() that returns a tftypes.Object with fixed attribute names — Terraform core uses this to filter the incoming HCL config.

Without CustomType, the framework uses a different code path that performs explicit key validation against the schema's Attributes map, which is why it correctly rejects unknown keys.

Conclusion

This is a Terraform core limitation that cannot be worked around at the provider level. The only true fixes would be:

1. Upstream fix in terraform-plugin-framework: Change how CustomType interacts with the schema validation to preserve the "Unsupported argument" check
2. Upstream fix in Terraform CLI: Make tftypes.Object conversion strict (reject extra keys) — though this is a deliberate design decision for backward compatibility
3. Upstream fix in terraform-plugin-codegen-framework: Generate code that doesn't use CustomType but retains type safety (requires significant design work)

For now, the best mitigation is documentation (already added to the v1 upgrade guide) emphasizing that all config attributes must use snake_case.

[hanneshayashi]

Related upstream issues in terraform-plugin-framework:

• hashicorp/terraform-plugin-framework#1049 — Consider raising an implementation diagnostic for mismatched CustomType / Attributes combinations: Documents the schema/CustomType duality where the framework uses Attributes for GetProviderSchema (sent to Terraform core) but uses CustomType for decoding. This is the mechanism that causes unknown keys to be silently dropped — Terraform core only knows about the Attributes, while the CustomType's AttrTypes control what keys survive type conversion.

• hashicorp/terraform-plugin-framework#774 — Consider Exported Reflection Helper for Model Type Attribute Types: Discusses the fundamental challenge of keeping CustomType attribute types in sync with schema attributes, which is the underlying design issue that makes our problem possible.