Core Concepts

Schema Definitions

The schema section is the backbone of every contract. It defines each field: its name, data type, nullability, constraints, and optional documentation. ContractHQ validates your live warehouse columns against this definition on every run.

Basic Field Definition

Each entry under schema is a YAML list item with at minimum a name and a type:

contract.yml

schema:
  - name: user_id
    type: uuid
    description: Unique identifier for the user.
    required: true
    pii: false

Scalar Types

Type	Description	Example value
string	UTF-8 text of any length.	"hello"
integer	Whole numbers (64-bit signed).	42
float	IEEE 754 double-precision numbers.	3.14
boolean	true or false.	true
date	Calendar date (ISO 8601 YYYY-MM-DD).	"2024-01-15"
timestamp	Date + time with optional timezone.	"2024-01-15T12:00:00Z"
uuid	RFC 4122 universally unique identifier.	"550e8400-..."
json	Arbitrary JSON blob (schema optional).	{"key":"val"}

Constraints

Add a constraints list to each field to enforce data quality rules at the column level:

contract.yml

- name: email
  type: string
  constraints:
    - not_null: true
    - unique: true
    - pattern: "^[\\w.]+@[\\w]+\\.[\\w]+$"
    - max_length: 255

Constraint	Applies to	Description
not_null	all	Column must have no NULL values.
unique	all	All values must be distinct.
pattern	string	Values must match a regex pattern.
min_length	string	Minimum character length.
max_length	string	Maximum character length.
minimum	integer, float	Minimum numeric value (inclusive).
maximum	integer, float	Maximum numeric value (inclusive).
allowed_values	string, integer	Enumerated list of permitted values.

Nested Objects

For json or struct-typed columns, use fields to recursively define the nested schema:

contract.yml

- name: address
  type: json
  fields:
    - name: street
      type: string
    - name: city
      type: string
    - name: postcode
      type: string
      constraints:
        - pattern: "^[A-Z]{2}\\d{1,2}.*"

Arrays

Mark a field as an array using array: true. Combine with items to constrain each element:

contract.yml

- name: tags
  type: string
  array: true
  items:
    constraints:
      - max_length: 50
      - allowed_values: [finance, engineering, product, marketing]

💡

Add pii: true to any field containing personally identifiable information. ContractHQ will flag PII fields in the registry UI and exclude them from sample data previews.

← What is a Data Contract?Data Quality Checks →