> ## Documentation Index
> Fetch the complete documentation index at: https://docs.royaltyport.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transformer

> Transform data using AI-powered prompts in your automation workflows

## Overview

The Transformer step takes the output from previous steps and reshapes it using AI. Instead of writing code to parse, map, and restructure data, you write a natural language prompt describing the transformation you want — and the AI produces the result as structured JSON.

This is useful when you need to:

* Extract specific fields from a large API response
* Rename and restructure data to match a target format
* Merge or flatten nested objects
* Filter an array down to matching items
* Convert between data formats (e.g. CSV-style rows to nested JSON)

## How It Works

At runtime, the Transformer step resolves any [template variables](/automations/steps/overview#template-variables) in your prompt before sending it to the AI. Data from previous steps, trigger payloads, variables, and databases must be explicitly referenced in the prompt using `{{...}}` syntax — the AI only sees what you include.

The AI returns the result as a JSON object in the `result` output field, which downstream steps can reference.

Because the output is always JSON, the Transformer works best when your prompt is specific about the structure you expect back.

<AccordionGroup>
  <Accordion title="Example: extract and rename fields">
    **Prompt:**

    ```
    From the following API response:
    {{step.fetch-articles.output.body}}

    Extract each article's id, title, and author name. Return an array of
    objects with the keys: articleId, title, authorName.
    ```

    **Output (`result`):**

    ```json theme={null}
    [
      { "articleId": 1, "title": "First Post", "authorName": "Alice" },
      { "articleId": 2, "title": "Second Post", "authorName": "Bob" }
    ]
    ```
  </Accordion>
</AccordionGroup>

## Configuration

| Field             | Description                                                                                                                                                                                    |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Prompt**        | Natural language instructions describing the transformation to apply. Use [template variables](/automations/steps/overview#template-variables) to reference specific data from previous steps. |
| **Output Schema** | Optional visual schema that defines the exact shape of the `result` object the model should return.                                                                                            |

### Writing Good Prompts

* **Be specific about output structure** — tell the AI exactly what keys and shape you expect back
* **Reference input paths explicitly** — e.g. "from the `body.data` array" rather than "from the data"
* **Keep it focused** — one transformation per step is easier to debug than a complex multi-part prompt

### Using Libraries

The prompt editor has built-in [library](/automations/libraries) integration. Click **Library** above the editor to load a saved prompt, or click **Save** to store the current prompt as a reusable library item. This is useful when the same transformation logic is shared across multiple automations.

## Output Schema

The **Output Schema** builder lets you define the exact structure you expect back from the Transformer, rather than relying solely on the prompt to describe it. When a schema is defined, it is compiled into a strict Zod schema at runtime and passed to the model — constraining its response to the shape you specify.

This removes the need to describe the output format in the prompt itself and makes it easier to access nested fields in downstream steps, because all defined paths appear automatically in the template picker.

### Adding Fields

In the **Output schema** section of the Transformer panel, click **Add field** to add a top-level field to the result object. Each field has:

| Setting         | Description                                                                      |
| --------------- | -------------------------------------------------------------------------------- |
| **Name**        | The key name in the `result` object (e.g. `title`, `amount`, `items`)            |
| **Type**        | The data type for this field (see table below)                                   |
| **Nullable**    | Whether the field is allowed to be `null` (toggle in the field settings popover) |
| **Description** | An optional hint for the model describing what this field should contain         |

### Supported Field Types

| Type      | Description                                                                                                  |
| --------- | ------------------------------------------------------------------------------------------------------------ |
| `string`  | A text value                                                                                                 |
| `number`  | A numeric value (integer or decimal)                                                                         |
| `boolean` | `true` or `false`                                                                                            |
| `null`    | Always null — useful for placeholder fields                                                                  |
| `enum`    | One of a fixed set of string values. Enter the allowed values as a comma-separated list below the field row. |
| `object`  | A nested object. Expand to add child fields.                                                                 |
| `array`   | A list of items. Choose the item type (including `object` for arrays of objects).                            |

### Nested Types

* **Objects** — add child fields inside the object field row to define the nested structure.
* **Arrays of objects** — set the item type to `object`, then add child fields to define each item's shape.
* **Arrays of enums** — set the item type to `enum` and enter the allowed values.

<AccordionGroup>
  <Accordion title="Example: array of objects with an enum field">
    Schema definition:

    * `tracks` (array, item type: object)
      * `title` (string)
      * `status` (enum: `active`, `inactive`, `pending`)
      * `plays` (number)

    The model will return:

    ```json theme={null}
    {
      "tracks": [
        { "title": "Song A", "status": "active", "plays": 14200 },
        { "title": "Song B", "status": "inactive", "plays": 830 }
      ]
    }
    ```

    Downstream steps can reference `{{step.transform.output.result.tracks}}` or individual fields like `{{step.transform.output.result.tracks[0].title}}`.
  </Accordion>
</AccordionGroup>

<Note>
  If no schema is defined, the Transformer falls back to open-ended JSON output — the model returns whatever structure the prompt describes. Defining a schema is optional but recommended when the result feeds into downstream steps that depend on specific field paths.
</Note>

## Output

| Field           | Type    | Description                                                            |
| --------------- | ------- | ---------------------------------------------------------------------- |
| `result`        | object  | The transformed data, shaped according to the Output Schema if defined |
| `error`         | boolean | Whether an error occurred                                              |
| `error_message` | string  | Error description if failed                                            |

<Tip>
  Downstream steps access the result via `{{step.your-step-name.output.result}}`. If you defined an Output Schema, all nested field paths (e.g. `result.tracks`, `result.tracks[0].title`) appear automatically in the template picker. If the result is an array, you can feed it into a [Loop step](/automations/steps/loop) to process each item.
</Tip>