From 8f824839164b3385a8762790bc5ea907f890ed07 Mon Sep 17 00:00:00 2001 From: Brian Flad Date: Wed, 14 Jun 2023 10:57:58 -0400 Subject: [PATCH] docs: Additional type-based semantic equality information (#769) Per out-of-band feedback: - Add mentions of custom types into SDK migration documentation for attribute fields - Add mention in custom type semantic equality section about framework automatic collection/object behaviors with element/underlying attribute types. --- .../docs/plugin/framework/handling-data/custom-types.mdx | 2 +- .../framework/migrating/attributes-blocks/fields.mdx | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/website/docs/plugin/framework/handling-data/custom-types.mdx b/website/docs/plugin/framework/handling-data/custom-types.mdx index 24cf7a895..71887490d 100644 --- a/website/docs/plugin/framework/handling-data/custom-types.mdx +++ b/website/docs/plugin/framework/handling-data/custom-types.mdx @@ -245,7 +245,7 @@ This value type functionality is checked in the following scenarios: - When refreshing a resource, the response new state value from the `Read` method logic is compared to the request prior state value. - When creating or updating a resource, the response new state value from the `Create` or `Update` method logic is compared to the request plan value. -The framework will only call semantic equality logic if both the prior and new values are known. Null or unknown values are unnecessary to check. +The framework will only call semantic equality logic if both the prior and new values are known. Null or unknown values are unnecessary to check. When working with collection types, the framework automatically calls semantic equality logic of element types. When working with object types, the framework automatically calls semantic equality of underlying attribute types. Implement the associated `github.com/hashicorp/terraform-plugin-framework/types/basetypes` package `*ValuableWithSemanticEquals` interface on the value type to define and enable this behavior. diff --git a/website/docs/plugin/framework/migrating/attributes-blocks/fields.mdx b/website/docs/plugin/framework/migrating/attributes-blocks/fields.mdx index 94fdaab26..22807d1f0 100644 --- a/website/docs/plugin/framework/migrating/attributes-blocks/fields.mdx +++ b/website/docs/plugin/framework/migrating/attributes-blocks/fields.mdx @@ -19,8 +19,8 @@ The following table describes the mapping between [SDK Schema Fields](https://pk | Optional | `Optional` field on attribute | | Computed | `Computed` field on attribute | | ForceNew | [RequiresReplace](/terraform/plugin/framework/migrating/attributes-blocks/force-new) on `PlanModifiers` field on attribute or implementation of [ResourceWithModifyPlan](/terraform/plugin/framework/migrating/resources/plan-modification#framework) interface | -| DiffSuppressFunc | [PlanModifiers](/terraform/plugin/framework/migrating/resources/plan-modification#framework) field on attribute or implementation of [ResourceWithModifyPlan](/terraform/plugin/framework/migrating/resources/plan-modification#framework) interface | -| DiffSuppressOnRefresh | [Read](/terraform/plugin/framework/migrating/resources/crud) method on resource | +| DiffSuppressFunc | [Custom Types](/terraform/plugin/framework/handling-data/custom-types), [PlanModifiers](/terraform/plugin/framework/migrating/resources/plan-modification#framework) field on attribute, or implementation of [ResourceWithModifyPlan](/terraform/plugin/framework/migrating/resources/plan-modification#framework) interface | +| DiffSuppressOnRefresh | [Custom Types](/terraform/plugin/framework/handling-data/custom-types) semantic equality logic or manual logic in [Read](/terraform/plugin/framework/migrating/resources/crud) method on resource | | Default | `Default` field on attribute using one of the predefined [Defaults](/terraform/plugin/framework/resources/default#common-use-case-attribute-defaults) or implementing one of the [`schema` package](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/resource/schema/defaults) interfaces | | DefaultFunc | `Default` field on attribute using one of the predefined [Defaults](/terraform/plugin/framework/resources/default#common-use-case-attribute-defaults) or implementing one of the [`schema` package](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/resource/schema/defaults) interfaces | | Description | `Description` field on attribute | @@ -36,8 +36,8 @@ The following table describes the mapping between [SDK Schema Fields](https://pk | AtLeastOneOf | [Predefined Validators](/terraform/plugin/framework/migrating/attributes-blocks/validators-predefined) | | RequiredWith | [Predefined Validators](/terraform/plugin/framework/migrating/attributes-blocks/validators-predefined) | | Deprecated | `DeprecationMessage` field on attribute | -| ValidateFunc | [Predefined Validators](/terraform/plugin/framework/migrating/attributes-blocks/validators-predefined) and [Custom Validators](/terraform/plugin/framework/migrating/attributes-blocks/validators-custom) | -| ValidateDiagFunc | [Predefined Validators](/terraform/plugin/framework/migrating/attributes-blocks/validators-predefined) and [Custom Validators](/terraform/plugin/framework/migrating/attributes-blocks/validators-custom) | +| ValidateFunc | [Predefined Validators](/terraform/plugin/framework/migrating/attributes-blocks/validators-predefined), [Custom Validators](/terraform/plugin/framework/migrating/attributes-blocks/validators-custom), or [Custom Types](/terraform/plugin/framework/handling-data/custom-types) validation logic | +| ValidateDiagFunc | [Predefined Validators](/terraform/plugin/framework/migrating/attributes-blocks/validators-predefined), [Custom Validators](/terraform/plugin/framework/migrating/attributes-blocks/validators-custom), or [Custom Types](/terraform/plugin/framework/handling-data/custom-types) validation logic | | Sensitive | `Sensitive` field on attribute |