index.mdx

page_title	description
Schema: Migrating from SDKv2 to the Framework	Migrate a schema from SDKv2 to the plugin Framework.

Schema

-> Note: The Plugin Framework is in beta.

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. Refer to Schemas in the Framework documentation for details.

This page explains the differences between the schema used by SDKv2 and the Framework. We also recommend reviewing these additional schema guides throughout the migration: /attributes-blocks/

• Attributes where the schema defines practitioner or provider data associated with a value and type.
• Attribute types where the schema defines the expected data structure and syntax.
• Attribute fields where the behaviors of an attribute are defined, such as Required, Optional, Computed, and Sensitive.
• Attribute defaults where the schema defines a value for an attribute which should be automatically included in a Terraform plan if it is not configured by the practitioner.
• Attributes without in-place updates where the schema defines an attribute that requires resource replacement if the value is updated.
• Attribute predefined validations and custom validations where the schema defines the syntax, constraints, or encoding expectations of a value.
• Blocks and computed blocks where the schema defines structural configuration sections of data, typically with nested attributes or further blocks.

Schema Structs

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.

The Framework uses tfsdk.Schema structs for providers, resources, and data sources. The schema struct is returned by a GetSchema function you define for the provider and each resource type and data source type. Refer to Framework for details.

SDKv2

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

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

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

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
}

Framework

In the Framework, you implement GetSchema method for your provider, resources, and data sources. This function is required by the provider.Provider, resource.Resource, and datasource.DataSource interfaces, respectively.

The following code shows how you define the GetSchema function for your provider, resources, and data sources.

func (p *provider) GetSchema(ctx context.Context) (tfsdk.Schema, diag.Diagnostics) {
    return tfsdk.Schema{}, nil
}

func (r *resourceExample) GetSchema(context.Context) (tfsdk.Schema, diag.Diagnostics) {
    return tfsdk.Schema{}, nil
}

func (r *dataSourceExample) GetSchema(context.Context) (tfsdk.Schema, diag.Diagnostics) {
    return tfsdk.Schema{}, nil
}

The Framework defines the schema.Schema struct as follows.

type Schema struct {
    Attributes          map[string]Attribute
    Blocks              map[string]Block
    Version             int64
    DeprecationMessage  string
    Description         string
    MarkdownDescription string
}

You use the Attributes field to define attributes for your provider, resources, and data sources. You 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 tfsdk.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 GetSchema method that returns the schema.
• The tfsdk.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 tfsdk.Schema for a resource in the Framework, copy the Version field in schema.Schema from the SDKv2 version of that resource.