@welldot/core 0.1.1 → 0.2.2

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.
Files changed (18) hide show
  1. package/README.md +142 -48
  2. package/dist/index.cjs +878 -30
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +4948 -107
  5. package/dist/index.d.ts +4948 -107
  6. package/dist/index.js +836 -29
  7. package/dist/index.js.map +1 -1
  8. package/docs/profiles/.gitkeep +0 -0
  9. package/docs/reference/fgdc-textures.md +380 -0
  10. package/docs/schema/v1/.gitkeep +0 -0
  11. package/docs/schema/v2/profiles/.gitkeep +0 -0
  12. package/docs/schema/v2/well.schema.json +949 -0
  13. package/{well-specifications.md → docs/spec/v1/well-format.md} +160 -95
  14. package/docs/spec/v2/format-reference.md +534 -0
  15. package/docs/spec/v2/interoperability.md +177 -0
  16. package/docs/spec/v2/object-schemas.md +657 -0
  17. package/docs/spec/v2/overview.md +85 -0
  18. package/package.json +7 -3
package/docs/spec/v2/object-schemas.md ADDED
@@ -0,0 +1,657 @@
1
+ # `.well` File Format Specification — Version 2.0: Object Schemas
2
+
3
+ **See also:** [overview.md](./overview.md) · [format-reference.md](./format-reference.md) · [interoperability.md](./interoperability.md)
4
+
5
+ ---
6
+
7
+ ## Object Schemas
8
+
9
+ ### `BoreHole` — `bore_hole[]`
10
+
11
+ A drilled interval of the borehole. Multiple entries describe a telescoping borehole.
12
+
13
+ | Field | Type | Required | Description |
14
+ | ----------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
15
+ | `from` | number | yes | Start depth in meters. |
16
+ | `to` | number | yes | End depth in meters. |
17
+ | `diameter` | number | yes | Borehole diameter in millimeters. |
18
+ | `drilling_method` | string | no | Free text description of the method used (e.g. `rotary`, `percussion`, `cable_tool`, `auger`, `air_hammer`). These example values are common terms, not an enforced enumeration — any free text is valid. |
19
+
20
+ ```json
21
+ { "from": 0, "to": 80, "diameter": 250, "drilling_method": "rotary" }
22
+ ```
23
+
24
+ ---
25
+
26
+ ### `WellCase` — `well_case[]`
27
+
28
+ Steel or plastic casing installed inside the borehole.
29
+
30
+ | Field | Type | Required | Description |
31
+ | ---------- | ------ | -------- | ------------------------------------- |
32
+ | `from` | number | yes | Start depth in meters. |
33
+ | `to` | number | yes | End depth in meters. |
34
+ | `type` | string | yes | Casing material. Free Text |
35
+ | `diameter` | number | yes | Casing outer diameter in millimeters. |
36
+
37
+ ---
38
+
39
+ ### `Reduction` — `reduction[]`
40
+
41
+ A transition piece connecting two casing or screen sections of different diameters.
42
+
43
+ | Field | Type | Required | Description |
44
+ | ----------- | ------ | -------- | ------------------------------------------------ |
45
+ | `from` | number | yes | Start depth in meters. |
46
+ | `to` | number | yes | End depth in meters. |
47
+ | `diam_from` | number | yes | Diameter at top in millimeters. |
48
+ | `diam_to` | number | yes | Diameter at bottom in millimeters. |
49
+ | `type` | string | yes | Reducer type material and description. Free Text |
50
+
51
+ ---
52
+
53
+ ### `WellScreen` — `well_screen[]`
54
+
55
+ Slotted or wire-wound screen section.
56
+
57
+ | Field | Type | Required | Description |
58
+ | ------------- | ------ | -------- | ------------------------------------------- |
59
+ | `from` | number | yes | Start depth in meters. |
60
+ | `to` | number | yes | End depth in meters. |
61
+ | `type` | string | yes | Screen type/material description. Free text |
62
+ | `diameter` | number | yes | Screen outer diameter in millimeters. |
63
+ | `screen_slot` | number | yes | Slot opening size in millimeters. |
64
+
65
+ > **v1 migration:** v1's `screen_slot_mm` field is renamed to `screen_slot` in v2. The value is in millimeters before and after — no conversion needed. See § Units for the rule that screen slot is always in millimeters regardless of any application's display preference.
66
+
67
+ ---
68
+
69
+ ### `SurfaceCase` — `surface_case[]`
70
+
71
+ Outer protective casing installed near the surface.
72
+
73
+ | Field | Type | Required | Description |
74
+ | ---------- | ------ | -------- | ------------------------------------- |
75
+ | `from` | number | yes | Start depth in meters. |
76
+ | `to` | number | yes | End depth in meters. |
77
+ | `diameter` | number | yes | Casing outer diameter in millimeters. |
78
+
79
+ ---
80
+
81
+ ### `HoleFill` — `hole_fill[]`
82
+
83
+ Material placed in the annular space between casing and borehole wall.
84
+
85
+ | Field | Type | Required | Description |
86
+ | ------------- | ------ | -------- | ---------------------------------------------------- |
87
+ | `from` | number | yes | Start depth in meters. |
88
+ | `to` | number | yes | End depth in meters. |
89
+ | `type` | string | yes | Either `gravel_pack` or `seal`. |
90
+ | `diameter` | number | yes | Outer diameter of the filled annulus in millimeters. |
91
+ | `description` | string | yes | Material description (e.g. grain size, material). |
92
+
93
+ ---
94
+
95
+ ### `CementPad` — `cement_pad`
96
+
97
+ Concrete wellhead pad. **All dimensions are in meters**.
98
+
99
+ | Field | Type | Required | Description |
100
+ | ----------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
101
+ | `type` | string | yes | Free text description of the pad, typically its material (e.g. `concrete`) but may also describe its shape (e.g. `circular`) or both. Not an enforced enumeration. |
102
+ | `width` | number | yes | Width in meters. |
103
+ | `thickness` | number | yes | Thickness in meters. |
104
+ | `length` | number | yes | Length in meters. |
105
+
106
+ > Note: A typical residential cement pad has dimensions on the order of `1.0` meter. Applications presenting these values in non-metric units (e.g. feet for US users) must convert `cement_pad` dimensions along with all other length fields.
107
+
108
+ ---
109
+
110
+ ### `Lithology` — `lithology[]`
111
+
112
+ Geological description of a depth interval.
113
+
114
+ | Field | Type | Required | Description |
115
+ | --------------- | --------- | -------- | -------------------------------------------------------------------- |
116
+ | `from` | number | yes | Start depth in meters. |
117
+ | `to` | number | yes | End depth in meters. |
118
+ | `description` | string | yes | Free-text geological description. |
119
+ | `color` | string | yes | Representative color as a CSS hex value. |
120
+ | `texture` | `Texture` | yes | Lithology pattern reference. See below. |
121
+ | `geologic_unit` | string | yes | Stratigraphic or geologic unit name. |
122
+ | `aquifer_unit` | string | yes | Aquifer unit name like "Aquifero Pirabas" or "Massachusetts Aquifer" |
123
+
124
+ ### `Texture`
125
+
126
+ | Field | Type | Required | Description |
127
+ | ------------ | ---------------- | -------- | ------------------------------------------------------------------------------------------------------ |
128
+ | `code` | string \| number | yes | The texture code within the declared vocabulary. |
129
+ | `vocabulary` | string | no | Either a short canonical token or an HTTPS URI identifying the vocabulary. Default: `fgdc`. See below. |
130
+
131
+ #### `vocabulary` values
132
+
133
+ The `vocabulary` field accepts two forms:
134
+
135
+ **Short canonical tokens** — well-known vocabularies maintained by the welldot project or by widely-adopted standards bodies. The v2.0 canonical set is:
136
+
137
+ | Token | Vocabulary |
138
+ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
139
+ | `fgdc` | FGDC Digital Cartographic Standard for Geologic Map Symbolization (FGDC-STD-013-2006), Chapter 25 — Lithology. Codes are integers. |
140
+ | `cgi` | Commission for the Management and Application of Geoscience Information (CGI) Simple Lithology vocabulary. Codes are URIs or short tokens per CGI. |
141
+ | `custom` | Application-defined vocabulary with no interoperability guarantee. Codes are opaque strings. Use of `custom` is discouraged when a documented alternative exists; prefer publishing a vocabulary URI. |
142
+
143
+ **HTTPS URIs** — when a regulator, geological survey, or institution maintains its own lithology vocabulary, the URI of its definition document is a valid `vocabulary` value. The URI SHOULD resolve to a machine-readable vocabulary description (SKOS, JSON-LD, or a documented JSON list of `{code, label}` entries), though parsers do not fetch it.
144
+
145
+ ```json
146
+ { "vocabulary": "fgdc", "code": 607 }
147
+ { "vocabulary": "cgi", "code": "sandstone" }
148
+ { "vocabulary": "https://brgm.fr/vocab/lithology/v1", "code": "GRES" }
149
+ { "vocabulary": "https://welldot.org/vocab/lithology-extended/v1", "code": "LATERITA" }
150
+ ```
151
+
152
+ Profiles SHOULD constrain the `vocabulary` field to a specific URI or short token relevant to their regulatory context.
153
+
154
+ > **v1 migration:** A v1 file's bare `fgdc_texture: "<code>"` field is treated as `texture: { code: "<code>", vocabulary: "fgdc" }`.
155
+
156
+ ```json
157
+ {
158
+ "from": 0,
159
+ "to": 20,
160
+ "description": "Areia fina amarelada",
161
+ "color": "#f5deb3",
162
+ "texture": { "code": 607, "vocabulary": "fgdc" },
163
+ "geologic_unit": "Quaternário",
164
+ "aquifer_unit": "freático"
165
+ }
166
+ ```
167
+
168
+ ---
169
+
170
+ ### `Fracture` — `fractures[]`
171
+
172
+ A discrete fracture or fracture zone.
173
+
174
+ | Field | Type | Required | Description |
175
+ | ----------------- | ------- | -------- | -------------------------------------------------------------------- |
176
+ | `depth` | number | yes | Depth of fracture in meters. |
177
+ | `water_intake` | boolean | yes | Whether the fracture produces water. |
178
+ | `description` | string | yes | Free-text description. |
179
+ | `swarm` | boolean | yes | Whether this fracture belongs to a swarm. |
180
+ | `azimuth` | number | yes | Azimuth in degrees from geographic north (0–360). |
181
+ | `dip` | number | yes | Dip angle in degrees from horizontal (0–90). |
182
+ | `depth_precision` | number | no | One-sigma precision of `depth` in meters. Default handled by editors |
183
+
184
+ ---
185
+
186
+ ### `Cave` — `caves[]`
187
+
188
+ A cavity or void zone.
189
+
190
+ | Field | Type | Required | Description |
191
+ | -------------- | ------- | -------- | -------------------------------- |
192
+ | `from` | number | yes | Start depth in meters. |
193
+ | `to` | number | yes | End depth in meters. |
194
+ | `water_intake` | boolean | yes | Whether the cave produces water. |
195
+ | `description` | string | yes | Free-text description. |
196
+
197
+ ---
198
+
199
+ ## `hydrodynamic_events[]`
200
+
201
+ A chronological, append-only ledger of all hydrodynamic observations. Events are ordered by `datetime` ascending (UTC-normalized instants); parsers MUST NOT assume order and SHOULD sort by `datetime` when querying. When two events share the same instant, an optional `sequence` integer breaks the tie.
202
+
203
+ > **Note — interpretive contracts, not pumping methods.** Each `type` value identifies a _category of field record_ with a distinct semantic contract, not a pumping technique or equipment class. Equipment belongs in the `equipment` field; test-analysis method belongs in `method` on `aquifer_analysis`. The contract for each type specifies what data it reliably supplies, how many steps it may carry, whether recovery is permitted, and whether its event ID is valid input to `source_event_ids` on an `aquifer_analysis` entry.
204
+
205
+ ### Event types
206
+
207
+ | `type` | Português (BR) | What it records | `steps` constraint | `recovery` | Valid in `source_event_ids` |
208
+ | ------------------ | ------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------ | ---------- | -------------------------------- |
209
+ | `spot_measurement` | Medição pontual | Static water level during a routine visit; optionally an informal brief pump observation. Not a controlled test. | 0 or 1 | Optional | As `static_level_source_id` only |
210
+ | `constant_rate` | Teste de vazão constante | Controlled pump test at exactly one fixed rate. | Exactly 1 | Optional | Yes |
211
+ | `step_drawdown` | Teste de vazão escalonada | Controlled pump test at two or more successive rates in ascending order. | ≥ 2, ascending | Optional | Yes |
212
+ | `airlift` | Air-lift | Historical fact that air-lift development was performed and produced an estimated yield. | ≥ 1 | Optional | No — see § airlift |
213
+ | `recovery_only` | Apenas recuperação | Recovery after a pumping event whose drawdown data was not recorded. | None | Required | Yes |
214
+
215
+ The `type` field accepts any string. Non-canonical values SHOULD use the `x-` prefix.
216
+
217
+ ### Common fields (all event types)
218
+
219
+ Only `id`, `type`, and `datetime` are required. All others are optional for all types.
220
+
221
+ | Field | Type | Required | Description |
222
+ | ----------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------- |
223
+ | `id` | string | yes | Unique within `hydrodynamic_events`. UUID v4 recommended. |
224
+ | `type` | string | yes | Event type. |
225
+ | `datetime` | string | yes | RFC 3339 datetime with mandatory UTC offset (e.g. `"2006-03-14T08:00:00-03:00"`). See § Datetime Conventions. |
226
+ | `sequence` | integer | no | Tiebreaker for events sharing the same instant. Lower values sort first. |
227
+ | `operator` | string | no | Person or company conducting the measurement or test. |
228
+ | `equipment` | string | no | Equipment description. |
229
+ | `notes` | string | no | Free-text observations. |
230
+
231
+ ---
232
+
233
+ ### `spot_measurement`
234
+
235
+ | Field | Type | Required | Description |
236
+ | ------------------------ | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
237
+ | `static_level` | number | yes | Depth to water surface from ground level, in meters. |
238
+ | `static_level_precision` | number | no | One-sigma precision of `static_level`. |
239
+ | `measurement_method` | string | no | Recommended: `electric_probe`, `pressure_transducer`, `air_line`, `tape`. |
240
+ | `steps` | `PumpingStep[]` | no | At most one step. For an informal brief pump observation during the visit — not a controlled test. Use `constant_rate` for a formal test. |
241
+ | `recovery` | `RecoveryPhase` | no | Recovery after the optional pumping step. |
242
+
243
+ ---
244
+
245
+ ### `constant_rate`
246
+
247
+ | Field | Type | Required | Description |
248
+ | ------------------------ | --------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
249
+ | `static_level` | number | no | Pre-test static level in meters. Omit if not measured. |
250
+ | `static_level_precision` | number | no | One-sigma precision of `static_level`. |
251
+ | `steps` | `PumpingStep[]` | no | Exactly one entry. A second step would make this a `step_drawdown`. Omit if only recovery data is available. |
252
+ | `recovery` | `RecoveryPhase` | no | Recovery measurements after pump shutdown. |
253
+
254
+ ---
255
+
256
+ ### `step_drawdown`
257
+
258
+ Jacob's `B` and `C` are derived — store them in `aquifer_analysis`, never here.
259
+
260
+ | Field | Type | Required | Description |
261
+ | ------------------------ | --------------- | -------- | -------------------------------------------------- |
262
+ | `static_level` | number | no | Pre-test static level in meters. |
263
+ | `static_level_precision` | number | no | One-sigma precision of `static_level`. |
264
+ | `steps` | `PumpingStep[]` | yes | Two or more steps in ascending order of flow rate. |
265
+ | `recovery` | `RecoveryPhase` | no | Recovery after the final step. |
266
+
267
+ ---
268
+
269
+ ### `airlift`
270
+
271
+ This type exists to record the historical fact that air-lift development was performed and produced an estimated yield. It is **not** suitable input for `aquifer_analysis`: tools producing `aquifer_analysis` entries MUST refuse to accept `airlift` event IDs in `source_event_ids` and MUST emit a warning if one is supplied.
272
+
273
+ Static level is not reliably measurable during air-lift and SHOULD be omitted.
274
+
275
+ | Field | Type | Required | Description |
276
+ | ---------- | --------------- | -------- | -------------------------------------------------------------- |
277
+ | `steps` | `PumpingStep[]` | yes | One or more steps. Each step may carry time-series `readings`. |
278
+ | `recovery` | `RecoveryPhase` | no | Recovery measurements after air-lift shutdown, if recorded. |
279
+
280
+ ---
281
+
282
+ ### `recovery_only`
283
+
284
+ | Field | Type | Required | Description |
285
+ | ------------------ | --------------- | -------- | ------------------------------------------------ |
286
+ | `pumping_rate` | number | no | Estimated preceding flow rate in m³/h. |
287
+ | `pumping_duration` | number | no | Estimated preceding pumping duration in minutes. |
288
+ | `recovery` | `RecoveryPhase` | yes | Recovery time-series. |
289
+
290
+ ---
291
+
292
+ ## Supporting Object Schemas
293
+
294
+ ### `PumpingStep`
295
+
296
+ | Field | Type | Required | Description |
297
+ | ---------------- | ---------------- | -------- | ----------------------------------------------------------------- |
298
+ | `rate` | number | yes | Pumping rate in m³/h. |
299
+ | `rate_precision` | number | no | One-sigma precision of `rate`. |
300
+ | `duration` | number | no | Duration in minutes. |
301
+ | `readings` | `LevelReading[]` | no | Time-series during this step. A single terminal reading is valid. |
302
+
303
+ ### `LevelReading`
304
+
305
+ | Field | Type | Required | Description |
306
+ | ----------------- | ------ | -------- | ----------------------------------------------------------------- |
307
+ | `elapsed` | number | yes | Time since step start (or pump shutdown for recovery) in minutes. |
308
+ | `depth` | number | yes | Depth to water surface from ground level in meters. |
309
+ | `depth_precision` | number | no | One-sigma precision of `depth`. |
310
+ | `pressure` | number | no | Pressure transducer reading in kPa. |
311
+
312
+ ### `RecoveryPhase`
313
+
314
+ | Field | Type | Required | Description |
315
+ | ---------- | ---------------- | -------- | ------------------------------------------------------------------ |
316
+ | `readings` | `LevelReading[]` | yes | Time-series after pump shutdown. `elapsed` measured from shutdown. |
317
+
318
+ ---
319
+
320
+ ## `aquifer_analysis[]`
321
+
322
+ An array of interpreted aquifer parameter sets. Multiple entries may coexist, representing different methods or analysts.
323
+
324
+ | Field | Type | Required | Description |
325
+ | ------------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
326
+ | `id` | string | yes | Unique within `aquifer_analysis`. |
327
+ | `datetime` | string | yes | RFC 3339 datetime with mandatory UTC offset. |
328
+ | `analyst` | string | no | Name of the hydrogeologist. |
329
+ | `source_event_ids` | string[] | yes | IDs of source `hydrodynamic_events` from this same file. See § Cross-reference and Uniqueness Rules. |
330
+ | `method` | string | no | See vocabulary below. |
331
+ | `static_level` | number | no | Static level used as reference, in meters. |
332
+ | `static_level_precision` | number | no | One-sigma precision of `static_level`. |
333
+ | `static_level_source_id` | string | no | ID of the event from which `static_level` was taken. |
334
+ | `dynamic_level` | number | no | Stabilized dynamic level in meters. |
335
+ | `dynamic_level_precision` | number | no | One-sigma precision of `dynamic_level`. |
336
+ | `flow_rate` | number | no | Flow rate associated with `dynamic_level`, in m³/h. |
337
+ | `flow_rate_precision` | number | no | One-sigma precision of `flow_rate`. |
338
+ | `max_flow_rate` | number | no | Maximum recommended sustained extraction rate in m³/h, as judged by the analyst from the source events. This is an interpretive recommendation, not the test rate. Distinct from `flow_rate`, which is the rate actually applied during the test that produced `dynamic_level`. |
339
+ | `max_flow_rate_precision` | number | no | One-sigma precision of `max_flow_rate` in m³/h. |
340
+ | `max_flow_rate_basis` | string | no | Free-text justification: safety factor applied, regulatory framework referenced (e.g. `"80% of test rate per ANA practice"`, `"limited by available drawdown to top of screen"`), or assumptions about long-term recharge. |
341
+ | `specific_capacity` | number | no | `Q/s` in m³/h per m (i.e. m²/h). |
342
+ | `transmissivity` | number | no | Aquifer transmissivity `T` in m²/s. |
343
+ | `storativity` | number | no | Dimensionless storativity `S`. |
344
+ | `hydraulic_conductivity` | number | no | Hydraulic conductivity `K` in m/s. Requires `aquifer_thickness`. |
345
+ | `aquifer_thickness` | number | no | Saturated aquifer thickness in meters. |
346
+ | `jacob_b` | number | no | Formation loss coefficient from Jacob's equation. |
347
+ | `jacob_c` | number | no | Well loss coefficient from Jacob's equation. |
348
+ | `well_efficiency_pct` | number | no | Well efficiency as a percentage. |
349
+ | `notes` | string | no | Methodology notes, assumptions, data quality remarks. |
350
+
351
+ ### `method` — Recommended values
352
+
353
+ `cooper_jacob`, `theis`, `neuman`, `hantush`, `birsoy_summers`, `eden_hazel`, `visual_inspection`. Non-canonical values SHOULD use the `x-` prefix.
354
+
355
+ ---
356
+
357
+ ## Derived Parameters — Computation Reference
358
+
359
+ The following values are **never stored**. Applications compute them on demand.
360
+
361
+ | Parameter | Formula | Inputs |
362
+ | ---------------------------- | -------------------------------------------- | ---------------------------------------------- |
363
+ | Drawdown `s` at time `t` | `depth(t) − static_level` | `LevelReading.depth`, event `static_level` |
364
+ | Residual drawdown (recovery) | `depth(t) − static_level` | `RecoveryPhase.readings`, event `static_level` |
365
+ | Specific capacity `Q/s` | `flow_rate / (dynamic_level − static_level)` | `AquiferAnalysis` fields |
366
+ | Unit drawdown `s/Q` | `(dynamic_level − static_level) / flow_rate` | `AquiferAnalysis` fields |
367
+ | Formation loss | `jacob_b × Q` | `AquiferAnalysis.jacob_b`, `flow_rate` |
368
+ | Well loss | `jacob_c × Q²` | `AquiferAnalysis.jacob_c`, `flow_rate` |
369
+ | Hydraulic conductivity `K` | `transmissivity / aquifer_thickness` | `AquiferAnalysis` fields |
370
+
371
+ ---
372
+
373
+ ## Querying Current State
374
+
375
+ **Current static level (NE):** Filter all events where `static_level` is present, sort by `datetime` descending (UTC-normalized), take the first result.
376
+
377
+ **Current specific capacity:** Find the most recent `aquifer_analysis` with `specific_capacity` present.
378
+
379
+ **Current transmissivity:** Find the most recent `aquifer_analysis` with `transmissivity` present.
380
+
381
+ ---
382
+
383
+ ## `history_logs[]`
384
+
385
+ A mutable chronological record of physical interventions, inspections, and incidents. Entries may be edited or removed to correct field errors.
386
+
387
+ Each entry carries two distinct timestamps:
388
+
389
+ - **`datetime`** — when the logged event actually occurred in the field.
390
+ - **`updated_at`** — when this log entry was most recently created or edited in the record system. This timestamp tracks the data lineage of the entry itself, not the event it describes.
391
+
392
+ These timestamps may differ substantially: a maintenance intervention `datetime` of 2018-06-12 may be paired with an `updated_at` of 2024-03-15 if the entry was added retroactively or corrected.
393
+
394
+ ### Categories
395
+
396
+ | `category` | Portuguese (BR) | Description |
397
+ | ------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
398
+ | `maintenance` | Manutenção | Physical intervention: pump replacement, casing repair, cleaning, redevelopment. |
399
+ | `inspection` | Inspeção | Site visit without physical alteration: visual survey, camera inspection, sample collection. |
400
+ | `incident` | Incidente | Unplanned event: partial collapse, contamination, prolonged drought, vandalism. |
401
+ | `event` | Evento | Generic milestone: construction completion, commissioning, deactivation, reactivation, ownership transfer, rehabilitation, data-integrity repair. |
402
+
403
+ Vocabulary is open. Non-canonical values SHOULD use the `x-` prefix.
404
+
405
+ ### `HistoryLogEntry`
406
+
407
+ | Field | Type | Required | Description |
408
+ | ------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
409
+ | `id` | string | yes | Unique within `history_logs`. |
410
+ | `datetime` | string | yes | RFC 3339 datetime with mandatory UTC offset. When the logged event occurred. |
411
+ | `updated_at` | string | no | RFC 3339 datetime with mandatory UTC offset. When this entry was most recently created or edited. When omitted, treated as equal to `datetime`. Producers SHOULD set this field whenever they create or modify an entry. |
412
+ | `category` | string | yes | Event category. |
413
+ | `description` | string | yes | Free-text account: work performed, findings, or incident narrative. |
414
+ | `author` | string | no | Person or company responsible for the record. |
415
+ | `severity` | string | no | Recommended: `low`, `medium`, `high`, `critical`. |
416
+ | `attachments` | `Attachment[]` | no | Supporting documents or photos. |
417
+
418
+ ### `updated_at` semantics
419
+
420
+ - `updated_at` MUST NOT be earlier than `datetime` only in the case of pre-dated logging — typically retroactive entry of historical events. There is no validation rule prohibiting `updated_at < datetime`; both orderings are legal.
421
+ - When a producer modifies the `description`, `category`, `severity`, `author`, or `attachments` of an existing entry, it SHOULD update `updated_at` to the current instant.
422
+ - When a producer modifies only the `id` (e.g. during duplicate-resolution), it SHOULD NOT update `updated_at`, since the substantive content of the entry has not changed.
423
+ - The `updated_at` field is not retroactive: parsers reading a v1 or early-v2.0 file without `updated_at` MUST NOT synthesize one.
424
+
425
+ ### `Attachment`
426
+
427
+ The `.well` format is not a file container. Attachments are referenced by URL.
428
+
429
+ | Field | Type | Required | Description |
430
+ | ------------- | ------ | -------- | ------------------------------------------------------------------------------------ |
431
+ | `id` | string | yes | Unique within the parent log entry's `attachments` array. |
432
+ | `uri` | string | yes | Full HTTPS URL. Relative paths are not permitted. |
433
+ | `media_type` | string | yes | MIME type (e.g. `image/jpeg`, `application/pdf`). |
434
+ | `filename` | string | no | Original filename for display. |
435
+ | `description` | string | no | Caption or content description. |
436
+ | `sha256` | string | no | SHA-256 hash of the file in lowercase hex. Consumers SHOULD validate after download. |
437
+
438
+ ### URL resolvability
439
+
440
+ The `uri` field is a reference, not a guarantee. URLs may become unreachable over time; consumers MUST handle fetch failures gracefully and MUST NOT treat them as file-format errors. When `sha256` is present, consumers that successfully fetch the attachment MUST validate the hash and MUST reject content that fails validation. Producers SHOULD include `sha256` for any attachment intended for long-term preservation.
441
+
442
+ ---
443
+
444
+ ## Complete Example
445
+
446
+ ```json
447
+ {
448
+ "$schema": "https://welldot.org/schema/v2/well.schema.json",
449
+ "@context": "https://welldot.org/context/v2.jsonld",
450
+ "version": 2,
451
+ "well_type": "tubular",
452
+ "name": "Poço PP-01",
453
+ "well_driller": "Perfuradora XYZ",
454
+ "construction_date": "2006-03-10",
455
+ "obs": "Sem anomalias observadas durante a perfuração.",
456
+
457
+ "well_id": [
458
+ { "authority": "SIAGAS", "id": "SP-0042819", "primary": true },
459
+ { "authority": "ANA", "id": "02000.001234/2006-78" }
460
+ ],
461
+
462
+ "location": {
463
+ "lat": -1.4558,
464
+ "lng": -48.5039,
465
+ "elevation": 12.5,
466
+ "properties": {
467
+ "elevation_datum": "wgs84_ellipsoid",
468
+ "crs": "EPSG:4326",
469
+ "elevation_precision": 0.5
470
+ }
471
+ },
472
+
473
+ "profiles": ["https://welldot.org/profiles/brazil-ana/v1/schema.json"],
474
+
475
+ "bore_hole": [
476
+ { "from": 0, "to": 80, "diameter": 250, "drilling_method": "rotary" }
477
+ ],
478
+ "well_case": [{ "from": 0, "to": 60, "type": "steel", "diameter": 200 }],
479
+ "reduction": [],
480
+ "well_screen": [
481
+ {
482
+ "from": 60,
483
+ "to": 80,
484
+ "type": "wire_wound",
485
+ "diameter": 150,
486
+ "screen_slot": 0.5
487
+ }
488
+ ],
489
+ "surface_case": [{ "from": 0, "to": 3, "diameter": 300 }],
490
+ "hole_fill": [
491
+ {
492
+ "from": 60,
493
+ "to": 80,
494
+ "type": "gravel_pack",
495
+ "diameter": 250,
496
+ "description": "Seixo 2-4mm"
497
+ },
498
+ {
499
+ "from": 3,
500
+ "to": 60,
501
+ "type": "seal",
502
+ "diameter": 250,
503
+ "description": "Cimento"
504
+ }
505
+ ],
506
+ "cement_pad": {
507
+ "type": "square",
508
+ "width": 1.0,
509
+ "thickness": 0.15,
510
+ "length": 1.0
511
+ },
512
+
513
+ "lithology": [
514
+ {
515
+ "from": 0,
516
+ "to": 20,
517
+ "description": "Areia fina amarelada",
518
+ "color": "#f5deb3",
519
+ "texture": { "code": 607, "vocabulary": "fgdc" },
520
+ "geologic_unit": "Quaternário",
521
+ "aquifer_unit": "freático"
522
+ },
523
+ {
524
+ "from": 20,
525
+ "to": 80,
526
+ "description": "Granito fraturado cinza",
527
+ "color": "#a9a9a9",
528
+ "texture": { "code": 718, "vocabulary": "fgdc" },
529
+ "geologic_unit": "Embasamento Cristalino",
530
+ "aquifer_unit": "fraturado"
531
+ }
532
+ ],
533
+
534
+ "fractures": [
535
+ {
536
+ "depth": 45.2,
537
+ "depth_precision": 0.1,
538
+ "water_intake": true,
539
+ "description": "Fratura aberta",
540
+ "swarm": false,
541
+ "azimuth": 120,
542
+ "dip": 35
543
+ }
544
+ ],
545
+
546
+ "caves": [],
547
+
548
+ "hydrodynamic_events": [
549
+ {
550
+ "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
551
+ "type": "airlift",
552
+ "datetime": "2006-03-10T14:00:00-03:00",
553
+ "operator": "Perfuradora XYZ",
554
+ "steps": [
555
+ {
556
+ "rate": 340.0,
557
+ "duration": 30,
558
+ "readings": [
559
+ { "elapsed": 30, "depth": 44.8, "depth_precision": 0.05 }
560
+ ]
561
+ }
562
+ ],
563
+ "notes": "Air-lift at end of drilling. Static level not reliable."
564
+ },
565
+ {
566
+ "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
567
+ "type": "constant_rate",
568
+ "datetime": "2006-03-14T08:00:00-03:00",
569
+ "operator": "Perfuradora XYZ",
570
+ "equipment": "Submersible pump 15 CV",
571
+ "static_level": 28.74,
572
+ "static_level_precision": 0.01,
573
+ "steps": [
574
+ {
575
+ "rate": 340.0,
576
+ "duration": 1440,
577
+ "readings": [
578
+ { "elapsed": 1, "depth": 32.1 },
579
+ { "elapsed": 5, "depth": 38.4 },
580
+ { "elapsed": 30, "depth": 42.8 },
581
+ { "elapsed": 60, "depth": 43.9 },
582
+ { "elapsed": 1440, "depth": 44.8 }
583
+ ]
584
+ }
585
+ ],
586
+ "recovery": {
587
+ "readings": [
588
+ { "elapsed": 5, "depth": 38.2 },
589
+ { "elapsed": 15, "depth": 33.6 },
590
+ { "elapsed": 30, "depth": 30.1 }
591
+ ]
592
+ },
593
+ "notes": "Test terminated at 24h. Recovery monitored for 30 min."
594
+ },
595
+ {
596
+ "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
597
+ "type": "spot_measurement",
598
+ "datetime": "2010-07-22T09:15:00-03:00",
599
+ "static_level": 31.2,
600
+ "measurement_method": "electric_probe",
601
+ "notes": "Routine annual monitoring."
602
+ }
603
+ ],
604
+
605
+ "aquifer_analysis": [
606
+ {
607
+ "id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
608
+ "datetime": "2006-03-15T16:00:00-03:00",
609
+ "analyst": "Dr. Maria Silva",
610
+ "source_event_ids": ["b2c3d4e5-f6a7-8901-bcde-f12345678901"],
611
+ "method": "cooper_jacob",
612
+ "static_level": 28.74,
613
+ "static_level_source_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
614
+ "dynamic_level": 44.8,
615
+ "flow_rate": 340.0,
616
+ "specific_capacity": 21.17,
617
+ "transmissivity": 4.2e-4,
618
+ "storativity": null,
619
+ "notes": "Cooper-Jacob straight-line fit, t=10min to t=1440min. S not determinable — no observation well."
620
+ }
621
+ ],
622
+
623
+ "history_logs": [
624
+ {
625
+ "id": "d0e1f2a3-b4c5-6789-defa-890123456789",
626
+ "datetime": "2006-03-10T00:00:00-03:00",
627
+ "updated_at": "2006-03-10T00:00:00-03:00",
628
+ "category": "event",
629
+ "description": "Well construction completed. Commissioned for public supply by COSANPA. Initial flow rate 340 m³/h via air-lift.",
630
+ "author": "Prefeitura Municipal de Belém"
631
+ },
632
+ {
633
+ "id": "a7b8c9d0-e1f2-3456-abcd-567890123456",
634
+ "datetime": "2018-06-12T09:30:00-03:00",
635
+ "updated_at": "2024-03-15T11:42:00-03:00",
636
+ "category": "maintenance",
637
+ "description": "Original 15 CV submersible pump replaced after motor burnout. New pump: Schneider ME-25 10 CV. (Description corrected 2024-03-15: model was ME-25, not ME-22 as originally logged.)",
638
+ "author": "Manutenção Rápida Ltda.",
639
+ "severity": "high",
640
+ "attachments": [
641
+ {
642
+ "id": "b8c9d0e1-f2a3-4567-bcde-678901234567",
643
+ "uri": "https://files.wellmanager.example.com/wells/pp-01/attachments/nota-fiscal-bomba-2018.pdf",
644
+ "media_type": "application/pdf",
645
+ "filename": "nota-fiscal-bomba-2018.pdf",
646
+ "description": "Purchase invoice for replacement pump",
647
+ "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
648
+ }
649
+ ]
650
+ }
651
+ ]
652
+ }
653
+ ```
654
+
655
+ ---
656
+
657
+ _Draft — `.well` Format Specification v2.0_