Difference in FhirValidator.validateWithResult when validating raw JSON vs parsed Bundle

[Vinod Aravind]

Hello HAPI FHIR team,

I am seeing different behavior in FhirValidator depending on whether I validate a parsed resource vs a raw JSON string.

---

Scenario

I have a Bundle JSON that contains structural issues, for example:

1. Extra array nesting in category.coding:

"category": [  {    "coding": [      [        {          "code": "food-insecurity",          "system": "http://hl7.org/fhir/us/sdoh-clinicalcare/CodeSystem/SDOHCC-CodeSystemTemporaryCodes",          "display": "Food Insecurity"        }      ]    ]  } ]

2. Address represented incorrectly (object vs array mismatch):

"address": [  {    "use": "work",    "city": "Verona",    "line": ["2025 Milky Way"],    "text": "2025 Milky Way Verona, WI 53593-2222",    "state": "WI",    "country": "USA",    "district": "DAVE",    "postalCode": "53593-2222"  } ]

---

Code paths compared

A. Parse JSON into a Bundle first and then validate:

final var bundle = fhirContext.newJsonParser().parseResource(Bundle.class, payload); final var hapiVR = bundleValidator.getFhirValidator().validateWithResult(bundle);

B. Validate raw JSON directly:

// final var bundle = fhirContext.newJsonParser().parseResource(Bundle.class, payload); // skipped final var hapiVR = bundleValidator.getFhirValidator().validateWithResult(payload);

---

Observation

• With method A (parsed Bundle), these structural issues are not detected during validation.
• With method B (raw JSON), the validator does detect errors like:

"The property coding must be an Array, not an Array (at Bundle.entry[18].resource.category[0].coding[0])" "The property address must be an Object, not an Array (at Bundle.entry[4].resource.address)"

---

Question

• Why is there a difference between validating a parsed Bundle vs validating the raw JSON payload?
• Is the JSON schema/type validation only triggered when working on raw text (String) rather than already-parsed resources?
• What is the recommended way to ensure these kinds of structural errors (extra array nesting, wrong element type) are always detected, even when validating a parsed resource? Should I explicitly enable setValidateAgainstStandardSchema(true)?

---

Any insights would be greatly appreciated!

Thanks,
Vinod A

[James Agnew]

The parsed structures (e.g. Patient.java) don't hold any of the original JSON/XML/RDF source data that was parsed in aside from the actual text values, so if there were structural issues with the source data like you quoted those are lost by the time you have a parsed FHIR resource. That's why the validator doesn't detect them, you need to pass the source data to the validator if you want it to catch this kind of issue.

Alternately you can use a Parser Error Handler to catch issues during parsing. This is more performant than using the validator, but only catches structural issues so it's not nearly as comprehensive.

Cheers,

James

--
You received this message because you are subscribed to the Google Groups "HAPI FHIR" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hapi-fhir+...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/hapi-fhir/0e895aee-59aa-4856-91ce-c229bd6990ebn%40googlegroups.com.

[Vinod Aravind]

Hi James,

Thanks for the clarification. I tried using a Parser Error Handler with a lenient parser and overridden methods to capture parser issues into an OperationOutcome, but it did not catch certain structural errors in my FHIR JSON.

Examples not caught by the Bundle option but detected when passing the raw JSON:

Extra array nesting in `category.coding`:


"category": [
  {
    "coding": [
      [
        {
          "code": "food-insecurity",
          "system": "http://hl7.org/fhir/us/sdoh-clinicalcare/CodeSystem/SDOHCC-CodeSystemTemporaryCodes",
          "display": "Food Insecurity"
        }
      ]
    ]
  }
]

Address object vs array mismatch:

"address": [
  {
    "use": "work",
    "city": "Verona",
    "line": ["2025 Milky Way"],
    "text": "2025 Milky Way Verona, WI 53593-2222",
    "state": "WI",
    "country": "USA",

    "district": "DANE",
    "postalCode": "53593-2222"
  }
]


It seems that once the JSON is parsed, the original structure is lost, preventing both the parser error handler and HAPI FHIR validator from detecting these issues.

Would passing the raw JSON directly to the validator be a good approach to catch these structural problems? Do you have any recommendations or best practices for this?

Thanks,
Vinod A