v1.1.0 — Production-Driven Refinement

Backward-compatible minor release driven by six months of production extraction across real carrier SBCs and EOCs. Every v1.0.0 document continues to validate against v1.1.0 unchanged.

What's new

Plan identity

• plan_year (integer) — supports cross-year plan-family grouping when effective_date is missing.
• coverage_period object (start_date, end_date) — captures the coverage window explicitly.
• market (string) — market segment (individual, small_group, large_group, medicare_advantage, …).

Accumulators (8 slots total)

• 4 new out-of-network slots: oon_individual_deductible, oon_family_deductible, oon_individual_oop_max, oon_family_oop_max. Closes the v1.0.0 gap where PPO plans with separate in/out-of-network accumulators could not be fully represented.
• New per-slot fields: period, network_tier, embedded, and applies_to on OOP max (parity with deductibles).
• Refactored into $defs/deductible_accumulator and $defs/oop_max_accumulator so all 8 slots stay in sync.

Benefits

• benefit_type discriminator (default "medical") — enables future modules (pharmacy, dental, vision, behavioral_health) without restructuring.
• canonical_key — machine-readable canonical identifier.
• raw_label — verbatim source-document label for traceability.

Cost shares

• notes field on cost_shares[] items (was missing in v1.0.0; the SCAN example wanted to use it).

Recommended vocabularies (new vocabularies/ directory)

• canonical-benefits.json — 100 canonical benefit identifiers across 13 categories.
• categories.json — 25 recommended uppercase snake_case category codes.
• markets.json — 12 recommended market codes.
• plan-types.json — 12 recommended plan-design codes.

These are non-normative: the schema treats the corresponding fields as free-form strings so adopters can extend; the vocabularies provide consistent values for interoperability.

Expanded examples

All 7 carrier example plans now cover 25–30 benefits each (198 total), spanning the full SBC service inventory: office visits, diagnostics, pharmacy (4 tiers), outpatient surgery, ER/urgent care/ambulance, inpatient hospital, mental/behavioral health, maternity, recovery (home health, rehab, SNF, DME, hospice), and pediatric vision/dental.

FHIR alignment

New docs/fhir-alignment.md. Field-by-field BPS ↔ FHIR R4 InsurancePlan mapping, worked example, lossy-mapping table with extension/qualifier advice, round-tripping guidance. R5/R6 outlook included; the guide will refresh once HL7 R6 stabilizes.

Repository hygiene

• LICENSE (MIT) added.
• .gitattributes to normalize line endings.
• examples/scan_example.json — removed notes from inside cost_shares[] (would have failed additionalProperties: false). The notes field is now formally defined on cost_shares[] in v1.1.0.

Backward compatibility

• All v1.0.0 required fields remain required.
• All v1.0.0 optional fields remain present with the same types.
• All additions are optional and additionalProperties: false boundaries are respected.
• A document declaring "schema_version": "1.0.0" validates against the v1.1.0 schema without changes.
• All 7 original example plans validate clean against v1.1.0 (verified).

Canonical URLs

• v1.1.0 schema: https://benefitplanstandard.org/schema/v1.1.0/benefit-plan.schema.json
• v1.0.0 schema (preserved): https://benefitplanstandard.org/schema/v1.0.0/benefit-plan.schema.json

Documentation

The companion docs PR is in Benefit-Plan-Standard/benefit-plan-docs#1, which fixes the three doc-vs-schema mismatches (product_type → plan_type, individual_oop → individual_oop_max, source_refs → source_references) and brings the docs site up to v1.1.0.

What's next

• Formal pharmacy module schema using benefit_type: "pharmacy".
• Behavioral health, dental, vision, maternity modules.
• HealthPlanAPI reference-implementation alignment to v1.1.0.
• Refreshed FHIR alignment once HL7 R6 normative behavior stabilizes.

v1.0.0 — Foundational Release

Note: This is a retroactive tag and release. The v1.0.0 schema was originally published on 2025-11-30 and accreted through December 2025 as the examples and supporting docs landed. This tag marks the final state of main immediately before v1.1.0 work began (commit 14fe5ba, 2025-12-06).

What v1.0.0 includes

• Canonical JSON Schema — schema/v1.0.0/benefit-plan.schema.json (JSON Schema Draft 2020-12).
• Top-level model: plan_id, plan_name, carrier, plan_type, effective_date, expiry_date, network_tiers[], accumulators (4 in-network slots), benefits[], source_references[], schema_version.
• Benefit model: benefit_id, category, service_name, place_of_service[], network_cost_shares[] (with ordered cost_shares[] array — copay/coinsurance/deductible with sequence, amount, rate, basis, applies_to_deductible, applies_to_moop), limits[], conditions[], moop_applicability, coding_hints.
• Example normalized plans for 7 carriers: Aetna, Blue Cross, Cigna, GatorCare, Humana, SCAN, UnitedHealthcare.
• Modules placeholder — extension framework for pharmacy, behavioral health, dental/vision.
• Documentation site at benefitplanstandard.org.

Canonical URL

https://benefitplanstandard.org/schema/v1.0.0/benefit-plan.schema.json

This URL is preserved going forward — v1.1.0 lives at a separate path and v1.0.0 documents continue to validate against v1.1.0 unchanged (backward-compatible).

Known gaps (addressed in v1.1.0)

• Accumulators only modeled in-network; out-of-network deductibles and OOP maxes required adopter extensions.
• No plan_year, coverage_period, or top-level market field.
• No benefit_type discriminator on benefits — module support required schema redesign.
• The examples/scan_example.json example placed notes inside cost_shares[] items, which would fail additionalProperties: false.

See v1.1.0 for the backward-compatible additions that close these gaps.