diff --git a/packages/@aws-cdk/cloud-assembly-schema/lib/cloud-assembly/artifact-schema.ts b/packages/@aws-cdk/cloud-assembly-schema/lib/cloud-assembly/artifact-schema.ts
index b3dbd0da8..22e14379d 100644
--- a/packages/@aws-cdk/cloud-assembly-schema/lib/cloud-assembly/artifact-schema.ts
+++ b/packages/@aws-cdk/cloud-assembly-schema/lib/cloud-assembly/artifact-schema.ts
@@ -238,7 +238,7 @@ export interface FeatureFlagReportProperties {
   /**
    * Information about every feature flag supported by this library.
    */
-  readonly flags: Record<string, FeatureFlag>;
+  readonly flags: { [flagName: string]: FeatureFlag };
 }
 
 /**
@@ -273,11 +273,44 @@ export interface FeatureFlag {
   readonly explanation?: string;
 
   /**
-   * The value of the flag if it is unconfigured
+   * The value of the flag that produces the same behavior as when the flag is not configured at all
    *
-   * @default - No value
+   *The structure of this field is a historical accident. The type of this field
+   *should have been boolean, which should have contained the default value for
+   *the flag appropriate for the *current* version of the CDK library. We are
+   *not rectifying this accident because doing so
+   *
+   * Instead, the canonical way to access this value is by evaluating
+   * `unconfiguredBehavesLike?.v2 ?? false`.
+   *
+   * @default false
+   */
+  readonly unconfiguredBehavesLike?: UnconfiguredBehavesLike;
+}
+
+export interface UnconfiguredBehavesLike {
+  /**
+   * Historical accident, don't use.
+   *
+   * This value may be present, but it should never be used. The actual value is
+   * in the `v2` field, regardless of the version of the CDK library.
+   *
+   * @default - ignore
+   */
+  readonly v1?: any;
+
+  /**
+   * The value of the flag that produces the same behavior as when the flag is not configured at all
+   *
+   * Even though it is called 'v2', this is the official name of this field. In
+   * any future versions of CDK (v3, v4, ...), this field will still be called 'v2'.
+   *
+   * The structure of this field is a historical accident. See the comment on
+   * `unconfiguredBehavesLike` for more information.
+   *
+   * @default false
    */
-  readonly unconfiguredBehavesLike?: { [key: string]: any };
+  readonly v2?: any;
 }
 
 /**
diff --git a/packages/@aws-cdk/cloud-assembly-schema/schema/cloud-assembly.schema.json b/packages/@aws-cdk/cloud-assembly-schema/schema/cloud-assembly.schema.json
index c91b4021b..9c00c4a41 100644
--- a/packages/@aws-cdk/cloud-assembly-schema/schema/cloud-assembly.schema.json
+++ b/packages/@aws-cdk/cloud-assembly-schema/schema/cloud-assembly.schema.json
@@ -505,8 +505,11 @@
                     "type": "string"
                 },
                 "flags": {
-                    "$ref": "#/definitions/Record<string,FeatureFlag>",
-                    "description": "Information about every feature flag supported by this library."
+                    "description": "Information about every feature flag supported by this library.",
+                    "type": "object",
+                    "additionalProperties": {
+                        "$ref": "#/definitions/FeatureFlag"
+                    }
                 }
             },
             "required": [
@@ -514,8 +517,38 @@
                 "module"
             ]
         },
-        "Record<string,FeatureFlag>": {
-            "type": "object"
+        "FeatureFlag": {
+            "description": "A single feature flag",
+            "type": "object",
+            "properties": {
+                "recommendedValue": {
+                    "description": "The library-recommended value for this flag, if any\n\nIt is possible that there is no recommended value. (Default - No recommended value.)"
+                },
+                "userValue": {
+                    "description": "The value configured by the user\n\nThis is the value configured at the root of the tree. Users may also have\nconfigured values at specific locations in the tree; we don't report on\nthose. (Default - Not configured by the user)"
+                },
+                "explanation": {
+                    "description": "Explanation about the purpose of this flag that can be shown to the user. (Default - No description)",
+                    "type": "string"
+                },
+                "unconfiguredBehavesLike": {
+                    "description": "The value of the flag that produces the same behavior as when the flag is not configured at all\n\nThe structure of this field is a historical accident. The type of this field\nshould have been boolean, which should have contained the default value for\nthe flag appropriate for the *current* version of the CDK library. We are\nnot rectifying this accident because doing so\n\nInstead, the canonical way to access this value is by evaluating\n`unconfiguredBehavesLike?.v2 ?? false`.",
+                    "default": false,
+                    "$ref": "#/definitions/UnconfiguredBehavesLike"
+                }
+            }
+        },
+        "UnconfiguredBehavesLike": {
+            "type": "object",
+            "properties": {
+                "v1": {
+                    "description": "Historical accident, don't use.\n\nThis value may be present, but it should never be used. The actual value is\nin the `v2` field, regardless of the version of the CDK library. (Default - ignore)"
+                },
+                "v2": {
+                    "description": "The value of the flag that produces the same behavior as when the flag is not configured at all\n\nEven though it is called 'v2', this is the official name of this field. In\nany future versions of CDK (v3, v4, ...), this field will still be called 'v2'.\n\nThe structure of this field is a historical accident. See the comment on\n`unconfiguredBehavesLike` for more information.",
+                    "default": false
+                }
+            }
         },
         "MissingContext": {
             "description": "Represents a missing piece of context.",
diff --git a/packages/@aws-cdk/cloud-assembly-schema/schema/version.json b/packages/@aws-cdk/cloud-assembly-schema/schema/version.json
index 4fea20043..aa8c4bc2a 100644
--- a/packages/@aws-cdk/cloud-assembly-schema/schema/version.json
+++ b/packages/@aws-cdk/cloud-assembly-schema/schema/version.json
@@ -1,5 +1,5 @@
 {
-  "schemaHash": "0807b42f8220bdafddeb4dad246a696721ed86e99ac6b13aa83359bab834d60d",
+  "schemaHash": "4755f1d1fcb2dc25dd6bff0494afa7d86c517274ffebdf2ac2dcb90ad4b899c4",
   "$comment": "Do not hold back the version on additions: jsonschema validation of the manifest by the consumer will trigger errors on unexpected fields.",
   "revision": 48
 }
\ No newline at end of file