Migrating schema

This page explains how to migrate schema from SDKv2 to the framework.

Refer to Schemas in the framework documentation for more details about implementing schema in the framework.

Background

Providers, resources, and data sources all use schema to define their attributes and behavior. Schemas specify the constraints of Terraform configuration blocks and how the provider, resource, or data source behaves.

Migrating schema structs

In SDKv2, resources and data sources use the same schema.Resource struct, while providers use the provider.Schema struct.

SDKv2 uses schema.Schema structs to define the structure, type, and behavior of values drawn from configuration, state, or plan data. The same schema.Schema struct type is used for providers, resources, and data sources. The schema struct is returned by the function that creates the provider, resource, or data source in question. As you migrate a given provider, resource, or data source to the framework, refer to Migrate attributes and blocks to learn how to migrate the attributes and blocks defined by your schema.

The framework uses its own schema.Schema structs for providers, resources, and data sources. The schema struct is returned by Schema() functions you define for your provider and each resource type and data source type. This function is required by the provider.Provider, resource.Resource, and datasource.DataSource interfaces, respectively.

The following code blocks show basic implementations using schema.Schema structs to define schemas for providers, resources, and data sources with SDKv2.

This example defines a provider schema in SDKv2:

func New() *schema.Provider {
    return &schema.Provider{
        Schema: map[string]*schema.Schema{},
        /* ... */
    }
}

This example defines a resource schema in SDKv2:

func resourceExample() *schema.Resource {
    return &schema.Resource{
        Schema: map[string]*schema.Schema{},
        /* ... */
    }
}

The following example defines a data source schema in SDKv2:

func dataSourceExample() *schema.Resource {
    return &schema.Resource{
        Schema: map[string]*schema.Schema{},
        /* ... */
    }
}

SDKv2 defines the schema.Schema struct as follows.

type Schema struct {
    Type                  ValueType
    ConfigMode            SchemaConfigMode
    Required              bool
    Optional              bool
    Computed              bool
    ForceNew              bool
    DiffSuppressFunc      SchemaDiffSuppressFunc
    DiffSuppressOnRefresh bool
    Default               interface{}
    DefaultFunc           SchemaDefaultFunc
    Description           string
    StateFunc             SchemaStateFunc
    Elem                  interface{}
    MaxItems              int
    MinItems              int
    Set                   SchemaSetFunc
    ConflictsWith         []string
    ExactlyOneOf          []string
    AtLeastOneOf          []string
    RequiredWith          []string
    Deprecated            string
    ValidateFunc          SchemaValidateFunc
    ValidateDiagFunc      SchemaValidateDiagFunc
    Sensitive             bool
}

The following code blocks show the same section of provider, resource, and data source code after migration.

The following example defines a provider schema in the framework:

func (p *ExampleCloudProvider) Schema(ctx context.Context, req provider.SchemaRequest, resp *provider.SchemaResponse) {
    resp.Schema = schema.Schema{/* ... */}
}

The following example defines a resource schema in the framework:

func (r *resourceExample) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
    resp.Schema = schema.Schema{/* ... */}
}

The following example defines a data source schema in the framework:

func (r *dataSourceExample) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) {
    resp.Schema = schema.Schema{/* ... */}
}

Use the Attributes schema field to define attributes for your provider, resources, and data sources. Use the Blocks field to define named blocks.

Migration notes

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

SDKv2 uses schema.Schema structs to define the provider, resources, and data sources. The framework uses concept-specific schema.Schema structs instead.
In SDKv2, schema structs are returned when a provider, resource, or data type is created. In the framework, the provider and each resource and data type have a Schema method that returns the schema.
In SDKv2, schema structs have a Set field which can be populated with a SchemaSetFunc which is used for hashing. In the framework, this is not required and does not need to be migrated.
The schema.Schema struct includes fields that you use to define attributes and blocks for your provider and each resource and data source.
When you populate the Version field in schema.Schema for a resource or data source when migrating to the framework, copy the Version field in schema.Schema from the SDKv2 version of that resource.

Migrating attributes and blocks

Each provider, resource, and data source schema defines the attributes and blocks they support. Refer to the following pages in this migration guide to migrate the attributes and blocks defined by your schema:

Attributes are defined by their schema.
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 when the value is updated.
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.