Harmonize the /lookup and /synonyms response shapes

オープン
#291 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
38/100
issue の種類
機能追加
明瞭さ
おおむね明確
活発さ
静か
技術スタック
fastapi, python

調査の方向性

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"]}
  1. Different names for the same field. label vs preferred_name, and synonyms vs names.
  2. types is biolink:-prefixed by /lookup and bare by /synonyms. A client joining the two has to normalize the prefix itself.
  3. Absent vs empty. /lookup builds a LookupResult and so always emits taxa, defaulting to []. /synonyms returns the raw Solr document, and Solr omits an empty multi-valued field entirely — so the key is missing rather than empty.
  4. /synonyms is untyped. /lookup has response_model=List[LookupResult]; /synonyms is Dict[str, Dict], so its shape appears nowhere in the OpenAPI schema and is not validated.
  5. Solr internals leak through /synonyms. id, _version_ and curie_suffix are implementation detail of the index, not of the concept.
  6. Fields only one endpoint has. /synonyms returns shortest_name_length and taxon_specific, which /lookup drops; /lookup returns score, highlighting, explain and debug, which have no meaning for a direct CURIE fetch.
  7. A CURIE that isn't in the index comes back from /synonyms as {"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 types is biolink:-prefixed everywhere or bare everywhere
  • Whether absent-vs-empty is normalized in both directions
  • Whether /synonyms keeps shortest_name_length and taxon_specific, and whether /lookup gains 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 ファイルあり
  • プルリクエストのテンプレートなし
  • コントリビューションガイドなし

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

NCATSTranslator/NameResolution のほかの issue

NCATSTranslator/NameResolution の issue をすべて見る

似ている issue

Python の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。