Use FHIR profiles and IG packages

What you’ll do

You load the Implementation Guide (IG) packages whose profiles your models produce, for example the International Patient Summary, or your own profiles, value sets and code systems as loose files. With the package loaded, the Workspace follows your profiles: path suggestions show profile cardinality, must-support, slices and extensions; checks report elements the profile forbids; the Profile tab counts the profile’s required and must-support elements; and validation checks the FHIR against the profile. What else a package is used for is under What Atlas uses from a package.

The FHIR packages page with the IPS package expanded, a missing dependency and a package that didn't load

The FHIR packages page after adding the IPS package.

Before you start

  • Open FHIR packages in the sidebar (under Mappings).

  • Have the package ready: its .tgz (as published on a package registry or by the IG’s build), or its id#version on packages.fhir.org. Or have the loose resources ready: StructureDefinition, ValueSet and CodeSystem .json files, Bundles of them, or a .zip of such files (for example an IG’s definitions.json.zip). Core FHIR (hl7.fhir.r4.core …) is built in; don’t add it.

  • A model’s profile is its structureDefinition, or the profile it writes into meta.profile (Start mapping a template).

Steps

1. Add a package

Under Add a package, the numbers match the screenshot above:

1 Drop files: drop npm packages .tgz, conformance resources .json or a .zip of them on the area, or click browse. You can pick several files, and drop or browse again to add more. The files are listed first; nothing is uploaded yet:

Three files listed for upload, the package name and the Upload button

A package, a StructureDefinition and a ZIP, ready to upload: leave a file out 1, the name for the loose resources 2, and Upload 3.

  • Each .tgz is stored as the package it is, up to 15 MB.

  • StructureDefinitions, ValueSets and CodeSystems (loose .json, Bundles, and the .json files in a .zip) are stored together as one package.

  • ConceptMaps go to Terminology (Manage ConceptMaps), where mappings use them.

  • Other files in a .zip (examples, a README) are skipped.

The cross next to a file leaves it out; Cancel drops them all.

Package name for the loose resources: shown when there are .json files or a .zip. Leave it empty and Atlas names the package after the .zip (local.<zip name>), else after the first profile (local.<profile name>). The package takes the first profile’s version (0.0.1 when it has none), so uploading the same resources again under the same name replaces the package. A name uses letters, digits, ., - and _.

Upload N files uploads them. When one file can’t be stored, Atlas stores none of them and says which file and why; the files stay listed so you can fix the list and upload again. Afterwards the card says what was stored:

Stored two packages, one ConceptMap added to Terminology, one file skipped

What an upload stored, and the file it skipped with the reason.

2 From packages.fhir.org: type package-id#version, for example hl7.fhir.uv.ips#1.1.0, and click Fetch. Fetch is enabled once the text has that form. This form is missing when fetching from a registry is turned off for your Atlas.

While Atlas works, the card says “Uploading …” (or “Uploading files…”) or “Fetching #…”.

2. Add what it depends on

A package needs the packages it depends on. When one isn’t loaded, Missing dependencies lists it: “Profiles from these packages (extensions, base profiles, value sets) can’t be resolved until they’re added.”

3 Fetch: fetches that dependency from the registry. Without a registry, upload its .tgz instead.

3. Check the packages

4 A package: its id, #version, the FHIR version, then the number of profiles, the size, the date it was last updated, and used by N models when models of any template produce one of its profiles. Click the chevron to see what it Depends on and its profiles: Profile (title and url), Type ((extension) for extension definitions), and Used by.

5 Used by: the models whose profile this is, across all templates.

6 not loaded: the package is stored but couldn’t be read for its FHIR version. Hover it for the reason. Its profiles aren’t used.

7 Remove package (step 4).

Refresh at the top reloads the list.

4. Remove a package

Click the trash icon of the package. Atlas asks first:

The confirmation to remove hl7.fhir.uv.ips#1.1.0

“Remove hl7.fhir.uv.ips#1.1.0? Models using its profiles fall back to base FHIR.”

What Atlas uses from a package

Atlas reads every StructureDefinition, ValueSet and CodeSystem of the loaded packages, whether uploaded, fetched from the registry or packaged from loose files:

In the package

What Atlas uses it for

