tx.fhir.org/r4 $expand: imported include excludes ignored + expansion.total inconsistent

[jmandel]

Summary

On https://tx.fhir.org/r4/ValueSet/$expand, imported include cases appear to:

1. return codes that are explicitly excluded, and
2. return expansion.total inconsistent with returned/pageable results.

Observed on 2026-03-05 (UTC).

Endpoint

POST https://tx.fhir.org/r4/ValueSet/$expand

---

Repro 1: imported include + peer concept include + exclude

Request (curl)

curl -sS \
  -H 'content-type: application/fhir+json' \
  --data @payload.json \
  'https://tx.fhir.org/r4/ValueSet/$expand'

Request payload (payload.json)

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "valueSet",
      "resource": {
        "resourceType": "ValueSet",
        "status": "active",
        "compose": {
          "include": [
            { "valueSet": ["http://hl7.org/fhir/ValueSet/administrative-gender"] },
            { "system": "http://hl7.org/fhir/publication-status", "concept": [{"code":"active"}] }
          ],
          "exclude": [
            { "system": "http://hl7.org/fhir/administrative-gender", "concept": [{"code":"other"},{"code":"unknown"}] }
          ]
        }
      }
    }
  ]
}

Observed response (exact JSON)

{
  "resourceType": "ValueSet",
  "status": "active",
  "expansion": {
    "timestamp": "2026-03-05T01:53:52.148Z",
    "identifier": "urn:uuid:ec229cbf-4df7-4458-8b89-81db9506cdfb",
    "parameter": [
      {
        "name": "used-codesystem",
        "valueUri": "http://hl7.org/fhir/administrative-gender|4.0.1"
      },
      {
        "name": "used-valueset",
        "valueUri": "http://hl7.org/fhir/ValueSet/administrative-gender|4.0.1"
      },
      {
        "name": "used-codesystem",
        "valueUri": "http://hl7.org/fhir/publication-status|4.0.1"
      }
    ],
    "total": 1,
    "contains": [
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "male",
        "display": "Male"
      },
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "female",
        "display": "Female"
      },
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "other",
        "display": "Other"
      },
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "unknown",
        "display": "Unknown"
      },
      {
        "system": "http://hl7.org/fhir/publication-status",
        "code": "active",
        "display": "Active"
      }
    ]
  }
}

Expected behavior

• Excluded codes other and unknown from administrative-gender should not be present.
• contains should be exactly:
  • http://hl7.org/fhir/administrative-gender|male
  • http://hl7.org/fhir/administrative-gender|female
  • http://hl7.org/fhir/publication-status|active
• expansion.total should be 3.

---

Repro 2: imported include + peer whole-system include + exclude

Request (curl)

curl -sS \
  -H 'content-type: application/fhir+json' \
  --data @payload.json \
  'https://tx.fhir.org/r4/ValueSet/$expand'

Request payload (payload.json)

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "valueSet",
      "resource": {
        "resourceType": "ValueSet",
        "status": "active",
        "compose": {
          "include": [
            { "valueSet": ["http://hl7.org/fhir/ValueSet/administrative-gender"] },
            { "system": "http://hl7.org/fhir/publication-status" }
          ],
          "exclude": [
            { "system": "http://hl7.org/fhir/administrative-gender", "concept": [{"code":"other"},{"code":"unknown"}] },
            { "system": "http://hl7.org/fhir/publication-status", "concept": [{"code":"unknown"}] }
          ]
        }
      }
    }
  ]
}

Observed response (exact JSON)

{
  "resourceType": "ValueSet",
  "status": "active",
  "expansion": {
    "timestamp": "2026-03-05T01:54:08.498Z",
    "identifier": "urn:uuid:f9668dd2-4868-4c40-80ac-b0b2614303c3",
    "parameter": [
      {
        "name": "used-codesystem",
        "valueUri": "http://hl7.org/fhir/administrative-gender|4.0.1"
      },
      {
        "name": "used-codesystem",
        "valueUri": "http://hl7.org/fhir/publication-status|4.0.1"
      },
      {
        "name": "used-valueset",
        "valueUri": "http://hl7.org/fhir/ValueSet/administrative-gender|4.0.1"
      }
    ],
    "total": 3,
    "contains": [
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "male",
        "display": "Male"
      },
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "female",
        "display": "Female"
      },
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "other",
        "display": "Other"
      },
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "unknown",
        "display": "Unknown"
      },
      {
        "system": "http://hl7.org/fhir/publication-status",
        "code": "draft",
        "display": "Draft"
      },
      {
        "system": "http://hl7.org/fhir/publication-status",
        "code": "active",
        "display": "Active"
      },
      {
        "system": "http://hl7.org/fhir/publication-status",
        "code": "retired",
        "display": "Retired"
      }
    ]
  }
}

