What a machine-readable file actually is

Definition

The three words, one at a time § 180.20

CMS defines a machine-readable file as “a single digital file that is in a machine-readable format,” and a machine-readable format as a digital representation of data that can be imported or read into a computer system for further processing.¹ Each word is doing work.

Before July 2024 that was almost the whole specification, and the result was predictable: thousands of files, each internally consistent and mutually incomparable. Hospitals chose their own column names, their own encodings of “cash price”, their own idea of what counted as an item. The rule was met and the data was unusable in aggregate. The CY2024 OPPS/ASC final rule closed that by requiring a CMS template — a fixed layout, fixed column headers and a published data dictionary — for every file from 1 July 2024 onward.⁵

Standard charges

Five prices for the same MRI § 180.20

The word “price” does not survive contact with hospital billing. A single procedure carries a whole family of numbers, and the rule requires all of them. This is the part most readers find surprising: the file does not have a price column.

So a single chest CT at a single hospital produces one gross charge, one cash price, one min, one max, and one negotiated charge for every plan the hospital contracts with. A mid-sized hospital with forty plans and forty thousand chargeable items is publishing something on the order of a million rows before anyone has argued about what an “item” is.

Format

Three legal shapes for the same data § 180.50(c)(2)

CMS publishes the template in three layouts.² A hospital picks one. All three carry the same required data elements; they differ only in how the payer dimension is folded.

In the 27 August 2026 crawl, of the files whose format could be read: 1,751 were CSV, 644 were JSON, and two were .xlsx — a format the template does not offer.⁷

The CSV files have a three-row header

This trips up nearly everyone reading one for the first time. A CSV MRF is not a normal CSV. Row 1 is a set of column headers describing the file and the hospital. Row 2 holds their values — one row, once, for the whole file. Row 3 is the real header row for the charge data, and the charge rows begin at row 4.³ Point a naive parser at it and every column name will be wrong.

hospital_name,last_updated_on,version,location_name,hospital_address,type_2_npi,license_number | MD,attester_name,To the best of its knowledge and belief, this hospital has included all applicable standard charge information…
Example Regional Medical Center,2026-01-14,3.0.0,Example Regional Medical Center,120 Mercy Way Baltimore MD 21201,1487654321,21-0143,Dana Whitfield,true

Worked example

One row, read closely

Here is a single item in the CSV “tall” layout, from row 3 down. Several columns are elided for width; the ones shown are the ones that carry meaning.

description,code | 1,code | 1 | type,setting,standard_charge | gross,standard_charge | discounted_cash,payer_name,plan_name,standard_charge | negotiated_dollar,standard_charge | min,standard_charge | max,standard_charge | methodology,additional_generic_notes
CT scan chest w/o contrast,71250,CPT,outpatient,2841.00,1136.40,Aetna,Choice POS II,612.75,498.10,1204.00,fee schedule,—
CT scan chest w/o contrast,71250,CPT,outpatient,2841.00,1136.40,UnitedHealthcare,Choice Plus,498.10,498.10,1204.00,fee schedule,—
…one further row per payer plan, for this one CPT code

Three things in that example are worth flagging, because they are where real files go wrong.³

• Blanks are meaningful. CMS is explicit that a hospital must leave a cell empty when it has no applicable data — not N/A, not 0, not –. Entering a placeholder is itself a deficiency, as is a dollar sign inside a numeric field.
• The code column is indexed. The header is code | 1 and code | 1 | type, repeating as code | 2 and so on, because one item routinely carries a CPT code, a revenue code and an internal chargemaster code at once. Twenty-one code types are valid values, from CPT and NDC through MS-DRG to LOCAL.
• Methodology is an enumeration, not prose. Exactly five values are legal: case rate, fee schedule, percent of total billed charges, per diem, and other — with other requiring an explanation in the notes column.

Required fields

The data dictionary, in full § 180.50(b)(2)

These are the data elements a file must encode to conform to CMS template v3.0.0, the version in force since 1 January 2026.³ Column names are the CSV “tall” spellings; the wide and JSON layouts carry the same elements under their own conventions.

About the file and the hospital

About each item or service

About the money

Three optional elements are also defined, so that hospitals which want to disclose them do so uniformly: financial_aid_policy, general_contract_provisions (stop-loss, lesser-of and carve-out terms that apply at claim level rather than line level), and billing_class.³

The hard case

When the price is not a number § 180.50(b)(2)(ii)(C)

A large share of hospital contracts do not set a dollar amount for a procedure. They set a rule: a percentage of the Medicare rate, or of billed charges, or a case rate modified by an outlier formula. This is the single hardest problem in the whole regime, and CMS has now changed its answer twice.

