provider/metaschema: Initial package

[bflad]

Reference: #132
Reference: #326
Reference: #437
Reference: #491
Reference: #508
Reference: #532

NOTE: Almost all providers will not use this functionality and it is already marked as experimental.

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:

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]metaschema.Attribute{
			"string_attribute": metaschema.StringAttribute{
				Required: true,
			},
			"custom_string_attribute": metaschema.StringAttribute{
				CustomType: timetypes.RFC3339Type,
				Optional:   true,
			},
			"list_attribute": metaschema.ListAttribute{
				ElementType: types.StringType,
				Optional:    true,
			},
			"list_nested_attribute": metaschema.ListNestedAttribute{
				NestedObject: metaschema.NestedAttributeObject{
					Attributes: map[string]metaschema.Attribute{
						"bool_attribute": metaschema.BoolAttribute{
							Optional: true,
						},
					},
				},
				Optional: true,
			},
			"single_nested_attribute": metaschema.SingleNestedAttribute{
				Attributes: map[string]metaschema.Attribute{
					"int64_attribute": metaschema.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:

func (p ExampleCloudProvider) GetMetaSchema(ctx context.Context) (tfsdk.Schema, diag.Diagnostics) {
  return tfsdk.Schema{/* ... */}, nil
}

Migrated implementation:

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:

// The "tfsdk.Attribute" could be omitted inside a map[string]tfsdk.Attribute
tfsdk.Attribute{
  Required: true,
  Type: types.StringType,
}

Migrated implementation:

// The metaschema.XXXAttribute must be declared inside map[string]metaschema.Attribute
metaschema.StringAttribute{
  Required: true,
}

Prior collection type (types.ListType, types.MapType, types.SetType) attribute implementation:

// The "tfsdk.Attribute" could be omitted inside a map[string]tfsdk.Attribute
tfsdk.Attribute{
  Required: true,
  Type: types.ListType{
    ElemType: types.StringType,
  },
}

Migrated implementation:

// 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:

// 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:

// 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:

// 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:

// The metaschema.XXXAttribute must be declared inside map[string]metaschema.Attribute
metaschema.ListNestedAttribute{
  NestedObject: metaschema.NestedAttributeObject{
    Attributes: map[string]metaschema.Attribute{/*...*/},
  },
  Required: true,
}

[bendbennett]

LGTM 👍

[github-actions]

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