CSV Validator

Validates tabular CSV data against structural rules and schema requirements before ingestion or transformation.

1. Purpose

Verify that a target CSV file has a consistent delimiter, valid header row, uniform row lengths, and conforms to required column constraints. A "CSV" is a comma-separated values text file per RFC 4180.

2. When to Use

Use this skill when:

• Receiving an uploaded or imported CSV file.
• Before running data analysis, migrations, or database inserts.
• User asks to "check", "clean", or "validate" a CSV file.

3. When Not to Use

• Do not use to parse complex JSON payloads; use json-schema-converter.
• Do not use to compute summary statistics or metrics; use tabular-analyzer.
• Do not use to extract single arbitrary text fields; use field-extractor.

4. Required Inputs

• csv_path: File path to the CSV file (string).
• expected_columns: Optional list of expected column header names (comma-separated string or array).
• delimiter: Optional separator character (default: ,).

5. Missing-Input Behavior

1. If csv_path is not supplied, stop immediately and ask: "Please provide the file path to the CSV file."
2. If csv_path points to a missing file, report: "Error: File <path> not found."
3. If expected_columns is omitted, validate structure only (uniform row lengths, non-empty header, parseable rows).

6. Procedure

Follow these numbered actions:

1. Action 1: Inspect File Metadata
   • Confirm file exists, is non-empty, and check byte size.
2. Action 2: Execute Validation
   • Run the companion validator script:

     python3 skills/csv-validator/scripts/validate_csv.py <csv_path> [--columns <cols>] [--delimiter <delim>] --json

   • Alternatively, if python3 is unavailable, manually read the header and inspect the first 100 lines for matching field count.
3. Action 3: Parse Validation Issues
   • Check for header mismatches, row count mismatches, and trailing blank rows.
4. Action 4: Emit Summary Report
   • Format the findings using Section 8.

7. Decision Rules

• If any row has a different column count than the header: mark status as INVALID.
• If expected columns are specified and header names do not match exactly (case-sensitive or trimmed): mark status as INVALID.
• If the file is 0 bytes or has no rows after header: mark status as EMPTY.
• If 0 issues are detected: mark status as VALID.

8. Output Format

Emit the CSV validation report using this template:

### CSV Validation Report: [Filename]

- **Status**: [VALID | INVALID | EMPTY]
- **Delimiter**: `[e.g., ,]`
- **Header Columns**: `[col1, col2, col3]`
- **Rows Processed**: [integer]
- **Issues Found**: [count]

#### Issue Details (if any)
- `Row [N]`: [Description of error, e.g., expected 4 columns, got 5]

#### Recommended Remediation
- [Concrete action to fix the CSV or schema]

9. Verification Checklist

• File existence confirmed on disk.
• Header was extracted and verified.
• Every data row was checked for matching column length.
• Companion script validate_csv.py executed or fallback executed.

10. Common Failures and Recovery

11. Stop or Escalation Conditions

Stop and ask the user when:

• File is corrupted or encoded in an unreadable binary format.
• File size exceeds memory or storage limits.

12. Examples

Example 1: Successful Execution

Input:

File: /data/users.csv
Expected columns: id,username,email,status
Content:
id,username,email,status
101,alice,alice@example.com,active
102,bob,bob@example.com,inactive

Expected Observable Actions:

1. Ran validate_csv.py /data/users.csv --columns "id,username,email,status" --json.
2. Verified 2 rows and identical headers.

Output:

### CSV Validation Report: users.csv

- **Status**: VALID
- **Delimiter**: `,`
- **Header Columns**: `id`, `username`, `email`, `status`
- **Rows Processed**: 2
- **Issues Found**: 0

#### Recommended Remediation
- None. File is ready for processing.

Example 2: Ambiguous or Failure Case

Input:

File: /data/orders.csv
Expected columns: order_id,total,created_at
Content:
order_id,total,created_at
201,49.99
202,12.50,2026-09-01,EXTRA_FIELD

Output:

### CSV Validation Report: orders.csv

- **Status**: INVALID
- **Delimiter**: `,`
- **Header Columns**: `order_id`, `total`, `created_at`
- **Rows Processed**: 2
- **Issues Found**: 2

#### Issue Details
- `Row 2`: column count mismatch (expected 3, got 2)
- `Row 3`: column count mismatch (expected 3, got 4)

#### Recommended Remediation
- Ensure each row in `orders.csv` has exactly 3 fields matching `order_id`, `total`, and `created_at`.

Example 3: Expected Final Output

Output:

### CSV Validation Report: inventory.csv

- **Status**: VALID
- **Delimiter**: `,`
- **Header Columns**: `sku`, `quantity`, `warehouse_id`
- **Rows Processed**: 1540
- **Issues Found**: 0

#### Recommended Remediation
- None. File conforms to schema.