Travis to familiarize self with USCDI vs US Core & Take Notes

[travis-sauer-oltech]

Effort estimate (hours)

2

Description

Per the title; be able to:

1. explain in simple terms what USCDI vs US Core are
2. Manually look through postgtresql for how medplum stores FHIR
3. Construct a simple SQL Query with JSONB functions, that looks up the last name from a patient in Medplum
4. Explain the differences between a FHIR Facade server and a Native server and which JHE and Medplum fall under
5. Start to consider next steps/options for how we'd implement with some dot points below

[travis-sauer-oltech]

1. explain in simple terms what USCDI vs US Core are

• USCDI (US Core Data for Interoperability) is a list of data elements that the Office of the National Coordinator for Health Information Technology (ONC) states all certified EHRs must be able to exchange specific data in a format-agnostic approach. In example, it says that you "must support patient name, allergies, labs, vitals
• US Core is a FHIR Implementation Guide (IG) published by Health Level Seven (HL7) that specifies exactly how to represent each USCDI element as a FHIR resource (which profile, which fields are required, which code systems, which value sets, etc.)
• Example: USCDI says "Patient Name is required." US Core says "Use Patient.name.family + Patient.name.given, cardinality 1..*, must support, conforms to us-core-patient profile."

[travis-sauer-oltech]

2. Manually look through postgtresql for how medplum stores FHIR

• Medplum is a native FHIR server, so each FHIR resource type gets its own table. Content is stored as text and not JSONB, so it's stored as serialized JSON of the full FHIR resource; Medplum stores it as text, casts to jsonb on demand (at the query level). See the below information_schema.columns query for proof.

• For every FHIR Resource type it creates three tables:

  • "Resource" which is the current state and one row per resource
  • "Resource_History" which is append-only where every prior version is listed, powers things like _history and vread
  • "Resource_Reference" which answers the reverse question of a foreign-key style look up. i.e. "Which Patients point at this resource?," for resourceType: "Patient"

• Extracted search-parameter columns sit alongside content. In example, birthdate date (column, type). Multi-valued params are stored as arrays, such as, __email text[], these are b-tree indexed for scalars and Generally Inverted Index for arrays, so FHIR searches like Patient?gender=male never sequentially scan the JSON.

[travis-sauer-oltech]

3. Construct a simple SQL Query with JSONB functions, that looks up the last name from a patient in Medplum

•            SELECT id, content::jsonb -> 'name' -> 0 ->> 'family' AS last_name
             FROM "Patient" WHERE deleted = false;

• Please also see the screenshot below for the proof

[travis-sauer-oltech]

4. Explain the differences between a FHIR Facade server and a Native server and which JHE and Medplum fall under

• Native FHIR Servers like Medplum store each FHIR resource's canonical JSON as the source of truth, then denormalize selected search parameters into dedicated columns so Postgres can index and query them efficiently. The JSON body is the source of truth, the extracted columns are accelerators.
• Facade FHIR Servers like JHE, keep data in a non-FHIR domain model (relational tables shaped around business entities) and assemble/parse FHIR JSON on the fly at each API call. ergo, FHIR is a wire format not a storage format.

Therefore:

• JHE is a facade server, because core_patient has flat columns identifier, name_family, and no JSON blob. FHIR patient resources are rendered by Django serializers on read. core.models.py showcases this
• Medplum is native, where every resource type has its own table with a content text (col. name, type), column holding the f ull FHIR JSON plus ~40 denormalized/search-helper columns, i.e. compartments uuid[] for access control.

[travis-sauer-oltech]

5. Start to consider next steps/options for how we'd implement with some dot points below

• Decide JHE posture: stay pure facade vs. add a JSONB landing table for raw FHIR passthrough
• US Core gap on JHE Patient: need to add gender, address, communication, race/ethnicity/birth-sex extensions
• Integration pattern (pick one only):
  • Option A: JHE pushes to Medplum (JHE -> Medplum via FHIR REST)
    • JHE ingestion pipeline looks like Wearable -> OW -> omh-shim -> JHE serializer -> POST /fhir/R4/Observation -> Medplum
  • Option B: Medplum pushes to JHE (Medplum -> JHE via Bot/Subscription)
    • Medplum is the ingest point; it fires an event to JHE when resources are written. i.e. External source -> POST /fhir/R4/Observation -> Medplum -> Subscription/Bot webhook -> JHE REST endpoint
  • Option C: Two-way sync over a shared identifier system
    • Both stores hold the same Patient independently and reconcile by a business identifier (MRN, JHE user id): JHE Patient.identifier == Medplum Patient.identifier[{system:".../jhe-user-id", value:"123"}]
      • Each side writes locally; a sync process (scheduled job or bi-directional Subscription) keeps them in step.
• omh-shim VS "OMH -> FHIR mapping layer" (why I think both are needed):
  • These are two different mappings in a three-step pipeline:
    • Vendor raw (Oura/OW JSON)[Vendor Schema] -> omh-shim (existing) (OMH Schema) -> OMH_FHIR mapper (missing) (FHIR schema) -> FHIR Observation (Medplum or JHE)
• Wire a HL7 FHIR Validator + US Core IG into CI on the JHE side
• Pin US Core version (6.1.0 or 7.0.0) in JHE docs.

[travis-sauer-oltech]

Probably important to note that this ticket: #35, opened by @minrk may have some relations to this issue.