# Author a contract in Soda Cloud
Once your dataset is onboarded, you can begin defining the expectations that make up your Data Contract.
## Creating a Contract
To create a Data Contract, navigate to any **onboarded dataset** and click **Create Contract**.
{% 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 %}
{% hint style="info" %}
**Create Contract** will return a **contract template skeleton** based on your data. This will facilitate check creation, since the bones of the contract are already in place. If you wish to start with an **empty contract file**, simply click on **Skip to empty contract** when prompted.
{% endhint %}
You’ll be taken to the **Contract Editor**, a powerful interface where you can define your contract in two ways:
* **No-code view**: Point-and-click UI to add quality checks and configure settings
* **Code view**: YAML editor for full control and advanced use cases.
> See language reference: [contract-language-reference](https://docs.soda.io/reference/contract-language-reference "mention")
You can switch between views at any time using the **editor toggle** in the top right corner.
{% hint style="success" %}
You can edit your contract **manually**, whether it is with the code or no-code interface, **or you can use** [**Contract Copilot**](https://docs.soda.io/data-testing/contract-copilot) to help you implement the checks you need automatically.
{% endhint %}
## Key concepts in contract authoring
Understanding how to structure your contract is essential. Soda supports several types of checks and configuration options:
* **Filter**: applies a global filter to limit which rows are considered across the entire contract (e.g., only the latest partition or rows from the past 7 days.)
* **Variables:** help you **parameterize** your contract, making it flexible and adaptable to different contexts (e.g., environments, schedules, or partitions.)
* **Dataset-level Checks**: rules that apply to the dataset as a whole, like row count, freshness, or schema checks.
* **Column-level Checks**: rules that apply to individual columns, like missing values, uniqueness, ranges, or regex formats.
All visible columns are detected during onboarding. You can also manually add columns if needed.
### Use variables
Variables allow **dynamic substitution of values** in contracts. They help you:
* **Parameterize** values that differ across environments, datasets, or schedules.
* **Reuse values** in multiple places within the same contract to reduce duplication and improve maintainability.
You can define variables at the top of your contract:
Then use them throughout your contract using the `${var.VARIABLE_NAME}` syntax.
For example:
```javascript
filter: timestamp = "${var.partition_timestamp}";
```
You can **test the contract with variables**:
When running the contract, variable values must be provided unless a default is defined.
Variables are ideal for partitioned datasets, date-based rules, or customizing checks based on context.
#### Out of the box variables
**Now**: You can use `${soda.NOW}` in your Contract to access the current timestamp.
***
### Define Attributes
Use attributes to **label**, **sort**, and **route** your checks in Soda Cloud. Attributes help you organize checks by properties such as domain, priority, location, and sensitivity (e.g., PII).
> Learn how to leverage attributes with [notifications](https://docs.soda.io/manage-issues/notifications "mention") and [browse-datasets](https://docs.soda.io/manage-issues/browse-datasets "mention").
**Set default attributes at the top level**
You can define default attributes at the dataset level. These attributes apply to **all checks**, unless overridden at the individual check level.
**Apply attributes to checks**
You can add attributes directly to individual checks. For example:
**Add attributes to checks in bulk**
{% hint style="warning" %}
Adding attributes to checks in bulk is currently in **private preview**. Contact to enable.
{% endhint %}
When working with a large contract, you can use the contract editor's filter to scope a subset of checks and assign attributes to all of them at once, rather than editing each check individually.
{% stepper %}
{% step %}
In the contract editor, **click the filter icon** and apply one or more filters to select which checks you want to tag.
The check list will update to show only the matching checks.
{% endstep %}
{% step %}
Click **+ Add Attributes** in the top right of the editor
The **Add attribute to filtered checks** dialog will open.
{% endstep %}
{% step %}
Select an **Attribute** and **Value** from the dropdowns
Click **+ Add Attribute** to include additional attribute-value pairs in the same operation.
{% endstep %}
{% step %}
Click **+ Add attributes** (bottom right) to confirm
The selected attributes will be applied to all checks matching the current filter.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
The attribute is applied to all checks matching the active filter, not only those visible on screen.
{% endhint %}
#### **Attribute Validation in Soda Cloud**
When publishing contract results to Soda Cloud, **all check attributes must be pre-defined in Soda Cloud**. If any attribute used in a contract is not registered in your Soda Cloud environment, the results will **not be published**, and the data contract scan will be **marked as failed**.
> Learn how to configure attributes in Soda Cloud: [check-and-dataset-attributes](https://docs.soda.io/manage-issues/check-and-dataset-attributes "mention").
***
## Testing the Contract
Before publishing, click **Test** (top right) to simulate a contract verification against your live data. Soda will:
* Run all defined checks
* Display which rules pass or fail
* Surface profiling and diagnostic insights
This dry run helps ensure your contract behaves as expected, before making it official.
{% 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 %}
### Test a contract on a data sample
> You can test a contract on a sample of your data. Learn more at the onboarding [Additional settings](https://docs.soda.io/onboard-data-sources-and-datasets/onboard-datasets-on-soda-cloud/additional-settings#test-a-contract-on-a-sample).
## Publishing the Contract
Once you're happy with the results, click **Publish** (top right).
Publishing sets this version as the **source of truth** for that dataset. From this point on:
* Verifications will use the published version
* All users see this contract as the authoritative definition of data quality for that dataset
* Changes will require a new version or a proposal (depending on permissions)
Publishing ensures your data expectations are versioned, visible, and enforceable.
{% 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 %}
***
You’re now ready to start verifying your contract and monitoring your data.
## Contract history
**Contract history** provides a snapshot view of all changes that have been made to a contract.\
No retention policy applies to contract history. All contract records are preserved in full without time limitation.
To access contract history:
{% stepper %}
{% step %}
**Navigate to a dataset** with an existing data contract.
{% endstep %}
{% step %}
**Click on the** :clock: **icon** next to **Edit Contract**, on the top right (or click on **Edit Contract >** :clock:).
{% endstep %}
{% step %}
**Review contract history** by choosing a version on the left panel and inspecting it on the right panel.
{% endstep %}
{% endstepper %}
Just as when a contract is being created or edited, you can toggle between the code and no-code views.
The code view allows to toggle diff and toggle split view.
{% columns %}
{% column %}
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
### Request history
While contract history allows to see the changes that a contract has undergone, **request history** provides an overview of the **change requests** that have been made over a specific contract.
#### View dataset request history
To access the request history of any dataset, navigate to the dataset > **Requests** tab.
The list of requests can be filtered by **title key word** and by **state** (**Open**, **Done**, **Won't do**, **Draft**, **Ready for review**, and **Waiting for feedback**)
> From this view, you can also [create a request](https://docs.soda.io/contract-collaboration#initiating-a-request).
This view provides a snapshot of each request, making visible:
* The title, description (if any), and time of creation of the request
* The state of the request (**Open**, **Done**, **Won't do**, **Draft**, **Ready for review**, and **Waiting for feedback**)
* The :lightbulb: icon, which indicates that the request has a proposal
* The :message-lines: icon, which indicates that the request has comments
{% columns %}
{% column %}
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
#### View organization request history
To access all request history in an organization, navigate to tab **Requests** on top of the page.
This page provides an overview of **all requests** made within the organization. The requests can be filtered by:
* Title key word(s)
* Status
* User that created the request
* Users that are participants in the request
***
{% if (visitor.claims.plan === 'datasetStandard')
%}
{% 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 === 'enterprise')
%}
{% 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 === '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 === 'enterprise' || visitor.claims.plan === 'enterpriseUserBased' || visitor.claims.plan === 'datasetStandard')
%}
{% 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 %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.soda.io/data-testing/cloud-managed-data-contracts/author-a-contract-in-soda-cloud.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
