.well File Format Specification — Version 2.4: Overview

v2.4 additions:
- version is the string "M.m" (^\d+\.\d+$), compared as two integers,
  never as text; patch levels are not allowed; readers accept 1, 2 and
  "M.m"
- location.properties.timezone (optional, IANA name): the local date of
  an instant is its date converted to this zone; a missing timezone in
  a file with condition fulfillments emits the warning missing_timezone
- logger_series (hydrodynamic event type): a continuous level series
  recorded by an installed sensor, with sensor_depth, interval,
  barometric_compensation and aggregation (none, hourly, daily with
  depth_min / depth_max); not a controlled test, not a static level
- LevelReading.datetime: the instant of a reading, required in a
  logger_series, where elapsed is absent
- Offline packaging: an optional ZIP (.wellz) with the .well file at
  the root and attachments at relative paths; relative uri allowed and
  sha256 required only inside the package
- Application extensions: x-<vendor>-<name> is RECOMMENDED
  (e.g. x-welldot-custom)

v2.4 clarifications:
- A known hydrodynamic event type is validated against its own schema
  and no longer falls back to the open x- rule; step counts per type
  are SHOULD (a free count is valid), and steps must be valid
  PumpingStep entries
- An optional field without a value is omitted, never written as null
  (storativity is no longer nullable); v2 integer files that still
  carry it are tolerated on read
- Ledgers MAY be edited in place; editing is NOT RECOMMENDED after a
  record has been exported, and corrects remains the way to retract a
  measurement. Result.validation is editable too
- Repeated records (collective permits, campaign blanks) share the
  same id and SHOULD have identical content; consumers MAY merge them
  by id. A fulfillment event_id or sample_id resolves only in the file
  of the well that produced it
- Unresolved references MUST be preserved when a file is re-exported,
  never silently removed
- A duplicated operating_regime.effective_from and an
  estimated_volume period_end not after period_start are warnings
- daily_operating_time above 24 is normalized to 24 with a warning
  (the stored value stays as written); a negative value is an error
- Attachment.document_type condition_evidence is typically found in
  permits[].conditions[].fulfillments
- The attachment lists (id uniqueness, "root is not an aggregate",
  where attachments are allowed) name the same set of records
- history_logs updated_at may be earlier than datetime for a pre-dated
  entry; neither ordering emits a warning
- well_id: producers SHOULD mark exactly one entry primary: true; "the
  first entry is canonical" is only the fallback

v2.3 additions:
- attachments (optional Attachment[]): root-level documents about the
  well as a whole (drilling report, as-built drawing, registry record…)
- Attachment becomes a common type and gains document_type
  (drilling_report, as_built_drawing, registry_record, photo,
  permit_document, condition_evidence, pump_curve, field_sheet,
  test_report, lab_report, invoice)
- pump_installations (optional PumpInstallation[]): pump installation
  history, with nameplate, intake depth, riser and electrical data
- permits (optional Permit[]): legal instruments governing abstraction
  (outorga, dispensa, cadastro) with validity, granted flow, daily
  operating time, volume limits, monthly schedule and conditions
  (condicionantes) whose deadlines are derived from ISO 8601 date
  durations; renewals are linked with supersedes. Each permit carries
  its identifier and/or request_identifier (verbatim, any format), a
  closed administrative status (requested, granted, suspended,
  revoked, denied, withdrawn), an administrative history (filing,
  process, notifications, fees, with done/due_date and attachments)
  and, on each condition, a responsible and the fulfillments of its
  deadlines (datetime, due_date, author, event_id, sample_id,
  attachments)
- meters (optional Meter[]): totalizer (hidrômetro) installation
  history; device facts only (type, serial, nominal diameter,
  max_reading for rollover)
- production (optional ProductionEntry[]): ledger of
  meter_reading entries (register values in m³) and estimated_volume
  entries (volumes estimated for a period without a meter); volumes
  are derived from consecutive readings, never stored as totals.
  Volumes declared to a regulator are not production data: they are
  the fulfillment of the permit's reporting condition
- operating_regime (optional OperatingRegime[]): declared flow rate,
  daily operating time and days per week, each entry in force from
  effective_from
- history_logs category status_change, with status (active,
  maintenance, inactive, decommissioned, abandoned): the well's
  operating status; current status is unknown without one
- history_logs category maintenance gains maintenance_type,
  pump_installation_id and meter_id
- history_logs gains hydrodynamic_event_ids and sample_ids (any
  category): references to the data an entry produced or observed,
  never copies of measured values
