Resource type schema - Extension development for CloudFormation
SyntaxProperties
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Resource type schema

To be considered valid, your resource type's schema must adhere to the Resource provider definition schema. This meta-schema provides a means of validating your resource specification during resource development.

Syntax

Below is the structure for a typical resource type schema. For the complete meta-schema definition, see the Resource Provider Definition Schema on GitHub.

{
    "typeName": "string",
    "description": "string",
    "sourceUrl": "string",
    "documentationUrl": "string",
    "replacementStrategy": "create_then_delete" | "delete_then_create",
    "taggable": true | false,
    "tagging": {
      "taggable": true | false,
      "tagOnCreate": true | false,
      "tagUpdatable": true | false,
      "cloudFormationSystemTags": true | false,
      "tagProperty": "json-pointer",
    },
    "definitions": {
        "definitionName": {
          . . .
        }
    },
    "properties": {
         "propertyName": {
            "description": "string",
            "type": "string",
             . . . 
            },
        },
    },
    "required": [
        "propertyName"
    ],
    "propertyTransform": {
      { 
        "/properties/propertyName": "transform"
      }  
    },
    "handlers": {
        "create": {
            "permissions": [
                "permission"
            ],
            "timeoutInMinutes": integer
        },
        "read": {
            "permissions": [
                "permission"
            ],
            "timeoutInMinutes": integer
        },
        "update": {
            "permissions": [
                "permission"
            ],
            "timeoutInMinutes": integer
        },
        "delete": {
            "permissions": [
                "permission"
            ],
            "timeoutInMinutes": integer
        },
        "list": {
            "permissions": [
                "permission"
            ],
            "timeoutInMinutes": integer
        }
    },
    "readOnlyProperties": [
        "/properties/propertyName"
    ],
    "writeOnlyProperties": [
        "/properties/propertyName"
    ],
    "conditionalCreateOnlyProperties": [
        "/properties/propertyName"
    ],
    "nonPublicProperties": [
        "/properties/propertyName"
    ],
    "nonPublicDefinitions": [
        "/properties/propertyName"
    ],
    "createOnlyProperties": [
        "/properties/propertyName"
    ],
    "deprecatedProperties": [
        "/properties/propertyName"
    ],
    "primaryIdentifier": [
        "/properties/propertyName"
    ],
    "additionalIdentifiers": [
        [ "/properties/propertyName" ]
    ],
    "typeConfiguration": {
      . . . 
    },
    "resourceLink": {
      "templateUri": "string",
      "mappings": "json-pointer"
    },
}

Properties

Below are the properties for a typical resource type schema.

typeName

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

Note

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

  • Alexa

  • AMZN

  • Amazon

  • ASK

  • Amazon

  • Custom

  • Dev

Required: Yes

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

description

A short description of the resource. This will be displayed in the Amazon CloudFormation console.

Required: Yes

sourceUrl

The URL of the source code for this resource, if public.

documentationUrl

The URL of a page providing detailed documentation for this resource.

Note

While the resource schema itself should include complete and accurate property descriptions, the documentationURL property enables you to provide users with documentation that describes and explains the resource in more detail, including examples, use cases, and other detailed information.

replacementStrategy

The order of replacement when a resource update necessitates replacing the existing resource with a new resource. For example, updating a resource property that is listed in createonlyProperties results in a new resource being created to replace the existing resource.

By default, when updating a resource that requires replacement, Amazon CloudFormation first creates the new resource, and then delete the old resource. However, some resources can only exist one at a time in a given account/region. For these resources, this attribute can be used to instruct Amazon CloudFormation to delete the existing resource before creating its replacement.

For more information on how resources are updated, see Update behaviors of stack resources in the Amazon CloudFormation User Guide.

Valid values: create_then_delete | delete_then_create

taggable

Deprecated. Use the tagging element instead.

tagging

Contains properties that specify the resource type's support for tags.

If your resource type does not support tagging, you must set taggable to false or your resource type will fail contract testing.

taggable

Whether this resource type supports tagging.

If your resource type does not support tagging, you must set taggable to false or your resource type will fail contract testing.

The default is true.

tagOnCreate

Whether this resource type supports tagging resources upon creation.

The default is true.

tagUpdatable

Whether this resource type supports updating tags during resource update operations.

The default is true.

cloudFormationSystemTags

Whether this resource type supports CloudFormation system tags.

The default is true.

tagProperty

A reference to where you have defined the Tags property in this resource type schema.

The default is /properties/Tags.

definitions

Use the definitions block to provide shared resource property schemas.

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

properties

The properties of the resource.

All properties of a resource must be expressed in the schema. Arbitrary inputs aren't allowed. A resource must contain at least one property.

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

Required: Yes

propertyName
insertionOrder

For properties of type array, set to true to specify that the order in which array items are specified must be honored, and that changing the order of the array will indicate a change in the property.

The default is true.

dependencies

Any properties that are required if this property is specified.

patternProperties

Use to specify a specification for key-value pairs.

"type": "object",
"propertyNames": {
   "format": "regex"
}
properties

Minimum: 1

patternProperties

Pattern: ^[A-Za-z0-9]{1,64}$

Specifies a pattern that properties must match to be valid.

allOf

The property must contain all of the data structures define here.

Contains a single schema. A list of schemas is not allowed.

Minimum: 1

anyOf

The property can contain any number of the data structures define here.

Contains a single schema. A list of schemas is not allowed.

Minimum: 1

oneOf

The property must contain only one of the data structures define here.

Contains a single schema. A list of schemas is not allowed.

Minimum: 1

items

For properties of type array, defines the data structure of each array item.

