Louvre Collections JSON Integration Plan

Status: Planned (B5 provider/data-source slice)

Updated: May 30, 2026

Official source summary

• Program: Louvre Collections JSON documentation
• Access model: add `.json` to a Louvre object entry URL
• Example: `https://collections.louvre.fr/ark:/53355/cl010277627.json`
• Content language: record content is French-first
• Rights note: text and image usage must comply with Louvre Terms of Use

Key constraints (from official documentation text)

• One JSON record is available per object entry URL.
• Records expose broad museum metadata fields (title, creation dates, creator attribution, dimensions, materials, provenance, bibliography, exhibitions, related works, images).
• `arkId` is a stable record key and should be treated as the provider-native identity.
• Image payload includes explicit `copyright` and URLs for full + thumbnail.
• Controlled vocabulary hints appear in `index` blocks and should be preserved.

Integration goals

• Treat Louvre JSON as a first-class B5 provider with URL-driven record retrieval.
• Normalize to `SourceRecord` + `Artwork` boundary contracts while preserving source-rich metadata in `_source.raw`.
• Preserve creator attribution nuance (attribution level, doubt, role, attributed-by metadata where present).
• Keep rights/reuse output conservative unless image rights explicitly permit reuse.

Proposed implementation slice

Adapter

• `src/adapters/louvre.ts`
• `fetchObjectByArkOrUrl` helper (`.json` suffix normalization)
• mapper from Louvre JSON fields to project contracts
• extraction of image metadata with per-image rights annotations

Routes

• `GET /api/louvre/profile`
• `POST /api/louvre/object` (single-object fetch by `arkId` or object URL)
• `POST /api/louvre/import` (fetch + normalize + persist)
• optional `POST /api/louvre/search` (future if Louvre exposes an official search endpoint compatible with provider contract)

UI

• add `louvre` source toggle in `/explore` import panel
• show source attribution + image-rights context in card/detail surfaces

Env configuration

• `LOUVRE_BASE_URL=https://collections.louvre.fr`
• `LOUVRE_TIMEOUT_MS=15000`
• `LOUVRE_MAX_IMPORT_BATCH=25`

Operational guardrails

• Do not scrape HTML when `.json` is available.
• Require URL allowlisting (`collections.louvre.fr`) before remote fetch.
• Preserve multilingual/raw text as-is; no destructive normalization of accents/diacritics.
• Respect Terms of Use for image display and downstream reuse messaging.

Standards mapping + tests

Required tests (failing-first):

• `tests/adapters/louvre.test.ts`
• `tests/api/louvre/profile.test.ts`
• `tests/api/louvre/object.test.ts`
• `tests/api/louvre/import.test.ts`

Provider-specific conformance tests:

• `.json` URL normalization and `arkId` extraction safety
• creator attribution fields (`attributionLevel`, `doubt`, `creatorRole`) preserved
• `dateCreated` array and uncertainty fields preserved in canonical structures
• dimensions/material/index blocks preserved without shape loss
• image rights metadata preserved and mapped to conservative reuse labels

Protocol checks (B8):

• `GET` + `OPTIONS` behavior on Louvre routes
• response shape conformance + URI opacity rules
• array-cardinality safety for multi-valued source fields

Exit criteria

• Adapter + routes + tests green.
• `/explore` can import Louvre records by URL/ARK.
• PR includes Standards Mapping note with round + fixture-anchor coverage.