all: Add UseNonNullStateForUnknown plan modifier to assist with child nested attribute use-cases

.changes/1.15.1.md

@@ -1,5 +1,9 @@
 ## 1.15.1 (July 31, 2025)
 
+NOTES:
+
+* This release contains a change in behavior for the `UseStateForUnknown` plan modifier, which will now preserve null values from prior state for unconfigured attributes. This updated version can cause plan inconsistency errors when used on child attributes of a nested attribute that expect `UseStateForUnknown` to keep the child attributes on new nested objects as `<unknown>` (known after apply). See [#1197](https://github.com/hashicorp/terraform-plugin-framework/issues/1197) for more details.
+
 BUG FIXES:
 
 * all: Fixed bug with `UseStateForUnknown` where known null state values were not preserved during update plans. ([#1117](https://github.com/hashicorp/terraform-plugin-framework/issues/1117))

.changes/unreleased/FEATURES-20251121-165955.yaml

@@ -0,0 +1,6 @@
+kind: FEATURES
+body: 'all: Added a new plan modifier for all types, `UseNonNullStateForUnknown` that preserves known, non-null, values for unconfigured attributes.
+    This can be used when it is known that an unconfigured value will remain the same after the attribute is updated to a non-null value.'
+time: 2025-11-21T16:59:55.611735-05:00
+custom:
+    Issue: "1242"

.changes/unreleased/NOTES-20251121-170117.yaml

@@ -0,0 +1,9 @@
+kind: NOTES
+body: 'In `[email protected]`, the `UseStateForUnknown` plan modifier was updated to preserve null values from prior state
+    for unconfigured attributes. This updated version can cause plan inconsistency errors when used on child attributes of a nested attribute
+    that expect `UseStateForUnknown` to keep the child attributes on new nested objects as `<unknown>` (known after apply).
+
+    The new `UseNonNullStateForUnknown` plan modifier can now be used where child attributes are expecting this pre-1.15.1 behavior.'
+time: 2025-11-21T17:01:17.961155-05:00
+custom:
+    Issue: "1197"

CHANGELOG.md

@@ -63,6 +63,10 @@ BUG FIXES:
 
 ## 1.15.1 (July 31, 2025)
 
+NOTES:
+
+* This release contains a change in behavior for the `UseStateForUnknown` plan modifier, which will now preserve null values from prior state for unconfigured attributes. This updated version can cause plan inconsistency errors when used on child attributes of a nested attribute that expect `UseStateForUnknown` to keep the child attributes on new nested objects as `<unknown>` (known after apply). See [#1197](https://github.com/hashicorp/terraform-plugin-framework/issues/1197) for more details.
+
 BUG FIXES:
 
 * all: Fixed bug with `UseStateForUnknown` where known null state values were not preserved during update plans. ([#1117](https://github.com/hashicorp/terraform-plugin-framework/issues/1117))

resource/schema/boolplanmodifier/use_non_null_state_for_unknown.go

@@ -0,0 +1,54 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package boolplanmodifier
+
+import (
+	"context"
+
+	"github.com/hashicorp/terraform-plugin-framework/resource/schema/planmodifier"
+)
+
+// UseNonNullStateForUnknown returns a plan modifier that copies a known, non-null, prior state
+// value into the planned value. Use this when it is known that an unconfigured value will remain the
+// same after the attribute is updated to a non-null value.
+//
+// To prevent Terraform errors, the framework automatically sets unconfigured
+// and Computed attributes to an unknown value "(known after apply)" on update.
+// Using this plan modifier will instead display the non-null prior state value in the
+// plan, unless a prior plan modifier adjusts the value.
+//
+// This plan modifier can be a useful alternative to [UseStateForUnknown] when the attribute is
+// a child of a nested attribute that can be null after the resource is created.
+func UseNonNullStateForUnknown() planmodifier.Bool {
+	return useNonNullStateForUnknown{}
+}
+
+type useNonNullStateForUnknown struct{}
+
+func (m useNonNullStateForUnknown) Description(_ context.Context) string {
+	return "Once set to a non-null value, the value of this attribute in state will not change."
+}
+
+func (m useNonNullStateForUnknown) MarkdownDescription(_ context.Context) string {
+	return "Once set to a non-null value, the value of this attribute in state will not change."
+}
+
+func (m useNonNullStateForUnknown) PlanModifyBool(ctx context.Context, req planmodifier.BoolRequest, resp *planmodifier.BoolResponse) {
+	// Do nothing if the state value is null.
+	if req.StateValue.IsNull() {
+		return
+	}
+
+	// Do nothing if there is a known planned value.
+	if !req.PlanValue.IsUnknown() {
+		return
+	}
+
+	// Do nothing if there is an unknown configuration value, otherwise interpolation gets messed up.
+	if req.ConfigValue.IsUnknown() {
+		return
+	}
+
+	resp.PlanValue = req.StateValue
+}

resource/schema/boolplanmodifier/use_non_null_state_for_unknown_test.go

@@ -0,0 +1,166 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package boolplanmodifier_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/hashicorp/terraform-plugin-framework/resource/schema/boolplanmodifier"
+	"github.com/hashicorp/terraform-plugin-framework/resource/schema/planmodifier"
+	"github.com/hashicorp/terraform-plugin-framework/tfsdk"
+	"github.com/hashicorp/terraform-plugin-framework/types"
+	"github.com/hashicorp/terraform-plugin-go/tftypes"
+)
+
+func TestUseNonNullStateForUnknownModifierPlanModifyBool(t *testing.T) {
+	t.Parallel()
+
+	testCases := map[string]struct {
+		request  planmodifier.BoolRequest
+		expected *planmodifier.BoolResponse
+	}{
+		"null-state": {
+			// when we first create the resource, the state value will be null,
+			// so use the unknown value
+			request: planmodifier.BoolRequest{
+				State: tfsdk.State{
+					Raw: tftypes.NewValue(
+						tftypes.Object{
+							AttributeTypes: map[string]tftypes.Type{
+								"attr": tftypes.Bool,
+							},
+						},
+						nil,
+					),
+				},
+				StateValue:  types.BoolNull(),
+				PlanValue:   types.BoolUnknown(),
+				ConfigValue: types.BoolNull(),
+			},
+			expected: &planmodifier.BoolResponse{
+				PlanValue: types.BoolUnknown(),
+			},
+		},
+		"known-plan": {
+			// this would really only happen if we had a plan
+			// modifier setting the value before this plan modifier
+			// got to it
+			//
+			// but we still want to preserve that value, in this
+			// case
+			request: planmodifier.BoolRequest{
+				State: tfsdk.State{
+					Raw: tftypes.NewValue(
+						tftypes.Object{
+							AttributeTypes: map[string]tftypes.Type{
+								"attr": tftypes.Bool,
+							},
+						},
+						map[string]tftypes.Value{
+							"attr": tftypes.NewValue(tftypes.Bool, false),
+						},
+					),
+				},
+				StateValue:  types.BoolValue(false),
+				PlanValue:   types.BoolValue(true),
+				ConfigValue: types.BoolNull(),
+			},
+			expected: &planmodifier.BoolResponse{
+				PlanValue: types.BoolValue(true),
+			},
+		},
+		"non-null-state-value-unknown-plan": {
+			// this is the situation we want to preserve the state in
+			request: planmodifier.BoolRequest{
+				State: tfsdk.State{
+					Raw: tftypes.NewValue(
+						tftypes.Object{
+							AttributeTypes: map[string]tftypes.Type{
+								"attr": tftypes.Bool,
+							},
+						},
+						map[string]tftypes.Value{
+							"attr": tftypes.NewValue(tftypes.Bool, true),
+						},
+					),
+				},
+				StateValue:  types.BoolValue(true),
+				PlanValue:   types.BoolUnknown(),
+				ConfigValue: types.BoolNull(),
+			},
+			expected: &planmodifier.BoolResponse{
+				PlanValue: types.BoolValue(true),
+			},
+		},
+		"null-state-value-unknown-plan": {
+			// Null state values should not be preserved
+			request: planmodifier.BoolRequest{
+				State: tfsdk.State{
+					Raw: tftypes.NewValue(
+						tftypes.Object{
+							AttributeTypes: map[string]tftypes.Type{
+								"attr": tftypes.Bool,
+							},
+						},
+						map[string]tftypes.Value{
+							"attr": tftypes.NewValue(tftypes.Bool, nil),
+						},
+					),
+				},
+				StateValue:  types.BoolNull(),
+				PlanValue:   types.BoolUnknown(),
+				ConfigValue: types.BoolNull(),
+			},
+			expected: &planmodifier.BoolResponse{
+				PlanValue: types.BoolUnknown(),
+			},
+		},
+		"unknown-config": {
+			// this is the situation in which a user is
+			// interpolating into a field. We want that to still
+			// show up as unknown, otherwise they'll get apply-time
+			// errors for changing the value even though we knew it
+			// was legitimately possible for it to change and the
+			// provider can't prevent this from happening
+			request: planmodifier.BoolRequest{
+				State: tfsdk.State{
+					Raw: tftypes.NewValue(
+						tftypes.Object{
+							AttributeTypes: map[string]tftypes.Type{
+								"attr": tftypes.Bool,
+							},
+						},
+						map[string]tftypes.Value{
+							"attr": tftypes.NewValue(tftypes.Bool, true),
+						},
+					),
+				},
+				StateValue:  types.BoolValue(true),
+				PlanValue:   types.BoolUnknown(),
+				ConfigValue: types.BoolUnknown(),
+			},
+			expected: &planmodifier.BoolResponse{
+				PlanValue: types.BoolUnknown(),
+			},
+		},
+	}
+
+	for name, testCase := range testCases {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			resp := &planmodifier.BoolResponse{
+				PlanValue: testCase.request.PlanValue,
+			}
+
+			boolplanmodifier.UseNonNullStateForUnknown().PlanModifyBool(context.Background(), testCase.request, resp)
+
+			if diff := cmp.Diff(testCase.expected, resp); diff != "" {
+				t.Errorf("unexpected difference: %s", diff)
+			}
+		})
+	}
+}

resource/schema/boolplanmodifier/use_state_for_unknown.go

@@ -17,6 +17,10 @@ import (
 // and Computed attributes to an unknown value "(known after apply)" on update.
 // Using this plan modifier will instead display the prior state value in the
 // plan, unless a prior plan modifier adjusts the value.
+//
+// Null is also a known value in Terraform and will be copied to the planned value
+// by this plan modifier. For use-cases like a child attribute of a nested attribute or
+// if null is desired to be marked as unknown in the case of an update, use [UseNonNullStateForUnknown].
 func UseStateForUnknown() planmodifier.Bool {
 	return useStateForUnknownModifier{}
 }

resource/schema/dynamicplanmodifier/use_non_null_state_for_unknown.go

@@ -0,0 +1,54 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package dynamicplanmodifier
+
+import (
+	"context"
+
+	"github.com/hashicorp/terraform-plugin-framework/resource/schema/planmodifier"
+)
+
+// UseNonNullStateForUnknown returns a plan modifier that copies a known, non-null, prior state
+// value into the planned value. Use this when it is known that an unconfigured value will remain the
+// same after the attribute is updated to a non-null value.
+//
+// To prevent Terraform errors, the framework automatically sets unconfigured
+// and Computed attributes to an unknown value "(known after apply)" on update.
+// Using this plan modifier will instead display the non-null prior state value in the
+// plan, unless a prior plan modifier adjusts the value.
+//
+// This plan modifier can be a useful alternative to [UseStateForUnknown] when the attribute is
+// a child of a nested attribute that can be null after the resource is created.
+func UseNonNullStateForUnknown() planmodifier.Dynamic {
+	return useNonNullStateForUnknown{}
+}
+
+type useNonNullStateForUnknown struct{}
+
+func (m useNonNullStateForUnknown) Description(_ context.Context) string {
+	return "Once set to a non-null value, the value of this attribute in state will not change."
+}
+
+func (m useNonNullStateForUnknown) MarkdownDescription(_ context.Context) string {
+	return "Once set to a non-null value, the value of this attribute in state will not change."
+}
+
+func (m useNonNullStateForUnknown) PlanModifyDynamic(ctx context.Context, req planmodifier.DynamicRequest, resp *planmodifier.DynamicResponse) {
+	// Do nothing if the state value is null.
+	if req.StateValue.IsNull() {
+		return
+	}
+
+	// Do nothing if there is a known planned value.
+	if !req.PlanValue.IsUnknown() {
+		return
+	}
+
+	// Do nothing if there is an unknown configuration value, otherwise interpolation gets messed up.
+	if req.ConfigValue.IsUnknown() {
+		return
+	}
+
+	resp.PlanValue = req.StateValue
+}