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

# Working with Mapping Files

> How mapping validation works for a Sync pipeline, and how to work with mapping files from the command line.

A mapping file is a YAML document that tells a Sync pipeline how to transform Auth0 events into FGA tuples. For the full mapping syntax (rules, tuple templates, tuple filters, iterators, and the expression language), see [Mapping Language](https://docs.fga.dev/relationship-sync/mapping-language.md). For complete, end-to-end mappings built around specific scenarios, see [Use-Cases](https://docs.fga.dev/relationship-sync/use-cases/b2b-organizations.md). This page covers how validation works for a Sync pipeline and how to work with mapping files from the command line.

## Validating a mapping file

Validate a mapping directly in the FGA Dashboard, from the Sync pipeline's **Mappings** tab: paste the YAML into the **Mappings** field and click **Add Mappings** (or **Update Mappings**, if you're changing an existing one). Validation checks, in order:

* **YAML syntax** — malformed YAML is rejected with a line/column pointer before anything else runs.
* **Structure** — required fields, valid `action` values, and the other structural rules described in [Mapping Language](https://docs.fga.dev/relationship-sync/mapping-language.md).
* **Consistency with your selected FGA model** — every relation a tuple template writes to must actually exist on that model.

All errors across all rules are reported at once, not just the first one. See [Troubleshooting: Mapping validation errors](https://docs.fga.dev/relationship-sync/troubleshooting.md#mapping-validation-errors) for the full breakdown by category.

You can also validate a mapping locally before uploading it, using the OpenFGA CLI's `fga mapping` command group:

```bash theme={null}
fga mapping validate mapping.yaml --model-file model.fga
```

This catches the same three error categories as the dashboard. The CLI can do more than the dashboard, including running a mapping's embedded tests; see below.

## Using the CLI

Beyond validation, the same command group lets you develop and test mapping files locally, offline, with no store reads or writes, before they run against live input. `fga mapping sync` is the one command that reads and writes a store; see [Applying a mapping to a store](#applying-a-mapping-to-a-store). `fga mapping test` is the only way to actually execute a mapping's embedded `tests:` cases; the dashboard checks syntax, structure, and model consistency when you add or update a mapping, but never runs them.

> [!NOTE]
>
> This tooling is for transforming data that's still in an external system's own schema (events, webhooks, API payloads) into FGA tuples. If your data is already shaped as FGA tuples (YAML, JSON, or CSV) and you just need to load it, you don't need the mapper at all. See [Import tuples](https://docs.fga.dev/getting-started/cli.md#import-tuples) instead.

| Command | Flags | Purpose |
| - | - | - |
| `fga mapping init [file]` | `--force`, `--minimal` | Scaffold a starter mapping YAML (rules + embedded tests). Output path is positional, defaults to `mapping.yaml`. |
| `fga mapping validate <file>` | `--model-file`, `--format text\|json`, `--verbose`/`-v` | Compile the mapping; with `--model-file`, also verify every tuple template is consistent with that FGA model. |
| `fga mapping test <file>` | `--format text\|json\|junit`, `--run <substr>`, `--fail-fast`, `--output-file`/`-o`, `--verbose`/`-v`, `--no-color` | Run the mapping's embedded `tests:` cases and report pass/fail. |
| `fga mapping evaluate <file>` | `--input`, `--writes-only`, `--format jsonl\|json`, `--aggregate`, `--continue-on-error`, `--interactive`/`-i` | Feed JSON input (stdin or `--input`) through the mapping and emit the resulting tuple operations, for piping into `fga tuple write`. Runs offline. `fga mapping run` is a deprecated alias. |
| `fga mapping sync <file>` | `--store-id` (required), `--model-id`, `--input`, `--dry-run`, `--continue-on-error`, `--quiet` | Feed JSON input through the mapping and apply the resulting writes and deletes to a store, expanding `tuple_filters` against the store's current tuples. |

The mapping file path is a **positional argument**, not a flag, for example `fga mapping validate mapping.yaml --model-file model.fga`.

`evaluate`'s default output is JSONL, one operation per line. `--writes-only` emits bare tuples (no `op` field, deletes dropped) in exactly the shape `fga tuple write --file` accepts:

```bash theme={null}
cat input.jsonl | fga mapping evaluate mapping.yaml --writes-only --format json > tuples.json
fga tuple write --store-id 01H... --file tuples.json
```

`fga tuple write` doesn't read from stdin yet, so this is a two-step handoff through a file rather than a single pipe. If stdin support ships later, this collapses into one command.

**Offline limitation.** `evaluate` can dedupe writes/deletes and detect conflicts without a store, but `tuple_filters` rules need a live FGA Read to know what they match. Offline, these are reported as a stderr warning, and under `tuple_filter_operations` in the `--format json` output, instead of being expanded into concrete writes and deletes. Fully-specified `delete` tuples still work normally. Use `fga mapping sync` to expand them against a store.

**Exit codes** (all of these commands):

| Code | Meaning |
| - | - |
| `0` | Success |
| `1` | Runtime failure: I/O, JSON parse/eval error, write/delete conflict, or a failing test |
| `2` | Usage error, compile error, or model inconsistency |

### Applying a mapping to a store

`fga mapping sync` evaluates the mapping like `evaluate`, then applies the resulting writes and deletes to an FGA store. For rules with `tuple_filters`, it reads the tuples that match each filter, compares them with the tuples the rule produces, and writes and deletes the difference.

```bash theme={null}
cat input.jsonl | fga mapping sync mapping.yaml --store-id 01H... --dry-run > plan.jsonl
cat input.jsonl | fga mapping sync mapping.yaml --store-id 01H...
```

`--dry-run` reads the store and prints the planned operations to stdout as JSONL, without writing them. It prints nothing at an interactive terminal, so redirect stdout to see the plan. `sync` processes one input record at a time, sends deletes before writes in chunks of 40 without a transaction, and ignores duplicate writes and missing deletes. See [Backfilling and reconciling](https://docs.fga.dev/relationship-sync/managing.md#reconciling) for using it to repair drift and for what it cannot repair. It requires OpenFGA CLI v0.8.2 or later.

### Piping live Auth0 events into `fga mapping evaluate`

`fga mapping evaluate` reads JSON Lines from stdin, but it doesn't fetch events itself. To run a mapping against real tenant activity instead of a static input file, pipe it from the [Auth0 CLI](https://github.com/auth0/auth0-cli)'s own Events API consumer:

```bash theme={null}
auth0 event-streams subscribe --json-compact | jq --unbuffered -c 'select(.event) | .event' | fga mapping evaluate ./fga/mapping.yaml
```

Each line `auth0 event-streams subscribe --json-compact` emits is `{"type": ..., "offset": ..., "event": {...}}`. `offset` is a resume cursor for the CLI itself, not something a mapping ever reads; `type` duplicates `event.type`. The mapping's `when` and `variables` expressions run against `input.data.object...` (see [Getting Started](https://docs.fga.dev/relationship-sync/getting-started.md#understand-the-mapping)), which lives inside that inner `event` object — so `jq` strips the wrapper down to just `.event` before handing each line to the mapper. `select(.event)` also drops heartbeat lines (`offset-only`), which carry no `event` field.

For example, an `organization.member.added` event arrives from `auth0 event-streams subscribe --json-compact` as:

```json theme={null}
{"type":"organization.member.added","offset":"NTY3ODkwMTIzCg==","event":{"id":"evt_abc123","specversion":"1.0","type":"organization.member.added","source":"urn:auth0:your-tenant.us.auth0.com","time":"2026-01-15T09:30:00Z","data":{"object":{"organization":{"id":"org_acme"},"user":{"user_id":"auth0|abc123"}}}}}
```

After `select(.event) | .event`, that's what `fga mapping evaluate` actually sees as one line of its input, and what a rule's `input.*` expressions resolve against:

```json theme={null}
{"id":"evt_abc123","specversion":"1.0","type":"organization.member.added","source":"urn:auth0:your-tenant.us.auth0.com","time":"2026-01-15T09:30:00Z","data":{"object":{"organization":{"id":"org_acme"},"user":{"user_id":"auth0|abc123"}}}}
```

This is the same shape as a `tests:` case's `input:` field (see [Embedded tests](https://docs.fga.dev/relationship-sync/mapping-language.md#embedded-tests)) and as the sample event objects in the [Events API's SSE examples](https://auth0.com/docs/customize/events/consume-events-with-events-api#example-sse-stream) — just JSON instead of YAML, and one line instead of an indented document.

`--unbuffered` matters here: without it, `jq` holds output in a buffer and only flushes once enough bytes accumulate, so tuples show up in bursts instead of as each event arrives, which defeats the point of piping a live stream.

This is for exploring a mapping against real events as they happen, not for backfilling or production use: `fga mapping evaluate` runs entirely offline (see [Using the CLI](#using-the-cli) above), so it never writes to your store. Pair it with `--writes-only` and hand the output to `fga tuple write` to actually apply the tuples, the same as with any other input source. `--writes-only` drops deletes, so tuples that should be removed stay in your store.
