@welldot/core 0.2.2 → 0.3.0

package/docs/spec/v2/format-reference.md

@@ -1,4 +1,4 @@
-# `.well` File Format Specification — Version 2.0: Format Reference
+# `.well` File Format Specification — Version 2.1: Format Reference
 
 **See also:** [overview.md](./overview.md) · [object-schemas.md](./object-schemas.md) · [interoperability.md](./interoperability.md)
 
@@ -49,6 +49,8 @@
 | `1`     | Initial release — constructive and geologic data only                                                                                                                                                                                                                 |
 | `2`     | Adds location, well_id (array), profiles, texture object, hydrodynamic_events, aquifer_analysis, history_logs, optional @context, \*\_precision fields, and extensibility conventions. Tightens unit semantics: all values are canonical SI, no per-file declaration. |
 
+Minor revisions (`2.1`, …) are additive and do not change the `version` integer: a v2.1 document still declares `"version": 2`. A v2.0 parser reading a v2.1 document sees the v2.1 fields (`well_purpose`, `centralizers`) as unrecognized members without the `x-` prefix. Per § Extensibility it MUST preserve them and MUST NOT reject the file, and it SHOULD emit a warning.
+
 ### Parser version handling
 
 The `version` field is an integer and must always be present.
@@ -119,7 +121,7 @@ Each minor revision of this spec MUST include a "Deprecations" subsection in its
 | Field               | Type    | Required | Description                                                                                                                                                                                                                                     |
 | ------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `version`           | integer | yes      | Format version. Must be `2` for this spec.                                                                                                                                                                                                      |
-| `well_type`         | string  | yes      | Classification of the well. See vocabulary below.                                                                                                                                                                                               |
+| `well_type`         | string  | yes      | Construction method of the well. See vocabulary below.                                                                                                                                                                                          |
 | `name`              | string  | no       | Well name or local identifier.                                                                                                                                                                                                                  |
 | `well_driller`      | string  | no       | Name of the drilling company or individual.                                                                                                                                                                                                     |
 | `construction_date` | string  | no       | ISO 8601 calendar date of well completion (`YYYY-MM-DD`). Date-only by design — time of day for construction completion is not meaningful at the precision the well registry cares about. Interpreted as the local civil date at the well site. |
@@ -135,6 +137,13 @@ Each minor revision of this spec MUST include a "Deprecations" subsection in its
 | `location` | `Location`                | no       | Geographic position and elevation. See § location.                           |
 | `profiles` | string[]                  | no       | Array of JSON Schema URLs declaring conformance to profiles. See § profiles. |
 
+### v2.1 additions
+
+| Field          | Type            | Required | Description                                                      |
+| -------------- | --------------- | -------- | ---------------------------------------------------------------- |
+| `well_purpose` | string[]        | no       | Intended use(s) of the well. See § well_purpose.                 |
+| `centralizers` | `Centralizer[]` | no       | Casing/screen centralizers. See object-schemas.md § Centralizer. |
+
 ---
 
 ## Datetime Conventions
@@ -162,18 +171,37 @@ When two events share the same instant, the optional `sequence` integer breaks t
 
 ## `well_type` — Recommended values
 
-The `well_type` field accepts any string. The values below are the recommended vocabulary for interoperability. Tools should treat unrecognized values gracefully.
+The `well_type` field accepts any string and describes the well's **construction method**. The values below are the recommended vocabulary for interoperability. Tools should treat unrecognized values gracefully.
 
 | Value                  | Portuguese (BR)         | Description                                    |
 | ---------------------- | ----------------------- | ---------------------------------------------- |
 | `tubular`              | Tubular                 | Conventional rotary or percussion drilled well |
-| `artesian`             | Artesiano               | Free-flowing artesian well                     |
 | `hand_dug`             | Cacimba / poço escavado | Manually excavated well or cistern             |
 | `horizontal`           | Horizontal              | Horizontal or sub-horizontal well              |
 | `infiltration_gallery` | Galeria de infiltração  | Horizontal subsurface infiltration gallery     |
+| `artesian`             | Artesiano               | **Deprecated in v2.1** — see below             |
 
 Non-canonical values SHOULD use the `x-` prefix (e.g. `x-radial_collector`).
 
