Polaris Identifiers and References¶

This guide covers how identifiers, references, and canonical URLs work in the Polaris FHIR specification.

Identifiers¶

Most Polaris resources will have identifiers with the standard Canonical URLs for all types. This can be seen in example JSON files and FSH specifications, but in general, the format is:

{
    "identifier": {
        "system": "https://fhir.apps.health/NamingSystem/<product-instance>-<resource>-identifier",
        "value": "<EMR-assigned identifier>"
    }
}

For resources that are created by an EMR instance and have an identifier space managed by that instance (e.g. Patients, Providers, etc.), the <product-instance> will be an URI-safe string uniquely identifying the installation of the product (Juno-123, OscarPro-foobarbazClinic, etc).

NOTE: The <product-instance> MUST EXACTLY EQUAL the 'value' of the Organization resource's identifier.
So if <product-instance> == Oscar-1234, then the Organization representing that EMR installation must have system=='https://fhir.apps.health/NamingSystem/Oscar-1234-organization-identifier', value=='Oscar-1234'

For non-instance-specific resources (e.g. Organizations, StructureDefinitions, ValueSets, CodeSystems, NamingSystems), the <product-instance> will be omitted.
Polaris Applications that choose to store data in the FHIR store will also use this naming scheme, using the application name ('cpar', 'cii', etc) as the <product-instance>.

Product Instance¶

The 'product instance' URI segment represents a globally-unique installation of a piece of software. In the case of an EMR, this should be prefixed by the product name of the EMR (like Juno-423482392 or OscarPro-3939232399). In the case of another system (the Polaris FHIR store will contain data from other sources), and appropriate globally 'instance identifier' should be chosen.

The 'product instance' identifier is a crucial element in Polaris system URIs, as it ensures that product instances (who are responsible for allocating identifiers) do not need to worry about identifier collisions.

References¶

While literal references will be allowed in Polaris, it is expected that resources generated by the EMR will not know the literal FHIR ids, and will instead use logical identifiers: specifically the identifiers defined in the Identifiers section above.

So, for example, a reference looks like this:

    "identifier": {
        "system": "https://fhir.apps.health/NamingSystem/<product-instance>-<resource>-identifier",
        "value": "<EMR-assigned identifier>"
    }

Technical IDs (id field)¶

Each FHIR resource (Organization, Patient, Device) has an id field:

Automatically generated by MedPlum upon resource creation.

Do not generate or include this yourself.

Canonical URL Structure¶

The standard format for canonical URLs is defined as:

https://fhir.apps.health/[artifact-type]/[product-instance]-[artifact-id]

Where:

Base URL: https://fhir.apps.health/ This is the base URL for all FHIR artifacts.
[artifact-type]: This indicates the type of FHIR artifact (e.g., StructureDefinition, CodeSystem, ValueSet, NamingSystem, etc.).
[product-instance]: This segment represents the site-specific EMR/product instance.
It should be unique to both the EMR system name and its instance number. For example, if "clinic 12" is associated with OscarPro EMR, it could be represented as OscarPro-12
It must be alphanumeric, and can include - and _ characters ([a-zA-Z0-9_-]+). UUIDs are acceptable, although it's always nice to have human readable identifiers if possible.
Product-instances must be consistent through time. If a product instance identifier changes for a particular install of an EMR, Bad Things will happen. Ensure consistency.
This element is optional. If the artifact is not tied to a specific EMR instance (e.g., it is defined centrally by WELL, or used across multiple systems), this segment can be omitted from the canonical URL. For such use cases, the canonical URL would follow the format: https://fhir.apps.health/[artifact-type]/[artifact-id]
[artifact-id]: A unique, human-readable identifier for the specific artifact. Use hyphens - as separators.

NamingSystem Subtypes (Optional)¶

The standard naming system for any Polaris resource is https://fhir.apps.health/NamingSystem/[product-instance]-[resource-type]-identifier. Every resource stored in MedPlum must have a unique identifier with this canonical URL (this is specified on each Polaris resource profile as an Invariant, so is enforced when we do validation).

Sometimes it is convenient to have an additional Well-specific identifier of a certain type, and there is no obvious URI or identifier system for it. For example, the raw EMR identifier for an Observation as sent by an Oscar EMR instance.

In these cases, a subtype of the standard Polaris ID is recommended. This subtype would be of the form: https://fhir.apps.health/NamingSystem/[product-instance]-[resource-type]-identifier/[subtype]. 'subtype' can be any [a-zA-Z0-9_-]+ string, as defined by the system sending the identifier.

For example, for a raw Oscar Observation id, an Oscar instance could encode that using the canonical system URI https://fhir.apps.health/NamingSystem/OscarPro-12-observation-identifier/raw-observation.

This should NOT be used when a more specific identifier system is available. For example, for a provincial patient identifier, the provincial patient identifier system should be used. If you're sending LOINC, just use http://loinc.org.

A good list of canonical URIs for various provincially assigned identifiers has been collected by the OLIS Implementation Guide

Standardized Canonical URL Formats by Artifact Type¶

Below are some examples using the updated structure:

NamingSystem: https://fhir.apps.health/NamingSystem/[product-instance]-patient-identifier
CodeSystem: https://fhir.apps.health/CodeSystem/[product-instance]-medication-codes
ValueSet: https://fhir.apps.health/ValueSet/[product-instance]-allergy-types

The following examples, while it is possible to have a product instance identifier, in practice it is very unlikely that a specific installed instance of an EMR will be defining their own objects of these types.

OperationDefinition: https://fhir.apps.health/OperationDefinition/[product-instance]-process-message
SearchParameter: https://fhir.apps.health/SearchParameter/[product-instance]-gender
CapabilityStatement: https://fhir.apps.health/CapabilityStatement/[product-instance]-server
ConceptMap: https://fhir.apps.health/ConceptMap/[product-instance]-medication-map
StructureDefinition (Profile): https://fhir.apps.health/StructureDefinition/[product-instance]-patient-profile
StructureDefinition (Extension): https://fhir.apps.health/StructureDefinition/[product-instance]-consent-status-extension