Data Model Reference¶
This page documents the TypeScript types and interfaces used across all workflows. All types are defined in lib/types.ts.
Workflow Types¶
Workflow¶
type Workflow = "validate" | "compare";
Identifies which workflow the user selected. Used to route the app between processing paths and result screens.
ValidateSession¶
Holds state for the multi-step Validate & Fix workflow.
type ValidateSession = {
fileName: string;
originalXml: string;
initialResult: ValidationResult; // result of first validateXml() call
fixes: AppliedFix[]; // fixes staged by the user in the fix editor
validationRules?: RulesProfile; // snapshot used for revalidation
revalidatedResult?: ValidationResult; // result after fixes applied
finalXml?: string; // corrected XML ready to download
};
Validation Workflow Types¶
ValidationResult¶
Returned by validateXml() in lib/validator.ts.
type ValidationResult = {
issues: ValidationIssue[];
records: StudentRecord[];
schoolCount: number;
studentCount: number;
gate: "READY" | "READY_WITH_WARNINGS" | "REVIEW_REQUIRED" | "BLOCKED" | "PENDING";
xsdValidated?: boolean;
};
| Field | Description |
|---|---|
issues |
All issues found during validation |
records |
Parsed student records extracted from the XML |
schoolCount |
Number of ns1:School elements found |
studentCount |
Total number of student records found |
gate |
Readiness state. The current validator returns BLOCKED for errors, REVIEW_REQUIRED for review warnings, and READY otherwise. The union also reserves READY_WITH_WARNINGS and PENDING. |
xsdValidated |
Whether a separate XSD-validation layer ran; currently false |
ValidationIssue¶
Represents a single finding from the validation pass.
type ValidationIssue = {
id: string; // unique ID (used to correlate with AppliedFix)
severity: "error" | "warning" | "info";
recordId?: string; // ID of the StudentRecord this issue belongs to
schoolNumber?: string; // school number for display
studentName?: string; // student name for display
field?: string; // XML field name (e.g. "Grade", "BirthDate")
currentValue?: string; // source value for a non-student issue (e.g. metadata)
message: string; // human-readable description of the problem
suggestedFix?: string; // correction the app recommends, if deterministic
autoFixable: boolean; // whether a suggestedFix exists and is safe to apply
ruleId: string; // which rule produced this issue (e.g. "grade-value")
xmlPath?: string; // XPath-style pointer to the element in the XML
layer?: DiagnosticLayer; // import/canonical/XML/etc. diagnostic layer
sourceLocation?: string; // workbook cell or other source location
repairProposal?: AddressRepairProposal; // coordinated multi-field repair
};
AppliedFix¶
Records a single correction that was staged in the fix editor and applied to the XML.
type AppliedFix = {
issueId: string; // ID of the ValidationIssue being resolved
recordId: string; // ID of the StudentRecord being modified
field: string; // XML field that was changed
oldValue: string; // value before the fix
newValue: string; // value written by the fix
ruleId: string; // rule that raised the original issue
appliedAt: number; // Unix timestamp (ms) when the fix was staged
repairId?: string; // links fields changed by one repair card
};
StudentRecord¶
An in-memory representation of a single student element, extracted during validation for use in the fix editor and audit log.
type StudentRecord = {
id: string; // stable ID used to correlate issues and fixes
xmlPath: string; // location in the XML tree (for write-back)
fields: Record<string, string>; // all student fields as key-value pairs
};
Cleaning Step Types¶
These types are used by the interactive cleaning step in the Validate & Fix workflow (lib/cleaning.ts, lib/types.ts).
CleaningMapping¶
A single raw → canonical substitution rule for one field.
interface CleaningMapping {
raw: string; // exact string to match (case-insensitive by default)
canonical: string; // replacement value
matchCase?: boolean; // true = case-sensitive match (default: false)
}
CleaningProfile¶
The full set of cleaning rules attached to a custom ruleset.
interface CleaningProfile {
enabledFields: string[]; // fields to apply mappings to (opt-in)
mappings: Record<string, CleaningMapping[]>; // field → ordered mapping list
}
Only fields listed in enabledFields are cleaned. Within a field, mappings are evaluated in order and the first match wins.
CleaningSummaryEntry¶
One row in the cleaning summary screen — one entry per mapping that was defined, including those with zero matches.
interface CleaningSummaryEntry {
field: string;
raw: string;
canonical: string;
count: number; // number of records changed by this mapping (0 = no match)
}
Validate & Fix reporting types¶
These types support the report downloads on the Validate & Fix download screen; reporting is not a separate workflow.
Student¶
A flat representation of a student record extracted from the STIX XML.
interface Student {
SchoolName: string;
SchoolNumber: string;
FirstName: string;
MiddleName: string;
LastName: string;
AliasFirstName: string;
AliasMiddleName: string;
AliasLastName: string;
BirthDate: string;
BirthYear: number | null; // derived from a valid YYYY-MM-DD BirthDate
Grade: string;
Class: string;
OEN: string;
Gender: string;
Language: string;
CountryOfOrigin: string;
Unit: string;
StreetNumber: string;
StreetNumberSuffix: string;
StreetName: string;
StreetType: string;
StreetDirection: string;
RuralRoute: string;
PoBoxNumber: string;
City: string;
Province: string;
PostalCode: string;
PhoneType: string;
GuardianFirstName: string;
GuardianLastName: string;
GuardianRelationship: string;
GuardianPhoneNumber: string;
GuardianPhoneType: string;
Guardian2FirstName: string;
Guardian2LastName: string;
Guardian2Relationship: string;
Guardian2PhoneNumber: string;
Guardian2PhoneType: string;
}
ExportResult¶
Returned by processExport() in lib/pullInfo.ts.
interface ExportResult {
allStudents: Student[];
filteredStudents: Student[]; // Grade GR7/GR8, BirthYear 2012/2013
schoolCounts: SchoolCount[];
gradeCounts: GradeCount[];
}
SchoolCount¶
One row in the School Counts report.
interface SchoolCount {
SchoolName: string;
BirthYear: number | null;
StudentCount: number;
}
GradeCount¶
One row in the Grade Counts report.
interface GradeCount {
SchoolName: string;
Grade: string;
GradeCount: number;
}
Compare Files types¶
STIXComparison is the result of compareSTIXFiles(). It stores source filenames and the current XML, student and school totals, matched/unchanged/added/removed/changed/moved counts, the calculated change rate and signal, and these detail collections:
recordChanges: added, removed, and changed records with per-field before/after values;fieldChanges: aggregate counts by compared field;schoolChanges: previous/current and change counts by school; andschoolTransfers: matched students whose school name changed.
Review decisions and proposed corrections are transient UI state in CompareWorkflow; they are not part of STIXComparison. Proposed corrections are applied to an exported copy of currentXml.