Format v2.4 · Apache 2.0

The record of a water well, as data.

.well is an open JSON format for the whole record of a water well, from construction and lithology to pumping tests, operation, permits, water quality and history. These docs cover the format, its specification and the libraries that read, validate, analyze and draw it.

Read about the format Specification

Live previewcoluna-mg-cristalino-abastecimento.well

Start here

Two ways in

I work with wells

Geologists, hydrogeologists and drillers: how a drilling report maps onto a .well file, explained in field terms. Lithology, construction, tests, operation, permits and water quality, no code needed.

I build software

Developers: read and validate files from TypeScript or any language with the JSON Schema, what the schema guarantees, and which parts of the spec matter for editors and databases.

The format

One file, one well, every stage of its life

A .well file starts as a drilling report and grows with the well: tests, permits, meters, analyses. Every field has one meaning and one unit, written down in a versioned specification.

Plain JSON

Opens in any editor, parses in any language, diffs in git. Full field names, so a file reads without the spec.

One unit per quantity

Meters, millimeters, m³/h. The file never declares units, so two files of the same well hold the same numbers.

Graceful incompleteness

Unknown values are left out, never invented. A registry record with only its construction is a valid file.

Open to extension

x- fields carry what the spec does not define, and every reader keeps them.

Neutral by design

No national rules inside the file. Regulators add theirs with profiles; limits are chosen when reading.

19 example wells

Complete files built on real Brazilian wells: karst, crystalline, sedimentary, flowing, hand-dug, messy.

Packages

TypeScript libraries, framework-free

The reference implementation of the format, published on npm under Apache 2.0. No UI framework required.

@welldot/core

Types, Zod validators, serialization, unit conversion, vocabularies with English and Portuguese labels, water quality limit sets.

@welldot/utils

Gravel pack volumes, drawdown and specific capacity, permit status and deadlines, production totals, hydrochemistry.

@welldot/render

A D3 renderer that draws the profile in SVG: FGDC lithology patterns, construction as built, zoom, tooltips, legends.

AI and agents

Docs your assistant can check against

Connect Claude, Cursor, VS Code or Gemini CLI to the docs MCP server. Your assistant searches the spec instead of guessing, and validates every .well file it writes with the same parseWell the libraries use.

Set up the MCP server Convert reports with an assistant

Claude Code

claude mcp add --transport http welldot https://docs.welldot.org/mcp

# Tools your assistant gets:
#   search_docs    search the spec, guides and API docs
#   get_page       read any page as Markdown
#   validate_well  check a .well file, errors with paths