FHIR Chat · FHIR NPM packages · implementers

Stream: implementers

Topic: FHIR NPM packages

Kesara Liyanage (Oct 25 2018 at 19:26):

Has anyone worked with FHIR NPM packages and have any insight on how it can be used to have more systematic Implementation Guides? Are there examples of FHIR NPM packages?

Ewout Kramer (Oct 26 2018 at 12:07):

Hi Kesara, this is very new technology - but the R4 publication tool and IG builder will now create these NPM packages. Also, materials hosted on http://simplifier.net can be exported as a package. @Martijn Harthoorn has a link to some demo materials.

I don't know exactly what you mean with "systematic", but packages solve versioning issues. It makes resolution of references from one (conformance)resource to another unambiguous in terms of to which version you are referring. More details can be found here: https://simplifier.net/organization/firely/news/55 and here https://blog.fire.ly/2017/11/28/versioning-and-canonical-urls/

Kesara Liyanage (Oct 26 2018 at 12:36):

Thanks Ewout, i was thinking of NPM Packages from the Java world. Is it possible to create the resources and value sets and profiles in a FHIR IG into an NPM Package to make them more machine readable? save development time?

Michel Rutten (Oct 26 2018 at 13:01):

Definitely, that is the intent.

Tom Pick (Oct 26 2018 at 13:04):

Thank you.

Michel Rutten (Oct 26 2018 at 13:04):

FYI you can download a free command-line tool "Torinox" from simplifier that provides a set of commands for creating and consuming FHIR NPM packages:
https://simplifier.net/downloads/torinox

Grahame Grieve (Oct 26 2018 at 13:08):

all the existing published implementation guides on hl7.org or fhir.org now have published NPM packages. Most of the tools that work with IGs now use NPM packages

Grahame Grieve (Oct 26 2018 at 13:09):

perhaps you're asking for something slightly different than that....

nicola (RIO/SS) (Oct 26 2018 at 13:09):

are we using official npm repo?

nicola (RIO/SS) (Oct 26 2018 at 13:09):

we discussed with @Michel Rutten - at least to mirror to it

Grahame Grieve (Oct 26 2018 at 13:11):

We don't have a repo strategy yet. I'm patching around not having one in the hope that we will get one. I had hoped to discuss this in Baltimore but it didn't happen.

Grahame Grieve (Oct 26 2018 at 13:11):

My preferred strategy is that we use registry.fhir.org as the master and mirror them to the npm repository

nicola (RIO/SS) (Oct 26 2018 at 13:11):

i mean this - https://www.npmjs.com/

Grahame Grieve (Oct 26 2018 at 13:12):

@Michel Rutten @Ewout Kramer @Martijn Harthoorn can we move this forward?

Martijn Harthoorn (Oct 26 2018 at 14:34):

• Our package registry on Simplifier is up-and-running. You can publish your own packages just by uploading your resources to a Simplifier project.
• Our package client Torinox (fhir command line) is ready to consume packages for validation.
• We are currently working on canonical resource resolving through packages for Simplifier online validation, snapshot generation and rendering.
• We are designing package consumption in Forge.
• With the next release of Simplifier you can upload a package file to a project.
• Torinox implements basic npm install and also some specific FHIR packaging commands, like finding packages that contain a specific canonical.

Grahame Grieve (Oct 26 2018 at 14:35):

With the next release of Simplifier you can upload an package file to a project.

Good. So we will upload all the pubished IGs as packages, and this will both update the contents of registry.fhir.org, and make the packages available on a package server?

Martijn Harthoorn (Oct 26 2018 at 14:36):

In the coming release, publishing a package is still a separate step, but we are looking into making it auto-publishable.

Martijn Harthoorn (Oct 26 2018 at 14:37):

But the update to registry.fhir.org is automatical.

Grahame Grieve (Oct 26 2018 at 14:38):

... I'm not exactly sure that that means. Focusing for now on the uploading a package generated outside simplifier... how does that work?

Martijn Harthoorn (Oct 26 2018 at 14:41):

Next week we will deploy a new version of Simplifier. Then you can just go to your Simplifier project(s), press upload, choose a package and that's it.

Grahame Grieve (Oct 26 2018 at 14:42):

can there be more than one package per project?

Martijn Harthoorn (Oct 26 2018 at 14:43):

No. We are going to treat a project as the 'editing environment' of a package.

Martijn Harthoorn (Oct 26 2018 at 14:43):

But a few weeks ago, I have already created all the projects you asked for.

