Fix TTL/RDF generation, working-with-data.md download links, and publish examples/output - #125
Merged
HendrikBorgelt merged 5 commits intoJul 14, 2026
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Four related fixes, all touching the example-data/documentation pipeline:
working-with-data.mddownload buttons were broken on the real site. The YAML/JSON download links usedhref="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.TTL/RDF generation was actually fixable, not a pre-existing linkml_runtime bug.
linkml-run-examples --output-formats ttlhad 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:unit: GM,unit: PERCENT,unit: g, …) instead of full QUDT URIs.rdflib_dumpertries to resolve everyunitvalue as a URI; a bare code with no colon hitsnamespaces.uri_for()'s "no prefix" branch and raisesUnknown CURIE prefix: @baseinstead of being treated as a plain string.CatalysisDatasetrecords use their published Handle-System identifier asid(e.g.hdl:21.11165/4cat/2d6m-exeb), reference chemical compounds viaCHEBI, and oneCharacterizationuses an eNanoMapper (ENM) term forrdf_type. None ofhdl,CHEBI, orENMwere declared in the root schema'sprefixes:block — they're only declared in vendored chemdcat-ap submodules, which doesn't propagate toSchemaView.namespaces()when the root schema is loaded directly (matching whyCHMO/OBI/NCITare already redundantly declared at the root too).With both fixed,
--output-formats ttlnow succeeds for all 15 example/test files, so it's requested in the_test-examplesrecipe going forward.Published
examples/output/. Its.gitignorerule 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.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 ofhdl/CHEBI/ENMabove) — without them,rdflib_dumpersynthesized placeholderns1/ns2/... prefixes bound to the literal unexpanded CURIE string instead of a real URI. All fixed the same way;.ttloutput is now free of placeholder prefixes.Test plan
just testpasses (39 pytest + schema generation + example validation)linkml-run-examples --output-formats ttlproduces all 15.ttlfiles with zero errors and zero placeholder namespace prefixesmkdocs serve