Profiles and extension definitions

Path suggestions, checks, the Profile tab, + Ext, and validation (Write FHIR and openEHR paths, Find what isn’t mapped yet, Add a FHIR extension).

ValueSets and CodeSystems

Validation with Terminology checks (codes & bindings) on: codes are checked against the ValueSets they are bound to, expanded from the packages’ CodeSystems (Validate against FHIR profiles). Path suggestions show a required or extensible binding. The code systems and their codes are suggested where you write terminology: ConceptMap groups and inline rows (Suggested systems and codes).

ConceptMaps

Nothing. Mappings translate codes with the ConceptMaps on Terminology (Manage ConceptMaps): upload them as .json (here or there), not inside a .tgz.

The codes Atlas suggests for a system are its CodeSystem’s, plus the codes the packages’ ValueSets list for it. For a code system no package defines, such as SNOMED CT or LOINC, that is only the codes the ValueSets list: a ValueSet defined by a filter (is-a …) can’t be expanded in Atlas, and validation reports such a code system as unknown. Many shared ValueSets and CodeSystems are in hl7.terminology.r4; when a package depends on it, Missing dependencies offers to fetch it.

Check it worked

In the Workspace, open a model that produces one of the package’s profiles:

Without any package, the page says:

The FHIR packages page without packages

“No packages yet. Paths are checked and FHIR is validated against base FHIR only.”

Tips

Tip

Fetch by id#version when you can: Atlas then lists the package’s dependencies, and Fetch adds each missing one in a click.

Tip

For profiles of your own, drop their StructureDefinition .json files, with the ValueSets and CodeSystems they bind, in one upload. Atlas packages them together; uploading them again under the same package name and version replaces the package.

Tip

A template exported from Atlas can carry its linked packages, and uploading that ZIP on the Engine state page brings them back (Export and move mappings).

Watch out

Warning

Removing a package takes its profiles away from every model that uses them: they fall back to base FHIR for suggestions, checks, coverage and validation.

Warning

Right after a package is added or removed, Atlas reloads the profiles. Until it is done, the page says “The packages are still being loaded; their profiles appear shortly.”

The notice that the packages are still being loaded

The loading notice.

If something goes wrong

An upload’s messages start with the file they are about.

Message

What to do

<file>: packages are limited to 15 MB

The .tgz is bigger than 15 MB. Fetch it by id#version instead.

<file>: files are limited to 60 MB

The file is bigger than 60 MB. Split the ZIP.

<file>: not a .tgz, .json or .zip

Leave the file out.

‘<name>’ is no package name: use letters, digits, ‘.’, ‘-’ and ‘_’, for example local.my-profiles

Change the package name.

<file>: Not a FHIR conformance resource, ConceptMap or Bundle of them

The .json holds no StructureDefinition, ValueSet, CodeSystem or ConceptMap (an example instance, say). In a ZIP or among other files it is only skipped.

Expected FHIR npm packages (.tgz), conformance resources (StructureDefinition, ValueSet, CodeSystem … as .json or a Bundle), ConceptMaps, or a .zip of them

Nothing in the upload can be stored.

<zip>: Archive has too many entries (limit 1000), <zip>: Archive uncompressed size exceeds limit, <file>: Entry exceeds size limit (52428800 bytes)

The ZIP is too big. Split it.

The registry’s package is larger than 15 MB

The package on the registry is bigger than 15 MB.

<file>: The package expands to more than 200 MB / ‘’ in the package expands to more than 50 MB / The package holds more than 50000 files

The package unpacks to too much.

<file>: Not a FHIR npm package (.tgz with package/package.json): …

The file isn’t an npm package. Use the IG’s package.tgz.

Engine: …

The engine refused a file. The files before it may be stored: check the list, then upload the rest.

Core FHIR definitions are built in; don’t upload …

Leave out hl7.fhir.r4.core and the other core packages.

package.json has no name or version

The package is incomplete; get it again from its source.

# not found in ()

Check the id and version on the registry.

Could not fetch from : …

The registry couldn’t be reached; try again, or upload the .tgz.

Fetching packages from a registry is disabled

Upload the .tgz instead.

See also Missing dependencies and The FHIR packages are still loading; try again in a moment..