Harmonize the /lookup and /synonyms response shapes
还没有人认领这个 Issue。
评估
- 难度
- 5/5
- 预计耗时
- 一周以上
- 新手友好度
- 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 文件
- 没有 Pull Request 模板
- 没有贡献指南
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
NCATSTranslator/NameResolution 的其他 Issue
-
难度 5/5 一周以上 新手友好度 35/100
-
难度 5/5 一周以上 新手友好度 35/100
-
难度 4/5 3-5 天 新手友好度 43/100
-
难度 3/5 1-2 天 新手友好度 66/100
-
难度 5/5 一周以上 新手友好度 25/100
查看 NCATSTranslator/NameResolution 的全部 Issue
相似的 Issue
-
难度 2/5 1-3 小时 新手友好度 78/100
huggingface/kernels#1006 ·
维护者通常 1 天内回复
-
precond_kda (new op, #1552) backward kernels hit CUDA illegal memory access on Blackwell under triton 3.3.1, pass under triton 3.7.1可能已有人在做 @YYuJLiu 今天认领。 未关闭
难度 2/5 1-3 小时 新手友好度 76/100
fla-org/flash-linear-attention#1749 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 78/100
bridgecrewio/checkov#7804 ·
维护者通常 2 天内回复
-
area:filesystem bug need-triage
难度 2/5 1-3 小时 新手友好度 85/100
维护者通常 1 天内回复
-
triage/confirmed
难度 2/5 1-3 小时 新手友好度 78/100
agentscope-ai/agentscope#4068 ·
维护者通常 2 天内回复