Validation
The framework can return diagnostics feedback for values in provider, resource, and data source configurations. This allows you to write validations that give users feedback about required syntax, types, and acceptable values.
Note: When implementing validation logic, configuration values may be unknown based on the source of the value. Implementations must account for this case, typically by returning early without returning new diagnostics.
Default Terraform CLI Validation
The Terraform configuration language is declarative and an implementation of HashiCorp Configuration Language (HCL). The Terraform CLI is responsible for reading and parsing configurations for validity, based on Terraform's concepts such as resource
blocks and associated syntax. The Terraform CLI automatically handles basic validation of value type and behavior information based on the provider, resource, or data source schema. For example, the Terraform CLI returns an error when a string value is given where a list value is expected and also when a required attribute is missing from a configuration.
Terraform CLI syntax and basic schema checks occur during the terraform apply
, terraform destroy
, terraform plan
, and terraform validate
commands. Any additional validation you define with the framework occurs directly after these checks are complete.
Attribute Validation
You can introduce validation on attributes using the generic framework-defined types such as types.String
. To do this, supply the tfsdk.Attribute
type Validators
field with a list of validations, and the framework will return diagnostics from all validators. For example:
All validators in the slice will always be run, regardless of whether previous validators returned an error or not.
Common Use Case Attribute Validators
You can implement attribute validators from the terraform-plugin-framework-validators Go module, which contains validation handling for many common use cases such as string contents and integer ranges.
Creating Attribute Validators
If there is not an attribute validator in terraform-plugin-framework-validators
that meets a specific use case, a provider-defined attribute validator can be created.
To create an attribute validator, you must implement the tfsdk.AttributeValidator
interface. For example:
Optionally and depending on the complexity, it may be desirable to also create a helper function to instantiate the validator. For example:
Path Based Attribute Validators
Attribute validators that need to accept paths to reference other attribute data should instead prefer path expressions. This allows consumers to use either absolute paths starting at the root of a schema, or relative paths based on the current attribute path where the validator is called.
Path expressions may represent one or more actual paths in the data. To find those paths, the process is called path matching. Depending on the actual data, a path match may return a parent path for null or unknown values, since any underlying paths of those null or unknown values would also represent the same value. This framework behavior is used to prevent false positives of returning no paths for null or unknown values.
The general structure for working with path expressions in an attribute validator is:
- Merge the given path expression(s) with the current attribute path expression, such as calling the
tfsdk.ValidateAttributeRequest
typeAttributePathExpression
fieldMergeExpressions()
method. - Loop through each merged path expression to get the matching paths within the data, such as calling the
tfsdk.ValidateAttributeRequest
typeConfig
fieldPathMatches()
method. - Loop through each matched path to get the generic
attr.Value
value, such as calling thetfsdk.ValidateAttributeRequest
typeConfig
fieldGetAttribute()
method. - Perform null and unknown value checks on the
attr.Value
, such as theIsNull()
method andIsUnknown()
method. - If the
attr.Value
is not null and not unknown, then usetfsdk.ValueAs()
using the expected value implementation as the target.
The following example shows a generic path based attribute validator that returns an error if types.Int64
values at the given path expressions are less than the current attribute types.Int64
value.
Type Validation
You may want to create a custom type to simplify schemas if your provider contains common attribute values with consistent validation rules. When you implement validation on a type, you do not need to declare the same validation on the attribute, but you can supply additional validations in that manner. For example:
Defining Type Validation
To support validation within a type, you must implement the xattr.TypeWithValidate
interface. For example:
Schema Validation
Provider, resource, and data source schemas also support validation across all attributes. This is helpful when checking values in multiple attributes, such as ensuring the values are compatible with each other.
Creating Provider Schema Validation
The framework performs provider validation in addition to attribute and type validation. You can implement either or both of the following interfaces.
The provider.ProviderWithConfigValidators
interface follows a similar pattern to attribute validation and allows for a more declarative approach. This lets you write consistent validators across multiple providers. You must implement the provider.ConfigValidator
interface for each validator. For example:
The provider.ProviderWithValidateConfig
interface is more imperative in design and is useful for validating unique functionality that typically applies to a single provider. For example:
Creating Resource Schema Validation
The framework performs resource schema validation in addition to any attribute and type validation. You can implement either or both of the following interfaces.
The resource.ResourceWithConfigValidators
interface follows a similar pattern to attribute validation and allows for a more declarative approach. This lets you create consistent validators across multiple resources. You must implement the resource.ConfigValidator
interface for each validator. For example:
The resource.ResourceWithValidateConfig
interface is more imperative in design and is useful for validating unique functionality that typically applies to a single resource. For example:
Creating Data Source Schema Validation
The framework performs data source schema validation in addition to any attribute and type validation. You can implement either or both of the following interfaces.
The datasource.DataSourceWithConfigValidators
interface follows a similar pattern to attribute validation and allows for a more declarative approach. This lets you write consistent validators across multiple data sources. You must implement the datasource.ConfigValidator
interface for each validator. For example:
The datasource.DataSourceWithValidateConfig
interface is more imperative in design and is useful for validating unique functionality that typically applies to a single data source. For example: