UPG004 - Required v0.7 field missing¶

Description¶

The v0.6 → v0.7 compat shim encountered a v0.7-required field that is missing from the source v0.6 payload AND cannot be synthesised from any related v0.6 field. The caller MUST provide the value manually before the upgraded payload validates against v0.7.

Category¶

Compat shim (Phase 4 of docs/plans/UNTP_0.7.0_MIGRATION.md).

Severity¶

error — this is the only UPG code that ships at error severity. The migrate CLI refuses to write the upgraded file when any UPG004 fires, regardless of --accept-warnings, because the result is guaranteed not to validate.

Common causes¶

Missing v0.7-required field	Synthesisable from v0.6?	Notes
Envelope `name`	only if `Product.name` is set	Otherwise UPG004; provide a top-level `name` manually.
Envelope `validFrom`	no	Cannot fabricate a date.
`Material.materialType`	no	v0.7 requires a `Classification` object; v0.6 made it optional. Supply a real classification code.
`Material.massFraction`	no	v0.7 requires a numeric value in `[0, 1]`; v0.6 made it optional.

How to fix¶

The shim emits one UPG004 per missing field with a JSONPath locator. Patch the source payload at exactly those paths before re-running the shim:

Python

from dppvalidator.compat import upgrade

# 1. First pass: collect the gaps.
upgraded, warnings = upgrade(payload_v06)
gaps = [w for w in warnings if w.code == "UPG004"]
for w in gaps:
    print(f"{w.path}: needs manual value — {w.message}")

# 2. Patch the source. Example: fill missing materialType.
payload_v06["credentialSubject"]["materialsProvenance"][0]["materialType"] = {
    "type": ["Classification"],
    "schemeId": "https://unstats.un.org/unsd/classifications/Econ/cpc/",
    "schemeName": "UN Central Product Classification",
    "code": "27310",
    "name": "Steel basic shapes",
}

# 3. Second pass: should produce no UPG004s.
upgraded, warnings = upgrade(payload_v06)
assert not any(w.code == "UPG004" for w in warnings)

For pipelines, treat UPG004 as a hard signal: failing data should go back to the producer, not be force-fed into the upgrade.