# Validating

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

A file is valid when it follows the schema: the required blocks are present, every field has the right type and every closed vocabulary has an allowed value. There is one definition of valid, `parseWell` from [`@welldot/core`](/core), and every route below uses it or the JSON Schema generated from it.

## Ways to validate

::tabs

:::tabs-item{label="Browser" icon="i-lucide-globe"}
Open [welldot.org](https://welldot.org) and drop the file on the editor. An invalid file is reported with the path of each problem.

On this site, a `::well-preview` block validates its content and lists the errors instead of drawing.
:::

:::tabs-item{label="AI assistant" icon="i-lucide-sparkles"}
Connect your assistant to the [docs MCP server](/ai/mcp) and ask it to validate the file. The `validate_well` tool runs `parseWell` and returns errors with their paths, plus advisory warnings.
:::

:::tabs-item{label="TypeScript" icon="i-lucide-code"}

```ts
import { parseWell } from '@welldot/core';

try {
  const well = parseWell(text);
} catch (error) {
  // Schema problems: a ZodError whose issues each have a path.
  // Invalid JSON or an unsupported version: a plain Error (SyntaxError for JSON).
}
```

See [Parsing and validating](/core/guides/parsing-and-validating).
:::

:::tabs-item{label="Other languages" icon="i-lucide-braces"}
Validate against the JSON Schema with any draft 2020-12 validator:

```text
https://welldot.org/schema/v2/well.schema.json
```

See [JSON Schema](/format/reference/json-schema).
:::

::

## Reading the errors

Each error has a path into the document and a message. Array positions count from zero.

| Error                                                                                        | Meaning                                                     |
| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `well_screen[0].screen_slot: Required`                                                       | The first screen has no `screen_slot`.                      |
| `bore_hole[1].to: Expected number, received string`                                          | A depth was written in quotes, or with its unit (`"60 m"`). |
| `hole_fill[2].type: Invalid enum value. Expected 'gravel_pack' \| 'seal', received 'gravel'` | `hole_fill` types are a closed list.                        |
| `fractures: Required`                                                                        | A required list is missing; write `[]` if there are none.   |
| `construction_date: construction_date must be YYYY-MM-DD`                                    | A date in another form, such as `20/05/2019`.               |
| `version: Unsupported .well format version: "3.0"` (code `unsupported_version`)              | The file declares a version this reader does not know.      |

The last row is not a schema error. `parseWell` throws a plain `Error` with the message `Unsupported .well format version: "3.0"` (or `Malformed .well format version: …`) before the schema runs. The MCP validator and this site report it with the path `version` and the code `unsupported_version`.

Fix the first errors first: one missing bracket or a wrong type high in the file can cause several messages below it.

## Errors and warnings

**Errors** make a file invalid. They come from the schema.

**Warnings** do not. They point at data that is valid but probably wrong, or that a calculation cannot use: a permit whose validity ends before it starts, a meter reading that goes backwards, a pump intake below the bottom of the well, a dangling reference. The spec marks these "warnings, never rejection"; see for example [permit validation](/format/spec/v2/object-schemas#validation-warnings-never-rejection-1) and [dangling references](/format/spec/v2/format-reference#dangling-references). The MCP server returns them separately, computed by [`@welldot/utils`](/utils).

## What validation does not check

Validation checks shape, not truth. It does not check that:

- a casing fits inside its hole, or that intervals do not overlap;
- `from` is smaller than `to`;
- the numbers match the source report;
- the texture code fits the description.

Some of these are good candidates for warnings in your own tools. The spec decides which rules exist; a validator never adds its own, so that every tool accepts the same files.

## The JSON Schema and the library

The JSON Schema is generated from the same Zod validators that `parseWell` uses, so they accept the same documents. A few rules can only be expressed in code, and `parseWell` also upgrades v1 files before checking them. When in doubt, `parseWell` is the reference. See [Schema validation](/format/spec/v2/interoperability#schema-validation) in the spec.