$questionnaire-package

Operation defined by Da Vinci DTR STU 2.0.0 for packaging a Questionnaire together with its referenced ValueSets and a pre-populated draft QuestionnaireResponse, returned as a single Bundle.

A DTR client calls this operation to retrieve everything needed to render a payer's questionnaire — Questionnaire definition, expanded ValueSets, and a draft QuestionnaireResponse with prefilled answers — without making additional requests to the server.

Current Limitations

The current implementation supports a subset of the full Da Vinci DTR specification:

Single Questionnaire flow only — the questionnaire parameter is used to request a specific Questionnaire
No CQL Library support — CQL libraries referenced by the Questionnaire are not included in the bundle
No context parameter — the CRD context ID parameter is not yet supported
No changedsince parameter — incremental updates based on timestamp are not supported

Endpoints

The operation is available at the following endpoints:

Endpoint	Description
`POST /fhir/Questionnaire/$questionnaire-package`	FHIR endpoint
`POST /Organization/{id}/fhir/Questionnaire/$questionnaire-package`	Multi-tenant FHIR endpoint

Auth

Authentication and scopes depend on the calling DTR client. See Authentication.

Input Parameters

The operation accepts a FHIR Parameters resource with the following parameters:

Parameter	Type	Cardinality	Description
questionnaire	canonical	1..1	The canonical URL of the Questionnaire to retrieve (optionally with version, e.g., `http://example.org/Questionnaire/my-form\|1.0`)
coverage	Coverage	0..1	Coverage resource that establishes the member and coverage context. The `beneficiary` reference is used to set `QuestionnaireResponse.subject`
order	Resource	0..1	Order resource (e.g., ServiceRequest, MedicationRequest) that establishes the context for documentation collection

Launch Context

The coverage and order parameters are passed to the populate operation as launch context variables, making them available in FHIRPath expressions:

%coverage — the Coverage resource
%order — the order resource (ServiceRequest, MedicationRequest, etc.)

Output Parameters

The operation returns a FHIR Parameters resource with:

Parameter	Type	Cardinality	Description
packagebundle	Bundle	1..1	A collection Bundle containing the Questionnaire, expanded ValueSets, and a draft QuestionnaireResponse
outcome	OperationOutcome	0..1	Warnings or informational messages about the operation (e.g., ValueSets that couldn't be expanded)

Package Bundle Structure

The packagebundle is a FHIR Bundle of type collection. Entries appear in this order:

First entry — the requested Questionnaire.
Middle entries — each ValueSet referenced by answerValueSet, pre-expanded.
Last entry — a draft QuestionnaireResponse with status in-progress.

ValueSet Handling

ValueSets are expanded using the $expand operation
Only ValueSets with 40 or fewer concepts are included in the bundle
ValueSets with more than 40 concepts are excluded, and an informational message is added to the outcome
If a ValueSet cannot be expanded, a warning is added to the outcome

Examples

Basic Request

Retrieve a questionnaire package by canonical URL:

POST /fhir/Questionnaire/$questionnaire-package
Content-Type: application/fhir+json
Accept: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "questionnaire",
      "valueCanonical": "http://example.org/Questionnaire/prior-auth-form|1.0"
    }
  ]
}

Request with Coverage

Include coverage to set the QuestionnaireResponse subject:

POST /fhir/Questionnaire/$questionnaire-package
Content-Type: application/fhir+json
Accept: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "questionnaire",
      "valueCanonical": "http://example.org/Questionnaire/prior-auth-form|1.0"
    },
    {
      "name": "coverage",
      "resource": {
        "resourceType": "Coverage",
        "id": "coverage-123",
        "status": "active",
        "beneficiary": { "reference": "Patient/patient-456" },
        "payor": [{ "reference": "Organization/payer-789" }]
      }
    }
  ]
}

Request with Coverage and Order

Include both coverage and order for full context in population expressions:

POST /fhir/Questionnaire/$questionnaire-package
Content-Type: application/fhir+json
Accept: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "questionnaire",
      "valueCanonical": "http://example.org/Questionnaire/prior-auth-form|1.0"
    },
    {
      "name": "coverage",
      "resource": {
        "resourceType": "Coverage",
        "id": "coverage-123",
        "status": "active",
        "beneficiary": { "reference": "Patient/patient-456" }
      }
    },
    {
      "name": "order",
      "resource": {
        "resourceType": "ServiceRequest",
        "id": "order-789",
        "status": "active",
        "intent": "order",
        "code": {
          "coding": [
            { "system": "http://example.org/procedures", "code": "12345", "display": "Medical Procedure" }
          ]
        },
        "subject": { "reference": "Patient/patient-456" }
      }
    }
  ]
}

