Harmonize the /lookup and /synonyms response shapes
Nessuno ha ancora preso questa issue.
Valutazione
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Idoneità per principianti
- 38/100
- Tipo di issue
- Funzionalità
- Chiarezza
- Abbastanza chiara
- Stato di attività
- Tranquilla
- Ambito
- api, backend-api-design
Direzione di ricerca
Start by reading the /lookup and /synonyms endpoint implementations and their response models, then inspect documentation/API.md and documentation/Babel.md for the caveats this change would remove. Decide the shared field names, types convention, empty field behavior, extra fields, and not-found response before implementing a Pydantic model. Done means /synonyms has a documented, validated response shape aligned with /lookup, with the breaking change and version bump addressed.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Descrizione
/lookup and /synonyms describe the same concept in two different shapes. Nothing here is wrong on its own, but a client that uses both endpoints has to special-case each one, and every divergence is a thing we have to explain in the API documentation rather than something a user can guess.
This came up while documenting the field lists on the improve-documentation branch — the taxa difference in particular is subtle enough that it needed its own paragraph in documentation/Babel.md.
Divergences
Verified against a local Solr loaded with tests/data/test-synonyms.json. For CHEBI:48407:
// GET /lookup?string=antiparkinson&limit=1
{"curie": "CHEBI:48407", "label": "antiparkinson agent", "synonyms": [...], "taxa": [], "types": ["biolink:NamedThing"]}
// GET /synonyms?preferred_curies=CHEBI:48407
{"curie": "CHEBI:48407", "preferred_name": "antiparkinson agent", "names": [...], "types": ["NamedThing"]}
- Different names for the same field.
labelvspreferred_name, andsynonymsvsnames. typesisbiolink:-prefixed by/lookupand bare by/synonyms. A client joining the two has to normalize the prefix itself.- Absent vs empty.
/lookupbuilds aLookupResultand so always emitstaxa, defaulting to[]./synonymsreturns the raw Solr document, and Solr omits an empty multi-valued field entirely — so the key is missing rather than empty. /synonymsis untyped./lookuphasresponse_model=List[LookupResult];/synonymsisDict[str, Dict], so its shape appears nowhere in the OpenAPI schema and is not validated.- Solr internals leak through
/synonyms.id,_version_andcurie_suffixare implementation detail of the index, not of the concept. - Fields only one endpoint has.
/synonymsreturnsshortest_name_lengthandtaxon_specific, which/lookupdrops;/lookupreturnsscore,highlighting,explainanddebug, which have no meaning for a direct CURIE fetch. - A CURIE that isn't in the index comes back from
/synonymsas{"FAKE:9999": {}}— an empty object rather than an omitted key or an explicit null.
Suggested direction
Give /synonyms a real Pydantic response model and make it return the same view of a concept that /lookup does, keeping the search-only fields (score, highlighting, explain, debug) exclusive to /lookup and dropping the Solr internals. That means picking one name per field and one convention for types.
That is a breaking change for /synonyms consumers, so it probably wants to ride along with a version bump, and it may be worth doing at the same time as #227 (bulk-synonyms) so that a new endpoint isn't added in the old shape.
Worth deciding explicitly rather than by default:
- Which field names win (
label/preferred_name,synonyms/names) - Whether
typesisbiolink:-prefixed everywhere or bare everywhere - Whether absent-vs-empty is normalized in both directions
- Whether
/synonymskeepsshortest_name_lengthandtaxon_specific, and whether/lookupgains them - What a not-found CURIE looks like
Once this is settled, the endpoint-specific caveats in documentation/API.md and the taxa paragraph in documentation/Babel.md can be deleted rather than maintained.
- Lingua principale
- Python
- Stelle
- 5
- Fork
- 4
- Metriche di merge delle PR
- Nessuna PR unita negli ultimi 30g
Preparare l'ambiente
- Include un Dockerfile o un file Docker Compose
- Nessun modello di pull request
- Nessuna guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di NCATSTranslator/NameResolution
-
Difficoltà 5/5 Più di una settimana Idoneità per principianti 35/100
-
Difficoltà 5/5 Più di una settimana Idoneità per principianti 35/100
-
Difficoltà 4/5 3-5 giorni Idoneità per principianti 43/100
-
Difficoltà 3/5 1-2 giorni Idoneità per principianti 66/100
-
Difficoltà 5/5 Più di una settimana Idoneità per principianti 25/100
Tutte le issue di NCATSTranslator/NameResolution
Issue simili
-
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 86/100
benchflow-ai/skillsbench#1090 ·
-
Missing unit tests for human-readable date/time formatters in utils/datetime.pyForse già presa @prabhleen2317 l’ha presa oggi. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 76/100
apache/iceberg-python#4387 ·
I maintainer di solito rispondono entro 1 giorno
-
[BUG] Hermes MCP adapter drops cwd, extra passthrough keys and the SSE transport when writing config.yamlForse già presa @Parth-Vasave l’ha presa oggi. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 76/100
microsoft/apm#3749 · 1 commento ·
I maintainer di solito rispondono entro 1 giorno
-
backend bug
Difficoltà 2/5 1-3 ore Idoneità per principianti 68/100
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
NVIDIA/numba-cuda-mlir#467 · 1 commento ·
I maintainer di solito rispondono entro 3 giorni