How do you describe an operation whose answer is a CSV file? — Mar 28, 2025

Advertising ViewDefinition in CapabilityStatement

The group settled on advertising ViewDefinition as a resource type in the CapabilityStatement, so discovery is ordinary FHIR: read the statement, look at the interactions, search for the views.

It is against the spec — ViewDefinition isn't a real resource — but the precedent already exists and clients in practice don't fail on resource types they don't recognise.

The caveat from the spec side: keep track of what works and what doesn't, because that experience is what should steer the R6 decision, including whether the version has to be explicit.

Input — a Parameters resource with a published profile

An OperationDefinition can express nearly the same information — it literally reuses the same parameter datatype, parts and all — but you can't validate against it and there are no good examples, so developers end up asking for a profile anyway.

A profile can also carry invariants an OperationDefinition can't, like you may not supply both viewUrl and viewCanonical.

R6 adds inputProfile and outputProfile for exactly this; earlier versions need a cross-version extension.

A style point that stuck

Prefer separate parameter names — viewUrl and viewCanonical — over one polymorphic parameter. Then client code switches on the parameter name, instead of switching on the name and then again on whatever type it discovers.

The interesting hole — return type is a required binding to FHIR types

There's no way to declare this returns CSV or this returns Parquet. The existing trick, which GraphQL uses, is to declare the return as Binary and lean on the Accept header and mime type.

Nobody actually wraps the response in a Binary resource — GraphQL clients would break if you did — so the spec is quietly lying about it. Someone pointed out the Binary page does document exactly this content-negotiation behaviour, which makes it half-defensible.

Action: file a ticket to allow declaring a content type directly.

Async export response — return a Parameters body too

Bulk export returns 202 with a Location header and a progress value that is just an unstructured string clients try to parse.

The proposal: return a Parameters body as well — an export ID, the location, the input parameters echoed back for debugging, and structured progress:

• Percentage
• Estimated completion
• Which views are already exported
• Rows processed

All optional, since some implementations can't report progress at all.

The same shape just accumulates fields as the job runs and ends with the outputs, and it leaves somewhere to put things like an auth hint for fetching the files.