Skip to content

proxy_provenance extension (v1)

1. Purpose

Locked decision 7 requires a formal 5-step proxy cascade (regional → country-adjacent → climate-analogue → generic-with-adaptation → peer-reviewed literature), with every EPD carrying provenance metadata. ISO 14044 §4.2.3 requires data quality to be assessed and documented (time-related, geographical, technological coverage; precision, completeness, representativeness, consistency, reproducibility — the classic DQI list) wherever inventory data is used, and EN 15804+A2 §5.3 requires declared/documented data quality for any EPD used in a construction-product declaration. Since openEPD has no native representation of "this data point is a proxy" or of a structured pedigree assessment — only a single scalar rsd — this extension exists to make ISO 14044 §4.2.3 and EN 15804+A2 §5.3 satisfiable within our schema, and to make the CLAUDE.md seed-EPD provenance gate mechanically enforceable in CI.

2. Attachment point

Epd.ext['chwr']['proxy_provenance'] — confirmed final (locked decision 20).

This uses openEPD's documented proprietary-extension mechanism (ext.<namespace>), which the spec guarantees is stored transparently and does not require the interpreting system to understand it — exactly the "safe against future openEPD upgrades" property we need, since a namespaced key under ext cannot collide with anything Building Transparency / C-Change Labs later adds to the core Epd model.

Python access pattern (openEPD 6.x):

# Write
epd.set_ext_field('chwr', {'proxy_provenance': pp.model_dump()})

# Read
data = epd.get_ext_field('chwr', {}).get('proxy_provenance')
pp = ProxyProvenance.model_validate(data) if data else None

The namespace segment is chwr — short, matches the repo name, and deliberately distinct from "sankofa," which is a working title and could change. openEPD's ext is a plain dict; set_ext_field / get_ext_field are convenience methods on BaseOpenEpdSchema.

We attach at the Epd object level (one proxy_provenance block per EPD), not per-indicator, because the cascade decision is made once per proxy-EPD-selection event — an adapted Turkish cement EPD has one provenance story covering all nine indicators simultaneously.

3. Schema (Pydantic v2 — backend/app/schemas/proxy_provenance.py)

Fields (all Python, implemented as Pydantic v2 BaseModel):

  • cascade_step (int, 1–5, required). Which step of the locked decision-7 cascade produced this EPD selection. 1 = regional (no proxying), 2 = country-adjacent, 3 = climate-analogue, 4 = generic with adaptation, 5 = peer-reviewed literature.
  • source_epd_reference (string or None, required if cascade_step > 1). Identifier of the source EPD being adapted.
  • source_citation (string, required). Citation URL or DOI for wherever this record's numbers actually came from. Always populated, even at step 1.
  • justification_text (string, required, min 280 characters). Prose explaining why this EPD/adaptation is appropriate for the target African context.
  • adaptation_factors (list of records, optional). Each entry: field_adapted (string), from_value (float), to_value (float), method_reference (string).
  • pedigree (sub-object, required). Five Weidema axes, each scored 1–5: reliability, completeness, temporal_correlation, geographical_correlation, further_technological_correlation.
  • pedigree_scoring_rubric_version (string, required). Version tag matching a version registered in §4 of this document.
  • gsd_squared (float, computed from pedigree scores via §5 formula).
  • data_geography (ISO 3166 alpha-3, required). Region of the source EPD data.
  • target_geography (ISO 3166 alpha-3, required). Intended-use region (project location).
  • climate_analogue_rationale (string, required if cascade_step ≥ 3).
  • peer_review_citation (string, required if cascade_step ≥ 4). Required from step 4 ("generic with adaptation") onward, not only at step 5, because the adaptation method needs a citable basis.
  • review_status (enum: unreviewed | internal_review | external_review, default unreviewed).
  • created_at (datetime, required).
  • created_by (string, required).
  • last_modified_at (datetime, required).

4. Pedigree axis rubrics (v1)

Paraphrased from Weidema & Wesnæs 1996 and adapted to earth-material EPD selection in Sub-Saharan Africa. Registry version: v1.0.0.

Reliability (how was the underlying data verified?)

Score Definition
1 Third-party-verified EPD from a recognized programme operator (EPDASA/INIES/ÖKOBAUDAT/EPD Norge/EPD International/IBU), independently audited.
2 Verified EPD from a recognized programme operator, but verification predates current PCR revision.
3 Industry-average or generic data published by a recognized body (e.g. UNEP GlobalABC), not individually verified.
4 Peer-reviewed academic measurement (e.g. Ben-Alon et al.) without formal EPD verification.
5 Estimated or back-calculated value with no independent check.

