Customize Terraform Properties

Remap API Property to Terraform Attribute Name

The x-speakeasy-name-override annotation adjusts the Terraform attribute name within a resource while remapping all the API data handling internally. This is useful, for example, to standardize differing API property names across operations to a single attribute name.

unique_id:
  type: string
  x-speakeasy-name-override: id

The annotation also has other SDK customization capabilities, however, those are generally unnecessary for Terraform providers as the generated Go SDK is internal to the provider code.

Align API Parameter With Terraform Property

The x-speakeasy-match annotation adjusts the API parameter name to align with a Terraform state property. If mismatches occur, a generation error will highlight appropriate root-level properties for accurate mapping.

paths:
  /pet/{petId}:
    delete:
      parameters:
        - name: petId
          x-speakeasy-match: id
      x-speakeasy-entity-operation: Pet#delete

Property Defaults

Setting a property default value that matches your API responses when unconfigured will enhance the Terraform plan to include the known value, rather than propagate the value as unknown (known after apply) during creation and updates.

Speakeasy generation automatically adds a Terraform schema attribute default with OAS default value, for each of the following OAS types:

Custom Defaults

For unsupported or advanced use cases, the Terraform SDK supports calling schema-defined custom default logic . Create the custom code implementing the Terraform type-specific resource/schema/defaults package interface in any code location and use the OAS x-speakeasy-terraform-custom-default extension to reference that implementation in the schema definition.

In this example, a custom string default implementation is created in internal/customdefaults/example.go:

package customdefaults
 
import (
  "context"
 
  "github.com/hashicorp/terraform-plugin-framework/resource/schema/defaults"
  "github.com/hashicorp/terraform-plugin-framework/types"
)
 
func Example() defaults.String {
  return exampleDefault{}
}
 
type exampleDefault struct{}
 
func (d exampleDefault) Description(ctx context.Context) string {
  return "Example custom default description"
}
 
func (d exampleDefault) MarkdownDescription(ctx context.Context) string {
  return "Example custom default description"
}
 
func (d exampleDefault) DefaultString(ctx context.Context, req defaults.StringRequest, resp *defaults.StringResponse) {
  resp.PlanValue = types.StringValue("example custom default")
}

With the following OAS configuration on the target property:

example:
  type: string
  x-speakeasy-terraform-custom-default:
    imports:
      - github.com/examplecorp/terraform-provider-examplecloud/internal/customdefaults
    schemaDefinition: customdefaults.Example()

The imports configuration is optional if the custom code is within the internal/provider package and does not require additional imports.

Hide Sensitive Properties

Properties marked as x-speakeasy-param-sensitive will be concealed from the console output of Terraform. This helps to ensure the confidentiality of sensitive data within Terraform operations.

components:
  schemas:
    Pet:
      type: object
      properties:
        name:
          type: string
        secret:
          type: string
          x-speakeasy-param-sensitive: true

Deprecation

Add OAS deprecated: true within a property to automatically return a warning diagnostic with a generic deprecation message when the property is configured in Terraform. Customize the messaging with the OAS x-speakeasy-deprecation-message extension.

In this example, Terraform will display a warning diagnostic with Custom deprecation message if the property is configured:

example:
  type: string
  deprecated: true
  x-speakeasy-deprecation-message: Custom deprecation message

Exclude Property From Terraform State

When x-speakeasy-terraform-ignore: true, this extension ensures the specified property and any interactions involving it are omitted from Terraform’s state management.

components:
  schemas:
    Pet:
      x-speakeasy-entity: Pet
      type: object
      properties:
        optionalMetadata:
          x-speakeasy-terraform-ignore: true
          type: string
        name:
          type: string
      required:
        - name

resource "petstore_pet" "mypet" {
  name = "myPet"
  # Attempting to set an ignored parameter results in an error
  # optionalMetadata = true
}

Custom Types

Set the x-speakeasy-terraform-custom-type extension to switch a property from the terraform-plugin-framework base type (e.g. types.String) to a custom type . Custom types typically include format-specific validation logic (such as a baked-in regular expression) or semantic equality handling to prevent unintentional value differences (such as ignoring inconsequential whitespace).

The following terraform-plugin-framework base types are supported for custom types:

• Bool
• Float32
• Float64
• Int32
• Int64
• List
• Map
• Set
• String

In this example, the ipv4_address string property will use the custom iptypes.IPv4Address type:

ipv4_address:
  type: string
  x-speakeasy-terraform-custom-type:
    imports:
      - github.com/hashicorp/terraform-plugin-framework-nettypes/iptypes
    schemaType: "iptypes.IPv4AddressType{}"
    valueType: iptypes.IPv4Address

Allow JSON String Attributes

Set the x-speakeasy-type-override extension to any to convert the associated attribute to a JSON string. This allows for inline the specification of the attribute’s value, accommodating attributes with variable or dynamic structures.

components:
  schemas:
    Pet:
      x-speakeasy-entity: Pet
      type: object
      properties:
        deep:
          x-speakeasy-type-override: any
          type: object
          properties:
            object:
              type: object
              additionalProperties: true
              properties:
                in:
                  type: object
                  properties:
                    here:
                      type: string
        name:
          type: string
      required:
        - name

resource "petstore_pet" "mypet" {
  name = "myPet"
  deep = jsonencode({
    object = {
      with = "anything"
      defined = true
    }
  })
}

Suppress Unnecessary Plan Changes

Setting the x-speakeasy-param-suppress-computed-diff to true suppresses unnecessary Terraform plan changes for computed attributes that are not definitively known until after application. This is useful in scenarios where computed attributes frequently cause spurious plan changes.

components:
  schemas:
    Pet:
      x-speakeasy-entity: Pet
      type: object
      properties:
        name:
          type: string
        status:
          x-speakeasy-param-suppress-computed-diff: true
          type: string