FHIR Profiles

[rahul1]

FHIR Profiles

In this post, I'll describe what FHIR profiles are, how I think they could be useful for Medplum, and what I see as the high level work needing to be done.

What are profiles?

FHIR profiles are essentially a way of specializing a FHIR resource into a "subclass." Specifically they:

• Restrict the cardinality of a field (e.g. make some fields mandatory)
• Require specific ontologies for fields (e.g. require LOINC for service requests)
• Define the structure of Extensions which should appear in the resource.

How are implemented?

The data object that FHIR uses to define the schemas of resources is called a StructureDefinition, which is itself a FHIR resource (🤯). The profiles-resources.json file contains the definitions for the FHIR base resources. Medplum Resources are also defined using these StructureDefinitions.

A profile is defined as a StructureDefinition that extends a base resource, using the baseDefinition field. Profiles can also.

The cool thing is that Medplum generates all of our DB schemas and TS type definitions directly from the StructureDefinition resources. This opens up some interesting technical possibilities down the road.

How are profiles used?

Each resource has a meta.profile that describes what profiles this resource claims to conform to. It's up to the server implementation to decide how to handle those claims.

Most FHIR implementation guides publish a set of profiles to enforce the data model they describe.

• The US Core define a set of profiles with required fields and extensions (e.g requires at least one name on Patient)
• The Lab Catalog IG describes a LabServiceDefinition profile of PlanDefinition, that enforces the use of LOIINC
• The Davinci PDEX define a set of profiles for managing provider directories, including a profile of Organization to represent an insurance network.

Opportunities for Medplum

The main opportunities I see for Medplum are:

• Simplify user onboarding
• Streamline our integration with 3rd party partners

Simplify user onboarding: Right now users define their data model using our documentation, FHIR documentation, and consultation with the medplum community to make sure they're modeling their data properly in FHIR. I envision a future in which our best practices can be encoded as profiles, that we can share with users when they start a Medplum deployment. The server could then enforce these best-practices programatically. I see the onboarding flow as something like:

• Medplum has a base set of Profiles for each vertical (Lab, Telehealth, Radiology, payers), based on industry standards / our experience
• These profiles cover 70-90% of a customer use case, but need some customization.
• As we work with users on their data model, we can fork / update these profiles to reflect a customer's unique workflow

Streamline integrations: We can define profiles to ensure all the relevant fields are populated when sending data to a 3rd party API. E.g. a CandidHealthEncounter profile.

Implementation Notes

I'm probably missing a bunch of stuff here

Low hanging fruits

• Utility function for validating a resource against a StructureDefinition: This will be a foundational building block before we do anything else. We have this in the server package, we just need to move it and clean it up.

Open Questions

• What do we actually do we resources that have profiles attached to them? Do we reject resources that don't conform to the resources they claim? Do we accept but show some kind of feedback in the Medplum app?
• How are profiles assigned to resources? Are they assigned by the client? Is there some kind of rules engine that assigns them automatically?
• If medplum has specific profiles that they "endorse", how are those shipped into the customer project
• What is the performance cost of running profile validation on every write?
• Should we support the FHIRPath based constraints on resources, as well as basic cardinality checks.

Nice to haves, but not required

• Generate Type Definitions from Profiles: For example, when constructing a CandidHealthEncounter - could get real-time feedback on any missing fields.
• Docs generated from Profiles: We can generate our resource reference docs based on StructureDefinitions. Then, we can also create the same form of documentation for any custom profiles created for a specific use case.

Reference

https://www.devdays.com/wp-content/uploads/2021/12/DD21US_20210608_Mirjam_Baltus_Introduction_to_Profiling.pdf
https://hl7.org/fhir/profiling.html

[mattwiller]

I would also specifically call out a couple other things that FHIR profiles commonly do using examples from the US Core Blood Pressure profile on Observation resources (which I totally agree with the "subclass" metaphor for):

• Specify fixed values for fields, e.g. that Observation.code contains exactly http://loinc.org|8480-6
• Use slices to assert that a field containing multiple values must have at least some values with a given pattern, e.g. that the Observation.component array contains two specific elements: one that matches a systolic pressure measurement, and another that matches a diastolic pressure measurement
  • Note: The cardinality of Observation.component under this example profile is 2..*; it can optionally contain other components like a full orthostatic blood pressure panel

Based on a cursory search of the Medplum codebase, we'll need to implement validation of both of those for profiles to function correctly.

[codyebberson]

Based on a cursory search of the Medplum codebase, we'll need to implement validation of both of those for profiles to function correctly.

Yep, need to evaluate ElementDefinition.constraint: https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.constraint

[mattwiller]

Just for clarity: the fixed value/slice validations are not FHIRPath constraints, but rather part of the profile definition itself

[codyebberson]

Oops, my bad 👍

