> For the complete documentation index, see [llms.txt](https://php-fhir-tools.ardenexal.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://php-fhir-tools.ardenexal.net/validation/ranges.md).

# Quantity & Temporal Range Validation

Validates `minValue[x]` / `maxValue[x]` constraints declared on a Structure Definition:

* `FHIRQuantityRangeValidator` — Quantity ranges, driven by the `#[FHIRQuantityRange]` attribute
* `FHIRTemporalRangeValidator` — `date` / `dateTime` / `instant` / `time` ranges, driven by the `#[FHIRTemporalRange]` attribute

Both validators skip `null` values, so a range constraint never fires on an absent element.

## Quantity ranges

`FHIRQuantityRangeValidator` compares a FHIR `Quantity` value against the constraint's `min` and `max` bounds. A value below `min` or above `max` raises an ERROR:

```
The value {{ value }} is below the minimum {{ min }} {{ unit }}.
The value {{ value }} exceeds the maximum {{ max }} {{ unit }}.
```

Because units cannot be safely converted here, the comparison only proceeds when the instance and the bound share the **same `system` + `code`**. Anything that prevents a safe comparison is surfaced as a WARNING rather than a hard failure:

| Situation                                     | Severity | Reason                                       |
| --------------------------------------------- | -------- | -------------------------------------------- |
| Value below `min` / above `max` (units match) | ERROR    | Genuine range violation                      |
| Instance unit differs from bound unit         | WARNING  | Cross-unit comparison not attempted          |
| Instance missing `system` or `code`           | WARNING  | Cannot identify the unit                     |
| Configured bound missing `system` or `code`   | WARNING  | Malformed bound                              |
| Instance value carries a `comparator`         | WARNING  | Approximate value, not a precise measurement |

## Temporal ranges

`FHIRTemporalRangeValidator` validates `date`, `dateTime`, `instant`, and `time` values against `min` / `max` bounds. Model properties hold primitive wrapper objects (e.g. `DatePrimitive`) which are `\Stringable`; the validator accepts both raw strings and `\Stringable` and compares their string form. Empty strings are skipped.

* **`time`** values are compared as plain strings.
* **Date-like** values (`date` / `dateTime` / `instant`) are parsed. Partial dates (`YYYY` or `YYYY-MM`) are expanded to the **start** of their period for the `min` check and the **end** for the `max` check, so `2024` satisfies a `min` of `2024-06-01` only if the whole year could fall on or after the bound.

An out-of-range value raises an ERROR:

```
The value {{ value }} is before the minimum {{ min }}.
The value {{ value }} is after the maximum {{ max }}.
```

An unparseable **configured bound** is surfaced as a WARNING (`The configured {{ side }} bound {{ bound }} is not a valid FHIR {{ type }} string.`), and an unparseable **instance value** raises a separate diagnostic (`The value {{ value }} is not a valid FHIR {{ type }} string.`) rather than silently passing.

See [Validation Reports & Violation Codes](/validation/reports.md) for how these severities surface in the report.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://php-fhir-tools.ardenexal.net/validation/ranges.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.