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

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

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.

Info

This extension completely suppresses the property from the Terraform state. If you want to suppress a specific operation, use x-speakeasy-ignore: true to omit the operation from the annotated CRUD method. For example, if a field is present in both the CREATE and READ response bodies, omitting it from the READ response body will turn off drift detection for that field. The field will remain in the CREATE response body and the Terraform state.

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
}

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

Warning

Applying this modifier when x-speakeasy-entity-operation: my_resource#read is not defined may result in drift between the Terraform plan and remote state should updates to attributes happen outside of Terraform changes. Please only apply this when necessary.