[codyebberson]

Utility function for validating a resource against a StructureDefinition: This will be a foundational building block before we do anything else. We have this in the server package, we just need to move it and clean it up.

We have a pretty decent starting point: https://github.com/medplum/medplum/blob/main/packages/core/src/schema.ts

Gaps:

• It assumes that the StructureDefinition is loaded and "indexed" in globalSchema. We will need to support passing in a separate StructureDefinition.
• It does not evaluate ElementDefinition.constraint: https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.constraint

What do we actually do we resources that have profiles attached to them? Do we reject resources that don't conform to the resources they claim? Do we accept but show some kind of feedback in the Medplum app?

I propose we reject with a 400 and OperationOutcome with issue populated with all of the issues. Our current FhirSchemaValidator class does the validation part. Our current <ResourceForm> component parses the OperationOutcome and displays all of the violations inline on the page.

How are profiles assigned to resources? Are they assigned by the client? Is there some kind of rules engine that assigns them automatically?

I don't know if the spec mandates anything here?

The two options I would consider:

1. Applied globally at the project level as a project admin setting.
2. Users specify profile in resource.meta.profile: https://hl7.org/fhir/resource-definitions.html#Meta.profile

If medplum has specific profiles that they "endorse", how are those shipped into the customer project

Yes, good callout, US Core being an obvious case.

Similar to the Terminology Service discussion, I assume that we will need to support a "view" that combines multiple Medplum Project resources seamlessly. So, for example, I might sign into my project Project/123. Project admin adds the "US Core" project, Project/456. Now whenever I search for FHIR resources, my search results can include resources from both Project/123 and Project/456. In the terminology service case, that would mean including extra CodeSystem and ValueSet resources. In this FHIR profiles case, that would mean including extra StructureDefinition resources.

What is the performance cost of running profile validation on every write?

(These are gut instinct guesses, need to measure)

The validation itself shouldn't be too bad, depending on the complexity of the FHIRPath expressions.

The more expensive part will be constantly loading the StructureDefiniton from database or Redis. StructureDefinition resources have a tendency to be large. Plus all of the string to JSON parsing.

I think? Need to measure. We can optimize as necessary. The user benefits definitely justify some degree of performance hit.

Should we support the FHIRPath based constraints on resources, as well as basic cardinality checks.

Yes, I think this is pretty critical. Also extremely powerful for helping customers to create the configuration they want. It will be so much better than "create resource, check with a bot, and clean up post facto". Instead it's just 400, nothing created, db stays clean.

Generate Type Definitions from Profiles: For example, when constructing a CandidHealthEncounter - could get real-time feedback on any missing fields.

Agree. Our generator tools can do most of the heavy lifting. There's still all of the gross work of packaging and publishing to npm though.

Docs generated from Profiles: We can generate our resource reference docs based on StructureDefinitions. Then, we can also create the same form of documentation for any custom profiles created for a specific use case.

👍

[rahul1]

Should we support the FHIRPath based constraints on resources, as well as basic cardinality checks.

Yes, I think this is pretty critical. Also extremely powerful for helping customers to create the configuration they want. It will be so much better than "create resource, check with a bot, and clean up post facto". Instead it's just 400, nothing created, db stays clean.

I think I agree with this - there's a lot of data hygiene that can be taken care of at this level. This brings up a few more considerations though:

• Should we start enforcing constraints on base resources?
• What should we do for existing "strict mode" projects that have resources that don't satisfy constraints? Should add this as another level of project strictness.

[codyebberson]

Should we start enforcing constraints on base resources?
What should we do for existing "strict mode" projects that have resources that don't satisfy constraints? Should add this as another level of project strictness.

No easy answer to this, but here is my proposal:

• For new projects in "strict" mode, yes, enforce constraints
• For existing projects in "non strict" mode, no, do not enforce constraints
• For existing projects in "strict" mode .... things get tricky....
  • We could write a script that tests how much would break if we turned it on by default
  • Otherwise, we need "strict", "non strict", and "strict + constraints" or some other less awful name

[rahul1]

Yeah I think doing an investigation on how many existing projects / resources would have trouble with constraints would be a good first step.

[rahul1]

Another question is how we would we want to deal with validating references? For example, a USCore MedicationRequest refers to a USCore Patient. So in a sense, a reference to a vanilla Patient is invalid.

When a MedicationRequest is created, are we going to validate the reference as well? I think we should be able to do this in a similar way we validate reference resourceTypes right now, but would need to think through the implementation

[codyebberson]

Perhaps a lightweight option would be:

1. Validate that the reference exists
2. Validate that the target resource has the appropriate Resource.meta.profile
3. The end

?

[rahul1]

Yeah, if #2 is feasible, I think that would be sufficient

[mattwiller]

