# For geologists

> How the parts of a drilling report and a well's later history map onto a .well file, explained in field terms.

This page is for geologists, hydrogeologists and drillers who know what a well report contains and want to know where each item goes in a `.well` file. No programming is needed. A `.well` file is text, and the [welldot.org](https://welldot.org) editor writes it for you if you prefer forms to JSON.

The well below is one of the [example files](/format/reference/examples): a 26 m well in the Dunas-Barreiras aquifer with two screens, a gravel pack and a cemented annulus. The profile is drawn from the file itself.

::well-preview{example="extremoz-rn-barreiras-raso"}
::

## Read a file as a report

A file is a list of named blocks. Most blocks are lists of **intervals**: a `from` depth and a `to` depth in meters, measured down from the ground surface. A casing from 0 to 8 m, a sandstone layer from 1.5 to 6 m and a screen from 8 to 11 m are all written the same way. The [depth convention](/format/concepts/depths-and-intervals) is the one idea to learn before anything else.

Measurements use one unit each, always the same: depths in meters, diameters in millimeters, flow rates in m³/h. A casing sold as 6 inches is written with its real outer diameter in millimeters. See [Units and precision](/format/concepts/units-and-precision).

## Identity and location

| In the report                                    | In the file                                                                                                          |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| Well name or code                                | `name`                                                                                                               |
| Type of well (tubular, hand-dug, gallery)        | `well_type`, the construction method only ([values](/format/spec/v2/format-reference#well_type--recommended-values)) |
| Use (supply, monitoring, piezometer)             | `well_purpose`, a list ([values](/format/spec/v2/format-reference#well_purpose--recommended-values-since-v21))       |
| Driller, completion date                         | `well_driller`, `construction_date` (`YYYY-MM-DD`)                                                                   |
| Registry numbers (SIAGAS, CNARH, a state agency) | `well_id`, one entry per authority ([rules](/format/spec/v2/format-reference#well_id))                               |
| Coordinates and ground elevation                 | `location`, in decimal degrees on WGS84 ([rules](/format/spec/v2/format-reference#location))                         |

::tip
An artesian well is not a type of construction. Write `well_type: "tubular"` and record the flowing condition as a water level above ground, which is a negative depth ([level sign convention](/format/spec/v2/format-reference#level-sign-convention)).
::

## Lithology, fractures and cavities

Each layer of the lithological description is one entry of `lithology`:

```json
{
  "from": 1.5,
  "to": 6,
  "description": "Arenito médio a grosso, pouco argiloso, creme-amarelado",
  "color": "#e2cf9a",
  "texture": { "code": 607, "vocabulary": "fgdc" },
  "geologic_unit": "Grupo Barreiras",
  "aquifer_unit": "Sistema Aquífero Dunas-Barreiras"
}
```

- `description` is the driller's or geologist's description, kept in the language of the report.
- `texture` is the fill pattern drawn on the profile. By default it is a code from the FGDC geologic map symbolization standard; the 600 series covers sedimentary rocks and the 700 series metamorphic and igneous rocks. The [FGDC texture reference](/format/spec/reference/fgdc-textures) lists all 282 codes and marks the ones that have a drawn pattern.
- `color` is the color used for the layer, as a hex code.
- `geologic_unit` and `aquifer_unit` name the stratigraphic unit and the aquifer it belongs to.

Discrete fractures go in `fractures` with their depth, dip, azimuth and whether they yield water. Cavities, common in karst, go in `caves` as intervals. See the [Lithology](/format/spec/v2/object-schemas#lithology--lithology), [Fracture](/format/spec/v2/object-schemas#fracture--fractures) and [Cave](/format/spec/v2/object-schemas#cave--caves) schemas.

## Construction

Construction is described as the well was built (as-built), one block per component:

| Component                   | Block          | Notes                                                                  |
| --------------------------- | -------------- | ---------------------------------------------------------------------- |
| Drilled hole                | `bore_hole`    | One entry per diameter; a telescoping hole has several.                |
| Blank casing                | `well_case`    | Material in `type`, outer diameter in mm.                              |
| Screen (filter)             | `well_screen`  | Slot opening in mm (`screen_slot`), screen design in `slot_type`.      |
| Diameter reduction          | `reduction`    | Diameter at the top and at the bottom.                                 |
| Surface (protective) casing | `surface_case` | The outer casing near the surface.                                     |
| Gravel pack and seals       | `hole_fill`    | `type` is `gravel_pack` or `seal`; the material goes in `description`. |
| Centralizers                | `centralizers` | An interval and a spacing, as reports give them.                       |
| Wellhead pad                | `cement_pad`   | Dimensions in meters.                                                  |

A casing that sticks up above the ground starts at a negative depth, for example `"from": -0.5`. The schemas are in [Object schemas](/format/spec/v2/object-schemas#object-schemas), and the recommended names for materials are in [Construction materials](/format/spec/v2/format-reference#construction-materials--recommended-values-since-v23).

## Water levels and pumping tests

Every measurement of the water level and every pumping test is an **event** in `hydrodynamic_events`, kept in time order. Each event has a type:

| Field work                                   | Event `type`       |
| -------------------------------------------- | ------------------ |
| Static level read during a visit             | `spot_measurement` |
| Test at one constant flow rate               | `constant_rate`    |
| Step-drawdown test                           | `step_drawdown`    |
| Air-lift development with an estimated yield | `airlift`          |
| Recovery readings without the drawdown phase | `recovery_only`    |
| Data logger series                           | `logger_series`    |

A test holds its static level, its pumping steps (rate in m³/h, duration in minutes, readings of elapsed time and depth) and an optional recovery phase. Drawdown and specific capacity are **not** stored: software computes them from the readings, so they can never disagree with the data. See [`hydrodynamic_events`](/format/spec/v2/object-schemas#hydrodynamic_events).

The interpretation of a test is a separate entry in `aquifer_analysis`: transmissivity, storativity, Jacob coefficients, recommended flow rate, the method and the analyst, and the ids of the events it used. Several interpretations of the same test can coexist. See [`aquifer_analysis`](/format/spec/v2/object-schemas#aquifer_analysis).

## History, permits and operation

- `history_logs` is the well's logbook: maintenance, inspections, incidents and changes of status (active, inactive, decommissioned, abandoned).
- `permits` records abstraction permits (outorgas), their validity, granted flow and conditions (condicionantes), and when each condition was met.
- `pump_installations` and `meters` record each pump and totalizer for the period it was installed.
- `production` holds meter readings, from which volumes are calculated, and `operating_regime` the declared pumping hours and flow.

These blocks are optional. A drilling report alone fills the construction and geology and leaves them out.

## Water quality

Each sample is one entry of `water_samples`, with its date, sampling point, laboratory and a list of results. A result names its parameter by a code (`nitrate_as_n`, `ph`, `total_coliforms`) and gives a value, a presence or absence, or a text. Results below the detection limit keep their qualifier (`<`). The unit comes from the parameter code, so it is never written next to the value.

Drinking water limits are **not** written in the file. Software compares the results with the limit set the reader chooses (WHO, the EU directive, the Brazilian ordinance). See [Water quality](/format/spec/v2/water-quality).

## What to do with missing data

Leave it out. The format is built for [graceful incompleteness](/format/spec/v2/overview#design-principles): a field without a value is omitted, never filled with a guess, zero or `null` ([absent values](/format/spec/v2/format-reference#absent-values-since-v24)). A file with only construction and lithology is complete enough to be drawn and registered, and more can be added later.

::note
The schema requires the construction and geology blocks even when they are empty: write `"fractures": []` when the report mentions none. The [Well object reference](/format/reference/objects/well) lists which blocks are required, and [Your first .well file](/format/getting-started/first-well-file) shows the minimum.
::

## Next

- [Your first .well file](/format/getting-started/first-well-file)
- [Converting a report](/format/guides/converting-a-report), by hand or with an AI assistant
- [Depths and intervals](/format/concepts/depths-and-intervals)