Templates

Fraud Detection ML Scores

Data Contract Template

Ensure Fraud Detection ML Scores data is fresh, accurate, and reliable before it’s used for real-time fraud decisions, case management, and downstream analytics.

Data contract description

This data contract enforces schema stability, a strict 1-hour freshness SLA based on scored_at, and required identifiers and model metadata to ensure trustworthy fraud scoring outputs. It prevents future-dated scores, blocks duplicate scores per transaction and model, validates fraud_score ranges and prediction label values, and enforces consistency between fraud_score and prediction_label thresholds. It also applies controlled formats for transaction IDs, semantic model versions, and feature hashes. Together, these checks reduce the risk of stale or malformed model outputs driving incorrect fraud actions, improve traceability across model versions, and protect downstream fraud monitoring, alerting, and reporting.

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, such as schema stability, freshness SLAs, and overall structural guarantees. This contract includes a schema check to detect unexpected structural changes, a row count check to prevent empty scoring loads, and a 1-hour freshness check based on scored_at to ensure scores remain timely for operational decisioning. It also blocks future-dated scoring events, enforces that fraud_score remains within the expected [0,1] range, prevents duplicate scores per transaction and model, and validates alignment between score thresholds and prediction labels—helping ensure consistent decision logic and reliable alerting.

Column checks

Column-level rules that define required fields, data types, allowed formats, and constraints for individual attributes. This contract enforces that transaction_id, model_id, model_version, fraud_score, prediction_label, scored_at, and feature_hash are not missing. It validates transaction_id as a UUID, constrains model identifiers and versions (including semantic version format), ensures fraud_score is bounded between 0 and 1, restricts prediction_label to approved values, and validates feature_hash as a SHA-256 hex string. These controls improve model output quality, support traceability and reproducibility, and reduce downstream failures caused by malformed identifiers or inconsistent scoring metadata.

fraud_scores_data_contract.yaml

dataset: datasource/db/schema/fraud_scores

variables:
  FRESHNESS_HOURS:
    default: 1

checks:
  - schema:
      allow_extra_columns: false
      allow_other_column_order: false
  - row_count:
      threshold:
        must_be_greater_than: 0
  - freshness:
      column: scored_at
      threshold:
        unit: hour
        must_be_less_than_or_equal: ${var.FRESHNESS_HOURS}
  - failed_rows:
      name: "scored_at must not be in the future"
      qualifier: scored_at_not_future
      expression: scored_at > ${soda.NOW}
  - failed_rows:
      name: "fraud_score must be between 0 and 1"
      qualifier: score_range
      expression: fraud_score < 0.0 OR fraud_score > 1.0
  - failed_rows:
      name: "No duplicate scores per transaction per model"
      qualifier: dup_txn_model
      query: |
        SELECT transaction_id, model_id
        FROM datasource.db.schema.fraud_scores
        GROUP BY transaction_id, model_id
        HAVING COUNT(*) > 1
      threshold:
        must_be: 0
  - failed_rows:
      name: "prediction_label must align with fraud_score threshold"
      qualifier: label_score_alignment
      expression: >
        (prediction_label = 'FRAUD' AND fraud_score < 0.5)
        OR (prediction_label = 'LEGIT' AND fraud_score > 0.9)

columns:
  - name: transaction_id
    data_type: string
    checks:
      - missing:
          name: No missing values
      - invalid:
          name: "transaction_id must be a UUID"
          valid_format:
            name: UUID
            regex: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  - name: model_id
    data_type: string
    checks:
      - missing:
          name: No missing values
      - invalid:
          name: "model_id length guardrail"
          valid_min_length: 1
          valid_max_length: 64
  - name: model_version
    data_type: string
    checks:
      - missing:
          name: No missing values
      - invalid:
          name: "Semantic version format (e.g. 1.2.3)"
          valid_format:
            name: semver
            regex: "^\\d+\\.\\d+\\.\\d+$"
  - name: fraud_score
    data_type: decimal
    checks:
      - missing:
          name: No missing values
      - invalid:
          name: "Score must be between 0 and 1"
          valid_min: 0.0
          valid_max: 1.0
  - name: prediction_label
    data_type: string
    checks:
      - missing:
          name: No missing values
      - invalid:
          name: "Allowed prediction labels"
          valid_values:
            - LEGIT
            - SUSPICIOUS
            - FRAUD
  - name: scored_at
    data_type: timestamp
    checks:
      - missing:
          name: No missing values
  - name: feature_hash
    data_type: string
    checks:
      - missing:
          name: No missing values
      - invalid:
          name: "feature_hash must be a valid SHA-256 hex string"
          valid_format:
            name: SHA-256 hash
            regex: "^[a-fA-F0-9]{64}$"

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

fraud_scores_data_contract.yaml

dataset: datasource/db/schema/fraud_scores

variables:
  FRESHNESS_HOURS:
    default: 1

