Object Function Parameter

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.

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:

provider::example::example({
    attr1 = "value1"
    attr2 = 123
    attr3 = null
})

Function Definition

Use the function.ObjectParameter type in the function definition to accept an object value.

The AttributeTypes field must be defined, which represents a mapping of attribute names to framework value types. An attribute type may itself contain further collection or object types, if necessary.

In this example, a function definition includes a first position object parameter:

func (f ExampleFunction) Definition(ctx context.Context, req function.DefinitionRequest, resp *function.DefinitionResponse) {
    resp.Definition = function.Definition{
        // ... other Definition fields ...
        Parameters: []function.Parameter{
            function.ObjectParameter{
                AttributeTypes: map[string]attr.Type{
                    "attr1": types.StringType,
                    "attr2": types.Int64Type,
                    "attr3": types.BoolType,
                },
                Name: "object_param",
                // ... potentially other ObjectParameter fields ...
            },
        },
    }
}

If the map value should be the element type of another collection parameter type, set the ElementType field according to the framework object type. Refer to the collection parameter type documentation for additional details.

If the map value should be a value type of an object parameter type, set the AttributeTypes map value according to the framework object type. Refer to the object parameter type documentation for additional details.

Allow Null Values

By default, Terraform will not pass null values to the function logic. Use the AllowNullValue field to explicitly allow null values, if there is a meaningful distinction that should occur in function logic. Enabling AllowNullValue requires no changes when reading argument data.

Allow Unknown Values

By default, Terraform will not pass unknown values to the function logic. Use the AllowUnknownValues field to explicitly allow unknown values, if there is a meaningful distinction that should occur in function logic. Enabling AllowUnknownValues requires using a framework object type when reading argument data.

Custom Types

You may want to build your own data value and type implementations to allow your provider to combine validation and other behaviors into a reusable bundle. This helps avoid duplication and ensures consistency. These implementations use the CustomType field in the parameter type.

Refer to Custom Types for further details on creating provider-defined types and values.

Documentation

Refer to function documentation for information about the Name, Description, and MarkdownDescription fields available.

Reading Argument Data

The function implementation documentation covers the general methods for reading function argument data in function logic.

When retrieving the argument value for this parameter:

• If CustomType is set, use its associated value type.
• If AllowUnknownValues is enabled, you must use the framework object type.
• If AllowNullValue is enabled, you must use a pointer to the Go structure type annotated with tfsdk field tags or the framework object type.
• Otherwise, use the Go structure type annotated with tfsdk field tags or framework object type.

In this example, a function defines a single object parameter and accesses its argument value:

func (f ExampleFunction) Definition(ctx context.Context, req function.DefinitionRequest, resp *function.DefinitionResponse) {
    resp.Definition = function.Definition{
        // ... other Definition fields ...
        Parameters: []function.Parameter{
            function.ObjectParameter{
                AttributeTypes: map[string]attr.Type{
                    "attr1": types.StringType,
                    "attr2": types.Int64Type,
                    "attr3": types.BoolType,
                },
                Name: "object_param",
            },
        },
    }
}

func (f ExampleFunction) Run(ctx context.Context, req function.RunRequest, resp *function.RunResponse) {
    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

    resp.Error = function.ConcatFuncErrors(resp.Error, req.Arguments.Get(ctx, &objectArg))

    // objectArg is now populated
    // ... other logic ...
}