Expectations

Expectations let your Files.com site define what “correct” file delivery looks like, continuously evaluate whether it happened, and keep history when it did not.

Expectations are meant to answer operational questions like:

Did the expected file arrive?
Was it on time?
Did it meet the required shape and count rules?
Is there an active issue someone needs to acknowledge?

Expectations are different from Automations and Syncs. Automations and Syncs act on files; Expectations monitor whether expected files arrived on time, in the right place, and in the right shape. In practice, Expectations are the sensor and Automations are the actuator.

An Expectation combines four concepts:

Scope: where to look for candidate files, using path, source, and optional exclude_pattern.
Trigger / timing: when a window opens and how long it stays eligible, using trigger, schedule fields, lookback_interval, late_acceptance_interval, inactivity_interval, and max_open_interval.
Criteria: what must be true for the window to succeed, using the structured criteria JSON document.
Outcome history: what happened over time, exposed through ExpectationEvaluation history and ExpectationIncident lifecycle records.

Scope and matching

Expectations reuse the familiar Files.com path-plus-glob model.

The path field identifies the folder scope, while source identifies which files within that scope are candidates. exclude_pattern removes files from consideration.

Like Automations, these fields support glob-style matching. Expectations treat those matches as one logical candidate set for each window. A single Expectation does not implicitly fan out into separate per-customer or per-folder evaluations just because the path contains wildcards.

Expectation windows

Expectations are evaluated in windows.

Each window is persisted as an ExpectationEvaluation record. A window opens, remains open while evidence can still arrive, and then closes into a terminal result such as success, late, missing, or invalid.

An Expectation has only one open window at a time.

Trigger modes

Expectations can open windows in three ways:

daily: run on a recurring daily/weekly/monthly/quarterly/yearly cadence using interval and either recurring_day or recurring_days.
custom_schedule: run using either the reusable Site-level Schedule selected by schedule_id or specific weekdays and times stored on the Expectation.
manual: an operator explicitly opens the window.

Schedule-driven expectations define an on-time deadline and may optionally remain eligible to close as late during late_acceptance_interval.

Manual expectations have no concept of late; they open when triggered and close based on inactivity or hard-stop timing.

Success criteria

The criteria field is a structured JSON object describing what counts as success for the window.

Criteria v1 can express things like:

file count constraints
total byte constraints
allowed extensions
filename regex validation
forbidden files
required named or globbed files with their own per-file constraints

Criteria v2 adds content_validation, which runs a customer-authored Files Transform Script in either per_file or whole_batch mode. Per-file scripts receive the file contents parsed by FTS as payload. Whole-batch scripts receive an array of file objects containing path, name, size, last_modified_at, and each file's parsed payload.

A content-validation script returns true or { success: true } to pass. It returns false or { success: false, errors: [...] } to fail. Error entries may be strings or structured objects with values such as message, field, row, expected, and actual; these details are preserved in readable form in the Evaluation's criteria_errors. Script, parsing, download, and size-limit errors also fail the criterion. Each file is limited to 100 MB, and whole-batch mode additionally limits the combined raw input to 100 MB.

Required file rule keys may also include standard strftime-style date/time tokens like %Y, %m, and %d. Those tokens are resolved at evaluation time using a stable window anchor: schedule-driven expectations use the window's deadline_at, while manual and upload expectations use the window's opened_at.

History and incidents

The Expectation itself stores summary state like last_evaluated_at, last_success_at, last_failure_at, and last_result.

For deeper inspection:

ExpectationEvaluation history shows each open or closed window and the evidence captured for it.
ExpectationIncident records track ongoing failure situations over time, including acknowledge, snooze, and resolve actions.

Manual windows do not open incidents in v1. Schedule-driven failures can open incidents, and later qualifying success can resolve them.

Resource Schema

Optional

