{"id":"linked-art/api/index","relativePath":"linked-art/api/index.md","title":"Linked Art API Reference Notes","markdown":"# Linked Art API Reference Notes\n\n**Last refreshed:** 2026-07-06\n\nThis section is Meta Museum's local working index for Linked Art API 1.0 reference material. It is designed for implementers and agents working in this repository: short enough to scan, source-linked enough to verify, and structured enough to map future code/test work to the official API.\n\nSource: [Linked Art API 1.0](https://linked.art/api/1.0/), published by the Linked Art Editorial Board under [CC BY 4.0](http://creativecommons.org/licenses/by/4.0/). These notes are derivative summaries for project use; the upstream Linked Art pages remain authoritative.\n\n## Scope\n\nLinked Art separates the application profile from any particular protocol, then defines a web API for conforming publishers. The API is built around:\n\n- Core entity description endpoints that return Linked Art JSON-LD.\n- Shared data structures for names, identifiers, statements, dimensions, rights, references, and assignments.\n- HAL `_links` for versioning, searches, related resources, and cross-format navigation.\n- Search response shape without requiring one query language.\n- Discovery APIs for harvesting, synchronization, and HTML-to-data signposting.\n- Protocol rules for HTTP(S), JSON-LD, content negotiation, and versioning.\n- JSON Schema definitions for endpoint response validation.\n\n## Local Reference Pages\n\nThe captured core entity endpoint notes are:\n\n- [Abstract Works](abstract-works.md) - `PropositionalObject` records for abstract/conceptual works, exhibition ideas, performance concepts, and similar non-text/non-visual works.\n- [Concepts](concepts.md) - full records for `Type`, `Material`, `Language`, `Currency`, and `MeasurementUnit` concepts.\n- [Digital Objects](digital-objects.md) - `DigitalObject` and `DigitalService` descriptions, access points, IIIF conformance, format metadata, and digital carrier/showing relationships.\n- [Events](events.md) - standalone `Period`, `Event`, and `Activity` records, including timespans, places, actor responsibility, causation, influence, and relative temporal ordering.\n- [Groups](groups.md) - `Group` actor records for organizations, families, departments, societies, and other identifiable sets of people or subgroups.\n- [People](people.md) - `Person` actor records for artists, collectors, curators, conservators, staff, and other people connected to art activities.\n- [Physical Objects](physical-objects.md) - `HumanMadeObject` records for tangible artworks, carriers, parts, ownership/custody/location state, content carried or shown, lifecycle events, and provenance.\n- [Places](places.md) - `Place` records for spatial extents, WKT geometry, spatial hierarchy, current locations, activity locations, movement origins/destinations, and residences.\n- [Provenance Activities](provenance-activities.md) - provenance wrapper `Activity`/`Event` records with required Provenance Activity classification and detailed `part[]` entries for acquisition, payment, custody, encounter, rights, movement, promise, and indeterminate transfer evidence.\n- [Sets](sets.md) - `Set` records for collections, exhibition object groups, archival groupings, auction lots, concept schemes, and other aggregations, with membership discovered from member records.\n- [Textual Works](textual-works.md) - `LinguisticObject` records for texts, including language, content, subject matter, authorship, publication activity, rights, and physical/digital carrier boundaries.\n- [Visual Works](visual-works.md) - `VisualItem` records for image content, including aboutness, representation, depicted types, creation, rights, and physical/digital showing relationships.\n\nThe captured API support notes are:\n\n- [JSON Schemas](json-schemas.md) - official endpoint schema catalog and local schema checklists.\n- [HAL](hal.md) - non-semantic `_links` metadata for `self`, CURIEs, API/model versions, alternate representations, Change Discovery collections, named relation-search links such as `activityUsedObject`, `workRepresentsAgent`, `activityTookPlaceAtPlace`, and `agentActiveAtPlace`, plus the complete 95-name upstream relation inventory extracted from the cloned Linked Art mirror.\n- [Search](search.md) - Linked Art Search API response shape for HAL relation-search and other result pages, including `OrderedCollectionPage`, embedded `OrderedCollection`, `orderedItems`, pagination links, and Meta Museum's current `nextPage`/`prevPage` compatibility refinement target.\n- [Discovery](discovery.md) - HTML `describedby` signposting, FAIR Signposting alignment, IIIF Change Discovery harvesting, Linked Art record-types context usage, and Meta Museum's current one-canonical-link and activity/dataset discovery coverage.\n- [Design Principles](design-principles.md) - IIIF-derived API design rules for use-case scope, internationalization, simplicity, REST/cacheability, JSON-LD, standards, extensibility, network access, layer boundaries, embedding, inverse relationships, and opaque URIs.\n- [JSON-LD Considerations](json-ld-considerations.md) - Linked Art context, profile media type, case sensitivity, array discipline, `id`/`type` aliases, scoped context naming, plain-JSON usability, and RDF compatibility rules.\n- [Protocol](protocol.md) - HTTP(S), REST retrieval scope, `GET`/`OPTIONS`/optional `HEAD`, content negotiation, CORS, version profile URIs, persistent URI practice, endpoint names, and opaque URI rules.\n- [Code And Tools](code-and-tools.md) - Linked Art ecosystem libraries, platforms, documentation aids, validators, visualization tools, and data-cleaning resources for implementation planning.\n- [Bibliography](bibliography.md) - scholarly and technical sources for Linked Art, LOUD, provenance, semantic annotation, image archives, and cross-collection discovery claims.\n- [CDWA Mapping](cdwa-mapping.md) - CDWA-to-Linked-Art crosswalk for object, title, creation, measurement, material, activity, provenance, visual, textual, and authority fields.\n- [Schema.org Mapping](schema-org-mapping.md) - Linked-Art-to-Schema.org projection rules for structured web data across people, organizations, places, concepts, objects, digital objects, works, events, and sets.\n- [Abstract Work Schema](schema-abstract-work.md) - expanded `abstract.json` notes for `PropositionalObject` required fields, permitted top-level fields, nested structures, and `created_by` activity shape.\n- [Concept Schema](schema-concept.md) - expanded `concept.json` notes for `crm:E55_Type`, concept subclasses, embedded statements/representations, creation activity, and `broader` hierarchy.\n- [Digital Object Schema](schema-digital-object.md) - expanded `digital.json` notes for `dig:D1_Digital_Object`, access points, formats, conformance, digital services, carried/shown content, and activity evidence.\n- [Event Schema](schema-event.md) - expanded `event.json` notes for `Period`, `Event`, and `Activity`, including timespans, places, temporal ordering, causation, actor responsibility, participants, and techniques.\n- [Group Schema](schema-group.md) - expanded `group.json` notes for `crm:E74_Group`, group membership, performed/participated activities, contact points, residences, formation, and dissolution.\n- [Person Schema](schema-person.md) - expanded `person.json` notes for `crm:E21_Person`, group membership, performed/participated activities, contact points, residences, birth, and death.\n- [Physical Object Schema](schema-physical-object.md) - expanded `object.json` notes for `crm:E22_Human-Made_Object`, current ownership/custody/location, materials, parts, content relationships, lifecycle, and provenance activities.\n- [Place Schema](schema-place.md) - expanded `place.json` notes for `crm:E53_Place`, spatial geometry, larger-place hierarchy, representations, subject pages, and incoming object/activity/actor place references.\n- [Provenance Activity Schema](schema-provenance-activity.md) - expanded `provenance.json` notes for `crm:E7_Activity`, required provenance classifications, temporal/activity fields, and detailed `part[]` transfer, payment, encounter, move, and rights-change evidence.\n- [Set Schema](schema-set.md) - expanded `set.json` notes for `la:Set`, parent set membership, physical member containers, exemplar templates, collection topics, dimensions, and set activity evidence.\n- [Textual Work Schema](schema-textual-work.md) - expanded `text.json` notes for `crm:E33_Linguistic_Object`, textual content, language, format, rights, aboutness, part relationships, carrier boundaries, and creation/use activity evidence.\n- [Visual Work Schema](schema-visual-work.md) - expanded `image.json` notes for `crm:E36_Visual_Item`, visual aboutness, represented entities, represented types, rights, dimensions, carrier boundaries, and creation/use activity evidence.\n- [Shared Structures](shared-structures.md) - reusable embedded structures for activities, digital links, dimensions, identifiers, monetary amounts, names, rights, references, statements, timespans, concepts, and relationship assignments, including inherited context and `_complete: false` dereference rules.\n- [Shared Activities](shared-activities.md) - embedded `Creation`, `Production`, `Formation`, `Dissolution`, `Birth`, `Death`, `PartRemoval`, `Modification`, `Destruction`, `Encounter`, and generic `Activity` structures, including incoming relationship names and `_complete: false` activity URI rules.\n- [Shared Digital Links](shared-digital-links.md) - nested `VisualItem`/`LinguisticObject` plus `DigitalObject` structures for images, web pages, access points, digital services, media types, and conformance references.\n- [Shared Dimensions](shared-dimensions.md) - embedded `Dimension` structures with numeric values, measurement units, classification, display labels, uncertainty bounds, duration usage, and `assigned_by` measurement evidence.\n- [Shared Concept References](shared-concept-references.md) - compact `Type`, `Language`, `Material`, `Currency`, and `MeasurementUnit` references for classification, vocabulary alignment, notation, and concept meta-classification.\n- [Shared Identifiers](shared-identifiers.md) - embedded `Identifier` structures for accession numbers, system identifiers, contact points, classification, notes, and assignment provenance.\n- [Shared Monetary Amounts](shared-monetary-amounts.md) - embedded `MonetaryAmount` structures with numeric values, `Currency` references, classifications, display labels, uncertainty bounds, notes, and payment/auction-lot usage.\n- [Shared Names](shared-names.md) - embedded `Name` structures for linguistic labels, language tagging, classified name types, nested name parts, statements, and assignment provenance.\n- [Shared Rights](shared-rights.md) - embedded `Right` structures for machine-comparable rights assertions, license classifications, rights holders, statements, and `subject_to` usage on intellectual works.\n- [Shared References](shared-references.md) - compact `id`/`type`/`_label` references to other resources, with optional `equivalent` and `notation`, and no `_complete` field.\n- [Shared Statements](shared-statements.md) - embedded `LinguisticObject` descriptions and notes with content, language, classification, labels, rights, creation evidence, and nested statements.\n- [Shared TimeSpans](shared-timespans.md) - embedded `TimeSpan` structures for fuzzy temporal boundaries, display labels, notes, duration dimensions, and minimum content requirements.\n- [Shared Relationships](shared-relationships.md) - embedded `AttributeAssignment` structures for asserted relationships, assignment provenance, `assigned_property`, and arbitrary related-entity links.\n\n## Project Use\n\nWhen adding API conformance work, use this local section as a checklist:\n\n- Confirm the official upstream page and version.\n- Add or update a local endpoint note with source URL, required type, required fields, recommended fields, optional fields, incoming relationship patterns, and current Meta Museum coverage.\n- Add executable tests when a page reveals a behavior we can prove locally.\n- Update `README.md` and `docs/roadmap.md` when the reference materially changes project coverage or evidence.\n\n## Refinement Targets\n\nThe remaining improvements are now implementation-depth refinements rather than missing local captures:\n\n- Extend official Search API `next`/`prev`, `startIndex`, and `partOf.first`/`partOf.last` coverage from the canonical `/api/search` and `/api/relations/{relation}` routes to provider-specific search routes.\n- Add HTTP `Link: rel=\"describedby\"` route-level smoke coverage for public HTML pages, complementing the existing exactly-one HTML `<link rel=\"describedby\">` guard.\n- Keep expanding the 95-name HAL relation inventory from documented checklist to executable relation-search fixtures as real modeled data supports each family.\n","sections":[{"level":2,"heading":"Scope","anchor":"scope"},{"level":2,"heading":"Local Reference Pages","anchor":"local-reference-pages"},{"level":2,"heading":"Project Use","anchor":"project-use"},{"level":2,"heading":"Refinement Targets","anchor":"refinement-targets"}],"html":"<h1 id=\"linked-art-api-reference-notes\">Linked Art API Reference Notes</h1>\n<p><strong>Last refreshed:</strong> 2026-07-06</p>\n<p>This section is Meta Museum&#39;s local working index for Linked Art API 1.0 reference material. It is designed for implementers and agents working in this repository: short enough to scan, source-linked enough to verify, and structured enough to map future code/test work to the official API.</p>\n<p>Source: <a href=\"https://linked.art/api/1.0/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"doc-link\">Linked Art API 1.0</a>, 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>. These notes are derivative summaries for project use; the upstream Linked Art pages remain authoritative.</p>\n<h2 id=\"scope\">Scope</h2>\n<p>Linked Art separates the application profile from any particular protocol, then defines a web API for conforming publishers. The API is built around:</p>\n<ul><li>Core entity description endpoints that return Linked Art JSON-LD.</li><li>Shared data structures for names, identifiers, statements, dimensions, rights, references, and assignments.</li><li>HAL `_links` for versioning, searches, related resources, and cross-format navigation.</li><li>Search response shape without requiring one query language.</li><li>Discovery APIs for harvesting, synchronization, and HTML-to-data signposting.</li><li>Protocol rules for HTTP(S), JSON-LD, content negotiation, and versioning.</li><li>JSON Schema definitions for endpoint response validation.</li></ul>\n<h2 id=\"local-reference-pages\">Local Reference Pages</h2>\n<p>The captured core entity endpoint notes are:</p>\n<ul><li>Abstract Works(abstract-works.md) - `PropositionalObject` records for abstract/conceptual works, exhibition ideas, performance concepts, and similar non-text/non-visual works.</li><li>Concepts(concepts.md) - full records for `Type`, `Material`, `Language`, `Currency`, and `MeasurementUnit` concepts.</li><li>Digital Objects(digital-objects.md) - `DigitalObject` and `DigitalService` descriptions, access points, IIIF conformance, format metadata, and digital carrier/showing relationships.</li><li>Events(events.md) - standalone `Period`, `Event`, and `Activity` records, including timespans, places, actor responsibility, causation, influence, and relative temporal ordering.</li><li>Groups(groups.md) - `Group` actor records for organizations, families, departments, societies, and other identifiable sets of people or subgroups.</li><li>People(people.md) - `Person` actor records for artists, collectors, curators, conservators, staff, and other people connected to art activities.</li><li>Physical Objects(physical-objects.md) - `HumanMadeObject` records for tangible artworks, carriers, parts, ownership/custody/location state, content carried or shown, lifecycle events, and provenance.</li><li>Places(places.md) - `Place` records for spatial extents, WKT geometry, spatial hierarchy, current locations, activity locations, movement origins/destinations, and residences.</li><li>Provenance Activities(provenance-activities.md) - provenance wrapper `Activity`/`Event` records with required Provenance Activity classification and detailed `part[]` entries for acquisition, payment, custody, encounter, rights, movement, promise, and indeterminate transfer evidence.</li><li>Sets(sets.md) - `Set` records for collections, exhibition object groups, archival groupings, auction lots, concept schemes, and other aggregations, with membership discovered from member records.</li><li>Textual Works(textual-works.md) - `LinguisticObject` records for texts, including language, content, subject matter, authorship, publication activity, rights, and physical/digital carrier boundaries.</li><li>Visual Works(visual-works.md) - `VisualItem` records for image content, including aboutness, representation, depicted types, creation, rights, and physical/digital showing relationships.</li></ul>\n<p>The captured API support notes are:</p>\n<ul><li>JSON Schemas(json-schemas.md) - official endpoint schema catalog and local schema checklists.</li><li>HAL(hal.md) - non-semantic `_links` metadata for `self`, CURIEs, API/model versions, alternate representations, Change Discovery collections, named relation-search links such as `activityUsedObject`, `workRepresentsAgent`, `activityTookPlaceAtPlace`, and `agentActiveAtPlace`, plus the complete 95-name upstream relation inventory extracted from the cloned Linked Art mirror.</li><li>Search(search.md) - Linked Art Search API response shape for HAL relation-search and other result pages, including `OrderedCollectionPage`, embedded `OrderedCollection`, `orderedItems`, pagination links, and Meta Museum&#39;s current `nextPage`/`prevPage` compatibility refinement target.</li><li>Discovery(discovery.md) - HTML `describedby` signposting, FAIR Signposting alignment, IIIF Change Discovery harvesting, Linked Art record-types context usage, and Meta Museum&#39;s current one-canonical-link and activity/dataset discovery coverage.</li><li>Design Principles(design-principles.md) - IIIF-derived API design rules for use-case scope, internationalization, simplicity, REST/cacheability, JSON-LD, standards, extensibility, network access, layer boundaries, embedding, inverse relationships, and opaque URIs.</li><li>JSON-LD Considerations(json-ld-considerations.md) - Linked Art context, profile media type, case sensitivity, array discipline, `id`/`type` aliases, scoped context naming, plain-JSON usability, and RDF compatibility rules.</li><li>Protocol(protocol.md) - HTTP(S), REST retrieval scope, `GET`/`OPTIONS`/optional `HEAD`, content negotiation, CORS, version profile URIs, persistent URI practice, endpoint names, and opaque URI rules.</li><li>Code And Tools(code-and-tools.md) - Linked Art ecosystem libraries, platforms, documentation aids, validators, visualization tools, and data-cleaning resources for implementation planning.</li><li>Bibliography(bibliography.md) - scholarly and technical sources for Linked Art, LOUD, provenance, semantic annotation, image archives, and cross-collection discovery claims.</li><li>CDWA Mapping(cdwa-mapping.md) - CDWA-to-Linked-Art crosswalk for object, title, creation, measurement, material, activity, provenance, visual, textual, and authority fields.</li><li>Schema.org Mapping(schema-org-mapping.md) - Linked-Art-to-Schema.org projection rules for structured web data across people, organizations, places, concepts, objects, digital objects, works, events, and sets.</li><li>Abstract Work Schema(schema-abstract-work.md) - expanded `abstract.json` notes for `PropositionalObject` required fields, permitted top-level fields, nested structures, and `created_by` activity shape.</li><li>Concept Schema(schema-concept.md) - expanded `concept.json` notes for `crm:E55_Type`, concept subclasses, embedded statements/representations, creation activity, and `broader` hierarchy.</li><li>Digital Object Schema(schema-digital-object.md) - expanded `digital.json` notes for `dig:D1_Digital_Object`, access points, formats, conformance, digital services, carried/shown content, and activity evidence.</li><li>Event Schema(schema-event.md) - expanded `event.json` notes for `Period`, `Event`, and `Activity`, including timespans, places, temporal ordering, causation, actor responsibility, participants, and techniques.</li><li>Group Schema(schema-group.md) - expanded `group.json` notes for `crm:E74_Group`, group membership, performed/participated activities, contact points, residences, formation, and dissolution.</li><li>Person Schema(schema-person.md) - expanded `person.json` notes for `crm:E21_Person`, group membership, performed/participated activities, contact points, residences, birth, and death.</li><li>Physical Object Schema(schema-physical-object.md) - expanded `object.json` notes for `crm:E22_Human-Made_Object`, current ownership/custody/location, materials, parts, content relationships, lifecycle, and provenance activities.</li><li>Place Schema(schema-place.md) - expanded `place.json` notes for `crm:E53_Place`, spatial geometry, larger-place hierarchy, representations, subject pages, and incoming object/activity/actor place references.</li><li>Provenance Activity Schema(schema-provenance-activity.md) - expanded `provenance.json` notes for `crm:E7_Activity`, required provenance classifications, temporal/activity fields, and detailed `part[]` transfer, payment, encounter, move, and rights-change evidence.</li><li>Set Schema(schema-set.md) - expanded `set.json` notes for `la:Set`, parent set membership, physical member containers, exemplar templates, collection topics, dimensions, and set activity evidence.</li><li>Textual Work Schema(schema-textual-work.md) - expanded `text.json` notes for `crm:E33_Linguistic_Object`, textual content, language, format, rights, aboutness, part relationships, carrier boundaries, and creation/use activity evidence.</li><li>Visual Work Schema(schema-visual-work.md) - expanded `image.json` notes for `crm:E36_Visual_Item`, visual aboutness, represented entities, represented types, rights, dimensions, carrier boundaries, and creation/use activity evidence.</li><li>Shared Structures(shared-structures.md) - reusable embedded structures for activities, digital links, dimensions, identifiers, monetary amounts, names, rights, references, statements, timespans, concepts, and relationship assignments, including inherited context and `_complete: false` dereference rules.</li><li>Shared Activities(shared-activities.md) - embedded `Creation`, `Production`, `Formation`, `Dissolution`, `Birth`, `Death`, `PartRemoval`, `Modification`, `Destruction`, `Encounter`, and generic `Activity` structures, including incoming relationship names and `_complete: false` activity URI rules.</li><li>Shared Digital Links(shared-digital-links.md) - nested `VisualItem`/`LinguisticObject` plus `DigitalObject` structures for images, web pages, access points, digital services, media types, and conformance references.</li><li>Shared Dimensions(shared-dimensions.md) - embedded `Dimension` structures with numeric values, measurement units, classification, display labels, uncertainty bounds, duration usage, and `assigned_by` measurement evidence.</li><li>Shared Concept References(shared-concept-references.md) - compact `Type`, `Language`, `Material`, `Currency`, and `MeasurementUnit` references for classification, vocabulary alignment, notation, and concept meta-classification.</li><li>Shared Identifiers(shared-identifiers.md) - embedded `Identifier` structures for accession numbers, system identifiers, contact points, classification, notes, and assignment provenance.</li><li>Shared Monetary Amounts(shared-monetary-amounts.md) - embedded `MonetaryAmount` structures with numeric values, `Currency` references, classifications, display labels, uncertainty bounds, notes, and payment/auction-lot usage.</li><li>Shared Names(shared-names.md) - embedded `Name` structures for linguistic labels, language tagging, classified name types, nested name parts, statements, and assignment provenance.</li><li>Shared Rights(shared-rights.md) - embedded `Right` structures for machine-comparable rights assertions, license classifications, rights holders, statements, and `subject_to` usage on intellectual works.</li><li>Shared References(shared-references.md) - compact `id`/`type`/`_label` references to other resources, with optional `equivalent` and `notation`, and no `_complete` field.</li><li>Shared Statements(shared-statements.md) - embedded `LinguisticObject` descriptions and notes with content, language, classification, labels, rights, creation evidence, and nested statements.</li><li>Shared TimeSpans(shared-timespans.md) - embedded `TimeSpan` structures for fuzzy temporal boundaries, display labels, notes, duration dimensions, and minimum content requirements.</li><li>Shared Relationships(shared-relationships.md) - embedded `AttributeAssignment` structures for asserted relationships, assignment provenance, `assigned_property`, and arbitrary related-entity links.</li></ul>\n<h2 id=\"project-use\">Project Use</h2>\n<p>When adding API conformance work, use this local section as a checklist:</p>\n<ul><li>Confirm the official upstream page and version.</li><li>Add or update a local endpoint note with source URL, required type, required fields, recommended fields, optional fields, incoming relationship patterns, and current Meta Museum coverage.</li><li>Add executable tests when a page reveals a behavior we can prove locally.</li><li>Update `README.md` and `docs/roadmap.md` when the reference materially changes project coverage or evidence.</li></ul>\n<h2 id=\"refinement-targets\">Refinement Targets</h2>\n<p>The remaining improvements are now implementation-depth refinements rather than missing local captures:</p>\n<ul><li>Extend official Search API `next`/`prev`, `startIndex`, and `partOf.first`/`partOf.last` coverage from the canonical `/api/search` and `/api/relations/{relation}` routes to provider-specific search routes.</li><li>Add HTTP `Link: rel=&quot;describedby&quot;` route-level smoke coverage for public HTML pages, complementing the existing exactly-one HTML `&lt;link rel=&quot;describedby&quot;&gt;` guard.</li><li>Keep expanding the 95-name HAL relation inventory from documented checklist to executable relation-search fixtures as real modeled data supports each family.</li></ul>","updatedAt":"2026-07-06T00:00:00.000Z","checksum":"04ab7332225148126d6f4e1b205adc6509860980c70852bbb3eb7459f1315941","checksumPrefix":"04ab73322251","anchorCount":4,"lineCount":93,"rawUrl":"/api/docs/content?path=linked-art%2Fapi%2Findex.md","htmlUrl":"/docs?doc=linked-art%2Fapi%2Findex.md","apiUrl":"/api/docs/content?path=linked-art%2Fapi%2Findex.md"}