2025 ADR data dictionary

Public snapshot for adr.biginformatics.com. Official HRSA/HAB documentation may be more current.

This package is a plain-language guide to the data submitted to the Health Resources and Services Administration (HRSA) HIV/AIDS Bureau (HAB) through the AIDS Drug Assistance Program Data Report (ADR). It covers both parts of the 2025 ADR:

• The Recipient Report is completed in HRSA's Electronic Handbooks (EHBs) and covers April 1, 2025, through March 31, 2026.
• The Client Report is uploaded as one or more XML files and covers January 1 through December 31, 2025. It includes one record for every person enrolled in the state ADAP at any time during that period, even if the person received no services.

Use this package to understand what each field means, its data type, possible values, when it is required, and whether it is entered, assigned, counted, or calculated. It is a reporting aid, not a replacement for the official HAB instructions, the ADR validation system, or the machine-readable XML schema (XSD).

Choose a format

• HTML explorer — best for searching and browsing in a web browser.
• Readable Markdown dictionary — best for a quick review in the notebook or GitHub.
• Main dictionary CSV — the editable source for Recipient Report fields, client-level fields, required XML structures, and labeled system outputs.
• Code sets CSV — one row per documented code and label.
• Validation rules CSV — the published active checks, their severity, and the fields they affect.

The three CSV files are the source of truth for the generated Markdown, HTML, and Excel versions. Each dictionary row identifies its source document and page so readers can check the original language.

Seven data levels

The dictionary uses seven levels so readers can tell what a value describes:

1. File metadata — schema version, software vendor, and technical-contact information stored in the Client Report XML file.
2. Recipient/award — recipient identity, award information, contacts, and other overall report information.
3. Recipient program — program operations, eligibility, enrollment, and service-delivery responses.
4. Recipient financial — funding sources, expenditures, reimbursements, and calculated totals.
5. Recipient formulary — antiretroviral, opportunistic-infection, hepatitis B, and hepatitis C medications reported on the Recipient Report.
6. Recipient aggregate — recipient-level counts and other totals that summarize clients or services.
7. Client level — one client's encrypted identifier, demographics, enrollment and certification, insurance services, medication assistance, and clinical information.

Some XML values describe the file or recipient rather than a client. They are labeled by what they describe, not simply by where they appear in the XML.

Required-status meanings

• Required — every record in the stated scope needs the value.
• Conditional — the value is needed only when the rule in the required_when column applies.
• Prepopulated / confirm — an HRSA system or grant record supplies the value, and the recipient reviews or confirms it.
• Optional — the reviewed sources allow the value but do not make it a condition of reporting.
• System-tracked — the ADR system assigns, calculates, or displays the value; the recipient does not enter or submit it as a normal field.
• Confirm against XSD — the reviewed sources conflict on whether or how the XML value should be sent. Check the current schema or HAB instructions before using it.

The occurrence column separately records how many times an XML element or web-form row may appear, such as once per file, once per client, or once for each reported medication. Policy-required status and XML occurrence are kept separate because the sources do not always agree.

The validation file uses three severity levels. An Error blocks certification or submission until it is fixed. A Warning must be corrected or explained with a comment. An Alert should be reviewed, but submission can continue without a comment.

The validation CSV includes all 69 active published checks: 11 Recipient checks and 58 Client checks, made up of 8 Errors, 38 Warnings, and 23 Alerts. Check 94 is excluded from the active count and CSV because the source explicitly marks it disabled.

How the sources were used

The package uses the three files in Bureau/Reports/ADR plus the XML guide linked from the official manual:

1. 2025 ADR Instruction Manual, version 1 — the main authority for who and what to report, the two reporting periods, Recipient Report fields, policy definitions, conditional reporting rules, calculations, and business rules.
2. ADR XML Schema Implementation Guide v3.7, revised January 2026 — the main technical authority for XML tag names, parent paths, numeric codes, formats, occurrence, the six file-metadata fields, eight XML container structures, and schema version 3.4.0. The manual links to this guide, but the repository does not contain a durable copy.
3. 2025 ADR Validations, revised January 2026 — the authority for active or disabled check IDs, the published message text, the affected question or element, and Error/Warning/Alert severity. A validation message does not silently redefine the values allowed by the manual or XML guide.
4. ADR Location: Client-Level Data Elements 2025 — a secondary aid for CAREWare data-entry locations and practical warnings. It has no stated author or issuing organization, so it does not override the three specification sources above.

When these sources disagree, the dictionary keeps the conflict in source_note instead of silently choosing one rule. For an XML implementation, use the current official XSD and live ADR test tool as the final tie-breakers for unresolved technical details.

Calculation highlights

