datasource/schema: Initial package (#546)

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{/*...*/},
  },
}
```

.changelog/546.txt

@@ -0,0 +1,7 @@
+```release-note:note
+datasource: The `DataSource` type `GetSchema` method has been deprecated. Use the `Schema` method instead.
+```
+
+```release-note:feature
+datasource/schema: New package which contains schema interfaces and types relevant to data sources
+```

datasource/data_source.go

@@ -8,7 +8,9 @@ import (
 )
 
 // DataSource represents an instance of a data source type. This is the core
-// interface that all data sources must implement.
+// interface that all data sources must implement. Data sources must also
+// implement the Schema method or the deprecated GetSchema method. The Schema
+// method will be required in a future version.
 //
 // Data sources can optionally implement these additional concepts:
 //
@@ -20,9 +22,6 @@ type DataSource interface {
 	// examplecloud_thing.
 	Metadata(context.Context, MetadataRequest, *MetadataResponse)
 
-	// GetSchema returns the schema for this data source.
-	GetSchema(context.Context) (tfsdk.Schema, diag.Diagnostics)
-
 	// Read is called when the provider must read data source values in
 	// order to update state. Config values should be read from the
 	// ReadRequest and new state values set on the ReadResponse.
@@ -60,6 +59,26 @@ type DataSourceWithConfigValidators interface {
 	ConfigValidators(context.Context) []ConfigValidator
 }
 
+// DataSourceWithGetSchema is a temporary interface type that extends
+// DataSource to include the deprecated GetSchema method.
+type DataSourceWithGetSchema interface {
+	DataSource
+
+	// GetSchema returns the schema for this data source.
+	//
+	// Deprecated: Use Schema method instead.
+	GetSchema(context.Context) (tfsdk.Schema, diag.Diagnostics)
+}
+
+// DataSourceWithSchema is a temporary interface type that extends
+// DataSource to include the new Schema method.
+type DataSourceWithSchema interface {
+	DataSource
+
+	// Schema should return the schema for this data source.
+	Schema(context.Context, SchemaRequest, *SchemaResponse)
+}
+
 // DataSourceWithValidateConfig is an interface type that extends DataSource to include imperative validation.
 //
 // Declaring validation using this methodology simplifies one-off

datasource/schema.go

@@ -0,0 +1,24 @@
+package datasource
+
+import (
+	"github.com/hashicorp/terraform-plugin-framework/datasource/schema"
+	"github.com/hashicorp/terraform-plugin-framework/diag"
+)
+
+// SchemaRequest represents a request for the DataSource to return its schema.
+// An instance of this request struct is supplied as an argument to the
+// DataSource type Schema method.
+type SchemaRequest struct{}
+
+// SchemaResponse represents a response to a SchemaRequest. An instance of this
+// response struct is supplied as an argument to the DataSource type Schema
+// method.
+type SchemaResponse struct {
+	// Schema is the schema of the data source.
+	Schema schema.Schema
+
+	// Diagnostics report errors or warnings related to validating the data
+	// source configuration. An empty slice indicates success, with no warnings
+	// or errors generated.
+	Diagnostics diag.Diagnostics
+}

datasource/schema/attribute.go

@@ -0,0 +1,33 @@
+package schema
+
+import (
+	"github.com/hashicorp/terraform-plugin-framework/internal/fwschema"
+)
+
+// Attribute define a value field inside the Schema. Implementations in this
+// package include:
+//   - BoolAttribute
+//   - Float64Attribute
+//   - Int64Attribute
+//   - ListAttribute
+//   - MapAttribute
+//   - NumberAttribute
+//   - ObjectAttribute
+//   - SetAttribute
+//   - StringAttribute
+//
+// Additionally, the NestedAttribute interface extends Attribute with nested
+// attributes. Only supported in protocol version 6. Implementations in this
+// package include:
+//   - ListNestedAttribute
+//   - MapNestedAttribute
+//   - SetNestedAttribute
+//   - SingleNestedAttribute
+//
+// In practitioner configurations, an equals sign (=) is required to set
+// the value. [Configuration Reference]
+//
+// [Configuration Reference]: https://developer.hashicorp.com/terraform/language/syntax/configuration
+type Attribute interface {
+	fwschema.Attribute
+}

datasource/schema/block.go

@@ -0,0 +1,27 @@
+package schema
+
+import (
+	"github.com/hashicorp/terraform-plugin-framework/internal/fwschema"
+)
+
+// Block defines a structural field inside a Schema. Implementations in this
+// package include:
+//   - ListNestedBlock
+//   - SetNestedBlock
+//   - SingleNestedBlock
+//
+// In practitioner configurations, an equals sign (=) cannot be used to set the
+// value. Blocks are instead repeated as necessary, or require the use of
+// [Dynamic Block Expressions].
+//
+// Prefer NestedAttribute over Block. Blocks should typically be used for
+// configuration compatibility with previously existing schemas from an older
+// Terraform Plugin SDK. Efforts should be made to convert from Block to
+// NestedAttribute as a breaking change for practitioners.
+//
+// [Dynamic Block Expressions]: https://developer.hashicorp.com/terraform/language/expressions/dynamic-blocks
+//
+// [Configuration Reference]: https://developer.hashicorp.com/terraform/language/syntax/configuration
+type Block interface {
+	fwschema.Block
+}

datasource/schema/bool_attribute.go

@@ -0,0 +1,183 @@
+package schema
+
+import (
+	"github.com/hashicorp/terraform-plugin-framework/attr"
+	"github.com/hashicorp/terraform-plugin-framework/internal/fwschema"
+	"github.com/hashicorp/terraform-plugin-framework/internal/fwschema/fwxschema"
+	"github.com/hashicorp/terraform-plugin-framework/schema/validator"
+	"github.com/hashicorp/terraform-plugin-framework/types"
+	"github.com/hashicorp/terraform-plugin-go/tftypes"
+)
+
+// Ensure the implementation satisifies the desired interfaces.
+var (
+	_ Attribute                             = BoolAttribute{}
+	_ fwxschema.AttributeWithBoolValidators = BoolAttribute{}
+)
+
+// BoolAttribute represents a schema attribute that is a boolean. When
+// retrieving the value for this attribute, use types.Bool as the value type
+// unless the CustomType field is set.
+//
+// Terraform configurations configure this attribute using expressions that
+// return a boolean or directly via the true/false keywords.
+//
+//	example_attribute = true
+//
+// Terraform configurations reference this attribute using the attribute name.
+//
+//	.example_attribute
+type BoolAttribute struct {
+	// CustomType enables the use of a custom attribute type in place of the
+	// default types.BoolType. When retrieving data, the types.BoolValuable
+	// associated with this custom type must be used in place of types.Bool.
+	CustomType types.BoolTypable
+
+	// Required indicates whether the practitioner must enter a value for
+	// this attribute or not. Required and Optional cannot both be true,
+	// and Required and Computed cannot both be true.
+	Required bool
+
+	// Optional indicates whether the practitioner can choose to enter a value
+	// for this attribute or not. Optional and Required cannot both be true.
+	Optional bool
+
+	// Computed indicates whether the provider may return its own value for
+	// this Attribute or not. Required and Computed cannot both be true. If
+	// Required and Optional are both false, Computed must be true, and the
+	// attribute will be considered "read only" for the practitioner, with
+	// only the provider able to set its value.
+	Computed bool
+
+	// Sensitive indicates whether the value of this attribute should be
+	// considered sensitive data. Setting it to true will obscure the value
+	// in CLI output. Sensitive does not impact how values are stored, and
+	// practitioners are encouraged to store their state as if the entire
+	// file is sensitive.
+	Sensitive bool
+
+	// Description is used in various tooling, like the language server, to
+	// give practitioners more information about what this attribute is,
+	// what it's for, and how it should be used. It should be written as
+	// plain text, with no special formatting.
+	Description string
+
+	// MarkdownDescription is used in various tooling, like the
+	// documentation generator, to give practitioners more information
+	// about what this attribute is, what it's for, and how it should be
+	// used. It should be formatted using Markdown.
+	MarkdownDescription string
+
+	// DeprecationMessage defines warning diagnostic details to display when
+	// practitioner configurations use this Attribute. The warning diagnostic
+	// summary is automatically set to "Attribute Deprecated" along with
+	// configuration source file and line information.
+	//
+	// Set this field to a practitioner actionable message such as:
+	//
+	//  - "Configure other_attribute instead. This attribute will be removed
+	//    in the next major version of the provider."
+	//  - "Remove this attribute's configuration as it no longer is used and
+	//    the attribute will be removed in the next major version of the
+	//    provider."
+	//
+	// In Terraform 1.2.7 and later, this warning diagnostic is displayed any
+	// time a practitioner attempts to configure a value for this attribute and
+	// certain scenarios where this attribute is referenced.
+	//
+	// In Terraform 1.2.6 and earlier, this warning diagnostic is only
+	// displayed when the Attribute is Required or Optional, and if the
+	// practitioner configuration sets the value to a known or unknown value
+	// (which may eventually be null). It has no effect when the Attribute is
+	// Computed-only (read-only; not Required or Optional).
+	//
+	// Across any Terraform version, there are no warnings raised for
+	// practitioner configuration values set directly to null, as there is no
+	// way for the framework to differentiate between an unset and null
+	// configuration due to how Terraform sends configuration information
+	// across the protocol.
+	//
+	// Additional information about deprecation enhancements for read-only
+	// attributes can be found in:
+	//
+	//  - https://github.com/hashicorp/terraform/issues/7569
+	//
+	DeprecationMessage string
+
+	// Validators define value validation functionality for the attribute. All
+	// elements of the slice of AttributeValidator are run, regardless of any
+	// previous error diagnostics.
+	//
+	// Many common use case validators can be found in the
+	// github.com/hashicorp/terraform-plugin-framework-validators Go module.
+	//
+	// If the Type field points to a custom type that implements the
+	// xattr.TypeWithValidate interface, the validators defined in this field
+	// are run in addition to the validation defined by the type.
+	Validators []validator.Bool
+}
+
+// ApplyTerraform5AttributePathStep always returns an error as it is not
+// possible to step further into a BoolAttribute.
+func (a BoolAttribute) ApplyTerraform5AttributePathStep(step tftypes.AttributePathStep) (interface{}, error) {
+	return a.GetType().ApplyTerraform5AttributePathStep(step)
+}
+
+// BoolValidators returns the Validators field value.
+func (a BoolAttribute) BoolValidators() []validator.Bool {
+	return a.Validators
+}
+
+// Equal returns true if the given Attribute is a BoolAttribute
+// and all fields are equal.
+func (a BoolAttribute) Equal(o fwschema.Attribute) bool {
+	if _, ok := o.(BoolAttribute); !ok {
+		return false
+	}
+
+	return fwschema.AttributesEqual(a, o)
+}
+
+// GetDeprecationMessage returns the DeprecationMessage field value.
+func (a BoolAttribute) GetDeprecationMessage() string {
+	return a.DeprecationMessage
+}
+
+// GetDescription returns the Description field value.
+func (a BoolAttribute) GetDescription() string {
+	return a.Description
+}
+
+// GetMarkdownDescription returns the MarkdownDescription field value.
+func (a BoolAttribute) GetMarkdownDescription() string {
+	return a.MarkdownDescription
+}
+
+// GetType returns types.StringType or the CustomType field value if defined.
+func (a BoolAttribute) GetType() attr.Type {
+	if a.CustomType != nil {
+		return a.CustomType
+	}
+
+	return types.BoolType
+}
+
+// IsComputed returns the Computed field value.
+func (a BoolAttribute) IsComputed() bool {
+	return a.Computed
+}
+
+// IsOptional returns the Optional field value.
+func (a BoolAttribute) IsOptional() bool {
+	return a.Optional
+}
+
+// IsRequired returns the Required field value.
+func (a BoolAttribute) IsRequired() bool {
+	return a.Required
+}
+
+// IsSensitive returns the Sensitive field value.
+func (a BoolAttribute) IsSensitive() bool {
+	return a.Sensitive
+}