From 255845ce344e714ee2033eb61487ab1d8acf9f44 Mon Sep 17 00:00:00 2001
From: Eli Polonsky <Eli.polonsky@gmail.com>
Date: Wed, 8 Jan 2025 20:49:13 +0200
Subject: [PATCH] fix: primitive metadata values cannot be loaded in jsii
 languages (#121)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

In https://github.com/aws/aws-cdk/pull/31041, the CDK started emitting booleans and numbers as metadata values.
However, since these types are not officially declared in the schema, jsii runtime type checking prevents loading them:

```console
[ERROR] ├── 🛑 Failing value is a boolean
[ERROR] │      true
[ERROR] ╰── 🔍 Failure reason(s):
[ERROR]     ├─ [as string] Value is not a string
[ERROR]     ├─ [as array<aws-cdk-lib.cloud_assembly_schema.Tag>] Value is not an array
[ERROR]     ├─ [as aws-cdk-lib.cloud_assembly_schema.FileAssetMetadataEntry] Value is not an object
[ERROR]     ╰─ [as aws-cdk-lib.cloud_assembly_schema.ContainerImageAssetMetadataEntry] Value is not an object
```

Fixes https://github.com/aws/jsii/issues/4742

> Note that releasing this will immediately resolve the above issue, no cdk release needed. It does bump the schema version, which we can update at will.

## FAQ

### If the types are not allowed in the schema, how can a manifest with them be written?

Actually, these types **are** allowed in the schema, in the json schema that is:

https://github.com/cdklabs/cloud-assembly-schema/blob/f5ae537437531364646e7515e5286e21583c8421/schema/cloud-assembly.schema.json#L131-L133

This free form data is added to the json schema in order to support calls to `node.addMetadata(key: string, value: any)`, as defined in the `constructs` API. However, this type was intentionally left out of the type declaration:

https://github.com/cdklabs/cloud-assembly-schema/blob/f5ae537437531364646e7515e5286e21583c8421/projenrc/update-schema.ts#L79-L89

I'm fairly certain the comment is not applicable anymore, because we don't run jsii compatibility checks on the schema (we just bump it on every change). In practice, I think we can probably get rid of this patching and just type metadata entry values as `any` - but that seems like a bigger change I don't want to go into right now.

### If such manifests cannot be loaded, how does synth work?

Because during synth, loading the assembly using the `Manifest` class happens solely inside the javascript space, it doesn't callback to java land. This problem presents itself **only when** directly using the java `Manifest` class and invoking the `loadAssemblyManifest` function on a manifest produced by `app.synth()`.
---
 lib/cloud-assembly/metadata-schema.ts | 12 +++++++++++-
 schema/cloud-assembly.schema.json     |  6 +++++-
 schema/version.json                   |  2 +-
 3 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/lib/cloud-assembly/metadata-schema.ts b/lib/cloud-assembly/metadata-schema.ts
index 95d3da8..2896e42 100644
--- a/lib/cloud-assembly/metadata-schema.ts
+++ b/lib/cloud-assembly/metadata-schema.ts
@@ -260,6 +260,15 @@ export type LogicalIdMetadataEntry = string;
  */
 export type StackTagsMetadataEntry = Tag[];
 
+/**
+ * Any other type of metadata entry
+ *
+ * This could probably be changed to `any`, but it's safer not
+ * to do so right now.
+ * See https://github.com/cdklabs/cloud-assembly-schema/pull/121.
+ */
+export type PrimitiveType = boolean | number | string;
+
 /**
  * Union type for all metadata entries that might exist in the manifest.
  */
@@ -267,7 +276,8 @@ export type MetadataEntryData =
   | AssetMetadataEntry
   | LogMessageMetadataEntry
   | LogicalIdMetadataEntry
-  | StackTagsMetadataEntry;
+  | StackTagsMetadataEntry
+  | PrimitiveType;
 
 /**
  * Type of artifact metadata entry.
diff --git a/schema/cloud-assembly.schema.json b/schema/cloud-assembly.schema.json
index 1fbafd9..0c25e0e 100644
--- a/schema/cloud-assembly.schema.json
+++ b/schema/cloud-assembly.schema.json
@@ -126,7 +126,11 @@
                             }
                         },
                         {
-                            "type": "string"
+                            "type": [
+                                "string",
+                                "number",
+                                "boolean"
+                            ]
                         },
                         {
                             "description": "Free form data."
diff --git a/schema/version.json b/schema/version.json
index d0e215b..6ca936d 100644
--- a/schema/version.json
+++ b/schema/version.json
@@ -1,4 +1,4 @@
 {
-  "schemaHash": "f0ccc3212331af8a1c75830878d218fd667e5957063831be3b5bfd803b25f0cc",
+  "schemaHash": "bf762e5da559c685e06892ef65fdfc33d1c4bd53d4eb07d4a326d476ac58ae25",
   "revision": 39
 }
\ No newline at end of file