Add HDMF ↔ LinkML mapping conventions and the base.yaml / CSRMatrix fixtures

[rly]

Fixes #1487
Fixes #1488

Motivation

This adds the initial HDMF ↔ LinkML mapping conventions document together with the hand-authored LinkML translation of a minimal test namespace that applies them, the first two deliverables of the "Read and write LinkML schema for HDMF (CSRMatrix / base.yaml)" epic (#1486). Before any reader or writer is built, we need an agreed, written contract for how HDMF Schema Language (HDMFSL) constructs map to LinkML, and fixtures that prove the contract is real.

The two were originally separate issues. They are combined here because a conventions document that nothing has ever parsed is not a verifiable deliverable, and because running the conventions through linkml-runtime changed several of them. Fixing the doc before it merges is cheaper than amending it right after.

The scope is the constructs used by base.yaml (Data, Container, SimpleMultiContainer) and sparse.yaml (CSRMatrix), packaged as a minimal test namespace. What is out of scope is listed explicitly so the doc is not mistaken for a complete mapping.

What is here

• docs/source/linkml_mapping.rst, added to the "Resources" toctree.
• LinkML fixtures in tests/unit/linkml_tests/fixtures/: namespace.yaml, base.yaml, sparse.yaml, and the companion hdmf-linkml-types.yaml defining the HDMFSL dtypes.
• A new linkml optional dependency group (linkml-runtime), wired into all, tox.ini, and the coverage workflow. The core install is unaffected and the tests skip when it is absent.
• tests/unit/linkml_tests/test_fixtures.py: the fixtures load under SchemaView, every range resolves, the dtype schema covers DtypeHelper.valid_primary_dtypes, and every field of the Spec objects HDMF loads natively from hdmf-common is present in the LinkML.

The coverage tests walk the natively loaded Spec objects rather than a hand-copied expectation, so a change to base.yaml or sparse.yaml that the fixtures do not follow fails here. The worked examples in the doc are literalincludes of the fixture files, so the documented example cannot drift from what is tested.

Conventions that changed once they were run through linkml-runtime

• The name identifier slot is declared once at each hierarchy root (Data, Container) and inherited via is_a. LinkML permits at most one identifier per class, so redeclaring it on every subclass was redundant.
• Every HDMFSL dtype string is its own named type, synonyms included. Spec stores whichever spelling the schema used, so collapsing uint onto uint32 would rewrite the dtype on the way back and break the comparison. A synonym's typeof points at its primary, which records the synonym relationship in LinkML itself.
• float, double, date, and datetime are reused from linkml:types rather than redefined. They collide by name with LinkML built-ins whose semantics agree (xsd:float is 32 bit, xsd:double is 64 bit), and redefining them would shadow the built-ins for every schema in the import closure.
• required is always written explicitly on an attribute slot. HDMFSL defaults an attribute to required while LinkML defaults a slot to optional, so an omitted required would flip the meaning.
• Spec subclasses dict and inherits dict equality, so the comparison is over the keys actually present. The doc now states the two consequences for the reader: defaults stay absent (no quantity: 1, no explicit default required), and order within attributes / datasets / groups is preserved.
• Includes carry the HDMFSL doc as the slot description. The original example dropped it.
• Fixed name and default_name on a type map to equals_string and ifabsent on the identifier slot. Issue Define the initial HDMF → LinkML mapping conventions #1487 asked for these; neither is exercised by the types in scope, so both are stated as the convention.
• AnyType is called out as the one class range that does not mean a data_type_inc.

How to test the behavior

pytest tests/unit/linkml_tests/
cd docs && sphinx-build -b html -W source _build/html

Verified: 14 tests pass (40 subtests), the full unit suite passes (1979 passed), the tests skip cleanly when linkml-runtime is not installed, ruff and codespell are clean, and the docs build with -W and 0 warnings.

Checklist

• Did you update CHANGELOG.md?
• Does the PR clearly describe the problem and the solution?
• Have you reviewed the Contributing Guide?
• Does the PR use "Fix #XXX" notation?

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.16%. Comparing base (7c8d91c) to head (449ba38).

Additional details and impacted files

@@           Coverage Diff           @@
##              dev    #1492   +/-   ##
=======================================
  Coverage   93.16%   93.16%           
=======================================
  Files          41       41           
  Lines       10259    10259           
  Branches     2122     2122           
=======================================
  Hits         9558     9558           
  Misses        422      422           
  Partials      279      279           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[rly]

@jwbear This is an initial pass of a document that describes the mapping between HDMF Schema Language and LinkML. Please translate sparse.yaml from the HDMF Common namespace into LinkML following these conventions, and add the translated yaml into the doc. If anything is not clear, please ask, and then we should probably clarify the doc. Your fresh eyes looking at this doc will be invaluable is assessing whether it is clear and comprehensive. I suggest we tackle this together with pair programming this week after you are familiar with the task. We can coordinate over Slack.

[jwbear]

@rly This is a nice reference, but in a CR isn't readily testable or verifiable. It might be helpful if you changed each of the actual requirements into a method stub or unit test that can be run to validate local criteria before a full compilation.