Work in progress.
This section of the Implementation Guide is subject to change.
General
- All FHIR implementations MUST comply with the HL7 FHIR standard.
- All implementations of FHIR interfaces MUST comply with the requirements outlined in the relevant release of the HL7 FHIR standards, as outlined on http://fhir.hl7.org/.
- All FHIR resources are published on a public FHIR reference server.
- All FHIR resources relating to national systems and other nationally defined FHIR API profiles (including StructureDefinitions, ValueSets, OperationDefinitions, ImplementationGuides, etc.) that are ready for external use (in either DRAFT or ACTIVE status) MUST also be made available the HL7 Estonia reference server api.fhir.hl7.ee.
- Resources that are part of the National Estonian Health System (TIS) MUST also be published on a TEHIK branded public FHIR server fhir.tehik.ee.
- Avoid FHIR Document Paradigm when possible. Use REST and Messaging Paradigms instead.
Conformance
Profiling
The FHIR standard provides a mechanism to specialise and extend FHIR resources by creating profiles.
In Estonia, profiles are developed according to the following “levels”:
In Estonia, profiles are developed according to the following “levels”:
- Level 1: The base FHIR resource profiles defined by HL7 International.
- Level 2: The ‘Estonian Base Profiles’ are Estonia-wide profiles curated through the HL7 FHIR Estonia community and published on the HL7 Estonia FHIR reference server.
- Level 3: The implementation-specific profiles for a particular system or domain.
Profiles for upTIS are published on the TEHIK FHIR Reference Server.
Profiles for Tervisekassa projects are published on the Tervisekassa FHIR Reference Server.
- Profiles MUST NOT define alternate summary fields for resources.
- All FHIR base resources have several fields defined as 'summary' fields, which appear when the client requests summary versions of the resource to be returned (for example, in search results). These summary fields can only be defined in base resources and cannot be changed in any profiles.
Versioning
- Nationally defined FHIR profiles will be versioned during development using Git, following the standard GitFlow model. The versioning for published artefacts will broadly follow semantic versioning standards. The major and minor versions will be visible, and the patch version MAY also be exposed. Version numbers held in profiles and resource instanced MUST therefore be in one of the following forms: MAJOR – e.g. 1 MAJOR.MINOR – e.g. 1.0 MAJOR.MINOR.PATCH – e.g. 1.0.2
- The version number MUST NOT be included in the profile name.
- The version number MUST be used as the profile version attribute.
Example of a version number in Estonian base Organization profile
<StructureDefinition xmlns="http://hl7.org/fhir">
<url value="http://hl7.ee/fhir/StructureDefinition/EEBase-Organization"/>
<name value="EEBaseOrganization"/>
<version value="1.0.0"/>
{
"resourceType": "StructureDefinition",
"id": "EEBase-Organization",
"url": "https://hl7.ee/fhir/StructureDefinition/EEBase-Organization",
"version": "1.0.0"
}
Naming
To promote consistency and make it easier for implementers to locate suitable profiles, extensions, value sets and others for their projects, a naming strategy will be adopted for EEBase-defined FHIR assets or FHIR assets derived from the EEBase. All EEBase-derived implementation guides and FHIR assets MUST follow these rules to claim conformace with the EEBase.
For detailed definitions of concepts discussed within this guidance document, refer to the appropriate published version of the FHIR standard.
- FHIR Profile name MUST follow an agreed format.
- The URL of a profile consists of several name segments and will be in the form:
https://[base url]/fhir/StructureDefinition/[Base]-[FHIRAssetName]-[BusinessName1]-[BusinessName2]- Base URL: The URL used for standard publishing. For example, hl7.org for HL7 International and hl7.ee for HL7 Estonia. Check the full list for details.
- Base: The provider name. EEBase for Estonian Base. Mandatory
- FHIRAssetName: The name of the base FHIR Resource. Mandatory
- BusinessNames: Business names are only used where mutiple profiles exist for a given base resource type. Optional
- No business version information is allowed in the resource URL.
- Segment names in FHIR Profile URL MUST follow Pascal case convention.
Examples
EEBase-Patient
EEBase-Patient-Unknown
EEBase-Observation-EducationLevel
RETS-MedicationRequest
EEHIF-MedicationRequest-Inpatient - Resource name: The [Base], [FHIRAssetName] and [BusinessNames] without hyphen (-) SHOULD be used as resource name.
- Resource id: The specification does not specify the form of resource id. [Base]-[FHIRAssetName]-[BusinessNames] with hyphen (-) is RECOMMENDED for this purpose.
- Title: The title of the resource MUST be the [Base], [FHIRAssetName] and [BusinessNames] with added spaces to make it human readable and understandable.
Example of EEBase Organization definition
<StructureDefinition xmlns="http://hl7.org/fhir">
<id value="EEBase-Organization"/>
<url value="http://hl7.ee/fhir/StructureDefinition/EEBase-Organization"/>
<version value="1.0.0"/>
<name value="EEBaseOrganization"/>
<title value="EEBase Organization"/>
{
"resourceType": "StructureDefinition",
"id": "EEBase-Organization",
"url": "https://hl7.ee/fhir/StructureDefinition/EEBase-Organization",
"version": "1.0.0",
"name": "EEBaseOrganization",
"title": "EEBase Organization"
}
- FHIR Extension MUST follow an agreed format.
- The URL of an Extension consists of several name segments and will be in the form:
https://[base url]/fhir/StructureDefinition/Extension-[Base]-[BusinessName]- Base URL: The URL used for standard publishing. See profile definition.
- Base: The standard provider name. See profile definition. Mandatory
- BusinessName: The business name of the Extension. Mandatory
- No business version information is allowed in the Extension URL
- Segment names in FHIR Extension URL MUST follow Pascal case convention.
- Resource name: "Extension", [Base] and [BusinessName] without hyphen (-) SHOULD be used as resource name.
- Resource id: The specification does not specify the form of resource id. "Extension", [Base] and [BusinessName] with hyphen (-) RECOMMENDED as resource id.
- Title: The title of the resource MUST be [Base] and [BusinessName], and the word "extension" with added spaces to make it human-readable and understandable.
Example of EEBase ADS extension definition
<StructureDefinition xmlns="http://hl7.org/fhir">
<url value="http://hl7.ee/fhir/StructureDefinition/Extension-EEBase-ADS"/>
<name value="ExtensionEEBaseADS"/>
<version value="1.0.0"/>
<id value="Extension-EEBase-ADS"/>
<title value="EEBase ADS extension"/>
{
"resourceType": "StructureDefinition",
"id": "Extension-EEBase-ADS",
"url": "https://hl7.ee/fhir/StructureDefinition/Extension-EEBase-ADS",
"version": "1.0.0",
"name": "ExtensionEEBaseADS",
"title": "EEBase ADS extension"
}
- FHIR OperationDefinition MUST follow an agreed format.
- The URL of an OperationDefinition consists of several name segments and will be in the form:
https://[base url]/fhir/OperationDefinition/[Base]-[BusinessName]- Base URL: The URL used for standard publishing. See profile definition.
- Base: The standard provider name. See profile definition. Mandatory
- BusinessName: The business name of OperationDefinition. Mandatory
- No business version information is allowed in the OperationDefinition URL.
- Segment names in FHIR OperationDefinition URL MUST follow Pascal case convention.
- Resource name: [Base] and [BusinessName] without hyphen (-) SHOULD be used as the resource name.
- Resource id: The specification does not specify the form of resource id. [Base] and [BusinessName] with Hyphen (-) RECOMMENDED as resource id.
- Title: The title of the resource MUST be [Base] and [BusinessName] with added spaces to make it human-readable and understandable.
Example of OperationDefinition resource definition
<OperationDefinition xmlns="http://hl7.org/fhir">
<id value="EEBase-PatientMerge"/>
<url value="https://hl7.org/fhir/OperationDefinition/EEBase-PatientMerge"/>
<version value="1.0.0" />
<name value="EEBasePatientMerge"/>
<title value="EEBase PatientMerge"/>
{
"resourceType": "OperationDefinition",
"id": "EEBase-PatientMerge",
"url": "https://hl7.org/fhir/OperationDefinition/EEBase-PatientMerge",
"version": "1.0.0",
"name": "EEBasePatientMerge",
"title": "EEBase PatientMerge"
}
- The FHIR-managed CodeSystems SHOULD use names defined by FHIR working groups.
- The FHIR-managed ValueSets SHOULD use names defined by FHIR working groups.
- Some ValueSets that use SNOMED CT will refer directly to SNOMED CT artefacts, for example, SNOMED CT Ref Sets, and there will not be a need to create a CodeSystem resource. There may be other ValueSets which follow the same principles, for example, LOINC.
- FHIR CodeSystem names MUST follow an agreed format.
- The URL of a CodeSystem consists of several segments and will be in the form:
https://[base url]/fhir/CodeSystem/[base]-[businessname1]-[businessname2] - The segments are defined as follows:
- Base URL: The URL used for standard publishing. See profile definition.
- Base: The standard provider name. See profile definition. Mandatory
- BusinessNames: The business names of the CodeSystem. The CodeSystem name MUST have at least one BusinessName segment. Where a CodeSystem MAY is used across several domains, business names SHOULD reflect that. Mandatory
- Resource name: [Base] and [BusinessNames] without hyphen (-) SHOULD be used as the resource name.
- Resource id: [Base] and [BusinessNames] in lowercase where every word is separated with a hyphen (-). The same formatting rules SHOULD be applied to the resource URL.
- Title: The resource's title MUST be [Base] and [BusinessNames] with added spaces to make it human-readable and understandable. BusinessName segment(s) of the title MAY follow Camel case convention.
Example of ArrivalMode CodeSystem definition
<CodeSystem xmlns="http://hl7.org/fhir">
<id value="eebase-arrivalmode"/>
<url value="https://hl7.ee/fhir/CodeSystem/eebase-arrivalmode"/>
<version value="1.0.0" />
<name value="EEBaseArrivalMode"/>
<title value="EEBase arrivalMode"/>
{
"resourceType": "CodeSystem",
"id": "eebase-arrivalmode",
"url": "https://hl7.ee/fhir/CodeSystem/eebase-arrivalmode",
"version": "1.0.0",
"name": "EEBaseArrivalMode",
"title": "EEBase arrivalMode"
}
- FHIR ValueSet names MUST follow an agreed format.
- The URL of a ValueSet consists of several name segments and will be in the form:
https://[base url]/fhir/ValueSet/[base]-[businessname1]-[businessname2] - The segments are defined as follows:
- Base URL: The URL used for standard publishing. See profile definition.
- Base: The standard provider name. See profile definition. Mandatory
- BusinessNames: The list of business names of the ValueSet. The ValueSet name MUST have at least one BusinessName segment. Where a ValueSet MAY be used across several domains, business names SHOULD reflect that. Mandatory
- Resource name: [Base] and [BusinessNames] without hyphen (-) SHOULD be used as the resource name.
- Resource id: [Base] and [BusinessNames] in lowercase where every word is separated with a hyphen (-). The same formatting rules SHOULD be applied to the resource URL.
- Title: The title of the resource MUST be [Base] and [BusinessNames] with added spaces to make it human-readable and understandable. BusinessName segment(s) of the title MAY follow Camel case convention
- The ValueSet name MUST be used as the ValueSet's filename.
Example of ArrivalMode ValueSet definition
<ValueSet xmlns="http://hl7.org/fhir">
<id value="eebase-arrivalmode"/>
<url value="https://hl7.ee/fhir/ValueSet/eebase-arrivalmode"/>
<version value="1.0.0" />
<name value="EEBaseArrivalMode"/>
<title value="EEBase arrivalMode"/>
{
"resourceType": "ValueSet",
"id": "eebase-arrivalmode",
"url": "https://hl7.ee/fhir/ValueSet/eebase-arrivalmode",
"version": "1.0.0",
"name": "EEBaseArrivalMode",
"title": "EEBase arrivalMode"
}
- FHIR identifier systems MUST follow an agreed format.
- The identifier systems MAY be used in the system element of the Identifier datatype. They establish the namespace for an asset's identifier.value element and have a URI datatype.
- The URL of an identifier systems consists of several name segments and will be in the form:
https://[base url]/fhir/NamingSystem/[businessname1]-[businessname2]-[businessname3]-[businessname4] - The segments are defined as follows:
- Base URL: The URL used for standard publishing. See profile definition.
- NamingSystem: The NamingSystem section of the identifier is formatted as a string 'NamingSystem'. This segment denotes that the string is an identifier system and is Mandatory.
- BusinessNames: The business name segments describe the identifier system. The first business name is Mandatory, but all subsequent ones are optional. There MAY be up to four business names each separated by a hyphen (-) character.
- Business names SHOULD be used as the logical ID in lowercase.
Example of NamingSystem definition for Estonian Address Data System (ADS)
<NamingSystem xmlns="http://hl7.org/fhir">
<id value="ads-id"/>
<url value="https://hl7.ee/fhir/NamingSystem/ads-id"/>
<version value="1.0.0" />
<name value="ADSID"/>
{
"resourceType": "NamingSystem",
"id": "ads-id",
"url": "https://hl7.ee/fhir/NamingSystem/ads-id",
"version": "1.0.0",
"name": "ADSID",
}
Resource identifiers
- Resource IDs MUST be generated only by FHIR server.
- Business ID-s MUST NOT be used as the resource ID.
- References between ReST resources SHOULD be literal references without FHIR server path but MAY be logical references.
- When using the FHIR ReST Paradigm, resources SHOULD reference other resources via URL (i.e. a literal reference in the FHIR standard). The resource owner should (where possible) only reference other resources that they can be relatively confident consumers of their API will be able to resolve and retrieve. For referencing other things outside this, a logical reference SHOULD be used.
- Note: URL references to other resources will (by default) return the latest version of the referenced resource. If this isn’t desirable, the resource owner may either contain the resource or use a versioned URL as a literal reference.
- References in FHIR messaging SHOULD be logical references.
- When using the FHIR Messaging Paradigm, messages will likely include references to external resources. These references SHOULD use an identifier from a known NamingSystem. This is known as a logical reference in the FHIR standard. The NamingSystem URI SHOULD be searchable on a FHIR Reference server to return the NamingSystem resource that describes the identifiers used (for example, https://fhir.hl7.ee/NamingSystem).
Publishing
- The Github repository for Estonian FHIR Base is https://github.com/HL7EE/ee-fhir-base.
- All FHIR resources relating to national systems and other nationally defined FHIR API profiles (including StructureDefinitions, ValueSets, OperationDefinitions, ImplementationGuides and others) MUST be held on a publicly available GitHub repository which MAY be synchronised with a Simplifier project.
- Comments, feedback and suggestions from developers on FHIR resources (and associated documentation) SHOULD be managed through Simplifier using the standard features for raising and tracking issues on the Simplifier ee-base project.
- All FHIR resource URIs must be resolvable URLs.
- All FHIR resources relating to national systems and other nationally defined FHIR API profiles (including StructureDefinitions, ValueSets, OperationDefinitions, ImplementationGuides and others) MUST have a URI that is a resolvable URL. Usually, this will be the URL of the resource on the FHIR API reference server (hl7.ee/fhir).
Serialization
- FHIR ReST APIs MUST support JSON serialisation and SHOULD also support XML serialisation.
- All FHIR ReST endpoints MUST support JSON formatted requests/responses.
- FHIR ReST endpoints SHOULD also support XML formatted requests/responses.
- The serialisation mime-types supported MUST be declared in the Conformance/CapabilityStatement resource for the endpoint, and the server MUST use the usual FHIR mechanisms to allow clients to request a specific Content Type as per the FHIR spec (servers may choose to reject the use of XML if it is not supported).
- Namespaces outside those defined in the FHIR specification MUST NOT be used.
- The FHIR standard specifies a specific namespace for FHIR XML elements, with a second namespace for XHTML content in narrative sections. Those specifying FHIR APIs MUST not use other namespaces in their APIs.
FHIR operations
- Where a request maps to a standard FHIR operation, the standard operation SHOULD be used.