Skip to content

Fix TTL/RDF generation, working-with-data.md download links, and publish examples/output - #125

Merged
HendrikBorgelt merged 5 commits into
nfdi4cat:mainfrom
HendrikBorgelt:fix-ttl-output-and-working-with-data-links
Jul 14, 2026
Merged

Fix TTL/RDF generation, working-with-data.md download links, and publish examples/output#125
HendrikBorgelt merged 5 commits into
nfdi4cat:mainfrom
HendrikBorgelt:fix-ttl-output-and-working-with-data-links

Conversation

@HendrikBorgelt

@HendrikBorgelt HendrikBorgelt commented Jul 14, 2026

Copy link
Copy Markdown
Member

Summary

Four related fixes, all touching the example-data/documentation pipeline:

  1. working-with-data.md download buttons were broken on the real site. The YAML/JSON download links used href="assets/examples/..." (no ../), which resolves to /working-with-data/assets/examples/... once mkdocs builds the page — a 404. Fixed to ../assets/examples/..., matching the pattern the doc generator already uses for the sunburst-chart iframes elsewhere.

  2. TTL/RDF generation was actually fixable, not a pre-existing linkml_runtime bug. linkml-run-examples --output-formats ttl had been failing partway through the example set, and a CI comment attributed it to "a pre-existing linkml_runtime bug (rdflib_dumper mishandling certain CURIEs), unrelated to schema content." Traced it to two concrete, fixable causes instead:

    • 124 occurrences across 5 example-data files used bare QUDT unit codes (unit: GM, unit: PERCENT, unit: g, …) instead of full QUDT URIs. rdflib_dumper tries to resolve every unit value as a URI; a bare code with no colon hits namespaces.uri_for()'s "no prefix" branch and raises Unknown CURIE prefix: @base instead of being treated as a plain string.
    • The three real-world CatalysisDataset records use their published Handle-System identifier as id (e.g. hdl:21.11165/4cat/2d6m-exeb), reference chemical compounds via CHEBI, and one Characterization uses an eNanoMapper (ENM) term for rdf_type. None of hdl, CHEBI, or ENM were declared in the root schema's prefixes: block — they're only declared in vendored chemdcat-ap submodules, which doesn't propagate to SchemaView.namespaces() when the root schema is loaded directly (matching why CHMO/OBI/NCIT are already redundantly declared at the root too).

    With both fixed, --output-formats ttl now succeeds for all 15 example/test files, so it's requested in the _test-examples recipe going forward.

  3. Published examples/output/. Its .gitignore rule was recently removed (only the explanatory comment survived) — publishing the json/yaml/ttl round-trip validation output it now produces so it's visible in the repo, and correcting the CI comment that still claimed it was git-ignored.

  4. Added a "Download RDF" button alongside the existing YAML/JSON buttons for each of the 3 real-world datasets on the Working with Data page. Publishing these surfaced 8 more of the same root-schema prefix-propagation gaps (RO, RXNO, qudt, schema, skos, foaf, adms, on top of hdl/CHEBI/ENM above) — without them, rdflib_dumper synthesized placeholder ns1/ns2/... prefixes bound to the literal unexpanded CURIE string instead of a real URI. All fixed the same way; .ttl output is now free of placeholder prefixes.

Test plan

  • just test passes (39 pytest + schema generation + example validation)
  • linkml-run-examples --output-formats ttl produces all 15 .ttl files with zero errors and zero placeholder namespace prefixes
  • Verified the download-link fix and the new RDF button locally via mkdocs serve

The YAML/JSON download buttons linked to assets/examples/... (no ../
prefix), which resolves incorrectly once mkdocs builds the page to
/working-with-data/index.html -- it needs ../assets/examples/... to reach
the sibling assets/ directory, matching the pattern already used by the
sunburst-chart iframes elsewhere in the generated docs.
TTL output (linkml-run-examples --output-formats ttl) was failing partway
through the example set. This was previously assumed to be a pre-existing
linkml_runtime bug unrelated to schema content -- it isn't. Two concrete,
fixable causes:

1. 124 occurrences across 5 example-data files used bare QUDT unit codes
   (e.g. `unit: GM`, `unit: PERCENT`, `unit: g`) instead of full QUDT URIs
   (`unit: https://qudt.org/vocab/unit/GM`). rdflib_dumper tries to resolve
   every `unit` value as a URI/CURIE; a bare code with no colon falls
   through namespaces.uri_for()'s "no prefix" branch, which raises
   "Unknown CURIE prefix: @base" instead of treating it as a plain string --
   a real linkml_runtime rough edge, but only reachable because our data
   had the wrong value shape in the first place.

2. The three real-world CatalysisDataset records use their published
   Handle-System identifier as `id` (e.g. `hdl:21.11165/4cat/2d6m-exeb`),
   and one Characterization uses an eNanoMapper (ENM) term for rdf_type --
   neither `hdl` nor `ENM` was declared in the root schema's prefixes
   block (ENM was only declared in coremeta4cat_characterization_ap.yaml,
   which doesn't propagate to SchemaView.namespaces() the same way class/
   slot definitions do -- matching why CHMO/OBI/NCIT are already
   redundantly declared at the root too). Adds hdl, CHMO, and ENM there.

Verified: `linkml-run-examples --output-formats ttl` now produces all 15
.ttl files with zero errors across the full test/example set.
examples/output/ was recently un-ignored (its .gitignore rule was removed,
leaving only the explanatory comment behind) -- publishing the round-trip
validation output (json + yaml, all 15 test/example files) it now produces
so it's visible in the repo rather than only as a transient CI artifact.

Also regenerates the Python dataclasses/pydantic models, generated schema
docs, Excel workbook, and sunburst charts against the schema/prefix fixes
in the previous commit.
Adds --output-formats ttl to the _test-examples recipe now that the
previous commit's fixes make it succeed cleanly, and updates the CI
comment that used to explain (and justify) skipping it -- also correcting
its now-stale claim that examples/output/ is git-ignored.
Adds a third "Download RDF" button (linking to a .ttl file) alongside the
existing YAML/JSON buttons for each of the 3 real-world datasets on the
Working with Data page.

Publishing these surfaced 8 more namespace prefixes (CHEBI, RO, RXNO,
qudt, schema, skos, foaf, adms) with the same root-schema propagation gap
already fixed for hdl/CHMO/ENM: each is declared in a vendored chemdcat-ap
submodule but wasn't visible to SchemaView.namespaces() when the root
schema is loaded directly, so rdflib_dumper fell back to synthesizing
placeholder ns1/ns2/... prefixes bound to the literal (unexpanded) CURIE
string instead of a real URI. Declaring them at the root too produces
clean, fully-resolved .ttl output with zero placeholder prefixes.

scripts/generate_example_outputs.py now also emits a .ttl per real-world
dataset (via the same rdflib_dumper path used by `just test`), regenerated
docs/assets/examples/ and examples/output/ accordingly.
@HendrikBorgelt
HendrikBorgelt merged commit f1e0bb8 into nfdi4cat:main Jul 14, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant