{"id":"linked-art/api/schema-textual-work","relativePath":"linked-art/api/schema-textual-work.md","title":"Linked Art API Schema: Textual Work","markdown":"# Linked Art API Schema: Textual Work\n\n**Last refreshed:** 2026-07-06\n\nSource: [Textual Work schema docs](https://linked.art/api/1.0/schema_docs/text/) and [text.json](https://linked.art/api/1.0/schema/text.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 Textual Work schema describes `crm:E33_Linguistic_Object`: textual content expressed in one or more human languages, whether or not it is written on a physical carrier. In Linked Art API terms this is the endpoint shape for intellectual or linguistic text, separate from the physical object that carries it and the digital object that makes it available.\n\nRelated upstream references:\n\n- [Textual Work API endpoint](https://linked.art/api/1.0/endpoint/textual_work/)\n- [Textual documents model documentation](https://linked.art/model/document/)\n\n## Top-Level Constraints\n\n- Schema type: object.\n- CRM class: `crm:E33_Linguistic_Object`.\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 `LinguisticObject`.\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 textual work.\n- `referred_to_by`: array of embedded statements or textual references about the textual work.\n- `equivalent`: array of compact references to equivalent identities.\n- `representation`: array of embedded `VisualItem` structures linked through digital objects.\n- `member_of`: array of `Set` references.\n- `subject_of`: array of embedded `LinguisticObject` web pages or digital objects focused on this text.\n- `attributed_by`: array of `AttributeAssignment` structures relating another entity to this text.\n- `dimension`: array of `Dimension` structures, such as page count or word count.\n- `subject_to`: array of `Right` structures that apply to the textual work.\n- `language`: array of `Language` references for languages expressed in the text.\n- `format`: media type of the embedded textual `content`, such as `text/plain` or `text/html`.\n- `about`: array of references to the main topics of the text.\n- `created_by`: creation activity for the intellectual or linguistic content.\n- `used_for`: array of activities in which this textual work was used.\n- `part_of`: array of `LinguisticObject` or `VisualItem` references of which this text is part.\n- `content`: string representation of the textual content when supplied.\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`representation` items are embedded `VisualItem` structures:\n\n- `type`: required.\n- `_label`, `identified_by`, `classified_as`, `referred_to_by`, and `digitally_shown_by` are allowed.\n- Nested digital objects can carry `access_point`, `format`, and `conforms_to`.\n\n## Text Content And Carrier Boundaries\n\nThe schema keeps textual content separate from carriers:\n\n- `content`: literal textual content when included in the endpoint response.\n- `language`: language references for the text.\n- `format`: media type of the embedded textual content.\n- `part_of`: another `LinguisticObject` or `VisualItem` of which this text forms part.\n- Physical objects carry text through object-side `carries`.\n- Digital objects carry text through digital-object-side `digitally_carries`.\n\nDo not collapse a book, scan, web page, and textual work into one entity. The textual work remains a `LinguisticObject`; carriers and surrogates remain separate linked resources.\n\n## Activity Fields\n\nThe schema supports textual-work activity evidence:\n\n- `created_by`: creation of the intellectual or linguistic 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 text was used, such as publication, exhibition interpretation, citation, or other documented use.\n\nAuthorship and publication should remain activity evidence rather than flattened display strings when the data supports it.\n\n## Meta Museum Notes\n\nMeta Museum already preserves Textual Work semantics through `/api/records/{id}` fixtures for the Textual Documents profile. Existing coverage proves physical book `HumanMadeObject` carriers link to `LinguisticObject` content through `carries`; textual records preserve monograph/chapter classifications, primary and system identifiers, language, `content`, authorship `Creation`, publishing `Activity`, object `about` references, abstract-work `part_of` links, pagination statements, page-count dimensions, and `digitally_carried_by` digital carriers.\n\nThis expanded schema adds the endpoint-level validation target for textual exports: required identity fields, no unexpected top-level properties, structured names/classifications/statements, language and content fields, rights, aboutness, part relationships, and textual-work creation/use activity evidence.\n\n## Test Ideas\n\n- Validate representative `LinguisticObject` records against `text.json`.\n- Assert `@context`, `id`, `type`, and `_label` are present.\n- Assert unknown top-level properties fail schema validation.\n- Preserve `language`, `content`, `format`, `about`, `subject_to`, `dimension`, `created_by`, `used_for`, and `part_of`.\n- Preserve `subject_to` as `Right` structures, not string labels.\n- Preserve carrier boundaries: physical objects use `carries`, digital objects use `digitally_carries`, and the text remains a distinct `LinguisticObject`.\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":"Text Content And Carrier Boundaries","anchor":"text-content-and-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-textual-work\">Linked Art API Schema: Textual 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/text/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"doc-link\">Textual Work schema docs</a> and <a href=\"https://linked.art/api/1.0/schema/text.json\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"doc-link\">text.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 Textual Work schema describes `crm:E33_Linguistic_Object`: textual content expressed in one or more human languages, whether or not it is written on a physical carrier. In Linked Art API terms this is the endpoint shape for intellectual or linguistic text, separate from the physical object that carries it and the digital object that makes it available.</p>\n<p>Related upstream references:</p>\n<ul><li><a href=\"https://linked.art/api/1.0/endpoint/textual_work/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"doc-link\">Textual Work API endpoint</a></li><li><a href=\"https://linked.art/model/document/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"doc-link\">Textual documents 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:E33_Linguistic_Object`.</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 `LinguisticObject`.</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 textual work.</li><li>`referred_to_by`: array of embedded statements or textual references about the textual work.</li><li>`equivalent`: array of compact references to equivalent identities.</li><li>`representation`: array of embedded `VisualItem` structures linked through digital objects.</li><li>`member_of`: array of `Set` references.</li><li>`subject_of`: array of embedded `LinguisticObject` web pages or digital objects focused on this text.</li><li>`attributed_by`: array of `AttributeAssignment` structures relating another entity to this text.</li><li>`dimension`: array of `Dimension` structures, such as page count or word count.</li><li>`subject_to`: array of `Right` structures that apply to the textual work.</li><li>`language`: array of `Language` references for languages expressed in the text.</li><li>`format`: media type of the embedded textual `content`, such as `text/plain` or `text/html`.</li><li>`about`: array of references to the main topics of the text.</li><li>`created_by`: creation activity for the intellectual or linguistic content.</li><li>`used_for`: array of activities in which this textual work was used.</li><li>`part_of`: array of `LinguisticObject` or `VisualItem` references of which this text is part.</li><li>`content`: string representation of the textual content when supplied.</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>`representation` items are embedded `VisualItem` structures:</p>\n<ul><li>`type`: required.</li><li>`_label`, `identified_by`, `classified_as`, `referred_to_by`, and `digitally_shown_by` are allowed.</li><li>Nested digital objects can carry `access_point`, `format`, and `conforms_to`.</li></ul>\n<h2 id=\"text-content-and-carrier-boundaries\">Text Content And Carrier Boundaries</h2>\n<p>The schema keeps textual content separate from carriers:</p>\n<ul><li>`content`: literal textual content when included in the endpoint response.</li><li>`language`: language references for the text.</li><li>`format`: media type of the embedded textual content.</li><li>`part_of`: another `LinguisticObject` or `VisualItem` of which this text forms part.</li><li>Physical objects carry text through object-side `carries`.</li><li>Digital objects carry text through digital-object-side `digitally_carries`.</li></ul>\n<p>Do not collapse a book, scan, web page, and textual work into one entity. The textual work remains a `LinguisticObject`; carriers and surrogates remain separate linked resources.</p>\n<h2 id=\"activity-fields\">Activity Fields</h2>\n<p>The schema supports textual-work activity evidence:</p>\n<ul><li>`created_by`: creation of the intellectual or linguistic 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 text was used, such as publication, exhibition interpretation, citation, or other documented use.</li></ul>\n<p>Authorship and publication should remain activity evidence rather than flattened display strings when the data supports it.</p>\n<h2 id=\"meta-museum-notes\">Meta Museum Notes</h2>\n<p>Meta Museum already preserves Textual Work semantics through `/api/records/{id}` fixtures for the Textual Documents profile. Existing coverage proves physical book `HumanMadeObject` carriers link to `LinguisticObject` content through `carries`; textual records preserve monograph/chapter classifications, primary and system identifiers, language, `content`, authorship `Creation`, publishing `Activity`, object `about` references, abstract-work `part_of` links, pagination statements, page-count dimensions, and `digitally_carried_by` digital carriers.</p>\n<p>This expanded schema adds the endpoint-level validation target for textual exports: required identity fields, no unexpected top-level properties, structured names/classifications/statements, language and content fields, rights, aboutness, part relationships, and textual-work creation/use activity evidence.</p>\n<h2 id=\"test-ideas\">Test Ideas</h2>\n<ul><li>Validate representative `LinguisticObject` records against `text.json`.</li><li>Assert `@context`, `id`, `type`, and `_label` are present.</li><li>Assert unknown top-level properties fail schema validation.</li><li>Preserve `language`, `content`, `format`, `about`, `subject_to`, `dimension`, `created_by`, `used_for`, and `part_of`.</li><li>Preserve `subject_to` as `Right` structures, not string labels.</li><li>Preserve carrier boundaries: physical objects use `carries`, digital objects use `digitally_carries`, and the text remains a distinct `LinguisticObject`.</li></ul>","updatedAt":"2026-07-06T00:00:00.000Z","checksum":"27f38ce348c4c5e35776513dd5c4bbc862b9d3d05baf3aad378daa3309a463d7","checksumPrefix":"27f38ce348c4","anchorCount":8,"lineCount":106,"rawUrl":"/api/docs/content?path=linked-art%2Fapi%2Fschema-textual-work.md","htmlUrl":"/docs?doc=linked-art%2Fapi%2Fschema-textual-work.md","apiUrl":"/api/docs/content?path=linked-art%2Fapi%2Fschema-textual-work.md"}