Skip to content

Expansion drops Annotations that carry multiple bodies #288

Description

@thehabes

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:

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:

[{"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:

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions