Requesting content uploads

Version 1.1.0, 2023-05-08

Preamble

The SU-TermServ is responsible for the maintenance of a instance of Ontoserver, which is currently hosted via the University of Cologne. Access is regulated through a contract.

Resources are added to the server after a reasonable user request. As the server is hosted for all customers within the MII and the NUM, it must be clear why any resource is needed on the server. It is not possible for customers to upload resources themselves, and all resources added will need to go through the appropriate channels.

The server deployed at the site is an instance of the Ontoserver program by CSIRO, a HL7-FHIR based terminology server. As such, all resources need to be valid FHIR resources (CodeSystem, ValueSet, ConceptMap, NamingSystem, StructureDefinition).

CDS vs other resources

There is an inherent division in the way resources are treated. Most of the requirements stated below are only enforced for resources that are created outside of the MII Core Dataset packages. The CDS governance is currently subject to change, and, going forward, further development of the CDS will be subject to the same naming conventions that this document is based on.

Applicability of these rules to the resources

The following rules only apply to resources that you define yourselves. This will principally be ValueSet and ConceptMap resources, as well as some CodeSystems. In many cases, CodeSystems will be defined by other organizations or projects. If these resources are available as FHIR resources, they SHALL NOT be included in your package, but rather be brought in through the NPM package dependency mechanism. If this is not possible and you need to include a foreign resource in your package, the metadata of the resource MAY deviate from these naming conventions.

Requesting versions of SNOMED CT and LOINC

In your request, state the version of SNOMED CT that you require. Versions of SNOMED CT look like this: 20230831. If you are using a different edition, you will also need to provide the identifier for the edition. For LOINC, state the version ID, which looks like this: 2.73.

Send your request for upload to [email protected].

Requesting FHIR resources to be added

Note about FHIR R5

While CodeSystem and ValueSet are compatible betwen FHIR R4 and R5, ConceptMap has undergone significant changes in FHIR R5. While currently only FHIR R4 is supported, this is going to change in the future. Thereafter, you will be responsible for providing a R5-compliant version of your ConceptMap.

As long as the resources you require are part of a Core Dataset of the MII, you will not need to provide the resources yourselves, and you will only need to point out which resources/modules are missing.

Send your request for upload to [email protected].

Naming & Metadata Conventions

Aside from the obvious requirement that all resources are valid FHIR R4 resources, there are some metadata requirements imposed by us.

For the metadata of all user-provided data, we ask that all metadata follow the Naming Conventions for the Creation of FHIR-Resources in the Medical Informatics Initiative, outlined in this document in the TMF SharePoint, with those rules affecting terminological resources being reproduced below.

Important distinction

Do note that the naming conventions have been developed concurrently to the MII CDS resources, and are currently not enforced for resources coming from these packages. This is subject to change, as the CDS governance will include these rules mandatorily in the future, and new versions of resources will need to be provided going forward. For new resources outside of the MII CDS, all rules below MUST already be followed.

Format

Even though XML is supported by the FHIR standard, we will only accept resources in the JSON format. This allows for the use and development of tooling for out purposes against one standard format instead of needing to support two equivalent formats.

Language

The preferred language for resources (in the description, title and name) is German, but if preferred, the use of English is legitimate.

You MAY provide translation extensions for e.g. the description, name and title to provide translations into English/German in order to improve international reusability of your resource.

This looks like this in JSON (and there is currently to our knowledge no tooling available to do this for you, so you would need to manually tweak the FHIR resource).

{
  "title": "MII CS Demo Übersetzungsdemo",
  "_title": {
    "extension": [ {
      "url": "http://hl7.org/fhir/StructureDefinition/translation",
      "extension": [
        {
          "url": "lang",
          "valueCode": "en"
        },
        {
          "url": "content",
          "valueString": "MII CS Demo Translation demo"
        }
      ],  
      } ]
    }
}

Profiles

For CodeSystem/ValueSet resources, your resources SHALL be compliant with these profiles

  • http://hl7.org/fhir/StructureDefinition/shareablecodesystem (documentation)
  • http://hl7.org/fhir/StructureDefinition/shareablevalueset (documentation)

These require the following elements mandatorily: url, version, expermimental, title, description, caseSensitive

Prefixes

In the following, we will define a number of prefixes for resource types that are used throughout this specification:

Prefix ResourceType
PR StructureDefinition for profiles
CS CodeSystem
VS ValueSet
CM ConceptMap
SM StructureMap
NS NamingSystem

For more prefixes, consult the specification in the TMF SharePoint.

Abbreviations for projects and project namespaces

The naming scheme was originally written for resources that are part of the MII CDS, and require that the resources make clear which team is responsible for the resource. Since you will also be responsible for updating the resource, you will need to make clear which project they belong to. You will need to create a short mnemonic for your project to use in many different places of the metadata. Here are some examples from the document:

official module name in CDS technical module name abbreviation
Modul Diagnose modul-diagnose Diagnose
Modul Laborbefund modul-labor Labor
Modul Intensivmedizin modul-icu ICU

The technical module name would be used in the url, while the abbreviation would be used in title, name and id.

