Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dhanyasukumaran1/fhir_query_validator/llms.txt

Use this file to discover all available pages before exploring further.

Every FHIR query begins with a resource type — the noun that tells the server what kind of data you want. Resource types are not just naming conventions; they are formal definitions in the FHIR R4 specification that enumerate exactly which search parameters are valid for each type. FHIR Query Validator uses these definitions as the source of truth: if a parameter is not defined for the resource type in your query, the validator reports an error. Understanding how resource types work — and why they differ — helps you write queries that pass validation on the first attempt.

​
What FHIR resource types are

A FHIR resource type is a structured data object with a defined schema, a set of valid search parameters, and a role in the clinical or administrative domain. The FHIR R4 specification defines over 140 resource types, ranging from foundational clinical types like Patient and Observation to administrative types like Organization and infrastructure types like CapabilityStatement. Each resource type has:
  • A fixed set of search parameters (e.g., family, birthdate for Patient)
  • A search parameter type for each parameter (string, date, token, reference, quantity, or URI), which determines valid value formats
  • An optional set of allowed modifiers per parameter
  • A set of allowed prefixes for date and quantity parameters
When the resource type changes, the set of valid parameters changes entirely. family is valid for Patient but not for Observation. code is valid for Observation but not for Patient. This is why the resource type is the first thing FHIR Query Validator checks.

​
Categories of FHIR resource types

FHIR resource types fall into three broad categories. The distinction matters for understanding which types appear in typical healthcare data pipelines and which search parameters each category tends to define.
Clinical resources represent patient health data — the core content of a medical record. These are the most commonly queried resource types in healthcare applications.
Resource typeDescription
PatientDemographics, identifiers, and contact information for a person receiving care
ObservationMeasurements and simple assertions (vital signs, lab results, survey answers)
ConditionClinical conditions, diagnoses, and problems recorded for a patient
MedicationRequestPrescriptions and medication orders for a patient
ProcedureActions performed on or for a patient (surgeries, therapies, other interventions)
AllergyIntoleranceRecorded allergies and adverse reaction risks
DiagnosticReportReports from diagnostic services, including lab panels and imaging
ImmunizationAdministration of a vaccine or other immunizing agent
CarePlanDescriptions of planned activities for a patient, often multi-disciplinary

​
How resource types affect search parameter validity

The FHIR R4 specification defines search parameters per resource type. FHIR Query Validator loads these definitions to determine which parameters are valid in a query.
resource_type_check.py
from fhir_query_validator import FHIRQueryValidator

validator = FHIRQueryValidator()

# 'family' is defined for Patient — valid
result = validator.validate_query("Patient?family=Smith")
print(result.is_valid)  # True

# 'family' is not defined for Observation — error
result = validator.validate_query("Observation?family=Smith")
print(result.is_valid)   # False
print(result.errors)     # ["Unknown search parameter 'family' for resource type 'Observation'"]

# 'code' is defined for Observation — valid
result = validator.validate_query("Observation?code=8867-4")
print(result.is_valid)  # True
Some search parameters are defined across all resource types. The _id, _lastUpdated, _tag, _profile, and _security control parameters are universal. _count, _sort, _include, and _revinclude are also broadly available. FHIR Query Validator recognizes these as valid for any resource type.

​
Checking supported resource types at runtime

You can inspect which resource types the validator knows about using the supported_resources attribute. This returns a list of resource type name strings.
check_supported.py
from fhir_query_validator import FHIRQueryValidator

validator = FHIRQueryValidator()

# List all supported resource types
print(validator.supported_resources)
# ['Account', 'ActivityDefinition', 'AdverseEvent', 'AllergyIntolerance',
#  'Appointment', 'Binary', 'Bundle', 'CarePlan', 'Claim', 'Condition',
#  'Coverage', 'DiagnosticReport', 'Encounter', 'Goal', 'Immunization',
#  'Location', 'Medication', 'MedicationRequest', 'Observation',
#  'Organization', 'Patient', 'Practitioner', 'Procedure', ...]