Property	Description
workspace_id Int64	Workspace ID. `0` means the default workspace.
name String	Expectation name.
description String	Expectation description.
path String	Path scope for the expectation. Supports workspace-relative presentation. This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
source String	Source glob used to select candidate files.
exclude_pattern String	Optional source exclusion glob.
disabled Bool	If true, the expectation is disabled.
trigger String	How this expectation opens windows. Possible values: `manual`, `upload`, `daily`, `custom_schedule`
interval String	If trigger is `daily`, this specifies how often to run the expectation.
recurring_day Int64	If trigger is `daily`, this selects the day number inside the chosen interval.
recurring_days List	If trigger is `daily`, this selects one or more day numbers inside a `week`, `month`, `quarter`, or `year` interval.
schedule_id Int64	If trigger is `custom_schedule`, the reusable Schedule used instead of the Expectation's schedule fields.
schedule_days_of_week List	If trigger is `custom_schedule`, the 0-based weekdays used by the schedule.
schedule_times_of_day List	Times of day in HH:MM format for the Expectation schedule.
schedule_time_zone String	Time zone used by the Expectation schedule.
holiday_region String	Optional holiday region used by the Expectation schedule.
lookback_interval Int64	How many seconds before the due boundary the window starts.
late_acceptance_interval Int64	How many seconds a schedule-driven window may remain eligible to close as late.
inactivity_interval Int64	How many quiet seconds are required before final closure.
max_open_interval Int64	Hard-stop duration in seconds for unscheduled expectations.
criteria Dynamic	Versioned success criteria definition for the expectation. Criteria v2 supports optional FTS content validation.

Read Only

Property	Description
id Int64	Expectation ID
expectations_version Int64	Criteria schema version for this expectation.
last_evaluated_at String	Last time this expectation was evaluated.
last_success_at String	Last time this expectation closed successfully.
last_failure_at String	Last time this expectation closed with a failure result.
last_result String	Most recent terminal result for this expectation. Possible values: `success`, `late`, `missing`, `invalid`
created_at String	Creation time.
updated_at String	Last update time.

Example Resource

resource "files_expectation" "example_expectation" {
  name                     = "Daily Vendor Feed"
  description              = "Wait for the vendor CSV every morning."
  path                     = "incoming/vendor_a"
  source                   = "*.csv"
  exclude_pattern          = "*.tmp"
  disabled                 = true
  trigger                  = "manual"
  interval                 = "day"
  recurring_day            = 3
  recurring_days           = [1, 15]
  schedule_id              = 1
  schedule_days_of_week    = [1, 3, 5]
  schedule_times_of_day    = ["06:00"]
  schedule_time_zone       = "UTC"
  holiday_region           = "us"
  lookback_interval        = 3600
  late_acceptance_interval = 900
  inactivity_interval      = 300
  max_open_interval        = 43200
  criteria                 = {
    count      = {
      exact = 1
    }
    extensions = ["csv"]
  }
  workspace_id             = 0
}

Resource Import

This Resource supports importing using the following syntax:

Example Import Command

# Expectations can be imported by specifying the id.
terraform import files_expectation.example_expectation 1

Data Source Schema

Required

Property	Description
id Int64	Expectation ID

Read Only

Property	Description
workspace_id Int64	Workspace ID. `0` means the default workspace.
name String	Expectation name.
description String	Expectation description.
path String	Path scope for the expectation. Supports workspace-relative presentation. This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
source String	Source glob used to select candidate files.
exclude_pattern String	Optional source exclusion glob.
disabled Bool	If true, the expectation is disabled.
expectations_version Int64	Criteria schema version for this expectation.
trigger String	How this expectation opens windows. Possible values: `manual`, `upload`, `daily`, `custom_schedule`
interval String	If trigger is `daily`, this specifies how often to run the expectation.
recurring_day Int64	If trigger is `daily`, this selects the day number inside the chosen interval.
recurring_days List	If trigger is `daily`, this selects one or more day numbers inside a `week`, `month`, `quarter`, or `year` interval.
schedule_id Int64	If trigger is `custom_schedule`, the reusable Schedule used instead of the Expectation's schedule fields.
schedule_days_of_week List	If trigger is `custom_schedule`, the 0-based weekdays used by the schedule.
schedule_times_of_day List	Times of day in HH:MM format for the Expectation schedule.
schedule_time_zone String	Time zone used by the Expectation schedule.
holiday_region String	Optional holiday region used by the Expectation schedule.
lookback_interval Int64	How many seconds before the due boundary the window starts.
late_acceptance_interval Int64	How many seconds a schedule-driven window may remain eligible to close as late.
inactivity_interval Int64	How many quiet seconds are required before final closure.
max_open_interval Int64	Hard-stop duration in seconds for unscheduled expectations.
criteria Dynamic	Versioned success criteria definition for the expectation. Criteria v2 supports optional FTS content validation.
last_evaluated_at String	Last time this expectation was evaluated.
last_success_at String	Last time this expectation closed successfully.
last_failure_at String	Last time this expectation closed with a failure result.
last_result String	Most recent terminal result for this expectation. Possible values: `success`, `late`, `missing`, `invalid`
created_at String	Creation time.
updated_at String	Last update time.

Example Data Source

data "files_expectation" "example_expectation" {
  id = 1
}