Units and 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 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 list. Water quality results take their unit from the parameter code; see water quality units.
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 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):
| 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, not152.4(as-built convention). - Slot numbers. A US slot number is thousandths of an inch: slot 20 is 0.508 mm (screen slot).
@welldot/core ships the common conversions (inchesToMm, feetToMeters, slotNumberToMm, usGallonsPerMinuteToCubicMeterPerHour, hpToKilowatts and more). See Unit conversion.
Dates and times
Dates and times have fixed forms too (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).
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.
{ "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.
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).