Technical Patterns Consideration for Pan-Canadian Guides

Requirements in pan-Canadian profiles are diligently collected (e.g., jurisdictional requirements & data dictionaries, pan-Canadian Health Data Content Framework) and validated through formal governance processes (e.g., representative working groups, public reviews, balloting) to ensure that the requirements facilitate a use case in a way that scales across Canadian geographies.

Direct use of a pan-Canadian profile within your guide is the best ways to guaranty alignment and ultimately mitigate the risk of introducing customization that will be required for vendors to support a use case in your jurisdiction.

There are considerations under which other mechanisms (e.g., re-profiling, imposeProfile, iGuide dependencies) may be helpful to assist early implementors in alignment and testing against pan-Canadian profiles. These mechanisms are can help the author anywhere from leveraging existing fully tested profiles to creating content that is closely aligned best practices in the FHIR community that helps experts test your content out more effectively and efficiently. that this section attempts to explore.

Determining Which Pattern Is Right For You

Before the creation of your jurisdictional FHIR implementation guide, we recommend the following preparation to help you optimize your ability to use of pan-Canadian artefacts:

  • Identify the use case and requirements (constraints and terminology) for the use case in your jurisdiction. This typically involves initial consultation with stakeholders followed by engagement with existing pan-Canadian efforts (e.g., pan-Canadian working groups).
  • Compare your use case and requirements against established technical artefacts (e.g., Interoperability Specifications, Reference Architecture, FHIR Implementation Guides) to inform your engagement with pan-Canadian working groups
    • Your scope of needs may already be covered by existing pan-Canadian artefacts or may reflect additional requirements that should be considered for inclusion - this preliminary analysis can help determine if additional changes to the pan-Canadian artefacts need to be introduced through the working group or a ballot
  • If the requirements are fully met by the respective FHIR profile, use the pan-Canadian profiles directly in your implementation guide. This ensures there is no divergence from the pan-Canadian standards and upholds our collective goal of promoting interoperability.
  • If there are profile-specific requirements that are not covered by the pan-Canadian profiles - determine if they can be conveyed through written requirements in your guide.
    • If the requirements can be conveyed in supplementary written requirements, proceed with direct use of the pan-Canadian profile
    • If the requirements cannot be conveyed through supplementary written requirements alone (e.g., a cardinality MUST be changed, an additional mustSupport flag must be added) - proceed to re-profiling (see below) and please raise the additional requirements to the respective working group via the working group's Infocentral forum.

Note: In most cases these additive requirements don't cause any issues, but this helps to ensure that any additional requirements or extensions are still compliant with pan-Canadian specification. It is also an opportunity to investigate and leverage the learnings from other jurisdictions (if they had similar requirements).

There are cases, particularly when a pan-Canadian specification is early in its maturity, where a jurisdiction uncovers a requirement that presents a challenge to direct use or re-profiling of a pan-Canadian profile. Examples of changes that cannot be accommodated through re-profiling are noted in the Conformance Rules for iGuide Authors. These require prioritization by the working groups to resolve with your team. Examples include:

  • Loosening the cardinality on a Required element or section slice in the specification (e.g., composition.section:Condition)
  • Prohibiting the inclusion (0..0) of Required or Must Support elements
  • Changing a binding on a value set that is Required by specification or FHIR (e.g., AllergyIntolerance Status)

When your work uncovers a need to change something in a pan-Canadian specification - follow the steps outlined on Change Request Process.

Applying Technical Mechanisms

Direct Use

Direct use involves the application of the pan-Canadian profile in your implementation guide, so it can be rendered on your implementation guide page alongside your additional jurisdictional guidance (if applicable).

Typically, the types of additional guidance that is provided in jurisdictional guides describes specific business context that is often related to integration with regional assets. Narrative guidance might exist on additional connectivity and security practices with those assets. The guides might describe specific mapping practices or business rules and policies that are relevant in that jurisdiction.

For example, a jurisdictional immunization repository may allow for the collection of estimated dateTimes when the immunization occurred. If information from this repository is expected to be utilized in the scope of the jurisdictional guide, additional details like "If immunization occurrence is indicated as estimated in the source, the estimated extension will be populated with a Boolean value of "true"" may be present. These provide the implementer with context for current business rules that govern that data they expect to receive.