Grahame Grieve (Oct 26 2018 at 14:44):

ok. thx

Martijn Harthoorn (Oct 26 2018 at 14:45):

https://simplifier.net/organization/hl7

Martijn Harthoorn (Oct 26 2018 at 14:45):

(see tab Projects)

Patrick Werner (Jan 14 2019 at 20:01):

i just downloaded a npm package from simplifier and found all examples in the package folder. According to the fhir npm spec these shouldn't be inside of the package folder. Is this a bug or is this: http://wiki.hl7.org/index.php?title=FHIR_NPM_Package_Spec not up to date?

Stefan Lang (Jan 14 2019 at 20:12):

Kind of related question: what exactly is an example? E.g. Simplifier treats Questionnaire instances as "Example of a Questionnaire", though these are definitional artifacts.

Grahame Grieve (Jan 15 2019 at 13:40):

hmm:

• It MAY contain additional content, like example resources or documentation:
• • such files SHALL not be in the package subfolder

Grahame Grieve (Jan 15 2019 at 13:40):

that's not true in true in practice

Grahame Grieve (Jan 15 2019 at 13:41):

all resources are in the \package folder, and package processors can read which types they are interested in

Patrick Werner (Jan 15 2019 at 16:10):

How will a processor than distinguish between the conformance related resources (CS,VS,Profiles) and the additional content like examples? A very theoretical edge case: A package with profiles and examples of profiles derived/conformant from the profiles.

Grahame Grieve (Jan 15 2019 at 17:10):

any difference that mattered would have to be explicit in the resource somehow

Martijn Harthoorn (Apr 04 2019 at 09:47):

Question to the community. In the package specification we have defined HL7 FHIR packages to have the following name:
hl7.fhir.core
Where the NPM version (semver) also desginates the FHIR version.
So:
FHIR STU3 -> hl7.fhir.core v3.0.1
FHIR R4 -> hl7.fhir.core v4.0.0

For people downloading - and using packages this can be confusing. Since users will assume they need the latest version.
If they are working on an STU3 project, they will get the R4 spec by accident.

My prososal would be to follow the logic that we defined for multi-version support to apply to the FHIR spec itself as well.
So:
FHIR STU3 -> hl7.fhir.core.r3
FHIR R4 -> hl7.fhir.core.r4

(in a sense: the FHIR spec is a multi-versioned IG)

Grahame Grieve (Apr 04 2019 at 10:07):

so I have decided that I actually prefer this - it solves a distribution problem for me. But it will break every tool in a single go, since they are all welded to the current arrangement - that is, my server, the validator, the toolkit, the notepad++ plug-in, the ig publisher, the canadian build process, some other internal code of mine, and I will have to republish every package

Grahame Grieve (Apr 04 2019 at 10:07):

every IG, every core package (5 of them)

Grahame Grieve (Apr 04 2019 at 10:08):

so, if we make this change: I will make it in my own time, and the eco-system will be broken for a few days. and I will fiercely oppose making any more changes like this

Grahame Grieve (Apr 04 2019 at 10:11):

and although I approve this change. I do not approve doing IGs the same - so that we have hl7.fhir.core.us.r2.1( which would actually be based on R4)

Michel Rutten (Apr 04 2019 at 11:43):

in a sense: the FHIR spec is a multi-versioned IG

Quite elegant, I like the symmetry!

I will fiercely oppose making any more changes like this

Yes. If we decide to break this, then we should do it ASAP while adoption of packages & impact of change is still limited.

Grahame Grieve (Apr 04 2019 at 12:37):

... it's not that limited already

Michel Rutten (Apr 04 2019 at 13:44):

Yes, so I suggest we make a decision ASAP.

Michel Rutten (Apr 04 2019 at 13:44):

Would you like to solicit community feedback at the WGM in Montreal?

Grahame Grieve (Apr 04 2019 at 20:27):

really, I'd rather break everything before Montreal along with the breaking changes to IG publication

Lloyd McKenzie (Apr 04 2019 at 20:40):

I'm struggling to understand the driver here. If you want the current release of FHIR, you grab 4.0.0. If you want something earlier, you grab something earlier. I don't understand the need for the switch, nor why the rationale for switching differs for the core spec vs. IGs

Morten Ernebjerg (Apr 05 2019 at 07:00):

