feat(cloud-assembly-schema): add policy validation report schema types by kaizencc · Pull Request #1515 · aws/aws-cdk-cli

kaizencc · 2026-05-14T17:22:11Z

Define the JSON schema types for policy-validation-report.json in the shared cloud-assembly-schema package. This file is written by aws-cdk-lib during synthesis and consumed by toolkit-lib's validate command. Having the types in the shared contract prevents drift between producer and consumer.

Corresponding types in aws-cdk-lib

These schema types mirror the structures defined in aws-cdk-lib:

packages/aws-cdk-lib/core/lib/validation/validation.ts — IPolicyValidationPluginBeta1, PolicyViolationBeta1, PolicyViolatingResourceBeta1
packages/aws-cdk-lib/core/lib/validation/private/report.ts — report formatting and JSON serialization

Schema sufficiency for RFC 899

We evaluated whether schema changes are needed to support CDK Comprehensive Validation (RFC 899) and its proposed output format. The existing schema is sufficient — all data required by the RFC is either already present or derivable at display time:

RFC requirement	How it's satisfied
Severity grouping (Fatal/Error/Warning)	`PolicyViolationJson.severity` is already present. CLI groups violations by severity at display time. Defaults to Warning if absent.
Source name (e.g. "ValidationEngine (Default)", "CdkNagValidator")	Derivable from `PluginReportJson.summary.pluginName`
Suppression/acknowledge ID	Derivable as `${pluginName}::${ruleName}` (both fields present). Spaces replaced with dashes per aws-cdk#37808.
Suppress instruction	Computed by CLI: `Acknowledge '${pluginName}::${ruleName}'`. Omitted for Fatal violations.
Summary counts	Computed from violation arrays at render time
Source file location	`ViolatingConstructJson.constructStack.location`
Construct path	`ViolatingConstructJson.constructPath`

For Construct Annotations specifically, aws-cdk-lib (via #37808) converts annotations into PolicyViolation objects before writing the report — extracting the [ack: id] tag as ruleName and mapping the level to severity. By the time the CLI reads the report, it's already structured.

No additional schema fields are needed. The RFC output is purely a CLI display concern.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

Define the JSON schema types for `policy-validation-report.json` in the shared cloud-assembly-schema package. This file is written by aws-cdk-lib during synthesis and consumed by toolkit-lib's validate command. Having the types in the shared contract prevents drift between producer and consumer. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

github-actions · 2026-05-14T17:22:35Z

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

…t coverage threshold

rix0rrr · 2026-05-19T08:25:45Z

+ * use `PolicyViolationSeverity.custom('critical')`.
+ */
+export class PolicyViolationSeverity {
+  static readonly ERROR = new PolicyViolationSeverity('error');


This is a schema library. We have no need of values, and I have a suspicion they will hinder more than they will help.

rix0rrr · 2026-05-19T08:27:02Z

+  readonly constructStack?: ConstructTraceJson;
+
+  /**
+   * Locations within the construct where the violation was detected.


What is the formalism here? Property names? JSON paths? What?

rix0rrr · 2026-05-19T08:27:15Z

+  /**
+   * The logical ID of the resource in the CloudFormation template.
+   */
+  readonly resourceLogicalId: string;


Needs to be optional if this is about constructs.

(In fact: how do we have optional construct PATHS, but definitely logical IDs?)

rix0rrr · 2026-05-19T08:27:48Z

+  /**
+   * The path to the CloudFormation template containing this resource.
+   */
+  readonly templatePath: string;


Same here, this cannot be required.

rix0rrr · 2026-05-19T08:28:38Z

+   *
+   * @default - no construct path
+   */
+  readonly constructPath?: string;


Why would we ever not have a construct path?

rix0rrr · 2026-05-19T08:29:02Z

+  /**
+   * The construct ID.
+   */
+  readonly id: string;


ID is unnecessary, it's the last part of teh path.

rix0rrr · 2026-05-19T08:29:22Z

+   *
+   * @default - no construct info
+   */
+  readonly construct?: string;


Suggested change

readonly construct?: string;

readonly classFqn?: string;

rix0rrr · 2026-05-19T08:29:38Z

+  readonly construct?: string;
+
+  /**
+   * The version of the library that contains this construct.


Library name and version? Or just version?

rix0rrr · 2026-05-19T08:29:50Z

+  readonly libraryVersion?: string;
+
+  /**
+   * The source code location where this construct was created.


Do you mean stack trace?

rix0rrr · 2026-05-19T08:36:07Z

+/**
+ * A report from a single validation plugin.
+ */
+export interface PluginReportJson {


Should we not report on suppressions in here as well? cdk-nag needs that, doesn't it?

rix0rrr · 2026-05-19T08:39:08Z

+  readonly constructPath?: string;
+
+  /**
+   * The construct creation stack trace.


There is a lot of data in that struct that is not a stack trace though.

…SON schema validation Add validation-report.schema.json and a loadValidationReport() method on Manifest, following the same pattern as loadAssetManifest/loadIntegManifest. Consumers can now load and validate the policy validation report in one call.

Test valid reports load correctly, optional fields are preserved, and invalid reports (missing required fields, invalid enum values) throw validation errors.

…m validate() The validate() method's `asserts manifest is AssemblyManifest` narrowing caused type errors when loadManifest was used for non-AssemblyManifest schemas (like the validation report). Changed to `void` since validate is used purely for its side effect (throwing on invalid schemas).

kaizencc · 2026-05-19T19:18:25Z

    schema: jsonschema.Schema,
    options?: LoadManifestOptions,
-  ): asserts manifest is assembly.AssemblyManifest {
+  ): void {


validate() is called in saveManifest and loadManifest for its side effect (throwing on invalid input). It happens to work for the other loaders because AssetManifest and IntegManifest both have version: string, making them structurally compatible with AssemblyManifest. We can't get it to work for PolicyValidationReportJson because it has no version field. The asserts narrowing isn't meant to be there — validate() validates against arbitrary schemas, not specifically AssemblyManifest

Subsequent research shows me that we should actually have a version: string property if we want the policy report as part of the manifest. So I've added it in, and now this line would work as is. However, it's still wrong for many of the functions in Manifest, and just happens to work because they all share version: string. So I'm keeping this change

Add required `version` field to PolicyValidationReportJson, matching the pattern used by AssemblyManifest and AssetManifest. This enables the existing version compatibility check in Manifest.validate() and prepares the report for inclusion in the cloud assembly protocol.

…lds test

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

kaizencc temporarily deployed to automation May 14, 2026 17:22 — with GitHub Actions Inactive

github-actions Bot added the p2 label May 14, 2026

aws-cdk-automation enabled auto-merge May 14, 2026 17:22

kaizencc temporarily deployed to no-approval May 14, 2026 17:22 — with GitHub Actions Inactive

aws-cdk-automation requested a review from a team May 14, 2026 17:22

kaizencc temporarily deployed to run-tests May 14, 2026 17:26 — with GitHub Actions Inactive

kaizencc temporarily deployed to run-tests May 18, 2026 15:38 — with GitHub Actions Inactive

kaizencc mentioned this pull request May 18, 2026

feat(core): failSynthOnValidationErrors context key to suppress console output and exit code aws/aws-cdk#37909

Merged

1 task

test(cloud-assembly-schema): add PolicyViolationSeverity tests to mee…

f4de61c

…t coverage threshold

kaizencc temporarily deployed to no-approval May 18, 2026 21:19 — with GitHub Actions Inactive

kaizencc temporarily deployed to run-tests May 18, 2026 21:24 — with GitHub Actions Inactive

Merge branch 'main' into conroyka/validation-report-schema

3f06a2d

rix0rrr reviewed May 19, 2026

View reviewed changes

rix0rrr added 2 commits May 19, 2026 10:54

Schema re-imagined

07add62

Add stack trace

71d7d2c

rix0rrr approved these changes May 19, 2026

View reviewed changes

kaizencc and others added 5 commits May 19, 2026 09:58

typo

d39ba6d

test(cloud-assembly-schema): add tests for Manifest.loadValidationReport

e0951ff

Test valid reports load correctly, optional fields are preserved, and invalid reports (missing required fields, invalid enum values) throw validation errors.

Merge branch 'main' into conroyka/validation-report-schema

85fd946

kaizencc commented May 19, 2026

View reviewed changes

kaizencc and others added 3 commits May 19, 2026 12:29

fix(cloud-assembly-schema): add missing version field to optional fie…

53b27b3

…lds test

chore: self mutation

56c5fc3

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

This was referenced May 21, 2026

feat(core): new validation report schema aws/aws-cdk#37970

Merged

feat(cli): cdk validate command (behind --unstable flag) #1527

Open

Conversation

kaizencc commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Corresponding types in aws-cdk-lib

Schema sufficiency for RFC 899

Uh oh!

github-actions Bot commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Dependency Review

Scanned Files

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rix0rrr May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

kaizencc commented May 14, 2026 •

edited

Loading

github-actions Bot commented May 14, 2026 •

edited

Loading

rix0rrr May 19, 2026 •

edited

Loading