The project SU-TermServ might feasibly use su-termserv for the technical module name, and SU-TermServ for the abbreviation.

With this said, the CDS guidelines also expect a project namespace. For CDS modules, this is simply MII. For NUM projects, this would reasonably be NUM.

For other collaborations not covered here, a new identifier SHALL be created as needed.

There is no central registry for these identifiers, but in the future, special tooling might be developed to provide insights into the resources on the server. Hence, we ask that all abbreviations are intuitive and consistent, to allow for interpretable visualisations and so on.

Filenames

As the filename, the name in Upper_Snake_Case with the file extension .json SHALL be used.

Metadata elements

title

The title is a human readable name for the resource. It allows for spaces, special characters like Umlauts (make sure you use UTF-8 though!).

  • Structure: <Project namespace> <Prefix ResourceType> <Abbreviation Project> <Description Content> [<Further info>]
  • Example for CS: MII CS Mikrobio Mikrobiologische Erreger (Bakterien, Pilze)
  • For VS, also include the used terminology though an appropriate abbreviation. If no name is obvious, leave it out or use lokal: MII VS Mikrobio Mikrobiologische Erreger (Bakterien, Pilze) [SNOMED CT]
  • For ConceptMap, reference the source and target terminology: MII CM Mikrobio Mikrobiologische Erreger (Bakterien, Pilze) [LOINC -> SNOMED CT]
  • VS & CM: If multiple source/target terminologies are referenced, separate them using commas.

name

The name is a machine-readable name for the resource. The same rules apply as for title, but Upper_Snake_Case SHALL be used.

Example: MII_VS_Mikrobio_Mikrobiologische_Erreger_Bakterien_Pilze_SNOMEDCT

id

The id is a logical identifier for the resource. It will be part of the physical URL the resource will be available as after the upload.

The FHIR specification has explicit rules about the format of IDs, represented by this regex: [A-Za-z0-9\-\.]{1,64}. This means:

  • all characters need to be US-ASCII
  • The only special characters are the hyphen - and the dot .
  • The length of the string is limited to be 64.

Hence, the id SHALL be chosen using the same pattern as the name, but with all underscores _ to be replaced by hyphens -. If the generated ID is longer than 64 characters, you MUST truncate it as needed to reach this hard limit imposed by the FHIR standard. Please consider in doing so that a longer ID close to the limit will often be more clear than one that has been truncated quite severely.

Example: mii-vs-mikrobio-mikrobiologische-erreger-snomedct (49 characters)

If you need concurrent access to different versions of the same resource via the FHIR terminology operations, you MUST adapt the ID format. Otherwise, the resource will be overwritten during an update resp. upload of a new package version (see below), and will only be accessible using FHIR’s vread mechanism.

In this case, the last characters of the ID SHALL represent the version string, separated by a hyphen -. This might necessitate further abbreviation of the ID pattern described above.

Example: mii-vs-mikrobio-mikrobiologische-erreger-snomedct-1.0.1-alpha1 (62 characters, here utilizing SemVer)

Canonical URLs und version

The version should not be featured in the url. Use the above rule for generating the ID without the versioning information to generate an ID used in the url.

url

The canonical URL is the one and only authoritative identifier for the resource.

Danger

In FHIR, all definitional resources, such as CS, VS, CM, StructureDefinitions, … have at least two URLs attached: the canonical URL, and the physical URL(-s) that the resource is available from on the network. It is BAD PRACTICE to reference resources by one of their physical URLs, as those are subject to changes. When implementing any kind of tooling against any kind of terminology server, reference resources by their canonical URL.

Note

The canonical URL doesn’t need to resolve to an authoritative version of the resource, but it is considered GOOD PRACTICE if it does. You may be interested in the Simplifier integration for canonical claims.

For the structure of canonical URLs, the rules in the MII’s naming convention are quite specifically tailored to resources within the MII CDS. Moreover, changes to canonical URLs that have been in use by other processes carry a significant burden in required changes with them. Hence, we only make recommendations here, and you MAY choose any globally unique URL instead.

The MII requires the following structure (at least for new resources)

https://www.medizininformatik-initiative.de/fhir/<technical module name>/<resource type>/<id of the resource>

If no dependencies to your resources exist yet, this might serve as a good starting point. For a ConceptMap defined by the SU-TermServ project, this might be a URL following that pattern:

https://mii-termserv.de/fhir/su-termserv/ConceptMap/sutermserv-cm-demo-map-snomedct-icd10gm

OIDs SHALL NOT be used as the canonical URL of FHIR resources, as they are not human readable. OIDs MAY be included in the identifier attribute with identifier.system set to urn:ietf:rfc:3986, and the OID in identifier.value prefixed with urn:oid:.

Example for OID identifiers:

{
  "identifier": [{
    "system": "urn:ietf:rfc:3986",
    "value": "urn:oid:0.4.0.127.0.16.1.1.2.1"
  }]
}

version

