For geologists

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 editor writes it for you if you prefer forms to JSON.

The well below is one of the example files: 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.

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 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.

Identity and location

Lithology, fractures and cavities

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

{
  "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 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, Fracture and Cave schemas.

Construction

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

A casing that sticks up above the ground starts at a negative depth, for example "from": -0.5. The schemas are in Object schemas, and the recommended names for materials are in Construction materials.

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:

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.

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.

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.

What to do with missing data

Leave it out. The format is built for graceful incompleteness: a field without a value is omitted, never filled with a guess, zero or null (absent values). A file with only construction and lithology is complete enough to be drawn and registered, and more can be added later.

Next

• Your first .well file
• Converting a report, by hand or with an AI assistant
• Depths and intervals