Trail documentation
Category envelopes and FHIR bundles: the boundary in FHIR Trail
Trace the normalized response into FHIR Trail’s flat resource list and understand which fields belong to the API and which belong to the app.
Start with the response contract
A developer needs to know which representation is being inspected before choosing a parser or validator. FHIR Trail receives records grouped into named categories. The interface flattens those arrays into a navigable list; that transformation does not produce a FHIR Bundle.
Identify the application’s annotation
The flattening helper adds a category field so entries can retain their group in the inspector. That label is useful for navigation, but it should not be presented as a field guaranteed to exist on the source EHR’s original resource. Keep the annotation’s origin clear when explaining or exporting examples.
Validate the layer you are actually using
Check the upstream normalized API contract when integrating the response. Check the local helper when investigating how category arrays became a list. A clinical FHIR validation step applied to an app-annotated object may be testing a different representation than the one its author intended.
Preserve an inspectable transformation
The current code keeps the returned record fields visible while adding the category label. An operator extending the inspector should document any further renaming, grouping or derived field. Tests should show how empty categories and unfamiliar resource types behave, rather than assuming every response looks like one sample.
The FinchNode contract is the integration reference
FHIR Trail links directly to FinchNode’s public OpenAPI contract because that is the response boundary used by this implementation. The inspector then makes its own small transformation visible. This gives developers a concrete reference for separating transport data from interface annotations.
Questions about this guide
Is the category field proof that the source uses the same grouping?
No. FHIR Trail adds that field while flattening the normalized category arrays.