Parameters

Parameters in function definitions describes how data values are passed to the function logic. Every parameter type has an associated value type, although this data handling is simplified for function implementations over other provider concepts, such as resource implementations.

Available Parameter Types

Function definitions support the following parameter types:

Primitive: Parameter that accepts a single value, such as a boolean, number, or string.
Collection: Parameter that accepts multiple values of a single element type, such as a list, map, or set.
Object: Parameter that accepts a structure of explicit attribute names.
Dynamic: Parameter that accepts any value type.

Primitive Parameter Types

Parameter types that accepts a single data value, such as a boolean, number, or string.

Parameter Type	Use Case
Bool	Boolean true or false
Float32	32-bit floating point number
Float64	64-bit floating point number
Int32	32-bit integer number
Int64	64-bit integer number
Number	Arbitrary precision (generally over 64-bit, up to 512-bit) number
String	Collection of UTF-8 encoded characters

Collection Parameter Types

Parameter types that accepts multiple values of a single element type, such as a list, map, or set.

Parameter Type	Use Case
List	Ordered collection of single element type
Map	Mapping of arbitrary string keys to values of single element type
Set	Unordered, unique collection of single element type

Object Parameter Type

Parameter type that accepts a structure of explicit attribute names.

Parameter Type	Use Case
Object	Single structure mapping explicit attribute names

Dynamic Parameter Type

Note

Dynamic value handling is an advanced use case. Prefer static parameter types when possible unless absolutely necessary for your use case.

Parameter that accepts any value type, determined by Terraform at runtime.

Parameter Type	Use Case
Dynamic	Accept any value type of data, determined at runtime.

Parameter Naming

All parameter types have a Name field that is required.

Missing Parameter Names

Attempting to use unnamed parameters will generate runtime errors of the following form:

│ Error: Failed to load plugin schemas
│
│ Error while loading schemas for plugin components: Failed to obtain provider schema: Could not load the schema for provider registry.terraform.io/cloud_provider/cloud_resource: failed to
│ retrieve schema from provider "registry.terraform.io/cloud_provider/cloud_resource": Invalid Function Definition: When validating the function definition, an implementation issue was
│ found. This is always an issue with the provider and should be reported to the provider developers.
│
│ Function "example_function" - Parameter at position 0 does not have a name.

Parameter Errors

Parameter names are used in runtime errors to highlight which parameter is causing the issue. For example, using a value that is incompatible with the parameter type will generate an error message such as the following:

│ Error: Invalid function argument
│
│   on resource.tf line 10, in resource "example_resource" "example":
│   10:   configurable_attribute = provider::example::example_function("string")
│     ├────────────────
│     │ while calling provider::example::example_function(bool_param)
│
│ Invalid value for "bool_param" parameter: a bool is required.

Parameter Validation

Validation handling for provider-defined function parameters can be enabled by using custom types.

Implement the function.ValidateableParameter interface on the custom value type to define and enable validation handling for a provider-defined function parameter, which will automatically raise an error when a value is determined to be invalid.

// Implementation of the function.ValidateableParameter interface
func (v CustomStringValue) ValidateParameter(ctx context.Context, req function.ValidateParameterRequest, resp *function.ValidateParameterResponse) {
    if v.IsNull() || v.IsUnknown() {
        return
    }

    _, err := time.Parse(time.RFC3339, v.ValueString())

    if err != nil {
        resp.Error = function.NewArgumentFuncError(
            req.Position,
            "Invalid RFC 3339 String Value: "+
                "An unexpected error occurred while converting a string value that was expected to be RFC 3339 format. "+
                "The RFC 3339 string format is YYYY-MM-DDTHH:MM:SSZ, such as 2006-01-02T15:04:05Z or 2006-01-02T15:04:05+07:00.\n\n"+
                fmt.Sprintf("Position: %d", req.Position)+"\n"+
                "Given Value: "+v.ValueString()+"\n"+
                "Error: "+err.Error(),
        )
    }
}

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