@welldot/core 0.3.0 → 0.4.0-next.20261015.d7c7365

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

@@ -1,6 +1,6 @@
-# `.well` File Format Specification — Version 2.1: Format Reference
+# `.well` File Format Specification — Version 2.3: Format Reference
 
-**See also:** [overview.md](./overview.md) · [object-schemas.md](./object-schemas.md) · [interoperability.md](./interoperability.md)
+**See also:** [overview.md](./overview.md) · [object-schemas.md](./object-schemas.md) · [interoperability.md](./interoperability.md) · [water-quality.md](./water-quality.md)
 
 ---
 
@@ -16,6 +16,7 @@
 
   "name": "...",
   "well_type": "...",
+  "well_purpose": [ ... ],
   "well_driller": "...",
   "construction_date": "YYYY-MM-DD",
   "obs": "...",
@@ -28,6 +29,7 @@
   "well_screen": [ ... ],
   "surface_case": [ ... ],
   "hole_fill": [ ... ],
+  "centralizers": [ ... ],
   "cement_pad": { ... },
 
   "lithology": [ ... ],
@@ -36,7 +38,16 @@
 
   "hydrodynamic_events": [ ... ],
   "aquifer_analysis": [ ... ],
-  "history_logs": [ ... ]
+  "history_logs": [ ... ],
+
+  "attachments": [ ... ],
+  "pump_installations": [ ... ],
+  "permits": [ ... ],
+  "meters": [ ... ],
+  "production": [ ... ],
+  "operating_regime": [ ... ],
+
+  "water_samples": [ ... ]
 }
 ```
 
@@ -49,7 +60,9 @@
 | `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.
+Minor revisions (`2.1`, `2.3`, …) are additive and do not change the `version` integer: a v2.3 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.
+
+The same rule applies to v2.3: a v2.0 or v2.1 parser reading a v2.3 document sees `attachments`, `pump_installations`, `permits`, `meters`, `production`, `operating_regime`, `water_samples`, `hydrodynamic_events[].corrects`, the `history_logs` data links (`hydrodynamic_event_ids`, `sample_ids`) and category-specific fields (`maintenance`, `status_change`) and the nested `attachments` arrays as unrecognized members. It MUST preserve them, MUST NOT reject the file, and SHOULD emit a warning. Such a parser does not know `corrects`, so it may still count a retracted event; this is the expected degradation.
 
 ### Parser version handling
 
@@ -60,7 +73,7 @@ The `version` field is an integer and must always be present.
 - Either parser encountering an unrecognized integer version MUST reject the file with a clear error.
 - A file without a `version` field SHOULD be rejected. Parsers MAY emit a warning and attempt to read the file as v1 if all required v1 fields are present and no v2-specific blocks are detected, but this fallback behavior is implementation-specific and not guaranteed by the spec.
 
-Files with `version: 1` MUST NOT contain any v2-only blocks (`hydrodynamic_events`, `aquifer_analysis`, `history_logs`, `profiles`, `well_id` as array, `location` object, `@context`). A v1 file containing such fields is malformed.
+Files with `version: 1` MUST NOT contain any v2-only blocks (`hydrodynamic_events`, `aquifer_analysis`, `history_logs`, `attachments`, `pump_installations`, `permits`, `meters`, `production`, `operating_regime`, `water_samples`, `profiles`, `well_id` as array, `location` object, `@context`). A v1 file containing such fields is malformed.
 
 ---
 
@@ -144,13 +157,54 @@ Each minor revision of this spec MUST include a "Deprecations" subsection in its
 | `well_purpose` | string[]        | no       | Intended use(s) of the well. See § well_purpose.                 |
 | `centralizers` | `Centralizer[]` | no       | Casing/screen centralizers. See object-schemas.md § Centralizer. |
 
+### v2.3 additions
+
+| Field                | Type                 | Required | Description                                                                                                                           |
+| -------------------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `attachments`        | `Attachment[]`       | no       | Documents about the well as a whole, not tied to any record. See object-schemas.md § Attachment.                                      |
+| `pump_installations` | `PumpInstallation[]` | no       | Pump installation history (installation block). See object-schemas.md § `pump_installations[]`.                                       |
+| `permits`            | `Permit[]`           | no       | Legal instruments governing abstraction (mutable record block). See object-schemas.md § `permits[]`.                                  |
+| `meters`             | `Meter[]`            | no       | Totalizer (hidrômetro) installation history (installation block). See object-schemas.md § `meters[]`.                                 |
+| `production`         | `ProductionEntry[]`  | no       | Append-only ledger of meter readings and declared volumes (ledger block). See object-schemas.md § `production[]`.                     |
+| `operating_regime`   | `OperatingRegime[]`  | no       | Declared operating regimes, each in force from `effective_from` (mutable record block). See object-schemas.md § `operating_regime[]`. |
+| `water_samples`      | `WaterSample[]`      | no       | Water samples and their field and laboratory results (ledger block). See water-quality.md.                                            |
+
+### Block kinds _(since v2.3)_
+
+Every top-level array is one of three kinds. The kind decides how records are corrected.
+
+| Kind           | Blocks                                               | Correction                                                                               | Edit tracking                           |
+| -------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------- |
+| Ledger         | `hydrodynamic_events`, `production`, `water_samples` | Append a new entry with `corrects` pointing to the retracted entry. Never edit in place. | None needed; the ledger is the history. |
+| Mutable record | `history_logs`, `permits`, `operating_regime`        | Edit in place.                                                                           | `updated_at` (instant) on the record.   |
+| Installation   | `pump_installations`, `meters`                       | Edit in place.                                                                           | `updated_at` (instant) on the record.   |
+
+Constructive and geologic arrays describe the well as built and are edited in place. `aquifer_analysis` entries are interpretations: a new interpretation is a new entry, and earlier ones coexist.
+
+**Ledger corrections.** A ledger entry referenced by any `corrects` field is excluded from every derivation but stays in the file. Chains are allowed (C corrects B, which corrected A); only the last uncorrected entry counts. A `corrects` cycle is malformed and emits a warning. An `aquifer_analysis` whose `source_event_ids` or `static_level_source_id` points to a retracted event emits a warning naming both ids.
+
+**Installation pattern.** Installation blocks describe equipment present in the well for a period, with `installed_at` (required) and `removed_at` (absent means currently installed).
+
+- `removed_at` earlier than or equal to `installed_at` is malformed and emits a warning.
+- Each entry is one installation, not one piece of equipment. A unit pulled and reinstalled gets a new entry with the same `serial`.
+- Overlapping open installations in the same block emit a warning, not an error. Standby pumps and secondary meters exist.
+
+### Naming rules _(since v2.3)_
+
+- No unit in a field name. Units are bound by the field-to-unit table (§ Units).
+- `flow_rate` is the canonical name for a volumetric rate; nameplate values use the `rated_` prefix (`rated_flow_rate`, `rated_head`, `rated_power`).
+- `from` / `to` are reserved for depth intervals in meters. Time intervals use `period_start` / `period_end`.
+- References to another array end in `_id` (single) or `_ids` (array), plus the two relationship fields `corrects` and `supersedes`.
+
+**`supersedes` vs `corrects`.** `supersedes` expresses legal succession between two valid permits and appears only on `permits`. It is not a correction mechanism: `corrects` retracts ledger entries.
+
 ---
 
 ## Datetime Conventions
 
 The `.well` format distinguishes two kinds of temporal values:
 
