@welldot/core 0.4.0-next.20261015.d7c7365 → 0.5.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/README.md +59 -19
- package/dist/index.cjs +344 -178
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +9203 -5704
- package/dist/index.d.ts +9203 -5704
- package/dist/index.js +334 -178
- package/dist/index.js.map +1 -1
- package/docs/reference/fgdc-textures.md +15 -0
- package/docs/schema/v2/well.schema.json +128 -11
- package/docs/spec/v1/well-format.md +26 -0
- package/docs/spec/v2/format-reference.md +170 -45
- package/docs/spec/v2/interoperability.md +25 -4
- package/docs/spec/v2/object-schemas.md +243 -96
- package/docs/spec/v2/overview.md +92 -9
- package/docs/spec/v2/water-quality.md +26 -3
- package/examples/README.md +12 -0
- package/examples/belem-pa-condominio-outorga.well +2 -1
- package/examples/belem-pa-monitoramento-posto.well +2 -1
- package/examples/belem-pa-pirabas-abastecimento.well +2 -2
- package/examples/belem-pa-poco-colmatado.well +2 -1
- package/examples/belem-pa-poco-raso-abandonado.well +2 -1
- package/examples/belem-pa-qualidade-agua-acida.well +2 -1
- package/examples/colatina-es-gnaisse-rural.well +2 -2
- package/examples/coluna-mg-cristalino-abastecimento.well +2 -2
- package/examples/estrela-doeste-sp-bauru-serra-geral.well +2 -1
- package/examples/extremoz-rn-barreiras-raso.well +2 -1
- package/examples/gastao-vidigal-sp-dados-inconsistentes.well +2 -1
- package/examples/irece-ba-carste-bambui.well +2 -1
- package/examples/lagoa-santa-mg-carste-abastecimento.well +2 -2
- package/examples/minas-novas-mg-cadastro-incompleto.well +2 -1
- package/examples/quixeramobim-ce-cristalino-salobro.well +2 -2
- package/examples/rinopolis-sp-estratigrafico-guarani.well +2 -1
- package/examples/santarem-pa-jorrante-alter-do-chao.well +2 -1
- package/examples/sao-gabriel-rs-cacimba.well +2 -1
- package/examples/sete-lagoas-mg-carste-industrial.well +2 -1
- package/package.json +1 -1
|
@@ -1,7 +1,86 @@
|
|
|
1
|
-
# `.well` File Format Specification — Version 2.
|
|
1
|
+
# `.well` File Format Specification — Version 2.4: Object Schemas
|
|
2
2
|
|
|
3
3
|
**See also:** [overview.md](./overview.md) · [format-reference.md](./format-reference.md) · [interoperability.md](./interoperability.md) · [water-quality.md](./water-quality.md)
|
|
4
4
|
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
This part of the `.well` v2.4 specification defines the records inside each top-level block: the common types (`Attachment`, date durations), the construction and geology objects, the `hydrodynamic_events` ledger and its supporting objects, `aquifer_analysis`, `history_logs`, and the operational blocks added in v2.3 (`pump_installations`, `permits`, `meters`, `production`, `operating_regime`). It ends with a complete example file. Water samples are specified in [water-quality.md](./water-quality.md); units and cross-reference rules in [format-reference.md](./format-reference.md).
|
|
8
|
+
|
|
9
|
+
## Table of contents
|
|
10
|
+
|
|
11
|
+
- [Common Types _(since v2.3)_](#common-types-since-v23)
|
|
12
|
+
- [`Attachment`](#attachment)
|
|
13
|
+
- [Date duration](#date-duration)
|
|
14
|
+
- [Object Schemas](#object-schemas)
|
|
15
|
+
- [`BoreHole` — `bore_hole[]`](#borehole--bore_hole)
|
|
16
|
+
- [`WellCase` — `well_case[]`](#wellcase--well_case)
|
|
17
|
+
- [`Reduction` — `reduction[]`](#reduction--reduction)
|
|
18
|
+
- [`WellScreen` — `well_screen[]`](#wellscreen--well_screen)
|
|
19
|
+
- [`SurfaceCase` — `surface_case[]`](#surfacecase--surface_case)
|
|
20
|
+
- [`HoleFill` — `hole_fill[]`](#holefill--hole_fill)
|
|
21
|
+
- [`Centralizer` — `centralizers[]` _(since v2.1)_](#centralizer--centralizers-since-v21)
|
|
22
|
+
- [`CementPad` — `cement_pad`](#cementpad--cement_pad)
|
|
23
|
+
- [`Lithology` — `lithology[]`](#lithology--lithology)
|
|
24
|
+
- [`Texture`](#texture)
|
|
25
|
+
- [`Fracture` — `fractures[]`](#fracture--fractures)
|
|
26
|
+
- [`Cave` — `caves[]`](#cave--caves)
|
|
27
|
+
- [`hydrodynamic_events[]`](#hydrodynamic_events)
|
|
28
|
+
- [Event types](#event-types)
|
|
29
|
+
- [Common fields (all event types)](#common-fields-all-event-types)
|
|
30
|
+
- [Corrections _(since v2.3)_](#corrections-since-v23)
|
|
31
|
+
- [`spot_measurement`](#spot_measurement)
|
|
32
|
+
- [`constant_rate`](#constant_rate)
|
|
33
|
+
- [`step_drawdown`](#step_drawdown)
|
|
34
|
+
- [`airlift`](#airlift)
|
|
35
|
+
- [`recovery_only`](#recovery_only)
|
|
36
|
+
- [`logger_series` _(since v2.4)_](#logger_series-since-v24)
|
|
37
|
+
- [Supporting Object Schemas](#supporting-object-schemas)
|
|
38
|
+
- [`PumpingStep`](#pumpingstep)
|
|
39
|
+
- [`LevelReading`](#levelreading)
|
|
40
|
+
- [`RecoveryPhase`](#recoveryphase)
|
|
41
|
+
- [`aquifer_analysis[]`](#aquifer_analysis)
|
|
42
|
+
- [`method` — Recommended values](#method--recommended-values)
|
|
43
|
+
- [Derived Parameters — Computation Reference](#derived-parameters--computation-reference)
|
|
44
|
+
- [Querying Current State](#querying-current-state)
|
|
45
|
+
- [`history_logs[]`](#history_logs)
|
|
46
|
+
- [Categories](#categories)
|
|
47
|
+
- [`HistoryLogEntry`](#historylogentry)
|
|
48
|
+
- [`updated_at` semantics](#updated_at-semantics)
|
|
49
|
+
- [Data links _(since v2.3)_](#data-links-since-v23)
|
|
50
|
+
- [Category-specific fields _(since v2.3)_](#category-specific-fields-since-v23)
|
|
51
|
+
- [`pump_installations[]` _(since v2.3)_](#pump_installations-since-v23)
|
|
52
|
+
- [`PumpInstallation`](#pumpinstallation)
|
|
53
|
+
- [`PumpElectrical`](#pumpelectrical)
|
|
54
|
+
- [Validation (warnings, never rejection)](#validation-warnings-never-rejection)
|
|
55
|
+
- [Derived values](#derived-values)
|
|
56
|
+
- [Rendering](#rendering)
|
|
57
|
+
- [`permits[]` _(since v2.3)_](#permits-since-v23)
|
|
58
|
+
- [`Permit`](#permit)
|
|
59
|
+
- [`PermitHistoryEntry`](#permithistoryentry)
|
|
60
|
+
- [`VolumeLimit`](#volumelimit)
|
|
61
|
+
- [`MonthlyGrant`](#monthlygrant)
|
|
62
|
+
- [`PermitCondition`](#permitcondition)
|
|
63
|
+
- [Deadline generation (normative)](#deadline-generation-normative)
|
|
64
|
+
- [Condition fulfillment](#condition-fulfillment)
|
|
65
|
+
- [Permit status (derived)](#permit-status-derived)
|
|
66
|
+
- [Validation (warnings, never rejection)](#validation-warnings-never-rejection-1)
|
|
67
|
+
- [`meters[]` _(since v2.3)_](#meters-since-v23)
|
|
68
|
+
- [`Meter`](#meter)
|
|
69
|
+
- [Validation (warnings, never rejection)](#validation-warnings-never-rejection-2)
|
|
70
|
+
- [`production[]` _(since v2.3)_](#production-since-v23)
|
|
71
|
+
- [Common fields](#common-fields)
|
|
72
|
+
- [`meter_reading`](#meter_reading)
|
|
73
|
+
- [`estimated_volume`](#estimated_volume)
|
|
74
|
+
- [Volume derivation (normative)](#volume-derivation-normative)
|
|
75
|
+
- [Precedence](#precedence)
|
|
76
|
+
- [Derived values](#derived-values-1)
|
|
77
|
+
- [Validation (warnings, never rejection)](#validation-warnings-never-rejection-3)
|
|
78
|
+
- [`operating_regime[]` _(since v2.3)_](#operating_regime-since-v23)
|
|
79
|
+
- [`OperatingRegime`](#operatingregime)
|
|
80
|
+
- [Validation (warnings, never rejection)](#validation-warnings-never-rejection-4)
|
|
81
|
+
- [`water_samples[]` _(since v2.3)_](#water_samples-since-v23)
|
|
82
|
+
- [Complete Example](#complete-example)
|
|
83
|
+
|
|
5
84
|
---
|
|
6
85
|
|
|
7
86
|
## Common Types _(since v2.3)_
|
|
@@ -13,7 +92,7 @@ The `.well` format is not a file container. Attachments are referenced by URL. S
|
|
|
13
92
|
| Field | Type | Required | Description |
|
|
14
93
|
| --------------- | ------ | -------- | ------------------------------------------------------------------------------------------ |
|
|
15
94
|
| `id` | string | yes | Unique within its owning `attachments` array. UUID v4 recommended. |
|
|
16
|
-
| `uri` | string | yes | Full HTTPS URL.
|
|
95
|
+
| `uri` | string | yes | Full HTTPS URL. A relative path is valid only inside an offline package _(since v2.4)_. |
|
|
17
96
|
| `media_type` | string | yes | MIME type (e.g. `image/jpeg`, `application/pdf`). |
|
|
18
97
|
| `document_type` | string | no | What the document is. See format-reference.md § `Attachment.document_type`. _(since v2.3)_ |
|
|
19
98
|
| `filename` | string | no | Original filename for display. |
|
|
@@ -22,18 +101,20 @@ The `.well` format is not a file container. Attachments are referenced by URL. S
|
|
|
22
101
|
|
|
23
102
|
#### Where attachments are allowed
|
|
24
103
|
|
|
25
|
-
| Location
|
|
26
|
-
|
|
|
27
|
-
| Root `attachments[]`
|
|
28
|
-
| `history_logs[].attachments`
|
|
29
|
-
| `permits[].attachments`
|
|
30
|
-
| `
|
|
31
|
-
| `
|
|
32
|
-
| `
|
|
33
|
-
| `
|
|
34
|
-
| `
|
|
35
|
-
|
|
36
|
-
|
|
104
|
+
| Location | Purpose |
|
|
105
|
+
| --------------------------------------------------- | --------------------------------------------------------------------------- |
|
|
106
|
+
| Root `attachments[]` | Documents about the well as a whole, not tied to any record. _(since v2.3)_ |
|
|
107
|
+
| `history_logs[].attachments` | Supporting documents or photos of a log entry. |
|
|
108
|
+
| `permits[].attachments` | The legal document (portaria, certificate). _(since v2.3)_ |
|
|
109
|
+
| `permits[].history[].attachments` | Notices, receipts, protocols of an administrative step. _(since v2.3)_ |
|
|
110
|
+
| `permits[].conditions[].fulfillments[].attachments` | Proof of submission (`condition_evidence`). _(since v2.3)_ |
|
|
111
|
+
| `pump_installations[].attachments` | Pump curves, invoices, photos. _(since v2.3)_ |
|
|
112
|
+
| `meters[].attachments` | Installation photos, invoices, certificates. _(since v2.3)_ |
|
|
113
|
+
| `hydrodynamic_events[].attachments` | Field sheets, logger exports. _(since v2.3)_ |
|
|
114
|
+
| `aquifer_analysis[].attachments` | Interpretation reports. _(since v2.3)_ |
|
|
115
|
+
| `water_samples[].attachments` | Laboratory reports (`lab_report`), field sheets, photos. _(since v2.3)_ |
|
|
116
|
+
|
|
117
|
+
An attachment belongs to the record it documents. A document that concerns several records is repeated on each; the repetition is one URI and one hash, and the hash guarantees both copies point to the same file. The root array is not a registry, and records do not reference root attachments by id. Nor is it an aggregate: it holds only general files about the well as a whole (e.g. the drilling report), never copies of the attachments of `history_logs`, `permits` (including their `history` entries and condition `fulfillments`), `pump_installations`, `meters`, `hydrodynamic_events`, `aquifer_analysis` or `water_samples` entries.
|
|
37
118
|
|
|
38
119
|
`Attachment.id` is unique within its owning array: the root `attachments[]`, or the `attachments` array of one record. The same id may appear under different records.
|
|
39
120
|
|
|
@@ -262,19 +343,22 @@ A cavity or void zone.
|
|
|
262
343
|
|
|
263
344
|
## `hydrodynamic_events[]`
|
|
264
345
|
|
|
265
|
-
A chronological
|
|
346
|
+
A chronological ledger of all hydrodynamic observations; it grows by appending. 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.
|
|
266
347
|
|
|
267
|
-
> **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
|
|
348
|
+
> **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 should carry, whether recovery is permitted, and whether its event ID is valid input to `source_event_ids` on an `aquifer_analysis` entry.
|
|
268
349
|
|
|
269
350
|
### Event types
|
|
270
351
|
|
|
271
|
-
| `type` | Português (BR) | What it records
|
|
272
|
-
| ------------------ | ------------------------- |
|
|
273
|
-
| `spot_measurement` | Medição pontual | Static water level during a routine visit; optionally an informal brief pump observation. Not a controlled test.
|
|
274
|
-
| `constant_rate` | Teste de vazão constante | Controlled pump test at exactly one fixed rate.
|
|
275
|
-
| `step_drawdown` | Teste de vazão escalonada | Controlled pump test at two or more successive rates in ascending order.
|
|
276
|
-
| `airlift` | Air-lift | Historical fact that air-lift development was performed and produced an estimated yield.
|
|
277
|
-
| `recovery_only` | Apenas recuperação | Recovery after a pumping event whose drawdown data was not recorded.
|
|
352
|
+
| `type` | Português (BR) | What it records | `steps` constraint | `recovery` | Valid in `source_event_ids` |
|
|
353
|
+
| ------------------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------ | ---------- | -------------------------------- |
|
|
354
|
+
| `spot_measurement` | Medição pontual | Static water level during a routine visit; optionally an informal brief pump observation. Not a controlled test. | SHOULD be 0 or 1 | Optional | As `static_level_source_id` only |
|
|
355
|
+
| `constant_rate` | Teste de vazão constante | Controlled pump test at exactly one fixed rate. | SHOULD be exactly 1 | Optional | Yes |
|
|
356
|
+
| `step_drawdown` | Teste de vazão escalonada | Controlled pump test at two or more successive rates in ascending order. | SHOULD be ≥ 2, ascending | Optional | Yes |
|
|
357
|
+
| `airlift` | Air-lift | Historical fact that air-lift development was performed and produced an estimated yield. | SHOULD be ≥ 1 | Optional | No — see § airlift |
|
|
358
|
+
| `recovery_only` | Apenas recuperação | Recovery after a pumping event whose drawdown data was not recorded. | None | Required | Yes |
|
|
359
|
+
| `logger_series` | Série de datalogger | Continuous level series recorded by an installed sensor. Not a controlled test nor a static level. _(since v2.4)_ | None | No | No — see § logger_series |
|
|
360
|
+
|
|
361
|
+
Each known `type` MUST satisfy its own schema: a malformed `constant_rate`, for example, is invalid rather than read as an unknown type. The step counts in the table are recommendations: `steps` MUST be an array of valid `PumpingStep` entries, but another count is valid. _(since v2.4)_
|
|
278
362
|
|
|
279
363
|
The `type` field accepts any string. Non-canonical values SHOULD use the `x-` prefix.
|
|
280
364
|
|
|
@@ -296,7 +380,7 @@ Only `id`, `type`, and `datetime` are required. All others are optional for all
|
|
|
296
380
|
|
|
297
381
|
### Corrections _(since v2.3)_
|
|
298
382
|
|
|
299
|
-
`hydrodynamic_events` is a ledger:
|
|
383
|
+
`hydrodynamic_events` is a ledger: events MAY be edited in place, but editing is NOT RECOMMENDED after the event has been exported. `corrects` remains the recommended mechanism for measurement corrections (a re-measurement): the correction is a new event whose `corrects` holds the id of the retracted event.
|
|
300
384
|
|
|
301
385
|
- A retracted event stays in the file but is excluded from every derivation (current static level, analyses, charts).
|
|
302
386
|
- Chains are allowed (C corrects B, which corrected A); only the last uncorrected entry counts.
|
|
@@ -307,24 +391,24 @@ Only `id`, `type`, and `datetime` are required. All others are optional for all
|
|
|
307
391
|
|
|
308
392
|
### `spot_measurement`
|
|
309
393
|
|
|
310
|
-
| Field | Type | Required | Description
|
|
311
|
-
| ------------------------ | --------------- | -------- |
|
|
312
|
-
| `static_level` | number | yes | Depth to water surface from ground level, in meters. Negative when the level is above ground (flowing artesian). See § Level sign convention.
|
|
313
|
-
| `static_level_precision` | number | no | One-sigma precision of `static_level`.
|
|
314
|
-
| `measurement_method` | string | no | Open vocabulary: see [format-reference.md](format-reference.md) § `hydrodynamic_events[].measurement_method`.
|
|
315
|
-
| `steps` | `PumpingStep[]` | no |
|
|
316
|
-
| `recovery` | `RecoveryPhase` | no | Recovery after the optional pumping step.
|
|
394
|
+
| Field | Type | Required | Description |
|
|
395
|
+
| ------------------------ | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
396
|
+
| `static_level` | number | yes | Depth to water surface from ground level, in meters. Negative when the level is above ground (flowing artesian). See § Level sign convention. |
|
|
397
|
+
| `static_level_precision` | number | no | One-sigma precision of `static_level`. |
|
|
398
|
+
| `measurement_method` | string | no | Open vocabulary: see [format-reference.md](format-reference.md) § `hydrodynamic_events[].measurement_method`. |
|
|
399
|
+
| `steps` | `PumpingStep[]` | no | SHOULD carry at most one step; another count is valid. For an informal brief pump observation during the visit — not a controlled test. Use `constant_rate` for a formal test. |
|
|
400
|
+
| `recovery` | `RecoveryPhase` | no | Recovery after the optional pumping step. |
|
|
317
401
|
|
|
318
402
|
---
|
|
319
403
|
|
|
320
404
|
### `constant_rate`
|
|
321
405
|
|
|
322
|
-
| Field | Type | Required | Description
|
|
323
|
-
| ------------------------ | --------------- | -------- |
|
|
324
|
-
| `static_level` | number | no | Pre-test static level in meters. Omit if not measured.
|
|
325
|
-
| `static_level_precision` | number | no | One-sigma precision of `static_level`.
|
|
326
|
-
| `steps` | `PumpingStep[]` | no |
|
|
327
|
-
| `recovery` | `RecoveryPhase` | no | Recovery measurements after pump shutdown.
|
|
406
|
+
| Field | Type | Required | Description |
|
|
407
|
+
| ------------------------ | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
408
|
+
| `static_level` | number | no | Pre-test static level in meters. Omit if not measured. |
|
|
409
|
+
| `static_level_precision` | number | no | One-sigma precision of `static_level`. |
|
|
410
|
+
| `steps` | `PumpingStep[]` | no | SHOULD carry exactly one entry; another count is valid. A second step would make this a `step_drawdown`. Omit if only recovery data is available. |
|
|
411
|
+
| `recovery` | `RecoveryPhase` | no | Recovery measurements after pump shutdown. |
|
|
328
412
|
|
|
329
413
|
---
|
|
330
414
|
|
|
@@ -332,12 +416,12 @@ Only `id`, `type`, and `datetime` are required. All others are optional for all
|
|
|
332
416
|
|
|
333
417
|
Jacob's `B` and `C` are derived — store them in `aquifer_analysis`, never here.
|
|
334
418
|
|
|
335
|
-
| Field | Type | Required | Description
|
|
336
|
-
| ------------------------ | --------------- | -------- |
|
|
337
|
-
| `static_level` | number | no | Pre-test static level in meters.
|
|
338
|
-
| `static_level_precision` | number | no | One-sigma precision of `static_level`.
|
|
339
|
-
| `steps` | `PumpingStep[]` | yes |
|
|
340
|
-
| `recovery` | `RecoveryPhase` | no | Recovery after the final step.
|
|
419
|
+
| Field | Type | Required | Description |
|
|
420
|
+
| ------------------------ | --------------- | -------- | --------------------------------------------------------------------------------------- |
|
|
421
|
+
| `static_level` | number | no | Pre-test static level in meters. |
|
|
422
|
+
| `static_level_precision` | number | no | One-sigma precision of `static_level`. |
|
|
423
|
+
| `steps` | `PumpingStep[]` | yes | SHOULD carry two or more steps in ascending order of flow rate; another count is valid. |
|
|
424
|
+
| `recovery` | `RecoveryPhase` | no | Recovery after the final step. |
|
|
341
425
|
|
|
342
426
|
---
|
|
343
427
|
|
|
@@ -347,10 +431,10 @@ This type exists to record the historical fact that air-lift development was per
|
|
|
347
431
|
|
|
348
432
|
Static level is not reliably measurable during air-lift and SHOULD be omitted.
|
|
349
433
|
|
|
350
|
-
| Field | Type | Required | Description
|
|
351
|
-
| ---------- | --------------- | -------- |
|
|
352
|
-
| `steps` | `PumpingStep[]` | yes |
|
|
353
|
-
| `recovery` | `RecoveryPhase` | no | Recovery measurements after air-lift shutdown, if recorded.
|
|
434
|
+
| Field | Type | Required | Description |
|
|
435
|
+
| ---------- | --------------- | -------- | --------------------------------------------------------------------------------------------------- |
|
|
436
|
+
| `steps` | `PumpingStep[]` | yes | SHOULD carry one or more steps; another count is valid. Each step may carry time-series `readings`. |
|
|
437
|
+
| `recovery` | `RecoveryPhase` | no | Recovery measurements after air-lift shutdown, if recorded. |
|
|
354
438
|
|
|
355
439
|
---
|
|
356
440
|
|
|
@@ -364,6 +448,64 @@ Static level is not reliably measurable during air-lift and SHOULD be omitted.
|
|
|
364
448
|
|
|
365
449
|
---
|
|
366
450
|
|
|
451
|
+
### `logger_series` _(since v2.4)_
|
|
452
|
+
|
|
453
|
+
A continuous level series recorded by an installed sensor: a pressure transducer with a datalogger, as used in monitoring networks and in mining (dewatering, slope piezometers, permit conditions). It is neither a controlled test nor a static level.
|
|
454
|
+
|
|
455
|
+
| Contract | Value |
|
|
456
|
+
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
457
|
+
| `steps` | None. `steps` MUST NOT be present. |
|
|
458
|
+
| `recovery` | No. `recovery` MUST NOT be present. |
|
|
459
|
+
| Valid in `source_event_ids` | No. |
|
|
460
|
+
| Valid as `static_level_source_id` | No. |
|
|
461
|
+
| Inherited common fields | `equipment`, `operator`, `attachments` (the raw logger export, with `sha256`), `corrects`, and the `history_logs[].hydrodynamic_event_ids` link. |
|
|
462
|
+
|
|
463
|
+
| Field | Type | Required | Description |
|
|
464
|
+
| ------------------------- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
465
|
+
| `measurement_method` | string | no | Open vocabulary: see [format-reference.md](format-reference.md) § `hydrodynamic_events[].measurement_method`. |
|
|
466
|
+
| `sensor_depth` | number | no | Sensor depth in meters from ground level. A level below it indicates an invalid reading. |
|
|
467
|
+
| `interval` | number | no | Nominal interval between readings, in minutes. Greater than zero. |
|
|
468
|
+
| `barometric_compensation` | string | no | Closed: `barologger` (Barologger / Barologger), `vented` (Vented cable / Cabo ventilado) or `none` (None / Nenhuma). |
|
|
469
|
+
| `aggregation` | string | no | Closed: `none` (Raw readings / Leituras brutas), `hourly` (Hourly / Horária) or `daily` (Daily / Diária). When `hourly` or `daily`, every reading MUST carry `depth_min` and `depth_max`. |
|
|
470
|
+
| `readings` | `LevelReading[]` | yes | One or more readings. Each reading MUST carry `datetime` and MUST NOT carry `elapsed`. See § LevelReading. |
|
|
471
|
+
|
|
472
|
+
A series MAY grow with new readings instead of becoming one event per download.
|
|
473
|
+
|
|
474
|
+
> **Note — pump state is not stored per reading.** A series has no per-reading `pumping` flag. In a well that pumps, the series mixes static and dynamic levels; interpretation crosses the series with `production` and `pump_installations`.
|
|
475
|
+
|
|
476
|
+
Validation (warnings, never rejection):
|
|
477
|
+
|
|
478
|
+
- An `aquifer_analysis` whose `source_event_ids` or `static_level_source_id` points to a `logger_series` emits a warning naming both ids.
|
|
479
|
+
- A reading whose `depth` is greater than `sensor_depth` (the level is below the sensor) emits a warning naming the event.
|
|
480
|
+
|
|
481
|
+
```json
|
|
482
|
+
{
|
|
483
|
+
"id": "8f2c1e4a-3b6d-4f0e-9a7c-5d1b2e3f4a5b",
|
|
484
|
+
"type": "logger_series",
|
|
485
|
+
"datetime": "2026-07-01T00:00:00-03:00",
|
|
486
|
+
"equipment": "Solinst Levelogger 5 LT, SN 2081234",
|
|
487
|
+
"measurement_method": "pressure_transducer",
|
|
488
|
+
"sensor_depth": 42.0,
|
|
489
|
+
"interval": 15,
|
|
490
|
+
"barometric_compensation": "barologger",
|
|
491
|
+
"aggregation": "none",
|
|
492
|
+
"readings": [
|
|
493
|
+
{
|
|
494
|
+
"datetime": "2026-07-01T00:00:00-03:00",
|
|
495
|
+
"depth": 18.42,
|
|
496
|
+
"pressure": 233.9
|
|
497
|
+
},
|
|
498
|
+
{
|
|
499
|
+
"datetime": "2026-07-01T00:15:00-03:00",
|
|
500
|
+
"depth": 18.44,
|
|
501
|
+
"pressure": 233.7
|
|
502
|
+
}
|
|
503
|
+
]
|
|
504
|
+
}
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
---
|
|
508
|
+
|
|
367
509
|
## Supporting Object Schemas
|
|
368
510
|
|
|
369
511
|
### `PumpingStep`
|
|
@@ -377,12 +519,15 @@ Static level is not reliably measurable during air-lift and SHOULD be omitted.
|
|
|
377
519
|
|
|
378
520
|
### `LevelReading`
|
|
379
521
|
|
|
380
|
-
| Field | Type | Required
|
|
381
|
-
| ----------------- | ------ |
|
|
382
|
-
| `elapsed` | number | yes
|
|
383
|
-
| `
|
|
384
|
-
| `
|
|
385
|
-
| `
|
|
522
|
+
| Field | Type | Required | Description |
|
|
523
|
+
| ----------------- | ------ | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
|
524
|
+
| `elapsed` | number | yes, except in `logger_series` | Time since step start (or pump shutdown for recovery) in minutes. MUST NOT be present in `logger_series` readings. |
|
|
525
|
+
| `datetime` | string | in `logger_series` only | RFC 3339 instant of the reading, with UTC offset. Required in `logger_series`; optional elsewhere. _(since v2.4)_ |
|
|
526
|
+
| `depth` | number | yes | Depth to water surface from ground level in meters. In an aggregated `logger_series`, the representative value of the interval. |
|
|
527
|
+
| `depth_precision` | number | no | One-sigma precision of `depth`. |
|
|
528
|
+
| `pressure` | number | no | Pressure transducer reading in kPa. |
|
|
529
|
+
| `depth_min` | number | aggregated `logger_series` only | Shallowest depth in the interval, in meters. Required when `aggregation` is `hourly` or `daily`; used only there. _(since v2.4)_ |
|
|
530
|
+
| `depth_max` | number | aggregated `logger_series` only | Deepest depth in the interval, in meters. Required when `aggregation` is `hourly` or `daily`; used only there. _(since v2.4)_ |
|
|
386
531
|
|
|
387
532
|
### `RecoveryPhase`
|
|
388
533
|
|
|
@@ -506,7 +651,7 @@ Vocabulary is open. Non-canonical values SHOULD use the `x-` prefix.
|
|
|
506
651
|
|
|
507
652
|
### `updated_at` semantics
|
|
508
653
|
|
|
509
|
-
- `updated_at`
|
|
654
|
+
- `updated_at` is usually later than `datetime`. It MAY be earlier when an entry is pre-dated (retroactive entry of a historical event); both orderings are valid and neither emits a warning.
|
|
510
655
|
- When a producer modifies the `description`, `category`, `severity`, `author`, or `attachments` of an existing entry, it SHOULD update `updated_at` to the current instant.
|
|
511
656
|
- 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.
|
|
512
657
|
- The `updated_at` field is not retroactive: parsers reading a v1 or early-v2.0 file without `updated_at` MUST NOT synthesize one.
|
|
@@ -627,29 +772,29 @@ A mutable record block: each entry transcribes one legal instrument governing ab
|
|
|
627
772
|
|
|
628
773
|
### `Permit`
|
|
629
774
|
|
|
630
|
-
| Field | Type | Required | Unit | Description
|
|
631
|
-
| ---------------------- | ---------------------- | -------- | ---- |
|
|
632
|
-
| `id` | string | yes | | Unique within `permits`. UUID v4 recommended.
|
|
633
|
-
| `type` | string | yes | | See format-reference.md § `permits[].type`.
|
|
634
|
-
| `authority` | string | yes | | Issuing body, e.g. `ANA`, `SEMAS-PA`. Same semantics as `well_id.authority`.
|
|
635
|
-
| `identifier` | string | no | | Identifier of the granted instrument (portaria, license code), verbatim.
|
|
636
|
-
| `request_identifier` | string | no | | Identifier of the request or administrative process (protocolo), verbatim.
|
|
637
|
-
| `status` | string (enum) | no | | Administrative status. Closed vocabulary, see below. Absent means `granted`.
|
|
638
|
-
| `issued_at` | string (date) | no | | Issue date.
|
|
639
|
-
| `valid_from` | string (date) | no | | Absent means valid from `issued_at`.
|
|
640
|
-
| `valid_until` | string (date) | no | | Absent means no fixed expiry.
|
|
641
|
-
| `renewal_requested_at` | string (date) | no | | Date a renewal request was filed.
|
|
642
|
-
| `water_use` | string[] | no | | See format-reference.md § `permits[].water_use`.
|
|
643
|
-
| `flow_rate` | number | no | m³/h | Maximum granted flow.
|
|
644
|
-
| `daily_operating_time` | number | no | h | Maximum granted daily operating time,
|
|
645
|
-
| `volume_limits` | `VolumeLimit[]` | no | | Only volumes stated in the document.
|
|
646
|
-
| `monthly_schedule` | `MonthlyGrant[]` | no | | Month-by-month grant.
|
|
647
|
-
| `conditions` | `PermitCondition[]` | no | | Obligations (condicionantes).
|
|
648
|
-
| `history` | `PermitHistoryEntry[]` | no | | Administrative steps: filing, process, notifications, fees.
|
|
649
|
-
| `supersedes` | string | no | | `permits[].id` of the instrument this one legally replaces.
|
|
650
|
-
| `notes` | string | no | |
|
|
651
|
-
| `updated_at` | string (instant) | no | | Last edit of this record.
|
|
652
|
-
| `attachments` | `Attachment[]` | no | | The legal document. See § Attachment.
|
|
775
|
+
| Field | Type | Required | Unit | Description |
|
|
776
|
+
| ---------------------- | ---------------------- | -------- | ---- | ----------------------------------------------------------------------------- |
|
|
777
|
+
| `id` | string | yes | | Unique within `permits`. UUID v4 recommended. |
|
|
778
|
+
| `type` | string | yes | | See format-reference.md § `permits[].type`. |
|
|
779
|
+
| `authority` | string | yes | | Issuing body, e.g. `ANA`, `SEMAS-PA`. Same semantics as `well_id.authority`. |
|
|
780
|
+
| `identifier` | string | no | | Identifier of the granted instrument (portaria, license code), verbatim. |
|
|
781
|
+
| `request_identifier` | string | no | | Identifier of the request or administrative process (protocolo), verbatim. |
|
|
782
|
+
| `status` | string (enum) | no | | Administrative status. Closed vocabulary, see below. Absent means `granted`. |
|
|
783
|
+
| `issued_at` | string (date) | no | | Issue date. |
|
|
784
|
+
| `valid_from` | string (date) | no | | Absent means valid from `issued_at`. |
|
|
785
|
+
| `valid_until` | string (date) | no | | Absent means no fixed expiry. |
|
|
786
|
+
| `renewal_requested_at` | string (date) | no | | Date a renewal request was filed. |
|
|
787
|
+
| `water_use` | string[] | no | | See format-reference.md § `permits[].water_use`. |
|
|
788
|
+
| `flow_rate` | number | no | m³/h | Maximum granted flow. |
|
|
789
|
+
| `daily_operating_time` | number | no | h | Maximum granted daily operating time. Above 24 is read as 24, with a warning. |
|
|
790
|
+
| `volume_limits` | `VolumeLimit[]` | no | | Only volumes stated in the document. |
|
|
791
|
+
| `monthly_schedule` | `MonthlyGrant[]` | no | | Month-by-month grant. |
|
|
792
|
+
| `conditions` | `PermitCondition[]` | no | | Obligations (condicionantes). |
|
|
793
|
+
| `history` | `PermitHistoryEntry[]` | no | | Administrative steps: filing, process, notifications, fees. |
|
|
794
|
+
| `supersedes` | string | no | | `permits[].id` of the instrument this one legally replaces. |
|
|
795
|
+
| `notes` | string | no | | |
|
|
796
|
+
| `updated_at` | string (instant) | no | | Last edit of this record. |
|
|
797
|
+
| `attachments` | `Attachment[]` | no | | The legal document. See § Attachment. |
|
|
653
798
|
|
|
654
799
|
`water_use` describes what the abstracted water is for. It is distinct from the top-level `well_purpose`, which describes the well's role.
|
|
655
800
|
|
|
@@ -702,7 +847,7 @@ Volumes implied by flow × time × days are derived and MUST NOT be stored here.
|
|
|
702
847
|
| ---------------------- | ------- | -------- | ---- | --------------------------------------- |
|
|
703
848
|
| `month` | integer | yes | | 1–12, unique within the schedule. |
|
|
704
849
|
| `flow_rate` | number | no | m³/h | |
|
|
705
|
-
| `daily_operating_time` | number | no | h |
|
|
850
|
+
| `daily_operating_time` | number | no | h | Above 24 is read as 24, with a warning. |
|
|
706
851
|
| `days` | integer | no | | Days of operation granted in the month. |
|
|
707
852
|
|
|
708
853
|
When `monthly_schedule` is present, a month absent from it has no abstraction granted. The top-level `flow_rate` and `daily_operating_time` hold the maximum across months; a monthly value above them emits a warning.
|
|
@@ -768,7 +913,7 @@ A water-quality `monitoring` condition is fulfilled by pointing to the sample wi
|
|
|
768
913
|
|
|
769
914
|
Derived status of each deadline, evaluated on the local civil date at the well site:
|
|
770
915
|
|
|
771
|
-
- **fulfilled** — a fulfillment has its `due_date`. **Fulfilled late** when that fulfillment's local date (the date part of
|
|
916
|
+
- **fulfilled** — a fulfillment has its `due_date`. **Fulfilled late** when that fulfillment's local date is after `due_date`. The local date is the `datetime` converted to `location.properties.timezone` _(since v2.4)_; without `timezone`, the date part of the string in the offset it carries.
|
|
772
917
|
- **upcoming** — no match and today is on or before `due_date`.
|
|
773
918
|
- **overdue** — no match and today is after `due_date`.
|
|
774
919
|
|
|
@@ -792,12 +937,13 @@ The lead time a renewal request requires varies by jurisdiction; it is evaluated
|
|
|
792
937
|
- `valid_until` earlier than the start date.
|
|
793
938
|
- A `supersedes` cycle, or a `supersedes` reference that does not resolve.
|
|
794
939
|
- Two granted, non-superseded permits of the same `type` with overlapping validity.
|
|
795
|
-
- A `daily_operating_time`
|
|
940
|
+
- A `daily_operating_time` above 24, on the permit or in `monthly_schedule`. It is read as 24 by every derivation; the stored value is not rewritten. A negative value is a schema error.
|
|
796
941
|
- A `monthly_schedule` value above the permit's top-level maximum.
|
|
797
942
|
- A duplicate `month`, `volume_limits` period, condition `id`, `history` `id` or fulfillment `id` within one permit.
|
|
798
943
|
- A condition with both `first_due` and `due_after`.
|
|
799
944
|
- A permit with neither `identifier` nor `request_identifier`, or a granted permit without `identifier`.
|
|
800
945
|
- A condition fulfillment that matches no deadline, or whose `event_id` / `sample_id` does not resolve.
|
|
946
|
+
- Permits with condition fulfillments in a file without `location.properties.timezone` _(since v2.4)_.
|
|
801
947
|
|
|
802
948
|
A collective grant covering several wells is repeated in each well's file until cross-file references arrive in v3.
|
|
803
949
|
|
|
@@ -838,7 +984,7 @@ The register values at installation and removal are recorded as ordinary `meter_
|
|
|
838
984
|
|
|
839
985
|
## `production[]` _(since v2.3)_
|
|
840
986
|
|
|
841
|
-
A ledger: the
|
|
987
|
+
A ledger: the record of water produced by the well, which grows by appending. Entries MAY be edited in place, but editing is NOT RECOMMENDED after the entry has been exported. `corrects` remains the recommended mechanism for measurement corrections: the correction is a new entry whose `corrects` holds the id of the retracted entry, following § `hydrodynamic_events[]` — Corrections (retracted entries stay in the file and are excluded from every derivation; chains are allowed; a cycle emits a warning). Entries are discriminated by `type`. Volumes are always derived, never stored as totals.
|
|
842
988
|
|
|
843
989
|
### Common fields
|
|
844
990
|
|
|
@@ -870,7 +1016,7 @@ A volume produced in a period, estimated without a meter (e.g. before a meter wa
|
|
|
870
1016
|
| Field | Type | Required | Unit | Description |
|
|
871
1017
|
| -------------- | ---------------- | -------- | ---- | ---------------------------------------------------------------------------------------- |
|
|
872
1018
|
| `period_start` | string (instant) | yes | | Start of the declared period. |
|
|
873
|
-
| `period_end` | string (instant) | yes | | End of the declared period.
|
|
1019
|
+
| `period_end` | string (instant) | yes | | End of the declared period. SHOULD be later than `period_start`; otherwise a warning. |
|
|
874
1020
|
| `volume` | number | yes | m³ | Volume produced in the period. |
|
|
875
1021
|
| `method` | string | no | | Basis of the estimate: `flow_time`, `energy`, `user_statement`, `x-…`. Descriptive only. |
|
|
876
1022
|
|
|
@@ -909,22 +1055,23 @@ A mutable record block: each entry declares how the well is intended to run from
|
|
|
909
1055
|
|
|
910
1056
|
### `OperatingRegime`
|
|
911
1057
|
|
|
912
|
-
| Field | Type | Required | Unit | Description
|
|
913
|
-
| ---------------------- | ---------------- | -------- | ---- |
|
|
914
|
-
| `id` | string | yes | | Unique within `operating_regime`.
|
|
915
|
-
| `effective_from` | string (instant) | yes | | When the regime takes effect.
|
|
916
|
-
| `flow_rate` | number | no | m³/h |
|
|
917
|
-
| `daily_operating_time` | number | no | h |
|
|
918
|
-
| `days_per_week` | integer | no | | 1–7.
|
|
919
|
-
| `notes` | string | no | |
|
|
920
|
-
| `updated_at` | string (instant) | no | | Last edit of this record.
|
|
1058
|
+
| Field | Type | Required | Unit | Description |
|
|
1059
|
+
| ---------------------- | ---------------- | -------- | ---- | ------------------------------------------------------- |
|
|
1060
|
+
| `id` | string | yes | | Unique within `operating_regime`. |
|
|
1061
|
+
| `effective_from` | string (instant) | yes | | When the regime takes effect. Duplicates are a warning. |
|
|
1062
|
+
| `flow_rate` | number | no | m³/h | |
|
|
1063
|
+
| `daily_operating_time` | number | no | h | Above 24 is read as 24, with a warning. |
|
|
1064
|
+
| `days_per_week` | integer | no | | 1–7. |
|
|
1065
|
+
| `notes` | string | no | | |
|
|
1066
|
+
| `updated_at` | string (instant) | no | | Last edit of this record. |
|
|
921
1067
|
|
|
922
1068
|
- An absent field means unknown, never zero.
|
|
923
1069
|
- A stopped well is recorded with a `history_logs` `status_change`, not a regime with `flow_rate: 0`.
|
|
924
|
-
- `daily_operating_time`
|
|
1070
|
+
- A `daily_operating_time` above 24 is stored as written, read as 24 by every derivation, and emits a warning. A negative `daily_operating_time` is a schema error, as is a `days_per_week` outside 1–7 (or not an integer).
|
|
925
1071
|
|
|
926
1072
|
### Validation (warnings, never rejection)
|
|
927
1073
|
|
|
1074
|
+
- A `daily_operating_time` above 24.
|
|
928
1075
|
- Two entries with the same `effective_from`.
|
|
929
1076
|
- Regime values above those of the permit active at `effective_from` (`flow_rate`, `daily_operating_time`).
|
|
930
1077
|
|
|
@@ -942,7 +1089,7 @@ A ledger of water samples, each with its field and laboratory results. The full
|
|
|
942
1089
|
{
|
|
943
1090
|
"$schema": "https://welldot.org/schema/v2/well.schema.json",
|
|
944
1091
|
"@context": "https://welldot.org/context/v2.jsonld",
|
|
945
|
-
"version": 2,
|
|
1092
|
+
"version": "2.4",
|
|
946
1093
|
"well_type": "tubular",
|
|
947
1094
|
"well_purpose": ["production"],
|
|
948
1095
|
"name": "Poço PP-01",
|
|
@@ -960,6 +1107,7 @@ A ledger of water samples, each with its field and laboratory results. The full
|
|
|
960
1107
|
"lng": -48.5039,
|
|
961
1108
|
"elevation": 12.5,
|
|
962
1109
|
"properties": {
|
|
1110
|
+
"timezone": "America/Belem",
|
|
963
1111
|
"elevation_datum": "wgs84_ellipsoid",
|
|
964
1112
|
"crs": "EPSG:4326",
|
|
965
1113
|
"elevation_precision": 0.5
|
|
@@ -1012,7 +1160,7 @@ A ledger of water samples, each with its field and laboratory results. The full
|
|
|
1012
1160
|
}
|
|
1013
1161
|
],
|
|
1014
1162
|
"cement_pad": {
|
|
1015
|
-
"type": "
|
|
1163
|
+
"type": "concrete",
|
|
1016
1164
|
"width": 1.0,
|
|
1017
1165
|
"thickness": 0.15,
|
|
1018
1166
|
"length": 1.0
|
|
@@ -1131,7 +1279,6 @@ A ledger of water samples, each with its field and laboratory results. The full
|
|
|
1131
1279
|
"flow_rate": 340.0,
|
|
1132
1280
|
"specific_capacity": 21.17,
|
|
1133
1281
|
"transmissivity": 4.2e-4,
|
|
1134
|
-
"storativity": null,
|
|
1135
1282
|
"notes": "Cooper-Jacob straight-line fit, t=10min to t=1440min. S not determinable — no observation well."
|
|
1136
1283
|
}
|
|
1137
1284
|
],
|
|
@@ -1555,4 +1702,4 @@ A ledger of water samples, each with its field and laboratory results. The full
|
|
|
1555
1702
|
|
|
1556
1703
|
---
|
|
1557
1704
|
|
|
1558
|
-
_`.well` Format Specification v2.
|
|
1705
|
+
_`.well` Format Specification v2.4_
|