Skip to main content
Jira progress: loading…

WTR-SHR

Water Share / Composition Calculator

1. Identity​

Loading identity…

Depends on module:

Purpose
Computes water composition shares (ratios or percentages) with water-governed semantics, enforcing canonical source/stress identifiers, valid denominator choices, and disclosure-grade metadata for ESRS E3.

This engine is a domain adapter over MEID_CALC_SHARE.

2. Contract References (ZAR)​

2.1 Input Schema​

ZAR Address: schema.compute.water.share.inputs.v1_0_0

Required conceptual fields:

  • numerator_ref: water component identifier (source/stress/basis)
  • denominator_ref: water total identifier
  • share_mode: RATIO | PERCENT (default PERCENT)
  • alignment: BY_YEAR | BY_INDEX (default BY_YEAR)

And either:

  • numerator: scalar or time-series
  • denominator: scalar or time-series

(or resolvable signal refs, if your orchestration supports that pattern)

2.2 Options Schema​

ZAR Address: schema.compute.water.share.options.v1_0_0

Common options:

  • denominator_floor: default 1e-9
  • cap_range: ENFORCE | ALLOW (default ENFORCE)
  • missing_policy: ERROR | SKIP
  • source_normalization: STRICT | LENIENT (default STRICT)
  • stress_bucket_normalization: STRICT | LENIENT (default STRICT)
  • rounding: optional digits

2.3 Output Schema​

ZAR Address: schema.compute.water.share.output.v1_0_0

Outputs include:

  • share_series
  • share_unit (ratio or percent)
  • metadata (normalized refs, floors, caps, alignment)

3. Accepted Input Shapes​

A. Source share of withdrawal (surface water / total withdrawal)

{
  "numerator_ref": "source:surface_water",
  "denominator_ref": "withdrawal_total",
  "numerator": [[2025, 100000]],
  "denominator": [[2025, 125000]],
  "share_mode": "PERCENT"
}

B. Stress share of withdrawal (high-stress / total withdrawal)

{
  "numerator_ref": "stress:high",
  "denominator_ref": "withdrawal_total",
  "numerator": [[2025, 45000]],
  "denominator": [[2025, 125000]],
  "share_mode": "RATIO"
}

C. Consumption ratio (consumption / withdrawal)

{
  "numerator_ref": "consumption_total",
  "denominator_ref": "withdrawal_total",
  "numerator": [[2025, 15000]],
  "denominator": [[2025, 125000]],
  "share_mode": "PERCENT"
}

4. Water-Specific Normalization Rules (Normative)​

4.1. Allowed numerator_ref values (v1)​

Source shares

  • source:surface_water
  • source:groundwater
  • source:seawater
  • source:third_party
  • source:rainwater_harvested
  • source:other

Stress shares

  • stress:high
  • stress:medium
  • stress:low
  • stress:unknown

Totals

  • withdrawal_total
  • consumption_total
  • discharge_total

4.2. Allowed denominator_ref values (v1)​

  • withdrawal_total
  • consumption_total
  • discharge_total

4.3. Pairing rules (governed)​

The engine MUST enforce the following valid combinations:

  • source:* MAY only be divided by withdrawal_total or consumption_total (not discharge unless explicitly added later)
  • stress:* MAY only be divided by withdrawal_total or consumption_total
  • consumption_total / withdrawal_total is allowed (consumption ratio)
  • discharge_total / withdrawal_total is allowed only if explicitly enabled by schema in later versions

Invalid pairings MUST error (v1 strict).

5. Compute Semantics (Normative)​

For each aligned period tt:

Let N(t)N(t) be numerator and D(t)D(t) be denominator.

shareraw(t)=N(t)max⁡(∣D(t)∣,ϵ)share_{\mathrm{raw}}(t) = \frac{N(t)}{\max(|D(t)|, \epsilon)}

If share_mode = RATIO: share(t)=shareraw(t)share(t) = share_{\mathrm{raw}}(t)

If share_mode = PERCENT: share(t)=100⋅shareraw(t)share(t) = 100 \cdot share_{\mathrm{raw}}(t)

If cap_range = ENFORCE:

  • ratio: clamp to [0,1][0,1]
  • percent: clamp to [0,100][0,100]

6. Validation & Error Model​

Error codes (suggested)

  • WATER_SHARE_INVALID_REF
  • WATER_SHARE_INVALID_PAIRING
  • WATER_SHARE_ALIGNMENT_MISMATCH
  • WATER_SHARE_DENOMINATOR_ZERO_GUARDED
  • WATER_SHARE_NON_FINITE_VALUE

7. Dependencies​

  • MEID_CALC_SHARE (primitive)
  • schema resolver (ZAR)
  • canonical water source list
  • canonical stress bucket list (if used)

Declared via ZAR dependencies.

8. Methods Served (v1)​

  • Water.withdrawal.source.share
  • Water.consumption.source.share
  • Water.withdrawal.stress.share
  • Water.consumption.stress.share

Recommendation on naming​

Use metric types (CSI) like:

  • water.withdrawal.by_source.share
  • water.withdrawal.by_stress.share

…and keep the engine MEID generic: MEID_CALC_WATER_SHARE.



GitHub RepoRequest for Change (RFC)