.well File Format Specification — Version 2.4: Water Quality

See also: overview.md · format-reference.md · object-schemas.md · interoperability.md

Overview

This document specifies the water_samples block (since v2.3): the sample and result schemas, the recommended values, the unit rules, the welldot parameter vocabulary and how jurisdiction requirements are expressed. Cross-cutting rules that also cover water samples stay in their general sections: datetimes and the _resolution: "day" convention, canonical units and field bindings, cross-references, uniqueness and precision in format-reference.md; attachments, ledger corrections and history_logs links in object-schemas.md. The Complete Example in object-schemas.md includes water samples.

Table of contents

• water_samples[]
  • WaterSample
  • SamplingPoint
  • Purge
  • PurgeReading
  • Laboratory
  • Result
  • Parameter
  • Filtration
  • Validation
  • Result rules
  • Malformed (rejected)
  • Validation (warnings, never rejection)
  • Derived values
  • History log links
• Recommended values
  • water_samples[].sample_type — Recommended values (since v2.3)
  • water_samples[].sampling_method — Recommended values (since v2.3)
  • water_samples[].sampling_point.type — Recommended values (since v2.3)
  • water_samples[].sampling_point.device — Recommended values (since v2.3)
• Units
• Parameter vocabulary
  • Vocabulary rules
  • Core vocabulary
  • Limit sets are not part of the file
• Regulatory profiles

water_samples[]

A ledger: each entry is one collection of water from the well, with the results measured on it in the field and in the laboratory. Entries MAY be edited in place, but editing is NOT RECOMMENDED after the entry has been exported. A revalidation of data already recorded is an edit of Result.validation in place. A corrected laboratory report is best written as a new sample whose corrects holds the id of the retracted sample, following object-schemas.md § hydrodynamic_events[] — Corrections (retracted samples stay in the file and are excluded from every derivation; chains are allowed; a cycle emits a warning).

The block serves drinking-water compliance, environmental and mining monitoring under licence, and hydrochemistry, in any jurisdiction. It follows the rigor of audited monitoring (chain of custody, field QA/QC, filtration, lab flags, data validation) with almost every field optional. It is jurisdiction-neutral: limits, exceedances and national rules are never stored; see § Parameter vocabulary — Limit sets are not part of the file.

Out of scope: limits and exceedances, sampling schedules, high-frequency telemetry (only aggregates enter), interpreted assessment (class, facies), and the laboratory's internal QC (method blanks, matrix spikes).

WaterSample

SamplingPoint

A sample's depth is a point, an interval, derived from the production pump, or unknown. All depths are measured from ground level.

• depth together with from or to is malformed.
• With pump_installation_id, the depth is not repeated on the sampling point.
• Field measurements taken from the top of casing are converted to ground level by the producer, by the same rule as water levels.
• A vertical profile or a multilevel well is several samples at different depths, with the same campaign and sequence for ordering.

Purge

All fields optional.

PurgeReading

purge.readings holds the stabilization series (pH, conductivity, temperature, dissolved oxygen, ORP, turbidity) that audits require. The final values at the time of collection go in results with measured_in: "field".

Laboratory

Result

"Canonical" is the unit of the parameter in the vocabulary, or unit for x- codes. See § Units.

Parameter

The welldot codes, their units, value forms and CAS equivalences are listed in § Parameter vocabulary.

Filtration

All fields optional.

Validation

An absent validation is equivalent to status: "unvalidated".

Result rules

Each result has exactly one value form. Three annotation layers are kept apart: the censoring qualifier, the laboratory flags and the reviewer's validation.

• < with value records the value the laboratory reported, usually the quantification or detection limit. It is neither zero nor absent.
• > covers upper bounds, such as counts above the method range.
• estimated marks values between the detection and quantification limits.
• not_detected without detection_limit emits a warning, because the result has no scale.
• value_precision is one sigma. Reports give an expanded uncertainty (usually k = 2); converters divide it by the coverage factor.
• fraction: "dissolved" is expected with filtration; without it, a warning is emitted. Dissolved metals filtered in the laboratory and in the field are not comparable in an audit.
• lab_flags has no vocabulary: codes vary by laboratory and country, and interpreting them is the job of validation.
• A rejected result is excluded from every derivation and from comparisons with limits. qualified results are kept.
• Revalidating the data of a recorded sample creates a new sample with corrects, like any ledger correction.
• The same parameter may appear twice in a sample when fraction or measured_in differ (total and dissolved iron; field and laboratory pH). An exact duplicate emits a warning.
• A welldot code and its CAS equivalent are the same parameter for duplicate detection and derivations.

