{"id":"linked-art/api/shared-monetary-amounts","relativePath":"linked-art/api/shared-monetary-amounts.md","title":"Linked Art API: Shared Monetary Amounts","markdown":"# Linked Art API: Shared Monetary Amounts\n\n**Last refreshed:** 2026-07-06\n\nSource: [Monetary Amounts shared structure](https://linked.art/api/1.0/shared/money/), 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\nMonetary amounts are value/currency structures used to describe an amount of money in a particular modeling context. They are similar to dimensions, but the unit is a `Currency`.\n\nIn the Linked Art API and model, monetary amounts are mainly used inside Provenance Activity structures, especially payments, but they can also appear as `dimension` values on sets such as auction lots.\n\n## Required Shape\n\nA monetary amount structure includes:\n\n- `type`: required. Must be `MonetaryAmount`.\n- `value`: required numeric value.\n- `currency`: required `Currency` reference.\n- `id`: optional URI identifying the amount.\n- `_complete`: optional completeness signal. If an `id` URI has richer dereferenceable information, `_complete: false` must be present.\n\n## Recommended Fields\n\n- `_label`: developer-facing label.\n- `classified_as`: classifications following the `Type` structure, such as starting price.\n- `identified_by`: textual display form of the structured amount, following the `Name` pattern.\n\n## Optional Fields\n\n- `upper_value_limit`: highest possible value for the amount.\n- `lower_value_limit`: lowest possible value for the amount.\n- `referred_to_by`: references to textual works about the amount, or embedded statements about the amount.\n\n## Common Incoming Relationships\n\n- `paid_amount`: used by `Payment` parts in Provenance Activity records to record money changing hands.\n- `dimension`: used on sets and other entities when a monetary amount describes the entity, such as an auction lot starting price.\n\n## Meta Museum Notes\n\nMeta Museum already preserves provenance payment structures and auction lot/set evidence as Linked Art JSON-LD. Monetary amounts should stay structured as `MonetaryAmount` with `value`, `currency`, display `identified_by`, notes, and classifications; UI code should not collapse them into formatted strings because currency URI, notation, and uncertainty bounds are reusable data.\n\n## Test Ideas\n\n- Preserve `MonetaryAmount.value`, `currency`, and `classified_as` on payment and auction lot fixtures.\n- Preserve `Currency` references with `id`, `type: Currency`, `_label`, and `notation`.\n- Preserve `identified_by` display text without replacing structured value/currency data.\n- Preserve `upper_value_limit` and `lower_value_limit` for uncertain amounts.\n- Preserve `referred_to_by` notes attached to monetary amounts.\n- Add a dereferenceable amount `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-monetary-amounts\">Linked Art API: Shared Monetary Amounts</h1>\n<p><strong>Last refreshed:</strong> 2026-07-06</p>\n<p>Source: <a href=\"https://linked.art/api/1.0/shared/money/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"doc-link\">Monetary Amounts 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>Monetary amounts are value/currency structures used to describe an amount of money in a particular modeling context. They are similar to dimensions, but the unit is a `Currency`.</p>\n<p>In the Linked Art API and model, monetary amounts are mainly used inside Provenance Activity structures, especially payments, but they can also appear as `dimension` values on sets such as auction lots.</p>\n<h2 id=\"required-shape\">Required Shape</h2>\n<p>A monetary amount structure includes:</p>\n<ul><li>`type`: required. Must be `MonetaryAmount`.</li><li>`value`: required numeric value.</li><li>`currency`: required `Currency` reference.</li><li>`id`: optional URI identifying the amount.</li><li>`_complete`: optional completeness signal. If an `id` URI has richer dereferenceable information, `_complete: false` must be present.</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 starting price.</li><li>`identified_by`: textual display form of the structured amount, following the `Name` pattern.</li></ul>\n<h2 id=\"optional-fields\">Optional Fields</h2>\n<ul><li>`upper_value_limit`: highest possible value for the amount.</li><li>`lower_value_limit`: lowest possible value for the amount.</li><li>`referred_to_by`: references to textual works about the amount, or embedded statements about the amount.</li></ul>\n<h2 id=\"common-incoming-relationships\">Common Incoming Relationships</h2>\n<ul><li>`paid_amount`: used by `Payment` parts in Provenance Activity records to record money changing hands.</li><li>`dimension`: used on sets and other entities when a monetary amount describes the entity, such as an auction lot starting price.</li></ul>\n<h2 id=\"meta-museum-notes\">Meta Museum Notes</h2>\n<p>Meta Museum already preserves provenance payment structures and auction lot/set evidence as Linked Art JSON-LD. Monetary amounts should stay structured as `MonetaryAmount` with `value`, `currency`, display `identified_by`, notes, and classifications; UI code should not collapse them into formatted strings because currency URI, notation, and uncertainty bounds are reusable data.</p>\n<h2 id=\"test-ideas\">Test Ideas</h2>\n<ul><li>Preserve `MonetaryAmount.value`, `currency`, and `classified_as` on payment and auction lot fixtures.</li><li>Preserve `Currency` references with `id`, `type: Currency`, `_label`, and `notation`.</li><li>Preserve `identified_by` display text without replacing structured value/currency data.</li><li>Preserve `upper_value_limit` and `lower_value_limit` for uncertain amounts.</li><li>Preserve `referred_to_by` notes attached to monetary amounts.</li><li>Add a dereferenceable amount `id` with richer detail available and verify `_complete: false`.</li></ul>","updatedAt":"2026-07-06T00:00:00.000Z","checksum":"030dc129f2cae5289e5cbf7c34fb137623507e86ceafb7ec2b11971dcaa8e9d4","checksumPrefix":"030dc129f2ca","anchorCount":7,"lineCount":52,"rawUrl":"/api/docs/content?path=linked-art%2Fapi%2Fshared-monetary-amounts.md","htmlUrl":"/docs?doc=linked-art%2Fapi%2Fshared-monetary-amounts.md","apiUrl":"/api/docs/content?path=linked-art%2Fapi%2Fshared-monetary-amounts.md"}