.well File Format Specification

Version: 1.0 Extension: .wellEncoding: UTF-8 Base format: JSON

Overview

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 geology (lithology, fractures, caves). v1 is stable and kept for reference. New files use version 2, described in ../v2/overview.md; deserializeWell() in @welldot/core reads v1 files and normalizes them to v2.

Table of contents

• Purpose
• Design Principles
• File Structure
• Top-level Fields
  • well_type — Recommended values
• Object Schemas
  • BoreHole — bore_hole[]
  • WellCase — well_case[]
  • Reduction — reduction[]
  • WellScreen — well_screen[]
  • SurfaceCase — surface_case[]
  • HoleFill — hole_fill[]
  • CementPad — cement_pad
  • Lithology — lithology[]
  • Fracture — fractures[]
  • Cave — caves[]
• Complete Example
• Versioning
• MIME Type

Purpose

The .well format is an open standard for representing water well data. It is designed to serve three distinct but complementary use cases:

Visualization. The format contains sufficient constructive and geological detail to produce accurate technical well profile drawings — including borehole geometry, casing strings, screens, gravel packs, lithological columns, fractures, and caves — at true depth scale.

Registration. The format captures the administrative and physical identity of a well, providing a complete static record suitable for submission to regulatory bodies, inclusion in national well registries, and long-term archival.

Research. The structured geological and constructive data enables cross-well analysis, aquifer characterization, and hydrogeological research. Field vocabulary choices (FGDC texture codes, geologic units, aquifer units) are aligned with standards used in scientific literature. Dynamic hydrological measurements — static level, dynamic level, pump tests, water quality — are outside the scope of v1 and are reserved for a future hydro extension block.

Design Principles

• Self-describing — full field names are used throughout; a .well file can be read and understood without consulting the spec
• Versioned — includes a version field for forward compatibility; parsers must reject unrecognized versions
• Self-contained — a single file encodes the complete static record of one well
• SI units — all depths are in meters, all diameters in millimeters; applications are responsible for unit conversion on display
• Geographic north — all azimuth values are referenced to geographic north
• Ground level as zero — all depth values are measured from ground level (0); elevation above sea level is stored separately in the elevation field

File Structure

A .well file is a JSON object with the following top-level structure:

{
  "version": 1,

  "well_type": "tubular",
  "name": "Poço PP-01",
  "well_driller": "Perfuradora XYZ",
  "construction_date": "2024-03-15",
  "lat": -1.4558,
  "lng": -48.5039,
  "elevation": 12.5,
  "obs": "Observações livres",

  "bore_hole": [ ... ],
  "well_case": [ ... ],
  "reduction": [ ... ],
  "well_screen": [ ... ],
  "surface_case": [ ... ],
  "hole_fill": [ ... ],
  "cement_pad": { ... },

  "lithology": [ ... ],
  "fractures": [ ... ],
  "caves": [ ... ]
}

Top-level Fields

well_type — Recommended values

The well_type field accepts any string. The values above are the recommended vocabulary for interoperability. Tools should treat unrecognized values gracefully.

Object Schemas

BoreHole — bore_hole[]

Represents a drilled interval of the borehole. Multiple entries describe a telescoping borehole with different diameters at different depth ranges.

{ "from": 0, "to": 80, "diameter": 250, "drilling_method": "rotary" }

WellCase — well_case[]

Steel or plastic casing installed inside the borehole.

{ "from": 0, "to": 60, "type": "steel", "diameter": 200 }

Reduction — reduction[]

A transition piece connecting two casing or screen sections of different diameters.

{ "from": 58, "to": 60, "diam_from": 200, "diam_to": 150, "type": "conical" }

WellScreen — well_screen[]

Slotted or wire-wound screen section that allows water to enter the well.

{
  "from": 60,
  "to": 80,
  "type": "wire_wound",
  "diameter": 150,
  "screen_slot_mm": 0.5
}

SurfaceCase — surface_case[]

Outer protective casing installed near the surface, typically to prevent surface contamination.

{ "from": 0, "to": 3, "diameter": 300 }

