Every value is a row in provenance

Provenance is a side table, not a footnote. For each cell in the variant row, there is a row in provenance recording source, URL, source class (the source's category — government, manufacturer, aggregator, community, derived, or manual — taken verbatim from the source registry), and applicable model-year range. Designed to defend a value under PCAF limited-assurance review.

Provenance row shape

Each provenance row is keyed by (variant_id, field_name) and carries the citation envelope. A value like co2_combined_g_km = 182 for the 2026 BMW 530i xDrive Sedan looks like this on the wire:

provenance row, variant 95124, co2_combined_g_kmjson

{
  "variant_id": 95124,
  "field_name": "co2_combined_g_km",
  "value_text": 182,
  "source": "transport-canada",
  "source_url": "https://open.canada.ca/data/en/dataset/98f1a129-f628-4ce4-b24d-6f16bf24dd64",
  "source_class": "government",
  "applies_to_year_start": 2026,
  "applies_to_year_end": 2026,
  "pcaf_data_quality_score": 2,
  "ingest_run_id": 18472,
  "fetched_at": "2026-04-12T08:14:22Z"
}

Every spec column on variants has at least one row in provenance. Values without provenance are not exported. ingest_run_id is FK to a row in ingest_runs; every write is attributable to a logged run. source_class is not a physical column on the provenance table — it is derived from sources.source_type at serving time.

Cross-source conflict resolution

Multiple sources frequently disagree on the same field. Three regulators publish slightly different CO₂ values for the same variant, or a manufacturer press release supersedes an earlier EEA submission. We resolve conflicts deterministically through the effective_value() SQL function:

effective_value() priority · pseudocodesql

SELECT value
FROM provenance p
WHERE p.variant_id = ? AND p.field_name = ?
ORDER BY
  field_source_policy.policy_rank NULLS LAST,  -- ascending: lower rank wins; explicit per-field overrides
  source_priority DESC NULLS LAST,  -- tier defaults (gold > silver)
  fetched_at DESC,               -- recency tiebreaker
  id ASC                        -- final deterministic tiebreaker
LIMIT 1;

The Apex API and snapshot exports both use effective_value(). A variant fetch (GET /v1/apex/{id}) returns the resolved value with an inline _provenance subtree showing the winning citation per field — no separate call required. The _provenance map is keyed by field name; each entry is shaped:

_provenance map (inline on every /v1/apex response)json

{
  "co2_combined_g_km": {
    "source":                "transport-canada",
    "source_url":            "https://open.canada.ca/data/en/...",
    "source_class":          "government",
    "match":                 "exact",
    "pcaf_dq":               2,
    "applies_to_year_start": 2026,
    "applies_to_year_end":   2026
  }
}

The inline map carries only the winning citation per field. The full candidate set — including superseded and non-winning (“suppressed”) values — is available in the downloadable snapshot's provenance table, where superseded rows carry an ISO timestamp in superseded_at. Sources without commercial-use clearance are excluded from both the inline map and the shipped snapshot provenance table.

PCAF Data-Quality Score (1–5)

Per the PCAF Standard motor-vehicle-loans methodology (Part A, December 2025), every value carries a DQ score from 1 (highest quality, audited) to 5 (industry-average proxy). Apex assigns the score per row based on source category, not per-portfolio:

score	band	when assigned	sources
1	third-party audited	Reserved. Requires an independent auditor's attestation of the value at row-level. We don't currently ship Score-1 rows.	—
2	regulator-verified primary	Source is a regulator's published value (EEA, EPA, NHTSA, KBA, ADEME, etc.) or an OEM's press kit citing a tested figure.	regulator · manufacturer press · collection card
3	corroborated / derived	Source is a knowledge graph (Wikidata / Wikipedia / OpenEV) with cross-source agreement, OR an Apex derivation from a Score-2 input (e.g., kW ↔ HP unit conversion).	wikidata · wikipedia-* · apex-derived
4	single-source estimate	Single non-regulator source, or a regression estimate from related fields. Honest fallback when nothing better exists.	regression · single-secondary · inferred
5	industry average	Reserved for cases where the value is a class/segment average (e.g., 'average BEV in this segment'). We don't currently ship Score-5 rows.	—

Score 1 is reserved. PCAF defines Score 1 as third-party-audited. Apex ships Score-2 inputs; portfolio-specific Score-1 attestation is the audit firm's engagement, not the data vendor's.

Coverage gaps are visible by design

A field missing on a variant is a missing field — not a zero, not an imputed value. The exception is fields that don't apply to a powertrain (e.g., battery_capacity_gross_kwh on an ICE variant), explicitly NULL rather than a fabricated zero.

The live coverage matrix publishes per-field × per-segment coverage on every snapshot. The gap-statement section on that page is updated each release.

Audit trail

PCAF limited-assurance engagements typically require: (1) the value, (2) the source URL, (3) the fetch timestamp, (4) the applies-to-year range, and (5) the DQ score. All five travel with every row.

Connect this provenance model to the canonical vehicle data API evaluation before testing the sample or planning an integration.