Skip to content
This repository has been archived by the owner on May 7, 2024. It is now read-only.

Commit

Permalink
Updated DocumentReference DSTU2 Resource
Browse files Browse the repository at this point in the history 
- Backtick'd a lot of elements throughout the entire page, including some linked elements
- Overview paragraph updated
- Swapped position of the value field lists (CCD-specific section after the primary list)
- Move to single disclaimer + error + outcomes callout towards the top
  - Adjusted the Create section to account for the "additional" HTTP 422 outcome that can occur
- Implementation notes moved under parameters tables
- Parameter table + Implementation notes adjustments
  - Mostly the "search" area that needed attention
- Anonymized the x-ref ID for the Create response
  • Loading branch information
@kckeim
kckeim committed Oct 9, 2023
1 parent 161165c commit caaccea
Showing 1 changed file with 67 additions and 64 deletions.
131 changes: 67 additions & 64 deletions content/millennium/dstu2/infrastructure/document-reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,19 +9,10 @@ title: DocumentReference | DSTU 2 API

## Overview

The DocumentReference resource is used to reference a clinical document for a patient within the health system. This resource supports reading Continuity of Care Documents (CCD), returning a list of clinical documents, and a reference to retrieve a document as a PDF. Additionally, this resource supports writing an unstructured document. References to implicitRules, relatesTo, and modifierExtensions are NOT supported and will fail a create request.
The DocumentReference resource is used to reference a clinical document for a patient within the health system. This resource supports reading Continuity of Care Documents (CCD), returning a list of clinical documents, and a reference to retrieve a document as a PDF. When retrieving document links and metadata, this resource will refer to the [`Binary`] resource for downloading the complete document.

