From 37dabc87ce686ae4a74836d455961c98522e583e Mon Sep 17 00:00:00 2001 From: Brian Flad Date: Fri, 15 Mar 2024 15:06:45 -0400 Subject: [PATCH] docs: Explicitly call out object parameter attributes are required (#956) Reference: https://github.com/hashicorp/terraform-plugin-framework/issues/955 This attempts to document the existing behavior of Terraform and the framework with relation to object parameters requiring all object attributes to be explicitly configured by adding an early paragraph about the behavior. The other updates on the page are to continue the overall parameter page consistency of configuration examples being used in the implementation examples later in the pages, so here the `attr3` and `null` value handling is shown in all the examples. In the future, there may be enhancements which could enable "optional" object attributes at which time this new documentation can be updated in relation to that potential new functionality. --- .../framework/functions/parameters/object.mdx | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/website/docs/plugin/framework/functions/parameters/object.mdx b/website/docs/plugin/framework/functions/parameters/object.mdx index 0e4c8871c..edd2443ed 100644 --- a/website/docs/plugin/framework/functions/parameters/object.mdx +++ b/website/docs/plugin/framework/functions/parameters/object.mdx @@ -8,12 +8,15 @@ description: >- Object function parameters expect a single structure mapping explicit attribute names to type definitions from a practitioner configuration. Values are accessible in function logic by a Go structure type annotated with `tfsdk` field tags or the [framework object type](/terraform/plugin/framework/handling-data/types/object). -In this Terraform configuration example, a object parameter is set to the mapped values of `attr1` to `"value1"` and `attr2` to `123`: +Configurations must include all object attributes or a configuration error is raised. Configurations explicitly setting object attribute values to `null` will prevent this type of configuration error while leaving that object attribute value unset. The `AllowNullValue` setting does not need to be enabled for object attribute `null` values to work in this manner. + +In this Terraform configuration example, a object parameter is set to the mapped values of `attr1` to `"value1"`, `attr2` to `123`, and `attr3` to `null`: ```hcl provider::example::example({ - attr1 = "value1", - attr2 = 123, + attr1 = "value1" + attr2 = 123 + attr3 = null }) ``` @@ -34,6 +37,7 @@ func (f ExampleFunction) Definition(ctx context.Context, req function.Definition AttributeTypes: map[string]attr.Type{ "attr1": types.StringType, "attr2": types.Int64Type, + "attr3": types.BoolType, }, // ... potentially other ObjectParameter fields ... }, @@ -92,6 +96,7 @@ func (f ExampleFunction) Definition(ctx context.Context, req function.Definition AttributeTypes: map[string]attr.Type{ "attr1": types.StringType, "attr2": types.Int64Type, + "attr3": types.BoolType, }, }, }, @@ -102,11 +107,13 @@ func (f ExampleFunction) Run(ctx context.Context, req function.RunRequest, resp var objectArg struct{ Attr1 *string `tfsdk:"attr1"` Attr2 *int64 `tfsdk:"attr2"` + Attr3 *bool `tfsdk:"attr3"` } // e.g. with AllowNullValues // var objectArg *struct{ // Attr1 *string `tfsdk:"attr1"` // Attr2 *int64 `tfsdk:"attr2"` + // Attr3 *bool `tfsdk:"attr3"` // } // var objectArg types.Object // e.g. with AllowUnknownValues or AllowNullValues