Contains a single schema. A list of schemas is not allowed.

In addition, the following elements, defined in draft-07 of the JSON Schema, are allowed in the properties object:

  • $ref

  • $comment

  • title

  • description

  • examples

  • default

  • multipleOf

  • maximum

  • exclusiveMaximum

  • minimum

  • exclusiveMinimum

  • minLength

  • pattern

  • maxItems

  • minItems

  • uniqueItems

  • contains

  • maxProperties

  • required

  • const

  • enum

  • type

  • format

propertyTransform

One or more transforms to apply to the property value when comparing for drift. For more information, see Preventing false drift detection results for resource types.

remote

Reserved for CloudFormation use.

readOnlyProperties

Resource properties that can be returned by a read or list request, but can't be set by the user.

Type: List of JSON pointers

writeOnlyProperties

Resource properties that can be specified by the user, but can't be returned by a read or list request. Write-only properties are often used to contain passwords, secrets, or other sensitive data.

Type: List of JSON pointers

conditionalCreateOnlyProperties

A list of JSON pointers for properties that can only be updated under certain conditions. For example, you can upgrade the engine version of an RDS DBInstance but you cannot downgrade it. When updating this property for a resource in a CloudFormation stack, the resource will be replaced if it cannot be updated.

Type: List of JSON pointers

nonPublicProperties

A list of JSON pointers for properties that are hidden. These properties will still be used but will not be visible

Type: List of JSON pointers

nonPublicDefinitions

A list of JSON pointers for definitions that are hidden. These definitions will still be used but will not be visible

Type: List of JSON pointers

createOnlyProperties

Resource properties that can be specified by the user only during resource creation.

Note

Any property not explicitly listed in the createOnlyProperties element can be specified by the user during a resource update operation.

Type: List of JSON pointers

deprecatedProperties

Resource properties that have been deprecated by the underlying service provider. These properties are still accepted in create and update operations. However they may be ignored, or converted to a consistent model on application. Deprecated properties are not guaranteed to be returned by read operations.

Type: List of JSON pointers

primaryIdentifier

The uniquely identifier for an instance of this resource type. An identifier is a non-zero-length list of JSON pointers to properties that form a single key. An identifier can be a single or multiple properties to support composite-key identifiers.

Type: List of JSON pointers

Required: Yes

additionalIdentifiers

An optional list of lists of supplementary identifiers, each of which uniquely identifies an instance of this resource type. An identifier can be a single property, or multiple properties to construct composite-key identifiers.

Type: List of lists

Minimum: 1

handlers

Specifies the provisioning operations which can be performed on this resource type. The handlers specified determine what provisioning actions CloudFormation takes with respect to the resource during various stack operations.

  • If the resource type doesn't contain create, read, and delete handlers, CloudFormation can't actually provision the resource.

  • If the resource type doesn't contain an update handler, CloudFormation can't update the resource during stack update operations, and will instead replace it.

If your resource type calls Amazon APIs in any of its handlers, you must create an IAM execution role that includes the necessary permissions to call those Amazon APIs, and provision that execution role in your account. For more information, see Accessing Amazon APIs from a Resource Type.

create
permissions

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

You must specify at least one permission for each handler.

Required: Yes

timeoutInMinutes

An integer specifying the timeout for the entire operation to be interpreted by the invoker of the handler, in minutes.

Minimum: 2

Maximum: 2160

Default: 120

Required: No

read
permissions

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

You must specify at least one permission for each handler.

Required: Yes

timeoutInMinutes

An integer specifying the timeout for the entire operation to be interpreted by the invoker of the handler, in minutes.

Minimum: 2

Maximum: 2160

Default: 120

Required: No

update
permissions

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

You must specify at least one permission for each handler.

Required: Yes

timeoutInMinutes

An integer specifying the timeout for the entire operation to be interpreted by the invoker of the handler, in minutes.

Minimum: 2

Maximum: 2160

Default: 120

Required: No

delete
permissions

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

You must specify at least one permission for each handler.

Required: Yes

timeoutInMinutes

An integer specifying the timeout for the entire operation to be interpreted by the invoker of the handler, in minutes.

Minimum: 2

Maximum: 2160

Default: 120

Required: No

list

The list handler must at least return the resource's primary identifier.

permissions

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

You must specify at least one permission for each handler.

Required: Yes

timeoutInMinutes

An integer specifying the timeout for the entire operation to be interpreted by the invoker of the handler, in minutes.

Minimum: 2

Maximum: 2160

Default: 120

Required: No

allOf

The resource must contain all of the data structures defined here.

Minimum: 1

anyOf

The resource can contain any number of the data structures define here.

Minimum: 1

oneOf

The resource must contain only one of the data structures define here.

Minimum: 1

A template-able link to a resource instance. External service links must be absolute, HTTPS URIs.

Required: Yes

Pattern: ^(/|https:)

Required: Yes

Type: List of JSON pointers

typeConfiguration

A type configuration schema that defines any properties that the user must specify for all instances of the extension in a given account and Region. For example, if your extension needs to access a third-party web service, you can include a configuration schema for the user to specify their credentials for that service.

Your configuration definition must validate against the provider configuration definition meta-schema.

When the user specifices a resource, they can sets the configuration. CloudFormation validates it against the configuration definition, and then saves this information at the Region level. From then on, CloudFormation can access that configuration schema during operations involving any instances of that extension in the Region. Configurations are available to CloudFormation during all resource operations, including read and list events that don't explicitly involve a stack template.

The CloudFormation property name is reserved, and cannot be used to define any properties in your configuration definition.

For more information, see Defining the account-level configuration of an extension.