sdac-validate-file-metadata

Purpose

Validates that an uploaded file name aligns with the report’s quarter and year metadata, and highlights naming mismatches before deeper validation begins.

Tool type

Deterministic (rule-based)

Tool ID

sdac-validate-file-metadata

Inputs

• report_id (string)
• file_name (string): Uploaded file name to analyze
• file_size_bytes (number, optional): Used for confidence scoring and warnings

Outputs

• success, matches
• expected_quarter, expected_year
• detected_quarter, detected_year
• discrepancies, warnings
• confidence (HIGH | MEDIUM | LOW)
• file_type (EXCEL | ONLINE_ENTRY | UNKNOWN)

Example output

{
  "success": true,
  "matches": false,
  "expected_quarter": "Q2",
  "expected_year": 2024,
  "detected_quarter": "Q1",
  "detected_year": 2024,
  "discrepancies": [
    "Detected quarter Q1 does not match expected quarter Q2."
  ],
  "warnings": [
    "Confirm the uploaded file is for the submitted quarter."
  ],
  "confidence": "HIGH",
  "file_type": "EXCEL"
}

Functional details

• Extracts quarter/year tokens (for example, Q1-2024) from the file name.
• Compares detected values against SDAC.data_CostReports metadata for the report.
• Assigns a confidence score based on match quality and file naming patterns.
• Flags ambiguous or missing quarter/year tokens.

Usage notes

• Intended to run before validation steps to catch mismatched or stale file uploads.
• Works best with naming conventions like DistrictName_Q1-2024.xlsx.

Implementation details

• Reads report metadata via loadReportMetadata(report_id).
• Uses pattern matching to detect quarter/year tokens and common file suffixes.
• Returns discrepancies array with human-readable guidance.

Code Location: packages/domain-sdac/src/tools/validate-file-metadata.tool.ts