Migrating attribute schema

This page explains how to migrate an individual attribute from SDKv2 to the plugin framework.

Refer to Migrating schema to learn how to migrate your provider, resource, or data source's schema to the framework.

Refer to Schemas - Attributes in the framework documentation for details about implementing attribute schema with the framework.

Background

Attributes define how users can configure values for your Terraform provider, resources, and data sources. Attributes are defined within your provider, resource, or data source schema, and represent the values that can be configured in their respective blocks and stored in state.

Migrating an attribute

In SDKv2, attributes are defined by the Schema field in the provider, resource, or data source schema. The Schema field maps each attribute name, as a string, to the attribute's schema.Schema struct. Both resources and data sources are defined using the schema.Resource struct.

In the framework, define attributes by setting the Attributes field on your provider, resource, or data type's schema, as returned by the Schema method. The schema.Schema type returned by SchemaResponse includes an Attributes field that maps each attribute name (string) to the attribute's definition.

The following code shows an implementation of attribute schema for a provider in SDKv2.

func ProviderExample() *schema.Provider {
    return &schema.Provider{
        Schema: map[string]*schema.Schema{
            "example_attribute": {
                Type:        schema.TypeString,
                Required:    true,
            },
            /* ... */
        }
    }
},

In SDKv2, resource and data source attributes are defined the same way on their respective types. The following code shows an implementation of attribute schema for a resource in SDKv2.

func resourceExample() *schema.Resource {
    return &schema.Resource{
        Schema: map[string]*schema.Schema{
            "example_attribute": {
                Type:        schema.TypeString,
                Required:    true,
            },
            /* ... */

The following code shows how to define an attribute for a resource with the framework.

func (r *ThingResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
    resp.Schema = schema.Schema{
        Attributes: map[string]schema.Attribute{
            "example": /* ... */

Migration Notes

Remember the following differences between SDKv2 and the framework when completing the migration.

• In SDKv2, attributes are defined by a map from attribute names to schema.Schema structs in the Schema field of your resource's schema. In the framework, attributes are defined by a map from attribute names to schema.Attribute implementations in your resource's schema, which is returned by the resource's Schema method.
• SDKv2 implicitly includes the computed string id attribute in a resource's schema. In the framework, the id attribute must be explicitly defined in the schema.
• There are several differences between the implementation of attributes in SDKv2 and the framework. Refer to the other pages in the Attributes & Blocks section of this migration guide for more details.

Examples

String attribute

The following example shows the implementation of the example_attribute attribute for the exampleDataSource data source.

In SDKv2, attributes are defined in a schema.Resource, for both resources and data sources.

func exampleDataSource() *schema.Resource {
    return &schema.Resource{
        /* ... */
        Schema: map[string]*schema.Schema{
            "example_attribute": {
                Type:        schema.TypeString,
                Required:    true,
            },
        /* ... */

The following shows the same section of provider code after the migration.

This code implements the example_attribute attribute for the exampleDataSource data source with the framework.

func (d *exampleDataSource) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) {
    resp.Schema = schema.Schema{
        /* ... */
        Attributes: map[string]schema.Attribute{
            "example_attribute": schema.StringAttribute{
                Required:    true,
            },
            /* ... */

Next steps

Refer to the following pages in this migration guide to migrate your attributes to the framework:

• Each attribute has an attribute type. An attribute's type defines its expected data structure and syntax.
• Attribute fields define optional behaviors of the attribute, such as Required, Optional, Computed, and Sensitive.
• Attribute defaults define a default value for the attribute.
• Some attributes require that a resource be replaced when their value changes. Use a ForceNew trigger to force replacement of the resource.
• Providers may implement attribute validation to define required syntax, constraints, or encoding for the attribute's value. Implement attribute validation with a predefined validator or a custom validator.
• Attributes can include blocks and computed blocks to define structural configuration sections of data, typically with nested attributes or further blocks.