Last refreshed: 2026-07-07
Source: Search API, part of Linked Art API 1.0, published by the Linked Art Editorial Board under CC BY 4.0. This is a project summary; the upstream page is authoritative.
Purpose
Linked Art keeps each relationship asserted in one record rather than duplicating inverse fields everywhere. The Search API supplies the discovery layer that lets clients find those inverse or referring records by following HAL links instead of inventing their own query grammar.
The important design boundary is:
- Entity records hold semantic Linked Art assertions.
- HAL `_links` advertise named search affordances.
- Search targets return result pages in a predictable `OrderedCollectionPage` shape.
- The URI behind a search link is implementation-defined; only the response contract matters.
Referring Record Links
Named relation links live in the `_links` block defined by the HAL notes. Names are camelCase and combine the current record class, relationship, and returned class. If there are no records participating in that relationship, the relation link should not be present. This prevents clients from issuing unnecessary empty-result requests and keeps followable links meaningful.
The expanded relation documentation is captured in HAL(hal.md), including the complete upstream relation inventory and Meta Museum's currently implemented relation-search subset.
Result Page Shape
Linked Art search result pages use the ActivityStreams-style collection pattern also familiar from IIIF and Web Annotation.
Required page fields:
- `@context`: must be `https://linked.art/ns/v1/search.json`.
- `id`: URI of the result page.
- `type`: must be `OrderedCollectionPage`.
- `partOf`: embedded `OrderedCollection` metadata for the total result set.
- `orderedItems`: array of result references, each with at least `id` and `type`.
Conditional/recommended page fields:
- `next`: present unless this is the last page.
- `prev`: present unless this is the first page.
- `startIndex`: recommended zero-based index of the first item in the overall collection.
Collection Shape
The embedded `partOf` collection should identify the overall result set.
Collection fields:
- `id`: URI of the collection.
- `type`: must be `OrderedCollection`.
- `first`: first result page reference.
- `last`: last result page reference.
- `totalItems`: recommended total count.
- `label`: optional language-map label.
- `summary`: optional language-map summary.
If the collection is requested separately, it must include the search context. When embedded in a page, it should not repeat `@context`.
Meta Museum Notes
Meta Museum already uses the Linked Art Search API pattern in two main ways:
- `/api/search` and provider search routes return `OrderedCollectionPage` results with stable pagination fields and result references.
- `/api/relations` and `/api/relations/{relation}?current=...` expose named HAL relation-search discovery, relation/current metadata, conformance links, and `OrderedCollectionPage` results for indexed Linked Art relationship families.
The canonical `/api/search` route and `/api/relations/{relation}` now emit the official Search API fields `next`, `prev`, `startIndex`, and `partOf.first`/`partOf.last` while preserving the older `nextPage`/`prevPage` string fields for compatibility. Provider-specific search routes still have mixed legacy coverage and should be normalized opportunistically as each provider route is touched.
Test Ideas
- Extend official `next`/`prev`, `startIndex`, and `partOf.first`/`partOf.last` coverage from `/api/search` and `/api/relations/{relation}` to provider-specific search routes.
- Assert relation links are omitted from entity `_links` when no matching records exist.
- Keep relation-search result items as references with `id` and `type`; do not inflate them into full records unless a separate embedding option is explicitly documented.