Well profiles, in open format.
Free editor for the whole record of a well: construction and geological profiles, pumping tests, operation, permits and water quality, exported as PDF. A simple, versioned JSON, readable by any language.
One JSON.
The whole well.
Today, well data lives in PDFs that don't talk to each other. The .well file is a simple, versioned format to change that — a single JSON that fully describes a well, from construction and geology to pump tests, installed pumps, meters and production, permits, water quality and maintenance history, designed as an international standard.
Drawing
Construction and geology at real scale, drawn the same way by any tool that reads the file.
Record
Predictable structure to archive and version well data, ready for submission and auditing.
Research
Organized metric fields allow cross-referencing and comparing wells across aquifers, regions, and eras.
Open
Human-readable JSON, public specification, and permissive license — free to use, extend, and contribute.
Pump tests
Raw test readings plus versioned interpretations — transmissivity, storativity, specific capacity — each tied to the tests it came from. See § III.
Operation & history
Installed pumps, meters, produced volumes and operating regime, water-use permits with their conditions, water-quality samples, and a log of maintenance and incidents across the well's working life.
Today, a water well's data exists in many places: in the driller's notebook, in the consultant's spreadsheet, in the PDF report submitted to the licensing authority. Each in its own format, each unreadable to the other. welldot and the .well format were created to solve this.
This project began as Well Profiler, a tool to draw well diagrams. It's growing into something broader: an open platform for the entire lifecycle of well data — not just the drawing.
Live editor
Tables linked to the drawing. Edit a layer, see the profile redrawn at real scale.
Open format
Human-readable JSON, public specification, and Apache 2.0 license. Implement in any language.
Submission-ready
PDF reports with your branding, the sections you choose and the profile at real scale across pages, in English or Portuguese.
From field readings to aquifer parameters.
Every level measurement and pumping test is an entry in an append-only ledger: spot measurements, constant-rate and step-drawdown tests, air-lift, recovery and more. Readings are stored as taken, and drawdown, s/Q, Q/s and other parameters are calculated automatically.
Tests as recorded
Steps with rate and duration, level readings over time and recovery after the pump stops.
Versioned interpretation
Each analysis records its method, analyst, source tests and results — T, S, K, specific capacity, recommended maximum flow. Several can coexist.
Analysis editor
The editor already reads analyses and shows the current aquifer state. Creating and editing them in the app is on the way.
Sample step-drawdown test, drawn by the editor's charts.
Standard inside,
flexible outside.
A single human-readable text file: archivable in folders, versionable in git, indexable in databases, analyzable by AI. The core is strict where it matters — SI metrics, WGS84, English keys — and flexible everywhere else.
The repository includes a ready-made welldot.skill: point any agent to github.com/rafaeelneto/welldot and it operates the format natively.
Start with what you have.
Well data is rarely complete. A 1987 report with only the depth and an air-lift yield, a registry without coordinates, a log with no lithology, a permit still without a number: each is already a valid .well file. Almost every field is optional, open fields take any text, and a missing field means unknown — never zero. In the field and in old archives, knowing what is missing is information too.
Almost everything is optional
Name, coordinates, construction date, driller, lithology, tests, permits: each block and each field goes in when it exists. Construction blocks can be empty lists. An event needs only an id, a type and a date; a permit, a type and an authority.
Suggested values, free text
Casing material, drilling method, permit type, maintenance type, well use: the format recommends a vocabulary for interoperability, but open fields accept any value. Values outside it take the x- prefix and are kept and shown as written.
Absent is unknown
No regime means unknown flow, not zero. No status change means unknown status, not active. Production before the first meter reading is unknown.
Gaps are data too
Missing details and inconsistencies become warnings for review, never a rejection. The record stays in the file with its history, and what is not known stays visible instead of being filled with made-up values.
{
"version": 2,
"name": "Poço 03",
"well_type": "tubular",
"well_depth": 84,
"obs": "1987 report. No lithological log.",
"bore_hole": [
{
"from": 0,
"to": 84,
"diameter": 250
}
],
"well_case": [
{
"from": 0,
"to": 84,
"diameter": 152,
"type": "x-galvanized_iron"
}
],
"reduction": [],
"well_screen": [],
"surface_case": [],
"hole_fill": [],
"lithology": [],
"fractures": [],
"caves": [],
"hydrodynamic_events": [
{
"id": "evt-01",
"type": "airlift",
"datetime": "1987-03-10T00:00:00-03:00",
"steps": [
{
"rate": 6
}
]
}
]
}Anyone can extend it.
A driller, a consultancy, a water utility, a university or a regulator: anyone can add what their work needs, without asking permission and without breaking anyone else's files. The spec requires every reader to keep these extensions on load and save. And what proves useful to many can become part of the format itself.
Your own fields and blocks
Any object takes fields with the x- prefix, and the file takes whole new top-level blocks: a state registry number, a company's internal code, gas monitoring at a mine.
Profiles for institutions
An agency, a company or a research network publishes a JSON Schema that requires extra fields, narrows vocabularies or sets its own x- extensions. Files declare it under profiles. Failures are warnings, and an unreachable profile never blocks a file.
From x- to the standard
An x- value that proves useful across many sources can be promoted to canonical: x-slug_test becomes slug_test, and both forms stay valid until the next major version. Changes to the core start as an open issue with the data, its real-world source and why no field can carry it.
{
"version": 2,
"name": "Poço 03",
"well_type": "tubular",
"well_depth": 84,
"bore_hole": [],
"well_case": [],
"reduction": [],
"well_screen": [],
"surface_case": [],
"hole_fill": [],
"lithology": [],
"fractures": [],
"caves": [],
"x-siagas": {
"registro": "1500012345"
}
}The future.
v2.3 covers geological, construction and hydrodynamic profiles — pump tests, aquifer analysis, pump installations, meters, production and operating regime, water-use permits and their conditions, water quality, general attachments and operational history. The specification evolves openly, and these are the gaps already mapped for the next versions.
Native .las
Import and storage of LAS geophysical logs (resistivity, gamma ray, caliper), side by side with the lithological profile.
Linked wells
References between files: observation wells for storativity, and one permit shared by several wells instead of repeated in each.
Multilingual text
Descriptions and notes tagged with their language, so the same file can carry Portuguese, English or Spanish text — plain strings stay valid.
Water quality assessment
Interpreted judgments such as water class, hydrochemical facies and fitness for use, stored next to the samples they come from.
Free, open tools, not just an app.
welldot is a set of small, independent packages. Use the editor, or pull just the piece you need into your own stack.
@welldot/core
Types, Zod validators, JSON Schema and serialization for the .well format, plus its vocabularies — materials, permit types, water-quality parameters and limit sets. The foundation everything else builds on.
View source →@welldot/utils
Analysis of a .well file: geometry and volumes, aquifer hydraulics and pumping-test series, production by period and permit deadlines, water-quality derivations such as ion balance, Piper and Stiff.
View source →@welldot/render
The D3-based SVG renderer that draws every profile on this site at real scale, with a configurable theme — embeddable in any web app.
View source →@welldot/pdf
Customizable PDF reports on pdfmake: branding, watermark, page layout, theme, section toggles and order, en/pt labels. Works without any UI framework.
View source →@welldot/vue
Vue 3 base components for .well editors, with the Welldot theme and a Nuxt module.
View source →Profiler app
This editor, source and all. Nuxt 4 + Vue 3, deployed at welldot.org — fork it or read how it's built.
View source →