{"id":"linked-art/api/shared-references","relativePath":"linked-art/api/shared-references.md","title":"Linked Art API: Shared References","markdown":"# Linked Art API: Shared References\n\n**Last refreshed:** 2026-07-06\n\nSource: [References shared structure](https://linked.art/api/1.0/shared/reference/), part of Linked Art API 1.0, published 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\nReferences connect Linked Art resources to other resources without embedding a full description of the target. They are intentionally small so clients can recognize that more information may be available by dereferencing the `id`.\n\nClients should expect to follow and pre-cache references for responsive user interfaces. The reference itself provides only enough information to understand what the link points to.\n\n## Required Shape\n\nA reference includes:\n\n- `id`: required dereferenceable URI identifying the referenced resource.\n- `type`: required class of the referenced resource. It must match the target resource after dereferencing.\n\n## Recommended Fields\n\n- `_label`: developer-facing label for the referenced resource. The label may differ from the dereferenced target label.\n\n## Optional Fields\n\n- `equivalent`: references to external resources equivalent to the referenced resource.\n- `notation`: commonly used notation or identifier strings, especially language tags on `Language` references.\n\n## Completeness Rule\n\nReferences do not carry `_complete`. They are inherently incomplete; otherwise they would be embedded structures rather than references. Consumers can detect references because they only carry the compact reference fields instead of the mandatory fields required by embedded structures.\n\nTypes are a special case: concept references may include meta-classifications, because dereferencing a vocabulary URI might not return a Linked Art formatted description.\n\n## Common Incoming Relationships\n\nReferences appear throughout the model, including `classified_as`, `member_of`, `shows`, `current_owner`, `current_location`, `about`, `carried_out_by`, `took_place_at`, `equivalent`, and many other relationship properties.\n\n## Meta Museum Notes\n\nMeta Museum already preserves references across record and dataset projections, including `equivalent[]` links used for Wikidata reconciliation, canonical record references, collection membership, owners, locations, activity participants, places, and shown or carried works. The important project rule is to preserve reference shape without inflating every reference into a partial embedded record or erasing the dereferenceable `id`.\n\n## Test Ideas\n\n- Preserve compact references with `id`, `type`, and `_label`.\n- Preserve `equivalent[]` on references for reconciliation.\n- Preserve `notation` on language references.\n- Do not add `_complete` to ordinary references.\n- Preserve references in `classified_as`, `member_of`, `shows`, `current_owner`, `current_location`, `about`, `carried_out_by`, and `took_place_at`.\n- Keep reference URI handling opaque; never infer type or semantics from URL path segments.\n","sections":[{"level":2,"heading":"Purpose","anchor":"purpose"},{"level":2,"heading":"Required Shape","anchor":"required-shape"},{"level":2,"heading":"Recommended Fields","anchor":"recommended-fields"},{"level":2,"heading":"Optional Fields","anchor":"optional-fields"},{"level":2,"heading":"Completeness Rule","anchor":"completeness-rule"},{"level":2,"heading":"Common Incoming Relationships","anchor":"common-incoming-relationships"},{"level":2,"heading":"Meta Museum Notes","anchor":"meta-museum-notes"},{"level":2,"heading":"Test Ideas","anchor":"test-ideas"}],"html":"<h1 id=\"linked-art-api-shared-references\">Linked Art API: Shared References</h1>\n<p><strong>Last refreshed:</strong> 2026-07-06</p>\n<p>Source: <a href=\"https://linked.art/api/1.0/shared/reference/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"doc-link\">References shared structure</a>, part of Linked Art API 1.0, published 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>References connect Linked Art resources to other resources without embedding a full description of the target. They are intentionally small so clients can recognize that more information may be available by dereferencing the `id`.</p>\n<p>Clients should expect to follow and pre-cache references for responsive user interfaces. The reference itself provides only enough information to understand what the link points to.</p>\n<h2 id=\"required-shape\">Required Shape</h2>\n<p>A reference includes:</p>\n<ul><li>`id`: required dereferenceable URI identifying the referenced resource.</li><li>`type`: required class of the referenced resource. It must match the target resource after dereferencing.</li></ul>\n<h2 id=\"recommended-fields\">Recommended Fields</h2>\n<ul><li>`_label`: developer-facing label for the referenced resource. The label may differ from the dereferenced target label.</li></ul>\n<h2 id=\"optional-fields\">Optional Fields</h2>\n<ul><li>`equivalent`: references to external resources equivalent to the referenced resource.</li><li>`notation`: commonly used notation or identifier strings, especially language tags on `Language` references.</li></ul>\n<h2 id=\"completeness-rule\">Completeness Rule</h2>\n<p>References do not carry `_complete`. They are inherently incomplete; otherwise they would be embedded structures rather than references. Consumers can detect references because they only carry the compact reference fields instead of the mandatory fields required by embedded structures.</p>\n<p>Types are a special case: concept references may include meta-classifications, because dereferencing a vocabulary URI might not return a Linked Art formatted description.</p>\n<h2 id=\"common-incoming-relationships\">Common Incoming Relationships</h2>\n<p>References appear throughout the model, including `classified_as`, `member_of`, `shows`, `current_owner`, `current_location`, `about`, `carried_out_by`, `took_place_at`, `equivalent`, and many other relationship properties.</p>\n<h2 id=\"meta-museum-notes\">Meta Museum Notes</h2>\n<p>Meta Museum already preserves references across record and dataset projections, including `equivalent[]` links used for Wikidata reconciliation, canonical record references, collection membership, owners, locations, activity participants, places, and shown or carried works. The important project rule is to preserve reference shape without inflating every reference into a partial embedded record or erasing the dereferenceable `id`.</p>\n<h2 id=\"test-ideas\">Test Ideas</h2>\n<ul><li>Preserve compact references with `id`, `type`, and `_label`.</li><li>Preserve `equivalent[]` on references for reconciliation.</li><li>Preserve `notation` on language references.</li><li>Do not add `_complete` to ordinary references.</li><li>Preserve references in `classified_as`, `member_of`, `shows`, `current_owner`, `current_location`, `about`, `carried_out_by`, and `took_place_at`.</li><li>Keep reference URI handling opaque; never infer type or semantics from URL path segments.</li></ul>","updatedAt":"2026-07-06T00:00:00.000Z","checksum":"22aa1cc20d4fe3d67c0c69fd38cbdaebd943dac86a16dc52eff3ffd45d71f3d4","checksumPrefix":"22aa1cc20d4f","anchorCount":8,"lineCount":51,"rawUrl":"/api/docs/content?path=linked-art%2Fapi%2Fshared-references.md","htmlUrl":"/docs?doc=linked-art%2Fapi%2Fshared-references.md","apiUrl":"/api/docs/content?path=linked-art%2Fapi%2Fshared-references.md"}