RFC 972: Structured design context in synthesized templates by satyakigh · Pull Request #981 · aws/aws-cdk-rfcs

satyakigh · 2026-08-04T17:54:12Z

This is a request for comments about Structured design context in synthesized templates. See #972 for
additional details.

APIs are signed off by @iliapolo

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

iliapolo

@satyakigh Are you also looking for feedback on the schema itself, or just the CDK part of things?

dgandhi62 · 2026-09-10T20:02:21Z

+
+The four allowed sources are:
+
+* `authored` - a person wrote or explicitly confirmed the information.


What if a human authored it AND any of the other three below are also true? Just something to consider

I think it becomes more important to create a source for AI agents specifically, and less so for humans

Added a precedence rule to Appendix A. authored applies whenever a person wrote or confirmed the text, even if it came from a comment, commit, or inference; the evidence goes in cite and note. Otherwise use the most direct evidence: comment, then commit. infer applies when the tool reasoned or combined evidence. A worked example is included.

Agreed on the second point. Three of the four values exist for automated producers, and the RFC now says so; a person writing Context directly in CDK code can omit trust. The enum is fixed by the published v1 schema (https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-attribute-metadata.html#aws-attribute-metadata-context-schema), so a dedicated agent value would be a schema change. infer already plays that role, and the authoring skill (https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/core-skills/aws-cloudformation/SKILL.md) is where agent guidance is tuned.

I see it. I think this information should be an instruction to authors and AI agents both, and should be part of the README (if not also the skill)

iliapolo

Also please provide the full public API of all classes we are introducing (in TypeScript form). Right now its kind of scattered between examples and hard to get a full picture.

We can then approve that API and merge it as stable from the get go.

iliapolo · 2026-09-21T19:19:05Z

+
+Two classes write the same documented template fields: `ResourceMetadataContext` writes
+information on individual resources, and `TemplateMetadataContext` writes information once
+for the whole template. `MetadataContextMixin` is a CDK Mixin, which is an API applied


For consistency with the aspect classes - it also makes sense because it can only be applied to resources.

Suggested change

for the whole template. `MetadataContextMixin` is a CDK Mixin, which is an API applied

for the whole template. `ResourceMetadataContextMixin` is a CDK Mixin, which is an API applied

The Mixin is removed entirely (see the thread on the Mixin form section below)

iliapolo · 2026-09-21T19:20:56Z

+People and automated tools that inspect a deployed template can
+therefore use the author's intent instead of guessing it.
+
+Two classes write the same documented template fields: `ResourceMetadataContext` writes


Suggested change

Two classes write the same documented template fields: `ResourceMetadataContext` writes

Two aspects write the same documented template fields: `ResourceMetadataContext` writes

Changed to "Two APIs". I avoided "aspects" because TemplateMetadataContext isn't aspect-backed: it writes the stack's template Metadata directly when add() is called. Only ResourceMetadataContext registers an aspect.

iliapolo · 2026-09-21T19:27:27Z

+No `trust` block appears because the caller did not provide one. The `trust` field is
+optional, and CDK never adds it automatically (see *Source and confidence* below).
+`mutable` is `change-with-constraints`, and the governing rule is recorded in
+`must`: `VisibilityTimeout` must remain at least six times the Lambda timeout.
+`change-with-constraints` means a value may change only while its stated rules remain true;
+using that value without a corresponding `must` rule gives the reader no useful guidance.
+


No need for this entire paragraph - it should all be mentioned in the schema definition we link to already. Unless you want to emphasize a specific property - but then also give a short explanation about it. I think we can just remove it.

iliapolo · 2026-09-21T19:33:45Z

+`why` or `must` when another applicable declaration supplies them, and no template-level
+field is required either.
+
+##### Propagation is explicit


This should come sooner - just after you show the example of add, that way the reader still has this API in their mind.

Moved. Propagation is explicit now follows the first add() example directly, and the quality guidance moved to the end of the README as Writing good context.

iliapolo · 2026-09-21T19:35:22Z

+`change-with-constraints` means a value may change only while its stated rules remain true;
+using that value without a corresponding `must` rule gives the reader no useful guidance.
+
+##### Resource context quality


Should go last after all other field specific explanations. Also rename to Writing good context

Done. It is now the last section, titled Writing good context, and it also absorbed the conciseness and size paragraphs that used to trail Template-level context.

iliapolo · 2026-09-21T20:20:45Z

+Template level here means `TemplateMetadataContext`, not the template's built-in
+`Description`. The two serve different readers: `Description` is one short, unstructured
+string (at most 1,024 bytes) that CloudFormation shows in the console stack list and
+returns from `DescribeStacks`, so it works best as a one-line statement of what the stack is.
+`TemplateMetadataContext` holds the structured fields `arch`, `must`, `ref`, and `owner`,
+which are returned only inside the template body (`GetTemplate`) and answer how the system
+is shaped, which rules apply everywhere, and where supporting material lives. Avoid repeating
+the `Description` text in `arch`, and keep rules out of `Description`. See *Template-level
+context* below for a side-by-side comparison.


Too much information about a side concept. Remove it (instead just link to the relevant section in the paragraph above).

Removed. The paragraph above now links to Template-level context

iliapolo · 2026-09-21T20:29:41Z

+   contributing evidence in `cite` and `note`.
+
+For example, a tool that lifts `why` from a comment writes `src: COMMENT` and
+`cite: 'lib/queue.ts:42'`; when the author reviews and accepts it, `src` becomes `AUTHORED`


You mean "src should become AUTHORED"? As in, the PR author should make a change after getting approval?

Yes. It now reads: "the author (or the tool, on the author's confirmation) should change src to AUTHORED and keep cite"

iliapolo · 2026-09-21T20:31:18Z

+and `cite` stays. Three of the four values exist for automated producers, where `src` matters
+most: a reader must be able to tell tool-derived Context from Context a person stands behind.
+A person writing Context directly in CDK code can omit `trust`, because the reviewed source
+already shows who wrote it. The Agent Toolkit's CloudFormation and CDK skills will be


already shows who wrote it

What do you mean? how? I thought a person writing context should explicitly use AUTHORED...

That sentence conflated source history with what a template reader can see. It now reads: a person writing Context directly uses src: AUTHORED; a tool uses COMMENT, COMMIT, or INFER according to its evidence and switches to AUTHORED only after a person confirms the text. trust stays optional per the schema, so a block without it leaves the source unstated, and the text recommends setting it wherever tool-derived and human-written Context may share a template.

iliapolo · 2026-09-21T20:50:20Z

+[Appendix A](#appendix-a---cloudformation-context-template-field-reference) for the
+`trust` object.
+
+##### Mixin form


Why do we actually need the mixin here? what does it give that the aspect doesn't?

Im also seeing the mixin API doesn't have all the capabilities, for example inheritAncestorContext, is that intentional? If we don't really need the mixin, lets not have it. If we are keeping it - we should also mention how conflicts between the aspect and the mixin are handled.

Agreed, and removed. It was a strict subset of the aspect: .with() on an L1 is ResourceMetadataContext.of(cfnResource).add(), and Mixins.of(scope).apply() is add(..., { propagate: true }), except that it applied eagerly, so resources created after the call were missed. It also needed an awslint mixin-namespace exemption. The Public API is now three classes

iliapolo · 2026-09-21T20:52:48Z

+directly with `CfnResource.addMetadata()`. If manually added information and a metadata-
+context API target the same resource and key, template generation fails instead of silently


Suggested change

directly with `CfnResource.addMetadata()`. If manually added information and a metadata-

context API target the same resource and key, template generation fails instead of silently

directly with `CfnResource.addMetadata()`. If manually added information and a metadata-context API target the same resource and key, template generation fails instead of silently

Applied, rewrapped so metadata-context stays on one line.

satyakigh force-pushed the context-rfc branch from e0d092c to 25ced1c Compare August 4, 2026 17:54

otaviomacedo reviewed Aug 6, 2026

View reviewed changes

Comment thread text/0972-metadata-context.md

satyakigh mentioned this pull request Aug 11, 2026

feat(core): embed structured design context in synthesized templates (MetadataContext) aws/aws-cdk#38381

Open

1 task

dgandhi62 reviewed Aug 26, 2026

View reviewed changes

Comment thread text/0972-metadata-context.md Outdated

Comment thread text/0972-metadata-context.md Outdated

iliapolo reviewed Aug 26, 2026

View reviewed changes

iliapolo requested changes Aug 27, 2026

View reviewed changes

satyakigh force-pushed the context-rfc branch from 1c0c294 to d210b04 Compare August 28, 2026 13:43

r-heimann mentioned this pull request Aug 31, 2026

feat: Add metadata context validation rules (I4010, I4011, I4012) aws-cloudformation/cfn-lint#4655

Merged

dgandhi62 reviewed Sep 10, 2026

View reviewed changes

satyakigh added 8 commits September 14, 2026 11:16

RFC 972: Structured design context in synthesized templates

5403c99

Improve rfc

40a2be9

add metadata under namespace

ca5c5eb

add precedence

77f6b08

address feedback

3588b9f

update RFC

ddf34be

Remove ops, gaps

5ce5e2a

Address feedback

12543b4

satyakigh force-pushed the context-rfc branch from 35cad9a to 12543b4 Compare September 14, 2026 15:16

atennak1 approved these changes Sep 14, 2026

View reviewed changes

iliapolo requested changes Sep 16, 2026

View reviewed changes

Comment thread text/0972-metadata-context.md Outdated

Comment thread text/0972-metadata-context.md Outdated

Comment thread text/0972-metadata-context.md Outdated

Comment thread text/0972-metadata-context.md Outdated

Comment thread text/0972-metadata-context.md Outdated

Update RFC to match schema

3c07073

iliapolo requested changes Sep 21, 2026

View reviewed changes

Address feedback

32c2f67


		The four allowed sources are:

		* `authored` - a person wrote or explicitly confirmed the information.

	for the whole template. `MetadataContextMixin` is a CDK Mixin, which is an API applied
	for the whole template. `ResourceMetadataContextMixin` is a CDK Mixin, which is an API applied

	Two classes write the same documented template fields: `ResourceMetadataContext` writes
	Two aspects write the same documented template fields: `ResourceMetadataContext` writes

		directly with `CfnResource.addMetadata()`. If manually added information and a metadata-
		context API target the same resource and key, template generation fails instead of silently

Conversation

satyakigh commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

iliapolo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

iliapolo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

satyakigh Sep 22, 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!

satyakigh Sep 22, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

satyakigh Sep 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

satyakigh commented Aug 4, 2026 •

edited

Loading

satyakigh Sep 22, 2026 •

edited

Loading

satyakigh Sep 22, 2026 •

edited

Loading

satyakigh Sep 22, 2026 •

edited

Loading

satyakigh Sep 22, 2026 •

edited

Loading

satyakigh Sep 22, 2026 •

edited

Loading

satyakigh Sep 22, 2026 •

edited

Loading