Sync open source content 🐝 (from c6672fc5bfee70a545f585a07abdacf450db5899)

Author: beezythebot

_meta.global.tsx

@@ -179,6 +179,9 @@ const meta = {
                   },
                 },
               },
+              "data-transforms": {
+                title: "Data transforms",
+              },
               webhooks: {
                 title: "Add webhooks to your SDKs",
               },

docs/cli-generation/customize-cli.mdx

@@ -281,12 +281,12 @@ The CLI target wraps a generated Go SDK, so many shared SDK/runtime customizatio
 
 The CLI target generates and embeds a Go SDK under the hood. Many shared SDK/runtime concepts still apply, including:
 
-- [Server configuration](/docs/customize-sdks/servers)
-- [Authentication and security](/docs/customize-sdks/authentication/overview)
-- [Retries](/docs/customize-sdks/runtime/retries)
-- [Pagination](/docs/customize-sdks/runtime/pagination)
-- [Error handling](/docs/customize-sdks/responses/errors)
-- [Global parameters](/docs/customize-sdks/globals)
+- [Server configuration](/docs/sdks/customize/servers)
+- [Authentication and security](/docs/sdks/customize/authentication/overview)
+- [Retries](/docs/sdks/customize/runtime/retries)
+- [Pagination](/docs/sdks/customize/runtime/pagination)
+- [Error handling](/docs/sdks/customize/responses/errors)
+- [Global parameters](/docs/sdks/customize/globals)
 
 For Go-specific SDK configuration, see the [Go configuration reference](/docs/speakeasy-reference/generation/go-config).
 

docs/sdks/customize/data-transforms.mdx