-**Calendar dates** — `YYYY-MM-DD`, no time, no offset. Used for `construction_date` only. Interpreted as the local civil date at the well site. The well site's timezone is not stored separately; calendar dates are sortable lexicographically and applications MUST NOT attempt to derive an instant from them.
+**Calendar dates** — `YYYY-MM-DD`, no time, no offset. Used for `construction_date` and, since v2.3, for legal documents: `permits[].issued_at`, `valid_from`, `valid_until`, `renewal_requested_at`; `permits[].conditions[].first_due`, `last_due`; `permits[].conditions[].fulfillments[].due_date`; and `permits[].history[].date`, `due_date`. Interpreted as the local civil date at the well site. The well site's timezone is not stored separately; calendar dates are sortable lexicographically and applications MUST NOT attempt to derive an instant from them.
 
 **Instants** — RFC 3339 datetime strings with a mandatory UTC offset (e.g. `2006-03-14T08:00:00-03:00` or `2006-03-14T11:00:00Z`). Used for all event, analysis, and log timestamps:
 
@@ -158,6 +212,28 @@ The `.well` format distinguishes two kinds of temporal values:
 - `aquifer_analysis[].datetime`
 - `history_logs[].datetime`
 - `history_logs[].updated_at`
+- `pump_installations[].installed_at`, `removed_at`, `updated_at` _(since v2.3)_
+- `permits[].updated_at`, `permits[].history[].updated_at`, `permits[].conditions[].fulfillments[].datetime`, `updated_at` _(since v2.3)_
+- `meters[].installed_at`, `removed_at`, `updated_at` _(since v2.3)_
+- `production[].datetime` (`meter_reading`); `production[].period_start`, `period_end` (`estimated_volume`) _(since v2.3)_
+- `operating_regime[].effective_from`, `updated_at` _(since v2.3)_
+- `water_samples[].datetime`, `laboratory.received_at`, `results[].analyzed_at`, `results[].validation.validated_at` _(since v2.3)_
+
+Validity and deadline checks compare calendar dates, never UTC instants. When an instant must be compared with a calendar date — for example a condition fulfillment's `datetime` against its `due_date` — the instant's local date is the date part of the string, in the offset it carries. Producers SHOULD therefore write such instants in the well site's local offset.
+
+Relative deadlines and recurrences are ISO 8601 date durations (`P90D`, `P6M`, `P1Y6M`); see object-schemas.md § Date duration.
+
+### Instants known only by date _(since v2.3)_
+
+Laboratory reports often give only the date of receipt or analysis. Such an instant is written at 00:00 local time at the well site, and a sibling field named after it with the `_resolution` suffix is set to `"day"`:
+
+```json
+{ "analyzed_at": "2026-09-17T00:00:00-03:00", "analyzed_at_resolution": "day" }
+```
+
+- Consumers MUST ignore the time of day when `_resolution` is `day`. Ordering, holding-time and deadline calculations on that field use day resolution.
+- `day` is the only allowed value; any other value is malformed. An absent `_resolution` means the instant is exact.
+- In v2.3 the convention applies to `water_samples[].laboratory.received_at` and `water_samples[].results[].analyzed_at`. It is the candidate general convention for any instant known only by its date.
 
 A datetime without an offset (naked `YYYY-MM-DDTHH:MM:SS`) is malformed and parsers MUST reject it. Time zone abbreviations (`EST`, `BRT`) are not RFC 3339 and MUST NOT be used.
 
@@ -169,6 +245,12 @@ When two events share the same instant, the optional `sequence` integer breaks t
 
 ---
 
+## Recommended vocabularies
+
+Many string fields are **open**: they accept any value, but recommend a vocabulary for interoperability. The sections below list each one. Non-canonical values SHOULD use the `x-` prefix, and tools MUST preserve unrecognized values and display them as-is.
+
+Every recommended vocabulary is also published as data by `@welldot/core` (e.g. `PERMIT_TYPES`, `CONSTRUCTION_MATERIALS`, `SAMPLE_TYPES`), each entry carrying its `value` and display labels keyed by BCP 47 language tag (at least `en` and `pt`). The field types use the `OpenVocab<T>` pattern (`T | (string & {})`): the recommended values are typed while any other string stays valid. The Portuguese column in the tables below may be more descriptive than the short display label.
+
 ## `well_type` — Recommended values
 
 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.