I'm not quite convinced that this is good idea, either. From my personal "NPM intution", I would expect the different FHIR release to map to major versions of the same package. My feeling is also that the "default to latest" problem here is no worse than it already is in general. That if, if you use STU3 you still need to deliberately navigate to the right (STU3) documentation pages, use the right HAPI packages etc. So it has to be a conscious decision which, in my view, means that it's OK to expect users to also make a conscious choice of major NPM package version and fix it (though I acknowledge that there is a lot of less-than-conscious use of NPM versions out there...).

Morten Ernebjerg (Apr 05 2019 at 07:00):

Also, if the FHIR releases are in different packages, how would the versioning of those look like? E.g. would STU 3.0.1 map to hl7.fhir.core.r3 v 0.0.1 , v1.0.1, v3.0.1, or something else? I think it might unclear to the users how to compute the right FHIR version from the package name and the package version (and, conversely, which package version to get for a given FHIR version).

Martijn Harthoorn (Apr 05 2019 at 09:10):

The core problem here is that the FHIR standard does not use Semver for versioning. It was not as widely adopted then.

Martijn Harthoorn (Apr 05 2019 at 09:10):

And so it's almost impossible to correctly map FHIR versions to correct semver.

Martijn Harthoorn (Apr 05 2019 at 09:11):

A clear example is that FHIR specification 3.5 is actually a 4.0 ballot.

Martijn Harthoorn (Apr 05 2019 at 09:11):

And so if FHIR would have used semver, that would be 4.0.0-ballot-2

Martijn Harthoorn (Apr 05 2019 at 09:12):

As a result it is close to impossible and therefore misleading to communicate FHIR versions with semver.

Martijn Harthoorn (Apr 05 2019 at 09:13):

Take version 3.5a.0. That cannot even be expressed as semver.

Morten Ernebjerg (Apr 05 2019 at 09:23):

I see, I hadn't taken that whole history into consideration - that does make the single-package solution less attractive. Under the proposed new scheme, how would the versioning of the individual packages work (e.g. how would one distinguish ballot releases from technical updates etc.)?

Martijn Harthoorn (Apr 05 2019 at 09:29):

For organizations that publish their own packages it is up to them. They can use the package version as the official release version. But anyone is free to use their own release marketing. Like MacOS: Leopart, Tiger, Panther, Jaguar.

But the packages versioning standard (SemVer) is very clear, precisely defined, and limited in options.

Martijn Harthoorn (Apr 05 2019 at 09:29):

For the FHIR spec itself it's a different issue.

Martijn Harthoorn (Apr 05 2019 at 09:29):

And of course that will serve as example to others.

Martijn Harthoorn (Apr 05 2019 at 09:30):

SemVer has a very specific purpose, and that is a technical form of communication for developers and tools how to do (automatic) upgrades.

Martijn Harthoorn (Apr 05 2019 at 09:33):

It helps managing and communicating breaking changes.

Martijn Harthoorn (Apr 05 2019 at 09:36):

https://semver.org/

Martijn Harthoorn (Apr 05 2019 at 09:39):

A technical update would be either a minor 3.x.0)or a patch (3.0.x).
A ballot release can probably be seen as a pre-release. But that's open for debate.

Grahame Grieve (Apr 05 2019 at 12:24):

3.5a.0 was special. there was never a package for it

Grahame Grieve (Apr 05 2019 at 12:24):

and it's true we don't quite use semver- not for the pre-release cycle. but we do nearly use it for the actual releases

Grahame Grieve (Apr 05 2019 at 12:25):

but the pre-release versions have no approach in your scheme. that's one problem with it

Martijn Harthoorn (Apr 05 2019 at 12:25):

In which scheme?

Grahame Grieve (Apr 05 2019 at 12:26):

hl7.fhir.core.r3 - that works nice for the milestone releases - which work anyway.

Grahame Grieve (Apr 05 2019 at 12:26):

what to call what was release 3.5.0 if you want to refer to it.

Grahame Grieve (Apr 05 2019 at 12:26):

at least with the current approach it's simple - every release has a version and that's the version of the core package

Grahame Grieve (Apr 12 2019 at 08:38):

A related question to this - @Martijn Harthoorn and I are discussing the package structure for core. I am presently distributing the core package as a single big package. It's 25MB. A little of that is supporting files (xml and json schema, images) but most of it is resources

Grahame Grieve (Apr 12 2019 at 08:39):

the biggest set of resources is all the terminology.

Grahame Grieve (Apr 12 2019 at 08:39):

@Martijn Harthoorn says it's too big and slow and should be split up for ease of use. My response to that is: splitting it up makes things slower in general, not faster, since the biggest set is at the bottom of the dependency stack

