reference data models

Data models

This page maps the JSON request and response models used by the browser API, Tauri commands, pair-order files, and comparison snapshot files. Source DTOs live in /Users/vriesd/projects/csv-align/src/backend/requests.rs, /Users/vriesd/projects/csv-align/src/presentation/responses.rs, and /Users/vriesd/projects/csv-align/frontend/src/types/api.ts.

Transport route map

Operation	Browser route	Tauri command	Main models
Create session	POST /api/sessions	create_session	SessionResponse
Delete session	DELETE /api/sessions/{session_id}	delete_session	No success body
Load CSV	POST /api/sessions/{session_id}/files/{file_letter}	load_csv_bytes	FileLoadResponse
Suggest mappings	POST /api/sessions/{session_id}/mappings	suggest_mappings	SuggestMappingsRequest, SuggestMappingsResponse
Compare	POST /api/sessions/{session_id}/compare	compare	CompareRequest, CompareResponse
Export CSV	GET /api/sessions/{session_id}/export	export_results	CSV bytes
Save pair order	POST /api/sessions/{session_id}/pair-order/save	save_pair_order	SavePairOrderRequest, pair-order file text
Load pair order	POST /api/sessions/{session_id}/pair-order/load	load_pair_order	LoadPairOrderRequest, LoadPairOrderResponse
Save comparison snapshot	POST /api/sessions/{session_id}/comparison-snapshot/save	save_comparison_snapshot	Snapshot JSON text
Load comparison snapshot	POST /api/sessions/{session_id}/comparison-snapshot/load	load_comparison_snapshot	LoadComparisonSnapshotRequest, LoadComparisonSnapshotResponse

Request models

Model	Fields
SuggestMappingsRequest	columns_a: string[], columns_b: string[]
MappingDto or MappingRequest	file_a_column, file_b_column, mapping_type, optional similarity
CompareRequest	key_columns_a, key_columns_b, comparison_columns_a, comparison_columns_b, column_mappings, optional normalization
ComparisonNormalizationConfig	treat_empty_as_null, null_tokens, null_token_case_insensitive, flexible_key_matching, case_insensitive, trim_whitespace, numeric_equivalence, decimal_rounding, date_normalization
SavePairOrderRequest	selection
LoadPairOrderRequest	contents
LoadComparisonSnapshotRequest	contents

mapping_type values are exact, manual, and fuzzy. Fuzzy mappings require similarity between 0.0 and 1.0.

Response models

Model	Fields
SessionResponse	session_id
FileLoadResponse	success, file_letter, file_name, headers, optional virtual_headers, columns, row_count
ColumnInfo or ColumnResponse	index, name, data_type
SuggestMappingsResponse	mappings
CompareResponse	success, results, summary
ResultResponse	result_type, key, values_a, values_b, duplicate_values_a, duplicate_values_b, differences
DifferenceResponse	column_a, column_b, value_a, value_b
SummaryResponse	total_rows_a, total_rows_b, matches, mismatches, missing_left, missing_right, unkeyed_left, unkeyed_right, duplicates_a, duplicates_b
LoadPairOrderResponse	selection
LoadComparisonSnapshotResponse	file_a, file_b, selection, mappings, normalization, results, summary
ErrorResponse	code, error

data_type values are string, integer, float, and date. result_type values are match, mismatch, missing_left, missing_right, unkeyed_left, unkeyed_right, duplicate_file_a, duplicate_file_b, and duplicate_both.

Pair-order files

Pair-order files save setup selections for a loaded CSV pair. They are not result snapshots.

The persisted JSON shape from /Users/vriesd/projects/csv-align/src/backend/pair_order.rs is:

{
  "version": 1,
  "headers_a": ["id", "name"],
  "headers_b": ["id", "display_name"],
  "selection": {
    "key_columns_a": ["id"],
    "key_columns_b": ["id"],
    "comparison_columns_a": ["name"],
    "comparison_columns_b": ["display_name"]
  }
}

Loading validates:

• Supported version.
• Current File A and File B headers match the saved headers.
• Selected columns exist as physical headers or valid virtual JSON labels.
• Key and comparison column counts match.
• Duplicate selections are rejected.

Comparison snapshot files

Comparison snapshots save completed results and reopen the Results step in read-only mode. The current persisted schema reports version: 2 from /Users/vriesd/projects/csv-align/src/backend/persistence/v1/mod.rs.

Top-level snapshot shape:

{
  "version": 2,
  "file_a": {},
  "file_b": {},
  "selection": {},
  "mappings": [],
  "normalization": {},
  "results": [],
  "summary": {}
}

file_a and file_b contain name, headers, virtual_headers, columns, and row_count. selection, mappings, normalization, results, and summary use the same shapes as comparison request and response models.

Loading validates:

• Supported snapshot version.
• File metadata matches headers and column indexes.
• Selected columns are present.
• Mappings cover selected comparison columns exactly once when mappings are present.
• Fuzzy mapping similarities are present and in range.
• Persisted summary matches regenerated summary from persisted results.

Key source files

File	Model role
/Users/vriesd/projects/csv-align/src/backend/requests.rs	Backend request DTOs, pair-order selection DTOs, snapshot load response DTOs, and validation error enum.
/Users/vriesd/projects/csv-align/src/presentation/responses.rs	Serializable response DTOs for file loads, mappings, comparisons, results, differences, and summaries.
/Users/vriesd/projects/csv-align/frontend/src/types/api.ts	Frontend TypeScript model mirror.
/Users/vriesd/projects/csv-align/src/api/app.rs	HTTP route constants and route parity list.
/Users/vriesd/projects/csv-align/frontend/src/services/apiRoutes.ts	Frontend browser route templates.
/Users/vriesd/projects/csv-align/frontend/src/services/tauriCommands.ts	Frontend Tauri command constants.
/Users/vriesd/projects/csv-align/src/backend/pair_order.rs	Pair-order file serialization and validation.
/Users/vriesd/projects/csv-align/src/backend/persistence/v1/mod.rs	Comparison snapshot schema, conversion, and validation.