@@ -189,7 +271,7 @@ Non-canonical values SHOULD use the `x-` prefix (e.g. `x-radial_collector`).
 
 ## `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.
+`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 `event`). Non-canonical values SHOULD use the `x-` prefix.
 
 | Value                   | Portuguese (BR)                 | Description                                                      |
 | ----------------------- | ------------------------------- | ---------------------------------------------------------------- |
@@ -204,6 +286,284 @@ Non-canonical values SHOULD use the `x-` prefix (e.g. `x-radial_collector`).
 
 ---
 
+## `bore_hole[].drilling_method` — Recommended values _(since v2.3)_
+
+| Value        | English    | Portuguese (BR)    |
+| ------------ | ---------- | ------------------ |
+| `rotary`     | Rotary     | Rotativo           |
+| `percussion` | Percussion | Percussão          |
+| `cable_tool` | Cable tool | Percussão a cabo   |
+| `auger`      | Auger      | Trado              |
+| `air_hammer` | Air hammer | Martelo pneumático |
+
+Non-canonical values SHOULD use the `x-` prefix.
+
+## Construction materials — Recommended values _(since v2.3)_
+
+Shared by `well_case[].type`, `well_screen[].type`, `reduction[].type` and `pump_installations[].riser_material`.
+
+| Value               | English           | Portuguese (BR) |
+| ------------------- | ----------------- | --------------- |
+| `pvc`               | PVC               | PVC             |
+| `geomechanical_pvc` | Geomechanical PVC | PVC geomecânico |
+| `carbon_steel`      | Carbon steel      | Aço carbono     |
+| `galvanized_steel`  | Galvanized steel  | Aço galvanizado |
+| `stainless_steel`   | Stainless steel   | Aço inox        |
+| `fiberglass`        | Fiberglass        | Fibra de vidro  |
+
+Non-canonical values SHOULD use the `x-` prefix.
+
+## `well_screen[].slot_type` — Recommended values _(since v2.3)_
+
+The screen design, independent of its material (`well_screen[].type`).
+
+| Value             | English         | Portuguese (BR)           |
+| ----------------- | --------------- | ------------------------- |
+| `continuous_slot` | Continuous slot | Espiralado (tipo Johnson) |
+| `slotted`         | Slotted         | Ranhurado                 |
+| `bridge_slot`     | Bridge slot     | Tipo ponte                |
+| `louver`          | Louver          | Veneziana                 |
+| `perforated`      | Perforated      | Perfurado                 |
+| `nold`            | Nold type       | Tipo Nold                 |
+
+`continuous_slot` is the wire-wrapped (wire-wound) screen. `nold` is the steel screen sold under that trade designation (_filtro tipo Nold_). Non-canonical values SHOULD use the `x-` prefix.
+
+## `centralizers[].type` — Recommended values _(since v2.1)_
+
+| Value              | English          | Portuguese (BR)   |
+| ------------------ | ---------------- | ----------------- |
+| `spring_bow`       | Spring bow       | Mola (spring bow) |
+| `rigid`            | Rigid            | Rígido            |
+| `semi_rigid`       | Semi-rigid       | Semirrígido       |
+| `polymer`          | Polymer          | Polimérico        |
+| `carbon_steel`     | Carbon steel     | Aço carbono       |
+| `galvanized_steel` | Galvanized steel | Aço galvanizado   |
+| `stainless_steel`  | Stainless steel  | Aço inox          |
+
+The steel values name rigid centralizers by their material. Non-canonical values SHOULD use the `x-` prefix.
+
+## `cement_pad.type` — Recommended values _(since v2.3)_
+
+| Value                 | English             | Portuguese (BR) |
+| --------------------- | ------------------- | --------------- |
+| `concrete`            | Concrete            | Concreto        |
+| `reinforced_concrete` | Reinforced concrete | Concreto armado |
+| `cement`              | Cement              | Cimento         |
+| `mortar`              | Mortar              | Argamassa       |
+
+`type` describes the pad material; other free text (e.g. a shape) remains valid.
+
+---
+
+## `pump_installations[].type` — Recommended values _(since v2.3)_
+
+| Value                | Portuguese (BR)        | Description                                       |
+| -------------------- | ---------------------- | ------------------------------------------------- |
+| `submersible`        | Bomba submersa         | Electric submersible pump.                        |
+| `vertical_turbine`   | Bomba de eixo vertical | Surface motor with line shaft.                    |
+| `jet`                | Bomba injetora         | Surface jet pump.                                 |
+| `progressive_cavity` | Bomba helicoidal       | Progressive cavity pump, common with solar power. |
+| `hand_pump`          | Bomba manual           |                                                   |
+| `compressor_airlift` | Compressor (air-lift)  | Permanent airlift production.                     |
+
+Solar is a `power_source`, never a `type`. Non-canonical values SHOULD use the `x-` prefix.
+
+## `pump_installations[].power_source` — Recommended values _(since v2.3)_
+
+| Value    | Portuguese (BR)      |
+| -------- | -------------------- |
+| `grid`   | Rede elétrica        |
+| `solar`  | Solar (fotovoltaico) |
+| `diesel` | Gerador a diesel     |
+| `hybrid` | Híbrido              |
+
+## `permits[].type` — Recommended values _(since v2.3)_
+
+| Value                | Portuguese (BR)                        | Description                         |
+| -------------------- | -------------------------------------- | ----------------------------------- |
+| `abstraction_permit` | Outorga de direito de uso              | Grant to abstract groundwater.      |
+| `preliminary_permit` | Outorga prévia / declaração de reserva | Permission before drilling.         |
+| `exemption`          | Dispensa / uso insignificante          | Formal exemption for small users.   |
+| `registration`       | Cadastro (e.g. CNARH)                  | Registration without a grant.       |
+| `dewatering_permit`  | Outorga para rebaixamento              | Mining and construction dewatering. |
+| `drilling_permit`    | Autorização de perfuração              | Authorization to drill the well.    |
+
+`renewal` is not a type: a renewal is a new permit of the same type whose `supersedes` points to the previous one. Non-canonical values SHOULD use the `x-` prefix.
+
+## `permits[].water_use` — Recommended values _(since v2.3)_
+
+| Value          | Portuguese (BR)                        |
+| -------------- | -------------------------------------- |
+| `human_supply` | Abastecimento público / consumo humano |
+| `industrial`   | Industrial                             |
+| `mining`       | Mineração                              |
+| `irrigation`   | Irrigação                              |
+| `livestock`    | Dessedentação animal                   |
+| `commercial`   | Comercial / serviços                   |
+
+`water_use` describes what the abstracted water is for; `well_purpose` describes the well's role.
+
+## `permits[].conditions[].category` — Recommended values _(since v2.3)_
+
+| Value                    | Portuguese (BR)            | Covers                                                                     |
+| ------------------------ | -------------------------- | -------------------------------------------------------------------------- |
+| `monitoring`             | Monitoramento              | Water level, flow, abstracted volume and water quality monitoring/sampling |
+| `reporting`              | Relatórios e declarações   | Periodic reports and volume/flow declarations submitted to the authority   |
+| `equipment_installation` | Instalação de equipamentos | Meters (hidrômetro), level gauges, sampling taps, telemetry                |
+| `well_protection`        | Proteção do poço           | Sanitary slab, seal, protection perimeter, wellhead closure                |
+| `environmental`          | Ambiental                  | Environmental measures, compensation, licensing of the activity            |
+| `legal`                  | Legal / administrativo     | Renewal request, fees, registrations, document submissions                 |
+
+Non-canonical values SHOULD use the `x-` prefix.
+
+## `permits[].history[].type` — Recommended values _(since v2.3)_
+
+| Value          | Portuguese (BR)                  |
+| -------------- | -------------------------------- |
+| `filing`       | Protocolo / requerimento         |
+| `process`      | Andamento do processo / despacho |
+| `notification` | Notificação / ofício             |
+| `fee`          | Taxa / emolumento                |
+| `inspection`   | Vistoria                         |
+| `decision`     | Decisão / publicação             |
+| `renewal`      | Renovação                        |
+
+Non-canonical values SHOULD use the `x-` prefix. The administrative `status` of a permit is a closed vocabulary; see object-schemas.md § `permits[]` — Administrative status.
+
+## `meters[].type` — Recommended values _(since v2.3)_
+
+| Value             | Portuguese (BR)         |
+| ----------------- | ----------------------- |
+| `mechanical`      | Hidrômetro mecânico     |
+| `electromagnetic` | Medidor eletromagnético |
+| `ultrasonic`      | Medidor ultrassônico    |
+
+Non-canonical values SHOULD use the `x-` prefix.
+
+## `production[]` — Recommended values _(since v2.3)_
+
+**`type`** — the entry discriminator: `meter_reading` (a totalizer register value) or `estimated_volume` (a volume estimated for a period, without a meter). Non-canonical entry types SHOULD use the `x-` prefix; parsers preserve them and exclude them from volume derivations.
+
+**`source`** (`meter_reading`):
+
+| Value       | Portuguese (BR) |
+| ----------- | --------------- |
+| `manual`    | Leitura manual  |
+| `telemetry` | Telemetria      |
+
+**`method`** (`estimated_volume`) — the basis of the estimate. Descriptive only: it never changes how the volume is counted.
+
+| Value            | Portuguese (BR)           | Description                                                        |
+| ---------------- | ------------------------- | ------------------------------------------------------------------ |
+| `flow_time`      | Vazão × tempo de operação | Flow rate times operating time (hour meter, operating regime).     |
+| `energy`         | Consumo de energia        | Derived from the pump's energy consumption.                        |
+| `user_statement` | Informado pelo usuário    | Stated by the owner or operator, without a documented calculation. |
+
+## `water_samples[]` — Recommended values _(since v2.3)_
+
+Recommended values for `sample_type`, `sampling_method`, `sampling_point.type` and `sampling_point.device` are listed in [water-quality.md](water-quality.md) § Recommended values.
+
+## `hydrodynamic_events[].measurement_method` — Recommended values
+
+Used by `spot_measurement` events.
+
+| Value                 | English             | Portuguese (BR)       |
+| --------------------- | ------------------- | --------------------- |
+| `electric_probe`      | Electric probe      | Sonda elétrica        |
+| `pressure_transducer` | Pressure transducer | Transdutor de pressão |
+| `air_line`            | Air line            | Linha de ar           |
+| `tape`                | Tape                | Trena                 |
+
+Non-canonical values SHOULD use the `x-` prefix.
+
+## `aquifer_analysis[].method` — Recommended values
+
+| Value               | English           | Portuguese (BR) |
+| ------------------- | ----------------- | --------------- |
+| `cooper_jacob`      | Cooper-Jacob      | Cooper-Jacob    |
+| `theis`             | Theis             | Theis           |
+| `neuman`            | Neuman            | Neuman          |
+| `hantush`           | Hantush           | Hantush         |
+| `birsoy_summers`    | Birsoy-Summers    | Birsoy-Summers  |
+| `eden_hazel`        | Eden-Hazel        | Eden-Hazel      |
+| `visual_inspection` | Visual inspection | Inspeção visual |
+
+Non-canonical values SHOULD use the `x-` prefix.
+
+## `history_logs[].category` — Recommended values
+
+| Value           | Portuguese (BR)     | Category-specific fields                                              |
+| --------------- | ------------------- | --------------------------------------------------------------------- |
+| `maintenance`   | Manutenção          | `maintenance_type`, `pump_installation_id`, `meter_id` _(since v2.3)_ |
+| `inspection`    | Inspeção            | —                                                                     |
+| `incident`      | Incidente           | —                                                                     |
+| `event`         | Evento              | —                                                                     |
+| `status_change` | Mudança de situação | `status` _(since v2.3)_                                               |
+
+Descriptions are in object-schemas.md § `history_logs[]`. Category-specific fields MUST be absent on entries of other categories; their presence emits a warning. Non-canonical values SHOULD use the `x-` prefix.
+
+## `history_logs[].severity` — Recommended values
+
+| Value      | English  | Portuguese (BR) |
+| ---------- | -------- | --------------- |
+| `low`      | Low      | Baixa           |
+| `medium`   | Medium   | Média           |
+| `high`     | High     | Alta            |
+| `critical` | Critical | Crítica         |
+
+Non-canonical values SHOULD use the `x-` prefix.
+
+## `history_logs[].maintenance_type` — Recommended values _(since v2.3)_
+
+| Value               | Portuguese (BR)             |
+| ------------------- | --------------------------- |
+| `inspection`        | Inspeção                    |
+| `cleaning`          | Limpeza                     |
+| `redevelopment`     | Redesenvolvimento           |
+| `disinfection`      | Desinfecção                 |
+| `pump_service`      | Manutenção da bomba         |
+| `meter_calibration` | Aferição do hidrômetro      |
+| `video_inspection`  | Filmagem / perfilagem ótica |
+| `level_measurement` | Medição de nível            |
+| `pump_test`         | Teste de bombeamento        |
+| `water_sampling`    | Coleta de água              |
+
+Non-canonical values SHOULD use the `x-` prefix.
+
+## `history_logs[].status` — Allowed values _(since v2.3)_
+
+Used by entries of category `status_change`. This is a **closed vocabulary**: `status` MUST be one of the five values below. Any other value, including an `x-` value, is a schema error and the file is rejected.
+
+| Value            | Portuguese (BR)        | Semantics                               |
+| ---------------- | ---------------------- | --------------------------------------- |
+| `active`         | Ativo / em operação    | Normal operation.                       |
+| `maintenance`    | Em manutenção          | Temporarily out of service for work.    |
+| `inactive`       | Paralisado             | Out of service, recoverable.            |
+| `decommissioned` | Desativado / tamponado | Permanently closed and properly sealed. |
+| `abandoned`      | Abandonado             | Left without proper sealing.            |
+
+The well's current status is the `status` of the `status_change` entry with the latest `datetime`; with no such entry, the status is unknown.
+
+## `Attachment.document_type` — Recommended values _(since v2.3)_
+
+| Value                | Portuguese (BR)                             | Typical location      |
+| -------------------- | ------------------------------------------- | --------------------- |
+| `drilling_report`    | Relatório de perfuração / relatório técnico | Root                  |
+| `as_built_drawing`   | Perfil construtivo as-built                 | Root                  |
+| `registry_record`    | Ficha cadastral (SIAGAS, CNARH)             | Root                  |
+| `photo`              | Fotografia                                  | Any                   |
+| `permit_document`    | Portaria / certificado de outorga           | `permits`             |
+| `condition_evidence` | Comprovante de cumprimento de condicionante | `history_logs`        |
+| `pump_curve`         | Curva da bomba                              | `pump_installations`  |
+| `field_sheet`        | Planilha de campo                           | `hydrodynamic_events` |
+| `test_report`        | Relatório de teste de bombeamento           | `aquifer_analysis`    |
+| `lab_report`         | Laudo laboratorial                          | `water_samples`       |
+| `invoice`            | Nota fiscal                                 | Any                   |
+
+The vocabulary is open; non-canonical values SHOULD use the `x-` prefix.
+
+---
+
 ## `well_id`
 
 Array of authority-scoped identifiers linking the well to external registries. A well may be registered in multiple national, regional, or institutional registries simultaneously.
@@ -299,19 +659,33 @@ All numeric values in a `.well` file are in **SI**. The format does not encode u
 
 ### Canonical units
 
-| Quantity                 | Unit                     | UCUM   | Stored as                                |
-| ------------------------ | ------------------------ | ------ | ---------------------------------------- |
-| Depth, length, elevation | meter                    | `m`    | number                                   |
-| Diameter                 | millimeter               | `mm`   | number                                   |
-| Volumetric flow rate     | cubic meter per hour     | `m3/h` | number                                   |
-| Elapsed time, duration   | minute                   | `min`  | number                                   |
-| Transmissivity           | square meter per second  | `m2/s` | number                                   |
-| Hydraulic conductivity   | meter per second         | `m/s`  | number                                   |
-| Pressure                 | kilopascal               | `kPa`  | number                                   |
-| Angle (azimuth, dip)     | degree                   | `deg`  | number (0–360 for azimuth, 0–90 for dip) |
-| Geographic coordinates   | decimal degree (WGS84)   | `deg`  | number                                   |
-| Calendar date            | ISO 8601                 | —      | string `YYYY-MM-DD`                      |
-| Instant                  | RFC 3339 with UTC offset | —      | string                                   |
+| Quantity                 | Unit                                               | UCUM                                           | Stored as                                |
+| ------------------------ | -------------------------------------------------- | ---------------------------------------------- | ---------------------------------------- |
+| Depth, length, elevation | meter                                              | `m`                                            | number                                   |
+| Diameter                 | millimeter                                         | `mm`                                           | number                                   |
+| Volumetric flow rate     | cubic meter per hour                               | `m3/h`                                         | number                                   |
+| Elapsed time, duration   | minute                                             | `min`                                          | number                                   |
+| Daily operating time     | hour                                               | `h`                                            | number (0–24)                            |
+| Volume                   | cubic meter                                        | `m3`                                           | number                                   |
+| Power                    | kilowatt                                           | `kW`                                           | number                                   |
+| Voltage                  | volt                                               | `V`                                            | number                                   |
+| Cross-sectional area     | square millimeter                                  | `mm2`                                          | number                                   |
+| Mass concentration       | milligram per liter                                | `mg/L`                                         | number _(since v2.3)_                    |
+| Electrical conductivity  | microsiemens per centimeter at 25 °C               | `uS/cm`                                        | number _(since v2.3)_                    |
+| Temperature              | degree Celsius                                     | `Cel`                                          | number _(since v2.3)_                    |
+| Redox potential          | millivolt                                          | `mV`                                           | number _(since v2.3)_                    |
+| Turbidity                | NTU, FNU, FAU, FTU (by parameter code)             | —                                              | number _(since v2.3)_                    |
+| Color                    | Hazen unit (uH = mg Pt-Co/L)                       | —                                              | number _(since v2.3)_                    |
+| Microbiological count    | MPN/100 mL, CFU/100 mL, CFU/mL (by parameter code) | `{MPN}/(100.mL)`, `{CFU}/(100.mL)`, `{CFU}/mL` | number _(since v2.3)_                    |
+| Activity concentration   | becquerel per liter                                | `Bq/L`                                         | number _(since v2.3)_                    |
+| Filter pore size         | micrometer                                         | `um`                                           | number _(since v2.3)_                    |
+| Transmissivity           | square meter per second                            | `m2/s`                                         | number                                   |
+| Hydraulic conductivity   | meter per second                                   | `m/s`                                          | number                                   |
+| Pressure                 | kilopascal                                         | `kPa`                                          | number                                   |
+| Angle (azimuth, dip)     | degree                                             | `deg`                                          | number (0–360 for azimuth, 0–90 for dip) |
+| Geographic coordinates   | decimal degree (WGS84)                             | `deg`                                          | number                                   |
+| Calendar date            | ISO 8601                                           | —                                              | string `YYYY-MM-DD`                      |
+| Instant                  | RFC 3339 with UTC offset                           | —                                              | string                                   |
 
 UCUM is the **Unified Code for Units of Measure**, the international machine-parseable unit standard used by OGC SWE and the scientific community. The UCUM column above documents the canonical encoding of each unit for use in JSON-LD contexts, profile schemas, and downstream interoperability — it is not encoded in `.well` files themselves.
 
@@ -338,6 +712,8 @@ UCUM is the **Unified Code for Units of Measure**, the international machine-par
 - `aquifer_analysis[].dynamic_level`, `dynamic_level_precision`
 - `aquifer_analysis[].aquifer_thickness`
 - `location.elevation`, `location.properties.elevation_precision`
+- `pump_installations[].intake_depth`, `rated_head`, `electrical.cable_length` _(since v2.3)_
+- `water_samples[].sampling_point.depth`, `depth_precision`, `from`, `to` _(since v2.3)_
 
 **Millimeter (`mm`)** — all diameters and slot openings:
 
@@ -348,18 +724,39 @@ UCUM is the **Unified Code for Units of Measure**, the international machine-par
 - `surface_case[].diameter`
 - `hole_fill[].diameter`
 - `centralizers[].diameter`
+- `pump_installations[].riser_diameter` _(since v2.3)_
+- `meters[].nominal_diameter` _(since v2.3)_
 
 **Cubic meter per hour (`m3/h`)** — all volumetric flow rates:
 
 - `PumpingStep.rate`, `rate_precision`
 - `aquifer_analysis[].flow_rate`, `flow_rate_precision`
 - `recovery_only.pumping_rate`
+- `pump_installations[].rated_flow_rate` _(since v2.3)_
+- `permits[].flow_rate`, `permits[].monthly_schedule[].flow_rate` _(since v2.3)_
+- `operating_regime[].flow_rate` _(since v2.3)_
+- `water_samples[].purge.flow_rate` _(since v2.3)_
 
 **Minute (`min`)** — all elapsed times and durations:
 
 - `PumpingStep.duration`
 - `LevelReading.elapsed`
 - `recovery_only.pumping_duration`
+- `water_samples[].purge.duration`, `purge.readings[].elapsed` _(since v2.3)_
+
+**Cubic meter (`m3`)** — volume _(since v2.3)_:
+
+- `permits[].volume_limits[].volume`
+- `meters[].max_reading`
+- `production[].reading` (`meter_reading`), `production[].volume` (`estimated_volume`)
+- `water_samples[].purge.volume`
+
+**Hour (`h`)** — daily operating time _(since v2.3)_:
+
+- `permits[].daily_operating_time`, `permits[].monthly_schedule[].daily_operating_time`
+- `operating_regime[].daily_operating_time`
+
+The minute remains the canonical unit for elapsed time and durations. The hour is bound only to `daily_operating_time`, which regulators always express in hours.
 
 **Square meter per second (`m2/s`)** — transmissivity:
 
@@ -373,6 +770,28 @@ UCUM is the **Unified Code for Units of Measure**, the international machine-par
 
 - `LevelReading.pressure`
 
+**Kilowatt (`kW`)** — power _(since v2.3)_:
+
+- `pump_installations[].rated_power`
+
+**Volt (`V`)** — voltage _(since v2.3)_:
+
+- `pump_installations[].electrical.voltage`
+
+**Square millimeter (`mm2`)** — cross-sectional area _(since v2.3)_:
+
+- `pump_installations[].electrical.cable_section`
+
+**Degree Celsius (`Cel`)** — temperature _(since v2.3)_:
+
+- `water_samples[].laboratory.received_temperature`
+
+**Micrometer (`um`)** — filter pore size _(since v2.3)_:
+
+- `water_samples[].results[].filtration.pore_size`
+
+**Unit by parameter code** _(since v2.3)_ — `water_samples[].results[].value`, `detection_limit`, `quantification_limit`, `value_precision` and `purge.readings[].value` are in the canonical unit of the result's parameter (see water-quality.md § Units).
+
 **Degree (`deg`)** — angles and geographic coordinates:
 
 - `fractures[].azimuth`, `fractures[].dip`
@@ -385,10 +804,17 @@ UCUM is the **Unified Code for Units of Measure**, the international machine-par
 - `aquifer_analysis[].well_efficiency_pct` (percentage, 0–100)
 - `aquifer_analysis[].specific_capacity` (derived ratio in m³/h per m, i.e. `m2/h`)
 - Lithology `color` (CSS hex string)
+- `pump_installations[].stages`, `electrical.phases` (counts)
+- `permits[].monthly_schedule[].month`, `days`; `permits[].conditions[].occurrences` (counts)
+- `operating_regime[].days_per_week` (count, 1–7)
+
+### Water quality units _(since v2.3)_
+
+Water quality results take their unit from the parameter code; only `x-` vocabulary codes declare `unit` (UCUM). The unit-by-code rule and regional unit normalization are specified in [water-quality.md](water-quality.md) § Units.
 
 ### 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.
+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. It does not apply to `pump_installations[].intake_depth`, which is an equipment depth and is always positive.
 
 ### Diameter and the as-built convention
 
@@ -404,7 +830,13 @@ An interchange format with configurable units multiplies the number of valid enc
 
 Producers receiving non-SI source data (imperial drilling reports, US gpm flow measurements, inch casing designations, slot-number screens) MUST convert to SI before writing. Consumers presenting the data to users in non-SI units MUST convert on read.
 
-Conversion utilities for the common transformations are provided in `@welldot/core` under the `units` module — m ↔ ft, mm ↔ in, m³/h ↔ L/s, m³/h ↔ US gpm, m²/s ↔ m²/d, DD ↔ DMS, slot-number ↔ mm, and similar.
+Conversion utilities for the common transformations are provided in `@welldot/core` under the `units` module — m ↔ ft, mm ↔ in, m³/h ↔ L/s, m³/h ↔ US gpm, m²/s ↔ m²/d, DD ↔ DMS, slot-number ↔ mm, cv/hp ↔ kW, L / ft³ / US gal ↔ m³, µg/L ↔ mg/L, mS/m ↔ µS/cm, and similar.
+
+---
+
+## Water quality parameter vocabulary _(since v2.3)_
+
+The `welldot` parameter vocabulary (98 codes), its rules, the CAS equivalences and the treatment of limit sets are specified in [water-quality.md](water-quality.md) § Parameter vocabulary.
 
 ---
 
@@ -426,6 +858,10 @@ An optional array of HTTPS URLs declaring formal extensions to the spec that the
 - The schema MAY link to human documentation via its `description` field or a custom `x-documentation` field pointing to a Markdown or PDF URL.
 - Profiles MAY impose additional required fields, constrain vocabulary values, or mandate the use of specific `x-` extensions for a regulatory context.
 
+### Example: a regulatory water quality profile _(since v2.3)_
+
+See [water-quality.md](water-quality.md) § Regulatory profiles.
+
 ### Profile validation
 
 - If a profile URL is unreachable, returns a non-JSON document, or fails to parse as JSON Schema, the profile is silently ignored. Parsers MUST NOT reject files whose profile URLs are unavailable.
@@ -461,20 +897,20 @@ Top-level blocks not defined in this spec MUST use the `x-` prefix. Parsers MUST
 ```json
 {
   "version": 2,
-  "x-water_quality": [ ... ],
+  "x-gas_monitoring": [ ... ],
   "x-geophysical_logs": [ ... ]
 }
 ```
 
 ### Custom vocabulary values — `x-` prefix
 
-Open vocabulary fields in this spec (`type` in `hydrodynamic_events`, `category` in `history_logs`, `vocabulary` in `texture`, `method` in `aquifer_analysis`, `well_type`, and any other field documented as accepting any string) SHOULD use the `x-` prefix when the value is non-canonical — i.e. not listed in the recommended vocabulary of this spec.
+Open vocabulary fields in this spec (`type` in `hydrodynamic_events`, `category` in `history_logs`, `vocabulary` in `texture` and in water quality `parameter` (as `x-…` vocabularies), `method` in `aquifer_analysis`, `well_type`, and any other field documented as accepting any string; not closed vocabularies such as `history_logs[].status`) SHOULD use the `x-` prefix when the value is non-canonical — i.e. not listed in the recommended vocabulary of this spec.
 
 Parsers MUST treat `x-` prefixed vocabulary values as valid. Promotion from `x-` form to canonical form follows the Deprecation Policy (see § Deprecation Policy — Vocabulary value promotion).
 
 ```json
 { "type": "x-slug_test" }
