# Units and precision

> Why every number in a .well file has one fixed SI unit, which units apply to which fields, how to convert non-SI reports, and how to record measurement precision.

A `.well` file never says which units it uses. Each kind of quantity has exactly one unit, fixed by the specification: depths in meters, diameters in millimeters, flow rates in cubic meters per hour, and so on. Two files that describe the same well therefore contain the same numbers.

## The units

The main ones, from the spec's [canonical units](/format/spec/v2/format-reference#canonical-units) table:

| Quantity                                 | Unit           |
| ---------------------------------------- | -------------- |
| Depth, length, elevation                 | m              |
| Diameter (hole, casing, screen, annulus) | mm             |
| Screen slot opening                      | mm             |
| Flow rate                                | m³/h           |
| Elapsed time, test duration              | min            |
| Volume                                   | m³             |
| Transmissivity                           | m²/s           |
| Hydraulic conductivity                   | m/s            |
| Power                                    | kW             |
| Substance concentration                  | mg/L           |
| Electrical conductivity                  | µS/cm at 25 °C |
| Angles (azimuth, dip)                    | degrees        |

The spec binds every numeric field to its unit in the [field-to-unit binding](/format/spec/v2/format-reference#field-to-unit-binding-normative) list. Water quality results take their unit from the parameter code; see [water quality units](/format/spec/v2/water-quality#units).

::note
The wellhead pad (`cement_pad`) is in meters like every other length, so a 1 × 1 m pad is written `1.0`, not `1000`.
::

## Why one unit

Configurable units would let the same well be written in many ways, make comparison harder and allow files whose declared units do not match their numbers. The spec's [rationale](/format/spec/v2/format-reference#rationale) follows GeoJSON (always WGS84) and RFC 3339 (always an offset): one well, one encoding. Display and input units belong to the applications that read and write the files.

## Converting reports

Reports often use inches, feet, gallons per minute or slot numbers. Convert them before writing the file ([rationale](/format/spec/v2/format-reference#rationale)):

| In the report         | In the file                                                      |
| --------------------- | ---------------------------------------------------------------- |
| Hole drilled at 10 in | `"diameter": 254`                                                |
| Casing 6 in (nominal) | the real outer diameter, for example `168.3` for 6 in steel pipe |
| Screen slot 20        | `"screen_slot": 0.508` (20 thousandths of an inch)               |
| Depth 150 ft          | `45.72`                                                          |
| Yield 50 US gpm       | `11.36` m³/h                                                     |
| Pump 5 hp             | `3.73` kW                                                        |

Two details matter:

- **As-built diameters.** Casing, screen and annulus diameters are the real outer diameter in millimeters, not the nominal trade size. A 6 in casing with an outer diameter of 168.3 mm is written `168.3`, not `152.4` ([as-built convention](/format/spec/v2/format-reference#diameter-and-the-as-built-convention)).
- **Slot numbers.** A US slot number is thousandths of an inch: slot 20 is 0.508 mm ([screen slot](/format/spec/v2/format-reference#screen-slot)).

`@welldot/core` ships the common conversions (`inchesToMm`, `feetToMeters`, `slotNumberToMm`, `usGallonsPerMinuteToCubicMeterPerHour`, `hpToKilowatts` and more). See [Unit conversion](/core/guides/unit-conversion).

## Dates and times

Dates and times have fixed forms too ([datetime conventions](/format/spec/v2/format-reference#datetime-conventions)):

- **Calendar dates** (`YYYY-MM-DD`) for the construction date and legal documents such as permits.
- **Instants** (RFC 3339 with a UTC offset, such as `2024-09-03T08:00:00-03:00`) for every measurement, test, log entry and sample. An instant without an offset is invalid.

A laboratory date known only to the day is written at local midnight with a `_resolution: "day"` marker ([instants known only by date](/format/spec/v2/format-reference#instants-known-only-by-date-since-v23)).

## Precision

Some measurements can carry their uncertainty in a sibling field named with `_precision`: `static_level_precision`, `depth_precision`, `lat_precision`, a result's `value_precision`. The value is one standard deviation, in the unit of the measurement it qualifies.

```json
{ "static_level": 3.94, "static_level_precision": 0.01 }
```

Laboratories usually report an expanded uncertainty U with a coverage factor k (often k = 2). Store U / k, not U. The full list of precision fields is in [Precision and uncertainty](/format/spec/v2/format-reference#precision-and-uncertainty).

::tip
Leave a precision field out when the report does not state one. A missing precision means "not documented", which is honest; an invented one is not.
::

## Coordinates

Coordinates are decimal degrees in a geographic reference system, WGS84 by default. Projected coordinates such as UTM must be converted to latitude and longitude before writing; the original system can be kept in `location.properties.original_crs` ([CRS scope](/format/spec/v2/format-reference#crs-scope)).