CenterForDigitalHumanities / CenterForDigitalHumanities/rerum_server_nodejs

Expansion drops Annotations that carry multiple bodies

Offen
#288 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
Vorherrschende Sprache
JavaScript
Sterne
3
Forks
6
Ø Merge
2 T. 47 Min.
Gemergte PRs (30 T.)
4

Beschreibung

Split out of the static review of #286 so it does not block that PR.

## What happens now

`assertionsFrom()` in `controllers/crud.js` returns early on an Array `body`:

```javascript
if (!body || typeof body !== "object" || Array.isArray(body)) return assertions
```

An Annotation carrying multiple bodies is still **gathered** by `findLeafAnnotationsFor()` and still **counted** in the `Annotations-Merged` response header, but contributes nothing to the expanded entity. From the client's side that reads as a nonzero merge count with no merged data.

`expand()` in `controllers/gog.js` now skips them explicitly too (added in #286 — previously a one element Array body merged onto the entity under the key `"0"`).

## Why it matters

The W3C model explicitly allows multiple bodies, and each element is usually an ordinary single-key assertion rather than a structural construct. Real examples already in `annotationStore.alpha`:

```json
[{"contributor":{"label":"Dunbar, Paul Laurence","id":"http://viaf.org/viaf/76335432"}},
{"issued":"1895-04-17"},
{"identifier":"Box 1, F1"},
{"uri":"https://udspace.udel.edu/handle/..."}]
```

## Current impact: none

Measured against production at the time of the #286 review:

- 911 leaf Annotations have an Array `body`
- **0** of them target a `rerum.io/v1/id/` URI under any of the six keys in `TARGET_KEYS`

Since `/v1/id/:_id/expanded` only expands RERUM-stored entities, nothing reachable through the endpoint is affected today. This is a gap that surfaces the first time an app writes a multi-body Annotation onto a RERUM entity.

## Possible approach

Each element is typically itself a single assertion, so the existing logic handles them if it recurses:

```javascript
if (Array.isArray(body)) {
for (const one of body) assertions.push(...assertionsFrom({ body: one }))
return assertions
}
```

Worth deciding at the same time:

- whether `Annotations-Merged` should count Annotations gathered or Annotations that actually contributed an assertion
- whether `controllers/gog.js` `expand()` should follow, or stay on single-body-only for its DEER-shaped `valueObject` wrapping

## Related

Multi-key **object** bodies (not Arrays) are also dropped whole rather than partially, by the `keys.length !== 1` check. Only 1 such document exists in production, so it was not worth acting on separately, but it is the same design question.

## Reference

- W3C Web Annotation Data Model, multiple bodies: https://www.w3.org/TR/annotation-model/#multiple-bodies

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Beginne mit controllers/crud.js und assertionsFrom(), untersuche anschließend controllers/gog.js expand(), findLeafAnnotationsFor() sowie die Verarbeitung der Annotations-Merged-Antwort. Kläre, wie Array-Bodies und Bodies von Objekten mit mehreren Schlüsseln behandelt werden sollen, und stelle sicher, dass Expansion und Merge-Anzahl übereinstimmen; das Payload nennt keinen Testpfad, daher sollte die Umsetzung eine Abdeckung des beschriebenen Verhaltens umfassen.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
javascript
Bereich
api, backend
Issue-Typ
Bug
Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Aktivitätsstatus
Ruhig
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
48/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.