{"id":"linked-art/api/groups","relativePath":"linked-art/api/groups.md","title":"Linked Art API: Groups","markdown":"# Linked Art API: Groups\n\n**Last refreshed:** 2026-07-06\n\nSource: [Groups endpoint](https://linked.art/api/1.0/endpoint/group/), 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\nThe Group endpoint describes identifiable sets of actors, including families, organizations, companies, departments, workshops, societies, and other sets of people or subgroups. It is similar to the Person endpoint, with additional fields for group membership and lifecycle.\n\n## Required Shape\n\nA Group endpoint record dereferences to one JSON-LD object:\n\n- `@context`: Linked Art context URI, or an array ending with that URI for extensions.\n- `id`: dereferenceable HTTP(S) URI for the group.\n- `type`: `Group`.\n\n## Recommended Fields\n\n- `_label`: developer-facing label.\n- `classified_as`: classifications following the `Type` structure, such as society or nationality.\n- `identified_by`: `Name` and/or `Identifier` structures.\n\n## Optional Fields\n\n- `referred_to_by`: statements about the group.\n- `equivalent`: external identities.\n- `representation`: visual works representing the group.\n- `member_of`: parent group membership.\n- `subject_of`: textual works focused on the group.\n- `attributed_by`: relationship assignment evidence.\n- `contact_point`: addresses or contact identifiers.\n- `residence`: associated place.\n- `carried_out`: professional activities of the group.\n- `participated_in`: events or activities in which the group participated but was not responsible.\n- `formed_by`: `Formation` event for the group.\n- `dissolved_by`: `Dissolution` event for the group.\n\n## Common Incoming Relationships\n\n- `member_of` from Person or Group records.\n- `carried_out_by` from activities.\n- `current_owner`, `current_custodian`, and `current_permanent_custodian` from object records.\n- `represents` from visual works.\n- `about` from textual works.\n- `transferred_custody_to` and `transferred_custody_from` from provenance activities.\n- `transferred_title_to` and `transferred_title_from` from provenance activities.\n- `paid_to` and `paid_from` from provenance payment activities.\n\n## Meta Museum Notes\n\nMeta Museum already exposes groups through `/api/agents/{id}` and preserves rich `Group` records through `/api/records/{id}`. Existing actor tests cover group contact points, group membership, formation, residence, professional activities, and group classifications. Activity and provenance coverage also uses `Group` references for carried-out-by actors, ownership/custody transfers, payments, and auction houses.\n\n## Test Ideas\n\n- Keep `/api/agents/{id}` role coverage aligned with both `Person` and `Group`.\n- Preserve a `Group` fixture with `contact_point`, `member_of`, `residence`, `carried_out`, `formed_by`, `dissolved_by`, `equivalent`, and `attributed_by`.\n- Preserve incoming provenance references to groups for title transfer, custody transfer, and payment without flattening them into labels.\n- Ensure group nationality and organization type remain `classified_as` terms rather than custom group subclasses.\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":"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-groups\">Linked Art API: Groups</h1>\n<p><strong>Last refreshed:</strong> 2026-07-06</p>\n<p>Source: <a href=\"https://linked.art/api/1.0/endpoint/group/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"doc-link\">Groups endpoint</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>The Group endpoint describes identifiable sets of actors, including families, organizations, companies, departments, workshops, societies, and other sets of people or subgroups. It is similar to the Person endpoint, with additional fields for group membership and lifecycle.</p>\n<h2 id=\"required-shape\">Required Shape</h2>\n<p>A Group endpoint record dereferences to one JSON-LD object:</p>\n<ul><li>`@context`: Linked Art context URI, or an array ending with that URI for extensions.</li><li>`id`: dereferenceable HTTP(S) URI for the group.</li><li>`type`: `Group`.</li></ul>\n<h2 id=\"recommended-fields\">Recommended Fields</h2>\n<ul><li>`_label`: developer-facing label.</li><li>`classified_as`: classifications following the `Type` structure, such as society or nationality.</li><li>`identified_by`: `Name` and/or `Identifier` structures.</li></ul>\n<h2 id=\"optional-fields\">Optional Fields</h2>\n<ul><li>`referred_to_by`: statements about the group.</li><li>`equivalent`: external identities.</li><li>`representation`: visual works representing the group.</li><li>`member_of`: parent group membership.</li><li>`subject_of`: textual works focused on the group.</li><li>`attributed_by`: relationship assignment evidence.</li><li>`contact_point`: addresses or contact identifiers.</li><li>`residence`: associated place.</li><li>`carried_out`: professional activities of the group.</li><li>`participated_in`: events or activities in which the group participated but was not responsible.</li><li>`formed_by`: `Formation` event for the group.</li><li>`dissolved_by`: `Dissolution` event for the group.</li></ul>\n<h2 id=\"common-incoming-relationships\">Common Incoming Relationships</h2>\n<ul><li>`member_of` from Person or Group records.</li><li>`carried_out_by` from activities.</li><li>`current_owner`, `current_custodian`, and `current_permanent_custodian` from object records.</li><li>`represents` from visual works.</li><li>`about` from textual works.</li><li>`transferred_custody_to` and `transferred_custody_from` from provenance activities.</li><li>`transferred_title_to` and `transferred_title_from` from provenance activities.</li><li>`paid_to` and `paid_from` from provenance payment activities.</li></ul>\n<h2 id=\"meta-museum-notes\">Meta Museum Notes</h2>\n<p>Meta Museum already exposes groups through `/api/agents/{id}` and preserves rich `Group` records through `/api/records/{id}`. Existing actor tests cover group contact points, group membership, formation, residence, professional activities, and group classifications. Activity and provenance coverage also uses `Group` references for carried-out-by actors, ownership/custody transfers, payments, and auction houses.</p>\n<h2 id=\"test-ideas\">Test Ideas</h2>\n<ul><li>Keep `/api/agents/{id}` role coverage aligned with both `Person` and `Group`.</li><li>Preserve a `Group` fixture with `contact_point`, `member_of`, `residence`, `carried_out`, `formed_by`, `dissolved_by`, `equivalent`, and `attributed_by`.</li><li>Preserve incoming provenance references to groups for title transfer, custody transfer, and payment without flattening them into labels.</li><li>Ensure group nationality and organization type remain `classified_as` terms rather than custom group subclasses.</li></ul>","updatedAt":"2026-07-06T00:00:00.000Z","checksum":"abbb3e00ba19560d16532921170e5c6604420984149ed14c9d8ecf67786e7b34","checksumPrefix":"abbb3e00ba19","anchorCount":7,"lineCount":61,"rawUrl":"/api/docs/content?path=linked-art%2Fapi%2Fgroups.md","htmlUrl":"/docs?doc=linked-art%2Fapi%2Fgroups.md","apiUrl":"/api/docs/content?path=linked-art%2Fapi%2Fgroups.md"}