undefined - DriftOps Docs

Contracts

A contract is a stored schema definition. It represents the expected structure of a document: field names, nesting, and types.

When you upload a JSON or EDI file to create a contract, DriftOps extracts the schema structure and saves it. That saved structure becomes the baseline for all future comparisons.

Contracts support:

Versioning - every schema change is saved as a new version. You can view the full history and revert to any previous version.
Tags - categorize by vendor, document type, or environment for filtering.
Vendor - a quick label for grouping contracts by trading partner.

Supported formats: JSON, EDI X12, XML, and flat-field key-value structures.

Comparisons

A comparison takes two inputs (source and target), diffs them field by field, and produces a report.

The comparison result contains four change categories:

added

Fields present in target but not in source.

removed

Fields present in source but missing in target.

changed

Fields present in both but with different types or structure.

renamed

Fields DriftOps infers were renamed based on similarity scoring.

Severity is assigned automatically:

trivialOnly additions. Backward compatible.

minorRenames or value changes. No fields removed.

majorAny removals or type changes. Breaking.

Comparisons linked to a contract create a drift event. Unlinked comparisons (no contract selected) produce a diff report only and do not create events.

Drift Events

A drift event is the permanent record of a comparison that found differences.

Each event has:

Source and target file names
Full diff report with all change details
Counts: additions, removals, changes, renames
Severity: trivial, minor, or major
Status: pending, resolved, ignored, or rejected

Status transitions:

pending

Default. Requires review.

resolved

Accepted. Optionally updates contract.

ignored

Acknowledged. No action.

rejected

Flagged invalid or unexpected.

Drift events appear in the Drift Inbox and can be filtered by status, severity, contract, or date range.

Monitors

A monitor is a webhook endpoint linked to a contract. It is how external systems push files into DriftOps for automated comparison.

Each monitor gets a unique token that forms its URL:

POST https://api.driftops.io/api/webhook/{token}

When a file is POSTed to that URL:

DriftOps validates the file (size, type, content).
It parses the file into a schema structure.
It runs a comparison against the linked contract.
If differences are found, a drift event is created.
If Slack is configured, a notification is sent.

Monitors are useful when your pipeline or trading partner controls when files are sent. If you need DriftOps to pull files on a schedule instead, use a Cloud Connection.

Cloud Connections

A cloud connection polls a storage bucket or server on a schedule and processes any new files it finds.

Supported sources:

AWS S3
Azure Blob Storage
Google Cloud Storage
MinIO (S3-compatible)
SFTP
FTP

Each connection stores credentials encrypted with Fernet symmetric encryption. Credentials are never returned in API responses.

Configuration options:

bucket_name / container

Where to look for files.

prefix

Optional path prefix to scope the watch.

file_pattern

Glob pattern, e.g. *.json or invoices/*.edi

poll_interval_minutes

How often to check. Default: 60 minutes.

Health tracking monitors consecutive failures and marks a connection as warning or critical when polling breaks.

Roles

Users within an organization have one of three roles:

Role	Contracts	Drift Events	Monitors	Users	Billing
`viewer`	read	read	read	-	-
`editor`	create, read, update	read, resolve, ignore	create, read, update	-	-
`admin`	full	full	full	invite, remove	read, manage

Roles are scoped to an organization. A user can be an admin in one org and a viewer in another.

Getting Started

Features