MM-1457 FHIR IG - Bewerkingsoverzicht

Pieter Edelman: MM-1454: Change SHALL to SHOULD for inclusion of resource.id, and add guidance on the usage

2020-10-19T07:51:37Z

MM-1454: Change SHALL to SHOULD for inclusion of resource.id, and add guidance on the usage

Pieter Edelman: MM-1457:Add transclusion tags

2020-10-13T19:28:46Z

MM-1457:Add transclusion tags

Pieter Edelman: MM-1457:Add transclusiong tags

2020-10-13T19:24:37Z

MM-1457:Add transclusiong tags

Pieter Edelman: MM-1457: Generalize from MedMij

2020-10-13T19:21:01Z

MM-1457: Generalize from MedMij

Pieter Edelman: MM-1457: Generalize from MedMij

2020-10-13T19:20:01Z

MM-1457: Generalize from MedMij

Pieter Edelman: MM-1457: Generalize from MedMij

2020-10-13T19:11:14Z

MM-1457: Generalize from MedMij

Pieter Edelman: /* Content Types and encodings */

2020-10-13T19:01:16Z

‎Content Types and encodings

Pieter Edelman: MM-1457: Generalize from MedMij

2020-10-13T19:00:30Z

MM-1457: Generalize from MedMij

Pieter Edelman: MM-1457: Create a short, generalized introduction for the FHIR IG

2020-10-13T18:58:32Z

MM-1457: Create a short, generalized introduction for the FHIR IG

Pieter Edelman: MM-1457: Duplicate relevant parts of the MedMij IG

2020-10-13T18:47:00Z

MM-1457: Duplicate relevant parts of the MedMij IG

Wijzigingen bekijken

@@ Regel 180: / Regel 180: @@
 FHIR recognizes two fields that are used as identifier for instances: <code>id</code> and <code>identifier</code>. Although these are both identifiers, they are unrelated and serve a completely different purpose:
 * <code>id</code> is the logical identifier, or technical identifier, akin to the id-field in a database. It is used as a unique handle for every instance on a particular server, and is needed to construct the URL to the instance. As such, it is used for referring between resources. The <code>id</code> has no further meaning outside of the server.
-* <code>identifier</code> is a business identifier, which 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.
+* <code>identifier</code> 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.
 This section is about the <code>id</code> field and more general about the concept of a logical/technical id to identify instances on a server. The usage of the <code>identifier</code> field, i.e. the business identifier, cannot be described in general terms and will be dictated one a use-case basis by the particular profiles.
@@ Regel 187: / Regel 187: @@
 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 <code>id</code> element should always be present when dealing with instances that have a logical id, thus with instances on a server. This means:
-* Any operation where an existing instance on the server is addressed, like reading or updating, ''needs'' a logical id to target said instance for the URL. In these cases, <code>id</code> field SHALL be populated in both the request and the response, and it SHALL match the id in the URL.
+* When a client reads, updates or otherwise addresses an existing resource on a server, the <code>id</code> 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, but the server SHALL populate it in the response. This is because upon sending, these new instances don't exist yet on the server, so a logical id has no meaning. But whenever it is created on the server, it should get a logical id assigned by the server. (Note: it is not strictly prohibited to populate the <code>id</code> 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 <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 <code>id</code> element in the response.<br/>''Note'': It is not strictly prohibited to populate the <code>id</code> 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 SHALL have the <code>id</code> field populated. Note that in some situations, servers might not support logical id's, for example when it is a stateless middleware server that gets its input from a non-FHIR XIS backend. If this is the case ''and'' if the use case doesn't require read support, [[#uuid-as-logical-id|a single use UUID]] or [[#oid-as-logical-id|an OID]] may be used to populate the <code>id</code> field; however, a server SHOULD try its best to populate it with a meaningful value.
+* When a client performs a search on a server, all instances in the returned searchset Bundle SHOULD have the <code>id</code> field populated.<br/>''Note'': A server SHOULD try its best to create stable ids for the resources it serves. Omitting <code>id</code>s is strongly discouraged as it breaks the assumptions about RESTful behavior. However, a server that omits <code>id</code>s is still considered conformant when the conditions below are met:
 === Logical ids, <code>fullUrl</code>s and references in Bundles ===
@@ Regel 200: / Regel 203: @@
 ; Instances with a logical id: If an instance can be accessed on the server using RESTful operations, the <code>id</code> of that instance in the Bundle will be populated. The corresponding <code>fullUrl</code> in this case SHALL be the absolute URL to the instance on the server.<p>Instances within the Bundle may use relative references to each other, like they are on the same server. The FHIR machinery specifies how to find the matching instance based on the <code>fullUrl</code>.</p>
 ; 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 <code>fullUrl</code> for the instance will be the UUID prefixed with <code><nowiki>urn:uuid:</nowiki></code>, while the <code>id</code> field (if present) is the unprefixed UUID.
