Fides Documentation – Ethyca

Editing SaaS Datasets

SaaS integration datasets are automatically generated when you configure a SaaS integration. However, you may need to customize these datasets — for example, to add data categories, update field descriptions, or remove fields that are not relevant to your use case.

This guide explains how to edit a SaaS dataset using the Fides API, what changes are allowed, and what happens to your customizations when the integration is updated.

Dataset edits are scoped to a single connection. If you have multiple connections of the same integration type (e.g., two Stripe connections), changes to one connection's dataset will not affect the other. Each connection maintains its own independent dataset.

Prerequisites

Editing a SaaS dataset via the API

To update a SaaS dataset, use the PATCH endpoint for connection datasets:

PATCH /api/v1/connection/{connection_key}/dataset

Pass the updated dataset as the request body. For example, to add a data category to a field:

[\
  {\
    "fides_key": "my_saas_instance",\
    "collections": [\
      {\
        "name": "user",\
        "fields": [\
          {\
            "name": "email",\
            "data_categories": ["user.contact.email"]\
          }\
        ]\
      }\
    ]\
  }\
]

To retrieve the current dataset for reference before editing, use GET /api/v1/connection/{connection_key}/dataset.

Editing rules

Only the collections section of a SaaS dataset is mutable. The following table summarizes what you can and cannot change:

Action Allowed? Notes
Add or update data_categories on a field Yes
Add or update the description of a field Yes
Modify fides_meta.data_type on a field Yes
Remove a non-protected field Yes
Remove a protected field No Restored from template automatically
Add new collections No Ignored during execution, discarded on update
Add references or identities No Must be defined in the SaaS config
Change top-level metadata (fides_key, name, description, data_categories, organization_fides_key, meta) No Restored to original value with a warning

Protected fields are collection fields referenced by the SaaS config (e.g., in param_values or postprocessors). You can modify their metadata (data categories, descriptions, etc.) but you cannot delete them. To check which fields are protected, use GET /api/v1/connection/{connection_key}/dataset/{dataset_key}/protected-fields.

Behavior on integration update

When a SaaS integration template is updated, Fides performs a three-way merge to reconcile your customizations with the new template. How the update is triggered depends on the template type:

In both cases, the merge is performed between your current dataset (with your customizations), the previously stored template (the baseline), and the new template (the update).

Scenario Behavior
You modified a field Your version is preserved, even if the template also changed it
You did not modify a field Updated to the new template version
You deleted a non-protected field Stays deleted
You deleted a protected field Restored from the new template
Template adds a new field Added to your dataset
Template removes a field Removed from your dataset

Example

Suppose the original template has a user collection with fields email, name, and product_id.

Your edits:

New template changes:

Result after merge:

Field Outcome
email Keeps your data category annotation
product_id Keeps your data_type (your change takes priority)
name Remains deleted (not a protected field)
created_at Added from the new template

Next steps

[Linking Datasets](/content/docs/integrations/guides/datasets/link-datasets "Linking Datasets"/index.html) [Index](/content/docs/integrations/guides/datasets "Index"/index.html)