checks:
  - schema:
      allow_extra_columns: false
      allow_other_column_order: false
  - row_count:
      threshold:
        must_be_greater_than: 0
  - freshness:
      column: scored_at
      threshold:
        unit: hour
        must_be_less_than_or_equal: ${var.FRESHNESS_HOURS}
  - failed_rows:
      name: "scored_at must not be in the future"
      qualifier: scored_at_not_future
      expression: scored_at > ${soda.NOW}
  - failed_rows:
      name: "fraud_score must be between 0 and 1"
      qualifier: score_range
      expression: fraud_score < 0.0 OR fraud_score > 1.0
  - failed_rows:
      name: "No duplicate scores per transaction per model"
      qualifier: dup_txn_model
      query: |
        SELECT transaction_id, model_id
        FROM datasource.db.schema.fraud_scores
        GROUP BY transaction_id, model_id
        HAVING COUNT(*) > 1
      threshold:
        must_be: 0
  - failed_rows:
      name: "prediction_label must align with fraud_score threshold"
      qualifier: label_score_alignment
      expression: >
        (prediction_label = 'FRAUD' AND fraud_score < 0.5)
        OR (prediction_label = 'LEGIT' AND fraud_score > 0.9)

columns:
  - name: transaction_id
    data_type: string
    checks:
      - missing:
          name: No missing values
      - invalid:
          name: "transaction_id must be a UUID"
          valid_format:
            name: UUID
            regex: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  - name: model_id
    data_type: string
    checks:
      - missing:
          name: No missing values
      - invalid:
          name: "model_id length guardrail"
          valid_min_length: 1
          valid_max_length: 64
  - name: model_version
    data_type: string
    checks:
      - missing:
          name: No missing values
      - invalid:
          name: "Semantic version format (e.g. 1.2.3)"
          valid_format:
            name: semver
            regex: "^\\d+\\.\\d+\\.\\d+$"
  - name: fraud_score
    data_type: decimal
    checks:
      - missing:
          name: No missing values
      - invalid:
          name: "Score must be between 0 and 1"
          valid_min: 0.0
          valid_max: 1.0
  - name: prediction_label
    data_type: string
    checks:
      - missing:
          name: No missing values
      - invalid:
          name: "Allowed prediction labels"
          valid_values:
            - LEGIT
            - SUSPICIOUS
            - FRAUD
  - name: scored_at
    data_type: timestamp
    checks:
      - missing:
          name: No missing values
  - name: feature_hash
    data_type: string
    checks:
      - missing:
          name: No missing values
      - invalid:
          name: "feature_hash must be a valid SHA-256 hex string"
          valid_format:
            name: SHA-256 hash
            regex: "^[a-fA-F0-9]{64}$"

Data contract description

fraud_scores_data_contract.yaml

dataset: datasource/db/schema/fraud_scores

variables:
  FRESHNESS_HOURS:
    default: 1

checks:
  - schema:
      allow_extra_columns: false
      allow_other_column_order: false
  - row_count:
      threshold:
        must_be_greater_than: 0
  - freshness:
      column: scored_at
      threshold:
        unit: hour
        must_be_less_than_or_equal: ${var.FRESHNESS_HOURS}
  - failed_rows:
      name: "scored_at must not be in the future"
      qualifier: scored_at_not_future
      expression: scored_at > ${soda.NOW}
  - failed_rows:
      name: "fraud_score must be between 0 and 1"
      qualifier: score_range
      expression: fraud_score < 0.0 OR fraud_score > 1.0
  - failed_rows:
      name: "No duplicate scores per transaction per model"
      qualifier: dup_txn_model
      query: |
        SELECT transaction_id, model_id
        FROM datasource.db.schema.fraud_scores
        GROUP BY transaction_id, model_id
        HAVING COUNT(*) > 1
      threshold:
        must_be: 0
  - failed_rows:
      name: "prediction_label must align with fraud_score threshold"
      qualifier: label_score_alignment
      expression: >
        (prediction_label = 'FRAUD' AND fraud_score < 0.5)
        OR (prediction_label = 'LEGIT' AND fraud_score > 0.9)

columns:
  - name: transaction_id
    data_type: string
    checks:
      - missing:
          name: No missing values
      - invalid:
          name: "transaction_id must be a UUID"
          valid_format:
            name: UUID
            regex: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  - name: model_id
    data_type: string
    checks:
      - missing:
          name: No missing values
      - invalid:
          name: "model_id length guardrail"
          valid_min_length: 1
          valid_max_length: 64
  - name: model_version
    data_type: string
    checks:
      - missing:
          name: No missing values
      - invalid:
          name: "Semantic version format (e.g. 1.2.3)"
          valid_format:
            name: semver
            regex: "^\\d+\\.\\d+\\.\\d+$"
  - name: fraud_score
    data_type: decimal
    checks:
      - missing:
          name: No missing values
      - invalid:
          name: "Score must be between 0 and 1"
          valid_min: 0.0
          valid_max: 1.0
  - name: prediction_label
    data_type: string
    checks:
      - missing:
          name: No missing values
      - invalid:
          name: "Allowed prediction labels"
          valid_values:
            - LEGIT
            - SUSPICIOUS
            - FRAUD
  - name: scored_at
    data_type: timestamp
    checks:
      - missing:
          name: No missing values
  - name: feature_hash
    data_type: string
    checks:
      - missing:
          name: No missing values
      - invalid:
          name: "feature_hash must be a valid SHA-256 hex string"
          valid_format:
            name: SHA-256 hash
            regex: "^[a-fA-F0-9]{64}$"

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