- hydrodynamic_events[].corrects: retracts an earlier event (ledger
  correction)
- hydrodynamic_events[].attachments, aquifer_analysis[].attachments
- Canonical units kW (power), V (voltage), mm² (cable cross-section),
  m³ (volume), h (daily operating time only)
- water_samples (optional WaterSample[]): ledger of water samples,
  each with its field and laboratory results in one list
  (distinguished by measured_in), sampling point (point depth or
  isolated interval, or the production pump), purge and stabilization
  readings, laboratory and chain of custody, field QA/QC
  (field_duplicate, split_sample via parent_sample_id; blanks),
  per-result filtration, lab flags and data validation; corrected
  reports and revalidations are new samples with corrects
- Parameter identity { code, vocabulary } with vocabularies welldot,
  cas and x-…; the welldot parameter vocabulary (98 codes) is
  published as versioned data in @welldot/core, with CAS
  equivalences; the unit of a welldot or cas parameter comes from its
  code (substances always mg/L), and unit (UCUM) exists only for x-
  codes
- Canonical units mg/L, µS/cm at 25 °C, °C, mV, NTU / FNU / FAU / FTU
  (by code), Hazen (uH), MPN/100 mL, CFU/100 mL, CFU/mL, Bq/L and µm
- _resolution convention: analyzed_at_resolution and
  laboratory.received_at_resolution set to "day" mark an instant
  known only by its date; consumers MUST ignore the time of day
- permit condition fulfillments gain sample_id (e.g. a water-quality
  monitoring condition)
- well_screen[].slot_type (screen design: continuous_slot, slotted,
  bridge_slot, louver, perforated, nold); type remains the screen
  material
- Recommended vocabularies for drilling_method, construction materials
  (well_case / well_screen / reduction type, riser_material),
  well_screen slot_type,
  centralizer steels, cement_pad.type, history_logs severity,
  measurement_method and aquifer_analysis method; every recommended
  vocabulary is published by @welldot/core with en/pt labels

v2.3 clarifications:
- Block kinds: every top-level array is a ledger, a mutable record or
  an installation; the kind decides how records are corrected
- Open vocabulary values are stored as their key, never as a
  translated label
- Datetime families: legal documents use calendar dates (YYYY-MM-DD),
  everything else uses RFC 3339 instants
- Naming rules: no units in field names; nameplate values use the
  rated_ prefix; time intervals use period_start / period_end
- supersedes (legal succession between permits) is distinct from
  corrects (ledger retraction)
- Permit status and condition deadlines are derived on the local civil
  date at the well site, never stored
- Volume derivation is normative: rollover via max_reading, never
  across two meters, unknown (never zero or negative) where readings
  do not cover; metered volume takes precedence over estimated
  volumes
- history_logs category change_of_use is no longer a recommended
  value; a change of use is an event entry (the current use lives in
  well_purpose)
- Jurisdiction neutrality: water quality limits, exceedances and
  national rules are never written to the file; limit sets (WHO, EU,
  Brazil…) are data in @welldot/core and local requirements enter
  through profiles

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")

v2.0 additions:
- location object (supersedes top-level lat/lng/elevation)
- well_id (array of authority-scoped identifiers)
- profiles (JSON Schema URLs for regulatory and domain-specific constraints)
- texture object (multi-vocabulary, replaces v1 fgdc_texture string)
- hydrodynamic_events (ledger of water-level observations)
- aquifer_analysis (interpreted aquifer parameter sets)
- history_logs (operational log of interventions and incidents,
  with updated_at edit timestamp)
- optional @context (reserved for JSON-LD interoperability)
- optional *_precision fields on key measurements
- WellScreen.screen_slot renamed from screen_slot_mm

v2.0 tightenings:
- All numeric values are SI by spec. The format does not encode a
  units declaration; see § Units for the canonical mapping. v1 was
  de facto SI in practice and no v1 file in existence declared
  non-SI units, so this is a clarification rather than a breaking
  change. Display and input units are application concerns.

v2.0 preserves all v1 fields. Parsers must accept v1 documents
unchanged and must accept the following v1-to-v2 normalizations:
- Top-level lat/lng/elevation → location.lat/lng/elevation
- fgdc_texture: "<code>" → texture: { code, vocabulary: "fgdc" }
- screen_slot_mm → screen_slot (value preserved; both versions are
  in millimeters)
- bole_hole → bore_hole (v1 typo compatibility)
- diam_pol (inches) → diameter (mm), multiplied by 25.4