Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Expose the person type and the organization type on embedded author references of a document

Aperta
  • Qualcosa non va?
#1,746 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
55/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Tranquilla
Stack tecnologico
javascript, nodejs
Ambito
api

Direzione di ricerca

Start by tracing the GET /api/v1/documents/{id} handler and the serializers or queries that build its embedded person references; compare them with the /cavers/{id} response to locate the existing type field. Check the Swagger Caver and Document schemas as well. Done means the specified document references include matching person types without changing existing fields, and the relevant schemas are updated; organization type is secondary and conditional on the data model.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Priority: Low Type: Feature

Expose the person type and the organization type on embedded author references of a document

Repo: grottocenter-api
Endpoint: GET /api/v1/documents/{id}
Reported by: frontend (grottocenter-front, document detail page)

Summary

The document payload returns its authors as bare identity references. The frontend needs to know what kind of author each entry is, in order to display the right icon:

  • a person can be a real user account (CAVER) or an author placeholder created to credit a non-member (AUTHOR) — two different icons exist in the frontend for these
  • an organization should be displayed with the icon matching its type, when a type exists

The information already exists server-side for persons (GET /cavers/{id} returns type), it is simply dropped when the person is embedded in a document.

Current behaviour (observed on production)

GET /api/v1/documents/20024

"authors": [{ "id": 2343, "nickname": "Martin" }]

GET /api/v1/documents/22507

"authorsOrganization": [
  {
    "id": 63,
    "name": "Spéléo Groupe La Tronche - FLT",
    "language": "fra",
    "isDeleted": false
  }
]

Same trimmed shapes elsewhere in the payload:

Field Current shape
authors[] { id, nickname }
creator { id, nickname }
reviewer { id, nickname }
validator { id, nickname }
authorsOrganization[] { id, name, language, isDeleted }
editor { id, name, language, isDeleted }
library { id, name, language, isDeleted }

Meanwhile GET /api/v1/cavers/{id} does return the discriminator (verified: caver 1895 → "type": "CAVER", caver 33 → "type": "AUTHOR"):

{ "id": 33, "type": "AUTHOR", "nickname": "Unknown", "language": "fra", ... }

Note that this happens in practice on real data: document 20024 has an author of type CAVER (id 2343) but a creator/reviewer/validator of type AUTHOR (id 33) — so the distinction is not cosmetic, it appears within a single document.

Request

1. Add type to embedded person references — main ask

Include the caver type on every person reference embedded in the document payload, using the exact same values as GET /cavers/{id}:

"authors": [{ "id": 2343, "nickname": "Martin", "type": "CAVER" }],
"creator":   { "id": 33,   "nickname": "Unknown", "type": "AUTHOR" },
"reviewer":  { "id": 33,   "nickname": "Unknown", "type": "AUTHOR" },
"validator": { "id": 33,   "nickname": "Unknown", "type": "AUTHOR" }

Enum: CAVER | AUTHOR (if other values exist, please list them — see the spec gap below).

If it is cheap to do so, the same applies to the author / reviewer sub-objects of the embedded descriptions[] and titles[] arrays, for consistency. Not required for this feature.

2. Add the organization type to authorsOrganization[] — secondary ask

We would like the equivalent discriminator for organizations. Today GET /api/v1/organizations/{id} exposes no type or category field — its only discriminator is the boolean isOfficialPartner. So, concretely:

This part is not blocking — point 1 is what we need to ship the correct icons for persons.

Why — frontend impact

The document detail page builds a single author line mixing persons and organizations, with one icon per entry (packages/web-app/src/pages/DocumentDetails/index.jsx:199-227):

...(documentData.authors ?? []).map(a => ({
  id: `caver-${a.id}`,
  name: a.nickname,
  iconType: 'caver',        // ← hardcoded: no way to know if it is an AUTHOR
  url: `/ui/persons/${a.id}`
})),
...(documentData.authorsOrganization ?? []).map(a => ({
  id: `org-${a.id}`,
  name: a.name,
  iconType: 'organization', // ← hardcoded: no organization type available
  url: `/ui/organizations/${a.id}`
}))

Consequences today:

  • every person is rendered with the generic caver icon, including author placeholders — which is misleading, since those are not real accounts (no login, no messaging, no activity). The frontend already owns a dedicated author icon and uses it on the person page (components/appli/Person/Person.jsx:194), where type is available.
  • the only workaround would be one extra GET /cavers/{id} request per author just to resolve an icon — an N+1 fan-out on every document page, which we do not want to do.

Spec gaps noticed along the way

Independently of the change above, the Swagger spec (api.grottocenter.org/api/v1/swagger.yaml) is out of date on these fields:

  • the Document schema documents neither authors nor authorsOrganization, although both are returned by GET /documents/{id}. It still documents a singular author and a massif (the API returns massifs).
  • the Caver schema does not document type, even though it is consistently returned. The frontend currently relies on an undocumented behaviour (there is an explicit code comment saying so in Person.jsx:107-110).

Acceptance criteria

  • GET /documents/{id} returns type on each authors[] entry
  • GET /documents/{id} returns type on creator, reviewer and validator
  • the values are identical to those returned by GET /cavers/{id} (CAVER / AUTHOR)
  • no other change to the existing shapes (purely additive, no field removed or renamed)
  • Swagger updated: Caver.type with its enum, Document.authors, Document.authorsOrganization
  • (secondary) organization type — exposed on authorsOrganization[]

Out of scope / related

GET /documents/{id}/children does not return authors at all today (fields: id, type, title, description, datePublication, dateInscription, dateReviewed, isValidated, isDeleted, files). Nothing to change there — but if authors are ever added to that payload, the same type field should be included.

Lingua principale
JavaScript
Stelle
18
Fork
3
Merge medio
1g 56m
PR unite (30g)
41

Preparare l'ambiente

  • Nessun Dockerfile né file Docker Compose
  • Ha un modello di pull request
  • Nessuna guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di GrottoCenter/grottocenter-api

Tutte le issue di GrottoCenter/grottocenter-api

Issue simili

Altre issue su JavaScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.