# Water quality vocabulary

> Look up water quality parameters, their units and labels, resolve CAS numbers, and use the WHO, EU and Brazilian limit sets that @welldot/core ships as data.

Water quality results in a `.well` file name their parameter by a code and a vocabulary, and take their unit from the code ([parameter vocabulary](/format/spec/v2/water-quality#parameter-vocabulary)). `@welldot/core` publishes the `welldot` vocabulary as versioned data, together with drinking water limit sets that are deliberately kept out of the files.

## Parameters

```ts
import { getParameterDefinition, getParameterLabel } from '@welldot/core';

getParameterDefinition({ code: 'nitrate_as_n', vocabulary: 'welldot' });
// {
//   code: 'nitrate_as_n', group: 'nutrient', label: 'Nitrate as N',
//   labels: { pt: 'Nitrato como N' }, unit: { symbol: 'mg/L', ucum: 'mg/L' },
//   form: 'value', molar_mass: 14.007, charge: -1
// }

getParameterLabel({ code: 'nitrate_as_n', vocabulary: 'welldot' }, 'pt'); // 'Nitrato como N'
```

Each `ParameterDefinition` carries the code, its group (`physical`, `major_ion`, `metal`, `nutrient`, `microbiology`, …), the English label and translations, the canonical unit (display symbol and UCUM code), the form of a result (`value`, `presence` or `text`), the CAS number when there is one, and molar mass and charge for ions used in ion balance and hydrochemical diagrams.

| Export                             | Description                                                                                     |
| ---------------------------------- | ----------------------------------------------------------------------------------------------- |
| `WATER_QUALITY_PARAMETERS`         | The 98 `welldot` parameter definitions.                                                         |
| `WATER_QUALITY_VOCABULARY_VERSION` | Version of the published vocabulary.                                                            |
| `WATER_QUALITY_UNITS`              | The canonical units the vocabulary uses.                                                        |
| `getParameterDefinition(param)`    | Looks up a `{ code, vocabulary }`; a `cas` code resolves to its `welldot` entry.                |
| `getParameterLabel(param, locale)` | Display name; unknown codes are returned as they are.                                           |
| `parameterKey(param)`              | One identity for a `welldot` code and its CAS equivalent, for grouping and duplicate detection. |
| `isKnownParameter(param)`          | `false` only for a `welldot` code this vocabulary version does not know.                        |

## CAS numbers

Substances can be identified by their CAS registry number ([vocabulary rules](/format/spec/v2/water-quality#vocabulary-rules)). The library resolves the ones that have a `welldot` equivalent:

```ts
import { getParameterDefinition, parameterKey } from '@welldot/core';

getParameterDefinition({ code: '14808-79-8', vocabulary: 'cas' })?.code; // 'sulfate'
parameterKey({ code: '14808-79-8', vocabulary: 'cas' }); // 'sulfate'
parameterKey({ code: 'sulfate', vocabulary: 'welldot' }); // 'sulfate', the same key
```

## Limit sets

Limits are not stored in `.well` files: a file records what was measured, and the reader decides which standard to compare it with ([limit sets are not part of the file](/format/spec/v2/water-quality#limit-sets-are-not-part-of-the-file)). The package ships three sets:

| Export              | Source                                           | `id`                |
| ------------------- | ------------------------------------------------ | ------------------- |
| `WHO_GDWQ_2022`     | WHO Guidelines for Drinking-water Quality (2022) | `who_gdwq_2022`     |
| `EU_2020_2184`      | EU Drinking Water Directive 2020/2184            | `eu_2020_2184`      |
| `BR_GM_MS_888_2021` | Brazil, Portaria GM/MS 888/2021                  | `br_gm_ms_888_2021` |

`WATER_QUALITY_LIMIT_SETS` lists them in display order, and `getLimitSet(id)` finds one by id. A set has a `name`, a `jurisdiction`, its `source` and a list of `limits`, each with a parameter `code`, a `min` and/or `max` in the parameter's canonical unit and a `basis`.

```ts
import { getLimitSet } from '@welldot/core';

getLimitSet('who_gdwq_2022')?.limits.find(l => l.code === 'arsenic');
// { code: 'arsenic', max: 0.01, basis: 'health', note: 'provisional' }
```

To compare a sample with a set, use `getExceedances` from [`@welldot/utils`](/utils/guides/water-quality), which handles censored values, presence limits and turbidity comparability.

::caution
The limit values are transcribed from the cited documents. Check them against the official text before any regulatory use.
::

## Related

- [Water quality](/format/spec/v2/water-quality) in the spec
- [Unit conversion](/core/guides/unit-conversion) for lab report units