The data.world public API supports several options for programmatically making updates to resources on the platform. PATCH is a method for making partial updates to individual records, such as adding tags, changing a description, or modifying a title.

In the next two weeks, we will be making a change to the way PATCH endpoints modify list values. We outline these changes below.

Existing Merge Behavior

Lists are merged with existing values on PATCH requests

1. A dataset has tags: [tag A , tag B] 
2. A PATCH request is sent to /datasets/democorp/my-example-dataset with body: { "tags": [ "tag C", "tag D" ]  }
3. The dataset is updated to reflect tags: [ tag A, tag B, tag C ,tag D]
4. A PATCH request is sent to /datasets/democorp/my-example-dataset with payload: { "tags": []  }
5. No change is applied and the tags remain: [ tag A, tag B, tag C ,tag D]

New Replace Behavior

Lists replace existing values on PATCH requests

1. A dataset has tags: [tag A , tag B] 
2. A PATCH request is sent to /datasets/democorp/my-example-dataset with body: { "tags": [ "tag C", "tag D" ]  }
3. The dataset is now updated to have tags: [ tag C ,tag D].  tag A and tag B have been removed.
4. I send a PATCH request to /datasets/democorp/my-example-dataset with body: { "tags": []  }
5. The dataset has been updated to remove all tags.

Why we are making this change

Today, PATCH can be used to add, modify, or remove fields for all non-list values. With the current merge logic, items can only be appended to list values using PATCH. As a consequence, if you want to remove or reorder the items in a list, you must use the PUT method, which does not support partial updates and requires a full overwrite of the existing record. The new logic to overwrite list values will allow users to make partial updates to records that remove or modify the order of items in the list without needing to modify the entire record.

This new logic primarily impacts tags, file labels, collections, and multi-select custom metadata fields.