Templates

Source-Aligned Events

Data Contract Template

Ensure data from source-aligned event streams is fresh, complete, and reliable before it is used for product analytics, user engagement tracking, and marketplace performance measurement.

Data contract description

This data contract is designed for Adevinta Spain, where source-aligned data products form the bronze layer of a medallion architecture, governing raw event streams from the moment they are ingested. The event_data dataset captures clickstream interactions — such as job_viewed, apply_clicked, and search_performed — across Adevinta Spain's marketplace platforms, with a one-hour freshness expectation on ingest_time and enum-level constraints on event names, platforms, entity types, and action outcomes. The contract helps keep event telemetry trustworthy and reusable for downstream analytics across its marketplace ecosystem.

Dataset

Defines the dataset this contract applies to, including its source and scope. This is the single point of reference for what data is being validated and protected.

Dataset checks

Validations that apply to the dataset as a whole, including schema stability, data freshness, and overall structural guarantees. This contract includes a schema check that prevents unexpected columns and unexpected column reordering, a row count check to ensure the dataset is not empty, and a freshness check that requires data to be less than one hour old based on ingest_time.

Column checks

Column-level rules that define required fields, uniqueness, allowed formats, and value constraints for individual attributes. This contract enforces that event_id, event_name, event_time, ingest_time, session_id, entity_type, entity_id, and action_result are not missing, and it requires event_id to be unique. It restricts event_name to approved product events, platform to approved platform values, entity_type to approved entity categories, and action_result to approved outcomes. It also applies length guardrails to key identifiers and version-related fields, including event_id, user_id, anonymous_id, session_id, app_version, and entity_id. Also, user_id, anonymous_id, platform, and app_version are constrained when present, but this contract does not require them to be populated.

source_aligned_event_data_contract.yaml

dataset

variables:
  CONTRACT_NAME:
    default: "event_data"
  CONTRACT_VERSION:
    default: "1"
  DESCRIPTION:
    default: "Product and event analytics data for consumer internet / marketplace platforms."
  START_DATE:
    default: "2024-01-01T00:00:00+00:00"
  SCHEMA_SOURCE:
    default: "url"
  SCHEMA_LOCATION_URL:
    default: "https://github.com/adevinta/event-schemas/event_data_v1.json"
  SCHEMA_FORMAT:
    default: "jsonSchema"
  SCHEMA_VERSION:
    default: "1.0"
  LANDING_SOURCE:
    default: "pub.mytopic"
  SDRN:
    default: "@client.@id"
  RELATION_KEY:
    default: "event_id"

checks:
  - schema:
      allow_extra_columns: false
      allow_other_column_order: false
  - row_count:
      threshold:
        must_be_greater_than: 0
  - freshness:
      column: ingest_time
      threshold:
        unit: hour
        must_be_less_than: 1

columns:
  - name: event_id
    data_type: string
    checks:
      - missing:
      - duplicate:
      - invalid:
          name: "Event ID length guardrail"
          valid_min_length: 1
          valid_max_length: 128
  - name: event_name
    data_type: string
    checks:
      - missing:
      - invalid:
          name: "Valid event names"
          valid_values:
            - job_viewed
            - apply_clicked
            - review_submitted
            - comment_posted
            - search_performed
  - name: event_time
    data_type: timestamp
    checks:
      - missing:
  - name: ingest_time
    data_type: timestamp
    checks:
      - missing:
  - name: user_id
    data_type: string
    checks:
      - invalid:
          name: "User ID length guardrail"
          valid_min_length: 1
          valid_max_length: 128
  - name: anonymous_id
    data_type: string
    checks:
      - invalid:
          name: "Anonymous ID length guardrail"
          valid_min_length: 1
          valid_max_length: 128
  - name: session_id
    data_type: string
    checks:
      - missing:
      - invalid:
          name: "Session ID length guardrail"
          valid_min_length: 1
          valid_max_length: 128
  - name: platform
    data_type: string
    checks:
      - invalid:
          name: "Valid platforms"
          valid_values:
            - web
            - ios
            - android
            - backend
  - name: app_version
    data_type: string
    checks:
      - invalid:
          name: "App version length guardrail"
          valid_min_length: 1
          valid_max_length: 64
  - name: entity_type
    data_type: string
    checks:
      - missing:
      - invalid:
          name: "Valid entity types"
          valid_values:
            - job
            - company
            - review
            - post
            - comment
            - message
  - name: entity_id
    data_type: string
    checks:
      - missing:
      - invalid:
          name: "Entity ID length guardrail"
          valid_min_length: 1
          valid_max_length: 128
  - name: action_result
    data_type: string
    checks:
      - missing:
      - invalid:
          name: "Valid action results"
          valid_values

Data contract description

Dataset

Defines the dataset this contract applies to, including its source and scope. This is the single point of reference for what data is being validated and protected.

Dataset checks

Column checks

source_aligned_event_data_contract.yaml

dataset

variables:
  CONTRACT_NAME:
    default: "event_data"
  CONTRACT_VERSION:
    default: "1"
  DESCRIPTION:
    default: "Product and event analytics data for consumer internet / marketplace platforms."
  START_DATE:
    default: "2024-01-01T00:00:00+00:00"
  SCHEMA_SOURCE:
    default: "url"
  SCHEMA_LOCATION_URL:
    default: "https://github.com/adevinta/event-schemas/event_data_v1.json"
  SCHEMA_FORMAT:
    default: "jsonSchema"
  SCHEMA_VERSION:
    default: "1.0"
  LANDING_SOURCE:
    default: "pub.mytopic"
  SDRN:
    default: "@client.@id"
  RELATION_KEY:
    default: "event_id"

checks:
  - schema:
      allow_extra_columns: false
      allow_other_column_order: false
  - row_count:
      threshold:
        must_be_greater_than: 0
  - freshness:
      column: ingest_time
      threshold:
        unit: hour
        must_be_less_than: 1

columns:
  - name: event_id
    data_type: string
    checks:
      - missing:
      - duplicate:
      - invalid:
          name: "Event ID length guardrail"
          valid_min_length: 1
          valid_max_length: 128
  - name: event_name
    data_type: string
    checks:
      - missing:
      - invalid:
          name: "Valid event names"
          valid_values:
            - job_viewed
            - apply_clicked
            - review_submitted
            - comment_posted
            - search_performed
  - name: event_time
    data_type: timestamp
    checks:
      - missing:
  - name: ingest_time
    data_type: timestamp
    checks:
      - missing:
  - name: user_id
    data_type: string
    checks:
      - invalid:
          name: "User ID length guardrail"
          valid_min_length: 1
          valid_max_length: 128
  - name: anonymous_id
    data_type: string
    checks:
      - invalid:
          name: "Anonymous ID length guardrail"
          valid_min_length: 1
          valid_max_length: 128
  - name: session_id
    data_type: string
    checks:
      - missing:
      - invalid:
          name: "Session ID length guardrail"
          valid_min_length: 1
          valid_max_length: 128
  - name: platform
    data_type: string
    checks:
      - invalid:
          name: "Valid platforms"
          valid_values:
            - web
            - ios
            - android
            - backend
  - name: app_version
    data_type: string
    checks:
      - invalid:
          name: "App version length guardrail"
          valid_min_length: 1
          valid_max_length: 64
  - name: entity_type
    data_type: string
    checks:
      - missing:
      - invalid:
          name: "Valid entity types"
          valid_values:
            - job
            - company
            - review
            - post
            - comment
            - message
  - name: entity_id
    data_type: string
    checks:
      - missing:
      - invalid:
          name: "Entity ID length guardrail"
          valid_min_length: 1
          valid_max_length: 128
  - name: action_result
    data_type: string
    checks:
      - missing:
      - invalid:
          name: "Valid action results"
          valid_values

Data contract description

source_aligned_event_data_contract.yaml

dataset

variables:
  CONTRACT_NAME:
    default: "event_data"
  CONTRACT_VERSION:
    default: "1"
  DESCRIPTION:
    default: "Product and event analytics data for consumer internet / marketplace platforms."
  START_DATE:
    default: "2024-01-01T00:00:00+00:00"
  SCHEMA_SOURCE:
    default: "url"
  SCHEMA_LOCATION_URL:
    default: "https://github.com/adevinta/event-schemas/event_data_v1.json"
  SCHEMA_FORMAT:
    default: "jsonSchema"
  SCHEMA_VERSION:
    default: "1.0"
  LANDING_SOURCE:
    default: "pub.mytopic"
  SDRN:
    default: "@client.@id"
  RELATION_KEY:
    default: "event_id"

checks:
  - schema:
      allow_extra_columns: false
      allow_other_column_order: false
  - row_count:
      threshold:
        must_be_greater_than: 0
  - freshness:
      column: ingest_time
      threshold:
        unit: hour
        must_be_less_than: 1

columns:
  - name: event_id
    data_type: string
    checks:
      - missing:
      - duplicate:
      - invalid:
          name: "Event ID length guardrail"
          valid_min_length: 1
          valid_max_length: 128
  - name: event_name
    data_type: string
    checks:
      - missing:
      - invalid:
          name: "Valid event names"
          valid_values:
            - job_viewed
            - apply_clicked
            - review_submitted
            - comment_posted
            - search_performed
  - name: event_time
    data_type: timestamp
    checks:
      - missing:
  - name: ingest_time
    data_type: timestamp
    checks:
      - missing:
  - name: user_id
    data_type: string
    checks:
      - invalid:
          name: "User ID length guardrail"
          valid_min_length: 1
          valid_max_length: 128
  - name: anonymous_id
    data_type: string
    checks:
      - invalid:
          name: "Anonymous ID length guardrail"
          valid_min_length: 1
          valid_max_length: 128
  - name: session_id
    data_type: string
    checks:
      - missing:
      - invalid:
          name: "Session ID length guardrail"
          valid_min_length: 1
          valid_max_length: 128
  - name: platform
    data_type: string
    checks:
      - invalid:
          name: "Valid platforms"
          valid_values:
            - web
            - ios
            - android
            - backend
  - name: app_version
    data_type: string
    checks:
      - invalid:
          name: "App version length guardrail"
          valid_min_length: 1
          valid_max_length: 64
  - name: entity_type
    data_type: string
    checks:
      - missing:
      - invalid:
          name: "Valid entity types"
          valid_values:
            - job
            - company
            - review
            - post
            - comment
            - message
  - name: entity_id
    data_type: string
    checks:
      - missing:
      - invalid:
          name: "Entity ID length guardrail"
          valid_min_length: 1
          valid_max_length: 128
  - name: action_result
    data_type: string
    checks:
      - missing:
      - invalid:
          name: "Valid action results"
          valid_values

How to Enforce Data Contracts with Soda

Embed data quality through data contracts at any point in your pipeline.

# pip install soda-{data source} for other data sources

pip install soda-postgres

# verify the contract locally against a data source

soda contract verify -c contract.yml -ds ds_config.yml

# publish and schedule the contract with Soda Cloud

soda contract publish -c contract.yml -sc sc_config.yml

Check out the CLI documentation to learn more.

How to Automatically Create Data Contracts.
In one Click.

Automatically write and publish data contracts using Soda's AI-powered data contract copilot.

Make data contracts work in production

Business knows what good data looks like. Engineering knows how to deliver it at scale. Soda unites both, turning governance expectations into executable contracts.

Book a demo