# Vocabularies

> Open and closed vocabularies in .well, how recommended values and x- values work, and where the lithology textures and water quality parameters come from.

Many fields in a `.well` file take a word from a list: the construction method, the casing material, the type of a pumping test, the category of a log entry. The format distinguishes two kinds of lists.

## Open vocabularies

Most lists are **open**. The spec recommends a set of values so that files from different sources agree, but any string is valid. A value outside the recommended set should start with `x-`, and every tool must keep it and show it as written ([recommended vocabularies](/format/spec/v2/format-reference#recommended-vocabularies)).

```json
{ "from": 0, "to": 12, "diameter": 200, "drilling_method": "x-jetting" }
```

Here `x-jetting` says plainly that jetting is not one of the recommended drilling methods (rotary, percussion, cable tool, auger, air hammer), while keeping the information.

Values are stored as their key (`stainless_steel`), never as a translated label (`Aço inox`). Labels are the job of the application; `@welldot/core` publishes English and Portuguese labels for every recommended value ([Vocabularies and textures](/core/guides/vocabularies-and-textures)).

Some open vocabularies, with their spec tables:

| Field                                                        | Recommended values                                                                                              |
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| `well_type`                                                  | [construction methods](/format/spec/v2/format-reference#well_type--recommended-values)                          |
| `well_purpose`                                               | [uses](/format/spec/v2/format-reference#well_purpose--recommended-values-since-v21)                             |
| `bore_hole[].drilling_method`                                | [drilling methods](/format/spec/v2/format-reference#bore_holedrilling_method--recommended-values-since-v23)     |
| `well_case[].type`, `well_screen[].type`, `reduction[].type` | [construction materials](/format/spec/v2/format-reference#construction-materials--recommended-values-since-v23) |
| `well_screen[].slot_type`                                    | [screen designs](/format/spec/v2/format-reference#well_screenslot_type--recommended-values-since-v23)           |
| `hydrodynamic_events[].type`                                 | [event types](/format/spec/v2/object-schemas#event-types)                                                       |
| `aquifer_analysis[].method`                                  | [analysis methods](/format/spec/v2/format-reference#aquifer_analysismethod--recommended-values)                 |
| `history_logs[].category`                                    | [log categories](/format/spec/v2/format-reference#history_logscategory--recommended-values)                     |

The full list is under [Recommended vocabularies](/format/spec/v2/format-reference#recommended-vocabularies) in the format reference.

::do-dont
#do
Use the recommended value when the report states it, and an `x-` value when it states something the list does not have.

```json
{ "type": "galvanized_steel" }
{ "type": "x-concrete" }
{ "drilling_method": "x-jetting" }
```

#dont
Force a value into the nearest recommended word, or write a custom value without the prefix.

```json
{ "type": "carbon_steel" }
{ "type": "Tubo de concreto" }
{ "drilling_method": "rotary" }
```

::

An unprefixed custom value, such as `"Tubo de concreto"`, is still valid: readers must accept and keep it. It is not recommended, because the spec says non-canonical values SHOULD use the `x-` prefix ([recommended vocabularies](/format/spec/v2/format-reference#recommended-vocabularies), [custom vocabulary values](/format/spec/v2/format-reference#custom-vocabulary-values--x--prefix)). The report's exact wording belongs in a free-text field such as `description`, `notes` or `obs`.

## Closed vocabularies

A few fields accept only the listed values, and anything else makes the file invalid. These are fields that software must be able to act on without guessing:

- `hole_fill[].type`: `gravel_pack` or `seal` ([HoleFill](/format/spec/v2/object-schemas#holefill--hole_fill)).
- `history_logs[].status`: `active`, `maintenance`, `inactive`, `decommissioned` or `abandoned` ([allowed values](/format/spec/v2/format-reference#history_logsstatus--allowed-values-since-v23)).
- `permits[].status`, result qualifiers, validation statuses and a few others, each marked in the spec.

## Lithology textures

A lithology layer's `texture` names a fill pattern with a `code` and a `vocabulary` ([Texture](/format/spec/v2/object-schemas#texture)). The default vocabulary is `fgdc`, the lithology patterns of the US Federal Geographic Data Committee's geologic map symbolization standard (FGDC-STD-013-2006). The 600 series (sedimentary) and 700 series (metamorphic and igneous) are the most useful for well logs. All 282 codes, and which of them have a drawn pattern, are in the [FGDC texture reference](/format/spec/reference/fgdc-textures).

```json
{ "texture": { "code": 627, "vocabulary": "fgdc" } }
```

Other vocabularies are allowed: `cgi` (the CGI Simple Lithology terms), or the HTTPS address of a vocabulary published by a survey or regulator ([vocabulary values](/format/spec/v2/object-schemas#vocabulary-values)).

## Water quality parameters

A result's parameter is also a code in a vocabulary: `{ "code": "nitrate_as_n", "vocabulary": "welldot" }`. The `welldot` vocabulary has 98 parameters, each with a fixed unit; CAS registry numbers (`"vocabulary": "cas"`) are accepted for substances, and `x-` vocabularies for anything else ([parameter vocabulary](/format/spec/v2/water-quality#parameter-vocabulary)).

## How values become official

When an `x-` value proves common, a later revision of the spec can promote it. The `x-` form then stays equivalent until the next major version ([vocabulary value promotion](/format/spec/v2/format-reference#vocabulary-value-promotion)). To propose a value, open an issue; see [Extending the format](/format/guides/extending).