Schema syntax reference for AWS CloudFormation Hooks - AWS CloudFormation
Schema syntaxExample Hooks schemas

Schema syntax reference for AWS CloudFormation Hooks

This section describes the syntax of the schema that you use to develop AWS CloudFormation Hooks.

A Hook includes a Hook specification represented by a JSON schema and Hook handlers. The first step in creating a custom Hook is modeling a schema that defines the Hook, its properties, and their attributes. When you initialize a custom Hook project using the CloudFormation CLI init command, a Hook schema file is created for you. Use this schema file as a starting point for defining the shape and semantics of your custom Hook.

Schema syntax

The following schema is the structure for a Hook.

{
"typeName": "string",
    "description": "string",
    "sourceUrl": "string",
    "documentationUrl": "string",
    "definitions": {
        "definitionName": {
          . . .
        }
    },
    "typeConfiguration": {
        "properties": {
             "propertyName": {
                "description": "string",
                "type": "string",
                 . . .
            },
        },
    "required": [
        "propertyName"
         . . .
            ],
    "additionalProperties": false
    },
    "handlers": {
        "preCreate": {
            "targetNames": [
            ],
            "permissions": [
            ]
        },
        "preUpdate": {
            "targetNames": [
            ],
            "permissions": [
            ]
        },
        "preDelete": {
            "targetNames": [
            ],
            "permissions": [
            ]
        }
   },
   "additionalProperties": false
}
typeName

The unique name for your Hook. Specifies a three-part namespace for your Hook, with a recommended pattern of Organization::Service::Hook.

Note

The following organization namespaces are reserved and can't be used in your Hook type names:

  • Alexa

  • AMZN

  • Amazon

  • ASK

  • AWS

  • Custom

  • Dev

Required: Yes

Pattern: ^[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}$

Minimum: 10

Maximum: 196

description

A short description of the Hook that's displayed in the CloudFormation console.

Required: Yes

sourceUrl

The URL of the source code for the Hook, if public.

Required: No

Maximum: 4096

documentationUrl

The URL of a page providing detailed documentation for the Hook.

Required: Yes

Pattern: ^https\:\/\/[0-9a-zA-Z]([-.\w]*[0-9a-zA-Z])(\:[0-9]*)*([\?/#].*)?$

Maximum: 4096

Note

Although the Hook schema should include complete and accurate property descriptions, you can use the documentationURL property to provide users with more details, including examples, use cases, and other detailed information.

definitions

Use the definitions block to provide shared Hook property schemas.

It's considered a best practice to use the definitions section to define schema elements that can be used at multiple points in your Hook type schema. You can then use a JSON pointer to reference that element at the appropriate places in your Hook type schema.

Required: No

typeConfiguration

The definition of a Hook’s configuration data.

Required: Yes

properties

The properties of the Hook. All properties of a Hook must be expressed in the schema. Align the Hook schema properties with the Hook type configuration properties.

Note

Nested properties aren't allowed. Instead, define any nested properties in the definitions element, and use a $ref pointer to reference them in the desired property.

additionalProperties

additionalProperties must be set to false. All properties of a Hook must be expressed in the schema: arbitrary inputs aren't allowed.

Required: Yes

Valid values: false

handlers

Handlers specify the operations which can initiate the Hook defined in the schema, such as Hook invocation points. For example, a preUpdate handler is invoked before the update operations for all specified targets in the handler.

Valid values: preCreate | preUpdate | preDelete

Note

At least one value must be specified for the handler.

Important

Stack operations that result in the status of UpdateCleanup do not invoke a Hook. For example, during the following two scenarios, the Hook's preDelete handler is not invoked:

  • the stack is updated after removing one resource from the template.

  • a resource with the update type of replacement is deleted.

targetNames

A string array of type names that Hook targets. For example, if a preCreate handler has an AWS::S3::Bucket target, the Hook runs for Amazon S3 buckets during the preprovisioning phase.

  • TargetName

    Specify at least one target name for each implemented handler.

    Pattern: ^[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}$

    Minimum: 1

    Required: Yes

    Warning

    SSM SecureString and Secrets Manager dynamic references are not resolved before they are passed to Hooks.

permissions

A string array that specifies the AWS permissions needed to invoke the handler.

Required: Yes

additionalProperties

additionalProperties must be set to false. All properties of a Hook must be expressed in the schema: arbitrary inputs aren't allowed.

Required: Yes

Valid values: false

Example Hooks schemas

Example 1

The Java and the Python walkthroughs use the following code example. The following is an example structure for a Hook called mycompany-testing-mytesthook.json.

{
    "typeName":"MyCompany::Testing::MyTestHook",
    "description":"Verifies S3 bucket and SQS queues properties before create and update",
    "sourceUrl":"https://mycorp.com/my-repo.git",
    "documentationUrl":"https://mycorp.com/documentation",
    "typeConfiguration":{
        "properties":{
            "minBuckets":{
                "description":"Minimum number of compliant buckets",
                "type":"string"
            },
            "minQueues":{
                "description":"Minimum number of compliant queues",
                "type":"string"
            },
            "encryptionAlgorithm":{
                "description":"Encryption algorithm for SSE",
                "default":"AES256",
                "type":"string"
            }
        },
        "required":[
            
        ],
        "additionalProperties":false
    },
    "handlers":{
        "preCreate":{
            "targetNames":[
                "AWS::S3::Bucket",
                "AWS::SQS::Queue"
            ],
            "permissions":[
                
            ]
        },
        "preUpdate":{
            "targetNames":[
                "AWS::S3::Bucket",
                "AWS::SQS::Queue"
            ],
            "permissions":[
                
            ]
        },
        "preDelete":{
            "targetNames":[
                "AWS::S3::Bucket",
                "AWS::SQS::Queue"
            ],
            "permissions":[
                "s3:ListBucket",
                "s3:ListAllMyBuckets",
                "s3:GetEncryptionConfiguration",
                "sqs:ListQueues",
                "sqs:GetQueueAttributes",
                "sqs:GetQueueUrl"
            ]
        }
    },
    "additionalProperties":false
}

Example 2

The following example is a schema that uses the STACK and CAHNGE_SET for targetNames to target a stack template and a change set operation.

{
    "typeName":"MyCompany::Testing::MyTestHook",
    "description":"Verifies Stack and Change Set properties before create and update",
    "sourceUrl":"https://mycorp.com/my-repo.git",
    "documentationUrl":"https://mycorp.com/documentation",
    "typeConfiguration":{
        "properties":{
            "minBuckets":{
                "description":"Minimum number of compliant buckets",
                "type":"string"
            },
            "minQueues":{
                "description":"Minimum number of compliant queues",
                "type":"string"
            },
            "encryptionAlgorithm":{
                "description":"Encryption algorithm for SSE",
                "default":"AES256",
                "type":"string"
            }
        },
        "required":[
        ],
        "additionalProperties":false
    },
    "handlers":{
        "preCreate":{
            "targetNames":[
                "STACK",
                "CHANGE_SET"
            ],
            "permissions":[  
            ]
        },
        "preUpdate":{
            "targetNames":[
                "STACK"
            ],
            "permissions":[
            ]
        },
        "preDelete":{
            "targetNames":[
                "STACK"
            ],
            "permissions":[
                
            ]
        }
    },
    "additionalProperties":false
}