Completeness (does the data cover the full declared unit and process scope?)

Score Definition
1 Full cradle-to-gate (or relevant module) data, all sub-processes accounted for, matches our declared unit exactly.
2 Minor gaps (e.g. packaging excluded) that are documented and small relative to total impact.
3 Some significant sub-process estimated rather than measured (e.g. kiln firing modeled generically).
4 Declared unit requires a non-trivial conversion (different reference unit, different functional basis) to apply to our material.
5 Substantial scope gaps requiring expert estimation to fill.

Temporal correlation (how old is the source data relative to the assessment date?)

Score Definition
1 Source data ≤3 years old at assessment date, matches EN 15804+A2 validity window.
2 3–6 years old.
3 6–10 years old.
4 10–15 years old, or EPD's valid_until has technically lapsed but the underlying process is known to be stable (e.g. traditional adobe production).
5 >15 years old or undated.

Geographical correlation (how far is the source region from the target region?)

Score Definition
1 Same country as target project.
2 Same climatic/economic region (e.g. within ECOWAS, similar grid mix and transport infrastructure).
3 Different region, same continent, comparable industrialization level (this is the typical "country-adjacent," cascade-step-2 case).
4 Different continent, but comparable production technology and climate (typical cascade-step-3 "climate-analogue" case, e.g. arid-zone masonry from another continent).
5 Different continent, different production technology, geography adjustment is a substantial assumption.

Further technological correlation (does the source process match our actual production method?)

Score Definition
1 Identical production technology (e.g. same CSEB press type, same stabiliser ratio).
2 Same technology family, minor process differences (e.g. different but comparable compaction method).
3 Related technology requiring a documented adaptation factor (this is the core cascade-step-4 "generic with adaptation" case).
4 Substantially different technology, adaptation based on engineering judgment rather than a measured conversion factor.
5 No comparable technology exists; value is a literature-derived estimate (typical cascade-step-5 case).

5. GSD² computation

Formula (standard pedigree-matrix aggregation, per Weidema & Wesnæs 1996, empirically refined by Ciroth et al. 2016, Int J LCA 21(9):1338–1348, DOI 10.1007/s11367-013-0670-5):

GSD² = exp( sqrt( Σ ln(Uᵢ)² + ln(U_basic)² ) )

The outer sqrt encloses both terms; per Ciroth et al. 2016 §3, the aggregated variance in log-space is Σ ln(Uᵢ)² + ln(U_basic)², and GSD² is the exponential of the standard deviation (square root) of that variance.

where each Uᵢ is the uncertainty factor corresponding to the pedigree score on axis i (looked up from a basic-uncertainty-factor table), and U_basic is a process-inherent basic uncertainty factor independent of pedigree.

Per Ciroth et al. 2016's own recommendation, v1 uses the classic ecoinvent pedigree uncertainty factor table as Uᵢ. Per orchestrator direction, the actual numeric table will be sourced by cross-checking Ciroth et al. 2016 directly against Brightway2's (bw2data) implementation (MIT-licensed) as a Phase 1 Step 1 sub-chat, before services/pedigree.py is implemented. Until then, gsd_squared is computed with all Uᵢ = 1.0 and U_basic = 1.0 (resulting in GSD² = 1.0 as a placeholder).

Worked example — Turkish Portland cement EPD selected as proxy for Senegalese cement, cascade step 3:

Axis Score Illustrative factor Uᵢ
Reliability 2 1.05
Completeness 2 1.05
Temporal correlation 3 1.10
Geographical correlation 4 1.20
Further technological correlation 2 1.05

U_basic ≈ 1.05 (illustrative — actual values must come from the Ciroth 2016 / Brightway2 cross-check sub-chat).

This worked example is illustrative of the computation mechanics only — specific factor values are placeholders, not validated numbers.

6. Validation rules (CI-enforced)

backend/tests/data/test_seed_epd_integrity.py enforces:

  • source_citation is present and is a URL or DOI resolvable via crossref.org (DOI) or live HTTP HEAD/GET (URL). Skipped for fixtures with "$test_only": true.
  • justification_text has minimum 280 characters.
  • pedigree has all 5 axes present, each an integer 1–5.
  • climate_analogue_rationale is present and non-empty if cascade_step ≥ 3.
  • peer_review_citation is present and resolvable if cascade_step ≥ 4.
  • pedigree_scoring_rubric_version matches a version registered in §4 of this file. The CI check parses version headers from this markdown file (the rubric registry) rather than hardcoding the version list.

7. JSON example