-{ "category": "x-decommission" }
+{ "category": "x-site_visit" }
 { "method": "x-theis_recovery" }
 ```
 
@@ -491,7 +927,17 @@ Each ID-bearing array maintains its **own uniqueness scope**. The ID namespaces
 - `hydrodynamic_events[].id` — unique within `hydrodynamic_events`
 - `aquifer_analysis[].id` — unique within `aquifer_analysis`
 - `history_logs[].id` — unique within `history_logs`
-- `history_logs[].attachments[].id` — unique within the attachments array of the same log entry
+- `pump_installations[].id` — unique within `pump_installations` _(since v2.3)_
+- `permits[].id` — unique within `permits` _(since v2.3)_
+- `permits[].conditions[].id` — unique within the `conditions` array of one permit _(since v2.3)_
+- `permits[].conditions[].fulfillments[].id` — unique within the `fulfillments` array of one condition _(since v2.3)_
+- `permits[].history[].id` — unique within the `history` array of one permit _(since v2.3)_
+- `permits[].monthly_schedule[].month` and `permits[].volume_limits[].period` — unique within one permit _(since v2.3)_
+- `meters[].id` — unique within `meters` _(since v2.3)_
+- `production[].id` — unique within `production` _(since v2.3)_
+- `operating_regime[].id` — unique within `operating_regime`; `operating_regime[].effective_from` is also unique within the block _(since v2.3)_
+- `water_samples[].id` — unique within `water_samples` _(since v2.3)_
+- `attachments[].id` — unique within its owning array: the root `attachments`, or the `attachments` array of one record (`history_logs`, `permits`, `pump_installations`, `hydrodynamic_events`, `aquifer_analysis`, `water_samples`). The same id may appear under different records.
 - `well_id[]` — uniqueness is on the composite key `(authority, id)`, not on `id` alone
 
 An ID value MAY repeat across different arrays without conflict (e.g. an event and an analysis MAY both use the ID `"001"`), though distinct values are recommended for clarity.
@@ -500,10 +946,26 @@ An ID value MAY repeat across different arrays without conflict (e.g. an event a
 
 The following fields hold references to IDs in other arrays:
 
-| Reference field                             | Points to                  | Resolution scope |
-| ------------------------------------------- | -------------------------- | ---------------- |
-| `aquifer_analysis[].source_event_ids[]`     | `hydrodynamic_events[].id` | Same file only   |
-| `aquifer_analysis[].static_level_source_id` | `hydrodynamic_events[].id` | Same file only   |
+| Reference field                                       | Points to                  | Resolution scope |
+| ----------------------------------------------------- | -------------------------- | ---------------- |
+| `aquifer_analysis[].source_event_ids[]`               | `hydrodynamic_events[].id` | Same file only   |
+| `aquifer_analysis[].static_level_source_id`           | `hydrodynamic_events[].id` | Same file only   |
+| `hydrodynamic_events[].corrects`                      | `hydrodynamic_events[].id` | Same file only   |
+| `production[].corrects`                               | `production[].id`          | Same file only   |
+| `production[].meter_id`                               | `meters[].id`              | Same file only   |
+| `permits[].supersedes`                                | `permits[].id`             | Same file only   |
+| `history_logs[].pump_installation_id`                 | `pump_installations[].id`  | Same file only   |
+| `history_logs[].meter_id`                             | `meters[].id`              | Same file only   |
+| `history_logs[].hydrodynamic_event_ids[]`             | `hydrodynamic_events[].id` | Same file only   |
+| `history_logs[].sample_ids[]`                         | `water_samples[].id`       | Same file only   |
+| `permits[].conditions[].fulfillments[].event_id`      | `hydrodynamic_events[].id` | Same file only   |
+| `permits[].conditions[].fulfillments[].sample_id`     | `water_samples[].id`       | Same file only   |
+| `water_samples[].corrects`                            | `water_samples[].id`       | Same file only   |
+| `water_samples[].parent_sample_id`                    | `water_samples[].id`       | Same file only   |
+| `water_samples[].static_level_event_id`               | `hydrodynamic_events[].id` | Same file only   |
+| `water_samples[].sampling_point.pump_installation_id` | `pump_installations[].id`  | Same file only   |
+
+Root `attachments` is not a registry: records never 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`, `pump_installations`, `hydrodynamic_events`, `aquifer_analysis` or `water_samples` entries. A document that concerns several records is repeated on each; `sha256` guarantees both copies point to the same file.
 
 Cross-file references are not supported in v2.
 
