Operations & Systems

A CSV Data Contract for Business Handoffs: Define the File Before Import

A file arrives with a column called quantity. One team means units available for sale. The other means units physically on the shelf.

Both teams can read the number. They still disagree about what it represents.

A CSV data contract gives that disagreement somewhere to surface before import. Define the row, the columns, the allowed values, and the conditions for accepting a delivery. Give each exception an owner.

CSV alone does not declare column types or uniqueness rules. The W3C CSV on the Web primer explains why accompanying metadata matters for interpretation and validation.

The worksheet below is a proposed agreement between two teams. It uses fictional inventory records. It is not a production import procedure or a claim of conformance with a formal standard.

Define What One Row Represents

Start with the smallest unit of meaning. For this example, one row describes one product at one warehouse on one snapshot date.

The sender prepares a warehouse inventory snapshot. The receiver reviews it for planning. The file does not authorize purchases, adjust stock, or replace a transaction history. Put those exclusions at the top of the agreement.

Choose whether the delivery is a full snapshot or a set of changes. Here, it is a full snapshot of the agreed product and warehouse combinations. An omitted combination means the delivery is incomplete until explained. It never means zero stock.

Define quantity before discussing its type. In this example, quantity means counted physical units, including units reserved for existing orders. The receiver must not label the result available stock.

Name the snapshot date separately from the export date. A file prepared on Tuesday may describe Monday's count. The date in each row identifies the count, while the delivery receipt records when the sender produced the file.

If the handoff later becomes part of API-first business operations, keep these definitions. A different transport does not settle an unresolved business meaning.

Write the Companion Specification

Use a short document beside the CSV. Assign it a contract name and version. For this fictional exchange, use inventory-snapshot-v1.

Specify the file rules before the column rules:

File property Agreement for this example
Layout One header record, followed by data records; no footer or totals row
Delimiter Comma
Encoding UTF-8, without a byte-order mark
Record ending LF
Quoting Double quotes around fields containing commas or quotes; double embedded quotes
Embedded line breaks Rejected in this version
Header matching Exact names and order shown below
Whitespace Preserve values; reject surrounding spaces in identifiers
Delivery mode Complete snapshot for the agreed coverage list
Version location Companion specification and delivery receipt

These are chosen constraints for this exchange. They are not claims that every CSV producer uses the same settings. Have the sender produce a sample under these rules. Have the receiver demonstrate that it can read that sample without guessing.

Then define each column:

Column Type and required value Meaning and validation
product_id Required text Exactly five digits; preserve leading zeros
warehouse_id Required text One of NORTH or SOUTH
snapshot_date Required date Valid calendar date written as YYYY-MM-DD
quantity_units Integer or UNKNOWN Nonnegative counted units; no decimal or thousands separator
count_status Required text counted or pending
bin_label Text; empty allowed Empty means no bin is assigned; UNKNOWN means assignment is unknown

Require the combination of product, warehouse, and snapshot date to be unique. Do not merge repeated combinations. A duplicate needs a sender decision about which record is valid.

For quantity_units, require an integer when status is counted. Require UNKNOWN when status is pending. An empty quantity is invalid. This cross-column rule belongs in the agreement even if the chosen import tool needs a separate check to enforce it.

Reserve UNKNOWN as a marker in the two columns that allow it. A warehouse cannot use that exact word as a real bin label under version one. If that restriction becomes impractical, change the contract openly.

Walk Through a Fictional File

The following records are invented. They illustrate the agreement without exposing a business export.

product_id,warehouse_id,snapshot_date,quantity_units,count_status,bin_label
00127,NORTH,2026-10-27,0,counted,
00410,NORTH,2026-10-27,12,counted,"Aisle 2, Shelf B"
00809,SOUTH,2026-10-27,UNKNOWN,pending,UNKNOWN

The first product has a completed count of zero units. Its empty bin label means no bin is assigned. The last product has no completed count, and its bin assignment remains unknown.

Those conditions require different follow-up work. A zero quantity can enter the planning review as a known count. An unknown quantity cannot support a conclusion about stock availability. An unassigned bin calls for an assignment decision, not an invented location.

The second product has a comma inside its bin label. The quoted field keeps that label together under the chosen file rules. Ask both teams to include this row in their acceptance sample.

Keep identifiers as text throughout the handoff. In this contract, 00127 is the identifier. Replacing it with 127 violates the agreement, even if someone believes the missing zeros are cosmetic.

The receipt for this sample lists three data records, three unique keys, two counted records, and one pending record. Known quantities sum to twelve units. Label that sum as known counted units. It is not a complete inventory total because one count remains unknown.

Keep Empty, Zero, and Unknown Separate

Write a missing-value rule for every column. A single global instruction to replace blanks with zero would break this example.

