# API currently uses 'fubar' but you're migrating to 'configuration'
schema:
  type: object
  x-speakeasy-transform-to-api:
    jq: |
      {
        fubar: .configuration
      }
  properties:
    configuration:
      type: object
```

Your Terraform provider exposes the new `configuration` field name while the API still expects `fubar`. When the API changes, you remove the transformation rather than forcing a breaking change on Terraform users.

This technique works for any planned API evolution where you want to minimize downstream impact.

## When to use transformations

Data transformations add complexity. They're valuable when:

- **Migrating existing providers**: Maintain your current interface while moving to generation
- **Significant UX improvements**: The transformation provides a meaningfully better user experience (like tags as maps)
- **Planned API changes**: You're preparing for a known future API modification

Avoid transformations when:

- **The API structure is reasonable**: If your API's structure works well in Terraform, don't add unnecessary transformation logic
- **Simple renames**: Minor naming differences usually aren't worth the complexity
- **You can change the API**: If you control the API and it's not yet released, consider changing the API instead

Generated code that directly reflects your API is simpler and easier to maintain. Use transformations when the value clearly outweighs the added complexity.

## Next steps

Data transformations are available now for Terraform provider generation. If you're considering migrating an existing provider or need to bridge the gap between your API structure and ideal provider interface, check out the documentation:

- [Terraform provider generation](/docs/terraform/create-terraform)
- [JQ playground](https://jq.speakeasy.com)

Data transformations solve a specific problem: they let you maintain the provider interface you've carefully designed while moving to generated code. This bridges the gap between manual implementation and generation, making migration feasible even when your provider has evolved significantly from your API's structure.