@@ -546,23 +1008,27 @@ The precision field name is the measurement field name suffixed with `_precision
 
 ### Supported precision fields
 
-| Measurement     | Precision field           | Defined on                 |
-| --------------- | ------------------------- | -------------------------- |
-| `lat`           | `lat_precision`           | `LocationProperties`       |
-| `lng`           | `lng_precision`           | `LocationProperties`       |
-| `elevation`     | `elevation_precision`     | `LocationProperties`       |
-| `static_level`  | `static_level_precision`  | events, `AquiferAnalysis`  |
-| `dynamic_level` | `dynamic_level_precision` | `AquiferAnalysis`          |
-| `depth`         | `depth_precision`         | `LevelReading`, `Fracture` |
-| `rate`          | `rate_precision`          | `PumpingStep`              |
-| `flow_rate`     | `flow_rate_precision`     | `AquiferAnalysis`          |
+| Measurement     | Precision field           | Defined on                            |
+| --------------- | ------------------------- | ------------------------------------- |
+| `lat`           | `lat_precision`           | `LocationProperties`                  |
+| `lng`           | `lng_precision`           | `LocationProperties`                  |
+| `elevation`     | `elevation_precision`     | `LocationProperties`                  |
+| `static_level`  | `static_level_precision`  | events, `AquiferAnalysis`             |
+| `dynamic_level` | `dynamic_level_precision` | `AquiferAnalysis`                     |
+| `depth`         | `depth_precision`         | `LevelReading`, `Fracture`            |
+| `rate`          | `rate_precision`          | `PumpingStep`                         |
+| `flow_rate`     | `flow_rate_precision`     | `AquiferAnalysis`                     |
+| `depth`         | `depth_precision`         | `SamplingPoint` _(since v2.3)_        |
+| `value`         | `value_precision`         | water quality `Result` _(since v2.3)_ |
 
 All precision fields are optional. When omitted, the measurement value carries no documented precision. Precision is the one-sigma standard deviation in the same unit as the measurement.
 
+Laboratory reports usually give an expanded uncertainty U with a coverage factor k (typically k = 2). Converters store `value_precision = U / k`, never U itself.
+
 ```json
 { "depth": 44.8, "depth_precision": 0.01 }
 ```
 
 ---
 
-_Draft — `.well` Format Specification v2.0_
+_`.well` Format Specification v2.3_