# Cloud Assembly Schema

This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.

## Cloud Assembly

The _Cloud Assembly_ is the output of the synthesis operation. It is produced as part of the
[`cdk synth`](https://github.com/aws/aws-cdk/tree/main/packages/aws-cdk#cdk-synthesize)
command, or the [`app.synth()`](https://github.com/aws/aws-cdk/blob/main/packages/@aws-cdk/core/lib/app.ts#L135) method invocation.

Its essentially a set of files and directories, one of which is the `manifest.json` file. It defines the set of instructions that are
needed in order to deploy the assembly directory.

> For example, when `cdk deploy` is executed, the CLI reads this file and performs its instructions:
>
> - Build container images.
> - Upload assets.
> - Deploy CloudFormation templates.

Therefore, the assembly is how the CDK class library and CDK CLI (or any other consumer) communicate. To ensure compatibility
between the assembly and its consumers, we treat the manifest file as a well defined, versioned schema.

## Schema

This module contains the typescript structs that comprise the `manifest.json` file, as well as the
generated _json-schema_.

## Versioning

The schema version is specified my the major version of the package release. It follows semantic versioning, but with a small twist.

When we add instructions to the assembly, they are reflected in the manifest file and the _json-schema_ accordingly.
Every such instruction, is crucial for ensuring the correct deployment behavior. This means that to properly deploy a cloud assembly,
consumers must be aware of every such instruction modification.

For this reason, every change to the schema, even though it might not strictly break validation of the _json-schema_ format,
is considered `major` version bump. All changes that do not impact the schema are considered a `minor` version bump.

## How to consume

If you'd like to consume the schema file in order to do validations on `manifest.json` files,
simply download it from this repo and run it against standard _json-schema_ validators, such as [jsonschema](https://www.npmjs.com/package/jsonschema).

Consumers must take into account the `major` version of the schema they are consuming. They should reject cloud assemblies
with a `major` version that is higher than what they expect. While schema validation might pass on such assemblies, the deployment integrity
cannot be guaranteed because some instructions will be ignored.

> For example, if your consumer was built when the schema version was 2.0.0, you should reject deploying cloud assemblies with a
> manifest version of 3.0.0.

## Contributing

The source code for this file has been moved to CDKLabs.

See [Contribution Guide](https://github.com/cdklabs/cloud-assembly-schema/blob/main/CONTRIBUTING.md)

## Types

| Name | Kind | Summary |
| --- | --- | --- |
| [`AmiContextQuery`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.AmiContextQuery) | Struct | Query to AMI context provider. |
| [`ArtifactManifest`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.ArtifactManifest) | Struct | A manifest for a single artifact within the cloud assembly. |
| [`ArtifactMetadataEntryType`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.ArtifactMetadataEntryType) | Enum | Type of artifact metadata entry. |
| [`ArtifactType`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.ArtifactType) | Enum | Type of cloud artifact. |
| [`AssemblyManifest`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.AssemblyManifest) | Struct | A manifest which describes the cloud assembly. |
| [`AssetManifest`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.AssetManifest) | Struct | Definitions for the asset manifest. |
| [`AssetManifestOptions`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.AssetManifestOptions) | Struct | Configuration options for the Asset Manifest. |
| [`AssetManifestProperties`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.AssetManifestProperties) | Struct | Artifact properties for the Asset Manifest. |
| [`AvailabilityZonesContextQuery`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.AvailabilityZonesContextQuery) | Struct | Query to availability zone context provider. |
| [`AwsCloudFormationStackProperties`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.AwsCloudFormationStackProperties) | Struct | Artifact properties for CloudFormation stacks. |
| [`AwsDestination`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.AwsDestination) | Struct | Destination for assets that need to be uploaded to AWS. |
| [`BootstrapRole`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.BootstrapRole) | Struct | Information needed to access an IAM role created as part of the bootstrap process. |
| [`CcApiContextQuery`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.CcApiContextQuery) | Struct | Query input for lookup up CloudFormation resources using CC API. |
| [`CdkCommand`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.CdkCommand) | Struct | Represents a cdk command i.e. `synth`, `deploy`, & `destroy`. |
| [`CdkCommands`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.CdkCommands) | Struct | Options for specific cdk commands that are run as part of the integration test workflow. |
| [`CloudFormationResourceJson`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.CloudFormationResourceJson) | Struct | A node in the construct creation stack trace. |
| [`ContainerImageAssetCacheOption`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.ContainerImageAssetCacheOption) | Struct | Options for configuring the Docker cache backend. |
| [`ContainerImageAssetMetadataEntry`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.ContainerImageAssetMetadataEntry) | Struct | Metadata Entry spec for container images. |
| [`ContextLookupRoleOptions`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.ContextLookupRoleOptions) | Struct | Options for context lookup roles. |
| [`ContextProvider`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.ContextProvider) | Enum | Identifier for the context provider. |
| [`DefaultCdkOptions`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.DefaultCdkOptions) | Struct | Default CDK CLI options that apply to all commands. |
| [`DeployCommand`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.DeployCommand) | Struct | Represents a cdk deploy command. |
| [`DeployOptions`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.DeployOptions) | Struct | Options to use with cdk deploy. |
| [`DestroyCommand`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.DestroyCommand) | Struct | Represents a cdk destroy command. |
| [`DestroyOptions`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.DestroyOptions) | Struct | Options to use with cdk destroy. |
| [`DockerCacheOption`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.DockerCacheOption) | Struct | Options for configuring the Docker cache backend. |
| [`DockerImageAsset`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.DockerImageAsset) | Struct | A file asset. |
| [`DockerImageDestination`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.DockerImageDestination) | Struct | Where to publish docker images. |
| [`DockerImageSource`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.DockerImageSource) | Struct | Properties for how to produce a Docker image from a source. |
| [`EndpointServiceAvailabilityZonesContextQuery`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.EndpointServiceAvailabilityZonesContextQuery) | Struct | Query to endpoint service context provider. |
| [`FeatureFlag`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.FeatureFlag) | Struct | A single feature flag. |
| [`FeatureFlagReportProperties`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.FeatureFlagReportProperties) | Struct | Artifact properties for a feature flag report. |
| [`FileAsset`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.FileAsset) | Struct | A file asset. |
| [`FileAssetMetadataEntry`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.FileAssetMetadataEntry) | Struct | Metadata Entry spec for files. |
| [`FileAssetPackaging`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.FileAssetPackaging) | Enum | Packaging strategy for file assets. |
| [`FileDestination`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.FileDestination) | Struct | Where in S3 a file asset needs to be published. |
| [`FileSource`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.FileSource) | Struct | Describe the source of a file asset. |
| [`Hooks`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.Hooks) | Struct | Commands to run at predefined points during the integration test workflow. |
| [`HostedZoneContextQuery`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.HostedZoneContextQuery) | Struct | Query to hosted zone context provider. |
| [`ICloudAssembly`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.ICloudAssembly) | Interface | Interoperable representation of a deployable cloud application. |
| [`IntegManifest`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.IntegManifest) | Struct | Definitions for the integration testing manifest. |
| [`KeyContextQuery`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.KeyContextQuery) | Struct | Query input for looking up a KMS Key. |
| [`LoadBalancerContextQuery`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.LoadBalancerContextQuery) | Struct | Query input for looking up a load balancer. |
| [`LoadBalancerFilter`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.LoadBalancerFilter) | Struct | Filters for selecting load balancers. |
| [`LoadBalancerListenerContextQuery`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.LoadBalancerListenerContextQuery) | Struct | Query input for looking up a load balancer listener. |
| [`LoadBalancerListenerProtocol`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.LoadBalancerListenerProtocol) | Enum | The protocol for connections from clients to the load balancer. |
| [`LoadBalancerType`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.LoadBalancerType) | Enum | Type of load balancer. |
| [`LoadManifestOptions`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.LoadManifestOptions) | Struct | Options for the loadManifest operation. |
| [`Manifest`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.Manifest) | Class | Protocol utility class. |
| [`MetadataEntry`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.MetadataEntry) | Struct | A metadata entry in a cloud assembly artifact. |
| [`MissingContext`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.MissingContext) | Struct | Represents a missing piece of context. |
| [`NestedCloudAssemblyProperties`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.NestedCloudAssemblyProperties) | Struct | Artifact properties for nested cloud assemblies. |
| [`PluginContextQuery`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.PluginContextQuery) | Struct | Query input for plugins. |
| [`PluginReportJson`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.PluginReportJson) | Struct | A report from a single validation plugin. |
| [`PolicyValidationReportJson`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.PolicyValidationReportJson) | Struct | The top-level structure of the policy validation report file. |
| [`PolicyViolationJson`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.PolicyViolationJson) | Struct | A single policy violation found by a validation plugin. |
| [`PropertyMutationMetadataEntry`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.PropertyMutationMetadataEntry) | Struct | Metadata type of a PropertyMutation. |
| [`RequireApproval`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.RequireApproval) | Enum | Specify what changes require manual approval. |
| [`RuntimeInfo`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.RuntimeInfo) | Struct | Information about the application's runtime components. |
| [`SecurityGroupContextQuery`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.SecurityGroupContextQuery) | Struct | Query input for looking up a security group. |
| [`SSMParameterContextQuery`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.SSMParameterContextQuery) | Struct | Query to SSM Parameter Context Provider. |
| [`SuppressedViolationJson`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.SuppressedViolationJson) | Struct | A violation that was acknowledged/suppressed and excluded from the active violation set. |
| [`Tag`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.Tag) | Struct | Metadata Entry spec for stack tag. |
| [`TestCase`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.TestCase) | Struct | Represents an integration test case. |
| [`TestOptions`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.TestOptions) | Struct | The set of options to control the workflow of the test runner. |
| [`TreeArtifactProperties`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.TreeArtifactProperties) | Struct | Artifact properties for the Construct Tree Artifact. |
| [`UnconfiguredBehavesLike`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.UnconfiguredBehavesLike) | Struct |  |
| [`ViolatingConstructJson`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.ViolatingConstructJson) | Struct | A construct that violated a policy rule. |
| [`VpcContextQuery`](/v2/docs/aws-cdk-lib.cloud_assembly_schema.VpcContextQuery) | Struct | Query input for looking up a VPC. |