Malformed (rejected)

• results empty or absent.
• A result with more than one value form, or none without qualifier: "not_detected"; not_detected together with a value form; <, > or estimated without value.
• unit on a welldot or cas parameter; an x- parameter without unit; a vocabulary other than welldot, cas or x-….
• sampling_point.depth together with from or to.
• An _resolution field with a value other than day; an instant without an offset.
• A value outside the closed enums qualifier, fraction, measured_in, filtration.location, validation.status. sample_type, sampling_method, sampling_point.type and device are open vocabularies.

Validation (warnings, never rejection)

• field_duplicate or split_sample without parent_sample_id.
• fraction: "dissolved" without filtration.
• A sample depth outside every well_screen interval (stagnant casing water).
• A sample depth below well_depth.
• A sample depth above the static level of static_level_event_id.
• presence on a numeric code, or value on a presence code (value form different from the vocabulary's).
• not_detected without detection_limit.
• The same parameter, fraction and measured_in repeated in one sample.
• A welldot code unknown to the vocabulary version.
• analyzed_at or laboratory.received_at earlier than the collection datetime.
• A reference that does not resolve: corrects, parent_sample_id, static_level_event_id, sampling_point.pump_installation_id.
• A corrects cycle.

Derived values

Derived values are computed by @welldot/utils and never stored. Retracted samples and rejected results are excluded from all of them.

• Exceedances against a selectable limit set (WHO, EU 2020/2184, Brazil, …) or the user's own limits. < and not_detected results never exceed; for presence limits, presence exceeds. turbidity, turbidity_ntu and turbidity_fnu compare with nephelometric limits, and turbidity_fau is never compared.
• Ion balance, converting mg/L to meq/L with the molar mass and charge of each code.
• Relative percent difference (RPD) between a duplicate or split and its original sample, per parameter.
• Blank contamination: parameters detected in field_blank, trip_blank or equipment_blank samples of the same campaign.
• Holding time, from datetime to analyzed_at, at the available resolution.
• Receipt temperature compliance.
• Purge stabilization from purge.readings.
• Acid drainage indicators (net alkalinity, sulfate/chloride ratio).
• Piper and Stiff coordinates and the hydrochemical facies.
• Effective sample depth (from sampling_point, or the pump's intake_depth) and whether the sample represents formation water (inside a screen interval and below the static level).

History log links

A history_logs entry (typically maintenance with maintenance_type: "water_sampling", or an inspection) records the task and points to the samples it collected with sample_ids. A water-quality monitoring permit condition is fulfilled by a condition fulfillment pointing to the sample the same way. See object-schemas.md § history_logs[] — Data links and § permits[] — Condition fulfillment.

Recommended values

Non-canonical values of these open vocabularies SHOULD use the x- prefix.

water_samples[].sample_type — Recommended values (since v2.3)

Non-canonical values SHOULD use the x- prefix. Laboratory internal QC (method blanks, matrix spikes) is out of scope.

water_samples[].sampling_method — Recommended values (since v2.3)

sampling_method describes the purge; sampling_point.device describes what collected the water. Portuguese terms follow ABNT NBR 15847 (métodos de purga).

Non-canonical values SHOULD use the x- prefix.

water_samples[].sampling_point.type — Recommended values (since v2.3)

Non-canonical values SHOULD use the x- prefix.

water_samples[].sampling_point.device — Recommended values (since v2.3)

Non-canonical values SHOULD use the x- prefix.

Units

A water quality result never declares a unit for a known parameter: the unit comes from the parameter code.

1. Substances (vocabulary welldot or cas) are always in mg/L. µg/L, ng/L and g/L are converted on import.
2. Parameters that are not concentrations (pH, conductivity, temperature, redox potential, turbidity, color, microbiology, radioactivity) have the unit fixed by their welldot code; see § Parameter vocabulary. pH is dimensionless.
3. x- vocabulary codes require unit, in UCUM. This is the only exception to the rule that the file never declares units. unit on a welldot or cas parameter is malformed, and an x- code without unit is malformed.
4. Turbidity and microbiological counts are separated by code, not by unit: turbidity_ntu, turbidity_fnu, turbidity_fau and the generic turbidity (FTU, formazin with no identified method); _mpn and _cfu count codes beside the presence codes.

Regional unit names are normalized on import:

The basis of expression lives in the code, never in the unit: nitrate reported "as N" and "as NO₃⁻" are different parameters (nitrate_as_n, nitrate_as_no3). @welldot/core provides concentrationToCanonical, milliSiemensPerMeterToMicroSiemensPerCm, milliSiemensPerCmToMicroSiemensPerCm, turbidityCodeForUnit, normalizeColorUnit and expandedToStandardUncertainty for these conversions.

Parameter vocabulary

A parameter is identified by an object { code, vocabulary }, like texture:

{ "code": "nitrate_as_n", "vocabulary": "welldot" }
{ "code": "71-43-2", "vocabulary": "cas" }
{ "code": "glyphosate_ampa", "vocabulary": "x-lab-codes" }

vocabulary is welldot, cas or an x-… vocabulary; any other value is malformed.

Vocabulary rules

1. Substances (welldot or cas) are always in mg/L. Conversions such as µg/L → mg/L happen on import.
2. Parameters that are not concentrations have their unit fixed by the welldot vocabulary (pH, conductivity, temperature, redox potential, turbidity, color, microbiology, radioactivity).
3. x- codes require unit, in UCUM. This is the only exception to the spec's unit rule.
4. The basis of expression is part of the code. nitrate_as_n and nitrate_as_no3 are different parameters. A CAS code always means the substance itself. There is no basis field.
5. Preference. When a welldot code exists it is used instead of the CAS number. The vocabulary publishes the equivalences, and parsers treat a welldot code and its equivalent CAS number as the same parameter.
6. Labels and translations. The canonical label is English. Translations, regional synonyms and descriptions live in the published vocabulary, which is versioned (WATER_QUALITY_VOCABULARY_VERSION in @welldot/core).
7. Regional unit names are normalized on import: uT and FTU → turbidity; mg Pt-Co/L, PCU and TCU → uH; mS/m → µS/cm (×10). See § Units.

A welldot code unknown to the vocabulary version emits a warning, never a rejection. Any other substance is recorded by its CAS number, in mg/L.

Core vocabulary

The core list has 98 welldot codes. The Mining and redox group and the additional metals cover acid drainage, gold leaching (cyanide) and explosives (nitrogen species). The Form column gives the value form a result of that code uses (value, presence or text); see § water_samples[] — Result rules.

The CAS numbers listed are the published equivalences: a result coded by that CAS number is treated as the corresponding welldot code. Codes whose basis differs from the substance (such as nitrate_as_n) or that measure an analytical fraction (such as cyanide_wad_as_cn) have no CAS equivalent. Radionuclides are in Bq/L even though they have CAS numbers, an exception to the mg/L rule; uranium by mass stays under uranium (mg/L).

Limit sets are not part of the file

Limits, guideline values and exceedances are never written to a .well file, and no field names a national standard. @welldot/core bundles selectable limit sets as separate data (WHO Guidelines for Drinking-water Quality, EU Directive 2020/2184, Brazil GM/MS 888/2021), and consumers compare results against the set the user picks, or against their own limits. In turbidity comparisons, turbidity, turbidity_ntu and turbidity_fnu compare with nephelometric limits; turbidity_fau is never compared. Local obligations (which parameters, how often) are expressed by profiles; see § Regulatory profiles.

Regulatory profiles

Jurisdiction-specific water quality requirements live in profiles, not in the core format. A drinking-water profile for one jurisdiction might require, for wells with well_purpose production:

• at least one water_samples entry per calendar year with results for a fixed parameter list (e.g. e_coli, total_coliforms, turbidity_ntu, free_chlorine, nitrate_as_n, fluoride);
• monthly e_coli and total_coliforms results (presence form) and half-yearly results for the full list;
• laboratory.accreditation on every sample and an attachment with document_type: "lab_report".

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.org/profiles/drinking-water/v1/schema.json",
  "allOf": [{ "$ref": "https://welldot.org/schema/v2/well.schema.json" }],
  "required": ["water_samples"],
  "properties": {
    "water_samples": {
      "items": {
        "required": ["laboratory", "attachments"],
        "properties": {
          "laboratory": { "required": ["name", "accreditation"] }
        }
      }
    }
  }
}

Frequency rules that JSON Schema cannot express (one sample per month, one per year) are checked by profile-aware tools and surfaced as warnings, like any profile failure. The limits that results are compared against still come from a limit set, never from the file.