The reference server for the API, built to force design questions out into the open — Mar 21, 2025
The Express-server demo
Discovery through CapabilityStatement, and a $run operation that applies a ViewDefinition and returns JSON, NDJSON or CSV, with $export to follow. Canonical resources are just files in a folder.
The point of building it is that it surfaces decisions prose lets you dodge — parameters now live in an OperationDefinition rather than in markdown, and the output formats in a ValueSet.
Test suite parameterised by base URL
Same tests run against anyone's implementation, driven by what that server's CapabilityStatement claims it supports. A reference client is next.
The longer-term prize: publicly hosted runners the ViewDefinition builder could switch between, so you author a view once and try it against several engines.
Format questions surfaced immediately
Bulk export answers with bespoke JSON; the argument here is to use FHIR Parameters for input and output instead, so ordinary FHIR SDKs can consume the API rather than needing a bulk-export-specific client — with content negotiation to offer plain JSON as well.
The ValueSet binding is awkward too: bind it extensible and a server that only does CSV can't reuse it, so example may be the honest binding.
patient and _since — inherited, but not free
Doing patient properly means the FHIR patient compartment, not a naive filter on ID — which means every runner needs compartment logic, or has to delegate to an underlying bulk export.
The group agreed patient is necessary in the real world rather than a demo nicety, so it stays.
John — levels below "run it"
- Pre-flight — given this ViewDefinition, your server's capabilities and my permissions, could you do this at all (parse it, answer yes or no, don't run it)
- Count-only / dry-run — record counts without files
That comes from a federated cohort-builder use case: ask several servers how many records match before asking any of them for columns.
These operations can be very expensive, and a client today has no way to discover that the answer is three days.