AWS CDK Cloud Assembly Schema

53.14.0 · active · verified Thu Apr 09

The `aws-cdk-cloud-assembly-schema` Python library defines the schema for the Cloud Assembly, which is the output of the AWS CDK's synthesis operation (e.g., `cdk synth`). This schema, primarily found in `manifest.json`, acts as the communication protocol between the AWS CDK framework (libraries) and the AWS CDK CLI (tools), providing instructions for deploying infrastructure. The library is actively maintained with frequent updates, usually in sync with the broader AWS CDK CLI project, currently at version 53.14.0.

Warnings

breaking Cloud Assembly Schema Version Mismatch: A common breaking error occurs when the AWS CDK CLI version is incompatible with the `aws-cdk-lib` version used by your application, leading to a 'Cloud assembly schema version mismatch' error. This happens because the schema version is strictly tied to the CDK libraries.
Fix: Always upgrade your AWS CDK CLI (globally installed `cdk` command) to the latest version to ensure compatibility with your `aws-cdk-lib` version. This is the recommended solution over downgrading libraries. Use `npm update -g aws-cdk` or `pip install --upgrade aws-cdk` (if using pip for CLI).
gotcha Intended Use as Internal Protocol: This library primarily defines the internal communication protocol (the Cloud Assembly manifest) between the AWS CDK framework and the AWS CDK CLI. It is generally not intended for direct use by end-developers building AWS CDK applications to define infrastructure, unlike `aws-cdk-lib`.
Fix: For defining AWS infrastructure programmatically, use `aws-cdk-lib` which provides higher-level constructs and a more application-centric API. Reserve direct interaction with `aws-cdk-cloud-assembly-schema` for advanced scenarios like building custom CDK tooling or validating generated Cloud Assemblies.
gotcha Strict Major Versioning Policy: The `aws-cdk-cloud-assembly-schema` follows semantic versioning with a critical nuance: *any* change to the schema, even if it doesn't strictly break JSON schema validation, results in a major version bump. This is because every instruction in the manifest is crucial for correct deployment behavior.
Fix: When building tools that consume cloud assemblies, always consider the major version of the schema. Consumers should reject cloud assemblies with a major version higher than what they explicitly support to guarantee deployment integrity, even if schema validation appears to pass.

Install

pip install aws-cdk-cloud-assembly-schema Install latest version

Imports

AssetManifest
```
from aws_cdk.cloud_assembly_schema import AssetManifest
```
Direct imports from this library are uncommon for typical CDK application development, as it primarily defines a protocol schema. It's mostly used internally by the CDK framework and CLI, or for advanced programmatic manipulation/validation of cloud assembly artifacts.

Quickstart

This quickstart demonstrates a basic AWS CDK application that creates an S3 bucket. While `aws-cdk-cloud-assembly-schema` is not directly imported here, running `cdk synth` on this application will produce a Cloud Assembly (including `manifest.json`) that conforms to the schema defined by this library. This illustrates the library's role as an underlying protocol definition rather than a direct development dependency for resource creation.

import os
import aws_cdk as cdk
import aws_cdk.aws_s3 as s3
from constructs import Construct

class MyCdkStack(cdk.Stack):
    def __init__(self, scope: Construct, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)

        # Create an S3 bucket
        s3.Bucket(self, "MyBucket",
            versioned=True,
            removal_policy=cdk.RemovalPolicy.DESTROY,
            auto_delete_objects=True
        )

app = cdk.App()
MyCdkStack(app, "MyFirstCdkStack",
    env=cdk.Environment(
        account=os.environ.get("CDK_DEFAULT_ACCOUNT", ""),
        region=os.environ.get("CDK_DEFAULT_REGION", "eu-west-1")
    )
)
app.synth()

view raw JSON →