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
Split out of the static review of #286 so it does not block that PR.
What happens now
assertionsFrom()incontrollers/crud.jsreturns early on an Arraybody:An Annotation carrying multiple bodies is still gathered by
findLeafAnnotationsFor()and still counted in theAnnotations-Mergedresponse 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()incontrollers/gog.jsnow 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:
bodyrerum.io/v1/id/URI under any of the six keys inTARGET_KEYSSince
/v1/id/:_id/expandedonly 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:
Worth deciding at the same time:
Annotations-Mergedshould count Annotations gathered or Annotations that actually contributed an assertioncontrollers/gog.jsexpand()should follow, or stay on single-body-only for its DEER-shapedvalueObjectwrappingRelated
Multi-key object bodies (not Arrays) are also dropped whole rather than partially, by the
keys.length !== 1check. Only 1 such document exists in production, so it was not worth acting on separately, but it is the same design question.Reference