Specification

Note

Code Generation is currently in tech preview.

The Provider Code Specification is a versioned interface between source(s) and provider code; this interface creates a separation of concerns between any potential source(s) of information and potential consumer(s) of that information.

The implementation is a JSON schema with associated Go bindings which defines the structure and types of the interface. The interface is hierarchical, and describes structures from their most granular form (e.g., data sources, provider, resources), through to the fine-grained details of the individual types contained therein (e.g., required, sensitive).

Refer to the Intermediate Representation within the terraform-plugin-codegen-framework repository for further examples of Provider Code Specification usage.

Data Sources, Provider, and Resources

The specification defines the following top-level object properties.

{
  "datasources": [...],
  "provider": {
    "name": "example"
  },
  "resources": [...],
  "version": "0.1.0"
}

Property	Type	Required	Description
datasources	Array	No	The data sources within the provider.
provider	Object	Yes	The provider.
resources	Array	No	The resources within the provider.
version	String	Yes	The version of the specification.

Names for data sources, provider, and resources must conform to the requirements for a Terraform identifier. Additionally, all letters used in data source, provider, and resource names must be lower case.

Provider

The provider object is defined as follows:

Property	Type	Required	Description
name	String	Yes	The provider type name (e.g., `examplecloud`).
schema	Object	No	Schema definition for the provider configuration.

Data Source

A datasources array object is defined as follows:

Property	Type	Required	Description
name	String	Yes	The data source type name (e.g., `thing`).
schema	Object	Yes	Schema definition for the data source configuration.

Resource

A resources array object is defined as follows:

Property	Type	Required	Description
name	String	Yes	The resource type name (e.g., `thing`).
schema	Object	Yes	Schema definition for the resource configuration.

Schema

A schema object is defined as the following. At least one of attributes or blocks must be specified.

{
  "datasources": [
    {
      "name": "example",
      "schema": {
        "attributes": [ ... ],
        "blocks": [ ... ]
      }
    }
  ],
  ...
}

Property	Type	Required	Description
attributes	Array	No	Attributes (types that accept values) within the schema.
blocks	Array	No	Blocks (structural types) within the schema.

Attributes

An object within the attributes array is defined as the following. Exactly one of the type properties (e.g., bool) must be specified.

{
  "datasources": [
    {
      "name": "example",
      "schema": {
        "attributes": [
          {
            "name": "bool_attribute",
            "bool": { ... }
          },
          {
            "name": "float64_attribute",
            "float64": { ... }
          },
          {
            "name": "int64_attribute",
            "int64": { ... }
          },
          {
            "name": "list_attribute",
            "list": { ... }
          },
          {
            "name": "list_nested_attribute",
            "list_nested": { ... }
          },
          {
            "name": "map_attribute",
            "map": { ... }
          },
          {
            "name": "map_nested_attribute",
            "map_nested": { ... }
          },
          {
            "name": "number_attribute",
            "number": { ... }
          },
          {
            "name": "object_attribute",
            "object": { ... }
          },
          {
            "name": "set_attribute",
            "set": { ... }
          },
          {
            "name": "set_nested_attribute",
            "set_nested": { ... }
          },
          {
            "name": "single_nested_attribute",
            "single_nested": { ... }
          },
          {
            "name": "string_attribute",
            "string": { ... }
          }
        ]
      }
    }
  ],
  ...
}

Property	Type	Required	Description
bool	Object	No	Boolean attribute definition.
float64	Object	No	Float64 attribute definition.
int64	Object	No	Int64 attribute definition.
list	Object	No	List attribute definition.
list_nested	Object	No	List nested attribute definition.
map	Object	No	Map attribute definition.
map_nested	Object	No	Map nested attribute definition.
name	String	Yes	The name of the attribute.
number	Object	No	Number attribute definition.
object	Object	No	Object attribute definition.
set	Object	No	Set attribute definition.
set_nested	Object	No	Set nested attribute definition.
single_nested	Object	No	Single nested attribute definition.
string	Object	No	String attribute definition.

Attribute names must conform to the requirements for a Terraform identifier. Additionally, all letters used in attribute names must be lower case.

Attribute Type

The attribute type object (i.e., one of bool, float64, int64, list, list_nested, map, map_nested, number, object, set, set_nested, single_nested, or string) is defined as the following.

Provider

Property	Type	Required	Description
attributes	Array	No	Only used for `single_nested` attributes. Attributes (types that accept values) within the schema
attribute_types	Array	No	Only used for defining the types within an `object` attribute.
associated_external_type	Object	No	Only used for `single_nested` attributes. Defines the relationship between a Terraform Plugin Framework type, and another Go type.
custom_type	Object	No	Defines behaviour for a kind of value across schemas.
deprecation_message	String	No	Message describing that the attribute is deprecated.
description	String	No	Description of the attribute.
element_type	Object	No	Only used for defining the type within a `list`, `map`, or `set` attribute.
nested_object	Object	No	Only used for defining the objects type within a `list_nested`, `map_nested`, or `set_nested` attribute.
optional_required	String	Yes	Specifies whether the attribute is optional (`optional`), or required (`required`).
sensitive	Boolean	No	Specifies whether the attribute is sensitive.
validators	Array	No	Attribute validators.

Data Source

Property	Type	Required	Description
attributes	Array	No	Only used for `single_nested` attributes. Attributes (types that accept values) within the schema
attribute_types	Array	No	Only used for defining the types within an `object` attribute.
associated_external_type	Object	No	Only used for `single_nested` attributes. Defines the relationship between a Terraform Plugin Framework type, and another Go type.
computed_optional_required	String	Yes	Specifies whether the attribute is computed (`computed`), computed and optional (`computed_optional`), optional (`optional`), or required (`required`).
custom_type	Object	No	Defines behaviour for a kind of value across schemas.
deprecation_message	String	No	Message describing that the attribute is deprecated.
description	String	No	Description of the attribute.
element_type	Object	No	Only used for defining the type within a `list`, `map`, and `set`.
nested_object	Object	No	Only used for defining the objects type within a `list_nested`, `map_nested`, or `set_nested` attribute.
sensitive	Boolean	No	Specifies whether the attribute is sensitive.
validators	Array	No	Attribute validators.

Resource

Property	Type	Required	Description
attributes	Array	No	Only used for `single_nested` attributes. Attributes (types that accept values) within the schema
attribute_types	Array	No	Only used for defining the types within an `object` attribute.
associated_external_type	Object	No	Only used for `single_nested` attributes. Defines the relationship between a Terraform Plugin Framework type, and another Go type.
computed_optional_required	String	Yes	Specifies whether the attribute is computed (`computed`), computed and optional (`computed_optional`), optional (`optional`), or required (`required`).
custom_type	Object	No	Defines behaviour for a kind of value across schemas.
default	Object	No	Default value for attribute.
deprecation_message	String	No	Message describing that the attribute is deprecated.
description	String	No	Description of the attribute.
element_type	Object	No	Only used for defining the type within a `list`, `map`, and `set`.
nested_object	Object	No	Only used for defining the objects type within a `list_nested`, `map_nested`, or `set_nested` attribute.
plan_modifiers	Array	No	Attribute plan modifiers.
sensitive	Boolean	No	Specifies whether the attribute is sensitive.
validators	Array	No	Attribute validators.

attribute_types

An object within the attribute_types array is defined as the following.

Note that attribute_types can only be defined on object attributes.

One of bool, float64, int64, list, map, number, object, set or string must be specified.

{
  "datasources": [
    {
      "name": "example",
      "schema": {
        "attributes": [
          {
            "name": "object_attribute",
            "object": {
              "computed_optional_required": "optional",
              "attribute_types": [
                {
                  "name": "example",
                  "string": {}
                }
              ]
            }
          },
          ...
        ]
      }
    }
  ],
  ...
}

Property	Type	Required	Description
bool	Object	No	Boolean schema type definition.
float64	Object	No	Float64 schema type definition.
int64	Object	No	Int64 schema type definition.
list	Object	No	List schema type definition.
list_nested	Object	No	List nested schema type definition.
map	Object	No	Map schema type definition.
map_nested	Object	No	Map nested schema type definition.
name	String	Yes	The name of the attribute type.
number	Object	No	Number schema type definition.
object	Object	No	Object schema type definition.
set	Object	No	Set schema type definition.
set_nested	Object	No	Set nested schema type definition.
single_nested	Object	No	Single nested schema type definition.
string	Object	No	String schema type definition.

associated_external_type

The associated_external_type object is defined as the following. It provides a mechanism for defining the relationship between a Terraform Plugin Framework type, and another Go type. This is useful during code generation as it enables the auto-generation of methods which convert to the external type from the Framework type and vice versa.

Note that associated_external_type can only be specified on a nested_object within list_nested, map_nested, and set_nested attributes, or on a single_nested attribute.

{
  "datasources": [
    {
      "name": "example",
      "schema": {
        "attributes": [
          {
            "name": "list_nested_block",
            "list_nested": {
              "nested_object": {
                "associated_external_type": {
                  "import": {
                    "path": "example.com/apisdk"
                  },
                  "type": "*apisdk.Type"
                },
                ...
              }
            }
          },
          ...
        ]
      }
    }
  ],
  ...
}

Property	Type	Required	Description
import	Object	No	Defines the import `path`, and an optional `alias`.
type	String	Yes	Specifies the external type, such as an API SDK type, to associate with the nested_object within a `list_nested`, `map_nested`, or `set_nested` attribute, or with a `single_nested` attribute.

custom_type

The custom_type object is defined as the following. Refer to Custom Types for further information.

{
  "resources": [
    {
      "name": "example",
      "schema": {
        "attributes": [
          {
            "name": "string_attribute",
            "string": {
              "custom_type": {
                "import": {
                  "path": "github.com/hashicorp/terraform-plugin-framework-timetypes/timetypes"
                },
                "type": "timetypes.RFC3339Type",
                "value_type": "timetypes.RFC3339"
              },
              ...
            }
          }
        ]
      }
    }
  ],
  ...
}

Property	Type	Required	Description
import	Object	No	Defines the import `path`, and an optional `alias`.
type	String	Yes	Specifies the type to use within the schema definition.
value_type	String	Yes	Specifies the value type to use for data handling (refer to Accessing State, Config, and Plan, for example).

default

The default object is defined as the following. Refer to Default for further information.

Note that default can only be specified on resource attributes.

{
  "resources": [
    {
      "name": "example",
      "schema": {
        "attributes": [
          {
            "name": "bool_attribute",
            "bool": {
              "default": {
                "static": true
              },
              ...
            }
          }
        ]
      }
    }
  ],
  ...
}

Property	Type	Required	Description
custom	Object	No	Specifies the `schema_definition`, and optional `imports` for the default.
static	Boolean, Number, or String	No	Only used for `bool`, `float64`, `int64`, `number`, and `string` attributes. Defines the default attribute value.

Note that for bool, float64, int64, number, and string attributes one of custom, or static must be specified. For all other attribute types, custom must be specified.

The static value must correspond to the type of the attribute type (i.e., bool, float64, int64, number, and string attributes define default static values as boolean, number, number, number, and string, respectively).

element_type

The element_type object is defined as the following.

Note that element_type can only be specified on list, map, and set attributes. Refer to List Attribute, Map Attribute, and Set Attribute for further information.

One of bool, float64, int64, list, map, number, object, set or string schema types must be specified.

{
  "datasources": [
    {
      "name": "example",
      "schema": {
        "attributes": [
          {
            "name": "list_attribute",
            "list": {
              "computed_optional_required": "optional",
              "element_type": {
                "string": {}
              }
            }
          },
          ...
        ]
      }
    }
  ],
  ...
}

Property	Type	Required	Description
bool	Object	No	Boolean schema type definition.
float64	Object	No	Float64 schema type definition.
int64	Object	No	Int64 schema type definition.
list	Object	No	List schema type definition.
list_nested	Object	No	List nested schema type definition.
map	Object	No	Map schema type definition.
map_nested	Object	No	Map nested schema type definition.
number	Object	No	Number schema type definition.
object	Object	No	Object schema type definition.
set	Object	No	Set schema type definition.
set_nested	Object	No	Set nested schema type definition.
single_nested	Object	No	Single nested schema type definition.
string	Object	No	String schema type definition.

nested_object

The nested_object object is defined as the following.

Note that nested_object can only be specified on list_nested, map_nested, and set_nested attributes, or list_nested, and set_nested blocks. Refer to List Nested Attribute, Map Nested Attribute, Set Nested Attribute, List Nested Block, and Set Nested Block for further information.

{
  "datasources": [
    {
      "name": "example",
      "schema": {
        "attributes": [
          {
            "name": "list_nested_attribute",
            "list_nested": {
              "computed_optional_required": "optional",
              "nested_object": {
                "attributes": [
                  {
                    "name": "bool_attribute",
                    "bool": {
                      "computed_optional_required": "optional"
                    }
                  }
                ]
              }
            }
          },
          ...
        ]
      }
    }
  ],
  ...
}

Provider and Data Source

Property	Type	Required	Description
associated_external_type	Object	No	Defines the relationship between a Terraform Plugin Framework type, and another Go type.
attributes	Array	No	Attributes (types that accept values) within the schema.
custom_type	Object	No	Defines behaviour for a kind of value across schemas.
validators	Array	No	Attribute validators.

Resource

Property	Type	Required	Description
associated_external_type	Object	No	Defines the relationship between a Terraform Plugin Framework type, and another Go type.
attributes	Array	No	Attributes (types that accept values) within the schema.
custom_type	Object	No	Defines behaviour for a kind of value across schemas.
plan_modifiers	Array	No	Attribute plan modifiers.
validators	Array	No	Attribute validators.

plan_modifiers

An object within the plan_modifiers array is defined as the following.

Note that plan_modifiers can only be defined for resources. Refer to Plan Modification for further information.

Note that currently, it is only possible to use predefined plan modifiers by specifying them using the custom property. However, it is likely that the specification will be enhanced in future to use generic behaviours which the Framework Code Generator could use to guide the generation of a specific implementation.

{
  "resources": [
    {
      "name": "example",
      "schema": {
        "attributes": [
          {
            "name": "bool_attribute",
            "bool": {
              "plan_modifiers": [
                {
                  "custom": {
                    "imports": [
                      {
                        "path": "github.com/hashicorp/terraform-plugin-framework/resource/schema/boolplanmodifier"
                      }
                    ],
                    "schema_definition": "boolplanmodifier.UseStateForUnknown()"
                  }
                }
              ],
              ...
            }
          }
        ]
      }
    }
  ],
  ...
}

Property	Type	Required	Description
imports	Array	No	Each import object in the array specifies `path`, and an optional `alias`.
schema_definition	String	No	Specifies the definition for use within the schema.

validators

An object within the validators array is defined as the following. Refer to Attribute Validation for further information.

Note that currently, it is only possible to use predefined validators by specifying them using the custom property. However, it is likely that the specification will be enhanced in future to use generic behaviours which the Framework Code Generator could use to guide the generation of a specific implementation.

{
  "resources": [
    {
      "name": "example",
      "schema": {
        "attributes": [
          {
            "name": "string_attribute",
            "string": {
              "validators": [
                {
                  "custom": {
                    "imports": [
                      {
                        "path": "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator"
                      }
                    ],
                    "schema_definition": "stringvalidator.LengthAtLeast(5)"
                  }
                }
              ]
              ...
            }
          }
        ]
      }
    }
  ],
  ...
}

Property	Type	Required	Description
imports	Array	No	Each import object in the array specifies `path`, and an optional `alias`.
schema_definition	String	No	Specifies the definition for use within the schema.

Blocks

An object within the blocks array is defined as the following. Exactly one of the type properties (e.g., list_nested) must be specified.

{
  "datasources": [
    {
      "name": "example",
      "schema": {
        "blocks": [
          {
            "name": "list_nested_block",
            "list_nested": { ... }
          },
          {
            "name": "set_nested_block",
            "set_nested": { ... }
          },
          {
            "name": "single_nested_block",
            "single_nested": { ... }
          },
          ...
        ]
      }
    }
  ],
  ...
}

Property	Type	Required	Description
list_nested	Object	No	List nested block definition.
set_nested	Object	No	Set nested block definition.
single_nested	Object	No	Single nested block definition.

Block names must conform to the requirements for a Terraform identifier. Additionally, all letters used in a block name must be lower case.

Block Type

The block type object (i.e., one of list_nested, set_nested or single_nested) is defined as the following.

Property	Type	Required	Description
associated_external_type	Object	No	Only used for `single_nested` blocks. Defines the relationship between a Terraform Plugin Framework type, and another Go type
attributes	Array	No	Only used for `single_nested`_blocks. Attributes (types that accept values) within the schema.
blocks	Array	No	Only used for `single_nested`_blocks. Blocks (structural types) within the schema.
custom_type	Object	No	Defines behaviour for a kind of value across schemas.
deprecation_message	String	No	Message describing that the attribute is deprecated.
description	String	No	Description of the attribute.
nested_object	Object	No	Only used for defining the objects type within a `list_nested`, or `set_nested` block.
plan_modifiers	Array	No	Only used for resources. Block plan modifiers.
validators	Array	No	Block validators.

Schema Custom

The schema custom object for default, plan_modifiers, and validators is defined as the following.

Property	Type	Required	Description
imports	Array	No	Each import object in the array specifies `path`, and an optional `alias`.
schema_definition	String	Yes	Specifies the definition for use within the schema.

Schema Type

The schema type object is defined as the following.

The list, map, and set attributes use schema types within element_type.

The object attribute uses schema types within attribute_types.

Property	Type	Required	Description
attribute_types	Object	No	Only used for defining the types within an `object` schema type.
custom_type	Object	No	Defines behaviour for a kind of value across schemas.
element_type	Object	No	Only used for defining the type within a `list`, `map`, or `set` schema type.

Import

The import object is defined as the following.

Property	Type	Required	Description
alias	String	No	Defines the import alias for use in combination with the path.
path	String	Yes	Specifies the path to the package.