FHIR:Vissue-MM-3497 FHIR IG R4 - Bewerkingsoverzicht

Luud Slagter op 24 aug 2022 om 09:00

2022-08-24T09:00:30Z

← Oudere versie		Versie van 24 aug 2022 09:00
Regel 74:		Regel 74:
	* For servers that support multiple FHIR versions on their endpoint:		* For servers that support multiple FHIR versions on their endpoint:
	** Servers SHALL process requests in accordance with a matching <code>fhirVersion</code> parameter in the <code>Accept</code> and <code>Content-Type</code> headers of incoming requests. This means that they SHALL format data according to the profiles specified for the matching FHIR version.		** Servers SHALL process requests in accordance with a matching <code>fhirVersion</code> parameter in the <code>Accept</code> and <code>Content-Type</code> headers of incoming requests. This means that they SHALL format data according to the profiles specified for the matching FHIR version.
	** Servers SHALL support a default version in absence of the <code>fhirVersion</code> parameter in the <code>Accept</code> and <code>Content-Type</code> headers.</p><p>Note: When a server previously supported FHIR STU3 on an endpoint, it makes sense to set STU3 as the default version to remain compatible with existing clients. Newer R4 implementations of clients are expected to use the <code>fhirVersion</code> parameter, whereas this was not the case for STU3 implementations.		** <p>Servers SHALL support a default version in absence of the <code>fhirVersion</code> parameter in the <code>Accept</code> and <code>Content-Type</code> headers.</p><p>Note: When a server previously supported FHIR STU3 on an endpoint, it makes sense to set STU3 as the default version to remain compatible with existing clients. Newer R4 implementations of clients are expected to use the <code>fhirVersion</code> parameter, whereas this was not the case for STU3 implementations.
	** In case of a mismatch between the requested <code>fhirVersion</code> and the supported <code>fhirVersion</code>(s), servers SHALL respond with HTTP status 400 Bad Request and SHOULD include an OperationOutcome with {{fhir\|.severity}} set to {{term\|fatal}} and {{fhir\|.code}} set to {{term\|exception}}, and SHOULD include a {{fhir\|.details}} element that outlines the mismatch.		** In case of a mismatch between the requested <code>fhirVersion</code> and the supported <code>fhirVersion</code>(s), servers SHALL respond with HTTP status 400 Bad Request and SHOULD include an OperationOutcome with {{fhir\|.severity}} set to {{term\|fatal}} and {{fhir\|.code}} set to {{term\|exception}}, and SHOULD include a {{fhir\|.details}} element that outlines the mismatch.

Luud Slagter op 24 aug 2022 om 08:55

2022-08-24T08:55:27Z

Luud Slagter: /* {{fhir|Resource.text}} or "the narrative" */

2022-08-24T08:47:21Z

{{fhir|Resource.text}} or "the narrative"

Luud Slagter: /* Including "secondary" resources when sending information */

2022-08-24T07:20:20Z

Including "secondary" resources when sending information

← Oudere versie		Versie van 24 aug 2022 07:20
Regel 392:		Regel 392:

	==Including "secondary" resources when sending information==		==Including "secondary" resources when sending information==
	When the client creates/updates a resource on a server, it often needs to reference and include "secondary" resources which are not the primary focus of the interaction -- e.g. an Observation must indicate its subject using a reference to a Patient resource. The situation may arise that the client includes an instance of a resource that already exists on the server, in the transaction (for example, when the client doesn't know about the existing resource). In this case, the server should align these new resources with the ones it already has.		When the client creates/updates a resource on a server, it often needs to reference and include "secondary" resources which are not the primary focus of the interaction - e.g. an Observation must indicate its subject using a reference to a Patient resource. The situation may arise that the client includes an instance of a resource that already exists on the server, in the transaction (for example, when the client doesn't know about the existing resource). In this case, the server should align these new resources with the ones it already has.

	A data conflict may arise if these secondary resources carry details that are not of interest within the particular context of the information standard. For example, the client posts an Observation and sends along a Patient resource containing a different telephone number than the one that is on record at the server side. This change in telephone number is not relevant in this particular context, since the interaction is about creating the Observation.		A data conflict may arise if these secondary resources carry details that are not of interest within the particular context of the information standard. For example, the client posts an Observation and sends along a Patient resource containing a different telephone number than the one that is on record at the server side. This change in telephone number is not relevant in this particular context, since the interaction is about creating the Observation.
