{"id":"linked-art/api/schema-visual-work","relativePath":"linked-art/api/schema-visual-work.md","title":"Linked Art API Schema: Visual Work","markdown":"# Linked Art API Schema: Visual Work\n\n**Last refreshed:** 2026-07-06\n\nSource: [Visual Work schema docs](https://linked.art/api/1.0/schema_docs/image/) and [image.json](https://linked.art/api/1.0/schema/image.json), 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 schema is authoritative.\n\n## Purpose\n\nThe Visual Work schema describes `crm:E36_Visual_Item`: the visual content of a work. In Linked Art API terms this is the endpoint shape for image or visual content, separate from the physical object that shows it and the digital object that digitally shows it.\n\nRelated upstream references:\n\n- [Visual Work API endpoint](https://linked.art/api/1.0/endpoint/visual_work/)\n- [Visual works and object aboutness model documentation](https://linked.art/model/object/aboutness/)\n\n## Top-Level Constraints\n\n- Schema type: object.\n- CRM class: `crm:E36_Visual_Item`.\n- Additional top-level properties are not allowed.\n- `@context`: required.\n- `id`: required URI string for the entity.\n- `type`: required class string. The practical Linked Art class is `VisualItem`.\n- `_label`: required developer-facing human-readable label.\n\n## Permitted Top-Level Fields\n\n- `identified_by`: array of `Name` or `Identifier` structures.\n- `classified_as`: array of `Type` structures that classify this visual work.\n- `referred_to_by`: array of embedded statements or textual references about the visual work.\n- `equivalent`: array of compact references to equivalent identities.\n- `member_of`: array of `Set` references.\n- `subject_of`: array of embedded `LinguisticObject` web pages or digital objects focused on this visual work.\n- `attributed_by`: array of `AttributeAssignment` structures relating another entity to this visual work.\n- `dimension`: array of `Dimension` structures that describe this visual work.\n- `subject_to`: array of `Right` structures that apply to the visual work.\n- `part_of`: array of `VisualItem` or `LinguisticObject` references of which this visual work is part.\n- `conceptually_part_of`: array of `PropositionalObject` references of which this visual work is conceptually part.\n- `about`: array of references to the main topics of the visual content.\n- `created_by`: creation activity for the intellectual or visual content.\n- `represents`: array of known entities represented in the visual content.\n- `represents_instance_of_type`: array of `Type` references for kinds of entities represented when the individual entity is not identified.\n- `used_for`: array of activities in which this visual work was used.\n\n## Embedded Structures Highlighted By The Schema\n\n`identified_by` items can be:\n\n- `Name` structures, with required `type` and `content`, plus optional `_label`, nested `identified_by`, `referred_to_by`, `classified_as`, `language`, and `part`.\n- `Identifier` structures, following the shared identifier pattern.\n\n`referred_to_by` items are embedded `LinguisticObject` statements:\n\n- `type`: required.\n- `content`: required.\n- `_label`, `identified_by`, `classified_as`, `referred_to_by`, `language`, and `format` are allowed.\n\n`subject_to` items are `Right` structures:\n\n- `type`: required and must be `Right`.\n- `_label`, `identified_by`, `classified_as`, `referred_to_by`, `created_by`, and `possessed_by` are allowed.\n\n`subject_of` items are embedded `LinguisticObject` structures:\n\n- `type`: required.\n- `_label`, `identified_by`, `classified_as`, `referred_to_by`, `language`, and `digitally_carried_by` are allowed.\n\n## Aboutness And Representation\n\nThe schema keeps visual subject relationships distinct:\n\n- `about`: the main topic or topics of the visual content.\n- `represents`: a known entity represented in the visual content.\n- `represents_instance_of_type`: a type of entity represented when the individual entity is not identified.\n\nDo not collapse a known represented person, object, or place into a generic type. Use `represents` for identified entities and `represents_instance_of_type` for depicted classes.\n\n## Carrier Boundaries\n\nThe schema keeps visual content separate from carriers and surrogates:\n\n- Physical objects show visual content through object-side `shows`.\n- Digital objects show visual content through digital-object-side `digitally_shows`.\n- Other endpoint records can point to visual content through `representation`.\n- The visual work remains a `VisualItem`; physical artworks, image files, services, and visual content should remain separate linked resources.\n\n## Activity Fields\n\nThe schema supports visual-work activity evidence:\n\n- `created_by`: creation of the intellectual or visual content, including common activity fields such as `took_place_at`, `timespan`, `caused_by`, `carried_out_by`, `used_specific_object`, `influenced_by`, `technique`, `during`, `after`, `before`, and `part_of`.\n- `used_for`: activities in which the visual work was used, such as publication, exhibition, documentation, or another described use.\n\nCreation and use should remain structured activity evidence rather than flattened creator/date strings when the data supports it.\n\n## Meta Museum Notes\n\nMeta Museum already preserves Visual Work semantics through object, digital object, and record fixtures. Existing coverage keeps carrier/content/surrogate boundaries explicit: physical `HumanMadeObject` records can show `VisualItem` content, `DigitalObject` records can digitally show visual content, and object records can carry `representation[]` references without treating image files, depicted content, and physical artworks as the same entity.\n\nThis expanded schema adds the endpoint-level validation target for visual exports: required identity fields, no unexpected top-level properties, structured names/classifications/statements, dimensions, rights, aboutness, representation relationships, part relationships, and visual-work creation/use activity evidence.\n\n## Test Ideas\n\n- Validate representative `VisualItem` records against `image.json`.\n- Assert `@context`, `id`, `type`, and `_label` are present.\n- Assert unknown top-level properties fail schema validation.\n- Preserve `about`, `represents`, and `represents_instance_of_type` as distinct relationships.\n- Preserve `subject_to` as `Right` structures, not string labels.\n- Preserve `dimension`, `created_by`, `used_for`, `part_of`, and `conceptually_part_of`.\n- Preserve carrier boundaries: physical objects use `shows`, digital objects use `digitally_shows`, and visual content remains a distinct `VisualItem`.\n","sections":[{"level":2,"heading":"Purpose","anchor":"purpose"},{"level":2,"heading":"Top-Level Constraints","anchor":"top-level-constraints"},{"level":2,"heading":"Permitted Top-Level Fields","anchor":"permitted-top-level-fields"},{"level":2,"heading":"Embedded Structures Highlighted By The Schema","anchor":"embedded-structures-highlighted-by-the-schema"},{"level":2,"heading":"Aboutness And Representation","anchor":"aboutness-and-representation"},{"level":2,"heading":"Carrier Boundaries","anchor":"carrier-boundaries"},{"level":2,"heading":"Activity Fields","anchor":"activity-fields"},{"level":2,"heading":"Meta Museum Notes","anchor":"meta-museum-notes"},{"level":2,"heading":"Test Ideas","anchor":"test-ideas"}],"html":"<h1 id=\"linked-art-api-schema-visual-work\">Linked Art API Schema: Visual Work</h1>\n<p><strong>Last refreshed:</strong> 2026-07-06</p>\n<p>Source: <a href=\"https://linked.art/api/1.0/schema_docs/image/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"doc-link\">Visual Work schema docs</a> and <a href=\"https://linked.art/api/1.0/schema/image.json\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"doc-link\">image.json</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 schema is authoritative.</p>\n<h2 id=\"purpose\">Purpose</h2>\n<p>The Visual Work schema describes `crm:E36_Visual_Item`: the visual content of a work. In Linked Art API terms this is the endpoint shape for image or visual content, separate from the physical object that shows it and the digital object that digitally shows it.</p>\n<p>Related upstream references:</p>\n<ul><li><a href=\"https://linked.art/api/1.0/endpoint/visual_work/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"doc-link\">Visual Work API endpoint</a></li><li><a href=\"https://linked.art/model/object/aboutness/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"doc-link\">Visual works and object aboutness model documentation</a></li></ul>\n<h2 id=\"top-level-constraints\">Top-Level Constraints</h2>\n<ul><li>Schema type: object.</li><li>CRM class: `crm:E36_Visual_Item`.</li><li>Additional top-level properties are not allowed.</li><li>`@context`: required.</li><li>`id`: required URI string for the entity.</li><li>`type`: required class string. The practical Linked Art class is `VisualItem`.</li><li>`_label`: required developer-facing human-readable label.</li></ul>\n<h2 id=\"permitted-top-level-fields\">Permitted Top-Level Fields</h2>\n<ul><li>`identified_by`: array of `Name` or `Identifier` structures.</li><li>`classified_as`: array of `Type` structures that classify this visual work.</li><li>`referred_to_by`: array of embedded statements or textual references about the visual work.</li><li>`equivalent`: array of compact references to equivalent identities.</li><li>`member_of`: array of `Set` references.</li><li>`subject_of`: array of embedded `LinguisticObject` web pages or digital objects focused on this visual work.</li><li>`attributed_by`: array of `AttributeAssignment` structures relating another entity to this visual work.</li><li>`dimension`: array of `Dimension` structures that describe this visual work.</li><li>`subject_to`: array of `Right` structures that apply to the visual work.</li><li>`part_of`: array of `VisualItem` or `LinguisticObject` references of which this visual work is part.</li><li>`conceptually_part_of`: array of `PropositionalObject` references of which this visual work is conceptually part.</li><li>`about`: array of references to the main topics of the visual content.</li><li>`created_by`: creation activity for the intellectual or visual content.</li><li>`represents`: array of known entities represented in the visual content.</li><li>`represents_instance_of_type`: array of `Type` references for kinds of entities represented when the individual entity is not identified.</li><li>`used_for`: array of activities in which this visual work was used.</li></ul>\n<h2 id=\"embedded-structures-highlighted-by-the-schema\">Embedded Structures Highlighted By The Schema</h2>\n<p>`identified_by` items can be:</p>\n<ul><li>`Name` structures, with required `type` and `content`, plus optional `_label`, nested `identified_by`, `referred_to_by`, `classified_as`, `language`, and `part`.</li><li>`Identifier` structures, following the shared identifier pattern.</li></ul>\n<p>`referred_to_by` items are embedded `LinguisticObject` statements:</p>\n<ul><li>`type`: required.</li><li>`content`: required.</li><li>`_label`, `identified_by`, `classified_as`, `referred_to_by`, `language`, and `format` are allowed.</li></ul>\n<p>`subject_to` items are `Right` structures:</p>\n<ul><li>`type`: required and must be `Right`.</li><li>`_label`, `identified_by`, `classified_as`, `referred_to_by`, `created_by`, and `possessed_by` are allowed.</li></ul>\n<p>`subject_of` items are embedded `LinguisticObject` structures:</p>\n<ul><li>`type`: required.</li><li>`_label`, `identified_by`, `classified_as`, `referred_to_by`, `language`, and `digitally_carried_by` are allowed.</li></ul>\n<h2 id=\"aboutness-and-representation\">Aboutness And Representation</h2>\n<p>The schema keeps visual subject relationships distinct:</p>\n<ul><li>`about`: the main topic or topics of the visual content.</li><li>`represents`: a known entity represented in the visual content.</li><li>`represents_instance_of_type`: a type of entity represented when the individual entity is not identified.</li></ul>\n<p>Do not collapse a known represented person, object, or place into a generic type. Use `represents` for identified entities and `represents_instance_of_type` for depicted classes.</p>\n<h2 id=\"carrier-boundaries\">Carrier Boundaries</h2>\n<p>The schema keeps visual content separate from carriers and surrogates:</p>\n<ul><li>Physical objects show visual content through object-side `shows`.</li><li>Digital objects show visual content through digital-object-side `digitally_shows`.</li><li>Other endpoint records can point to visual content through `representation`.</li><li>The visual work remains a `VisualItem`; physical artworks, image files, services, and visual content should remain separate linked resources.</li></ul>\n<h2 id=\"activity-fields\">Activity Fields</h2>\n<p>The schema supports visual-work activity evidence:</p>\n<ul><li>`created_by`: creation of the intellectual or visual content, including common activity fields such as `took_place_at`, `timespan`, `caused_by`, `carried_out_by`, `used_specific_object`, `influenced_by`, `technique`, `during`, `after`, `before`, and `part_of`.</li><li>`used_for`: activities in which the visual work was used, such as publication, exhibition, documentation, or another described use.</li></ul>\n<p>Creation and use should remain structured activity evidence rather than flattened creator/date strings when the data supports it.</p>\n<h2 id=\"meta-museum-notes\">Meta Museum Notes</h2>\n<p>Meta Museum already preserves Visual Work semantics through object, digital object, and record fixtures. Existing coverage keeps carrier/content/surrogate boundaries explicit: physical `HumanMadeObject` records can show `VisualItem` content, `DigitalObject` records can digitally show visual content, and object records can carry `representation[]` references without treating image files, depicted content, and physical artworks as the same entity.</p>\n<p>This expanded schema adds the endpoint-level validation target for visual exports: required identity fields, no unexpected top-level properties, structured names/classifications/statements, dimensions, rights, aboutness, representation relationships, part relationships, and visual-work creation/use activity evidence.</p>\n<h2 id=\"test-ideas\">Test Ideas</h2>\n<ul><li>Validate representative `VisualItem` records against `image.json`.</li><li>Assert `@context`, `id`, `type`, and `_label` are present.</li><li>Assert unknown top-level properties fail schema validation.</li><li>Preserve `about`, `represents`, and `represents_instance_of_type` as distinct relationships.</li><li>Preserve `subject_to` as `Right` structures, not string labels.</li><li>Preserve `dimension`, `created_by`, `used_for`, `part_of`, and `conceptually_part_of`.</li><li>Preserve carrier boundaries: physical objects use `shows`, digital objects use `digitally_shows`, and visual content remains a distinct `VisualItem`.</li></ul>","updatedAt":"2026-07-06T00:00:00.000Z","checksum":"7dc44dd62a63f7a2da29212078547b7c112d00f0e47e462b4030305e30aac923","checksumPrefix":"7dc44dd62a63","anchorCount":9,"lineCount":111,"rawUrl":"/api/docs/content?path=linked-art%2Fapi%2Fschema-visual-work.md","htmlUrl":"/docs?doc=linked-art%2Fapi%2Fschema-visual-work.md","apiUrl":"/api/docs/content?path=linked-art%2Fapi%2Fschema-visual-work.md"}