Harmonize the /lookup and /synonyms response shapes
まだ誰も着手していません。
評価
- 難易度
- 5/5
- 見積もり時間
- 1週間以上
- 初心者へのやさしさ
- 38/100
- issue の種類
- 機能追加
- 明瞭さ
- おおむね明確
- 活発さ
- 静か
調査の方向性
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.
索引モデルが issue の本文から書いたものです。
説明
/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.
- 主要言語
- Python
- スター
- 5
- フォーク
- 4
- PR マージ指標
- 30日以内にマージされた PR はありません
環境構築
- Dockerfile または Docker Compose ファイルあり
- プルリクエストのテンプレートなし
- コントリビューションガイドなし
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
NCATSTranslator/NameResolution のほかの issue
-
難易度 5/5 1週間以上 初心者へのやさしさ 35/100
-
難易度 5/5 1週間以上 初心者へのやさしさ 35/100
-
難易度 4/5 3〜5日 初心者へのやさしさ 43/100
-
難易度 3/5 1〜2日 初心者へのやさしさ 66/100
-
難易度 5/5 1週間以上 初心者へのやさしさ 25/100
NCATSTranslator/NameResolution の issue をすべて見る
似ている issue
-
難易度 1/5 1時間未満 初心者へのやさしさ 86/100
benchflow-ai/skillsbench#1090 ·
-
Missing unit tests for human-readable date/time formatters in utils/datetime.py対応中かも @prabhleen2317 が今日担当しました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 76/100
apache/iceberg-python#4387 ·
メンテナーはふだん 1 日以内に返信
-
[BUG] Hermes MCP adapter drops cwd, extra passthrough keys and the SSE transport when writing config.yaml対応中かも @Parth-Vasave が今日担当しました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 76/100
microsoft/apm#3749 · コメント 1 件 ·
メンテナーはふだん 1 日以内に返信
-
backend bug
難易度 2/5 1〜3時間 初心者へのやさしさ 68/100
-
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
NVIDIA/numba-cuda-mlir#467 · コメント 1 件 ·
メンテナーはふだん 3 日以内に返信