Release 4 FHIR CI-Build

This page is part of the Continuous Integration Build of FHIR Specification (v4.0.1: R4 - Mixed Normative and STU ) in it's permanent home (it will always (will be available incorrect/inconsistent at this URL). The current version which supercedes this version is 5.0.0 . For a full list of available versions, see times).
See the Directory of published versions icon . Page versions: R5 R4B R4 R3 R2

2.44 2.10 Resource OperationOutcome - Content

Responsible Owner: FHIR Infrastructure icon Work Group Maturity Level : N   Normative (from v4.0.0) Security Category : Anonymous Compartments : Not linked to any No defined compartments
This page has been approved as part of an ANSI standard. See the Infrastructure Package for further details.

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

2.44.1 2.10.1 Scope and Usage

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, or component of one, and provide information about the outcome of the operation.

The OperationOutcome resource is used in the following circumstances:

  • When a RESTful interaction or 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

2.44.2 2.10.2 Boundaries and Relationships

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. OperationOutcome 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

2.10.3 References to this Resource

2.44.3 2.10.4 Resource Content

Structure

Name Flags Card. Type Description & Constraints      Filter: Filters 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 | success
IssueSeverity Binding: Issue Severity ( Required )
. . . . code Σ 1..1 code Error or warning code
IssueType Binding: Issue Type ( Required )
. . . . details Σ 0..1 CodeableConcept Additional details about the error
Operation Binding: Example Audit Event Outcome Codes Detail ( 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 icon

See the Extensions for this resource

UML Diagram ( Legend )

OperationOutcome ( DomainResource ) Issue Indicates whether the issue indicates a variation from successful processing severity : code [1..1] « How the issue affects the success of the action. null (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. null (Strength=Required) IssueType ! » Additional details about the error. This may be a text description of the error or a system code that identifies the error details : CodeableConcept [0..1] « A code that provides details as the exact issue. null (Strength=Example) OperationOutcomeCodes AuditEventOutcomeDetailExample ?? » Additional diagnostic information about 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 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 subset of FHIRPath](fhirpath.html#simple) limited to element names, repetition indicators and the default child accessor that identifies one of the elements in the resource that caused this issue to be raised expression : string [0..*] An error, 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 | success -->

  <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 -->
  <<a href="operationoutcome-definitions.html#OperationOutcome.issue.location" title="This element is deprecated because it is XML specific. It is replaced by issue.expression, which is format independent, and simpler to parse. 


  <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>

JSON Template 

{doco
  "resourceType" : "OperationOutcome",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "issue" : [{ // R!  A single issue associated with the action
    "

    "severity" : "<code>", // R!  fatal | error | warning | information | success

    "code" : "<code>", // R!  Error or warning code
    "

    "details" : { CodeableConcept }, // Additional details about the error

    "diagnostics" : "<string>", // Additional diagnostic information about the issue
    "<a href="operationoutcome-definitions.html#OperationOutcome.issue.location" title="This element is deprecated because it is XML specific. It is replaced by issue.expression, which is format independent, and simpler to parse. 


    "location" : ["<string>"], // Deprecated: Path of element(s) related to issue
    "expression" : ["<string>"] // FHIRPath of element(s) related to issue
  }]
}

Turtle Template 

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


[ a fhir:OperationOutcome;
  fhir:nodeRole fhir:treeRoot; # if this is the parser root

  # from 
  # from 
  fhir:
    fhir:
    fhir:
    fhir:
    fhir:
    fhir:<a href="operationoutcome-definitions.html#OperationOutcome.issue.location" title="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 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." class="dict">OperationOutcome.issue.location
    fhir:
  ], ...;

  # from Resource: fhir:id, fhir:meta, fhir:implicitRules, and fhir:language
  # from DomainResource: fhir:text, fhir:contained, fhir:extension, and fhir:modifierExtension
  fhir:issue ( [ # 1..* A single issue associated with the action
    fhir:severity [ code ] ; # 1..1 fatal | error | warning | information | success
    fhir:code [ code ] ; # 1..1 Error or warning code
    fhir:details [ CodeableConcept ] ; # 0..1 Additional details about the error
    fhir:diagnostics [ string ] ; # 0..1 Additional diagnostic information about the issue
    fhir:location  ( [ string ] ... ) ; # 0..* Deprecated: Path of element(s) related to issue
    fhir:expression  ( [ string ] ... ) ; # 0..* FHIRPath of element(s) related to issue
  ] ... ) ;

]

Changes since R3 from both R4 and R4B

OperationOutcome
OperationOutcome.issue.severity
  • Change value set from http://hl7.org/fhir/ValueSet/issue-severity to http://hl7.org/fhir/ValueSet/issue-severity|4.0.1 No longer marked as Modifier Add code success
OperationOutcome.issue.code
  • Change Remove codes structure , required , value set from http://hl7.org/fhir/ValueSet/issue-type to http://hl7.org/fhir/ValueSet/issue-type|4.0.1 , invariant , login , unknown , expired , forbidden , suppressed , not-supported , duplicate , multiple-matches , not-found , deleted , too-long , code-invalid , extension , too-costly , business-rule , conflict , lock-error , no-store , exception , timeout , incomplete , throttled
  • Add code success

See the Full Difference for further information

This analysis is available for R4 as XML or JSON . See R3 <--> R4 Conversion Maps (status = 6 tests that all execute ok. All tests pass round-trip testing and all r3 resources are valid.) for R4B as XML or JSON .

Structure

Name Flags Card. Type Description & Constraints      Filter: Filters 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 | success
IssueSeverity Binding: Issue Severity ( Required )
. . . . code Σ 1..1 code Error or warning code
IssueType Binding: Issue Type ( Required )
. . . . details Σ 0..1 CodeableConcept Additional details about the error
Operation Binding: Example Audit Event Outcome Codes Detail ( 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 icon

See the Extensions for this resource

UML Diagram ( Legend )

OperationOutcome ( DomainResource ) Issue Indicates whether the issue indicates a variation from successful processing severity : code [1..1] « How the issue affects the success of the action. null (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. null (Strength=Required) IssueType ! » Additional details about the error. This may be a text description of the error or a system code that identifies the error details : CodeableConcept [0..1] « A code that provides details as the exact issue. null (Strength=Example) OperationOutcomeCodes AuditEventOutcomeDetailExample ?? » Additional diagnostic information about 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 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 subset of FHIRPath](fhirpath.html#simple) limited to element names, repetition indicators and the default child accessor that identifies one of the elements in the resource that caused this issue to be raised expression : string [0..*] An error, 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 | success -->

  <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 -->
  <<a href="operationoutcome-definitions.html#OperationOutcome.issue.location" title="This element is deprecated because it is XML specific. It is replaced by issue.expression, which is format independent, and simpler to parse. 


  <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>

JSON Template 

{doco
  "resourceType" : "OperationOutcome",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "issue" : [{ // R!  A single issue associated with the action
    "

    "severity" : "<code>", // R!  fatal | error | warning | information | success

    "code" : "<code>", // R!  Error or warning code
    "

    "details" : { CodeableConcept }, // Additional details about the error

    "diagnostics" : "<string>", // Additional diagnostic information about the issue
    "<a href="operationoutcome-definitions.html#OperationOutcome.issue.location" title="This element is deprecated because it is XML specific. It is replaced by issue.expression, which is format independent, and simpler to parse. 


    "location" : ["<string>"], // Deprecated: Path of element(s) related to issue
    "expression" : ["<string>"] // FHIRPath of element(s) related to issue
  }]
}

Turtle Template 

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


[ a fhir:OperationOutcome;
  fhir:nodeRole fhir:treeRoot; # if this is the parser root

  # from 
  # from 
  fhir:
    fhir:
    fhir:
    fhir:
    fhir:
    fhir:<a href="operationoutcome-definitions.html#OperationOutcome.issue.location" title="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 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." class="dict">OperationOutcome.issue.location
    fhir:
  ], ...;

  # from Resource: fhir:id, fhir:meta, fhir:implicitRules, and fhir:language
  # from DomainResource: fhir:text, fhir:contained, fhir:extension, and fhir:modifierExtension
  fhir:issue ( [ # 1..* A single issue associated with the action
    fhir:severity [ code ] ; # 1..1 fatal | error | warning | information | success
    fhir:code [ code ] ; # 1..1 Error or warning code
    fhir:details [ CodeableConcept ] ; # 0..1 Additional details about the error
    fhir:diagnostics [ string ] ; # 0..1 Additional diagnostic information about the issue
    fhir:location  ( [ string ] ... ) ; # 0..* Deprecated: Path of element(s) related to issue
    fhir:expression  ( [ string ] ... ) ; # 0..* FHIRPath of element(s) related to issue
  ] ... ) ;

]

Changes since Release 3 from both R4 and R4B

OperationOutcome
OperationOutcome.issue.severity
  • Change value set from http://hl7.org/fhir/ValueSet/issue-severity to http://hl7.org/fhir/ValueSet/issue-severity|4.0.1 No longer marked as Modifier Add code success
OperationOutcome.issue.code
  • Change Remove codes structure , required , value set from http://hl7.org/fhir/ValueSet/issue-type to http://hl7.org/fhir/ValueSet/issue-type|4.0.1 , invariant , login , unknown , expired , forbidden , suppressed , not-supported , duplicate , multiple-matches , not-found , deleted , too-long , code-invalid , extension , too-costly , business-rule , conflict , lock-error , no-store , exception , timeout , incomplete , throttled
  • Add code success

See the Full Difference for further information

This analysis is available for R4 as XML or JSON . See R3 <--> R4 Conversion Maps (status = 6 tests that all execute ok. All tests pass round-trip testing and all r3 resources are valid.) for R4B as XML or JSON .

 

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

2.44.3.1 2.10.4.1 Terminology Bindings

Path Definition ValueSet Type Reference Documentation
OperationOutcome.issue.severity IssueSeverity Required

How the issue affects the success of the action.

OperationOutcome.issue.code IssueType Required IssueSeverity OperationOutcome.issue.code

A code that describes the type of issue. Required IssueType

OperationOutcome.issue.details A AuditEventOutcomeDetailExample (a valid code that provides details as the exact issue. from Operation Outcome Codes icon ) Example OperationOutcomeCodes

Example values to indicate more detailed reason for outcome.

2.44.4 2.10.5 Using Operation Outcome Resources

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.

2.44.5 2.10.6 Using the Expression

Each issue in an operation outcome SHOUD SHOULD have an expression that reports a location for the issue. A correctly populated expression can allow client systems to:

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

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

Error locations are always reported using a simplified FHIRPath statement in the expression element. In addition to the simplified FHIRPath restrictions, the expression SHALL not NOT contain a .resolve() function. These examples are legal: 

 <expression value="Patient.identifier"/>

  "expression" : "Patient.identifier[2].value"

but this is not: 

  "expression" : "Patient.identifier.where(system.value='http://example.com/mrn').value"

2.44.5.1 2.10.6.1 Reporting Errors in the HTTP Headers

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

Expresson Description
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.

2.10.7 Search Parameters

Search parameters for this resource. See also the full list of search parameters for this resource , and check the Extensions registry for search parameters on extensions related to this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

(No search parameters for this resource)