{"id":"linked-art/api/shared-timespans","relativePath":"linked-art/api/shared-timespans.md","title":"Linked Art API: Shared TimeSpans","markdown":"# Linked Art API: Shared TimeSpans\n\n**Last refreshed:** 2026-07-06\n\nSource: [TimeSpans shared structure](https://linked.art/api/1.0/shared/timespan/), 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\nTimeSpans describe the temporal extent of periods, events, activities, and more specific activity classes. They are designed for fuzzy starting and ending points while still supporting search and computation.\n\nA TimeSpan is not just a display date. It can include textual labels, fuzzy boundary dates, notes, classifications, and duration.\n\n## Required Shape\n\nA timespan structure includes:\n\n- `type`: required. Must be `TimeSpan`.\n- `id`: optional URI identifying the timespan.\n- `_complete`: optional completeness signal. If an `id` URI has richer dereferenceable information, `_complete: false` must be present.\n\nImportant minimum-content rule: a TimeSpan must have at least one of `identified_by`, `begin_of_the_begin`, or `end_of_the_end`. Without one of those, there is no useful information for a consumer and a dereferenceable `id` would be indistinguishable from a reference.\n\n## Recommended Fields\n\n- `_label`: developer-facing label.\n- `classified_as`: classifications following the `Type` structure.\n- `identified_by`: textual representation of the structured time span, following the `Name` pattern.\n- `begin_of_the_begin`: earliest possible date-time at which the timespan could have started.\n- `end_of_the_end`: latest possible date-time at which the timespan could have ended.\n\n## Optional Fields\n\n- `end_of_the_begin`: latest possible date-time at which the timespan could have started.\n- `begin_of_the_end`: earliest possible date-time at which the timespan could have ended.\n- `referred_to_by`: references to textual works about the timespan, or embedded statements about it.\n- `duration`: `Dimension` structure describing the length of time within the boundary range.\n\n## Common Incoming Relationships\n\n- `timespan`: used by activities, events, periods, and temporal endpoint records.\n\n## Meta Museum Notes\n\nMeta Museum already preserves timespans on activities, events, provenance parts, dataset projections, and ActivityStreams evidence rows. Existing checks around real Update evidence also depend on UTC `endTime` freshness outside Linked Art, but Linked Art `TimeSpan` remains the semantic place for fuzzy historical or lifecycle dates. Future fixture work should broaden coverage for all four TimeSpan boundaries and duration dimensions.\n\n## Test Ideas\n\n- Preserve `begin_of_the_begin`, `end_of_the_begin`, `begin_of_the_end`, and `end_of_the_end` when supplied.\n- Preserve `identified_by` display labels without replacing structured boundary dates.\n- Preserve `referred_to_by` notes about temporal evidence.\n- Preserve `duration` as a `Dimension` with value and `MeasurementUnit`.\n- Verify a TimeSpan has at least one of `identified_by`, `begin_of_the_begin`, or `end_of_the_end`.\n- Add a dereferenceable timespan `id` with richer detail available and verify `_complete: false`.\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-shared-timespans\">Linked Art API: Shared TimeSpans</h1>\n<p><strong>Last refreshed:</strong> 2026-07-06</p>\n<p>Source: <a href=\"https://linked.art/api/1.0/shared/timespan/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"doc-link\">TimeSpans 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>TimeSpans describe the temporal extent of periods, events, activities, and more specific activity classes. They are designed for fuzzy starting and ending points while still supporting search and computation.</p>\n<p>A TimeSpan is not just a display date. It can include textual labels, fuzzy boundary dates, notes, classifications, and duration.</p>\n<h2 id=\"required-shape\">Required Shape</h2>\n<p>A timespan structure includes:</p>\n<ul><li>`type`: required. Must be `TimeSpan`.</li><li>`id`: optional URI identifying the timespan.</li><li>`_complete`: optional completeness signal. If an `id` URI has richer dereferenceable information, `_complete: false` must be present.</li></ul>\n<p>Important minimum-content rule: a TimeSpan must have at least one of `identified_by`, `begin_of_the_begin`, or `end_of_the_end`. Without one of those, there is no useful information for a consumer and a dereferenceable `id` would be indistinguishable from a reference.</p>\n<h2 id=\"recommended-fields\">Recommended Fields</h2>\n<ul><li>`_label`: developer-facing label.</li><li>`classified_as`: classifications following the `Type` structure.</li><li>`identified_by`: textual representation of the structured time span, following the `Name` pattern.</li><li>`begin_of_the_begin`: earliest possible date-time at which the timespan could have started.</li><li>`end_of_the_end`: latest possible date-time at which the timespan could have ended.</li></ul>\n<h2 id=\"optional-fields\">Optional Fields</h2>\n<ul><li>`end_of_the_begin`: latest possible date-time at which the timespan could have started.</li><li>`begin_of_the_end`: earliest possible date-time at which the timespan could have ended.</li><li>`referred_to_by`: references to textual works about the timespan, or embedded statements about it.</li><li>`duration`: `Dimension` structure describing the length of time within the boundary range.</li></ul>\n<h2 id=\"common-incoming-relationships\">Common Incoming Relationships</h2>\n<ul><li>`timespan`: used by activities, events, periods, and temporal endpoint records.</li></ul>\n<h2 id=\"meta-museum-notes\">Meta Museum Notes</h2>\n<p>Meta Museum already preserves timespans on activities, events, provenance parts, dataset projections, and ActivityStreams evidence rows. Existing checks around real Update evidence also depend on UTC `endTime` freshness outside Linked Art, but Linked Art `TimeSpan` remains the semantic place for fuzzy historical or lifecycle dates. Future fixture work should broaden coverage for all four TimeSpan boundaries and duration dimensions.</p>\n<h2 id=\"test-ideas\">Test Ideas</h2>\n<ul><li>Preserve `begin_of_the_begin`, `end_of_the_begin`, `begin_of_the_end`, and `end_of_the_end` when supplied.</li><li>Preserve `identified_by` display labels without replacing structured boundary dates.</li><li>Preserve `referred_to_by` notes about temporal evidence.</li><li>Preserve `duration` as a `Dimension` with value and `MeasurementUnit`.</li><li>Verify a TimeSpan has at least one of `identified_by`, `begin_of_the_begin`, or `end_of_the_end`.</li><li>Add a dereferenceable timespan `id` with richer detail available and verify `_complete: false`.</li></ul>","updatedAt":"2026-07-06T00:00:00.000Z","checksum":"ea33d788e29b6c7f5765117d495b05b7a9ff782bb62496401207d4164d566602","checksumPrefix":"ea33d788e29b","anchorCount":7,"lineCount":54,"rawUrl":"/api/docs/content?path=linked-art%2Fapi%2Fshared-timespans.md","htmlUrl":"/docs?doc=linked-art%2Fapi%2Fshared-timespans.md","apiUrl":"/api/docs/content?path=linked-art%2Fapi%2Fshared-timespans.md"}