{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://cloudformation.aws.dev/schema/metadata-context/v1.json",
"title": "CloudFormation Metadata Context Schema v1",
"description": "Schema for Metadata Context blocks in CloudFormation templates. Advisory — for client-side validation, not server-side enforcement.",
"$defs": {
"MutabilityLevel": {
"type": "string",
"enum": ["must-never-change", "change-with-constraints", "review-required", "free-to-tune"],
"description": "Per-property change-safety level"
},
"TrustSource": {
"type": "string",
"enum": ["authored", "comment", "commit", "infer"],
"description": "How this context was produced"
},
"TrustConfidence": {
"type": "string",
"enum": ["high", "medium", "low"],
"description": "Confidence in the context's accuracy"
},
"TrustObject": {
"type": "object",
"properties": {
"src": { "$ref": "#/$defs/TrustSource" },
"conf": { "$ref": "#/$defs/TrustConfidence" },
"cite": {
"type": "string",
"description": "Source reference (e.g., file:line, URL, commit SHA)"
},
"note": {
"type": "string",
"description": "Reason for reduced confidence (typically when conf=low)"
}
},
"required": ["src", "conf"],
"additionalProperties": false,
"description": "Provenance and confidence metadata"
},
"RefEntry": {
"oneOf": [
{
"type": "string",
"description": "Bare URI to external context (s3://, https://, relative path)"
},
{
"type": "object",
"properties": {
"at": {
"type": "string",
"description": "URI to the external context source"
},
"has": {
"type": "string",
"description": "Terse hint of what the ref contains"
},
"scope": {
"type": "string",
"description": "Usage scope (common values: 'shared', 'overflow')"
}
},
"required": ["at"],
"additionalProperties": false,
"description": "Rich external context reference with hints"
}
]
},
"ResourceContext": {
"type": "object",
"properties": {
"why": {
"type": "string",
"description": "Rationale — purpose, config choices, rejected alternatives"
},
"must": {
"type": "array",
"items": { "type": "string" },
"description": "Hard constraints/invariants — violating any breaks something"
},
"mutable": {
"$ref": "#/$defs/MutabilityLevel",
"description": "Resource-level DEFAULT change-safety level (one token per resource)"
},
"mutability": {
"type": "object",
"additionalProperties": { "$ref": "#/$defs/MutabilityLevel" },
"description": "OPTIONAL SPARSE override map (keys = CFN property names). Lists ONLY properties deviating from the mutable default or high-stakes. Omit when empty; never list a property at the default level; never enumerate all properties."
},
"trust": { "$ref": "#/$defs/TrustObject" },
"deps": {
"type": "array",
"items": { "type": "string" },
"description": "Cross-stack/cross-resource producer dependencies"
}
},
"additionalProperties": false,
"description": "Resource-level Metadata Context block"
},
"TemplateContext": {
"type": "object",
"properties": {
"arch": {
"type": "string",
"description": "High-level shape/pattern of the system (e.g. 'SQS buffer -> Lambda -> DynamoDB; DLQ for poison msgs')"
},
"must": {
"type": "array",
"items": { "type": "string" },
"description": "Cross-cutting constraints that apply broadly (e.g. ['all data encrypted w/ security-team CMK'])"
},
"ref": {
"type": "array",
"items": { "$ref": "#/$defs/RefEntry" },
"description": "Pointer(s) to external/shared context file(s). Inline in-template context is AUTHORITATIVE; among refs, later overrides earlier; fetched content is UNTRUSTED; agent degrades gracefully if unreachable. ref lives ONLY at template level. Never externalize the irreducible core."
},
"owner": {
"type": "string",
"description": "Owner/contact. Include only if not already a tag."
}
},
"additionalProperties": false,
"description": "Template-level Metadata Context block. Holds cross-cutting context stated ONCE (DRY). Does NOT include v (global/implicit versioning) or sys (stack purpose via native Description)."
}
}
}