An example of Direct Use of pan-Canadian profile in a jurisdictional implementation guide:

Direct-Use

How To Use

FHIR packages allow content published in other projects (e.g., pan-Canadian projects) to be accessible and renderable in your guide to enable direct use without having to re-create the StructureDefinitions. Packages are versioned, allowing you to decide which version of the pan-Canadian artefacts you would like to include. These instructions are the basis for both direct use and re-profiling.

The following instructions describe how to add the pan-Canadian guide package into your project in Simplifier.

  1. In your Simplifier project page, click the green "Manage" button under the Dependencies Tab.
  2. Use the search bar to find and select the package id, then select the version you would like to leverage. Click Add. Then Click Save.
  • Note: If you are not sure which package id and version to use, go to the pan-Canadian project and review the package details under the Packages tab.
  1. Once the package is successfully added to your project, you can use or reference the PS-CA artifacts in the markdown pages you create using the Implementation Guide Editor.

  • There are many different ways to render the profiles in your IG pages using the Simplifier syntax (e.g., Rendering Differential, Snapshot, or Hybrid views of profiles).

    • Differential rendering shows only the changes that are being made to the base resource. It includes only the elements that have been added, changed, or removed from the base resource. This rendering is often used when creating a new profile that is based on an existing profile.

    Fig. Differential View differential

    • Snapshot rendering shows the complete definition of the profile, including all elements and constraints. It is a fully expanded view of the profile that can be used for validation and implementation.

    Fig. Snapshot View Snapshot

    • Hybrid rendering combines the differential and snapshot renderings. It includes the complete definition of the profile, but highlights the changes that have been made from the base resource.

    Fig. Hybrid View Hybrid

  1. After you have added the profiles into your respective iGuide pages, you can include your additional jurisdictional details to the pages using markdown.

Re-profiling

Re-profiling allows the iGuide author to include the pan-Canadian profile as the baseDefinition for their profiles, inheriting the all aspects of the profile without having to make those changes manually within their own profiles.

Example of use: Adding PS-CA profile into StructureDefinition.basedOn to allow your profile to inherit constraints directly from PS-CA without needing to include in differential.

Re-profiling

Fig. Example of re-profiling

Informal alignment

Informal alignment is defined as adopting and using an existing guidance and enforcing your rules (such as relaxing constraints on elements) on the profiles it has.

The process for an informal alignment involves reviewing the StructureDefinition of the primary iGuide's profile, inputting its constraints manually into your profile, and surfacing any constraints that need to be relaxed in your iGuide's issue log.

Example of use: Reviewing the StructureDefinition of the PS-CA profile, inputting its constraints manually into your profile, and surfacing any constraints that need to be relaxed to PS-CA issue log.

Impose Profile Extension

Every element in a given resource can have have an extension (learn more about extensions here):

  • Both types of extensions are considered experimental and are still being defined by the community
  • This extension allows you to inherit additional conformance rules from the nominated profile
  • Impose profile extension allows for multi-inheritance without having to re-profile and it is structured (validation tooling can be used for validation concurrently)

Example of future use (proposed framework):

  • The PS-CA Patient resource is re-profiled from the International Patient Summary iguide Patient resource and applies the impose profile extension resource to point to assert the rules in CA Core patient apply.

Impose-profile-extension Fig. Inheritance of an extension into a profile

iGuide Dependencies

iGuide dependencies allow the iGuide author to reference other guides, pointing to any and all constraints (profiles, terminology, extensions) defined in those guides without having to replicate all that work within their own guide.

This technical pattern is useful when re-using national and implementation specific extensions or terminology.

Example of use: Adding PS-CA Guide into ImplementationGuide.dependsOn to allow your guide to point to PS-CA profiles, terminology, extensions, etc.

Instance Validation

Instance Validation is used for validating non-MustSupport constraints against existing specifications. This approach is usually used in a testing environment (such as Connectathons) for some quick lightweight testing.

Example of use: Adding PS-CA Profile to meta.profile element in example messages, running through validator (e.g., FHIR Validator, Simplifier validation button, etc.).

Instance-validation Fig. Process for selecting guides to validate your work against