FSH Style Guide: Avoiding `^url =` - UP-Manila-SILab/ph-core GitHub Wiki

❌ Why You Should Not Use ^url =

While technically valid, using the ^url = construct in FSH to manually set the URL of a StructureDefinition (such as an extension or profile) is discouraged for several reasons:

1. Redundancy and Risk of Inconsistency

The ^url is automatically generated by SUSHI using the canonical base URL and the Id of the artifact. Manually setting it introduces a risk of mismatch between the Id and the url, which can lead to confusion, broken references, or validation errors.

2. Hardcoding Reduces Maintainability

If your project’s base URL changes (e.g., moving from a test to a production environment), hardcoded ^url values must be updated manually across all FSH files. This is error-prone and inefficient.

3. Breaks Convention and Tooling Expectations

FHIR tooling and implementation guides often assume that the url follows the pattern:

<canonical>/StructureDefinition/<Id>

Overriding this with ^url can break assumptions in downstream tools, validators, and IG publishers.

✅ Use baseUrl via sushi-config.yaml

Instead of setting ^url, define your base URL once in the sushi-config.yaml file using the canonical property:

canonical: http://example.org/fhir

Then, in your FSH files, simply define the Id:

Extension: patient-birthPlace
Id: patient-birthPlace
Title: "Patient Birth Place"
Description: "The place where the patient was born."
* valueAddress

SUSHI will automatically generate the correct url:

http://example.org/fhir/StructureDefinition/patient-birthPlace
⚠️ **GitHub.com Fallback** ⚠️