Skip to content

docs(core): document special construct IDs - #38698

Open
ZedingZhang wants to merge 1 commit into
aws:mainfrom
ZedingZhang:docs/construct-logical-id-special-ids
Open

docs(core): document special construct IDs#38698
ZedingZhang wants to merge 1 commit into
aws:mainfrom
ZedingZhang:docs/construct-logical-id-special-ids

Conversation

@ZedingZhang

Copy link
Copy Markdown

Issue # (if applicable)

Closes #21410.

Reason for this change

The special treatment of construct IDs named Default and Resource during CloudFormation logical ID generation was only documented in the implementation. Users could unintentionally change logical IDs or produce duplicate logical IDs without knowing that these names have special behavior.

Description of changes

Adds a new section to the aws-cdk-lib README that documents:

  • How construct paths are used to generate CloudFormation logical IDs.
  • The replacement risks associated with renaming or moving constructs.
  • How Default is removed entirely from logical ID calculation, including the hash.
  • How Resource is omitted from the human-readable portion of nested resource logical IDs while remaining part of the hash.
  • The intended uses and collision risks of both special IDs.

This is a documentation-only change and does not modify logical ID behavior.

Describe any new or updated permissions being added

None.

Description of how you validated changes

  • Ran git diff --check.
  • Ran MarkdownLint against packages/aws-cdk-lib/README.md using the repository's MarkdownLint configuration.
  • Compared the documentation against the implementation in core/lib/private/uniqueid.ts and the existing logical ID tests.

A full build was not run because the change only adds prose and a Markdown table, with no code or Rosetta examples.

Checklist


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

@github-actions github-actions Bot added bug This issue is a bug. effort/small Small work item – less than a day of effort p2 labels Aug 29, 2026
@aws-cdk-automation
aws-cdk-automation requested a review from a team August 29, 2026 16:33
@github-actions github-actions Bot added the beginning-contributor [Pilot] contributed between 0-2 PRs to the CDK label Aug 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

beginning-contributor [Pilot] contributed between 0-2 PRs to the CDK bug This issue is a bug. effort/small Small work item – less than a day of effort p2

Projects

None yet

Development

Successfully merging this pull request may close these issues.

aws_sns_subscriptions: Naming topic Default breaks subscriptions

1 participant