Expected behavior

• Excluded codes other and unknown from administrative-gender should not be present.
• Result set should contain exactly 5 codes:
  • administrative-gender: male, female
  • publication-status: draft, active, retired
• expansion.total should be 5.

---

Repro 3: same query as Repro 2, paged (count=1) shows total inconsistency

Request (curl)

curl -sS \
  -H 'content-type: application/fhir+json' \
  --data @payload.json \
  'https://tx.fhir.org/r4/ValueSet/$expand'

Request payload (payload.json) for offset=0,count=1

{
  "resourceType": "Parameters",
  "parameter": [
    {"name":"count","valueInteger":1},
    {"name":"offset","valueInteger":0},
    {
      "name": "valueSet",
      "resource": {
        "resourceType": "ValueSet",
        "status": "active",
        "compose": {
          "include": [
            { "valueSet": ["http://hl7.org/fhir/ValueSet/administrative-gender"] },
            { "system": "http://hl7.org/fhir/publication-status" }
          ],
          "exclude": [
            { "system": "http://hl7.org/fhir/administrative-gender", "concept": [{"code":"other"},{"code":"unknown"}] },
            { "system": "http://hl7.org/fhir/publication-status", "concept": [{"code":"unknown"}] }
          ]
        }
      }
    }
  ]
}

Observed response at offset=0,count=1 (exact JSON)

{
  "resourceType": "ValueSet",
  "status": "active",
  "expansion": {
    "timestamp": "2026-03-05T01:54:08.545Z",
    "identifier": "urn:uuid:d8d370d0-e9fc-46e5-ad3a-ae5d93da9ddf",
    "parameter": [
      {
        "name": "offset",
        "valueInteger": 0
      },
      {
        "name": "count",
        "valueInteger": 1
      },
      {
        "name": "used-codesystem",
        "valueUri": "http://hl7.org/fhir/administrative-gender|4.0.1"
      },
      {
        "name": "used-codesystem",
        "valueUri": "http://hl7.org/fhir/publication-status|4.0.1"
      },
      {
        "name": "used-valueset",
        "valueUri": "http://hl7.org/fhir/ValueSet/administrative-gender|4.0.1"
      }
    ],
    "offset": 0,
    "total": 3,
    "contains": [
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "male",
        "display": "Male"
      }
    ]
  }
}

Offset sweep results (same query, count=1, offsets 0..7)

[
  {
    "offset": 0,
    "total": 3,
    "contains": [
      "http://hl7.org/fhir/administrative-gender|male"
    ]
  },
  {
    "offset": 1,
    "total": 3,
    "contains": [
      "http://hl7.org/fhir/administrative-gender|female"
    ]
  },
  {
    "offset": 2,
    "total": 3,
    "contains": [
      "http://hl7.org/fhir/administrative-gender|other"
    ]
  },
  {
    "offset": 3,
    "total": 3,
    "contains": [
      "http://hl7.org/fhir/administrative-gender|unknown"
    ]
  },
  {
    "offset": 4,
    "total": 3,
    "contains": [
      "http://hl7.org/fhir/publication-status|draft"
    ]
  },
  {
    "offset": 5,
    "total": 3,
    "contains": [
      "http://hl7.org/fhir/publication-status|active"
    ]
  },
  {
    "offset": 6,
    "total": 3,
    "contains": [
      "http://hl7.org/fhir/publication-status|retired"
    ]
  },
  {
    "offset": 7,
    "total": 3,
    "contains": []
  }
]

Expected behavior

• expansion.total should be consistent with pageable membership.
• For this query, drained unique membership is 7 in current behavior, while total is reported as 3.

---

Notes

• This report is based on live responses from tx.fhir.org/r4, not local patched behavior.
• If useful I can attach a tiny script that executes all repros and validates expected invariants (contains excludes, contains <= total for non-paged full fetch, paged union consistency).