# Welldot

> Open-source ecosystem for geological water well log visualization and data management, built around the `.well` open file format: a JSON standard to digitally communicate, register and store water well data instead of raw scanned images, PDFs or closed formats. Everything is Apache 2.0 licensed and free. Welldot provides a web application for drawing well construction and lithology profiles, plus framework-agnostic TypeScript libraries to read, validate, analyze and render `.well` files.

## Documentation Sets

- [Complete documentation](https://docs.welldot.org/llms-full.txt): Every hand-written and spec page in one file.

## The .well format

- [The .well format](https://docs.welldot.org/raw/format.md): An open JSON format for the complete record of a water well, from construction and lithology to tests, operation, permits and water quality.
- [What is .well?](https://docs.welldot.org/raw/format/getting-started/what-is-well.md): What a .well file holds, the problem it solves, and how the specification, the JSON Schema and the welldot packages fit together.
- [For geologists](https://docs.welldot.org/raw/format/getting-started/for-geologists.md): How the parts of a drilling report and a well's later history map onto a .well file, explained in field terms.
- [For developers](https://docs.welldot.org/raw/format/getting-started/for-developers.md): Read, validate and write .well files from code, what the schema guarantees, and which parts of the spec matter most when you build on the format.
- [Your first .well file](https://docs.welldot.org/raw/format/getting-started/first-well-file.md): Write a small, valid .well file by hand, step by step, and see the profile it draws.
- [Depths and intervals](https://docs.welldot.org/raw/format/concepts/depths-and-intervals.md): How .well measures depth from the ground surface, writes components as from/to intervals, and handles stick-up, water levels above ground and the well's usable depth.
- [Units and precision](https://docs.welldot.org/raw/format/concepts/units-and-precision.md): Why every number in a .well file has one fixed SI unit, which units apply to which fields, how to convert non-SI reports, and how to record measurement precision.
- [Vocabularies](https://docs.welldot.org/raw/format/concepts/vocabularies.md): Open and closed vocabularies in .well, how recommended values and x- values work, and where the lithology textures and water quality parameters come from.
- [Profiles](https://docs.welldot.org/raw/format/concepts/profiles.md): How a .well file declares that it follows extra rules, such as a regulator's required fields, using JSON Schema profiles.
- [Versions and deprecation](https://docs.welldot.org/raw/format/concepts/versions-and-deprecation.md): How .well versions are written and compared, what readers do with older and newer files, and how fields are deprecated without breaking existing files.
- [Extensibility](https://docs.welldot.org/raw/format/concepts/extensibility.md): How to carry data the spec does not define, with x- fields, x- blocks and x- vocabulary values, and why every reader must keep them.
- [Writing a .well by hand](https://docs.welldot.org/raw/format/guides/writing-by-hand.md): Habits that keep a hand-written .well file valid and faithful as it grows, from the order of blocks to ids, dates and test readings.
- [Converting a report](https://docs.welldot.org/raw/format/guides/converting-a-report.md): Turn a drilling report, well log or laboratory report into a .well file, by hand or with an AI assistant running the welldot-converter skill, and check the result.
- [Validating](https://docs.welldot.org/raw/format/guides/validating.md): Check that a .well file is valid, in the browser, with an AI assistant, from TypeScript or with the JSON Schema in any language, and read the error messages.
- [Extending for your own needs](https://docs.welldot.org/raw/format/guides/extending.md): Add the data your project needs to .well files with x- extensions, decide between a local extension, a profile and a spec change, and propose a change to the format.
- [Building an editor or database on .well](https://docs.welldot.org/raw/format/guides/building-on-well.md): Design decisions for software that reads and writes .well files at scale, such as editors, registries, databases and data pipelines, with links to the rules behind each.
- [JSON Schema](https://docs.welldot.org/raw/format/reference/json-schema.md): The published JSON Schema for .well v2, where it comes from, and how to validate files with it in editors and in languages other than TypeScript.
- [Example wells](https://docs.welldot.org/raw/format/reference/examples.md): Nineteen complete, valid .well files built on real Brazilian wells, covering crystalline, karst, sedimentary, shallow and problem cases, with live previews and download links.
- [Reference](https://docs.welldot.org/raw/format/reference.md): Lookup material for the .well format, generated from the schema and the spec: objects and fields, the JSON Schema, vocabularies and example files.
- [The specification](https://docs.welldot.org/raw/format/spec.md): The normative .well specification, how it is organized, how it relates to this site and to the packages, and how it changes.
- [Format changelog](https://docs.welldot.org/raw/format/changelog.md): The revisions of the .well format, each linking to its "Changes in v2.x" section in the specification overview.
- [Object reference](https://docs.welldot.org/raw/format/reference/objects.md): Every object of the .well format and its fields, generated from the JSON Schema.
- [.well File Format Specification — Version 2.4: Overview](https://docs.welldot.org/raw/format/spec/v2/overview.md): The .well v2 specification is split into five documents. This one gives the context: what changed in each revision (v2.4, v2.3, v2.1 and from v1), why the format exists, the design principles the oth…
- [.well File Format Specification — Version 2.4: Format Reference](https://docs.welldot.org/raw/format/spec/v2/format-reference.md): This part of the .well v2.4 specification defines the file as a whole: the top-level structure and fields, how versions and deprecations work, datetime conventions, the recommended values of every op…
- [.well File Format Specification — Version 2.4: Interoperability](https://docs.welldot.org/raw/format/spec/v2/interoperability.md): This part of the .well v2.4 specification covers how .well connects to other standards and tools: the reserved JSON-LD @context and its publication plan, how the format maps onto the OGC GroundWaterM…
- [.well File Format Specification — Version 2.4: Object Schemas](https://docs.welldot.org/raw/format/spec/v2/object-schemas.md): This part of the .well v2.4 specification defines the records inside each top-level block: the common types (Attachment, date durations), the construction and geology objects, the hydrodynamic_events…
- [.well File Format Specification — Version 2.4: Water Quality](https://docs.welldot.org/raw/format/spec/v2/water-quality.md): This document specifies the water_samples block _(since v2.3)_: the sample and result schemas, the recommended values, the unit rules, the welldot parameter vocabulary and how jurisdiction requiremen…
- [.well File Format Specification](https://docs.welldot.org/raw/format/spec/v1/well-format.md): This is the specification of version 1 of the .well format: one JSON file that holds the static record of one water well, its identity, construction (borehole, casing, screens, fills, cement pad) and…
- [FGDC Texture Patterns Reference](https://docs.welldot.org/raw/format/spec/reference/fgdc-textures.md): This document lists all texture patterns available in FGDC_TEXTURES_OPTIONS from @welldot/core. These codes follow the FGDC (Federal Geographic Data Committee) digital cartographic standard for geolo…
- [JSON Schema (v2)](https://welldot.org/schema/v2/well.schema.json): Machine-readable schema, generated from the Zod validators.

## Guides

- [Contributing](https://docs.welldot.org/raw/contributing.md): How to contribute to welldot, from reporting a problem with the docs to proposing a change to the .well format, and where each kind of change lives.
- [Content components](https://docs.welldot.org/raw/contributing/components.md): The components a docs page can use, with the MDC syntax that produces each one.
- [Update rules](https://docs.welldot.org/raw/contributing/update-rules.md): Which code and spec changes need a docs change in the same pull request, what CI checks automatically, and the checklist to run at the end of every change to the spec or a published package.
- [Writing docs](https://docs.welldot.org/raw/contributing/writing-docs.md): The writing rules for docs.welldot.org, how pages are organized and ordered, how to add a page, which pages are generated, and how to run and check the site locally.

## @welldot/core

- [@welldot/core](https://docs.welldot.org/raw/core.md): The TypeScript reference implementation of the .well format, with types, Zod validators, serialization, unit conversion, vocabularies and water quality data.
- [@welldot/core changelog](https://docs.welldot.org/raw/core/changelog.md)
- [First use](https://docs.welldot.org/raw/core/getting-started/first-use.md): Read a .well file with @welldot/core, handle validation errors, inspect the typed data, change it and save it again.
- [Installation](https://docs.welldot.org/raw/core/getting-started/installation.md): Install @welldot/core with npm, pnpm or yarn, check the requirements, and find the JSON Schema and example files it ships with.
- [Parsing and validating](https://docs.welldot.org/raw/core/guides/parsing-and-validating.md): Validate .well text with parseWell, validate objects with WellSchema and the per-object schemas, turn Zod issues into readable messages, and read legacy files.
- [Serializing and sharing](https://docs.welldot.org/raw/core/guides/serializing-and-sharing.md): Write a Well back to .well text with serializeWell, keep unknown members, check whether a well holds data, and redact sections before sharing a file.
- [Unit conversion](https://docs.welldot.org/raw/core/guides/unit-conversion.md): Convert between the canonical SI units of .well files and the units people read and type, with the conversion helpers of @welldot/core.
- [Versions and time zones](https://docs.welldot.org/raw/core/guides/versions-and-time-zones.md): Work with the .well version field and the well site time zone using WELL_FORMAT_VERSION, parseFormatVersion, compareFormatVersions and isIanaTimeZone.
- [Vocabularies and textures](https://docs.welldot.org/raw/core/guides/vocabularies-and-textures.md): Use the recommended and closed vocabularies that @welldot/core publishes as data, show English and Portuguese labels, type open fields with OpenVocab, and look up FGDC textures.
- [Water quality vocabulary](https://docs.welldot.org/raw/core/guides/water-quality-vocabulary.md): Look up water quality parameters, their units and labels, resolve CAS numbers, and use the WHO, EU and Brazilian limit sets that @welldot/core ships as data.
- [API reference](https://docs.welldot.org/raw/core/api.md): Functions, classes and types exported by @welldot/core.

## @welldot/utils

- [@welldot/utils](https://docs.welldot.org/raw/utils.md): Pure functions that analyze a parsed .well file, from volumes and drawdown to permit status, production totals and water quality indicators, following the spec's derivation rules.
- [@welldot/utils changelog](https://docs.welldot.org/raw/utils/changelog.md)
- [First use](https://docs.welldot.org/raw/utils/getting-started/first-use.md): Load a .well file and compute a well summary with @welldot/utils, covering depth, gravel pack volume, water levels, specific capacity, status and production.
- [Installation](https://docs.welldot.org/raw/utils/getting-started/installation.md): Install @welldot/utils, its relationship to @welldot/core, and the separate SIAGAS entry point.
- [Formatting](https://docs.welldot.org/raw/utils/guides/formatting.md): Display numbers, dates, calendar dates, coordinates and unit labels from .well data without floating-point noise or time zone shifts, using the display helpers of @welldot/utils.
- [Geometry and volumes](https://docs.welldot.org/raw/utils/guides/geometry-and-volumes.md): Estimate gravel pack and seal volumes, compute cylindrical and annular volumes, and read depths and diameters from a well's construction with @welldot/utils.
- [Logger import](https://docs.welldot.org/raw/utils/guides/logger-import.md): Turn a pressure transducer or data logger export into logger_series readings, with column mapping, time zones, merging and downsampling, using @welldot/utils.
- [Operation and production](https://docs.welldot.org/raw/utils/guides/operation.md): Derive production volumes from meter readings, total them by period, read the operating regime and the well's current status, and collect operation warnings with @welldot/utils.
- [Permits](https://docs.welldot.org/raw/utils/guides/permits.md): Derive a permit's status, list condition deadlines and whether each was met, follow renewals, and collect permit warnings with @welldot/utils.
- [Water levels and pumping tests](https://docs.welldot.org/raw/utils/guides/pumping-tests.md): Read the current static and dynamic levels, compute drawdown and specific capacity, prepare pumping test plots and respect ledger corrections with @welldot/utils.
- [SIAGAS import](https://docs.welldot.org/raw/utils/guides/siagas-import.md): Import a Brazilian well from the SIAGAS groundwater registry, and its RIMAS monitoring series, into a .well file with @welldot/utils/siagas.
- [Water quality](https://docs.welldot.org/raw/utils/guides/water-quality.md): Compare water samples with WHO, EU or Brazilian limits, compute ion balance, hydrochemical facies and Piper and Stiff values, and check field QA/QC with @welldot/utils.
- [API reference](https://docs.welldot.org/raw/utils/api.md): Functions, classes and types exported by @welldot/utils.

## @welldot/render

- [@welldot/render](https://docs.welldot.org/raw/render.md): A D3 renderer that draws a .well file as a technical well profile in SVG, with lithology patterns, construction, fractures, caves, labels, zoom and tooltips.
- [@welldot/render changelog](https://docs.welldot.org/raw/render/changelog.md)
- [First use](https://docs.welldot.org/raw/render/getting-started/first-use.md): Draw a .well file into an SVG element with WellRenderer, from parsing the file to redrawing when the data changes.
- [Installation](https://docs.welldot.org/raw/render/getting-started/installation.md): Install @welldot/render, its runtime requirements, and how to keep it out of server-side rendering.
- [Using it in a framework](https://docs.welldot.org/raw/render/guides/frameworks.md): Wrap WellRenderer in a Vue or React component that renders on the client only, redraws when the data changes, follows the container width and cleans up.
- [Zoom, pan and highlights](https://docs.welldot.org/raw/render/guides/interaction.md): Control zoom and pan, build zoom buttons that stay in sync with the mouse, and highlight intervals or items of the profile from your own UI.
- [Layers and labels](https://docs.welldot.org/raw/render/guides/layers-and-labels.md): What each layer of the profile shows and which .well block it comes from, and how to turn on depth labels, descriptions, unit strips, construction labels and the optional layers.
- [Legends](https://docs.welldot.org/raw/render/guides/legends.md): Explain the symbols of a profile with a ready-made SVG legend, or build your own legend layout from the legend entries and per-symbol drawings.
- [Locale and units](https://docs.welldot.org/raw/render/guides/locale-and-units.md): Draw the profile's labels, tooltips and legend in English or Portuguese, and show depths in meters or feet and diameters in millimeters or inches.
- [Panels and layout](https://docs.welldot.org/raw/render/guides/panels-and-layout.md): Size the drawing, split a long well over several panels, choose each panel's depth window, repeat bands between pages, and handle casing stick-up.
- [Theming](https://docs.welldot.org/raw/render/guides/theming.md): Change the colors, strokes and fonts of the profile with a WellTheme, set up a dark theme that follows your site, and rename the SVG classes.
- [API reference](https://docs.welldot.org/raw/render/api.md): Functions, classes and types exported by @welldot/render.

## AI tools

- [AI and agents](https://docs.welldot.org/raw/ai.md): How AI assistants can read these docs, validate .well files and convert well reports, through the MCP server, llms.txt and the welldot-converter skill.
- [Converting reports with an assistant](https://docs.welldot.org/raw/ai/conversion-skill.md): Use the welldot-converter Agent Skill to turn water well reports in any language into validated .well files with Claude, ChatGPT, Gemini, Cursor or Codex.
- [llms.txt and Markdown pages](https://docs.welldot.org/raw/ai/llms.md): Give an AI assistant the welldot docs as plain text, with llms.txt, llms-full.txt, the raw Markdown of every page and the page actions.
- [MCP server](https://docs.welldot.org/raw/ai/mcp.md): Connect an AI assistant to the welldot docs MCP server to search the documentation, read pages and validate .well files, with setup for Claude Code, Claude Desktop, Cursor, VS Code and Gemini CLI.
- [Welldot MCP server](https://docs.welldot.org/mcp): Model Context Protocol endpoint: search the docs and validate .well files.