FHIR:Vprepub-1.0 FHIR Profiling Guidelines R4 - Bewerkingsoverzicht

Pieter Edelman: Issue #286: Guidance on mapping identity's

2022-11-08T10:21:03Z

Issue #286: Guidance on mapping identity's

← Oudere versie		Versie van 8 nov 2022 10:21
Regel 99:		Regel 99:
	Any StructureDefinition that profiles a Resource does so because there is some kind of logical definition ''dictating'' how. Profiles SHALL have a traceable relationship with their functional counterpart(s).		Any StructureDefinition that profiles a Resource does so because there is some kind of logical definition ''dictating'' how. Profiles SHALL have a traceable relationship with their functional counterpart(s).

	The FHIR specification contains several solutions for this problem, [http://hl7.org/fhir/conceptmap.html ConceptMap] (>=STU1), [http://hl7-fhir.github.io/structuredefinition.html StructureMap] (>=STU3), [http://hl7.org/fhir/elementdefinition-definitions.html ElementDefinition.mapping]. Neither of these solutions are mature and cover our use case.		The FHIR specification contains several solutions for this problem, [http://hl7.org/fhir/conceptmap.html ConceptMap] (>=STU1), [http://hl7-fhir.github.io/structuredefinition.html StructureMap] (>=STU3), [http://hl7.org/fhir/elementdefinition-definitions.html {{fhir\|ElementDefinition.mapping}}]. Neither of these solutions are mature and cover our use case.

	* ConceptMap: works best for value sets and codes.		* ConceptMap: works best for value sets and codes.
	* StructureMap: overcomplicated and unclear how to apply and whether or not this has a future.		* StructureMap: overcomplicated and unclear how to apply and whether or not this has a future.
	* ElementDefinition.mapping: is a free text mapping ''inside'' the profile. This means we cannot add mappings to profiles from third parties without updating their resource.		* {{fhir\|ElementDefinition.mapping}}: is a free text mapping ''inside'' the profile. This means we cannot add mappings to profiles from third parties without updating their resource.

	===Current implementation===		===Current implementation===

	We use the mapping elements in profiles to map functional ~~elements~~ to resource elements. ~~Functional elements are referenced based on their id in the functional model~~. ~~The~~ mapping SHALL resolve to a description of the functional model. For zibs, this SHOULD be the English page on zibs.nl.		We use the {{fhir\|StructureDefinition.mapping}} and {{fhir\|ElementDefinition.mapping}} elements in profiles to map functional concepts to resource elements. The following rules apply:
			* The mapping {{fhir\|.mapping.uri}} SHALL resolve to a description of the functional model:
			** For zibs, this SHOULD be the English page on zibs.nl.
			** For functional models in ART-DECOR, this SHOULD be the link to the dataset on ART-DECOR v3 in the format of <q>[host]/ad/#/[prefix]/datasets/dataset/[dataset id]/[dataset effectiveDate]</q>
			* The {{fhir\|.mapping.identity}} should be a constructed in the following way:
			** For zibs, this SHOULD be the <q>zib-[English zib name, lowercased]-v[version]-[publication]EN</q>
			** For functional models in ART-DECOR, this SHOULD be, all in lowercase, <q>[project prefix][dataset name]-[dataset effectiveDate as 'yyyymmdd']</q>. The dataset name SHOULD be the English name if available, otherwise it SHOULD be the Dutch name. All spaces are replaced by dashes. If the project prefix and dataset name are similar, it's better to not repeat it and simply use 'dataset'.
			* The {{fhir\|.mapping.name}} should be constructed in the following way:
			** For zibs, this SHOULD be <q>zib [English zib name]-v[version]([publication]EN)</q>
			** For functional models in ART-DECOR, this SHOULD be <q>ART-DECOR Dataset [dataset name] [dataset effectiveDate]</q>. The dataset name SHOULD be the English name if available, otherwise it SHOULD be the Dutch name. If the dataset name contains the word 'dataset', it SHOULD not be repeated.
			* Functional concepts are referenced based on their id in the functional model, which should be used to populate {{fhir\|.mapping.map}}.
			* The description of the functional concept is ''normally'' placed in {{fhir\|.mapping.comment}}, unless other rules apply (see [[#References that are reversed in FHIR]]).
			* When slicing, the mapping is made on the ''content'' of the slice, not the slice itself (see also [[#Placing-Info]]).

	~~When slicing, the mapping is made~~ on ~~the ''content'' of the slice, not the slice itself (see also [[#Placing-Info]]).~~		So on the root of the StructureDefinition, the mapping for a zib should be defined as:

	On the root ~~element~~ of the StructureDefinition, the mapping should ~~thus~~ be defined as:
	<syntaxhighlight lang="xml">		<syntaxhighlight lang="xml">
	<mapping>		<mapping>

Pieter Edelman: 168: Document how to handle errors in the functional definition

2022-10-24T14:52:46Z

168: Document how to handle errors in the functional definition

← Oudere versie		Versie van 24 okt 2022 14:52
Regel 133:		Regel 133:

	Note that [[#Mandatory FHIR elements without a functional counterpart\|implicitly mapped elements]] and [[#References that are reversed in FHIR\|reversed references]] use a slightly different {{fhir\|comment}}.		Note that [[#Mandatory FHIR elements without a functional counterpart\|implicitly mapped elements]] and [[#References that are reversed in FHIR\|reversed references]] use a slightly different {{fhir\|comment}}.

			==Handling errors, proposed changes and omissions in the functional model==

			Conformance resources which are based on a functional model SHOULD faithfully represent the functional model. This implies that errors in the functional model ''cannot'' be fixed in the FHIR implementation unless it's really trivial; doing so would lead to a difference between the FHIR implementation and the functional model, resulting in unclear and hard to use specifications.

			Practically, this results in the following guidelines:
			<ul>
			<li>If the error is fixed on the functional level, it is adopted in the conformance resources.</li>
			<li>If an error is trivial AND recognized as something that will be fixed on the functional level, it can be adopted (e.g. spelling mistakes).</li>
			<li>In any other case, the error will be implemented as-is in the conformance resources. This includes the following cases:<ul>
			<li>The error is not recognized as something that needs to be fixed.</li>
			<li>The error is recognized as something that needs to be fixed, but the fix has to wait until the next version.</li>
			</ul><p>The error is documented using a hyperlink to the ticket in the suitable element, usually the {{fhir\|.comment}} field of the relevant profile element.</p>
			<p>Note: if the error prevents the creation of the conformance resources, then the functional model is deemed unimplementable and no conformance resources are created.</p>
			</ul>

			Omissions in the functional model are handled like any other error, with one important exception: if extra information is needed ''in order to'' create an implementation (like a code for a functional concept), and this information will be added to a future version of the functional model, it makes sense to already adopt it for the current implementation. This addition is documented with a reference to the relevant ticket.

			===For zibs specifically===
			For zibs specifically, these guidelines are practically fulfilled in the following way.

			* For any error found in the functional model, a BITS ticket is created in the ZIB project.
			** If the ticket results in an erratum, the fix is adopted without notice.
			** If the error is not recognized, or won't be fixed until the next (pre-)release:
			*** If the conformance resources can be made, the error is documented with a hyperlink to the BITS ticket in the suitable element, usually the {{fhir\|.comment}} field of the relevant profile element.
			*** If the conformance resources cannot be made, this is documented in the release notes using a hyperlink to the BITS ticket.
			*** (Only) if the error pertains something trivial like a spelling mistake AND will be fixed in a future release, it is adopted without any notice.
			* For missing definition codes, a BITS ticket is created in the ZIB project.
			** If the tickets results in a definition code, it is implemented in the conformance resource. The {{fhir\|.comment}} field of the element containing the code will document the code using the following remark: <q>This code aligns with the future version of this zib. See [BITS ticket]</q> for details.<q>, where [BITS ticket] should be a Markdown formatted hyperlink to the relevant ticket with the ticket key as title text.

	=Versioning=		=Versioning=

Pieter Edelman: FIX: spelling mistake

2021-12-23T10:47:56Z

FIX: spelling mistake

← Oudere versie		Versie van 23 dec 2021 10:47
Regel 174:		Regel 174:
	* For CodeSpecification extension slices, [[#Handling_conflicts_with_base_bindings\|a custom rule applies]].		* For CodeSpecification extension slices, [[#Handling_conflicts_with_base_bindings\|a custom rule applies]].

	Slices follow the convention of FHIR elements in general, using a camelCased name starting with a lowercase letter. If the slice name represents or starts with an abbreviation, ~~the~~ the entire abbreviation should be lowercased (e.g. 'bsn' instead of 'BSN').		Slices follow the convention of FHIR elements in general, using a camelCased name starting with a lowercase letter. If the slice name represents or starts with an abbreviation, the entire abbreviation should be lowercased (e.g. 'bsn' instead of 'BSN').

	=ValueSet binding=		=ValueSet binding=

Pieter Edelman: FIX: spelling mistake

2021-12-23T10:04:02Z

FIX: spelling mistake

← Oudere versie		Versie van 23 dec 2021 10:04
Regel 66:		Regel 66:
	Concepts in a functional description oftentimes refer to each other; e.g. most clinical concepts will refer to the concept of a Patient. In FHIR these connections are realized using the reference datatype, which allow to specify the target (base resource of profile) as well. For example, a profile representing the zib Problem could set the target of the {{fhir\|.subject}} element to the profile representing the zib Patient.		Concepts in a functional description oftentimes refer to each other; e.g. most clinical concepts will refer to the concept of a Patient. In FHIR these connections are realized using the reference datatype, which allow to specify the target (base resource of profile) as well. For example, a profile representing the zib Problem could set the target of the {{fhir\|.subject}} element to the profile representing the zib Patient.

	However, setting the target explicitly means a restriction of the allowed targets, which runs counter to the principles of open world modelling. On the other hand, specifying a dedicated profile provides useful guidance on how to handle this profile. To address both concerns, the target profile will be added next to the base resource.For example, the Condition resource allows Patient and Group as target in the {{fhir\|.subject}} element. When profiling the zib Problem, ~~the~~ the profile representing the zib Patient will be added as a third option.		However, setting the target explicitly means a restriction of the allowed targets, which runs counter to the principles of open world modelling. On the other hand, specifying a dedicated profile provides useful guidance on how to handle this profile. To address both concerns, the target profile will be added next to the base resource.For example, the Condition resource allows Patient and Group as target in the {{fhir\|.subject}} element. When profiling the zib Problem, the profile representing the zib Patient will be added as a third option.

	=Functional model as base=		=Functional model as base=

Pieter Edelman: Issue 185: Add guidance on the use of .condition

2021-12-17T12:20:46Z

Issue 185: Add guidance on the use of .condition

← Oudere versie		Versie van 17 dec 2021 12:20
Regel 413:		Regel 413:
	* For elements that bind ValueSets:		* For elements that bind ValueSets:
	** If there is a ConceptMap, {{fhir\|.binding.description}} will be: <q>Use ConceptMap [ConceptMap.name] to translate terminology from the functional model to profile terminology in ValueSet [ValueSet.name]</q>		** If there is a ConceptMap, {{fhir\|.binding.description}} will be: <q>Use ConceptMap [ConceptMap.name] to translate terminology from the functional model to profile terminology in ValueSet [ValueSet.name]</q>
			* For elements that are (directly or indirectly) included in a custom constraint defined elsewhere:
			** The keys of all related constraints are added to {{fhir\|.condition}} (note: this is thus not necessary when the constraint is defined on the element itself). Because {{fhir\|.condition}} is added to notify the implementer that a constraint applies to the usage if this element, this rule applies to both the element directly mentioned in the constraint as well as its child element(s) that contain the mapping to the functional model.

	===ConceptMaps===		===ConceptMaps===

Pieter Edelman: Add guidance about references to zib MedicalDevice

2021-12-17T09:56:32Z

Add guidance about references to zib MedicalDevice

← Oudere versie		Versie van 17 dec 2021 09:56
Regel 478:		Regel 478:

	The reason for this is that even though the subject is assumed, when it is not explicitly defined, no formal mapping can be made to a profile. On the other hand, it can be assumed that the subject will be modeled explicitly once the zib is used in a use case scenario,		The reason for this is that even though the subject is assumed, when it is not explicitly defined, no formal mapping can be made to a profile. On the other hand, it can be assumed that the subject will be modeled explicitly once the zib is used in a use case scenario,

	===Referencing zib HealthProfessional===		===Referencing zib HealthProfessional===
	[https://zibs.nl/wiki/HealthProfessional-v3.5(2020EN) Zib HealthProfessional] is mapped onto two profiles: one on FHIR resource PractitionerRole (zib-HealthProfessional-PractitionerRole) and one on FHIR resource Practitioner (zib-HealthProfessional-Practitioner). The PractitionerRole resource covers the recording of the location and types of services that HealthProfessionals are able to provide for a HealthcareProvider, whereas the Practitioner resource captures the personal information, including the identifiers of the health professional.		[https://zibs.nl/wiki/HealthProfessional-v3.5(2020EN) Zib HealthProfessional] is mapped onto two profiles: one on FHIR resource PractitionerRole (zib-HealthProfessional-PractitionerRole) and one on FHIR resource Practitioner (zib-HealthProfessional-Practitioner). The PractitionerRole resource covers the recording of the location and types of services that HealthProfessionals are able to provide for a HealthcareProvider, whereas the Practitioner resource captures the personal information, including the identifiers of the health professional.
Regel 490:		Regel 491:

	To ensure consistent documentation of this mechanism, the profile {{Simplifier\|http://nictiz.nl/fhir/StructureDefinition/pattern-HealthProfessionalReference}} has been created.		To ensure consistent documentation of this mechanism, the profile {{Simplifier\|http://nictiz.nl/fhir/StructureDefinition/pattern-HealthProfessionalReference}} has been created.

			===References to zib MedicalDevice===
			There are quite a few zibs that reference zib MedicalDevice. In FHIR, this association is implemented using a reversed reference ''from'' the DeviceUseStatement resource representing zib MedicalDevice (zib-MedicalDevice). However, because of the high number of references, the guidelines described in [[#References_that_are_reversed_in_FHIR]] would result in a chaotic collection of slices defined in the zib-MedicalDevice profile. Therefore, a slightly adapted approach has been chosen for this profile:
			* There's a single slice defined for ''all'' the zib MedicalDevice references: {{fhir\|DeviceUseStatement.reasonReference:zibMedicalDeviceReference}}.
			* The {{fhir\|.short}} of this slice is fixed on <q>zib MedicalDevice reference</q> instead of a concatenation of all the target profiles.
			* Similarly, the {{fhir\|.definition}} and {{fhir\|.comment}} carry a general explanation about the use of this slice.
			* For each zib referring zib MedicalDevice:
			** The profile is added to this list of target profiles (needs to be overwritten with the nl-core version in the nl-core layer).
			** The mapping is added (with the "Reversed reference" line as specified in [[#References_that_are_reversed_in_FHIR]]).
			** The Dutch name is added as {{fhir\|.alias}} (as specified in [[#References_that_are_reversed_in_FHIR]]).

			Profiles that derive from zib-MedicalDevice in the context of a particular zib (like zib HearingFunction and zib VisualFunction) cannot re-use this slice for their own reference (the target profile is not derived from one of the profiles listed in the resource). Therefore, they should set the cardinality of this general slice to 0..0 and define their own reference slice.

	=Data type mapping=		=Data type mapping=

Pieter Edelman: Add guidance about adding implicit subject references on the nl-core layer

2021-12-17T09:28:44Z

Add guidance about adding implicit subject references on the nl-core layer

← Oudere versie		Versie van 17 dec 2021 09:28
Regel 470:		Regel 470:

	==Zib 2020 specific considerations==		==Zib 2020 specific considerations==
			===Implicit subject reference===
			Starting from release 2020, zibs oftentimes do not explicitly define their subject, i.e. who or what the information is about. However, the general guideline for zibs is that they capture healthcare information about a patient. So implicitly there ''is'' a subject, and this subject is usually a patient -- although in some cases it might be inferred that the subject is something or someone else, or can be more than just a patient.

			The following guidelines apply for profiling a zib without an explicit subject:
			* In the zib profiles, the subject will ''not'' be modeled explicitly.
			* In the nl-core profiles, the subject ''will'' be modeled as a reference to the relevant nl-core profile.

			The reason for this is that even though the subject is assumed, when it is not explicitly defined, no formal mapping can be made to a profile. On the other hand, it can be assumed that the subject will be modeled explicitly once the zib is used in a use case scenario,
	===Referencing zib HealthProfessional===		===Referencing zib HealthProfessional===
	[https://zibs.nl/wiki/HealthProfessional-v3.5(2020EN) Zib HealthProfessional] is mapped onto two profiles: one on FHIR resource PractitionerRole (zib-HealthProfessional-PractitionerRole) and one on FHIR resource Practitioner (zib-HealthProfessional-Practitioner). The PractitionerRole resource covers the recording of the location and types of services that HealthProfessionals are able to provide for a HealthcareProvider, whereas the Practitioner resource captures the personal information, including the identifiers of the health professional.		[https://zibs.nl/wiki/HealthProfessional-v3.5(2020EN) Zib HealthProfessional] is mapped onto two profiles: one on FHIR resource PractitionerRole (zib-HealthProfessional-PractitionerRole) and one on FHIR resource Practitioner (zib-HealthProfessional-Practitioner). The PractitionerRole resource covers the recording of the location and types of services that HealthProfessionals are able to provide for a HealthcareProvider, whereas the Practitioner resource captures the personal information, including the identifiers of the health professional.

Pieter Edelman: Issue 73: document Attachment as proper datatype for ED

2021-11-15T14:29:47Z

Issue 73: document Attachment as proper datatype for ED

← Oudere versie		Versie van 15 nov 2021 14:29
Regel 498:		Regel 498:
	\| {{datatype\|boolean}} \|\| {{datatype\|BL}} \|\| {{datatype\|boolean}} \|\|		\| {{datatype\|boolean}} \|\| {{datatype\|BL}} \|\| {{datatype\|boolean}} \|\|
	\|-		\|-
	\| {{datatype\|blob}} \|\| {{datatype\|ED}} \|\| {{datatype\|base64Binary}} \|\|		\| {{datatype\|blob}} \|\| {{datatype\|ED}} \|\| {{datatype\|base64Binary}} or {{datatype\|Attachment}} \|\|
	\|-		\|-
	\| {{datatype\|code}} \|\| {{datatype\|CD}} \|\| {{datatype\|CodeableConcept}} or {{datatype\|coding}} or {{datatype\|code}} \|\| In general, {{datatype\|CodeableConcept}} will be the right choice. See [http://hl7.org/fhir/terminologies.html Using Codes in Resources] for details.		\| {{datatype\|code}} \|\| {{datatype\|CD}} \|\| {{datatype\|CodeableConcept}} or {{datatype\|coding}} or {{datatype\|code}} \|\| In general, {{datatype\|CodeableConcept}} will be the right choice. See [http://hl7.org/fhir/terminologies.html Using Codes in Resources] for details.

Pieter Edelman: Issue 186: Add guidance on how to handle references that are reversed in FHIR

2021-11-02T10:28:12Z

Issue 186: Add guidance on how to handle references that are reversed in FHIR

@@ Regel 132: / Regel 132: @@
 </syntaxhighlight>
-Note that [[#Mandatory FHIR elements without a functional counterpart|implicitly mapped elements]] use a slightly different {{fhir|comment}}.
+Note that [[#Mandatory FHIR elements without a functional counterpart|implicitly mapped elements]] and [[#References that are reversed in FHIR|reversed references]] use a slightly different {{fhir|comment}}.
 =Versioning=
@@ Regel 229: / Regel 229: @@
 On occasion, FHIR requires an element to be populated while the functional model doesn't specify it. For example, the Procedure resource has the required element {{fhir|Procedure.status}}, but the zib Procedure, which is mapped to this FHIR resource, doesn't specify such a field.
-In these circumstances, an effort should be made to map the zib concepts implictly to these elements. For example, FHIR {{fhir|Procedure.status}} can be inferred from the zib concept ProcedureEndDate; if it is in the past, then the status should be assumed to be completed. If it is not possible to make such an implicit mapping, the FHIR element is left as-is; the implementation guide should describe how the implementer should deal with it, probably using the data-absent-reason extension.
+In these circumstances, an effort should be made to map the zib concepts implicitly to these elements. For example, FHIR {{fhir|Procedure.status}} can be inferred from the zib concept ProcedureEndDate; if it is in the past, then the status should be assumed to be completed. If it is not possible to make such an implicit mapping, the FHIR element is left as-is; the implementation guide should describe how the implementer should deal with it, probably using the data-absent-reason extension.
 Implicit mappings are documented in the following way:
@@ Regel 235: / Regel 235: @@
 * The {{fhir|mapping}} element is populated with the mapped concept, but the description is altered to: <q>[concept name] (implicit, main mapping is on [element name])</q>.
 * Other metadata ({{fhir|.definition}}, {{fhir|.short}}, {{fhir|.alias}}) isn't populated according to the normal guidelines.
 =Practical guidelines=

Pieter Edelman: Issue 66: add the guidance that the Concept section from the zib doesn't always need to be copied verbatim

2021-10-26T13:24:38Z

Issue 66: add the guidance that the Concept section from the zib doesn't always need to be copied verbatim

← Oudere versie		Versie van 26 okt 2021 13:24
Regel 328:		Regel 328:
	* description:		* description:
	** For profiles:		** For profiles:
	*** For zib profiles: the 'Concept' section from the zib.		*** For zib profiles: the 'Concept' section from the zib. When the profile represents just a part of a zib and the 'Concept' section does not cover the actual use of the profile, a relevant excerpt or an adaptation should be used.
	*** For nl-core profiles: copy the description from the zib profile.		*** For nl-core profiles: copy the description from the zib profile.
	*** For standard specific profiles: as applicable.		*** For standard specific profiles: as applicable.