The rule’s position is that a hospital must publish a dollar amount whenever a dollar amount can be derived. If the contract says 70% of a known fee schedule, the hospital is required to do the arithmetic and publish the result in negotiated_dollar — not to publish “70%” and leave the reader to find the schedule.³ The percentage and algorithm columns exist only for charges that genuinely cannot be resolved in advance.

But a file full of percentages is still a file without prices, so CMS added a requirement to report what the hospital was actually paid:¹

• 1 Jan 2025 – 31 Dec 2025. An estimated allowed amount: the average dollar amount the hospital had historically received from that payer for that item.
• From 1 Jan 2026. That single average is gone. In its place, a distribution: the 10th percentile, the median and the 90th percentile of allowed amounts actually received, plus the count of remittances behind them.

The mechanics are tightly specified. Amounts come from EDI 835 electronic remittance advice data, or an equivalent source, over a window no shorter than 12 months and no longer than 15 months before the file is posted. Zero-dollar remittances are excluded. Where a percentile falls between two observations, the next highest observed value is used. The count is encoded as a whole number, except that anything from one to ten must be written as the literal string 1 through 10 — a small-cell rule that stops the file from re-identifying an individual patient’s claim.³

Practicalities

Why these files are enormous

Items × payers × plans × settings, with no compression required and a regulatory duty to keep the whole thing digitally searchable. The arithmetic does the rest.

Across the 3,486 files this project fetched and read in the 27 August 2026 crawl, the total came to roughly 571 GB — an average of about 164 MB per hospital, with the largest well into the gigabytes.⁷ That is the raw published price data of the American hospital system, and it is small only by the standards of things that are not spreadsheets.

Two consequences follow, and both shape how this tracker works. First, you cannot casually download a national sample; the audit reads MRF headers with HTTP range requests rather than pulling whole files, which is how it can check the template version and last_updated_on for thousands of hospitals without moving hundreds of gigabytes. Second, plenty of hospitals put these files behind a CDN that treats an automated fetch of a 200 MB object as an attack — 186 hospitals in the last crawl refused automation outright, which is recorded as Blocked rather than as a failure, because a hospital that blocks a crawler may be perfectly compliant to a human with a browser.⁷

Version drift is real

The version field is self-reported, and hospitals report some remarkable things. In the last crawl, 2,630 files declared a 3.0 template, but 112 still declared 2.0, four declared 1.0, and a scattering claimed versions CMS has never published — 37 files asserted “4.0” and one “2026.1”.⁷ A declared version is a claim about a file, not a fact about it; this audit records the claim and does not validate the file against the schema. CMS publishes an online and command-line validator that does.⁶

Reading the data

What an MRF cannot tell you

The file is a disclosure of contracted rates. It is not a quote, and treating it as one produces confident nonsense.

The same caution applies to this tracker, in the other direction. A hospital marked Compliant here has published a file that could be found, fetched and parsed. Whether its contents are accurate, complete, or even internally consistent is a different question, and one that reading the file — not the pointer to it — is required to answer.

References

Sources

Every regulatory claim on this page is cited to its paragraph in the current Code of Federal Regulations. Everything about the template itself comes from CMS’s own technical implementation guide, which is the normative specification the regulation points at.

1. 45 CFR Part 180 — Hospital Price Transparency Electronic Code of Federal Regulations, current text. ecfr.gov/current/title-45/part-180 Used for: every definition, requirement, deadline and penalty described on this page. The § chips beside each heading link straight to the paragraph relied on.
2. Hospital Price Transparency — technical implementation guide CMS, github.com/CMSgov/hospital-price-transparency Used for: the three template layouts, the implementation timeline, and the 1 April 2026 enforcement date for the v3.0 data elements.
3. Hospital Price Transparency CSV Data Dictionary v3.0 CMS, documentation/CSV Used for: column names, the three-row CSV header, valid values for code type and methodology, the treatment of blanks, the percentage-versus-dollar instruction, the allowed-amount calculation window and the 1 through 10 small-cell rule.
4. Guide for Updating from Data Dictionary v2.2 to v3.0 CMS, documentation/UPDATE_GUIDE.md Used for: what changed in v3.0 — attestation replacing affirmation, the new attester and NPI elements, the renamed location field, and the allowed-amount elements replacing the estimated allowed amount.
5. CY2024 Hospital Outpatient PPS / ASC final rule 88 FR 82184, 22 November 2023. federalregister.gov Used for: the introduction of the mandatory CMS template from 1 July 2024, and the data elements phased in on 1 January 2025.
6. Hospital Price Transparency tools — validator, naming wizard, TXT file generator CMS, cmsgov.github.io/hpt-tool Used for: the existence of an official validator that tests a file against the template, which this audit deliberately does not attempt.
7. CMS HPT Tracker — national crawl, 27 August 2026 This project. Snapshot in data/hpt-audit/; results at tracker.html. Used for: file counts, formats, total and average file size, declared template versions, and the count of hospitals blocking automated access.