❓ Support for ValueSet.compose.include.filter in Snowstorm for Non-SNOMED CodeSystems

[HengJayWang]

Hi Snowstorm team 👋,

I'm currently working on uploading ValueSets to a Snowstorm-based FHIR Terminology Server. Some of these ValueSets use compose.include.filter with operators such as is-a or descendent-of, targeting the ICD-10-CM CodeSystem.

However, when trying to upload these ValueSets, I receive an error like the following:
This server does not expect any ValueSet property filters for ICD-10.

For instance, when attempting to expand a ValueSet with the following structure:

{
  "resourceType": "ValueSet",
  "compose": {
    "include": [
      {
        "system": "http://hl7.org/fhir/sid/icd-10-cm",
        "version": "2025",
        "filter": [
          {
            "property": "concept",
            "op": "is-a",
            "value": "I70.2"
          }
        ]
      }
    ]
  }
}

This seems to indicate that Snowstorm does not support filter-based inclusion for ICD-10-CM. I've reviewed the documentation but couldn't find specific clarification on whether this feature is expected to work for non-SNOMED CodeSystems.

Could you please clarify:

• Does Snowstorm support ValueSet.compose.include.filter for ICD-10-CM or similar CodeSystems?

• If not, are there any recommended workarounds (e.g., code enumeration) or future plans to support this capability?

• Could I be missing some required configuration steps? 🤔

  • For example, after uploading a CodeSystem, are there any additional indexing or terminology services I need to enable for filters to work?

I'd appreciate any insights or references the community can share. 🙏 Thanks in advance!

Best regards,
Jay Wang

[kaicode]

Snowstorm supports the concept "is-a" and concept "ancestor" filter on generic CodeSystem that has "hierarchyMeaning": "is-a".

However this has been explicitly disabled for ICD-10 and ICD-10-CM for two reasons:

1. The FHIR specification says that no filters have been defined for ICD-X - https://hl7.org/fhir/R4B/icd.html#4.3.11.5
2. When I created that functionality I was really thinking about "is-a" meaning subsumption in the Ontology sense of the word. We know that ICD-10 is a statistical classification and does not have these semantics, so providing an is-a filter seemed wrong. Perhaps we could allow the "ancestor" filter because that is only talking about hierarchy navigation and ICD-10 clearly has a hierarchy.

Right now it's not possible to use these filters for ICD-10 or ICD-10-CM, but perhaps this should be relaxed for the ancestor filter. Would this help with your use case?

[HengJayWang]

Hi Kai @kaicode 👋,

Thanks for your detailed response. 🥰
But I have another question I'd like to ask regarding ValueSet creation behavior.

Based on my current tests, it seems that when creating a ValueSet, Snowstorm validates the system string inside the ValueSet against the URLs of the CodeSystems that were previously uploaded. If the URLs don't match exactly, the creation is rejected ❌.

For Example, In my ValueSet, I use ICD-10 with the system value: http://www.cms.gov/Medicare/Coding/ICD10
However, when importing the ICD-10 CodeSystem into Snowstorm, I used the -u flag with: http://hl7.org/fhir/sid/icd-10

Because these two URLs differ, the ValueSet fails to be created.

🧩 My questions are:

1. When uploading a CodeSystem using the -u parameter, is it permissible to provide any arbitrary URL value, or are there limitations?

2. I checked both Snowstorm and HAPI CLI examples for terminology uploads, and I couldn't find any detailed explanation about acceptable -u values. Most examples simply use:

   • http://hl7.org/fhir/sid/icd-10-cm

   • http://hl7.org/fhir/sid/icd-10

3. I tried uploading the ICD-10 CodeSystem using -u http://www.cms.gov/Medicare/Coding/ICD10 (which is the URL used in a VSAC-generated ValueSet), but encountered the following error: HAPI-0878: Did not find file matching concepts.csv

Does this mean the -u parameter is expected to match specific pre-defined values only? 🤔

---

Actually, the ValuleSet use URL http://www.cms.gov/Medicare/Coding/ICD10 is generated by the VSAC Authoring Tool, and I assume it should be considered a valid system URI. So I'm confused:

• Is there a canonical list of system URLs that Snowstorm (or HAPI CLI) expects or supports? I think in some localization scenario need to use the custom CodeSystem URL instead of HL7 URL.

• When uploading a CodeSystem for use with external ValueSets (like those from VSAC), how should we choose the -u URL?

• Are there more detailed guidelines or documentation about how system URLs are matched or validated during ValueSet processing?

Any clarification or documentation links would be greatly appreciated 🙏

Thanks again!

Best regards,
Jay Wang

[kaicode]

The system URIs that HAPI and Snowstorm expect are documented in the official HL7 Using ICD-X Codes with FHIR documentation.
The only documentation for loading non-SNOMED CodeSystems into FHIR is Snowstorm FHIR Terminology Server.

[kaicode]

We are a bit restricted by the hapi-fhir-cli tool and the parameters that accepts.

HAPI and Snowstorm need the official ICD-10 URI in order to accept and import the ICD-10 native package format. However, if that package was converted to a generic format then in theory it could be imported using any URI.
The generic format could either be a FHIR package, or the basic custom codesystem format (example here).

[edwardlo12]

I think the default set of CodeSystem url is here https://github.com/hapifhir/hapi-fhir/blob/c844c3f5765994be8fffa7553936069efc4b81b6/hapi-fhir-storage/src/main/java/ca/uhn/fhir/jpa/term/api/ITermLoaderSvc.java#L35-L40.

[edwardlo12]

https://github.com/hapifhir/hapi-fhir/blob/8a44e1058fb0e0e063a152882e1f0dbbd15e1d10/hapi-fhir-jpaserver-base/src/main/java/ca/uhn/fhir/jpa/term/TermReadSvcImpl.java#L1646-L1671

I think is because of there is only "is-a" and "descendent-of" in the original HAPI-FHIR code. Therefore we can't use other operator...
But i don't know how to write JAVA, so I have no idea to contribute...

And I had tried with HAPI FHIR 8.2.0-1, it works with "is-a" and "descendent-of".

[edwardlo12]

Hi @kaicode
I have tried to fix this problem in hapi-fhir.

Is there anything I can do more with snowstorm?
But I can't find the logic about this in snowstorm code base.

[kaicode]

@edwardlo12 I'm away from my desk this week without a laptop. I'll aim to respond with more details on Monday.

[edwardlo12]

Thanks 🙏🏻

[kaicode]

Snowstorm implements the HAPI FHIR interface ITermCodeSystemStorageSvc in the class FHIRTermCodeSystemStorage.java that receives FHIR imports.

The Snowstorm ValueSet filtering behaviour for ICD-10 is in FHIRValueSetService.java here.

[edwardlo12]

@kaicode Could I add filtering with ICD-10-X here?
Or I should keep it not supported?

snowstorm/src/main/java/org/snomed/snowstorm/fhir/services/FHIRValueSetService.java

Lines 921 to 923 in 2e7f8ca

	} else if (codeSystemVersion.getUrl().startsWith("http://hl7.org/fhir/sid/icd-10")) {
	// Spec says there are no filters for ICD-9 and 10.
	throw exception("This server does not expect any ValueSet property filters for ICD-10.", OperationOutcome.IssueType.NOTSUPPORTED, 400);