Basic Importmap support (WIP)

[noelmcloughlin]

There is a chicken-and-egg situation when developing modular LinkML schemas which could be supported better. The issue happens when the LinkML schema has modular design and affects imports and developer lifecycle...

Linkml status

• SchemaLoader bug (impacts multiple generators) -> new issue tbc
• gen-doc bug (does not pass importmap parameter to schemaview) -> new issue tbc
• Requires fix(prefixes): ensure curiemaps are not lost in merged linkml schemas linkml#3575 or fix: merge imported schema prefixes into schema.prefixes (closes #3574) linkml#3580
• Validator issue: Validator should support importmap (or accept a fully-resolved schema without re-resolving imports) linkml#3349 (fixed or not?)

Problem

LinkML imports are resolved by the loader as follows:

1. CURIE expansion via prefixes - for example linkml:/schema/linkml (hypothetical) uses prefix linkml: https://w3id.org/linkml which expands to https://w3id.org/linkml/schema/linkml.
2. Import-map lookup - SchemaLoader supports importmap (CLI flag --importmap PATH) containing key matching the expanded URI (or prefix).
3. Built-in Catalog - linkml:types, etc
4. Filessytem - a string with no schema (i.e. hypothetical ./linkml_sub_schema)
5. HTTP fetch - last resort

The pure URI imports work for consumers only after the URI resolves (w3id.org redirect, GitHub serves the yaml). But at development time, step 5 fails because there are competing requirements

Requirement	Needs
gen-project runs locally	URI must resolve to a file on disk
External LinkML imports <myproject>:/schema/sub_schema.yaml (other variants possible)	URI must resolve to published YAML over HTTPS
Generated artifacts caryy canonical from_schema IRIs	Imports must be expressed as as URIs, not relative paths

A relative import ./sub-schema or ./modules/sub-schema only satisfies first - a bare URI only satisifes second - the mechanism designed to bridge both is LinkML importmap.

importmap

• it is build-time-only indirection. The YAML committed to the repo stays canonical (URI form). No rewriting or hacking after publishing.
• It allows literal subsition ("https://w3id.org/my-awesome-schema/schema/module/sub_schema" -> "src/my_awesome_schema/schema/module/sub_schema.yaml)
• Consumers never see this - they imports resolve via w3id -> Github (or whatever solution they have)
• gen-project, gen-owl, gen-jsonschema, linkml-lint, linkml-convert, etc all accept `--importmap.

solution here

So it would be great to support importmap out of the box - should work for everyone.

Add template/importmap.json.jinja with two entries (schemaloader expects no trailing colon, shcemaview map_import expects trailing colon. Add both keys for safety.

{
    "{{project_slug}": "src/{project_slug}",
    "{{project_slug}:": "src/{project_slug}"
}

Update config.yaml and config.public.mk to pass importmap: importmap.json to each generator.

Workaround

Various local hacks needed.