DEV Community: mock health

Your FHIR Sandbox Looks the Part. Nobody in It Has Aged.

mock health — Mon, 10 Aug 2026 22:58:19 +0000

Epic's sandbox, an integration platform's dev environment, and the JSON fixtures in your repo.

Pick any patient out of Open Epic's sandbox. Camila Lopez, say. Query her today:

curl -H "Authorization: Bearer $TOKEN" \
  "https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4/Patient/erXuFYUfucBZaryVksYEcMg3"

Now query her again next month. Next year. It's the same bytes. Same conditions, same encounters, same meta.lastUpdated. That timestamp has not moved in years, and it is never going to.

This is not a complaint about data quality. I've written that post already — the sandbox patients are thin, their names are "Test Cancer," and you can't demo off them. That's the content problem, and it's well understood.

This is a different problem, and I think it's the more expensive one, because it's invisible. The sandbox doesn't just contain bad data. The sandbox doesn't contain time.

The test you cannot write

Here is the single most important request your integration will ever make:

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE/Patient/$ID/\$everything?_since=2026-08-01T00:00:00Z"

"What changed since I last looked." Every production integration is built on some version of this — a delta poll, a subscription, a nightly bulk-export diff. It is how you avoid re-ingesting a million resources every hour. It is the hot path.

Run it against a static sandbox and you get an empty Bundle. Run it with _since set to the epoch and you get everything, once, and then empty Bundles forever after.

So your delta-sync test passes.

It passes because there is nothing to sync. You have written a test that asserts your code correctly handles zero changes, and you have learned nothing about whether it handles one. The first time your code sees a real delta is in a customer's production environment, against real PHI, on a Tuesday.

Three flavors of nothing happening

Static sandboxes aren't all static the same way, and the differences matter when you're trying to work around them.

1. Epic's sandbox: frozen

Open Epic gives you eight named test patients — Camila Lopez, Derrick Lin, Desiree Powell, Elijah Davis, Linda Ross, Olivia Roberts, Warren McGinnis, Jason Argonaut. They are a fixture set. They exist so you can confirm your OAuth flow completes, your client parses a Bundle, and your pagination doesn't crash.

For that job they are honestly fine. Epic never claimed otherwise. But nothing in that environment ever transitions: no encounter opens, no result posts, no condition resolves, no resource gets a new versionId. It's a photograph of a clinic, and you're trying to test a video player.

2. An integration platform's dev environment: provisioned like production

The second flavor is more interesting, because the platform is perfectly capable of automation and you still can't get at it.

We ship an inbound Redox destination — you register https://api.mock.health/api/redox and Redox delivers to it. I built it, documented it, then went to test it the way a customer would: send data through the API, watch it arrive.

It didn't arrive. Redox answered with a 400 that named the missing piece:

"Errors": [{
  "Module": "Subscriptions",
  "Text": "No subscriptions. Meta.Destinations needs to contain a
           destination from existing subscriptions."
}]

Fair enough — a subscription links a source to a destination, and once one exists, messages route automatically with nobody watching. That's real automation and it's documented. My mistake, and I went to go create one.

I couldn't. In the Development environment:

Every subscription in the account was already provisioned against a single source named Redox Dev Tools — the thing behind the Send button in their UI. There is no API credential for it, because it isn't that kind of source.
On a subscription's detail page, Edit is disabled. The source can't be repointed.
There's no New subscription button on the Connections page. The button that's there is Request new connection, which opens a form stating that "all connections are subject to a readiness and resource availability review before approval."
My own API key authenticates as a different source — "Redox Request Ingress (Development)" — which nothing is subscribed to. Hence the 400.

So the automation exists, and the only source wired to my destination is the one with a human in front of it. Getting a different one wired means filing a request and waiting for a person at Redox to approve it.

That's a defensible design. Redox moves real PHI between real health systems; gating who can route data where is the correct instinct, and I'd be more worried if a stranger could self-serve a pipe into a hospital. But it means their dev environment is provisioned like production — and an environment provisioned like production isn't a sandbox. It's a staging area you have to be onboarded into.

For a connectivity check, that's fine. For "run my integration suite nightly against my pipeline," a human approval queue upstream of your first test is the whole ballgame.

One caveat, honestly. Redox's docs describe a New subscription button I don't have, so what I hit may be a permission or account-tier artifact rather than a universal property of dev environments. I've asked them. If it's self-serve for you and I simply couldn't see it, tell me and I'll correct this post with a link.

3. Your own fixtures: stale by construction

The one nobody wants to talk about, because it's self-inflicted.

You gave up on vendor sandboxes and seeded your own Postgres with a JSON fixture set. It was great. It was your data, shaped how you needed it.

Then the dates hardcoded themselves into your test suite. That "recent" encounter you seeded in January reads as eight months stale in August. Your "active" medication has an end date in the past. Your HbA1c trend stops. Somebody adds dateutil.relativedelta(months=-3) to keep one patient current, and now your fixtures aren't deterministic, and now a test fails on the first of the month for reasons nobody can reproduce.

Static fixtures don't stay still. They rot in place, which is worse, because a frozen sandbox is at least honestly frozen.

The bugs this hides

This is the actual argument. A corpus that never changes cannot produce a failing test for any of these:

_since boundary conditions. Inclusive or exclusive at the timestamp? Server clock vs. your clock? Resources written during your poll window — do you get them twice, or never?
Replay idempotency. The same resource delivered twice. Do you upsert on a stable identifier, or do you now have two Patients?
Out-of-order arrival. The Observation lands before the Encounter it references. Does your ingest dangle the reference, drop the resource, or 500?
Version conflicts. A resource you cached is updated upstream. Does your If-Match on meta.versionId do the right thing, or do you silently clobber?
Webhook retry dedup. The delivery times out on your end, the sender retries, you process it twice. Does anything downstream double-count?
Pagination across a moving result set. You're on page 3 of 40 when new resources land. Do you skip records, repeat them, or loop?
Cache invalidation. How would you even know? Nothing has ever invalidated.

Every one of these is a time bug. Every one of them ships to production untested if your sandbox is a photograph. And they don't fail loudly — they fail as a duplicate patient in a customer's chart, or a lab result that quietly never arrived.

What we built instead

mock.health's sandbox runs a clock.

A timeline walker advances each patient's pre-generated history into the live sandbox on a compressed schedule — roughly one model-week per real day. A scheduler hits an internal endpoint hourly. Each tick:

Computes model time as anchor_model + (now - anchor_real) * speed, then finds every event-group whose anchor has come due.
Re-dates the group so its clinical timestamps land at the real moment it "happens" on the compressed clock. Intra-group offsets are preserved, so an admission still precedes its discharge by the right interval. birthDate is never shifted — patients don't get younger.
Writes it as a transaction bundle, PUT with client-assigned UUIDs.

That third step is the one that makes the whole thing work, and it's almost boring: a real write produces a real meta.lastUpdated. Which means _lastUpdated polling and bulk-export deltas return genuinely fresh results — on /fhir and on every /v/* vendor twin. We didn't build a delta API. We made data actually change, and FHIR's existing delta semantics started working on their own.

Each walked event-group also appends a CDC row to a cursor-based change feed (GET /api/feed), gets pre-rendered into HL7v2 (ADT^A01/A04/A03, ORM^O01, ORU^R01) and C-CDA — the C-CDA written back as a DocumentReference you can find via $docref — and fires HMAC-signed webhooks to registered subscribers.

And when a dataset's timeline is exhausted, it re-arms: cursors reset, the anchor moves to now, and history replays. Because the writes are PUTs with stable UUIDs, a replay is an idempotent update with fresh timestamps rather than a pile of duplicates. The sandbox doesn't run out.

The part where I found the same bug in my own server

I wrote that line about FHIR's delta semantics working on their own, then went to verify it the way I'd want a reader to. Pick a patient, poll $everything with a future _since, confirm you get an empty Bundle.

I got the entire compartment. 122 resources, none of them newer than a date in 2099.

HAPI accepts _since on Patient/$everything and ignores it. Not rejects: ignores.

I want to sit on that for a second, because HAPI is not some abandoned side project. It's the open-source reference implementation — the thing a large share of FHIR stacks are built on, ours included, and the thing people reach for when they want to know how a behavior is supposed to work. It is very good software. And this is in it.

My first assumption was that I'd misconfigured something. I ran the same test against the public hapi.fhir.org server: same answer. It reproduces on 8.8 through 8.11.

The obvious defense is that _since is optional. And it is — sort of. In the R4 OperationDefinition the parameter is 0..1, which means a client doesn't have to send one. It does not mean a server that receives one may pretend it didn't. Three things make that reading hard to sustain here:

HAPI declares the canonical operation, not a reduced one. Ask its CapabilityStatement what $everything is and it answers with HL7's own definition:

everything  ->  http://hl7.org/fhir/OperationDefinition/Patient-everything

Every other operation it implements points at a HAPI-local OperationDefinition describing what HAPI actually does — .../OperationDefinition/Multi-its-meta, .../Global-is-diff. For $everything it points at the spec's definition, the one that contains _since and says the parameter exists so "a client can request only records that have changed since the last request." So the server isn't declining an optional feature. It's naming the full contract and then implementing part of it.

It filters everything else on that same operation. _type works. _lastUpdated works on ordinary type-level searches. The date filter just never got wired into $everything.

And the response says the filter ran. FHIR's mechanism for telling a client which parameters a server actually honored is the Bundle's self link. Here's what comes back for a cursor in 2099:

self: .../Patient/{id}/$everything?_count=2&_since=2099-01-01T00%3A00%3A00Z

The parameter is echoed. No OperationOutcome, no warning, no code: not-supported. The one channel a well-behaved client would check to detect a dropped parameter reports success while handing back the entire compartment. That's what turns a missing feature into a silent one.

I filed it upstream — hapifhir/hapi-fhir#8039. This is no complaint about the maintainers; the HAPI team ships an enormous amount of FHIR for free. It's evidence for the actual point, which is that this survived in the reference implementation, in front of everybody, for years — because of the exact thing this post is about:

On a static sandbox, "correctly returned nothing" and "ignored your filter" are the same response. Camila Lopez has no resources newer than your cursor either way. The bug is only observable against data that moves. Our clock is what surfaced it.

The fix is unglamorous. When a request carries _since, the API stops forwarding the operation and assembles the answer itself from per-type compartment searches with _lastUpdated=gt, which HAPI does get right. Same URL, same Bundle shape, and now the filter is real:

curl -H "Authorization: Bearer $KEY" \
  "https://api.mock.health/fhir/Patient/$ID/\$everything?_since=2099-01-01T00:00:00Z"
# {"resourceType":"Bundle","type":"searchset","total":0,"entry":[]}

Three things fell out of doing it, and they're all the boundary conditions from the list above:

The bound is exclusive, lastUpdated > cursor, because R4 says "updated after." That means a resource written in the same millisecond as your cursor that you didn't receive will never arrive. Poll with a few minutes of overlap and dedupe on id + versionId. Our own $export uses an inclusive bound, which is an inconsistency I'd rather write down than quietly paper over.
A malformed _since returns 400 instead of being ignored. Silently widening to "everything" is how this class of bug hides.
A truncated delta says so in-band, as an OperationOutcome entry in the Bundle. A client that receives a short page and advances its high-water mark loses the remainder permanently — a worse failure than the one I started with, and an easy one to introduce while fixing it.

I'm keeping this section rather than editing the post into a cleaner story, because the cleaner story would be false and the messy one is the argument. I did not find this by reading the spec. I found it because the data moved.

So the test you couldn't write, you can write:

# Snapshot
curl -H "Authorization: Bearer $KEY" \
  "https://api.mock.health/fhir/Patient/$ID/\$everything?_since=$(date -u -d '1 hour ago' +%FT%TZ)"

# Wait. Ask again. Different answer.

What this doesn't give you

Three honest limits, because a living sandbox is not a production environment:

It's still synthetic. It won't replace a real integration test against a real EHR with real credentials. It gets you most of the way there before you have access — which is the whole point — but "most of the way" is the claim.
The clock is compressed, not real-time. One model-week per real day is fast enough that deltas are always available and slow enough that a week of your testing spans months of patient history. It is not a live hospital feed, and if you need sub-second event latency this isn't it.
FHIR Subscriptions aren't on the vendor twins, deliberately. You get them on /fhir. You don't get them on /v/epic or /v/cerner, because real Epic and Cerner production endpoints don't support Subscriptions, and a twin that's more capable than the thing it's imitating teaches you a lie. The twins stay faithful to what your integration will actually face.

The Free tier gets _since polling and the FHIR change feed against the sample dataset — enough to prove the delta path in your client works. Renditions (HL7v2, C-CDA), webhooks, and Subscriptions are Pro.

The point

Sandboxes are graded on the wrong axis. The industry conversation is about whether the data is realistic — enough conditions, plausible names, correct codes. That matters, and it's the easier problem.

The harder one is that a sandbox with perfect data and no clock still can't test the half of your integration that deals with change. And that half is where the production incidents come from, because it's the half you shipped untested.

Ask your sandbox what changed in the last hour. If the answer is always "nothing," you don't have a test environment. You have a fixture.

Testing FHIR Integrations Without a Hospital

mock health — Tue, 14 Apr 2026 21:24:38 +0000

You're building a FHIR integration. You need to test it against data that looks like what a hospital actually produces.

You don't have access to a hospital.

This is the catch-22 that every FHIR startup lives in for 6-12 months. You can't get production EHR access without a working, tested integration. You can't build one without production-quality data. Epic's app marketplace review takes 2-4 months. Oracle Health takes 3-6. And all of them want evidence that your software works before they give you the data to prove it.

The Testing Pyramid for FHIR

Tier 1: Parse and Validate

Does your FHIR output conform to US Core profiles? You don't need a server for this. The HAPI FHIR Validator runs locally:

java -jar validator_cli.jar patient-bundle.json \
  -ig hl7.fhir.us.core#6.1.0 \
  -profile http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient

Run this in CI on every commit. It catches malformed resources, missing required fields, and profile violations.

Tier 2: Integration

This requires a running FHIR server with SMART on FHIR auth. You need to test the full request lifecycle: discovery, authorization, token exchange, scoped queries.

Things that break at this tier and nowhere else:

Your search uses Observation?category=laboratory but the server indexes it as Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory
Your SMART scopes request patient/Observation.read but the server only grants patient/Observation.rs — read and search are separate grants
Patient/$everything returns 2,000 entries with pagination links your client doesn't follow

Tier 3: Realistic

This is the tier most teams skip. You need patients that look like real patients:

What you're testing	What the data needs
Lab trending UI	3+ years of longitudinal labs with reference ranges
Medication reconciliation	8-12 active medications with start dates and dosages
Problem list display	5-15 active conditions with SNOMED coding
Prior auth workflow	Complex patients who actually get denied

If your Tier 3 data is a single patient named "Test Cancer" with one condition, your tests aren't testing anything.

Your Options

Option 1: Local HAPI + Synthea

You've probably already done this. HAPI in Docker, a handful of Synthea patients, maybe a script that generates 10 bundles.

docker run -p 8080:8080 hapiproject/hapi:latest
cd synthea && ./run_synthea -p 10

When this is enough: Early prototyping, Tier 1 validation.

When it isn't: No SMART auth. Synthea defaults produce patients with single conditions and no clinical depth. At some point the test data pipeline becomes its own project — one you maintain alongside the product you're actually building.

Option 2: Vendor Sandboxes

Open Epic, Oracle Health Code, SMART Health IT Sandbox.

When this is enough: Testing OAuth against a real vendor's auth server.

When it isn't: Open Epic gives you 8 patients with sparse data. No comorbidity patterns. No longitudinal labs. No imaging. No clinical notes. We wrote a whole post about this.

Option 3: Clinically Realistic Sandbox

A FHIR server with SMART auth and patients generated from real clinical patterns.

curl -s https://api.mock.health/fhir/Condition?patient=example \
  -H "Authorization: Bearer $TOKEN" | jq '.entry[].resource.code.coding[0].display'

"Type 2 diabetes mellitus"
"Essential hypertension"
"Chronic kidney disease, stage 3"
"Hyperlipidemia"
"Diabetic retinopathy"

These conditions travel together because the generation engine learned that pattern from real CMS claims data. Compare to Open Epic: "Pain in throat".

What Changes When You Get Production Access

Your sandbox-tested code won't ship unmodified. You'll encounter vendor-specific extensions, data quality variance (plan for trash), and an opaque app review process.

But the architecture you built against a sandbox will survive. The specific data handling will need adaptation. That's normal — sandbox testing builds the 90% that doesn't depend on vendor-specific behavior.

Tier	Tool	Catches
1	HAPI Validator in CI	Malformed resources, profile violations
2	SMART-enabled sandbox	OAuth bugs, search parameter issues
3	Realistic synthetic data	Logic errors with complex patients

Run Tier 1 on every commit. Run Tier 2 when you change auth or query logic. Run Tier 3 before every demo and before you apply for production access.

mock.health — SMART-enabled FHIR sandbox with clinical density to get through Tier 3 testing. API key in 60 seconds →

Three Ways to Build a Multi-Tenant FHIR Server

mock health — Sun, 12 Apr 2026 23:35:03 +0000

You're building a FHIR platform that serves multiple customers. Each one needs isolated data through the same API. There's no best practice for this — Darren Devitt's FHIR Architecture Decisions calls multi-tenancy a "deal breaker" requirement that can eliminate entire classes of FHIR servers.

Three models exist. We've built two of them in production with HAPI FHIR.

Model 1: Separate Database Per Tenant

Each tenant gets their own database schema — or for true physical isolation, their own database host.

What you get: Strongest isolation. Independent scaling. DROP SCHEMA to delete a tenant. Compliance teams love it (especially separate hosts).

What breaks: You're managing N connection pools, N migrations, N backups. HAPI's HikariCP defaults to 10 connections — we exhausted the pool with 8 concurrent workers and left HAPI in a zombie state. Cold starts per tenant add 30-45 seconds when a database hasn't been accessed recently.

When to use it: Regulations mandate physical separation. Tenants are large enough to justify the overhead.

Model 2: Shared Database, Partitioned Tables

One database, but every resource row gets a PARTITION_ID column. HAPI supports this natively:

partitioning:
  database_partition_mode_enabled: true
  request_tenant_partitioning_mode: true
  allow_references_across_partitions: true

Creating a partition:

POST /fhir/$partition-management-create-partition
{"resourceType": "Parameters", "parameter": [
  {"name": "id", "valueInteger": 101},
  {"name": "name", "valueCode": "tenant_acme"}
]}

What you get: Logical isolation at the storage layer. One database to manage. Cross-partition references for shared data (practitioner directories, formularies).

What breaks: HAPI bugs surface here. #1099: patient=UUID triggers "Non-unique ID" errors — fix by rewriting to patient:Patient._id=UUID. #6665: bulk export background jobs lose partition context entirely — we rebuilt the Bulk Data Access IG in Python.

No built-in access control. HAPI doesn't know who's calling — your API gateway handles auth and routing.

When to use it: Many tenants, moderate data volumes. You want logical isolation without N databases.

Model 3: Shared Database, Tag-Based Filtering

One database, no partitions. Every resource gets a meta.tag for its tenant. Your gateway appends _tag=tenant_acme to every query.

extra_params["_tag"] = f"https://yourapp.com/tenant|{tenant_id}"

What you get: Simplest to implement. Zero overhead per tenant. Works with any FHIR server, not just HAPI.

What breaks: No real isolation — the boundary is your gateway's tag-filtering logic. A missed _tag parameter on one endpoint leaks data across tenants.

Worse: HAPI ignores _tag on instance reads. GET /fhir/Patient/abc-123 returns the resource regardless of tags. You need post-fetch verification:

resource = resp.json()
resource_tags = {t["system"] + "|" + t["code"] for t in resource.get("meta", {}).get("tag", [])}
if not resource_tags.intersection(allowed_tags):
    return 404

When to use it: Prototyping. Internal tools. Small deployments. A starting point before migrating to partitions.

How to Choose

Concern	Separate DB	Partitions	Tags
Isolation	Strongest	Logical (storage)	Logical (query)
Compliance	Happy	Usually OK	Nervous
Ops cost per tenant	High	Low	Zero
Performance isolation	Full	Shared DB	Shared everything
HAPI bugs	Fewer	More	Fewer
Works with any server	Yes	HAPI-specific	Yes
Instance read safety	Inherent	Inherent	Post-fetch check

The direction of migration matters: you can move from tags → partitions → separate databases, but not easily the other way. Start with the simplest model that meets your compliance requirements.

Whichever model you choose, the FHIR server handles storage. Auth, routing, and access control are your gateway's job. We wrote about what that gateway looks like.

mock.health handles multi-tenant isolation so you can focus on your integration. Isolated FHIR data with SMART auth — no partition management required. Try it free →

Building a FHIR API Gateway: What HAPI Won't Do for You

mock health — Fri, 10 Apr 2026 22:56:33 +0000

HAPI is a FHIR storage engine. It validates resources, indexes search parameters, and returns Bundles. What it does not do: authenticate users, enforce per-tenant access control, generate correct URLs behind a reverse proxy, or stream large responses without buffering.

We run FastAPI in front of HAPI on Google Cloud Run. Here are the five things the gateway does that HAPI can't.

1. Auth Injection: One Hook, Every Request

In production, HAPI sits behind Cloud Run's IAM layer. Every request needs a GCP identity token. The pattern: an httpx event hook that fires before every outbound request.

async def _inject_hapi_auth(request: httpx.Request):
    token = await get_id_token(audience_url)
    request.headers["Authorization"] = f"Bearer {token}"

The bug we hit: auth injection was per-route. The main proxy had it. Portal routes didn't. Everything worked locally (no IAM). Four endpoints returned 403 in production.

Lesson: Auth belongs on the HTTP client, not on individual routes. One hook, one place, every request.

2. The `--proxy-headers` Trap

This will save you a day if you're running FastAPI behind any load balancer.

Cloud Run terminates TLS. Your app gets HTTP. The load balancer passes X-Forwarded-Proto: https. Uvicorn ignores this by default. So request.base_url returns http://.

The cascade:

SMART discovery advertises http:// token endpoint
Client POSTs auth code to http:// URL
Cloud Run 302 redirects HTTP → HTTPS
302 converts POST to GET (per HTTP spec)
Token endpoint gets GET → 405 Method Not Allowed

Nine places in our code use request.base_url. All nine broke. The fix:

CMD ["uvicorn", "api:app", "--host", "0.0.0.0", "--port", "8000",
     "--proxy-headers", "--forwarded-allow-ips", "*"]

If you're running uvicorn behind any reverse proxy and generating URLs from request.base_url, you need these flags. You won't catch this locally.

3. Tag-Based Access Control

HAPI has no per-user access control. Our gateway appends _tag parameters to scope searches by tenant/dataset.

The gotcha: HAPI ignores _tag on instance reads. GET /fhir/Patient/abc-123 returns the resource regardless of tags. Our gateway does post-fetch verification — fetch the resource, check its tags, return 404 if they don't match.

resource_tags = {t["system"] + "|" + t["code"] for t in resource.get("meta", {}).get("tag", [])}
if not resource_tags.intersection(allowed_tags):
    return 404

Not ideal — the resource is fetched and discarded. But HAPI doesn't support tag filtering on instance reads.

4. Streaming Large Responses

A FHIR $everything can return megabytes. Don't buffer it.

resp = await client.send(req, stream=True)
return StreamingResponse(
    resp.aiter_bytes(),
    status_code=resp.status_code,
    media_type="application/fhir+json",
)

One gotcha: if HAPI returns 503, detect it before starting the stream. Once you've started a StreamingResponse, you can't change the status code.

5. The Catch-All Route Ordering Trap

Our FHIR proxy has a catch-all: /fhir/{path:path}. This matches everything — including /fhir/Patient/$export and /fhir/DocumentReference/$docref, which have dedicated handlers.

If the catch-all mounts first, those routes are unreachable.

# Order matters
app.include_router(bulk_export_router)  # most specific
app.include_router(docref_router)
app.include_router(fhir_router)         # catch-all last

Sounds obvious. Costs an afternoon when you add a new router six months later and forget.

Build the Gateway First

If you're deploying a FHIR server to production, build the gateway layer before you build features on top. Auth, URL generation, access control, streaming, and route safety affect every endpoint you'll add later. The FHIR server stores data. The gateway decides who sees it.

mock.health handles the gateway — SMART auth, access control, streaming — so you can focus on your application. Try it free →

The Contents of That Dumpster Are Private

mock health — Mon, 06 Apr 2026 23:09:23 +0000

Nikhil Krishnan wrote a great piece recently arguing that open source is healthcare's moment. The business models exist (Red Hat, GitLab). AI is lowering the contribution barrier. The ecosystem is ready.

He's right. But there's a punchline missing from the open-standards conversation that anyone who's actually built against healthcare APIs knows intimately:

The standard exists. Nobody follows it the same way.

FHIR (Fast Healthcare Interoperability Resources) is the anointed standard. ONC mandates it. CMS requires it for payer Patient Access APIs. Every major EHR vendor will tell you they support it. And technically, they do — the way a restaurant "supports" vegetarians by offering a side salad.

Same Patient, Different Reality

Flexpa recently published a fascinating comparison: the same patient's health data pulled through two different API pathways. The results should make anyone building healthcare software nervous:

TEFCA path: 192 FHIR resources, but only 1 condition — "pain in throat"
ONC g(10) path: 166 resources, 11 conditions including rhinitis — but missed a documented cat dander allergy entirely

Same patient. Same standard. Wildly different clinical picture. If you were building a care coordination app, which version of this patient would you trust?

This isn't an edge case. It's the norm.

The Spec Says One Thing. Production Says Another.

The January 2026 deadline for USCDI v3 and US Core 6.1.0 was supposed to fix this. Certified health IT modules must now support the latest FHIR profiles with richer data elements. On paper, progress.

In practice:

Major state Medicaid agencies — Arizona, Colorado, Illinois, Indiana, Massachusetts, New York, Pennsylvania, Texas — remain non-compliant
No BCBS plan operated by HCSC has successfully had a patient complete authorization and FHIR data retrieval
53 payers list refresh token support in their SMART configurations but don't actually issue refresh tokens
UnitedHealthcare has nearly 100 patients who simply cannot access their own data through the mandated API

These aren't obscure edge cases. These are the largest payers and state programs in the country.

The Normalization Tax

Even when the APIs work, the data that comes back requires heavy lifting before it's usable.

Zus Health reports that pulling records from clinical networks yields about 200 documents per patient, mapping to over 1,000 raw FHIR resources. Conditions arrive as a grab bag of ICD-9, ICD-10, and SNOMED codes — sometimes all three for the same condition. Without normalization, deduplication, and enrichment, the volume is pure noise.

Particle Health built an entirely proprietary CCDA-to-FHIR converter because open source libraries didn't meet their quality bar.

This is the dirty secret: an entire category of healthcare infrastructure companies exists primarily to clean up the mess that "standardized" data exchange creates. The standard is the floor, not the ceiling — and the floor has holes in it.

Plan for Trash

FHIR is a good standard. US Core is a good implementation guide. The ONC keeps tightening the spec — USCDI v3, US Core 6.1.0, SMART App Launch 2.0. But tighter specs only help if implementations actually conform. Right now, "FHIR-compliant" is a checkbox on a certification form, not a meaningful guarantee that the data you receive will be complete, consistent, or even parseable.

So here's the engineering takeaway: stop hoping for clean data. Plan for trash.

Every application that consumes FHIR from external systems needs a validation layer that isn't optional:

Profile validation on ingest. Every resource that crosses your system boundary gets validated against the US Core profile you expect. Not just schema validation — profile-level.
Completeness checks per data class. USCDI defines 22 data classes. When you pull a patient's record, how many are actually populated? Track and surface that distinction.
Automated regression testing against real-world variance. Your integration tests shouldn't run against a single pristine FHIR server. They should run against data that looks like what production actually sends — missing fields, mixed code systems, DSTU2 holdovers.

The companies actually moving the needle in interoperability — Flexpa, Zus, Particle, Onyx — all learned this the hard way. They built proprietary normalization, deduplication, and validation pipelines because the alternative was shipping broken products. The standard isn't bad. Conformance is just unreliable.

The Dumpster Metaphor, Extended

The meme says the contents of the dumpster are private. That's the HIPAA joke, and it's funny. But the deeper joke is:

Even if you get permission to open the dumpster, what's inside is still trash.

Don't wait for the spec to get stricter, or for ONC enforcement to get teeth, or for vendors to suddenly care about data quality. Build like you know the dumpster is full of trash — because it is — and validate everything that comes out of it.

Which means your test data needs to look like what production actually sends — not pristine sandbox patients with perfect coding. If your integration tests pass against clean data and break against the dumpster, your tests are lying to you.

mock.health generates FHIR data with the clinical density and variance you'll see in the real world. Free tier, no sales call →

How to Make Claude Write Valid Synthea Modules

mock health — Fri, 03 Apr 2026 22:24:49 +0000

Synthea has 85 disease modules. Each one is a JSON state machine that generates encounters, conditions, labs, medications, and procedures for a specific disease. If you need a condition Synthea doesn't cover — celiac disease, migraine, GERD, whatever — you author a new module.

The module format is learnable. The hard part is the medical codes.

Every module embeds SNOMED codes for conditions, LOINC codes for labs, and RxNorm codes for medications. Ask an LLM to write a celiac disease module and it'll generate SNOMED code 396331005. That's correct. Ask it for a duodenal biopsy and it might generate 12866006. Looks right. Validates as a real SNOMED code. It's actually pneumococcal vaccination.

You can't tell a valid code from a hallucinated one by looking at it. The only way to know is to check it against a terminology server. This post teaches that workflow, and we published a Claude Code skill that automates it.

Why You'd Want Custom Modules

We generated 10,000 patients from a fresh Synthea clone and compared against CDC benchmarks:

Coronary heart disease: 0%. Alzheimer's: 0%. Entire disease categories missing from 10,000 patients. Each module runs independently, so conditions don't interact the way real diseases do. We wrote about this in depth in how we validate synthetic data.

An average 80+ year-old Synthea patient has 74 active conditions. The top 1% of real Medicare patients have about 8. Most are social determinants and administrative codes, not diseases.

If your use case needs a disease that Synthea's 85 modules don't cover, you're authoring a module.

The Module Format in 60 Seconds

A Synthea module is a JSON file with a name, a states object, and a gmf_version. Each state has a type and a transition. Here's the smallest useful module:

{
  "name": "Example Condition",
  "states": {
    "Initial": {
      "type": "Initial",
      "distributed_transition": [
        { "distribution": 0.01, "transition": "Onset" },
        { "distribution": 0.99, "transition": "Terminal" }
      ]
    },
    "Onset": {
      "type": "ConditionOnset",
      "codes": [{ "system": "SNOMED-CT", "code": "??????", "display": "??????" }],
      "direct_transition": "Terminal"
    },
    "Terminal": { "type": "Terminal" }
  },
  "gmf_version": 2
}

The ?????? is the problem. What SNOMED code goes there?

State types you'll use: Initial, Terminal, Encounter/EncounterEnd, ConditionOnset/ConditionEnd, MedicationOrder/MedicationEnd, Observation, Procedure, Guard, Delay, SetAttribute.

Transitions: direct_transition (always), conditional_transition (if-then), distributed_transition (probabilistic), complex_transition (conditions + probabilities).

The Code Problem

System	What it codes	Example
SNOMED-CT	Conditions, procedures, findings	`396331005` = Celiac disease
LOINC	Lab results, vital signs	`31017-7` = tTG IgA antibody
RxNorm	Medications	`310325` = Ferrous sulfate 325mg

LLMs pattern-match these codes from training data. They don't look them up. For common conditions, usually right. For anything less common, the LLM generates a plausible number that might not exist.

The fix: tx.fhir.org, a free public FHIR terminology server. No account needed. One curl call validates any code:

curl -s "https://tx.fhir.org/r4/CodeSystem/\$validate-code?\
system=http://snomed.info/sct&code=396331005" \
  | jq '.parameter[] | select(.name=="result" or .name=="display")'

{ "name": "result", "valueBoolean": true }
{ "name": "display", "valueString": "Coeliac disease" }

And to find the right code:

curl -s "https://tx.fhir.org/r4/ValueSet/\$expand?\
url=http://snomed.info/sct?fhir_vs&filter=celiac+disease&count=5" \
  | jq '.expansion.contains[] | {code, display}'

This is what separates a working module from one that generates corrupt FHIR.

The Skill

We published a Claude Code skill that automates this workflow:

claude install github:mock-health/samples/synthea-module-skill
claude "/synthea create a celiac disease module"

The skill follows six steps:

Check existing modules — avoids duplicating what's already there
Research the condition — prevalence, diagnostic criteria, treatment
Look up every code — validates against tx.fhir.org before writing
Generate module JSON — following Synthea's exact schema
Build and test — ./gradlew build -x test + ./run_synthea -m <name> -p 1
Inspect output — checks the generated FHIR bundle

The SKILL.md contains the full module schema reference, code system mappings, grounding rules, and common pitfalls.

Working Example: Celiac Disease

Every code validated against tx.fhir.org:

Concept	System	Code	Display
Celiac disease	SNOMED-CT	`396331005`	Coeliac disease
EGD	SNOMED-CT	`76009000`	Esophagogastroduodenoscopy
Duodenal biopsy	SNOMED-CT	`235261009`	Biopsy of duodenum
Gluten free diet	SNOMED-CT	`160671006`	Gluten free diet
Iron deficiency anemia	SNOMED-CT	`87522002`	Iron deficiency anemia
tTG IgA antibody	LOINC	`31017-7`	Tissue transglutaminase IgA Ab
Ferritin	LOINC	`2276-4`	Ferritin [Mass/volume] in Serum or Plasma
Ferrous sulfate	RxNorm	`310325`	ferrous sulfate 325 MG Oral Tablet

The state machine:

Initial → Age_Guard (wait until age 2)
  → Prevalence_Check (monthly, age-stratified probability)
    → Symptom_Onset → Diagnostic_Encounter
      → tTG IgA test → Referral (2-6 weeks)
        → Endoscopy + Duodenal biopsy
          → Celiac_Diagnosis → Gluten-free diet
            → 50%: Iron deficiency → Ferrous sulfate
              → Annual monitoring (tTG IgA + ferritin)

The module uses complex_transition for age-stratified onset — childhood and ages 30-50 get different probabilities. The full module JSON is about 200 lines. Drop it into synthea/src/main/resources/modules/ and run:

cd synthea
./gradlew build -x test
./run_synthea -m celiac_disease -p 10 -s 42
jq -r '.entry[].resource.resourceType' output/fhir/*.json | sort | uniq -c | sort -rn

For Deeper Work

/fhir Claude Code skill — FHIR R4/R5, IGs, FSH, SMART on FHIR, validation
Inferno — ONC FHIR server compliance testing
Synthea Module Builder — GUI for visual module authoring
tx.fhir.org — public FHIR terminology server (free, no account)

The module format is learnable. The vocabulary problem is solvable. Ground your codes, and don't trust any medical code an LLM generates from memory — including ours. We built mock.health because we hit the limits of module-level fixes. Population-level realism requires a different architecture entirely. Free tier, API key in 60 seconds →

Build a SMART on FHIR App in 30 Minutes

mock health — Thu, 26 Mar 2026 20:55:05 +0000

SMART on FHIR is how apps talk to electronic health records. It's OAuth 2.0 with a few healthcare-specific conventions: a discovery document that tells your app where to authenticate, scopes that map to FHIR resource types, and a launch context that tells you which patient you're looking at.

This tutorial follows SMART App Launch STU2.1 — the current published standard. If you've built an OAuth login flow before, you already understand 80% of it. The other 20% is what this covers.

We're going to build a standalone SMART app that authenticates against a FHIR server, fetches a patient's vital signs, and renders interactive charts — heart rate, blood pressure, SpO2, temperature, weight, and BMI. The whole thing fits in a single index.html file. No React, no bundler, no npm install. Just a text editor and a browser.

By the end you'll have a working app and a mental model for how every SMART on FHIR app works under the hood — whether it's a one-page demo or a production clinical decision support tool launching inside Epic.

Prerequisites

You need two things:

1. A mock.health account. Go to mock.health and sign up. It's free. This gives you a FHIR R4 server with synthetic patients that actually have realistic clinical data — vital signs, conditions, medications, imaging studies.

2. A registered SMART app. In the mock.health dashboard, go to Sandbox → Register App and create a new app with these settings:

App Name: Vital Signs Chart (or whatever you want)
Redirect URI: http://localhost:8080/smart-on-fhir-vital-signs/index.html
Scopes: launch/patient, patient/Patient.rs, patient/Observation.rs, openid, fhirUser

Copy the Client ID — you'll need it in a minute.

A note on scope syntax. SMART App Launch STU2 introduced a new scope format. The v1 format patient/Patient.read became patient/Patient.rs in v2, where the suffix letters map to individual operations: create, read, update, delete, search. So .rs means read + search, and v1's .write maps to v2's .cud. Servers advertise which format they support via permission-v1 and permission-v2 in their capabilities. Most production EHRs accept both formats today. This tutorial uses v2 (*.rs), but v1 (*.read) will also work with mock.health.

The redirect URI matters. It must exactly match the URL where your app is running. When the authorization server sends the user back to your app after login, it appends an authorization code to this URL. If it doesn't match what you registered, the server rejects the request.

Step 1: Discover the SMART Endpoints

Every SMART-enabled FHIR server publishes a discovery document at /.well-known/smart-configuration. This tells your app where to send the user for authorization and where to exchange codes for tokens.

const baseUrl = 'https://api.mock.health';

const response = await fetch(`${baseUrl}/fhir/.well-known/smart-configuration`);
const config = await response.json();

// config.authorization_endpoint → where to redirect the user
// config.token_endpoint         → where to exchange the code for a token

The response looks like this:

{
  "issuer": "https://api.mock.health",
  "authorization_endpoint": "https://api.mock.health/smart/authorize",
  "token_endpoint": "https://api.mock.health/smart/token",
  "grant_types_supported": ["authorization_code"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["launch/patient", "patient/Patient.rs", "patient/Observation.rs", "openid", "fhirUser"],
  "capabilities": ["launch-standalone", "client-public", "context-standalone-patient", "permission-v1", "permission-v2", "sso-openid-connect"]
}

Why discovery instead of hardcoding? Because every FHIR server puts these endpoints at different paths. Epic uses /oauth2/authorize. Oracle Health (Cerner) uses /tenants/{tenant}/protocols/oauth2/profiles/smart-v1/personas/patient/authorize. The discovery document means your app works against any conformant server without code changes.

Step 2: Generate a PKCE Challenge

PKCE (Proof Key for Code Exchange, pronounced "pixie") prevents authorization code interception attacks. Your app generates a random secret (the verifier), hashes it (the challenge), and sends only the hash to the authorization server. When you exchange the code for a token later, you prove you're the same app by sending the original verifier.

function generateCodeVerifier(len = 64) {
  const arr = new Uint8Array(len);
  crypto.getRandomValues(arr);
  return base64url(arr);
}

async function computeCodeChallenge(verifier) {
  const digest = await crypto.subtle.digest(
    'SHA-256',
    new TextEncoder().encode(verifier)
  );
  return base64url(new Uint8Array(digest));
}

function base64url(bytes) {
  let bin = '';
  for (const b of bytes) bin += String.fromCharCode(b);
  return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
}

Store the verifier in sessionStorage — you'll need it after the redirect.

const verifier = generateCodeVerifier();
const challenge = await computeCodeChallenge(verifier);
sessionStorage.setItem('pkce_verifier', verifier);

Step 3: Redirect to Authorize

Build the authorization URL and redirect the user's browser:

const state = crypto.randomUUID();
sessionStorage.setItem('auth_state', state);

const params = new URLSearchParams({
  response_type: 'code',
  client_id: clientId,
  redirect_uri: location.origin + location.pathname,
  scope: 'launch/patient patient/Patient.rs patient/Observation.rs openid fhirUser',
  state,
  aud: `${baseUrl}/fhir`,
  code_challenge: challenge,
  code_challenge_method: 'S256',
});

location.href = `${config.authorization_endpoint}?${params}`;

What each parameter does:

response_type: 'code' — We want an authorization code. Always code.
client_id — Identifies your app.
redirect_uri — Where to send the user back. Must exactly match what you registered.
scope — What data you're requesting. launch/patient asks for a patient context. patient/Observation.rs asks to read and search Observations scoped to that patient.
state — A random string to prevent CSRF attacks.
aud — The FHIR endpoint this token should work with. Prevents token replay across servers.
code_challenge — The PKCE challenge.

After this redirect, the user sees a consent screen. When they approve, the server redirects back to your redirect_uri with ?code=...&state=... appended.

Step 4: Handle the Callback and Exchange the Code

When your page loads, check if there's a code parameter in the URL:

const params = new URLSearchParams(location.search);
const code = params.get('code');
const state = params.get('state');

if (code) {
  if (state !== sessionStorage.getItem('auth_state')) {
    throw new Error('State mismatch — possible CSRF');
  }

  history.replaceState(null, '', location.pathname);

  const verifier = sessionStorage.getItem('pkce_verifier');

  const body = new URLSearchParams({
    grant_type: 'authorization_code',
    code,
    redirect_uri: location.origin + location.pathname,
    client_id: clientId,
  });
  if (verifier) body.set('code_verifier', verifier);

  const response = await fetch(tokenEndpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body,
  });

  const tokens = await response.json();
}

The token response includes everything you need:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "launch/patient patient/Patient.rs patient/Observation.rs openid fhirUser",
  "patient": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "id_token": "eyJhbGciOiJSUzI1NiJ9..."
}

Two SMART-specific fields: patient is the launch context — the ID of the patient the user selected. id_token contains the authenticated user's identity via the fhirUser claim.

Step 5: Fetch Vital Signs

Now you have a bearer token and a patient ID:

const headers = {
  Authorization: `Bearer ${tokens.access_token}`,
  Accept: 'application/fhir+json',
};

const patient = await fetch(`${baseUrl}/fhir/Patient/${tokens.patient}`, { headers })
  .then(r => r.json());

const observations = await fetch(
  `${baseUrl}/fhir/Observation?patient=${tokens.patient}&category=vital-signs&_sort=-date&_count=200`,
  { headers }
).then(r => r.json());

Each Observation has a LOINC code that identifies what it measures:

Vital Sign	LOINC Code	Value Location
Heart Rate	`8867-4`	`valueQuantity.value`
Blood Pressure	`85354-9`	`component[].valueQuantity.value`
Temperature	`8310-5`	`valueQuantity.value`
SpO2	`2708-6`	`valueQuantity.value`
Weight	`29463-7`	`valueQuantity.value`
BMI	`39156-5`	`valueQuantity.value`

Blood pressure is the odd one out. It's a panel — the Observation itself has LOINC code 85354-9, but the actual systolic and diastolic values live in component entries with their own LOINC codes (8480-6 for systolic, 8462-4 for diastolic). Every FHIR developer hits this for the first time and wonders why it's nested. Welcome to the club.

Step 6: Render the Charts

We use Chart.js — one CDN script tag, no build step:

<script src="https://cdn.jsdelivr.net/npm/chart.js@4"></script>

Group observations by type, sort by date, render a line chart for each. For blood pressure, render two datasets on the same chart — systolic and diastolic.

The Complete App

The full working app is ~475 lines in a single index.html. Clone it and run it:

git clone https://github.com/mock-health/samples.git
cd samples
python3 -m http.server 8080

# Open http://localhost:8080/smart-on-fhir-vital-signs/index.html

Enter your Client ID, click Connect, approve access, and you'll see your patient's vital signs charted out.

The full source is on GitHub.

What Changes in Production EHRs

This tutorial uses mock.health, which implements the SMART spec faithfully. Production EHRs are different:

App registration takes weeks, not seconds. Epic's App Orchard requires a formal review process. Budget 2–8 weeks for approval.

Scopes vary. Some EHRs still only accept v1 syntax (patient/Observation.read). Check the server's .well-known/smart-configuration capabilities.

Discovery endpoints aren't always where you expect. Some older servers don't support .well-known/smart-configuration. Fall back to the CapabilityStatement (GET /metadata) and extract OAuth URLs from rest[0].security.extension.

Tokens expire and refresh tokens matter. In production, request offline_access scope and implement refresh token rotation.

None of this changes the fundamental flow. Discovery → PKCE → authorize → callback → token → API calls. Same everywhere. The operational details differ.

Sign up at mock.health — free tier, no sales call. The hardest part of building a SMART on FHIR app is getting access to a server that has realistic data and implements the spec correctly. Now you have one.

The FHIR Sandbox Problem: Why Open Epic Won't Get You to Your First Customer

mock health — Sun, 22 Mar 2026 21:05:56 +0000

You're three months into building a FHIR integration. You've got OAuth working, you can pull Patient resources, your UI renders demographics cleanly. Time to show it to a potential customer.

You open the sandbox patient and see this:

{
  "resourceType": "Patient",
  "id": "erXuFYUfucBZaryVksYEcMg3",
  "name": [
    {
      "use": "usual",
      "text": "Test Cancer",
      "family": "Cancer",
      "given": ["Test"]
    }
  ],
  "birthDate": "1971-08-07",
  "gender": "female",
  "address": [
    {
      "use": "home",
      "line": ["123 Main St."],
      "city": "Madison",
      "state": "WI",
      "postalCode": "53703"
    }
  ]
}

The patient's name is "Test Cancer." The address is 123 Main St. There are no emergency contacts, no marital status, no communication preferences. You scroll through the rest of the sandbox patients. "Derrick Lin." "Jason Argonaut." A handful of others, all equally sparse.

This is Open Epic's sandbox. And it's the starting point for nearly every FHIR startup in the US.

What Open Epic Actually Gives You

Open Epic provides a shared FHIR R4 sandbox with eight named test patients (Camila Lopez, Derrick Lin, Desiree Powell, Elijah Davis, Linda Ross, Olivia Roberts, Warren McGinnis, and Jason Argonaut). These patients exist to validate API connectivity — to confirm that your OAuth flow works, that you can parse a Bundle, that your FHIR client handles pagination. They were never designed to represent what real patient data looks like.

Here's what the sandbox gives you versus what you need to demo a real clinical application:

Capability	Open Epic Sandbox	Production Demo Needs
Patient demographics	Name, DOB, gender, address	Race, ethnicity, language, multiple addresses, contacts
Conditions	1-3 active conditions	5-15 conditions with onset dates, comorbidity patterns
Medications	Sparse, often missing	Active + historical, with dosage and frequency
Lab observations	Few, no trends	Longitudinal panels (HbA1c over 3 years, lipid trends)
Imaging studies	None	ImagingStudy + DiagnosticReport with narrative text
Clinical notes	None or minimal	Discharge summaries, progress notes, radiology reports
Encounters	1-3 encounters	Multi-year history across ambulatory, inpatient, ED
Vital signs	Sparse	Trending data (BP, weight, heart rate over time)

The sandbox is optimized for certification. It proves your app can authenticate and read FHIR resources. It says nothing about whether your app can handle a real patient record.

The Alternative Landscape Is Shrinking

Open Epic isn't the only sandbox, but the options are thinner than you'd think.

Logica Health (formerly HSPC) ran a well-regarded public sandbox for years. It was retired on October 31, 2024. If your integration documentation still points there, those links are dead.

SMART Health IT maintains a sandbox with about 100 Synthea-generated patients. The data is structurally valid but clinically shallow — default Synthea output without enrichment. (If you've used it, you know the feeling: the FHIR parses fine, but the patient has three conditions and no meds.)

Individual health systems sometimes provide sandbox access, but getting it requires a signed BAA, a security review, and months of procurement. That's not a sandbox. That's a sales cycle.

The Gap Between Sandbox and Production

Missing fields are the obvious problem. The deeper problem is missing clinical coherence — real patient data tells a story, and sandbox data doesn't have one.

No Comorbidities

In the real world, Type 2 Diabetes doesn't travel alone. It shows up with hypertension, hyperlipidemia, chronic kidney disease, and obesity. A 62-year-old diabetic in a production EHR typically has 8-15 active conditions, most of them clinically related.

Open Epic's test patients have conditions, but they're isolated. You won't find a patient whose diabetes diagnosis is followed by quarterly HbA1c labs trending from 7.2 to 8.1 over 18 months, with a metformin prescription added at diagnosis and a GLP-1 agonist added when the HbA1c crossed 8.0. That's what your app needs to demo against.

No Imaging, No Clinical Narrative

Search for ImagingStudy resources in the Open Epic sandbox. Empty bundles. No DiagnosticReports with radiology narrative. No discharge summaries, no progress notes. Production EHRs have presentedForm.data fields with base64-encoded report text — the full narrative a radiologist dictated. Sandboxes have "FINDINGS: Normal. IMPRESSION: Normal." or nothing at all.

If you're building anything that touches imaging, clinical NLP, or document summarization — you have zero test data to work with.

No Longitudinal History

Real patients have years of history. A production Patient sits at the center of hundreds of linked resources — encounters spanning a decade, medication changes over time, lab trends that tell a clinical story.

Sandbox patients have one or two encounters. You can't demonstrate a timeline view, trend analysis, or care gap detection when the patient's entire history fits in a single API response.

What You Actually Get: Epic Sandbox vs. Production

To make this concrete, here's a real query against the Epic on FHIR sandbox for Camila Lopez — the "Test Cancer" patient from the opening of this post — filtering for laboratory observations:

curl -s "https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4/Observation\
?patient=erXuFYUfucBZaryVksYEcMg3&category=laboratory" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/fhir+json" | jq '.total, [.entry[].resource |
    {code: .code.text, date: .effectiveDateTime,
     value: (.valueQuantity.value | tostring) + " " + .valueQuantity.unit}]'

A representative sandbox response:

2,
[
  {
    "code": "Hemoglobin A1c/Hemoglobin.total in Blood",
    "date": "2019-06-10T15:38:00Z",
    "value": "7.6 %"
  },
  {
    "code": "Glucose [Mass/volume] in Blood",
    "date": "2019-06-10T15:38:00Z",
    "value": "138 mg/dL"
  }
]

Two observations. Both from the same date. No prior values, no subsequent values. If you're building a diabetes management dashboard, a trend chart, or a care gap detector — this tells you nothing.

Now compare that to what a production EHR returns — or what mock.health generates — for a 62-year-old with Type 2 Diabetes:

15,
[
  { "code": "Hemoglobin A1c", "date": "2022-01-15", "value": "6.8 %" },
  { "code": "Hemoglobin A1c", "date": "2022-04-22", "value": "7.1 %" },
  { "code": "Hemoglobin A1c", "date": "2022-07-30", "value": "7.4 %" },
  { "code": "Hemoglobin A1c", "date": "2022-10-18", "value": "7.9 %" },
  { "code": "Hemoglobin A1c", "date": "2023-01-12", "value": "8.1 %" },
  { "code": "Hemoglobin A1c", "date": "2023-04-05", "value": "7.6 %" },
  { "code": "Hemoglobin A1c", "date": "2023-07-20", "value": "7.3 %" },
  { "code": "Hemoglobin A1c", "date": "2023-10-11", "value": "7.1 %" },
  { "code": "Hemoglobin A1c", "date": "2024-01-08", "value": "7.0 %" },
  { "code": "Hemoglobin A1c", "date": "2024-04-15", "value": "6.9 %" },
  { "code": "Glucose",        "date": "2022-01-15", "value": "128 mg/dL" },
  { "code": "Glucose",        "date": "2022-07-30", "value": "156 mg/dL" },
  { "code": "Glucose",        "date": "2023-01-12", "value": "172 mg/dL" },
  { "code": "Glucose",        "date": "2023-07-20", "value": "145 mg/dL" },
  { "code": "Glucose",        "date": "2024-04-15", "value": "132 mg/dL" }
]

Fifteen observations spanning two and a half years. You can see the HbA1c climbing from 6.8 to 8.1 — the point at which a clinician would escalate medication — then trending back down after treatment adjustment. The glucose values correlate. There's a clinical story in this data.

The sandbox has the right resource types. The data inside them is empty.

What "Realistic" Means for a FHIR Integration

"Realistic" has a specific definition. It's in the spec.

US Core Profiles

US Core is the implementation guide that specifies how FHIR resources should be structured in the US healthcare system. Every EHR certified under ONC's Health IT Certification Program must conform to US Core profiles.

US Core doesn't just say "include a Patient resource." It specifies which fields are required (must be present), which are must-support (must be handled if present), and which extensions are standard. A US Core Patient requires name, gender, and identifier. It must-supports race, ethnicity, birthDate, and communication.

If your test data doesn't include must-support fields, you can't verify that your app handles them correctly. And if your demo doesn't show them, your prospect — who looks at US Core-conformant data all day — will notice.

USCDI Data Classes

The United States Core Data for Interoperability (USCDI) defines the minimum data classes that certified health IT must support. USCDI v3, mandatory as of January 2026, includes:

Patient demographics (including sexual orientation and gender identity)
Allergies and intolerances
Medications (active and historical)
Problems (conditions)
Procedures
Laboratory results
Vital signs
Clinical notes (discharge summaries, progress notes, consultation notes)
Diagnostic imaging (reports and studies)
Health insurance information
Clinical tests

Your test data should cover all of these. The sandbox covers maybe four.

Correlated Clinical Data

The hardest gap to fill is missing correlations. In real clinical data, conditions, medications, labs, and encounters are causally connected. A diabetes diagnosis triggers HbA1c monitoring every 3-6 months. An elevated creatinine prompts a nephrology referral. An abnormal chest X-ray leads to a CT follow-up.

Standard synthetic data generators don't model these relationships. A 2019 validation study of Synthea in BMC Medical Informatics and Decision Making found that Synthea-generated populations showed 0% blood pressure control rates compared to 69.7% in real-world data. The resources parse. The population statistics are wrong.

Try It

You can query mock.health's FHIR API directly:

curl -s https://api.mock.health/fhir/Patient?_count=1 \
  -H "Accept: application/fhir+json" | jq '.entry[0].resource | {
    name: .name[0].text,
    birthDate,
    gender,
    race: .extension[] | select(.url | contains("race")) | .extension[0].valueCoding.display,
    ethnicity: .extension[] | select(.url | contains("ethnicity")) | .extension[0].valueCoding.display
  }'

And a radiology report with actual clinical narrative:

curl -s "https://api.mock.health/fhir/DiagnosticReport?category=RAD&_count=1" \
  -H "Accept: application/fhir+json" | jq -r '
    .entry[0].resource.presentedForm[0].data' | base64 -d

That base64 -d decodes the report text. You'll see findings, impressions, and clinical language — not "Normal. Normal. Normal."

If you've already built a SMART on FHIR app, you can point it at https://api.mock.health/fhir and get realistic clinical data through the same OAuth flow you'll use in production.