{"id":"linked-art/api/search","relativePath":"linked-art/api/search.md","title":"Linked Art API: Search","markdown":"# Linked Art API: Search\n\n**Last refreshed:** 2026-07-07\n\nSource: [Search API](https://linked.art/api/1.0/search/), part of Linked Art API 1.0, published by the Linked Art Editorial Board under [CC BY 4.0](http://creativecommons.org/licenses/by/4.0/). This is a project summary; the upstream page is authoritative.\n\n## Purpose\n\nLinked 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.\n\nThe important design boundary is:\n\n- Entity records hold semantic Linked Art assertions.\n- HAL `_links` advertise named search affordances.\n- Search targets return result pages in a predictable `OrderedCollectionPage` shape.\n- The URI behind a search link is implementation-defined; only the response contract matters.\n\n## Referring Record Links\n\nNamed 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.\n\nThe expanded relation documentation is captured in [HAL](hal.md), including the complete upstream relation inventory and Meta Museum's currently implemented relation-search subset.\n\n## Result Page Shape\n\nLinked Art search result pages use the ActivityStreams-style collection pattern also familiar from IIIF and Web Annotation.\n\nRequired page fields:\n\n- `@context`: must be `https://linked.art/ns/v1/search.json`.\n- `id`: URI of the result page.\n- `type`: must be `OrderedCollectionPage`.\n- `partOf`: embedded `OrderedCollection` metadata for the total result set.\n- `orderedItems`: array of result references, each with at least `id` and `type`.\n\nConditional/recommended page fields:\n\n- `next`: present unless this is the last page.\n- `prev`: present unless this is the first page.\n- `startIndex`: recommended zero-based index of the first item in the overall collection.\n\n## Collection Shape\n\nThe embedded `partOf` collection should identify the overall result set.\n\nCollection fields:\n\n- `id`: URI of the collection.\n- `type`: must be `OrderedCollection`.\n- `first`: first result page reference.\n- `last`: last result page reference.\n- `totalItems`: recommended total count.\n- `label`: optional language-map label.\n- `summary`: optional language-map summary.\n\nIf the collection is requested separately, it must include the search context. When embedded in a page, it should not repeat `@context`.\n\n## Meta Museum Notes\n\nMeta Museum already uses the Linked Art Search API pattern in two main ways:\n\n- `/api/search` and provider search routes return `OrderedCollectionPage` results with stable pagination fields and result references.\n- `/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.\n\nThe 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.\n\n## Test Ideas\n\n- Extend official `next`/`prev`, `startIndex`, and `partOf.first`/`partOf.last` coverage from `/api/search` and `/api/relations/{relation}` to provider-specific search routes.\n- Assert relation links are omitted from entity `_links` when no matching records exist.\n- 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.\n","sections":[{"level":2,"heading":"Purpose","anchor":"purpose"},{"level":2,"heading":"Referring Record Links","anchor":"referring-record-links"},{"level":2,"heading":"Result Page Shape","anchor":"result-page-shape"},{"level":2,"heading":"Collection Shape","anchor":"collection-shape"},{"level":2,"heading":"Meta Museum Notes","anchor":"meta-museum-notes"},{"level":2,"heading":"Test Ideas","anchor":"test-ideas"}],"html":"<h1 id=\"linked-art-api-search\">Linked Art API: Search</h1>\n<p><strong>Last refreshed:</strong> 2026-07-07</p>\n<p>Source: <a href=\"https://linked.art/api/1.0/search/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"doc-link\">Search API</a>, part of Linked Art API 1.0, published by the Linked Art Editorial Board under <a href=\"http://creativecommons.org/licenses/by/4.0/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"doc-link\">CC BY 4.0</a>. This is a project summary; the upstream page is authoritative.</p>\n<h2 id=\"purpose\">Purpose</h2>\n<p>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.</p>\n<p>The important design boundary is:</p>\n<ul><li>Entity records hold semantic Linked Art assertions.</li><li>HAL `_links` advertise named search affordances.</li><li>Search targets return result pages in a predictable `OrderedCollectionPage` shape.</li><li>The URI behind a search link is implementation-defined; only the response contract matters.</li></ul>\n<h2 id=\"referring-record-links\">Referring Record Links</h2>\n<p>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.</p>\n<p>The expanded relation documentation is captured in HAL(hal.md), including the complete upstream relation inventory and Meta Museum&#39;s currently implemented relation-search subset.</p>\n<h2 id=\"result-page-shape\">Result Page Shape</h2>\n<p>Linked Art search result pages use the ActivityStreams-style collection pattern also familiar from IIIF and Web Annotation.</p>\n<p>Required page fields:</p>\n<ul><li>`@context`: must be `https://linked.art/ns/v1/search.json`.</li><li>`id`: URI of the result page.</li><li>`type`: must be `OrderedCollectionPage`.</li><li>`partOf`: embedded `OrderedCollection` metadata for the total result set.</li><li>`orderedItems`: array of result references, each with at least `id` and `type`.</li></ul>\n<p>Conditional/recommended page fields:</p>\n<ul><li>`next`: present unless this is the last page.</li><li>`prev`: present unless this is the first page.</li><li>`startIndex`: recommended zero-based index of the first item in the overall collection.</li></ul>\n<h2 id=\"collection-shape\">Collection Shape</h2>\n<p>The embedded `partOf` collection should identify the overall result set.</p>\n<p>Collection fields:</p>\n<ul><li>`id`: URI of the collection.</li><li>`type`: must be `OrderedCollection`.</li><li>`first`: first result page reference.</li><li>`last`: last result page reference.</li><li>`totalItems`: recommended total count.</li><li>`label`: optional language-map label.</li><li>`summary`: optional language-map summary.</li></ul>\n<p>If the collection is requested separately, it must include the search context. When embedded in a page, it should not repeat `@context`.</p>\n<h2 id=\"meta-museum-notes\">Meta Museum Notes</h2>\n<p>Meta Museum already uses the Linked Art Search API pattern in two main ways:</p>\n<ul><li>`/api/search` and provider search routes return `OrderedCollectionPage` results with stable pagination fields and result references.</li><li>`/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.</li></ul>\n<p>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.</p>\n<h2 id=\"test-ideas\">Test Ideas</h2>\n<ul><li>Extend official `next`/`prev`, `startIndex`, and `partOf.first`/`partOf.last` coverage from `/api/search` and `/api/relations/{relation}` to provider-specific search routes.</li><li>Assert relation links are omitted from entity `_links` when no matching records exist.</li><li>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.</li></ul>","updatedAt":"2026-07-07T00:00:00.000Z","checksum":"fe2301e3ac01fd205490588cd13dc4b2b07e4db964ad4fb4cd78e06f98e36657","checksumPrefix":"fe2301e3ac01","anchorCount":6,"lineCount":72,"rawUrl":"/api/docs/content?path=linked-art%2Fapi%2Fsearch.md","htmlUrl":"/docs?doc=linked-art%2Fapi%2Fsearch.md","apiUrl":"/api/docs/content?path=linked-art%2Fapi%2Fsearch.md"}