Manage contracts

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.

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 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 and import it 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.

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. 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

To create a new domain:

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

4. Click Create domain.

Manage domain sources

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

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

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. This supports advanced validation, including validating field values with regular expressions.

Define event properties

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

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

Enable Include built-in context fields to automatically allow standard SDK 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

You can import components 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

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

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

3. Enforcement behavior for fields

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

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

Under Schema, define the structure of the component payload. This works exactly like defining an 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

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.

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

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 you have configured for the event.