{"id":"linked-art/api/discovery","relativePath":"linked-art/api/discovery.md","title":"Linked Art API: Discovery","markdown":"# Linked Art API: Discovery\n\n**Last refreshed:** 2026-07-07\n\nSource: [Discovery APIs](https://linked.art/api/1.0/discovery/), 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 Discovery describes how other web pages, APIs, and harvesters can find Linked Art records. It covers two complementary patterns:\n\n- HTML-to-data signposting for clients that start from a public human page.\n- Harvesting and synchronization through IIIF Change Discovery-style activity streams.\n\n## HTML Data Visibility\n\nPublic HTML pages should expose a machine-readable Linked Art record with `describedby` links.\n\nFor HTTP responses, the preferred signpost is a `Link` header:\n\n```http\nLink: ; rel=\"describedby\"; type=\"application/ld+json;profile='https://linked.art/ns/v1/linked-art.json'\"\n```\n\nFor browser-facing HTML, the page head must include exactly one matching link:\n\n```html\n\n```\n\nThe one-link rule matters: if an HTML page advertises more than one Linked Art record, clients cannot know which JSON-LD record describes the page.\n\nLinked Art notes that this pattern follows the FAIR Signposting Profile.\n\n## Harvesting\n\nFor harvestable synchronization, Linked Art points to the IIIF Change Discovery API. Linked Art record classes can be made available in the change stream by adding the Linked Art record-types context alongside the IIIF discovery context:\n\n```json\n{\n \"@context\": [\n \"https://linked.art/ns/v1/record-types.json\",\n \"http://iiif.io/api/discovery/1/context.json\"\n ]\n}\n```\n\nThat lets entries describe Linked Art records directly, for example an `Update` whose `object.type` is `HumanMadeObject`.\n\n## Meta Museum Notes\n\nMeta Museum already has substantial Discovery coverage:\n\n- Public artwork and entity pages expose exactly one canonical `rel=\"describedby\"` link using the Linked Art profile media type constant.\n- Dereferenced record responses expose canonical Linked Art JSON-LD record URLs and align `_links.self.href` with record IDs.\n- Activity feed responses provide ActivityStreams and IIIF Change Discovery-compatible synchronization layers through `/api/activity`, `/api/activity/collection`, and `/api/activity/page/{page}`.\n- `/api/providers/capabilities` advertises activity-syndication endpoints and callback-signing metadata for follow-your-nose consumer setup.\n- Dataset reuse discovery is advertised through capabilities and dataset distribution metadata, with format URLs, checksums, and license links.\n\nThe main refinement opportunity is to extend the HTML signposting guard from in-page `` declarations to HTTP response headers where Next route/page mechanics make that practical. The current tests already prove the one-canonical-HTML-link requirement; a future route-level smoke should also prove a `Link: rel=\"describedby\"` header on public HTML responses.\n\n## Test Ideas\n\n- Keep the existing one-canonical-`describedby` HTML link test for public record pages.\n- Add route-level smoke for `Link` response headers on public object/entity HTML pages.\n- Assert the `describedby` link uses `application/ld+json;profile=\"https://linked.art/ns/v1/linked-art.json\"`.\n- Assert ActivityStreams collection responses include Linked Art/IIIF discovery contexts when exposing Linked Art object types.\n- Assert capabilities discovery points clients to dataset distributions, activity feeds, and callback registration without out-of-band URLs.\n","sections":[{"level":2,"heading":"Purpose","anchor":"purpose"},{"level":2,"heading":"HTML Data Visibility","anchor":"html-data-visibility"},{"level":2,"heading":"Harvesting","anchor":"harvesting"},{"level":2,"heading":"Meta Museum Notes","anchor":"meta-museum-notes"},{"level":2,"heading":"Test Ideas","anchor":"test-ideas"}],"html":"

Linked Art API: Discovery

\n

Last refreshed: 2026-07-07

\n

Source: Discovery APIs, 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.

\n

Purpose

\n

Linked Art Discovery describes how other web pages, APIs, and harvesters can find Linked Art records. It covers two complementary patterns:

\n\n

HTML Data Visibility

\n

Public HTML pages should expose a machine-readable Linked Art record with `describedby` links.

\n

For HTTP responses, the preferred signpost is a `Link` header:

\n
\nLink: <https://example.com/data/object/1>; rel="describedby"; type="application/ld+json;profile='https://linked.art/ns/v1/linked-art.json'"\n
\n

For browser-facing HTML, the page head must include exactly one matching link:

\n
\n<link\n  rel="describedby"\n  href="https://example.com/data/object/1"\n  type="application/ld+json;profile='https://linked.art/ns/v1/linked-art.json'"\n/>\n
\n

The one-link rule matters: if an HTML page advertises more than one Linked Art record, clients cannot know which JSON-LD record describes the page.

\n

Linked Art notes that this pattern follows the FAIR Signposting Profile.

\n

Harvesting

\n

For harvestable synchronization, Linked Art points to the IIIF Change Discovery API. Linked Art record classes can be made available in the change stream by adding the Linked Art record-types context alongside the IIIF discovery context:

\n
\n{\n  "@context": [\n    "https://linked.art/ns/v1/record-types.json",\n    "http://iiif.io/api/discovery/1/context.json"\n  ]\n}\n
\n

That lets entries describe Linked Art records directly, for example an `Update` whose `object.type` is `HumanMadeObject`.

\n

Meta Museum Notes

\n

Meta Museum already has substantial Discovery coverage:

\n\n

The main refinement opportunity is to extend the HTML signposting guard from in-page `<link>` declarations to HTTP response headers where Next route/page mechanics make that practical. The current tests already prove the one-canonical-HTML-link requirement; a future route-level smoke should also prove a `Link: rel="describedby"` header on public HTML responses.

\n

Test Ideas

\n","updatedAt":"2026-07-07T00:00:00.000Z","checksum":"407a0f6a9de4f501b33adf610921892ace8663a0b570fc2527507c856f1b8a79","checksumPrefix":"407a0f6a9de4","anchorCount":5,"lineCount":72,"rawUrl":"/api/docs/content?path=linked-art%2Fapi%2Fdiscovery.md","htmlUrl":"/docs?doc=linked-art%2Fapi%2Fdiscovery.md","apiUrl":"/api/docs/content?path=linked-art%2Fapi%2Fdiscovery.md"}