Coverage Vocabulary v1.4 - Cascade Protocol

Overview

Namespace URI:: https://ns.cascadeprotocol.org/coverage/v1#
Preferred Prefix:: coverage:
Version:: 1.4
Status:: Stable
Schema File:: coverage.ttl (Turtle/RDF)
Layer:: 2 (Domain Vocabulary)

The Coverage Vocabulary is a Layer 2 domain vocabulary for patient-owned insurance and benefits data. It resolves the overlap between checkup:InsuranceInfo (Layer 3, patient-reported) and clinical:CoverageRecord (Layer 2, EHR-imported) by providing a shared set of standardized insurance properties. Insurance data is cross-cutting: it is administrative and financial rather than clinical, it is not app-specific (any health app benefits from knowing a patient's coverage), and it is contributed by both patient self-report and EHR import. Any health app can use coverage: properties via the mixed namespace pattern.

From v1.2 onward, the vocabulary also models the denial and appeal workflow — enabling patients to document insurer denials, link supporting clinical evidence, and track appeals through all administrative levels.

Download TTL Back to Documentation

Classes

coverage:InsurancePlan

owl:Class — v1.0

An insurance plan the patient is enrolled in. Unifies patient-reported data (from checkup:InsuranceInfo) and EHR-imported data (from clinical:CoverageRecord) into a single standardized representation.

Subclass of: prov:Entity

See also: fhir:Coverage

Pod storage: /coverage/plans/{plan-id}.ttl

coverage:Deductible

owl:Class — v1.0 (properties added v1.1)

Annual deductible status and progress tracking for an insurance plan. Enables patients to monitor their progress toward meeting annual deductible limits.

Subclass of: prov:Entity

See also: fhir:ExplanationOfBenefit

coverage:CopaySchedule

owl:Class — v1.0 (properties added v1.1)

Copay amounts by service category for an insurance plan. Helps patients understand their cost-sharing responsibilities for different types of care.

Subclass of: prov:Entity

coverage:ClaimRecord

owl:Class — v1.1

A medical claim submitted to an insurer for reimbursement.

See also: fhir:Claim

coverage:BenefitStatement

owl:Class — v1.1

An Explanation of Benefits (EOB) document — the insurer's formal response to a claim, including adjudication details, denial reasons, and patient cost responsibility. CMS mandates patient access via the CARIN Alliance FHIR IG.

See also: fhir:ExplanationOfBenefit

coverage:DenialNotice

owl:Class — v1.2

A formal denial of coverage issued by an insurer. Distinct from BenefitStatement — a DenialNotice initiates an appeal process rather than recording a payment outcome. Modeled as a prov:Entity because it is a static document with a fixed issue date.

Subclass of: prov:Entity

See also: fhir:ExplanationOfBenefit

Pod storage: /coverage/denials/{id}.ttl

coverage:AppealRecord

owl:Class — v1.2

A formal appeal filing contesting a denial notice. One record per appeal level. Modeled as a prov:Activity because it represents an active process with a start date, parties involved, and an outcome.

Subclass of: prov:Activity

See also: fhir:Task

Pod storage: /coverage/appeals/{id}.ttl

coverage:DenialReasonCode

owl:Class — v1.3

Enumeration class for structured denial reason codes. Use named individuals (e.g., coverage:NotMedicallyNecessary) as values for coverage:denialReasonCode. Aligns with HL7 ClaimResponse adjudication codes and CARIN IG for Blue Button (STU2).

See also: HL7 adjudication codes, CARIN IG STU2

InsurancePlan Properties

These properties unify data from both patient-reported intake forms and EHR-imported coverage records.

Core (v1.0)

coverage:providerName

owl:DatatypeProperty

Name of insurance company or plan provider (e.g., Aetna, Blue Cross, Medicare). Unifies checkup:insuranceProvider and clinical:providerName.

Domain: coverage:InsurancePlan • Range: xsd:string

coverage:memberId

owl:DatatypeProperty

Insurance policy member/subscriber ID number.

Domain: coverage:InsurancePlan • Range: xsd:string

coverage:groupNumber

owl:DatatypeProperty

Employer group number for employer-sponsored plans.

Domain: coverage:InsurancePlan • Range: xsd:string

coverage:planName

owl:DatatypeProperty

Name of the insurance plan (e.g., "Gold PPO 500").

Domain: coverage:InsurancePlan • Range: xsd:string

coverage:planType

owl:DatatypeProperty

Type of insurance plan. Values: hmo, ppo, epo, pos, hdhp, medicare, medicaid, tricare, other.

Domain: coverage:InsurancePlan • Range: xsd:string

coverage:coverageType

owl:DatatypeProperty

Classification of coverage. Values: primary, secondary, dental, vision.

Domain: coverage:InsurancePlan • Range: xsd:string

coverage:effectiveStart

owl:DatatypeProperty

Start date of coverage period.

Domain: coverage:InsurancePlan • Range: xsd:date

coverage:effectiveEnd

owl:DatatypeProperty

End date of coverage period.

Domain: coverage:InsurancePlan • Range: xsd:date

Subscriber (v1.0)

coverage:subscriberId

owl:DatatypeProperty

Identifier for the policy holder from the insurer.

Domain: coverage:InsurancePlan • Range: xsd:string

coverage:subscriberName

owl:DatatypeProperty

Name of insurance subscriber (the primary policyholder).

Domain: coverage:InsurancePlan • Range: xsd:string

coverage:subscriberRelationship

owl:DatatypeProperty

Relationship of patient to subscriber. Values: self, spouse, child, parent, other.

Domain: coverage:InsurancePlan • Range: xsd:string

Pharmacy Benefits (v1.0)

coverage:rxBin

owl:DatatypeProperty

Pharmacy benefit BIN (Bank Identification Number). Used for prescription drug claims processing.

Domain: coverage:InsurancePlan • Range: xsd:string

coverage:rxPcn

owl:DatatypeProperty

Pharmacy benefit PCN (Processor Control Number). Used for prescription drug claims routing.

Domain: coverage:InsurancePlan • Range: xsd:string

coverage:rxGroup

owl:DatatypeProperty

Pharmacy benefit group number.

Domain: coverage:InsurancePlan • Range: xsd:string

Deductible Properties (v1.1)

coverage:deductibleAmount

owl:DatatypeProperty

Annual deductible limit amount.

Domain: coverage:Deductible • Range: xsd:decimal

coverage:deductibleCurrency

owl:DatatypeProperty

Currency code for the deductible amount (e.g., USD).

Domain: coverage:Deductible • Range: xsd:string

coverage:deductibleMetAmount

owl:DatatypeProperty

Amount of the deductible that has been met so far in the coverage period.

Domain: coverage:Deductible • Range: xsd:decimal

coverage:deductiblePeriod

owl:DatatypeProperty

The benefit year or period this deductible applies to (e.g., 2026).

Domain: coverage:Deductible • Range: xsd:string

coverage:deductibleType

owl:DatatypeProperty

Deductible category. Values: individual, family, in-network, out-of-network.

Domain: coverage:Deductible • Range: xsd:string

CopaySchedule Properties (v1.1)

coverage:copayAmount

owl:DatatypeProperty

Copay amount for this service category.

Domain: coverage:CopaySchedule • Range: xsd:decimal

coverage:copayCurrency

owl:DatatypeProperty

Currency code for the copay amount.

Domain: coverage:CopaySchedule • Range: xsd:string

coverage:copayType

owl:DatatypeProperty

Service category this copay applies to. Values: primary-care, specialist, emergency, prescription.

Domain: coverage:CopaySchedule • Range: xsd:string

ClaimRecord Properties (v1.1)

coverage:claimDate

owl:DatatypeProperty

Date and time the claim was submitted.

Domain: coverage:ClaimRecord • Range: xsd:dateTime

coverage:claimTotal

owl:DatatypeProperty

Total billed amount for the claim.

Domain: coverage:ClaimRecord • Range: xsd:decimal

coverage:claimStatus

owl:DatatypeProperty

Current status of the claim. Values: active, cancelled, draft, entered-in-error.

Domain: coverage:ClaimRecord • Range: xsd:string

coverage:claimType

owl:DatatypeProperty

Type of claim. Values: professional, institutional, oral, pharmacy, vision.

Domain: coverage:ClaimRecord • Range: xsd:string

coverage:billingProvider

owl:DatatypeProperty

Name or identifier of the provider that submitted the claim.

Domain: coverage:ClaimRecord • Range: xsd:string

coverage:hasDiagnosis

owl:DatatypeProperty

ICD-10 code URI for the diagnosis supporting this claim.

Domain: coverage:ClaimRecord • Range: xsd:string

coverage:hasProcedure

owl:DatatypeProperty

CPT or SNOMED code URI for the procedure billed in this claim.

Domain: coverage:ClaimRecord • Range: xsd:string

coverage:sourceRecordId

owl:DatatypeProperty

Original source system record identifier. No domain restriction — shared by ClaimRecord and BenefitStatement.

Range: xsd:string

BenefitStatement Properties (v1.1)

coverage:adjudicationDate

owl:DatatypeProperty

Date and time the claim was adjudicated by the insurer.

Domain: coverage:BenefitStatement • Range: xsd:dateTime

coverage:adjudicationStatus

owl:DatatypeProperty

Processing status of the adjudication. Values: completed, cancelled, entered-in-error.

Domain: coverage:BenefitStatement • Range: xsd:string

coverage:outcomeCode

owl:DatatypeProperty

Processing outcome of the adjudication. Values: queued, complete, error, partial.

Domain: coverage:BenefitStatement • Range: xsd:string

coverage:denialReason

owl:DatatypeProperty

Free-text denial reason from the EOB. For structured denial workflow, use coverage:DenialNotice with coverage:denialReasonCode.

Domain: coverage:BenefitStatement • Range: xsd:string

coverage:totalBilled

owl:DatatypeProperty

Total amount billed by the provider.

Domain: coverage:BenefitStatement • Range: xsd:decimal

coverage:totalAllowed

owl:DatatypeProperty

Total allowed amount per the insurer's fee schedule.

Domain: coverage:BenefitStatement • Range: xsd:decimal

coverage:totalPaid

owl:DatatypeProperty

Amount paid by the insurer.

Domain: coverage:BenefitStatement • Range: xsd:decimal

coverage:patientResponsibility

owl:DatatypeProperty

Amount the patient owes (copay + coinsurance + deductible portion).

Domain: coverage:BenefitStatement • Range: xsd:decimal

coverage:relatedClaim

owl:ObjectProperty

Links an ExplanationOfBenefit to its corresponding ClaimRecord.

Domain: coverage:BenefitStatement • Range: coverage:ClaimRecord

DenialNotice Properties (v1.2–1.3)

coverage:deniedProcedureCode

owl:DatatypeProperty — v1.2

CPT or HCPCS code of the denied service (e.g., E0787 for CGM).

Domain: coverage:DenialNotice • Range: xsd:string

coverage:denialReasonCode

owl:DatatypeProperty — v1.2

Structured coded denial reason. Recommended values are coverage:DenialReasonCode named individuals (see below). Distinct from the free-text coverage:denialReason. Aligns with HL7 ClaimResponse adjudication and CARIN IG Blue Button STU2.

Domain: coverage:DenialNotice • Range: xsd:string

See also: HL7 adjudication, CARIN IG STU2

coverage:denialLetterDate

owl:DatatypeProperty — v1.2

Date the denial notice was issued. The appeal deadline clock starts from this date.

Domain: coverage:DenialNotice • Range: xsd:date

coverage:appealDeadline

owl:DatatypeProperty — v1.2

Computed deadline for filing an appeal, based on the denial date, plan type, and applicable jurisdiction rules.

Domain: coverage:DenialNotice • Range: xsd:date

coverage:coveragePolicyReference

owl:DatatypeProperty — v1.2

The LCD, NCD, or coverage policy cited as the basis for denial (e.g., LCD L33822).

Domain: coverage:DenialNotice • Range: xsd:string

coverage:deniedClinicalContext

owl:ObjectProperty — v1.3

References clinical or health records in the Pod that are relevant to this denial — procedures, lab results, diagnoses, device readings. Enables appeals to cite specific clinical evidence against policy criteria. Range is intentionally open (rdfs:Resource) to allow linking across clinical:, health:, and pots: namespaces.

Domain: coverage:DenialNotice • Range: rdfs:Resource

AppealRecord Properties (v1.2–1.3)

coverage:appealLevel

owl:DatatypeProperty — v1.2

The administrative level of this appeal. Values: redetermination, qio_reconsideration, alj_hearing, mac_review, federal_court, internal_level1, internal_level2, external_review, state_insurance_dept, litigation.

Domain: coverage:AppealRecord • Range: xsd:string

coverage:appealFiledDate

owl:DatatypeProperty — v1.2

Date the appeal was formally filed.

Domain: coverage:AppealRecord • Range: xsd:date

coverage:appealOutcome

owl:DatatypeProperty — v1.2

Outcome of the appeal. Values: approved, denied, partial, withdrawn, pending.

Domain: coverage:AppealRecord • Range: xsd:string

coverage:appealOutcomeDate

owl:DatatypeProperty — v1.2

Date the appeal outcome was received.

Domain: coverage:AppealRecord • Range: xsd:date

coverage:relatedDenialNotice

owl:ObjectProperty — v1.2

Links an AppealRecord to the DenialNotice it contests.

Domain: coverage:AppealRecord • Range: coverage:DenialNotice

coverage:outcomeReason

owl:DatatypeProperty — v1.3

Free-text explanation of why the appeal was approved, denied, or partially approved. Captures the insurer's stated rationale for the outcome.

Domain: coverage:AppealRecord • Range: xsd:string

coverage:reversalAmount

owl:DatatypeProperty — v1.3

Reimbursement amount granted if the appeal was approved or partially approved. Expressed as a decimal in the currency of the related InsurancePlan.

Domain: coverage:AppealRecord • Range: xsd:decimal

DenialReasonCode Named Individuals (v1.3)

Standard-mapped enumeration values for coverage:denialReasonCode. Use these named individuals to enable structured, machine-readable denial tracking. Aligns with HL7 ClaimResponse adjudication codes and the CARIN IG for Blue Button STU2.

Named Individual	Label	Standard Alignment
`coverage:NotMedicallyNecessary`	Not Medically Necessary	HL7 adjudication `noauth`; CMS reason 50
`coverage:LCDCriteriaNotMet`	LCD Criteria Not Met	CMS Local Coverage Determination
`coverage:NCDCriteriaNotMet`	NCD Criteria Not Met	CMS National Coverage Determination
`coverage:ServiceNotCovered`	Service Not Covered	HL7 adjudication `benefit`
`coverage:PriorAuthorizationRequired`	Prior Authorization Required	HL7 adjudication `noauth`; X12 835 reason code 4
`coverage:DuplicateClaim`	Duplicate Claim	X12 835 reason code 18
`coverage:InformationRequested`	Additional Information Requested	X12 835 reason code 16

FHIR Alignment

The Coverage Vocabulary aligns with multiple FHIR R4 resources.

Coverage Class/Property	FHIR Alignment
`coverage:InsurancePlan`	`fhir:Coverage`
`coverage:providerName`	`Coverage.payor` (display)
`coverage:memberId`	`Coverage.identifier`
`coverage:groupNumber`	`Coverage.class` (group)
`coverage:planName`	`Coverage.class` (plan)
`coverage:planType`	`Coverage.type`
`coverage:effectiveStart`	`Coverage.period.start`
`coverage:effectiveEnd`	`Coverage.period.end`
`coverage:subscriberId`	`Coverage.subscriberId`
`coverage:subscriberRelationship`	`Coverage.relationship`
`coverage:ClaimRecord`	`fhir:Claim`
`coverage:BenefitStatement`	`fhir:ExplanationOfBenefit`
`coverage:DenialNotice`	`fhir:ExplanationOfBenefit` (denied outcome)
`coverage:AppealRecord`	`fhir:Task`

Usage Examples

Insurance Plan (v1.0)

@prefix coverage: <https://ns.cascadeprotocol.org/coverage/v1#> .
@prefix cascade: <https://ns.cascadeprotocol.org/core/v1#> .
@prefix prov: <http://www.w3.org/ns/prov#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<#insurance-primary> a coverage:InsurancePlan ;
    cascade:schemaVersion "1.3" ;
    cascade:dataProvenance cascade:SelfReported ;
    coverage:providerName "Blue Cross Blue Shield" ;
    coverage:memberId "XYZ123456789" ;
    coverage:groupNumber "GRP-98765" ;
    coverage:planType "ppo" ;
    coverage:coverageType "primary" ;
    coverage:effectiveStart "2026-01-01"^^xsd:date ;
    coverage:effectiveEnd "2026-12-31"^^xsd:date ;
    coverage:subscriberRelationship "self" .

Denial Notice with Clinical Context (v1.3)

@prefix coverage: <https://ns.cascadeprotocol.org/coverage/v1#> .
@prefix health: <https://ns.cascadeprotocol.org/health/v1#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<#denial-001> a coverage:DenialNotice ;
    coverage:deniedProcedureCode "E0787" ;
    coverage:denialReasonCode coverage:NotMedicallyNecessary ;
    coverage:denialLetterDate "2026-03-01"^^xsd:date ;
    coverage:appealDeadline "2026-04-01"^^xsd:date ;
    coverage:coveragePolicyReference "LCD L33822" ;
    coverage:deniedClinicalContext </health/devices/cgm-readings-q1.ttl> ,
                                    </clinical/conditions/diabetes-t1.ttl> .

<#appeal-001> a coverage:AppealRecord ;
    coverage:relatedDenialNotice <#denial-001> ;
    coverage:appealLevel "redetermination" ;
    coverage:appealFiledDate "2026-03-15"^^xsd:date ;
    coverage:appealOutcome "approved" ;
    coverage:appealOutcomeDate "2026-04-10"^^xsd:date ;
    coverage:outcomeReason "Patient meets LCD L33822 criteria — CGM medically necessary for Type 1 diabetes with documented hypoglycemia unawareness." ;
    coverage:reversalAmount 1200.00 .

Recommended Storage

The recommended Solid Pod storage layout for coverage data places insurance plans under a dedicated /coverage/ directory. Each record is stored as its own Turtle file, enabling fine-grained access control and independent updates.

/coverage/
    plans/
        {plan-id}.ttl          # InsurancePlan instances
    deductibles/
        {year}.ttl             # Annual deductible tracking
    denials/
        {denial-id}.ttl        # DenialNotice instances (v1.2+)
    appeals/
        {appeal-id}.ttl        # AppealRecord instances (v1.2+)

SHACL Validation Shapes

Validation shapes for this vocabulary are defined in coverage.shapes.ttl.

Shapes defined:

coverage:InsurancePlanShape — Validates InsurancePlan instances with required provider name, member ID, plan type, and coverage type
coverage:ClaimRecordShape — Validates ClaimRecord instances
coverage:BenefitStatementShape — Validates BenefitStatement (EOB) instances
coverage:DenialNoticeShape — Validates DenialNotice instances
coverage:AppealRecordShape — Validates AppealRecord instances

All shapes use sh:minCount 0 (permissive) — properties are optional unless marked required.

Changelog

Version 1.4 (2026-08-08)

Shapes only. No class or property added, removed or renamed. Both changes are strictly widening: two classes of previously-rejected conformant record now pass.
coverage:subscriberRelationship held five of the seven codes in the SubscriberPolicyholder code system, which is what FHIR R4 binds Coverage.relationship to. common (Common Law Spouse) and injured (Injured Party) were simply missing, so an export carrying either was warned for being correct. The list is now that code system in full.
coverage:coverageType enforced a closed four-member enum (primary, secondary, dental, vision) at sh:Violation severity on an element FHIR R4 binds extensibly, where alternate codes MAY be used if the value set does not cover the concept. A payer sending a conformant v3-ActCode code such as EHCPOL had the record rejected outright. Presence is still a Violation; the value is now checked by the new coverage:CoverageTypeVocabularyShape at sh:Warning, against the FHIR value set plus the four retained Cascade values. Note also that the original four conflated two FHIR elements: primary/secondary describe Coverage.order, not Coverage.type.

Version 1.3 (2026-03-17)

Added coverage:DenialReasonCode class — enumeration class for structured denial reason codes with HL7 and CARIN IG alignment
Added 7 named individuals: coverage:NotMedicallyNecessary, coverage:LCDCriteriaNotMet, coverage:NCDCriteriaNotMet, coverage:ServiceNotCovered, coverage:PriorAuthorizationRequired, coverage:DuplicateClaim, coverage:InformationRequested
Added coverage:deniedClinicalContext (ObjectProperty, domain: DenialNotice) — open-range link to clinical evidence in the Pod supporting an appeal
Added coverage:outcomeReason (DatatypeProperty, domain: AppealRecord) — free-text explanation of the appeal outcome
Added coverage:reversalAmount (DatatypeProperty, domain: AppealRecord) — reimbursement amount for approved appeals

Version 1.2 (2026-03-16)

Added coverage:DenialNotice class (prov:Entity subclass, fhir:ExplanationOfBenefit alignment) with 5 properties: deniedProcedureCode, denialReasonCode, denialLetterDate, appealDeadline, coveragePolicyReference
Added coverage:AppealRecord class (prov:Activity subclass, fhir:Task alignment) with 5 properties: appealLevel, appealFiledDate, appealOutcome, appealOutcomeDate, relatedDenialNotice
Recommended Pod storage paths added: /coverage/denials/, /coverage/appeals/

Version 1.1 (2026-03-12)

Added coverage:ClaimRecord class (fhir:Claim alignment) with 7 properties: claimDate, claimTotal, claimStatus, claimType, billingProvider, hasDiagnosis, hasProcedure
Added coverage:BenefitStatement class (fhir:ExplanationOfBenefit alignment) with 9 properties: adjudicationDate, adjudicationStatus, outcomeCode, denialReason, totalBilled, totalAllowed, totalPaid, patientResponsibility, relatedClaim
Added coverage:sourceRecordId (no-domain property, shared by ClaimRecord and BenefitStatement)
Added fill properties to coverage:Deductible: deductibleAmount, deductibleCurrency, deductibleMetAmount, deductiblePeriod, deductibleType
Added fill properties to coverage:CopaySchedule: copayAmount, copayCurrency, copayType
Added SHACL shapes for all new classes in coverage.shapes.ttl (permissive, sh:minCount 0)

Version 1.0 (2026-02-18)

Initial release with InsurancePlan class and 14 properties:
- 8 core properties: providerName, memberId, groupNumber, planName, planType, coverageType, effectiveStart, effectiveEnd
- 3 subscriber properties: subscriberId, subscriberName, subscriberRelationship
- 3 pharmacy benefit properties: rxBin, rxPcn, rxGroup
Added Deductible and CopaySchedule classes (properties deferred to v1.1)
FHIR Coverage resource alignment documented
Part of Schema Refactoring Plan Phase 2 (WS4)