HoleFill — hole_fill[]

Material placed in the annular space between the casing and the borehole wall.

{
  "from": 60,
  "to": 80,
  "type": "gravel_pack",
  "diameter": 250,
  "description": "Seixo 2-4mm"
}

CementPad — cement_pad

The concrete pad installed at ground level (depth 0) around the wellhead. Dimensions are in meters.

{ "type": "square", "width": 1.0, "thickness": 0.15, "length": 1.0 }

Lithology — lithology[]

Geological description of a depth interval.

{
  "from": 0,
  "to": 20,
  "description": "Areia fina amarelada",
  "color": "#f5deb3",
  "fgdc_texture": "sand",
  "geologic_unit": "Quaternário",
  "aquifer_unit": "freático"
}

Fracture — fractures[]

A discrete fracture or fracture zone intersected by the borehole.

{
  "depth": 45.2,
  "water_intake": true,
  "description": "Fratura aberta",
  "swarm": false,
  "azimuth": 120,
  "dip": 35
}

Cave — caves[]

A cavity or void zone intersected by the borehole.

{ "from": 50, "to": 52, "water_intake": false, "description": "Caverna seca" }

Complete Example

{
  "version": 1,
  "well_type": "tubular",
  "name": "Poço PP-01",
  "well_driller": "Perfuradora XYZ",
  "construction_date": "2024-03-15",
  "lat": -1.4558,
  "lng": -48.5039,
  "elevation": 12.5,
  "obs": "Sem anomalias observadas durante a perfuração.",

  "bore_hole": [
    { "from": 0, "to": 80, "diameter": 250, "drilling_method": "rotary" }
  ],

  "well_case": [{ "from": 0, "to": 60, "type": "steel", "diameter": 200 }],

  "reduction": [
    {
      "from": 58,
      "to": 60,
      "diam_from": 200,
      "diam_to": 150,
      "type": "conical"
    }
  ],

  "well_screen": [
    {
      "from": 60,
      "to": 80,
      "type": "wire_wound",
      "diameter": 150,
      "screen_slot_mm": 0.5
    }
  ],

  "surface_case": [{ "from": 0, "to": 3, "diameter": 300 }],

  "hole_fill": [
    {
      "from": 60,
      "to": 80,
      "type": "gravel_pack",
      "diameter": 250,
      "description": "Seixo 2-4mm"
    },
    {
      "from": 3,
      "to": 60,
      "type": "seal",
      "diameter": 250,
      "description": "Cimento"
    }
  ],

  "cement_pad": {
    "type": "square",
    "width": 1.0,
    "thickness": 0.15,
    "length": 1.0
  },

  "lithology": [
    {
      "from": 0,
      "to": 20,
      "description": "Areia fina amarelada",
      "color": "#f5deb3",
      "fgdc_texture": "sand",
      "geologic_unit": "Quaternário",
      "aquifer_unit": "freático"
    },
    {
      "from": 20,
      "to": 80,
      "description": "Granito fraturado cinza",
      "color": "#a9a9a9",
      "fgdc_texture": "granite",
      "geologic_unit": "Embasamento Cristalino",
      "aquifer_unit": "fraturado"
    }
  ],

  "fractures": [
    {
      "depth": 45.2,
      "water_intake": true,
      "description": "Fratura aberta",
      "swarm": false,
      "azimuth": 120,
      "dip": 35
    },
    {
      "depth": 62.0,
      "water_intake": false,
      "description": "Fratura de cisalhamento",
      "swarm": true,
      "azimuth": 90,
      "dip": 70
    }
  ],

  "caves": [
    {
      "from": 50,
      "to": 52,
      "water_intake": false,
      "description": "Caverna seca"
    }
  ]
}

Versioning

The version field must always be present and is an integer starting at 1. Parsers must reject files with an unrecognized version value and should warn when version is absent.

A hydro block for dynamic hydrological data (static level, dynamic level, pump tests, water quality) is reserved for v2 and must not appear in v1 files.

MIME Type

application/vnd.well+json

Specification v1.0 — .well format