Consider Allowing Usage of Custom Types for Nested Attributes

[bendbennett]

Module version

github.com/hashicorp/terraform-plugin-framework v0.15.0

Use-cases

In order to provider greater flexibility when using nested attributes, the ability to use a custom type for a nested attribute would be beneficial. This would provide the same advantages afforded when using custom types for simple types, for example using an RFC3339 type rather than a string type for the handling of strings that hold RFC3339 timestamps. See usage of a prototype for an RFC3339 type for an example.

Attempted Solutions

Helper functions can be created which will handle nested attributes in a specific way, but this is not as streamlined as having custom types for nested attributes where functions can be directly associated with the type.

Proposal

Refactoring to expose the NestedAttributes interface and having all attr.Value and any custom nested attribute implement a new FrameworkValue interface allows custom types to be used for nested attributes.

For example, the following terraform configuration, provider resource schema, model (for unmarshalling onto) and create function should allow the usage of a function associated with the custom type. Both a "standard" list nested attribute and a list nested attribute using a custom type are illustrated for comparison

Terraform Configuration

resource "example_resource" "example" {
  list_nested_attribute = [
    {
      int64_attribute = 9223372036854775807
      list_attribute  = ["list-element", "list-element"]
    },
    {
      int64_attribute = 9223372036854775807
      list_attribute  = ["list-element", "list-element"]
    }
  ]

  list_nested_attribute_custom = [
    {
      int64_attribute = 9223372036854775807
      list_attribute  = ["list-element", "list-element"]
    },
    {
      int64_attribute = 9223372036854775807
      list_attribute  = ["list-element", "list-element"]
    }
  ]

Provider Resource Schema

func (e *exampleResource) GetSchema(ctx context.Context) (tfsdk.Schema, diag.Diagnostics) {
	return tfsdk.Schema{
		Attributes: map[string]tfsdk.Attribute{
			"list_nested_attribute": {
				Optional: true,
				Attributes: tfsdk.ListNestedAttributes(map[string]tfsdk.Attribute{
					"int64_attribute": {
						Optional: true,
						Type:     types.Int64Type,
					},
					"list_attribute": {
						Optional: true,
						Type:     types.ListType{ElemType: types.StringType},
					},
				}),
			},
			"list_nested_attribute_custom": {
				Optional: true,
				Attributes: ListNestedAttributesCustomType{
					tfsdk.ListNestedAttributes(map[string]tfsdk.Attribute{
						"int64_attribute": {
							Optional: true,
							Type:     types.Int64Type,
						},
						"list_attribute": {
							Optional: true,
							Type:     types.ListType{ElemType: types.StringType},
						},
					}),
				},
			},
		},
	}, nil
}

Model

type exampleResourceData struct {
	ListNestedAttribute       types.List                      `tfsdk:"list_nested_attribute"`
	ListNestedAttributeCustom ListNestedAttributesCustomValue `tfsdk:"list_nested_attribute_custom"`

Create func

func (e *exampleResource) Create(ctx context.Context, req resource.CreateRequest, resp *resource.CreateResponse) {
	var data exampleResourceData

	diags := req.Plan.Get(ctx, &data)
	resp.Diagnostics.Append(diags...)

	if resp.Diagnostics.HasError() {
		return
	}

	data.ListNestedAttributeCustom.CustomFunc(ctx)

	diags = resp.State.Set(ctx, &data)
	resp.Diagnostics.Append(diags...)
}

Custom Type and Value Implementation

The following is an example of of a custom type and custom value that can be used for a custom nested list type described above.

type ListNestedAttributesCustomType struct {
	types.NestedAttributes
}

func (l ListNestedAttributesCustomType) Type() attr.Type {
	return ListNestedAttributesCustomTypeType{
		l.NestedAttributes.Type(),
	}
}

type ListNestedAttributesCustomTypeType struct {
	attr.Type
}

func (l ListNestedAttributesCustomTypeType) ValueFromTerraform(ctx context.Context, value tftypes.Value) (attr.Value, error) {
	val, err := l.Type.ValueFromTerraform(ctx, value)
	if err != nil {
		return nil, err
	}

	return ListNestedAttributesCustomValue{
		val.(types.List),
	}, nil
}

type ListNestedAttributesCustomValue struct {
	types.List
}

func (l ListNestedAttributesCustomValue) ToFrameworkValue() attr.Value {
	return l.List
}

func (l ListNestedAttributesCustomValue) CustomFunc(ctx context.Context) {
	tflog.Info(ctx, "calling CustomFunc on custom list nested attribute")
}

References

• Consider Allowing Usage of Custom Types for Structural Elements #508

[bflad]

Providers should now be able to implement this using the new datasource/schema, provider/schema, and resource/schema packages available in v0.17.0. 👍

[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.