Content Validation

The file-level criteria on an Expectation describe what uploads are expected, like checking how many files arrive, how large they are, and what they're called. Content Validation criteria look inside those files. Each Expectation can contain any combination of file-level criteria and Content Validation criteria.

This is the difference between knowing a partner sent orders.csv on time and knowing that orders.csv has the columns you agreed on, dates in the format your pipeline parses, and amounts that aren't negative. A delivery can satisfy every file-level rule and still be unusable.

Content Validation uses TransformScript to inspect a file's contents, rather than generating a new file. The script you supply reads the parsed file data and decides whether the data is acceptable.

Your script works with parsed data rather than raw text, so there is no parsing code for you to write. TransformScript reads CSV and TSV, XLSX spreadsheets, JSON and NDJSON, YAML, XML, and the HL7, X12, and EDIFACT interchange formats.

Enabling Content Validation

Enable Content Validation in the Expectation's criteria, choose whether to validate each file separately or all at once, and provide your validation script in the Files TransformScript field.

Content Validation determines each file's format from its extension and parses it before your script runs, so it only works on the structured formats listed above. When a file's extension isn't one Files.com recognizes, declare the format with an input directive in the script and choose Per file. Whole batch ignores the directive and fails the evaluation on the first file it cannot identify from its filename.

The web interface provides the standard TransformScript editor, with a reference panel, live syntax-checking, and AI assistance available without leaving the editor.

Choosing the Validation Mode

Content Validation criteria can either evaluate each file independently or by examining all of the file content at once. Which mode to choose depends on the type of check you are making.

Each script run is a Files TransformScript invocation and consumes Transformation and AI Credits. Per file runs the script once per matched file, so a window matching twenty files costs twenty invocations. Whole batch runs it once however many files matched.

Per File

Per file runs the provided script once for every matched file, with payload holding that file's contents. Use it for any rule that concerns one file on its own.

Content validation errors in Per file mode identify the file they came from, so one script can report on each file in a batch independently.

Whole Batch

Whole batch runs the script once for the entire matched set. Each file is parsed independently first, and payload is an array holding one entry per matched file. Each entry describes a file and includes that file's own parsed contents:

The name payload appears at both levels. The script's own payload is the array of files; each entry's payload is one file's data. A script written over this array reads them as payload and file.payload.

Use batch mode for content validation rules that span files. Common uses include: reconciling a manifest total against the line-level files it accompanies, flagging duplicated data amongst files, or ensuring that batch limits aren't exceeded.

A script in this mode can still report a problem with an individual file, and can raise as many errors as it finds. An Expectation does not automatically name which file caused a content validation to fail in batch mode. To "bubble up" attribution from specific files triggering errors, include the file's name or path in the message returned by the script.

Using AI to Write a Script

You don't have to write TransformScript yourself. In the web interface, Ask AI opens the AI Assistant alongside the TransformScript editor, and the Assistant is fluent in TransformScript. Describe the rules your files have to satisfy, and the Assistant writes the script. A Use Script button on its reply puts that script directly into the field.

The AI Assistant understands what a Content Validation script is for. Asked for validation rules rather than a transformation, it returns the correct result shape for content validation. It fills in message, field, row, expected, and actual without being asked. Complex validations that check several conditions at once, rules where one field's validity depends on another's, or rules that reference specific business and EDI formats like X12 or HL7 with named segments can be generated directly rather than assembled by hand.

Because the Assistant can read what is already in the field, the conversation builds on your script instead of restarting. "Also reject rows where the amount is negative" or "report the row number too" amends what you have. The field changes only when you press Use Script, so you can ask for several attempts and keep the one you want.

Checking What It Wrote

The Assistant writes the script, but only your files can tell you whether it is right about your data. Test with a file you expect to pass as well as one you expect to fail. A script that incorrectly flags good data is harder to notice than one that misses bad data.

Check what the script does when it cannot evaluate something. A script that compares against a numeric range has to decide what to do when the range isn't numeric. Skipping the comparison avoids an execution error, but it also lets an invalid file pass with no sign the check was skipped. If a rule matters, make the unreadable case produce an error rather than silence.

Test whether a rule means what you intended. An ambiguous requirement like "This field is required" can be read as "the field is present" or "the field holds a usable value." Make sure the AI Assistant implemented the one you meant.

One habit the Assistant won't apply on its own is joining a list of allowed values with something other than a comma, so check any expected that holds a list against the rules in Writing Errors People Can Act On.

Testing a Script

However the script is written, the definitive way to know it is right about your files is to run it against them. Uploading a file and waiting for the Expectation Evaluation window to close is the slowest way to find that out.

For a per-file script, the Transform File action runs it against one file on demand. Add output json to the header of your script, transform a sample file, and read the result. The output directive has no role in validation, where the return value is the verdict rather than something to serialize, so a script tested this way goes into the criteria field unchanged.

