HealthSamurai · glebmark · Sep 10, 2026 · Sep 10, 2026
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -90,8 +90,20 @@
     * [Pharmacy](data-integration/carin-bb/pharmacy.md)
     * [Oral](data-integration/carin-bb/oral.md)
   * [Drug Formulary](data-integration/drug-formulary/README.md)
-    * [Payer Plans](data-integration/drug-formulary/payer-plans.md)
+    * [Payer Plans](data-integration/drug-formulary/payer-plans/README.md)
+      * [Plan Identifiers](data-integration/drug-formulary/payer-plans/plan-identifiers.md)
+      * [Plan Contacts](data-integration/drug-formulary/payer-plans/plan-contacts.md)
+      * [Coverage Areas](data-integration/drug-formulary/payer-plans/coverage-areas.md)
+      * [Drug Coverages](data-integration/drug-formulary/payer-plans/drug-coverages.md)
+      * [Drug Coverage Benefits](data-integration/drug-formulary/payer-plans/drug-coverage-benefits.md)
+      * [Drug Plans](data-integration/drug-formulary/payer-plans/drug-plans.md)
+      * [Drug Plan Specific Costs](data-integration/drug-formulary/payer-plans/drug-plan-specific-costs.md)
+      * [Drug Plan Tier Benefits](data-integration/drug-formulary/payer-plans/drug-plan-tier-benefits.md)
+      * [Drug Plan Tier Costs](data-integration/drug-formulary/payer-plans/drug-plan-tier-costs.md)
+      * [Drug Plan General Costs](data-integration/drug-formulary/payer-plans/drug-plan-general-costs.md)
     * [Formularies](data-integration/drug-formulary/formularies.md)
+      * [Formulary Identifiers](data-integration/drug-formulary/formulary-identifiers.md)
+      * [Formulary Contacts](data-integration/drug-formulary/formulary-contacts.md)
     * [Formulary Drugs](data-integration/drug-formulary/formulary-drugs.md)
     * [Formulary Items](data-integration/drug-formulary/formulary-items.md)
 * [Releases](releases.md)
diff --git a/assets/data-integration/coverage_areas.75383ebd.csv b/assets/data-integration/coverage_areas.75383ebd.csv
@@ -0,0 +1,4 @@
+coverage_area_id,name,aliases,status,type_codes,phone,fax,email,url,address_line1,address_line2,city,state,zip,latitude,longitude,region_geojson,managing_org_npi,last_updated,is_deleted
+AREA-NY,New York State,,active,,8885551002,,,https://example.org/areas/ny,,,,NY,,42.9538,-75.5268,,9999999993,2026-10-01T09:00:00-05:00,
+AREA-BRONX,Bronx County,,active,,,,,,,,Bronx,NY,,40.8448,-73.8648,"{""type"":""Polygon"",""coordinates"":[[[-73.933,40.785],[-73.748,40.785],[-73.748,40.916],[-73.933,40.916],[-73.933,40.785]]]}",9999999993,2026-10-01T09:00:00-05:00,
+AREA-US,United States,,active,,,,,,,,,,,,,"{""type"":""Polygon"",""coordinates"":[[[-125.0,24.5],[-66.9,24.5],[-66.9,49.4],[-125.0,49.4],[-125.0,24.5]]]}",9999999993,2026-10-01T09:00:00-05:00,
diff --git a/assets/data-integration/drug_coverage_benefits.a5ea5fb1.csv b/assets/data-integration/drug_coverage_benefits.a5ea5fb1.csv
@@ -0,0 +1,3 @@
+benefit_id,coverage_id,requirement,limit_values,limit_units,limit_codes,is_deleted
+BEN-DSNP-RX,COV-DSNP-RX,Part D covered drugs only,90,days,days-supply,
+BEN-ISNP-RX,COV-ISNP-RX,,,,,
diff --git a/assets/data-integration/drug_plan_general_costs.9c2ffe06.csv b/assets/data-integration/drug_plan_general_costs.9c2ffe06.csv
@@ -0,0 +1,5 @@
+drug_plan_id,cost_type,cost_type_system,group_size,amount,comment,is_deleted
+DP-DSNP,premium,,1,0.00,No monthly premium for members with full Medicaid,
+DP-DSNP,deductible,,1,0.00,,
+DP-ISNP,premium,,1,38.50,,
+DP-ISNP,deductible,,1,590.00,Applies to tiers 3 and above,
diff --git a/assets/data-integration/drug_plan_specific_costs.336af84a.csv b/assets/data-integration/drug_plan_specific_costs.336af84a.csv
@@ -0,0 +1,4 @@
+drug_plan_id,pharmacy_benefit_type,is_deleted
+DP-DSNP,1-month-in-retail,
+DP-DSNP,3-month-in-mail,
+DP-ISNP,1-month-in-retail,
diff --git a/assets/data-integration/drug_plan_tier_benefits.71fa84e0.csv b/assets/data-integration/drug_plan_tier_benefits.71fa84e0.csv
@@ -0,0 +1,11 @@
+drug_plan_id,pharmacy_benefit_type,drug_tier,is_deleted
+DP-DSNP,1-month-in-retail,preferred-generic,
+DP-DSNP,1-month-in-retail,generic,
+DP-DSNP,1-month-in-retail,preferred-brand,
+DP-DSNP,1-month-in-retail,non-preferred-brand,
+DP-DSNP,1-month-in-retail,specialty,
+DP-DSNP,3-month-in-mail,preferred-generic,
+DP-DSNP,3-month-in-mail,generic,
+DP-DSNP,3-month-in-mail,preferred-brand,
+DP-ISNP,1-month-in-retail,preferred-generic,
+DP-ISNP,1-month-in-retail,preferred-brand,
diff --git a/assets/data-integration/drug_plan_tier_costs.8119bc4b.csv b/assets/data-integration/drug_plan_tier_costs.8119bc4b.csv
@@ -0,0 +1,14 @@
+drug_plan_id,pharmacy_benefit_type,drug_tier,cost_type,value,option,applicability,is_deleted
+DP-DSNP,1-month-in-retail,preferred-generic,copay,0.00,no-charge,,
+DP-DSNP,1-month-in-retail,generic,copay,5.00,charge,,
+DP-DSNP,1-month-in-retail,preferred-brand,copay,47.00,charge,,
+DP-DSNP,1-month-in-retail,non-preferred-brand,copay,0.00,copay-not-applicable,,
+DP-DSNP,1-month-in-retail,non-preferred-brand,coinsurance,25,after-deductible,,
+DP-DSNP,1-month-in-retail,specialty,copay,0.00,copay-not-applicable,,
+DP-DSNP,1-month-in-retail,specialty,coinsurance,33,charge,,
+DP-DSNP,3-month-in-mail,preferred-generic,copay,0.00,no-charge,,
+DP-DSNP,3-month-in-mail,generic,copay,10.00,charge,,
+DP-DSNP,3-month-in-mail,preferred-brand,copay,94.00,charge,,
+DP-ISNP,1-month-in-retail,preferred-generic,copay,0.00,no-charge,,
+DP-ISNP,1-month-in-retail,preferred-generic,coinsurance,0,coinsurance-not-applicable,,
+DP-ISNP,1-month-in-retail,preferred-brand,copay,45.00,charge,,
diff --git a/assets/data-integration/drug_plans.84771d8d.csv b/assets/data-integration/drug_plans.84771d8d.csv
@@ -0,0 +1,3 @@
+drug_plan_id,plan_id,identifier_values,identifier_systems,coverage_area_ids,network_ids,is_deleted
+DP-DSNP,PLAN-DSNP,H6776-001-000,http://cms.gov/medicare/ma-plan-id,,NET-001,
+DP-ISNP,PLAN-ISNP,,,,NET-001,
diff --git a/assets/data-integration/formularies.3b50688b.csv b/assets/data-integration/formularies.3b50688b.csv
@@ -0,0 +1,4 @@
+formulary_id,formulary_name,formulary_aliases,status,period_start,period_end,owned_by_org_npi,administered_by_org_npi,network_ids,coverage_area_ids,last_updated,is_deleted
+FORM-2027-A,Example Health 2027 Part D Formulary,,active,2027-01-01,2027-12-31,9999999993,,NET-001,AREA-NY,2026-10-01T09:00:00-05:00,
+FORM-2027-B,Example Health 2027 I-SNP Formulary,,active,2027-01-01,2027-12-31,9999999993,9999999994,NET-001,AREA-NY,2026-10-01T09:00:00-05:00,
+FORM-2026-A,Example Health 2026 Part D Formulary,Example Health 2026 Formulary,retired,2026-01-01,2026-12-31,9999999993,,NET-001,AREA-NY,2026-12-31T23:59:00-05:00,
diff --git a/assets/data-integration/formularies.e38cbf0b.csv b/assets/data-integration/formularies.e38cbf0b.csv
diff --git a/assets/data-integration/formulary_contacts.b4214da9.csv b/assets/data-integration/formulary_contacts.b4214da9.csv
@@ -0,0 +1,3 @@
+contact_id,formulary_id,contact_purpose,contact_name,phone,fax,email,url,address_line1,address_line2,city,state,zip,is_deleted
+CT-FORM-2027-A-PDF,FORM-2027-A,FORMULARY,2027 Part D formulary,,,,https://example.org/formularies/form-2027-a.pdf,,,,,,
+CT-FORM-2027-B-PDF,FORM-2027-B,FORMULARY,2027 I-SNP formulary,,,,https://example.org/formularies/form-2027-b.pdf,,,,,,
diff --git a/...-integration/formulary_drugs.47d248a8.csv → ...-integration/formulary_drugs.56874659.csv b/...-integration/formulary_drugs.47d248a8.csv → ...-integration/formulary_drugs.56874659.csv
@@ -1,4 +1,4 @@
-drug_id,rxnorm_code,rxnorm_form_group_code,rxnorm_display,ndc_codes,gpi_code,status,dose_form_code,dose_form_text,last_updated,is_deleted
+drug_id,rxnorm_code,rxnorm_form_group_codes,rxnorm_display,ndc_codes,gpi_code,status,dose_form_code,dose_form_text,last_updated,is_deleted
 RX-1000091,1000091,1160770,,,,active,,,2026-10-01T09:00:00-05:00,
 RX-1049640,1049640,1185784,,,,active,,TABLET,2026-10-01T09:00:00-05:00,
 RX-209459,209459,1187315,,,,active,385055001,,2026-10-01T09:00:00-05:00,

diff --git a/assets/data-integration/formulary_identifiers.3815ad2e.csv b/assets/data-integration/formulary_identifiers.3815ad2e.csv
@@ -0,0 +1,4 @@
+formulary_id,identifier_value,identifier_system,is_deleted
+FORM-2027-A,00027113,http://cms.gov/medicare/formulary-id,
+FORM-2027-B,00027114,http://cms.gov/medicare/formulary-id,
+FORM-2026-A,00026113,http://cms.gov/medicare/formulary-id,
diff --git a/assets/data-integration/payer_plans.a2023674.csv b/assets/data-integration/payer_plans.a2023674.csv
diff --git a/assets/data-integration/payer_plans.b83c1465.csv b/assets/data-integration/payer_plans.b83c1465.csv
@@ -0,0 +1,3 @@
+plan_id,plan_name,plan_aliases,status,plan_type,period_start,period_end,coverage_area_ids,owned_by_org_npi,administered_by_org_npi,network_ids,last_updated,is_deleted
+PLAN-DSNP,Example Health D-SNP,,active,mediadv,2027-01-01,2027-12-31,AREA-NY,9999999993,,NET-001,2026-10-01T09:00:00-05:00,
+PLAN-ISNP,Example Health I-SNP,,active,mediadvhmo,2027-01-01,2027-12-31,AREA-NY,9999999993,,NET-001,2026-10-01T09:00:00-05:00,
diff --git a/assets/data-integration/plan_contacts.bcd881a6.csv b/assets/data-integration/plan_contacts.bcd881a6.csv
@@ -0,0 +1,7 @@
+contact_id,plan_id,contact_purpose,contact_name,phone,fax,email,url,address_line1,address_line2,city,state,zip,is_deleted
+CT-DSNP-MEMBERS,PLAN-DSNP,PATINF,Member Services,8885551002;8885551099,,members@example.org,,123 Main St,,Anytown,NY,12345,
+CT-DSNP-MARKETING,PLAN-DSNP,MARKETING,Example Health D-SNP plan page,,,,https://example.org/plans/dsnp,,,,,,
+CT-DSNP-SUMMARY,PLAN-DSNP,SUMMARY,Summary of drug benefits,,,,https://example.org/plans/dsnp/benefits,,,,,,
+CT-DSNP-FORMULARY,PLAN-DSNP,FORMULARY,2027 Part D formulary,,,,https://example.org/plans/dsnp/formulary,,,,,,
+CT-ISNP-MEMBERS,PLAN-ISNP,PATINF,Member Services,8885551003,,,,,,,,,
+CT-ISNP-FORMULARY,PLAN-ISNP,FORMULARY,2027 I-SNP formulary,,,,https://example.org/plans/isnp/formulary,,,,,,
diff --git a/assets/data-integration/plan_drug_coverages.1d4b69ed.csv b/assets/data-integration/plan_drug_coverages.1d4b69ed.csv
@@ -0,0 +1,3 @@
+coverage_id,plan_id,formulary_ids,network_ids,is_deleted
+COV-DSNP-RX,PLAN-DSNP,FORM-2027-A,NET-001,
+COV-ISNP-RX,PLAN-ISNP,FORM-2027-B,NET-001,
diff --git a/assets/data-integration/plan_identifiers.c61a2825.csv b/assets/data-integration/plan_identifiers.c61a2825.csv
@@ -0,0 +1,3 @@
+plan_id,identifier_value,identifier_system,is_deleted
+PLAN-DSNP,H6776-001-000,http://cms.gov/medicare/ma-plan-id,
+PLAN-ISNP,H6776-002-000,http://cms.gov/medicare/ma-plan-id,
diff --git a/docs/data-integration/README.md b/docs/data-integration/README.md
@@ -36,4 +36,4 @@ graph LR
 | [USCDI v3.1 Data](uscdi/README.md) | US Core 6.1.0 | 24 |
 | [Provider Directory](provider-directory/README.md) | PDex Plan-Net STU 1.2.0 | 4 |
 | [Claims and Encounters](carin-bb/README.md) | CARIN Blue Button STU 2.1.0 | 10 |
-| [Drug Formulary](drug-formulary/README.md) | PDex US Drug Formulary STU 2.1.0 | 4 |
+| [Drug Formulary](drug-formulary/README.md) | PDex US Drug Formulary STU 2.1.0 | 16 |
diff --git a/docs/data-integration/drug-formulary/README.md b/docs/data-integration/drug-formulary/README.md
@@ -8,16 +8,16 @@ description: >-
 
 ## Datasets
 
-Built to [Da Vinci PDex US Drug Formulary STU 2.1.0](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/). A formulary is the list of drugs a plan pays for, with the tier, cost sharing and coverage rules for each. The IG splits it into four resources, and the feed has one dataset per resource.
+Built to [Da Vinci PDex US Drug Formulary STU 2.1.0](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/). A formulary is the list of drugs a plan pays for, with the tier, cost sharing and coverage rules for each. The IG splits it into four resources plus the locations a plan is offered in; the feed has one dataset per resource, and the payer plan, whose profile nests several repeating structures, is a group of eleven datasets, one per repeating element.
 
 | Dataset | US Drug Formulary STU 2.1.0 target profile |
 |---|---|
-| [`payer_plans`](payer-plans.md) | [Payer Insurance Plan](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-PayerInsurancePlan.html) (InsurancePlan), with its coverage area as [Insurance Plan Location](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-InsurancePlanLocation.html) |
-| [`formularies`](formularies.md) | [Formulary](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-Formulary.html) (InsurancePlan) |
+| [`payer_plans`](payer-plans/README.md) and its ten child datasets | [Payer Insurance Plan](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-PayerInsurancePlan.html) (InsurancePlan), with its coverage areas as [Insurance Plan Location](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-InsurancePlanLocation.html) (Location) |
+| [`formularies`](formularies.md), [`formulary_identifiers`](formulary-identifiers.md), [`formulary_contacts`](formulary-contacts.md) | [Formulary](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-Formulary.html) (InsurancePlan) |
 | [`formulary_drugs`](formulary-drugs.md) | [Formulary Drug](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-FormularyDrug.html) (MedicationKnowledge) |
 | [`formulary_items`](formulary-items.md) | [Formulary Item](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-FormularyItem.html) (Basic) |
 
-The four fit together this way. A payer plan states its drug benefit as a cost-sharing table, one cell per pharmacy benefit type and drug tier, and points at the formulary it uses. A formulary is a named list for a plan year. A formulary drug is one prescribable product, identified by RxNorm. A formulary item is the row of the list: this drug, on this formulary, in this tier, with these requirements.
+They fit together this way. A payer plan states its drug benefit as a cost-sharing table, one cell per pharmacy benefit type and drug tier, points at the formulary it uses, and names its coverage areas and contacts. A formulary is a named list for a plan year. A formulary drug is one prescribable product, identified by RxNorm. A formulary item is the row of the list: this drug, on this formulary, in this tier, with these requirements.
 
 ## Data conventions
 
@@ -27,7 +27,7 @@ The four fit together this way. A payer plan states its drug benefit as a cost-s
 | Delivery | Full snapshot each extract, not deltas. A drug removed during the plan year stays in the snapshot as `retired` with an `availability_end` until the plan year ends, so a member can still see it was covered; a plan or formulary that ended is likewise `retired`. Rows absent from a snapshot are removed. |
 | Keys | `plan_id`, `formulary_id` and `drug_id` are your identifiers and stay stable across snapshots. A plan that also appears in the [Provider Directory](../provider-directory/README.md#plans) uses the same `plan_id` there, and `*_org_npi` and `network_ids` are keys into that feed's `organizations` and `networks`. |
 | Codes | Send the code, not the description. Drugs are RxNorm; Payerbox derives every display from its terminology service. |
-| Multiple values | `;`-separated, positionally aligned across companion columns. |
+| Multiple values | `;`-separated, positionally aligned across companion columns. A repeating structure with fields of its own is a dataset instead, one row per occurrence, keyed to its parent. Free-text lists such as aliases must not contain `;` inside a value; a value that needs one goes in a single-value column or its own row. |
 | Amounts | Copays are decimal US dollars; coinsurance is a percentage, `0` to `100`, no `%` sign. |
 | Dates | `YYYY-MM-DD`. |
 | Not PHI | A formulary is public information and is also served unauthenticated. It carries no member data. |