# Contract collaboration

Data contracts define the expectations between data producers and data consumers, ensuring that the data delivered is fit for purpose and aligned with business needs. However, data requirements evolve, and consumers often identify gaps or new use cases that require adjustments.

To support this, Soda provides a collaborative process that allows **data consumers to request changes** to existing data contracts or propose the creation of new ones. Consumers can directly propose changes by editing the data contract with **Soda's no-code editor**, suggesting concrete modifications for the dataset owner to review.

This approach enables data consumers to express their requirements not just in abstract terms but in actionable, implementable contract changes. By doing so, the consumer helps the dataset owner by:

* Making their needs clearer and more concrete.
* Supporting faster alignment between producers and consumers.
* Contributing to quicker and smoother implementation.
* Reducing unnecessary communication overhead.

The dataset owner remains the final decision-maker, reviewing proposed changes, iterating with the consumer as needed, and then publishing the updated contract once consensus is reached.

This collaborative workflow ensures that **data contracts remain living agreements** that continuously adapt to evolving business use cases while maintaining producer accountability.

> In Soda Cloud, you can access a view of the **contract history**, which allows to inspect all changes made to a specific contract.
>
> **Learn more about** [#contract-history](https://docs.soda.io/cloud-managed-data-contracts/author-a-contract-in-soda-cloud#contract-history "mention")**.**

## Explore requests

The **Requests** dashboard centralizes all data contract change requests in one place, making collaboration and review explicit and traceable.

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2FOMaEBWxXDMJ50x0647pR%2Fimage.png?alt=media&#x26;token=e7e791c6-2a07-41d0-8eff-7dc52094adc2" alt=""><figcaption></figcaption></figure>

#### Browse requests

Browse all requests across datasets, with key context such as status, author, participants, comments, and creation date. You can **view**, **edit** and **update** any request by clicking on it from the list and navigating the side panel.

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2FPXo7B1gVFFbJ5cdHOCA5%2Fimage.png?alt=media&#x26;token=2bd56641-eb1b-4b62-a1f5-332b5f8a492b" alt=""><figcaption></figcaption></figure>

#### Filter requests

You can filter requests by:

* <i class="fa-lightbulb">:lightbulb:</i> **Request:** the name of the request
* <i class="fa-table">:table:</i> **Dataset:** the location of the request
* <i class="fa-circle-info">:circle-info:</i> **Status:** "Open", "Done", or "Won't do"
* <i class="fa-user">:user:</i> **Author:** the user who created the request
* <i class="fa-user-group">:user-group:</i> **Participants:** the users that took part in the request

#### Save request collections

**Save filtered views as collections** for quick access and share them with your organization.

## Initiate a request

{% hint style="warning" %}
This action requires the **Propose checks** permission on the dataset. Learn more about permissions here: [dataset-attributes-and-responsibilities](https://docs.soda.io/dataset-attributes-and-responsibilities "mention")
{% endhint %}

Users can:

* **Request a change** by simply describing their needs and use cases.
* **Propose changes directly** by editing the data contract, suggesting concrete modifications for the dataset owner to review.

When a request is created, dataset owners automatically receive an email notification, ensuring they can promptly review and collaborate with the requester.

### Initiate a request with a proposal&#x20;

To propose a change or create a new contract, data consumers can initiate a request directly from the dataset page.

1. **Navigate to a dataset**\
   Go to any onboarded dataset in Soda.
2. **Start editing**
   * If the dataset does not yet have a contract, click **Create Contract**.
   * If a contract already exists, click **Edit Contract**.
3. **Make changes**\
   Update the contract based on your needs and use case. You can add, modify, or remove elements to ensure the contract reflects the requirements you want to address.
4. **Create a new request**\
   After making your edits, click **Create a Request**.

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2F9bv0DFTfx6qNxRuFGWXS%2Fimage.png?alt=media&#x26;token=7a4b52d1-fad5-4359-8efa-da0419307996" alt=""><figcaption></figcaption></figure>

5. **Provide details**\
   You will be prompted to:
   1. Enter a **title** for the request.
   2. Provide a **reasoning** or description of the changes, explaining why they are needed.

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2FuoPq5Kf3bFyiPXvycXvU%2Fimage.png?alt=media&#x26;token=34610ea4-ea84-4e6a-ad1f-ae9fbe4fbd34" alt=""><figcaption></figcaption></figure>

6. **Save the request**\
   Once you click **Save**, a new request is created containing your proposed changes. This proposal is then shared with the dataset owner for review and follow-up.

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2F8HuESYwALQysfGdCa80p%2FScreenshot%202025-08-20%20at%2010.13.20%E2%80%AFAM.png?alt=media&#x26;token=742f84aa-9550-4e73-ae74-1a1165742e66" alt=""><figcaption></figcaption></figure>

### Initiate a request without a proposal&#x20;

In some cases, data consumers may want to request changes without directly editing the contract themselves. This allows them to highlight a need while leaving the implementation details to the dataset owner.

1. **Navigate to the dataset**\
   Open the dataset in Soda.
2. **Go to the Requests tab**\
   Select the **Requests** tab for that dataset.
3. **Create a new request**\
   Click **Create a Request**.

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2Fn925aiwjdL1bDkUpWwuN%2FScreenshot%202025-08-20%20at%2010.18.33%E2%80%AFAM.png?alt=media&#x26;token=40b0e157-ea50-4ad1-8759-6fd245cefffb" alt=""><figcaption></figcaption></figure>

4. **Provide details**\
   You will be prompted to:
   1. Enter a **title** for the request.
   2. Provide a **reasoning** or description of the changes, explaining why they are needed.

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2F08J9u0QcITaabBLDFxXg%2FScreenshot%202025-08-20%20at%2010.20.09%E2%80%AFAM.png?alt=media&#x26;token=4bd187ab-c3b9-4a18-86e1-875c94a11cfa" alt=""><figcaption></figcaption></figure>

5. **Save the request**\
   Once you click **Save**, the request is created. The dataset owner will be notified and can review, clarify, and propose changes to the contract based on your input.

## Collaborate over a Request

Each dataset page includes a **Requests** tab where all requests related to that dataset are listed. From here, users can:

* **Search** for a request by name.
* **Filter** requests by status: *Open*, *Done*, or *Won’t Do*.
* **Click on any request** to access collaboration tools.

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2FNtegOcUCRqqaCo7wCJFG%2FScreenshot%202025-08-20%20at%2010.31.53%E2%80%AFAM.png?alt=media&#x26;token=b3a5b9f6-8a7b-4883-afa3-9df337af2be3" alt=""><figcaption></figcaption></figure>

Once inside a request, users can collaborate in the following ways:

### Review Proposals

Click **View Proposal** to examine an existing proposal associated with the request.

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2FMQjyTBSJ1zpAzNSCsrbS%2Fezgif-8070ba2848fa4e.gif?alt=media&#x26;token=45f2b96d-b739-495d-b072-8bd6bc5ecc99" alt=""><figcaption></figcaption></figure>

When viewing a proposal, visual indicators show exactly what has changed in the contract:

* **Blue icon** → element was **modified** (M).
* **Red icon** → element was **removed** (R).
* **Green icon** → element was **added** (A).
* **Blue dot** → a parent element has one or more **children that were updated**.

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2Fs0HGjRDFGB9bRt7yWHGb%2FScreenshot%202025-08-20%20at%2010.54.51%E2%80%AFAM.png?alt=media&#x26;token=a34343af-7b7e-41a1-8a77-df387d36d5c0" alt="" width="375"><figcaption></figcaption></figure>

### Exchange Messages

Participants can post text messages within the request to clarify needs, align on requirements, and discuss next steps.

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2FRyopv5DkaNxPf4uvmjSb%2FScreenshot%202025-08-20%20at%2010.36.30%E2%80%AFAM.png?alt=media&#x26;token=e4c7b216-a063-41cc-a800-a803bdc6a3de" alt=""><figcaption></figcaption></figure>

### Create a New Proposal

Users can contribute new proposals to move the request forward.&#x20;

**Iterate on an existing proposal:** while viewing a proposal, click the **pen icon** to edit and build upon it.

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2F7FVMrDdv6VvwqU4G7VDk%2FScreenshot%202025-08-20%20at%2010.58.50%E2%80%AFAM.png?alt=media&#x26;token=7c2fadf1-4ff5-463d-ba1c-de4c72f0d8dc" alt="" width="563"><figcaption></figcaption></figure>

**From scratch:** click **Add Proposal** to create a brand-new proposal.

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2FgVgHDpNZhPQC9Oa49iiB%2FScreenshot%202025-08-20%20at%2010.59.20%E2%80%AFAM.png?alt=media&#x26;token=dbf57a0f-97e0-477d-82a2-af97c2f10456" alt="" width="375"><figcaption></figcaption></figure>

In both cases:

1. Make your edits.

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2FIqMkR0OpMJdEo06upj75%2FScreenshot%202025-08-20%20at%2011.03.57%E2%80%AFAM.png?alt=media&#x26;token=5b40c49f-cb78-460a-a4cc-61be73d6d1e0" alt=""><figcaption></figcaption></figure>

2. Click **Save**.
3. Provide a message to explain what you have done.

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2FIlDOtobkSnKgf3IERy3E%2FScreenshot%202025-08-20%20at%2011.01.00%E2%80%AFAM.png?alt=media&#x26;token=ff0f473b-2509-41dd-bd2a-09af80e5ae72" alt=""><figcaption></figcaption></figure>

4. Click **Save** again

All participants are automatically **notified by email** when a new proposal is created or an iteration is made, ensuring everyone stays aligned and can respond promptly.

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2FJ3DsVelotOqhtH6ZHZWy%2FScreenshot%202025-08-20%20at%2011.02.41%E2%80%AFAM.png?alt=media&#x26;token=3aae0d85-fc6e-4b54-824a-e9e59dcf0b23" alt=""><figcaption></figcaption></figure>

## Publish a proposal

{% hint style="warning" %}
This action requires the **Manage Contract** permission on the dataset. Learn more about permissions here: [dataset-attributes-and-responsibilities](https://docs.soda.io/dataset-attributes-and-responsibilities "mention")
{% endhint %}

### Publishing to Soda Cloud

After reviewing a proposal, you can **publish it** by clicking the **Publish** button. Once published, all participants associated with the request will automatically receive a notification, ensuring they are informed of the update.

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2FWxHgya8XxgRQT4qyv38F%2FScreenshot%202025-08-20%20at%2011.41.15%E2%80%AFAM.png?alt=media&#x26;token=809bd98f-747d-4b12-87ae-688e56f803f2" alt="" width="375"><figcaption></figcaption></figure>

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2FpV8hynfGZF3Dm4lL88Jz%2FScreenshot%202025-08-20%20at%2011.43.02%E2%80%AFAM.png?alt=media&#x26;token=924489d2-3d4d-4146-92c1-632fa2b4b5c4" alt=""><figcaption></figcaption></figure>

#### Resolving conflict

In case a new version of the contract has been published, it is required to sync the proposal with the latest version to publish it.

1. When reviewing a proposal, click on **Sync to latest**

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2F92chxEWjOulDtCSToP45%2FScreenshot%202025-08-20%20at%2011.43.54%E2%80%AFAM.png?alt=media&#x26;token=d28f9c08-5417-4e59-bc4c-2ef2889660a5" alt=""><figcaption></figcaption></figure>

2. There are then 2 scenarios that can arise:&#x20;
   1. Soda can **automatically merges the 2 versions**. You can then proceed to the next step
   2. **There are conflicts that Soda cannot resolve**. In this case, you will be required to resolve the conflict. Soda offers a tool allowing you to compare the latest published version (left side) with the version of the proposal (right side). You can then edit the proposal version to resolve the conflicts. Click **Continue** to proceed

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2FcMEYXkTxVWgQdTINmbfX%2FScreenshot%202025-08-20%20at%2011.52.26%E2%80%AFAM.png?alt=media&#x26;token=4fa08dc8-36af-4ad8-a265-70c3872bf0d4" alt=""><figcaption></figcaption></figure>

3. Optionally, do extra edits
4. Click **Save** to create a new proposal, which you can now publish

### Publish to Git

You can fetch the content of a proposal from Soda Cloud and save it as a contract file, which can then be published to Git. This allows you to incorporate approved changes into version-controlled data contracts.

```bash
soda request fetch -r 7 -p 1 -sc soda-cloud.yaml --f ./contracts/ecommerce_orders.yamlRe
```

<table><thead><tr><th width="225.433349609375">Parameter</th><th width="123.8499755859375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>-r</code></td><td>Yes</td><td>The request number. Identifies the request to fetch. Request numbers can be found when reviewing a proposal. See screenshot below.</td></tr><tr><td><code>-p</code></td><td>No</td><td>The proposal number. Defaults to the latest proposal if not specified. Proposal numbers are shown as the decimal part when reviewing a proposal. See screenshot below.</td></tr><tr><td><code>--soda-cloud, -sc</code></td><td>Yes</td><td>Path to the Soda Cloud config file (e.g., <code>soda-cloud.yaml</code>).</td></tr><tr><td><code>--f</code></td><td>Yes</td><td>Path to the output file where the contract will be written.</td></tr></tbody></table>

Request and proposal numbers can be found on Soda Cloud when reviewing a proposal. The first number is the request, and the decimal is the proposal.

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2F06tHO36Erwk9fxuT5NXe%2FScreenshot%202025-08-20%20at%2011.35.57%E2%80%AFAM.png?alt=media&#x26;token=238404f7-735c-4e35-9dfc-8f13be255e05" alt="" width="375"><figcaption></figcaption></figure>

After fetching the proposal, you can optionally use the **publish command** to publish it from Soda Cloud to Git:  [#publish-a-contract](https://docs.soda.io/reference/cli-reference#publish-a-contract "mention")

## Close a request

Each request in Soda has a **status** to reflect its lifecycle. Initially, a request is created in the **Open** state. Once the requested changes have been implemented and published, the request can be moved to **Done**. If the decision is made not to implement the request, it can be transitioned to **Won’t Do**. Whenever a request’s status is updated, all participants are automatically notified by email, ensuring transparency and alignment across the collaboration process.

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2FuT1rYEWv6eujhyQtVPI7%2FScreenshot%202025-08-20%20at%2012.21.41%E2%80%AFPM.png?alt=media&#x26;token=f7648275-ded5-4033-9a23-fcfe379ebf5e" alt=""><figcaption></figcaption></figure>

<br>

***

{% if visitor.claims.plan === 'free' %}
{% hint style="success" %}
You are **logged in to Soda** and seeing the **Free license** documentation. Learn more about [documentation-access-and-licensing](https://docs.soda.io/reference/documentation-access-and-licensing "mention").
{% endhint %}
{% endif %}

{% if visitor.claims.plan === 'teams' %}
{% hint style="success" %}
You are **logged in to Soda** and seeing the **Team license** documentation. Learn more about [documentation-access-and-licensing](https://docs.soda.io/reference/documentation-access-and-licensing "mention").
{% endhint %}
{% endif %}

{% if visitor.claims.plan === 'enterprise' || visitor.claims.plan === 'enterpriseUserBased' %}
{% hint style="success" %}
You are **logged in to Soda** and seeing the **Enterprise license** documentation. Learn more about [documentation-access-and-licensing](https://docs.soda.io/reference/documentation-access-and-licensing "mention").
{% endhint %}
{% endif %}

{% if !(visitor.claims.plan === 'free' || visitor.claims.plan === 'teams' || visitor.claims.plan === 'enterprise' || visitor.claims.plan === 'enterpriseUserBased') %}
{% hint style="info" %}
You are **not logged in to Soda** and are viewing the default public documentation. Learn more about [documentation-access-and-licensing](https://docs.soda.io/reference/documentation-access-and-licensing "mention").
{% endhint %}
{% endif %}