For fields supported on write, see the [create](#create) section.

The following fields are returned if valued for the docref operation (CCD read):

* [DocumentReference id](http://hl7.org/fhir/dstu2/resource-definitions.html#Resource.id){:target="_blank"}
* [Subject (patient)](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.subject){:target="_blank"}
* [Document type](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.type){:target="_blank"}
* [Index date/time (when document reference created)](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.indexed){:target="_blank"}
* [Status (current)](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.status){:target="_blank"}
* [Format](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.content.format){:target="_blank"}
* [ContentType and URL (fully qualified link to the Binary CCD)](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.content.attachment){:target="_blank"}
Additionally, this resource supports writing an unstructured document.
References to [`implicitRules`], [`modifierExtension`], and [`relatesTo`] are NOT supported and will fail a create request. For fields supported on write, see the [create](#create) section.

The following fields are returned if valued for clinical documents:

Expand All @@ -41,6 +32,23 @@ The following fields are returned if valued for clinical documents:
* [Title](https://hl7.org/fhir/dstu2/datatypes-definitions.html#Attachment.title){:target="_blank"}
* [Patient encounter](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.context.encounter){:target="_blank"}

The following fields are returned if valued for the $docref operation (CCD read):

* [DocumentReference id](http://hl7.org/fhir/dstu2/resource-definitions.html#Resource.id){:target="_blank"}
* [Subject (patient)](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.subject){:target="_blank"}
* [Document type](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.type){:target="_blank"}
* [Index date/time (when document reference created)](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.indexed){:target="_blank"}
* [Status (current)](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.status){:target="_blank"}
* [Format](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.content.format){:target="_blank"}
* [ContentType and URL (fully qualified link to the Binary CCD)](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.content.attachment){:target="_blank"}


<%= disclaimer %>

### Errors

The common [errors] and [OperationOutcomes] may be returned.

## Terminology Bindings

<%= terminology_table(:document_reference, :dstu2) %>
Expand All @@ -51,11 +59,6 @@ Search for DocumentReferences that meet supplied query parameters:

GET /DocumentReference?:parameters

_Implementation Notes_

* Search results are currently limited to published clinical documents.
* Contents of the document are found by following the Attachment URL. See more information on the [Binary resource] to determine what Authorization scopes are required, and how to set the Accept header when downloading document contents.

### Authorization Types

<%= authorization_types(provider: true, patient: true, system: true) %>
Expand All @@ -64,17 +67,27 @@ _Implementation Notes_

Name | Required? | Type | Description
-------------|----------------------------------------|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`_id` | This, or one of `patient` or `subject` | [`token`] | The logical resource id associated with the resource. Example: `_id=7891`
`patient` | This, or one of `_id` or `subject` | [`reference`] | The patient to which the document reference belongs. Example: `patient=12345`
`subject` | This, or one of `_id` or `patient` | [`reference`] | The subject of the document reference. Must represent a Patient resource. May use the :Patient modifier. Example: `subject=Patient/12345 or subject:Patient=12345`
`encounter` | No | [`reference`] | The encounter to which the document reference belongs. Must represent an Encounter resource. May include a single or comma separated list of references. Example: `encounter=4567`
`created` | No | [`date`] | A date/time the referenced document was created. Must use the `ge` and `le` prefixes. Example: `created=ge2017-01-07&created=le2017-02-05`
[`_count`] | No | [`number`] | The maximum number of results to return.
`_id` | This, or one of `patient` or `subject` | [`token`] | The logical resource id associated with the resource. Example: `12345`
`patient` | This, or one of `_id` or `subject` | [`reference`] | The patient to which the document reference belongs. Example: `12345`
`subject` | This, or one of `_id` or `patient` | [`reference`] | The subject of the document reference. May use the :Patient modifier. Example: `Patient/12345`
`encounter` | N | [`reference`] | The encounter to which the document reference belongs. Example: `12345`
`created` | N | [`date`] | A date/time the referenced document was created. Example: `created=ge2017-01-07&created=le2017-02-05`
[`_count`] | N | [`number`] | The maximum number of results to return. Defaults to `10` and a maximum of `100` documents can be returned.

Notes:
_Implementation Notes_

- The `_id` parameter may not be provided at the same time as the `patient`, `subject`, `encounter`, `created`, or `_count` parameters.
- When the `created` parameter is provided:
- Search results are currently limited to published clinical documents.
- Contents of the document are found by following the Attachment URL.
- See more information on the [`Binary`] resource to determine what Authorization scopes are required, and how to set the `Accept` header when downloading document contents.
- When searching with the `_id` parameter:
- It must not be provided with any other parameters.
- When searching with the `subject` parameter:
- It must appear once, and must represent a Patient resource.
- It can be provided either with or without the :Patient modifier. Example: `subject=Patient/12345` or `subject:Patient=12345`
- When searching with the `encounter` parameter:
- It must appear once, and must represent an Encounter resource.
- It can be provided with either a single references, or a comma-separated list of references. Example `encounter=1234` or `encounter=1234,5678`
- When searching with the `created` parameter:
- It must be provided twice, once with the `ge` parameter and once with the `le` parameter.
- The two provided date/times may not be equal and must form a closed range.
- If one `created` parameter includes a time, both must include a time.
Expand All @@ -94,12 +107,6 @@ Notes:
<%= headers status: 200 %>
<%= json(:dstu2_document_reference_docref_search) %>

<%= disclaimer %>

### Errors

The common [errors] and [OperationOutcomes] may be returned.

## Retrieve by id

List an individual DocumentReference by its id:
Expand All @@ -108,8 +115,11 @@ List an individual DocumentReference by its id:

_Implementation Notes_

* Contents of the document are found by following the Attachment URL. See more information on the [Binary resource] to determine what Authorization scopes are required, and how to set the Accept header when downloading document contents.
* If no mappings are available for LOINC codes when returning DocumentReference.type codings, an unknown data absent reason will be returned in place of the LOINC codes. This is to follow the [Argonaut profile's](http://www.fhir.org/guides/argonaut/r2/StructureDefinition-argo-documentreference.html) required binding for type. When available, Proprietary codings will be returned in addition to the data absent reason.
- Contents of the document are found by following the Attachment URL.
- See more information on the [`Binary`] resource to determine what Authorization scopes are required, and how to set the `Accept` header when downloading document contents.
- If no mappings are available for LOINC codes when returning `type` codings, an unknown data absent reason will be returned in place of the LOINC codes.
- This is to follow the [Argonaut profile's](http://www.fhir.org/guides/argonaut/r2/StructureDefinition-argo-documentreference.html) required binding for type.
- When available, Proprietary codings will be returned in addition to the data absent reason.

### Authorization Types

Expand All @@ -130,12 +140,6 @@ _Implementation Notes_
<%= headers status: 200 %>
<%= json(:dstu2_document_reference_docref_bundle_entry) %>

<%= disclaimer %>

### Errors

The common [errors] and [OperationOutcomes] may be returned.

## Create

Create new documents. Currently limited to unstructured clinical notes or documentation. For example, a document with display formatting or styling can be written, but a CCD cannot.
Expand All @@ -144,8 +148,9 @@ Create new documents. Currently limited to unstructured clinical notes or docume

_Implementation Notes_

* The modifier elements [implicitRules], [modifierExtension] and [relatesTo] are not supported and will be rejected if present.
* Currently only XHTML formatted documents are supported. You can validate your document using any available strict XHTML 1.0 validator (eg: [w3 validator] or this [html5 validator]).
- The modifier elements [`implicitRules`], [`modifierExtension`], and [`relatesTo`] are not supported and will be rejected if present.
- Currently only XHTML formatted documents are supported.
- You can validate your document using any available strict XHTML 1.0 validator (eg: [w3 validator] or this [html5 validator]).

### Authorization Types

Expand Down Expand Up @@ -189,29 +194,27 @@ strict-transport-security: max-age=631152000
vary: Origin,User-Agent,Accept-Encoding
x-content-type-options: nosniff
x-frame-options: SAMEORIGIN
x-request-id: 9c7510c0-0bb5-4148-b37e-51a774c4091b
x-request-id: 111111111111111111111111111111111111
x-xss-protection: 1; mode=block
</pre>

<%= disclaimer %>

### Errors

The common [errors] and [OperationOutcomes] may be returned. Additional [OperationOutcomes] may be returned in the following scenarios:
In addition to the common [OperationOutcomes], the following Outcome can be returned for this operation:

HTTP Status | Cause | Severity | Code
-------------|------------------------------------|-----------|---------------
422 | Body contained relatesTo | error | not-supported

## Operation: docref
## Operation: $docref

Argonaut operation for querying DocumentReferences for the supplied parameters:

GET /DocumentReference/$docref?:parameters

_Implementation Notes_

* The [DocumentReference.relatesTo] modifier element is not supported and will not be returned.
* The [`relatesTo`] modifier element is not supported and will not be returned.

### Authorization Types

Expand All @@ -226,14 +229,21 @@ _Implementation Notes_
Name | Required? | Type | Description
----------|-----------|---------------|-------------------------------------------------
`patient` | Y | [`reference`] | A reference to the patient whose document references are required. Example: `12345`
`type` | Y | [`token`] | The document reference type, can be a list of comma separated values. Example: `http://loinc.org|34133-9`
`start` | N | [`date`] | The start of the date range from which document reference records should be included. If not provided, then all records from the beginning of time are included. Example: `2014-09-24T12:00:00.000Z`
`end` | N | [`date`] | The end of the date range till which document reference records should be included. If not provided, then all records up to the current date are included. Example: `2016-09-24T12:00:00.000Z`
`type` | Y | [`token`] | The document reference type. Example: `http://loinc.org\|34133-9`
`start` | N | [`date`] | The start of the date range from which document reference records should be included. Example: `2014-09-24T12:00:00.000Z`
`end` | N | [`date`] | The end of the date range till which document reference records should be included. Example: `2016-09-24T12:00:00.000Z`

Notes:

- The `type` parameter must include both a system and a code. (e.g. `&type=http://loinc.org|34133-9`)
- The `start` and `end` parameters must be valid [dateTime]s with a time component. They must have prefixes of `eq` or nothing.
- The `type` parameter:
- It must include both a system and a code. (e.g. `&type=http://loinc.org\|34133-9`)
- It may be a single system and code, or a comma-separated list.
- The `start` and `end` parameters:
- They must be valid [dateTime]s with a time component.
- They must have prefixes of `eq` or nothing.
- If `start` is not provided, then all records from the beginning of time are included.
- If `end` is not provided, then all records up to the current date are included.


### Headers

Expand All @@ -250,15 +260,9 @@ Notes:
<%= headers status: 200 %>
<%= json(:dstu2_document_reference_docref_bundle) %>

<%= disclaimer %>

### Errors

The common [errors] and [OperationOutcomes] may be returned.

[implicitRules]: http://hl7.org/fhir/DSTU2/resource-definitions.html#Resource.implicitRules
[modifierExtension]: http://hl7.org/fhir/DSTU2/domainresource-definitions.html#DomainResource.modifierExtension
[relatesTo]: http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.relatesTo
[`implicitRules`]: http://hl7.org/fhir/DSTU2/resource-definitions.html#Resource.implicitRules
[`modifierExtension`]: http://hl7.org/fhir/DSTU2/domainresource-definitions.html#DomainResource.modifierExtension
[`relatesTo`]: http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.relatesTo
[html5 validator]: https://html5.validator.nu/
[w3 validator]: http://validator.w3.org/#validate_by_upload+with_options
[`reference`]: http://hl7.org/fhir/DSTU2/search.html#reference
Expand All @@ -267,7 +271,6 @@ The common [errors] and [OperationOutcomes] may be returned.
[`number`]: http://hl7.org/fhir/dstu2/search.html#number
[`date`]: http://hl7.org/fhir/DSTU2/search.html#date
[dateTime]: http://hl7.org/fhir/DSTU2/datatypes.html#dateTime
[DocumentReference.relatesTo]: http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.relatesTo
[errors]: ../../#client-errors
[Binary resource]: ../binary/#authorization-types
[`Binary`]: ../binary/#authorization-types
[OperationOutcomes]: ../../#operation-outcomes

0 comments on commit caaccea

Please sign in to comment.