Documentation
¶
Overview ¶
Package stringvalidator provides validators for types.String attributes and function parameters.
There are also HashiCorp-supported custom string types available for specific use cases, including but not limited to:
Index ¶
- func All(validators ...validator.String) validator.String
- func AlsoRequires(expressions ...path.Expression) validator.String
- func Any(validators ...validator.String) validator.String
- func AnyWithAllWarnings(validators ...validator.String) validator.String
- func AtLeastOneOf(expressions ...path.Expression) validator.String
- func ConflictsWith(expressions ...path.Expression) validator.String
- func ExactlyOneOf(expressions ...path.Expression) validator.String
- func LengthAtLeast(minLength int) lengthAtLeastValidator
- func LengthAtMost(maxLength int) lengthAtMostValidator
- func LengthBetween(minLength, maxLength int) lengthBetweenValidator
- func NoneOf(values ...string) noneOfValidator
- func NoneOfCaseInsensitive(values ...string) noneOfCaseInsensitiveValidator
- func OneOf(values ...string) oneOfValidator
- func OneOfCaseInsensitive(values ...string) oneOfCaseInsensitiveValidator
- func RegexMatches(regexp *regexp.Regexp, message string) regexMatchesValidator
- func UTF8LengthAtLeast(minLength int) utf8LengthAtLeastValidator
- func UTF8LengthAtMost(maxLength int) utf8LengthAtMostValidator
- func UTF8LengthBetween(minLength int, maxLength int) utf8LengthBetweenValidator
Examples ¶
- All
- AlsoRequires
- Any
- AnyWithAllWarnings
- AtLeastOneOf
- ConflictsWith
- ExactlyOneOf
- LengthAtLeast
- LengthAtLeast (Function)
- LengthAtMost
- LengthAtMost (Function)
- LengthBetween
- LengthBetween (Function)
- NoneOf
- NoneOf (Function)
- OneOf
- OneOf (Function)
- RegexMatches
- RegexMatches (Function)
- UTF8LengthAtLeast
- UTF8LengthAtLeast (Function)
- UTF8LengthAtMost
- UTF8LengthAtMost (Function)
- UTF8LengthBetween
- UTF8LengthBetween (Function)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func All ¶ added in v0.7.0
All returns a validator which ensures that any configured attribute value attribute value validates against all the given validators.
Use of All is only necessary when used in conjunction with Any or AnyWithAllWarnings as the Validators field automatically applies a logical AND.
Example ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/datasource/schema" "github.com/hashicorp/terraform-plugin-framework/schema/validator" ) func main() { // Used within a Schema method of a DataSource, Provider, or Resource _ = schema.Schema{ Attributes: map[string]schema.Attribute{ "example_attr": schema.StringAttribute{ Required: true, Validators: []validator.String{ // Validate this String value must either be: // - "one" // - Length at least 4 characters, but not "three" stringvalidator.Any( stringvalidator.OneOf("one"), stringvalidator.All( stringvalidator.LengthAtLeast(4), stringvalidator.NoneOf("three"), ), ), }, }, }, } }
Output:
func AlsoRequires ¶ added in v0.7.0
func AlsoRequires(expressions ...path.Expression) validator.String
AlsoRequires checks that a set of path.Expression has a non-null value, if the current attribute or block also has a non-null value.
This implements the validation logic declaratively within the schema. Refer to [datasourcevalidator.RequiredTogether], [providervalidator.RequiredTogether], or [resourcevalidator.RequiredTogether] for declaring this type of validation outside the schema definition.
Relative path.Expression will be resolved using the attribute or block being validated.
Example ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/datasource/schema" "github.com/hashicorp/terraform-plugin-framework/path" "github.com/hashicorp/terraform-plugin-framework/schema/validator" ) func main() { // Used within a Schema method of a DataSource, Provider, or Resource _ = schema.Schema{ Attributes: map[string]schema.Attribute{ "example_attr": schema.StringAttribute{ Optional: true, Validators: []validator.String{ // Validate this attribute must be configured with other_attr. stringvalidator.AlsoRequires(path.Expressions{ path.MatchRoot("other_attr"), }...), }, }, "other_attr": schema.StringAttribute{ Optional: true, }, }, } }
Output:
func Any ¶ added in v0.7.0
Any returns a validator which ensures that any configured attribute value passes at least one of the given validators.
To prevent practitioner confusion should non-passing validators have conflicting logic, only warnings from the passing validator are returned. Use AnyWithAllWarnings() to return warnings from non-passing validators as well.
Example ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/datasource/schema" "github.com/hashicorp/terraform-plugin-framework/schema/validator" ) func main() { // Used within a Schema method of a DataSource, Provider, or Resource _ = schema.Schema{ Attributes: map[string]schema.Attribute{ "example_attr": schema.StringAttribute{ Required: true, Validators: []validator.String{ // Validate this String value must either be: // - "one" // - Length at least 4 characters stringvalidator.Any( stringvalidator.OneOf("one"), stringvalidator.LengthAtLeast(4), ), }, }, }, } }
Output:
func AnyWithAllWarnings ¶ added in v0.7.0
AnyWithAllWarnings returns a validator which ensures that any configured attribute value passes at least one of the given validators. This validator returns all warnings, including failed validators.
Use Any() to return warnings only from the passing validator.
Example ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/datasource/schema" "github.com/hashicorp/terraform-plugin-framework/schema/validator" ) func main() { // Used within a Schema method of a DataSource, Provider, or Resource _ = schema.Schema{ Attributes: map[string]schema.Attribute{ "example_attr": schema.StringAttribute{ Required: true, Validators: []validator.String{ // Validate this String value must either be: // - "one" // - Length at least 4 characters stringvalidator.AnyWithAllWarnings( stringvalidator.OneOf("one"), stringvalidator.LengthAtLeast(4), ), }, }, }, } }
Output:
func AtLeastOneOf ¶ added in v0.7.0
func AtLeastOneOf(expressions ...path.Expression) validator.String
AtLeastOneOf checks that of a set of path.Expression, including the attribute this validator is applied to, at least one has a non-null value.
This implements the validation logic declaratively within the tfsdk.Schema. Refer to [datasourcevalidator.AtLeastOneOf], [providervalidator.AtLeastOneOf], or [resourcevalidator.AtLeastOneOf] for declaring this type of validation outside the schema definition.
Any relative path.Expression will be resolved using the attribute being validated.
Example ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/datasource/schema" "github.com/hashicorp/terraform-plugin-framework/path" "github.com/hashicorp/terraform-plugin-framework/schema/validator" ) func main() { // Used within a Schema method of a DataSource, Provider, or Resource _ = schema.Schema{ Attributes: map[string]schema.Attribute{ "example_attr": schema.StringAttribute{ Optional: true, Validators: []validator.String{ // Validate at least this attribute or other_attr should be configured. stringvalidator.AtLeastOneOf(path.Expressions{ path.MatchRoot("other_attr"), }...), }, }, "other_attr": schema.StringAttribute{ Optional: true, }, }, } }
Output:
func ConflictsWith ¶ added in v0.7.0
func ConflictsWith(expressions ...path.Expression) validator.String
ConflictsWith checks that a set of path.Expression, including the attribute the validator is applied to, do not have a value simultaneously.
This implements the validation logic declaratively within the schema. Refer to [datasourcevalidator.Conflicting], [providervalidator.Conflicting], or [resourcevalidator.Conflicting] for declaring this type of validation outside the schema definition.
Relative path.Expression will be resolved using the attribute being validated.
Example ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/datasource/schema" "github.com/hashicorp/terraform-plugin-framework/path" "github.com/hashicorp/terraform-plugin-framework/schema/validator" ) func main() { // Used within a Schema method of a DataSource, Provider, or Resource _ = schema.Schema{ Attributes: map[string]schema.Attribute{ "example_attr": schema.StringAttribute{ Optional: true, Validators: []validator.String{ // Validate this attribute must not be configured with other_attr. stringvalidator.ConflictsWith(path.Expressions{ path.MatchRoot("other_attr"), }...), }, }, "other_attr": schema.StringAttribute{ Optional: true, }, }, } }
Output:
func ExactlyOneOf ¶ added in v0.7.0
func ExactlyOneOf(expressions ...path.Expression) validator.String
ExactlyOneOf checks that of a set of path.Expression, including the attribute the validator is applied to, one and only one attribute has a value. It will also cause a validation error if none are specified.
This implements the validation logic declaratively within the schema. Refer to [datasourcevalidator.ExactlyOneOf], [providervalidator.ExactlyOneOf], or [resourcevalidator.ExactlyOneOf] for declaring this type of validation outside the schema definition.
Relative path.Expression will be resolved using the attribute being validated.
Example ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/datasource/schema" "github.com/hashicorp/terraform-plugin-framework/path" "github.com/hashicorp/terraform-plugin-framework/schema/validator" ) func main() { // Used within a Schema method of a DataSource, Provider, or Resource _ = schema.Schema{ Attributes: map[string]schema.Attribute{ "example_attr": schema.StringAttribute{ Optional: true, Validators: []validator.String{ // Validate only this attribute or other_attr is configured. stringvalidator.ExactlyOneOf(path.Expressions{ path.MatchRoot("other_attr"), }...), }, }, "other_attr": schema.StringAttribute{ Optional: true, }, }, } }
Output:
func LengthAtLeast ¶
func LengthAtLeast(minLength int) lengthAtLeastValidator
LengthAtLeast returns an validator which ensures that any configured attribute or function parameter value is of single-byte character length greater than or equal to the given minimum. Null (unconfigured) and unknown (known after apply) values are skipped.
minLength cannot be less than zero. Invalid input for minLength will result in an implementation error message during validation.
Use UTF8LengthAtLeast for checking multiple-byte characters.
Example ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/datasource/schema" "github.com/hashicorp/terraform-plugin-framework/schema/validator" ) func main() { // Used within a Schema method of a DataSource, Provider, or Resource _ = schema.Schema{ Attributes: map[string]schema.Attribute{ "example_attr": schema.StringAttribute{ Required: true, Validators: []validator.String{ // Validate string value length must be at least 3 characters. stringvalidator.LengthAtLeast(3), }, }, }, } }
Output:
Example (Function) ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/function" ) func main() { _ = function.Definition{ Parameters: []function.Parameter{ function.StringParameter{ Name: "example_param", Validators: []function.StringParameterValidator{ // Validate string value length must be at least 3 characters. stringvalidator.LengthAtLeast(3), }, }, }, } }
Output:
func LengthAtMost ¶
func LengthAtMost(maxLength int) lengthAtMostValidator
LengthAtMost returns an validator which ensures that any configured attribute or function parameter value is of single-byte character length less than or equal to the given maximum. Null (unconfigured) and unknown (known after apply) values are skipped.
maxLength cannot be less than zero. Invalid input for maxLength will result in an implementation error message during validation.
Use UTF8LengthAtMost for checking multiple-byte characters.
Example ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/datasource/schema" "github.com/hashicorp/terraform-plugin-framework/schema/validator" ) func main() { // Used within a Schema method of a DataSource, Provider, or Resource _ = schema.Schema{ Attributes: map[string]schema.Attribute{ "example_attr": schema.StringAttribute{ Required: true, Validators: []validator.String{ // Validate string value length must be at most 256 characters. stringvalidator.LengthAtMost(256), }, }, }, } }
Output:
Example (Function) ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/function" ) func main() { _ = function.Definition{ Parameters: []function.Parameter{ function.StringParameter{ Name: "example_param", Validators: []function.StringParameterValidator{ // Validate string value length must be at most 256 characters. stringvalidator.LengthAtMost(256), }, }, }, } }
Output:
func LengthBetween ¶
func LengthBetween(minLength, maxLength int) lengthBetweenValidator
LengthBetween returns a validator which ensures that any configured attribute or function parameter value is of single-byte character length greater than or equal to the given minimum and less than or equal to the given maximum. Null (unconfigured) and unknown (known after apply) values are skipped.
minLength cannot be less than zero or greater than maxLength. Invalid combinations of minLength and maxLength will result in an implementation error message during validation.
Use UTF8LengthBetween for checking multiple-byte characters.
Example ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/datasource/schema" "github.com/hashicorp/terraform-plugin-framework/schema/validator" ) func main() { // Used within a Schema method of a DataSource, Provider, or Resource _ = schema.Schema{ Attributes: map[string]schema.Attribute{ "example_attr": schema.StringAttribute{ Required: true, Validators: []validator.String{ // Validate string value length must be at least 3 and at most 256 characters. stringvalidator.LengthBetween(3, 256), }, }, }, } }
Output:
Example (Function) ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/function" ) func main() { _ = function.Definition{ Parameters: []function.Parameter{ function.StringParameter{ Name: "example_param", Validators: []function.StringParameterValidator{ // Validate string value length must be at least 3 and at most 256 characters. stringvalidator.LengthBetween(3, 256), }, }, }, } }
Output:
func NoneOf ¶ added in v0.3.0
func NoneOf(values ...string) noneOfValidator
NoneOf checks that the String held in the attribute or function parameter is none of the given `values`.
Example ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/datasource/schema" "github.com/hashicorp/terraform-plugin-framework/schema/validator" ) func main() { // Used within a Schema method of a DataSource, Provider, or Resource _ = schema.Schema{ Attributes: map[string]schema.Attribute{ "example_attr": schema.StringAttribute{ Required: true, Validators: []validator.String{ // Validate string value must not be "one", "two", or "three" stringvalidator.NoneOf([]string{"one", "two", "three"}...), }, }, }, } }
Output:
Example (Function) ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/function" ) func main() { _ = function.Definition{ Parameters: []function.Parameter{ function.StringParameter{ Name: "example_param", Validators: []function.StringParameterValidator{ // Validate string value must not be "one", "two", or "three" stringvalidator.NoneOf([]string{"one", "two", "three"}...), }, }, }, } }
Output:
func NoneOfCaseInsensitive ¶ added in v0.3.0
func NoneOfCaseInsensitive(values ...string) noneOfCaseInsensitiveValidator
NoneOfCaseInsensitive checks that the String held in the attribute or function parameter is none of the given `values`.
func OneOf ¶ added in v0.3.0
func OneOf(values ...string) oneOfValidator
OneOf checks that the String held in the attribute or function parameter is one of the given `values`.
Example ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/datasource/schema" "github.com/hashicorp/terraform-plugin-framework/schema/validator" ) func main() { // Used within a Schema method of a DataSource, Provider, or Resource _ = schema.Schema{ Attributes: map[string]schema.Attribute{ "example_attr": schema.StringAttribute{ Required: true, Validators: []validator.String{ // Validate string value must be "one", "two", or "three" stringvalidator.OneOf([]string{"one", "two", "three"}...), }, }, }, } }
Output:
Example (Function) ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/function" ) func main() { _ = function.Definition{ Parameters: []function.Parameter{ function.StringParameter{ Name: "example_param", Validators: []function.StringParameterValidator{ // Validate string value must be "one", "two", or "three" stringvalidator.OneOf([]string{"one", "two", "three"}...), }, }, }, } }
Output:
func OneOfCaseInsensitive ¶ added in v0.3.0
func OneOfCaseInsensitive(values ...string) oneOfCaseInsensitiveValidator
OneOfCaseInsensitive checks that the String held in the attribute or function parameter is one of the given `values`.
func RegexMatches ¶
RegexMatches returns an AttributeValidator which ensures that any configured attribute or function parameter value:
- Is a string.
- Matches the given regular expression https://github.com/google/re2/wiki/Syntax.
Null (unconfigured) and unknown (known after apply) values are skipped. Optionally an error message can be provided to return something friendlier than "value must match regular expression 'regexp'".
Example ¶
package main import ( "regexp" "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/datasource/schema" "github.com/hashicorp/terraform-plugin-framework/schema/validator" ) func main() { // Used within a Schema method of a DataSource, Provider, or Resource _ = schema.Schema{ Attributes: map[string]schema.Attribute{ "example_attr": schema.StringAttribute{ Required: true, Validators: []validator.String{ // Validate string value satisfies the regular expression for alphanumeric characters stringvalidator.RegexMatches( regexp.MustCompile(`^[a-zA-Z0-9]*$`), "must only contain only alphanumeric characters", ), }, }, }, } }
Output:
Example (Function) ¶
package main import ( "regexp" "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/function" ) func main() { _ = function.Definition{ Parameters: []function.Parameter{ function.StringParameter{ Name: "example_param", Validators: []function.StringParameterValidator{ // Validate string value satisfies the regular expression for alphanumeric characters stringvalidator.RegexMatches( regexp.MustCompile(`^[a-zA-Z0-9]*$`), "must only contain only alphanumeric characters", ), }, }, }, } }
Output:
func UTF8LengthAtLeast ¶ added in v0.9.0
func UTF8LengthAtLeast(minLength int) utf8LengthAtLeastValidator
UTF8LengthAtLeast returns an validator which ensures that any configured attribute or function parameter value is of UTF-8 character count greater than or equal to the given minimum. Null (unconfigured) and unknown (known after apply) values are skipped.
minLength cannot be less than zero. Invalid input for minLength will result in an implementation error message during validation.
Use LengthAtLeast for checking single-byte character counts.
Example ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/datasource/schema" "github.com/hashicorp/terraform-plugin-framework/schema/validator" ) func main() { // Used within a Schema method of a DataSource, Provider, or Resource _ = schema.Schema{ Attributes: map[string]schema.Attribute{ "example_attr": schema.StringAttribute{ Required: true, Validators: []validator.String{ // Validate UTF-8 character count must be at least 3 characters. stringvalidator.UTF8LengthAtLeast(3), }, }, }, } }
Output:
Example (Function) ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/function" ) func main() { _ = function.Definition{ Parameters: []function.Parameter{ function.StringParameter{ Name: "example_param", Validators: []function.StringParameterValidator{ // Validate UTF-8 character count must be at least 3 characters. stringvalidator.UTF8LengthAtLeast(3), }, }, }, } }
Output:
func UTF8LengthAtMost ¶ added in v0.9.0
func UTF8LengthAtMost(maxLength int) utf8LengthAtMostValidator
UTF8LengthAtMost returns an validator which ensures that any configured attribute or function parameter value is of UTF-8 character count less than or equal to the given maximum. Null (unconfigured) and unknown (known after apply) values are skipped.
maxLength cannot be less than zero. Invalid input for maxLength will result in an implementation error message during validation.
Use LengthAtMost for checking single-byte character counts.
Example ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/datasource/schema" "github.com/hashicorp/terraform-plugin-framework/schema/validator" ) func main() { // Used within a Schema method of a DataSource, Provider, or Resource _ = schema.Schema{ Attributes: map[string]schema.Attribute{ "example_attr": schema.StringAttribute{ Required: true, Validators: []validator.String{ // Validate UTF-8 character count must be at most 255 characters. stringvalidator.UTF8LengthAtMost(255), }, }, }, } }
Output:
Example (Function) ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/function" ) func main() { _ = function.Definition{ Parameters: []function.Parameter{ function.StringParameter{ Name: "example_param", Validators: []function.StringParameterValidator{ // Validate UTF-8 character count must be at most 255 characters. stringvalidator.UTF8LengthAtMost(255), }, }, }, } }
Output:
func UTF8LengthBetween ¶ added in v0.9.0
UTF8LengthBetween returns an validator which ensures that any configured attribute or function parameter value is of UTF-8 character count greater than or equal to the given minimum and less than or equal to the given maximum. Null (unconfigured) and unknown (known after apply) values are skipped.
minLength and maxLength cannot be less than zero and maxLength must be greater than or equal to minLength. Invalid combinations of minLength and maxLength will result in an implementation error message during validation.
Use LengthBetween for checking single-byte character counts.
Example ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/datasource/schema" "github.com/hashicorp/terraform-plugin-framework/schema/validator" ) func main() { // Used within a Schema method of a DataSource, Provider, or Resource _ = schema.Schema{ Attributes: map[string]schema.Attribute{ "example_attr": schema.StringAttribute{ Required: true, Validators: []validator.String{ // Validate UTF-8 character count must be at least 3 characters // and at most 255 characters. stringvalidator.UTF8LengthBetween(3, 255), }, }, }, } }
Output:
Example (Function) ¶
package main import ( "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/function" ) func main() { _ = function.Definition{ Parameters: []function.Parameter{ function.StringParameter{ Name: "example_param", Validators: []function.StringParameterValidator{ // Validate UTF-8 character count must be at least 3 characters // and at most 255 characters. stringvalidator.UTF8LengthBetween(3, 255), }, }, }, } }
Output:
Types ¶
This section is empty.
Source Files
¶
- all.go
- also_requires.go
- any.go
- any_with_all_warnings.go
- at_least_one_of.go
- conflicts_with.go
- doc.go
- exactly_one_of.go
- length_at_least.go
- length_at_most.go
- length_between.go
- none_of.go
- none_of_case_insensitive.go
- one_of.go
- one_of_case_insensitive.go
- regex_matches.go
- utf8_length_at_least.go
- utf8_length_at_most.go
- utf8_length_between.go