FHIR Release 3 (STU) Current Build

2.44 2.45 Resource OperationOutcome - Content

FHIR Infrastructure Work Group Maturity Level : 5   Trial Use Normative Compartments : Not linked to any defined compartments

Normative Candidate Note: This page is candidate normative content for R4 in the Infrastructure Package . Once normative, it will lose it's Maturity Level, and breaking changes will no longer be made.

A collection of error, warning warning, or information messages that result from a system action.

Operation outcomes are sets of error, warning and information messages that provide detailed information about the outcome of an attempted system operation. They are provided as a direct system response response, or component of one one, and provide information about the outcome of the operation.

The OperationOutcome resource is used in the following circumstances:

  • When an RESTful operation fails
  • As the response on a validation operation to provide information about the outcome
  • As part of a message response, usually when the message has not been processed correctly
  • As the response to a batch/transaction, when requested
  • As part of a search's Bundle response containing information about the search

This resource is referenced by GuidanceResponse and MessageHeader . The reference from GuidanceResponse indicates that there is an additional use context that needs to be addressed in the scope.

This resource is not used for reporting clinical or workflow issues associated with a proposed or ongoing action; these would be handled using DetectedIssue or other resources. The resource is not designed to be persisted or referenced from other parts of the workflow.

It is possible to have both OperationOutcome and DetectedIssue together, where the OperationOutcome might indicate that a requested action was rejected due to a clinical issue and the DetectedIssue provides the details of the issue.

This resource is referenced by GuidanceResponse and MessageHeader

Structure

Name Flags Card. Type Description & Constraints doco
. . OperationOutcome Σ N DomainResource Information about the success/failure of an action
Elements defined in Ancestors: id , meta , implicitRules , language , text , contained , extension , modifierExtension
. . . issue Σ 1..* BackboneElement A single issue associated with the action
. . . . severity ?! Σ 1..1 code fatal | error | warning | information
IssueSeverity ( Required )
. . . . code Σ 1..1 code Error or warning code
IssueType ( Required )
. . . . details Σ 0..1 CodeableConcept Additional details about the error
Operation Outcome Codes ( Example )
. . . . diagnostics Σ 0..1 string Additional diagnostic information about the issue
. . . . location Σ XD 0..* string Deprecated: Path of element(s) related to issue
. . . . expression Σ 0..* string FHIRPath of element(s) related to issue

doco Documentation for this format

UML Diagram ( Legend )

