datasource/schema: Initial package

.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
+}