@welldot/core 0.2.3 → 0.3.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 +5 -3
- package/dist/index.cjs +26 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +117 -2
- package/dist/index.d.ts +117 -2
- package/dist/index.js +25 -0
- package/dist/index.js.map +1 -1
- package/docs/schema/v2/well.schema.json +40 -0
- package/docs/spec/v2/format-reference.md +38 -4
- package/docs/spec/v2/interoperability.md +4 -2
- package/docs/spec/v2/object-schemas.md +45 -14
- package/docs/spec/v2/overview.md +31 -4
- package/package.json +1 -1
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# `.well` File Format Specification — Version 2.
|
|
1
|
+
# `.well` File Format Specification — Version 2.1: Object Schemas
|
|
2
2
|
|
|
3
3
|
**See also:** [overview.md](./overview.md) · [format-reference.md](./format-reference.md) · [interoperability.md](./interoperability.md)
|
|
4
4
|
|
|
@@ -92,6 +92,26 @@ Material placed in the annular space between casing and borehole wall.
|
|
|
92
92
|
|
|
93
93
|
---
|
|
94
94
|
|
|
95
|
+
### `Centralizer` — `centralizers[]` _(since v2.1)_
|
|
96
|
+
|
|
97
|
+
Centralizers clamped to a casing or screen string to keep it concentric in the borehole, so the gravel pack and annular seal have uniform thickness. Each entry describes a depth interval over which centralizers are installed at a regular spacing, which is how drilling reports usually give them.
|
|
98
|
+
|
|
99
|
+
| Field | Type | Required | Description |
|
|
100
|
+
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------- |
|
|
101
|
+
| `from` | number | yes | Start depth in meters (depth of the first centralizer). |
|
|
102
|
+
| `to` | number | yes | End depth in meters (depth of the last centralizer). `from === to` denotes a single centralizer. |
|
|
103
|
+
| `spacing` | number | no | Spacing between consecutive centralizers in meters. Must be positive. Omit when the spacing is unknown. |
|
|
104
|
+
| `type` | string | yes | Centralizer type. Recommended: `spring_bow`, `rigid`, `semi_rigid`, `polymer`. Non-canonical values use `x-`. |
|
|
105
|
+
| `diameter` | number | no | As-built outer diameter in millimeters. |
|
|
106
|
+
| `description` | string | no | Free-text description (e.g. material, manufacturer). |
|
|
107
|
+
|
|
108
|
+
- The array is **optional**. v2.0 documents without it remain valid.
|
|
109
|
+
- Individual positions are derived from `from`, `to`, and `spacing` (`from`, `from + spacing`, … up to `to`). The count is derived and MUST NOT be stored.
|
|
110
|
+
- Each entry SHOULD fall within a `well_case` or `well_screen` interval. Validators MUST NOT reject documents that violate this.
|
|
111
|
+
- Centralizers do not contribute to the calculated well depth.
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
95
115
|
### `CementPad` — `cement_pad`
|
|
96
116
|
|
|
97
117
|
Concrete wellhead pad. **All dimensions are in meters**.
|
|
@@ -232,13 +252,13 @@ Only `id`, `type`, and `datetime` are required. All others are optional for all
|
|
|
232
252
|
|
|
233
253
|
### `spot_measurement`
|
|
234
254
|
|
|
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.
|
|
255
|
+
| Field | Type | Required | Description |
|
|
256
|
+
| ------------------------ | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
257
|
+
| `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. |
|
|
258
|
+
| `static_level_precision` | number | no | One-sigma precision of `static_level`. |
|
|
259
|
+
| `measurement_method` | string | no | Recommended: `electric_probe`, `pressure_transducer`, `air_line`, `tape`. |
|
|
260
|
+
| `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. |
|
|
261
|
+
| `recovery` | `RecoveryPhase` | no | Recovery after the optional pumping step. |
|
|
242
262
|
|
|
243
263
|
---
|
|
244
264
|
|
|
@@ -393,12 +413,13 @@ These timestamps may differ substantially: a maintenance intervention `datetime`
|
|
|
393
413
|
|
|
394
414
|
### Categories
|
|
395
415
|
|
|
396
|
-
| `category`
|
|
397
|
-
|
|
|
398
|
-
| `maintenance`
|
|
399
|
-
| `inspection`
|
|
400
|
-
| `incident`
|
|
401
|
-
| `event`
|
|
416
|
+
| `category` | Portuguese (BR) | Description |
|
|
417
|
+
| --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
418
|
+
| `maintenance` | Manutenção | Physical intervention: pump replacement, casing repair, cleaning, redevelopment. |
|
|
419
|
+
| `inspection` | Inspeção | Site visit without physical alteration: visual survey, camera inspection, sample collection. |
|
|
420
|
+
| `incident` | Incidente | Unplanned event: partial collapse, contamination, prolonged drought, vandalism. |
|
|
421
|
+
| `event` | Evento | Generic milestone: construction completion, commissioning, deactivation, reactivation, ownership transfer, rehabilitation, data-integrity repair. |
|
|
422
|
+
| `change_of_use` | Mudança de uso | _(since v2.1)_ The well's purpose changed (e.g. production → monitoring). Update `well_purpose` to the new use and log the change here. |
|
|
402
423
|
|
|
403
424
|
Vocabulary is open. Non-canonical values SHOULD use the `x-` prefix.
|
|
404
425
|
|
|
@@ -449,6 +470,7 @@ The `uri` field is a reference, not a guarantee. URLs may become unreachable ove
|
|
|
449
470
|
"@context": "https://welldot.org/context/v2.jsonld",
|
|
450
471
|
"version": 2,
|
|
451
472
|
"well_type": "tubular",
|
|
473
|
+
"well_purpose": ["production"],
|
|
452
474
|
"name": "Poço PP-01",
|
|
453
475
|
"well_driller": "Perfuradora XYZ",
|
|
454
476
|
"construction_date": "2006-03-10",
|
|
@@ -503,6 +525,15 @@ The `uri` field is a reference, not a guarantee. URLs may become unreachable ove
|
|
|
503
525
|
"description": "Cimento"
|
|
504
526
|
}
|
|
505
527
|
],
|
|
528
|
+
"centralizers": [
|
|
529
|
+
{
|
|
530
|
+
"from": 6,
|
|
531
|
+
"to": 54,
|
|
532
|
+
"spacing": 12,
|
|
533
|
+
"type": "spring_bow",
|
|
534
|
+
"diameter": 245
|
|
535
|
+
}
|
|
536
|
+
],
|
|
506
537
|
"cement_pad": {
|
|
507
538
|
"type": "square",
|
|
508
539
|
"width": 1.0,
|
package/docs/spec/v2/overview.md
CHANGED
|
@@ -1,11 +1,38 @@
|
|
|
1
|
-
# `.well` File Format Specification — Version 2.
|
|
1
|
+
# `.well` File Format Specification — Version 2.1: Overview
|
|
2
2
|
|
|
3
|
-
**Version:** 2.
|
|
3
|
+
**Version:** 2.1 **Extension:** `.well` **Encoding:** UTF-8 **Base format:** JSON **MIME type:** `application/vnd.well+json` **JSON Schema:** `https://welldot.org/schema/v2/well.schema.json` **JSON Schema draft:** 2020-12 **JSON-LD Context (optional):** `https://welldot.org/context/v2.jsonld` **Status:** v2.0 ratified — shipped in `@welldot/core` v0.2.0 · v2.1 shipped in `@welldot/core` v0.3.0
|
|
4
4
|
|
|
5
5
|
**See also:** [format-reference.md](./format-reference.md) · [object-schemas.md](./object-schemas.md) · [interoperability.md](./interoperability.md)
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
+
## Changes in v2.1
|
|
10
|
+
|
|
11
|
+
v2.1 is an additive minor revision. Every valid v2.0 document is a valid v2.1 document, and documents keep declaring `"version": 2`.
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
v2.1 additions:
|
|
15
|
+
- well_purpose (optional string[]): intended use(s) of the well —
|
|
16
|
+
production, monitoring, piezometer, water_level_indicator (INA),
|
|
17
|
+
observation, exploration, injection, dewatering
|
|
18
|
+
- centralizers (optional Centralizer[]): casing/screen centralizers
|
|
19
|
+
as depth interval + spacing
|
|
20
|
+
- history_logs category `change_of_use`
|
|
21
|
+
|
|
22
|
+
v2.1 clarifications:
|
|
23
|
+
- well_type describes the construction method only
|
|
24
|
+
- Level sign convention: water levels above ground are negative
|
|
25
|
+
(made explicit; already implied by "ground level as zero")
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
### Deprecations
|
|
29
|
+
|
|
30
|
+
| Deprecated | Replacement | Removal |
|
|
31
|
+
| ----------------------- | --------------------------------------------------------------------------------------------------------- | ------- |
|
|
32
|
+
| `well_type: "artesian"` | Construction method in `well_type` (usually `tubular`) + negative `static_level` in `hydrodynamic_events` | v3 |
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
9
36
|
## Changes from v1
|
|
10
37
|
|
|
11
38
|
```
|
|
@@ -60,7 +87,7 @@ The `.well` format is an open standard for representing water well data. It is d
|
|
|
60
87
|
- **Self-contained** — a single file encodes the complete record of one well.
|
|
61
88
|
- **Units are SI, declared by spec** — all numeric values in a `.well` file are stored in SI units. The format does not encode a per-file units declaration. See § Units for the canonical unit of each quantity. Conversion to and from a user's preferred display or input units is an application concern.
|
|
62
89
|
- **CRS is declared, not assumed** — geographic coordinates are accompanied by an explicit coordinate reference system declaration. The default is WGS84 (`EPSG:4326`).
|
|
63
|
-
- **Ground level as zero** — all depth values are measured from ground level (0); elevation above the WGS84 ellipsoid (or declared datum) is stored separately in `location.elevation`.
|
|
90
|
+
- **Ground level as zero** — all depth values are measured from ground level (0); elevation above the WGS84 ellipsoid (or declared datum) is stored separately in `location.elevation`. Water levels above ground are negative.
|
|
64
91
|
- **Geographic north** — all azimuth values are referenced to geographic north.
|
|
65
92
|
- **Append-only event history (by authoring convention)** — `hydrodynamic_events` is intended as a ledger. New measurements should be added as new entries; existing entries should not be modified. This is enforced by authoring tools in the welldot stack, not by the file format itself. The format provides `id`, `datetime`, and `sequence` to support this discipline.
|
|
66
93
|
- **Derived values are never stored raw** — `s/Q`, `Q/s`, drawdown `s`, and any other value computable from stored fields must not appear as stored fields. Applications compute them on demand.
|
|
@@ -82,4 +109,4 @@ The following are recognized limitations of this version, reserved for future ve
|
|
|
82
109
|
|
|
83
110
|
---
|
|
84
111
|
|
|
85
|
-
_`.well` Format Specification v2.
|
|
112
|
+
_`.well` Format Specification v2.1_
|
package/package.json
CHANGED