aws-apigateway: JsonSchema additionalItems is undeployable

[jusdino]

Describe the bug

It looks like the aws-apigateway JsonSchema interface is wrong with its type for the additionalItems property: The interface expects type JsonSchema[] but, based on the JSON Schema Draft-04 meta schema, it should be JsonSchema | boolean, just like it is for additionalProperties. This error results in models that include an additionalItems parameter being undeployable via CDK:

• If the CDK code follows the JSON interface and provides a JsonSchema[], API Gateway will reject the model as invalid.
• If the CDK code correctly uses a JsonSchema or boolean, the app won't synthesize.

I'll demonstrate the correct use of additionalItems in the integration test for the PR I'll open to fix this, shortly.

Expected Behavior

aws-cdk should deploy any correct JSON Schema model up to Draft-04.

Current Behavior

aws-cdk cannot deploy models with JsonSchema that include additionalItems.

Reproduction Steps

See the integration test in accompanying PR.

Possible Solution

We should be able to simply correct the interface. This is strictly a breaking change but, based on my understanding of the policy on breaking changes, since this bug prevents use of the changed feature, the change should be acceptable.

CDK CLI Version

2.1005.0

Node.js Version

v22.14.0

OS

Ubuntu 24.04.2 LTS

Language

TypeScript

Language Version

5.5.4

[pahud]

Thank you for the feedback and PR. I am surprised as JSII should not support union types like

https://github.com/aws/aws-cdk/blame/2dc5d702bc55030927dd45fe88a6cd68f629fee9/packages/aws-cdk-lib/aws-apigateway/lib/json-schema.ts#L34

but it's in our codebase. I'll bring this up to the team for inputs and we'll review your PR when it's ready.

[jusdino]

Sounds good! The PR is already ready. It does have this breaking change, though, so the CodeBuild is failing.

[jusdino]

Good morning @pahud, just checking in on this one.

[jusdino]

BTW, about the union types:

I am surprised as JSII should not support union types like

https://github.com/aws/aws-cdk/blame/2dc5d702bc55030927dd45fe88a6cd68f629fee9/packages/aws-cdk-lib/aws-apigateway/lib/json-schema.ts#L34

but it's in our codebase. I'll bring this up to the team for inputs and we'll review your PR when it's ready.

Strictly speaking, that's a bit of a misnomer. JSII does support union types, just kind of poorly, so resorting to union types is discouraged. If I remember right, it results in a crummy interface for some languages, since it winds up doing something like using the nearest common ancestor type of all elements in the union, for statically typed languages. So, this JsonSchema | boolean would just wind up being something like object in those cases. That's not great, but it's consistent with the additionalProperties type, so I think it's appropriate here.

[jusdino]

@pahud hey there! Just trying to keep this from getting lost in the shuffle. I was kind of hoping that this would be just a matter of validating with the team then merging. Anything I can do to assist further?

[github-actions]

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.