Document behavior/validation limitations of nested attributes vs blocks

[asaba-hashi]

Module version

latest

Use-cases

When creating a terraform provider, the current document suggests the blocks should not be used:

Use nested attributes for new schema implementations. Block support is mainly for migrating prior SDK-based providers.

However, there are some validation differences:

type Things struct {
	A     types.Bool `tfsdk:"A"`
	B types.Bool `tfsdk:"B"`
}

type SomeResource struct {
   Things things
}

<snip>
"things": schema.SingleNestedAttribute{
				Attributes: map[string]schema.Attribute{
					"B": schema.BoolAttribute{
						Default:  booldefault.StaticBool(false),
						Optional: true,
						Computed: true,
					},
					"B": schema.BoolAttribute{
						Default:  booldefault.StaticBool(false),
						Optional: true,
						Computed: true,
					},
}
required: true,
}

resource "some_resource" "some_resource_name" {

  things = {
     A = true
     want_this_to_fail_validation = "but doesn't"
  }
}

Attempted Solutions

Reported as a bug here in #805 to terraform in hashicorp/terraform#33570, however, this can't be addressed in the near term for compatibility: hashicorp/terraform#33570 (comment)

Proposal

Documentation should be updated to include notes on the validation behavior of blocks compared to nested attributes.

References

[bflad]

While adding documentation around this is likely valid in some form, since it is an explicit behavior of Terraform, I believe we need to be careful about not confusing provider developers further. It is awkward for provider developers to choose how they believe practitioners should have to design their configurations since working with blocks is explicitly much harder and working with attributes is much easier. This really feels like a concern to be solved in the configuration validation/linting space, if a practitioner feels it is important. Provider developers should not be burdened with concerns outside of defining what is valid for their data input.

If you have proposals for specific wording and/or placement of that wording, it is certainly welcome feedback.

[asaba-hashi]

Based on the discussion of tradeoffs in hashicorp/terraform#33570, my suggestion would be to add a table to the nested attribute docs and reference it from the block docs, with the tradeoffs discussed listed:

|Nested Attributes | Blocks |
|------------------|--------|
|Easy|Hard|
|Can't validate extra fields/typos in optional fields| .... |
| ... | May require use of dynamic_blocks |

etc.

[bflad]

The maintainers have discussed this further with the Terraform core team and we all have decided that adding provider developer documentation that seems to discourage nested attributes usage is not preferable. While there is inherent risk that an attribute name typo may be introduced in a practitioner configuration, the resource plan should convey what data values are correctly being handled and the configuration benefits/ease for practitioners is generally worth the tradeoff. To that end, the preference here will be to leave the documentation as-is and monitor for similar developer reports to discover whether additional documentation in this area is warranted. Thank you for raising this. 👍

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.