Vocabularies
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).
{ "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).
Some open vocabularies, with their spec tables:
| Field | Recommended values |
|---|---|
well_type | construction methods |
well_purpose | uses |
bore_hole[].drilling_method | drilling methods |
well_case[].type, well_screen[].type, reduction[].type | construction materials |
well_screen[].slot_type | screen designs |
hydrodynamic_events[].type | event types |
aquifer_analysis[].method | analysis methods |
history_logs[].category | log categories |
The full list is under Recommended vocabularies in the format reference.
Use the recommended value when the report states it, and an x- value when it states something the list does not have.
{ "type": "galvanized_steel" }
{ "type": "x-concrete" }
{ "drilling_method": "x-jetting" }
Force a value into the nearest recommended word, or write a custom value without the prefix.
{ "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, custom vocabulary values). 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_packorseal(HoleFill).history_logs[].status:active,maintenance,inactive,decommissionedorabandoned(allowed values).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). 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.
{ "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).
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).
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). To propose a value, open an issue; see Extending the format.