From f06479b2e412ea6c69eeace9c0de8c5370736479 Mon Sep 17 00:00:00 2001 From: Rico Huijbers Date: Mon, 11 Aug 2025 15:26:31 +0200 Subject: [PATCH 1/3] fix(schema): `unconfiguredBehavesLike` contains info for multiple versions The way it's currently specified, the `unconfiguredBehavesLike` field that's in the Cloud Assembly Schema requires the CLI to know the current major version of the CDK Library to properly evaluate: It looks like `unconfiguredBehavesLike: { v1: ..., v2: ... }` subfields, and that requires the CLI to know whether to look in the `v1` or `v2` subfield (and in the future `v3`, `v4`, etc...). That is unnecessary: since the CDK Library knows its own current version so it could just have communicated `unconfiguredBehavesLike: true` to accurately reflect its current behavior, without the consumer needing to know anything about the version. The CLI code right now is only reading the `v2` field, but that will become inaccurate if we ever release CDKv3. In this PR, we're saying that the `v2` subfield is the "official" location of this value going forward. `v1` should be ignored if present (but is still included to not trip up any JSON Schema validation). This leads to the least amount of interference with the existing ecosystem (no forced upgrade by CDK users and no backwards compatibility path in the CLI to potentially read 2 fields). --- .../lib/cloud-assembly/artifact-schema.ts | 39 +++++++++++++++++-- 1 file changed, 36 insertions(+), 3 deletions(-) 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..1de93867c 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 @@ -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; } /** From dfb8c76e594c2b58fcbaf6eed58fe5f1713e6b6a Mon Sep 17 00:00:00 2001 From: Rico Huijbers Date: Mon, 11 Aug 2025 16:18:30 +0200 Subject: [PATCH 2/3] Aha, Record<...> is not being translated --- .../lib/cloud-assembly/artifact-schema.ts | 2 +- .../schema/cloud-assembly.schema.json | 41 +++++++++++++++++-- .../cloud-assembly-schema/schema/version.json | 4 +- 3 files changed, 40 insertions(+), 7 deletions(-) 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 1de93867c..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; + readonly flags: { [flagName: string]: FeatureFlag }; } /** 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", - "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": { - "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..942f81942 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 +} From 928fdecccab7085c10089e37f34114198d9ecf68 Mon Sep 17 00:00:00 2001 From: github-actions Date: Mon, 11 Aug 2025 14:26:53 +0000 Subject: [PATCH 3/3] chore: self mutation Signed-off-by: github-actions --- packages/@aws-cdk/cloud-assembly-schema/schema/version.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/@aws-cdk/cloud-assembly-schema/schema/version.json b/packages/@aws-cdk/cloud-assembly-schema/schema/version.json index 942f81942..aa8c4bc2a 100644 --- a/packages/@aws-cdk/cloud-assembly-schema/schema/version.json +++ b/packages/@aws-cdk/cloud-assembly-schema/schema/version.json @@ -2,4 +2,4 @@ "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