FHIR:V1.0 FHIR Profiling Guidelines R4 - Bewerkingsoverzicht

Pieter Edelman: Beveiligde "FHIR:V1.0 FHIR Profiling Guidelines R4": Protect production page from accidental edits ([Bewerken=Alleen beheerders toestaan] (vervalt niet) [Hernoemen=Alleen beheerders toestaan] (vervalt niet))

2022-11-08T10:22:37Z

Beveiligde "FHIR:V1.0 FHIR Profiling Guidelines R4": Protect production page from accidental edits ([Bewerken=Alleen beheerders toestaan] (vervalt niet) [Hernoemen=Alleen beheerders toestaan] (vervalt niet))

← Oudere versie	Versie van 8 nov 2022 10:22
(geen verschil)

Pieter Edelman: Publish prepub to live environment

2022-11-08T10:22:36Z

Publish prepub to live environment

Pieter Edelman: Gekopieerd van FHIR:Vprepub-1.0 FHIR Profiling Guidelines R4, versie 46338

2022-11-08T10:22:31Z

Gekopieerd van FHIR:Vprepub-1.0 FHIR Profiling Guidelines R4, versie 46338

← Oudere versie	Versie van 8 nov 2022 10:22
(geen verschil)

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.

← Oudere versie		Versie van 8 nov 2022 10:22
Regel 1:		Regel 1:
	~~__NOINDEX__~~
	{{DISPLAYTITLE:FHIR Profiling Guidelines for FHIR R4}}		{{DISPLAYTITLE:FHIR Profiling Guidelines for FHIR R4}}
	__NUMBEREDHEADINGS__		__NUMBEREDHEADINGS__
	=Introduction=		=Introduction=

	This page lays out the conventions for creating FHIR profiles and associated conformance resources within Nictiz. These guidelines are specifically aimed at FHIR R4; for the STU3 profiling work, [[FHIR:~~Vprepub-1~~.0_FHIR_Profiling_Guidelines_STU3\|a separate document exists]].		This page lays out the conventions for creating FHIR profiles and associated conformance resources within Nictiz. These guidelines are specifically aimed at FHIR R4; for the STU3 profiling work, [[FHIR:V1.0_FHIR_Profiling_Guidelines_STU3\|a separate document exists]].

	This page is titled "profiling guidelines", but actually addresses all conformance resources (profiles, extensions, value sets, code systems, CapabilityStatements) and associated examples. We use these terms somewhat interchangeable throughout this document; 'profile' can usually be read as 'the whole set of conformance resources'.		This page is titled "profiling guidelines", but actually addresses all conformance resources (profiles, extensions, value sets, code systems, CapabilityStatements) and associated examples. We use these terms somewhat interchangeable throughout this document; 'profile' can usually be read as 'the whole set of conformance resources'.
Regel 201:		Regel 200:

	In general, the slice discriminator is set to {{fhir\|discriminator.type}} = {{term\|value}} and {{fhir\|discriminator.path}} to the path where the discriminator value is located (if it is the root element, it should be noted as <code>$this</code>). The sliced element gets a {{fhir\|pattern}} or a {{term\|required}} ValueSet binding on the location of the path. No further cardinality constrains are added in the sliced element that correspond with the {{fhir\|pattern[x]}} as they are made mandatory by the pattern.		In general, the slice discriminator is set to {{fhir\|discriminator.type}} = {{term\|value}} and {{fhir\|discriminator.path}} to the path where the discriminator value is located (if it is the root element, it should be noted as <code>$this</code>). The sliced element gets a {{fhir\|pattern}} or a {{term\|required}} ValueSet binding on the location of the path. No further cardinality constrains are added in the sliced element that correspond with the {{fhir\|pattern[x]}} as they are made mandatory by the pattern.
	These general slicing guidelines apply to the following situations. See [[FHIR:~~Vprepub-1~~.0_FHIR_Profiling_Guidelines_R4_examples\|this page for examples in XML]]:		These general slicing guidelines apply to the following situations. See [[FHIR:V1.0_FHIR_Profiling_Guidelines_R4_examples\|this page for examples in XML]]:
	* [[#Mapping_semantic_codes_to_profiles\|Mapping semantic codes to profiles]] requires the presence of the semantic code while leaving the option to use the element for other concepts, e.g the zib LaboratoryTestResultCode profile uses {{fhir\|Observation.category}} for a sematic code that represents the zib ''and'' to map the zib concept ResultType.		* [[#Mapping_semantic_codes_to_profiles\|Mapping semantic codes to profiles]] requires the presence of the semantic code while leaving the option to use the element for other concepts, e.g the zib LaboratoryTestResultCode profile uses {{fhir\|Observation.category}} for a sematic code that represents the zib ''and'' to map the zib concept ResultType.
	* Identifier systems are always defined on a sliced {{fhir\|.identifier}}, even if there is only one defined.		* Identifier systems are always defined on a sliced {{fhir\|.identifier}}, even if there is only one defined.
Regel 225:		Regel 224:
	However, option 2 should be used if there are different requirements for the ValueSet bindings.		However, option 2 should be used if there are different requirements for the ValueSet bindings.

	Also see the [[FHIR:~~Vprepub-1~~.0 FHIR Profiling Guidelines R4 examples\|examples]].		Also see the [[FHIR:V1.0 FHIR Profiling Guidelines R4 examples\|examples]].
	==Binding strength==		==Binding strength==
	The FHIR profiles should faithfully reproduce the binding strength from the functional description. It may not always be possible to adopt the binding strength verbatim. For example, when creating slices for ValueSets, the binding strength must be set to {{term\|required}} in order to make the discriminator work, even though the binding strength in the functional description is {{term\|extensible}}. However, by making the slicing {{term\|open}}, conceptually the same result is achieved.		The FHIR profiles should faithfully reproduce the binding strength from the functional description. It may not always be possible to adopt the binding strength verbatim. For example, when creating slices for ValueSets, the binding strength must be set to {{term\|required}} in order to make the discriminator work, even though the binding strength in the functional description is {{term\|extensible}}. However, by making the slicing {{term\|open}}, conceptually the same result is achieved.

	Also see the [[FHIR:~~Vprepub-1~~.0 FHIR Profiling Guidelines R4 examples\|examples]].		Also see the [[FHIR:V1.0 FHIR Profiling Guidelines R4 examples\|examples]].
	==Handling conflicts with base bindings==		==Handling conflicts with base bindings==
	FHIR base resource might specify a {{term\|required}} binding for some of its elements, whereas the corresponding concept in the functional specification uses alternative or more specialized codes. To conform both to FHIR and to the functional description, a ConceptMap will be created to map the codes from the functional specification to the codes from the FHIR ValueSet. 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].		FHIR base resource might specify a {{term\|required}} binding for some of its elements, whereas the corresponding concept in the functional specification uses alternative or more specialized codes. To conform both to FHIR and to the functional description, a ConceptMap will be created to map the codes from the functional specification to the codes from the FHIR ValueSet. 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].