OperationOutcome ( DomainResource ) Issue Indicates whether the issue indicates a variation from successful processing (this element modifies the meaning of other elements) severity : code [1..1] « How the issue affects the success of the action. (Strength=Required) IssueSeverity ! » Describes the type of the issue. The system that creates an OperationOutcome SHALL choose the most applicable code from the IssueType value set, and may additional provide its own code for the error in the details element code : code [1..1] « A code that describes the type of issue. (Strength=Required) IssueType ! » Additional details about the error. This may be a text description of the error, error or a system code that identifies the error details : CodeableConcept [0..1] « A code that provides details as the exact issue. (Strength=Example) Operation Outcome OperationOutcomeCodes ?? » Additional diagnostic information about the issue. Typically, this may be a description of how a value is erroneous, or a stack dump to help trace the issue diagnostics : string [0..1] This element is deprecated because it is XML specific. It is replaced by issue.expression, which is format independent, and simpler to parse. For resource issues, this will be a simple XPath limited to element names, repetition indicators and the default child access accessor that identifies one of the elements in the resource that caused this issue to be raised. For HTTP errors, will be "http." + the parameter name location : string [0..*] A simple FHIRPath [simple subset of FHIRPath](fhirpath.html#simple) limited to element names, repetition indicators and the default child access accessor that identifies one of the elements in the resource that caused this issue to be raised expression : string [0..*] An error, warning warning, or information message that results from a system action issue [1..*]

XML Template

<OperationOutcome xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <
  <

 <issue>  <!-- 1..* A single issue associated with the action -->
  <severity value="[code]"/><!-- 1..1 fatal | error | warning | information -->

  <code value="[code]"/><!-- 1..1 Error or warning code -->
  <</details>

  <details><!-- 0..1 CodeableConcept Additional details about the error --></details>

  <diagnostics value="[string]"/><!-- 0..1 Additional diagnostic information about the issue -->
  <
  <

  <location value="[string]"/><!-- 0..* Deprecated: Path of element(s) related to issue -->
  <expression value="[string]"/><!-- 0..* FHIRPath of element(s) related to issue -->

 </issue>
</OperationOutcome>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .doco
[ a fhir:;

[ a fhir:OperationOutcome;

  fhir:nodeRole fhir:treeRoot; # if this is the parser root
  # from Resource: .id, .meta, .implicitRules, and .language
  # from DomainResource: .text, .contained, .extension, and .modifierExtension
  fhir:
    fhir:

  fhir:OperationOutcome.issue [ # 1..* A single issue associated with the action
    fhir:OperationOutcome.issue.severity [ code ]; # 1..1 fatal | error | warning | information

    fhir:OperationOutcome.issue.code [ code ]; # 1..1 Error or warning code
    fhir:

    fhir:OperationOutcome.issue.details [ CodeableConcept ]; # 0..1 Additional details about the error

    fhir:OperationOutcome.issue.diagnostics [ string ]; # 0..1 Additional diagnostic information about the issue
    fhir:
    fhir:

    fhir:OperationOutcome.issue.location [ string ], ... ; # 0..* Deprecated: Path of element(s) related to issue
    fhir:OperationOutcome.issue.expression [ string ], ... ; # 0..* FHIRPath of element(s) related to issue

  ], ...;
]

Changes since DSTU2 R3

OperationOutcome
OperationOutcome.issue.expression OperationOutcome.issue.severity
  • Added Element No longer marked as Modifier

See the Full Difference for further information

This analysis is available as XML or JSON .

See R2 <--> R3 <--> R4 Conversion Maps (status = 6 tests that all execute ok. All tests pass round-trip testing and all r3 resources are valid.). valid.)

Structure

Name Flags Card. Type Description & Constraints doco
. . OperationOutcome Σ N DomainResource Information about the success/failure of an action
Elements defined in Ancestors: id , meta , implicitRules , language , text , contained , extension , modifierExtension
. . . issue Σ 1..* BackboneElement A single issue associated with the action
. . . . severity ?! Σ 1..1 code fatal | error | warning | information
IssueSeverity ( Required )
. . . . code Σ 1..1 code Error or warning code
IssueType ( Required )
. . . . details Σ 0..1 CodeableConcept Additional details about the error
Operation Outcome Codes ( Example )
. . . . diagnostics Σ 0..1 string Additional diagnostic information about the issue
. . . . location Σ XD 0..* string Deprecated: Path of element(s) related to issue
. . . . expression Σ 0..* string FHIRPath of element(s) related to issue

doco Documentation for this format

UML Diagram ( Legend )

OperationOutcome ( DomainResource ) Issue Indicates whether the issue indicates a variation from successful processing (this element modifies the meaning of other elements) severity : code [1..1] « How the issue affects the success of the action. (Strength=Required) IssueSeverity ! » Describes the type of the issue. The system that creates an OperationOutcome SHALL choose the most applicable code from the IssueType value set, and may additional provide its own code for the error in the details element code : code [1..1] « A code that describes the type of issue. (Strength=Required) IssueType ! » Additional details about the error. This may be a text description of the error, error or a system code that identifies the error details : CodeableConcept [0..1] « A code that provides details as the exact issue. (Strength=Example) Operation Outcome OperationOutcomeCodes ?? » Additional diagnostic information about the issue. Typically, this may be a description of how a value is erroneous, or a stack dump to help trace the issue diagnostics : string [0..1] This element is deprecated because it is XML specific. It is replaced by issue.expression, which is format independent, and simpler to parse. For resource issues, this will be a simple XPath limited to element names, repetition indicators and the default child access accessor that identifies one of the elements in the resource that caused this issue to be raised. For HTTP errors, will be "http." + the parameter name location : string [0..*] A simple FHIRPath [simple subset of FHIRPath](fhirpath.html#simple) limited to element names, repetition indicators and the default child access accessor that identifies one of the elements in the resource that caused this issue to be raised expression : string [0..*] An error, warning warning, or information message that results from a system action issue [1..*]

XML Template

<OperationOutcome xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <
  <

 <issue>  <!-- 1..* A single issue associated with the action -->
  <severity value="[code]"/><!-- 1..1 fatal | error | warning | information -->

  <code value="[code]"/><!-- 1..1 Error or warning code -->
  <</details>

  <details><!-- 0..1 CodeableConcept Additional details about the error --></details>

  <diagnostics value="[string]"/><!-- 0..1 Additional diagnostic information about the issue -->
  <
  <

  <location value="[string]"/><!-- 0..* Deprecated: Path of element(s) related to issue -->
  <expression value="[string]"/><!-- 0..* FHIRPath of element(s) related to issue -->

 </issue>
</OperationOutcome>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .doco
[ a fhir:;

[ a fhir:OperationOutcome;

  fhir:nodeRole fhir:treeRoot; # if this is the parser root
  # from Resource: .id, .meta, .implicitRules, and .language
  # from DomainResource: .text, .contained, .extension, and .modifierExtension
  fhir:
    fhir:

  fhir:OperationOutcome.issue [ # 1..* A single issue associated with the action
    fhir:OperationOutcome.issue.severity [ code ]; # 1..1 fatal | error | warning | information

    fhir:OperationOutcome.issue.code [ code ]; # 1..1 Error or warning code
    fhir:

    fhir:OperationOutcome.issue.details [ CodeableConcept ]; # 0..1 Additional details about the error

    fhir:OperationOutcome.issue.diagnostics [ string ]; # 0..1 Additional diagnostic information about the issue
    fhir:
    fhir:

    fhir:OperationOutcome.issue.location [ string ], ... ; # 0..* Deprecated: Path of element(s) related to issue
    fhir:OperationOutcome.issue.expression [ string ], ... ; # 0..* FHIRPath of element(s) related to issue

  ], ...;
]

Changes since DSTU2 Release 3

OperationOutcome
OperationOutcome.issue.expression OperationOutcome.issue.severity
  • Added Element No longer marked as Modifier

See the Full Difference for further information

This analysis is available as XML or JSON .

See R2 <--> R3 <--> R4 Conversion Maps (status = 6 tests that all execute ok. All tests pass round-trip testing and all r3 resources are valid.). valid.)

 

Alternate See the Profiles & Extensions and the alternate definitions: Master Definition ( XML , + JSON ), , XML Schema / Schematron (for ) + JSON Schema , ShEx (for Turtle ) + see the extensions & the dependency analysis

Path Definition Type Reference
OperationOutcome.issue.severity How the issue affects the success of the action. Required IssueSeverity
OperationOutcome.issue.code A code that describes the type of issue. Required IssueType
OperationOutcome.issue.details A code that provides details as the exact issue. Example Operation Outcome Codes OperationOutcomeCodes

On the RESTful interface, operation outcome resources are only relevant when a level of computable detail is required that is more granular than that provided by the HTTP response codes. This granularity could include:

  • more detail about the location of an issue
  • the ability to identify multiple distinct issues
  • provision of finer error codes that connect to known business failure states

Operation outcomes returned SHOULD be in alignment with the HTTP response code. For example, if the HTTP code indicates a failure (300+), at least one of the issues should have a severity of "error", indicating the reason for the failure.

Operation outcomes must include at least one issue. See the All OK example for a template for an operation that returns no errors.

Each issue in an operation outcome may SHOUD have an expression that reports a location reported. Systems that create operation outcomes SHOULD populate for the location of an error. issue. A correctly propulated location populated expression can allow client systems to:

  • Connect return errors with the appropriate UI widget
  • Route errors to the corect correct application or system log
  • Develop more intelligent testing applications

In order to support these kinds of usages, this applications need to use the location expression element consistently. Applications can use the location expression element to refer to a location inside a resource, or some location in the HTTP request (when appropriate).

2.44.5.1 Reporting Errors in Resources

While resources may be represented in XML, JSON, or other forms, error Error locations are always reported using a simplified XPath notation: <location value="/f:Patient/f:identifier"/> The XPath must use the FHIR standard XPath prefixes f: and h: FHIRPath for the FHIR and XHTML namespaces respectively. The XPath here can be used to automatically find the relevant XML element in a resource if the resource is represented in XML. Because resources are often represented statement in JSON, and because applications will often process the XPath directly (e.g. expression element. In addition to determine the relevant widget), the XPath statement must be simple. Specifically, simplified FHIRPath restrictions, the XPath expression SHALL only not contain element names and repetition indicators. So this is a .resolve() function. These examples are legal:

<location value="/f:Patient/f:identifier[2]/f:label"/>
 <expression value="Patient.identifier"/>
  "expression" : "Patient.identifier[2].value"

but this is not:

<location value="/f:Patient/f:identifier[f:system/@value='http://example.com/mrn']/f:label"/>
  "expression" : "Patient.identifier.where(system.value='http://example.com/mrn').value"
Because the Xpath is required to be simple, it can be converted to JsonPointer by dropping the namespace prefixes, and correcting for array offsets. The XPaths above have these equivalent JsonPointer representations: Patient/identifier Patient/identifier/2/label Note that correcting for array offsets may require knowledge of which elements are Arrays in JSON. It is also possible to convert the XPath statements to JsonPath, though there is no single standard for JsonPath.

Servers may also need to report errors in the HTTP headers - especially query parameters when processing searches. Errors are reported using a case sensitive location expression that has two parts, a fixed "http" and the header or query parameter name separated by a ".". Some examples:

Location Expresson Description
http.name:exact http.code A reference to the search parameter "code"
http."name:exact" A reference to the search parameter "name" with the modifier ":exact"
http.Authorization A reference to the Authorization header - perhaps to indicate that it is missing, and some form of authentication is required.

This specification follows the convention that HTTP headers start with an uppercase character, and URL parameters start with a lowercase character. Implementations are encouraged to follow this convention, so that no name collisions occur.