> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage contracts

> Define, validate, and version event schemas using contracts to ensure reliable event data.

## Overview

Contracts define the events and fields Hightouch expects from an event source, so you can catch incomplete or inconsistent data before it reaches your warehouse.

The contract system has three parts:

* An **event contract** defines the name, type, description, and validation schema for a single event (for example, `Order Completed`).
* A **component** is a reusable piece of event schema that can be added to one or more event schemas or nested within other components (for example, `User Identity`).
* A **domain** is a collection of event contracts and components that can be applied to one or more event sources (for example, `E-commerce Events`).

Each event contract belongs to a single domain. A domain can be applied to multiple event sources.

After contracts exist, the [Events CLI](https://docs.hightouch.com/events/contracts/cli.md) can generate typed SDK wrappers so application code matches those schemas.

## Example use cases

**Team-level ownership with domains.** A large retailer with multiple corporate divisions wants each division to own its own event schemas while sharing one workspace and a common set of event sources. By creating a [domain](#create-a-domain) per division, each team manages its own event contracts and components independently, while the shared sources are validated against every domain applied to them.

**Shared field groups with components.** Every event needs the same `cart_metadata` or `device_info` block. Instead of redefining those fields in each event schema, define them once as a [component](#add-a-component) and [import it](#import-components-into-the-event-schema) into every event that needs it. When the shape changes, update the component in one place and roll it out to importing schemas on your own schedule using [component versions](#2-manage-component-versions).

**Reducing duplication across similar sources.** A common pattern is to set up two event sources with two collections of event schemas that are largely the same but differ by a few properties—for example, production vs. staging, or iOS vs. Android. Instead of maintaining duplicate schemas, define the shared fields in components and put source-specific fields in components [scoped to specific sources](#3-manage-component-sources). A single set of event schemas can then serve both sources.

**Auditing component usage before making changes.** A data engineer wants to answer "where is this field group used?" before changing it. The component's **Usage** tab lists every schema that imports the component, so you can assess the impact of a change before publishing a new version.

## Create a domain

![Add domain button](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/events/contracts/add-domain.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=f2cd752a1b4064c0eab17546280e955c)

To create a new domain:

1. Go to **Event Collection → Contracts**.
2. Click **Add domain**.
3. Provide a domain name and optional description.

![Name & description](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/events/contracts/name-description.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=649fbdf59fa1355a8dd9777e59c1ee93)

4. Click **Create domain**.

## Manage domain sources

![Add sources button](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/events/contracts/add-sources-button.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=0cd2c066d5be0ee9c436fa64c9c7d392)

From the domain detail page, select the Sources tab and click **Add sources** to choose the event sources this domain should monitor.

Hightouch will validate events coming from these sources against the event schemas defined in the domain.

A source can be attached to multiple domains. However, two domains that share a source can't declare the same event contract (matching name and type). Hightouch will prevent you from attaching a source, or creating an event contract, that would cause a conflict.

## Add an event contract

![New contract configuration](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/events/contracts/new-contract-config.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=b1e6544ab9c99432d431ae226e350faf)

To define an event contract within a domain:

1. Open your domain.
2. Click **Add event**.
3. Configure the event in the **Configuration** section:
   * **Type** (for example, `Track`)
   * **Name** — must exactly match the event name sent in your code (including capitalization and spacing).

To find events that are already flowing from your sources but aren't yet declared in a domain, go to **Event Collection → Event library**. From there, you can add an observed event to a domain directly.

### 1. Define the event schema

![New contract schema](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/events/contracts/schema.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=608ab100c34c9ba39a72fff797e91605)

When creating an event contract, the most important step is defining its **validation schema**.

Under **Schema**, define the structure of the event payload.

You can:

* Use the visual schema builder
* Toggle **Edit as JSON** to directly modify the schema
* Create multiple schema versions

Hightouch uses [JSON Schema Draft 7](https://json-schema.org/draft-07/json-schema-release-notes). This supports advanced validation, including [validating field values with regular expressions](https://json-schema.org/understanding-json-schema/reference/regular_expressions).

#### Define event properties

![Event properties](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/events/contracts/schema-properties.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=1f2a554331c8a238659e938ea1117c21)

Under **Properties**, you can:

* Add fields using **Add property**
* Set field types (for example, `String`, `Number`, `Array`)
* Mark fields as **Required**
* Define nested objects or array element types
* Import reusable components for use in the event schema

These rules determine whether an event is considered valid.

#### Configure context validation

![Context validation](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/events/contracts/schema-context.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=179390175bf5902323377a8552b11b0b)

Events include a `context` object, which contains metadata such as device information, page details, or SDK-provided fields.

Under **Context**, you can define validation rules for context fields.

#### Include built-in context fields

![Built-in context toggle](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/events/contracts/built-in-context-toggle.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=0a531a67b4a565be6dbf6f56edae6ae2)

Enable **Include built-in context fields** to automatically allow [standard SDK fields](https://docs.hightouch.com/events/event-spec.md#automatically-captured-fields) (like device info, page data, IP address, etc.) without having to define them manually.

If you define a context field that shares a name with a built-in one, your definition takes precedence.

#### Import components into the event schema

![Import components](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/events/contracts/import-components.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=f97fd036ab16e97f9468c0b5804f1755)

You can import [components](https://docs.hightouch.com/events/contracts/management.md#add-a-component) into event schemas to reuse their schemas in multiple events. You can import components in two ways:

* **Add component** button: Import all fields from a component for use at the top level of the event schema.
* **Component** property type: Use a component as the type (similar to `Object`) for a specific property in the event schema.

Components can be imported even if they live in a different domain.

### 2. Manage schema versions

Contracts support **multiple versions of the same event schema**.

Versioning is useful when it is difficult to migrate your codebase to use the latest payload. For example, when an iOS app takes a while to be updated across all devices.

After creating your first event contract, you can create additional versions of the
schema. The first version is the "default" version, which applies to events that
do not specify a version in the payload. It is recommended that your events
follow an incrementing pattern (for example, v1, v2, v3), although not strictly
required.

In the event detail page, you can:

* Create a new version using the **Add version** button in the version dropdown
* Switch between versions using the version dropdown (for example, `v2`, `default`)
* Edit versions independently

  ![Event versioning screenshot](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/events/contracts/editing-versions.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=0b95c8c5cb49b781f17ad9636fa8dd13)

When invoking an event, you can specify the schema version via:

```
client.track('Order Completed', {
  ...
}, {
  context: {
    htevents: {
      schemaVersion: "v2"
    }
  }
});
```

### 3. Enforcement behavior for fields

![Enforcement settings](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/events/contracts/enforcement-settings.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=553d59e7210fddf636b7918b17c24b93)

You can define what happens when an event contains:

* **Undeclared properties** (fields not defined in the schema)
* **Invalid fields** (missing required fields or incorrect types)

#### Undeclared fields

For undeclared fields within an event, you can choose:

* **Allow** — Sync the event with a warning.
* **Filter** — Sync the event but remove undeclared fields.
* **Block** — Prevent the event from syncing.

#### Invalid fields

For invalid fields, you can choose:

* **Allow** — Sync the event with a warning.
* **Block** — Prevent the event from syncing.

These settings apply to both event properties and context fields.

## Add a component

![New component](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/events/contracts/add-component-button.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=c7004dc5c4651ed26f30dd72c8891c65)

To define a component within a domain:

1. Open your domain and select the **Components** tab.
2. Click **Add component**.
3. Configure the component in the **Configuration** section:
   * **Name** — a descriptive name for the component. This doesn't have to match any property names in the event schema(s) that import the component.

### 1. Define the component schema

![Component schema](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/events/contracts/component-schema.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=77fb2c740b50700e05c4aed2b2448355)

Under **Schema**, define the structure of the component payload. This works exactly like [defining an event schema](#1-define-the-event-schema).

You can also import other components into the component schema. Hightouch warns you if any component imports cause a circular dependency.

### 2. Manage component versions

![Component versioning](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/events/contracts/component-versioning.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=935d89f69544620e7ffc547228ae102c)

Components support **multiple versions of the same schema**.

Unlike event schema versions, component versions aren't selected from the event payload. When you import a component into a schema, the import is pinned to a specific version of that component. Schemas that pin an older version continue to validate against it until you update the import to point to a newer version.

Versioning is useful when you want to evolve a component's schema without immediately updating every event that uses it.

After creating a component, you can create additional versions of the schema using the **Add version** button. The first version is named "default." It's recommended that your components follow an incrementing pattern (for example, v1, v2, v3), although not strictly required.

### 3. Manage component sources

By default, components will apply to all event sources in the domain they are used in. However, you can limit components to specific event sources by clicking the **Edit sources** button in the component detail page.

![Edit component sources button](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/events/contracts/edit-component-sources-button.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=3acde14abd774125bd1ae319c960709b)

From here, you can select **All sources** or **Specific sources**.

![Select component sources](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/events/contracts/select-component-sources.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=6b0158c6ef471ac2c7c3313490787d96)

Components that are applied to specific event sources will only be used when events are synced from those sources. Otherwise, their fields will be considered undeclared, and will be ignored or treated as invalid, depending on the [enforcement behavior](#3-enforcement-behavior-for-fields) you have configured for the event.