String Type

String types store a collection of UTF-8 encoded bytes.

By default, strings from schema (configuration, plan, and state) data are represented in the framework by types.StringType and its associated value storage type of types.String. These types fully support Terraform's type system concepts that cannot be represented in Go built-in types, such as *string. Framework types can be extended by provider code or shared libraries to provide specific use case functionality.

Schema Definitions

Use one of the following attribute types to directly add a string value to a schema or nested attribute type:

Schema Type	Attribute Type
Data Source	`schema.StringAttribute`
Provider	`schema.StringAttribute`
Resource	`schema.StringAttribute`
Ephemeral Resource	`schema.StringAttribute`

If the string value should be the element type of a collection attribute type, set the ElemType field to types.StringType or the appropriate custom type.

If the string value should be a value type of an object attribute type, set the AttrTypes map value to types.StringType or the appropriate custom type.

Accessing Values

Tip

Review the attribute documentation to understand how schema-based data gets mapped into accessible values, such as a types.String in this case.

Note

The (types.String).String() method is reserved for debugging purposes and returns "<null>" if the value is null and "<unknown>" if the value is unknown. Use (types.String).ValueString() or (types.String).ValueStringPointer() for accessing a known string value.

Access types.String information via the following methods:

(types.String).IsNull() bool: Returns true if the string is null.
(types.String).IsUnknown() bool: Returns true if the string is unknown.
(types.String).ValueString() string: Returns the known string, or an empty string if null or unknown.
(types.String).ValueStringPointer() *string: Returns a string pointer to a known value, nil if null, or a pointer to an empty string if unknown.

In this example, a string value is checked for being null or unknown value first, before accessing its known value:

// Example data model definition
// type ExampleModel struct {
//   ExampleAttribute types.String `tfsdk:"example_attribute"`
// }
//
// This would be filled in, such as calling: req.Plan.Get(ctx, &data)
var data ExampleModel

// optional logic for handling null value
if data.ExampleAttribute.IsNull() {
    // ...
}

// optional logic for handling unknown value
if data.ExampleAttribute.IsUnknown() {
    // ...
}

// myString now contains a Go string with the known value
myString := data.ExampleAttribute.ValueString()

Setting Values

Call one of the following to create a types.String value:

types.StringNull(): A null string value.
types.StringUnknown(): An unknown string value.
types.StringValue(string): A known value.
types.StringPointerValue(*string): A known value.

In this example, a known string value is created:

types.StringValue("example value")

Otherwise, for certain framework functionality that does not require types implementations directly, such as:

A Go built-in string, *string (only with typed nil, (*string)(nil)), or type alias of string such as type MyStringType string can be used instead.

In this example, a string is directly used to set a string attribute value:

diags := resp.State.SetAttribute(ctx, path.Root("example_attribute"), "example value")

In this example, a types.List of types.String is created from a []string:

listValue, diags := types.ListValueFrom(ctx, types.StringType, []string{"value one", "value two"})

Extending

The framework supports extending its base type implementations with custom types. These can adjust expected provider code usage depending on their implementation.

Common Use Case Types

HashiCorp provides additional Go modules which contain custom string type implementations covering common use cases with validation and semantic equality logic:

terraform-plugin-framework-jsontypes: JSON encoded strings, such as exact byte strings and normalized strings
terraform-plugin-framework-nettypes: Networking strings, such as IPv4 addresses, IPv6 addresses, and CIDRs
terraform-plugin-framework-timetypes: Timestamp strings, such as RFC3339