Migrating from Clarity XML to Clarity CSV
A practical guide to Bitfocus' Data Import Tool (DIT) transition.
Table of Contents
Overview
A practical guide to Bitfocus' Data Import Tool (DIT) transition — what actually changes, what breaks if you don't plan for it, and the order of operations for transitioning before Clarity XML sunsets.
Why Migration Matters
Bitfocus has set FY27 / October 2026 as the target sunset for Clarity XML, the extended-HMIS-XML format that the Data Import Tool (DIT) has long accepted alongside HUD's own CSV standard. Clarity CSV is the replacement: a CSV-based format built to cover the same ground as XML, including the Clarity-specific extensions that HUD's plain CSV spec doesn't have.
The catch is that Clarity CSV is not yet a byte-for-byte equivalent. Service mapping still runs through the DIT's UI rather than a programmatic tag, attendance time isn't yet modeled in CSV, and custom fields — which are supported — are handled differently than they were in Clarity XML.
This guide walks through what changes, what to check before you cut over, and a concrete order of operations, drawing on the current Bitfocus Help Center documentation for the DIT.
Accepted Formats
The following are the current accepted formats:
-
HUD HMIS CSV: The federal baseline format, per HUD's own specification. Neither Clarity-specific nor going anywhere.
-
Clarity CSV (New): Bitfocus' CSV-based superset, carrying the Clarity- specific extensions that HUD's plain CSV doesn't cover. This is the migration target.
-
Clarity XML (Sunsetting): The extended-HMIS-XML format Clarity CSV is replacing.
XML vs. CSV
| Aspect | Clarity XML | Clarity CSV |
| Custom fields |
Supported — Client Profile custom fields, plus custom fields on enrollment, exit, status update, and annual assessment, as tagged XML elements |
Supported — carried as additional columns appended after |
| Minimum valid file |
Won't validate without top-level Organization, Project, and User elements carrying their referenced IDs. |
Mapping zip needs at least |
| Full file set |
Single XML payload conforming to the published Clarity XML Schema. |
Up to seven additional files: clients, enrollments, assessments, services, expenses, attendance, plus the mapping files above. |
| Service mapping |
Optional HMIS: |
Mapping happens through the DIT's own dropdown UI; there's no header-level equivalent to |
| Assessment type |
The spec lacks a field to indicate the assessment type, so it must be set manually for each import job. |
|
| Bad SSN placeholders |
Blocks and fails the entire import until placeholder characters are corrected to lowercase x. |
Warns, and auto-converts disallowed placeholders to x — the import proceeds. |
| Multi-select fields | Bracketed list syntax: [1,2,3] |
Same syntax: [1,2,3] |
| Overwrite precedence |
|
Same rule, same risk: |
| Programmatic access |
RESTful XML API Import tool — scripted, credential-based access to the DIT. |
Not documented as of this writing — confirm current API support with your Bitfocus CSM if you rely on scripted imports. |
Before you migrate
Read below for considerations before migration.
How Custom Fields Travel in CSV
Custom data elements are supported in Clarity CSV — they ride along as extra columns appended after ExportID in three of the seven files: ClarityClient.csv (Client Profile custom fields), ClarityEnrollment.csv (enrollment/exit/status/annual-assessment custom fields — those stages are unified into one file), and ClarityAssessment.csv (custom assessment fields).
There's no equivalent in the service, expense, or attendance files. Because these columns are positional rather than tagged the way XML's custom-field elements are, column order has to match your instance's field schema exactly — confirm it before your first live run rather than assuming order will be forgiving.
Programmatic Service Mapping
If your XML pipeline uses hmis:ServiceItemID to map services without a human in the loop, that mapping moves into the DIT's UI under Clarity CSV. Budget time to rebuild it there, and re-verify it after every program or service catalog change.
Assessment Type
The assessment type has to be stated, not inferred. Because the CSV spec lacks a field for assessment type, whoever runs the import must specify it manually each time. Bake this into your import runbook now rather than discovering it during your first live cutover.
Review Validation Every Run
CSV downgrades several conditions that used to hard-fail an XML import — like malformed SSN placeholders — into warnings or silently-rejected records. That's better for throughput, but it means a bad row won't necessarily stop your import anymore. Get in the habit of reading the DIT's validation log after every run, not just checking for a pass/fail status.
The full catalog of DIT CSV validations — every rule, its severity, and which standard it applies to — is maintained at clarityhs-public/dit-validations-catalog (restricted to DIT licensees only).
Clarity CSV files can also be validated outside the DIT for basic structure and format using a CSV on the Web Schema — see clarityhs-public/clarity-csv-schema (restricted to customers only).
Migration plan
-
Inventory your current XML feed: List every field it populates, flagging anything that's a custom field and which record type it belongs to (client, enrollment/exit/status/annual-assessment, or assessment)— you'll need that to place each one in the right CSV file.
-
Build the Clarity CSV mapping set: Get the current Export / Program / ServiceItem / Assessment / Event / EventLocation mapping template from your Bitfocus CSM or the DIT sample files page, and mirror your existing program, service, coordinated-entry-event, and assessment mappings into it. Anything left unmapped won't import.
-
Run a parallel test on a training site: Import the full seven-file Clarity CSV set (clients, enrollments, assessments, services, expenses, attendance) alongside your existing XML feed, and diff record counts between the two.
-
Read the validation log every time: Confirm nothing is quietly landing as a warning or a rejected record that used to be a hard failure under XML — those issues won't surface any other way.
-
Place your custom-field columns correctly: Add the corresponding custom columns after
ExportIDinClarityClient.csv,ClarityEnrollment.csv, andClarityAssessment.csv, matching your instance's field schema exactly — order matters here in a way it didn't for tagged XML elements. -
Cut over with margin, not against the deadline: Aim to be fully on Clarity CSV well before FY27 / October 2026, with at least one full reporting cycle validated on the new format before XML support ends.
Frequently Asked Questions (FAQ)
Do I need to migrate before the next annual HMIS schema update?
No, Bitfocus' Clarity XML to Clarity CSV transition is unrelated to any HUD’s HMIS CSV Schema changes. Bitfocus will continue to support standalone HUD HMIS CSV uploads with the DIT.
Is HUD HMIS CSV the same thing as Clarity CSV?
No. HUD HMIS CSV is the federal baseline that both formats already have to support. Clarity CSV is Bitfocus' own superset of that, purpose-built to carry the Clarity-specific extensions that previously only existed in Clarity XML.
Are custom fields supported in Clarity CSV?
Yes. They're carried as additional columns appended after ExportID in ClarityClient.csv, ClarityEnrollment.csv, and ClarityAssessment.csv—not in the service, expense, or attendance files. Because they're positional rather than tagged the way XML's custom-field elements are, column order has to match your instance's field schema exactly; confirm it with your Bitfocus CSM before your first live run.
Will my programmatic/API-based import still work?
The documented RESTful import API is specifically the XML API Import tool. Equivalent programmatic access for Clarity CSV isn't documented as of this writing — confirm directly with Bitfocus before assuming a scripted CSV path exists.
Additional Resources
Published: 07/29/2026