Skip to content
English
Request Article Update Go to Customer portal
  • There are no suggestions because the search field is empty.

Migrating from Clarity XML to Clarity CSV

A practical guide to converting your Data Import Tool (DIT) imports from Clarity XML to Clarity CSV.

Note: Clarity XML, including Clarity XML 2026 and Clarity XML (Mapping), was retired as a DIT data format on September 30, 2026.

Table of Contents

Overview

A practical guide to moving from Clarity XML to Clarity CSV in the Data Import Tool (DIT): what changed, what to check, and the order of operations for converting your imports.

Why Migration Matters

Clarity XML, the extended-HMIS-XML format the Data Import Tool (DIT) previously accepted alongside HUD's own CSV standard, was retired on September 30, 2026. 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.

Clarity CSV is not yet a byte-for-byte equivalent. Service mapping still runs through the DIT's UI rather than via a programmatic tag; attendance time isn't yet modeled in CSV; and custom fields are handled differently than in Clarity XML. 

This guide walks through what changed, what to check, and a concrete order of operations for converting your imports, 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.

No longer accepted: Clarity XML, including Clarity XML 2026 and Clarity XML (Mapping), was retired on September 30, 2026.

XML vs. CSV

Use this table to translate your former Clarity XML setup to Clarity CSV. The Clarity XML column describes how XML worked before it was retired.

Aspect Clarity XML (retired) 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 ExportID in ClarityClient.csv, ClarityEnrollment.csv, and ClarityAssessment.csv. Not available in the service, expense, or attendance files.
Minimum valid file

Won't validate without top-level Organization, Project, and User elements carrying their referenced IDs.

Mapping zip needs at least Export.csv, Program.csv, ServiceItem.csv, Assessment.csv, Event.csv, and EventLocation.csv. For the actual data, a zip containing only ClarityExport.csv is valid, but it imports nothing — that file contains metadata only.
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: ServiceItemID tag lets you map services programmatically — no UI step required.

Mapping happens through the DIT's own dropdown UI; there's no header-level equivalent to ServiceItemID yet.
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

DateUpdated decides which record wins —can overwrite a non-null value with null.

Same rule, same risk: DateUpdated precedence, non-null-to-null overwrites possible.
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

Review the following before converting your imports.

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 change to the program or service catalog.

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 hard-failed under 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 test on a training site: Import the full Clarity CSV set (clients, enrollments, assessments, services, expenses, attendance) to a training site, and compare record counts against your most recent XML import or your source system.

  • 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 ExportID in ClarityClient.csv, ClarityEnrollment.csv, and ClarityAssessment.csv, matching your instance's field schema exactly — order matters here in a way it didn't for tagged XML elements.

  • Move production imports to Clarity CSV: Because Clarity XML is no longer accepted, switch your production imports as soon as your training-site test is validated. Validate at least one full reporting cycle on the new format.

Frequently Asked Questions (FAQ)

Do I still need to migrate?

Yes. Clarity XML was retired on September 30, 2026, and is no longer accepted by the DIT. To keep importing data, convert your imports to Clarity CSV. This change is unrelated to any HUD HMIS CSV schema changes, and Bitfocus continues 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.

Is Clarity XML still accepted?

No. Clarity XML 2026 and Clarity XML (Mapping) are no longer available in the DIT's Supported Data Formats.

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?

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

 

 

Updated: 10/01/2026