Resource Provider Schema - CloudFormation Command Line Interface
SyntaxPropertiesHow to Specify a Property as Dependent on Another How to Define Nested PropertiesAdvanced: How to Encapsulate Complex Logic
AWS services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with AWS services in China.

Resource Provider Schema

In order to be considered valid, your resource provider'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 provider schema. For the complete meta-schema definition, see the Resource Provider Definition Schema on GitHub. 

{
    "typeName": "string",
    "description": "string",
    "sourceUrl": "string",
    "documentationUrl": "string",
    "definitions": {
        "definitionName": {
          . . .
        }
    },
    "properties": {
         "propertyName": {
            "description": "string",
            "type": "string",
             . . . 
        },
 
        },
    },
    "required": [
        "propertyName"
    ],
    "readOnlyProperties": [
        "/properties/propertyName"
    ],
    "writeOnlyProperties": [
        "/properties/propertyName"
    ],
    "primaryIdentifier": [
        "/properties/propertyName"
    ],
    "createOnlyProperties": [
        "/properties/propertyName"
    ],
    "deprecatedProperties": [
        "/properties/propertyName"
    ],
    "additionalIdentifiers": [
        [
            "/properties/propertyName"
        ]
    ],
    "handlers": {
        "create": {
            "permissions": [
                "permission"
            ]
        },
        "read": {
            "permissions": [
                "permission"
            ]
        },
        "update": {
            "permissions": [
                "permission"
            ]
        },
        "delete": {
            "permissions": [
                "permission"
            ]
        },
        "list": {
            "permissions": [
                "permission"
            ]
        }
    }
}

Properties

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 cannot be used in your resource 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}$

description

A short description of the resource. This will be displayed in the AWS 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.

definitions

Use the definitions block to provide shared resource property schemas.

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

properties

The properties of the resource.

All properties of a resource must be expressed in the schema. Arbitrary inputs are not 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 false.

readOnly

Reserved for CloudFormation use.

writeOnly

Reserved for CloudFormation use.

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

  • exclusiveMinimum

  • minLength

  • pattern

  • maxItems

  • minItems

  • uniqueItems

  • contains

  • maxProperties

  • maxProperties

  • required

  • const

  • enum

  • type

  • format

remote

Reserved for CloudFormation use.

readOnlyProperties

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

Type: List of JSON pointers

writeOnlyProperties

Resource properties that can be specified by the user, but cannot 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

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 provider. 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 supplementary identifiers, each of which uniquely identifies an instance of this resource provider. An identifier is a non-zero-length list of JSON pointers to properties that form a single key. An identifier can be a single property, or multiple properties to construct composite-key identifiers.

Type: List of JSON pointers

Minimum: 1

handlers

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

  • If the resource provider does not contain create, read, and delete handlers, CloudFormation cannot actually provision the resource.

  • If the resource provider does not contain an update handler, CloudFormation cannot update the resource during stack update operations, and will instead replace it.

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

create
permissions

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

You must specify at least one permission for each handler.

Required: Yes

read
permissions

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

You must specify at least one permission for each handler.

Required: Yes

update
permissions

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

You must specify at least one permission for each handler.

Required: Yes

delete
permissions

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

You must specify at least one permission for each handler.

Required: Yes

list

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

permissions

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

You must specify at least one permission for each handler.

Required: Yes

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

In addition, the following element, defined in draft-07 of the JSON Schema, is allowed:

  • required

How to Specify a Property as Dependent on Another

Use the dependencies element to specify if a property is required in order for another property to be specified. In the following example, if the user specifies a value for the ResponseCode property, they must also specify a value for ResponsePagePath, and vice versa. (Note that, as a best practice, this is also called out in the description of each property.) 

"properties": {
"CustomErrorResponse": {
    "additionalProperties": false,
    "dependencies": {
        "ResponseCode": [
            "ResponsePagePath"
        ],
        "ResponsePagePath": [
            "ResponseCode"
        ]
    },
    "properties": {
        "ResponseCode": {
            "description": "The HTTP status code that you want CloudFront to return to the viewer along with the custom error page. If you specify a value for ResponseCode, you must also specify a value for ResponsePagePath.",
            "type": "integer"
        },
        "ResponsePagePath": {
            "description": "The path to the custom error page that you want CloudFront to return to a viewer when your origin returns the HTTP status code specified by ErrorCode. If you specify a value for ResponsePagePath, you must also specify a value for ResponseCode.",
            "type": "string"
        }
        . . . 
    },
    "type": "object" 
},
},
. . .

How to Define Nested Properties

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

For example, define the reused element in the definitions section: 

"definitions": {
    "AccountId": {
        "pattern": "^[0-9]{12}$",
        "type": "string"
    },
    . . . 
},
. . .

And then reference that definition where appropriate:

"AwsAccountNumber": {
    "description": "An AWS account that is included in the TrustedSigners complex type for this distribution.",
    "$ref": "#/definitions/AccountId"
},
    . . .

Advanced: How to Encapsulate Complex Logic

Use the allOf, oneOf, or anyOf elements to encapsulate complex logic in your resource provider schema.

In the example below, if whitelist is specified for the Forward property in your resource, then the WhitelistedNames property must also be specified. 

"properties": {
"Cookies": {
    "oneOf": [
        {
            "additionalProperties": false,
            "properties": {
               "Forward": {
                    "description": "Specifies which cookies to forward to the origin for this cache behavior.",
                    "enum": [
                        "all",
                        "none"
                    ],
                    "type": "string"
                }
            },
            "required": [
                "Forward"
            ]
        },
        {
            "additionalProperties": false,
            "properties": {
                "Forward": {
                    "description": "Specifies which cookies to forward to the origin for this cache behavior.",
                    "enum": [
                        "whitelist"
                    ],
                    "type": "string"
                },
                "WhitelistedNames": {
                    "description": "Required if you specify whitelist for the value of Forward.",
                    "items": {
                       "type": "string"
                    },
                    "minItems": 1,
                    "type": "array"
                }
            },
            "required": [
                "Forward",
                "WhitelistedNames"
            ]
        }
    ,
    type": "object"
},
},
. . .