Custom type support in Terraform

New features to the Speakeasy Platform - April 8, 2025

Terraform providers require robust type handling to ensure consistent, reliable infrastructure management. Today, we’re excited to announce custom type support in Speakeasy-generated Terraform providers. Custom types enable enhanced validation, improved data handling consistency, and seamless integration with specialized Terraform type libraries. This feature allows API providers to leverage the full power of the terraform-plugin-framework’s custom type system while maintaining the simplicity and automation benefits of Speakeasy’s SDK generation.

How it works

When you define an API schema field that requires specialized validation or handling, you can now use the OpenAPI Specification extension x-speakeasy-terraform-custom-type to specify custom type implementations. This extension allows you to define the necessary imports, schema type, and value type for your custom implementation:

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

The schema implementation automatically enables the custom type’s built-in validation during Terraform planning, while maintaining compatibility with your Go SDK’s type system. This approach provides the best of both worlds: robust validation at the Terraform layer and seamless data handling in your API integration code.

Key improvements

This release includes several significant enhancements to our Terraform generation:

• Replaced the terraform-plugin-framework Number schema and value types with Float64 for the generator number type, creating a more consistent 1:1 mapping between Terraform and Go SDK types
• Added initial custom type support for framework base types including Bool, Float32, Float64, Int32, Int64, List, Map, Set and String
• Polished SDK-to-Terraform code conversion for various primitive types including date, date-time, int32, and number
• Improved variable naming within deeply nested types for better code readability

Getting started

To leverage custom type support in your Terraform providers:

1. Identify fields in your API schema that would benefit from specialized validation or handling
2. Add the x-speakeasy-terraform-custom-type extension to those fields in your OpenAPI Specification document directly or via OpenAPI Overlay
3. Regenerate your Terraform provider using the Speakeasy CLI

For more information on custom types in Terraform, see the official Terraform plugin framework documentation (opens in a new tab).

🛠️ New Features and Bug Fixes 🐛

NOTE

Based on the most recent CLI version: Speakeasy v1.524.0 (opens in a new tab)

Terraform

🐝 Feat: Added custom type support for Terraform providers via x-speakeasy-terraform-custom-type extension.
🐝 Feat: Replaced Number with Float64 type for improved data handling consistency.
🐝 Feat: Enhanced primitive type conversion for date, date-time, int32, and number types.
🐝 Feat: Improved variable naming within deeply nested types.