Successful Response

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "packagebundle",
      "resource": {
        "resourceType": "Bundle",
        "type": "collection",
        "entry": [
          {
            "resource": {
              "resourceType": "Questionnaire",
              "id": "prior-auth-form",
              "url": "http://example.org/Questionnaire/prior-auth-form",
              "version": "1.0",
              "status": "active",
              "item": [
                {
                  "linkId": "diagnosis",
                  "type": "choice",
                  "text": "Primary Diagnosis",
                  "answerValueSet": "http://example.org/ValueSet/diagnosis-codes"
                }
              ]
            }
          },
          {
            "resource": {
              "resourceType": "ValueSet",
              "url": "http://example.org/ValueSet/diagnosis-codes",
              "expansion": {
                "contains": [
                  { "system": "http://hl7.org/fhir/sid/icd-10", "code": "J06.9", "display": "Acute upper respiratory infection" }
                ]
              }
            }
          },
          {
            "resource": {
              "resourceType": "QuestionnaireResponse",
              "questionnaire": "http://example.org/Questionnaire/prior-auth-form|1.0",
              "status": "in-progress",
              "subject": { "reference": "Patient/patient-456" },
              "item": [
                { "linkId": "diagnosis", "text": "Primary Diagnosis" }
              ]
            }
          }
        ]
      }
    }
  ]
}

Response with Warnings

When some ValueSets cannot be included:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "packagebundle",
      "resource": {
        "resourceType": "Bundle",
        "type": "collection",
        "entry": [
          { "resource": { "resourceType": "Questionnaire", "id": "prior-auth-form" } },
          {
            "resource": {
              "resourceType": "QuestionnaireResponse",
              "questionnaire": "http://example.org/Questionnaire/prior-auth-form|1.0",
              "status": "in-progress"
            }
          }
        ]
      }
    },
    {
      "name": "outcome",
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          {
            "severity": "information",
            "code": "too-costly",
            "diagnostics": "ValueSet too large to embed (>40 concepts): http://example.org/ValueSet/large-codes"
          },
          {
            "severity": "warning",
            "code": "not-found",
            "diagnostics": "ValueSet expansion failed: http://example.org/ValueSet/unknown-codes"
          }
        ]
      }
    }
  ]
}

Error Response — Missing Parameter

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "required",
      "diagnostics": "Missing required parameter: 'questionnaire'"
    }
  ]
}

Error Response — Questionnaire Not Found

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "diagnostics": "Questionnaire not found: http://example.org/Questionnaire/unknown"
    }
  ]
}

Using Population Expressions

Questionnaires can include population expressions that reference the launch context. For example:

{
  "resourceType": "Questionnaire",
  "url": "http://example.org/Questionnaire/with-population",
  "item": [
    {
      "linkId": "coverage-id",
      "type": "string",
      "text": "Coverage ID",
      "extension": [
        {
          "url": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-initialExpression",
          "valueExpression": { "language": "text/fhirpath", "expression": "%coverage.id" }
        }
      ]
    },
    {
      "linkId": "order-status",
      "type": "string",
      "text": "Order Status",
      "extension": [
        {
          "url": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-initialExpression",
          "valueExpression": { "language": "text/fhirpath", "expression": "%order.status" }
        }
      ]
    },
    {
      "linkId": "patient-name",
      "type": "string",
      "text": "Patient Name",
      "extension": [
        {
          "url": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-initialExpression",
          "valueExpression": { "language": "text/fhirpath", "expression": "%subject.name.first().given.first()" }
        }
      ]
    }
  ]
}

When this questionnaire is requested with coverage and order parameters, the QuestionnaireResponse will have pre-populated answers:

{
  "resourceType": "QuestionnaireResponse",
  "status": "in-progress",
  "subject": { "reference": "Patient/patient-456" },
  "item": [
    { "linkId": "coverage-id", "answer": [{ "valueString": "coverage-123" }] },
    { "linkId": "order-status", "answer": [{ "valueString": "active" }] },
    { "linkId": "patient-name", "answer": [{ "valueString": "John" }] }
  ]
}