By Medical form

QuestionnaireResponse vs Custom JSON for Form Data Capture

QuestionnaireResponse vs Custom JSON for Form Data Capture

A clinical form has to land somewhere. The two common choices are the FHIR QuestionnaireResponse resource, which keeps the data inside the FHIR ecosystem, and a custom JSON shape designed by the team for their specific application. Both work. The choice between them shapes downstream interoperability, validation rigor, and the engineering cost of changes years later. For broader background, see more on FHIR data exchange patterns.

The FHIR SDC form builders reference guide covers the broader picture in which this comparison sits.

What Each Side Actually Is

Side-by-side comparison of FHIR QuestionnaireResponse and custom JSON for form data capture across structure, interoperability, mapping, and tooling.

A QuestionnaireResponse is the FHIR resource designed to hold the answers to a Questionnaire. Each answer is linked to the originating question by linkId, types are constrained by the source Questionnaire, and the entire response can be validated against the questionnaire definition. The trade-off is that the QuestionnaireResponse shape is verbose and not always easy for downstream non-FHIR consumers to work with.

A custom JSON shape is whatever the team designs. It can be flat, hierarchical, denormalized, whatever fits the immediate use case. The trade-off is that the team owns the schema, the validation, and the round-trip to any FHIR consumer downstream.

Where QuestionnaireResponse Wins

QuestionnaireResponse is the right choice when:

  1. The data eventually lands in a FHIR-shaped clinical store as Observations, Conditions, or Procedures, and the SDC extraction pipeline can do the mapping.
  2. The team wants validation against the Questionnaire definition for free, with no separate schema layer to maintain.
  3. The data has to be shared across systems that already speak FHIR, which is increasingly the default in 2026.

The top FHIR form engines with strong validation walkthrough covers how QuestionnaireResponse validation looks in production engines.

Where Custom JSON Wins

Custom JSON is the right choice when:

  1. The form data is genuinely application-specific and never needs to leave the application's own data store.
  2. The team needs a much terser shape than QuestionnaireResponse provides, particularly for offline-first mobile apps where payload size matters.
  3. The team is not yet on a FHIR-shaped clinical store and converting to QuestionnaireResponse would require building the FHIR layer just for forms.

In all three cases, the cost of going custom is the cost of owning the schema and the validation. That cost is sometimes worth it.

The Migration Question

Teams that start with custom JSON and later move to FHIR usually pay a migration tax. The mapping from a flat custom shape to a QuestionnaireResponse plus the extracted Observations is real engineering work, and the historical data has to be replayed. The cleanest path for teams that expect to land on FHIR eventually is to start on QuestionnaireResponse from day one, even if the broader stack is not yet FHIR-shaped.

For the related architectural question of how QuestionnaireResponse compares to FHIR Composition for structured clinical note capture, the SDC vs FHIR Composition comparison covers the trade-offs.

The choice is real but not religious. Pick QuestionnaireResponse if the team is or will be on FHIR; pick custom JSON if the team genuinely will not be. The wrong move is to pretend the migration is cheap when it is not. A working layer in this part of the stack is mostly invisible; if the team is still discussing it weekly a year later, the layer is doing too much. Picking carefully here saves more cycles in year two than any front-loaded feature comparison ever does.

Sources