Skip to content

Polaris FHIR System URI Format Update: What You Need to Know

What’s This About?

If you're integrating with Polaris or working with a FHIR server like Medplum, there’s been a small but important change in how instance-specific URLs are structured. This mostly affects how you reference identifiers in your FHIR data, especially if you're creating, validating, or querying resources that use identifier.system.

Let’s walk through the change—and what you should do about it.

What Changed?

Old Format (no longer used)

https://fhir.apps.health/[instance-id]/NamingSystem/[resource]-identifier

New Format (use this!)

https://fhir.apps.health/NamingSystem/[instance-id]-[resource]-identifier

The Key Differences:

  • The instance ID moved after NamingSystem
  • The instance ID and resource type are now joined with a - (hyphen)
  • This format better follows common FHIR conventions and works better with tooling

Why Should I Care?

If you're doing any of the following, this change affects you:

  • Creating FHIR resources using Java, JavaScript, or other SDKs
  • Pushing data to a Medplum server (or similar FHIR API)
  • Writing FHIR queries using identifier.system
  • Validating resources against profiles that use canonical URLs

The URLs in your identifier.system, extension.url, ValueSet.url, etc., need to use the new format.

Real-World Example

Let’s say you're generating a Patient resource using the HAPI FHIR Java library:

✅ New Format (correct):

Identifier identifier = new Identifier()
    .setSystem("https://fhir.apps.health/NamingSystem/clinic-1234-patient-identifier")
    .setValue("PAT-12345");

Patient patient = new Patient();
patient.addIdentifier(identifier);

❌ Old Format (will no longer validate cleanly):

// Don't use this anymore!
.setSystem("https://fhir.apps.health/clinic-1234/NamingSystem/patient-identifier")

Querying with Medplum

If you’re querying Medplum for a Patient by identifier, your API call might look like this:

curl "https://api.medplum.com/fhir/R4/Patient?identifier=https://fhir.apps.health/NamingSystem/clinic-1234-patient-identifier|PAT-12345" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Or using JavaScript:

const result = await medplum.search('Patient', {
  identifier: 'https://fhir.apps.health/NamingSystem/clinic-1234-patient-identifier|PAT-12345'
});

This URL is now the expected pattern. If you use the old format, queries may not behave as expected.

More Examples

Resource Updated URL
Patient https://fhir.apps.health/NamingSystem/clinic-1234-patient-identifier
Appointment https://fhir.apps.health/NamingSystem/oscar-pro-484-appointment-identifier
Organization https://fhir.apps.health/NamingSystem/juno-emr-555-organization-identifier

What About Extensions and ValueSets?

If you’re working with Extension.url or validating ValueSet references, those URLs follow the same new format.

{
  "extension": [
    {
      "url": "https://fhir.apps.health/NamingSystem/oscar-pro-4843-appointment-identifier",
      "valueIdentifier": {
        "value": "APT-00001"
      }
    }
  ]
}

What Didn’t Change?

Good news: if the URL doesn’t include an instance ID, you’re all good. No changes there.

✅ These are fine:

  • https://fhir.apps.health/NamingSystem/standard-codes
  • https://fhir.apps.health/CodeSystem/appointment-status

Only instance-specific URLs were updated.

How to Check Your Resources

You can quickly check your code or data files by looking for the old pattern. Try this from your terminal:

grep -r "fhir\.apps\.health/[^/]*/NamingSystem" .

If you find any, update them to the new format. If you're unsure, just swap the segment that looks like:

[instance]/NamingSystem/[resource]-identifier

...to:

NamingSystem/[instance]-[resource]-identifier

Need Help?

This URL update brings Polaris closer to FHIR standards and makes it easier to work with modern tooling like Medplum, HAPI, and more.