Scripts for a batch-mode content validation need to be tested through an Expectation, because Transform File runs against one file at a time. And the JSON result quotes every value, which means a comma-joined list looks perfectly readable there and only turns ambiguous once it is rendered into a Criteria Error. Put at least one real failure through an Evaluation before relying on the wording.

What the Script Returns

A content validation script produces a verdict rather than a file. Returning true or false is enough for a simple pass or fail. To say why a file failed, return an object with a boolean success and an errors array. A script that returns any other shape fails with a Criteria Error explaining that it must return true, false, or an object with a boolean success field.

Sample Success Results

true

{ success: true }

Sample Failure Results

false

{
  success: false,
  errors: [{
    message: "Amount does not match",
    field: "amount",
    row: 12,
    expected: "25.00",
    actual: "24.50"
  }]
}

errors accepts strings or objects. The fields message, field, row, expected, and actual are conventional details to include in an object, and any other key you add is carried into the error text as well.

A returned false on its own is a valid failure, but it tells whoever reads the Evaluation nothing beyond "the script said no." The errors array makes the Evaluation actionable.

Common Validation Patterns

Most content validation comes down to a few recurring problems, like columns that are missing or misnamed, values in the wrong format, fields that are only valid in combination with another field, and rules that can only be judged across a whole delivery. Example Validation Scripts covers each one with a complete script you can adapt.

An Expectation has a single script field, so every rule you want enforced lives in one script. Rules of different kinds combine freely, because each one contributes its own array of errors regardless of whether it examined the whole file or every row.

Writing Errors People Can Act On

Each error is included in the Evaluation's Criteria Errors. In Per file mode the entry is prefixed with content_validation and the path of the file being validated:

content_validation incoming/orders.csv: Amount must be positive (field: amount, row: 2, expected: > 0, actual: -4)

The person reading that is usually trying to get a partner to resend a corrected file. Adding clear error messages turns a reverse-engineering investigation into a task that gets resolved fast.

Join lists in your messages with something other than a comma. The Evaluation's Criteria Errors text separates its own fields with commas, so a value that contains commas runs together with the fields after it. A header list joined with ", " produces this:

… (field: header, expected: account_id, amount, effective_date, actual: order_id, amount, ship_date)

There is no way to tell where expected ends. Choosing a different separator for a list included in a message keeps the boundaries visible:

… (field: header, expected: account_id | amount | effective_date, actual: order_id | amount | ship_date)

Write messages that claim only what your script actually checked. An error that says "unexpected header row" is less precise than "the first row does not match the expected header row".

List the supplemental fields in the order you want them read. The message is followed by the other detail fields in the order your script lists them.

Naming the File in Whole Batch Mode

In Whole batch mode, the Criteria Errors of an Expectation use a prefix that identifies the batch rather than a file, because the script ran once against all of them:

content_validation whole_batch: Total entries exceeds daily limit (expected: 1000, actual: 1012)

That is the right prefix for a rule about the batch. For a rule about one file within it, the path is only in the error if your script put it there — so read the file's name or path from its entry in payload and lead the message with it:

message: "$(e.file): amount is not a number, so the batch total cannot be reconciled"

which produces an entry that names the file the sender has to fix:

content_validation whole_batch: detail-east.csv: amount is not a number, so the batch total cannot be reconciled (field: amount, expected: a numeric amount on every row, actual: N/A)

A batch script raises as many errors as it finds, across as many files as it finds them in, so without this every entry looks like it could have come from any file in the delivery.

Evaluation Results

Content validation failures make a populated Evaluation Invalid when the window closes, which opens an Incident for scheduled windows. Failures include a script returning a failure result, an unparseable file, an execution error, and a file that could not be downloaded or exceeded the size limits.

An Evaluation that is still Open does not show content validation errors, even when matching files have already arrived. Content validation runs when the window closes, at which point the errors are recorded and the Evaluation status is updated.

If nothing matched, the Evaluation is Missing rather than Invalid — there was no content to validate. File-level and content-validation errors appear together in the same Criteria Errors list when both kinds of rule fail.

Limits

Content validation limits how much input file data it processes, and how many errors it records for one Evaluation.

When evidence is omitted or truncated because of these limits, the Criteria Errors say so explicitly rather than leaving a short list looking complete.

Expectation Versions

Every Expectation has a version that fixes which kinds of criteria it can use. The version is assigned when the Expectation is created and never changes. Version 1 supports file-level criteria only. Version 2 supports file-level criteria and Content Validation.

To apply content validation to a delivery a version 1 Expectation already monitors, create a new Expectation with the same scope, trigger, and file-level criteria, and add Content Validation to it.