MHPKG: carry the 2026-09-15 Termboard draft into the schema, with a delta check #62

[jh-RLI]

Summary of the discussion

#62: the new Termboard draft (8922125, 2026-09-15) added parts the LinkML schema did not know, and there was no repeatable way to see the delta between a Termboard export and the schema.

Approach agreed with the maintainer: compare, don't convert. The tool diffs the Termboard JSON export against the schema through a committed mapping file. Every schema change stays a human decision, and the mapping records it. The JSON export is used because the OWL export is not valid RDF/XML (details below).

The loop now

# save the Termboard JSON export as mhpkg/model/schema_<YYYYMMDD>.json, then:
uv run --group schema python mhpkg/model/termboard_delta.py          # what changed?
# edit the schema and/or mhpkg/model/termboard_mapping.yaml, regenerate, then:
uv run --group schema python mhpkg/schema/check_generated.py
uv run --group graph  python mhpkg/schema/validate.py
uv run --group schema python mhpkg/model/termboard_delta.py --check  # exit 0 = everything accounted for

Documented in mhpkg/model/README.md.

What the tool reports

1. unmapped terms and relations
2. mapped names no longer in the export
3. mapping targets that are not in the schema
4. typed drawn edges the schema cannot realise (slot missing on the class, or target outside the slot's range)
5. untyped related to edges with no named counterpart

term_request, deferred and open entries are listed as known and do not fail. Run against the unchanged schema, the 2026-09-15 export produced 13 findings: 3 missing classes, 2 enums, 3 enum values, 2 slots and 3 out-of-range edges. That list was the work for this PR. The tool was also checked with a deliberately broken export and mapping, and every check fired.

Schema changes (2026-09-15 draft)

Termboard	Schema	Term
aggregated inventory analysis	AggregatedInventoryAnalysis	mhpo:MHPO_00020005
greenhouse gas emission value	GreenhouseGasEmissionValue	oeo:OEO_00340065
share	FractionValue	oeo:OEO_00140127
refers to technology / heat generation technology	covers_technology, TechnologyEnum	oeo:OEO_00390101; asserted subclasses of OEO_00020308
has temporal resolution / annual	has_temporal_resolution, TemporalResolutionEnum	oeo:OEO_00000516, oeo:OEO_00020161
tCO2eq	MassUnitEnum.metric_ton	oeo:OEO_00010137
%	FractionUnitEnum.percent	obo:UO_0000187
part of convoi	TERM REQUEST 6	—
has numerator / has denominator	TERM REQUEST 7	—
is about municipality, on behalf of	TERM REQUEST 1 and 3 (already open)	—
has uuid	open — the IRI already is the identity (MH-02, #61)	—
aggregated potential analysis	deferred — the draft gives it no content	—

⚠️ Modelling calls for the people drafting the model

• GreenhouseGasEmissionValue vs carbon dioxide equivalent quantity value (OEO_00140083). The class follows the Termboard name. If every MHPKG emission figure is in tCO2eq, the narrower class may be the better one.
• A share carries its numerator's carrier and year directly, as a stopgap until TERM REQUEST 7 is filed and answered.
• Technology and temporal resolution are optional. WPG Annex 2 does not require either.
• The year floor dropped from 2024 to 1990, because the inventory analysis holds past base years. "2024 or later" still holds inside a target scenario, through the new hand-written mhpkg_context.shacl.ttl.
• For the Termboard board itself: fix the typo tartget scenario indicators, delete an unnamed self-edge on final energy consumption value, and drop the related to edges that duplicate a typed one.

Findings along the way

• 🔴 Termboard's OWL export is not valid RDF/XML, old and new: an owl:Restriction sits inside rdfs:subClassOf rdf:parseType="Resource", and rdflib rejects it.
• 🔴 Some rules depend on the container, and LinkML cannot express them. gen-shacl constrains per class, so "a target-scenario value is ≥ 2024" and "exactly one target scenario" (lost when has_part became sh:or over two classes) now live in a second hand-written shapes file. Removing that file makes exactly the four expected negative cases fail. This is input for MH-07: hand-written companions are a category, not a single exception.
• ✅ TechnologyEnum needs no reasoner. OEO's heat generation technologies are asserted subclasses, unlike energy carriers.
• 🐛 The committed example value IRI value/a878a3a1-… was not what mint_slice.py mints, and no tuple variant reproduced it. It is replaced with the minted value/78153046-….
• 🐛 kassel_valid.ttl recommended pyshacl -s … -s …, the trap validate.py exists to avoid (only the last -s is used). It now points at validate.py.
• 🐛 The root README still called mhpkg a provisional name; the earlier retraction missed that copy.

Verification (local)

• validate.py: valid example CONFORMS; negative control 20 violations, 20 accounted for (cases 1–10 plus 4 documented cascades)
• check_generated.py: generated SHACL matches the schema (494 triples, isomorphic)
• termboard_delta.py --check: exit 0, 9 known and recorded holes
• uv lock --check: OK. mkdocs build --strict: OK. No dependency changes.

Not included: the MHPO pin has moved (34776b6 → ae9e4d3, +18/−4 terms), but none of the new terms is needed here. The delta check is not wired into CI; that belongs with MH-12.

Type of change (CHANGELOG.md)

Added

• mhpkg/model/termboard_delta.py, termboard_mapping.yaml, README.md: the Termboard → schema delta check
• mhpkg/schema/: the 2026-09-15 draft (three classes, two slots, four enums, term requests 6–7), mhpkg_context.shacl.ttl, negative-control cases 8–10

Updated

• has_scenario_year_value floor 2024 → 1990; the example value IRI is now reproducible; the stale provisional-name warning in the root README is removed

Removed

• nothing

Workflow checklist

Automation

Closes #62

PR-Assignee

• 🐙 Follow the workflow in CONTRIBUTING.md
• 📝 Update the CHANGELOG.md
• 📙 Update the documentation

Reviewer

• 🐙 Follow the Reviewer Guidelines
• 🐙 Provided feedback and show sufficient appreciation for the work done

🤖 Generated with Claude Code