DataLoom design

Application

DataLoom is an offline PySide6/Qt desktop application. It does not upload files, call cloud services, or require a network connection during normal operation.

Import rules

Accept two or more files in one batch.
Every file in a batch must be Bitwarden JSON or every file must be Bitwarden CSV.
Reject mixed-format batches and encrypted/protected exports.
Validate the expected Bitwarden structure before processing.
Preserve supported item types and unknown JSON fields where possible.
Keep source filename, input index, record index, and Bitwarden item ID as internal provenance metadata for review and logging; do not add it to exported vault records.

Duplicate policy

Only exact duplicates are removed automatically. All uncertain or conflicting records remain in the merged collection and are shown in Duplicate Review.

Exact duplicate

Two records are exact duplicates when they have the same item type and equivalent normalized content, including the relevant login username, password, URI data, folder, notes, custom fields, and other representable fields. Comparisons are case-insensitive where appropriate.

Likely duplicate

Same item type, normalized URL identity, and username, but one or more values differ. These records remain separate.

Possible duplicate

Same item type and normalized URL identity, but different usernames or other identity fields. These records remain separate.

Non-login records use type-appropriate stable fields and full normalized content. Folder membership is retained but does not alone determine duplication.

URL normalization

Normalize URLs conservatively and case-insensitively by parsing the URL, lowercasing the scheme/host, removing default ports, removing trailing slashes, and applying the configured www. equivalence. Query strings and paths remain significant unless Bitwarden-specific behavior establishes otherwise. The original URI is always preserved for export.

When normalization is ambiguous, retain both records and flag them for review.

Newest record preference

When duplicate records conflict, use Bitwarden revisionDate when available and valid. The newest record is preferred only where the timestamp is reliable. CSV commonly lacks sufficient revision metadata; in that case DataLoom keeps a deterministic first record in the merged output, retains all conflicting records in Duplicate Review, and logs that newest selection was unavailable.

Review interface

Import Summary — files, format, counts, validation warnings, and output locations.
Merged Entries — records included in the output, with provenance and classification.
Duplicate Review — grouped likely/possible duplicates and exact-duplicate removal decisions, with side-by-side differences.
Audit Log — live in-app view and persistent plain-text log.

The workflow is automated; there is no general record editor. Review is read-only in the first version.

Audit logging

The requested log records every file and record viewed, fields inspected, comparisons, classifications, selection decisions, warnings, and exports, including secret values. Because this log is equivalent in sensitivity to a vault, the import warning must explicitly state that it contains secrets. The user is responsible for retaining and deleting the log. DataLoom must never log secrets from its own synthetic fixtures into repository files.

Export

JSON input produces JSON output.
CSV input produces CSV output.
JSON is the lossless preferred format.
Before CSV export, report any fields that CSV cannot represent completely (for example, nested/custom structures, passkey data, or attachment metadata).
Never silently discard unsupported data.

Data lifecycle

DataLoom does not automatically delete input, output, or log files. After processing it displays the exact locations of all generated files. Real exports and generated vault/log files are ignored by Git.

3.9 KiB Raw Blame History