# Proposal for WGM evening session on post-package-publication-patterns

## Overview/Background
The current IG Publisher has a dependencies section that indicates what packages are required by the IG.
https://www.hl7.org/fhir/packages.html#2.1.10.2

"dependencies": {
  "hl7.fhir.r5.core": "5.0.x"
}

Due to the way that this is defined, it is only able to declare a single version of a dependent IG.
> Note: there are several *special* version values that include `current` and `dev`

This definition prevents an IG from declaring a dependency on multiple versions, such as USCore 3.1.1 and 6.0.1

### Resolving resource canonical references
FHIR Resources inside the IG can refer to other resources via canonical references, which may be versioned, or unversioned. An unversioned canonical reference implies that the "current" should be used according to the `versionAlgorithm` specified in the resource among those loaded in the current context.
This current context is not well defined by the FHIR specifications at this time.

> *The resource doesn't indicate what IG it comes from, let alone what IG a dependency should come from. However there is a new extension that can indicate the container that a resource came from (if was loaded from an IG).*

A common practice among many IGs is to fully re-version all canonical content in the package to the same as the package itself. The major exception to this rule is the THO package which only changes the version of a resource when it's content changes.

> There were some discussions floating about that during the build of an IG it *could* update all canonicals to be to the explicit version that they were to during the build, or could even be done through tooling (such as uploadfig) during deployment time. This is also the expected content of a proposed package.lock file.

## Notes

Package.lock file?
REQUIRE versioned canonicals inside packages
UploadFIG could POC tying that down

Package format needs a way to depend on multiple versions
Alias approach doesn't help using the canonical in the resources - that's worse

Update the dependencies format to permit multiple versions in the same string (comma seperated?)

## Alias approach
Update the tooling to permit including multiple IGs via an alias.
Would this also require some change to canonical references too?

## Package.lock approach
How would this be different to just marking all canonical references in the package with explicitly versioned canonicals?

## Known workaround
The current workaround that "just works(tm)" is to create and upload another IG that has no content of it's own, but does define a dependency on the desired IG itself.
This could have a package ID that has the same package ID as the desired target one, with a suffix of the specific version eg:

{
    "name": "hl7.fhir.us.core-3.1.1",
    "version": "1.0.0",
    "type": "IG",
    "date": "20240401",
    "license": "CC0-1.0",
    "canonical": "http://hl7.org/fhir/us/core-3.1.1",
    "title": "US Core Implementation Guide indirect v3.1.1",
    "description": "The US Core Implementation Guide v3.1.1 indirect versioned dependency",
    "dependencies": {
      "hl7.fhir.us.core": "3.1.1"
    },
    "author": "HL7 International - Cross-Group Projects",
    "jurisdiction": "urn:iso:std:iso:3166#US"
  }

This format doesn't require a change to any of the tool chain, however does require publishing of this stub package to the registry(s).
However the sushi compiler doesn't currently handle transitive dependencies.

# Consolidated Canonical Service

One issue during resolution today is the addition of the 'package' concept, which FHIR servers did not previously have. Many implementers consider packages to be a publication/tooling artifact and that they should not need to deal with them.

This causes a disconnect because now canonical resolution can have intertwined dependencies with package resolution.

One revised approach to resolving canonical URLs is to have a service that does resolution. The concept would be to have a service that:
* receives canonical artifacts either individually or via packages
* resolves versioned canonical URLs by providing the resource
* resolves unversioned canonical URLs by providing the 'current' resource
* If canonicals are uploaded via packages, the 'most recent' package version is current, regardless of canonical versioning
* If canonicals are uploaded individually, version algorithm changes are resolved by order precedence in definition date/times
* Is it worth proposing an update to version algorithm to include a start date/time?
* can provide the entire 'chain' of definitional artifacts
* E.g., asking for 'profile foo' can provide the canonical of 'foo', the canonical of 'bar' that it is defined on, and the canonical resource definition for the resource
* can provide sets of artifacts based on definitional package (e.g., all artifacts defined in US Core 3.1.1)

This process simplifies resolution for clients because they can always resolve in a single request and do not need to inject the concept of packages into their code.

## Impacts

### Publication

For publication tooling, this approach could either be ignored or added to tooling. If used in tooling, package dependencies would no longer be strictly necessary - the dependency tree would be built on individual artifacts in that case.

If that approach is taken, either a 'scan' step or an explicit list in the IG would be preferred. In either case, there is then an explicit tree of dependencies *per canonical artifact*.

### Implementation

At implementation time, canonical resolution is simplified. If a server needs access to a particular version of US Core Patient, they can simply resolve it. If they want the entire tree of canonicals it depends on, they can request that in a single call as well.

Implementations would be expected/encourage/required to cache these definitions. E.g., fail requests for the same data from the same client in too-close of a period.

### Cost analysis

TODO: fill in details.

Back-of-the-napkin estimate was at or under $20.00 USD per month, but had a lot of assumptions. Need to document and try to get detailed usage numbers.

-----

3 -> 7
US Core 3.0.1
US Core 3.0.2
US Core 3.1.0
US Core 3.1.1
US Core 4.0.1
US Core 5.0.0
US Core 6.1.0
US Core 7.0.0

MyPatient :: US Core Patient 6.1.0
? https://build.fhir.org/ig/HL7/fhir-extensions/StructureDefinition-structuredefinition-compliesWithProfile.html
- US Core 3.1.1
- Canada Base 1.0.0
- AU Base 1.0.0

US Core 7.0.0 as USCore
US Core 6.1.1 as USCoreOld
US Core 3.1.0 as USCoreOlder

HRex Organization - https://hl7.org/fhir/us/davinci-hrex/StructureDefinition-hrex-organization.html
- One Of:
- US Core 6.1.0 Organization
- US Core 3.1.1 Organization
- https://www.hl7.org/fhir/us/core/StructureDefinition-us-core-organization.html

MyProfile :: HRexOrganization
- complies with: US Core 6.1.0
- or -
- complies with: US Core 3.1.1

Look at NPM Peer dependencies