Consider Allowing Usage of Custom Types for Structural Elements #508

bendbennett · 2022-10-05T13:12:08Z

Module version

github.com/hashicorp/terraform-plugin-framework v0.14.0

Use-cases

During the development of the v0.1.0 of terraform-plugin-framework-timeouts it became clear that it would be useful to be able to use custom types for structural elements such as blocks. The use-case in this instance was to be able to use a custom type within the schema and model for timeouts so that behaviour (e.g., functions) associated with the custom type could be used by provider developers when accessing timeouts.

For instance, given the following configuration:

resource "timeouts_example" "example" {
  timeouts {
    create = "60m"
    read = "30m"
    update = "12m"
  }

It would simplify provider developer experience if schema and model could be defined as follows:

func (t *exampleResource) GetSchema(ctx context.Context) (tfsdk.Schema, diag.Diagnostics) {
	return tfsdk.Schema{
		Attributes: map[string]tfsdk.Attribute{
			/* ... */
		},

		Blocks: map[string]tfsdk.Block{
			"timeouts": timeouts.Block(ctx, timeouts.Opts{
				Create: true,
				Read:   true,
				Update: true,
			}),
		},
	}, nil
}

type exampleResourceData struct {
	/* ... */
	Timeouts    timeouts.Timeouts `tfsdk:"timeouts"`
}

Access and usage of the timeouts within CRUD functions might then look something like the following:

func (r exampleResource) Create(ctx context.Context, req resource.CreateRequest, resp *resource.CreateResponse) {
	var data exampleResourceData

	diags := req.Plan.Get(ctx, &data)
	resp.Diagnostics.Append(diags...)

	if resp.Diagnostics.HasError() {
		return
	}

	createTimeout := data.Timeouts.Create(ctx, time.Minute*20)
	
	ctx, cancel := context.WithTimeout(ctx, createTimeout)
	defer cancel()

	/* ... */
}

Currently, it's not possible to use a custom type (e.g., timeouts.Timeouts) for structural elements, in this case tfsdk.Block as types.Object is used within the Framework and using a custom type results in errors indicating a type mismatch between the custom type and types.Object.

Attempted Solutions

In v0.1.0 of terraform-plugin-framework-timeouts types.Object has been used and helper functions such as timeouts.Create which accept types.Object have been created.

Proposal

Refactor the way in which structural elements such as types.Block rely on a concrete type (i.e., types.Object) to use an interface (e.g., TypeWithAttributeTypes) so that custom types which implement this interface can be used in place of types.Object to allow custom types with additional functionality to be used.

The text was updated successfully, but these errors were encountered:

…terfaces Reference: #132 Reference: #508 Reference: #532 Since the initial version of the framework, it has treated nested attributes and blocks as a singular entity with some internal gynastics to handle the one (single; object) or two (list, map, set to object) actual types that make up the nested attribute or block. Having these schema abstractions as single entities caused developer confusion when attempting to extract data or create paths. Other desirable features for the framework are the ability to customize the types, define validators, and define plan modifiers of nested attributes and blocks. This type customization, validation, or plan modification may need to be on the nested object to simplify provider implementations. Exposing these options with a flat abstraction could be confusing. This change introduces the concept of a nested attribute object and a nested block object into the `internal/fwschema` package and makes the necessary implementation changes to `tfsdk.Attribute` and `tfsdk.Block`. While the `tfsdk` package schema handling does not expose the new potential enhancements, the upcoming `datasource`, `provider`, and `resource` schema handling will. The existing unit testing shows no regressions and the new unit tests with validation show it should be possible to implement nested object validation (and when implemented in the near future, plan modification). This changeset additionally migrates more `tfsdk.Schema` logic into the `internal/fwschema` package in further preparation for creating additional schema implementations that will benefit from the existing schema logic.

Reference: #132 Reference: #326 Reference: #437 Reference: #491 Reference: #508 Reference: #532 This change introduces a new `datasource/schema` package, which contains schema interfaces and types relevant to data sources, such as omitting plan modifiers and schema versioning. This new schema implementation also provides strongly typed attributes, nested attributes, and blocks with customizable types. Nested attributes and blocks are exposed with a separate nested object for customization and validation. The implementation leans heavily on the design choice of the framework being responsible for preventing provider developer runtime errors. The tailored fields no longer expose functionality that is not available for data sources. The framework design will also raise compiler-time errors for errant typing of validators. Upstream updates to terraform-plugin-framework-validators to support the new `schema/validator` package are in progress. These changes require unit testing, terraform-provider-corner testing, and website documentation updates before being ready for primetime. Now is a great time for general feedback before those efforts begin in earnest.

…terfaces (#545) Reference: #132 Reference: #508 Reference: #532 Since the initial version of the framework, it has treated nested attributes and blocks as a singular entity with some internal gynastics to handle the one (single; object) or two (list, map, set to object) actual types that make up the nested attribute or block. Having these schema abstractions as single entities caused developer confusion when attempting to extract data or create paths. Other desirable features for the framework are the ability to customize the types, define validators, and define plan modifiers of nested attributes and blocks. This type customization, validation, or plan modification may need to be on the nested object to simplify provider implementations. Exposing these options with a flat abstraction could be confusing. This change introduces the concept of a nested attribute object and a nested block object into the `internal/fwschema` package and makes the necessary implementation changes to `tfsdk.Attribute` and `tfsdk.Block`. While the `tfsdk` package schema handling does not expose the new potential enhancements, the upcoming `datasource`, `provider`, and `resource` schema handling will. The existing unit testing shows no regressions and the new unit tests with validation show it should be possible to implement nested object validation (and when implemented in the near future, plan modification). This changeset additionally migrates more `tfsdk.Schema` logic into the `internal/fwschema` package in further preparation for creating additional schema implementations that will benefit from the existing schema logic.

Reference: #132 Reference: #326 Reference: #437 Reference: #491 Reference: #508 Reference: #532 This change introduces a new `datasource/schema` package, which contains schema interfaces and types relevant to data sources, such as omitting plan modifiers and schema versioning. This new schema implementation also provides strongly typed attributes, nested attributes, and blocks with customizable types. Nested attributes and blocks are exposed with a separate nested object for customization and validation. The implementation leans heavily on the design choice of the framework being responsible for preventing provider developer runtime errors. The tailored fields no longer expose functionality that is not available for data sources. The framework design will also raise compiler-time errors for errant typing of validators. Upstream updates to terraform-plugin-framework-validators to support the new `schema/validator` package are in progress. These changes require unit testing, terraform-provider-corner testing, and website documentation updates before being ready for primetime. Now is a great time for general feedback before those efforts begin in earnest.

Reference: #132 Reference: #326 Reference: #437 Reference: #491 Reference: #508 Reference: #532 This change introduces a new `datasource/schema` package, which contains schema interfaces and types relevant to data sources, such as omitting plan modifiers and schema versioning. This new schema implementation also provides strongly typed attributes, nested attributes, and blocks with customizable types. Nested attributes and blocks are exposed with a separate nested object for customization and validation. The implementation leans heavily on the design choice of the framework being responsible for preventing provider developer runtime errors. The tailored fields no longer expose functionality that is not available for data sources. The framework design will also raise compiler-time errors for errant typing of validators.

Reference: #132 Reference: #326 Reference: #437 Reference: #491 Reference: #508 Reference: #532 This change introduces a new `datasource/schema` package, which contains schema interfaces and types relevant to data sources, such as omitting plan modifiers and schema versioning. This new schema implementation also provides strongly typed attributes, nested attributes, and blocks with customizable types. Nested attributes and blocks are exposed with a separate nested object for customization and validation. The implementation leans heavily on the design choice of the framework being responsible for preventing provider developer runtime errors. The tailored fields no longer expose functionality that is not available for data sources. The framework design will also raise compiler-time errors for errant typing of validators. No changes are required for data handling in the `Read` method. Example definition: ```go package test import ( "context" "github.com/bflad/terraform-plugin-framework-type-time/timetypes" "github.com/hashicorp/terraform-plugin-framework-validators/float64validator" "github.com/hashicorp/terraform-plugin-framework-validators/listvalidator" "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/datasource" "github.com/hashicorp/terraform-plugin-framework/datasource/schema" "github.com/hashicorp/terraform-plugin-framework/schema/validator" "github.com/hashicorp/terraform-plugin-framework/types" ) type ThingDataSource struct{} func (d ThingDataSource) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) { resp.Schema = schema.Schema{ Attributes: map[string]schema.Attribute{ "string_attribute": schema.StringAttribute{ Required: true, Validators: []validator.String{ stringvalidator.LengthBetween(3, 256), }, }, "custom_string_attribute": schema.StringAttribute{ CustomType: timetypes.RFC3339Type, Optional: true, }, "list_attribute": schema.ListAttribute{ ElementType: types.StringType, Optional: true, }, "list_nested_attribute": schema.ListNestedAttribute{ NestedObject: schema.NestedAttributeObject{ Attributes: map[string]schema.Attribute{ "bool_attribute": schema.BoolAttribute{ Optional: true, }, }, Validators: []validator.Object{ /*...*/ }, }, Optional: true, Validators: []validator.List{ listvalidator.SizeAtMost(2), }, }, "single_nested_attribute": schema.SingleNestedAttribute{ Attributes: map[string]schema.Attribute{ "int64_attribute": schema.Int64Attribute{ Optional: true, }, }, Optional: true, }, }, Blocks: map[string]schema.Block{ "list_block": schema.ListNestedBlock{ NestedObject: schema.NestedBlockObject{ Attributes: map[string]schema.Attribute{ "float64_attribute": schema.Float64Attribute{ Optional: true, Validators: []validator.Float64{ float64validator.OneOf(1.2, 2.4), }, }, }, Validators: []validator.Object{ /*...*/ }, }, Validators: []validator.List{ listvalidator.SizeAtMost(2), }, }, }, } } ``` To migrate a data source schema: - Add `github.com/hashicorp/terraform-plugin-framework/datasource/schema` to the `import` statement - Switch the `datasource.DataSource` implementation `GetSchema` method to `Schema` whose response includes a `schema.Schema` from the new package. Prior implementation: ```go func (d ThingDataSource) GetSchema(ctx context.Context) (tfsdk.Schema, diag.Diagnostics) { return tfsdk.Schema{/* ... */}, nil } ``` Migrated implementation: ```go func (d ThingDataSource) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) { resp.Schema = schema.Schema{/*...*/} } ``` - Switch `map[string]tfsdk.Attribute` with `map[string]schema.Attribute` - Switch `map[string]tfsdk.Block` with `map[string]schema.Block` - Switch individual attribute and block definitions. Unless the code was already taking advantage of custom attribute types (uncommon so far), the `Type` field will be removed and the map entries must declare the typed implementation, e.g. a `tfsdk.Attribute` with `Type: types.StringType` is equivalent to `schema.StringAttribute`. Custom attribute types can be specified via the `CustomType` field in each of the implementations. Prior primitive type (`types.BoolType`, `types.Float64Type`, `types.Int64Type`, `types.NumberType`, `types.StringType`) attribute implementation: ```go // The "tfsdk.Attribute" could be omitted inside a map[string]tfsdk.Attribute tfsdk.Attribute{ Required: true, Type: types.StringType, } ``` Migrated implementation: ```go // The schema.XXXAttribute must be declared inside map[string]schema.Attribute schema.StringAttribute{ Required: true, } ``` Prior collection type (`types.ListType`, `types.MapType`, `types.SetType`) attribute implementation: ```go // The "tfsdk.Attribute" could be omitted inside a map[string]tfsdk.Attribute tfsdk.Attribute{ Required: true, Type: types.ListType{ ElemType: types.StringType, }, } ``` Migrated implementation: ```go // The schema.XXXAttribute must be declared inside map[string]schema.Attribute schema.ListAttribute{ ElementType: types.StringType, Required: true, } ``` Prior single nested attributes type (`tfsdk.SingleNestedAttributes()`) attribute implementation: ```go // The "tfsdk.Attribute" could be omitted inside a map[string]tfsdk.Attribute tfsdk.Attribute{ Attributes: tfsdk.SingleNestedAttributes(map[string]tfsdk.Attribute{/*...*/}), Required: true, }, ``` Migrated implementation: ```go // The schema.XXXAttribute must be declared inside map[string]schema.Attribute schema.SingleNestedAttribute{ Attributes: map[string]schema.Attribute{/*...*/}, Required: true, } ``` Prior collection nested attributes type (`tfsdk.ListNestedAttributes()`, `tfsdk.MapNestedAttributes()`, `tfsdk.SetNestedAttributes()`) attribute implementation: ```go // The "tfsdk.Attribute" could be omitted inside a map[string]tfsdk.Attribute tfsdk.Attribute{ Attributes: tfsdk.ListNestedAttributes(map[string]tfsdk.Attribute{/*...*/}), Required: true, }, ``` Migrated implementation: ```go // The schema.XXXAttribute must be declared inside map[string]schema.Attribute schema.ListNestedAttribute{ NestedObject: schema.NestedAttributeObject{ Attributes: map[string]schema.Attribute{/*...*/}, }, Required: true, } ``` Prior collection blocks type (`tfsdk.Block`) attribute implementation: ```go // The "tfsdk.Block" could be omitted inside a map[string]tfsdk.Block tfsdk.Block{ Attributes: map[string]tfsdk.Attribute{/*...*/}, Blocks: map[string]tfsdk.Block{/*...*/}, NestingMode: tfsdk.BlockNestingModeList, }, ``` Migrated implementation: ```go // The schema.XXXBlock must be declared inside map[string]schema.Block schema.ListNestedBlock{ NestedObject: schema.NestedBlockObject{ Attributes: map[string]schema.Attribute{/*...*/}, Blocks: map[string]schema.Block{/*...*/}, }, } ```

Reference: #132 Reference: #326 Reference: #437 Reference: #491 Reference: #508 Reference: #532 This change introduces a new `provider/schema` package, which contains schema interfaces and types relevant to providers, such as omitting `Computed`, plan modifiers, and schema versioning. This new schema implementation also provides strongly typed attributes, nested attributes, and blocks with customizable types. Nested attributes and blocks are exposed with a separate nested object for customization and validation. The implementation leans heavily on the design choice of the framework being responsible for preventing provider developer runtime errors. The tailored fields no longer expose functionality that is not available for providers. The framework design will also raise compiler-time errors for errant typing of validators. No changes are required for data handling in the `Read` method. Example definition: ```go package test import ( "context" "github.com/bflad/terraform-plugin-framework-type-time/timetypes" "github.com/hashicorp/terraform-plugin-framework-validators/float64validator" "github.com/hashicorp/terraform-plugin-framework-validators/listvalidator" "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/provider" "github.com/hashicorp/terraform-plugin-framework/provider/schema" "github.com/hashicorp/terraform-plugin-framework/schema/validator" "github.com/hashicorp/terraform-plugin-framework/types" ) type ExampleCloudProvider struct{} func (p ExampleCloudProvider) Schema(ctx context.Context, req provider.SchemaRequest, resp *provider.SchemaResponse) { resp.Schema = schema.Schema{ Attributes: map[string]schema.Attribute{ "string_attribute": schema.StringAttribute{ Required: true, Validators: []validator.String{ stringvalidator.LengthBetween(3, 256), }, }, "custom_string_attribute": schema.StringAttribute{ CustomType: timetypes.RFC3339Type, Optional: true, }, "list_attribute": schema.ListAttribute{ ElementType: types.StringType, Optional: true, }, "list_nested_attribute": schema.ListNestedAttribute{ NestedObject: schema.NestedAttributeObject{ Attributes: map[string]schema.Attribute{ "bool_attribute": schema.BoolAttribute{ Optional: true, }, }, Validators: []validator.Object{ /*...*/ }, }, Optional: true, Validators: []validator.List{ listvalidator.SizeAtMost(2), }, }, "single_nested_attribute": schema.SingleNestedAttribute{ Attributes: map[string]schema.Attribute{ "int64_attribute": schema.Int64Attribute{ Optional: true, }, }, Optional: true, }, }, Blocks: map[string]schema.Block{ "list_block": schema.ListNestedBlock{ NestedObject: schema.NestedBlockObject{ Attributes: map[string]schema.Attribute{ "float64_attribute": schema.Float64Attribute{ Optional: true, Validators: []validator.Float64{ float64validator.OneOf(1.2, 2.4), }, }, }, Validators: []validator.Object{ /*...*/ }, }, Validators: []validator.List{ listvalidator.SizeAtMost(2), }, }, }, } } ``` To migrate a provider schema: - Add `github.com/hashicorp/terraform-plugin-framework/provider/schema` to the `import` statement - Switch the `provider.Provider` implementation `GetSchema` method to `Schema` whose response includes a `schema.Schema` from the new package. Prior implementation: ```go func (p ExampleCloudProvider) GetSchema(ctx context.Context) (tfsdk.Schema, diag.Diagnostics) { return tfsdk.Schema{/* ... */}, nil } ``` Migrated implementation: ```go func (p ExampleCloudProvider) Schema(ctx context.Context, req provider.SchemaRequest, resp *provider.SchemaResponse) { resp.Schema = schema.Schema{/*...*/} } ``` If the provider requires no schema, the method can be entirely empty. - Switch `map[string]tfsdk.Attribute` with `map[string]schema.Attribute` - Switch `map[string]tfsdk.Block` with `map[string]schema.Block` - Switch individual attribute and block definitions. Unless the code was already taking advantage of custom attribute types (uncommon so far), the `Type` field will be removed and the map entries must declare the typed implementation, e.g. a `tfsdk.Attribute` with `Type: types.StringType` is equivalent to `schema.StringAttribute`. Custom attribute types can be specified via the `CustomType` field in each of the implementations. Prior primitive type (`types.BoolType`, `types.Float64Type`, `types.Int64Type`, `types.NumberType`, `types.StringType`) attribute implementation: ```go // The "tfsdk.Attribute" could be omitted inside a map[string]tfsdk.Attribute tfsdk.Attribute{ Required: true, Type: types.StringType, } ``` Migrated implementation: ```go // The schema.XXXAttribute must be declared inside map[string]schema.Attribute schema.StringAttribute{ Required: true, } ``` Prior collection type (`types.ListType`, `types.MapType`, `types.SetType`) attribute implementation: ```go // The "tfsdk.Attribute" could be omitted inside a map[string]tfsdk.Attribute tfsdk.Attribute{ Required: true, Type: types.ListType{ ElemType: types.StringType, }, } ``` Migrated implementation: ```go // The schema.XXXAttribute must be declared inside map[string]schema.Attribute schema.ListAttribute{ ElementType: types.StringType, Required: true, } ``` Prior single nested attributes type (`tfsdk.SingleNestedAttributes()`) attribute implementation: ```go // The "tfsdk.Attribute" could be omitted inside a map[string]tfsdk.Attribute tfsdk.Attribute{ Attributes: tfsdk.SingleNestedAttributes(map[string]tfsdk.Attribute{/*...*/}), Required: true, }, ``` Migrated implementation: ```go // The schema.XXXAttribute must be declared inside map[string]schema.Attribute schema.SingleNestedAttribute{ Attributes: map[string]schema.Attribute{/*...*/}, Required: true, } ``` Prior collection nested attributes type (`tfsdk.ListNestedAttributes()`, `tfsdk.MapNestedAttributes()`, `tfsdk.SetNestedAttributes()`) attribute implementation: ```go // The "tfsdk.Attribute" could be omitted inside a map[string]tfsdk.Attribute tfsdk.Attribute{ Attributes: tfsdk.ListNestedAttributes(map[string]tfsdk.Attribute{/*...*/}), Required: true, }, ``` Migrated implementation: ```go // The schema.XXXAttribute must be declared inside map[string]schema.Attribute schema.ListNestedAttribute{ NestedObject: schema.NestedAttributeObject{ Attributes: map[string]schema.Attribute{/*...*/}, }, Required: true, } ``` Prior collection blocks type (`tfsdk.Block`) attribute implementation: ```go // The "tfsdk.Block" could be omitted inside a map[string]tfsdk.Block tfsdk.Block{ Attributes: map[string]tfsdk.Attribute{/*...*/}, Blocks: map[string]tfsdk.Block{/*...*/}, NestingMode: tfsdk.BlockNestingModeList, }, ``` Migrated implementation: ```go // The schema.XXXBlock must be declared inside map[string]schema.Block schema.ListNestedBlock{ NestedObject: schema.NestedBlockObject{ Attributes: map[string]schema.Attribute{/*...*/}, Blocks: map[string]schema.Block{/*...*/}, }, } ```

Reference: #132 Reference: #326 Reference: #437 Reference: #491 Reference: #508 Reference: #532 This change introduces a new `resource/schema` package, which contains schema interfaces and types relevant to resources. This new schema implementation also provides strongly typed attributes, nested attributes, and blocks with customizable types. Nested attributes and blocks are exposed with a separate nested object for customization, plan modification, and validation. The implementation leans heavily on the design choice of the framework being responsible for preventing provider developer runtime errors. The tailored fields no longer expose functionality that is not available for resources. The framework design will also raise compiler-time errors for errant typing of validators. No changes are required for data handling in any other `resource.Resource` methods. Example definition: ```go package test import ( "context" "github.com/bflad/terraform-plugin-framework-type-time/timetypes" "github.com/hashicorp/terraform-plugin-framework-validators/float64validator" "github.com/hashicorp/terraform-plugin-framework-validators/listvalidator" "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/resource" "github.com/hashicorp/terraform-plugin-framework/resource/schema" "github.com/hashicorp/terraform-plugin-framework/schema/validator" "github.com/hashicorp/terraform-plugin-framework/types" ) type ThingResource struct{} func (r ThingResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) { resp.Schema = schema.Schema{ Attributes: map[string]schema.Attribute{ "string_attribute": schema.StringAttribute{ Required: true, Validators: []validator.String{ stringvalidator.LengthBetween(3, 256), }, }, "custom_string_attribute": schema.StringAttribute{ CustomType: timetypes.RFC3339Type, Optional: true, }, "list_attribute": schema.ListAttribute{ ElementType: types.StringType, Optional: true, }, "list_nested_attribute": schema.ListNestedAttribute{ NestedObject: schema.NestedAttributeObject{ Attributes: map[string]schema.Attribute{ "bool_attribute": schema.BoolAttribute{ Optional: true, }, }, Validators: []validator.Object{ /*...*/ }, }, Optional: true, Validators: []validator.List{ listvalidator.SizeAtMost(2), }, }, "single_nested_attribute": schema.SingleNestedAttribute{ Attributes: map[string]schema.Attribute{ "int64_attribute": schema.Int64Attribute{ Optional: true, }, }, Optional: true, }, }, Blocks: map[string]schema.Block{ "list_block": schema.ListNestedBlock{ NestedObject: schema.NestedBlockObject{ Attributes: map[string]schema.Attribute{ "float64_attribute": schema.Float64Attribute{ Optional: true, Validators: []validator.Float64{ float64validator.OneOf(1.2, 2.4), }, }, }, Validators: []validator.Object{ /*...*/ }, }, Validators: []validator.List{ listvalidator.SizeAtMost(2), }, }, }, } } ``` To migrate a resource schema: - Add `github.com/hashicorp/terraform-plugin-framework/resource/schema` to the `import` statement - Switch the `resource.Resource` implementation `GetSchema` method to `Schema` whose response includes a `schema.Schema` from the new package. Prior implementation: ```go func (r ThingResource) GetSchema(ctx context.Context) (tfsdk.Schema, diag.Diagnostics) { return tfsdk.Schema{/* ... */}, nil } ``` Migrated implementation: ```go func (r ThingResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) { resp.Schema = schema.Schema{/*...*/} } ``` If the resource requires no schema, the method can be entirely empty. - Switch `map[string]tfsdk.Attribute` with `map[string]schema.Attribute` - Switch `map[string]tfsdk.Block` with `map[string]schema.Block` - Switch individual attribute and block definitions. Unless the code was already taking advantage of custom attribute types (uncommon so far), the `Type` field will be removed and the map entries must declare the typed implementation, e.g. a `tfsdk.Attribute` with `Type: types.StringType` is equivalent to `schema.StringAttribute`. Custom attribute types can be specified via the `CustomType` field in each of the implementations. Prior primitive type (`types.BoolType`, `types.Float64Type`, `types.Int64Type`, `types.NumberType`, `types.StringType`) attribute implementation: ```go // The "tfsdk.Attribute" could be omitted inside a map[string]tfsdk.Attribute tfsdk.Attribute{ Required: true, Type: types.StringType, } ``` Migrated implementation: ```go // The schema.XXXAttribute must be declared inside map[string]schema.Attribute schema.StringAttribute{ Required: true, } ``` Prior collection type (`types.ListType`, `types.MapType`, `types.SetType`) attribute implementation: ```go // The "tfsdk.Attribute" could be omitted inside a map[string]tfsdk.Attribute tfsdk.Attribute{ Required: true, Type: types.ListType{ ElemType: types.StringType, }, } ``` Migrated implementation: ```go // The schema.XXXAttribute must be declared inside map[string]schema.Attribute schema.ListAttribute{ ElementType: types.StringType, Required: true, } ``` Prior single nested attributes type (`tfsdk.SingleNestedAttributes()`) attribute implementation: ```go // The "tfsdk.Attribute" could be omitted inside a map[string]tfsdk.Attribute tfsdk.Attribute{ Attributes: tfsdk.SingleNestedAttributes(map[string]tfsdk.Attribute{/*...*/}), Required: true, }, ``` Migrated implementation: ```go // The schema.XXXAttribute must be declared inside map[string]schema.Attribute schema.SingleNestedAttribute{ Attributes: map[string]schema.Attribute{/*...*/}, Required: true, } ``` Prior collection nested attributes type (`tfsdk.ListNestedAttributes()`, `tfsdk.MapNestedAttributes()`, `tfsdk.SetNestedAttributes()`) attribute implementation: ```go // The "tfsdk.Attribute" could be omitted inside a map[string]tfsdk.Attribute tfsdk.Attribute{ Attributes: tfsdk.ListNestedAttributes(map[string]tfsdk.Attribute{/*...*/}), Required: true, }, ``` Migrated implementation: ```go // The schema.XXXAttribute must be declared inside map[string]schema.Attribute schema.ListNestedAttribute{ NestedObject: schema.NestedAttributeObject{ Attributes: map[string]schema.Attribute{/*...*/}, }, Required: true, } ``` Prior collection blocks type (`tfsdk.Block`) attribute implementation: ```go // The "tfsdk.Block" could be omitted inside a map[string]tfsdk.Block tfsdk.Block{ Attributes: map[string]tfsdk.Attribute{/*...*/}, Blocks: map[string]tfsdk.Block{/*...*/}, NestingMode: tfsdk.BlockNestingModeList, }, ``` Migrated implementation: ```go // The schema.XXXBlock must be declared inside map[string]schema.Block schema.ListNestedBlock{ NestedObject: schema.NestedBlockObject{ Attributes: map[string]schema.Attribute{/*...*/}, Blocks: map[string]schema.Block{/*...*/}, }, } ```

Reference: #132 Reference: #326 Reference: #437 Reference: #491 Reference: #508 Reference: #532 This change introduces a new `provider/metaschema` package, which contains schema interfaces and types relevant to provider meta schemas, such as omitting `Computed`, `DeprecatedMessage`, `Sensitive`, plan modifiers, validators, blocks, schema descriptions, and schema versioning. This new schema implementation also provides strongly typed attributes and nested attributes with customizable types. Nested attributes are exposed with a separate nested object for customization. The implementation leans heavily on the design choice of the framework being responsible for preventing provider developer runtime errors. The tailored fields no longer expose functionality that is not available for provider meta schemas. No changes are required for data handling during requests. Example definition: ```go package test import ( "context" "github.com/bflad/terraform-plugin-framework-type-time/timetypes" "github.com/hashicorp/terraform-plugin-framework-validators/float64validator" "github.com/hashicorp/terraform-plugin-framework-validators/listvalidator" "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" "github.com/hashicorp/terraform-plugin-framework/provider" "github.com/hashicorp/terraform-plugin-framework/provider/metaschema" "github.com/hashicorp/terraform-plugin-framework/schema/validator" "github.com/hashicorp/terraform-plugin-framework/types" ) type ExampleCloudProvider struct{} func (p ExampleCloudProvider) MetaSchema(ctx context.Context, req provider.MetaSchemaRequest, resp *provider.MetaSchemaResponse) { resp.Schema = metaschema.Schema{ Attributes: map[string]schema.Attribute{ "string_attribute": schema.StringAttribute{ Required: true, }, "custom_string_attribute": schema.StringAttribute{ CustomType: timetypes.RFC3339Type, Optional: true, }, "list_attribute": schema.ListAttribute{ ElementType: types.StringType, Optional: true, }, "list_nested_attribute": schema.ListNestedAttribute{ NestedObject: schema.NestedAttributeObject{ Attributes: map[string]schema.Attribute{ "bool_attribute": schema.BoolAttribute{ Optional: true, }, }, }, Optional: true, }, "single_nested_attribute": schema.SingleNestedAttribute{ Attributes: map[string]schema.Attribute{ "int64_attribute": schema.Int64Attribute{ Optional: true, }, }, Optional: true, }, }, } } ``` To migrate a provider meta schema: - Add `github.com/hashicorp/terraform-plugin-framework/provider/metaschema` to the `import` statement - Switch the `provider.ProviderWithMetaSchema` implementation `GetMetaSchema` method to `MetaSchema` whose response includes a `metaschema.Schema` from the new package. Prior implementation: ```go func (p ExampleCloudProvider) GetMetaSchema(ctx context.Context) (tfsdk.Schema, diag.Diagnostics) { return tfsdk.Schema{/* ... */}, nil } ``` Migrated implementation: ```go func (p ExampleCloudProvider) MetaSchema(ctx context.Context, req provider.MetaSchemaRequest, resp *provider.MetaSchemaResponse) { resp.Schema = metaschema.Schema{/*...*/} } ``` If the provider requires no meta schema, the method can be removed entirely. - Switch `map[string]tfsdk.Attribute` with `map[string]metaschema.Attribute` - Switch individual attribute definitions. Unless the code was already taking advantage of custom attribute types (uncommon so far), the `Type` field will be removed and the map entries must declare the typed implementation, e.g. a `tfsdk.Attribute` with `Type: types.StringType` is equivalent to `metaschema.StringAttribute`. Custom attribute types can be specified via the `CustomType` field in each of the implementations. Prior primitive type (`types.BoolType`, `types.Float64Type`, `types.Int64Type`, `types.NumberType`, `types.StringType`) attribute implementation: ```go // The "tfsdk.Attribute" could be omitted inside a map[string]tfsdk.Attribute tfsdk.Attribute{ Required: true, Type: types.StringType, } ``` Migrated implementation: ```go // The metaschema.XXXAttribute must be declared inside map[string]metaschema.Attribute schema.StringAttribute{ Required: true, } ``` Prior collection type (`types.ListType`, `types.MapType`, `types.SetType`) attribute implementation: ```go // The "tfsdk.Attribute" could be omitted inside a map[string]tfsdk.Attribute tfsdk.Attribute{ Required: true, Type: types.ListType{ ElemType: types.StringType, }, } ``` Migrated implementation: ```go // The metaschema.XXXAttribute must be declared inside map[string]metaschema.Attribute metaschema.ListAttribute{ ElementType: types.StringType, Required: true, } ``` Prior single nested attributes type (`tfsdk.SingleNestedAttributes()`) attribute implementation: ```go // The "tfsdk.Attribute" could be omitted inside a map[string]tfsdk.Attribute tfsdk.Attribute{ Attributes: tfsdk.SingleNestedAttributes(map[string]tfsdk.Attribute{/*...*/}), Required: true, }, ``` Migrated implementation: ```go // The metaschema.XXXAttribute must be declared inside map[string]metaschema.Attribute metaschema.SingleNestedAttribute{ Attributes: map[string]metaschema.Attribute{/*...*/}, Required: true, } ``` Prior collection nested attributes type (`tfsdk.ListNestedAttributes()`, `tfsdk.MapNestedAttributes()`, `tfsdk.SetNestedAttributes()`) attribute implementation: ```go // The "tfsdk.Attribute" could be omitted inside a map[string]tfsdk.Attribute tfsdk.Attribute{ Attributes: tfsdk.ListNestedAttributes(map[string]tfsdk.Attribute{/*...*/}), Required: true, }, ``` Migrated implementation: ```go // The metaschema.XXXAttribute must be declared inside map[string]metaschema.Attribute metaschema.ListNestedAttribute{ NestedObject: metaschema.NestedAttributeObject{ Attributes: map[string]metaschema.Attribute{/*...*/}, }, Required: true, } ```

bendbennett · 2022-11-30T14:46:37Z

Closed by #553, #558, #546

github-actions · 2022-12-31T02:13:41Z

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.

bendbennett added the enhancement New feature or request label Oct 5, 2022

bendbennett added this to the v1.0.0 milestone Oct 5, 2022

bendbennett added a commit that referenced this issue Oct 5, 2022

Implementing custom type for blocks (#508)

cf19ec1

bendbennett added a commit that referenced this issue Oct 7, 2022

Adding documentation and tests for block (#508)

aa0723e

bendbennett added a commit that referenced this issue Oct 7, 2022

Adding support for using ValueWithAttrs interface (#508)

5b8a4b5

bendbennett mentioned this issue Oct 7, 2022

Consider Allowing Usage of Custom Types for Structural Elements #509

Closed

bendbennett added a commit that referenced this issue Oct 28, 2022

Implementing custom type for blocks (#508)

6f0b6bc

bendbennett added a commit that referenced this issue Oct 28, 2022

Adding documentation and tests for block (#508)

fad0233

bendbennett added a commit that referenced this issue Oct 28, 2022

Adding support for using ValueWithAttrs interface (#508)

897a02f

bendbennett mentioned this issue Oct 28, 2022

Consider Allowing Usage of Custom Types for Structural Elements - Nested Attributes #524

Closed

bendbennett mentioned this issue Nov 10, 2022

Consider Allowing Usage of Custom Types for Nested Attributes #532

Closed

bflad mentioned this issue Nov 18, 2022

internal/fwschema: Add NestedAttributeObject and NestedBlockObject interfaces #545

Merged

bflad mentioned this issue Nov 18, 2022

datasource/schema: Initial package #546

Merged

bflad mentioned this issue Nov 28, 2022

provider/schema: Initial package #553

Merged

bflad mentioned this issue Nov 29, 2022

resource/schema: Initial package #558

Merged

bflad mentioned this issue Nov 29, 2022

provider/metaschema: Initial package #562

Merged

bendbennett closed this as completed Nov 30, 2022

github-actions bot locked as resolved and limited conversation to collaborators Dec 31, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Consider Allowing Usage of Custom Types for Structural Elements #508

Consider Allowing Usage of Custom Types for Structural Elements #508

bendbennett commented Oct 5, 2022 •

edited

bendbennett commented Nov 30, 2022

github-actions bot commented Dec 31, 2022

Consider Allowing Usage of Custom Types for Structural Elements #508

Consider Allowing Usage of Custom Types for Structural Elements #508

Comments

bendbennett commented Oct 5, 2022 • edited

Module version

Use-cases

Attempted Solutions

Proposal

bendbennett commented Nov 30, 2022

github-actions bot commented Dec 31, 2022

bendbennett commented Oct 5, 2022 •

edited