# Check if a specific resource type is supported before querying
resource = "MolecularSequence"
if resource in validator.supported_resources:
    print(f"{resource} is supported")
else:
    print(f"{resource} is not supported — query will fail validation")
Use supported_resources to validate user-supplied resource type names in your application before constructing a query string. This avoids an unnecessary round-trip through the full validation pipeline when the resource type itself is the only unknown.

​
Checking supported search parameters at runtime

The supported_search_parameters attribute returns a dictionary mapping each resource type name to its list of valid search parameter names.
check_params.py
from fhir_query_validator import FHIRQueryValidator

validator = FHIRQueryValidator()

# Get all search parameters for Patient
patient_params = validator.supported_search_parameters.get("Patient", [])
print(patient_params)
# ['_id', '_lastUpdated', 'active', 'address', 'address-city',
#  'address-country', 'address-postalcode', 'address-state', 'address-use',
#  'birthdate', 'death-date', 'deceased', 'email', 'family', 'gender',
#  'general-practitioner', 'given', 'identifier', 'language', 'link',
#  'name', 'organization', 'phone', 'phonetic', 'telecom', ...]

# Check whether a specific parameter is valid for a resource type
param = "birthdate"
if param in validator.supported_search_parameters.get("Patient", []):
    print(f"'{param}' is a valid search parameter for Patient")

​
Key resource types and their search parameters

The following table covers the FHIR resource types most commonly used in clinical and analytics applications. Each row lists the most frequently used search parameters.
Resource typeCategoryKey search parameters
PatientClinicalfamily, given, birthdate, gender, identifier, address-city, address-postalcode, deceased, general-practitioner, organization
ObservationClinicalcode, patient, subject, category, date, status, value-quantity, component-code, performer
ConditionClinicalpatient, subject, code, clinical-status, verification-status, category, onset-date, recorded-date, severity
MedicationRequestClinicalpatient, subject, medication, status, intent, authoredon, requester, category, encounter
EncounterAdministrativepatient, subject, status, type, class, date, participant, practitioner, location, reason-code
DiagnosticReportClinicalpatient, subject, code, category, status, date, issued, performer, result, encounter
ProcedureClinicalpatient, subject, code, status, date, performer, encounter, reason-code, category
AllergyIntoleranceClinicalpatient, code, clinical-status, verification-status, type, category, criticality, onset, recorder
ImmunizationClinicalpatient, status, vaccine-code, date, lot-number, performer, reaction, location
OrganizationAdministrativename, identifier, type, address, address-city, address-state, partof, active, endpoint
PractitionerAdministrativename, family, given, identifier, gender, address, address-city, active, telecom
LocationAdministrativename, identifier, type, address, address-city, address-state, operational-status, organization, partof
This table shows commonly used parameters, not the complete list. The FHIR R4 specification defines additional search parameters for each resource type. Use supported_search_parameters to get the authoritative list from the validator, or consult the supported resources reference for the full enumeration.

​
Resource type names are case-sensitive

FHIR resource type names always use PascalCase. The validator checks case exactly.
capitalization.py
from fhir_query_validator import FHIRQueryValidator

validator = FHIRQueryValidator()

# These all fail — wrong capitalization
cases = [
    "patient?family=Smith",           # all lowercase
    "PATIENT?family=Smith",           # all uppercase
    "medication_request?patient=1",   # underscore instead of PascalCase
    "medicationrequest?patient=1",    # no capitalization
]

for query in cases:
    result = validator.validate_query(query)
    print(f"{query!r}: {result.errors[0] if result.errors else 'valid'}")

# Correct capitalization
result = validator.validate_query("MedicationRequest?patient=Patient/123")
print(result.is_valid)  # True

​
Next steps

Supported resources reference

The full list of FHIR R4 resource types and their complete search parameter sets supported by the validator.

FHIR for developers

A broader introduction to FHIR, the REST API model, and FHIR search query anatomy.

Build docs developers (and LLMs) love

Get started for freeTalk to us