Requesting content uploads

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).

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

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.

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:

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:

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)

url

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

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.

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.

copyright, publisher, contact

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