# Extract fields

Copy a JSONPath value into a target field, optionally transforming it.

## When to use it

Copy a value addressed by a JSONPath into an output field, optionally transforming it. This operation selects existing structured data; it is different from asking a model to infer a value from a document.

## Add and configure

1. Add **Extract fields** from the workflow step picker.
2. Give the step a recognisable name and connect its required inputs.
3. Set the options below. Nested names identify fields within an object or a list item.
4. Validate the recipe, inspect the test result, then run it on the intended data.

The step identifier used in the editor’s code view is `extract`.

## Settings

| Setting | Accepted value | Required | Default | What it controls |
| --- | --- | --- | --- | --- |
| Mode (`mode`) | "copy" / "upper" / "lower" / "strip" | No | "copy" | Transformation applied to the extracted value. |
| Source (`source`) | string | Yes | Not specified | JSONPath into each record. |
| Target (`target`) | string | Yes | Not specified | Destination field name on the record. |

## Inputs and outputs

| Direction | Port | Content | Required | Multiple records |
| --- | --- | --- | --- | --- |
| Inputs | `in` | records | Yes | Yes |
| Outputs | `out` | records | Yes | Yes |

## Effects, testing, and recovery

Transforms or passes records without a declared external side effect.

The declared preview behaviour is to execute this step. Reads, processing, or model usage can therefore be real. Read [dry runs](/docs/workflows/dry-runs) before using a preview with live connections.

No duplicate-prevention key is declared for this step. The step declares safe replay for its supported recovery path.

## Example: Lift a nested field to the top level

Step settings:

```json
{
  "source": "$.author.name",
  "target": "author_name"
}
```

Input records:

```json
[
  {
    "author": {
      "name": "Ada"
    }
  }
]
```

Expected output for this example:

```json
[
  {
    "author": {
      "name": "Ada"
    },
    "author_name": "Ada"
  }
]
```

## Example: Upper-case a code in place; records without it pass through

Step settings:

```json
{
  "mode": "upper",
  "source": "$.code",
  "target": "code"
}
```

Input records:

```json
[
  {
    "code": "ab-1"
  },
  {
    "title": "no code"
  }
]
```

Expected output for this example:

```json
[
  {
    "code": "AB-1"
  },
  {
    "title": "no code"
  }
]
```

## Check the result

Inspect the selected run’s status, counts, errors, and output records. An empty collection can be a valid result, and a completed step can contain per-record failures where the step defines that behaviour. Check the next step’s expected record shape before publishing or delivering the result.