Skip to main content

How the data flows: from CMS files to FHIR

Two public CMS inputs, each read by its own importer, become one Benefit Plan Standard (BPS) document per plan; a third, the CMS Part D formulary file, adds a Medicare plan's drug list (Import Part D drug lists, not drawn). One converter, scripts/to-insuranceplan.js, turns that document into one output: a FHIR InsurancePlan file, and it is the only step that writes FHIR.

How the data flows: from CMS files to FHIRThe CMS Marketplace public use files are read by from-marketplace-puf.js and the CMS Medicare Advantage plan benefit package files are read by from-pbp.js. Both write a Benefit Plan Standard document on the Benefit Plan Standard schema 1.2.0. to-insuranceplan.js converts the document into an InsurancePlan in the CARIN Digital Insurance Card profile, FHIR R4, one file per plan.CMS Marketplacepublic use filesPlan Attributes, Benefits andCost Sharing, and Network PUFsCMS Medicare Advantageplan benefit package filesPBP Benefits, 1 zipper contract yearfrom-marketplace-puf.jsfrom-pbp.jsBenefit Plan StandarddocumentJSON, one per planSchema v1.2.0latest releaseto-insuranceplan.jsInsurancePlan.CARIN Digital InsuranceCard profile, FHIR R4.One file per plan.

The commands below run from the schema repository. Each section links to the page that explains the step.

Get the files​

Clone the schema repository and install the two packages the validator and the importers use. Then download each CMS file set into its git-ignored folder, once per year:

git clone https://github.com/Benefit-Plan-Standard/benefit-plan-schema.git && cd benefit-plan-schema
npm install ajv ajv-formats # one time

# CMS Marketplace public use files, once per plan year
mkdir -p data/puf/2026 && cd data/puf/2026
curl -O https://download.cms.gov/marketplace-puf/2026/plan-attributes-puf.zip
curl -O https://download.cms.gov/marketplace-puf/2026/benefits-and-cost-sharing-puf.zip
curl -O https://download.cms.gov/marketplace-puf/2026/network-puf.zip
unzip plan-attributes-puf.zip && unzip benefits-and-cost-sharing-puf.zip && unzip network-puf.zip
cd ../../..

# CMS Medicare Advantage PBP Benefits files, once per contract year
mkdir -p data/pbp/2027 && cd data/pbp/2027
curl -L -O https://www.cms.gov/files/zip/pbp-benefits-2027.zip
unzip pbp-benefits-2027.zip
cd ../../..

Record the download dates in data/puf/2026/download.json ({"downloaded": "YYYY-MM-DD"}, with "downloaded_files": {"network-puf.zip": "YYYY-MM-DD"} when the Network PUF was downloaded on another day) and in data/pbp/2027/download.json ({"downloaded": "YYYY-MM-DD", "release_label": "PBP Benefits-2027"}). The Marketplace importer needs all 3 Marketplace files. Explained on CMS Marketplace public files and CMS Medicare Advantage PBP files.

Import Marketplace​

List an issuer's plans in a state, then import one plan variant with the Marketplace importer into a document on the Benefit Plan Standard schema 1.2.0 (the Marketplace importer wrote 1.1.0 until October 20, 2026):

node scripts/from-marketplace-puf.js --year 2026 --issuer 40220 --state TX
node scripts/from-marketplace-puf.js --year 2026 --plan 40220TX0080024-01 --out plan.json

Explained on CMS Marketplace public files.

Import Medicare Advantage​

List a contract's plans, then import one plan into a BPS document on the v1.2.0 schema:

node scripts/from-pbp.js --year 2027 --contract H2406
node scripts/from-pbp.js --year 2027 --plan H2406-013-000 --out h2406.json

Explained on CMS Medicare Advantage PBP files.

Import Part D drug lists​

Since November 11, 2026, a third importer, scripts/from-partd-formulary.js, reads the CMS monthly public use file "Prescription Drug Plan Formulary and Pharmacy Network Information" and writes the drug lists of Medicare Part D plans: a formulary list (schema/v1.2.0/formulary.schema.json) once for every plan that shares it, and a plan document that is the Medicare Advantage importer's document for the plan with pharmacy.formulary_reference and the plan's own items. It needs the PBP files above beside the monthly file, which goes, unzipped, into data/partd-formulary/<release>/txt/ with a download.json:

node scripts/from-partd-formulary.js --release 2027_20261008 --plan H2406-013-000 --out plan.json   # 1 plan, its list inline
node scripts/from-partd-formulary.js --release 2027_20261008 --formulary 00027002 --out list.json # 1 list

Specification: docs/specs/partd-formulary-importer.md in the schema repository.

Convert to FHIR​

The converter reads either importer's output unchanged and writes one Bundle per document, to stdout or to a file:

node scripts/to-insuranceplan.js plan.json > plan.insuranceplan.json
node scripts/to-insuranceplan.js h2406.json -o h2406.bundle.json

Explained on FHIR InsurancePlan.

Validate​

Check each document against the Benefit Plan Standard schema 1.2.0, which the importers write and which scripts/validate.js checks against unless --schema names another version (a formulary list: --schema schema/v1.2.0/formulary.schema.json), then check the Bundles with the HL7 FHIR validator against the CARIN Digital Insurance Card ballot package:

node scripts/validate.js plan.json
node scripts/validate.js h2406.json

java -Dfile.encoding=UTF-8 -jar validator_cli.jar -version 4.0.1 \
-ig hl7.fhir.us.insurance-card#2.0.0-ballot \
-ig fhir/definitions \
plan.insuranceplan.json h2406.bundle.json

Explained on FHIR InsurancePlan.

This site does not redistribute CMS files or carrier documents: you download the CMS files from CMS.