Since _profile is already a search parameter, I think it should be pretty feasible to use the existing columns in Postgres and make queries checking a reference simple and fast

[mattlong]

@rahul1 @codyebberson @mattwiller

The time has come to handle references to other profiles! As a concrete example, USCoreImplantableDeviceProfile has a reference to a USCorePatientProfile in Device.patient. In particular, the type of the reference is:

"type": [
  {
	"code": "Reference",
	"targetProfile": [
	  "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
	]
  }
]

This should translate to a search for Patient?_profile=http%3A%2F%2Fhl7.org%2Ffhir%2Fus%2Fcore%2FStructureDefinition%2Fus-core-patient, but where should that translation happen? Client-side or Server-side?

Client-side
ResourceInput or medplum.searchResources is updated to accept StructureDefinition URLs in addition to ResourceType. When it receives a URL, searches for a StructureDefinition by url and then proceeds to search for the resolved ResourceType and adds a _profile filter to the query.

Server-side
The /fhir/R4/:resourceType endpoint is similarly updated to accept SD URLs and does the same resolution described above.

Reading through the FHIR search and profile documentation, it seems that client-side resolution is the intended approach but would involve more network hops. In the short term, the extra network hops seem acceptable. Longer term, it might be preferable to parse/load/index all targetProfile entries encountered similarly to the treatment innerTypes gets in packages/core/src/typeschema/types.ts#parseStructureDefinition, but maybe not since that would incur a tax every time the edit page is loaded when the user may not wind up searching in a given reference input.

Thoughts?

[mattlong]

I put together the client-based POC in #3552

Update: The client-side approach has been merged in #3552

[mattwiller]

I put together a more detailed design document (below) for how we might want to approach building out support for profile validation, and would love any feedback that folks have on it!

https://gist.github.com/mattwiller/7e39f09561f5b6771ca3aac98a411ec8

[codyebberson]

Awesome, this is fantastic. Thanks @mattwiller !

What should the server do if a resource specifies a profile the server doesn't understand?
Since the user controls the profiles available in their Project, maybe this should be an error

Agree, I think this should be 400 bad request.

Customers may also want to apply profiles globally to all resources of a given type in their project; how should we accommodate that?

Yes, agree, I think this is something we should support.

We probably need to support a mechanism of "here are the acceptable profiles for this resource type", which would be an array of StructureDefinition references or canonical URLs. I assume that it has to be an array to, for example, have multiple Observation profiles for the different shapes of Observation.

We can either do this at the Project level, with a new resourceProfiles / requiredProfiles / supportedProfiles property.

We could also do it at the AccessPolicy level if we want to support different users with different profile configurations. That might get gross though.

Where/how should we store common profiles like US Core so they can be re-used easily by all customers?

Loosely held opinion: This is slightly out of scope for the immediate requirements, but it's good for us to have an eye on this question. In my mind, this is similar to the Terminology Service Discussion, and the "linked projects" idea. That would support the US Core StructureDefinitions living in a single Project. When a user is signed into their Project that uses US Core, all of their search results would actually be the combination of resources from both Projects.

How can we ensure that customers' apps aren't broken by new validation rules or control the rollout in their Project?

😢

I reluctantly think we need something in addition to "strictMode". There isn't a good answer for this.

Once we have a branch that implements all of the new validation rules, we could write a big batch operation that evaluates every resource in every project, and then we would at least know the impact.

[codyebberson]

Thinking about customer impact on each of these individually...

1. Refactor the validation code to accept a profile StructureDefinition as input, so it can work with arbitrary profiles outside of the base specification
2. Fix cardinality checks to support fields with cardinality like 0..2
3. Improve validation for string-backed values by fencing regexes and adding more specific validation for datetime types
4. Implement fixed value validation rules
5. Implement slicing validation rules
6. Enable specifying profiles to validate against in meta.profile
7. Benchmark writes of resources with 1-3 profiles attached with ~50 ms target
8. Allow customers to upload profiles into their project that can be used for resource validation
9. Evaluate constraint definitions on resource types and their fields

1, 6, 7, and 8 are pure refactoring or net new

2 and 3 are fixing existing bugs. That might cause breaks, but I'm ok with it.

5 only applies to FHIR Profile StructureDefinitions, not the base StructureDefinitions, correct? I'm also ok with that.

It's really only 4 and 9 that potentially break existing data?

[rahul1]

I don't think 4 breaks existing data, since none of the base specifications specify fixed values for elements (iirc)

[mattwiller]

I suspect that 3 and 9 have the potential to break on existing data. In theory parts of 2 could as well, since the existing code doesn't check the actual field cardinality, but I'm not aware of any base spec definitions that have a maximum cardinality other than 1 or *

[mattwiller]

My thinking here is to sequence 3 at the end, right before 9; that way we could do a release that includes profile validation but isn't breaking, followed by a later potentially breaking release