+:* <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 <code>fullUrl</code> 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 <code>id</code> element with the unprefixed UUID or OID in cases when the <code>id</code> 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 <code>identifier</code> field), like the UZI number of a healthcare provider. The <code>fullUrl</code> will be the OID prefixed with <code><nowiki>urn:oid:</nowiki></code>, while the <code>id</code> field (if present) is the unprefixed OID. However, 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 <code>identifier</code> field), like the UZI number of a healthcare provider. The <code>fullUrl</code> 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 <code>id</code> has a maximum length of 64 characters, so only OIDs that contain less than 64 characters can be used.
+* The <code>id</code> has a maximum length of 64 characters, so only OIDs that contain less than 64 characters can be used.
-:** OID-based id's 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.
 : Instances within the Bundle should use the prefixed version of the UUID/OID for referencing.

@@ Regel 370: / Regel 370: @@
 <section end=OverarchingPrinciples />
 =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 technical design page.
@@ Regel 380: / Regel 381: @@
 {{NoteBox|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.}}

@@ Regel 11: / Regel 11: @@
 This implementation guide 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/STU3 FHIR STU3 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.
 =Use case overarching principles=
 ==Content Types and encodings==
@@ Regel 367: / Regel 368: @@
 | [https://informatiestandaarden.nictiz.nl/wiki/MedMij:Vprepub/FHIR_Error_handling_examples#Resource_syntax_or_data_is_incorrect_or_invalid Example]
 |}
 =FHIR Packages=

@@ Regel 369: / Regel 369: @@
 =FHIR Packages=
-MedMij adopts 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 technical design page.
+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 technical design page.
 For even more background information:

@@ Regel 56: / Regel 56: @@
 {| class="wikitable"
-|+MedMij constraints on [https://hl7.org/fhir/STU3/references.html#Reference FHIR STU3 reference datatype]
+|+Constraints on [https://hl7.org/fhir/STU3/references.html#Reference FHIR STU3 reference datatype]
 ! Name !! Flags !! Card. || Type || Description & Constraints
 |-
@@ Regel 68: / Regel 68: @@
 |}
-In loosely coupled context it is usually good practice to include information rather than have systems progressively retrieve it. When the FHIR servers are in fact a facade on non-FHIR systems, it may not be possible to build external references from the resource id, as non-FHIR systems may not support that concept. Example: a resource for the general practitioner will have an AGB and/or UZI identifier in any information system, the id for the same resource might not be known anywhere. The expectation within MedMij is therefore that the vast majority of references will be based on internal references or identifier.
+In a loosely coupled context it is usually good practice to include information rather than have systems progressively retrieve it. When the FHIR servers are in fact a facade on non-FHIR systems, it may not be possible to build external references from the resource id, as non-FHIR systems may not support that concept. Example: a resource for the general practitioner will have an AGB and/or UZI identifier in any information system, the id for the same resource might not be known anywhere. The expectation is therefore that the vast majority of references will be based on internal references or identifiers.
-The basic requirements for using references in MedMij are:
+The basic requirements for using references in this context are:
 * The ''reference'', if used, SHALL be resolvable

@@ Regel 25: / Regel 25: @@
 Coded information is extremely important for interoperability between systems. It enables systems to act on information rather than have humans read everything for interpretation - it enables medication related alerts, exercise encouragements because of weight increase, and many more things. In the HCIMs and profiles, we therefore strive for complete coverage of all possible situations.
-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 now deprecated way. Therefore, it is vital that the sender includes the semantics of the code in his communication using (CodeableConcept.)[https://hl7.org/fhir/STU3/datatypes.html#coding coding.display] and/or [https://hl7.org/fhir/STU3/datatypes.html#codeableconcept CodeableConcept.text]. Although it might be overkill for the generic profiles to use these fields in closely coupled situations. Within the loosely coupled MedMij context however, systems SHOULD include .display and/or .text for coded data in FHIR instances. Both could be absent for example in historic data or in data acquired without such info from a third party.
+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 (CodeableConcept.)[https://hl7.org/fhir/STU3/datatypes.html#coding coding.display] and/or [https://hl7.org/fhir/STU3/datatypes.html#codeableconcept 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.
 ===Mapping of coded concepts===

@@ Regel 16: / Regel 16: @@
 * XML: application/fhir+xml
 * JSON: application/fhir+json
-* RDF: text/turtle - Not supported in MedMij
+* RDF: text/turtle - Not supported in this context
 Servers SHALL support both XML and JSON, while clients MAY use either format for the request and the response. For the response, servers SHALL support server-driven content negotiation as described in [https://www.hl7.org/fhir/stu3/http.html#mime-type the FHIR specification]. This means that clients can indicate the desired response format using the optional <code>_format=[mimetype]</code> URL parameter, or the acceptable response format(s) using the <code>Accept</code> header. The URL parameter takes precedence over the header. If a client does not request a specific content-type, then it is server discretion to respond using XML or JSON.

@@ Regel 6: / Regel 6: @@
 __TOC__
-=About the IG=
+=Introduction=
-This is the technical MedMij FHIR implementation guide based on '''HL7® FHIR® version STU3'''.
+This implementation guide describes the considerations for using '''HL7® FHIR®''' in context of information standards that are maintained by Nictiz. It applies specifically to HL7® FHIR® version 3 (STU3).
-==Purpose==
+This implementation guide 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/STU3 FHIR STU3 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.
 =Use case overarching principles=