Grahame Grieve (Apr 12 2019 at 08:40):

We've been talking about
.tx - all the terminologies
.types - the base structure definitions
.profiles - extensions and profiles
. api - capability statement and search parameters

Grahame Grieve (Apr 12 2019 at 08:41):

most tools will depend on the first 3. Which is nearly all the content. Which is why I think that splitting it up will be slower.

Grahame Grieve (Apr 12 2019 at 08:41):

(oh: then you have a base package that just depends on the split up packages - so the package tooling just has to fetch all the packages instead of one of them)

Grahame Grieve (Apr 12 2019 at 08:42):

and anyone thinking about this should understand: we have no process that leads to releasing one of these packages and not the others

Martijn Harthoorn (Apr 12 2019 at 09:00):

Tx. Grahame.
In detail, the proposed alternative would be to create four packages:
- hl7.fhir.r3.types
- hl7.fhir.r3.profiles
- hl7.fhir.r3.api
- hl7.fhir.r3.tx
And one meta package hl7.fhir.r3 referencing the others.
Although there are arguments for both ways, I believe that these base sets should not depend on each other. Not all tools need the actual terminology sets in order to work. And people who need the terminology, don't necessarily need the types (structure definitions).
Just like I think the DataElements should go in a different package.

Grahame Grieve (Apr 12 2019 at 11:18):

.types + .profiles must depend on .tx, since they refer to the content in there extensively. and .profiles must depend on .types for the same reason. And .api depends on them all

Grahame Grieve (Apr 12 2019 at 11:18):

even if some tools don't use them (not sure what tool can do anything useful without the terminologies)

Martijn Harthoorn (Apr 12 2019 at 11:53):

That is what you have meta packages for, right?

Lloyd McKenzie (Apr 12 2019 at 14:51):

What set of tools don't use the terminologies?

Grahame Grieve (Apr 13 2019 at 21:19):

I am currently generating hl7.fhir.core + hl7.fhir.core.gen which only contains the bits needed for code generation

Grahame Grieve (Apr 15 2019 at 12:36):

well, we're not getting a lot of feedback on this...

Michel Rutten (Apr 15 2019 at 12:53):

As an example, Forge only requires access to core StructureDefinition resources. Forge only tries to resolve external references to other StructureDefinitions (base profile, element type profiles). Specifically, Forge never resolves references to ValueSet resources. So Forge can function without the terminology definitions.
Nonetheless, it may still be useful to include core terminology definitions with Forge, as this allows modellers to select valueset references from a directory listing (instead of having to search for the correct canonical url externally, e.g. on the internet). Breaking up the packages would allow load-on-demand and decrease startup delay during the initial run.

Grahame Grieve (Apr 15 2019 at 12:57):

it's definitely a requirement to allow a user to look up on value set.

Grahame Grieve (Apr 15 2019 at 13:01):

as for load on demand... you can do load on demand without breaking the packages up. If you're only loading a subset, sure... it's quicker once. And you only ever download the core package once.... but it's slower for every other tool ...

Martijn Harthoorn (Apr 15 2019 at 13:41):

I don't really see how subsets are slower.

Martijn Harthoorn (Apr 15 2019 at 13:42):

Unless you put the same content in there that was already delivered through a different package.

Martijn Harthoorn (Apr 15 2019 at 13:42):

But that in itself is 'fighting' the package philosophy.

Michel Rutten (Apr 15 2019 at 13:50):

it's definitely a requirement to allow a user to look up on value set.

Of course. But considering that Forge currently does not actually resolve ValueSet references, there is no "hard" dependency.

Grahame Grieve (Apr 15 2019 at 20:53):

subsets are slower because you get the same content, but latencies for each pacakge instead of one

Martijn Harthoorn (Apr 16 2019 at 11:54):

I think for less than 10 sub packages that is not significant.
The upside is of course that there is more frequent intermediate feedback to the user that also summarizes to the user what he/she's going to get.

Grahame Grieve (May 08 2019 at 10:29):

a group of tool smiths talked about this last night. We will be making the change to package ids, such that fhir core packages are identified as hl7.fhir.core.r[X]. I will be making this change as soon as possible

nicola (RIO/SS) (May 12 2019 at 05:29):

github announced npm packages support https://github.com/features/package-registry

Grahame Grieve (May 12 2019 at 14:47):

Should we investigate using this?

Natasha Singh (Jun 25 2019 at 15:59):

@Martijn Harthoorn @Michel Rutten I'm exploring use of Torinox sync command to update my project files on Simplifier. However it looks like the sync --up always POSTs and never PUTs. Each time I sync --up, new resources are generated in my project even when nothing has changed in the profiles I'm uploading with sync --up. Is there a way to update and not create via Torinox?

Martijn Harthoorn (Jun 26 2019 at 09:19):

The sync command identifies based on the file name. So it should do a PUT for files that are already in the project.

Martijn Harthoorn (Jun 26 2019 at 09:21):

We can take a look, if you tell us which project.

Natasha Singh (Jun 26 2019 at 14:30):

The sync command identifies based on the file name. So it should do a PUT for files that are already in the project.

@Martijn Harthoorn
Ah I see..I could have sworn that didn't work before but I just tried uploading a few times without changing anything, and I see that it does seem to PUT for the files that already exist.

Also, I notice the Settings > Delete button is back too. So now I can delete the extra files I accidentally uploaded. Thanks :)

Martijn Harthoorn (Jun 26 2019 at 14:40):

Happy to hear that.

Patrick Werner (Jul 22 2019 at 15:49):

I have to come back to this issue:

hmm:

• It MAY contain additional content, like example resources or documentation:
• • such files SHALL not be in the package subfolder

all resources are in the \package folder, and package processors can read which types they are interested in

the wiki page still states that examples shouldn't be in package, in reality they are.
I'm still searching for a method to distinguish if a file is an example or a conformance resource. (theoretical edge use case: i have example StructureDefinitions which souldn't be used for conformance testing)

Michel Rutten (Jul 22 2019 at 15:51):

@Patrick Werner Maybe you can use the StructureDefinition.experimental property:
http://hl7.org/fhir/structuredefinition-definitions.html#StructureDefinition.experimental

Lloyd McKenzie (Jul 22 2019 at 15:52):

Examples should be in the NPM package because they might be referenced by downstream IGs

Patrick Werner (Jul 22 2019 at 16:29):

ok. But how do i know if an example is an example?

Lloyd McKenzie (Jul 22 2019 at 17:03):

Why do you care?

Patrick Werner (Jul 23 2019 at 08:26):

because i'm going to implement a package importer which takes a package and uploads it to a (modified) hapi "validate-all" FHIR server.
I only want to upload conformance related resources and skip the examples.

Oliver Egger (Jul 23 2019 at 13:18):

@Patrick Werner context provides a function, see https://github.com/ahdis/matchbox/blob/master/src/main/java/ch/ahdis/matchbox/util/IgUploadR4.java

Patrick Werner (Jul 23 2019 at 13:23):

thanks @Oliver Egger i just checked the hapi code:

 public List<MetadataResource> allConformanceResources() {
    throw new UnsupportedOperationException();
  }

