welldotdocs
Getting started

Your first .well file

Write a small, valid .well file by hand, step by step, and see the profile it draws.

This page builds a small well from an empty file: a 60 m tubular well in sandstone with one casing, one screen, a gravel pack and three lithology layers. You need a text editor. Save the result as demo.well.

Start with the version and the identity

Every file starts with version. Files written today use "2.4", as a string (Versioning). well_type is the construction method, here a drilled tubular well. The spec requires it (core identity), although parseWell currently accepts a file without it.

{
  "version": "2.4",
  "name": "Demo well, sandstone aquifer",
  "well_type": "tubular",
  "location": { "lat": -22.2139, "lng": -49.9458, "elevation": 512 }
}

location is optional. Coordinates are decimal degrees on WGS84 and the elevation is in meters (location).

Describe the hole

The borehole is a list of intervals, one per diameter. Depths are meters below ground and diameters are millimeters (Units). This hole is drilled at 254 mm (10 in) to 60 m.

"bore_hole": [{ "from": 0, "to": 60, "diameter": 254, "drilling_method": "rotary" }]

Add the casing, the screen and the annulus

A blank casing from 0.5 m above ground to 36 m, then a screen to 54 m. The casing starts at -0.5 because it sticks up above the ground. hole_fill describes the annulus: a cement seal at the top and a gravel pack around the screen.

"well_case": [{ "from": -0.5, "to": 36, "type": "pvc", "diameter": 168.3 }],
"well_screen": [
  { "from": 36, "to": 54, "type": "pvc", "diameter": 168.3, "screen_slot": 0.75 }
],
"hole_fill": [
  { "from": 0, "to": 30, "type": "seal", "diameter": 254, "description": "Cement grout" },
  { "from": 30, "to": 60, "type": "gravel_pack", "diameter": 254, "description": "Gravel, 2–4 mm" }
]

Diameters are the real outer diameter (as-built), not the nominal size: a 6 in PVC casing is 168.3 mm (as-built convention).

Add the lithology

Each layer has a depth interval, a description, a color, a texture code for the pattern and the geologic and aquifer units. Code 607 is "massive sand or sandstone" in the FGDC texture reference.

"lithology": [
  { "from": 0, "to": 8, "description": "Red clayey soil", "color": "#9c5a3c", "texture": { "code": 620, "vocabulary": "fgdc" }, "geologic_unit": "Cover", "aquifer_unit": "Unsaturated zone" },
  { "from": 8, "to": 30, "description": "Silty sandstone", "color": "#c9a27a", "texture": { "code": 612, "vocabulary": "fgdc" }, "geologic_unit": "Botucatu Formation", "aquifer_unit": "Guarani" },
  { "from": 30, "to": 60, "description": "Medium-grained sandstone", "color": "#e0c48f", "texture": { "code": 607, "vocabulary": "fgdc" }, "geologic_unit": "Botucatu Formation", "aquifer_unit": "Guarani" }
]

Close the required lists

The construction and geology lists are required even when empty. This well has no reduction, surface casing, fractures or caves, so they are empty lists.

"reduction": [],
"surface_case": [],
"fractures": [],
"caves": []

The complete file

Put the pieces together inside one object. The preview validates the file with @welldot/core and draws it with @welldot/render.

Live previewinline .well
{
  "version": "2.4",
  "name": "Demo well, sandstone aquifer",
  "well_type": "tubular",
  "location": { "lat": -22.2139, "lng": -49.9458, "elevation": 512 },
  "bore_hole": [
    { "from": 0, "to": 60, "diameter": 254, "drilling_method": "rotary" }
  ],
  "well_case": [{ "from": -0.5, "to": 36, "type": "pvc", "diameter": 168.3 }],
  "reduction": [],
  "well_screen": [
    { "from": 36, "to": 54, "type": "pvc", "diameter": 168.3, "screen_slot": 0.75 }
  ],
  "surface_case": [],
  "hole_fill": [
    { "from": 0, "to": 30, "type": "seal", "diameter": 254, "description": "Cement grout" },
    { "from": 30, "to": 60, "type": "gravel_pack", "diameter": 254, "description": "Gravel, 2–4 mm" }
  ],
  "lithology": [
    { "from": 0, "to": 8, "description": "Red clayey soil", "color": "#9c5a3c", "texture": { "code": 620, "vocabulary": "fgdc" }, "geologic_unit": "Cover", "aquifer_unit": "Unsaturated zone" },
    { "from": 8, "to": 30, "description": "Silty sandstone", "color": "#c9a27a", "texture": { "code": 612, "vocabulary": "fgdc" }, "geologic_unit": "Botucatu Formation", "aquifer_unit": "Guarani" },
    { "from": 30, "to": 60, "description": "Medium-grained sandstone", "color": "#e0c48f", "texture": { "code": 607, "vocabulary": "fgdc" }, "geologic_unit": "Botucatu Formation", "aquifer_unit": "Guarani" }
  ],
  "fractures": [],
  "caves": []
}

Check it

  • Open welldot.org and drop demo.well on the editor. It shows the same profile and lets you keep editing with forms.
  • Ask an AI assistant connected to the docs MCP server to validate it.
  • From code, call parseWell from @welldot/core.

If something is wrong, the validator names the field: well_screen[0].screen_slot: Required means the first screen has no slot size. Validating explains the messages.

Where to go next

For developers

Depths and intervals