Advanced features

Speciality annotations

The annotations in this section are not commonly used within Speakeasy. We recommend contacting our team to help you determine whether they are correct for you.

Force-marking a property as read-only

The x-speakeasy-param-readonly extension marks a property as read-only. Any user attempt to modify it in Terraform will result in a runtime error. This prevents unintended changes to critical properties in Terraform configurations.

components:
  schemas:
    Pet:
      type: object
      properties:
        name:
          type: string
        id:
          type: integer
          x-speakeasy-param-readonly: true

Force-designating a property as optional

Apply x-speakeasy-param-optional to any property to designate it as optional. This extension takes precedence over the required attribute in the JSON Schema specification, providing flexibility in Terraform configurations by allowing optional settings for certain properties.

components:
  schemas:
    Pet:
      type: object
      properties:
        name:
          type: string
        id:
          type: integer
          x-speakeasy-param-optional: true

Forcing resource recreation on property change

Properties marked with x-speakeasy-param-force-new will cause the associated Terraform resource to be destroyed and recreated whenever the property value changes. This ensures that any alteration to the property triggers a complete recreation of the object.

components:
  schemas:
    Pet:
      type: object
      properties:
        name:
          type: string
        id:
          type: integer
          x-speakeasy-param-force-new: true

Updating behavior for plan-only attributes

The x-speakeasy-terraform-plan-only extension ensures that only the values from the Terraform plan are used during updates, overriding any prior state or default values provided by the API. By preventing prior state values from being merged into the update request, the annotation ensures that omitted or null values in the plan are correctly reflected in API calls.

components:
  schemas:
    Pet:
      type: object
      properties:
        properties:
        name:
          type: string
        id:
          type: integer
          nullable: true
          x-speakeasy-terraform-plan-only: true

Deduplicating Terraform types

The terraform types folder includes a representation of your data models that is appropriate for the terraform-plugin-framework type system. However, if you have multiple types with the same signature (for example, the same set of child property types), a lot of these types may be effectively duplicated. To minimize the Git repository and binary size, it might make sense to deduplicate these types by reusing types with the same signature across different resources. To enable this, set the following configuration option:

terraform:
  enableTypeDeduplication: true

This option is false by default.