Validated against installed openepd==6.34.2 Pydantic models during Session 3B. Field paths reconciled per docs/methodology/openepd-subset-decision.md §5. This example is stored as backend/tests/data/seed_epds/turkish_portland_proxy.json and is the golden regression fixture.

{
  "$test_only": true,
  "id": "chwr-seed-cement-001",
  "doctype": "OpenEPD",
  "openepd_version": "6",
  "declaration_url": "https://example-registry.invalid/epd/turkish-portland-cement-2023",
  "program_operator": {
    "web_domain": "epdinternational.com",
    "name": "EPD International AB"
  },
  "product_name": "Portland Cement CEM I 42.5R (proxy)",
  "product_description": "Rotary-kiln Portland cement, Turkish production, used as climate-analogue proxy for Senegalese cement in the absence of a domestic verified EPD.",
  "declared_unit": {
    "qty": 1.0,
    "unit": "kg"
  },
  "pcr": {
    "name": "PCR for Cement, EPD International 2019:14"
  },
  "impacts": {
    "EF 3.1": {
      "gwp": {
        "A1A2A3": {"mean": 0.87, "unit": "kg CO2 eq", "rsd": 0.20, "dist": "log-normal"}
      },
      "odp": {
        "A1A2A3": {"mean": 3.1e-8, "unit": "kg CFC-11 eq", "rsd": 0.30, "dist": "log-normal"}
      }
    }
  },
  "ext": {
    "chwr": {
      "proxy_provenance": {
        "cascade_step": 3,
        "source_epd_reference": "https://example-registry.invalid/epd/turkish-portland-cement-2023",
        "source_citation": "https://example-registry.invalid/epd/turkish-portland-cement-2023",
        "justification_text": "No domestically verified cement EPD exists for Senegal at time of assessment. Turkish Portland cement is selected as a climate-analogue proxy: both regions share semi-arid climate classification (Koppen BSh/BWh), comparable rotary-kiln dry-process technology, and Turkey's cement sector is a commonly cited African-LCA-literature analogue for West African cement production absent local data (see UNEP GlobalABC Africa material database notes). Grid carbon intensity difference between the two countries is not adjusted in this record; see adaptation_factors for the one applied correction.",
        "adaptation_factors": [
          {
            "field_adapted": "gwp_A1A2A3",
            "from_value": 0.83,
            "to_value": 0.87,
            "method_reference": "Linear grid-intensity scaling, Senegal/Turkey national grid kg CO2/kWh ratio per IPCC EFDB 2024, applied to the electricity-attributable share of A1-A3 GWP only."
          }
        ],
        "pedigree": {
          "reliability": 2,
          "completeness": 2,
          "temporal_correlation": 3,
          "geographical_correlation": 4,
          "further_technological_correlation": 2
        },
        "pedigree_scoring_rubric_version": "v1.0.0",
        "gsd_squared": 1.0,
        "data_geography": "TUR",
        "target_geography": "SEN",
        "climate_analogue_rationale": "Both source and target regions fall within Koppen semi-arid (BSh) to hot-desert (BWh) transitional zones, which is the primary driver of cement curing-water and kiln-fuel-mix comparability assumed here.",
        "review_status": "unreviewed",
        "created_at": "2026-07-10T00:00:00Z",
        "created_by": "sub-chat:openepd-subset-decision",
        "last_modified_at": "2026-07-10T00:00:00Z"
      }
    }
  }
}

8. Versioning and stable URL

Semantic-version tagging for this extension document: v1.0.0 for this initial design, incrementing minor for additive fields, major for any breaking change. Per the Phase 1 IP task in ROADMAP.md, once GitHub Pages/MkDocs deploys, the stable citable URL is:

https://marconeev.github.io/chwr_LCA/data-schema/proxy-provenance-ext/

9. Future compatibility

The extension is namespaced under ext['chwr'], which per the openEPD spec's extension contract is guaranteed non-colliding with anything Building Transparency / C-Change Labs or any PCR committee adds to the core schema or to specs.

Open questions (for the orchestrator, not decided here)

  1. ~~Should peer_review_citation be required at cascade_step >= 4 or >= 5?~~ Resolved: >= 4, per orchestrator decision. Reflected in §3 and §6.
  2. ~~ext namespace key: chwr vs. reverse-domain form?~~ Resolved: chwr, per orchestrator decision. Reflected in §2 and §9.
  3. Basic uncertainty factor table (§5) remains placeholder-only — sourcing the real numeric table via the Ciroth et al. 2016 / Brightway2 cross-check is tracked as a Phase 1 Step 1 sub-chat per orchestrator's ROADMAP note.