CenterForDigitalHumanities / CenterForDigitalHumanities/rerum_server_nodejs

Expansion drops Annotations that carry multiple bodies

Open
#288 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
3
Forks
6
Avg merge
1h 25m
Merged PRs (30d)
3

Description

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

Contributor guide

Open the contributing guide

Research direction

Start with controllers/crud.js and assertionsFrom(), then inspect controllers/gog.js expand(), findLeafAnnotationsFor(), and the Annotations-Merged response handling. Resolve how array and multi-key object bodies should be treated and ensure expansion and the merge count agree; the payload names no test path, so completion should include coverage for the described behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
api, backend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.