{ "openapi": "3.0.2", "info": { "title": "DTR Payer Service", "description": "This capability statement defines the expected capabilities of payer systems that provide questionnaires to DTR clients. Such systems need only support server capabilities for the Questionnaire Package, ValueSet Expand, and Next Question operations.", "license": { "name": "Creative Commons Zero v1.0 Universal", "url": "http://spdx.org/licenses/CC0-1.0.html" }, "version": "2.2.0", "contact": { "name": "HL7 International / Clinical Decision Support", "url": "http://www.hl7.org/Special/committees/dss" } }, "externalDocs": { "url": "http://hl7.org/fhir/us/davinci-dtr/CapabilityStatement/dtr-payer-service", "description": "FHIR CapabilityStatement" }, "paths": { "/metadata": { "summary": "Access to the Server\u0027s Capability Statement", "description": "All FHIR Servers return a CapabilityStatement that describes what services they perform", "get": { "summary": "Return the server\u0027s capability statement", "operationId": "metadata", "responses": { "default": { "description": "Error, with details", "content": { "application/fhir+json": { "schema": { "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/OperationOutcome" } } } }, "200": { "description": "the capbility statement", "content": { "application/fhir+json": { "schema": { "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/CapabilityStatement" } } } } }, "parameters": [ { "$ref": "#/components/parameters/format" }, { "$ref": "#/components/parameters/pretty" }, { "$ref": "#/components/parameters/summary" }, { "$ref": "#/components/parameters/elements" } ] } }, "/Questionnaire/$questionnaire-package": { "summary": "Operation $questionnaire-package on type Questionnaire", "description": "Operation $questionnaire-package on type Questionnaire", "get": { "summary": "$questionnaire-package on type Questionnaire", "description": "This operation returns one or more \u0027collection\u0027 Bundles each consisting of a single Questionnaire resource, a single QuestionnaireResponse resource, and any dependency Library and ValueSet instances needed to allow a renderer to fully render and otherwise process the Questionnaire.\n\n§oper-6^dtr-client^exchange:The operation **SHALL** take as input the Coverage resource(s) identifying the member and the type(s) of Coverage for which additional information is needed and at least one of:§ \n* Zero or more canonicals specifying the URL and, (optionally) the version of the Questionnaire(s) to retrieve;\n* A CRD/PAS context ID, and/or\n* One or more Request or Encounter resources\n\nIf specific Questionnaires are specified, the operation will return the specified versions of the respective Questionnaires (or current version if no version is indicated). For the other parameters (context id or resources) the payer will determine, all Questionnaires relevant to determining coverage, prior authorization, claims acceptability, documentation requirements, etc. that are relevant to the specified context. The list of questionnaires returned will be the union of those determined by evaluating each of the provided parameters, with each Questionnaire version only being returned once. §oper-7?^dtr-server^exchange:If multiple versions of a questionnaire are returned, each **SHALL** be associated with distinct orders or coverages in the associated QuestionnaireResponses (see below).§\n\n§oper-8?^dtr-server^exchange:If this operation is invoked with a context id provided by CRD where the `coverage-information` extension indicated that additional documentation was required, but no questionnaires are returned by the operation, the operation **SHALL** return an OperationOutcome with clear instructions on how else to determine needed documentation or an indication that circumstances have changed and additional documentation is no longer necessary.§\n\nIn most cases, only one order and one coverage will be provided. However, the operation allows for circumstances where the decision support engine can handle multiple active coverages - either for the same payer or multiple payers handled by the same engine. It also handles multiple orders with overlapping requirements where a payer might be able to minimize the answers to be gathered by processing the answers as a group.\n\n§oper-9?^dtr-server^exchange:If any of the explicitly requested questionnaires cannot be found, a warning **SHALL** be provided in the [`Outcome`](StructureDefinition-dtr-qpackage-output-parameters.html) element of the outer `Parameters` resource.§ Similarly, if there is an issue understanding any of the orders or coverages and determining appropriate Questionnaires, a warning will be provided.\n\nEach Questionnaire will be packaged into a distinct Bundle. §oper-10?^dtr-server^exchange:If the operation is successful, the response **SHALL** be a `Parameters` resource conformant to the [DTRQuestionnairePackageOutputParameters](StructureDefinition-dtr-qpackage-output-parameters.html) profile.§ §oper-11?^dtr-server^exchange:If the operation fails, the response payload **SHOULD** be an OperationOutcome.§\n\n§oper-12^dtr-server^exchange:The Bundle **SHALL** include the Questionnaire as the first entry along with all external Libraries referenced by the Questionnaire using the [cqf-library](https://build.fhir.org/ig/HL7/fhir-extensions/StructureDefinition-cqf-library.html) extension, as well as a recursive retrieval of all `relatedArtifact` references of type \u0027depends-on\u0027.§ §oper-13^dtr-server^exchange:All Libraries **SHALL** include both CQL and EML representations.§ §oper-14^dtr-server^exchange:The Bundle **SHALL** include all external ValueSet instances referenced by the Questionnaire.§ §oper-15^dtr-server^exchange:All value sets with expansions under 40 entries **SHALL** be expanded as of the current date and using expansion parameters (such as SNOMED release) as deemed appropriate by the payer.§\n\n§oper-16^dtr-server^exchange:All references to Questionnaires, Libraries, and ValueSets within the Bundle **SHALL** be version specific, as breaking changes may occur between versions and would likely cause failures or inconsistent data.§ Note that the same Libraries and/or ValueSets may appear in more than one Questionnaire Bundle, possibly with a different version.\n\nIf any of the dependencies cannot be retrieved or value sets expanded, a warning will be included in the [`Outcome`](StructureDefinition-dtr-qpackage-output-parameters.html). Each Library and ValueSet will only appear once in the Bundle, even if it is referenced multiple places. The only exception is if more than one version of a Library or ValueSet are referenced. Multiple versions of a ValueSet will be returned. §oper-17^dtr-server^exchange:Multiple versions of a Library **MAY** be treated as an error, or **MAY** be handled by returning the \u0027most recent\u0027 version of the referenced versions.§\n\n§oper-18^dtr-server^exchange:As well, the Questionnaire Bundle **SHALL** contain one initial draft `QuestionnaireResponse` that references the `Questionnaire` for that Bundle and populate the subject as well as repetitions of the Context extension that identify the Coverage(s) and Request or Encounter resources the `Questionnaire` is to be completed for.§ The same `QuestionnaireResponse` might be associated with multiple Request resources or may need to be filled out separately for different Requests.\n\n§oper-19^dtr-server^exchange:The payer **MAY** opt to pre-populate some answers in the provided QuestionnaireResponses based on information the payer has in its own records or has from context from CRD or from other prior auth or claims submissions.§\n\nPayers must be cautious about prepopulating Questionnaires with sensitive information, because there are rare situations where a malicious application could attempt to access information that was not authorized by the EHR.\n\n§oper-20?^dtr-client^exchange:When resuming a work in progress questionnaire response the DTR client **SHALL** invoke the operation with the timestamp to see if the questionnaire package has changed since it was last retrieved, presuming that the `QuestionnaireResponse.meta.lastUpdated` element corresponds to the last package retrieval time.§\n\n### Notes\n* For adaptive questionnaires, there will be no question items to reference any ValueSets and no expressions to reference any Libraries. However, the payer may still opt to include Libraries or ValueSets in the initial Bundle to avoid the overhead of needing to send contained content with each [`$next-question`](http://hl7.org/fhir/uv/sdc/STU3/OperationDefinition-Questionnaire-next-question.html) invocation. Alternatively, any needed Libraries and ValueSets may manifest as \u0027contained\u0027 resources within the QuestionnaireResponse returned by [`$next-question`](http://hl7.org/fhir/uv/sdc/STU3/OperationDefinition-Questionnaire-next-question.html) based on which questions have been selected. (see [Adaptive Form Considerations](https://build.fhir.org/ig/HL7/davinci-dtr/specification.html#adaptive-form-considerations))\n\n* The `outcome` parameter is only present if the operation completes successfully with a 200 HTTP response code. In the event of an error, no Parameters response will be returned at all, though a bare `OperationOutcome` might be returned.\n\n* When DTR is launched from CRD the context is available in the `coverage-information` extension, but when launched from PAS the context is from the Task. \n\n#### Working with Multiple Forms\nWhen retrieving a Questionnaire Package, it\u0027s possible that a payer will have some sets of information they need to collect that is \u0027conditional\u0027. i.e., Depending on answers to initial questions, other sets of information may or may not need to be collected. Historically, this may have been handled as \u0027First, fill out Form A. Then, depending on the answers provided in Form A, there may be instructions to fill out Form B, C, and/or D\u0027. However, in the context of the Questionnaire Package operation, the expectation is that all forms returned by the $questionnaire-package operation are intended to be filled out, and they might be filled out in any order based on user preference. \n\nIf a payer is in a situation where they have historically had \u0027conditional\u0027 forms, there are two technical approaches that can be used to meet the requirement:\n\n1. Make use of adaptive forms and define a single adaptive form rooted in the questions from A that will subsequently ask questions from the internal forms B, C, and/or D as necessary, gathering all of the answers into a single Questionnaire Response.\n2. Make use of standard forms and combine forms A, B, C, and D into a single monolithic form that makes use of enableWhen logic to determine when the questions from the B, C, and/or D form sections are available/required to be completed. Note that it\u0027s possible for the CRD server to continue to maintain the separate individual forms and use a light-weight \u0027parent\u0027 form and SDC assembly or a similar mechanism to combine them all into a single Questionnaire before including it in the `$questionnaire-package` response.", "operationId": "op-questionnaire-package-Questionnaire", "responses": { "default": { "description": "Error, with details", "content": { "application/fhir+json": { "schema": { "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/OperationOutcome" } } } }, "200": { "description": "Operation response", "content": { "application/fhir+json": { "schema": { "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/Parameters" } } } } } } }, "/Questionnaire/$next-question": { "summary": "Operation $next-question on type Questionnaire", "description": "Operation $next-question on type Questionnaire", "get": { "summary": "$next-question on type Questionnaire", "description": "The Next Question operation is used for *adaptive questionnaires* - forms where the next question (or set of questions) is based on previous answers. The result of this operation is to return an updated QuestionnaireResponse with a contained Questionnaire that includes the next question (or set of questions). It might also include display items with instructions and/or read-only questions containing calculated scores. This operation uses the [QuestionnaireResponse](http://hl7.org/fhir/R4/questionnaireresponse.html) resource with a [*contained*](http://hl7.org/fhir/R4/references.html#contained) [Questionnaire](http://hl7.org/fhir/R4/questionnaire.html) as both the input and output parameter. The client initiates and queries for the next question by including the answers to all required questions in the questionnaire to that point. The Server updates the contained Questionnaire in the QuestionnaireResponse in the with the next question or set of questions and any needed instruction or score items. When the questionnaire is complete, the Server updates the `QuestionnaireResponse.status` resource parameter to `complete`. If completion of the questionnaire has exceeded any time limit, the Server may return an [OperationOutcome](http://hl7.org/fhir/R4/operationoutcome.html) with an error.", "operationId": "op-next-question-Questionnaire", "responses": { "default": { "description": "Error, with details", "content": { "application/fhir+json": { "schema": { "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/OperationOutcome" } } } }, "200": { "description": "Operation response", "content": { "application/fhir+json": { "schema": { "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/Parameters" } } } } } } }, "/Questionnaire/$log-questionnaire-errors": { "summary": "Operation $log-questionnaire-errors on type Questionnaire", "description": "Operation $log-questionnaire-errors on type Questionnaire", "get": { "summary": "$log-questionnaire-errors on type Questionnaire", "description": "§oper-1^dtr-client,dtr-server^exchange:This operation **SHALL** be supported by payers and DTR applications.§ It allows submission of issues encountered when working with these DTR-provided artifacts. The operation will pass the Questionnaire and an OperationOutcome detailing the issue(s) including where the error occurred. \n\n§oper-2^dtr-client^exchange:The input OperationOutcome resource **SHOULD** include information on the DTR application identity and version, date-time with time-zone offset, as well as the provider endpoint during which the error occurred, and it **SHALL NOT** contain information about the response or information retrieved from FHIR APIs that could potentially include PHI.§ §oper-3^dtr-client^exchange:The Questionnaire reference **SHOULD** be version-specific.§", "operationId": "op-log-questionnaire-errors-Questionnaire", "responses": { "default": { "description": "Error, with details", "content": { "application/fhir+json": { "schema": { "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/OperationOutcome" } } } }, "200": { "description": "Operation response", "content": { "application/fhir+json": { "schema": { "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/Parameters" } } } } } } }, "/ValueSet/$expand": { "summary": "Operation $expand on type ValueSet", "description": "Operation $expand on type ValueSet", "get": { "summary": "$expand on type ValueSet", "description": "The definition of a value set is used to create a simple collection of codes suitable for use for data entry or validation. \n\nIf the operation is not called at the instance level, one of the in parameters url, context or valueSet must be provided. An expanded value set will be returned, or an OperationOutcome with an error message.", "operationId": "op-expand-ValueSet", "responses": { "default": { "description": "Error, with details", "content": { "application/fhir+json": { "schema": { "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/OperationOutcome" } } } }, "200": { "description": "Operation response", "content": { "application/fhir+json": { "schema": { "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/Parameters" } } } } } } }, "/ValueSet/{rid}/$expand": { "summary": "Operation $expand on instance of ValueSet", "description": "Operation $expand on an instance of ValueSet", "get": { "summary": "$expand on ValueSet instance", "description": "The definition of a value set is used to create a simple collection of codes suitable for use for data entry or validation. \n\nIf the operation is not called at the instance level, one of the in parameters url, context or valueSet must be provided. An expanded value set will be returned, or an OperationOutcome with an error message.", "operationId": "op-expand-ValueSet-instance", "parameters": [ { "$ref": "#/components/parameters/rid" } ], "responses": { "default": { "description": "Error, with details", "content": { "application/fhir+json": { "schema": { "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/OperationOutcome" } } } }, "200": { "description": "Operation response", "content": { "application/fhir+json": { "schema": { "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/Parameters" } } } } } } } }, "components": { "parameters": { "rid": { "name": "rid", "in": "path", "description": "id of the resource (\u003dResource.id)", "required": true, "allowEmptyValue": false, "style": "simple", "schema": { "type": "string" } }, "hid": { "name": "hid", "in": "path", "description": "id of the history entry (\u003dResource.meta.versionId)", "required": true, "allowEmptyValue": false, "style": "simple", "schema": { "type": "string" } }, "summary": { "name": "_summary", "in": "query", "description": "Requests the server to return a designated subset of the resource", "allowEmptyValue": true, "style": "form", "schema": { "type": "string", "enum": [ "true", "text", "data", "count", "false" ] } }, "format": { "name": "_format", "in": "query", "description": "Specify alternative response formats by their MIME-types (when a client is unable acccess accept: header)", "allowEmptyValue": true, "style": "form", "schema": { "type": "string", "format": "mime-type" } }, "pretty": { "name": "_pretty", "in": "query", "description": "Ask for a pretty printed response for human convenience", "allowEmptyValue": true, "style": "form", "schema": { "type": "boolean" } }, "elements": { "name": "_elements", "in": "query", "description": "Requests the server to return a collection of elements from the resource", "allowEmptyValue": true, "style": "form", "explode": false, "schema": { "type": "array", "format": "string", "items": { "format": "string" } } }, "count": { "name": "_count", "in": "query", "description": "The maximum number of search results on a page. The server is not bound to return the number requested, but cannot return more", "schema": { "type": "number" } } } } }