Structural Errors

Structural errors are detected during the earliest validation phase. They indicate problems with the basic JSON structure of the resource, the presence of unrecognized elements, or issues with the resourceType property. These errors must be resolved before other validation phases can produce meaningful results.

Error Codes

STRUCTURE_UNKNOWN_ELEMENT

An element was found in the resource that is not defined in the StructureDefinition for this resource type. This often indicates a typo in the element name or an element that belongs to a different resource type.

Example – invalid resource:

{
  "resourceType": "Patient",
  "nmae": [
    {
      "family": "Smith"
    }
  ]
}

The element nmae is not defined in the Patient StructureDefinition. The correct element name is name.

Fix:

{
  "resourceType": "Patient",
  "name": [
    {
      "family": "Smith"
    }
  ]
}

STRUCTURE_INVALID_JSON

The input is not valid JSON. The validator could not parse the content before any FHIR-level validation could begin.

Example – invalid resource:

{
  "resourceType": "Patient",
  "name": [
    { "family": "Smith", }
  ]
}

The trailing comma after "Smith" is not valid JSON.

Fix: Ensure the input is well-formed JSON. Use a JSON linter or your editor’s built-in validation to catch syntax errors before running the FHIR validator.

STRUCTURE_NOT_OBJECT

The top-level JSON value is not an object. FHIR resources must be represented as JSON objects (enclosed in curly braces).

Example – invalid resource:

[
  { "resourceType": "Patient" }
]

A JSON array was provided instead of a JSON object.

Fix: Ensure the resource is a single JSON object at the top level:

{
  "resourceType": "Patient"
}

If you need to validate multiple resources, wrap them in a FHIR Bundle resource or validate each one individually.

STRUCTURE_NO_RESOURCE_TYPE

The JSON object does not contain a resourceType property. Every FHIR resource must declare its type using this property.

Example – invalid resource:

{
  "name": [
    {
      "family": "Smith"
    }
  ]
}

Fix: Add the resourceType property:

{
  "resourceType": "Patient",
  "name": [
    {
      "family": "Smith"
    }
  ]
}

STRUCTURE_UNKNOWN_RESOURCE

The resourceType value does not match any known FHIR resource type. This may indicate a typo, a custom resource type that has not been loaded, or a version mismatch.

Example – invalid resource:

{
  "resourceType": "Pateint",
  "name": [
    {
      "family": "Smith"
    }
  ]
}

The value Pateint is not a valid FHIR resource type (note the typo).

Fix: Use the correct resource type name. FHIR resource type names are case-sensitive and use PascalCase:

{
  "resourceType": "Patient",
  "name": [
    {
      "family": "Smith"
    }
  ]
}