Harmonize the /lookup and /synonyms response shapes
Chưa có ai nhận issue này.
Đánh giá
- Độ khó
- 5/5
- Thời gian dự kiến
- Hơn một tuần
- Mức phù hợp với người mới
- 38/100
- Loại issue
- Tính năng
- Độ rõ ràng
- Khá rõ ràng
- Mức độ hoạt động
- Ít trao đổi
- Lĩnh vực
- api, backend-api-design
Hướng nghiên cứu
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.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Mô tả
/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.
- Ngôn ngữ chính
- Python
- Star
- 5
- Fork
- 4
- Chỉ số merge pull request
- Không có pull request nào được merge trong 30 ngày
Chuẩn bị môi trường
- Có Dockerfile hoặc tệp Docker Compose
- Không có mẫu pull request
- Không có hướng dẫn đóng góp
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Issue khác của NCATSTranslator/NameResolution
-
Độ khó 5/5 Hơn một tuần Mức phù hợp với người mới 35/100
-
Độ khó 5/5 Hơn một tuần Mức phù hợp với người mới 35/100
-
Độ khó 4/5 3-5 ngày Mức phù hợp với người mới 43/100
-
Độ khó 3/5 1-2 ngày Mức phù hợp với người mới 66/100
-
Độ khó 5/5 Hơn một tuần Mức phù hợp với người mới 25/100
Tất cả issue của NCATSTranslator/NameResolution
Issue tương tự
-
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 86/100
benchflow-ai/skillsbench#1090 ·
-
Missing unit tests for human-readable date/time formatters in utils/datetime.pyCó thể đã có người làm @prabhleen2317 đã nhận hôm nay. Đang mở
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 76/100
apache/iceberg-python#4387 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
[BUG] Hermes MCP adapter drops cwd, extra passthrough keys and the SSE transport when writing config.yamlCó thể đã có người làm @Parth-Vasave đã nhận hôm nay. Đang mở
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 76/100
microsoft/apm#3749 · 1 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
-
backend bug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 68/100
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
NVIDIA/numba-cuda-mlir#467 · 1 bình luận ·
Maintainer thường phản hồi trong vòng 3 ngày