Regel 400:		Regel 400:
	* If so, the client MAY send a bare-bones instance as the secondary resource containing just minimal information, but this SHOULD include the information necessary for the server to match its own copy. The information standard MAY specify which information is minimally needed for such a secondary resource and MAY also restrict the information that is sent in the secondary resource.		* If so, the client MAY send a bare-bones instance as the secondary resource containing just minimal information, but this SHOULD include the information necessary for the server to match its own copy. The information standard MAY specify which information is minimally needed for such a secondary resource and MAY also restrict the information that is sent in the secondary resource.
	* The client MUST include a {{fhir\|Bundle.entry.request}} for each of the resources in the Bundle, including the secondary resources that are only there for referencing purposes. {{fhir\|.request}} SHOULD be a <code>POST</code> to the appropriate endpoint. As an alternative, <code>PUT</code> MAY be used, but is strongly discouraged; if the client has knowledge on the id of the resource on the server, an absolute URL is strongly preferred.		* The client MUST include a {{fhir\|Bundle.entry.request}} for each of the resources in the Bundle, including the secondary resources that are only there for referencing purposes. {{fhir\|.request}} SHOULD be a <code>POST</code> to the appropriate endpoint. As an alternative, <code>PUT</code> MAY be used, but is strongly discouraged; if the client has knowledge on the id of the resource on the server, an absolute URL is strongly preferred.
	* If the server can unequivocally ~~de-duplicate~~ this secondary resource (for example, because the patient is already known from the security context or the healthcare provider is recognized by the UZI number), it MAY choose to ignore the differences of this resource or it MAY incorporate them (see the [https://hl7.org/fhir/r4/http.html#transactional-integrity the section on transactional integrity] in the FHIR specification). Please note that absence of information should not result in deletion of information on the server, as the client could send a bare-bones instance. If the server chooses to ignore the differences, it SHOULD do so silently by responding with a 200 OK status code for the corresponding {{fhir\|Bundle.entry.response.status}} in the response Bundle.		* If the server can unequivocally deduplicate this secondary resource (for example, because the patient is already known from the security context or the healthcare provider is recognized by the UZI number), it MAY choose to ignore the differences of this resource or it MAY incorporate them (see the [https://hl7.org/fhir/r4/http.html#transactional-integrity the section on transactional integrity] in the FHIR specification). Please note that absence of information should not result in deletion of information on the server, as the client could send a bare-bones instance. If the server chooses to ignore the differences, it SHOULD do so silently by responding with a 200 OK status code for the corresponding {{fhir\|Bundle.entry.response.status}} in the response Bundle.
	* The server SHALL rewrite the references in the primary resource to the instance of the secondary resource it already has.		* The server SHALL rewrite the references in the primary resource to the instance of the secondary resource it already has.

Luud Slagter: /* Handling errors */

2022-08-24T07:15:52Z

Handling errors

← Oudere versie		Versie van 24 aug 2022 07:15
Regel 308:		Regel 308:

	== Handling errors==		== Handling errors==
	Errors in FHIR interactions are usually communicated using the combination of an appropriate HTTP status code in the 4xx-5xx range, and an [https://hl7.org/fhir/R4/operationoutcome.html OperationOutcome] resource providing more details regarding the error. The OperationOutcome resource contains mandatory elements to indicate the overall type and severity of the error (respectively {{fhir\|.code}} and {{fhir\|.severity}}) and MAY express the location (using {{fhir\|.location}} or {{fhir\|.expression}}) and a free-form or coded description of the error (using the {{fhir\|.diagnostics}} or {{fhir\|.~~detail~~}} element). Although these latter elements are not required, their usage is strongly encouraged.		Errors in FHIR interactions are usually communicated using the combination of an appropriate HTTP status code in the 4xx-5xx range, and an [https://hl7.org/fhir/R4/operationoutcome.html OperationOutcome] resource providing more details regarding the error. The OperationOutcome resource contains mandatory elements to indicate the overall type and severity of the error (respectively {{fhir\|.code}} and {{fhir\|.severity}}) and MAY express the location (using {{fhir\|.location}} or {{fhir\|.expression}}) and a free-form or coded description of the error (using the {{fhir\|.diagnostics}} or {{fhir\|.details}} element). Although these latter elements are not required, their usage is strongly encouraged.

	For the most common errors, the expected handling is listed in the table below. This should be interpreted as a guideline, as the nature of an error is not always unambiguous and various FHIR reference implementations will make different choices. The FHIR specification provides more detail [https://www.hl7.org/fhir/R4/http.html on error handling in general], [https://www.hl7.org/fhir/R4/security.html#AccessDenied access denied responses] and [https://www.hl7.org/fhir/R4/search.html#errors for search operations specifically].		For the most common errors, the expected handling is listed in the table below. This should be interpreted as a guideline, as the nature of an error is not always unambiguous and various FHIR reference implementations will make different choices. The FHIR specification provides more detail [https://www.hl7.org/fhir/R4/http.html on error handling in general], [https://www.hl7.org/fhir/R4/security.html#AccessDenied access denied responses] and [https://www.hl7.org/fhir/R4/search.html#errors for search operations specifically].
Regel 316:		Regel 316:
	* 401 Unauthorized - authorization is required for the interaction that was attempted (usually emitted by the authorization server)		* 401 Unauthorized - authorization is required for the interaction that was attempted (usually emitted by the authorization server)
	* 403 Forbidden - the server was unable to execute the search, due to an authorization failure (usually emitted by the resource server)		* 403 Forbidden - the server was unable to execute the search, due to an authorization failure (usually emitted by the resource server)
	* 404 Not Found - resource type not supported, or not an FHIR endpoint		* 404 Not Found - resource type not supported, or not a FHIR endpoint
	* 422 Unprocessable Entity - the proposed resource violated applicable FHIR profiles or server business rules		* 422 Unprocessable Entity - the proposed resource violated applicable FHIR profiles or server business rules

Regel 330:		Regel 330:
	\|		\|
	* HTTP 401 Unauthorized		* HTTP 401 Unauthorized
	* OperationOutcome with {{fhir\|.code}} set to {{term\|security}}		* OperationOutcome with {{fhir\|.code}} set to {{term\|security}}.
	\| [[FHIR:V1.0 FHIR_Error_handling_examples#Not_authorized\|Example]]		\| [[FHIR:V1.0 FHIR_Error_handling_examples#Not_authorized\|Example]]
	\|-		\|-
Regel 336:		Regel 336:
	\|		\|
	* HTTP 403 Forbidden		* HTTP 403 Forbidden
	* OperationOutcome with {{fhir\|.code}} set to {{term\|security}}		* OperationOutcome with {{fhir\|.code}} set to {{term\|security}}.
	\| [[FHIR:V1.0 FHIR_Error_handling_examples#Invalid_authorization\|Example]]		\| [[FHIR:V1.0 FHIR_Error_handling_examples#Invalid_authorization\|Example]]
	\|-		\|-
Regel 342:		Regel 342:
	\|		\|
	* HTTP 404 Not Found		* HTTP 404 Not Found
	* OperationOutcome with {{fhir\|.code}} set to {{term\|not-supported}}		* OperationOutcome with {{fhir\|.code}} set to {{term\|not-supported}}.
	\| [[FHIR:V1.0 FHIR_Error_handling_examples#Resource_is_not_supported\|Example]]		\| [[FHIR:V1.0 FHIR_Error_handling_examples#Resource_is_not_supported\|Example]]
	\|-		\|-
Regel 361:		Regel 361:
	\|		\|
	* HTTP 200 OK		* HTTP 200 OK
	* Empty Bundle of {{fhir\|.type}} {{term\|searchset}}		* Empty Bundle of {{fhir\|.type}} {{term\|searchset}}.
	* OperationOutcome in Bundle as an entry marked with {{fhir\|Bundle.entry.search.mode}} of {{term\|outcome}}.		* OperationOutcome in Bundle as an entry marked with {{fhir\|Bundle.entry.search.mode}} set to {{term\|outcome}}.
	* OperationOutcome with {{fhir\|.code}} set to {{term\|not-found}} and {{fhir\|.severity}} not set to {{term\|fatal}} or {{term\|error}}.		* OperationOutcome with {{fhir\|.code}} set to {{term\|not-found}} and {{fhir\|.severity}} not set to {{term\|fatal}} or {{term\|error}}.
	\| [[FHIR:V1.0 FHIR_Error_handling_examples#Unkown_or_unsupported_search_parameter_value\|Example]]		\| [[FHIR:V1.0 FHIR_Error_handling_examples#Unkown_or_unsupported_search_parameter_value\|Example]]
Regel 370:		Regel 370:
	\|		\|
	* HTTP 404 Not Found		* HTTP 404 Not Found
	* OperationOutcome with {{fhir\|.code}} set to {{term\|not-found}}		* OperationOutcome with {{fhir\|.code}} set to {{term\|not-found}}.
	\| [[FHIR:V1.0 FHIR_Error_handling_examples#Request_on_an_unknown_id\|Example]]		\| [[FHIR:V1.0 FHIR_Error_handling_examples#Request_on_an_unknown_id\|Example]]
	\|-		\|-
Regel 377:		Regel 377:
	\|		\|
	* HTTP 400 Bad Request		* HTTP 400 Bad Request
	* OperationOutcome with {{fhir\|.code}} set to {{term\|invalid}}		* OperationOutcome with {{fhir\|.code}} set to {{term\|invalid}}.
	\| [[FHIR:V1.0 FHIR_Error_handling_examples#No_or_incorrect_Resource_id\|Example]]		\| [[FHIR:V1.0 FHIR_Error_handling_examples#No_or_incorrect_Resource_id\|Example]]
	\|-		\|-

Luud Slagter: /* Usage of the {{fhir|.id}}, {{fhir|.identifier}} and {{fhir|.fullUrl}} elements in FHIR instances */

2022-08-24T07:00:31Z

Usage of the {{fhir|.id}}, {{fhir|.identifier}} and {{fhir|.fullUrl}} elements in FHIR instances

Luud Slagter: /* Search */

2022-08-24T06:46:59Z

Luud Slagter: /* Profile use and declaration */

2022-08-24T06:36:39Z

Profile use and declaration

← Oudere versie		Versie van 24 aug 2022 06:36
Regel 132:		Regel 132:
	The implementation guides for the various information standards list the package version and profiles to use for the FHIR resources. A profile is a statement about the rules that this resource was created against. In the interest of interoperability it is important that, when using said information standard:		The implementation guides for the various information standards list the package version and profiles to use for the FHIR resources. A profile is a statement about the rules that this resource was created against. In the interest of interoperability it is important that, when using said information standard:
	* Each resource SHALL be a valid instance of the applicable profile. Note that this applies not only to profiles listed directly in the IG, but also to profiles referred from/used by listed profiles.		* Each resource SHALL be a valid instance of the applicable profile. Note that this applies not only to profiles listed directly in the IG, but also to profiles referred from/used by listed profiles.
	* Each resource SHALL include the canonical URL of this profile in the {{fhir\|meta.profile}} element. If the applicable profile is an [[#Layering:_zibs.2C_nl-core_profiles_and_information_standard_specific_profiles\|information standard specific profile derived from an nl-core-profile]], the canonical URL of the latter SHALL be included in an additional {{fhir\|.profile}} element. The canonical of compatible base or derived profiles MAY be included as well.		* Each resource SHALL include the canonical URL of this profile in the {{fhir\|.meta.profile}} element. If the applicable profile is an [[#Layering:_zibs.2C_nl-core_profiles_and_information_standard_specific_profiles\|information standard specific profile derived from an nl-core profile]], the canonical URL of the latter SHALL be included in an additional {{fhir\|.profile}} element. The canonical of compatible base or derived profiles MAY be included as well.
	* A receiving system MAY use the stated value of {{fhir\|meta.profile}} for validation, documentation or other purposes.		* A receiving system MAY use the stated value of {{fhir\|.meta.profile}} for validation, documentation or other purposes.
	* A receiving system MAY use other profiles than stated in {{fhir\|meta.profile}}, e.g. when it has derived more constrained profiles based on the stated meta.profile. Reasons for additional validation may include protecting the integrity of the receiving system or determination of internal process flow.		* A receiving system MAY use other profiles than stated in {{fhir\|.meta.profile}}, e.g. when it has derived more constrained profiles based on the stated {{fhir\|.meta.profile}}. Reasons for additional validation may include protecting the integrity of the receiving system or determination of internal process flow.
	* The use of a version (appended to the canonical URL, ~~seperated~~ by a vertical bar <code>\|</code>) is strongly discouraged, because declaring compatibility this way is incompatible with any SemVer Grammar (e.g. it is not possible to declare a <code>\|1.x</code> compatibility in a {{datatype\|canonical}}).		* The use of a version (appended to the canonical URL, separated by a vertical bar <code>\|</code>) is strongly discouraged, because declaring compatibility this way is incompatible with any SemVer Grammar (e.g. it is not possible to declare a <code>\|1.x</code> compatibility in a {{datatype\|canonical}}).

	===FHIR Packages===		===FHIR Packages===

Luud Slagter: /* Use of the reference data type */

2022-08-23T14:59:42Z

Use of the reference data type

← Oudere versie		Versie van 23 aug 2022 14:59
Regel 113:		Regel 113:
	==Use of the reference data type==		==Use of the reference data type==
	A key feature of FHIR is the ability of resources to reference each other. This is done using the [https://hl7.org/fhir/R4/references.html#Reference {{datatype\|Reference}} data type]. This data type supports two modes of referencing:		A key feature of FHIR is the ability of resources to reference each other. This is done using the [https://hl7.org/fhir/R4/references.html#Reference {{datatype\|Reference}} data type]. This data type supports two modes of referencing:
	; [https://hl7.org/fhir/R4/references.html#literal Literal references], using the {{fhir\|.reference}} element: A relative or absolute REST endpoint containing {{fhir\|.id}} of the referenced resource. In a Bundle context, this may also be a reference to a {{fhir\|Bundle.resource.fullUrl}}.		; [https://hl7.org/fhir/R4/references.html#literal Literal references], using the {{fhir\|.reference}} element: A relative or absolute REST endpoint containing the {{fhir\|.id}} of the referenced resource. In a Bundle context, this may also be a reference to a {{fhir\|Bundle.resource.fullUrl}}.
	; [https://hl7.org/fhir/R4/references.html#logical Logical references], using the {{fhir\|.identifier}} element: Meaning a match on the business identifier ({{fhir\|.identifier}}) for the referenced resource, without specifying where to find the referenced resource. Note: confusingly, although this reference type is called "logical reference", it does ''not'' act on the "logical identifier" ({{fhir\|.id}}) of resources.		; [https://hl7.org/fhir/R4/references.html#logical Logical references], using the {{fhir\|.identifier}} element: Meaning a match on the business identifier ({{fhir\|.identifier}}) for the referenced resource, without specifying where to find the referenced resource. Note: confusingly, although this reference type is called "logical reference", it does ''not'' act on the "logical identifier" ({{fhir\|.id}}) of resources.

Luud Slagter: /* Use of coded concepts */

2022-08-23T14:57:14Z

Use of coded concepts

← Oudere versie		Versie van 23 aug 2022 14:57
Regel 81:		Regel 81:
	Coded information is important for interoperability between systems. The zibs prescribe which ValueSets and CodeSystems to use for all its concepts.		Coded information is important for interoperability between systems. The zibs prescribe which ValueSets and CodeSystems to use for all its concepts.

	However, it is likely that unknown codes present themselves in the communication, for example because the sending system has updated its medication codes to a newer version than the receiving system, or because an older record item is coded in a way that now has been deprecated. It is therefore vital that, in addition to the code itself, the sender includes the semantics of the code. Therefore, systems SHOULD include [https://hl7.org/fhir/R4/datatypes.html#coding {{fhir\|(CodeableConcept.)coding.display}}] and/or [https://hl7.org/fhir/r4/datatypes.html#codeableconcept {{fhir\|CodeableConcept.text}}] for coded data in FHIR instances. These fields may only be absent in rare circumstances, for example when dealing with ~~historic~~ data, or in data acquired without such info from a third party. If multiple {{datatype\|codings}} are available, at least one {{fhir\|coding.display}} SHALL be available, which SHALL be the value most relevant to the use case.		However, it is likely that unknown codes present themselves in the communication, for example because the sending system has updated its medication codes to a newer version than the receiving system, or because an older record item is coded in a way that now has been deprecated. It is therefore vital that, in addition to the code itself, the sender includes the semantics of the code. Therefore, systems SHOULD include [https://hl7.org/fhir/R4/datatypes.html#coding {{fhir\|(CodeableConcept.)coding.display}}] and/or [https://hl7.org/fhir/r4/datatypes.html#codeableconcept {{fhir\|CodeableConcept.text}}] for coded data in FHIR instances. These fields may only be absent in rare circumstances, for example when dealing with historical data, or in data acquired without such info from a third party. If multiple {{datatype\|codings}} are available, at least one {{fhir\|.coding.display}} SHALL be available, which SHALL be the value most relevant to the use case.

	If {{fhir\|(CodeableConcept.)coding.display}} cannot be retrieved [https://www.hl7.org/fhir/r4/datatypes.html#Coding from the relevant code system], it may be retrieved from the {{fhir\|ValueSet}} that is bound to the relevant element. Any other value for {{fhir\|coding.display}} will trigger a warning during validation. The semantic validity of the display value will then have to be assessed.		If {{fhir\|(CodeableConcept.)coding.display}} cannot be retrieved [https://www.hl7.org/fhir/r4/datatypes.html#Coding from the relevant code system], it may be retrieved from the {{fhir\|ValueSet}} that is bound to the relevant element. Any other value for {{fhir\|.coding.display}} will trigger a warning during validation. The semantic validity of the display value will then have to be assessed.

	The [https://hl7.org/fhir/R4/datatypes.html#CodeableConcept spec on CodeableConcept] offers guidance on how the presence of {{fhir\|CodeableConcept.text}} can be handled. Usually, the value of {{fhir\|.text}} will be preferred above {{fhir\|.coding.display}}, unless one of the {{datatype\|codings}} is flagged with {{fhir\|.userSelected}} = {{term\|true}}. A {{fhir\|.coding}} equivalent to {{term\|other}} (often {{fhir\|.code}} {{term\|OTH}} in {{fhir\|.system}} {{term\|<nowiki>http://terminology.hl7.org/CodeSystem/v3-NullFlavor</nowiki>}}) leads to {{fhir\|.text}} containing the actual meaning of the concept. For example: given an element for eye color with a bound ValueSet with concepts {{term\|blue}}, {{term\|brown}} and {{term\|OTH}}, if {{fhir\|.coding.code}} is filled with {{term\|OTH}}, {{fhir\|.text}} is to be filled with {{term\|green}} (or any other color that is not represented in the ValueSet). Systems SHALL present the value of {{fhir\|.text}} to its users.		The [https://hl7.org/fhir/R4/datatypes.html#CodeableConcept spec on CodeableConcept] offers guidance on how the presence of {{fhir\|CodeableConcept.text}} can be handled. Usually, the value of {{fhir\|.text}} will be preferred above {{fhir\|.coding.display}}, unless one of the {{datatype\|codings}} is flagged with {{fhir\|.userSelected}} = {{term\|true}}. A {{fhir\|.coding}} equivalent to {{term\|other}} (often {{fhir\|.code}} {{term\|OTH}} in {{fhir\|.system}} {{term\|<nowiki>http://terminology.hl7.org/CodeSystem/v3-NullFlavor</nowiki>}}) leads to {{fhir\|.text}} containing the actual meaning of the concept. For example: given an element for eye color with a bound ValueSet with concepts {{term\|blue}}, {{term\|brown}} and {{term\|OTH}}, if {{fhir\|.coding.code}} is filled with {{term\|OTH}}, {{fhir\|.text}} is to be filled with {{term\|green}} (or any other color that is not represented in the ValueSet). Systems SHALL present the value of {{fhir\|.text}} to its users.

	===Code system URIs===		===Code system URIs===
	A coded value in FHIR is communicated as a combination of a code (in {{fhir\|.code}}) and the canonical URI for the code system from which it was drawn (in {{fhir\|.system}}). Implementers SHALL use the canonical URI that can be found by inspecting the ValueSet that is bound to a coded element in the appropriate FHIR profile<ref>Although the canonical URI is not formally defined in the ValueSet, in practical terms it can be found here.</ref>. Please note that a code system URI ''can'' align with its OID (as a (<code><nowiki>urn:oid:[oid]</nowiki></code> URI), but that this is not always the case. For example, SNOMED CT is referenced by URL rather than by <code><nowiki>urn:oid:[oid]</nowiki></code><ref>For an overview of URLs defined, see [https://www.hl7.org/fhir/R4/terminologies-systems.html the FHIR core specification] or [http://hl7.nl/wiki/index.php?title=OIDs_en_FHIR_System_URIs HL7 NL for the Dutch realm].</ref>.		A coded value in FHIR is communicated as a combination of a code (in {{fhir\|.code}}) and the canonical URI for the code system from which it was drawn (in {{fhir\|.system}}). Implementers SHALL use the canonical URI that can be found by inspecting the ValueSet that is bound to a coded element in the appropriate FHIR profile<ref>Although the canonical URI is not formally defined in the ValueSet, in practical terms it can be found here.</ref>. Please note that a code system URI ''can'' align with its OID (as a <code><nowiki>urn:oid:[oid]</nowiki></code> URI), but that this is not always the case. For example, SNOMED CT is referenced by URL rather than by <code><nowiki>urn:oid:[oid]</nowiki></code><ref>For an overview of URLs defined, see [https://www.hl7.org/fhir/R4/terminologies-systems.html the FHIR core specification] or [http://hl7.nl/wiki/index.php?title=OIDs_en_FHIR_System_URIs HL7 NL for the Dutch realm].</ref>.

	===Mapping of coded concepts===		===Mapping of coded concepts===
	Terminology from zibs or UCSDs (use case specific data sets) needs to be faithfully applied to the FHIR profiles, but this is not directly possible when the base FHIR resource defines required terminology that bears no direct relationship with the zibs or UCSD. These cases include, but are not limited to, the FHIR resource elements of data type {{datatype\|code}} (for example {{fhir\|Patient.gender}}, {{fhir\|status}} elements, structural type elements). This data type always describes FHIR specific terminology, which usually doesn't align with the zibs/UCSD terminology.		Terminology from zibs or UCSDs (use case specific data sets) needs to be faithfully applied to the FHIR profiles, but this is not directly possible when the base FHIR resource defines required terminology that bears no direct relationship with the zibs or UCSD. These cases include, but are not limited to, the FHIR resource elements of data type {{datatype\|code}} (for example {{fhir\|Patient.gender}}, {{fhir\|status}} elements, structural type elements). This data type always describes FHIR specific terminology, which usually doesn't align with the zibs/UCSD terminology.

	In these cases, a mapping will be provided to explain the relationship between de zib/UCSD terminology and the FHIR terminology. This is normally done through a FHIR [https://hl7.org/fhir/R4/conceptmap.html ConceptMap], which can translate between the terminology used in the zib/UCSD, and the terminology that FHIR instances need to adhere to. This ConceptMap will be linked to the existing ValueSet using the ~~extension~~ [https://www.hl7.org/fhir/extension-11179-permitted-value-conceptmap.html permitted-value-conceptmap extension]. When the ConceptMap {{fhir\|equivalence}} is not {{term\|equal}} or {{term\|equivalent}}, the terminology from the zib/UCSD SHALL be communicated using the extension [https://simplifier.net/resolve?target=simplifier&canonical=http://nictiz.nl/fhir/StructureDefinition/ext-CodeSpecification ext-CodeSpecification] on the same element. It is recommended to use this extension in other {{fhir\|equivalence}}-situations as well. This allows unambiguous interpretation on the receiver end.		In these cases, a mapping will be provided to explain the relationship between the zib/UCSD terminology and the FHIR terminology. This is normally done through a FHIR [https://hl7.org/fhir/R4/conceptmap.html ConceptMap], which can translate between the terminology used in the zib/UCSD, and the terminology that FHIR instances need to adhere to. This ConceptMap will be linked to the existing ValueSet using the [https://www.hl7.org/fhir/extension-11179-permitted-value-conceptmap.html permitted-value-conceptmap extension]. When the ConceptMap {{fhir\|equivalence}} is not {{term\|equal}} or {{term\|equivalent}}, the terminology from the zib/UCSD SHALL be communicated using the extension [https://simplifier.net/resolve?target=simplifier&canonical=http://nictiz.nl/fhir/StructureDefinition/ext-CodeSpecification ext-CodeSpecification] on the same element. It is recommended to use this extension in other {{fhir\|equivalence}} situations as well. This allows unambiguous interpretation on the receiver end.

	Example snippet from an instance of {{Simplifier\|http://nictiz.nl/fhir/StructureDefinition/nl-core-AllergyIntolerance\|title=AllergyIntolerance}} where in {{fhir\|.criticality}} both the FHIR terminology {{term\|high}} and the SNOMED CT {{term\|24484000}} terminology are communicated. The FHIR terminology is obtained from the zib terminology using ConceptMap {{Simplifier\|http://nictiz.nl/fhir/ConceptMap/MateVanKritiekZijnCodelijst-to-AllergyIntoleranceCriticality\|title=MateVanKritiekZijnCodelijst_to_AllergyIntoleranceCriticality}}:		Example snippet from an instance of {{Simplifier\|http://nictiz.nl/fhir/StructureDefinition/nl-core-AllergyIntolerance\|title=AllergyIntolerance}} where in {{fhir\|.criticality}} both the FHIR terminology {{term\|high}} and the SNOMED CT {{term\|24484000}} terminology are communicated. The FHIR terminology is obtained from the zib terminology using ConceptMap {{Simplifier\|http://nictiz.nl/fhir/ConceptMap/MateVanKritiekZijnCodelijst-to-AllergyIntoleranceCriticality\|title=MateVanKritiekZijnCodelijst_to_AllergyIntoleranceCriticality}}:

← Oudere versie		Versie van 23 aug 2022 14:57
Regel 81:		Regel 81:
	Coded information is important for interoperability between systems. The zibs prescribe which ValueSets and CodeSystems to use for all its concepts.		Coded information is important for interoperability between systems. The zibs prescribe which ValueSets and CodeSystems to use for all its concepts.

	However, it is likely that unknown codes present themselves in the communication, for example because the sending system has updated its medication codes to a newer version than the receiving system, or because an older record item is coded in a way that now has been deprecated. It is therefore vital that, in addition to the code itself, the sender includes the semantics of the code. Therefore, systems SHOULD include [https://hl7.org/fhir/R4/datatypes.html#coding {{fhir\|(CodeableConcept.)coding.display}}] and/or [https://hl7.org/fhir/r4/datatypes.html#codeableconcept {{fhir\|CodeableConcept.text}}] for coded data in FHIR instances. These fields may only be absent in rare circumstances, for example when dealing with ~~historic~~ data, or in data acquired without such info from a third party. If multiple {{datatype\|codings}} are available, at least one {{fhir\|coding.display}} SHALL be available, which SHALL be the value most relevant to the use case.		However, it is likely that unknown codes present themselves in the communication, for example because the sending system has updated its medication codes to a newer version than the receiving system, or because an older record item is coded in a way that now has been deprecated. It is therefore vital that, in addition to the code itself, the sender includes the semantics of the code. Therefore, systems SHOULD include [https://hl7.org/fhir/R4/datatypes.html#coding {{fhir\|(CodeableConcept.)coding.display}}] and/or [https://hl7.org/fhir/r4/datatypes.html#codeableconcept {{fhir\|CodeableConcept.text}}] for coded data in FHIR instances. These fields may only be absent in rare circumstances, for example when dealing with historical data, or in data acquired without such info from a third party. If multiple {{datatype\|codings}} are available, at least one {{fhir\|.coding.display}} SHALL be available, which SHALL be the value most relevant to the use case.

	If {{fhir\|(CodeableConcept.)coding.display}} cannot be retrieved [https://www.hl7.org/fhir/r4/datatypes.html#Coding from the relevant code system], it may be retrieved from the {{fhir\|ValueSet}} that is bound to the relevant element. Any other value for {{fhir\|coding.display}} will trigger a warning during validation. The semantic validity of the display value will then have to be assessed.		If {{fhir\|(CodeableConcept.)coding.display}} cannot be retrieved [https://www.hl7.org/fhir/r4/datatypes.html#Coding from the relevant code system], it may be retrieved from the {{fhir\|ValueSet}} that is bound to the relevant element. Any other value for {{fhir\|.coding.display}} will trigger a warning during validation. The semantic validity of the display value will then have to be assessed.

	The [https://hl7.org/fhir/R4/datatypes.html#CodeableConcept spec on CodeableConcept] offers guidance on how the presence of {{fhir\|CodeableConcept.text}} can be handled. Usually, the value of {{fhir\|.text}} will be preferred above {{fhir\|.coding.display}}, unless one of the {{datatype\|codings}} is flagged with {{fhir\|.userSelected}} = {{term\|true}}. A {{fhir\|.coding}} equivalent to {{term\|other}} (often {{fhir\|.code}} {{term\|OTH}} in {{fhir\|.system}} {{term\|<nowiki>http://terminology.hl7.org/CodeSystem/v3-NullFlavor</nowiki>}}) leads to {{fhir\|.text}} containing the actual meaning of the concept. For example: given an element for eye color with a bound ValueSet with concepts {{term\|blue}}, {{term\|brown}} and {{term\|OTH}}, if {{fhir\|.coding.code}} is filled with {{term\|OTH}}, {{fhir\|.text}} is to be filled with {{term\|green}} (or any other color that is not represented in the ValueSet). Systems SHALL present the value of {{fhir\|.text}} to its users.		The [https://hl7.org/fhir/R4/datatypes.html#CodeableConcept spec on CodeableConcept] offers guidance on how the presence of {{fhir\|CodeableConcept.text}} can be handled. Usually, the value of {{fhir\|.text}} will be preferred above {{fhir\|.coding.display}}, unless one of the {{datatype\|codings}} is flagged with {{fhir\|.userSelected}} = {{term\|true}}. A {{fhir\|.coding}} equivalent to {{term\|other}} (often {{fhir\|.code}} {{term\|OTH}} in {{fhir\|.system}} {{term\|<nowiki>http://terminology.hl7.org/CodeSystem/v3-NullFlavor</nowiki>}}) leads to {{fhir\|.text}} containing the actual meaning of the concept. For example: given an element for eye color with a bound ValueSet with concepts {{term\|blue}}, {{term\|brown}} and {{term\|OTH}}, if {{fhir\|.coding.code}} is filled with {{term\|OTH}}, {{fhir\|.text}} is to be filled with {{term\|green}} (or any other color that is not represented in the ValueSet). Systems SHALL present the value of {{fhir\|.text}} to its users.

	===Code system URIs===		===Code system URIs===
	A coded value in FHIR is communicated as a combination of a code (in {{fhir\|.code}}) and the canonical URI for the code system from which it was drawn (in {{fhir\|.system}}). Implementers SHALL use the canonical URI that can be found by inspecting the ValueSet that is bound to a coded element in the appropriate FHIR profile<ref>Although the canonical URI is not formally defined in the ValueSet, in practical terms it can be found here.</ref>. Please note that a code system URI ''can'' align with its OID (as a (<code><nowiki>urn:oid:[oid]</nowiki></code> URI), but that this is not always the case. For example, SNOMED CT is referenced by URL rather than by <code><nowiki>urn:oid:[oid]</nowiki></code><ref>For an overview of URLs defined, see [https://www.hl7.org/fhir/R4/terminologies-systems.html the FHIR core specification] or [http://hl7.nl/wiki/index.php?title=OIDs_en_FHIR_System_URIs HL7 NL for the Dutch realm].</ref>.		A coded value in FHIR is communicated as a combination of a code (in {{fhir\|.code}}) and the canonical URI for the code system from which it was drawn (in {{fhir\|.system}}). Implementers SHALL use the canonical URI that can be found by inspecting the ValueSet that is bound to a coded element in the appropriate FHIR profile<ref>Although the canonical URI is not formally defined in the ValueSet, in practical terms it can be found here.</ref>. Please note that a code system URI ''can'' align with its OID (as a <code><nowiki>urn:oid:[oid]</nowiki></code> URI), but that this is not always the case. For example, SNOMED CT is referenced by URL rather than by <code><nowiki>urn:oid:[oid]</nowiki></code><ref>For an overview of URLs defined, see [https://www.hl7.org/fhir/R4/terminologies-systems.html the FHIR core specification] or [http://hl7.nl/wiki/index.php?title=OIDs_en_FHIR_System_URIs HL7 NL for the Dutch realm].</ref>.

	===Mapping of coded concepts===		===Mapping of coded concepts===
	Terminology from zibs or UCSDs (use case specific data sets) needs to be faithfully applied to the FHIR profiles, but this is not directly possible when the base FHIR resource defines required terminology that bears no direct relationship with the zibs or UCSD. These cases include, but are not limited to, the FHIR resource elements of data type {{datatype\|code}} (for example {{fhir\|Patient.gender}}, {{fhir\|status}} elements, structural type elements). This data type always describes FHIR specific terminology, which usually doesn't align with the zibs/UCSD terminology.		Terminology from zibs or UCSDs (use case specific data sets) needs to be faithfully applied to the FHIR profiles, but this is not directly possible when the base FHIR resource defines required terminology that bears no direct relationship with the zibs or UCSD. These cases include, but are not limited to, the FHIR resource elements of data type {{datatype\|code}} (for example {{fhir\|Patient.gender}}, {{fhir\|status}} elements, structural type elements). This data type always describes FHIR specific terminology, which usually doesn't align with the zibs/UCSD terminology.

	In these cases, a mapping will be provided to explain the relationship between de zib/UCSD terminology and the FHIR terminology. This is normally done through a FHIR [https://hl7.org/fhir/R4/conceptmap.html ConceptMap], which can translate between the terminology used in the zib/UCSD, and the terminology that FHIR instances need to adhere to. This ConceptMap will be linked to the existing ValueSet using the ~~extension~~ [https://www.hl7.org/fhir/extension-11179-permitted-value-conceptmap.html permitted-value-conceptmap extension]. When the ConceptMap {{fhir\|equivalence}} is not {{term\|equal}} or {{term\|equivalent}}, the terminology from the zib/UCSD SHALL be communicated using the extension [https://simplifier.net/resolve?target=simplifier&canonical=http://nictiz.nl/fhir/StructureDefinition/ext-CodeSpecification ext-CodeSpecification] on the same element. It is recommended to use this extension in other {{fhir\|equivalence}}-situations as well. This allows unambiguous interpretation on the receiver end.		In these cases, a mapping will be provided to explain the relationship between the zib/UCSD terminology and the FHIR terminology. This is normally done through a FHIR [https://hl7.org/fhir/R4/conceptmap.html ConceptMap], which can translate between the terminology used in the zib/UCSD, and the terminology that FHIR instances need to adhere to. This ConceptMap will be linked to the existing ValueSet using the [https://www.hl7.org/fhir/extension-11179-permitted-value-conceptmap.html permitted-value-conceptmap extension]. When the ConceptMap {{fhir\|equivalence}} is not {{term\|equal}} or {{term\|equivalent}}, the terminology from the zib/UCSD SHALL be communicated using the extension [https://simplifier.net/resolve?target=simplifier&canonical=http://nictiz.nl/fhir/StructureDefinition/ext-CodeSpecification ext-CodeSpecification] on the same element. It is recommended to use this extension in other {{fhir\|equivalence}} situations as well. This allows unambiguous interpretation on the receiver end.

	Example snippet from an instance of {{Simplifier\|http://nictiz.nl/fhir/StructureDefinition/nl-core-AllergyIntolerance\|title=AllergyIntolerance}} where in {{fhir\|.criticality}} both the FHIR terminology {{term\|high}} and the SNOMED CT {{term\|24484000}} terminology are communicated. The FHIR terminology is obtained from the zib terminology using ConceptMap {{Simplifier\|http://nictiz.nl/fhir/ConceptMap/MateVanKritiekZijnCodelijst-to-AllergyIntoleranceCriticality\|title=MateVanKritiekZijnCodelijst_to_AllergyIntoleranceCriticality}}:		Example snippet from an instance of {{Simplifier\|http://nictiz.nl/fhir/StructureDefinition/nl-core-AllergyIntolerance\|title=AllergyIntolerance}} where in {{fhir\|.criticality}} both the FHIR terminology {{term\|high}} and the SNOMED CT {{term\|24484000}} terminology are communicated. The FHIR terminology is obtained from the zib terminology using ConceptMap {{Simplifier\|http://nictiz.nl/fhir/ConceptMap/MateVanKritiekZijnCodelijst-to-AllergyIntoleranceCriticality\|title=MateVanKritiekZijnCodelijst_to_AllergyIntoleranceCriticality}}:

← Oudere versie		Versie van 24 aug 2022 08:55
Regel 9:		Regel 9:
	This implementation guide (IG) describes the requirements for using '''HL7® FHIR®''' in context of information standards that are maintained by Nictiz. It applies specifically to HL7® FHIR® version 4.0.1 (R4).		This implementation guide (IG) describes the requirements for using '''HL7® FHIR®''' in context of information standards that are maintained by Nictiz. It applies specifically to HL7® FHIR® version 4.0.1 (R4).

	This IG is aimed at software vendors and developers that need to implement FHIR based information standards maintained by Nictiz. Users of this guide are expected to be familiar with the [https://hl7.org/fhir/R4 FHIR R4 specification] and resource processing. Where relevant, links to the FHIR specification are provided. This implementation guide is not intended to be a tutorial on that subject. This IG uses the conformance verbs (SHALL, SHOULD, MAY) defined in the FHIR Conformance Rules. Requirements that use the verb 'SHOULD' are treated as 'comply or explain' during compliance testing ('qualification').		This IG is aimed at software vendors and developers that need to implement FHIR-based information standards maintained by Nictiz. Users of this guide are expected to be familiar with the [https://hl7.org/fhir/R4 FHIR R4 specification] and resource processing. Where relevant, links to the FHIR specification are provided. This implementation guide is not intended to be a tutorial on that subject. This IG uses the conformance verbs (SHALL, SHOULD, MAY) defined in the FHIR Conformance Rules. Requirements that use the verb 'SHOULD' are treated as 'comply or explain' during compliance testing ('qualification').

	This IG describes overarching principles all Nictiz standards implemented in FHIR R4 SHALL conform to. However, information standard specific IGs or profiles can extend, specialize or overrule these principles if explicitly documented. These principles SHALL NOT break conformance to the FHIR Core specification.		This IG describes overarching principles all Nictiz standards implemented in FHIR R4 SHALL conform to. However, information standard specific IGs or profiles can extend, specialize or overrule these principles if explicitly documented. These principles SHALL NOT break conformance to the FHIR Core specification.
Regel 36:		Regel 36:

	===Relating FHIR profiles to its functional counterpart===		===Relating FHIR profiles to its functional counterpart===
	All profiles have a traceable relationship with their functional counterparts based on the element mapping mechanism in FHIR. This allows to:		All profiles have a traceable relationship with their functional counterparts based on the element mapping mechanism in FHIR. This allows to:
	# define one or more references from a FHIR profile to an external URL where the functional definition can be found		# define one or more references from a FHIR profile to an external URL where the functional definition can be found
	# define for each FHIR profile element to which concept ''within'' a functional definition it corresponds		# define for each FHIR profile element to which concept ''within'' a functional definition it corresponds
Regel 60:		Regel 60:

	For clients, the following rules and guidelines apply:		For clients, the following rules and guidelines apply:
	* Clients SHALL use the appropriate FHIR version for the server endpoint. Clients may use any FHIR based or other method for version discovery, including but not limited to:		* Clients SHALL use the appropriate FHIR version for the server endpoint. Clients may use any FHIR-based or other method for version discovery, including but not limited to:
	** Checking the {{fhir\|CapabilityStatement.fhirVersion}} in the server CapabilityStatement: <code>GET [base]/metadata</code>.		** Checking the {{fhir\|CapabilityStatement.fhirVersion}} in the server CapabilityStatement: <code>GET [base]/metadata</code>.
	** Checking the server endpoint <code>[base]/$versions</base></code>; note however that servers are not required to support this operation.		** Checking the server endpoint <code>[base]/$versions</base></code>; note however that servers are not required to support this operation.
Regel 138:		Regel 138:

	===FHIR Packages===		===FHIR Packages===
	The information standards maintained by Nictiz adopt the FHIR Packaging mechanism to support consistent versioning of profiles and related conformance resources such as OperationDefinitions. FHIR Packaging is based on the NPM Packaging mechanism and offers developers a convenient way to include the conformance resources in their favorite IDE. The relevant package version is indicated and linked in the information ~~standards~~ specific IG.		The information standards maintained by Nictiz adopt the FHIR Packaging mechanism to support consistent versioning of profiles and related conformance resources such as OperationDefinitions. FHIR Packaging is based on the NPM Packaging mechanism and offers developers a convenient way to include the conformance resources in their favorite IDE. The relevant package version is indicated and linked in the information standard specific IG.

	Please note that every effort has been made to ensure that the examples contained in the packages are correct and useful, but they are not a normative part of any information standard.		Please note that every effort has been made to ensure that the examples contained in the packages are correct and useful, but they are not a normative part of any information standard.
Regel 147:		Regel 147:
	* [https://blog.fire.ly/2017/11/28/versioning-and-canonical-urls/ What is the problem that packaging could address]		* [https://blog.fire.ly/2017/11/28/versioning-and-canonical-urls/ What is the problem that packaging could address]

	'''Note''': It is '''not''' required to implement FHIR based information standards using the packaging mechanism. It is still possible to download all or selected resources from Simplifier on as-needed basis. You are however encouraged to invest in dealing with packages.		'''Note''': It is '''not''' required to implement FHIR-based information standards using the packaging mechanism. It is still possible to download all or selected resources from Simplifier on as-needed basis. You are however encouraged to invest in dealing with packages.

	==Search==		==Search==
Regel 208:		Regel 208:
	; Instances without a logical id: When instances are to be created on a server or when the server doesn't support reading individual instances, they don't have a logical id. When these id-less instances need to be referenced from within a Bundle, there are two alternatives:		; Instances without a logical id: When instances are to be created on a server or when the server doesn't support reading individual instances, they don't have a logical id. When these id-less instances need to be referenced from within a Bundle, there are two alternatives:
	:* <span id="uuid-as-logical-id"></span>UUIDs can be used as single-use ids that will change each time the Bundle is generated. The {{fhir\|.fullUrl}} for the instance will be the UUID prefixed with <code><nowiki>urn:uuid:</nowiki></code>. <ref name="id-ambiguous">Some implementations may choose to populate the {{fhir\|.id}} element with the unprefixed UUID or OID in cases when the {{fhir\|.id}} field is expected, for example in searchset Bundles. The FHIR specification is ambiguous on the requirements to do so. For a long discussion on the topic, see [https://chat.fhir.org/#narrow/stream/179166-implementers/topic/Confused.20about.20URN.20fullUrl's.20and.20resource.2Eid's chat.fhir.org].</ref>		:* <span id="uuid-as-logical-id"></span>UUIDs can be used as single-use ids that will change each time the Bundle is generated. The {{fhir\|.fullUrl}} for the instance will be the UUID prefixed with <code><nowiki>urn:uuid:</nowiki></code>. <ref name="id-ambiguous">Some implementations may choose to populate the {{fhir\|.id}} element with the unprefixed UUID or OID in cases when the {{fhir\|.id}} field is expected, for example in searchset Bundles. The FHIR specification is ambiguous on the requirements to do so. For a long discussion on the topic, see [https://chat.fhir.org/#narrow/stream/179166-implementers/topic/Confused.20about.20URN.20fullUrl's.20and.20resource.2Eid's chat.fhir.org].</ref>
	:* <span id="oid-as-logical-id"></span>OIDs can be used if the instance has an OID based ''business'' identifier (i.e. the {{fhir\|.identifier}} field), like the UZI number of a healthcare provider. The {{fhir\|.fullUrl}} will be the OID prefixed with <code><nowiki>urn:oid:</nowiki></code><ref name="id-ambiguous"/><ref>The use of OIDs as id has some limitations:		:* <span id="oid-as-logical-id"></span>OIDs can be used if the instance has an OID-based ''business'' identifier (i.e. the {{fhir\|.identifier}} field), like the UZI number of a healthcare provider. The {{fhir\|.fullUrl}} will be the OID prefixed with <code><nowiki>urn:oid:</nowiki></code><ref name="id-ambiguous"/><ref>The use of OIDs as id has some limitations:
	* The {{fhir\|.id}} has a maximum length of 64 characters, so only OIDs that contain less than 64 characters can be used.		* The {{fhir\|.id}} has a maximum length of 64 characters, so only OIDs that contain less than 64 characters can be used.
	* OID based ids are expected to be stable, just like RESTful ids. Different Bundle instances SHALL always use the same OID based ids.		* OID-based ids are expected to be stable, just like RESTful ids. Different Bundle instances SHALL always use the same OID-based ids.
	* Some ''objects'' may have multiple OID based identifiers, like AGB and UZI for practitioners. Which one do you choose? And what happens when the UZI number becomes available after you've already used the AGB as {{fhir\|.id}}?		* Some ''objects'' may have multiple OID-based identifiers, like AGB and UZI for practitioners. Which one do you choose? And what happens when the UZI number becomes available after you've already used the AGB as {{fhir\|.id}}?
	* Specifically for HL7 V3 based backends: an HL7 V3 II data type normally consists of a <code>@root</code> (OID) and an <code>@extension</code> (string). Concatenation of <code>@root</code> and <code>@extension</code> only yields a new OID if <code>@extension</code> is numeric. Other combinations of <code>@root.@extension</code>, may yield a valid {{fhir\|.id}} (pattern <code>[A-Za-z0-9\-\.]{1,64}</code>), but may not be a valid OID. In this case it is no longer possible to create a {{fhir\|.fullUrl}} consistent with the {{fhir\|.id}} based the <nowiki>urn:oid:</nowiki> scheme.</ref>.		* Specifically for HL7 V3 based backends: an HL7 V3 II data type normally consists of a <code>@root</code> (OID) and an <code>@extension</code> (string). Concatenation of <code>@root</code> and <code>@extension</code> only yields a new OID if <code>@extension</code> is numeric. Other combinations of <code>@root.@extension</code>, may yield a valid {{fhir\|.id}} (pattern <code>[A-Za-z0-9\-\.]{1,64}</code>), but may not be a valid OID. In this case it is no longer possible to create a {{fhir\|.fullUrl}} consistent with the {{fhir\|.id}} based on the <nowiki>urn:oid:</nowiki> scheme.</ref>.
	: Instances within the Bundle should use the prefixed version of the UUID/OID for referencing.		: Instances within the Bundle should use the prefixed version of the UUID/OID for referencing.

← Oudere versie		Versie van 24 aug 2022 08:47
Regel 437:		Regel 437:
	** The resource is contained in another resource.		** The resource is contained in another resource.
	** It is explicitly documented in the information standard to do otherwise.		** It is explicitly documented in the information standard to do otherwise.
	* ~~Receiver~~ SHALL support the narrative. Ignoring the narrative is considered passive support. Support for the narrative SHALL be in accordance with the status and explicitly documented use in the relevant information standard.		* Receivers SHALL support the narrative. Ignoring the narrative is considered passive support. Support for the narrative SHALL be in accordance with the status and explicitly documented use in the relevant information standard.
	* ~~Receiver~~ SHALL NOT generically depend on presence of a clinically safe narrative as their only means to present data to users when an explicitly documented use case for status empty or additional exists. Also, using just the narrative you would not expect to produce graphs, support for medication alerts and other functionality.		* Receivers SHALL NOT generically depend on the presence of a clinically safe narrative as their only means to present data to users when an explicitly documented use case for status empty or additional exists. Also, using just the narrative you would not expect to produce graphs, support for medication alerts and other functionality.

	==="Clinically safe" narratives===		==="Clinically safe" narratives===
Regel 448:		Regel 448:
	The decision to what entails "clinically safe" information, is somewhat arbitrary. Guidelines for "clinically safe" inspired by the [https://hl7.org/fhir/R4/w5.html FHIR W5 report]:		The decision to what entails "clinically safe" information, is somewhat arbitrary. Guidelines for "clinically safe" inspired by the [https://hl7.org/fhir/R4/w5.html FHIR W5 report]:
	* If you only had the narrative: the intention and context should be clear to you.		* If you only had the narrative: the intention and context should be clear to you.
	* Who. Patient/subject, performer, author and/or other primary actors. Is this about family history or the actual patient.		* Who. Patient/subject, performer, author and/or other primary actors. Is this about family history or the actual patient?
	* What. The topic for the resource is clear.		* What. The topic for the resource is clear.
	* When. Is this past, present, or future information.		* When. Is this past, present, or future information?
	* Why. What led up to the event. E.g. Condition, Referral that caused Encounter or Procedure.		* Why. What led up to the event? E.g. Condition, Referral that caused Encounter or Procedure.
	* Where. Location of the event/action in the resource.		* Where. Location of the event/action in the resource.
	* Context. Relevant context as present ~~as presented~~ in the resource. status, Encounter, EpisodeOfCare, Diagnosis, Condition, BodySite.		* Context. Relevant context as present in the resource. E.g. status, Encounter, EpisodeOfCare, Diagnosis, Condition, BodySite.
	* Rendering every identifier and/or code detail may not be necessary. {{fhir\|Resource.text}} is for human assessment of the situation so emphasis should be on display text, representing identifier/code/system as relevant in the context.		* Rendering every identifier and/or code detail may not be necessary. {{fhir\|Resource.text}} is for human assessment of the situation so emphasis should be on display text, representing identifier/code/system as relevant in the context.

← Oudere versie		Versie van 24 aug 2022 07:00
Regel 182:		Regel 182:
	FHIR recognizes two fields that are used as identifier for instances: {{fhir\|.identifier}} and {{fhir\|.id}}. Although these are both identifiers, they are unrelated and serve a completely different purpose:		FHIR recognizes two fields that are used as identifier for instances: {{fhir\|.identifier}} and {{fhir\|.id}}. Although these are both identifiers, they are unrelated and serve a completely different purpose:
	* {{fhir\|.identifier}} is a business identifier, which usually has a meaning ''outside'' of the server. Examples are a registration number of a healthcare provider, a BSN or social security number for citizens, ISBNs for books, etc. Any instance may have multiple kinds of identifiers.		* {{fhir\|.identifier}} is a business identifier, which usually has a meaning ''outside'' of the server. Examples are a registration number of a healthcare provider, a BSN or social security number for citizens, ISBNs for books, etc. Any instance may have multiple kinds of identifiers.
	* {{fhir\|.id}} is the logical identifier, or technical identifier, akin to the id-field in a database. It is used as a unique handle for an instance of a given type on a particular server, and is needed to construct the URL to the instance. As such, it is used for referring between resources. The {{fhir\|.id}} has no further meaning outside of the server.		* {{fhir\|.id}} is the logical identifier, or technical identifier, akin to the id field in a database. It is used as a unique handle for an instance of a given type on a particular server, and is needed to construct the URL to the instance. As such, it is used for referring between resources. The {{fhir\|.id}} has no further meaning outside of the server.

	=== When is {{fhir\|.identifier}} expected? ===		=== When is {{fhir\|.identifier}} expected? ===
	Source systems SHALL be responsible for assigning a business identifier to every identifiable information object. Source systems SHALL have a methodology in place to guarantee global uniqueness. This business identifier is assigned to the {{fhir\|.identifier}} element of FHIR instances when sending the resource, using a {{fhir\|.system}} (e.g. an URL or [[Hoofdpagina#Object_IDentifiers_.28OIDs.29\|OID]] that is under control of the sending organization). Because in HL7v3 (CDA) an identifier can only be composed using OIDs, the {{fhir\|.system}} should preferably be an OID to accommodate compatibility in transformations from FHIR. This is especially true for resources that are used in information standards that have a HL7v3 (CDA) component, such as the BgZ, GP data and Medication process.		Source systems SHALL be responsible for assigning a business identifier to every identifiable information object. Source systems SHALL have a methodology in place to guarantee global uniqueness. This business identifier is assigned to the {{fhir\|.identifier}} element of FHIR instances when sending the resource, using a {{fhir\|.system}} (e.g. a URL or [[Hoofdpagina#Object_IDentifiers_.28OIDs.29\|OID]] that is under control of the sending organization). Because in HL7v3 (CDA) an identifier can only be composed using OIDs, the {{fhir\|.system}} should preferably be an OID to accommodate compatibility in transformations from FHIR. This is especially true for resources that are used in information standards that have an HL7v3 (CDA) component, such as the BgZ, GP data and Medication process.

	Secondary systems, that are not the source of the resource, SHALL be responsible for maintaining the business identifier assigned by the source system as they obtained it. The presence of the {{fhir\|.identifier}} element helps receiving systems with re-identification and deduplication of resources.		Secondary systems, that are not the source of the resource, SHALL be responsible for maintaining the business identifier assigned by the source system as they obtained it. The presence of the {{fhir\|.identifier}} element helps receiving systems with re-identification and deduplication of resources.
Regel 192:		Regel 192:
	As stated above, the logical id is meant to uniquely identify instances on a particular server; it is a vital component when using FHIR within a RESTful context. So as a rule of thumb, the {{fhir\|.id}} element should always be present when dealing with instances that have a logical id, thus with instances on a server. This means:		As stated above, the logical id is meant to uniquely identify instances on a particular server; it is a vital component when using FHIR within a RESTful context. So as a rule of thumb, the {{fhir\|.id}} element should always be present when dealing with instances that have a logical id, thus with instances on a server. This means:
	* When a client reads, updates or otherwise addresses an existing resource on a server, the {{fhir\|.id}} element SHALL be populated in the request and response, and it SHALL match the id in the request URL.		* When a client reads, updates or otherwise addresses an existing resource on a server, the {{fhir\|.id}} element SHALL be populated in the request and response, and it SHALL match the id in the request URL.
	* When a client sends a ''new'' instance to a server using a create operation, the ~~<code>~~id~~</code>~~ element is ''not'' expected to be present -- these new instances don't exist yet on the server, so a logical id has no meaning. However, the server SHALL assign a logical id and populate the {{fhir\|.id}} element in the response.<br/>''Note'': It is not strictly prohibited to populate the {{fhir\|.id}} field when sending a new instance, but the server SHOULD ignore it.		* When a client sends a ''new'' instance to a server using a create operation, the {{fhir\|.id}} element is ''not'' expected to be present -- these new instances don't exist yet on the server, so a logical id has no meaning. However, the server SHALL assign a logical id and populate the {{fhir\|.id}} element in the response.<br/>''Note'': It is not strictly prohibited to populate the {{fhir\|.id}} field when sending a new instance, but the server SHOULD ignore it.
	* When a client performs a search on a server, all instances in the returned searchset Bundle SHOULD have the {{fhir\|.id}} field populated.<br/>''Note'': A server SHOULD try its best to create stable ids for the resources it serves. Omitting {{fhir\|.id}} elements is strongly discouraged as it breaks the assumptions about RESTful behavior. However, a server that omits {{fhir\|.id}}s is still considered conformant when the conditions below are met:		* When a client performs a search on a server, all instances in the returned searchset Bundle SHOULD have the {{fhir\|.id}} field populated.<br/>''Note'': A server SHOULD try its best to create stable ids for the resources it serves. Omitting {{fhir\|.id}} elements is strongly discouraged as it breaks the assumptions about RESTful behavior. However, a server that omits {{fhir\|.id}}s is still considered conformant when the conditions below are met:
	*# The server does not natively support logical ids, for example when it is a stateless middleware server that gets its input from a non-FHIR backend.		*# The server does not natively support logical ids, for example when it is a stateless middleware server that gets its input from a non-FHIR backend.
	*# ''And'' the use case doesn't require read / update / delete / patch support for any of the returned of referenced resources, as stated by the CapabilityStatement for the information standard.		*# ''And'' the use case doesn't require read/update/delete/patch support for any of the returned or referenced resources, as stated by the CapabilityStatement for the information standard.
	*# ''And'' the server includes all referenced resources in searchset Bundles (regardless of whether the client asked to do so). These resources refer to each other based on the fullUrl mechanism as described below.		*# ''And'' the server includes all referenced resources in searchset Bundles (regardless of whether the client asked to do so). These resources refer to each other based on the fullUrl mechanism as described below.

	=== Logical ids, {{fhir\|.fullUrl}}s and references in Bundles ===		=== Logical ids, {{fhir\|.fullUrl}}s and references in Bundles ===

	There are several FHIR operations, like searching or batch create operations, where multiple instances are placed together in a Bundle. These instances will usually contain references to each other. These internal references cannot be resolved simply by inspecting the {{fhir\|.id}} element of every instance; it is not guaranteed that all instances have a logical id. Instead, Bundles allow an {{fhir\|entry.fullUrl}} element for each instance which may be used for references. This is an additional mechanism to the logical id, not a replacement:		There are several FHIR operations, like searching or batch create operations, where multiple instances are placed together in a Bundle. These instances will usually contain references to each other. These internal references cannot be resolved simply by inspecting the {{fhir\|.id}} element of every instance; it is not guaranteed that all instances have a logical id. Instead, Bundles allow an {{fhir\|.entry.fullUrl}} element for each instance which may be used for references. This is an additional mechanism to the logical id, not a replacement:
	* The [[#When_is_id_expected.3F\|guidelines above]] for populating the {{fhir\|.id}} field still apply.		* The [[#When_is_id_expected.3F\|guidelines above]] for populating the {{fhir\|.id}} field still apply.
	* If {{fhir\|.id}} is present, {{fhir\|.fullUrl}} SHALL correspond with it (see below).		* If {{fhir\|.id}} is present, {{fhir\|.fullUrl}} SHALL correspond with it (see below).
Regel 208:		Regel 208:
	; Instances without a logical id: When instances are to be created on a server or when the server doesn't support reading individual instances, they don't have a logical id. When these id-less instances need to be referenced from within a Bundle, there are two alternatives:		; Instances without a logical id: When instances are to be created on a server or when the server doesn't support reading individual instances, they don't have a logical id. When these id-less instances need to be referenced from within a Bundle, there are two alternatives:
	:* <span id="uuid-as-logical-id"></span>UUIDs can be used as single-use ids that will change each time the Bundle is generated. The {{fhir\|.fullUrl}} for the instance will be the UUID prefixed with <code><nowiki>urn:uuid:</nowiki></code>. <ref name="id-ambiguous">Some implementations may choose to populate the {{fhir\|.id}} element with the unprefixed UUID or OID in cases when the {{fhir\|.id}} field is expected, for example in searchset Bundles. The FHIR specification is ambiguous on the requirements to do so. For a long discussion on the topic, see [https://chat.fhir.org/#narrow/stream/179166-implementers/topic/Confused.20about.20URN.20fullUrl's.20and.20resource.2Eid's chat.fhir.org].</ref>		:* <span id="uuid-as-logical-id"></span>UUIDs can be used as single-use ids that will change each time the Bundle is generated. The {{fhir\|.fullUrl}} for the instance will be the UUID prefixed with <code><nowiki>urn:uuid:</nowiki></code>. <ref name="id-ambiguous">Some implementations may choose to populate the {{fhir\|.id}} element with the unprefixed UUID or OID in cases when the {{fhir\|.id}} field is expected, for example in searchset Bundles. The FHIR specification is ambiguous on the requirements to do so. For a long discussion on the topic, see [https://chat.fhir.org/#narrow/stream/179166-implementers/topic/Confused.20about.20URN.20fullUrl's.20and.20resource.2Eid's chat.fhir.org].</ref>
	:* <span id="oid-as-logical-id"></span>OIDs can be used if the instance has an OID-based ''business'' identifier (i.e. the {{fhir\|.identifier}} field), like the UZI number of a healthcare provider. The {{fhir\|.fullUrl}} will be the OID prefixed with <code><nowiki>urn:oid:</nowiki></code><ref name="id-ambiguous"/><ref>The use of OIDs as id has some limitations:		:* <span id="oid-as-logical-id"></span>OIDs can be used if the instance has an OID based ''business'' identifier (i.e. the {{fhir\|.identifier}} field), like the UZI number of a healthcare provider. The {{fhir\|.fullUrl}} will be the OID prefixed with <code><nowiki>urn:oid:</nowiki></code><ref name="id-ambiguous"/><ref>The use of OIDs as id has some limitations:
	* The {{fhir\|.id}} has a maximum length of 64 characters, so only OIDs that contain less than 64 characters can be used.		* The {{fhir\|.id}} has a maximum length of 64 characters, so only OIDs that contain less than 64 characters can be used.
	* OID based ids are expected to be stable, just like RESTful ids. Different Bundle instances SHALL always use the same OID based ids.		* OID based ids are expected to be stable, just like RESTful ids. Different Bundle instances SHALL always use the same OID based ids.
Regel 272:		Regel 272:
	<entry>		<entry>
	<!-- The newly created instance gets the logical id "5678" from the server -->		<!-- The newly created instance gets the logical id "5678" from the server -->
	<fullUrl value="http://example-xis.com/~~QuestionnaireResponse~~/5678"/>		<fullUrl value="http://example-xis.com/Observation/5678"/>
	<resource>		<resource>
	<Observation>		<Observation>
Regel 294:		Regel 294:
	...		...
	<valueReference>		<valueReference>
	<!-- Reference to ~~the relative URL of~~ the created instance may be relative -->		<!-- Reference to the created instance may be relative -->
	<reference value="Observation/5678"/>		<reference value="Observation/5678"/>
	</valueReference>		</valueReference>

← Oudere versie		Versie van 24 aug 2022 06:46
Regel 158:		Regel 158:
	** All stated parameters and modifiers SHALL be used for searching as specified in the information standard.		** All stated parameters and modifiers SHALL be used for searching as specified in the information standard.
	* A client MAY use additional search parameters in the search (such as date-range) not defined in the information standard. These may serve to further constrain the result set.		* A client MAY use additional search parameters in the search (such as date-range) not defined in the information standard. These may serve to further constrain the result set.
	* <span id="unknown_search_parameter_handling">A server MAY ignore and MAY support additional search parameters. A server SHALL report the applied parameters [https://www.hl7.org/fhir/R4/search.html#conformance in the self link] of the response and SHOULD provide additional information about the search process using an OperationOutcome in the search result Bundle (as an entry with {{fhir\|search.mode}} set to {{term\|outcome}}). A client MAY use the self link and/or OperationOutcome to inform the user, independently apply these filters to the result set, or take some other action.</span>		* <span id="unknown_search_parameter_handling">A server MAY ignore and MAY support additional search parameters. A server SHALL report the applied parameters [https://www.hl7.org/fhir/R4/search.html#conformance in the self link] of the response and SHOULD provide additional information about the search process using an OperationOutcome in the search result Bundle (as an entry with {{fhir\|.search.mode}} set to {{term\|outcome}}). A client MAY use the self link and/or OperationOutcome to inform the user, independently apply these filters to the result set, or take some other action.</span>
	* A server SHALL reject any search request that contains parameters suffixed by a modifier that the server does '''not''' support for that parameter. For example, if the server supports the name search parameter, but not the :exact modifier on the name, it should reject a search with the parameter {{fhir\|1=name:exact=Bill}}, using an HTTP 400 error with an OperationOutcome with a clear error message.		* A server SHALL reject any search request that contains parameters suffixed by a modifier that the server does '''not''' support for that parameter. For example, if the server supports the {{fhir\|name}} search parameter, but not the {{fhir\|:exact}} modifier on the name, it should reject a search with the parameter {{fhir\|1=name:exact=Bill}}, using an HTTP 400 error with an OperationOutcome with a clear error message.
	* A server SHALL NOT return information that is out of scope for the defined use case or authorization, even if the request by the client is wider than the use case.		* A server SHALL NOT return information that is out of scope for the defined use case or authorization, even if the request by the client is wider than the use case.
	* Repeating search parameters constitute a logical AND. Repeating search parameter values constitute a logical OR. Where applicable, this will be described further in the implementation guide.		* Repeating search parameters constitute a logical AND. Repeating search parameter values constitute a logical OR. Where applicable, this will be described further in the implementation guide.
Regel 169:		Regel 169:
	When a search parameter has a type of date, number or quantity, the request [https://www.hl7.org/fhir/R4/search.html#prefix uses prefixes] to control the search behavior. Unless explicitly stated otherwise, the minimum set of supported prefixes for these types is {{fhir\|eq}}, {{fhir\|gt}}, {{fhir\|lt}}, {{fhir\|ge}} and {{fhir\|le}}. For example:		When a search parameter has a type of date, number or quantity, the request [https://www.hl7.org/fhir/R4/search.html#prefix uses prefixes] to control the search behavior. Unless explicitly stated otherwise, the minimum set of supported prefixes for these types is {{fhir\|eq}}, {{fhir\|gt}}, {{fhir\|lt}}, {{fhir\|ge}} and {{fhir\|le}}. For example:
	GET [base]/Observation?date=ge2019-01-01&date=le2020-01-01		GET [base]/Observation?date=ge2019-01-01&date=le2020-01-01
	~~Searches~~ on all Observation resources that have an {{fhir\|.effective[x]}} between January 1, 2019 and January 1, 2020.		searches on all Observation resources that have an {{fhir\|.effective[x]}} between January 1, 2019 and January 1, 2020.

	===Search results===		===Search results===
	====Including referenced resources====		====Including referenced resources====
	It is possible that servers do not support read interactions, but all references from search results need to be resolvable (see [[#Use of the reference data type]]). Therefore servers MAY choose to include the referenced resources in the ''searchset'' Bundle, even if the client didn't use any ~~<code>~~_include~~</code>~~ parameters. These resources SHALL have ~~<code>~~Bundle.entry.mode~~</code>~~ set to ~~"''~~include~~''"~~. Servers SHOULD NOT use contained resources for this purpose.		It is possible that servers do not support read interactions, but all references from search results need to be resolvable (see [[#Use of the reference data type]]). Therefore servers MAY choose to include the referenced resources in the {{term\|searchset}} Bundle, even if the client didn't use any {{fhir\|_include}} parameters. These resources SHALL have {{fhir\|Bundle.entry.search.mode}} set to {{term\|include}}. Servers SHOULD NOT use contained resources for this purpose.

	====Paging====		====Paging====