Harmonize the /lookup and /synonyms response shapes
Nadie ha tomado este issue todavía.
Evaluación
- Dificultad
- 5/5
- Tiempo estimado
- Más de una semana
- Aptitud para principiantes
- 38/100
- Tipo de issue
- Nueva funcionalidad
- Claridad
- Bastante claro
- Estado de actividad
- Tranquilo
- Área
- api, backend-api-design
Línea de trabajo
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.
Escrito por el modelo de indexación a partir del texto del issue.
Descripción
/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.
- Lenguaje dominante
- Python
- Estrellas
- 5
- Forks
- 4
- Métricas de merge de PR
- Sin PR fusionados en 30 d
Preparar el entorno
- Incluye un Dockerfile o un archivo de Docker Compose
- Sin plantilla de pull request
- Sin guía de contribución
Primeros pasos
- Lee el issue completo y luego la guía de contribución del proyecto.
- Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
- Haz un fork del repositorio y trabaja en una rama.
- Abre un pull request que haga referencia al número del issue.
Más de NCATSTranslator/NameResolution
-
Dificultad 5/5 Más de una semana Aptitud para principiantes 35/100
-
Dificultad 5/5 Más de una semana Aptitud para principiantes 35/100
-
Dificultad 4/5 3-5 días Aptitud para principiantes 43/100
-
Dificultad 3/5 1-2 días Aptitud para principiantes 66/100
-
Dificultad 5/5 Más de una semana Aptitud para principiantes 25/100
Todos los issues de NCATSTranslator/NameResolution
Issues similares
-
Dificultad 1/5 Menos de una hora Aptitud para principiantes 86/100
benchflow-ai/skillsbench#1090 ·
-
Missing unit tests for human-readable date/time formatters in utils/datetime.pyPosiblemente ocupada @prabhleen2317 la tomó hoy. Abierto
Dificultad 2/5 1-3 horas Aptitud para principiantes 76/100
apache/iceberg-python#4387 ·
Los mantenedores suelen responder en 1 día
-
[BUG] Hermes MCP adapter drops cwd, extra passthrough keys and the SSE transport when writing config.yamlPosiblemente ocupada @Parth-Vasave la tomó hoy. Abierto
Dificultad 2/5 1-3 horas Aptitud para principiantes 76/100
microsoft/apm#3749 · 1 comentario ·
Los mantenedores suelen responder en 1 día
-
backend bug
Dificultad 2/5 1-3 horas Aptitud para principiantes 68/100
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 78/100
NVIDIA/numba-cuda-mlir#467 · 1 comentario ·
Los mantenedores suelen responder en 3 días