+**`artesian` (deprecated in v2.1, removal in v3).** Artesianism is a hydraulic condition, not a construction method: an artesian well is usually a `tubular` well. A flowing artesian condition is recorded as a `hydrodynamic_events` entry whose `static_level` is negative (see § Level sign convention), and applications derive the label from it. Parsers MUST continue to accept `well_type: "artesian"` and MUST NOT rewrite it. Authoring tools SHOULD offer to migrate it to the actual construction method on edit.
+
+---
+
+## `well_purpose` — Recommended values _(since v2.1)_
+
+`well_purpose` is an optional array of strings giving the well's current intended use(s). A well may have more than one purpose (e.g. `["production", "monitoring"]`). Changes of use over time belong in `history_logs` (category `change_of_use`). Non-canonical values SHOULD use the `x-` prefix.
+
+| Value                   | Portuguese (BR)                 | Description                                                      |
+| ----------------------- | ------------------------------- | ---------------------------------------------------------------- |
+| `production`            | Produção / captação             | Water supply abstraction                                         |
+| `monitoring`            | Poço de monitoramento           | Groundwater level and/or quality monitoring                      |
+| `piezometer`            | Piezômetro                      | Measures hydraulic head at a discrete depth interval             |
+| `water_level_indicator` | INA — indicador de nível d'água | Open standpipe for water table readings (typically geotechnical) |
+| `observation`           | Poço de observação              | Observation well for aquifer tests on a nearby pumping well      |
+| `exploration`           | Pesquisa / exploratório         | Investigation or test well                                       |
+| `injection`             | Injeção / recarga               | Managed aquifer recharge or injection                            |
+| `dewatering`            | Rebaixamento                    | Construction or mining dewatering                                |
+
 ---
 
 ## `well_id`
@@ -298,6 +326,7 @@ UCUM is the **Unified Code for Units of Measure**, the international machine-par
 - `well_screen[].from`, `well_screen[].to`
 - `surface_case[].from`, `surface_case[].to`
 - `hole_fill[].from`, `hole_fill[].to`
+- `centralizers[].from`, `centralizers[].to`, `centralizers[].spacing`
 - `cement_pad.width`, `cement_pad.length`, `cement_pad.thickness`
 - `lithology[].from`, `lithology[].to`
 - `fractures[].depth`, `fractures[].depth_precision`
@@ -318,6 +347,7 @@ UCUM is the **Unified Code for Units of Measure**, the international machine-par
 - `well_screen[].diameter`, `well_screen[].screen_slot`
 - `surface_case[].diameter`
 - `hole_fill[].diameter`
+- `centralizers[].diameter`
 
 **Cubic meter per hour (`m3/h`)** — all volumetric flow rates:
 
@@ -356,6 +386,10 @@ UCUM is the **Unified Code for Units of Measure**, the international machine-par
 - `aquifer_analysis[].specific_capacity` (derived ratio in m³/h per m, i.e. `m2/h`)
 - Lithology `color` (CSS hex string)
 
+### Level sign convention
+
+Depths are measured from ground level (0) and increase downward. Water levels above ground level are therefore **negative**. This applies to `static_level`, `LevelReading.depth`, and `aquifer_analysis[].static_level` / `dynamic_level`. A negative static level is how a flowing artesian condition is recorded (see § `well_type`). This convention was implicit in v2.0 and is made explicit in v2.1 without changing semantics.
+
 ### Diameter and the as-built convention
 
 Diameters in casing, screens, surface case, and hole fill are stored as the **as-built outer diameter in millimeters**, not as nominal manufacturer designations. A casing sold as "6 inch" with a real outer diameter of 168.3 mm is recorded as `168.3`, not `152.4` (the literal conversion of 6 inches to mm). Nominal-to-actual mapping for common pipe and screen sizes is a market convention handled by applications — typically by the converter or input form — not by the file format.

package/docs/spec/v2/interoperability.md

@@ -1,4 +1,4 @@
-# `.well` File Format Specification — Version 2.0: Interoperability
+# `.well` File Format Specification — Version 2.1: Interoperability
 
 **See also:** [overview.md](./overview.md) · [format-reference.md](./format-reference.md) · [object-schemas.md](./object-schemas.md)
 
@@ -57,7 +57,7 @@ Adds mappings for `lithology`, `fractures`, `caves`, `texture`, `texture.code`,
 
 **Phase 4 — Hydrodynamic & analysis (v2.1)**
 
-Adds mappings for `hydrodynamic_events`, `aquifer_analysis`, `history_logs`, and supporting types (`PumpingStep`, `LevelReading`, `RecoveryPhase`, `Attachment`). Maps event readings to O&M's `OM_Observation` pattern and time-series to TimeseriesML where alignment is verified. This phase ships alongside the v2.1 spec revision.
+Adds mappings for `well_purpose`, `centralizers`, `hydrodynamic_events`, `aquifer_analysis`, `history_logs`, and supporting types (`PumpingStep`, `LevelReading`, `RecoveryPhase`, `Attachment`). Maps event readings to O&M's `OM_Observation` pattern and time-series to TimeseriesML where alignment is verified. This phase ships alongside the v2.1 spec revision.
 
 ### Versioning and stability
 
@@ -127,6 +127,8 @@ The mapping below is **informative, not normative**. Class names in italics are
 | `reduction[]`               | GWML2-WellConstruction | No direct equivalent — casing transition                           |
 | `hole_fill[]`               | GWML2-WellConstruction | Annular fill / gravel pack / seal (?)                              |
 | `cement_pad`                | GWML2-WellConstruction | No direct equivalent — wellhead furniture                          |
+| `centralizers[]`            | GWML2-WellConstruction | No verified equivalent — casing accessory (?)                      |
+| `well_purpose[]`            | GWML2-Well             | `GW_Well` purpose / use property (?)                               |
 | `lithology[]`               | GWML2-Well             | _`GW_GeologyLogCoverage`_ (realizes `CV_DiscreteCoverage`)         |
 | `lithology[].geologic_unit` | GWML2-Main             | _`GW_HydrogeologicalUnit`_ (specializes GeoSciML `GeologicUnit`)   |
 | `fractures[]`               | GWML2-Well             | Fracture log interval (?)                                          |

package/docs/spec/v2/object-schemas.md

@@ -1,4 +1,4 @@
-# `.well` File Format Specification — Version 2.0: Object Schemas
+# `.well` File Format Specification — Version 2.1: Object Schemas
 
 **See also:** [overview.md](./overview.md) · [format-reference.md](./format-reference.md) · [interoperability.md](./interoperability.md)
 
@@ -92,6 +92,26 @@ Material placed in the annular space between casing and borehole wall.
 
 ---
 
+### `Centralizer` — `centralizers[]` _(since v2.1)_
+
+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.
+
+| Field         | Type   | Required | Description                                                                                                   |
+| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------- |
+| `from`        | number | yes      | Start depth in meters (depth of the first centralizer).                                                       |
+| `to`          | number | yes      | End depth in meters (depth of the last centralizer). `from === to` denotes a single centralizer.              |
+| `spacing`     | number | no       | Spacing between consecutive centralizers in meters. Must be positive. Omit when the spacing is unknown.       |
+| `type`        | string | yes      | Centralizer type. Recommended: `spring_bow`, `rigid`, `semi_rigid`, `polymer`. Non-canonical values use `x-`. |
+| `diameter`    | number | no       | As-built outer diameter in millimeters.                                                                       |
+| `description` | string | no       | Free-text description (e.g. material, manufacturer).                                                          |
+
+- The array is **optional**. v2.0 documents without it remain valid.
+- Individual positions are derived from `from`, `to`, and `spacing` (`from`, `from + spacing`, … up to `to`). The count is derived and MUST NOT be stored.
+- Each entry SHOULD fall within a `well_case` or `well_screen` interval. Validators MUST NOT reject documents that violate this.
+- Centralizers do not contribute to the calculated well depth.
+
+---
+
 ### `CementPad` — `cement_pad`
 
 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
 
 ### `spot_measurement`
 
-| Field                    | Type            | Required | Description                                                                                                                               |
-| ------------------------ | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `static_level`           | number          | yes      | Depth to water surface from ground level, in meters.                                                                                      |
-| `static_level_precision` | number          | no       | One-sigma precision of `static_level`.                                                                                                    |
-| `measurement_method`     | string          | no       | Recommended: `electric_probe`, `pressure_transducer`, `air_line`, `tape`.                                                                 |
-| `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. |
-| `recovery`               | `RecoveryPhase` | no       | Recovery after the optional pumping step.                                                                                                 |
+| Field                    | Type            | Required | Description                                                                                                                                   |
+| ------------------------ | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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. |
+| `static_level_precision` | number          | no       | One-sigma precision of `static_level`.                                                                                                        |
+| `measurement_method`     | string          | no       | Recommended: `electric_probe`, `pressure_transducer`, `air_line`, `tape`.                                                                     |
+| `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.     |
+| `recovery`               | `RecoveryPhase` | no       | Recovery after the optional pumping step.                                                                                                     |
 
 ---
 
@@ -393,12 +413,13 @@ These timestamps may differ substantially: a maintenance intervention `datetime`
 
 ### Categories
 
