Problem

I have been supporting the Terraform AWSCC provider from the last couple of years documenting examples, contributing with small code changes and triaging issues with the provider usage. Some of the key themess I have found are:

  • A valid json schema doesn’t always mean they would translate well with the provider.
  • The provider has to take some specific steps to support some of the terraform workflows to ensure there is no drift when there isn’t one supposed to be.
  • AWS Schema updates aren’t versioned via some metadata available via public APIs, though the AWS console shows a specific LastUpdated date which might be on an internal API. ( wishlist item to have this be public similar to private extenstions)

The existing AWS CloudFormation APIs (DescribeType and ListTypes) provide current schema versions and metadata like creation dates, but they don’t preserve historical versions or tell you when schemas actually changed. While the AWS console shows a “last updated” date for resource types, this information doesn’t appear to be available through the API. For example:

aws cloudformation describe-type --type RESOURCE --type-name "AWS::S3::Bucket"

This returns the current schema and metadata like:

{
    "Arn": "arn:aws:cloudformation:us-east-1::type/resource/AWS-S3-Bucket",
    "TypeName": "AWS::S3::Bucket",
    "IsDefaultVersion": true,
    "TimeCreated": "2021-09-08T21:54:30.601000+00:00",
    "Schema": "{\"typeName\": \"AWS::S3::Bucket\", ...}"
}

But there’s no history of when it changed or what the previous versions looked like. This makes it impossible to correlate provider issues with specific schema updates especially for a partner like HashiCorp or Pulumi.

A Possible Workaround

This is purely personal pet project born out of a limitation as I couldn’t identify when CloudFormation schema versions actually changed, which made troubleshooting Terraform AWSCC provider issues a nightmare at times.

Introducing cfn-schema-versioning.

The intention of the repo are a few things :

  • Schema versioning: Preserve every version of each CloudFormation schema in git history
  • Change traceability: Git diff to show exactly what changed between schema versions
  • Timeline tracking: Approximate metadata tracking of when changes were detected. This is approximate as it really depends on when the schema was updated and published and we ran the GH workflows.
  • AWS metadata: Captures additional AWS-provided metadata like creation time and deprecation status

How It Works

The repository runs automated monitoring twice weekly via GitHub Actions:

  1. Scheduled fetch: Runs on Mondays and Wednesdays at 6 AM UTC to fetch all AWS resource type schemas
  2. Schema comparison: Compares new schemas with existing files to detect actual changes
  3. Selective updates: Only commits and updates timestamps when schemas actually change
  4. Git history: Full change history preserved in git commits with timestamps

The version_metadata.json file tracks key information for each resource type:

{
  "AWS::S3::Bucket": {
    "deprecation_status": "LIVE",
    "first_seen": "2026-01-19T02:02:20.407855",
    "last_updated": "2026-01-19T02:16:06.407687", 
    "time_created": "2020-01-13T23:53:35.925000+00:00"
  }
}

When resource types are removed from AWS, they’re moved to removed_schemas.json to preserve the historical record. This approach selfishly helps me (and hopefully others) troubleshoot when CloudFormation schema changes break things in the Terraform AWSCC provider or when resource types get removed. Hopefully we get the updated date in a schema with schema version references in the CloudControl API and this repo can be archived :)