Resource-operation-validate - FHIR v5.0.0-draft-final

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.1 Operation $validate on Resource

FHIR Infrastructure icon

Work Group

Maturity Level: N

Normative

Compartments: N/A

The validate operation checks whether the attached content would be acceptable either generally, as a create, an update or as a delete to an existing resource. The action the server takes depends on the mode parameter:

[mode not provided]: The server checks the content of the resource against any schema, constraint rules, and other general terminology rules
create: The server checks the content, and then checks that the content would be acceptable as a create (e.g. that the content would not violate any uniqueness constraints)
update: The server checks the content, and then checks that it would accept it as an update against the nominated specific resource (e.g. that there are no changes to immutable fields the server does not allow to change, and checking version integrity if appropriate)
delete: The server ignores the content, and checks that the nominated resource is allowed to be deleted (e.g. checking referential integrity rules)

Modes update and delete can only be used when the operation is invoked at the resource instance level. The return from this operation is an OperationOutcome

Note that this operation is not the only way to validate resources - see Validating Resources for further information.

The canonical URL for this operation definition is

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

Formal Definition (as a OperationDefinition).

URL: [base]/[Resource]/$validate

URL: [base]/[Resource]/[id]/$validate

This is an idempotent operation

In Parameters:

Name

Scope

Cardinality

Type

Binding

Profile

Documentation

resource

0..1

Resource

Must be present unless the mode is "delete"

mode

0..1

code

Resource Validation Mode (Required)

Default is 'no action'; (e.g. general validation)

profile

0..1

canonical

If this is nominated, then the resource is validated against this specific profile. If a profile is nominated, and the server cannot validate against the nominated profile, it SHALL return an error

usageContext TU

0..*

UsageContext

Indicates an implementation context that applies to this validation. Influences which additionalBindings are relevant. NOTE: Expectations around subsumption testing, etc. are not yet defined and may be server-specific.

Out Parameters:

Name

Scope

Cardinality

Type

Binding

Profile

Documentation

return

1..1

OperationOutcome

If the operation outcome does not list any errors, and a mode was specified, then this is an indication that the operation would be expected to succeed (excepting for transactional integrity issues, see below)

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

This operation may be used during design and development to validate application design. It can also be used at run-time. One possible use might be that a client asks the server whether a proposed update is valid as the user is editing a dialog and displays an updated error to the user. The operation can be used as part of a light-weight two phase commit protocol but there is no expectation that the server will hold the content of the resource after this operation is used, or that the server guarantees to successfully perform an actual create, update or delete after the validation operation completes.

This operation returns a 200 Ok provided that it was possible to perform validation, irrespective of whether validation issues were found. However, it is possible that certain errors in the validated content (e.g. invalid character set, broken JSON, etc.) may cause the overall validation operation to fail with a 4xx or 5xx series response.

Note: the correct behavior of validation with regard to language (especially for Coding.display) is currently undefined, and further development and testing may lead to specific requirements or recommendations in subsequent releases

Future versions of this specifcation may add additional validation parameters. A candidate list is maintained with the FHIR Validator Documentation icon

2.1.27.5.7.1.1 Examples

Request: Validate a Patient against the DAF patient profile using POST directly.

POST /open/Patient/$validate?profile=http://hl7.org/fhir/StructureDefinition/daf-patient
[other headers]

