# 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`.

::steps

### Start with the version and the identity

Every file starts with `version`. Files written today use `"2.4"`, as a string ([Versioning](/format/spec/v2/format-reference#versioning)). `well_type` is the construction method, here a drilled `tubular` well. The spec requires it ([core identity](/format/spec/v2/format-reference#core-identity)), although `parseWell` currently accepts a file without it.

```json
{
  "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](/format/spec/v2/format-reference#location)).

### Describe the hole

The borehole is a list of intervals, one per diameter. Depths are meters below ground and diameters are millimeters ([Units](/format/spec/v2/format-reference#units)). This hole is drilled at 254 mm (10 in) to 60 m.

```json
"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.

```json
"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](/format/spec/v2/format-reference#diameter-and-the-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](/format/spec/reference/fgdc-textures).

```json
"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.

```json
"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`.

::well-preview

```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](https://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](/ai/mcp) to validate it.
- From code, call `parseWell` from [`@welldot/core`](/core/getting-started/first-use).

If something is wrong, the validator names the field: `well_screen[0].screen_slot: Required` means the first screen has no slot size. [Validating](/format/guides/validating) explains the messages.

## Where to go next

- Add a water level: a `spot_measurement` event in `hydrodynamic_events` ([schema](/format/spec/v2/object-schemas#spot_measurement)).
- Read [Writing a .well by hand](/format/guides/writing-by-hand) for the habits that keep a file valid as it grows.
- Browse the [example wells](/format/reference/examples) for complete records.