• Encrypted UCI (ClientUci): the manual describes building a UCI from the first and third characters of the client's first and last names, full birth date in MMDDYY, and a sex-at-birth UCI code, then applying SHA-1. The sources do not fully define normalization and error handling, and they conflict on output length. Use an approved HAB UCI/eUCI tool.
• Birth year: extract the year from the client's full date of birth. Only the year is submitted as BirthYear, although the full date is also needed to create the UCI.
• Federal poverty level percent: derive the percentage from household income, household size, and the selected federal poverty measure as of year end. HAB prefers HHS poverty guidelines unless the organization already uses Census poverty thresholds. The sources do not provide complete household or rounding rules.
• New enrollment: classify a client as newly enrolled only when this is the person's first application to that state ADAP and the person met eligibility during the report period. Receiving a service alone does not make a client newly enrolled.
• Service-receipt flags: base these flags on qualifying paid services. Exclude reversed claims. In general, keep retroactively reimbursed services in client reporting and report the reimbursement in Recipient funding.
• Recipient expenditure total: the ADR system adds Questions 6a through 6d.
• Insurance and medication amounts: report whole-dollar totals or per-dispense amounts under the documented category rules. Medication assistance means ADAP paid for the medication in full; deductible and co-pay help belongs under insurance services.
• Premium months: count every covered month, including covered months outside the Client Report period, and do not prorate partial premiums. The allowed range remains unresolved across sources.
• Clinical values: report every test performed during the period using the specimen or blood-draw date. Convert a logarithmic viral-load result to copies per milliliter before submission. The reviewed ADR sources do not state the conversion equation or rounding rule. For an undetectable result, use the assay's lower limit, or zero when that limit is unavailable.

The calculated_or_derived and calculation_or_derivation columns identify these and other values that are assigned, classified, transformed, counted, or calculated.

Known source conflicts and defects

• Race element ID: the technical guide assigns Race ID 5. The manual says Gender ID 6 was removed but incorrectly labels Race as ID 6 in two places, and the CAREWare guide repeats that error. The dictionary uses ID 5 and records ID 6 only as a source error or alias, not as a second submitted element.
• Last eligibility confirmation: the manual removes LastEligibilityConfirmationDate (ID 17) from the 2025 element list, but guide v3.7 still includes it as an optional XML element and active check 112 still tests it. The dictionary labels it as a legacy, conflicted element that must be confirmed against the current XSD; check 112 keeps the same warning.
• Policy requirement versus XML acceptance: the manual calls most client elements required for reporting, while the guide marks several of them Required: No even when it shows one occurrence per client. The dictionary records policy status and XML occurrence separately. A file passing schema upload does not prove that its reporting data are complete.
• Premium-month range: guide v3.7 says 0–15, while validation check 108 and the CAREWare guide say 1–18. The manual gives an example of 13 months and explains why coverage can extend outside the report period, but it does not set a maximum. Confirm the range in the current XSD or live system.
• Zero-dollar amounts: the XML guide permits zero for premium, co-pay/deductible, and medication amounts. The manual generally requires $1–$100,000 when the related service was received and says to round a positive amount below $1 up to $1. Validations also warn when a service is reported with a missing or zero amount. The dictionary therefore notes zero as schema-permitted but generally incomplete under the business rule when a related service was received.
• Recipient funding total: the manual allows all eight Question 5 funding sources to be zero when none were received. Check 14 warns when their total is not greater than zero. The check is kept as a review warning, not treated as proof that the manual bans an all-zero response.
• Date separators and sample XML: the manual shows MM/DD/YYYY, while guide v3.7 describes mm,dd,yyyy and gives comma-separated examples. Some guide examples also contain malformed tags. Confirm the wire format in the current XSD or upload tester; do not copy the sample XML without checking it.
• XML nesting and CLD_ID: the guide's early overview can be read as placing the client complex elements directly under the root, while its later revised sample nests them inside AdrClientReport. This dictionary follows the later nested sample. The guide also says CLD_ID applies to its seven listed client complex elements, but both revised samples omit the attribute. Confirm the hierarchy and attribute placement against the current XSD.
• eUCI length and codes: the manual describes a 40-character alphanumeric SHA-1 result. The guide calls for 40 uppercase hexadecimal characters plus one letter from A through Z and shows 41 characters. The XML sex code for Unknown is 4, while the UCI input code for Unknown is 9; these are different code systems. Use the approved HAB generator and confirm the submitted length against the current XSD and eUCI guidance.
• Validation aliases: published messages include misspelled or older names such as LastEligibilityConfimationDate, EnrollmenStatusAtEndOfYearId, and HIVAIDSStatusId. The dictionary maps a message to the current guide element when possible while preserving the original name as an alias or provenance note.
• Manual Appendix A: Appendix A repeats Ethnicity at the end of the demographics list, and its second page is mislabeled Appendix B in the footer. The repeated line does not create a second field.

Limits

The reviewed source set does not contain:

• the current ADR XSD files and lookup tables from the 2025 download package;
• a formal Recipient Report/EHB field schema with exact input types, lengths, identifiers, and all interface-required markers;
• the current Question 7a–7c medication formularies or stable medication identifiers;
• the eUCI Application User Guide and full UCI normalization rules;
• executable validation logic—the validation PDF contains human-readable messages only; or
• reliable authorship, version, and system-applicability details for the CAREWare location guide.

Because of these gaps, web-form types are labeled as inferred when needed, current formulary choices are not invented, warning thresholds are not treated as code-set limits, and unresolved XML details are flagged rather than guessed. This package is specific to the 2025 ADR and should not be treated as a 2026 reporting specification merely because several supporting documents were published in 2026.

Updating this public snapshot

This repository is published from the reviewed HAB Informatics working notebook. Its GitHub Pages workflow runs only when manually dispatched; ordinary pushes do not deploy the site.