Skip to main content

FHIR InsurancePlan Files

Each of the 10 Benefit Plan Standard examples read from a published plan document, and each of the 5 imported from the CMS Medicare Advantage PBP files, is also published as a FHIR R4 InsurancePlan. (The 5 examples imported from the CMS Marketplace public files are converted too, but are not published here.) The FHIR files are produced by a converter in the schema repository (scripts/to-insuranceplan.js), which anyone can run locally.

How the CMS files reach the converter through the two importers, with every command, is on How the data flows.

These are static JSON files, not a FHIR API. There is no FHIR server, endpoint, search, _format parameter or other REST behavior. You download a file the same way you would download any other file from this site. Inside each file, the Bundle.entry.fullUrl values are urn:uuid: identifiers, not addresses.

Profile status​

Each InsurancePlan targets the CARIN Digital Insurance Card SBC InsurancePlan profile (http://hl7.org/fhir/us/insurance-card/StructureDefinition/sbc-insurance-plan).

That profile is draft and experimental. It exists only in the ballot package hl7.fhir.us.insurance-card#2.0.0-ballot (STU 2 ballot, September 2026), not in any published release of the CARIN Digital Insurance Card IG. The same goes for its extensions (DeductibleApplies, CostAppliesToNetwork, BenefitLimitation) and the code systems it binds. The files are validated against that ballot package and will be refreshed once STU 2.0.0 publishes.

The files​

The 15 published files​

The list is also available as JSON: /fhir/index.json. The index is a plain JSON list, not a FHIR resource.

The 10 files read from plan documents​

FilePlanBPS schemaBenefits placedBenefits outside the SBC codes
aetna-ppo-1500-80-50.jsonAetna FL PPO 1500 80/50 CY V251.1.0261
aetna-ppo-5000-80-50.jsonAetna FL PPO 5000 80/50 CY V251.1.0261
ambetter-ca-silver-94-hmo.jsonHealth Net of CA: Silver 94 Ambetter HMO1.1.0273
cigna-oap-bowdoin.jsonBowdoin College: Open Access Plus (Cigna)1.1.0264
flblue-blueoptions-505.jsonFlorida Blue BlueOptions 5051.1.0274
gatorcare-prime-epo.jsonFlorida Blue BlueOptions 03768 - Prime EPO Plan (GatorCare)1.2.03611
humana-gold-plus-h1036-025-hmo.jsonHumana Gold Plus H1036-025 (HMO). Medicare Advantage, read from the CMS Summary of Benefits, validates against v1.2.0, not v1.1.0.1.2.02646
kaiser-ca-gold-80-hmo.jsonKAISER PERMANENTE®: Gold 80 HMO1.1.0283
scan-classic-hmo-los-angeles.jsonSCAN Classic (HMO), Los Angeles County (SCAN Health Plan). Medicare Advantage, read from the CMS Summary of Benefits, validates against v1.2.0, not v1.1.0.1.2.02249
uhc-choice-plus-hsa-gold-1700.jsonUnitedHealthcare® UHC Choice Plus HSA Gold 1700-41.1.0263

The two Medicare Advantage files come from CMS Summary of Benefits documents, which are not SBCs. They conform structurally to the SBC profile, but most of their benefits (dental, vision, hearing, supplemental benefits, Part B drugs) have no code in the SBC benefit category code system, so those benefits are listed by identity only (see below).

Note, accumulator tier ids (October 21, 2026). The Benefit Plan Standard documents behind the Humana H1036-025 and SCAN Classic files declare Benefit Plan Standard schema 1.2.0, and each wrote in-network as the network_tier of its 2 accumulators. On October 21, 2026 those 4 values became IN, the tier_id of the in-network tier, which is how the Benefit Plan Standard schema 1.2.0 describes network_tier and how the Medicare Advantage importer (scripts/from-pbp.js) and the Marketplace importer (scripts/from-marketplace-puf.js) write it. The Benefit Plan Standard converter (scripts/to-insuranceplan.js) re-converted the 2 files the same day; their benefit counts above and their validation result are unchanged.

The 5 Medicare Advantage PBP files​

These 5 are produced by the CMS Medicare Advantage PBP importer and converted by the same converter. In /fhir/index.json each carries the label "Medicare Advantage, imported from the CMS PBP benefits files for contract year 2027, validates against v1.2.0, not v1.1.0."

FilePlanBPS schemaBenefits placedBenefits listed by name only (outside the SBC codes, and Part D)
aarp-medicare-advantage-from-uhc-fl-0021-ppo-h2406-013-000.jsonAARP Medicare Advantage from UHC FL-0021 (PPO), H2406-013-000 (UnitedHealthcare)1.2.01655 (22 and 33 Part D)
humana-gold-plus-h1036-068-hmo-h1036-068-000.jsonHumana Gold Plus H1036-068 (HMO), H1036-068-0001.2.01664 (22 and 42 Part D)
aetna-medicare-select-extra-hmo-pos-h1609-028-000.jsonAetna Medicare Select Extra (HMO-POS), H1609-028-0001.2.01689 (22 and 67 Part D)
upmc-for-life-ppo-rx-choice-ppo-h5533-019-000.jsonUPMC for Life PPO Rx Choice (PPO), H5533-019-0001.2.01689 (22 and 67 Part D)
scan-costco-medicare-advantage-hmo-h5425-140-000.jsonSCAN Costco Medicare Advantage (HMO), H5425-140-000 (SCAN Health Plan)1.2.01689 (22 and 67 Part D)

Each holds the 38 medical benefits of its Benefit Plan Standard document, 16 placed and 22 listed by name only, and since October 24, 2026 its Part D benefits, all listed by name only: the SBC InsurancePlan profile has no coverage stage, pharmacy network or day supply to tell a tier's Part D rows apart. The Part D deductible and out-of-pocket threshold are plan-level costs (plan.generalCost). The importer's 2 stand-alone Part D plans are not converted, because the profile describes a medical plan. Since November 4, 2026 (draft 8) each inpatient hospital benefit carries 1 more BenefitLimitation, with limitText and limitType days and no value: the plan files its additional inpatient days as unlimited, and the profile has no element for no limit. Since November 11, 2026 (draft 9) each file's Premium cost carries a comment that the amount is the monthly premium without its Part D part, which no PBP file states. Since October 20, 2026 the Medicare Advantage importer (scripts/from-pbp.js) also reads preventive services (PBP category 14a) into a preventive_care benefit, which the Benefit Plan Standard converter (scripts/to-insuranceplan.js) places under the SBC code preventive-care: that is the 16th placed benefit. An HMO-POS plan, such as the Aetna file, also carries a point-of-service tier (see below).

Fetching a file​

curl -O https://benefitplanstandard.org/fhir/InsurancePlan/aetna-ppo-1500-80-50.json
curl https://benefitplanstandard.org/fhir/index.json

Each file is a FHIR Bundle of type collection with two entries: the InsurancePlan and the Organization named in InsurancePlan.ownedBy. File names and resource ids come from the BPS plan_id, and the files stay byte-identical from one run to the next.

Reading a file​

  • Benefits. A benefit appears in both InsurancePlan.coverage[].benefit[] and InsurancePlan.plan[0].specificCost[].benefit[]. Its type carries an SBC benefit category code, followed by the BPS canonical benefit key as a second coding.
  • Benefits outside the SBC codes. The profile requires every benefit type to come from a 29-code SBC benefit category code system. A BPS benefit with no code there, such as chiropractic care, acupuncture or bariatric surgery, is not placed in coverage or specificCost. It is listed in a bps-unmapped-benefit extension on the InsurancePlan, which identifies the benefit but does not carry its cost sharing. Home health care is in this group for the eight SBC plans, for SCAN and for the 5 PBP files, because the code system has no general home health code. (The Humana Summary of Benefits file has no home health benefit.) Since October 24, 2026 the Part D benefits of the 5 PBP files are in this group too, whatever their key, because the profile has no coverage stage, pharmacy network or day supply.
  • Not covered. A cost entry with type text Not covered has no amount; its value carries a data-absent-reason of not-applicable. It is not a $0 cost.
  • Not stated in the BPS document. The profile requires at least two cost entries per benefit. When the BPS document gives only one (for example, a benefit the BPS file prices only in network), a second entry is added for the missing network with this text and a data-absent-reason of unknown. It does not mean the benefit is covered or not covered there.
  • Covered; amount not stated in the BPS document. The BPS document marks the benefit as covered in that network but records no amount.
  • Contact. The Benefit Plan Standard schema 1.2.0 draft gained contacts (the member services phone and website) and network_tiers[].provider_directory_url on October 20, 2026, and the Medicare Advantage importer (scripts/from-pbp.js) fills them in the documents behind the 5 PBP files: the phone in all 5, the website in 1 and the provider directory link in 2, where the CMS file gives a full address. The Benefit Plan Standard converter (scripts/to-insuranceplan.js) does not map them yet. In every file the required contact is present with a data-absent-reason of unknown and no phone number or URL, and in the 5 PBP files the phone, website and directory link are carried only as quoted text in bps-source-reference extensions.
  • Page references. The eight SBC files carry page references for the plan document as a whole, on the InsurancePlan, in bps-source-reference extensions. They are not per-benefit citations, except that GatorCare also carries them on its 8 placed pharmacy benefits, and each of its references names its PDF in the document part. The two Summary of Benefits files also carry page references on each placed benefit. The 5 PBP files carry a source reference on each placed benefit too, naming the PBP service category and file, with no page.
  • Everything else from BPS (network tier ids, cost-share basis, out-of-pocket applicability, accumulator period, conditions, market, schema version) is carried in bps-* extensions.

Note, limits and conditions (October 5, 2026). The 8 SBC files were regenerated on October 5, 2026 from examples corrected against their PDFs. They now carry the limits and conditions printed in the SBC Limitations column: structured limits as BenefitLimitation extensions on coverage.benefit, and the condition text, including limit wording that a structured limit cannot hold, in coverage.benefit.requirement. Limits on benefits outside the SBC codes, such as home health care and chiropractic care, are not carried.

Note, a second in-network tier. The converter now maps a second in-network tier (IN2, as written by the CMS Marketplace public files importer) to in-network with a cost-tier qualifier: the code value-choice when the tier name says "Value Choice", and text only otherwise. Tier 1 entries carry no qualifier. None of the 15 files here has a second in-network tier.

Note, the point-of-service tier. The converter maps the POS tier of an HMO-POS plan, as written by the CMS Medicare Advantage PBP importer, to out-of-network with the text-only qualifier Point-of-service option. Before it did, it refused the tier. The 10 files read from plan documents are byte-identical before and after.

BPS extension definitions​

The bps-* extensions and the BPS canonical benefits code system are draft, and are published as static files:

  • https://benefitplanstandard.org/fhir/StructureDefinition/<name>.json, for bps-source-reference, bps-plan-metadata, bps-identifier-source, bps-benefit, bps-condition, bps-cost-share, bps-accumulator and bps-unmapped-benefit
  • https://benefitplanstandard.org/fhir/CodeSystem/canonical-benefits.json, version 1.4.0, 124 concepts, built from the Benefit Plan Standard canonical benefit vocabulary 1.4.0

Their canonical URLs (https://benefitplanstandard.org/fhir/StructureDefinition/<name> and https://benefitplanstandard.org/fhir/CodeSystem/canonical-benefits, without .json) redirect a browser to the .json file. The validator does not fetch them from this site: it loads the CARIN definitions from the hl7.fhir.us.insurance-card#2.0.0-ballot package and the BPS definitions from fhir/definitions in the schema repository, as shown below.

Running the converter locally​

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

# Convert one BPS document (v1.1.0 or v1.2.0); the Bundle is written to stdout
node scripts/to-insuranceplan.js examples/aetna_example.json > aetna.fhir.json

# Run the tests (fails if output drifts from the files in examples/fhir/)
node --test scripts/to-insuranceplan.test.js

The converter makes no network calls and keeps no state. It checks the input against the BPS schema version the document declares, and exits with an error rather than guessing when a document has something it cannot map, such as a network tier it does not recognize. The mapping is specified in docs/specs/insuranceplan-converter.md.

Validating​

With the HL7 FHIR validator (validator_cli.jar), from the schema repository:

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 \
examples/fhir/*.json

The command above covers all 15 files in the folder. The current result, per group, all with validator 7.0.0:

  • The 10 files read from plan documents: 0 errors and 75 warnings. 7 of the 8 SBC files were last run on October 13, 2026 (fifth run), with the same counts on October 31, 2026 (tenth run) and November 1, 2026 (eleventh run). The GatorCare file was run on those 2 dates, after it gained its pharmacy side and after its market came out, with the same 1 warning. The Humana H1036-025 and SCAN Classic files were run on October 21, 2026 (seventh run), after the Benefit Plan Standard converter re-converted them with accumulator tier id IN, with the same 42 and 4 warnings as before.
  • The 5 Medicare Advantage PBP files: 0 errors and 17 warnings, run on October 20, 2026 (sixth run), after the Medicare Advantage importer (scripts/from-pbp.js) gained preventive services, the premium, the contacts and the provider directory link. The 1 new warning is a text-only Point-of-service option qualifier on the Aetna file's preventive services benefit.
  • The 5 Marketplace Bundles in examples/fhir-puf/, which are not published here: 0 errors and 91 warnings, run on October 21, 2026 (seventh run), after the Marketplace importer (scripts/from-marketplace-puf.js) moved accumulator tier ids to IN and OUT.

The warnings, all of them expected, are listed and explained in examples/fhir/VALIDATION.md.