seems not to be implemented yet.
Also if it was, how do you distinguish between examples and conformance resources (i don't want to rely on filenames as these could be anything.)

Grahame Grieve (Jul 24 2019 at 11:46):

the answer is that you cannot tell. I can't tell either. And that's not because I can't be bothered but because there is no fixed answer. Things that are example conformance resources may be used for real by implementers

Grahame Grieve (Jul 24 2019 at 11:46):

but the new packages should help you in this regard.... have you followed that discussion?

Patrick Werner (Jul 24 2019 at 15:35):

i agree that no one can tell and think that is a problem. The creator of a package should be able to mark resources as an example explicitly. So i can decide if i skip examples when i add a package to my fhir server conformance module.
thanks for the heads up @Grahame Grieve i haven't yet. You mean this thread: https://chat.fhir.org/#narrow/stream/179177-conformance/topic/Package.20rework ?

Grahame Grieve (Jul 24 2019 at 21:57):

yes. that thread. For an IG, there is an explicit answer - the IG resource has a marker for each resource for whether it's an example. It's in the core spec where the answer is ambiguous

Grahame Grieve (Jul 24 2019 at 21:58):

for CodeSystem, ValueSet, StructureDefinition, ConceptMap, that is. Not ambiguous for any other resource. But since we're talking about 10-15 resources, who care?

Patrick Werner (Jul 25 2019 at 15:27):

i care, and other implementers as well. i think not being explicit and loosing information from IG -> package is bad practice.
NPM package format knows "directories.example" why not put examples in a example folder (like it is described on the FHIR package spec site) and use the directories attribute in package.json to specify in which folder the examples are contained.

Alexander Zautke (Jul 25 2019 at 15:48):

As for packages created on Simplifier I suppose the issue is the same. Examples of ConformanceResources can't be put into a separate example folder as we don't have a flag to differentiate between them and "real" resources. Correct @Martijn Harthoorn ?

Alexander Zautke (Jul 25 2019 at 15:51):

I would agree with Patrick in the sense that we should at least separate example out into a separate folder for which we can know for sure that they are examples. Safes you the trouble of filtering them out in the process of importing them to a server.

Alexander Zautke (Jul 25 2019 at 15:53):

Given the new examples package, the core spec should be fine now in this regard.

Stefan Lang (Jul 25 2019 at 16:12):

I agree that examples should be distinguishable and would like to add Questionnaire and the full list of other definitional artifacts to the list of potentially ambigous resources.
So having a subfolder called "examples" may be a solution. Or, as Alex says, having a seperate package for examples.
The latter might also have advantages in that you can add examples at a later point in time without changing the actual package of conformance and terminology resources.

Patrick Werner (Jul 25 2019 at 16:23):

i like extra example packages. We then would need a propertie in the package.json to specify the kind of package

Grahame Grieve (Jul 25 2019 at 20:42):

the information is not lost in the package , you just have to parse the IG resource

Grahame Grieve (Jul 25 2019 at 20:43):

but I don't mind generated x.y.core and x.y.examples as well as x.y

Patrick Werner (Jul 26 2019 at 07:33):

the information is not lost in the package , you just have to parse the IG resource

ahhhh! Thanks for pointing that out. Just had a look at the CG IG, ig.json is part of a package. I wasn't aware of that. Probably because i was looking at Simplifier packages all the time, Simplifier doesn't include a IG resource.
@Alexander Zautke @Michel Rutten could Simplifier include a IG resource as well for this purpose?

Patrick Werner (Jul 26 2019 at 07:35):

@Grahame Grieve including the actual IG resource into the package should be mentioned here: http://wiki.hl7.org/index.php?title=FHIR_NPM_Package_Spec
I assume this is a SHALL requirement?

Alexander Zautke (Jul 26 2019 at 09:05):

On Simplifier you can create packages independently of an IG. Some implementers want to publish the profiles separately and I think that should still be valid.

Alexander Zautke (Jul 26 2019 at 09:08):

@Martijn Harthoorn might be able to come up with a solution on how to separate the examples into a different package or folder

Martijn Harthoorn (Jul 26 2019 at 14:11):

Yes. The center use case of FHIR packages is conformance resource distribution. You can publish IG's through packages, but that is basically a separate spec.

Martijn Harthoorn (Jul 26 2019 at 14:12):

And Yes. There are a lot of organizations who have a separate cadence for publishing conformance packages and their corresponding IG's.

Martijn Harthoorn (Jul 26 2019 at 14:19):

We see it as good practice to either include examples with your package or have a separate package that contains the examples.

Martijn Harthoorn (Jul 26 2019 at 14:20):

If there are a lot of examples, it becomes more logical to separate them, since consumers might want to distribute the profiles without their examples in their app or tool.

Patrick Werner (Jul 29 2019 at 08:58):

We see it as good practice to either include examples with your package or have a separate package that contains the examples.

Ok, how do i distinguish examples from non-examples? If the package contains a whole IG it is easy, but if i have a package without an IG.json containing examples and conformance resources i can't do it.
An easy fix would be to use https://docs.npmjs.com/files/package.json#directoriesexample the directories.example propertie is part of the npm spec and could be used to point to all examples...

Grahame Grieve (Jul 29 2019 at 10:10):

Or make an ig.json...

Patrick Werner (Jul 29 2019 at 11:32):

Or make an ig.json...

Yes, either way would work. As @Martijn Harthoorn pointed out, packages could be used without an IG context so they don't have an ig.json.
So we could: * make the ig.json mandatory in the FHIR package spec
or * specify examples in the package.json and include this in the package spec

Either way would work for us, but we need consensus.

Martijn Harthoorn (Jul 29 2019 at 11:34):

Can you explain your use-case?

Martijn Harthoorn (Jul 29 2019 at 11:35):

Because, adding that kind of logic, can push a burden on all package consumer software.

Patrick Werner (Jul 29 2019 at 11:36):

I want to upload/integrate packages into hapi. If i just upload a package to the Validation Module the i would upload examples as well. Which i don't want, especially not if examples are StructureDefinitions.

Patrick Werner (Jul 29 2019 at 11:39):

Fhir packing is based on (compatible?) with NPM. NPM know example dirs: https://docs.npmjs.com/files/package.json#directoriesexample

Patrick Werner (Jul 29 2019 at 11:39):

So this could be used an be still compliant to NPM

Patrick Werner (Jul 29 2019 at 11:40):

On the other hand all the FHIR packing implementations are wrong as:

A FHIR package is a tarball (tar in gzip). The package contains

a subfolder named 'package'
a package manifest (package/package.json)
A set of conformance resource files, also in the package subfolder
It MAY contain additional content, like example resources or documentation:
such files SHALL not be in the package subfolder

Patrick Werner (Jul 29 2019 at 11:41):

http://wiki.hl7.org/index.php?title=FHIR_NPM_Package_Spec#Format

Martijn Harthoorn (Jul 29 2019 at 11:41):

In theory, we could adopt the npm example spec. But the thing is -- not only will all package creation software have to implement that. Which won't happen. But you also have to provide tooling for users to properly implement it. Which I don't see happening either.

Patrick Werner (Jul 29 2019 at 11:42):

examples are currently inside the package folder - in contrast to the FHIR package spec

Martijn Harthoorn (Jul 29 2019 at 11:47):

Good point.

Martijn Harthoorn (Jul 29 2019 at 12:01):

I agree. My proposal is: let's make it a convention to move example resources to a folder 'examples' next (on the same level as) the packages folder
Root
- Package
- Examples
And I am ok with implementing that in Simplifier.

Martijn Harthoorn (Jul 29 2019 at 12:02):

I am pretty sure that not all authors are going to properly separate them, though.

Patrick Werner (Jul 29 2019 at 12:16):

I agree. My proposal is: let's make it a convention to move example resources to a folder 'examples' next (on the same level as) the packages folder
Root
- Package
- Examples
And I am ok with implementing that in Simplifier.

sounds great. @Grahame Grieve could the IG publisher also move all examples to an extra folder?

Grahame Grieve (Jul 29 2019 at 20:38):

make me a task

Grahame Grieve (Jul 29 2019 at 20:39):

what happens for hl7.fhir.rX.examples?

Patrick Werner (Jul 30 2019 at 11:27):

everything in the FHIR example NPM packages would be under root/examples

Grahame Grieve (Aug 02 2019 at 10:29):

so

Grahame Grieve (Aug 02 2019 at 10:29):

package.tgz

Grahame Grieve (Aug 02 2019 at 10:29):

this is what we are talking about, right?

Patrick Werner (Aug 02 2019 at 11:45):

yes :+1: :tada:

Patrick Werner (Aug 02 2019 at 11:46):

do you still need a task?

Grahame Grieve (Aug 02 2019 at 12:30):

... probably not

Grahame Grieve (Aug 02 2019 at 12:31):

actually, yes. FHIR-I have to sign off on it

Patrick Werner (Aug 02 2019 at 13:16):

GF#23043]

Martijn Harthoorn (Sep 30 2019 at 15:05):

Grahame, as promised, the last bit of feedback on the current Fhir Package spec before finalizing:

- Section: Package Name:
-- the text "package name consists of one or more namespaces" - shall we make it at least two?
-- Add: "If you have packages for multiple FHIR versions, it's a best practice to add that in the package name in the form of: Rx, where x is the release version. Example: hl7.fhir.r3.core"

- Section: Versions
-- The link to SemVer (and several other links) is formatted incorrectly
-- Let's be more specific that we use semver 2 (that includes the non string based comparing)
Since we want to adhere to NPM, we should change that SHOULD to MUST follow SemVer2, since no package server can support it otherwise.
and the update and install logic of clients depend on it.

- Section: Version selection strategy
- This paragraph still contains a lot of broken sentences.

- Section: Format
- Add: "Example resources SHOULD be placed in an /examples folder. Tools working with examples, SHALL understand this."

- Section: Package manifest
- canonical - is this the canonical base?

- Section: Dependencies
-Change text to: "A fhir package SHALL have a dependency to at least one FHIR core package (hl7.fhir.r3.core, hl7.fhir.r4.core)"
we probably want some future flexibility here. So maybe replace SHALL with SHOULD.

Finally: we have implemented search in Simplifier, but differently than NPM, because it was not very helpful for FHIR.
Shall we add/discuss this later?
We currently implemented:
~/catalog
With the following optional parameters
?name=(packageid)
?canonical=
?fhirversion=2|3|4
?prerelease= true|false

Martijn Harthoorn (Sep 30 2019 at 15:05):

@Grahame Grieve

Chris Moesel (Sep 30 2019 at 15:50):

Late to the discussion (sorry)... I don't have much to add, except I noticed:
The package manifest example has this:

"web" : "http://hl7.org/fhir/us/acme/Draft1",

but the doc doesn't list web, it lists url:

url - optional = where information about the package can be found on the web

and also further down it says:

url = ImplementationGuide.manifest.rendering - required for IGs

The actual NPM package.json spec, however, defines a homepage property:

The url to the project homepage.
Example:
"homepage": "https://github.com/owner/project#readme"

Is there a reason that FHIR package.json does not use the already established homepage property?

Chris Moesel (Sep 30 2019 at 15:53):

The NPM doc also provides a way for the package.json to indicate where certain things (like docs, examples, etc) exist. It's fine for FHIR to require things like examples be in a specific location, but I wonder if we should also follow NPM guidance and list that in the directories portion of package.json?

Martijn Harthoorn (Oct 02 2019 at 11:46):

There are of course a lot of things where we implicitly follow the NPM spec. You can use any field that NPM describes. The question is does it specificying it explicitly make the experience in FHIR better.

Maybe we can follow the regular FHIR way here and see if anyone wants to actually implement it.

Martijn Harthoorn (Oct 02 2019 at 11:47):

Do you think we are explicit enough in the document that we try to to adhere to the NPM spec?

Martijn Harthoorn (Oct 02 2019 at 11:47):

(in as much as NPM is a spec)

Martijn Harthoorn (Oct 02 2019 at 11:48):

We could use the directories node for the "examples" folder, in case you put the examples outside of the package folder.

Chris Moesel (Oct 02 2019 at 12:48):

Do you think we are explicit enough in the document that we try to to adhere to the NPM spec?

I think I was mainly thrown off by the invention of web/url properties and the ignoring of the existing homepage property. If that's intentional because you want to allow homepage to point to some other location (for whatever reason), then maybe we should document that to avoid confusion. If it's not intentional though, it seems to me like if "we try to adhere to the NPM spec" then there's no good reason not to use homepage instead of web or url.

Grahame Grieve (Oct 02 2019 at 12:49):

homepage isn't the same as what we are doing, or I would have used it

Chris Moesel (Oct 02 2019 at 12:54):

OK. I think of what you're calling url/web as the home page of the IG -- but maybe that's just me. Is the intent that home page would be a page about the IG, rather than the IG itself? If so, that makes sense, but I still think we should document it so that people like me don't wonder why FHIR had to invent a new url or web property when there's already a perfectly good homepage property.

Grahame Grieve (Oct 02 2019 at 19:19):

The definition is:

The url to the project homepage

The IG is not the project home page, it's a human readable representation of the package version

Grahame Grieve (Oct 02 2019 at 19:52):

@Martijn Harthoorn

Add: "If you have packages for multiple FHIR versions

Added, but watered down, given there was already slightly different advice in the page

Version selection strategy

Apparently I added that, but I don't remember doing so. I cleaned it up

Anything I didn't comment on I accepted and changed

Grahame Grieve (Oct 02 2019 at 19:58):

I did clarify the documentation on url vs web vs package - it's url

Martijn Harthoorn (Oct 07 2019 at 09:18):

I think it looks good Grahame.
We probably want to merge the two sections about having the Rx version in the package id at some point..

Patrick Werner (Jan 20 2020 at 19:21):

just downloaded a Simplifier package. package.json is not contained in the root dir as i would have expected/it is done at npmjs.com. It is placed into the package folder.
Could this be alligned between @Grahame Grieve and @Martijn Harthoorn ? I would be in favor of doing it like the npm guys do: put it in the package root

Grahame Grieve (Jan 20 2020 at 20:02):

the specification is here:

Grahame Grieve (Jan 20 2020 at 20:02):

https://confluence.hl7.org/display/FHIR/NPM+Package+Specification

Grahame Grieve (Jan 20 2020 at 20:02):

as far as I know, we are fully aligned on this point

Grahame Grieve (Jan 20 2020 at 20:02):

from day #1 that document as said that package.json goes in /package.

Patrick Werner (Jan 20 2020 at 21:08):

i'm fine with putting it into /package or ROOT as long its aligned.

Patrick Werner (Jan 20 2020 at 21:09):

Which it is, i just realised. Didn't see the surrounding package folder of the IG produced package at first.
Sorry, my bad.

Last updated: Apr 12 2022 at 19:14 UTC