Resource type schema - CloudFormation Command Line Interface
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.

Resource type schema

In order 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",
    "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 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.

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 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 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 true.

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

  • minLength

  • pattern

  • maxItems

  • minItems

  • uniqueItems

  • contains

  • 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 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 supplementary identifiers, each of which uniquely identifies 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 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 type. The handlers specified determine what provisioning actions CloudFormation takes with respect to the resource during various stack operations.

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

  • If the resource type 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 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

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

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

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

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

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