Fact Of Death Direct Enquiry Response Implementation Guide
0.1.0 - ci-build
Fact Of Death Direct Enquiry Response Implementation Guide
0.1.0 - ci-build
Fact Of Death Direct Enquiry Response Implementation Guide - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
The Fact Of Death Direct Enquiry Response (FODDER) Implementation Guide defines the FHIR interface for querying deceased patient records from the Veritas Data Research Fact of Death API. This specification document provides comprehensive technical details about the profiles, extensions, and operations that comprise FODDER.
The DeceasedPatient profile constrains the US Core Patient Profile to represent confirmed deceased individuals with known dates of death, as returned from the Veritas Fact of Death API.
Canonical URL: https://onyxhealth.io/fhir/fodder/StructureDefinition/fodder-deceased-patient
dateTime, never a boolean2024-01-10T14:30:00Zdeceased[x] choice type is constrained to dateTime onlyProfile: DeceasedPatient
Parent: USCorePatientProfile
Id: fodder-deceased-patient
Title: "FODDER Deceased Patient Profile"
* deceased[x] only dateTime
* deceased[x] 1..1 MS
* identifier 1..*
FODDER uses the standard FHIR match-grade extension to convey match quality, replacing the need for a custom extension. This extension is defined in the base FHIR specification and is designed specifically for Patient/$match responses.
Extension URL: http://hl7.org/fhir/StructureDefinition/match-grade
The match-grade extension is placed on Bundle.entry.search in the $match response, not on the Patient resource itself. This is the standard location defined by the FHIR specification for match quality metadata.
The extension uses a required binding to the match-grade ValueSet:
| Code | Display | Definition |
|---|---|---|
certain |
Certain Match | The record is known to be a match |
probable |
Probable Match | The record is a probable match |
possible |
Possible Match | The record may be a possible match |
certainly-not |
Certainly Not a Match | The record is known not to be a match |
{
"entry": [
{
"resource": { ... },
"search": {
"mode": "match",
"score": 0.95,
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/match-grade",
"valueCode": "certain"
}
]
}
}
]
}
The FODDER service maps Veritas API match confidence scores to standard match-grade codes:
| Veritas Score Range | match-grade Code | Rationale |
|---|---|---|
| 0.90 - 1.00 | certain |
All identifiers match exactly |
| 0.70 - 0.89 | probable |
High confidence with minor discrepancies |
| 0.50 - 0.69 | possible |
Moderate confidence, some identifiers match |
| 0.00 - 0.49 | certainly-not |
Low confidence, likely not the same person |
The DeathRecordDocumentReference profile defines a DocumentReference resource for optionally including a death record PDF document alongside a matched DeceasedPatient in a $match response Bundle.
Canonical URL: https://onyxhealth.io/fhir/fodder/StructureDefinition/fodder-death-record-document-reference
| Element | Cardinality | Description |
|---|---|---|
status |
1..1 (fixed: current) |
Document is current |
type |
1..1 (fixed: LOINC 64297-5) | Death certificate |
subject |
1..1 | Reference to the matched DeceasedPatient |
content.attachment.contentType |
1..1 (fixed: application/pdf) |
MIME type |
content.attachment.data |
0..1 | Base64-encoded PDF (inline delivery) |
content.attachment.url |
0..1 | URL to retrieve PDF (by-reference delivery) |
content.attachment.title |
0..1 | Human-readable title |
content.attachment.creation |
0..1 | Date the document was created |
Servers MAY deliver the death record document in two ways:
Inline (base64): Include the PDF directly in content.attachment.data. Suitable for small documents or when immediate access is needed.
By reference (URL): Provide a URL in content.attachment.url pointing to a Binary endpoint. The client fetches the PDF separately. Recommended for large-scale $match responses to keep the Bundle size manageable.
The DocumentReference is included as an additional Bundle entry with search.mode = "include" to signal that it is supplementary to the matched Patient entry:
{
"entry": [
{
"resource": { "resourceType": "Patient", ... },
"search": { "mode": "match", "score": 0.95 }
},
{
"resource": { "resourceType": "DocumentReference", ... },
"search": { "mode": "include" }
}
]
}
Clients that do not need the PDF can simply ignore entries with search.mode = "include".
Profile: DeathRecordDocumentReference
Parent: DocumentReference
Id: fodder-death-record-document-reference
* status = #current
* type 1..1 MS
* type = $loinc#64297-5 "Death certificate"
* subject 1..1 MS
* subject only Reference(DeceasedPatient)
* content 1..* MS
* content.attachment.contentType 1..1 MS
* content.attachment.contentType = #application/pdf
* content.attachment.data 0..1 MS
* content.attachment.url 0..1 MS
FODDER implements the standard FHIR Patient/$match operation for querying deceased patient records. The operation accepts standard FHIR Patient search parameters and returns a Bundle of matching DeceasedPatient resources.
Operation URL: POST /Patient/$match
Request Parameters (as per FHIR spec):
Example Request:
POST /Patient/$match HTTP/1.1
Content-Type: application/fhir+json
Authorization: Bearer <access-token>
{
"resourceType": "Parameters",
"parameter": [
{
"name": "resource",
"resource": {
"resourceType": "Patient",
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-ssn",
"value": "123-45-6789"
}
],
"name": [
{
"family": "Doe",
"given": ["John"]
}
],
"birthDate": "1950-03-15"
}
}
]
}
Response Type: Bundle of type searchset
The operation returns a FHIR Bundle containing:
search.mode = "match"search elementsearch.score for each entry (0.0 to 1.0)search.mode = "include" containing death record PDFsExample Response:
{
"resourceType": "Bundle",
"type": "searchset",
"timestamp": "2024-01-10T14:35:00Z",
"total": 1,
"entry": [
{
"fullUrl": "http://api.example.org/fhir/Patient/deceased-patient-example",
"resource": {
"resourceType": "Patient",
"id": "deceased-patient-example",
"meta": {
"profile": [
"https://onyxhealth.io/fhir/fodder/StructureDefinition/fodder-deceased-patient"
]
},
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-ssn",
"value": "123-45-6789"
}
],
"name": [
{
"family": "Doe",
"given": ["John"]
}
],
"birthDate": "1950-03-15",
"gender": "male",
"deceasedDateTime": "2024-01-10T14:30:00Z"
},
"search": {
"mode": "match",
"score": 0.95,
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/match-grade",
"valueCode": "certain"
}
]
}
},
{
"fullUrl": "http://api.example.org/fhir/DocumentReference/death-record-example",
"resource": {
"resourceType": "DocumentReference",
"status": "current",
"type": {
"coding": [
{
"system": "http://loinc.org",
"code": "64297-5",
"display": "Death certificate"
}
]
},
"subject": {
"reference": "Patient/deceased-patient-example"
},
"content": [
{
"attachment": {
"contentType": "application/pdf",
"url": "http://api.example.org/fhir/Binary/death-record-example",
"title": "Fact of Death Record - John Doe"
}
}
]
},
"search": {
"mode": "include"
}
}
]
}
The search.score value is paired with the standard match-grade extension code to provide both a numeric score and a categorical classification.
FODDER defines the FHIR interface contract that clients see. The actual death record lookup is performed by proxying requests to the Veritas Data Research proprietary API. Key points:
When a system claims conformance to the DeceasedPatient profile:
deceasedDateTime - All implementations SHALL return this elementidentifier - All implementations SHALL return at least one identifiertype - All implementations SHALL set to LOINC 64297-5 "Death certificate"subject - All implementations SHALL reference the matched DeceasedPatientcontent.attachment.contentType - All implementations SHALL set to "application/pdf"content.attachment.data or content.attachment.url - Implementations SHALL provide at least oneAll DeceasedPatient and DocumentReference examples provided in this IG validate successfully against their respective profiles. Organizations implementing this IG should: