Validating
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, and every route below uses it or the JSON Schema generated from it.
Ways to validate
Open 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.
Connect your assistant to the docs MCP server and ask it to validate the file. The validate_well tool runs parseWell and returns errors with their paths, plus advisory warnings.
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).
}
Validate against the JSON Schema with any draft 2020-12 validator:
https://welldot.org/schema/v2/well.schema.json
See 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 and dangling references. The MCP server returns them separately, computed by @welldot/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;
fromis smaller thanto;- 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 in the spec.