Document where NodeNorm's data comes from, and serve the API docs that were being discarded

[gaurav]

NodeNorm is a thin frontend over data whose complexity is almost entirely Babel's, and that inheritance was undocumented in one direction and stale in the other. This splits the two clearly, and fixes the largest documentation hole in the API along the way.

The division

Three buckets, decided once so it stays decided:

• NodeNorm's own — API surface, response shape, conflation flags and defaults, Redis layout, the loader, deployment. Stays here.
• Babel's, but a user hits it on day one — cliques, preferred identifiers, preferred labels, information content, conflation ordering, descriptions. Stated in full here, in our own words, with a link out. Not truncated to a link, so the docs still stand alone.
• Babel's, and users can find it themselves — how cliques are actually built, per-source ingest, the pipeline, DuckDB exports. One link to Babel's index, then we stop.

The new documentation/Babel.md holds the middle bucket and is deliberately the only file in this repository that links into Babel's docs/ tree. Everything else links to it. A reorganisation on the Babel side now breaks one file instead of twenty.

The OpenAPI fix

construct_open_api_schema() regenerates paths from the route decorators and copies back only info, tags and servers. Everything under paths: in resources/openapi.yml — 235 lines — has therefore never been served to anyone. That included the only written statement of the conflation ordering guarantees ("the gene(s) always appear first", "the active ingredient appears before any formulations") and the /get_setid stability guarantee, neither of which existed anywhere else in the repo.

That prose now lives on the decorators, and the dead block is deleted. Every operation gains a real 200 description instead of FastAPI's default "Successful Response", and /get_normalized_nodes goes from documenting its output as an untyped object to a full schema plus a worked example.

The response models are attached via responses={200: {"model": ...}} rather than response_model=, deliberately — create_node() builds those dicts by hand and omits keys that don't apply, so letting FastAPI filter output through a model risks silently dropping a field the model forgot. Verified response_field is None on both routes: schema documented, serialization untouched.

Also fixed: the MIT license was parsed then dropped from the served schema; apidocs.py called app.openapi_schema() on a dict; CurieList used title= instead of description=, so Swagger showed no help text for any of its fields; and both TRAPI summaries claimed to normalize a "response object".

Stale content corrected

The README's compendia example predated Biolink-prefixed types (chemical_substance, bare PUBCHEM:) and was a normalization response, not a compendium line. Its config.json example listed Redis credentials, which the loader reads only from redis_config.yaml. API.md was missing include_taxa, taxa, all parameter defaults, the biolink_model block from /status, and had a sentence that trailed off after "These methods".

Root path is now recorded as /; the TRAPI-versioned prefixes are deprecated, and the only place one should still appear is the OpenAPI servers block.

Two corrections found by checking rather than trusting

• DrugChemicalSmaller.txt.gz is a SapBERT training export, not a conflation file — so Babel's "only two conflation files" is right, and I dropped a planned edit.
• "NodeNorm reports the lowest IC" was wrong. min(ICs) happens in Babel (src/node.py:443); NodeNorm returns the stored per-clique value unchanged. Corrected in both repos.

Verification

• pytest -m "not integration" — 27 passed, 4 skipped.
• Booted the app and inspected /openapi.json: license, x-translator, x-trapi and the SERVER_ROOT/TRAPI_VERSION server override all still present; all 8 paths carry real descriptions.
• Confirmed by grep that only documentation/Babel.md links into Babel's docs/ tree, and that all six link targets exist.

black was not run: the repo is not black-clean at baseline (10 files, including several this PR never touches), so reformatting would bury the diff. Confirmed these changes add no new violations.

Companion PR

Babel-side fixes are in NCATSTranslator/Babel#973, including correcting its claim that NodeNorm does not use preferred_name.

Follow-ups filed

#398 (drug_chemical_conflate defaults to true on GET but false on POST — a real behavioural inconsistency, documented here as a known divergence), #399 (Retry(method_whitelist=) removed in urllib3 2.0), #400 (no v2.5.x release notes), #401 (docker-compose-redis.yml does not exist), #402 (duplicate handler names, OpenAPI version mismatch).

🤖 Generated with Claude Code

[gaurav]

Pushed a commit here repointing every cross-repo link at main.

NodeNormalization, Babel and NameResolution all default to main now; a /blob/master/ URL resolves only through GitHub's post-rename redirect, which is the kind of thing that disappears quietly. 25 links across five files — the endpoint descriptions in server.py (12), this branch's new Babel.md (6), the /status examples in API.md (2), openapi.yml (2), and the notebook including its Colab badge (3).

Most of them predate this branch; they are here because this is the documentation PR and because #405 is stacked on it and inherits them. raw.githubusercontent.com/biolink/biolink-model/master/... is deliberately untouched — biolink-model really does default to master.

Verified: every rewritten github.com URL returns 200, the notebook is still valid JSON, and tests/frontend passes (22 passed, 4 skipped).

Worth considering as a follow-up: NameRes now has tests/test_docs_links.py::test_no_master_branch_links, which fails CI on both the blob/ and raw.githubusercontent.com forms. Without something like it these drift back.

[gaurav]

Added tests/test_docs_links.py, ported from NameRes so both services enforce the same rules: relative links resolve, heading anchors exist, the API.md anchors used in the endpoint descriptions exist, and nothing is pinned to master. All offline — a link check that fails when GitHub is slow is one people learn to ignore.

It earned its place on the first run: 12 more master links in releases/ that my earlier grep missed, because they use the pre-rename TranslatorSRI org as well as the pre-rename branch, so a pattern looking for NCATSTranslator/<repo>/blob/master/ never saw them. Now NCATSTranslator/Babel/blob/main/; all five distinct targets return 200.

The other three checks passed unchanged, so the whole file came across rather than just the master ban.

tests/frontend is unaffected — 26 passed, 4 skipped here, and 35 passed on #405 once rebased, where the new test also covers skills/nodenorm/SKILL.md.