{"id":"providers/louvre-collections-json","relativePath":"providers/louvre-collections-json.md","title":"Louvre Collections JSON Integration Plan","markdown":"# Louvre Collections JSON Integration Plan\n\nStatus: Planned (B5 provider/data-source slice)  \nUpdated: May 30, 2026\n\n## Official source summary\n\n- Program: Louvre Collections JSON documentation\n- Access model: add `.json` to a Louvre object entry URL\n- Example: `https://collections.louvre.fr/ark:/53355/cl010277627.json`\n- Content language: record content is French-first\n- Rights note: text and image usage must comply with Louvre Terms of Use\n\n## Key constraints (from official documentation text)\n\n- One JSON record is available per object entry URL.\n- Records expose broad museum metadata fields (title, creation dates, creator attribution, dimensions, materials, provenance, bibliography, exhibitions, related works, images).\n- `arkId` is a stable record key and should be treated as the provider-native identity.\n- Image payload includes explicit `copyright` and URLs for full + thumbnail.\n- Controlled vocabulary hints appear in `index` blocks and should be preserved.\n\n## Integration goals\n\n- Treat Louvre JSON as a first-class B5 provider with URL-driven record retrieval.\n- Normalize to `SourceRecord` + `Artwork` boundary contracts while preserving source-rich metadata in `_source.raw`.\n- Preserve creator attribution nuance (attribution level, doubt, role, attributed-by metadata where present).\n- Keep rights/reuse output conservative unless image rights explicitly permit reuse.\n\n## Proposed implementation slice\n\n### Adapter\n\n- `src/adapters/louvre.ts`\n  - `fetchObjectByArkOrUrl` helper (`.json` suffix normalization)\n  - mapper from Louvre JSON fields to project contracts\n  - extraction of image metadata with per-image rights annotations\n\n### Routes\n\n- `GET /api/louvre/profile`\n- `POST /api/louvre/object` (single-object fetch by `arkId` or object URL)\n- `POST /api/louvre/import` (fetch + normalize + persist)\n- optional `POST /api/louvre/search` (future if Louvre exposes an official search endpoint compatible with provider contract)\n\n### UI\n\n- add `louvre` source toggle in `/explore` import panel\n- show source attribution + image-rights context in card/detail surfaces\n\n## Env configuration\n\n- `LOUVRE_BASE_URL=https://collections.louvre.fr`\n- `LOUVRE_TIMEOUT_MS=15000`\n- `LOUVRE_MAX_IMPORT_BATCH=25`\n\n## Operational guardrails\n\n- Do not scrape HTML when `.json` is available.\n- Require URL allowlisting (`collections.louvre.fr`) before remote fetch.\n- Preserve multilingual/raw text as-is; no destructive normalization of accents/diacritics.\n- Respect Terms of Use for image display and downstream reuse messaging.\n\n## Standards mapping + tests\n\nRequired tests (failing-first):\n\n- `tests/adapters/louvre.test.ts`\n- `tests/api/louvre/profile.test.ts`\n- `tests/api/louvre/object.test.ts`\n- `tests/api/louvre/import.test.ts`\n\nProvider-specific conformance tests:\n\n- `.json` URL normalization and `arkId` extraction safety\n- creator attribution fields (`attributionLevel`, `doubt`, `creatorRole`) preserved\n- `dateCreated` array and uncertainty fields preserved in canonical structures\n- dimensions/material/index blocks preserved without shape loss\n- image rights metadata preserved and mapped to conservative reuse labels\n\nProtocol checks (B8):\n\n- `GET` + `OPTIONS` behavior on Louvre routes\n- response shape conformance + URI opacity rules\n- array-cardinality safety for multi-valued source fields\n\n## Exit criteria\n\n- Adapter + routes + tests green.\n- `/explore` can import Louvre records by URL/ARK.\n- PR includes Standards Mapping note with round + fixture-anchor coverage.\n","sections":[{"level":2,"heading":"Official source summary","anchor":"official-source-summary"},{"level":2,"heading":"Key constraints (from official documentation text)","anchor":"key-constraints-from-official-documentation-text"},{"level":2,"heading":"Integration goals","anchor":"integration-goals"},{"level":2,"heading":"Proposed implementation slice","anchor":"proposed-implementation-slice"},{"level":3,"heading":"Adapter","anchor":"adapter"},{"level":3,"heading":"Routes","anchor":"routes"},{"level":3,"heading":"UI","anchor":"ui"},{"level":2,"heading":"Env configuration","anchor":"env-configuration"},{"level":2,"heading":"Operational guardrails","anchor":"operational-guardrails"},{"level":2,"heading":"Standards mapping + tests","anchor":"standards-mapping-tests"},{"level":2,"heading":"Exit criteria","anchor":"exit-criteria"}],"html":"<h1 id=\"louvre-collections-json-integration-plan\">Louvre Collections JSON Integration Plan</h1>\n<p>Status: Planned (B5 provider/data-source slice)  </p>\n<p>Updated: May 30, 2026</p>\n<h2 id=\"official-source-summary\">Official source summary</h2>\n<ul><li>Program: Louvre Collections JSON documentation</li><li>Access model: add `.json` to a Louvre object entry URL</li><li>Example: `https://collections.louvre.fr/ark:/53355/cl010277627.json`</li><li>Content language: record content is French-first</li><li>Rights note: text and image usage must comply with Louvre Terms of Use</li></ul>\n<h2 id=\"key-constraints-from-official-documentation-text\">Key constraints (from official documentation text)</h2>\n<ul><li>One JSON record is available per object entry URL.</li><li>Records expose broad museum metadata fields (title, creation dates, creator attribution, dimensions, materials, provenance, bibliography, exhibitions, related works, images).</li><li>`arkId` is a stable record key and should be treated as the provider-native identity.</li><li>Image payload includes explicit `copyright` and URLs for full + thumbnail.</li><li>Controlled vocabulary hints appear in `index` blocks and should be preserved.</li></ul>\n<h2 id=\"integration-goals\">Integration goals</h2>\n<ul><li>Treat Louvre JSON as a first-class B5 provider with URL-driven record retrieval.</li><li>Normalize to `SourceRecord` + `Artwork` boundary contracts while preserving source-rich metadata in `_source.raw`.</li><li>Preserve creator attribution nuance (attribution level, doubt, role, attributed-by metadata where present).</li><li>Keep rights/reuse output conservative unless image rights explicitly permit reuse.</li></ul>\n<h2 id=\"proposed-implementation-slice\">Proposed implementation slice</h2>\n<h3 id=\"adapter\">Adapter</h3>\n<ul><li>`src/adapters/louvre.ts`</li><li>`fetchObjectByArkOrUrl` helper (`.json` suffix normalization)</li><li>mapper from Louvre JSON fields to project contracts</li><li>extraction of image metadata with per-image rights annotations</li></ul>\n<h3 id=\"routes\">Routes</h3>\n<ul><li>`GET /api/louvre/profile`</li><li>`POST /api/louvre/object` (single-object fetch by `arkId` or object URL)</li><li>`POST /api/louvre/import` (fetch + normalize + persist)</li><li>optional `POST /api/louvre/search` (future if Louvre exposes an official search endpoint compatible with provider contract)</li></ul>\n<h3 id=\"ui\">UI</h3>\n<ul><li>add `louvre` source toggle in `/explore` import panel</li><li>show source attribution + image-rights context in card/detail surfaces</li></ul>\n<h2 id=\"env-configuration\">Env configuration</h2>\n<ul><li>`LOUVRE_BASE_URL=https://collections.louvre.fr`</li><li>`LOUVRE_TIMEOUT_MS=15000`</li><li>`LOUVRE_MAX_IMPORT_BATCH=25`</li></ul>\n<h2 id=\"operational-guardrails\">Operational guardrails</h2>\n<ul><li>Do not scrape HTML when `.json` is available.</li><li>Require URL allowlisting (`collections.louvre.fr`) before remote fetch.</li><li>Preserve multilingual/raw text as-is; no destructive normalization of accents/diacritics.</li><li>Respect Terms of Use for image display and downstream reuse messaging.</li></ul>\n<h2 id=\"standards-mapping-tests\">Standards mapping + tests</h2>\n<p>Required tests (failing-first):</p>\n<ul><li>`tests/adapters/louvre.test.ts`</li><li>`tests/api/louvre/profile.test.ts`</li><li>`tests/api/louvre/object.test.ts`</li><li>`tests/api/louvre/import.test.ts`</li></ul>\n<p>Provider-specific conformance tests:</p>\n<ul><li>`.json` URL normalization and `arkId` extraction safety</li><li>creator attribution fields (`attributionLevel`, `doubt`, `creatorRole`) preserved</li><li>`dateCreated` array and uncertainty fields preserved in canonical structures</li><li>dimensions/material/index blocks preserved without shape loss</li><li>image rights metadata preserved and mapped to conservative reuse labels</li></ul>\n<p>Protocol checks (B8):</p>\n<ul><li>`GET` + `OPTIONS` behavior on Louvre routes</li><li>response shape conformance + URI opacity rules</li><li>array-cardinality safety for multi-valued source fields</li></ul>\n<h2 id=\"exit-criteria\">Exit criteria</h2>\n<ul><li>Adapter + routes + tests green.</li><li>`/explore` can import Louvre records by URL/ARK.</li><li>PR includes Standards Mapping note with round + fixture-anchor coverage.</li></ul>","updatedAt":"2018-10-20T01:46:40.000Z","checksum":"775f91a8d8133449392dc5824ac2bc9b698ec503aaf754f794ba9a05bc76c26a","checksumPrefix":"775f91a8d813","anchorCount":11,"lineCount":91,"rawUrl":"/api/docs/content?path=providers%2Flouvre-collections-json.md","htmlUrl":"/docs?doc=providers%2Flouvre-collections-json.md","apiUrl":"/api/docs/content?path=providers%2Flouvre-collections-json.md"}