2025 RSR data dictionary

Public snapshot for rsr.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 Ryan White HIV/AIDS Program Services Report (RSR). It covers the Recipient Report, Provider Report, provider-level totals, file information, and client-level XML data for reporting year 2025.

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, 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 submitted fields, required XML structures, and labeled system outputs.
• Code sets CSV — one row per documented code and label, including the manual Element ID-to-XML ServiceID crosswalk.
• Validation rules CSV — reviewed system checks, their severity, and the fields they affect.

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

Seven data levels

The dictionary uses seven levels instead of putting every non-client item into one broad “other” category:

1. File metadata — information about the XML file, reporting year, software, and technical contact.
2. Recipient/award — recipient identity, award information, contacts, providers, funded services, and certification responses.
3. Provider organization — organization identity, address, ownership, contacts, and organization characteristics.
4. Provider program — program contacts, funding confirmation, quality management, and program-level responses.
5. Service delivery site — site address, phone, website, and services connected to the site.
6. Provider aggregate — totals submitted for HIV counseling and testing, medications for addiction treatment, and clients by ZIP code, plus clearly labeled counts calculated by the RSR system.
7. Client level — one client’s encrypted identifier, demographics, service use, and clinical information.

Some provider or system identifiers appear inside a client XML record. They are labeled by what they describe, not simply by where they appear in the file.

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. Many client fields depend on the services a client received.
• Prepopulated / confirm — another HRSA system or contract record supplies the value, and the reporter reviews or certifies it.
• Optional — the reviewed sources allow the value but do not make it a condition of submission.
• System-tracked — the system assigns, calculates, or records the value; the reporter does not enter it as a normal field.

The occurrence column tells you 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 service.

The validation file also uses three 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 106 active checks in the reviewed report. Checks 41 and 42 are intentionally excluded because the source marks them disabled.

How the sources were used

The package was built from all three documents in Bureau/Reports/RSR:

1. 2025 RSR Instruction Manual — controls reporting scope, current terms, plain-language meaning, service-based conditions, and Recipient/Provider web-form content.
2. RSR Data Dictionary and XML Schema Implementation Guide v3.10 — controls client XML tag names, paths, codes, formats, order, and occurrence when those technical details are stated.
3. 2025 RSR Validation Report, revised October 2025 — supplies required-field checks, cross-field rules, calculations, and Error/Warning/Alert severity.

When sources disagree, the dictionary keeps the conflict in the source_note column instead of silently combining the rules. For an XML implementation, confirm unresolved differences against the current official XSD and live RSR system.

Calculation highlights

• Encrypted UCI (eUCI): use an approved HAB UCI/eUCI tool. Known inputs include the client’s full date of birth, sex at birth, and consistently recorded name information. The submitted value is a 41-character encrypted identifier. The reviewed documents do not publish the full encryption algorithm.
• Federal poverty level percent: generally calculated as annual household income divided by the poverty measure for the household size, multiplied by 100. HAB prefers HHS poverty guidelines unless the organization already uses Census thresholds. The sources do not give a complete household-size or rounding method.
• Service visits: count distinct service days for each client and service category. Two visits in the same category on the same day count as one day. Report 1–365; omit a service category with no visits.
• Viral load: convert a logarithmic result L to copies per milliliter with 10^L. For “not detected,” report the test’s lower limit; use zero only when that limit is unknown. Viral suppression is later identified from the submitted result and is not a separate submitted field.
• HIV counseling and testing totals: negative and positive counts cannot exceed the total tested, and their sum cannot exceed the total. Referred-to-care cannot exceed either the positive count or total tested. These are checks; one count should not be invented from the others.
• ZIP totals: submit a positive client count for each residence ZIP. Use the most recent residence, a service-site ZIP as a proxy when needed, or 99999 when neither is known. The system compares the ZIP total with the distinct client-level population.
• System and contract values: Provider ID and registration code are system assigned. Provider, funded-service, and funding-source information may be pulled from contract records for review and certification.

The calculated_or_derived and calculation_or_derivation columns identify these and other assigned, classified, transformed, counted, or time-based values.

Known source conflicts

• The manual uses UEI; some validation messages still say the older term DUNS. The dictionary treats DUNS as a legacy label, not a second field.
• Provider HIV counseling and testing question numbers shift between the manual and validation report. Stable field meanings are used, with both references noted.
• Several client XML names and paths differ between the manual and implementation guide, including capitalization. XML is case-sensitive, so the current XSD should settle these differences.
• The sources disagree about when NewClient, ReceivedServicePreviousYear, and some Ending the HIV Epidemic (EHE) Initiative fields are required.
• Some fields are described as required even though the guide lists XML occurrence as 0–1. The guide also conflicts with itself about omitting unavailable values versus marking the poverty tag as having no value (xsi:nil).
• Date examples use both comma-separated and slash-separated forms, and a few sample XML values or tags contain apparent document errors. Do not copy a sample without checking the current XSD.

Limits

The local source set does not contain the official XSD files, a formal Recipient/Provider web-form schema, the ZIP upload template, the complete UCI algorithm, a complete poverty calculation and rounding method, or the web system’s client merge rules. Because of these gaps:

• web-form types are marked as inferred when no formal type is published;
• warning thresholds are shown as validation rules, not treated as allowed-value limits;
• unresolved XML details are flagged rather than guessed; and
• this 2025 dictionary should not be treated as a 2026 reporting specification, even though the 2025 manual was released in February 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.