R5 Final QA

This page is part of the FHIR Specification (v5.0.0-draft-final: Final QA Preview for R5 - see ballot notes). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4

2.1.27.5.7.5 Operation $convert on Resource

FHIR Infrastructure icon Work Group Maturity Level: 1Draft Compartments: N/A

This operation takes a resource in one form, and returns to in another form. Both the resource and return parameters are a single resource. The primary use of this operation is to convert between formats (e.g. (XML -> JSON or vice versa).

The canonical URL for this operation definition is

 http://hl7.org/fhir/OperationDefinition/Resource-convert

Formal Definition (as a OperationDefinition).

URL: [base]/$convert

This is an idempotent operation

In Parameters:
NameScopeCardinalityTypeBindingProfileDocumentation
resource1..1Resource

The resource that is to be converted

Out Parameters:
NameScopeCardinalityTypeBindingProfileDocumentation
return1..1Resource

The resource after conversion

Note: as this is the only out parameter, it is a resource, and it has the name 'return', the result of this operation is returned directly as a resource

While the primary use of this operation is simple - converting a resource from one format to another, there are many potential uses including:

  • converting resources from one version to another
  • restructuring information in a resource (e.g. moving method into/out of Observation.code)
  • extracting data from a questionnaire
  • converting CDA documents or v2 messages (as a binary resource) to a bundle (or vice versa) (or even openEHR or openMHealth).

These variants would all be associated with parameters that define and control these kind of conversions, though such parameters are not defined at this time. In the absence of any parameters, simple format conversion is all that will occur.

For this reason, implementers should be aware that:

  • the return resource type may be different from the resource parameter resource type (for example, it might be a bundle)
  • binary resources may be represented directly using some other content-type (in other words, just post the content directly)

Implementers are encouraged to provide feedback to HL7 about their use of this operation

2.1.27.5.7.5.1 Examples

Request: #1: Convert a Patient from XML to JSON


POST /base/$convert
Accept: application/fhir+json
Content-Type: application/fhir+xml
[other headers]

<?xml version="1.0" encoding="UTF-8"?>
<Patient xmlns="http://hl7.org/fhir">
	<id value="example"/>
	<!--  MRN assigned by ACME healthcare on 6-May 2001  -->
	<identifier>
		<use value="usual"/>
		<type>
			<coding>
				<system value="http://terminology.hl7.org/CodeSystem/v2-0203"/>
				<code value="MR"/>
			</coding>
		</type>
		<system value="urn:oid:1.2.36.146.595.217.0.1"/>
		<value value="12345"/>
		<period>
			<start value="2001-05-06"/>
		</period>
		<assigner>
			<display value="Acme Healthcare"/>
		</assigner>
	</identifier>
	<active value="true"/>
	<!--  Peter James Chalmers, but called "Jim"  -->
	<name>
		<use value="official"/>
		<family value="Chalmers"/>
		<given value="Peter"/>
		<given value="James"/>
	</name>
	<name>
		<use value="usual"/>
		<given value="Jim"/>
	</name>
	<name>
    <!-- Maiden names apply for anyone whose name changes as a result of marriage - irrespective of gender -->
    <use value="maiden"/>
    <family value="Windsor"/>
		<given value="Peter"/>
		<given value="James"/>
    <period>
      <end value="2002"/>
    </period>
	</name>
	<telecom>
		<use value="home"/>
		<!--  home communication details aren't known  -->
	</telecom>
	<telecom>
		<system value="phone"/>
		<value value="(03) 5555 6473"/>
		<use value="work"/>
		<rank value="1"/>
	</telecom>
	<telecom>
		<system value="phone"/>
		<value value="(03) 3410 5613"/>
		<use value="mobile"/>
		<rank value="2"/>
	</telecom>
	<telecom>
		<system value="phone"/>
		<value value="(03) 5555 8834"/>
		<use value="old"/>
		<period>
      <end value="2014"/>
		</period>
	</telecom>
	<!--  use FHIR code system for male / female  -->
	<gender value="male"/>
	<birthDate value="1974-12-25">
		<extension url="http://hl7.org/fhir/StructureDefinition/patient-birthTime">
			<valueDateTime value="1974-12-25T14:35:45-05:00"/>
		</extension>
	</birthDate>
	<deceasedBoolean value="false"/>
	<address>
		<use value="home"/>
		<type value="both"/>
		<text value="534 Erewhon St
PeasantVille, Rainbow, Vic  3999"/>
		<line value="534 Erewhon St"/>
		<city value="PleasantVille"/>
		<district value="Rainbow"/>
		<state value="Vic"/>
		<postalCode value="3999"/>
		<period>
			<start value="1974-12-25"/>
		</period>
	</address>
	<contact>
		<relationship>
			<coding>
				<system value="http://terminology.hl7.org/CodeSystem/v2-0131"/>
				<code value="N"/>
			</coding>
		</relationship>
		<name>
			<family value="du Marché">
				<!--  the "du" part is a family name prefix (VV in iso 21090)  -->
				<extension url="http://hl7.org/fhir/StructureDefinition/humanname-own-prefix">
					<valueString value="VV"/>
				</extension>
			</family>
			<given value="Bénédicte"/>
		</name>
		<telecom>
			<system value="phone"/>
			<value value="+33 (237) 998327"/>
		</telecom>
		<address>
			<use value="home"/>
			<type value="both"/>
			<line value="534 Erewhon St"/>
			<city value="PleasantVille"/>
			<district value="Rainbow"/>
			<state value="Vic"/>
			<postalCode value="3999"/>
			<period>
				<start value="1974-12-25"/>
			</period>
		</address>
		<gender value="female"/>
		<period>
			<!--  The contact relationship started in 2012  -->
			<start value="2012"/>
		</period>
	</contact>
	<managingOrganization>
		<reference value="Organization/1"/>
	</managingOrganization>
</Patient>

Response to request: #1: return the JSON format


HTTP/1.1 200 OK
Content-Type: application/fhir+json
[other headers]

{
  "resourceType" : "Patient",
  "id" : "example",
  "identifier" : [{
    "use" : "usual",
    "type" : {
      "coding" : [{
        "system" : "http://terminology.hl7.org/CodeSystem/v2-0203",
        "code" : "MR"
      }]
    },
    "system" : "urn:oid:1.2.36.146.595.217.0.1",
    "value" : "12345",
    "period" : {
      "start" : "2001-05-06"
    },
    "assigner" : {
      "display" : "Acme Healthcare"
    }
  }],
  "active" : true,
  "name" : [{
    "use" : "official",
    "family" : "Chalmers",
    "given" : ["Peter",
    "James"]
  },
  {
    "use" : "usual",
    "given" : ["Jim"]
  },
  {
    "use" : "maiden",
    "family" : "Windsor",
    "given" : ["Peter",
    "James"],
    "period" : {
      "end" : "2002"
    }
  }],
  "telecom" : [{
    "use" : "home"
  },
  {
    "system" : "phone",
    "value" : "(03) 5555 6473",
    "use" : "work",
    "rank" : 1
  },
  {
    "system" : "phone",
    "value" : "(03) 3410 5613",
    "use" : "mobile",
    "rank" : 2
  },
  {
    "system" : "phone",
    "value" : "(03) 5555 8834",
    "use" : "old",
    "period" : {
      "end" : "2014"
    }
  }],
  "gender" : "male",
  "birthDate" : "1974-12-25",
  "_birthDate" : {
    "extension" : [{
      "url" : "http://hl7.org/fhir/StructureDefinition/patient-birthTime",
      "valueDateTime" : "1974-12-25T14:35:45-05:00"
    }]
  },
  "deceasedBoolean" : false,
  "address" : [{
    "use" : "home",
    "type" : "both",
    "text" : "534 Erewhon St PeasantVille, Rainbow, Vic  3999",
    "line" : ["534 Erewhon St"],
    "city" : "PleasantVille",
    "district" : "Rainbow",
    "state" : "Vic",
    "postalCode" : "3999",
    "period" : {
      "start" : "1974-12-25"
    }
  }],
  "contact" : [{
    "relationship" : [{
      "coding" : [{
        "system" : "http://terminology.hl7.org/CodeSystem/v2-0131",
        "code" : "N"
      }]
    }],
    "name" : {
      "family" : "du Marché",
      "_family" : {
        "extension" : [{
          "url" : "http://hl7.org/fhir/StructureDefinition/humanname-own-prefix",
          "valueString" : "VV"
        }]
      },
      "given" : ["Bénédicte"]
    },
    "telecom" : [{
      "system" : "phone",
      "value" : "+33 (237) 998327"
    }],
    "address" : {
      "use" : "home",
      "type" : "both",
      "line" : ["534 Erewhon St"],
      "city" : "PleasantVille",
      "district" : "Rainbow",
      "state" : "Vic",
      "postalCode" : "3999",
      "period" : {
        "start" : "1974-12-25"
      }
    },
    "gender" : "female",
    "period" : {
      "start" : "2012"
    }
  }],
  "managingOrganization" : {
    "reference" : "Organization/1"
  }
}

Request: #2: Convert a resource from R3 to R4. The Content-Type header specifies that the content is R3, and the Accept header specifies that R4 should be returned. It is up to the server how the conversion should happen.


POST /base/$convert
Accept: application/fhir+json; fhirVersion=4.0
Content-Type: application/fhir+json; fhirVersion=3.0
[other headers]

-- snip R3 version of a resource --

Response to request: #2: Response to request #2: return the R4 Response as specified in the Content-Header


200 OK
Content-Type: application/fhir+json; fhirVersion=4.0
[other headers]

-- snip - R4 version of a resource --

 

For more information about operations, including how they are invoked, see Operations.