Consider Removing Block MaxItems/MinItems Fields

[bflad]

Module version

v0.10.0

Use-cases

When validating a Terraform configuration, there are the following high level concepts:

• HCL syntax checking by Terraform core, such as allowed characters, tokenization, formatting, etc.
• Terraform-specific syntax checking by Terraform core, such as resource blocks that accept type and name labels
• Provider-specific syntax checking by Terraform core, such as attribute types and structure from provider, data source, and resource schemas
• Provider-specific semantic value checking by the provider (any SDK and provider logic), such as expected string length constraints, number of list elements, or another attribute being required when one is configured

The first two levels of validation are essentially done together, courtesy of how HCL implementations work, so practitioners receive those classes of configuration errors together. The third level may be bundled in those errors as well, but I personally do not know the intimate details of that Terraform core implementation. Any potential validation errors from the fourth, semantic level is wholly separate as Terraform core calls a Validate*Config RPC and is expected to pass schema-valid data to the provider.

The protocol between Terraform core and providers implements very light validation support at the third level, essentially only for specifying the maximum and minimum number of configuration blocks. If specified and the configuration blocks are "hardcoded" (e.g. not using dynamic), Terraform core can potentially produce an error on its side. There are various situations that prevent this type of validation from triggering, such as unknown values.

In the framework currently, the Terraform core block count validation can be defined via:

tfsdk.Block{
  // other fields omitted for brevity
  MaxItems: 2,
  MinItems: 2,
}

Or the provider block count validation can be defined via:

tfsdk.Block{
  // other fields omitted for brevity
  Validators: []tfsdk.AttributeValidator{
    listvalidator.SizeBetween(2, 2),
  },
}

For reference, attributes always use validators:

tfsdk.Attribute{
  // other fields omitted for brevity
  Validators: []tfsdk.AttributeValidator{
    listvalidator.SizeBetween(2, 2),
  },
}

Practitioners may benefit from there error messages being consolidated to just the provider-side validation. Provider developers may benefit from defining attribute and block validation similarly.

One note: The MaxItems/MinItems fields are used by tooling like terraform-plugin-docs in the block documentation. To keep documentation parity if the fields were removed, descriptions would require manual updates to include text around the number of expected elements, until enhanced documentation generation support is available that can read the descriptions of each validator.

Proposal

Remove the MaxItems/MinItems fields from blocks and instead encourage the usage of validators, similar to attributes.

References

• https://github.com/hashicorp/terraform-plugin-framework/issues/421
• https://github.com/hashicorp/terraform-plugin-framework/pull/422
• https://github.com/hashicorp/terraform/issues/30669#issuecomment-1192547643

[YakDriver]

I think this is a good idea. Nothing worse than errors introduced from multiple ways to do the same thing.

[github-actions[bot]]

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.