@welldot/core 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +179 -0
- package/README.md +179 -0
- package/dist/index.cjs +310 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +747 -0
- package/dist/index.d.ts +747 -0
- package/dist/index.js +269 -0
- package/dist/index.js.map +1 -0
- package/package.json +72 -0
- package/well-specifications.md +374 -0
|
@@ -0,0 +1,374 @@
|
|
|
1
|
+
# `.well` File Format Specification
|
|
2
|
+
|
|
3
|
+
**Version:** 1.0
|
|
4
|
+
**Extension:** `.well`
|
|
5
|
+
**Encoding:** UTF-8
|
|
6
|
+
**Base format:** JSON
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## Purpose
|
|
11
|
+
|
|
12
|
+
The `.well` format is an open standard for representing water well data. It is designed to serve three distinct but complementary use cases:
|
|
13
|
+
|
|
14
|
+
**Visualization.** The format contains sufficient constructive and geological detail to produce accurate technical well profile drawings — including borehole geometry, casing strings, screens, gravel packs, lithological columns, fractures, and caves — at true depth scale.
|
|
15
|
+
|
|
16
|
+
**Registration.** The format captures the administrative and physical identity of a well, providing a complete static record suitable for submission to regulatory bodies, inclusion in national well registries, and long-term archival.
|
|
17
|
+
|
|
18
|
+
**Research.** The structured geological and constructive data enables cross-well analysis, aquifer characterization, and hydrogeological research. Field vocabulary choices (FGDC texture codes, geologic units, aquifer units) are aligned with standards used in scientific literature. Dynamic hydrological measurements — static level, dynamic level, pump tests, water quality — are outside the scope of v1 and are reserved for a future `hydro` extension block.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## Design Principles
|
|
23
|
+
|
|
24
|
+
- **Self-describing** — full field names are used throughout; a `.well` file can be read and understood without consulting the spec
|
|
25
|
+
- **Versioned** — includes a `version` field for forward compatibility; parsers must reject unrecognized versions
|
|
26
|
+
- **Self-contained** — a single file encodes the complete static record of one well
|
|
27
|
+
- **SI units** — all depths are in meters, all diameters in millimeters; applications are responsible for unit conversion on display
|
|
28
|
+
- **Geographic north** — all azimuth values are referenced to geographic north
|
|
29
|
+
- **Ground level as zero** — all depth values are measured from ground level (0); elevation above sea level is stored separately in the `elevation` field
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## File Structure
|
|
34
|
+
|
|
35
|
+
A `.well` file is a JSON object with the following top-level structure:
|
|
36
|
+
|
|
37
|
+
```json
|
|
38
|
+
{
|
|
39
|
+
"version": 1,
|
|
40
|
+
|
|
41
|
+
"well_type": "tubular",
|
|
42
|
+
"name": "Poço PP-01",
|
|
43
|
+
"well_driller": "Perfuradora XYZ",
|
|
44
|
+
"construction_date": "2024-03-15",
|
|
45
|
+
"lat": -1.4558,
|
|
46
|
+
"lng": -48.5039,
|
|
47
|
+
"elevation": 12.5,
|
|
48
|
+
"obs": "Observações livres",
|
|
49
|
+
|
|
50
|
+
"bore_hole": [ ... ],
|
|
51
|
+
"well_case": [ ... ],
|
|
52
|
+
"reduction": [ ... ],
|
|
53
|
+
"well_screen": [ ... ],
|
|
54
|
+
"surface_case": [ ... ],
|
|
55
|
+
"hole_fill": [ ... ],
|
|
56
|
+
"cement_pad": { ... },
|
|
57
|
+
|
|
58
|
+
"lithology": [ ... ],
|
|
59
|
+
"fractures": [ ... ],
|
|
60
|
+
"caves": [ ... ]
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## Top-level Fields
|
|
67
|
+
|
|
68
|
+
| Field | Type | Required | Description |
|
|
69
|
+
|---------------------|---------|----------|--------------------------------------------------|
|
|
70
|
+
| `version` | integer | yes | Format version. Must be `1` for this spec. |
|
|
71
|
+
| `well_type` | string | yes | Classification of the well. See vocabulary below.|
|
|
72
|
+
| `name` | string | no | Well name or local identifier. |
|
|
73
|
+
| `well_driller` | string | no | Name of the drilling company or individual. |
|
|
74
|
+
| `construction_date` | string | no | ISO 8601 date of well completion (YYYY-MM-DD). |
|
|
75
|
+
| `lat` | number | no | Latitude in decimal degrees (WGS84). |
|
|
76
|
+
| `lng` | number | no | Longitude in decimal degrees (WGS84). |
|
|
77
|
+
| `elevation` | number | no | Ground elevation above sea level in meters. |
|
|
78
|
+
| `obs` | string | no | Free-text observations about the well. |
|
|
79
|
+
|
|
80
|
+
### `well_type` — Recommended values
|
|
81
|
+
|
|
82
|
+
| Value | Description |
|
|
83
|
+
|------------------------|------------------------------------------------|
|
|
84
|
+
| `tubular` | Conventional rotary or percussion drilled well |
|
|
85
|
+
| `artesian` | Free-flowing artesian well |
|
|
86
|
+
| `hand_dug` | Manually excavated well or cistern |
|
|
87
|
+
| `horizontal` | Horizontal or sub-horizontal well |
|
|
88
|
+
| `infiltration_gallery` | Horizontal subsurface infiltration gallery |
|
|
89
|
+
|
|
90
|
+
The `well_type` field accepts any string. The values above are the recommended vocabulary for interoperability. Tools should treat unrecognized values gracefully.
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## Object Schemas
|
|
95
|
+
|
|
96
|
+
### `BoreHole` — `bore_hole[]`
|
|
97
|
+
|
|
98
|
+
Represents a drilled interval of the borehole. Multiple entries describe a telescoping borehole with different diameters at different depth ranges.
|
|
99
|
+
|
|
100
|
+
| Field | Type | Required | Description |
|
|
101
|
+
|-------------------|--------|----------|------------------------------------|
|
|
102
|
+
| `from` | number | yes | Start depth in meters. |
|
|
103
|
+
| `to` | number | yes | End depth in meters. |
|
|
104
|
+
| `diameter` | number | yes | Borehole diameter in millimeters. |
|
|
105
|
+
| `drilling_method` | string | no | Method used (e.g. `rotary`, `percussion`, `cable_tool`). |
|
|
106
|
+
|
|
107
|
+
```json
|
|
108
|
+
{ "from": 0, "to": 80, "diameter": 250, "drilling_method": "rotary" }
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
### `WellCase` — `well_case[]`
|
|
114
|
+
|
|
115
|
+
Steel or plastic casing installed inside the borehole.
|
|
116
|
+
|
|
117
|
+
| Field | Type | Required | Description |
|
|
118
|
+
|------------|--------|----------|-------------------------------------|
|
|
119
|
+
| `from` | number | yes | Start depth in meters. |
|
|
120
|
+
| `to` | number | yes | End depth in meters. |
|
|
121
|
+
| `type` | string | yes | Casing material. Recommended: `steel`, `pvc`, `hdpe`, `fiberglass`. |
|
|
122
|
+
| `diameter` | number | yes | Casing outer diameter in millimeters.|
|
|
123
|
+
|
|
124
|
+
```json
|
|
125
|
+
{ "from": 0, "to": 60, "type": "steel", "diameter": 200 }
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
### `Reduction` — `reduction[]`
|
|
131
|
+
|
|
132
|
+
A transition piece connecting two casing or screen sections of different diameters.
|
|
133
|
+
|
|
134
|
+
| Field | Type | Required | Description |
|
|
135
|
+
|-------------|--------|----------|------------------------------------------|
|
|
136
|
+
| `from` | number | yes | Start depth in meters. |
|
|
137
|
+
| `to` | number | yes | End depth in meters. |
|
|
138
|
+
| `diam_from` | number | yes | Diameter at the top of the reducer in mm.|
|
|
139
|
+
| `diam_to` | number | yes | Diameter at the bottom of the reducer in mm.|
|
|
140
|
+
| `type` | string | yes | Reducer type (e.g. `conical`, `stepped`).|
|
|
141
|
+
|
|
142
|
+
```json
|
|
143
|
+
{ "from": 58, "to": 60, "diam_from": 200, "diam_to": 150, "type": "conical" }
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
### `WellScreen` — `well_screen[]`
|
|
149
|
+
|
|
150
|
+
Slotted or wire-wound screen section that allows water to enter the well.
|
|
151
|
+
|
|
152
|
+
| Field | Type | Required | Description |
|
|
153
|
+
|------------------|--------|----------|------------------------------------------|
|
|
154
|
+
| `from` | number | yes | Start depth in meters. |
|
|
155
|
+
| `to` | number | yes | End depth in meters. |
|
|
156
|
+
| `type` | string | yes | Screen type. Recommended: `wire_wound`, `bridge_slot`, `louvered`, `pvc_slotted`. |
|
|
157
|
+
| `diameter` | number | yes | Screen outer diameter in millimeters. |
|
|
158
|
+
| `screen_slot_mm` | number | yes | Slot opening size in millimeters. |
|
|
159
|
+
|
|
160
|
+
```json
|
|
161
|
+
{ "from": 60, "to": 80, "type": "wire_wound", "diameter": 150, "screen_slot_mm": 0.5 }
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
### `SurfaceCase` — `surface_case[]`
|
|
167
|
+
|
|
168
|
+
Outer protective casing installed near the surface, typically to prevent surface contamination.
|
|
169
|
+
|
|
170
|
+
| Field | Type | Required | Description |
|
|
171
|
+
|------------|--------|----------|-------------------------------------------|
|
|
172
|
+
| `from` | number | yes | Start depth in meters. |
|
|
173
|
+
| `to` | number | yes | End depth in meters. |
|
|
174
|
+
| `diameter` | number | yes | Casing outer diameter in millimeters. |
|
|
175
|
+
|
|
176
|
+
```json
|
|
177
|
+
{ "from": 0, "to": 3, "diameter": 300 }
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
### `HoleFill` — `hole_fill[]`
|
|
183
|
+
|
|
184
|
+
Material placed in the annular space between the casing and the borehole wall.
|
|
185
|
+
|
|
186
|
+
| Field | Type | Required | Description |
|
|
187
|
+
|---------------|--------|----------|--------------------------------------------------|
|
|
188
|
+
| `from` | number | yes | Start depth in meters. |
|
|
189
|
+
| `to` | number | yes | End depth in meters. |
|
|
190
|
+
| `type` | string | yes | Either `gravel_pack` or `seal`. |
|
|
191
|
+
| `diameter` | number | yes | Outer diameter of the filled annulus in mm. |
|
|
192
|
+
| `description` | string | yes | Material description (e.g. grain size, material).|
|
|
193
|
+
|
|
194
|
+
```json
|
|
195
|
+
{ "from": 60, "to": 80, "type": "gravel_pack", "diameter": 250, "description": "Seixo 2-4mm" }
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
---
|
|
199
|
+
|
|
200
|
+
### `CementPad` — `cement_pad`
|
|
201
|
+
|
|
202
|
+
The concrete pad installed at ground level (depth 0) around the wellhead. Dimensions are in meters.
|
|
203
|
+
|
|
204
|
+
| Field | Type | Required | Description |
|
|
205
|
+
|-------------|--------|----------|------------------------------------------|
|
|
206
|
+
| `type` | string | yes | Pad shape (e.g. `square`, `rectangular`, `circular`). |
|
|
207
|
+
| `width` | number | yes | Width in meters. |
|
|
208
|
+
| `thickness` | number | yes | Thickness in meters. |
|
|
209
|
+
| `length` | number | yes | Length in meters. |
|
|
210
|
+
|
|
211
|
+
```json
|
|
212
|
+
{ "type": "square", "width": 1.0, "thickness": 0.15, "length": 1.0 }
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
---
|
|
216
|
+
|
|
217
|
+
### `Lithology` — `lithology[]`
|
|
218
|
+
|
|
219
|
+
Geological description of a depth interval.
|
|
220
|
+
|
|
221
|
+
| Field | Type | Required | Description |
|
|
222
|
+
|-----------------|--------|----------|---------------------------------------------------|
|
|
223
|
+
| `from` | number | yes | Start depth in meters. |
|
|
224
|
+
| `to` | number | yes | End depth in meters. |
|
|
225
|
+
| `description` | string | yes | Free-text geological description. |
|
|
226
|
+
| `color` | string | yes | Representative color as a CSS hex value. |
|
|
227
|
+
| `fgdc_texture` | string | yes | Texture code per the FGDC Digital Cartographic Standard for Geologic Map Symbolization. |
|
|
228
|
+
| `geologic_unit` | string | yes | Name of the stratigraphic or geologic unit. |
|
|
229
|
+
| `aquifer_unit` | string | yes | Aquifer classification (e.g. `freático`, `confinado`, `fraturado`). |
|
|
230
|
+
|
|
231
|
+
```json
|
|
232
|
+
{
|
|
233
|
+
"from": 0,
|
|
234
|
+
"to": 20,
|
|
235
|
+
"description": "Areia fina amarelada",
|
|
236
|
+
"color": "#f5deb3",
|
|
237
|
+
"fgdc_texture": "sand",
|
|
238
|
+
"geologic_unit": "Quaternário",
|
|
239
|
+
"aquifer_unit": "freático"
|
|
240
|
+
}
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
---
|
|
244
|
+
|
|
245
|
+
### `Fracture` — `fractures[]`
|
|
246
|
+
|
|
247
|
+
A discrete fracture or fracture zone intersected by the borehole.
|
|
248
|
+
|
|
249
|
+
| Field | Type | Required | Description |
|
|
250
|
+
|----------------|---------|----------|---------------------------------------------------------------|
|
|
251
|
+
| `depth` | number | yes | Depth of the fracture in meters. |
|
|
252
|
+
| `water_intake` | boolean | yes | Whether the fracture produces water. |
|
|
253
|
+
| `description` | string | yes | Free-text description. |
|
|
254
|
+
| `swarm` | boolean | yes | Whether this fracture belongs to a swarm (closely spaced set).|
|
|
255
|
+
| `azimuth` | number | yes | Azimuth in degrees from geographic north (0–360). |
|
|
256
|
+
| `dip` | number | yes | Dip angle in degrees from horizontal (0–90). |
|
|
257
|
+
|
|
258
|
+
```json
|
|
259
|
+
{ "depth": 45.2, "water_intake": true, "description": "Fratura aberta", "swarm": false, "azimuth": 120, "dip": 35 }
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
---
|
|
263
|
+
|
|
264
|
+
### `Cave` — `caves[]`
|
|
265
|
+
|
|
266
|
+
A cavity or void zone intersected by the borehole.
|
|
267
|
+
|
|
268
|
+
| Field | Type | Required | Description |
|
|
269
|
+
|----------------|---------|----------|--------------------------------------|
|
|
270
|
+
| `from` | number | yes | Start depth in meters. |
|
|
271
|
+
| `to` | number | yes | End depth in meters. |
|
|
272
|
+
| `water_intake` | boolean | yes | Whether the cave produces water. |
|
|
273
|
+
| `description` | string | yes | Free-text description. |
|
|
274
|
+
|
|
275
|
+
```json
|
|
276
|
+
{ "from": 50, "to": 52, "water_intake": false, "description": "Caverna seca" }
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
---
|
|
280
|
+
|
|
281
|
+
## Complete Example
|
|
282
|
+
|
|
283
|
+
```json
|
|
284
|
+
{
|
|
285
|
+
"version": 1,
|
|
286
|
+
"well_type": "tubular",
|
|
287
|
+
"name": "Poço PP-01",
|
|
288
|
+
"well_driller": "Perfuradora XYZ",
|
|
289
|
+
"construction_date": "2024-03-15",
|
|
290
|
+
"lat": -1.4558,
|
|
291
|
+
"lng": -48.5039,
|
|
292
|
+
"elevation": 12.5,
|
|
293
|
+
"obs": "Sem anomalias observadas durante a perfuração.",
|
|
294
|
+
|
|
295
|
+
"bore_hole": [
|
|
296
|
+
{ "from": 0, "to": 80, "diameter": 250, "drilling_method": "rotary" }
|
|
297
|
+
],
|
|
298
|
+
|
|
299
|
+
"well_case": [
|
|
300
|
+
{ "from": 0, "to": 60, "type": "steel", "diameter": 200 }
|
|
301
|
+
],
|
|
302
|
+
|
|
303
|
+
"reduction": [
|
|
304
|
+
{ "from": 58, "to": 60, "diam_from": 200, "diam_to": 150, "type": "conical" }
|
|
305
|
+
],
|
|
306
|
+
|
|
307
|
+
"well_screen": [
|
|
308
|
+
{ "from": 60, "to": 80, "type": "wire_wound", "diameter": 150, "screen_slot_mm": 0.5 }
|
|
309
|
+
],
|
|
310
|
+
|
|
311
|
+
"surface_case": [
|
|
312
|
+
{ "from": 0, "to": 3, "diameter": 300 }
|
|
313
|
+
],
|
|
314
|
+
|
|
315
|
+
"hole_fill": [
|
|
316
|
+
{ "from": 60, "to": 80, "type": "gravel_pack", "diameter": 250, "description": "Seixo 2-4mm" },
|
|
317
|
+
{ "from": 3, "to": 60, "type": "seal", "diameter": 250, "description": "Cimento" }
|
|
318
|
+
],
|
|
319
|
+
|
|
320
|
+
"cement_pad": { "type": "square", "width": 1.0, "thickness": 0.15, "length": 1.0 },
|
|
321
|
+
|
|
322
|
+
"lithology": [
|
|
323
|
+
{
|
|
324
|
+
"from": 0, "to": 20,
|
|
325
|
+
"description": "Areia fina amarelada",
|
|
326
|
+
"color": "#f5deb3",
|
|
327
|
+
"fgdc_texture": "sand",
|
|
328
|
+
"geologic_unit": "Quaternário",
|
|
329
|
+
"aquifer_unit": "freático"
|
|
330
|
+
},
|
|
331
|
+
{
|
|
332
|
+
"from": 20, "to": 80,
|
|
333
|
+
"description": "Granito fraturado cinza",
|
|
334
|
+
"color": "#a9a9a9",
|
|
335
|
+
"fgdc_texture": "granite",
|
|
336
|
+
"geologic_unit": "Embasamento Cristalino",
|
|
337
|
+
"aquifer_unit": "fraturado"
|
|
338
|
+
}
|
|
339
|
+
],
|
|
340
|
+
|
|
341
|
+
"fractures": [
|
|
342
|
+
{ "depth": 45.2, "water_intake": true, "description": "Fratura aberta", "swarm": false, "azimuth": 120, "dip": 35 },
|
|
343
|
+
{ "depth": 62.0, "water_intake": false, "description": "Fratura de cisalhamento", "swarm": true, "azimuth": 90, "dip": 70 }
|
|
344
|
+
],
|
|
345
|
+
|
|
346
|
+
"caves": [
|
|
347
|
+
{ "from": 50, "to": 52, "water_intake": false, "description": "Caverna seca" }
|
|
348
|
+
]
|
|
349
|
+
}
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
---
|
|
353
|
+
|
|
354
|
+
## Versioning
|
|
355
|
+
|
|
356
|
+
The `version` field must always be present and is an integer starting at `1`. Parsers must reject files with an unrecognized `version` value and should warn when `version` is absent.
|
|
357
|
+
|
|
358
|
+
| Version | Description |
|
|
359
|
+
|---------|-------------------------------|
|
|
360
|
+
| `1` | Initial release of the format |
|
|
361
|
+
|
|
362
|
+
A `hydro` block for dynamic hydrological data (static level, dynamic level, pump tests, water quality) is reserved for v2 and must not appear in v1 files.
|
|
363
|
+
|
|
364
|
+
---
|
|
365
|
+
|
|
366
|
+
## MIME Type
|
|
367
|
+
|
|
368
|
+
```
|
|
369
|
+
application/vnd.well+json
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
---
|
|
373
|
+
|
|
374
|
+
*Specification v1.0 — `.well` format*
|