For quantity, zero is a completed observation. UNKNOWN is an explicit absence of a completed observation. Empty is a contract violation. For the bin label, empty has its own agreed meaning.

Ask the receiver to describe each case back to the sender. Use plain statements: the completed count found zero units, the count is pending, or no bin is assigned. If those statements produce disagreement, revise the definition before testing software.

Do not accept a receiver workaround that erases the distinction. A required numeric destination field does not authorize converting unknown quantities into zero. Keep those records outside that destination until the teams choose a compatible design.

Record whether an allowed unknown blocks the whole delivery. For this example, planning may accept a snapshot with pending counts when the pending-record count is visible. A different use may require every count to be complete. That is an acceptance decision, not a parser setting.

Return Rejections With Enough Evidence to Act

Separate structural failures from record failures. An unreadable file, a wrong header, or a missing contract version should stop validation of the delivery. Do not guess which columns belong together.

For readable files, report invalid records without changing their submitted values. Use the delivery identifier, data-record number, field, original value, failed rule, and owner. Number data records from one after the header. That convention avoids confusion about spreadsheet row numbers.

Suppose a second fictional delivery contains these problems:

Data record Field Submitted value Failed rule Required response
Four quantity_units twelve Integer required for a counted record Sender verifies the count
Five product_id 127 Exactly five digits required Sender returns to its identifier source
Six snapshot_date 2026-02-30 Valid calendar date required Sender verifies the snapshot date

Do not translate twelve into a number or pad the identifier during validation. Those edits would hide what the sender supplied. Ask for a corrected delivery that references the rejected one.

For this proposed workflow, any invalid record holds the entire snapshot from operational use. The receiver can inspect valid records in a staging area. Inspection does not mean acceptance.

Keep the first delivery and its rejection report intact. Label the corrected file as a replacement. Do not append a corrected full snapshot to the rejected snapshot and treat the combined result as one delivery.

Reconcile Records Before Accepting the Handoff

Have both teams count the same things. Use data-record counts, unique-key counts, counted records, pending records, and known quantity totals. Record the expected product and warehouse coverage separately.

For a readable delivery, assign every record one validation outcome: valid or rejected. The input count must equal those two counts combined. Keep delivery acceptance separate from record validity.

A delivery with three valid records can still fail acceptance if the agreed coverage list expects four combinations. A clean validation report does not explain the missing combination.

Compare totals at the agreed level. If the receiver splits data by warehouse, reconcile each warehouse as well as the combined file. This gives a reviewer a smaller place to inspect a discrepancy.

Use the same snapshot when comparing totals. A fresh export may contain a different count. If the sender changes the source while investigating, request a new delivery identifier and record what changed.

The receiver signs off on the file it checked. The sender confirms that the receipt describes the file it sent. Keep both acknowledgments with the specification and the validation result.

Distinguish This Worksheet From W3C Metadata

The W3C Metadata Vocabulary for Tabular Data defines properties for schemas, datatypes, required values, null markers, keys, and CSV dialects. It provides a formal vocabulary for machine-readable descriptions.

This worksheet includes business decisions beyond column descriptions: who corrects a record, whether a delivery is held, and what acceptance means. It does not implement the W3C vocabulary. A document titled data contract does not establish CSVW conformance.

If a receiver needs CSVW metadata, assign that implementation explicitly. Map the approved meanings to the vocabulary and verify them with the selected processor. Keep unsupported checks visible as separate validation requirements.

Use the W3C primer to understand the formal approach. Keep the team's acceptance record alongside any machine-readable schema.

Change the Version Before Changing the Meaning

Treat a renamed column, a new null marker, or a revised quantity definition as a proposed contract change. Do not hide it in a familiar filename.

For this workflow, even an added optional column requires receiver acceptance because version one fixes header names and order. Define a more flexible policy only when both teams agree how unfamiliar columns will be handled.

Send the revised specification with a difference list and a synthetic sample. Name the last delivery using the old version. Name the first proposed delivery using the new version. Keep the transition date unconfirmed until both sides accept it.

Put the operating instructions in the team's SOP documentation. Include the current contract, sample, rejection report, and replacement procedure. If a Google Sheets workflow consumes the file, identify that receiver explicitly instead of assuming every spreadsheet behaves alike.

Close the handoff with four recorded answers: which file, which contract version, which checks, and who accepted the result. Leave unresolved discrepancies visible.

The file needs an agreement.

Sources

Topic map: Spreadsheets, CSV files, and data handoffs

Articles in this cluster, then the 3 clusters that share the most topics with it.

This cluster: Spreadsheets, CSV files, and data handoffs

Neighbor: Business reporting and statistics

Neighbor: Records, access, and continuity

Neighbor: APIs, webhooks, and automation