-| `category`    | Portuguese (BR) | Description                                                                                                                                       |
-| ------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `maintenance` | Manutenção      | Physical intervention: pump replacement, casing repair, cleaning, redevelopment.                                                                  |
-| `inspection`  | Inspeção        | Site visit without physical alteration: visual survey, camera inspection, sample collection.                                                      |
-| `incident`    | Incidente       | Unplanned event: partial collapse, contamination, prolonged drought, vandalism.                                                                   |
-| `event`       | Evento          | Generic milestone: construction completion, commissioning, deactivation, reactivation, ownership transfer, rehabilitation, data-integrity repair. |
+| `category`      | Portuguese (BR) | Description                                                                                                                                       |
+| --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `maintenance`   | Manutenção      | Physical intervention: pump replacement, casing repair, cleaning, redevelopment.                                                                  |
+| `inspection`    | Inspeção        | Site visit without physical alteration: visual survey, camera inspection, sample collection.                                                      |
+| `incident`      | Incidente       | Unplanned event: partial collapse, contamination, prolonged drought, vandalism.                                                                   |
+| `event`         | Evento          | Generic milestone: construction completion, commissioning, deactivation, reactivation, ownership transfer, rehabilitation, data-integrity repair. |
+| `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.           |
 
 Vocabulary is open. Non-canonical values SHOULD use the `x-` prefix.
 
@@ -449,6 +470,7 @@ The `uri` field is a reference, not a guarantee. URLs may become unreachable ove
   "@context": "https://welldot.org/context/v2.jsonld",
   "version": 2,
   "well_type": "tubular",
+  "well_purpose": ["production"],
   "name": "Poço PP-01",
   "well_driller": "Perfuradora XYZ",
   "construction_date": "2006-03-10",
@@ -503,6 +525,15 @@ The `uri` field is a reference, not a guarantee. URLs may become unreachable ove
       "description": "Cimento"
     }
   ],
+  "centralizers": [
+    {
+      "from": 6,
+      "to": 54,
+      "spacing": 12,
+      "type": "spring_bow",
+      "diameter": 245
+    }
+  ],
   "cement_pad": {
     "type": "square",
     "width": 1.0,

package/docs/spec/v2/overview.md

@@ -1,11 +1,38 @@
-# `.well` File Format Specification — Version 2.0: Overview
+# `.well` File Format Specification — Version 2.1: Overview
 
-**Version:** 2.0 **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:** Ratified — shipped in `@welldot/core` v0.2.0
+**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
 
 **See also:** [format-reference.md](./format-reference.md) · [object-schemas.md](./object-schemas.md) · [interoperability.md](./interoperability.md)
 
 ---
 
+## Changes in v2.1
+
+v2.1 is an additive minor revision. Every valid v2.0 document is a valid v2.1 document, and documents keep declaring `"version": 2`.
+
+```
+v2.1 additions:
+- well_purpose (optional string[]): intended use(s) of the well —
+  production, monitoring, piezometer, water_level_indicator (INA),
+  observation, exploration, injection, dewatering
+- centralizers (optional Centralizer[]): casing/screen centralizers
+  as depth interval + spacing
+- history_logs category `change_of_use`
+
+v2.1 clarifications:
+- well_type describes the construction method only
+- Level sign convention: water levels above ground are negative
+  (made explicit; already implied by "ground level as zero")
+```
+
+### Deprecations
+
+| Deprecated              | Replacement                                                                                               | Removal |
+| ----------------------- | --------------------------------------------------------------------------------------------------------- | ------- |
+| `well_type: "artesian"` | Construction method in `well_type` (usually `tubular`) + negative `static_level` in `hydrodynamic_events` | v3      |
+
+---
+
 ## Changes from v1
 
 ```
@@ -60,7 +87,7 @@ The `.well` format is an open standard for representing water well data. It is d
 - **Self-contained** — a single file encodes the complete record of one well.
 - **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.
 - **CRS is declared, not assumed** — geographic coordinates are accompanied by an explicit coordinate reference system declaration. The default is WGS84 (`EPSG:4326`).
-- **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`.
+- **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.
 - **Geographic north** — all azimuth values are referenced to geographic north.
 - **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.
 - **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
 
 ---
 
-_`.well` Format Specification v2.0 — Ratified_
+_`.well` Format Specification v2.1_

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@welldot/core",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "type": "module",
   "description": "TypeScript types, Zod validators, and serialization utilities for the .well open format — a JSON standard for water well data.",
   "keywords": [