@@ -0,0 +1,213 @@
+---
+title: "Data transforms"
+description: "Use jq expressions to automatically transform data between the API wire format and the SDK interface."
+---
+
+import { Callout } from "@/mdx/components";
+
+# Data transforms
+
+When the shape of data on the wire differs from the shape SDK users should see, use the `x-speakeasy-transform-from-api` and `x-speakeasy-transform-to-api` extensions to bridge the gap automatically. These extensions apply [jq expressions](https://jqlang.org/manual/) to transform data during serialization and deserialization, so SDK users work with a clean interface while the underlying API format is preserved.
+
+<Callout title="Language support" type="info">
+  Data transforms currently generate transform code for the **Go** target only. Other SDK targets (TypeScript, Python, Java, C#) will silently ignore these extensions.
+</Callout>
+
+## When to use data transforms
+
+Data transforms are useful when:
+
+- The API returns a response shape that could be cleaner for SDK consumers, such as deeply nested structures that should be flattened
+- The API schema cannot be changed, but the SDK should present a better interface
+- Fields need to be derived from other fields, such as combining `first_name` and `last_name` into `display_name`
+
+## Extensions
+
+Place these extensions on a schema in the OpenAPI spec, typically on request body or response schemas.
+
+- `x-speakeasy-transform-from-api`: Transforms data **from** the API response before the SDK user sees it.
+- `x-speakeasy-transform-to-api`: Transforms data **to** the API request format before sending.
+
+Both extensions can be used on the same schema when transforms are needed in both directions.
+
+### Format
+
+The value must be a YAML mapping with a `jq` key:
+
+```yaml
+x-speakeasy-transform-from-api:
+  jq: '.your_expression_here'
+```
+
+<Callout title="Note" type="info">
+  The only supported transform type is `jq`. Invalid syntax produces a build error with the expression and the parse error.
+</Callout>
+
+## Examples
+
+### Copy a field
+
+```yaml
+components:
+  schemas:
+    Resource:
+      type: object
+      x-speakeasy-transform-from-api:
+        jq: '. + { backup_id: .id }'
+      properties:
+        id:
+          type: string
+```
+
+### Rename a field
+
+```yaml
+components:
+  schemas:
+    Resource:
+      type: object
+      x-speakeasy-transform-to-api:
+        jq: '{ displayName: .name }'
+      properties:
+        name:
+          type: string
+```
+
+### Add a derived field
+
+```yaml
+components:
+  schemas:
+    User:
+      type: object
+      x-speakeasy-transform-from-api:
+        jq: '. + { display_name: .first_name + " " + .last_name }'
+      properties:
+        first_name:
+          type: string
+        last_name:
+          type: string
+```
+
+### Flatten a nested structure
+
+```yaml
+components:
+  schemas:
+    Order:
+      type: object
+      x-speakeasy-transform-from-api:
+        jq: '. + { status: .metadata.status } | del(.metadata)'
+      properties:
+        id:
+          type: string
+        metadata:
+          type: object
+          properties:
+            status:
+              type: string
+```
+
+### Conditional field addition
+
+```yaml
+components:
+  schemas:
+    Account:
+      type: object
+      x-speakeasy-transform-from-api:
+        jq: 'if .status == "active" then . + { is_active: true } else . end'
+      properties:
+        status:
+          type: string
+```
+
+### Remove a field before sending
+
+```yaml
+components:
+  schemas:
+    UpdateRequest:
+      type: object
+      x-speakeasy-transform-to-api:
+        jq: 'del(.internal_field)'
+      properties:
+        name:
+          type: string
+        internal_field:
+          type: string
+```
+
+### Bidirectional transforms
+
+Apply both extensions on the same schema to transform data in both directions:
+
+```yaml
+components:
+  schemas:
+    Service:
+      type: object
+      x-speakeasy-transform-to-api:
+        jq: '{ displayName: .name, maxInstances: .max_instance_count }'
+      x-speakeasy-transform-from-api:
+        jq: '. + { name: .displayName, max_instance_count: .maxInstances }'
+      properties:
+        displayName:
+          type: string
+        maxInstances:
+          type: integer
+```
+
+### Convert an array to a map
+
+Transform arrays from the API into a simpler map structure:
+
+```yaml
+requestBody:
+  content:
+    application/json:
+      schema:
+        type: object
+        x-speakeasy-transform-to-api:
+          jq: |
+            .tags |= (
+              if type == "object" then
+                to_entries | map({key: .key, value: .value})
+              else
+                .
+              end
+            )
+        properties:
+          tags:
+            type: array
+            items:
+              type: object
+              properties:
+                key:
+                  type: string
+                value:
+                  type: string
+```
+
+### Build composite identifiers
+
+Create combined identifiers from separate API fields:
+
+```yaml
+responses:
+  "200":
+    content:
+      application/json:
+        schema:
+          type: object
+          x-speakeasy-transform-from-api:
+            jq: |
+              .id = "projects/\(.project_id)/regions/\(.region)/databases/\(.name)"
+          properties:
+            project_id:
+              type: string
+            region:
+              type: string
+            name:
+              type: string
+```

docs/terraform/customize-terraform/entity-mapping.mdx

@@ -579,6 +579,12 @@ data.example_things.items[0].id
   `x-speakeasy-wrapped-attribute` to customize it.
 </Callout>
 
+### Data transforms
+
+When the shape of data on the wire differs from the structure a Terraform provider should expose, use the `x-speakeasy-transform-from-api` and `x-speakeasy-transform-to-api` extensions to apply [jq expressions](https://jqlang.org/manual/) that automatically reshape data during serialization and deserialization.
+
+For full details on format, available extensions, and examples, see [Data transforms](/docs/sdks/customize/data-transforms).
+
 ### Resources with Soft Delete
 
 By default, a generated managed resource uses the HTTP 404 Not Found status code on read to automatically remove the resource from the Terraform state which causes the next Terraform plan to propose recreating the resource. For resource APIs that support soft delete (grace time period before the resource is fully deleted), the `x-speakeasy-soft-delete-property` annotation adds a check against a read response property to also propose resource recreation.