What is AWSTemplateFormatVersion in template.yaml?
This page has been translated by machine translation. View original
Introduction
Hello, I'm Shota Yamamoto.
As I've been learning AWS, I've had more opportunities to use CloudFormation.
When creating templates, I ask AI or edit existing templates, but I became curious about AWSTemplateFormatVersion, which is always present at the top.
So in this post, I'll summarize what I found out about AWSTemplateFormatVersion.
What is AWSTemplateFormatVersion
The official documentation states the following.
The AWSTemplateFormatVersion section (optional) identifies the template format version that the template conforms to. The latest template format version is 2010-09-09 and is currently the only valid value.
In other words, AWSTemplateFormatVersion is a section for declaring "which CloudFormation formatting rules this template is written according to."
It can be summarized in the following 2 points.
- It can be omitted: It's an optional section, so the template works even if you don't write it. If omitted, CloudFormation treats it as if the latest format version were specified.
- The only valid value is 2010-09-09: The format version has never been updated since it was defined on September 9, 2010.
In other words, behavior is the same whether you write it or not, and if you do write it, you can't use any value other than 2010-09-09.
Trying it out
I'll actually create stacks with various patterns and test the behavior.
Omitting the section
First is the pattern where the section is omitted. I'll create a stack with the following template.
Description: AWSTemplateFormatVersion hands-on using S3 bucket
Resources:
HandsOnBucket:
Type: AWS::S3::Bucket
Properties:
BucketName: !Sub "cfn-format-version-${AWS::AccountId}-${AWS::StackName}"
Tags:
- Key: Name
Value: cfn-format-version-handson
- Key: Project
Value: format-version-handson
Outputs:
BucketName:
Description: Created S3 bucket name
Value: !Ref HandsOnBucket
When I created it using this template, it was created without errors, just as the documentation says.
Specifying an invalid value
Next, I'll create one with a date I decided on myself.
I specified the template as follows.
AWSTemplateFormatVersion: '2026-01-01'
Description: AWSTemplateFormatVersion hands-on using S3 bucket
Resources:
HandsOnBucket:
Type: AWS::S3::Bucket
Properties:
BucketName: !Sub "cfn-format-version-${AWS::AccountId}-${AWS::StackName}"
Tags:
- Key: Name
Value: cfn-format-version-handson
- Key: Project
Value: format-version-handson
Outputs:
BucketName:
Description: Created S3 bucket name
Value: !Ref HandsOnBucket
This time, the following error occurred.
Template format error: 2026-01-01 is not a supported value forAWSTemplateFormatVersion.
The message means that a template with that date is not supported.
Without quotation marks
Finally, as a bonus, I'll also try creating it without quotation marks.
AWSTemplateFormatVersion: 2010-09-09
Description: AWSTemplateFormatVersion hands-on using S3 bucket
Resources:
HandsOnBucket:
Type: AWS::S3::Bucket
Properties:
BucketName: !Sub "cfn-format-version-${AWS::AccountId}-${AWS::StackName}"
Tags:
- Key: Name
Value: cfn-format-version-handson
- Key: Project
Value: format-version-handson
Outputs:
BucketName:
Description: Created S3 bucket name
Value: !Ref HandsOnBucket
AWSTemplateFormatVersion: 2026-01-01
Description: AWSTemplateFormatVersion hands-on using S3 bucket
Resources:
HandsOnBucket:
Type: AWS::S3::Bucket
Properties:
BucketName: !Sub "cfn-format-version-${AWS::AccountId}-${AWS::StackName}"
Tags:
- Key: Name
Value: cfn-format-version-handson
- Key: Project
Value: format-version-handson
Outputs:
BucketName:
Description: Created S3 bucket name
Value: !Ref HandsOnBucket
The result was the same here too: only the one with the mismatched date caused an error.
Should you write AWSTemplateFormatVersion
From the verification so far, we found that behavior doesn't change whether or not you write AWSTemplateFormatVersion.
So, should you include it when actually writing templates?
Since CloudFormation was made generally available in 2011, many features such as new sections and intrinsic functions have been added.
Despite that, the format version has remained 2010-09-09 and has never been updated.
The official documentation doesn't state the reason explicitly, but it's probably because all the new features so far have been added in a way that lets existing templates keep working as they are, so there was no need to raise the format version.
Therefore, there's no problem with omitting it, but I thought it's better to write it.
Most templates, including the samples in the official documentation, include AWSTemplateFormatVersion, so writing it lets you align the format with other templates.
In addition, when you open a YAML file, the first line tells you at a glance that it's a CloudFormation template, which makes it easier to identify files without reading their contents when dealing with multiple YAML files.
Conclusion
In this post, I investigated CloudFormation's AWSTemplateFormatVersion.
I had been writing it somewhat out of habit, but I was able to actually confirm that it can be omitted and that the only valid value is 2010-09-09.
Behavior is the same whether you write it or not, but from the standpoint of consistency with other templates and readability, I plan to keep writing it.
I hope this helps anyone who was curious about the same thing.
References
About Classmethod Operations Inc.
We are the operations company of the Classmethod Group.
Our specialist teams in operations, maintenance and development, support, corporate IT, and back office are a group of experts who provide everything from business outsourcing to problem solving and high-value-added services through "mechanisms" that make full use of IT and AI.
We are recruiting members for a variety of positions.
If you are interested in the culture, mechanisms, and work styles that realize both "Operational Excellence" and "working and living as yourself," please take a look at the Classmethod Operations Inc. corporate site. ※In January 2026, the company name was changed from Annotation Inc.