{"id":1919,"library":"aws-cdk-cloud-assembly-schema","title":"AWS CDK Cloud Assembly Schema","description":"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.","status":"active","version":"53.14.0","language":"en","source_language":"en","source_url":"https://github.com/aws/aws-cdk-cli","tags":["aws","cdk","cloud","schema","infrastructure-as-code","iac"],"install":[{"cmd":"pip install aws-cdk-cloud-assembly-schema","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.9 or later for compatibility with `aws-cdk-lib`.","package":"python","optional":false}],"imports":[{"note":"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.","symbol":"AssetManifest","correct":"from aws_cdk.cloud_assembly_schema import AssetManifest"}],"quickstart":{"code":"import os\nimport aws_cdk as cdk\nimport aws_cdk.aws_s3 as s3\nfrom constructs import Construct\n\nclass MyCdkStack(cdk.Stack):\n    def __init__(self, scope: Construct, id: str, **kwargs) -> None:\n        super().__init__(scope, id, **kwargs)\n\n        # Create an S3 bucket\n        s3.Bucket(self, \"MyBucket\",\n            versioned=True,\n            removal_policy=cdk.RemovalPolicy.DESTROY,\n            auto_delete_objects=True\n        )\n\napp = cdk.App()\nMyCdkStack(app, \"MyFirstCdkStack\",\n    env=cdk.Environment(\n        account=os.environ.get(\"CDK_DEFAULT_ACCOUNT\", \"\"),\n        region=os.environ.get(\"CDK_DEFAULT_REGION\", \"eu-west-1\")\n    )\n)\napp.synth()\n","lang":"python","description":"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."},"warnings":[{"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).","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}