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.

FHIR Query Validator applies a set of structured validation rules to every query string. Understanding these rules helps you interpret error messages and write queries that pass validation. Rules are applied in order — a resource type error will prevent parameter validation from running.

​
Validation order

1

Parse the query string

The query is split into resource type and parameter pairs. Malformed query strings (missing ?, invalid encoding) are caught here.
2

Validate the resource type

The resource type portion (before ?) is checked against the list of known FHIR R4 resource types.
3

Validate search parameter names

Each parameter name is checked against the list of valid search parameters for that resource type.
4

Validate parameter values and modifiers

Each parameter value is checked for correct format based on its data type. Modifiers and comparison prefixes are also validated.

​
Resource type rules

RuleDescriptionError message
Must be a known FHIR R4 resourceThe resource type must appear in the FHIR R4 specificationUnknown FHIR resource type '{type}'
Case-sensitivepatient is not valid — use PatientUnknown FHIR resource type 'patient'. Did you mean 'Patient'?
No whitespaceSpaces in the resource type are not allowedInvalid resource type: contains whitespace

​
Search parameter rules

RuleDescriptionError message
Must exist for resourceA parameter must be defined for the queried resource typeUnknown search parameter '{param}' for resource '{resource}'
Case-sensitiveParameter names are lowercase by conventionUnknown search parameter '{Param}'. Did you mean '{param}'?
Modifiers must be valid for typeOnly applicable modifiers are allowed per parameter typeModifier ':{modifier}' is not valid for parameter type '{type}'

​
Value format rules by parameter type

String parameters accept free-text values. No specific format is required, but some modifiers alter behavior.Valid modifiers: :exact, :contains, :missing
Patient?name=Smith          # valid
Patient?name:exact=Smith    # valid — exact match
Patient?name:contains=mit   # valid — substring match
Patient?name:missing=true   # valid — patients with no name
Token parameters match coded values. They accept system|code, code, or |code formats.Valid modifiers: :not, :text, :above, :below, :in, :not-in, :missing, :of-type
Observation?code=8867-4               # code only
Observation?code=http://loinc.org|8867-4  # system|code
Observation?code:not=8867-4           # negation
Observation?code:text=heart rate      # match by display text
Error: Invalid token format '{value}'. Use 'code', 'system|code', or '|code'
Date parameters require ISO 8601 date or datetime format. Comparison prefixes are supported.Valid prefixes: eq, ne, lt, le, gt, ge, sa, eb, apValid formats: YYYY, YYYY-MM, YYYY-MM-DD, YYYY-MM-DDThh:mm:ss+zz:zz
Patient?birthdate=1990-01-15          # exact date
Patient?birthdate=ge1990-01-01        # on or after
Patient?birthdate=lt2000-12-31        # before
Observation?date=2023-06-01T00:00:00Z # datetime with timezone
Error: Invalid date format '{value}'. Use ISO 8601 format (YYYY-MM-DD or YYYY-MM-DDThh:mm:ss+zz:zz)
Number parameters accept integers or decimals. Comparison prefixes are supported.Valid prefixes: eq, ne, lt, le, gt, ge, sa, eb, ap
RiskAssessment?probability=0.8
RiskAssessment?probability=gt0.5
Error: Invalid number format '{value}'. Use a numeric value with optional prefix (eq, ne, lt, le, gt, ge)
Quantity parameters combine a number with optional unit system and code: number|system|code.Valid prefixes: eq, ne, lt, le, gt, ge, sa, eb, ap
Observation?value-quantity=8.6|http://unitsofmeasure.org|g/dL
Observation?value-quantity=gt5.0||mg
Error: Invalid quantity format '{value}'. Use 'number', 'number|system|code', or 'prefix+number'
Reference parameters point to another FHIR resource. They accept a relative reference, absolute URL, or logical identifier.Valid modifiers: :type, :identifier, :missing, :above, :below
Observation?patient=Patient/123           # relative reference
Observation?patient=https://example.org/Patient/123  # absolute URL
Observation?subject:Patient=123           # typed reference
URI parameters match exact URIs. The :above and :below modifiers enable hierarchical matching.
ValueSet?url=http://hl7.org/fhir/ValueSet/administrative-gender
ValueSet?url:below=http://hl7.org/fhir/
Composite parameters combine two parameters using $ as a separator.
Observation?code-value-quantity=8867-4$gt60
Error: Invalid composite format '{value}'. Use 'param1$param2' syntax

​
Modifier validity by parameter type

ModifierStringTokenDateNumberQuantityReferenceURI
:exactYes——————
:containsYes——————
:missingYesYesYesYesYesYesYes
:not—Yes—————
:text—Yes—————
:above—Yes———YesYes
:below—Yes———YesYes
:in—Yes—————
:not-in—Yes—————
:identifier—————Yes—
:type—————Yes—
:of-type—Yes—————

​
Special parameter rules

ParameterValid valuesNotes
_countPositive integerMaximum number of results per page
_sortParameter name, optionally prefixed with - for descendinge.g., _sort=birthdate, _sort=-date
_summarytrue, false, text, data, countControls response verbosity
_formatjson, xml, application/fhir+json, application/fhir+xmlResponse format
_includeResourceType:searchParam or ResourceType:searchParam:targetTypeInclude referenced resources
_revincludeResourceType:searchParamInclude resources that reference the result
_elementsComma-separated element namesReturn only specified elements
Validation rules follow the HL7 FHIR R4 specification. Custom resource types or extended profiles may require custom configuration to avoid false validation errors.

Build docs developers (and LLMs) love

Get started for freeTalk to us