To make the version interpretable by Ontoserver, two formats are allowable, and you MAY chose either depending on your preference:

  1. Use the date of publication in the format YYYYMMdd (e.g. 20230131)
  2. Use the Semantic Versioning specification (e.g. 1.0.0 < 2.0.1-alpha < 1.0.1-rc < 1.0.1)

You MAY also indicate which versioning algorithm is used by your resource using a new element in FHIR R5, versionAlgorithm, with values chosen from(https://hl7.org/fhir/ValueSet/version-algorithm)[http://hl7.org/fhir/ValueSet/version-algorithm]. But this is not required.

Note

It is likely that Ontoserver will also support the other versioning algorithms in that ValueSet in the future, but to keep things simple, use one of two ways of representing versions above.

description

The description MUST be filled due to the CS/VS profile; here you may add detailed information about the provenance of the resource, the use case, etc.

In these elements, you MAY add further information about your resource.

For copyright, the use of the SPDX License Identifiers is advised.

In publisher, you should include the long name of your project; concrete contact detail, perhaps even for specific people should be provided via the contact element.

meta.tag

Using the tag element, workflow-specific information can be added to FHIR resources.

We have defined resources for this purpose that are made available per NPM package and on the server instance:

  • CodeSystem with canonical https://mii-termserv.de/fhir/su-termserv/CodeSystem/mii-cs-suts-resource-tags-project (physical, expansion): This tag defines the broad project namespace.
  • CodeSystem with canonical https://mii-termserv.de/fhir/su-termserv/CodeSystem/mii-cs-suts-resource-tags-dataset (physical, expansion): This tag defines that a resource belongs to a certain dataset.

You MAY add these tags as required to your resources. We reserve the right to add tags to your resources ourselves, since they allow for a relatively straightforward implementation of tooling that semantically groups resources.

If in these resources a value is missing that you require, please get in touch so that the CS can be updated appropriately.

You MAY of course add more than one tag with the same URL, and add any other tags that you require.

Packaging of resources

Resources to be uploaded (except for SNOMED CT and LOINC, see above) SHALL be bundled as a FHIR Package and made publicly available. The upload of “secret” resources is not desired by us.

Package requirements

It is not necessary to create a new package only with your terminological resources alongside your real ImplementationGuide. If you desire to do so anyways, this is acceptable, however, you are then also responsible for maintaining synchronicity between the terminology package and the “real” publication/IG.

If you do create a specific upload for publication by us to the central Ontoserver, you do not need to create a ImplementationGuide for that, but you may desire to do so anyway.

Packages will only be uploaded in their entirety, i.e. we will not remove certain terminological resources from the package if requested to do so.

Resources SHALL be, until further notice, made compatible with FHIR R4 resp. R4B, until better tooling support for R5 ConceptMap exists. For CS and VS the specification between R4 and R5 is identical, so that no changes to those resources will be required.

In your request to the SU-TermServ, please provide the link to the public package in the desired version.

Package distribution options

Simplifier.net

You MAY create a project and associated package on the Simplifier.net authoring and collaboration platform. This may require a paid license. For the creation of such a package you may refer to the documentation of Simplifier.

Via the official FHIR Registry

HL7 International also hosts a registry. The burden to get your package into this registry seems rather high, unless using Simplifier.net. Please refer to the documentation of the registry for more details.

Via the GitLab Package Registry

GitLab provides a facility for distributing both public (and private) NPM packages using project-specific registries. We have prepared a template repository that documents how a package can be created using this approach. Please refer to the README in the repo linked above, as well as the GitLab documentation for the NPM registry.

This option does not incur costs to you, as the repository needs to be public.

Via the GitHub Package Registry

In the same fashion as GitLab, GitHub also provides the facility to distribute NPM packages. Please refer to the GitHub documentation as well as the GitLab template mentioned above.

Versioning and updates

When you update your package, please send a new request via e-mail. We will not act on our own accord to update resources.

If you do not state that concurrent access to multiple resource versions is required, only the requested versions are uploaded, and no resources are deleted. If you do remove a resource from a package version, the previous version of that resource from the previous package version will remain available on the server. If you do desire deletion of this resource, please communicate this accordingly.

Please also keep in mind that if you do require multiple versions of the same resource on the server, you will need to adapt the id, c.f. above.

Since the server is FHIR-based, older resource versions with the same ID will always remain available using the vread mechanism. This is a requirement by FHIR and can not be circumvented. This also applies to “deleted” resources. Until the server is redeployed with a fresh database, which me may decide to do at any time without previous anouncement during routine maintenance/downtime, deleted resource versions remain accessible.

Deviations from these rules

If you need central access to resources that are maintained outside of your responsibility, you can also request the upload of the respective package. In your e-mail, please state a reason why you need these resources for your project.

Those resources MAY deviate from the naming conventions, but we reserve the right to modify name, id, title previous to the upload to bring them more in-line with the other resources on the server. version and url will of course not be modified.

This excemption still requires that resources are available via FHIR packages.

Support

Should you require assistance in the creation of resources and packages, you can reach out to the SU-TermServ team via e-mail or Zulip.

Release Notes

  • 1.1.0 (2024-05-08): Use the name as the filename
  • 1.0.0 (2023-11-06): Initial version