R4 Draft for Comment
FoundationThis page is part of the FHIR Specification (v3.2.0: R4 Ballot 1). 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 R3 R2
| FHIR Infrastructure Work Group | Maturity Level: 5 | Normative | Compartments: Not linked to any defined compartments |
Normative Candidate Note: Some of the content on this page (marked clearly) 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.
This resource has 4 operations associated with it:
| $validate | Validate a resource |
| $meta | Access a list of profiles, tags, and security labels |
| $meta-add | Add profiles, tags, and security labels to a resource |
| $meta-delete | Delete profiles, tags, and security labels for a resource |
For more information about operations, including how they are invoked, see Operations.
Normative Candidate Note: This operation is candidate normative content as part of the overall resource for R4 in the Infrastructure Package. Once normative, it will lose it's Maturity Level, and breaking changes will no longer be made.
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:
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
The official 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 | Cardinality | Type | Binding | Profile | Documentation |
| resource | 0..1 | Resource | Must be present unless the mode is "delete" | ||
| mode | 0..1 | code | ResourceValidationMode (Required) | Default is 'no action'; (e.g. general validation) | |
| profile | 0..1 | uri | 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 | ||
| Out Parameters: | |||||
| Name | 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 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 whether or not the resource is valid. A 4xx or 5xx error means that the validation itself could not be performed, and it is unknown whether the resource is valid or not.
Validate a Patient against the DAF patient profile using POST directly. (Request):
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://hl7.org/fhir/v3/Race"/> <code value="2106-3"/> <display value="White"/> </valueCoding> </extension> <extension url="ombCategory"> <valueCoding> <system value="http://hl7.org/fhir/v3/Race"/> <code value="1002-5"/> <display value="American Indian or Alaska Native"/> </valueCoding> </extension> <extension url="ombCategory"> <valueCoding> <system value="http://hl7.org/fhir/v3/Race"/> <code value="2028-9"/> <display value="Asian"/> </valueCoding> </extension> <extension url="detailed"> <valueCoding> <system value="http://hl7.org/fhir/v3/Race"/> <code value="1586-7"/> <display value="Shoshone"/> </valueCoding> </extension> <extension url="detailed"> <valueCoding> <system value="http://hl7.org/fhir/v3/Race"/> <code value="2036-2"/> <display value="Filipino"/> </valueCoding> </extension> </extension> <extension url="http://hl7.org/fhir/StructureDefinition/us-core-ethnicity"> <extension url="ombCategory"> <valueCoding> <system value="http://hl7.org/fhir/v3/Ethnicity"/> <code value="2135-2"/> <display value="Hispanic or Latino"/> </valueCoding> </extension> <extension url="detailed"> <valueCoding> <system value="http://hl7.org/fhir/v3/Ethnicity"/> <code value="2184-0"/> <display value="Dominican"/> </valueCoding> </extension> <extension url="detailed"> <valueCoding> <system value="http://hl7.org/fhir/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>
Validate a proposed patient update - and for this example, using the Parameters syntax (Request):
POST /open/Patient/example/$validate
[other headers]
<Parameters xmlns="http://hl7.org/fhir">
<parameter>
<name value="mode"/>
<valueCode value="update"/>
<parameter>
<parameter>
<name value="mode"/>
<resource>
<?xml version="1.0" encoding="UTF-8"?>
<Patient xmlns="http://hl7.org/fhir">
<id value="example"/>
<text>
<status value="generated"/>
<div xmlns="http://www.w3.org/1999/xhtml">
<table>
<tbody>
<tr>
<td>Name</td>
<td>Peter James
<b>Chalmers</b> ("Jim")
</td>
</tr>
<tr>
<td>Address</td>
<td>534 Erewhon, Pleasantville, Vic, 3999</td>
</tr>
<tr>
<td>Contacts</td>
<td>Home: unknown. Work: (03) 5555 6473</td>
</tr>
<tr>
<td>Id</td>
<td>MRN: 12345 (Acme Healthcare)</td>
</tr>
</tbody>
</table>
</div>
</text>
<!-- MRN assigned by ACME healthcare on 6-May 2001 -->
<identifier>
<use value="usual"/>
<type>
<coding>
<system value="http://hl7.org/fhir/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://hl7.org/fhir/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>
Returned when the resource is valid (Response):
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="additional"/>
<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>
Returned when the resource is not valid (Response):
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 "label" @ /Patient/identifier/label)</p>
</div>
</text>
<issue>
<severity value="error"/>
<code value="structure"/>
<details>
<text value="Error parsing resource XML (Unknown Content "label""/>
</details>
<location value="/f:Patient/f:identifier"/>
<expression value="Patient.identifier"/>
</issue>
</OperationOutcome>
Normative Candidate Note: Though the resource is a candidate for normative for R4, this operation is not included. It's status will remain 'Trial Use' while more experience is gathered.
This operation retrieves a summary of the profiles, tags, and security labels for the given scope; e.g. for each scope:
The official URL for this operation definition is
http://hl7.org/fhir/OperationDefinition/Resource-meta
Formal Definition (as a OperationDefinition).
URL: [base]/$meta
URL: [base]/[Resource]/$meta
URL: [base]/[Resource]/[id]/$meta
This is an idempotent operation
| Out Parameters: | |||||
| Name | Cardinality | Type | Binding | Profile | Documentation |
| return | 1..1 | Meta | The meta returned by the operation | ||
At the system and type levels, the $meta operation is used to get a summary of all the labels that are in use across the system. The principle use for this operation is to support search e.g. what tags can be searched for. At these levels, the meta will not contain versionId, lastUpdated etc. Systems are not obligated to implement the operation at this level (and should return a 4xx error if they don't). At the resource and historical entry level, the $meta operation returns the same meta as would be returned by accessing the resource directly. This can be used to allow a system to get access to the meta-information for the resource without accessing the resource itself, e.g. for security reasons
Get all the tags, profiles, and security labels used on patient resources (Request):
GET /fhir/Patient/$meta
All the tags, profiles, and security labels used on patient resources (Response):
HTTP/1.1 200 OK
[other headers]
<Parameters>
<parameter>
<name value="return"/>
<valueMeta>
<profile value="http://hl7.org/fhir/StructureDefinition/daf-patient"/>
<profile value="http://hl7.org/fhir/StructureDefinition/uslab-patient"/>
<security>
<system value="http://hl7.org/fhir/v3/ActCode"/>
<code value="EMP"/>
<display value="employee information sensitivity"/>
</security>
<tag>
<system value="http://example.org/codes/tags"/>
<code value="current"/>
<display value="Current Inpatient"/>
</tag>
</valueMeta>
</parameter>
</Parameters>
Normative Candidate Note: Though the resource is a candidate for normative for R4, this operation is not included. It's status will remain 'Trial Use' while more experience is gathered.
This operation takes a meta, and adds the profiles, tags, and security labels found in it to the nominated resource. This operation can also be used on historical entries - to update them without creating a different historical version
The official URL for this operation definition is
http://hl7.org/fhir/OperationDefinition/Resource-meta-add
Formal Definition (as a OperationDefinition).
URL: [base]/[Resource]/[id]/$meta-add
This is not an idempotent operation
| In Parameters: | |||||
| Name | Cardinality | Type | Binding | Profile | Documentation |
| meta | 1..1 | Meta | Profiles, tags, and security labels to add to the existing resource. Note that profiles, tags, and security labels are sets, and duplicates are not created. The identity of a tag or security label is the system+code. When matching existing tags during adding, version and display are ignored. For profiles, matching is based on the full URL | ||
| Out Parameters: | |||||
| Name | Cardinality | Type | Binding | Profile | Documentation |
| return | 1..1 | Meta | Resulting meta for the resource | ||
This operation is special in that executing this operation does not cause a new version of the resource to be created. The meta is updated directly. This is because the content in meta does not affect the meaning of the resource, and the security labels (in particular) are used to apply access rules to existing versions of resources
Add a 'paper record lost' tag to a resource (Request):
POST /fhir/Patient/example/$meta-add
[Other headers]
<Parameters>
<parameter>
<name value="meta"/>
<valueMeta>
<tag>
<system value="http://example.org/codes/tags"/>
<code value="record-lost"/>
<display value="Patient File Lost"/>
</tag>
</valueMeta>
</parameter>
</Parameters>
All the tags, profiles, and security labels used on patient resources (Response):
HTTP/1.1 200 OK
[other headers]
<Parameters>
<parameter>
<name value="return"/>
<valueMeta>
<profile value="http://hl7.org/fhir/StructureDefinition/daf-patient"/>
<tag>
<system value="http://example.org/codes/tags"/>
<code value="current"/>
<display value="Current Inpatient"/>
</tag>
<tag>
<system value="http://example.org/codes/tags"/>
<code value="record-lost"/>
<display value="Patient File Lost"/>
</tag>
</valueMeta>
</parameter>
</Parameters>
Normative Candidate Note: Though the resource is a candidate for normative for R4, this operation is not included. It's status will remain 'Trial Use' while more experience is gathered.
This operation takes a meta, and deletes the profiles, tags, and security labels found in it from the nominated resource. This operation can also be used on historical entries
The official URL for this operation definition is
http://hl7.org/fhir/OperationDefinition/Resource-meta-delete
Formal Definition (as a OperationDefinition).
URL: [base]/[Resource]/[id]/$meta-delete
This is not an idempotent operation
| In Parameters: | |||||
| Name | Cardinality | Type | Binding | Profile | Documentation |
| meta | 1..1 | Meta | Profiles, tags, and security labels to delete from the existing resource. It is not an error if these tags, profiles, and labels do not exist. The identity of a tag or security label is the system+code. When matching existing tags during deletion, version and display are ignored. For profiles, matching is based on the full URL | ||
| Out Parameters: | |||||
| Name | Cardinality | Type | Binding | Profile | Documentation |
| return | 1..1 | Meta | Resulting meta for the resource | ||
This operation is special in that executing this operation does not cause a new version of the resource to be created. The meta is updated directly. This is because the content in meta does not affect the meaning of the resource, and the security labels (in particular) are used to apply access rules to existing versions of resources
Remove the 'current patient' tag from a resource (Request):
POST /fhir/Patient/example/$meta-delete
[Other headers]
<Parameters>
<parameter>
<name value="meta"/>
<valueMeta>
<tag>
<system value="http://example.org/codes/tags"/>
<code value="current"/>
<display value="Current Inpatient"/>
</tag>
</valueMeta>
</parameter>
</Parameters>
All the tags, profiles, and security labels used on patient resources (Response):
HTTP/1.1 200 OK
[other headers]
<Parameters>
<parameter>
<name value="return"/>
<valueMeta>
<profile value="http://hl7.org/fhir/StructureDefinition/daf-patient"/>
<tag>
<system value="http://example.org/codes/tags"/>
<code value="record-lost"/>
<display value="Patient File Lost"/>
</tag>
</valueMeta>
</parameter>
</Parameters>
®© HL7.org 2011+. FHIR Release 4 Draft for Comment (Jan-2018 v3.2.0-12885) generated on Wed, Dec 20, 2017 15:56+1100. QA Page
Links: Search |
Version History |
Table of Contents |
Credits |
Compare to DSTU3 |
|
Propose a change