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. 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. 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 PUFBenefits and Cost Sharing PUFCMS Medicare Advantageplan benefit package filesPBP Benefits, 1 zipper contract yearfrom-marketplace-puf.jsfrom-pbp.jsBenefit Plan StandarddocumentJSON, one per planSchema v1.1.0 (current)v1.2.0 draft for Medicare Advantageto-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
unzip plan-attributes-puf.zip && unzip benefits-and-cost-sharing-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 date in data/puf/2026/download.json ({"downloaded": "YYYY-MM-DD"}) and in data/pbp/2027/download.json ({"downloaded": "YYYY-MM-DD", "release_label": "PBP Benefits-2027"}). 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 into a BPS v1.1.0 document:

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 draft 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.

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 BPS document against the schema version it declares, 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 --schema schema/v1.2.0/benefit-plan.schema.json 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.