From Cloudformation documentation, tags should be expressed as arrays of Key/Value

[gautaz]

CloudFormation Lint Version

cfn-lint 1.10.0

What operating system are you using?

Linux hepao 6.6.49-NixOS SMP PREEMPT_DYNAMIC Wed Sep 4 11:28:31 UTC 2024 x86_64 GNU/Linux

Describe the bug

Looking at CloudFormation documentation regarding tags on, for instance, Batch job definitions, a template for this type of resource would be (from my understanding):

AWSTemplateFormatVersion: '2010-09-09'
Resources:
  TesJobDefinition:
    Properties:
      Tags:
        - Key: key
          Value: value
      Type: Container
    Type: AWS::Batch::JobDefinition

But cfn-lint validation fails:

❯ cfn-lint test.yaml
E3012 [{'Key': 'key', 'Value': 'value'}] is not of type 'object', 'string'
/workspace/test.yaml:5:7

Expected behavior

The expectation would be that the example template is valid.

Nevertheless, I must say that I find the Cloudformation documentation on this point particularly awkward as I would have expected an object to express a list of tags.
As a matter of fact, this is what cfn-lint currently considers as valid:

AWSTemplateFormatVersion: '2010-09-09'
Resources:
  TesJobDefinition:
    Properties:
      Tags:
        key: value
      Type: Container
    Type: AWS::Batch::JobDefinition

But as the current CloudFormation documentation goes, other tools like cloudtools/troposphere seem to follow it and generate tags as arrays of Key/Value.

Looking at PRs related to this, I have stumbled upon #3437 which seems to say that the Cloudformation specification says "object" and the documentation says "array".
As troposphere also uses the Cloudformation specification to generate most of its code, I am rather puzzled...

So, which one is right?
And where is the source of truth if not the Cloudformation documentation?

Reproduction template

AWSTemplateFormatVersion: '2010-09-09'
Resources:
  TesJobDefinition:
    Properties:
      Tags:
        - Key: key
          Value: value
      Type: Container
    Type: AWS::Batch::JobDefinition

[kddejong]

If you use your template against the service early validation will fail with:

Property validation failure: [Value of property {/Tags} does not match type {Map}]

From this I think you need to follow the Tag structure of mapping like Key: Value

[gautaz]

Hello @kddejong, thanks for your input.

I am not sure about what you call the "service early validation", I suppose this is related to the CLI command aws cloudformation validate-template.

So I have tested it with the following template:

AWSTemplateFormatVersion: '2010-09-09'
Resources:
  TesJobDefinition:
    Properties:
      Tags:
        - Key: key
          Value: value
      Type: Container
    Type: AWS::Batch::JobDefinition

And the result seems to be a success (0 status code):

❯ aws cloudformation validate-template --template-body file://test.yaml
{
    "Parameters": []
}

Can you give me a bit more details so that I am sure that we are talking about the same validation process?

Also the comments I have highlighted in the issue description make the distinction between what is said in the Clouformation documentation and the Cloudformation specification. Where is this specification available if this is not the documentation?

[kddejong]

Early validation is where the property values are validated against the provider schema

https://aws.amazon.com/about-aws/whats-new/2024/03/aws-cloudformation-new-validation-checks-stack-operations/

To use this feature you have to create a stack with that template.

[gautaz]

OK, so looking at the provider schema (eu-west-3 in my case) for AWS::Batch::JobDefinition, the property Tags is described this way:

    "Tags" : {
      "type" : "object"
    }

Now I understand your point, so the issue is troposphere generating an array of Key/Value instead of a dictionary or me badly using troposhere.
Thanks @kddejong for the clarification, I can close the issue.