<?xml version="1.0" encoding="UTF-8"?>
<Patient xmlns="http://hl7.org/fhir">
	<id value="us01"/>
	<text>
		<status value="generated"/>
		<div xmlns="http://www.w3.org/1999/xhtml">
			<p>
				<b>Generated Narrative with Details</b>
			</p>
			<p>
				<b>id</b>: us01</p>
			<p>
				<b>active</b>: true</p>
				<p>
				<b>birthsex</b>: Male</p>
			<p>
				<b>name</b>: Peter James Chalmers (OFFICIAL)</p>
			<p>
				<b>telecom</b>: ph: (03) 5555 6473(WORK), person@example.org(WORK)</p>
			<p>
				<b>address</b>: 534 Erewhon St PleasantVille Vic 3999 (HOME)</p>
			<p>
				<b>race</b>: White, American Indian or Alaska Native, Asian, Shoshone, Filipino</p>
			<p>
				<b>ethnicity</b>: Hispanic or Latino, Dominican, Mexican</p>
		</div>
	</text>
	<extension url="http://hl7.org/fhir/StructureDefinition/us-core-race">
		<extension url="ombCategory">
			<valueCoding>
				<system value="http://terminology.hl7.org/CodeSystem/v3-Race"/>
				<code value="2106-3"/>
				<display value="White"/>
			</valueCoding>
		</extension>
		<extension url="ombCategory">
			<valueCoding>
				<system value="http://terminology.hl7.org/CodeSystem/v3-Race"/>
				<code value="1002-5"/>
				<display value="American Indian or Alaska Native"/>
			</valueCoding>
		</extension>
		<extension url="ombCategory">
			<valueCoding>
				<system value="http://terminology.hl7.org/CodeSystem/v3-Race"/>
				<code value="2028-9"/>
				<display value="Asian"/>
			</valueCoding>
		</extension>
		<extension url="detailed">
			<valueCoding>
				<system value="http://terminology.hl7.org/CodeSystem/v3-Race"/>
				<code value="1586-7"/>
				<display value="Shoshone"/>
			</valueCoding>
		</extension>
		<extension url="detailed">
			<valueCoding>
				<system value="http://terminology.hl7.org/CodeSystem/v3-Race"/>
				<code value="2036-2"/>
				<display value="Filipino"/>
			</valueCoding>
		</extension>
	</extension>
	<extension url="http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity">
		<extension url="ombCategory">
			<valueCoding>
				<system value="http://terminology.hl7.org/CodeSystem/v3-Ethnicity"/>
				<code value="2135-2"/>
				<display value="Hispanic or Latino"/>
			</valueCoding>
		</extension>
		<extension url="detailed">
			<valueCoding>
				<system value="http://terminology.hl7.org/CodeSystem/v3-Ethnicity"/>
				<code value="2184-0"/>
				<display value="Dominican"/>
			</valueCoding>
		</extension>
		<extension url="detailed">
			<valueCoding>
				<system value="http://terminology.hl7.org/CodeSystem/v3-Ethnicity"/>
				<code value="2148-5"/>
				<display value="Mexican"/>
			</valueCoding>
		</extension>
	</extension>
	<extension url="http://hl7.org/fhir/StructureDefinition/us-core-birthsex">
		<valueCode value="M"/>
	</extension>
	<active value="true"/>
	<!--  Peter James Chalmers, but called "Jim"  -->
	<name>
		<use value="official"/>
		<family value="Chalmers"/>
		<given value="Peter"/>
		<given value="James"/>
	</name>
	<telecom>
		<system value="phone"/>
		<value value="(03) 5555 6473"/>
		<use value="work"/>
	</telecom>
	<telecom>
		<extension url="http://hl7.org/fhir/StructureDefinition/us-core-direct">
			<valueBoolean value="true"/>
		</extension>
		<system value="email"/>
		<value value="person@example.org"/>
		<use value="work"/>
	</telecom>
	<address>
		<use value="home"/>
		<line value="534 Erewhon St"/>
		<city value="PleasantVille"/>
		<district value="Orange County"/>
		<state value="Vic"/>
		<postalCode value="3999"/>
	</address>
</Patient>

Request: Validate a proposed patient update - and for this example, using the Parameters syntax


POST /open/Patient/example/$validate
[other headers]

<Parameters xmlns="http://hl7.org/fhir">
  <parameter>
    <name value="mode"/>
    <valueCode value="update"/>
  </parameter>
  <parameter>
    <name value="resource"/>
    <resource>
      <?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>
    </resource>
  </parameter>
</Parameters>

Response: Returned when the resource is valid


HTTP/1.1 200 OK
[other headers]

<?xml version="1.0" encoding="UTF-8"?>
<OperationOutcome xmlns="http://hl7.org/fhir">
  <id value="allok"/>
  <text>
    <status value="generated"/>
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p>All OK</p>
    </div>
  </text>
  <issue> 
    <severity value="information"/>
    <code value="informational"/>
    <details>
      <text value="All OK"/>
    </details>
 </issue>
</OperationOutcome>

Response: Returned when the resource is not valid


HTTP/1.1 200 OK
[other headers]

<?xml version="1.0" encoding="UTF-8"?>
<OperationOutcome xmlns="http://hl7.org/fhir">
  <id value="validationfail"/>
  <text>
    <status value="generated"/>
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p>Error parsing resource XML (Unknown Content &quot;label&quot; @ /Patient/identifier/label) at Patient.identifier</p>
    </div>
  </text>
  <issue>
    <severity value="error"/>
    <code value="structure"/>
    <details>
      <text value="Error parsing resource XML (Unknown Content &quot;label&quot;"/>
    </details> 
    <location value="/f:Patient/f:identifier"/>
    <expression value="Patient.identifier"/>
  </issue>
</OperationOutcome>

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