Required blocks in resources implemented with `terraform-plugin-framework` are listed as optional

[kangasta]

Terraform CLI and terraform-plugin-docs Versions

Terraform v1.8.2
on darwin_arm64

require github.com/hashicorp/terraform-plugin-docs v0.19.1

Provider Code

func (r *networkResource) Schema(_ context.Context, _ resource.SchemaRequest, resp *resource.SchemaResponse) {
	resp.Schema = schema.Schema{
		Attributes: map[string]schema.Attribute{
			// Omitted
		},
		Blocks: map[string]schema.Block{
			"ip_network": schema.ListNestedBlock{
				NestedObject: schema.NestedBlockObject{
					Attributes: map[string]schema.Attribute{
						// Omitted
					},
				},
				Validators: []validator.List{
					listvalidator.IsRequired(),
					listvalidator.SizeBetween(1, 1),
				},
			},
		},
	}
}

Expected Behavior

ip_network block is listed as required (with min and max items)

Actual Behavior

ip_network block is listed as optional

Steps to Reproduce

1. tfplugindocs with provider that has required blocks implemented with terraform-plugin-framework.

How much impact is this issue causing?

Medium

Logs

No response

Additional Information

Based on discussion in discuss.hashicorp.com this is a known issue from while ago, but there was no issue in this repository about the bug.

Code of Conduct

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

[bflad]

Hi @kangasta 👋 Thank you for raising this issue.

This tool is currently dependent on getting schema information from calling terraform providers schema -json command, which has limitations on what information is passed between the provider and Terraform. Not all information defined in terraform-plugin-framework schema code passes across that interface and unfortunately this is one of those cases. Schema blocks in Terraform technically do not have the concept of "required" or "optional" -- there is only the count of them in a configuration (0 or more). The Validators in that particular framework schema code enables configuration validation logic that only runs on the provider side (within the framework itself) without Terraform ever knowing about it. At some point we might introduce a new, separate interface so that provider documentation can pick up additional provider implementation details such as this, but there are no timelines associated with that effort yet.

In the meantime the best we could do with the existing information available from Terraform is potentially change how its rendered in the documentation (e.g. without distinguishing between "required" and "optional" for blocks). If you or anyone has particular design ideas around that, it would be great to hear.

Another way to avoid this particular documentation limitation is switch from blocks to nested attributes. All attributes in Terraform natively have the concept of "required" versus "optional". For new implementations, using nested attributes instead of blocks is typically recommended. Please note though that for existing schemas, this would be a breaking change as practitioners would have to slightly switch their configuration syntax.

[kangasta]

Maybe instead of just Required, Optional and Read-only the sections could be Required Attributes, Optional Attributes, Blocks and Read-only? I prepared PR to try that: #366

[kangasta]

Hello! I updated the related PR (#366) so that it renders blocks in separate H3 section only when user defines --blocks-section flag. This way existing documentation generation would not be affected.

For example on how this would look in Terraform registry documentation, see for instance upcloud_network resource.