Introduction

Schema patches provide a way to stage a batch of schema changes — fields, mappings, and identity key ranks — into a single, named changeset that can be reviewed and applied together. Rather than editing the schema directly (where each change immediately enters the unpublished draft), patches let you group related changes, inspect a diff of what would change, and publish everything at once.

When a patch is applied, it creates a new published schema version. If anything goes wrong, you can revert to a previous version using the standard schema version history.

When to Use Schema Patches

Schema patches are useful when:

• Batching related changes: You're adding a new set of fields and mappings that belong together (e.g., onboarding a new data source) and want to review and apply them as a unit.
• Team coordination: Multiple people are working on schema changes and you want named, described changesets that are easy to identify and review.
• Pre-publish review: You want to see a complete diff of proposed changes against the live schema before anything takes effect.
• Isolating changes from the draft: Direct schema edits accumulate in a shared unpublished draft. Patches keep your changes separate until you're ready to apply them.

How Schema Patches Work

The schema patch lifecycle has five steps:

1. Create a patch — Start by creating a new patch with a name and description. Each patch targets a specific table (e.g., user). Think of the patch as an empty container for your proposed changes.

2. Add changes — Add, modify, or mark for deletion any combination of fields, mappings, and identity key ranks within the patch. You can make as many changes as needed before moving forward.

3. Review the diff — Inspect the patch to see exactly what would change relative to the live schema. The patch response includes property-level diffs for every modified field and mapping, so you can verify each change before it goes live.

4. Apply the patch — When you're satisfied, apply the patch. This publishes a new schema version containing all of the patch's changes. From this point forward, incoming data is processed against the updated schema.

5. Revert if needed — If the applied changes cause issues, use schema version history to revert to a previous version.

📘

You can update a patch as many times as needed before applying it. You can also delete a patch entirely if you decide not to proceed.

Understanding Patch Status

Each field, mapping, or rank within a patch carries an edit status that describes its relationship to the live schema:

When you retrieve a patch, the response includes a diff for each changed item showing the specific properties that differ and their before/after values. This makes it straightforward to audit exactly what a patch will do before applying it.

Working with Fields and Mappings in Patches

Fields and mappings can be individually added, updated, or marked for deletion within a patch. You can also undo a specific change (removing it from the patch) without discarding the entire patch.

For example, if you add three fields to a patch and then realize one of them isn't ready, you can remove just that field's changes while keeping the other two.

When adding or updating a field in a patch, the same properties apply as when managing fields directly — data type, merge operator, capacity, keep days, and so on. See Fields & Mappings for details on field and mapping properties.

📘

If you don't specify a managed_by value when adding a field or mapping to a patch, it defaults to the current user.

Working with Identity Key Ranks in Patches

Identity key rank lists — which control the priority ordering of identity keys used during profile resolution — can also be staged in a patch. This allows you to bundle rank changes alongside field and mapping updates, ensuring everything is reviewed and applied together.

See Identity Key Ranks for more on how rank ordering affects identity resolution.

Related

• Schema Versions — Publishing and reverting schema versions
• Fields & Mappings — Managing individual fields and mappings
• Identity Key Ranks — Identity key ranking and priority