The complete mapping file syntax for Auth0 Relationship Sync, covering rules, tuple templates, tuple filters, iterators, and the expression language.
Auth0 Relationship Sync uses a mapping file to describe how Auth0 events become FGA tuples. A mapping file is a small, declarative YAML document: it matches incoming Auth0 events against rules, pulls out the fields you care about, and produces FGA tuple writes or deletes. This page is the complete syntax reference for that mapping file.Here’s the basic shape: two rules that add and remove a user from an organization as Auth0 emits membership events.
Label shown in validation output and error messages.
when
no
Expr expression. The rule is skipped if false. Supports &&, ||, !, comparisons, and all functions listed below.
variables
no
Ordered map of name → Expr. Each variable can reference input and any previously defined variable in the same rule.
tuples
yes (unless every tuple_filters entry deletes, or iterator.tuples supplies the desired tuples)
One or more tuple templates to write or delete.
tuple_filters
no
Read-diff-write or full-delete against existing FGA tuples. See Tuple filters.
iterator
no
Fan-out: evaluates iterator.tuples once per item in a collection. Takes source, as, and tuples.
Tuple fields
Field
Required
Description
user
yes
Interpolated string for the user URN. Use {{ variables.name }}, {{ input.field }}, or the iterator alias.
relation
yes
Interpolated string for the relation name.
object
yes
Interpolated string for the object URN.
action
no
"write" (default) or "delete".
Idempotent writes and deletes
Every write or delete a mapping engine performs ignores conflicts rather than failing: writes pass OpenFGA’s on_duplicate: "ignore" (skip a tuple that already exists), and deletes pass on_missing: "ignore" (skip a tuple that’s already gone). This applies automatically to every tuple template; there’s nothing to configure in the mapping. It’s what makes it safe for a rule to write or delete the same tuple more than once, whether from a genuinely duplicate event or from reprocessing during reconciliation.See Ignoring duplicate or missing tuples for how these options work at the OpenFGA API level.
Tuple filters
Tuple filters power two patterns:Reconcile (read-diff-write): the mapping engine reads tuples matching the filter from FGA, computes the delta against the desired state in tuples (or iterator.tuples, when the rule has an iterator), and writes the minimum changes. Use this for update events where the source system sends the full new state but not what specifically changed:
Reconcile re-reads the current tuples on every update event, even when the field didn’t change. If the event carries data.previous_object, you can skip no-op events and avoid the read; see Attributes and metadata for both approaches and their trade-offs.Full delete: set action: delete to remove all tuples matching the filter, without writing replacements:
Auth0 emits organization.member.deleted when a user leaves an organization, or when the organization itself is deleted, but never emits organization.member.role.deleted in either case. Left alone, a user’s role-assignment tuples outlive their membership. Add a rule that filters on the user and organization without pinning a relation, so it catches whatever role tuples exist:
This runs alongside your normal membership-removal rule (the one that deletes the member relation). Omitting relation here means it matches and deletes any relation this user has to this organization, including roles assigned as relations directly on the organization via organization.member.role.assigned.This technique assumes roles are modeled as relations on the organization itself. If your model instead writes role assignments to a separate role object, a user+organization filter can’t reach those tuples directly unless the assignment’s user side is organization-specific. See Roles: a user, within an organization membership for a pattern that wires role assignments through an intermediate object instead, so a pair of filters on membership removal revokes every role tied to it without needing to enumerate role IDs.
Cleaning up group tuples on group deletion
Auth0 emits only the single group.deleted event when a SCIM group is deleted. There’s no fan-out to a group.member.deleted event per member, so a deleted group’s membership tuples outlive the group. Two filters cover this, since the deleted group can appear on either side of a tuple:
The first filter matches every tuple where the deleted group is the object: its direct user members, any child groups nested inside it, and its connection relation tuple if your model has one. The second filter catches the case the first one misses: if the deleted group was itself nested as a member of some other group, that tuple has the deleted group in the user position (group:{{ variables.group_id }}#member), not the object, so it needs its own filter.Tuple filter fields:
Field
Required
Description
object
yes
At minimum a bare type prefix like "group:", even if the filter is really keyed on user.
user
no
Interpolated string, same as a tuple template’s user.
relation
no
Interpolated string, same as a tuple template’s relation.
action
no
"delete" to remove all matching tuples; omit to reconcile against tuples or iterator.tuples.
Iterator (fan-out)
Emit one set of tuples per item in a collection. Useful when a single input document contains an array of entities:
identity.connection is the connection’s name, but events such as group.created identify a connection by ID. The map translates each name to the ID that connection: objects use, and the filter skips identities on connections you do not list, because an unlisted name has no map entry and fails to evaluate. Keep the names in the when, the source, and the map in step. See B2B via Connections for the full pattern.The tuple templates go inside iterator, under tuples, and are evaluated once per item.
Delete actions
Delete can be set per-tuple (action: delete inside a tuple template); see the “Remove user from organization” example above.Deleting nested/userset members uses the #relation suffix syntax:
when guards and variable expressions use the Expr language. Expressions are sandboxed: no file I/O, network, or shell access.Available context:input (the full input document), variables (values computed earlier in the same rule), and the iterator alias inside iterator rules.String functions:lower(s), upper(s), trim(s), replace(s, old, new), split(s, sep), join(arr, sep), hasPrefix(s, prefix), hasSuffix(s, suffix), contains (infix operator: "hello" contains "ell").Collection functions:len(x), in (membership: "x" in arr), ?? (null-coalescing: value ?? "default").json_path(obj, path): safely traverses nested structures using a dot-separated path. Returns nil for missing paths instead of throwing.
When to use json_pathTwo-level key access like input.data.object.user.user_id throws if the intermediate key (user) is absent. Use json_path whenever the path may not exist across all input types processed by the same mapping file. Optional chaining (input.data.object?.app_metadata?.department_id) is the lighter-weight alternative when you just need a nil-safe read, not a dynamic path.
Embedded tests
Mapping files can include a tests: section with sample input documents and expected outputs: