diff --git a/website/docs/plugin/framework/handling-data/attributes.mdx b/website/docs/plugin/framework/handling-data/attributes.mdx index afdfc3f9..a6b158e5 100644 --- a/website/docs/plugin/framework/handling-data/attributes.mdx +++ b/website/docs/plugin/framework/handling-data/attributes.mdx @@ -577,3 +577,6 @@ You may want to build your own attribute value and type implementations to allow Refer to [Custom Types](/terraform/plugin/framework/handling-data/custom-types) for further details on creating provider-defined types and values. +## Common Custom Types and Values + +A collection of Go modules have been created with attribute value and type implementations for common use cases, such as normalized JSON strings, IPv4/IPv6 addresses, and RFC3339 time strings. Refer to [Common Custom Types](/terraform/plugin/framework/handling-data/custom-types#common-custom-types) for further details. \ No newline at end of file diff --git a/website/docs/plugin/framework/handling-data/custom-types.mdx b/website/docs/plugin/framework/handling-data/custom-types.mdx index c80cf2db..3718ac39 100644 --- a/website/docs/plugin/framework/handling-data/custom-types.mdx +++ b/website/docs/plugin/framework/handling-data/custom-types.mdx @@ -15,10 +15,19 @@ Supported behaviors for custom types include: ## Example Use Cases -- Encoded values, such as JSON or YAML string. -- Networking values, such as an IPv4 address string. -- Time values, such as an RFC3339 string. +- Encoded values, such as an XML or YAML string. - Provider-specific values, such as an AWS ARN or AzureRM location string. +- Networking values, such as a MAC address. +- Time values, such as an ISO 8601 string. + +## Common Custom Types +The following Go modules contain custom type implementations covering common use cases with validation and semantic equality logic (where appropriate). +- [`terraform-plugin-framework-jsontypes`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-jsontypes) + - JSON strings (both normalized and exact matching) +- [`terraform-plugin-framework-nettypes`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-nettypes) + - IPv4/IPv6 addresses and CIDRs +- [`terraform-plugin-framework-timetypes`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-timetypes) + - Timestamps (such as RFC3339) ## Concepts @@ -96,6 +105,8 @@ It is recommended to use Go type embedding of the base type to simplify the impl - `ValueFromTerraform(context.Context, tftypes.Value) (attr.Value, error)` - `ValueType(context.Context) attr.Value` - `String() string` +- `ValueFrom{TYPE}(context.Context, basetypes.{TYPE}Value) (basetypes.{TYPE}Valuable, diag.Diagnostics)` + - This method signature is different for each `*Typable` custom schema type interface listed above, for example `basetypes.StringTypable` is defined as [`ValueFromString`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/types/basetypes#StringTypable) In this example, the `basetypes.StringTypable` interface is implemented to create a custom string type with an associated [value type](#value-type): @@ -196,6 +207,14 @@ It is recommended to use Go type embedding of the base type to simplify the impl - `Equal(attr.Value) bool` - `Type(context.Context) attr.Type` + + +The overridden `Equal(attr.Value) bool` method should not contain [Semantic Equality](#semantic-equality) logic. `Equal` should only check the type of `attr.Value` and the underlying base value. + +An example of this can be found below with the `CustomStringValue` implementation. + + + In this example, the `basetypes.StringValuable` interface is implemented to create a custom string value type with an associated [schema type](#schema-type): ```go